GitCorner

Code

ossartcraftfilmcraft🌐
f67d38b35cc5
//! Dynamics: compressor, expander/gate, look-ahead true-peak limiter.
//!
//! Detection is stereo-linked (the loudest channel drives one common gain) so the image does
//! not shift. Gain computers work in dB; attack/release are one-pole smoothers on the gain.

use super::util::{coef, lin_db};
use crate::oversample::{Interpolator, PolyphaseBank, true_peak_factor};
use crate::{AudioEffect, ParamSpec, ParamValues, Smoothed, Unit, block_len, db_to_gain, param_plumbing};
use std::collections::VecDeque;

/// Static compressor curve with a quadratic soft knee (output level in dB for input level `x`).
pub fn compressor_curve(x: f32, threshold: f32, ratio: f32, knee: f32) -> f32 {
    let d = x - threshold;
    if knee > 0.0 && 2.0 * d.abs() <= knee {
        x + (1.0 / ratio - 1.0) * (d + knee / 2.0).powi(2) / (2.0 * knee)
    } else if d > 0.0 {
        threshold + d / ratio
    } else {
        x
    }
}

/// Static downward-expander curve (output level in dB), attenuation limited to `range` dB.
pub fn expander_curve(x: f32, threshold: f32, ratio: f32, range: f32) -> f32 {
    if x >= threshold { x } else { x + ((x - threshold) * (ratio - 1.0)).max(-range) }
}

// ---------------------------------------------------------------------------------------------

/// Feed-forward compressor (peak or RMS detector, soft knee, attack/release, make-up gain).
pub struct Compressor {
    pv: ParamValues,
    sr: f32,
    threshold: f32,
    ratio: f32,
    knee: f32,
    rms: bool,
    att: f32,
    rel: f32,
    rms_coef: f32,
    makeup: Smoothed,
    /// Detector mean square (RMS mode).
    ms: f32,
    /// Smoothed gain reduction (dB, ≤ 0).
    env: f32,
    gr_meter: f32,
}

impl Compressor {
    pub const PARAMS: &'static [ParamSpec] = &[
        ParamSpec::new("threshold", "Threshold", -60.0, 0.0, -20.0, Unit::Decibels),
        ParamSpec::new("ratio", "Ratio", 1.0, 30.0, 4.0, Unit::Ratio),
        ParamSpec::new("knee", "Knee", 0.0, 24.0, 6.0, Unit::Decibels),
        ParamSpec::log("attack", "Attack", 0.01, 300.0, 10.0, Unit::Milliseconds),
        ParamSpec::log("release", "Release", 1.0, 3000.0, 100.0, Unit::Milliseconds),
        ParamSpec::new("makeup", "Make-up Gain", -40.0, 40.0, 0.0, Unit::Decibels),
        ParamSpec::choice("detector", "Detector", &["Peak", "RMS"], 0),
    ];

    pub fn new(sample_rate: f32, _channels: usize) -> Self {
        let mut s = Compressor {
            pv: ParamValues::new(Self::PARAMS),
            sr: sample_rate,
            threshold: 0.0,
            ratio: 1.0,
            knee: 0.0,
            rms: false,
            att: 0.0,
            rel: 0.0,
            rms_coef: coef(10.0, sample_rate),
            makeup: Smoothed::with_ms(1.0, sample_rate, 20.0),
            ms: 0.0,
            env: 0.0,
            gr_meter: 0.0,
        };
        s.apply_params(true);
        s
    }

    fn apply_params(&mut self, snap: bool) {
        self.threshold = self.pv.v("threshold");
        self.ratio = self.pv.v("ratio");
        self.knee = self.pv.v("knee");
        self.att = coef(self.pv.v("attack"), self.sr);
        self.rel = coef(self.pv.v("release"), self.sr);
        self.rms = self.pv.idx("detector") == 1;
        self.makeup.set(db_to_gain(self.pv.v("makeup")));
        if snap {
            self.makeup.snap();
        }
    }

    /// Static curve at the current settings.
    pub fn curve(&self, x_db: f32) -> f32 {
        compressor_curve(x_db, self.threshold, self.ratio, self.knee)
    }

    /// Current gain reduction in dB (≤ 0), for metering.
    pub fn gain_reduction_db(&self) -> f32 {
        self.gr_meter
    }
}

