headroom

public

Star0

Fork 0

Watch0

2 commits 1 branch 0 tags 0 releases521.6 KiB

Commit `614b4e43f9f3`

tarball

atagen <boss@atagen.co>2026-06-02 05:09 UTC

12 files changed+2654-0

dsp: agc, compressor, true-peak limiter, bs.1770 metering

Added file: crates/headroom-dsp/Cargo.toml+23 additions@@ -0,0 +1,23 @@
+[package]
+name = "headroom-dsp"
+description = "automatic loudness and per-app volume control (pipewire)"
+version.workspace = true
+edition.workspace = true
+license = "MPL-2.0"
+homepage.workspace = true
+repository.workspace = true
+authors.workspace = true
+
+[dependencies]
+# intentionally empty: must build clean on any host, most reusable crate in the workspace.
+# think twice before adding a dependency here.
+
+[dev-dependencies]
+criterion = { workspace = true }
+
+[features]
+default = []
+
+[[bench]]
+name = "layer_a"
+harness = false

Added file: crates/headroom-dsp/benches/layer_a.rs+134 additions@@ -0,0 +1,134 @@
+//! layer a (per-app level control) microbenchmarks vs the plan §4.7 budget.
+
+use criterion::{
+    black_box, criterion_group, criterion_main, BatchSize, Criterion, Throughput,
+};
+use headroom_dsp::{
+    Compressor, CompressorConfig, LevelEnvelopes, LevelEnvelopesConfig, Limiter, LimiterConfig,
+};
+
+/// 1024-frame quantum at 48 kHz stereo: 2048 interleaved samples, 21.3 ms/block.
+const FRAMES: usize = 1024;
+const CHANNELS: usize = 2;
+const SR: f32 = 48_000.0;
+const BLOCK_DT_S: f32 = FRAMES as f32 / SR;
+
+/// noisy-but-bounded synthetic block; realistic value range so branch predictors / fpu
+/// exercise the same paths as real audio.
+fn make_block() -> Vec<f32> {
+    let mut buf = Vec::with_capacity(FRAMES * CHANNELS);
+    // two sine partials + tiny dc: peak not pegged to one sample, mean-square not trivially zero.
+    let f1 = 220.0 / SR;
+    let f2 = 1730.0 / SR;
+    for n in 0..FRAMES {
+        let t = n as f32;
+        let s = 0.4 * (2.0 * std::f32::consts::PI * f1 * t).sin()
+            + 0.18 * (2.0 * std::f32::consts::PI * f2 * t).sin()
+            + 0.005;
+        buf.push(s);
+        buf.push(s * 0.92); // slight L/R difference
+    }
+    buf
+}
+
+/// what the audio-thread layer a callback computes per block.
+/// hand-rolled loop so the bench measures the candidate code, not iterator combinators.
+#[inline]
+fn analysis_scan(samples: &[f32]) -> (f32, f32) {
+    let mut peak = 0.0_f32;
+    let mut sumsq = 0.0_f32;
+    for &s in samples {
+        let a = s.abs();
+        if a > peak {
+            peak = a;
+        }
+        sumsq += s * s;
+    }
+    let mean_sq = sumsq / samples.len() as f32;
+    (peak, mean_sq)
+}
+
+fn bench_analysis_scan(c: &mut Criterion) {
+    let block = make_block();
+    let mut group = c.benchmark_group("layer_a_audio_thread");
+    group.throughput(Throughput::Elements((FRAMES * CHANNELS) as u64));
+    group.bench_function("analysis_scan_stereo_1024", |b| {
+        b.iter(|| {
+            let (p, m) = analysis_scan(black_box(&block));
+            black_box((p, m));
+        });
+    });
+    group.finish();
+}
+
+fn bench_level_envelopes(c: &mut Criterion) {
+    let mut env = LevelEnvelopes::new(LevelEnvelopesConfig::default(), BLOCK_DT_S);
+    let block = make_block();
+    let (peak, mean_sq) = analysis_scan(&block);
+
+    let mut group = c.benchmark_group("layer_a_daemon_thread");
+    group.bench_function("level_envelopes_process_block", |b| {
+        b.iter(|| {
+            let d = env.process_block(black_box(peak), black_box(mean_sq));
+            black_box(d);
+        });
+    });
+    group.finish();
+}
+
+fn bench_filter_kernels(c: &mut Criterion) {
+    // context only: layer a relative to the rt filter's existing per-frame cost.
+    let mut comp = Compressor::new(CompressorConfig::default(), SR);
+    let mut lim = Limiter::new(LimiterConfig::default(), SR);
+    let mut silence_lim = Limiter::new(LimiterConfig::default(), SR);
+    let mut block_lim = Limiter::new(LimiterConfig::default(), SR);
+    let mut silence_block_lim = Limiter::new(LimiterConfig::default(), SR);
+    let block = make_block();
+    let mut silence = vec![0.0_f32; FRAMES * CHANNELS];
+
+    let mut group = c.benchmark_group("filter_reference_per_frame");
+    group.throughput(Throughput::Elements(1));
+    group.bench_function("compressor_process_frame", |b| {
+        b.iter(|| {
+            let (l, r) = comp.process_frame(black_box(0.3), black_box(-0.2));
+            black_box((l, r));
+        });
+    });
+    group.bench_function("limiter_process_frame", |b| {
+        b.iter(|| {
+            let (l, r) = lim.process_frame(black_box(0.3), black_box(-0.2));
+            black_box((l, r));
+        });
+    });
+    group.bench_function("limiter_process_frame_silence", |b| {
+        b.iter(|| {
+            let (l, r) = silence_lim.process_frame(black_box(0.0), black_box(0.0));
+            black_box((l, r));
+        });
+    });
+    group.bench_function("limiter_process_block_1024", |b| {
+        b.iter_batched(
+            || block.clone(),
+            |mut buf| {
+                block_lim.process_interleaved_stereo(black_box(&mut buf));
+                black_box(buf);
+            },
+            BatchSize::SmallInput,
+        );
+    });
+    group.bench_function("limiter_process_block_silence_1024", |b| {
+        b.iter(|| {
+            silence_block_lim.process_interleaved_stereo(black_box(&mut silence));
+            black_box(&silence);
+        });
+    });
+    group.finish();
+}
+
+criterion_group!(
+    benches,
+    bench_analysis_scan,
+    bench_level_envelopes,
+    bench_filter_kernels
+);
+criterion_main!(benches);

