MediaShell – GNOME Media Controls

A GNOME extension that adds configurable MPRIS media controls to the top bar.

MediaShell is a GNOME Shell extension that adds configurable MPRIS media controls to the top bar. Its customizable popup displays album art, track information, playback controls, and a selector for switching between active media apps. The top bar and popup can be configured independently, while GTK4 and Libadwaita preferences provide a consistent GNOME experience.

Screenshots

Workspace

Popup	Popup media app selector	Popup theming

Extension settings

Popup	Top bar	Panel

Interactions	Others	About

Features

GNOME integration

• The top bar and popup use GNOME Shell widgets and follow the desktop's visual language.
• Preferences are built with GTK4 and Libadwaita.
• Optionally hide GNOME's built-in media controls while MediaShell is enabled.

Independent top bar and popup

• Configure the contents of the popup and top bar independently.
• Choose the panel position and reorder the app icon, album art, track information, visualizer, and playback controls.
• Build track information from MPRIS fields and custom text, with independent scrolling behavior for each surface.

Playback and seeking

• Use previous, play/pause, next, seek, shuffle, and repeat controls in the popup or top bar.
• The popup can add a seekable progress bar, playback-speed control, and volume control.
• Controls follow the app's playback state and reported MPRIS capabilities.

Media app selector

• Switch between media apps currently available through MPRIS.
• Pin the selected media app for the current Shell session.
• Open or quit an app when its MPRIS implementation supports the action.
• Block apps you do not want MediaShell to display without changing their MPRIS service.

Album art

• Display local or remote album art in the popup and top bar with configurable presentation.
• An optional persistent cache improves repeated loads and can be inspected or cleared from Preferences.

Visualizer

• Add an optional decorative top bar visualizer with Beats, Pulse, Classic, Spectrum, and Vinyl styles.
• Adjust the animation speed; motion follows the active media app's playback state.

Mouse and keyboard

• Map left, middle, right, and double clicks plus scroll directions to actions; touch activation follows the primary action.
• Use global shortcuts for playback, seeking, volume, media app actions, opening the popup, and Preferences.

Requirements

• GNOME Shell 47–50
• A media app or browser session that exposes an MPRIS service

Important

MediaShell follows the capabilities reported by the active MPRIS app. Seeking, shuffle, repeat, playback speed, volume, and app actions are available only when supported. Track metadata and album art depend on what the app provides for the current media.

Note

Browser MPRIS sessions are controlled by the browser and active website. They may appear, change identity, or disappear as tabs, pages, and playback ownership change.

Download

Manual installation

1. Download the latest extension package from releases.
2. Install it using GNOME Extensions or the command line:

gnome-extensions install --force mediashell@wstxda.github.com.shell-extension.zip
gnome-extensions enable mediashell@wstxda.github.com

3. Log out and back in after the first installation. On X11, GNOME Shell can instead be restarted with Alt+F2, r, and Enter.

Development

Use the versions declared by the project and verify the local GNOME toolchain:

pnpm install
pnpm run env:doctor
pnpm check
pnpm build

Use pnpm verify for a release candidate. The generated extension package is written to dist/builds/.

Documentation

• Contributing
• Development
• Architecture

Donate

Credits

Sakith B.
For your work on the Media Controls extension.