4c39ecd5d2
The `route.set <app> <route>` overlay used to emit a single
`RouteRule` keyed on `process_binary`. The matcher ANDs across
non-empty fields, so a stream that didn't advertise
`application.process.binary` would miss the rule even though
its `application.name` was a perfect match. pw-cat is the
canonical hit — it sets `application.name = "pw-cat"` and
`node.name = "pw-cat"` but leaves `process.binary` unset
entirely. The same goes for several Electron and Flatpak
wrappers where the wrapping process eats the binary name.
`apply_route_overrides` now emits TWO rules per override, one
keyed on each identity field, with the same route. PipeWire
iterates rules in order and returns on first match, so the
effect is an OR across `process_binary` and `application_name`
for the single override — exactly the "match by whatever name
the stream advertises" intent of the CLI verb.
Why two rules and not "loosen the matcher to OR these two
fields": the matcher's AND-across-fields is load-bearing for
profile-author rules like `{process_binary: ["firefox"],
media_role: ["voice"]}` (match firefox-with-voice-role only).
Loosening the matcher would silently break those. Two
single-field rules with the same route preserve the original
semantics and add zero risk.
`is_single_app_rule_for_any` (the retain pre-pass that drops
old override rules before re-emitting) extends to recognise
the application_name-only variant too, so re-setting or
unsetting an override leaves no residual rules.
Tests
- `profile_store::tests::set_route_emits_both_process_binary_and_application_name_rules`
asserts both variants exist after `set_route`.
- `profile_store::tests::set_route_then_unset_leaves_no_residual_rules`
catches the matching retain-pre-pass regression that would
have leaked rules on unset.
- `routing::tests::application_name_only_rule_matches_stream_with_no_process_binary`
proves a stream with `application.name = "pw-cat"` and no
`process.binary` actually matches the application_name-keyed
rule path. 194 tests pass (was 191; +3 for the new
coverage); clippy clean.
Live verification
Daemon up, pw-cat → headroom-processed (default rule).
`headroom route set pw-cat bypass`: pw-cat's link snaps to
`Mbox:playback_FL` within one drain tick (~50 ms); status
reports `route: bypass`. Layer A tap survives the transition
intact. `headroom route unset pw-cat`: snaps back to
`headroom-processed:playback_FL`. Both transitions are
audibly clean against the F2 audio-gap mitigation from
`
|
||
|---|---|---|
| contrib/systemd | ||
| crates | ||
| docs | ||
| nix | ||
| profiles | ||
| .gitignore | ||
| Cargo.lock | ||
| Cargo.toml | ||
| flake.lock | ||
| flake.nix | ||
| IPC.md | ||
| PLAN.md | ||
| README.md | ||
| rust-toolchain.toml | ||
headroom
AGC + compressor + true-peak limiter daemon for PipeWire, in Rust.
Headroom puts a per-application audio safety net between noisy sources (browsers, voice chat, random video) and your speakers, while leaving the things you don't want compressed (music players, games, DAWs) untouched.
- Hard −0.1 dBTP ceiling on the processed route, with proper
inter-sample-peak handling, enforced inline so the contract holds
regardless of control-plane state. Streams routed
bypassride the real sink directly and are not in scope of the contract — that's the trade-off that makes the per-app exclusion useful. - Per-app exclusion with profile-driven rules.
- Layer A per-app level control (peak + RMS detector → smoothed
channelVolumeswrites) for taming individual streams without touching the bus path. Zero added signal-path latency; safe to use on bypass-routed streams. - Single binary daemon + CLI, controlled over a Unix-domain socket
with a documented JSON wire protocol (see
IPC.md). - First-party Rust crate (
headroom-client) for programmatic use; third-party clients (Qt panels, status bars, …) target the wire protocol directly. - Live profile reload — edit a TOML file in
$XDG_CONFIG_HOME/headroom/profiles/and the daemon picks up changes within ~500 ms; the audio thread doesn't glitch.
See PLAN.md for the full design and roadmap.
Status
Alpha. The signal chain (AGC, compressor, two-tier limiter, Layer A
per-app), the routing engine (explicit-link enforcement, sink hotplug,
sticky default sink), the IPC server with topic subscriptions, the
headroom monitor TUI, and live profile reload all work end-to-end.
Packaging exposes a systemd user unit and Nix modules. What's missing
is real-world soak time on multi-rate / Bluetooth setups and other
distros' init systems.
Installing
Nix (flake)
This repo is a flake; the daemon plus its systemd user unit and the canonical profiles are exposed as a package.
nix run github:amaanq/headroom -- daemon # one-shot run
nix profile install github:amaanq/headroom # add to $PATH
For Home Manager, add the flake as an input and enable the module:
{
inputs.headroom.url = "github:amaanq/headroom";
# In your Home Manager configuration:
imports = [ inputs.headroom.homeModules.default ];
services.headroom.enable = true;
}
The module symlinks the shipped profiles into
$XDG_CONFIG_HOME/headroom/profiles/, drops the systemd user unit
into the user's services dir, and the unit starts after PipeWire and
WirePlumber come up. services.headroom.extraProfiles lets you add
your own.
For NixOS (system-wide binary install + systemd-user discovery):
{
inputs.headroom.url = "github:amaanq/headroom";
# In your NixOS configuration:
imports = [ inputs.headroom.nixosModules.default ];
programs.headroom.enable = true;
}
Then any user can systemctl --user enable --now headroom.
Other distros (manual)
cargo install --path crates/headroom-cli # or: cargo build --release
# Profiles
mkdir -p ~/.config/headroom/profiles
cp profiles/*.toml ~/.config/headroom/profiles/
# systemd user unit (edit the ExecStart path to point at your binary)
install -Dm644 contrib/systemd/headroom.service \
~/.config/systemd/user/headroom.service
sed -i "s|@bindir@|$(dirname "$(command -v headroom)")|" \
~/.config/systemd/user/headroom.service
systemctl --user daemon-reload
systemctl --user enable --now headroom
Usage
Once the daemon is running:
headroom status # JSON snapshot — sinks, streams, active profile
headroom profile list # available profiles
headroom profile use night # activate one
headroom monitor # full-screen TUI (bus gauges + per-stream)
headroom monitor --json meters # line-delimited JSON, for scripting
headroom route set firefox processed
headroom set compressor.threshold_db -28
headroom bypass on # kill switch — straight to the real sink
See headroom --help for the full surface.
Building
nix develop # toolchain + pipewire dev libs + helpers
cargo build # iterate
cargo test --workspace
nix build # final packaged headroom binary
License
GPL-3.0-or-later for the daemon and CLI. headroom-dsp and headroom-ipc
are MPL-2.0 so they can be reused by non-GPL plugin hosts and clients.