playerctl-mini

Terminal UI for cava spectrum bars.

The visualizer follows the user cava bar layout: 2 terminal cells wide, 1 cell gap, automatic bar count up to cava’s 512 bar limit.

Requirements

• Lua 5.x
• Optional: LuaSocket (lua-socket on Fedora): uses socket.sleep for steadier frame pacing instead of sleep(1) via the shell each frame.
• playerctl
• cava
• PulseAudio or PipeWire
• A real TTY (chmod +x and run in a terminal, not piped)

Run

chmod +x playerctl-mini.lua
./playerctl-mini.lua

Or: lua playerctl-mini.lua

Install

mkdir -p ~/.local/bin
cp playerctl-mini.lua ~/.local/bin/playerctl-mini
chmod +x ~/.local/bin/playerctl-mini

This installs the executable as ~/.local/bin/playerctl-mini. Make sure ~/.local/bin is in your PATH.

To uninstall:

rm -f ~/.local/bin/playerctl-mini

Keys

Key	Action
h	Previous
Space	Play / pause
l	Next
q	Quit

Playback controls use plain playerctl and affect the default MPRIS player. There is no YouTube Music filtering.

Environment

Variable	Purpose
PLAYERCTL_MINI_CAVA_SOURCE	Cava input source name (see pactl list sources short). If unset, cava uses source = auto.
PLAYERCTL_MINI_CAVA_METHOD	pulse (default) or pipewire.
PLAYERCTL_MINI_CAVA_SENSITIVITY	Cava sensitivity (50-200, default 100). Only used when autosens is off (see below).

Cava uses autosens = 0, fixed sensitivity (tune with PLAYERCTL_MINI_CAVA_SENSITIVITY), framerate = 60, bar_width = 2, bar_spacing = 1, lower_cutoff_freq = 50, higher_cutoff_freq = 10000, sleep_timer = 0, and noise_reduction = 77. Cava produces low-latency raw frames at 60 Hz; the UI also renders at 60 FPS and applies a light interpolation pass so movement has more intermediate steps instead of jumping between heights.

The UI never reads directly from cava’s pipe. A small runner script blocks on cava in the background and atomically writes the latest complete frame to /tmp/playerctl_mini_cava.frame; the UI only reads that snapshot, so a slow pipe read cannot freeze rendering.

Files

• Generated cava config: /tmp/playerctl_mini_cava.conf (overwritten on start / resize).
• Generated cava runner: /tmp/playerctl_mini_cava_runner.sh.
• Latest cava frame snapshot: /tmp/playerctl_mini_cava.frame.