cliamp

The cliamp quickshell widget is a compact (300 x 72) "now playing" card designed for Quickshell. It displays media information (title, artist, time) and features a 10-band Winamp 2-style spectrum visualizer.

Key Features:

• Automatic Visibility: Hides itself when cliamp is not running.
• Live Theming: Colors are pulled from the active Omarchy theme (~/.config/omarchy/current/theme/colors.toml) and update live when the theme changes.
• Interactivity: Click the card to seek; press Esc or Q to quit the widget.
• Visualizer: Uses a 10-band spectrum driven by cliamp visstream via IPC.

Requirements:

• Linux only.
• Quickshell 0.2+.
• cliamp running with its default MPRIS service enabled (org.mpris.MediaPlayer2.cliamp).

The widget provides a notification-sized 'now playing' card with the following capabilities:

• Visuals: A 300 x 72 card centered at the bottom of every screen featuring a Winamp 2-style LED spectrum analyzer with falling peak caps.
• Controls: Track title and artist display, a click-to-seek progress bar with time readout, and vector transport icons (prev / play-pause / next).
• Theme Integration: Automatically follows the active Omarchy theme (background, foreground, accent, color1..color8, selection_background). The card border tracks the Omarchy selection_background (falling back to color8).
• Dismissal: Click the card and press Esc or Q to dismiss it.

Cliamp integrates with operating system media control infrastructure to allow external control of playback, metadata, and volume.

• Linux: Uses MPRIS2 over D-Bus. Requires a running D-Bus session bus.
• macOS: Uses MPNowPlayingInfoCenter and MPRemoteCommandCenter. No additional requirements as frameworks are built-in.
• Other platforms: Uses a no-op stub.

A variety of community-built plugins are available to extend cliamp functionality, primarily focusing on audio visualization and service integration.

Available Plugins:

• Audio Visualizers:

  • cliamp-plugin-led-burst: Stereo LED matrix visualizer
  • cliamp-plugin-block-burst: Stereo LED block matrix visualizer
  • cliamp-plugin-vu-meter: Analog multi VU meter style visualizer
  • cliamp-plugin-nightrider: Nightrider style visualizer
  • cliamp-plugin-tubeamp: Vacuum-tube amplifier visualizer
  • cliamp-plugin-nova: Concentric-ring spectrum visualizer
  • cliamp-plugin-mandelbrot: Zooming psychedelic Mandelbrot set visualizer (features braille rendering and bass reactivity)

• Service Integrations:

  • cliamp-lastfm: Last.fm scrobbling

Navigate and manage local files:

• ↑ / ↓ or j / k: Move cursor
• ← / → or h / l or Enter: Back / open directory or file
• /: Filter files
• Space: Select or unselect file/directory
• a: Select/unselect all visible audio files
• R: Replace current queue with selected files
• w: Write selected files to a local playlist
• ~ / .: Jump to home / current working directory
• Esc o: Close file browser

Manage the playback queue and playlist:

• a: Toggle queue (play next)
• A: Open Queue manager
• x: Remove highlighted track from current playlist
• p: Open Playlist manager
• r: Cycle repeat (Off / All / One)
• z: Toggle shuffle

Once authenticated, you can access your Qobuz library through the provider panel.

Navigation & Search:

• Use Esc or b to open the provider browser and select Qobuz.
• Press Q to jump directly to Qobuz.
• Press Ctrl+F to search the Qobuz catalog for tracks.
• Press Ctrl+R to refresh (re-resolves stream URLs) if playback stalls.

Library Content:

• Favorite Tracks: Your liked songs.
• Random Tracks: A random sample of up to 500 unique tracks from your playlists. Press Ctrl+R to reshuffle.
• Your playlists: Your created or subscribed playlists.
• Favorite albums/artists: Browsable views for your favorites.

To use the Quickshell Now-Playing Widget (Omarchy), you must meet the following requirements:

• Quickshell 0.2+
• A running cliamp: Required on Linux to provide the MPRIS service and IPC socket for live spectrum data.
• Omarchy (Optional for functionality, required for theme integration): If Omarchy is installed, the widget uses ~/.config/omarchy/current/theme/colors.toml for its palette. Without Omarchy, the widget falls back to built-in kanagawa-dragon-ish default colors.

To access private likes, hidden uploads, or SoundCloud Go+ subscriber-gated tracks, you must allow yt-dlp to use your browser's session. This is done by setting the cookies_from option in your [soundcloud] configuration.

Supported browser names include:

• firefox
• chrome
• chromium
• brave
• edge
• opera
• safari
• vivaldi

As long as you are signed into SoundCloud in the specified browser, cliamp will act as your logged-in user.

[soundcloud]
enabled = true
user = "yourname"
cookies_from = "firefox"

You can run the widget immediately without installation, or install it as a named Quickshell configuration.

Run without installing:

qs -p contrib/quickshell/shell.qml

Install as a named Quickshell config:

mkdir -p ~/.config/quickshell
ln -s "$PWD/contrib/quickshell" ~/.config/quickshell/cliamp
qs -c cliamp

After installation, ensure cliamp is running in another terminal to see the card appear on every screen.