Development
Internals
Crate layout, config parsing modules, and packaging notes.
Workspace Layout
| Crate | Responsibility |
|---|---|
crates/common | Shared config model and spectrum frame types |
crates/daemon | Audio-activity daemon and overlay process lifecycle |
crates/engine | Visualizer frame source contracts and runtime backend |
crates/overlay | GTK4 and layer-shell overlay UI and renderer |
crates/control | kwybarsctl CLI commands and diagnostics |
Common Config Modules
| File | Purpose |
|---|---|
crates/common/src/config/model.rs | Config enums, structs, defaults, and error types |
crates/common/src/config/parse.rs | File loading and config parsing helpers |
crates/common/src/config/tests.rs | Parser and default regression tests |
crates/common/src/config/mod.rs | Stable public exports |
Overlay Rendering Modules
| File | Purpose |
|---|---|
crates/overlay/src/ui/draw/linear.rs | Line, frame, and mirror placement helpers |
crates/overlay/src/ui/draw/wave.rs | Wave geometry and curve paths |
crates/overlay/src/ui/draw/centered.rs | Radial and polygon geometry |
crates/overlay/src/ui/draw/particles.rs | Particle and floating-particle placement |
crates/overlay/src/ui/draw/path.rs | Cairo path builders |
crates/overlay/src/ui/draw/tests.rs | Draw regression tests |
Runtime Behavior Notes
- overlay and daemon both debounce config reloads
- visual-only changes do not restart the audio probe unnecessarily
- daemon-launched overlays subscribe to the daemon frame socket, avoiding duplicate Cava or PipeWire helper processes in the normal workflow
- monitor selection changes rebuild the window set
- theme file changes are hot reloaded
- invalid config reloads leave the current runtime config active
If [daemon].overlay_command or overlay_args changes during a hot switch, the daemon restarts the overlay so the new command takes effect immediately.
Packaging Notes
- AUR VCS packaging lives under
aur/kwybars-git - binary packaging lives under
aur/kwybars-bin - example config should install to
/usr/share/doc/kwybars/examples/config.toml - built-in themes should install to
/usr/share/kwybars/themes - the user unit should install to
/usr/lib/systemd/user/kwybars-daemon.service
kwybars-bin uses the GitHub release tarball named kwybars-version-x86_64-linux.tar.gz.