Omarchy Cliamp Player

A third-party Omarchy bar widget for cliamp: playback controls, 30 synchronized visualizer modes, a demand-driven live spectrum, and a screen-local now-playing card.

Features

• Native horizontal and vertical Omarchy bar layouts
• Playback, seeking, previous/next, stop, shuffle, repeat, and volume controls
• Right-click play/pause, middle-click next, and scroll-volume bar gestures
• Serialized transport commands that cannot overtake each other or accept stale status
• All 30 built-in cliamp vis modes, synchronized with cliamp's TUI
• Mode-specific Canvas rendering using live 16-band spectrum data
• Automatic now-playing card with hover-aware dismissal
• Analyzer active only while the popup or now-playing card is visible
• ffmpeg default-monitor capture with cliamp visstream fallback
• Live Omarchy colors, fonts, spacing, and bar placement

Screenshots

Bars	Wave	Sand

Requirements

• Omarchy with third-party shell plugin support
• cliamp v1.63.2 or newer on PATH
• Python 3
• One spectrum backend:
  • Preferred: ffmpeg with PulseAudio input support
  • Fallback: cliamp visstream
• Optional: pactl for resolving the current default output monitor by name

The ffmpeg backend observes the complete default PipeWire/PulseAudio output mix, so other audible applications can influence the spectrum. Sink changes are detected and reopened automatically. If ffmpeg fails, the analyzer falls back to cliamp visstream; playback controls and metadata remain available if both backends fail.

Install

The repository root is the plugin package. Omarchy clones it directly into ~/.config/omarchy/plugins/io.github.dylanmccavitt.cliamp-player and validates manifest.json before enabling any code.

omarchy plugin add https://github.com/dylanmccavitt/omarchy-cliamp-player.git --enable

For a non-interactive installation after reviewing the repository:

omarchy plugin add https://github.com/dylanmccavitt/omarchy-cliamp-player.git --enable --yes

The manifest places the widget in the right section by default. Reposition it with Omarchy bar settings or:

omarchy bar move io.github.dylanmccavitt.cliamp-player --section right

Update or remove the git-managed installation with:

omarchy plugin update io.github.dylanmccavitt.cliamp-player
omarchy plugin remove io.github.dylanmccavitt.cliamp-player

Migrating from v0.1.0

The pre-marketplace release used the unnamespaced ID cliamp-player. Omarchy plugin IDs cannot be changed in place, so remove that checkout before installing v0.1.1:

omarchy plugin disable cliamp-player
omarchy plugin remove cliamp-player
omarchy plugin add https://github.com/dylanmccavitt/omarchy-cliamp-player.git --enable

Local checkout

omarchy plugin validate .
mkdir -p ~/.config/omarchy/plugins
rm -rf ~/.config/omarchy/plugins/io.github.dylanmccavitt.cliamp-player
cp -a . ~/.config/omarchy/plugins/io.github.dylanmccavitt.cliamp-player
omarchy-shell shell rescanPlugins
omarchy plugin enable io.github.dylanmccavitt.cliamp-player

Interaction

Bar

• Left-click: open or close the player
• Right-click: play or pause
• Middle-click: next track
• Scroll: change volume by 2 dB

The icon dims whenever cliamp is not actively playing.

Player

• Click the progress track to seek
• Previous, play/pause, next, and stop controls
• Shuffle and repeat-mode controls
• Volume down/up controls
• Visualizer dropdown for changing the spectrum rendering mode
• Click outside the card or use its close button to dismiss it

Now-playing card

The card appears when cliamp starts or the track changes. Hovering pauses its dismissal timer. Clicking it opens the full player.

Visualizer modes

The dropdown is populated from cliamp vis list. Selecting a row sends cliamp vis <name>, so cliamp's TUI, the popup, and the now-playing card stay on the same mode.

Family	Built-in modes
Bars and meters	Bars, Bars Dot, Bars Outline, Bricks, Columns, Classic Peak, Ascii, Classic LED, Stereo
Plots and symmetry	Wave, Scope, Heartbeat, Butterfly, Terrain, Retro, Pulse
Particles and scenes	Rain, Scatter, Flame, Matrix, Binary, Sakura, Firework, Bubbles, Firefly, Mosaic, Sand, Geyser, Logo
Disabled	None

Cliamp exposes normalized spectrum bands, not its terminal framebuffer. Spectrum.qml reproduces each mode's visual language with a native Canvas renderer rather than copying terminal cells. Colors continue to follow the active Omarchy theme.

Settings

The Omarchy bar settings panel exposes:

• maxWidth: maximum horizontal track-label width, 80–400 px
• showArtist: include the artist in the horizontal bar label
• autoHideMs: now-playing card duration, 1500–15000 ms

Shell lifecycle

Cliamp Player uses Omarchy's live bar-widget lifecycle. These commands continue working after bar and plugin reloads:

omarchy-shell shell summon io.github.dylanmccavitt.cliamp-player
omarchy-shell shell hide io.github.dylanmccavitt.cliamp-player
omarchy-shell shell toggle io.github.dylanmccavitt.cliamp-player

Repository structure

Omarchy requires a single-plugin git repository with manifest.json and every declared entry point at the repository root.

manifest.json             Omarchy metadata, entry point, placement, and settings schema
Widget.qml                Bar integration and pointer lifecycle
PlayerController.qml      Serialized cliamp commands, status, and analyzer lifecycle
PlayerPopup.qml           Interactive player panel
NowPlayingOverlay.qml     Song-change card
Spectrum.qml              30-mode Canvas renderer
analyzer.py               Bounded ffmpeg/visstream spectrum backend
README.md                 Installation, controls, architecture, and troubleshooting
LICENSE                   MIT terms and retained upstream notice
screenshots/              Publication images; not loaded at runtime

The repository contains no install hooks, symlinks, privileged commands, vendored dependencies, or machine-specific paths. Plugin code runs only after Omarchy validates, installs, and enables it.

Verify

omarchy plugin validate .
qmllint *.qml
python3 -c 'from pathlib import Path; p = Path("analyzer.py"); compile(p.read_bytes(), str(p), "exec")'
ruff check analyzer.py
cliamp status --json | jq -e '.ok and (.visualizer | type == "string")'
cliamp vis list

Runtime verification requires active cliamp playback because spectrum data is intentionally not mocked.

Troubleshooting

Metadata works but the visualizer is empty

Confirm that cliamp is playing and that at least one capture backend works:

ffmpeg -hide_banner -f pulse -i @DEFAULT_MONITOR@ -t 1 -f null -
cliamp visstream --fps 5

The selected mode does not change

cliamp vis list
cliamp vis ClassicLED
cliamp status --json | jq -r '.visualizer'

The expected final output is ClassicLED.

Relationship to the existing cliamp overlay

This repository publishes io.github.dylanmccavitt.cliamp-player, an independent bar-widget plugin. The cliamp plugin in bjarneo/omarchy-shell-plugins is a persistent overlay with a different plugin ID, entry point, process model, and interface.

Both can be installed because their IDs do not conflict. Enabling both is usually unnecessary because each provides a now-playing card.

The initial Winamp-style segmented-analyzer behavior and now-playing concept were informed by that MIT-licensed plugin. Its copyright notice is retained in LICENSE. The interactive player, serialized command controller, demand-driven analyzer, 30-mode renderer, and bar integration are separate implementations.

License

MIT. See LICENSE for the retained upstream notice and this project's copyright.