Added file: crates/headroom-dsp/src/agc.rs+183 additions@@ -0,0 +1,183 @@
+//! anti-zipper smoother toward the control thread's agc target.
+
+use crate::util::{db_to_lin, time_to_alpha};
+
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct AgcGainConfig {
+    /// smoother tau (ms). small enough to chase a 50 ms control tick without zippering,
+    /// large enough not to itself act as a gain envelope.
+    pub anti_zipper_ms: f32,
+}
+
+impl Default for AgcGainConfig {
+    fn default() -> Self {
+        Self {
+            anti_zipper_ms: 5.0,
+        }
+    }
+}
+
+pub struct AgcGain {
+    cfg: AgcGainConfig,
+    sample_rate: f32,
+    target_db: f32,
+    current_db: f32,
+    alpha: f32,
+    enabled: bool,
+}
+
+impl AgcGain {
+    #[must_use]
+    pub fn new(cfg: AgcGainConfig, sample_rate: f32) -> Self {
+        Self {
+            cfg,
+            sample_rate,
+            target_db: 0.0,
+            current_db: 0.0,
+            alpha: time_to_alpha(cfg.anti_zipper_ms, sample_rate),
+            enabled: true,
+        }
+    }
+
+    pub fn set_target_db(&mut self, db: f32) {
+        if db.is_finite() {
+            self.target_db = db;
+        }
+    }
+
+    /// disabling pushes target to 0 dB so an active boost/cut unwinds at the smoother rate
+    /// rather than snapping.
+    pub fn set_enabled(&mut self, enabled: bool) {
+        self.enabled = enabled;
+        if !enabled {
+            self.target_db = 0.0;
+        }
+    }
+
+    pub fn set_config(&mut self, cfg: AgcGainConfig) {
+        self.cfg = cfg;
+        self.alpha = time_to_alpha(cfg.anti_zipper_ms, self.sample_rate);
+    }
+
+    #[must_use]
+    pub fn config(&self) -> AgcGainConfig {
+        self.cfg
+    }
+
+    #[must_use]
+    pub fn current_db(&self) -> f32 {
+        self.current_db
+    }
+
+    #[must_use]
+    pub fn target_db(&self) -> f32 {
+        self.target_db
+    }
+
+    #[must_use]
+    pub fn enabled(&self) -> bool {
+        self.enabled
+    }
+
+    pub fn process_frame(&mut self, l: f32, r: f32) -> (f32, f32) {
+        self.current_db += self.alpha * (self.target_db - self.current_db);
+        if l == 0.0 && r == 0.0 {
+            return (0.0, 0.0);
+        }
+        let gain = db_to_lin(self.current_db);
+        (l * gain, r * gain)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::util::lin_to_db;
+
+    const SR: f32 = 48_000.0;
+
+    #[test]
+    fn unity_at_zero_db() {
+        let mut agc = AgcGain::new(AgcGainConfig::default(), SR);
+        for _ in 0..100 {
+            let (l, r) = agc.process_frame(0.5, -0.3);
+            assert!((l - 0.5).abs() < 1e-6);
+            assert!((r - -0.3).abs() < 1e-6);
+        }
+    }
+
+    #[test]
+    fn smooths_toward_target() {
+        let mut agc = AgcGain::new(AgcGainConfig::default(), SR);
+        agc.set_target_db(6.0);
+        // After ~5 ms (one anti-zipper tau), current_db should be in
+        // the ~63% region.
+        let samples = (0.005 * SR) as usize;
+        for _ in 0..samples {
+            let _ = agc.process_frame(0.0, 0.0);
+        }
+        let cur = agc.current_db();
+        assert!(
+            (cur - 6.0 * 0.63).abs() < 0.5,
+            "expected ~3.8 dB after one tau, got {cur}"
+        );
+        // Settle.
+        for _ in 0..(SR as usize) {
+            let _ = agc.process_frame(0.0, 0.0);
+        }
+        assert!((agc.current_db() - 6.0).abs() < 0.01);
+    }
+
+    #[test]
+    fn applies_gain_to_signal() {
+        let mut agc = AgcGain::new(AgcGainConfig::default(), SR);
+        agc.set_target_db(6.0);
+        // Run long enough to settle.
+        for _ in 0..(SR as usize) {
+            let _ = agc.process_frame(0.0, 0.0);
+        }
+        let (l, r) = agc.process_frame(0.5, 0.5);
+        // +6 dB = factor of ~2.0.
+        assert!((l / 0.5 - 2.0).abs() < 0.05, "got {l}");
+        assert!((r / 0.5 - 2.0).abs() < 0.05);
+    }
+
+    #[test]
+    fn disable_unwinds_back_to_unity() {
+        let mut agc = AgcGain::new(AgcGainConfig::default(), SR);
+        agc.set_target_db(6.0);
+        for _ in 0..(SR as usize) {
+            let _ = agc.process_frame(0.0, 0.0);
+        }
+        assert!((agc.current_db() - 6.0).abs() < 0.01);
+
+        agc.set_enabled(false);
+        for _ in 0..(SR as usize) {
+            let _ = agc.process_frame(0.0, 0.0);
+        }
+        assert!(agc.current_db().abs() < 0.01, "got {}", agc.current_db());
+    }
+
+    #[test]
+    fn rejects_non_finite_target() {
+        let mut agc = AgcGain::new(AgcGainConfig::default(), SR);
+        agc.set_target_db(3.0);
+        agc.set_target_db(f32::NAN);
+        assert!((agc.target_db() - 3.0).abs() < 1e-6);
+        agc.set_target_db(f32::INFINITY);
+        assert!((agc.target_db() - 3.0).abs() < 1e-6);
+    }
+
+    #[test]
+    fn lin_round_trip_check() {
+        // Sanity: after settling, gain at target_db should produce
+        // peak that matches lin_to_db.
+        let mut agc = AgcGain::new(AgcGainConfig::default(), SR);
+        agc.set_target_db(-6.0);
+        for _ in 0..(SR as usize) {
+            let _ = agc.process_frame(0.0, 0.0);
+        }
+        let (l, _) = agc.process_frame(1.0, 1.0);
+        assert!((lin_to_db(l) - -6.0).abs() < 0.05);
+    }
+}

Added file: crates/headroom-dsp/src/compressor.rs+364 additions@@ -0,0 +1,364 @@
+//! feed-forward log-domain compressor with soft-knee static curve.
+
+use crate::util::{db_to_lin, lin_to_db, time_to_alpha};
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Detector {
+    /// max(|l|,|r|). slightly more percussive on transients.
+    Peak,
+    /// one-pole low-passed mean square. smoother on percussive material.
+    Rms,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct CompressorConfig {
+    /// envelope state is NOT reset while disabled; with typical release constants any residual
+    /// transient on re-enable is sub-audible.
+    pub enabled: bool,
+    pub threshold_db: f32,
+    /// >= 1.0
+    pub ratio: f32,
+    /// 0 = hard knee.
+    pub knee_db: f32,
+    pub attack_ms: f32,
+    pub release_ms: f32,
+    /// `None` = automatic mild boost.
+    pub makeup_db: Option<f32>,
+    pub detector: Detector,
+    /// only used when detector == Rms.
+    pub rms_window_ms: f32,
+}
+
+impl Default for CompressorConfig {
+    fn default() -> Self {
+        Self {
+            enabled: true,
+            threshold_db: -24.0,
+            ratio: 2.5,
+            knee_db: 6.0,
+            attack_ms: 10.0,
+            release_ms: 100.0,
+            makeup_db: None,
+            detector: Detector::Peak,
+            rms_window_ms: 5.0,
+        }
+    }
+}
+
+impl CompressorConfig {
+    #[must_use]
+    pub fn sanitized(mut self) -> Self {
+        if self.ratio < 1.0 {
+            self.ratio = 1.0;
+        }
+        self.knee_db = self.knee_db.max(0.0);
+        self.attack_ms = self.attack_ms.max(0.0);
+        self.release_ms = self.release_ms.max(0.0);
+        self.rms_window_ms = self.rms_window_ms.max(0.1);
+        self
+    }
+}
+
+/// stereo-linked.
+pub struct Compressor {
+    cfg: CompressorConfig,
+    sample_rate: f32,
+    envelope_db: f32,
+    attack_alpha: f32,
+    release_alpha: f32,
+    rms_state: f32,
+    rms_alpha: f32,
+    last_gr_db: f32,
+}
+
+impl Compressor {
+    #[must_use]
+    pub fn new(cfg: CompressorConfig, sample_rate: f32) -> Self {
+        let cfg = cfg.sanitized();
+        Self {
+            cfg,
+            sample_rate,
+            envelope_db: -200.0,
+            attack_alpha: time_to_alpha(cfg.attack_ms, sample_rate),
+            release_alpha: time_to_alpha(cfg.release_ms, sample_rate),
+            rms_state: 0.0,
+            rms_alpha: time_to_alpha(cfg.rms_window_ms, sample_rate),
+            last_gr_db: 0.0,
+        }
+    }
+
+    #[must_use]
+    pub fn config(&self) -> CompressorConfig {
+        self.cfg
+    }
+
+    /// negative when compressing.
+    #[must_use]
+    pub fn gain_reduction_db(&self) -> f32 {
+        self.last_gr_db
+    }
+
+    /// envelope kept across same-enabled tweaks (don't pop); reset on disabled → enabled so a
+    /// stale envelope doesn't duck the first ~release_ms of audio on resume.
+    pub fn set_config(&mut self, cfg: CompressorConfig) {
+        let cfg = cfg.sanitized();
+        let was_disabled = !self.cfg.enabled;
+        self.cfg = cfg;
+        if was_disabled && self.cfg.enabled {
+            self.envelope_db = -200.0;
+            self.rms_state = 0.0;
+            self.last_gr_db = 0.0;
+        }
+        self.attack_alpha = time_to_alpha(cfg.attack_ms, self.sample_rate);
+        self.release_alpha = time_to_alpha(cfg.release_ms, self.sample_rate);
+        self.rms_alpha = time_to_alpha(cfg.rms_window_ms, self.sample_rate);
+    }
+
+    pub fn process_frame(&mut self, left: f32, right: f32) -> (f32, f32) {
+        if !self.cfg.enabled {
+            // report 0 so meters show "off", not the stale last value.
+            self.last_gr_db = 0.0;
+            return (left, right);
+        }
+        if left == 0.0 && right == 0.0 && self.envelope_db <= -199.0 && self.rms_state == 0.0 {
+            self.envelope_db = -200.0;
+            self.last_gr_db = 0.0;
+            return (0.0, 0.0);
+        }
+        let det_lin = match self.cfg.detector {
+            Detector::Peak => left.abs().max(right.abs()),
+            Detector::Rms => {
+                let sq = 0.5 * left.mul_add(left, right * right);
+                self.rms_state += self.rms_alpha * (sq - self.rms_state);
+                self.rms_state.max(0.0).sqrt()
+            }
+        };
+        let det_db = lin_to_db(det_lin.max(1e-20));
+
+        if det_db > self.envelope_db {
+            self.envelope_db += self.attack_alpha * (det_db - self.envelope_db);
+        } else {
+            self.envelope_db += self.release_alpha * (det_db - self.envelope_db);
+        }
+
+        let gr_db = static_curve_gain_reduction(
+            self.envelope_db,
+            self.cfg.threshold_db,
+            self.cfg.ratio,
+            self.cfg.knee_db,
+        );
+        let makeup_db = self
+            .cfg
+            .makeup_db
+            .unwrap_or_else(|| auto_makeup(self.cfg.threshold_db, self.cfg.ratio));
+
+        let lin_gain = db_to_lin(-gr_db + makeup_db);
+        self.last_gr_db = -gr_db;
+
+        (left * lin_gain, right * lin_gain)
+    }
+
+    pub fn reset(&mut self) {
+        self.envelope_db = -200.0;
+        self.rms_state = 0.0;
+        self.last_gr_db = 0.0;
+    }
+}
+
+/// returns positive gain reduction (dB) to subtract from the input level.
+fn static_curve_gain_reduction(
+    input_db: f32,
+    threshold_db: f32,
+    ratio: f32,
+    knee_db: f32,
+) -> f32 {
+    let over = input_db - threshold_db;
+    if knee_db > 0.0 && over > -knee_db * 0.5 && over < knee_db * 0.5 {
+        // quadratic soft knee
+        let x = over + knee_db * 0.5;
+        let factor = (x * x) / (2.0 * knee_db);
+        factor * (1.0 - 1.0 / ratio)
+    } else if over > 0.0 {
+        over * (1.0 - 1.0 / ratio)
+    } else {
+        0.0
+    }
+}
+
+/// half the static gr at 0 dBFS. conservative — the limiter is downstream, don't push it.
+fn auto_makeup(threshold_db: f32, ratio: f32) -> f32 {
+    let gr_at_zero = (-threshold_db).max(0.0) * (1.0 - 1.0 / ratio);
+    gr_at_zero * 0.5
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn below_threshold_is_unity_minus_makeup() {
+        let mut c = Compressor::new(CompressorConfig::default(), 48_000.0);
+        // Drive a long, low signal and check we land at expected gain.
+        let mut last = (0.0_f32, 0.0_f32);
+        for _ in 0..10_000 {
+            last = c.process_frame(0.01, 0.01);
+        }
+        // Below threshold: gain reduction is zero, only makeup applied.
+        let makeup_db = auto_makeup(-24.0, 2.5);
+        let expected = 0.01 * db_to_lin(makeup_db);
+        assert!(
+            (last.0 - expected).abs() < 1e-3,
+            "got {} expected {}",
+            last.0,
+            expected
+        );
+        assert!(c.gain_reduction_db().abs() < 0.1);
+    }
+
+    #[test]
+    fn above_threshold_reduces_gain() {
+        let cfg = CompressorConfig {
+            threshold_db: -20.0,
+            ratio: 4.0,
+            knee_db: 0.0, // hard knee for clean math
+            attack_ms: 0.1,
+            release_ms: 0.1,
+            makeup_db: Some(0.0), // no makeup so we test pure reduction
+            ..CompressorConfig::default()
+        };
+        let mut c = Compressor::new(cfg, 48_000.0);
+        // Drive ~-6 dBFS = 0.5 in linear.
+        let target = 0.5_f32;
+        let mut last_out = 0.0;
+        for _ in 0..2_000 {
+            let (l, _) = c.process_frame(target, target);
+            last_out = l;
+        }
+        // Input is 14 dB above threshold. With ratio 4, GR = 14*(1-0.25) = 10.5 dB.
+        // Expected output: -6 - 10.5 = -16.5 dB linear = 0.1496.
+        let expected_db = -6.0 - 14.0 * (1.0 - 0.25);
+        let expected_lin = db_to_lin(expected_db);
+        let got_db = lin_to_db(last_out);
+        assert!(
+            (got_db - expected_db).abs() < 0.5,
+            "got {got_db} expected {expected_db}"
+        );
+        assert!(c.gain_reduction_db() < -5.0, "gr was {}", c.gain_reduction_db());
+        let _ = expected_lin;
+    }
+
+    #[test]
+    fn exact_zero_crossing_does_not_reset_active_envelope() {
+        let cfg = CompressorConfig {
+            threshold_db: -24.0,
+            attack_ms: 0.1,
+            release_ms: 200.0,
+            makeup_db: Some(0.0),
+            ..CompressorConfig::default()
+        };
+        let mut c = Compressor::new(cfg, 48_000.0);
+        for _ in 0..1_000 {
+            let _ = c.process_frame(1.0, 1.0);
+        }
+        assert!(c.gain_reduction_db() < -10.0);
+
+        let _ = c.process_frame(0.0, 0.0);
+        assert!(
+            c.gain_reduction_db() < -10.0,
+            "a single exact-zero frame should release, not reset"
+        );
+    }
+
+    #[test]
+    fn ratio_below_one_is_clamped() {
+        let cfg = CompressorConfig {
+            ratio: 0.5,
+            ..CompressorConfig::default()
+        }
+        .sanitized();
+        assert_eq!(cfg.ratio, 1.0);
+    }
+
+    #[test]
+    fn disabled_compressor_passes_signal_through_unchanged() {
+        // Same hot input that would compress hard in the enabled
+        // test above. With `enabled: false`, output equals input
+        // exactly (no makeup gain, no reduction), and the reporter
+        // shows zero GR — so the `transparent` and `bypass-all`
+        // profiles actually do what their name claims.
+        let cfg = CompressorConfig {
+            enabled: false,
+            threshold_db: -20.0,
+            ratio: 4.0,
+            makeup_db: Some(12.0),
+            ..CompressorConfig::default()
+        };
+        let mut c = Compressor::new(cfg, 48_000.0);
+        for _ in 0..1_000 {
+            let (l, r) = c.process_frame(0.5, 0.5);
+            assert_eq!(l, 0.5);
+            assert_eq!(r, 0.5);
+        }
+        assert_eq!(c.gain_reduction_db(), 0.0);
+    }
+
+    #[test]
+    fn enable_transition_resets_stale_envelope() {
+        // Run a loud signal through an enabled compressor to wind
+        // the envelope up, then disable + re-enable via set_config.
+        // The first sample after re-enable must NOT see the stale
+        // envelope (which would otherwise duck the signal until
+        // release_ms wound it down). Concretely: with a quiet input
+        // after re-enable, the envelope should be at the floor, so
+        // GR is zero — same as a freshly-constructed compressor.
+        let loud_cfg = CompressorConfig {
+            enabled: true,
+            threshold_db: -20.0,
+            ratio: 4.0,
+            attack_ms: 0.1,
+            release_ms: 1000.0, // slow release so stale state would otherwise stick
+            knee_db: 0.0,
+            makeup_db: Some(0.0),
+            ..CompressorConfig::default()
+        };
+        let mut c = Compressor::new(loud_cfg, 48_000.0);
+        // Drive hot signal to wind envelope up.
+        for _ in 0..2_000 {
+            c.process_frame(0.5, 0.5);
+        }
+        assert!(
+            c.gain_reduction_db() < -5.0,
+            "precondition: envelope should be wound up; gr={}",
+            c.gain_reduction_db()
+        );
+
+        // Disable, then re-enable — should reset.
+        let mut disabled_cfg = loud_cfg;
+        disabled_cfg.enabled = false;
+        c.set_config(disabled_cfg);
+        c.set_config(loud_cfg);
+
+        // Now drive a quiet signal. With reset envelope, GR should
+        // ride near zero; without reset, the stale envelope would
+        // bleed gain reduction out over ~release_ms.
+        let (l, r) = c.process_frame(0.001, 0.001);
+        assert!(
+            c.gain_reduction_db().abs() < 0.01,
+            "envelope didn't reset across enable transition; gr={}",
+            c.gain_reduction_db()
+        );
+        // Output should be quiet (within makeup-applied scale).
+        assert!(l.abs() < 0.01);
+        assert!(r.abs() < 0.01);
+    }
+
+    #[test]
+    fn static_curve_at_threshold_with_soft_knee() {
+        // At exactly threshold, soft knee contributes exactly half the
+        // ratio's compression amount at the upper knee shoulder.
+        let gr = static_curve_gain_reduction(-24.0, -24.0, 4.0, 6.0);
+        // At over==0 inside the knee, x = knee/2, factor = knee/8.
+        // GR = knee/8 * (1 - 1/4) = 6/8 * 0.75 = 0.5625
+        assert!((gr - 0.5625).abs() < 1e-4, "gr={gr}");
+    }
+}

Added file: crates/headroom-dsp/src/delay.rs+66 additions@@ -0,0 +1,66 @@
+//! fixed-length fifo sample delay.
+
+pub struct DelayLine {
+    buf: Vec<f32>,
+    write_idx: usize,
+}
+
+impl DelayLine {
+    /// 0 clamps to 1 (one-sample identity minimum).
+    #[must_use]
+    pub fn new(samples: usize) -> Self {
+        Self {
+            buf: vec![0.0; samples.max(1)],
+            write_idx: 0,
+        }
+    }
+
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.buf.len()
+    }
+
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        false
+    }
+
+    /// write `x`, return the sample written `len` calls ago.
+    pub fn push_pop(&mut self, x: f32) -> f32 {
+        let out = self.buf[self.write_idx];
+        self.buf[self.write_idx] = x;
+        self.write_idx = (self.write_idx + 1) % self.buf.len();
+        out
+    }
+
+    pub fn reset(&mut self) {
+        for v in &mut self.buf {
+            *v = 0.0;
+        }
+        self.write_idx = 0;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn delays_exactly_n_samples() {
+        let mut d = DelayLine::new(4);
+        let expected = [0.0, 0.0, 0.0, 0.0, 1.0, 2.0, 3.0, 4.0];
+        let inputs = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0];
+        for (i, &x) in inputs.iter().enumerate() {
+            let y = d.push_pop(x);
+            assert!((y - expected[i]).abs() < 1e-9, "i={i} y={y}");
+        }
+    }
+
+    #[test]
+    fn zero_length_clamps_to_one() {
+        let mut d = DelayLine::new(0);
+        assert_eq!(d.len(), 1);
+        assert_eq!(d.push_pop(1.0), 0.0);
+        assert_eq!(d.push_pop(2.0), 1.0);
+    }
+}

