Internals
How Kwybars is put together, its module layout, and packaging notes.
How It Works
Kwybars is one process with two long-lived threads.
- The audio thread captures the monitor of the default PipeWire output, runs a frequency analysis on it, and publishes the newest spectrum.
- The main thread owns the Wayland connection and the event loop. It turns the newest spectrum into bar motion, draws into shared-memory buffers, and hands them to one layer-shell surface per selected monitor.
Config files and images are read on short-lived worker threads, so the main thread never waits on the disk.
When nothing plays, the audio thread sleeps, no surface is mapped, and nothing is drawn.
Module Layout
All code lives under src/.
| Module | Responsibility |
|---|---|
main.rs | Entry point: parses the command line and hands off |
cli/ | Command-line parsing and the subcommands |
app/ | Startup, event loop wiring, reload handling, shutdown |
config/ | Config schema, parsing, older-key compatibility, themes, colors.toml |
audio/capture/ | PipeWire stream and the audio thread |
audio/spectrum/ | Windowing, FFT, and mapping to bars |
audio/dynamics/ | Bar motion: sensitivity, smoothing, falloff |
activity/ | Deciding when audio counts as playing, and the fades |
wayland/ | Monitors, layer surfaces, scaling, buffers |
render/ | Drawing: colors, per-layout geometry, the image overlay |
reload/ | File watching and debounced config loading |
Logic that does not need Wayland or PipeWire (config, geometry, spectrum, dynamics, activity) is kept free of those types and is covered by unit tests.
Runtime Behavior Notes
- config reloads are debounced, so a burst of quick edits is applied once
- only the part a change touches is rebuilt; a color change does not restart audio capture
- monitor selection changes add and remove surfaces without touching the rest
- theme files,
colors.toml, and the overlay image are watched as well as the config - a config that fails to load leaves the running config active
- redraws follow the monitor's frame callbacks, capped at
framerate, and stop when nothing moves
Packaging Notes
A package installs:
| File | Location |
|---|---|
kwybars | /usr/bin/kwybars |
| man page | /usr/share/man/man1/kwybars.1 |
| example configs | /usr/share/doc/kwybars/examples/ |
| theme files | /usr/share/kwybars/themes/ |
| user unit | /usr/lib/systemd/user/kwybars.service |
The only runtime dependency is PipeWire (libpipewire-0.3). Building needs the PipeWire development files, pkg-config, and libclang.
The built-in themes are compiled into the binary; the theme files are installed as well so users can copy and adapt them.