# Headroom A Rust AGC + compressor + true-peak limiter for PipeWire. Per-application exclusion, profile-based presets, single-binary daemon, scriptable over a Unix-domain socket. This document is the canonical plan. It supersedes the earlier conversational sketch. --- ## 1. Goals & non-goals ### Goals - **Hard safety net.** Output is guaranteed to stay below a configurable ceiling (default **−0.1 dBTP**) with proper inter-sample peak handling. This guarantee survives daemon misbehaviour, profile reloads, and bad routing decisions — it is enforced inline in the audio path. - **Per-application exclusion.** Music players, games, and DAWs route around the processor; browsers, voice chat, and "everything else" go through it. Rules are app-level and live in profiles. - **Drop-in defaults.** First-run experience: install, enable user service, done. No mandatory config. Power users edit TOML or use the CLI. - **Profiles** for distinct listening scenarios (default / night / speech / transparent / bypass-all). - **Single binary.** Daemon, filter, routing, and control loop all live in one process. The DSP kernels are a separate crate so they can be reused (LV2/standalone) later. - **Scriptable.** Unix-domain-socket IPC with a documented JSON schema so anyone can write an alternative client (Qt/QuickShell panel, Eww widget, scripts). A first-party Rust crate (`headroom-ipc`) wraps it. - **Rust, lean dep tree.** No NIH where mature crates exist, no bloat where they don't. ### Non-goals (v0) - Surround / >2-channel content. v0 is stereo only; >2ch is routed directly to the real sink, untouched by Headroom's filter chain. - LV2/CLAP plugin distribution. The DSP crate is plugin-shaped so this is cheap to add later, but it's not a v0 deliverable. - GUI. Third parties can build one against the IPC. - Capture-side processing (microphone). v0 is playback only. --- ## 2. Architecture Each app's audio takes one of four end-to-end paths, chosen by two **orthogonal** profile flags: a routing decision (processed vs. bypass) and a per-app level-control flag (on vs. off). ``` ┌─── optional, opt-in per app (Layer A) ────────────────┐ │ │ │ ┌─► passive tap ─► peak + RMS ─► AppLevelController │ │ │ (sibling link in same quantum) │ │ │ │ │ │ │ │ Props.channelVolumes write ◄──────┘ │ │ │ │ └───┼───────────────────────────────────────────────────┘ │ │ APP STREAM NODE │ ┌──────────────────────────┐ │ │ raw output │ app's audio ───►├──►│ × channelVolumes │──► output port │ └──────────────────────────┘ │ │ └────────────────────────────────────────────│ │ routing decision (Layer B) │ target.object set by daemon │ │ ┌─────────────────────────────────────────┴┐ ▼ ▼ route = "bypass" route = "processed" target.object = target.object = preferred_real_sink headroom-processed │ │ │ ▼ │ ┌─────────────────────┐ │ │ headroom-processed │ │ │ (virtual sink, the │ │ │ system default) │ │ └─────────┬───────────┘ │ ▼ │ ┌─────────────────────┐ │ │ headroom-filter │ │ │ (pw_stream pair) │ │ Layer C (bus DSP) │ AGC → compressor │ │ │ → soft → hard │ │ └─────────┬───────────┘ │ │ ▼ ▼ preferred_real_sink ◄──────────────────────► (DAC) ``` ### The four end-to-end paths | | Routing = bypass | Routing = processed | |---|---|---| | **per-app off** | ① **true bypass** — Headroom touches nothing on the signal path. Same latency as if Headroom weren't installed. | ③ **bus DSP only** — stream flows through `headroom-processed` and the inline chain. `channelVolumes` left at whatever the user/app set. | | **per-app on** | ② **per-app only** — level-reactive `channelVolumes` writes, no graph hop. Zero added signal-path latency. | ④ **full stack** — per-app level control *and* bus DSP. Maximum protection. | Path-by-path properties: | Path | Signal-path latency added | Limiter contract? | Per-app gain ride? | |---|---|---|---| | ① bypass / per-app off | 0 | no | no | | ② bypass / per-app on | 0 | no | yes (Layer A) | | ③ processed / per-app off | filter hop + ~2 ms lookahead | yes (Layer C hard tier) | no | | ④ processed / per-app on | filter hop + ~2 ms lookahead | yes (Layer C hard tier) | yes (Layer A) | The two flags are independent. A competitive game's typical config is ①: zero Headroom involvement in its audio. A user concerned about notification dings on top of that game would put Discord on ② or ④ (so notifications get tamed via Discord's own `channelVolumes`) while leaving the game on ①. ``` headroom-core (daemon, one process) • per-app level controllers (Layer A) • routing engine + preferred_real_sink (Layer B) • slow AGC loop, profile manager (Layer C) • IPC server │ ▼ $XDG_RUNTIME_DIR/headroom/control.sock │ ┌───────────┴───────────┐ ▼ ▼ headroom CLI third-party clients (Qt panel, widgets, …) ``` See §4 for Layer A's mechanics and §5 for the PipeWire-level details of Layers B and C. ### One virtual sink, one daemon process - `headroom-processed` — virtual sink. Set as the system default so new streams land in it by default. Its monitor is captured by `headroom-filter`, pushed through the DSP graph, and emitted to the current `preferred_real_sink`. - **No bypass sink.** Streams marked `route = "bypass"` are pointed directly at `preferred_real_sink` via a `target.object` metadata write. They pay zero added latency vs. running without Headroom installed at all — there's no extra graph hop, no extra DSP. The word "bypass" in the profile DSL means "route directly to the real sink, untouched." - The **daemon** owns: - the one virtual sink (created on startup, torn down on exit); - the filter (a pair of `pw_stream`s — capture + playback — running on PipeWire's realtime audio thread, with the playback half targeting `preferred_real_sink`); - one **`AppLevelController`** per managed app stream (§4), each with its own passive `pw_stream` tap, peak/RMS envelopes, and `Props.channelVolumes` writer. Created/destroyed on stream lifecycle events. - **`preferred_real_sink` tracking.** The daemon watches the `default.audio.sink` metadata key. When the user changes the system default (via pavucontrol, `wpctl set-default`, etc.) to a hardware sink, the daemon (a) treats that sink as the new `preferred_real_sink`, (b) re-links `headroom-filter`'s playback stream to it, and (c) rewrites `target.object` for every currently-bypassed stream so they follow. Hotplug / Bluetooth handoffs use the same machinery. - the slow AGC loop (reads loudness, writes gain target into the filter via an `rtrb` channel); - the routing engine (subscribes to the PipeWire registry, evaluates rules on new streams, writes `target.object` to the `default` metadata: either `headroom-processed` for processed streams or `preferred_real_sink` for bypassed streams); - the IPC server. ### Why no `headroom-bypass` sink An earlier iteration of the design had a second virtual sink (`headroom-bypass`) that loopback'd to the real sink, so "bypassed" streams routed to it. This added one PipeWire quantum of latency to every bypassed stream for no functional benefit — `module-loopback` buffers across the quantum boundary even when the DSP is a no-op. Direct routing via `target.object` skips the hop entirely. The win is real for competitive games, DAW monitoring, and music players: they now ride exactly the same path they'd take if Headroom weren't installed. ### Why this is *not* the "analytical sink + adjust master volume" ### shape originally proposed Volume control via SPA `Props` updates is not sample-accurate. A true-peak limiter needs a small internal delay line so gain reduction is applied to the same samples that were analyzed. Therefore the **brickwall must be inline**. The analytical-monitor approach is still used — for the *slow* AGC loop, where multi-second time constants make control-plane latency irrelevant — but it cannot own the ceiling. ### Why a `pw_stream` pair, not an LV2 plugin in `module-filter-chain` LV2 is not native to PipeWire; it's one of several plugin formats `module-filter-chain` happens to host (via lilv). Using LV2 would split Headroom into a plugin + a daemon + a filter-chain JSON, pull in a lilv runtime, and force gain-target updates through a 32-bit-float control-port abstraction. A `pw_stream` capture+playback pair is the same pattern `module-filter-chain` itself uses internally, but written directly in Rust against `pipewire-rs`, in the same process as the rest of the daemon. One binary, no IPC for parameter updates, idiomatic Rust audio thread. An LV2 wrapper of `headroom-dsp` remains a viable optional deliverable for use in DAWs. --- ## 3. DSP ### 3.1 Two-tier true-peak limiter (`headroom-dsp::limiter`) The limiter has **two parallel tiers** sharing the same upsampler, downsampler, delay line, and sliding peak buffer. Both run at the oversampled rate. **Hard tier — the safety contract.** Output ceiling default **−0.1 dBTP**, configurable. Instant attack on the gain envelope plus a brief hold and a slow release. Two defensive `clamp` stages downstream (once in the oversampled domain, once at the input rate after downsampling) guarantee the contract numerically — the envelope can misbehave and the contract still holds. Never bypassed, never disabled. **Soft tier — the comfort cap.** Targets a *dynamic* ceiling computed as `program_lufs + max_psr_db`. Smooth attack/release envelope so the gain reduction sounds like volume riding, not a slap. Pulls transients to a comfortable peak-to-loudness ratio (default 14 dB) *before* they ever threaten the hard ceiling. When the AGC hasn't yet provided a program loudness (startup, after reset), the soft tier falls back to a static ceiling. Disabled by omitting `[limiter.soft]` in a profile — useful for the `transparent` profile where users want pure brickwall behavior. Algorithm (per oversampled sample, after upsampling): 1. Push raw `|s|` into the sliding-window peak buffer; read the max-of-window. 2. **Soft tier** computes target = `soft_ceiling / window_peak` (clamped to ≤ 1), runs through the smooth attack/release envelope, yields `soft_gain`. 3. **Hard tier** predicts the worst-case effective peak after the soft tier acts (max of `window_peak * soft_gain` and the asymptote `min(window_peak, soft_ceiling)`), then sizes `hard_target` to keep that under the hard ceiling. Instant attack, hold, exponential release. Yields `hard_gain`. 4. `total_gain = min(soft_gain, hard_gain)`. 5. Multiply the delayed sample by `total_gain`. 6. Clamp at hard ceiling (defense-in-depth). 7. Downsample, clamp again at hard ceiling at the input rate. When the soft tier is doing its job, the hard tier's "predicted-post-soft" target stays above 1.0 and the hard tier never engages. When the soft tier is mid-attack (peak just arrived), the hard tier snaps in as a safety, then releases as the soft tier catches up. The compressor and AGC stages run *before* the limiter. ### 3.2 Feed-forward compressor (`headroom-dsp::compressor`) Standard shape: log-domain detector (peak or RMS, switchable) → ratio + soft knee → attack/release envelope smoother → makeup gain → linear gain → apply to (small) delayed input. ~150 lines of clean code. Defaults aimed at "gentle, transparent": threshold −24 dBFS, ratio 2.5:1, knee 6 dB, attack 10 ms, release 100 ms, makeup auto. ### 3.3 Slow AGC (`headroom-core::agc`) Algorithmic descendant of EasyEffects' `autogain.cpp`. Runs *outside* the audio thread, on a ~50 ms control tick. - Feeds the audio thread's monitor tap into `ebur128` with `Mode::M | S | I | TRUE_PEAK`. - Computes `target_gain_dB = target_lufs − measured_lufs`. - Smooths with separate attack/release coefficients (leaky integrator). - Gates when momentary loudness < silence threshold. - Soft-clamps so the AGC can never push more than ±N dB (profile knob). - Writes the new gain target into the audio thread via an `rtrb` queue. The AGC's gain is applied *before* the compressor. The compressor and limiter still own their own behaviour and ceilings. ### 3.4 Measurement: `ebur128` `Mode::M | S | I | TRUE_PEAK`. EBU TECH 3341/3342 conformant via the `ebur128` crate. Constructed on the daemon thread; fed from a ring-buffer consumer that pulls from the audio thread. The audio thread allocates nothing. This is **bus-level** measurement only — used to drive the slow AGC loop and meter the processed sink output. Per-app measurement (§4) uses a different, much cheaper metric. --- ## 4. Per-application level control (Layer A) An opt-in, near-zero-latency feedback loop that watches each managed application's output stream and adjusts its `Props.channelVolumes` multiplier in response to **two parallel level metrics**: - a **fast peak envelope** that catches short bursts and sustained loud passages (think: a notification ding, a video that just got louder), and - a **slow RMS envelope** that catches *sustained loudness* mismatches (think: "Discord is permanently louder than everything else even when nobody's shouting"). A stream's applied gain reduction is `max(peak_reduction, rms_reduction)` — whichever path is asking for more cut wins, and recovery only happens when *both* paths agree the stream has settled. This is the layer's whole point: the peak path handles transients within one quantum; the RMS path keeps long-term inter-app loudness balanced. Neither alone is enough. Orthogonal to bus routing — a stream can be processed *or* bypassed *and* level-controlled independently. Its goal is "tame noisy apps without startling the listener and without making the chronic loudmouth permanently dominate," while the signal path itself stays untouched. ### 4.1 Why this is zero-latency The per-app multiplier is the `channelVolumes` value PipeWire already applies inside the app's stream node — it's the same number `pavucontrol`'s per-app slider writes to. Adjusting it doesn't insert a graph node; nothing new sits between the app and its destination sink. The only cost is that **the analysis happens via a sibling fanout link**, not in the playback path: PipeWire schedules fanout consumers in parallel within the same quantum, so the playback path's timing is identical to the no-tap case. ``` ┌──► passive tap (analysis only) │ │ │ ▼ │ peak + RMS envelopes │ (audio thread, sub-ms) app stream ──────┤ │ (output port) │ ▼ │ rtrb push │ │ │ ▼ │ AppLevelController (daemon thread) │ │ │ │ Props.channelVolumes write │ ▼ (back into the app stream node) │ ┌─────────────────────┐ └──►│ app stream multiplies │ by channelVolumes, │──► (its sink — Layer B) │ then publishes. │ └─────────────────────┘ ``` ### 4.2 The metrics: peak + RMS, no LUFS LUFS is the wrong measurement here. Its shortest window (momentary, 400 ms) blurs out exactly the transients we want to catch, and the K-weighting filter adds CPU for no benefit when we're trying to react fast. We also explicitly want a *second* path that targets sustained loudness — for that, plain mean-square RMS is the right cheap stand-in, not LUFS. | Metric | Window | Job | |---|---|---| | **Peak envelope** — `max(\|samples\|)` per block, smoothed | ~100 ms attack window, ~500 ms release | Fast: catches a notification ding, a clip getting louder, a partner standing up and shouting. Triggers cut on `peak_threshold_db` (default −6 dBFS). | | **RMS envelope** — block mean-square, smoothed | ~1–2 s | Slow: catches "this app is just chronically louder than everything else." Triggers cut on `rms_target_db` (default ≈ −20 dBFS RMS). | Both are computed from the *same* raw buffer in the audio thread, so the audio-thread cost is one additional MAC accumulator and a max- scan per sample. Cost analysis in §4.7. ### 4.3 Architecture For each managed playback stream (matched by routing rule — see §6): 1. **Audio thread (tap stream's process callback):** - Pull the buffer from the fanout link. - `peak = max(|samples|)` over the block. - `mean_sq = Σ(x*x) / n` over the block. - Push `{node_id, peak, mean_sq}` to a per-stream `rtrb`. 2. **Daemon thread (`AppLevelController` per stream):** - Drain the rtrb. - Update peak envelope (one-pole, fast α — attack within a block, release ~500 ms). - Update RMS envelope (one-pole, slow α — window ~1–2 s). - Compute `peak_reduction_db` and `rms_reduction_db` independently, then `proposed = max(peak_reduction_db, rms_reduction_db)`. - Smooth toward `proposed`. - If the smoothed value is significantly different from last-written AND we're not rate-limited (~10 Hz max writes per stream), submit `Props.channelVolumes` update. The recovery condition is intentionally *both*-paths-agree: a release on the peak path only counts toward unwinding gain reduction if the RMS path also reads quiet. This avoids the pumping artefact where a transient-heavy stream would rapidly release between transients only to be slapped back down on the next one. ### 4.4 Honouring user-set volumes The daemon subscribes to `Props` param-change events on each managed stream. When a `channelVolumes` change arrives that's meaningfully different from `last_written_volume`, it wasn't us — the user adjusted via pavucontrol, a hotkey, an app's own UI, etc. The controller then either: - **defers entirely** (stops adjusting the stream until the user opts back in via `headroom per-app reset `), or - **treats the user value as a ceiling** (continues to cut on spikes but never raises above what the user wanted). Default is the ceiling behaviour — it's the principle-of-least-surprise choice. Users who want strict deference set a profile flag. #### A historical concern: apps that fight back Some PulseAudio-era apps (Discord most famously) used to read and re-assert their own `channelVolumes` periodically, fighting any external volume manager. The pattern produced a visible ping-pong loop and effectively disabled per-app management. The pattern is largely absent from modern PipeWire-native and Electron-based apps in 2024+: in-app sliders write `channelVolumes` only on user interaction, not on a timer. From Headroom's perspective, those user-interaction writes are indistinguishable from a pavucontrol slider move — both are legitimate external changes the deference policy correctly yields to. If a fight-back app does appear, the **ceiling** deference mode degrades gracefully: - App produces hot output → Headroom cuts to 0.5. - App writes `channelVolumes = 1.0` back over our cut. - Headroom detects the external change, marks the new value (1.0) as the ceiling, and stops actively writing. - Layer A becomes effectively inert for that stream — there is no ping-pong, the user just doesn't get the per-app cut they were hoping for. The bus-level Layer C limiter (if engaged) still enforces the absolute output ceiling regardless. Explicit pattern detection and rate-limiting of ceiling updates (e.g., "ignore ceiling-restoring writes that arrive within N seconds of our own writes") is deferred to v1, pending evidence from real-world testing that any modern app warrants it. The graceful degradation property is the v0 contract. ### 4.5 Reaction-time honesty The signal-path latency is **zero**. The reaction latency to a spike is bounded by: ``` spike in block N ─► analysis (same quantum) ─► rtrb push (ns) ─► controller computes (μs) ─► Props write to pw main loop ─► applied to block N+1 of the app stream ``` So sustained loud passages are attenuated within ~one quantum (5–20 ms depending on the system's quantum). **Isolated one-block transients still leak through** — the first block carrying the spike plays with the old gain; subsequent blocks see the reduction. This is the irreducible cost of "no lookahead allowed." For absolute spike prevention you need lookahead, which means latency, which contradicts the constraint of this layer. The bus-level Layer C limiter (§3.1) catches anything that would exceed the absolute ceiling regardless of whether Layer A has caught up. Layer A reduces *workload* on Layer C by pre-attenuating noisy apps; it doesn't replace it. ### 4.6 Layered budget summary | Layer | Metric | Time scale | Signal-path latency added | |---|---|---|---| | A: per-app peak | sample peak per block | tens of ms | **0** | | A: per-app RMS | block mean-square | seconds | **0** | | C: inline soft tier | true-peak, lookahead | sub-ms | shared with hard tier | | C: inline hard tier | true-peak, lookahead | sub-ms | ~2 ms lookahead | | C: bus AGC | LUFS (ebur128) | many seconds | — (control plane only) | Five distinct jobs, five distinct time scales, no two layers duplicate each other. Layer A is the cheapest line of defense and the only one that costs zero latency on the audio path. ### 4.7 Resource budget per stream | | No TRUE_PEAK (recommended for Layer A) | |---|---| | Audio thread per quantum | ~10 μs (peak + RMS pass) | | Daemon thread per measurement | ~few μs (HashMap lookup + envelope math) | | Memory per controller | ~100 bytes | | Memory per ebur128 (if enabled) | — N/A; Layer A doesn't use ebur128 | At realistic stream counts (2–5 managed apps): **<0.5% CPU total, <1 KB RAM total**. Doesn't move the needle. ### 4.8 Lifecycle - **Stream appears** with `media.class = Stream/Output/Audio` matching a `[[per_app.rules]]` pattern: create tap link (`pw_link_create`), spawn controller, register rtrb. - **Stream disappears** (`pw_registry::global_removed`): tear down tap, drop controller, clean up rtrb. - **App restarts**: new `node_id` → fresh controller. User-volume deference state is per-stream-instance, which is the right default. --- ## 5. PipeWire integration ### 4.1 Sinks Created on daemon startup by emitting a `pipewire.conf.d` fragment into `$XDG_CONFIG_HOME/pipewire/pipewire.conf.d/headroom.conf` (if not already present) and reloading. Alternative: create them at runtime via `pw-loopback` equivalents using `pipewire-rs`. v0 ships with the runtime-creation path so the install footprint is "one binary, one unit file." Sink properties: - `headroom-processed`: `node.name=headroom-processed`, `media.class=Audio/Sink`, `audio.position=[FL,FR]`, `node.description="Headroom (processed)"`. Promoted to system default on startup so new streams land in it by default. There is no second sink. Bypassed streams are routed directly at the current `preferred_real_sink` via `target.object` metadata writes (see §4.3). ### 4.2 The filter Two `pw_stream`s: - **Capture stream** linked to `headroom-processed`'s monitor. Format: `F32 LE`, channels 2, rate matched to real sink, latency-quantum matched (default 1024 frames; configurable). - **Playback stream** linked to the current `preferred_real_sink`. Same format. `process` callback: pull a buffer from capture, run AGC gain → compressor → limiter → push to playback. Allocation-free. Parameter updates arrive over an `rtrb` SPSC queue from the control thread. ### 4.3 Routing - Subscribe to `pw_registry` global-added events. - On any new node with `media.class == "Stream/Output/Audio"` and `node.dont-move != true`: - Read `application.process.binary`, `application.name`, `pipewire.access.portal.app_id`, `media.role`. - Evaluate routing rules from the active profile to decide `processed` vs. `bypass`. - Write `target.object` into the `default` metadata: - `processed` → `headroom-processed`'s `object.serial`. - `bypass` → `preferred_real_sink`'s `object.serial`. WirePlumber honours this for any movable stream. - Watch `default.audio.sink` metadata changes. When the user switches the system default to a hardware sink, the daemon: - records that sink as the new `preferred_real_sink`, - re-links `headroom-filter`'s playback stream to it, - rewrites `target.object` for every currently-bypassed stream so they follow the new hardware, - re-asserts `headroom-processed` as the *default for new streams* (so subsequent app launches still land in the processor). - Hotplug (sink appears/disappears) goes through the same code path. ### 4.4 Stream identification | Property | Reliability | Use | |---|---|---| | `application.process.binary` | high (kernel-sourced) | primary key | | `application.name` | medium | secondary / display | | `pipewire.access.portal.app_id` | high (Flatpak only) | match sandboxed apps | | `media.role` | low (most apps omit) | bonus signal only | | `media.class` | structural | gate to playback streams | --- ## 6. Profiles Location: `$XDG_CONFIG_HOME/headroom/profiles/*.toml` (overriding shipped defaults in `/usr/share/headroom/profiles/` if installed system-wide). Hot-reloaded via `notify-debouncer-mini`. Each profile is a complete listening scenario. Schema (`headroom-core::profile`): ```toml name = "default" description = "Gentle transparent processing for everyday use." [agc] enabled = true target_lufs = -18.0 # ITU-R BS.1770 integrated target attack_ms = 2000.0 release_ms = 800.0 silence_threshold_lufs = -70.0 max_boost_db = 12.0 max_cut_db = 12.0 [compressor] enabled = true detector = "peak" # "peak" | "rms" threshold_db = -24.0 ratio = 2.5 knee_db = 6.0 attack_ms = 10.0 release_ms = 100.0 makeup_db = "auto" # number or "auto" [limiter] ceiling_dbtp = -0.1 lookahead_ms = 2.0 release_ms = 80.0 hold_ms = 5.0 oversample = 4 # 1 | 2 | 4 | 8 (1 disables ISP detection) link = "stereo" # "stereo" | "dual-mono" [meters] publish_hz = 20.0 [[rules]] match = { process_binary = ["spotify", "mpv", "ardour", "reaper", "qpwgraph"] } route = "bypass" [[rules]] match = { process_binary = ["firefox", "chromium", "google-chrome", "Discord", "discord", "element-desktop", "Slack", "zoom", "WEBRTC VoiceEngine"] } route = "processed" [default_route] route = "processed" # safe default: anything unmatched is processed # ---------------------------------------------------------------------- # Per-application level control (Layer A). Orthogonal to routing — you # can enable per-app on bypass-routed streams to get zero-latency # level control (e.g. tame Discord notifications without touching # the game's audio path). # ---------------------------------------------------------------------- [per_app] enabled = true # master switch; false disables Layer A entirely default_enabled = false # for streams not matched by any rule below # Per-rule knobs. Matches use the same key set as [[rules]] above. [[per_app.rules]] match = { process_binary = ["Discord", "discord", "element-desktop", "Slack", "zoom"] } enabled = true peak_threshold_db = -6.0 # short-window peak above this triggers cut rms_target_db = -20.0 # long-term RMS target (slow path) max_cut_db = 12.0 # never cut more than this peak_attack_ms = 5.0 peak_release_ms = 500.0 rms_window_ms = 1500.0 defer_to_user = "ceiling" # "ceiling" | "strict" [[per_app.rules]] match = { process_binary = ["firefox", "chromium", "google-chrome"] } enabled = true peak_threshold_db = -3.0 # browsers run hotter; raise the trigger rms_target_db = -18.0 # Music, DAWs, games default to per-app off — they're either trusted # to set their own level or routed bypass for a reason. [[per_app.rules]] match = { process_binary = ["spotify", "mpv", "ardour", "reaper", "qpwgraph", "carla"] } enabled = false ``` ### Shipped profiles | name | one-liner | |---|---| | `default` | Gentle transparent processing, sensible for daily use. | | `night` | Aggressive: −20 LUFS, 4:1, fast release, narrow dynamic range. | | `speech` | VoIP-focused; short attack, fast release, slight rumble cut. | | `transparent` | Limiter only. Compressor + AGC bypassed. Safety net only. | | `bypass-all` | Routes everything directly to the real sink. The kill switch. | The limiter section of `bypass-all` is irrelevant in practice (nothing flows through `headroom-processed`), but its ceiling field is still respected as a fail-safe in case a stream lands on the processed sink anyway. --- ## 7. IPC Transport: Unix-domain socket, `SOCK_STREAM`, `0600`, at `$XDG_RUNTIME_DIR/headroom/control.sock`. Wire protocol: **see `IPC.md`** for the full normative schema. Summary: u32 BE length prefix + UTF-8 JSON payload. Three message shapes — `Request` (id + op + args), `Response` (id + result|error), `Event` (topic + data). Subscribers signal interest by topic; events fan out to all subscribers with bounded per-subscriber queues. Slow subscribers have events **dropped** (overflow events count is itself published on the `daemon` topic so clients know they fell behind). The first-party Rust wrapper is `headroom-client`, mirroring how [`niri-ipc`](https://github.com/YaLTeR/niri/tree/main/niri-ipc) wraps Niri's socket: a thin, no-magic crate that re-exports the wire types from `headroom-ipc` and adds a blocking `Client` (and an optional async `AsyncClient` behind a feature flag). --- ## 8. CLI ``` headroom status # current profile, sinks, levels headroom daemon # run the daemon (systemd Type=simple) headroom profile list | use | show [name] headroom route list headroom route set processed|bypass # persists in user profile headroom route unset headroom route stream processed|bypass # ad-hoc headroom set # tweak active profile in place headroom get headroom bypass on|off # global kill switch headroom reload # reload profiles from disk headroom monitor # live meter TUI (uses subscribe) ``` CLI is sync, blocks on `UnixStream`. Talks the same JSON wire as any other client. --- ## 9. Crates ``` headroom/ ├── flake.nix # devshell + package ├── Cargo.toml # workspace ├── PLAN.md # this file ├── IPC.md # wire-protocol schema (normative) ├── README.md └── crates/ ├── headroom-dsp/ # AGC + compressor + limiter (pure DSP, no PW) ├── headroom-ipc/ # wire types, framing, serde; no I/O ├── headroom-client/ # blocking client (+ optional async); thin ├── headroom-core/ # daemon: PW integration, routing, profiles, IPC server └── headroom-cli/ # `headroom` binary; depends on headroom-client ``` ### External crates (final v0 dep list) **Audio / DSP** - `pipewire`, `libspa` — official PipeWire bindings. - `ebur128` — measurement. - `rtrb` — SPSC ring buffer (audio ↔ control). - `basedrop` — RT-safe shared ownership. - `assert_no_alloc` — debug-build tripwire. **Plumbing** - `serde`, `serde_json` — IPC + profile (de)serialization. - `serde-toml` (`toml`) — profile files. - `clap` (derive) — CLI. - `tracing`, `tracing-subscriber`, `tracing-journald` — logs. - `notify`, `notify-debouncer-mini` — profile hot-reload. - `crossbeam-channel` — control-plane channels. - `parking_lot` — mutexes. - `signal-hook` — clean shutdown. - `thiserror` — error types. No `tokio`, no `zbus`, no `dbus-*`. --- ## 10. Nix `flake.nix` ships: - A **devshell** with rust toolchain (via `rust-overlay` for pinned channel; default to a stable release pinned in `rust-toolchain.toml`), `pkg-config`, `pipewire`'s dev outputs, `clang` (for bindgen if invoked by deps), `socat` (handy for poking the IPC), `jq`. - A **package** output (`packages..default`) that builds the daemon + CLI with `rustPlatform.buildRustPackage`. v0 uses `cargoLock.lockFile`. Crane can come later if incremental builds in CI become a bottleneck. - A `nixosModules.default` placeholder so packagers can wire the user unit later. Not implemented in v0 of the flake itself. Intermediate dev work uses plain `cargo` inside `nix develop`. Final builds and any CI go through `nix build`. --- ## 11. Phased implementation The phases are roughly token-of-work units, not calendar weeks. **Phase 0 — scaffolding.** Flake, workspace, crate skeletons, README, PLAN/IPC docs. *(done as part of this commit)* **Phase 1 — IPC + client.** `headroom-ipc` (types, framing, codec) and `headroom-client` (blocking `Client`) implemented against the schema in `IPC.md`. Round-trip tests, fuzz the codec. *(this commit)* **Phase 2 — DSP kernels.** `headroom-dsp` with limiter, compressor, AGC, oversampler, envelope. Tested in isolation against synthesized signals; limiter validated to hold a −0.1 dBTP ceiling on EBU TECH 3341 generators. *(this commit: limiter first)* **Phase 3 — daemon core.** `headroom-core` brings up the `headroom-processed` virtual sink, the filter (pw_stream pair), the `preferred_real_sink` tracker, the registry subscriber, and the routing engine. Hardcoded profile, no IPC server yet. **Phase 4 — IPC server + profile manager.** Wire `headroom-core` to the IPC schema. Profile loading + hot-reload. Slow AGC loop ticking on real loudness measurements. **Phase 5 — CLI + monitor TUI.** `headroom-cli` implements all the subcommands above, plus a `monitor` TUI built on the meters subscription. **Phase 6 — Per-application level control (Layer A).** Per-managed-stream tap creation, `AppLevelController` with peak + RMS envelopes, `Props.channelVolumes` writer, user-volume deference logic, `[per_app]` profile parsing, `headroom per-app …` CLI verbs, and a per-stream meter event on the IPC. Land after the bus path is stable so we have a baseline to compare against. **Phase 7 — Packaging.** systemd user unit, install paths, default profile install, basic NixOS module. **Phase 8 — Hardening.** Latency budget verification on real hardware, Bluetooth-handoff edge case, profile-reload while audio is flowing, multi-rate hardware, allocation-tracer sweep with `assert_no_alloc` in debug. --- ## 12. Risks & open questions - **WirePlumber re-linking on device hotplug.** When a Bluetooth headset connects, WP re-evaluates linking. Headroom must re-pin its routed streams. Tractable; the registry events surface this. - **Latency budget.** Processed path: one quantum hop (the filter) plus lookahead (~2 ms) plus 4× oversampling buffering ≈ 8–15 ms added to processed-path latency. Fine for video/voice. Bypass path: **zero added latency** — the stream rides the real sink directly. - **Default-sink changes.** When the user switches the system default to a hardware sink, the daemon adopts it as `preferred_real_sink`, re-links the filter's playback, retargets bypassed streams, and re-asserts `headroom-processed` as the default for new streams. Watching `default.audio.sink` in the metadata is the trigger. - **Sample-rate mismatch.** `headroom-processed`, the filter, and the real sink must agree, or PipeWire resamples behind our back. The filter should source its rate from the real sink and convert on the capture side only. - **Surround content downmix vs. passthrough.** v0 punts: anything >2ch is routed directly to the real sink (bypass behaviour) regardless of profile rule. Documented behaviour. --- ## 13. License GPL-3.0-or-later for the daemon and CLI. `headroom-dsp` and `headroom-ipc` are MPL-2.0 so third-party clients and plugin hosts can link them without GPL contagion. (Re-evaluate when LSP-derived code is introduced; current plan does not pull any.)