impl AudioEffect for Compressor {
    param_plumbing!("compressor");
    fn transfer_db(&self, band: usize, input_db: f32) -> Option<f32> {
        (band == 0).then(|| self.curve(input_db) + self.pv.v("makeup"))
    }
    fn reset(&mut self) {
        self.makeup.snap();
        self.ms = 0.0;
        self.env = 0.0;
        self.gr_meter = 0.0;
    }
    fn process(&mut self, channels: &mut [&mut [f32]]) {
        let n = block_len(channels);
        for i in 0..n {
            let mut peak = 0.0f32;
            let mut sq = 0.0f32;
            for ch in channels.iter() {
                let x = ch[i];
                peak = peak.max(x.abs());
                sq = sq.max(x * x);
            }
            let level_db = if self.rms {
                self.ms = self.rms_coef * self.ms + (1.0 - self.rms_coef) * sq;
                if !(1e-30..=f32::MAX).contains(&self.ms) {
                    self.ms = 0.0;
                }
                10.0 * self.ms.max(1e-20).log10()
            } else {
                lin_db(peak)
            };
            let target = self.curve(level_db) - level_db;
            let c = if target < self.env { self.att } else { self.rel };
            self.env = c * self.env + (1.0 - c) * target;
            if !(1e-9..=f32::MAX).contains(&self.env.abs()) {
                self.env = 0.0;
            }
            let g = db_to_gain(self.env) * self.makeup.tick();
            for ch in channels.iter_mut() {
                ch[i] *= g;
            }
        }
        self.gr_meter = self.env;
    }
}

// ---------------------------------------------------------------------------------------------

/// Downward expander / noise gate with hold (ratio ≥ 10 behaves as a gate).
pub struct Gate {
    pv: ParamValues,
    sr: f32,
    threshold: f32,
    ratio: f32,
    range: f32,
    att: f32,
    rel: f32,
    hold: u32,
    hold_left: u32,
    env: f32,
}

impl Gate {
    pub const PARAMS: &'static [ParamSpec] = &[
        ParamSpec::new("threshold", "Threshold", -90.0, 0.0, -40.0, Unit::Decibels),
        ParamSpec::log("ratio", "Ratio", 1.0, 100.0, 10.0, Unit::Ratio),
        ParamSpec::new("range", "Range", 0.0, 90.0, 60.0, Unit::Decibels),
        ParamSpec::log("attack", "Attack", 0.01, 100.0, 1.0, Unit::Milliseconds),
        ParamSpec::new("hold", "Hold", 0.0, 2000.0, 50.0, Unit::Milliseconds),
        ParamSpec::log("release", "Release", 1.0, 3000.0, 150.0, Unit::Milliseconds),
    ];

    pub fn new(sample_rate: f32, _channels: usize) -> Self {
        let mut s = Gate {
            pv: ParamValues::new(Self::PARAMS),
            sr: sample_rate,
            threshold: 0.0,
            ratio: 1.0,
            range: 0.0,
            att: 0.0,
            rel: 0.0,
            hold: 0,
            hold_left: 0,
            env: 0.0,
        };
        s.apply_params(true);
        s
    }

    fn apply_params(&mut self, _snap: bool) {
        self.threshold = self.pv.v("threshold");
        self.ratio = self.pv.v("ratio");
        self.range = self.pv.v("range");
        self.att = coef(self.pv.v("attack"), self.sr);
        self.rel = coef(self.pv.v("release"), self.sr);
        self.hold = (self.pv.v("hold") * 0.001 * self.sr) as u32;
    }

    pub fn curve(&self, x_db: f32) -> f32 {
        expander_curve(x_db, self.threshold, self.ratio, self.range)
    }
}

impl AudioEffect for Gate {
    param_plumbing!("gate");
    fn transfer_db(&self, band: usize, input_db: f32) -> Option<f32> {
        (band == 0).then(|| self.curve(input_db))
    }
    fn reset(&mut self) {
        self.env = 0.0;
        self.hold_left = 0;
    }
    fn process(&mut self, channels: &mut [&mut [f32]]) {
        let n = block_len(channels);
        for i in 0..n {
            let peak = channels.iter().fold(0.0f32, |a, c| a.max(c[i].abs()));
            let level = lin_db(peak);
            let target = self.curve(level) - level;
            if target >= self.env {
                // Opening (or staying open): attack.
                self.env = self.att * self.env + (1.0 - self.att) * target;
                if target >= 0.0 {
                    self.hold_left = self.hold;
                }
            } else if self.hold_left > 0 {
                self.hold_left -= 1;
            } else {
                self.env = self.rel * self.env + (1.0 - self.rel) * target;
                if !self.env.is_finite() {
                    self.env = 0.0;
                }
            }
            let g = db_to_gain(self.env);
            for ch in channels.iter_mut() {
                ch[i] *= g;
            }
        }
    }
}

