Skip to main content

qualia_audio/fx/reverb/
comb.rs

1//! Feedback comb filter with in-loop damping lowpass (Freeverb-style).
2//!
3//! Delegated to [`etalon_signal::reverb::comb_step`].
4
5use crate::types::AudioError;
6
7/// Feedback comb filter — fixed delay, feedback gain, damping lowpass.
8#[derive(Debug, Clone)]
9pub struct CombFilter {
10    buffer: Vec<f32>,
11    index: usize,
12    feedback: f32,
13    /// One-pole damping coefficient in `[0, 1)`. Higher = darker tail.
14    damp: f32,
15    /// Lowpass state held across the feedback loop.
16    filterstore: f32,
17}
18
19impl CombFilter {
20    /// Construct with a delay of `delay_samples` (clamped to ≥ 1).
21    pub fn new(delay_samples: usize, feedback: f32, damp: f32) -> Result<Self, AudioError> {
22        let n = delay_samples.max(1);
23        if !feedback.is_finite() || !damp.is_finite() {
24            return Err(AudioError::InvalidParameter);
25        }
26        Ok(Self {
27            buffer: vec![0.0; n],
28            index: 0,
29            feedback: feedback.clamp(-0.999, 0.999),
30            damp: damp.clamp(0.0, 0.999),
31            filterstore: 0.0,
32        })
33    }
34
35    /// Delay length in samples.
36    #[inline]
37    pub fn delay(&self) -> usize {
38        self.buffer.len()
39    }
40
41    /// Update feedback (room size) live. Clamped for stability.
42    #[inline]
43    pub fn set_feedback(&mut self, feedback: f32) {
44        if feedback.is_finite() {
45            self.feedback = feedback.clamp(-0.999, 0.999);
46        }
47    }
48
49    /// Update damping live. Clamped to `[0, 1)`.
50    #[inline]
51    pub fn set_damp(&mut self, damp: f32) {
52        if damp.is_finite() {
53            self.damp = damp.clamp(0.0, 0.999);
54        }
55    }
56
57    /// Zero the delay line and lowpass state. No allocation.
58    pub fn reset(&mut self) {
59        for s in self.buffer.iter_mut() {
60            *s = 0.0;
61        }
62        self.index = 0;
63        self.filterstore = 0.0;
64    }
65
66    /// Process one sample. **Zero-alloc, no locks.**
67    #[inline]
68    pub fn process_sample(&mut self, input: f32) -> f32 {
69        etalon_signal::reverb::comb_step(
70            &mut self.buffer,
71            &mut self.index,
72            self.feedback,
73            self.damp,
74            &mut self.filterstore,
75            input,
76        )
77    }
78
79    /// Block process: `output[i] = process_sample(input[i])`. **Zero-alloc.**
80    pub fn process(&mut self, input: &[f32], output: &mut [f32]) -> Result<(), AudioError> {
81        if output.len() < input.len() {
82            return Err(AudioError::OutputBufferTooSmall);
83        }
84        for (o, &x) in output.iter_mut().zip(input.iter()) {
85            *o = self.process_sample(x);
86        }
87        Ok(())
88    }
89}
90
91#[cfg(test)]
92mod tests {
93    use super::*;
94
95    #[test]
96    fn impulse_echoes_at_delay_period_with_decay() {
97        let d = 7usize;
98        let g = 0.6f32;
99        let mut c = CombFilter::new(d, g, 0.0).unwrap();
100        let n = 4 * d + 1;
101        let mut input = vec![0.0f32; n];
102        input[0] = 1.0;
103        let mut out = vec![0.0f32; n];
104        c.process(&input, &mut out).unwrap();
105
106        assert!(
107            (out[d] - 1.0).abs() < 1e-6,
108            "first echo at D should be ~1.0, got {}",
109            out[d]
110        );
111        assert!(
112            (out[2 * d] - g).abs() < 1e-6,
113            "second echo ~g, got {}",
114            out[2 * d]
115        );
116        assert!(
117            (out[3 * d] - g * g).abs() < 1e-6,
118            "third echo ~g^2, got {}",
119            out[3 * d]
120        );
121        assert!(
122            (out[4 * d] - g * g * g).abs() < 1e-6,
123            "fourth echo ~g^3, got {}",
124            out[4 * d]
125        );
126
127        assert!(out[1].abs() < 1e-9);
128        assert!(out[d - 1].abs() < 1e-9);
129        assert!(out[d + 1].abs() < 1e-9);
130
131        assert!(out[2 * d].abs() < out[d].abs());
132        assert!(out[3 * d].abs() < out[2 * d].abs());
133    }
134
135    #[test]
136    fn damping_reduces_tail_energy() {
137        let d = 11usize;
138        let g = 0.7f32;
139        let n = 20 * d;
140        let mut input = vec![0.0f32; n];
141        input[0] = 1.0;
142
143        let mut bright = CombFilter::new(d, g, 0.0).unwrap();
144        let mut dark = CombFilter::new(d, g, 0.5).unwrap();
145        let mut ob = vec![0.0f32; n];
146        let mut od = vec![0.0f32; n];
147        bright.process(&input, &mut ob).unwrap();
148        dark.process(&input, &mut od).unwrap();
149
150        let eb: f32 = ob.iter().map(|x| x * x).sum();
151        let ed: f32 = od.iter().map(|x| x * x).sum();
152        assert!(
153            ed < eb,
154            "damped tail energy {} should be < undamped {}",
155            ed,
156            eb
157        );
158        assert!(eb.is_finite() && ed.is_finite());
159    }
160
161    #[test]
162    fn bounded_and_finite_under_sustained_input() {
163        let mut c = CombFilter::new(31, 0.85, 0.2).unwrap();
164        let input = vec![0.5f32; 4096];
165        let mut out = vec![0.0f32; 4096];
166        c.process(&input, &mut out).unwrap();
167        assert!(out.iter().all(|x| x.is_finite()));
168        assert!(out.iter().all(|x| x.abs() < 100.0));
169    }
170
171    #[test]
172    fn output_too_small_errors() {
173        let mut c = CombFilter::new(4, 0.5, 0.0).unwrap();
174        let input = [0.0f32; 8];
175        let mut out = [0.0f32; 4];
176        assert_eq!(
177            c.process(&input, &mut out),
178            Err(AudioError::OutputBufferTooSmall)
179        );
180    }
181}