wehub-resource-sync
87 lines
4.5 KiB
Markdown
87 lines
4.5 KiB
Markdown
# cliamp quickshell widget
|
|
|
|
A compact "now playing" card for [Quickshell](https://quickshell.org) (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:
|
|
|
|
```sh
|
|
qs -p contrib/quickshell/shell.qml
|
|
```
|
|
|
|
Or install as a named Quickshell config:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```qml
|
|
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.
|