// ---------------------------------------------------------------------------------------------

/// Look-ahead brick-wall limiter.
///
/// The required gain for each (optionally true-peak) detected sample is held for the look-ahead
/// window with a sliding minimum, released with a one-pole, and then smoothed with a moving
/// average exactly as long as the look-ahead, so the gain has reached its target when the peak
/// leaves the delay line. A final clip at the ceiling guarantees the sample peak never exceeds it.
pub struct Limiter {
    pv: ParamValues,
    sr: f32,
    in_gain: Smoothed,
    ceiling: f32,
    rel: f32,
    true_peak: bool,
    /// Look-ahead (samples) and detector alignment delay.
    look: usize,
    det_delay: usize,
    bank: PolyphaseBank,
    interp: Vec<Interpolator>,
    /// Per-channel delay line (ring), length `look + det_delay + 1`.
    delay: Vec<Vec<f32>>,
    wpos: usize,
    /// Monotonic deque for the sliding minimum: (sample index, gain).
    minq: VecDeque<(u64, f32)>,
    /// Box filter ring and running sum.
    box_ring: Vec<f32>,
    box_pos: usize,
    box_sum: f64,
    rel_state: f32,
    t: u64,
    gr_meter: f32,
}

impl Limiter {
    pub const PARAMS: &'static [ParamSpec] = &[
        ParamSpec::new("input_gain", "Input Boost", 0.0, 24.0, 0.0, Unit::Decibels),
        ParamSpec::new("ceiling", "Ceiling", -24.0, 0.0, -1.0, Unit::Decibels),
        ParamSpec::log("release", "Release", 1.0, 1000.0, 60.0, Unit::Milliseconds),
        ParamSpec::toggle("true_peak", "True Peak", true),
    ];
    /// Fixed look-ahead time.
    pub const LOOKAHEAD_MS: f32 = 5.0;

    pub fn new(sample_rate: f32, channels: usize) -> Self {
        let channels = channels.max(1);
        let bank = PolyphaseBank::new(true_peak_factor(sample_rate as f64).max(2));
        let look = ((Self::LOOKAHEAD_MS * 0.001 * sample_rate).round() as usize).max(1);
        let det_delay = bank.delay();
        let dlen = look + det_delay + 1;
        let mut s = Limiter {
            pv: ParamValues::new(Self::PARAMS),
            sr: sample_rate,
            in_gain: Smoothed::with_ms(1.0, sample_rate, 20.0),
            ceiling: 1.0,
            rel: 0.0,
            true_peak: true,
            look,
            det_delay,
            bank,
            interp: vec![Interpolator::default(); channels],
            delay: vec![vec![0.0; dlen]; channels],
            wpos: 0,
            minq: VecDeque::with_capacity(look + 2),
            box_ring: vec![1.0; look + 1],
            box_pos: 0,
            box_sum: (look + 1) as f64,
            rel_state: 1.0,
            t: 0,
            gr_meter: 0.0,
        };
        s.apply_params(true);
        s
    }

    fn apply_params(&mut self, snap: bool) {
        self.in_gain.set(db_to_gain(self.pv.v("input_gain")));
        self.ceiling = db_to_gain(self.pv.v("ceiling"));
        self.rel = coef(self.pv.v("release"), self.sr);
        self.true_peak = self.pv.on("true_peak");
        if snap {
            self.in_gain.snap();
        }
    }

    /// Current gain reduction in dB (≤ 0).
    pub fn gain_reduction_db(&self) -> f32 {
        self.gr_meter
    }
}

