headroom

//! 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;