// Copyright (C) 2026 Yusuke Oda // SPDX-License-Identifier: AGPL-3.0-only //! Independent research prototypes. Attack/release parameters are 63.2% time constants. use std::collections::VecDeque; #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum StereoLink { Maximum, MaximumAfterDetector, EnergyAverage, Independent, } #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum CompressorMethod { PeakLog, PeakLinear, RmsIir, RmsWindow, PeakLinearGain, PeakLogDecoupled, } #[derive(Clone, Copy, Debug)] pub struct CompressorParameters { pub threshold_db: f64, pub ratio: f64, pub knee_db: f64, pub attack_ms: f64, pub release_ms: f64, pub makeup_db: f64, } impl Default for CompressorParameters { fn default() -> Self { Self { threshold_db: -18.0, ratio: 4.0, knee_db: 6.0, attack_ms: 10.0, release_ms: 100.0, makeup_db: 0.0, } } } #[derive(Clone)] struct AverageState { samples: Box<[f64]>, position: usize, sum: f64, } #[derive(Clone)] struct MovingAverage { state: AverageState, } impl MovingAverage { fn new(length: usize, initial: f64) -> Self { Self { state: AverageState { samples: vec![initial; length.max(1)].into_boxed_slice(), position: 0, sum: initial * length.max(1) as f64, }, } } fn reset(&mut self, value: f64) { self.state.samples.fill(value); self.state.position = 0; self.state.sum = value * self.state.samples.len() as f64; } #[inline] fn process_sample(&mut self, value: f64) -> f64 { let old = self.state.samples[self.state.position]; self.state.samples[self.state.position] = value; self.state.sum += value - old; self.state.position += 1; if self.state.position == self.state.samples.len() { self.state.position = 0; } (self.state.sum / self.state.samples.len() as f64).max(0.0) } fn heap_bytes(&self) -> usize { self.state.samples.len() * size_of::() } } #[derive(Clone)] struct CompressorState { detector: [f64; 2], reduction_db: [f64; 2], gain: [f64; 2], } #[derive(Clone)] pub struct Compressor { state: CompressorState, method: CompressorMethod, link: StereoLink, parameters: CompressorParameters, attack: f64, release: f64, rms: f64, makeup: f64, knee_low: f64, knee_low_power: f64, averages: [MovingAverage; 2], rate: f64, } impl Compressor { pub fn new(method: CompressorMethod, link: StereoLink, rate: f64, rms_ms: f64) -> Self { assert!(rate.is_finite() && rate >= 44100.0 && rms_ms > 0.0); let window = (rate * rms_ms * 0.002).round() as usize; let mut x = Self { state: CompressorState { detector: [0.0; 2], reduction_db: [0.0; 2], gain: [1.0; 2], }, method, link, parameters: CompressorParameters::default(), attack: 0.0, release: 0.0, rms: coefficient(rms_ms, rate), makeup: 1.0, knee_low: 0.0, knee_low_power: 0.0, averages: std::array::from_fn(|_| { MovingAverage::new( if method == CompressorMethod::RmsWindow { window } else { 1 }, 0.0, ) }), rate, }; x.set_parameters(CompressorParameters::default()); x } pub fn set_parameters(&mut self, p: CompressorParameters) { assert!( p.threshold_db.is_finite() && p.ratio >= 1.0 && p.ratio.is_finite() && p.knee_db >= 0.0 && p.knee_db.is_finite() && p.attack_ms.is_finite() && p.attack_ms >= 0.0 && p.release_ms.is_finite() && p.release_ms >= 0.0 && p.makeup_db.is_finite() ); self.attack = coefficient(p.attack_ms, self.rate); self.release = coefficient(p.release_ms, self.rate); self.makeup = 10_f64.powf(p.makeup_db / 20.0); self.knee_low = 10_f64.powf((p.threshold_db - p.knee_db / 2.0) / 20.0); self.knee_low_power = self.knee_low * self.knee_low; self.parameters = p; } pub fn reset(&mut self) { self.state = CompressorState { detector: [0.0; 2], reduction_db: [0.0; 2], gain: [1.0; 2], }; for a in &mut self.averages { a.reset(0.0); } } pub fn gains(&self) -> [f64; 2] { self.state.gain } pub fn state_bytes(&self) -> usize { size_of::() + self .averages .iter() .map(MovingAverage::heap_bytes) .sum::() } pub fn latency_samples(&self) -> usize { 0 } #[inline] fn static_reduction(&self, level: f64, power: bool) -> f64 { if level <= if power { self.knee_low_power } else { self.knee_low } { return 0.0; } let db = if power { 10.0 * level.log10() } else { 20.0 * level.log10() }; let over = db - self.parameters.threshold_db; let slope = 1.0 - 1.0 / self.parameters.ratio; let w = self.parameters.knee_db; if over > w / 2.0 { slope * over } else { slope * (over + w / 2.0).powi(2) / (2.0 * w) } } #[inline] fn process_inner_sample(&mut self, input: [f64; 2]) -> [f64; 2] { let power = MODE == 2 || MODE == 3; let mut level = if power { [input[0] * input[0], input[1] * input[1]] } else { [input[0].abs(), input[1].abs()] }; match self.link { StereoLink::Maximum => { let maximum = level[0].max(level[1]); level.fill(maximum); } StereoLink::EnergyAverage => { let value = if power { (level[0] + level[1]) * 0.5 } else { ((level[0] * level[0] + level[1] * level[1]) * 0.5).sqrt() }; level.fill(value); } StereoLink::Independent | StereoLink::MaximumAfterDetector => {} } let detector_channels = if self.link == StereoLink::Independent || self.link == StereoLink::MaximumAfterDetector { 2 } else { 1 }; for (ch, target) in level.iter_mut().enumerate().take(detector_channels) { *target = if MODE == 1 { let a = if *target > self.state.detector[ch] { self.attack } else { self.release }; self.state.detector[ch] = a * self.state.detector[ch] + (1.0 - a) * *target; self.state.detector[ch] } else if MODE == 2 { self.state.detector[ch] = self.rms * self.state.detector[ch] + (1.0 - self.rms) * *target; self.state.detector[ch] } else if MODE == 3 { self.averages[ch].process_sample(*target) } else { *target }; } if self.link == StereoLink::MaximumAfterDetector { let maximum = level[0].max(level[1]); level.fill(maximum); } let channels = if self.link == StereoLink::Independent { 2 } else { 1 }; for (ch, level) in level.into_iter().enumerate().take(channels) { let target = self.static_reduction(level, power); if MODE == 4 { let gain = 10_f64.powf(-target / 20.0); let a = if gain < self.state.gain[ch] { self.attack } else { self.release }; self.state.gain[ch] = a * self.state.gain[ch] + (1.0 - a) * gain; } else { let reduction = if MODE == 1 { target } else if MODE == 5 { self.state.detector[ch] = target.max( self.release * self.state.detector[ch] + (1.0 - self.release) * target, ); self.attack * self.state.reduction_db[ch] + (1.0 - self.attack) * self.state.detector[ch] } else { let a = if target > self.state.reduction_db[ch] { self.attack } else { self.release }; a * self.state.reduction_db[ch] + (1.0 - a) * target }; self.state.reduction_db[ch] = reduction; self.state.gain[ch] = 10_f64.powf(-reduction / 20.0); } } if channels == 1 { self.state.gain[1] = self.state.gain[0]; if self.link != StereoLink::MaximumAfterDetector { self.state.detector[1] = self.state.detector[0]; } self.state.reduction_db[1] = self.state.reduction_db[0]; } [ input[0] * self.state.gain[0] * self.makeup, input[1] * self.state.gain[1] * self.makeup, ] } pub fn process_sample(&mut self, input: [f64; 2]) -> [f64; 2] { match self.method { CompressorMethod::PeakLog => self.process_inner_sample::<0>(input), CompressorMethod::PeakLinear => self.process_inner_sample::<1>(input), CompressorMethod::RmsIir => self.process_inner_sample::<2>(input), CompressorMethod::RmsWindow => self.process_inner_sample::<3>(input), CompressorMethod::PeakLinearGain => self.process_inner_sample::<4>(input), CompressorMethod::PeakLogDecoupled => self.process_inner_sample::<5>(input), } } pub fn process_samples(&mut self, input: &[[f64; 2]], output: &mut [[f64; 2]]) { assert_eq!(input.len(), output.len()); macro_rules! run { ($m:expr) => { for (x, y) in input.iter().zip(output) { *y = self.process_inner_sample::<$m>(*x); } }; } match self.method { CompressorMethod::PeakLog => run!(0), CompressorMethod::PeakLinear => run!(1), CompressorMethod::RmsIir => run!(2), CompressorMethod::RmsWindow => run!(3), CompressorMethod::PeakLinearGain => run!(4), CompressorMethod::PeakLogDecoupled => run!(5), } } } #[derive(Clone, Copy, Debug, PartialEq, Eq)] pub enum LimiterMethod { Instant, MaxBox, MaxTriangle, MaxCompensated, } #[derive(Clone, Copy, Debug)] pub struct LimiterParameters { pub ceiling_db: f64, pub input_gain_db: f64, pub release_ms: f64, } impl Default for LimiterParameters { fn default() -> Self { Self { ceiling_db: -1.0, input_gain_db: 6.0, release_ms: 100.0, } } } #[derive(Clone)] struct MaximumState { queue: VecDeque<(usize, f64)>, position: usize, } #[derive(Clone)] struct RunningMaximum { state: MaximumState, length: usize, } impl RunningMaximum { fn new(length: usize) -> Self { Self { state: MaximumState { queue: VecDeque::with_capacity(length.max(1)), position: 0, }, length: length.max(1), } } fn reset(&mut self) { self.state.queue.clear(); self.state.position = 0; } #[inline] fn process_sample(&mut self, value: f64) -> f64 { let n = self.state.position; self.state.position += 1; while self .state .queue .front() .is_some_and(|&(at, _)| at + self.length <= n) { self.state.queue.pop_front(); } while self .state .queue .back() .is_some_and(|&(_, old)| old <= value) { self.state.queue.pop_back(); } self.state.queue.push_back((n, value)); self.state.queue.front().unwrap().1 } fn heap_bytes(&self) -> usize { self.state.queue.capacity() * size_of::<(usize, f64)>() } } #[derive(Clone)] struct LimiterState { envelope: [f64; 2], gain: [f64; 2], delay: Box<[[f64; 2]]>, position: usize, } #[derive(Clone)] pub struct Limiter { state: LimiterState, method: LimiterMethod, link: StereoLink, rate: f64, lookahead: usize, maximum: [RunningMaximum; 2], average: [[MovingAverage; 2]; 2], ceiling: f64, input_gain: f64, release: f64, attack: f64, beta: f64, } impl Limiter { pub fn new(method: LimiterMethod, link: StereoLink, rate: f64, lookahead_ms: f64) -> Self { assert!( rate >= 44100.0 && rate.is_finite() && lookahead_ms >= 0.0 && lookahead_ms.is_finite() ); assert!(matches!( link, StereoLink::Maximum | StereoLink::Independent )); let n = if method == LimiterMethod::Instant { 0 } else { (lookahead_ms * rate * 0.001).round() as usize }; let first = if method == LimiterMethod::MaxTriangle { n / 2 + 1 } else { n + 1 }; let second = if method == LimiterMethod::MaxTriangle { n - n / 2 + 1 } else { 1 }; let beta = 1.0 - 1.0 / 1.01; let mut out = Self { state: LimiterState { envelope: [1.0; 2], gain: [1.0; 2], delay: vec![[0.0; 2]; n.max(1)].into_boxed_slice(), position: 0, }, method, link, rate, lookahead: n, maximum: std::array::from_fn(|_| RunningMaximum::new(n + 1)), average: std::array::from_fn(|_| { [ MovingAverage::new(first, 1.0), MovingAverage::new(second, 1.0), ] }), ceiling: 1.0, input_gain: 1.0, release: 0.0, attack: f64::powf(beta, 1.0 / (n + 1) as f64), beta, }; out.set_parameters(LimiterParameters::default()); out.reset(); out } pub fn set_parameters(&mut self, p: LimiterParameters) { assert!( p.ceiling_db.is_finite() && p.input_gain_db.is_finite() && p.release_ms.is_finite() && p.release_ms >= 0.0 && p.release_ms.is_finite() ); self.ceiling = 10_f64.powf(p.ceiling_db / 20.0); self.input_gain = 10_f64.powf(p.input_gain_db / 20.0); self.release = coefficient(p.release_ms, self.rate); } pub fn reset(&mut self) { self.state.envelope = [self.ceiling; 2]; self.state.gain = [1.0; 2]; self.state.delay.fill([0.0; 2]); self.state.position = 0; for m in &mut self.maximum { m.reset(); } for a in &mut self.average { for s in a { s.reset(self.ceiling); } } } pub fn gains(&self) -> [f64; 2] { self.state.gain } pub fn latency_samples(&self) -> usize { self.lookahead } pub fn state_bytes(&self) -> usize { size_of::() + self.state.delay.len() * size_of::<[f64; 2]>() + self .maximum .iter() .map(RunningMaximum::heap_bytes) .sum::() + self .average .iter() .flatten() .map(MovingAverage::heap_bytes) .sum::() } #[inline] fn process_inner_sample(&mut self, raw: [f64; 2]) -> [f64; 2] { let input = [raw[0] * self.input_gain, raw[1] * self.input_gain]; let mut levels = [input[0].abs(), input[1].abs()]; let channels = if self.link == StereoLink::Maximum { let maximum = levels[0].max(levels[1]); levels.fill(maximum); 1 } else { 2 }; for (ch, peak) in levels.into_iter().enumerate().take(channels) { let peak = peak.max(self.ceiling); let envelope = if MODE == 0 { peak.max(self.release * self.state.envelope[ch] + (1.0 - self.release) * peak) } else if MODE == 3 { let target = peak.max((peak - self.beta * self.state.envelope[ch]) / (1.0 - self.beta)); let maximum = self.maximum[ch].process_sample(target); let a = if maximum > self.state.envelope[ch] { self.attack } else { self.release }; a * self.state.envelope[ch] + (1.0 - a) * maximum } else { let maximum = self.maximum[ch].process_sample(peak); maximum.max(self.release * self.state.envelope[ch] + (1.0 - self.release) * maximum) }; self.state.envelope[ch] = envelope; let smooth = if MODE == 1 || MODE == 2 { let first = self.average[ch][0].process_sample(envelope); if MODE == 2 { self.average[ch][1].process_sample(first) } else { first } } else { envelope }; self.state.gain[ch] = (self.ceiling / smooth).min(1.0); } if channels == 1 { self.state.envelope[1] = self.state.envelope[0]; self.state.gain[1] = self.state.gain[0]; } let delayed = if self.lookahead == 0 { input } else { let value = self.state.delay[self.state.position]; self.state.delay[self.state.position] = input; self.state.position += 1; if self.state.position == self.lookahead { self.state.position = 0; } value }; [ delayed[0] * self.state.gain[0], delayed[1] * self.state.gain[1], ] } pub fn process_sample(&mut self, input: [f64; 2]) -> [f64; 2] { match self.method { LimiterMethod::Instant => self.process_inner_sample::<0>(input), LimiterMethod::MaxBox => self.process_inner_sample::<1>(input), LimiterMethod::MaxTriangle => self.process_inner_sample::<2>(input), LimiterMethod::MaxCompensated => self.process_inner_sample::<3>(input), } } pub fn process_samples(&mut self, input: &[[f64; 2]], output: &mut [[f64; 2]]) { assert_eq!(input.len(), output.len()); macro_rules! run { ($m:expr) => { for (x, y) in input.iter().zip(output) { *y = self.process_inner_sample::<$m>(*x); } }; } match self.method { LimiterMethod::Instant => run!(0), LimiterMethod::MaxBox => run!(1), LimiterMethod::MaxTriangle => run!(2), LimiterMethod::MaxCompensated => run!(3), } } } fn coefficient(ms: f64, rate: f64) -> f64 { if ms == 0.0 { 0.0 } else { (-1000.0 / (ms * rate)).exp() } } #[cfg(test)] mod tests { use super::*; #[test] fn maxima_match_direct_window() { for length in [1, 2, 7, 48, 241] { let mut m = RunningMaximum::new(length); let mut history = Vec::new(); let mut random = 1_u64; for n in 0..10000 { random = random.wrapping_mul(6364136223846793005).wrapping_add(1); let value = if n % 5 == 0 { 0.0 } else { (random >> 11) as f64 / (1_u64 << 53) as f64 }; history.push(value); let lo = history.len().saturating_sub(length); let wanted = history[lo..] .iter() .copied() .fold(f64::NEG_INFINITY, f64::max); assert_eq!(m.process_sample(value), wanted); } } } #[test] fn static_curve_is_continuous_and_has_expected_ratio() { for method in [ CompressorMethod::PeakLog, CompressorMethod::PeakLinear, CompressorMethod::RmsIir, CompressorMethod::RmsWindow, CompressorMethod::PeakLinearGain, CompressorMethod::PeakLogDecoupled, ] { let mut c = Compressor::new(method, StereoLink::Maximum, 48000.0, 10.0); let p = CompressorParameters { attack_ms: 0.0, release_ms: 0.0, ..Default::default() }; c.set_parameters(p); for db in [-72.0, -21.0, -18.0, -15.0, -6.0, 6.0] { c.reset(); let input = 10_f64.powf(db / 20.0); let mut y = [0.0; 2]; for _ in 0..48000 { y = c.process_sample([input, input]); } let over = db - p.threshold_db; let expected = if over <= -p.knee_db / 2.0 { db } else if over >= p.knee_db / 2.0 { p.threshold_db + over / p.ratio } else { db - (1.0 - 1.0 / p.ratio) * (over + p.knee_db / 2.0).powi(2) / (2.0 * p.knee_db) }; assert!( (20.0 * y[0].log10() - expected).abs() < 1e-10, "{method:?} {db}" ); } } } #[test] fn limiter_obeys_sample_ceiling() { for rate in [44100.0, 48000.0, 96000.0] { for method in [ LimiterMethod::Instant, LimiterMethod::MaxBox, LimiterMethod::MaxTriangle, LimiterMethod::MaxCompensated, ] { for link in [StereoLink::Maximum, StereoLink::Independent] { let mut l = Limiter::new(method, link, rate, 1.0); let mut random = 3_u64; for n in 0..20000 { random = random.wrapping_mul(6364136223846793005).wrapping_add(1); let noise = (random >> 11) as f64 / (1_u64 << 53) as f64 * 2.0 - 1.0; let input = if n % 500 < 100 { [noise * 8.0, (n as f64 * 0.35).sin() * 4.0] } else { [0.0; 2] }; let out = l.process_sample(input); assert!( out.iter().all(|x| x.abs() <= l.ceiling * (1.0 + 1e-10)), "{method:?} {n} {out:?}" ); } } } } } #[test] fn series_and_scalar_match() { let input: Vec<_> = (0..10000) .map(|n| [(n as f64 * 0.13).sin(), (n as f64 * 0.19).sin()]) .collect(); for method in [ CompressorMethod::PeakLog, CompressorMethod::PeakLinear, CompressorMethod::RmsIir, CompressorMethod::RmsWindow, CompressorMethod::PeakLinearGain, CompressorMethod::PeakLogDecoupled, ] { let mut a = Compressor::new(method, StereoLink::Maximum, 48000.0, 10.0); let mut b = a.clone(); let scalar: Vec<_> = input.iter().map(|x| a.process_sample(*x)).collect(); let mut series = vec![[0.0; 2]; input.len()]; b.process_samples(&input, &mut series); assert_eq!(scalar, series); } for method in [ LimiterMethod::Instant, LimiterMethod::MaxBox, LimiterMethod::MaxTriangle, LimiterMethod::MaxCompensated, ] { let mut a = Limiter::new(method, StereoLink::Maximum, 48000.0, 1.0); let mut b = a.clone(); let scalar: Vec<_> = input.iter().map(|x| a.process_sample(*x)).collect(); let mut series = vec![[0.0; 2]; input.len()]; b.process_samples(&input, &mut series); assert_eq!(scalar, series); } } }