impl AudioEffect for Limiter {
    param_plumbing!("limiter");
    fn latency(&self) -> usize {
        self.look + self.det_delay
    }
    fn reset(&mut self) {
        self.in_gain.snap();
        self.interp.iter_mut().for_each(Interpolator::reset);
        self.delay.iter_mut().for_each(|d| d.iter_mut().for_each(|v| *v = 0.0));
        self.wpos = 0;
        self.minq.clear();
        self.box_ring.iter_mut().for_each(|v| *v = 1.0);
        self.box_pos = 0;
        self.box_sum = self.box_ring.len() as f64;
        self.rel_state = 1.0;
        self.t = 0;
        self.gr_meter = 0.0;
    }
    fn process(&mut self, channels: &mut [&mut [f32]]) {
        let n = block_len(channels);
        let nch = channels.len().min(self.delay.len());
        let dlen = self.delay[0].len();
        let window = (self.look + 1) as u64;
        let mut last_g = None;
        for i in 0..n {
            let g_in = self.in_gain.tick();
            let det_pos = (self.wpos + dlen - self.det_delay) % dlen;
            let out_pos = (self.wpos + 1) % dlen; // oldest = look + det_delay samples ago
            let mut det = 0.0f32;
            for ch in 0..nch {
                let x = channels[ch][i] * g_in;
                self.delay[ch][self.wpos] = x;
                let aligned = self.delay[ch][det_pos].abs();
                let tp = if self.true_peak { self.interp[ch].push_peak(&self.bank, x) } else { 0.0 };
                det = det.max(aligned.max(tp));
            }
            let greq = if det > self.ceiling { self.ceiling / det } else { 1.0 };
            // Sliding minimum over the last `window` values.
            while let Some(&(_, v)) = self.minq.back() {
                if v >= greq {
                    self.minq.pop_back();
                } else {
                    break;
                }
            }
            self.minq.push_back((self.t, greq));
            while let Some(&(idx, _)) = self.minq.front() {
                if idx + window <= self.t {
                    self.minq.pop_front();
                } else {
                    break;
                }
            }
            let m = self.minq.front().map_or(1.0, |&(_, v)| v);
            // Release.
            self.rel_state = if m < self.rel_state { m } else { self.rel_state + (m - self.rel_state) * (1.0 - self.rel) };
            // Moving average over look+1 samples.
            self.box_sum += self.rel_state as f64 - self.box_ring[self.box_pos] as f64;
            self.box_ring[self.box_pos] = self.rel_state;
            self.box_pos = (self.box_pos + 1) % self.box_ring.len();
            let g = (self.box_sum / self.box_ring.len() as f64) as f32;
            for ch in 0..nch {
                let y = self.delay[ch][out_pos] * g;
                channels[ch][i] = y.clamp(-self.ceiling, self.ceiling);
            }
            self.wpos = (self.wpos + 1) % dlen;
            self.t += 1;
            // Periodically re-sum to cancel floating-point drift.
            if self.t.is_multiple_of(65536) {
                self.box_sum = self.box_ring.iter().map(|&v| v as f64).sum();
            }
            last_g = Some(g);
        }
        if let Some(g) = last_g {
            self.gr_meter = lin_db(g);
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::loudness::LoudnessMeter;
    use crate::testutil::*;

    const SR: f32 = 48000.0;

    #[test]
    fn compressor_static_curve() {
        let c = |x| compressor_curve(x, -20.0, 4.0, 0.0);
        assert_eq!(c(-30.0), -30.0);
        assert_eq!(c(-20.0), -20.0);
        assert_eq!(c(0.0), -15.0);
        // Soft knee: continuous at both knee edges, midpoint below the hard curve.
        let k = |x| compressor_curve(x, -20.0, 4.0, 10.0);
        assert!((k(-25.0) + 25.0).abs() < 1e-5);
        assert!((k(-15.0) - c(-15.0)).abs() < 1e-5);
        assert!(k(-20.0) < -20.0);
        assert!((k(-20.0) - (-20.0 + (0.25 - 1.0) * 25.0 / 20.0)).abs() < 1e-5);
        // Monotonic.
        let mut prev = f32::MIN;
        for i in 0..800 {
            let y = k(-80.0 + i as f32 * 0.1);
            assert!(y >= prev);
            prev = y;
        }
    }

    #[test]
    fn compressor_steady_state_matches_curve() {
        for detector in [0.0, 1.0] {
            let mut c = Compressor::new(SR, 2);
            c.set_param("threshold", -20.0);
            c.set_param("ratio", 4.0);
            c.set_param("knee", 0.0);
            c.set_param("makeup", 3.0);
            c.set_param("detector", detector);
            // Constant (DC) level: peak and RMS detectors agree.
            for level_db in [-40.0f32, -10.0, -2.0] {
                c.reset();
                let v = db_to_gain(level_db);
                let mut l = vec![v; 48000];
                let mut r = vec![-v; 48000];
                c.process(&mut [&mut l, &mut r]);
                let out_db = lin_db(l[47999]);
                let expect = compressor_curve(level_db, -20.0, 4.0, 0.0) + 3.0;
                assert!((out_db - expect).abs() < 0.05, "det {detector} in {level_db}: {out_db} vs {expect}");
                assert_eq!(l[47999], -r[47999]);
            }
        }
    }

    #[test]
    fn compressor_attack_time() {
        let mut c = Compressor::new(SR, 1);
        c.set_param("threshold", -20.0);
        c.set_param("ratio", 20.0);
        c.set_param("knee", 0.0);
        c.set_param("attack", 10.0);
        let mut x = vec![1.0f32; 4800];
        c.process(&mut [&mut x]);
        // After one time constant ~63% of the final reduction (in dB) is applied.
        let final_db = compressor_curve(0.0, -20.0, 20.0, 0.0);
        let at_tau = lin_db(x[480]);
        assert!((at_tau / final_db - 0.632).abs() < 0.02, "{at_tau} / {final_db}");
    }

    #[test]
    fn gate_attenuates_below_threshold_and_holds() {
        let mut g = Gate::new(SR, 1);
        g.set_param("threshold", -30.0);
        g.set_param("ratio", 100.0);
        g.set_param("range", 40.0);
        g.set_param("hold", 100.0);
        g.set_param("release", 10.0);
        let loud = db_to_gain(-10.0);
        let quiet = db_to_gain(-50.0);
        let mut x: Vec<f32> = (0..48000).map(|i| if i < 24000 { loud } else { quiet }).collect();
        g.process(&mut [&mut x]);
        assert!((lin_db(x[23999]) + 10.0).abs() < 0.01);
        // During hold (100 ms) the gate stays open.
        assert!((lin_db(x[24000 + 2400]) + 50.0).abs() < 0.01);
        // Well after hold + release: attenuated by the full range.
        assert!((lin_db(x[47999]) + 90.0).abs() < 0.1, "{}", lin_db(x[47999]));
        assert!((expander_curve(-40.0, -30.0, 2.0, 60.0) + 50.0).abs() < 1e-6);
    }

    #[test]
    fn limiter_never_exceeds_ceiling() {
        let mut rng = Rng::new(7);
        for tp in [0.0, 1.0] {
            let mut lim = Limiter::new(SR, 2);
            lim.set_param("ceiling", -1.0);
            lim.set_param("input_gain", 12.0);
            lim.set_param("true_peak", tp);
            let ceiling = db_to_gain(-1.0);
            let mut all_l = Vec::new();
            let mut all_r = Vec::new();
            for block in 0..200 {
                let len = 1 + (rng.next_u64() % 700) as usize;
                let mut l: Vec<f32> = (0..len).map(|_| rng.uniform() * 0.8).collect();
                let mut r: Vec<f32> = (0..len).map(|_| rng.uniform() * 0.3).collect();
                if block % 7 == 0 {
                    l[len / 2] = 4.0; // impulse
                    r[0] = -3.0;
                }
                lim.process(&mut [&mut l, &mut r]);
                assert!(l.iter().chain(&r).all(|v| v.abs() <= ceiling + 1e-7));
                all_l.extend_from_slice(&l);
                all_r.extend_from_slice(&r);
            }
            if tp == 1.0 {
                // With true-peak detection the reconstructed peak stays close to the ceiling.
                let mut m = LoudnessMeter::new(SR as f64, 2);
                m.process(&[&all_l, &all_r]);
                assert!(m.true_peak_dbtp() < -1.0 + 0.6, "TP {}", m.true_peak_dbtp());
            }
        }
    }

    #[test]
    fn limiter_is_transparent_below_ceiling_with_reported_latency() {
        let mut lim = Limiter::new(SR, 1);
        let lat = lim.latency();
        let x = sine(1000.0, 0.3, SR as f64, 4800, 0.0);
        let mut y = x.clone();
        lim.process(&mut [&mut y]);
        for i in lat..4800 {
            assert!((y[i] - x[i - lat]).abs() < 1e-6);
        }
    }

    #[test]
    fn limiter_reduces_loud_sine_to_ceiling_smoothly() {
        let mut lim = Limiter::new(SR, 1);
        lim.set_param("ceiling", -6.0);
        let mut x = sine(200.0, 1.0, SR as f64, 48000, 0.0);
        lim.process(&mut [&mut x]);
        let tail = &x[24000..];
        let peak = tail.iter().fold(0.0f32, |a, v| a.max(v.abs()));
        assert!((lin_db(peak) + 6.0).abs() < 0.3, "{}", lin_db(peak));
    }
}