A dynamic, elegant, and highly customizable music widget for GNOME Shell. It brings a pill-shaped media controller with a live audio visualizer directly to your Dash or Panel, complete with a rich Pop-Up Menu.

   

Adaptive Color Engine — The pill's background color and visualizer accent are automatically extracted from the dominant color of the current track's album art, and update smoothly on every track change.

Four Visualizer Modes — Choose between Off, Wave (smooth continuous sine-like waveform), Beat (jumpy bar animation), or Real-Time (requires the cava package for live audio visualization). Bar count, bar width, height, and margin are all independently configurable.

Per-Layer Transparency — Transparency can be enabled globally and then applied individually to the background, album art, text, and visualizer, giving full compositing control without coupling layers together.

Sync GNOME Accent Color — Dynamically changes the GNOME Shell system accent color to match the dominant color of the currently playing album art, unifying the whole desktop aesthetic.

Custom Color Override — When adaptive colors are not desired, a full custom color mode lets you set fixed background and text colors via a color picker, overriding the dynamic system entirely.

Pill Shadow — An optional drop shadow can be applied to the main pill widget with independent control over blur radius and intensity.

Outline Border — A subtle border around the pill can be shown or hidden independently of the background and transparency settings.

Dynamic Width — The pill can automatically resize its width to fit the current track title, with the configured width acting as a maximum cap. Changes are animated with a crossfade.

Configurable Click Actions — Five interaction types can each be assigned an independent action: Left Click, Double Click, Middle Click, Right Click, and Hover. Available actions are: None, Play/Pause, Next Track, Previous Track, Open Player App, Close Player App, Open Pop-Up Menu, Select Player, and Open Settings.

Hover Delay — When a Hover action is assigned, a configurable delay (0–3000 ms) prevents the action from triggering immediately on accidental cursor contact.

Scroll to Change Volume — Scrolling over the pill adjusts system volume via PulseAudio/PipeWire with GNOME OSD feedback. A built-in delta accumulator ensures smooth and accurate behavior on high-resolution touchpads.

Scroll to Change Track — The scroll action can alternatively be set to skip forward or backward through the track queue.

Scroll to Switch Player — A third scroll mode cycles through active MPRIS-compatible media players, letting you control multiple apps without opening a menu.

Scroll Direction Inversion — Both the scroll animation direction (visual jump effect) and the actual scroll direction (up/down mapping for track and volume) can be inverted independently.

Tablet Mode Controls — A dedicated on-pill button overlay for touch and tablet use. Configurable to show Skip Only, Play/Pause Only, or All Controls directly on the pill surface.

Always ON Mode — The pill retains the last known track metadata and stays visible even after the media player is closed, instead of disappearing when no active player is detected.

Hide Default GNOME Player — Suppresses the built-in media controls widget in the GNOME Quick Settings panel to avoid duplicate interfaces.

Scrolling Track Title — When the track title or artist name exceeds the available pill width, the text scrolls horizontally.

Inline Artist — When the pill is narrow or squeezed, the display can switch to a combined "Title • Artist" single-line format.

Compact Mode — Hides the title and artist text entirely, leaving only the album art and visualizer visible for a minimal footprint.

Fallback Album Art — A custom image file (PNG or JPEG) can be set as a fallback to display when the current track provides no album art.

Synchronized Lyrics — Real-time lyric display synchronized to the current track's playback position. Lyrics can optionally fade in with a configurable transition duration (50–2000 ms).

Seek Bar — A fully interactive seek bar allows jumping to any position in the current track directly from the pop-up, without opening the player application.

Spinning Vinyl — The album art in the pop-up rotates continuously while music is playing, pausing automatically on pause. Rotation speed is adjustable (1–50).

Square Album Art Mode — The album art in the pop-up can be shown as a square instead of circular. When square mode is active, the spinning animation is automatically disabled.

Shuffle and Loop Controls — Optional shuffle and repeat toggle buttons can be shown in the pop-up alongside the standard playback controls.

Custom Control Buttons — Up to two additional buttons can be added to the pop-up controls row. Each button can be assigned one of: Volume, Seek Step, Audio Output, Sleep Timer, Playback Speed, or Recently Played history.

Player Selector — An optional row at the top of the pop-up displays icons for all currently active MPRIS players, allowing switching between players with a single click.

Pop-up Visualizer — The audio visualizer can also be displayed inside the pop-up menu, with its own independent bar count (2–64), bar width (1–20 px), and height (20–200 px) settings. A complementary option hides the main pill visualizer when the pop-up is open, creating a visual transfer effect.

Dynamic Menu Resizing — When skipping tracks from the pop-up, the menu smoothly resizes and crossfades to accommodate different album art dimensions.

Close on Mouse Leave — The pop-up can be configured to automatically close when the cursor moves away from it.

Custom Pop-up Width — The pop-up menu's automatic dynamic sizing can be overridden with a fixed custom width (260–800 px).