Added file: crates/headroom-dsp/src/envelope.rs+90 additions@@ -0,0 +1,90 @@
+//! exponential attack/release envelope follower.
+
+use crate::util::time_to_alpha;
+
+pub struct AttackRelease {
+    attack_alpha: f32,
+    release_alpha: f32,
+    state: f32,
+}
+
+impl AttackRelease {
+    #[must_use]
+    pub fn new(attack_ms: f32, release_ms: f32, sample_rate: f32) -> Self {
+        Self {
+            attack_alpha: time_to_alpha(attack_ms, sample_rate),
+            release_alpha: time_to_alpha(release_ms, sample_rate),
+            state: 0.0,
+        }
+    }
+
+    pub fn set_times(&mut self, attack_ms: f32, release_ms: f32, sample_rate: f32) {
+        self.attack_alpha = time_to_alpha(attack_ms, sample_rate);
+        self.release_alpha = time_to_alpha(release_ms, sample_rate);
+    }
+
+    /// attack on rising input, release on falling.
+    pub fn process_peak(&mut self, target: f32) -> f32 {
+        if target > self.state {
+            self.state += self.attack_alpha * (target - self.state);
+        } else {
+            self.state += self.release_alpha * (target - self.state);
+        }
+        self.state
+    }
+
+    /// inverse of process_peak: attack on falling gain, release on rising (recover to unity).
+    pub fn process_gain(&mut self, target: f32) -> f32 {
+        if target < self.state {
+            self.state += self.attack_alpha * (target - self.state);
+        } else {
+            self.state += self.release_alpha * (target - self.state);
+        }
+        self.state
+    }
+
+    #[must_use]
+    pub fn state(&self) -> f32 {
+        self.state
+    }
+
+    pub fn reset(&mut self, value: f32) {
+        self.state = value;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn peak_mode_attacks_fast_releases_slow() {
+        let fs = 48_000.0;
+        let mut env = AttackRelease::new(0.1, 100.0, fs);
+        // Drive to 1.0 and let it settle.
+        for _ in 0..100 {
+            env.process_peak(1.0);
+        }
+        assert!(env.state() > 0.99);
+        // Drop input to 0.0 and verify slow decay.
+        env.process_peak(0.0);
+        assert!(env.state() > 0.999);
+        for _ in 0..10 {
+            env.process_peak(0.0);
+        }
+        // Still well above zero on the release time scale.
+        assert!(env.state() > 0.8);
+    }
+
+    #[test]
+    fn gain_mode_attacks_on_drop() {
+        let fs = 48_000.0;
+        let mut env = AttackRelease::new(0.1, 100.0, fs);
+        env.reset(1.0);
+        // Demand a gain drop. Should snap down quickly.
+        for _ in 0..100 {
+            env.process_gain(0.5);
+        }
+        assert!(env.state() < 0.51);
+    }
+}

Added file: crates/headroom-dsp/src/level_envelopes.rs+365 additions@@ -0,0 +1,365 @@
+//! block-rate two-tier (peak + rms) level detector for layer a (per-app level control).
+//!
+//! recovery is implicit: each envelope releases at its own constant, so neither path sticks
+//! once input drops.
+
+use crate::util::{lin_to_db, time_to_alpha};
+
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct LevelEnvelopesConfig {
+    /// peak envelope above this → cut. catches transient bursts.
+    pub peak_threshold_db: f32,
+    /// smoothed rms above this → cut. catches sustained loudness mismatch.
+    pub rms_target_db: f32,
+    /// cap on max(peak, rms) reduction.
+    pub max_cut_db: f32,
+    pub peak_attack_ms: f32,
+    pub peak_release_ms: f32,
+    /// one-pole tau on the mean-square input.
+    pub rms_window_ms: f32,
+}
+
+impl Default for LevelEnvelopesConfig {
+    fn default() -> Self {
+        Self {
+            peak_threshold_db: -6.0,
+            rms_target_db: -20.0,
+            max_cut_db: 12.0,
+            peak_attack_ms: 5.0,
+            peak_release_ms: 500.0,
+            rms_window_ms: 1500.0,
+        }
+    }
+}
+
+impl LevelEnvelopesConfig {
+    #[must_use]
+    pub fn sanitized(mut self) -> Self {
+        if self.peak_threshold_db > 0.0 {
+            self.peak_threshold_db = 0.0;
+        }
+        if self.rms_target_db > 0.0 {
+            self.rms_target_db = 0.0;
+        }
+        if !self.max_cut_db.is_finite() || self.max_cut_db < 0.0 {
+            self.max_cut_db = 0.0;
+        }
+        for v in [
+            &mut self.peak_attack_ms,
+            &mut self.peak_release_ms,
+            &mut self.rms_window_ms,
+        ] {
+            if !v.is_finite() || *v < 0.0 {
+                *v = 0.0;
+            }
+        }
+        self
+    }
+}
+
+pub struct LevelEnvelopes {
+    cfg: LevelEnvelopesConfig,
+    block_dt_s: f32,
+    peak_attack_alpha: f32,
+    peak_release_alpha: f32,
+    rms_alpha: f32,
+    /// starts at floor so the first push doesn't trip the threshold.
+    peak_env_db: f32,
+    rms_smoothed_mean_sq: f32,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct LevelDecision {
+    pub peak_reduction_db: f32,
+    pub rms_reduction_db: f32,
+    /// `min(max_cut, max(peak, rms))`, always >= 0. 0 = leave channelVolumes alone.
+    pub total_reduction_db: f32,
+}
+
+impl LevelEnvelopes {
+    /// `block_dt_s` = samples_per_block / sample_rate; up to ~100 ms tracks fine for v0.
+    #[must_use]
+    pub fn new(cfg: LevelEnvelopesConfig, block_dt_s: f32) -> Self {
+        let cfg = cfg.sanitized();
+        let (peak_attack_alpha, peak_release_alpha, rms_alpha) = compute_alphas(&cfg, block_dt_s);
+        Self {
+            cfg,
+            block_dt_s,
+            peak_attack_alpha,
+            peak_release_alpha,
+            rms_alpha,
+            peak_env_db: -200.0,
+            rms_smoothed_mean_sq: 0.0,
+        }
+    }
+
+    #[must_use]
+    pub fn config(&self) -> LevelEnvelopesConfig {
+        self.cfg
+    }
+
+    #[must_use]
+    pub fn block_dt_s(&self) -> f32 {
+        self.block_dt_s
+    }
+
+    /// recomputes alphas; doesn't reset envelope state (live tweaks stay artefact-free).
+    pub fn set_config(&mut self, cfg: LevelEnvelopesConfig) {
+        let cfg = cfg.sanitized();
+        let (a_a, a_r, a_rms) = compute_alphas(&cfg, self.block_dt_s);
+        self.cfg = cfg;
+        self.peak_attack_alpha = a_a;
+        self.peak_release_alpha = a_r;
+        self.rms_alpha = a_rms;
+    }
+
+    /// re-derives alphas. call when the audio thread's quantum changes.
+    pub fn set_block_dt(&mut self, dt_s: f32) {
+        if dt_s <= 0.0 || !dt_s.is_finite() || (dt_s - self.block_dt_s).abs() < 1e-9 {
+            return;
+        }
+        self.block_dt_s = dt_s;
+        let (a_a, a_r, a_rms) = compute_alphas(&self.cfg, dt_s);
+        self.peak_attack_alpha = a_a;
+        self.peak_release_alpha = a_r;
+        self.rms_alpha = a_rms;
+    }
+
+    /// `peak_lin` = per-block max|x|, `mean_sq_lin` = per-block Σx²/N.
+    pub fn process_block(&mut self, peak_lin: f32, mean_sq_lin: f32) -> LevelDecision {
+        let peak_lin = peak_lin.max(0.0);
+        let mean_sq_lin = mean_sq_lin.max(0.0);
+
+        let target_db = lin_to_db(peak_lin);
+        if target_db > self.peak_env_db {
+            self.peak_env_db += self.peak_attack_alpha * (target_db - self.peak_env_db);
+        } else {
+            self.peak_env_db += self.peak_release_alpha * (target_db - self.peak_env_db);
+        }
+
+        // smooth in the linear-power domain (canonical R128/IEC rms detector), then to dB.
+        self.rms_smoothed_mean_sq += self.rms_alpha * (mean_sq_lin - self.rms_smoothed_mean_sq);
+        // 20*log10(sqrt(mean_sq)) = 10*log10(mean_sq)
+        let rms_db = 10.0 * self.rms_smoothed_mean_sq.max(1e-30).log10();
+
+        let peak_reduction_db = (self.peak_env_db - self.cfg.peak_threshold_db).max(0.0);
+        let rms_reduction_db = (rms_db - self.cfg.rms_target_db).max(0.0);
+        let combined = peak_reduction_db.max(rms_reduction_db);
+        let total_reduction_db = combined.min(self.cfg.max_cut_db);
+
+        LevelDecision {
+            peak_reduction_db,
+            rms_reduction_db,
+            total_reduction_db,
+        }
+    }
+
+    /// reset envelope state; call when re-attaching after a deference period.
+    pub fn reset(&mut self) {
+        self.peak_env_db = -200.0;
+        self.rms_smoothed_mean_sq = 0.0;
+    }
+}
+
+fn compute_alphas(cfg: &LevelEnvelopesConfig, block_dt_s: f32) -> (f32, f32, f32) {
+    let block_dt_ms = block_dt_s * 1000.0;
+    let block_rate = if block_dt_s > 0.0 { 1.0 / block_dt_s } else { 1.0 };
+    // time_to_alpha against block rate, not sample rate: smoothers run at block boundaries,
+    // one (peak, mean_sq) pair per block. time_to_alpha is rate-agnostic.
+    let attack = time_to_alpha(cfg.peak_attack_ms, block_rate);
+    let release = time_to_alpha(cfg.peak_release_ms, block_rate);
+    let rms = time_to_alpha(cfg.rms_window_ms, block_rate);
+    let _ = block_dt_ms; // currently informational
+    (attack, release, rms)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::util::db_to_lin;
+
+    /// 1024-frame quantum at 48 kHz.
+    const BLOCK_DT_S: f32 = 1024.0 / 48_000.0;
+
+    fn run_steady(env: &mut LevelEnvelopes, peak_lin: f32, mean_sq_lin: f32, blocks: usize) -> LevelDecision {
+        let mut last = env.process_block(peak_lin, mean_sq_lin);
+        for _ in 1..blocks {
+            last = env.process_block(peak_lin, mean_sq_lin);
+        }
+        last
+    }
+
+    #[test]
+    fn quiet_signal_produces_no_reduction() {
+        let mut env = LevelEnvelopes::new(LevelEnvelopesConfig::default(), BLOCK_DT_S);
+        let quiet = db_to_lin(-30.0);
+        let mean_sq = quiet * quiet;
+        let dec = run_steady(&mut env, quiet, mean_sq, 200);
+        assert_eq!(dec.peak_reduction_db, 0.0);
+        assert_eq!(dec.rms_reduction_db, 0.0);
+        assert_eq!(dec.total_reduction_db, 0.0);
+    }
+
+    #[test]
+    fn peak_above_threshold_requests_cut() {
+        let cfg = LevelEnvelopesConfig {
+            peak_threshold_db: -6.0,
+            // Long RMS window so the slow path doesn't dominate.
+            rms_target_db: 0.0,
+            rms_window_ms: 5_000.0,
+            ..Default::default()
+        };
+        let mut env = LevelEnvelopes::new(cfg, BLOCK_DT_S);
+        // 0 dBFS peak: 6 dB over threshold.
+        let peak = db_to_lin(0.0);
+        let mean_sq = (peak * peak) * 0.05; // low rms (intermittent peak)
+        let dec = run_steady(&mut env, peak, mean_sq, 200);
+        assert!(
+            (dec.peak_reduction_db - 6.0).abs() < 0.5,
+            "expected ~6 dB peak cut, got {}",
+            dec.peak_reduction_db
+        );
+        assert_eq!(dec.rms_reduction_db, 0.0);
+        assert!((dec.total_reduction_db - 6.0).abs() < 0.5);
+    }
+
+    #[test]
+    fn rms_above_target_requests_cut() {
+        let cfg = LevelEnvelopesConfig {
+            // Push peak threshold up so only RMS engages.
+            peak_threshold_db: 0.0,
+            rms_target_db: -20.0,
+            rms_window_ms: 200.0, // shorter so test converges quickly
+            ..Default::default()
+        };
+        let mut env = LevelEnvelopes::new(cfg, BLOCK_DT_S);
+        // Sustained -10 dBFS RMS: 10 dB above target.
+        let rms_lin = db_to_lin(-10.0);
+        let mean_sq = rms_lin * rms_lin;
+        // Peak set just below threshold so peak detector stays asleep.
+        let peak = db_to_lin(-1.0);
+        let dec = run_steady(&mut env, peak, mean_sq, 200);
+        assert_eq!(dec.peak_reduction_db, 0.0);
+        assert!(
+            (dec.rms_reduction_db - 10.0).abs() < 0.5,
+            "expected ~10 dB RMS cut, got {}",
+            dec.rms_reduction_db
+        );
+    }
+
+    #[test]
+    fn combined_takes_max_of_peak_and_rms() {
+        let cfg = LevelEnvelopesConfig {
+            peak_threshold_db: -6.0,
+            rms_target_db: -20.0,
+            rms_window_ms: 200.0,
+            max_cut_db: 100.0,
+            ..Default::default()
+        };
+        let mut env = LevelEnvelopes::new(cfg, BLOCK_DT_S);
+        let peak = db_to_lin(0.0); // 6 dB over
+        let rms_lin = db_to_lin(-10.0); // 10 dB over
+        let mean_sq = rms_lin * rms_lin;
+        let dec = run_steady(&mut env, peak, mean_sq, 200);
+        assert!((dec.peak_reduction_db - 6.0).abs() < 0.5);
+        assert!((dec.rms_reduction_db - 10.0).abs() < 0.5);
+        assert!(
+            (dec.total_reduction_db - 10.0).abs() < 0.5,
+            "max(6, 10) ≈ 10, got {}",
+            dec.total_reduction_db
+        );
+    }
+
+    #[test]
+    fn total_reduction_is_clamped_to_max_cut_db() {
+        let cfg = LevelEnvelopesConfig {
+            peak_threshold_db: -30.0,
+            rms_target_db: -30.0,
+            rms_window_ms: 50.0,
+            max_cut_db: 3.0, // tight cap
+            ..Default::default()
+        };
+        let mut env = LevelEnvelopes::new(cfg, BLOCK_DT_S);
+        let peak = db_to_lin(0.0); // 30 dB over
+        let rms_lin = db_to_lin(-5.0);
+        let mean_sq = rms_lin * rms_lin;
+        let dec = run_steady(&mut env, peak, mean_sq, 200);
+        assert!(dec.peak_reduction_db > 20.0);
+        assert!(
+            (dec.total_reduction_db - 3.0).abs() < 1e-3,
+            "total clamped to max_cut_db, got {}",
+            dec.total_reduction_db
+        );
+    }
+
+    #[test]
+    fn peak_envelope_releases_after_burst() {
+        let cfg = LevelEnvelopesConfig {
+            peak_threshold_db: -6.0,
+            rms_target_db: 0.0,
+            rms_window_ms: 5_000.0,
+            peak_attack_ms: 5.0,
+            peak_release_ms: 100.0,
+            ..Default::default()
+        };
+        let mut env = LevelEnvelopes::new(cfg, BLOCK_DT_S);
+        // Burst.
+        for _ in 0..20 {
+            env.process_block(db_to_lin(0.0), 0.0);
+        }
+        let burst = env.process_block(db_to_lin(0.0), 0.0);
+        assert!(burst.peak_reduction_db > 5.0);
+
+        // Silence.
+        for _ in 0..200 {
+            env.process_block(0.0, 0.0);
+        }
+        let quiet = env.process_block(0.0, 0.0);
+        assert!(
+            quiet.peak_reduction_db < 0.5,
+            "expected ~0 after release, got {}",
+            quiet.peak_reduction_db
+        );
+    }
+
+    #[test]
+    fn set_config_updates_alphas_without_reset() {
+        let mut env = LevelEnvelopes::new(LevelEnvelopesConfig::default(), BLOCK_DT_S);
+        for _ in 0..100 {
+            env.process_block(db_to_lin(-3.0), 0.0);
+        }
+        let before = env.process_block(db_to_lin(-3.0), 0.0);
+        // Tighter threshold; envelope state preserved across the swap.
+        env.set_config(LevelEnvelopesConfig {
+            peak_threshold_db: -12.0,
+            ..LevelEnvelopesConfig::default()
+        });
+        let after = env.process_block(db_to_lin(-3.0), 0.0);
+        assert!(
+            after.peak_reduction_db > before.peak_reduction_db,
+            "tighter threshold should request more cut"
+        );
+    }
+
+    #[test]
+    fn set_block_dt_recomputes_alphas() {
+        let mut env = LevelEnvelopes::new(LevelEnvelopesConfig::default(), BLOCK_DT_S);
+        let original_attack = env.peak_attack_alpha;
+        // Double the block period — slower block rate → smaller alpha
+        // for the same time constant.
+        env.set_block_dt(BLOCK_DT_S * 2.0);
+        assert!(env.peak_attack_alpha > original_attack);
+    }
+
+    #[test]
+    fn reset_returns_to_idle_state() {
+        let mut env = LevelEnvelopes::new(LevelEnvelopesConfig::default(), BLOCK_DT_S);
+        for _ in 0..200 {
+            env.process_block(db_to_lin(0.0), db_to_lin(-3.0));
+        }
+        env.reset();
+        let dec = env.process_block(0.0, 0.0);
+        assert_eq!(dec.peak_reduction_db, 0.0);
+        assert_eq!(dec.rms_reduction_db, 0.0);
+    }
+}

Added file: crates/headroom-dsp/src/lib.rs+23 additions@@ -0,0 +1,23 @@
+//! dsp kernels. every `process_*` is allocation-free + bounded-time; `new` allocates (not rt-safe).
+
+#![forbid(unsafe_code)]
+#![warn(missing_docs)]
+
+mod agc;
+mod compressor;
+mod delay;
+mod envelope;
+mod level_envelopes;
+mod limiter;
+mod oversample;
+mod sliding_max;
+pub mod util;
+
+pub use agc::{AgcGain, AgcGainConfig};
+pub use compressor::{Compressor, CompressorConfig, Detector};
+pub use delay::DelayLine;
+pub use envelope::AttackRelease;
+pub use level_envelopes::{LevelDecision, LevelEnvelopes, LevelEnvelopesConfig};
+pub use limiter::{Limiter, LimiterConfig, SetConfigOutcome, SoftTierConfig};
+pub use oversample::{design_lowpass_blackman, PolyphaseDownsampler, PolyphaseUpsampler};
+pub use sliding_max::SlidingMaxBuffer;

Added file: crates/headroom-dsp/src/limiter.rs+1046 additions@@ -0,0 +1,1046 @@
+//! two-tier true-peak limiter: parallel soft (dynamic psr ceiling) + hard (absolute contract) tiers.
+
+use crate::delay::DelayLine;
+use crate::envelope::AttackRelease;
+use crate::oversample::{design_lowpass_blackman, PolyphaseDownsampler, PolyphaseUpsampler};
+use crate::sliding_max::SlidingMaxBuffer;
+use crate::util::{db_to_lin, lin_to_db, time_to_alpha};
+
+/// soft tier targets a dynamic ceiling `program_loudness_lufs + max_psr_db`; bounds the
+/// peak-to-loudness ratio, not a safety contract (that's the hard tier).
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct SoftTierConfig {
+    /// max peak-to-shortterm-loudness ratio (dB). effective ceiling = `program_lufs + max_psr_db`.
+    pub max_psr_db: f32,
+    /// fallback ceiling (dBTP) when no program loudness yet (startup, before first agc window).
+    pub static_ceiling_dbtp: f32,
+    pub attack_ms: f32,
+    pub release_ms: f32,
+}
+
+impl Default for SoftTierConfig {
+    fn default() -> Self {
+        Self {
+            max_psr_db: 14.0,
+            static_ceiling_dbtp: -6.0,
+            attack_ms: 5.0,
+            release_ms: 200.0,
+        }
+    }
+}
+
+impl SoftTierConfig {
+    #[must_use]
+    pub fn sanitized(mut self) -> Self {
+        if self.static_ceiling_dbtp > 0.0 {
+            self.static_ceiling_dbtp = 0.0;
+        }
+        if !self.max_psr_db.is_finite() || self.max_psr_db < 0.0 {
+            self.max_psr_db = 0.0;
+        }
+        if self.attack_ms < 0.0 || !self.attack_ms.is_finite() {
+            self.attack_ms = 0.0;
+        }
+        if self.release_ms < 0.0 || !self.release_ms.is_finite() {
+            self.release_ms = 0.0;
+        }
+        self
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq)]
+pub struct LimiterConfig {
+    /// hard-tier output ceiling (dBTP). must be `<= 0.0`.
+    pub ceiling_dbtp: f32,
+    /// lookahead (ms); sets delay-line length + peak-window size. shared by both tiers.
+    pub lookahead_ms: f32,
+    /// hard-tier exponential release toward unity (ms).
+    pub release_ms: f32,
+    /// hard-tier hold after a reduction before release begins (ms).
+    pub hold_ms: f32,
+    /// oversample factor. 1 disables isp detection; 4 is the bs.1770-4 reference.
+    pub oversample: usize,
+    /// fir taps for the oversampling filter (odd).
+    pub fir_taps: usize,
+    /// `None` disables the soft tier → pure brickwall.
+    pub soft: Option<SoftTierConfig>,
+}
+
+impl Default for LimiterConfig {
+    fn default() -> Self {
+        Self {
+            ceiling_dbtp: -0.1,
+            lookahead_ms: 2.0,
+            release_ms: 80.0,
+            hold_ms: 5.0,
+            oversample: 4,
+            fir_taps: 31,
+            soft: Some(SoftTierConfig::default()),
+        }
+    }
+}
+
+/// internal-rate cap (Hz). detector upsamples to `sample_rate × oversample`; above ~192 kHz
+/// fir cost rises linearly with no isp-detection gain, so drop oversample on high base rates.
+pub const MAX_INTERNAL_RATE_HZ: f32 = 192_000.0;
+
+impl LimiterConfig {
+    /// rate-agnostic. callers that know the sample rate should prefer [`Self::sanitize_for_rate`]
+    /// so oversample scales down on high-rate inputs.
+    #[must_use]
+    pub fn sanitized(mut self) -> Self {
+        if self.ceiling_dbtp > 0.0 {
+            self.ceiling_dbtp = 0.0;
+        }
+        self.oversample = self.oversample.clamp(1, 8);
+        if self.fir_taps < 5 {
+            self.fir_taps = 5;
+        }
+        if self.fir_taps % 2 == 0 {
+            self.fir_taps += 1;
+        }
+        if let Some(soft) = self.soft {
+            self.soft = Some(soft.sanitized());
+        }
+        self
+    }
+
+    /// caps oversample so post-upsample rate stays ≤ [`MAX_INTERNAL_RATE_HZ`]; always ≥ 1.
+    /// at default 4×: 48 kHz → 4×, 96 kHz → 2×, 192 kHz → 1×.
+    #[must_use]
+    pub fn sanitize_for_rate(self, sample_rate: f32) -> Self {
+        let mut s = self.sanitized();
+        if sample_rate > 0.0 {
+            let max_os =
+                (MAX_INTERNAL_RATE_HZ / sample_rate).floor().max(1.0) as usize;
+            if s.oversample > max_os {
+                s.oversample = max_os;
+            }
+        }
+        s
+    }
+
+    /// brickwall only (no soft tier).
+    #[must_use]
+    pub fn brickwall_only() -> Self {
+        Self {
+            soft: None,
+            ..Self::default()
+        }
+    }
+}
+
+const MAX_OVERSAMPLE: usize = 8;
+const SILENCE_EPS: f32 = 1.0e-20;
+const OUTPUT_IDLE_EPS: f32 = 1.0e-12;
+const GAIN_IDLE_EPS: f32 = 1.0e-4;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SetConfigOutcome {
+    /// applied in place.
+    Applied,
+    /// differs in `oversample`/`fir_taps`/`lookahead_ms` (in samples) → would realloc buffers.
+    /// limiter unchanged; rebuild from `Limiter::new` on the control thread.
+    StructuralChange,
+}
+
+pub struct Limiter {
+    cfg: LimiterConfig,
+    /// captured at construction so try_set_config can recompute time coeffs without a repass.
+    sample_rate: f32,
+    ceiling_lin: f32,
+    os: usize,
+
+    // Per-channel oversampler / downsampler / delay-line paths.
+    up_l: PolyphaseUpsampler,
+    up_r: PolyphaseUpsampler,
+    down_l: PolyphaseDownsampler,
+    down_r: PolyphaseDownsampler,
+    delay_l: DelayLine,
+    delay_r: DelayLine,
+
+    /// sliding-window peak (oversampled domain), shared across channels + tiers.
+    peak_buf: SlidingMaxBuffer,
+
+    // ---- Hard tier state (instant attack + hold + release) ----
+    hard_gain: f32,
+    hold_remaining: u32,
+    hold_samples_os: u32,
+    hard_release_alpha: f32,
+
+    // ---- Soft tier state (smooth envelope) ----
+    soft_envelope: Option<AttackRelease>,
+    soft_max_psr_db: f32,
+    soft_static_ceiling_lin: f32,
+    program_loudness_lufs: Option<f32>,
+    /// effective soft ceiling (linear), recomputed when program loudness changes.
+    soft_ceiling_lin: f32,
+
+    // scratch buffers (sized for max oversample factor).
+    up_buf_l: [f32; MAX_OVERSAMPLE],
+    up_buf_r: [f32; MAX_OVERSAMPLE],
+    gained_buf_l: [f32; MAX_OVERSAMPLE],
+    gained_buf_r: [f32; MAX_OVERSAMPLE],
+
+    // telemetry (sampled per frame).
+    last_peak_lin: f32,
+    last_gr_db: f32,
+    last_soft_gr_db: f32,
+    last_hard_gr_db: f32,
+    last_output_lin: f32,
+    idle_drain_frames: usize,
+    silent_drain_remaining: usize,
+}
+
+impl Limiter {
+    /// allocates fir coeffs, polyphase tables, delay buffers. not rt-safe.
+    #[must_use]
+    pub fn new(cfg: LimiterConfig, sample_rate: f32) -> Self {
+        let cfg = cfg.sanitized();
+        let os = cfg.oversample;
+        let lowpass = if os > 1 {
+            design_lowpass_blackman(cfg.fir_taps, 0.45 / os as f32)
+        } else {
+            vec![1.0]
+        };
+
+        let os_rate = sample_rate * os as f32;
+        let lookahead_samples_os = (cfg.lookahead_ms * 1e-3 * os_rate).round() as usize;
+        let lookahead_samples_os = lookahead_samples_os.max(1);
+        let lookahead_frames = lookahead_samples_os.div_ceil(os);
+        let idle_drain_frames = lookahead_frames + cfg.fir_taps * 2 + 2;
+        let hold_samples_os = (cfg.hold_ms * 1e-3 * os_rate).round() as u32;
+        let hard_release_alpha = time_to_alpha(cfg.release_ms, os_rate);
+        let ceiling_lin = db_to_lin(cfg.ceiling_dbtp);
+
+        let (soft_envelope, soft_max_psr_db, soft_static_ceiling_lin, soft_ceiling_lin) =
+            if let Some(soft) = cfg.soft {
+                let env = AttackRelease::new(soft.attack_ms, soft.release_ms, os_rate);
+                let static_ceiling_lin = db_to_lin(soft.static_ceiling_dbtp);
+                (
+                    Some(env),
+                    soft.max_psr_db,
+                    static_ceiling_lin,
+                    static_ceiling_lin,
+                )
+            } else {
+                (None, 0.0, 1.0, 1.0)
+            };
+
+        let mut me = Self {
+            cfg,
+            sample_rate,
+            ceiling_lin,
+            os,
+            up_l: PolyphaseUpsampler::new(os, &lowpass),
+            up_r: PolyphaseUpsampler::new(os, &lowpass),
+            down_l: PolyphaseDownsampler::new(os, &lowpass),
+            down_r: PolyphaseDownsampler::new(os, &lowpass),
+            delay_l: DelayLine::new(lookahead_samples_os),
+            delay_r: DelayLine::new(lookahead_samples_os),
+            peak_buf: SlidingMaxBuffer::new(lookahead_samples_os),
+            hard_gain: 1.0,
+            hold_remaining: 0,
+            hold_samples_os,
+            hard_release_alpha,
+            soft_envelope,
+            soft_max_psr_db,
+            soft_static_ceiling_lin,
+            program_loudness_lufs: None,
+            soft_ceiling_lin,
+            up_buf_l: [0.0; MAX_OVERSAMPLE],
+            up_buf_r: [0.0; MAX_OVERSAMPLE],
+            gained_buf_l: [0.0; MAX_OVERSAMPLE],
+            gained_buf_r: [0.0; MAX_OVERSAMPLE],
+            last_peak_lin: 0.0,
+            last_gr_db: 0.0,
+            last_soft_gr_db: 0.0,
+            last_hard_gr_db: 0.0,
+            last_output_lin: 0.0,
+            idle_drain_frames,
+            silent_drain_remaining: 0,
+        };
+        // seed soft envelope to unity: no phantom gain reduction on the first frames.
+        if let Some(env) = &mut me.soft_envelope {
+            env.reset(1.0);
+        }
+        me
+    }
+
+    #[must_use]
+    pub fn config(&self) -> LimiterConfig {
+        self.cfg
+    }
+
+    #[must_use]
+    pub fn ceiling_dbtp(&self) -> f32 {
+        self.cfg.ceiling_dbtp
+    }
+
+    /// applied total reduction `min(soft_gain, hard_gain)` (dB, negative when limiting).
+    #[must_use]
+    pub fn gain_reduction_db(&self) -> f32 {
+        self.last_gr_db
+    }
+
+    #[must_use]
+    pub fn soft_gain_reduction_db(&self) -> f32 {
+        self.last_soft_gr_db
+    }
+
+    /// non-zero ⇒ soft tier didn't hold the ceiling and the brickwall engaged. routinely
+    /// non-zero on benign material ⇒ soft under-configured (psr too high / attack too slow /
+    /// lookahead too short).
+    #[must_use]
+    pub fn hard_gain_reduction_db(&self) -> f32 {
+        self.last_hard_gr_db
+    }
+
+    #[must_use]
+    pub fn true_peak_dbtp(&self) -> f32 {
+        lin_to_db(self.last_peak_lin.max(1e-20))
+    }
+
+    /// `program_loudness_lufs + soft.max_psr_db` when both known, else `static_ceiling_dbtp`.
+    /// `None` if soft tier disabled.
+    #[must_use]
+    pub fn effective_soft_ceiling_dbtp(&self) -> Option<f32> {
+        self.cfg.soft.map(|_| lin_to_db(self.soft_ceiling_lin))
+    }
+
+    /// live-update non-structural params (ceiling, hard release/hold, soft toggle + scalars).
+    /// allocation-free, rt-safe. structural changes return [`SetConfigOutcome::StructuralChange`]
+    /// and leave the limiter unchanged — see that variant.
+    pub fn try_set_config(&mut self, cfg: LimiterConfig) -> SetConfigOutcome {
+        let cfg = cfg.sanitized();
+        let os_rate = self.sample_rate * cfg.oversample as f32;
+        let new_lookahead_samples_os =
+            ((cfg.lookahead_ms * 1e-3 * os_rate).round() as usize).max(1);
+        let cur_lookahead_samples_os = self.peak_buf.window();
+        if cfg.oversample != self.os
+            || cfg.fir_taps != self.cfg.fir_taps
+            || new_lookahead_samples_os != cur_lookahead_samples_os
+        {
+            return SetConfigOutcome::StructuralChange;
+        }
+
+        self.ceiling_lin = db_to_lin(cfg.ceiling_dbtp);
+        self.hard_release_alpha = time_to_alpha(cfg.release_ms, os_rate);
+        self.hold_samples_os = (cfg.hold_ms * 1e-3 * os_rate).round() as u32;
+
+        match (cfg.soft, self.cfg.soft) {
+            (Some(new_soft), Some(_old_soft)) => {
+                self.soft_max_psr_db = new_soft.max_psr_db;
+                self.soft_static_ceiling_lin = db_to_lin(new_soft.static_ceiling_dbtp);
+                if let Some(env) = &mut self.soft_envelope {
+                    env.set_times(new_soft.attack_ms, new_soft.release_ms, os_rate);
+                }
+            }
+            (Some(new_soft), None) => {
+                // re-enable: seed envelope to unity, no phantom gain reduction.
+                let mut env = AttackRelease::new(new_soft.attack_ms, new_soft.release_ms, os_rate);
+                env.reset(1.0);
+                self.soft_envelope = Some(env);
+                self.soft_max_psr_db = new_soft.max_psr_db;
+                self.soft_static_ceiling_lin = db_to_lin(new_soft.static_ceiling_dbtp);
+            }
+            (None, Some(_)) => {
+                self.soft_envelope = None;
+                self.soft_max_psr_db = 0.0;
+                self.soft_static_ceiling_lin = 1.0;
+            }
+            (None, None) => {}
+        }
+
+        self.cfg = cfg;
+        self.recompute_soft_ceiling();
+        SetConfigOutcome::Applied
+    }
+
+    /// program loudness for the dynamic soft ceiling; called by the agc at tick rate.
+    /// non-finite ignored.
+    pub fn set_program_loudness_lufs(&mut self, lufs: f32) {
+        if !lufs.is_finite() {
+            return;
+        }
+        self.program_loudness_lufs = Some(lufs);
+        self.recompute_soft_ceiling();
+    }
+
+    /// forget program loudness; soft tier falls back to its static ceiling.
+    pub fn clear_program_loudness(&mut self) {
+        self.program_loudness_lufs = None;
+        self.recompute_soft_ceiling();
+    }
+
+    fn recompute_soft_ceiling(&mut self) {
+        self.soft_ceiling_lin = match (self.cfg.soft, self.program_loudness_lufs) {
+            (Some(_), Some(lufs)) => {
+                let dynamic_dbtp = (lufs + self.soft_max_psr_db).min(0.0);
+                db_to_lin(dynamic_dbtp)
+            }
+            (Some(_), None) => self.soft_static_ceiling_lin,
+            (None, _) => 1.0,
+        };
+    }
+
+    /// allocation-free. output guaranteed within `±ceiling_dbtp` (the hard contract).
+    pub fn process_frame(&mut self, left: f32, right: f32) -> (f32, f32) {
+        // sanitize NaN/Inf to zero; never let garbage into limiter state.
+        let left = if left.is_finite() { left } else { 0.0 };
+        let right = if right.is_finite() { right } else { 0.0 };
+        let input_silent = left.abs() <= SILENCE_EPS && right.abs() <= SILENCE_EPS;
+        if input_silent && self.signal_path_idle() {
+            self.last_peak_lin = 0.0;
+            self.last_gr_db = 0.0;
+            self.last_soft_gr_db = 0.0;
+            self.last_hard_gr_db = 0.0;
+            self.last_output_lin = 0.0;
+            return (0.0, 0.0);
+        }
+        if input_silent {
+            self.silent_drain_remaining = self.silent_drain_remaining.saturating_sub(1);
+        } else {
+            self.silent_drain_remaining = self.idle_drain_frames;
+        }
+
+        self.up_l.process(left, &mut self.up_buf_l[..self.os]);
+        self.up_r.process(right, &mut self.up_buf_r[..self.os]);
+
+        let mut frame_peak = 0.0_f32;
+        let mut min_soft_gain = 1.0_f32;
+        let mut min_total_gain = 1.0_f32;
+
+        for k in 0..self.os {
+            let s_l = self.up_buf_l[k];
+            let s_r = self.up_buf_r[k];
+
+            let peak = s_l.abs().max(s_r.abs());
+            frame_peak = frame_peak.max(peak);
+
+            let window_peak = self.peak_buf.push_and_max(peak);
+
+            // ---- Soft tier --------------------------------------
+            let soft_gain = if let Some(env) = &mut self.soft_envelope {
+                let target = if window_peak > self.soft_ceiling_lin && window_peak > 1e-20 {
+                    self.soft_ceiling_lin / window_peak
+                } else {
+                    1.0
+                };
+                env.process_gain(target)
+            } else {
+                1.0
+            };
+            if soft_gain < min_soft_gain {
+                min_soft_gain = soft_gain;
+            }
+
+            // ---- Hard tier --------------------------------------
+            // size hard gain against the peak *after* the soft tier acts, so it doesn't do
+            // redundant work. predicted_post_soft = max(immediate: current soft gain applied;
+            // asymptotic: soft converged to target) — the larger/more conservative.
+            let predicted_post_soft = if self.soft_envelope.is_some() {
+                let asymptotic = window_peak.min(self.soft_ceiling_lin);
+                let immediate = window_peak * soft_gain;
+                asymptotic.max(immediate)
+            } else {
+                window_peak
+            };
+            let hard_target =
+                if predicted_post_soft > self.ceiling_lin && predicted_post_soft > 1e-20 {
+                    self.ceiling_lin / predicted_post_soft
+                } else {
+                    1.0
+                };
+
+            if hard_target < self.hard_gain {
+                self.hard_gain = hard_target;
+                self.hold_remaining = self.hold_samples_os;
+            } else if self.hold_remaining > 0 {
+                self.hold_remaining -= 1;
+            } else {
+                self.hard_gain += self.hard_release_alpha * (hard_target - self.hard_gain);
+                if self.hard_gain > hard_target {
+                    self.hard_gain = hard_target;
+                }
+            }
+
+            // ---- Combine ----------------------------------------
+            let total_gain = soft_gain.min(self.hard_gain);
+            if total_gain < min_total_gain {
+                min_total_gain = total_gain;
+            }
+
+            let d_l = self.delay_l.push_pop(s_l);
+            let d_r = self.delay_r.push_pop(s_r);
+
+            let mut out_l = d_l * total_gain;
+            let mut out_r = d_r * total_gain;
+
+            // defense-in-depth #1: clip in the oversampled domain so overshoots can't enter
+            // the downsampler.
+            out_l = out_l.clamp(-self.ceiling_lin, self.ceiling_lin);
+            out_r = out_r.clamp(-self.ceiling_lin, self.ceiling_lin);
+
+            self.gained_buf_l[k] = out_l;
+            self.gained_buf_r[k] = out_r;
+        }
+
+        let mut out_l = self.down_l.process(&self.gained_buf_l[..self.os]);
+        let mut out_r = self.down_r.process(&self.gained_buf_r[..self.os]);
+
+        // defense-in-depth #2: clip post-downsample, guarding against fir ringing nudging
+        // the output above the ceiling.
+        out_l = out_l.clamp(-self.ceiling_lin, self.ceiling_lin);
+        out_r = out_r.clamp(-self.ceiling_lin, self.ceiling_lin);
+
+        self.last_peak_lin = frame_peak;
+        self.last_soft_gr_db = lin_to_db(min_soft_gain.max(1e-12));
+        self.last_hard_gr_db = lin_to_db(self.hard_gain.max(1e-12));
+        self.last_gr_db = lin_to_db(min_total_gain.max(1e-12));
+        self.last_output_lin = out_l.abs().max(out_r.abs());
+        if input_silent
+            && self.silent_drain_remaining == 0
+            && self.last_output_lin <= OUTPUT_IDLE_EPS
+            && self.gain_state_idle()
+        {
+            self.reset_signal_path();
+        }
+
+        (out_l, out_r)
+    }
+
+    /// process an interleaved stereo buffer in place.
+    pub fn process_interleaved_stereo(&mut self, buf: &mut [f32]) {
+        debug_assert!(buf.len() % 2 == 0);
+        for frame in buf.chunks_exact_mut(2) {
+            let (l, r) = self.process_frame(frame[0], frame[1]);
+            frame[0] = l;
+            frame[1] = r;
+        }
+    }
+
+    /// reset all internal state; program loudness is also cleared.
+    pub fn reset(&mut self) {
+        self.reset_signal_path();
+        self.program_loudness_lufs = None;
+        self.recompute_soft_ceiling();
+    }
+
+    fn reset_signal_path(&mut self) {
+        self.up_l.reset();
+        self.up_r.reset();
+        self.down_l.reset();
+        self.down_r.reset();
+        self.delay_l.reset();
+        self.delay_r.reset();
+        self.peak_buf.reset();
+        self.hard_gain = 1.0;
+        self.hold_remaining = 0;
+        if let Some(env) = &mut self.soft_envelope {
+            env.reset(1.0);
+        }
+        self.last_peak_lin = 0.0;
+        self.last_gr_db = 0.0;
+        self.last_soft_gr_db = 0.0;
+        self.last_hard_gr_db = 0.0;
+        self.last_output_lin = 0.0;
+        self.silent_drain_remaining = 0;
+    }
+
+    fn signal_path_idle(&self) -> bool {
+        self.silent_drain_remaining == 0
+            && self.last_peak_lin <= OUTPUT_IDLE_EPS
+            && self.last_output_lin <= OUTPUT_IDLE_EPS
+            && self.gain_state_idle()
+    }
+
+    fn gain_state_idle(&self) -> bool {
+        self.hold_remaining == 0
+            && (self.hard_gain - 1.0).abs() <= GAIN_IDLE_EPS
+            && self
+                .soft_envelope
+                .as_ref()
+                .is_none_or(|env| (env.state() - 1.0).abs() <= GAIN_IDLE_EPS)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::f32::consts::PI;
+
+    // ----------------------------------------------------------------
+    // sanitize_for_rate: oversample factor scales down so the
+    // internal (post-upsample) rate stays bounded.
+    // ----------------------------------------------------------------
+
+    #[test]
+    fn sanitize_for_rate_caps_oversample_at_internal_192k() {
+        // Default config has oversample = 4.
+        let default = LimiterConfig::default();
+        assert_eq!(default.oversample, 4);
+
+        // At 48 kHz: 4× = 192 kHz, at the cap, untouched.
+        assert_eq!(default.sanitize_for_rate(48_000.0).oversample, 4);
+        // At 44.1 kHz: 4× = 176.4 kHz, under the cap.
+        assert_eq!(default.sanitize_for_rate(44_100.0).oversample, 4);
+        // At 96 kHz: 4× = 384 kHz, exceeds; drop to 2× = 192 kHz.
+        assert_eq!(default.sanitize_for_rate(96_000.0).oversample, 2);
+        // At 192 kHz: cap forces oversample = 1.
+        assert_eq!(default.sanitize_for_rate(192_000.0).oversample, 1);
+        // Pathological rate above the cap still leaves at least 1.
+        assert_eq!(default.sanitize_for_rate(384_000.0).oversample, 1);
+    }
+
+    #[test]
+    fn sanitize_for_rate_preserves_user_lower_oversample() {
+        // User who explicitly set oversample = 2 at 48 kHz should
+        // keep it; the rate cap doesn't push the value *up*.
+        let cfg = LimiterConfig {
+            oversample: 2,
+            ..LimiterConfig::default()
+        };
+        assert_eq!(cfg.sanitize_for_rate(48_000.0).oversample, 2);
+    }
+
+    // ----------------------------------------------------------------
+    // try_set_config: scalar updates apply in place, structural
+    // changes are rejected.
+    // ----------------------------------------------------------------
+
+    #[test]
+    fn try_set_config_applies_scalar_changes() {
+        let sr = 48_000.0;
+        let mut l = Limiter::new(LimiterConfig::default(), sr);
+        let cfg = LimiterConfig {
+            ceiling_dbtp: -3.0,
+            release_ms: 200.0,
+            hold_ms: 10.0,
+            ..LimiterConfig::default()
+        };
+        assert_eq!(l.try_set_config(cfg), SetConfigOutcome::Applied);
+        assert!((l.ceiling_dbtp() - -3.0).abs() < 1e-6);
+        let active = l.config();
+        assert!((active.release_ms - 200.0).abs() < 1e-6);
+        assert!((active.hold_ms - 10.0).abs() < 1e-6);
+    }
+
+    #[test]
+    fn try_set_config_can_toggle_soft_tier() {
+        let sr = 48_000.0;
+        let mut l = Limiter::new(LimiterConfig::default(), sr);
+        // Start with soft on. Disable it.
+        let mut cfg = LimiterConfig {
+            soft: None,
+            ..LimiterConfig::default()
+        };
+        assert_eq!(l.try_set_config(cfg), SetConfigOutcome::Applied);
+        assert!(l.config().soft.is_none());
+        assert!(l.effective_soft_ceiling_dbtp().is_none());
+
+        // Re-enable with custom params.
+        let new_soft = SoftTierConfig {
+            max_psr_db: 10.0,
+            static_ceiling_dbtp: -4.0,
+            attack_ms: 8.0,
+            release_ms: 300.0,
+        };
+        cfg.soft = Some(new_soft);
+        assert_eq!(l.try_set_config(cfg), SetConfigOutcome::Applied);
+        let active_soft = l.config().soft.expect("soft re-enabled");
+        assert!((active_soft.max_psr_db - 10.0).abs() < 1e-6);
+        assert!((active_soft.static_ceiling_dbtp - -4.0).abs() < 1e-6);
+    }
+
+    #[test]
+    fn try_set_config_rejects_oversample_change() {
+        let sr = 48_000.0;
+        let mut l = Limiter::new(LimiterConfig::default(), sr);
+        let cfg = LimiterConfig {
+            oversample: 8,
+            ..LimiterConfig::default()
+        };
+        assert_eq!(l.try_set_config(cfg), SetConfigOutcome::StructuralChange);
+        // Limiter unchanged.
+        assert_eq!(l.config().oversample, LimiterConfig::default().oversample);
+    }
+
+    #[test]
+    fn try_set_config_rejects_lookahead_change() {
+        let sr = 48_000.0;
+        let mut l = Limiter::new(LimiterConfig::default(), sr);
+        let cfg = LimiterConfig {
+            // resizes delay + peak buffer
+            lookahead_ms: 5.0,
+            ..LimiterConfig::default()
+        };
+        assert_eq!(l.try_set_config(cfg), SetConfigOutcome::StructuralChange);
+    }
+
+    #[test]
+    fn try_set_config_rejects_fir_taps_change() {
+        let sr = 48_000.0;
+        let mut l = Limiter::new(LimiterConfig::default(), sr);
+        let cfg = LimiterConfig {
+            fir_taps: 63,
+            ..LimiterConfig::default()
+        };
+        assert_eq!(l.try_set_config(cfg), SetConfigOutcome::StructuralChange);
+    }
+
+    fn run_sine(
+        limiter: &mut Limiter,
+        freq: f32,
+        amp_db: f32,
+        samples: usize,
+        sr: f32,
+    ) -> Vec<f32> {
+        let amp = db_to_lin(amp_db);
+        let mut out = Vec::with_capacity(samples * 2);
+        for n in 0..samples {
+            let t = n as f32 / sr;
+            let s = amp * (2.0 * PI * freq * t).sin();
+            let (l, r) = limiter.process_frame(s, s);
+            out.push(l);
+            out.push(r);
+        }
+        out
+    }
+
+    // ----------------------------------------------------------------
+    // Hard-tier contract: holds with or without the soft tier present.
+    // ----------------------------------------------------------------
+
+    #[test]
+    fn passes_signal_below_both_ceilings_unchanged() {
+        let sr = 48_000.0;
+        let mut l = Limiter::new(LimiterConfig::default(), sr);
+        // -18 dBFS is below the default static soft ceiling of -6 dBTP
+        // and the hard ceiling. Neither tier should engage.
+        let out = run_sine(&mut l, 440.0, -18.0, 4_800, sr);
+        let max_abs = out.iter().skip(1_000).fold(0.0_f32, |a, &b| a.max(b.abs()));
+        let max_db = lin_to_db(max_abs);
+        assert!(
+            (max_db - (-18.0)).abs() < 0.5,
+            "expected ~-18 dB, got {max_db}"
+        );
+        assert!(
+            l.gain_reduction_db().abs() < 0.5,
+            "expected ~0 GR, got {}",
+            l.gain_reduction_db()
+        );
+    }
+
+    #[test]
+    fn enforces_hard_ceiling_on_hot_signal_with_soft_tier() {
+        let sr = 48_000.0;
+        let mut l = Limiter::new(LimiterConfig::default(), sr);
+        let out = run_sine(&mut l, 440.0, 6.0, 9_600, sr);
+        let ceiling_lin = db_to_lin(-0.1);
+        let max_abs = out
+            .iter()
+            .skip(2_000)
+            .fold(0.0_f32, |a, &b| a.max(b.abs()));
+        assert!(
+            max_abs <= ceiling_lin + 1e-6,
+            "above hard ceiling: max_abs={max_abs}, ceiling_lin={ceiling_lin}"
+        );
+    }
+
+    #[test]
+    fn enforces_hard_ceiling_on_intersample_peak_with_soft_tier() {
+        let sr = 48_000.0;
+        let mut l = Limiter::new(LimiterConfig::default(), sr);
+        let ceiling_lin = db_to_lin(-0.1);
+        let mut max_abs = 0.0_f32;
+        let mut sign = 1.0_f32;
+        let amp = 0.95_f32;
+        for n in 0..9_600 {
+            let s = sign * amp;
+            sign = -sign;
+            let (lo, ro) = l.process_frame(s, s);
+            if n > 1_500 {
+                max_abs = max_abs.max(lo.abs()).max(ro.abs());
+            }
+        }
+        assert!(
+            max_abs <= ceiling_lin + 1e-6,
+            "ISP: above hard ceiling: max_abs={max_abs}, ceiling_lin={ceiling_lin}"
+        );
+    }
+
+    #[test]
+    fn enforces_hard_ceiling_on_transient_impulse_with_soft_tier() {
+        let sr = 48_000.0;
+        let mut l = Limiter::new(LimiterConfig::default(), sr);
+        let ceiling_lin = db_to_lin(-0.1);
+        let mut max_abs = 0.0_f32;
+        for n in 0..4_800_usize {
+            let s = if n == 1_000 { 4.0 } else { 0.0 };
+            let (lo, ro) = l.process_frame(s, s);
+            max_abs = max_abs.max(lo.abs()).max(ro.abs());
+        }
+        assert!(
+            max_abs <= ceiling_lin + 1e-6,
+            "impulse: above hard ceiling: max_abs={max_abs}, ceiling_lin={ceiling_lin}"
+        );
+    }
+
+    #[test]
+    fn brickwall_only_skips_soft_tier_entirely() {
+        let sr = 48_000.0;
+        let mut l = Limiter::new(LimiterConfig::brickwall_only(), sr);
+        assert!(l.effective_soft_ceiling_dbtp().is_none());
+        // Drive a hot signal; brickwall must still hold.
+        let out = run_sine(&mut l, 440.0, 6.0, 4_800, sr);
+        let ceiling_lin = db_to_lin(-0.1);
+        let max_abs = out.iter().skip(800).fold(0.0_f32, |a, &b| a.max(b.abs()));
+        assert!(max_abs <= ceiling_lin + 1e-6);
+        // No soft gain reduction should ever have been recorded.
+        assert!(l.soft_gain_reduction_db().abs() < 1e-6);
+    }
+
+    // ----------------------------------------------------------------
+    // Soft tier: static fallback ceiling
+    // ----------------------------------------------------------------
+
+    #[test]
+    fn soft_tier_static_ceiling_engages_before_hard() {
+        let sr = 48_000.0;
+        // Static soft ceiling at -6 dBTP, attack short enough to
+        // settle inside the lookahead.
+        let cfg = LimiterConfig {
+            lookahead_ms: 5.0,
+            soft: Some(SoftTierConfig {
+                static_ceiling_dbtp: -6.0,
+                attack_ms: 1.0,
+                release_ms: 100.0,
+                ..SoftTierConfig::default()
+            }),
+            ..LimiterConfig::default()
+        };
+        let mut l = Limiter::new(cfg, sr);
+        // Drive a +6 dB sine — well above the soft ceiling.
+        let out = run_sine(&mut l, 440.0, 6.0, 9_600, sr);
+
+        // Output should sit near the soft ceiling, well below hard.
+        let soft_ceiling_lin = db_to_lin(-6.0);
+        let max_abs = out
+            .iter()
+            .skip(2_000)
+            .fold(0.0_f32, |a, &b| a.max(b.abs()));
+        // Allow small overshoot during soft attack (gain hasn't fully
+        // settled when the peak arrives), but it must be well under
+        // the hard ceiling.
+        assert!(
+            max_abs <= soft_ceiling_lin * 1.1,
+            "output above soft ceiling: max_abs={max_abs}, soft_lin={soft_ceiling_lin}"
+        );
+        // Soft tier should report meaningful GR; hard tier ideally
+        // does very little once the soft tier has settled.
+        assert!(
+            l.soft_gain_reduction_db() < -3.0,
+            "soft GR too small: {}",
+            l.soft_gain_reduction_db()
+        );
+    }
+
+    // ----------------------------------------------------------------
+    // Soft tier: dynamic ceiling from program loudness
+    // ----------------------------------------------------------------
+
+    #[test]
+    fn dynamic_ceiling_tracks_program_loudness() {
+        let sr = 48_000.0;
+        let mut l = Limiter::new(LimiterConfig::default(), sr);
+        // Default max_psr_db = 14.
+        l.set_program_loudness_lufs(-18.0);
+        let dyn_ceiling = l.effective_soft_ceiling_dbtp().expect("soft tier active");
+        assert!(
+            (dyn_ceiling - (-4.0)).abs() < 1e-3,
+            "expected -4 dBTP, got {dyn_ceiling}"
+        );
+
+        // Move the program louder; ceiling rises (and clamps at 0).
+        l.set_program_loudness_lufs(-2.0);
+        let dyn_ceiling = l.effective_soft_ceiling_dbtp().unwrap();
+        assert!(
+            (-0.1..=0.0).contains(&dyn_ceiling),
+            "expected clamp near 0 dBTP, got {dyn_ceiling}"
+        );
+
+        // Clear it; falls back to static.
+        l.clear_program_loudness();
+        let fallback = l.effective_soft_ceiling_dbtp().unwrap();
+        assert!(
+            (fallback - (-6.0)).abs() < 1e-3,
+            "expected static -6 dBTP, got {fallback}"
+        );
+    }
+
+    #[test]
+    fn silence_fast_path_preserves_program_loudness() {
+        let sr = 48_000.0;
+        let mut l = Limiter::new(LimiterConfig::default(), sr);
+        l.set_program_loudness_lufs(-18.0);
+        let before = l.effective_soft_ceiling_dbtp().unwrap();
+
+        for _ in 0..10_000 {
+            let (lo, ro) = l.process_frame(0.0, 0.0);
+            assert_eq!(lo, 0.0);
+            assert_eq!(ro, 0.0);
+        }
+
+        assert_eq!(l.effective_soft_ceiling_dbtp().unwrap(), before);
+        assert_eq!(l.gain_reduction_db(), 0.0);
+        assert_eq!(l.true_peak_dbtp(), -200.0);
+    }
+
+    #[test]
+    fn silence_fast_path_does_not_truncate_lookahead_tail() {
+        let sr = 48_000.0;
+        let mut l = Limiter::new(LimiterConfig::brickwall_only(), sr);
+        for _ in 0..16 {
+            let _ = l.process_frame(0.5, 0.5);
+        }
+
+        let mut delayed_peak = 0.0_f32;
+        for n in 0..200 {
+            let (lo, ro) = l.process_frame(0.0, 0.0);
+            if n > 8 {
+                delayed_peak = delayed_peak.max(lo.abs()).max(ro.abs());
+            }
+        }
+
+        assert!(
+            delayed_peak > 1.0e-6,
+            "lookahead tail was truncated before it could drain: delayed_peak={delayed_peak}"
+        );
+    }
+
+    #[test]
+    fn dynamic_ceiling_bounds_psr_on_hot_transient() {
+        let sr = 48_000.0;
+        // Long lookahead and fast soft attack so the soft tier
+        // demonstrably catches the transient before the hard tier
+        // needs to.
+        let cfg = LimiterConfig {
+            lookahead_ms: 5.0,
+            soft: Some(SoftTierConfig {
+                max_psr_db: 14.0,
+                static_ceiling_dbtp: -6.0,
+                attack_ms: 1.0,
+                release_ms: 100.0,
+            }),
+            ..LimiterConfig::default()
+        };
+        let mut l = Limiter::new(cfg, sr);
+        l.set_program_loudness_lufs(-18.0);
+        // Expected dynamic ceiling: -18 + 14 = -4 dBTP ≈ 0.631 lin.
+        let dyn_ceil_lin = db_to_lin(-4.0);
+
+        // Slam a +6 dBFS impulse.
+        let mut max_after = 0.0_f32;
+        for n in 0..4_800_usize {
+            let s = if n == 800 { db_to_lin(6.0) } else { 0.0 };
+            let (lo, _) = l.process_frame(s, s);
+            if n > 700 {
+                max_after = max_after.max(lo.abs());
+            }
+        }
+        // Output should be at or below the dynamic soft ceiling with
+        // a small ringing margin. Critically, the hard tier should
+        // *not* be the thing that catches it — its GR should be small.
+        assert!(
+            max_after <= dyn_ceil_lin * 1.15,
+            "soft tier didn't bound the transient: max={max_after}, dyn_ceil={dyn_ceil_lin}"
+        );
+        // The hard tier may snap briefly at peak entry (soft envelope
+        // hasn't ramped yet), then take its release time to recover.
+        // We don't require zero hard engagement here — only that it
+        // isn't doing the majority of the work.
+        assert!(
+            l.hard_gain_reduction_db().abs() < 4.0,
+            "hard tier engaged unreasonably: {}",
+            l.hard_gain_reduction_db()
+        );
+    }
+
+    // ----------------------------------------------------------------
+    // Misc
+    // ----------------------------------------------------------------
+
+    #[test]
+    fn nan_inputs_do_not_propagate_with_soft_tier() {
+        let sr = 48_000.0;
+        let mut l = Limiter::new(LimiterConfig::default(), sr);
+        for _ in 0..1_000 {
+            let (lo, ro) = l.process_frame(f32::NAN, f32::INFINITY);
+            assert!(lo.is_finite() && ro.is_finite());
+        }
+    }
+
+    #[test]
+    fn ceiling_clamps_positive_config_to_zero() {
+        let cfg = LimiterConfig {
+            ceiling_dbtp: 3.0,
+            ..LimiterConfig::default()
+        }
+        .sanitized();
+        assert_eq!(cfg.ceiling_dbtp, 0.0);
+    }
+
+    #[test]
+    fn set_program_loudness_ignores_non_finite() {
+        let sr = 48_000.0;
+        let mut l = Limiter::new(LimiterConfig::default(), sr);
+        // Establish a baseline.
+        l.set_program_loudness_lufs(-20.0);
+        let baseline = l.effective_soft_ceiling_dbtp().unwrap();
+        // NaN / Inf should be ignored.
+        l.set_program_loudness_lufs(f32::NAN);
+        assert_eq!(l.effective_soft_ceiling_dbtp().unwrap(), baseline);
+        l.set_program_loudness_lufs(f32::INFINITY);
+        assert_eq!(l.effective_soft_ceiling_dbtp().unwrap(), baseline);
+    }
+
+    #[test]
+    fn soft_tier_reduces_perceived_peak_to_loudness_ratio() {
+        // The whole point of the soft tier: a transient on top of a
+        // quieter program should NOT come out near the hard ceiling.
+        let sr = 48_000.0;
+        let cfg = LimiterConfig {
+            lookahead_ms: 5.0,
+            soft: Some(SoftTierConfig {
+                max_psr_db: 12.0,
+                static_ceiling_dbtp: -8.0,
+                attack_ms: 1.0,
+                release_ms: 100.0,
+            }),
+            ..LimiterConfig::default()
+        };
+        let mut brickwall = Limiter::new(LimiterConfig::brickwall_only(), sr);
+        let mut two_tier = Limiter::new(cfg, sr);
+        two_tier.set_program_loudness_lufs(-20.0);
+
+        let mut bw_peak = 0.0_f32;
+        let mut tt_peak = 0.0_f32;
+        for n in 0..4_800_usize {
+            // Quiet program with a single big spike.
+            let s = if n == 1_200 { db_to_lin(3.0) } else { 0.01 };
+            let (lo_bw, _) = brickwall.process_frame(s, s);
+            let (lo_tt, _) = two_tier.process_frame(s, s);
+            if n > 1_000 {
+                bw_peak = bw_peak.max(lo_bw.abs());
+                tt_peak = tt_peak.max(lo_tt.abs());
+            }
+        }
+        // Brickwall lets the spike through near the hard ceiling.
+        // Two-tier holds it much lower.
+        assert!(
+            tt_peak < bw_peak * 0.6,
+            "soft tier did not meaningfully reduce peak: bw={bw_peak}, tt={tt_peak}"
+        );
+    }
+}

Added file: crates/headroom-dsp/src/oversample.rs+208 additions@@ -0,0 +1,208 @@
+//! polyphase fir up/downsamplers for the limiter's oversampled isp detection (itu-r bs.1770-4).
+
+use std::f32::consts::PI;
+
+/// blackman-windowed sinc lowpass fir, normalized for unity dc gain.
+/// odd `taps` → linear phase, group delay `(taps - 1) / 2`. `fc` normalized in `0.0..0.5`.
+/// use `fc = 0.5 / M` as the prototype for M-times oversampling.
+#[must_use]
+pub fn design_lowpass_blackman(taps: usize, fc: f32) -> Vec<f32> {
+    let taps = taps.max(1);
+    let m = (taps as f32 - 1.0).max(1.0);
+    let mut h = vec![0.0_f32; taps];
+    let mut sum = 0.0_f32;
+    for (n, h_n) in h.iter_mut().enumerate() {
+        let x = n as f32 - m / 2.0;
+        let sinc = if x.abs() < 1e-9 {
+            2.0 * fc
+        } else {
+            (2.0 * PI * fc * x).sin() / (PI * x)
+        };
+        let w = 0.42 - 0.5 * (2.0 * PI * n as f32 / m).cos() + 0.08 * (4.0 * PI * n as f32 / m).cos();
+        *h_n = sinc * w;
+        sum += *h_n;
+    }
+    if sum.abs() > 1e-12 {
+        for v in &mut h {
+            *v /= sum;
+        }
+    }
+    h
+}
+
+/// one input sample → `factor` output samples. coeffs pre-scaled by `factor` for unity dc gain.
+pub struct PolyphaseUpsampler {
+    factor: usize,
+    taps_per_phase: usize,
+    /// `phases[j * taps_per_phase + p] = h[p * factor + j] * factor`.
+    phases: Vec<f32>,
+    history: Vec<f32>,
+    write_idx: usize,
+}
+
+impl PolyphaseUpsampler {
+    #[must_use]
+    pub fn new(factor: usize, fir_taps: &[f32]) -> Self {
+        let factor = factor.max(1);
+        let taps_per_phase = fir_taps.len().div_ceil(factor);
+        let mut phases = vec![0.0_f32; factor * taps_per_phase];
+        for (n, &h) in fir_taps.iter().enumerate() {
+            let j = n % factor;
+            let p = n / factor;
+            phases[j * taps_per_phase + p] = h * factor as f32;
+        }
+        Self {
+            factor,
+            taps_per_phase,
+            phases,
+            history: vec![0.0_f32; taps_per_phase.max(1)],
+            write_idx: 0,
+        }
+    }
+
+    #[must_use]
+    pub fn factor(&self) -> usize {
+        self.factor
+    }
+
+    /// emit `factor` samples into `out[..factor]`; `out.len() >= factor`.
+    pub fn process(&mut self, x: f32, out: &mut [f32]) {
+        debug_assert!(out.len() >= self.factor);
+        let len = self.history.len();
+        self.history[self.write_idx] = x;
+        let just_written = self.write_idx;
+        self.write_idx = (self.write_idx + 1) % len;
+
+        for (j, slot) in out.iter_mut().take(self.factor).enumerate() {
+            let phase = &self.phases[j * self.taps_per_phase..(j + 1) * self.taps_per_phase];
+            let mut acc = 0.0_f32;
+            for (p, &h) in phase.iter().enumerate() {
+                let idx = (just_written + len - p) % len;
+                acc += h * self.history[idx];
+            }
+            *slot = acc;
+        }
+    }
+
+    pub fn reset(&mut self) {
+        for v in &mut self.history {
+            *v = 0.0;
+        }
+        self.write_idx = 0;
+    }
+}
+
+/// `factor` input samples → one output. same prototype lowpass as the upsampler.
+/// no polyphase split — savings are modest at our tap count, clarity wins.
+pub struct PolyphaseDownsampler {
+    factor: usize,
+    taps: Vec<f32>,
+    history: Vec<f32>,
+    write_idx: usize,
+}
+
+impl PolyphaseDownsampler {
+    #[must_use]
+    pub fn new(factor: usize, fir_taps: &[f32]) -> Self {
+        let factor = factor.max(1);
+        Self {
+            factor,
+            taps: fir_taps.to_vec(),
+            history: vec![0.0_f32; fir_taps.len().max(1)],
+            write_idx: 0,
+        }
+    }
+
+    #[must_use]
+    pub fn factor(&self) -> usize {
+        self.factor
+    }
+
+    /// push `factor` samples, return one filtered output.
+    pub fn process(&mut self, ins: &[f32]) -> f32 {
+        debug_assert_eq!(ins.len(), self.factor);
+        let len = self.history.len();
+        for &x in ins {
+            self.history[self.write_idx] = x;
+            self.write_idx = (self.write_idx + 1) % len;
+        }
+        let mut acc = 0.0_f32;
+        for (k, &h) in self.taps.iter().enumerate() {
+            let idx = (self.write_idx + len - 1 - k) % len;
+            acc += h * self.history[idx];
+        }
+        acc
+    }
+
+    pub fn reset(&mut self) {
+        for v in &mut self.history {
+            *v = 0.0;
+        }
+        self.write_idx = 0;
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn fir(taps: usize, factor: usize) -> Vec<f32> {
+        design_lowpass_blackman(taps, 0.45 / factor as f32)
+    }
+
+    #[test]
+    fn upsampler_dc_gain_preserved() {
+        let h = fir(31, 4);
+        let mut up = PolyphaseUpsampler::new(4, &h);
+        // Drive DC and let the filter settle, then check unity gain.
+        let mut buf = [0.0_f32; 8];
+        let mut last_avg = 0.0;
+        for _ in 0..200 {
+            up.process(1.0, &mut buf);
+            last_avg = buf[..4].iter().sum::<f32>() / 4.0;
+        }
+        assert!((last_avg - 1.0).abs() < 1e-3, "got {last_avg}");
+    }
+
+    #[test]
+    fn down_then_up_roundtrip_is_bounded() {
+        // Stuff zero-padded input through up then down; output amplitude
+        // should approximately equal input on smooth signals.
+        let h = fir(31, 4);
+        let mut up = PolyphaseUpsampler::new(4, &h);
+        let mut down = PolyphaseDownsampler::new(4, &h);
+        let mut max_err = 0.0_f32;
+        let mut up_buf = [0.0_f32; 8];
+        // Drive a slow sine well below Nyquist.
+        for n in 0..2_000 {
+            let t = n as f32 / 48_000.0;
+            let x = (2.0 * std::f32::consts::PI * 1_000.0 * t).sin() * 0.5;
+            up.process(x, &mut up_buf);
+            let y = down.process(&up_buf[..4]);
+            // After group-delay warm-up, the error should be small.
+            if n > 80 {
+                max_err = max_err.max((x - y).abs());
+            }
+        }
+        // The filter is symmetric, so up/down with the same kernel
+        // introduces ~6 dB attenuation by design (each pass contributes
+        // half the gain). What we care about here is finite, bounded
+        // output and no runaway.
+        assert!(max_err < 1.0, "max_err {max_err}");
+    }
+
+    #[test]
+    fn upsampler_handles_impulse() {
+        let h = fir(15, 4);
+        let mut up = PolyphaseUpsampler::new(4, &h);
+        let mut buf = [0.0_f32; 8];
+        up.process(1.0, &mut buf);
+        // Some non-zero output expected on first impulse already.
+        assert!(buf[..4].iter().any(|&v| v.abs() > 1e-6));
+        // Drive zeros; output decays to zero.
+        for _ in 0..200 {
+            up.process(0.0, &mut buf);
+        }
+        assert!(buf[..4].iter().all(|&v| v.abs() < 1e-6));
+    }
+}

Added file: crates/headroom-dsp/src/sliding_max.rs+98 additions@@ -0,0 +1,98 @@
+//! amortized-O(1) sliding-window max via monotonic-decreasing deque; bounded capacity, no realloc.
+
+use std::collections::VecDeque;
+
+pub struct SlidingMaxBuffer {
+    window: usize,
+    counter: u64,
+    /// `(index, value)`, monotonically decreasing in value from front.
+    deque: VecDeque<(u64, f32)>,
+}
+
+impl SlidingMaxBuffer {
+    /// 0 clamps to 1.
+    #[must_use]
+    pub fn new(window: usize) -> Self {
+        let window = window.max(1);
+        Self {
+            window,
+            counter: 0,
+            deque: VecDeque::with_capacity(window),
+        }
+    }
+
+    #[must_use]
+    pub fn window(&self) -> usize {
+        self.window
+    }
+
+    /// max over the most recent `window` samples, inclusive of `value`.
+    pub fn push_and_max(&mut self, value: f32) -> f32 {
+        // drop entries aged out of the window.
+        let cutoff = self.counter.saturating_sub(self.window as u64 - 1);
+        while let Some(&(idx, _)) = self.deque.front() {
+            if idx < cutoff {
+                self.deque.pop_front();
+            } else {
+                break;
+            }
+        }
+        // drop back entries <= value: they can never become the max.
+        while let Some(&(_, v)) = self.deque.back() {
+            if v <= value {
+                self.deque.pop_back();
+            } else {
+                break;
+            }
+        }
+        self.deque.push_back((self.counter, value));
+        self.counter += 1;
+        // deque is non-empty (we just pushed).
+        self.deque.front().map_or(0.0, |&(_, v)| v)
+    }
+
+    pub fn reset(&mut self) {
+        self.counter = 0;
+        self.deque.clear();
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn tracks_window_max() {
+        let mut s = SlidingMaxBuffer::new(3);
+        assert_eq!(s.push_and_max(1.0), 1.0);
+        assert_eq!(s.push_and_max(3.0), 3.0);
+        assert_eq!(s.push_and_max(2.0), 3.0);
+        assert_eq!(s.push_and_max(2.0), 3.0); // 3.0 aged out... actually still in (window=3, last 3 are [3,2,2])
+        assert_eq!(s.push_and_max(0.5), 2.0); // window is now [2,2,0.5]
+        assert_eq!(s.push_and_max(0.5), 2.0); // [2,0.5,0.5]
+        assert_eq!(s.push_and_max(0.5), 0.5); // [0.5,0.5,0.5]
+    }
+
+    #[test]
+    fn monotonically_decreasing_input() {
+        let mut s = SlidingMaxBuffer::new(4);
+        for (i, &v) in [5.0_f32, 4.0, 3.0, 2.0, 1.0, 0.5].iter().enumerate() {
+            let m = s.push_and_max(v);
+            // After window is filled, max is the value `window-1` back.
+            let expected = match i {
+                0..=3 => 5.0,
+                4 => 4.0,
+                _ => 3.0,
+            };
+            assert_eq!(m, expected);
+        }
+    }
+
+    #[test]
+    fn window_one_is_identity() {
+        let mut s = SlidingMaxBuffer::new(1);
+        for v in [1.0, 2.0, 0.5, 9.0_f32, -3.0] {
+            assert_eq!(s.push_and_max(v), v);
+        }
+    }
+}

Added file: crates/headroom-dsp/src/util.rs+54 additions@@ -0,0 +1,54 @@
+//! db <-> linear conversions, time constants.
+
+/// lower bound to avoid `log10(0)`.
+pub const PEAK_FLOOR: f32 = 1e-20;
+
+/// inputs at or below [`PEAK_FLOOR`] clamp to `-200 dB`.
+#[must_use]
+pub fn lin_to_db(x: f32) -> f32 {
+    if x <= PEAK_FLOOR {
+        -200.0
+    } else {
+        20.0 * x.log10()
+    }
+}
+
+#[must_use]
+pub fn db_to_lin(db: f32) -> f32 {
+    10.0_f32.powf(db / 20.0)
+}
+
+/// one-pole smoother coefficient for `y[n] = y[n-1] + alpha * (x[n] - y[n-1])`.
+/// alpha = `1 - exp(-1 / (tau * fs))`, tau = `time_ms / 1000`. time_ms <= 0 → 1.0 (instant).
+#[must_use]
+pub fn time_to_alpha(time_ms: f32, sample_rate: f32) -> f32 {
+    if time_ms <= 0.0 || sample_rate <= 0.0 {
+        1.0
+    } else {
+        let tau_samples = (time_ms * 1e-3) * sample_rate;
+        1.0 - (-1.0 / tau_samples).exp()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn db_round_trips() {
+        for db in [-60.0, -20.0, -6.0, -0.1, 0.0, 3.0, 6.0_f32] {
+            let lin = db_to_lin(db);
+            let back = lin_to_db(lin);
+            assert!((back - db).abs() < 1e-3, "db={db} back={back}");
+        }
+    }
+
+    #[test]
+    fn time_to_alpha_endpoints() {
+        assert_eq!(time_to_alpha(0.0, 48_000.0), 1.0);
+        assert!(time_to_alpha(1000.0, 48_000.0) < 0.01);
+        // Very fast attack: alpha approaches 1.
+        let a_fast = time_to_alpha(0.01, 48_000.0);
+        assert!(a_fast > 0.05, "fast alpha was {a_fast}");
+    }
+}

headroom

Commit 614b4e43f9f3

Commit `614b4e43f9f3`