bjarneo--cliamp/contrib/quickshell

cliamp quickshell widget

A compact "now playing" card for Quickshell (300 x 72), centered along the bottom of every screen and driven by cliamp's MPRIS service (org.mpris.MediaPlayer2.cliamp). Two-row layout: title + time on top, artist + transport on the second row, a 10-band Winamp 2-style spectrum below, and a thin click-to-seek line at the bottom. Colors are picked up from the active Omarchy theme (~/.config/omarchy/current/theme/colors.toml) and update live when the theme changes. Hides itself when cliamp is not running. Click the card and press Esc or Q to quit the widget.

Linux only. Requires Quickshell 0.2+ and cliamp running with its default MPRIS service enabled (it is by default on Linux).

Quick start

Run it directly without installing:

qs -p contrib/quickshell/shell.qml

Or install as a named Quickshell config:

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

Then start cliamp in another terminal. The card appears on every screen, anchored to the bottom edge.

Customization

Theme colors come from Omarchy's active theme file:

~/.config/omarchy/current/theme/colors.toml

Mapping into the widget:

Omarchy key	Widget role
background	card background
foreground	primary text (title)
accent	progress fill, seek handle, play/pause icon
color2	visualizer bottom LED rows (green slot), play/pause hover
color3	visualizer mid LED rows + peak caps, prev/next hover (yellow slot)
color1	visualizer top LED rows (red slot)
selection_background	card border (falls back to color8)
color8	secondary text + prev/next icons, time readout (falls back to a darker foreground)

The card border uses selection_background (a muted dark gray in most Omarchy themes), falling back to color8 if that key is missing. Switching theme rewrites colors.toml in place; the widget watches it and re-applies colors live (no reload needed).

To reposition the card, edit shell.qml. The defaults anchor a transparent full-width strip to the bottom of every screen and center a 300 x 72 card inside it with a 16 px gap from the edge:

PanelWindow {
    anchors { bottom: true; left: true; right: true }
    margins { bottom: 16 }
    implicitHeight: 72
    color: "transparent"

    NowPlaying {
        width: 300
        height: parent.height
        anchors.horizontalCenter: parent.horizontalCenter
    }
}

Swap bottom for top to flip to the top edge, or replace the horizontalCenter anchor with anchors.left / anchors.right to push it into a corner.

Files

File	Purpose
shell.qml	Entry point. Wires up a PanelWindow per screen and finds cliamp on the MPRIS bus.
NowPlaying.qml	The bar widget itself.
TransportButton.qml	Reusable prev/play/next button (hover + enabled state).
MediaIcon.qml	Resolution-independent transport icons drawn with Canvas2D (prev / play / pause / next / stop).
Visualizer.qml	Canvas-based ClassicPeak spectrum (bars + falling peak markers).
BandStream.qml	Wraps cliamp visstream and exposes the live 10-band frames as reactive properties.

Notes

• The widget polls MprisPlayer.position on a 250 ms timer while playing, since Quickshell's MPRIS service does not emit reactive updates for position drift.
• Player detection uses dbusName === "cliamp" (cliamp registers the well-known name org.mpris.MediaPlayer2.cliamp in mediactl/service_linux.go).
• Clicking the progress bar issues an MPRIS SetPosition, which cliamp handles via playback.SetPositionMsg.
• Theme colors come from the active Omarchy theme via a FileView watching ~/.config/omarchy/current/theme/colors.toml. The TOML is parsed in QML with a small regex (no external script). Theme swaps update the card without reloading Quickshell.
• Spectrum bands stream over the cliamp IPC socket via cliamp visstream. One long-lived subprocess per widget.
• The widget renders a Winamp 2-style spectrum analyzer: each band is a stack of LED segments with a tiny gap between them, with a falling peak cap. Three-tone gradient across the height — color2 (green) for the bottom rows, color3 (yellow) for the middle, color1 (red) for the top, mirroring the classic Winamp gradient (and the cliamp TUI). The bar block spans the full card width, edge to edge.
• All UI elements use sharp 90-degree corners (no radius) to match a terminal aesthetic.