Pop-up Styling Inheritance — The pop-up can independently inherit the pill's background transparency, corner radius, custom background color, and custom text color.

Dynamic Contrast — Pop-up text and control buttons automatically switch between light and dark based on the album art's luminance, maintaining readability on both bright and dark covers.

Four Placement Targets — The pill can be placed in the Dock (requires Dash-to-Dock or Ubuntu Dock), or in any of the three Top Panel zones: Left Box, Center Box, or Right Box.

Alignment Presets — Within the chosen container, the pill can be aligned to First (Start), Center, Last (End), or placed at a manually specified index position.

Independent Offset Control — Vertical (Y) and Horizontal (X) offsets can be fine-tuned independently, with separate profiles stored for Dock mode and Panel mode.

Independent Size Profiles — Widget width, height, and album art thumbnail size are stored separately for Dock and Panel modes, with different valid ranges appropriate to each context.

Corner Radius — Controls the roundness of the widget edges globally, from fully square (0) to a complete pill shape (50+).

Outer Edge Margin — Adds spacing before the album art and after the visualizer to control padding at the pill's outer edges.

Game Mode — Detects when a fullscreen application is focused and automatically disables the visualizer and all CSS animations to eliminate compositor overhead. Resumes automatically when the fullscreen application closes.

Slow Player Workaround — Adds a slight delay to track change handling to fix synchronization issues with players that emit metadata updates slightly after the track change signal.

Player Filter — Players can be filtered using a Blacklist (exclude named players) or Whitelist (allow only named players) mode, with the filter list editable as comma-separated MPRIS app names. Currently active players are detected live via D-Bus and can be added to the filter list with a single click.

Manual App ID Mapping — When the extension cannot automatically identify a player's window for Open/Close App actions, a manual mapping table allows pairing an MPRIS player name to its correct window App ID. Running players are detected via D-Bus and can be registered with one click, then edited in-place or deleted individually.

Selected Player Lock — The extension tracks which player is currently selected and maintains focus on it across track changes and player restarts.

Export Settings — The complete configuration is serialized to a .json file saved to a user-selected path for backup or transfer between machines.

Import Settings — A previously exported .json file can be loaded to instantly restore a full configuration.

Factory Reset — All settings are reset to their defaults in a single action.

1. Clone the repository:

git clone https://github.com/Andbal23/dynamic-music-pill.git

2. Enter the directory:

cd dynamic-music-pill

3. Create the extension directory:

mkdir -p ~/.local/share/gnome-shell/extensions/dynamic-music-pill@andbal

4. Copy all files:

cp -r * ~/.local/share/gnome-shell/extensions/dynamic-music-pill@andbal/

5. Compile GSettings schemas:

cd ~/.local/share/gnome-shell/extensions/dynamic-music-pill@andbal
glib-compile-schemas schemas/

6. Restart GNOME Shell:

• X11: Press Alt+F2, type r, and press Enter.
• Wayland: Log out and log back in.

7. Enable the extension via GNOME Extensions, Extension Manager, or:

gnome-extensions enable dynamic-music-pill@andbal

This extension also provides a Nix Flake for easy installation directly from GitHub.

# GNOME 45-49:
nix profile add github:Andbal23/dynamic-music-pill

# GNOME 50:
nix profile add github:Andbal23/dynamic-music-pill#gnome50

Add the input to your flake.nix:

inputs.dynamic-music-pill.url = "github:Andbal23/dynamic-music-pill";

Then add the package to your configuration.nix or Home Manager config:

# GNOME 45-49:
environment.systemPackages = [
  inputs.dynamic-music-pill.packages.${pkgs.system}.default
];

# GNOME 50:
environment.systemPackages = [
  inputs.dynamic-music-pill.packages.${pkgs.system}.gnome50
];

Rebuild your system with sudo nixos-rebuild switch and you're good to go!

The Real-Time visualizer mode requires the cava package to be installed.

Translations are managed on Weblate. No coding knowledge is required.

1. Click the badge below to visit the translation page.
2. Sign in with your GitHub account.
3. Select your language and start translating.

The Preferences window is organized into five tabs.

Each of the five interaction types can be assigned one of the following actions: None, Play/Pause, Next Track, Previous Track, Open Player App, Close Player App, Open Pop-Up Menu, Select Player, Open Settings.

When the extension cannot automatically identify a media player's window for the Open/Close App actions, a manual mapping table allows pairing the MPRIS player name to its correct window App ID.

Running players are detected live via D-Bus. Clicking Use This next to a detected player adds it to the mapping table. You then type in the correct App ID and save. Saved mappings can be edited in-place or deleted individually.

To find a player's App ID: press Alt+F2, type lg, open the Windows tab, and look at the wmclass: or app: field for the player window. Remove the .desktop suffix if present.

Common App ID examples:

This project is licensed under the GPL-3.0 License.

Made with ❤️ for the GNOME community.