MediaShell – GNOME Media Controls

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

MediaShell is a GNOME Shell extension for controlling MPRIS media from the top bar. Its customizable popup displays artwork, track information, playback controls, and a selector for switching between active media apps. The top bar and popup can be configured independently, while Preferences use GTK4 and Libadwaita.

Screenshots

Workspace

Popup	Popup media app selector	Popup theming

Extension settings

Popup	Top bar	Panel

Interactions	Others	About

Features

GNOME integration

• Built with GNOME Shell widgets, GTK4, and Libadwaita to fit naturally into the desktop.
• Hide GNOME's native media controls or enhance them with MediaShell controls where supported.

Independent top bar and popup

• Configure the top bar and popup independently.
• Arrange track information, app identity, artwork, playback controls, and the optional visualizer to match your layout.

Playback controls

• Control previous, play/pause, next, seeking, shuffle, and repeat through MPRIS when supported by the active media app.
• Add playback position, volume, and playback-speed controls to the popup when available.

Media app selector

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

Album art

• Display local or remote artwork in the popup and top bar.
• Use an optional persistent cache to improve repeated artwork loads.

Visualizer

• Add an optional visualizer to the top bar with multiple presentation styles.
• Animation follows the active media app's playback state.

Mouse and keyboard

• Assign mouse buttons, double click, and scroll directions to MediaShell actions.
• Use global shortcuts for playback, seeking, volume, media app actions, the popup, and Preferences.

Requirements

• GNOME Shell 48–51
• A media app or browser session that exposes an MPRIS service

Important

MediaShell follows the capabilities and metadata reported by the active MPRIS media app. Controls or media information that the app does not expose cannot be provided reliably by the extension.

Note

Browser MPRIS sessions are controlled by the browser and active website, so their identity and metadata may change as playback ownership moves between pages or tabs.

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

3. After the first installation, start a new GNOME Shell session so the extension is discovered. On X11, GNOME Shell can instead be restarted with Alt+F2, r, and Enter.
4. Enable MediaShell:

gnome-extensions enable mediashell@wstxda.github.com

Development

pnpm install
pnpm env:doctor
pnpm check
pnpm build:debug

package.json is the authoritative command list. See Development for the development workflow and Contributing before making changes.

Documentation

• Contributing
• Development
• Architecture

Donate

Credits

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