Skip to Content
Kwybars
Development

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/.

ModuleResponsibility
main.rsEntry 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:

FileLocation
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.

On this page