Skip to main content

qualia_core_db/audio/dsp/
meters.rs

1//! Audio meters — waveform, phase correlation, loudness (LUFS).
2
3/// Waveform view — computes peak/RMS envelope of a signal buffer.
4#[derive(Debug, Clone)]
5pub struct WaveformMeter {
6    /// Maximum absolute sample value seen by the last `analyse`.
7    pub peak: f64,
8    /// Root-mean-square level of the last analysed buffer.
9    pub rms: f64,
10}
11
12impl WaveformMeter {
13    /// Create a zeroed meter.
14    pub fn new() -> Self {
15        Self {
16            peak: 0.0,
17            rms: 0.0,
18        }
19    }
20
21    /// Analyse a buffer and update peak/RMS.
22    pub fn analyse(&mut self, samples: &[f64]) {
23        if samples.is_empty() {
24            self.peak = 0.0;
25            self.rms = 0.0;
26            return;
27        }
28        let mut sum_sq = 0.0;
29        let mut peak = 0.0;
30        for &s in samples {
31            let abs = s.abs();
32            if abs > peak {
33                peak = abs;
34            }
35            sum_sq += s * s;
36        }
37        self.peak = peak;
38        self.rms = (sum_sq / samples.len() as f64).sqrt();
39    }
40
41    /// Get a downsampled waveform display (min/max per bucket).
42    pub fn waveform_display(samples: &[f64], buckets: usize) -> Vec<(f64, f64)> {
43        if samples.is_empty() || buckets == 0 {
44            return vec![];
45        }
46        let bucket_size = samples.len() / buckets;
47        if bucket_size == 0 {
48            return vec![];
49        }
50        let mut result = Vec::with_capacity(buckets);
51        for i in 0..buckets {
52            let start = i * bucket_size;
53            let end = ((i + 1) * bucket_size).min(samples.len());
54            let mut min = f64::INFINITY;
55            let mut max = f64::NEG_INFINITY;
56            for &s in &samples[start..end] {
57                if s < min {
58                    min = s;
59                }
60                if s > max {
61                    max = s;
62                }
63            }
64            if min == f64::INFINITY {
65                min = 0.0;
66                max = 0.0;
67            }
68            result.push((min, max));
69        }
70        result
71    }
72}
73
74/// Phase correlation meter — measures stereo correlation.
75#[derive(Debug, Clone)]
76pub struct PhaseMeter {
77    /// Normalised correlation in `[-1, 1]`: 1 = mono/correlated, 0 =
78    /// uncorrelated, -1 = fully out of phase.
79    pub correlation: f64,
80}
81
82impl PhaseMeter {
83    /// Create a meter initialised to `correlation = 1.0` (mono).
84    pub fn new() -> Self {
85        Self { correlation: 1.0 }
86    }
87
88    /// Analyse left/right channels.
89    pub fn analyse(&mut self, left: &[f64], right: &[f64]) {
90        let n = left.len().min(right.len());
91        if n == 0 {
92            self.correlation = 1.0;
93            return;
94        }
95        let mut sum_lr = 0.0;
96        let mut sum_l2 = 0.0;
97        let mut sum_r2 = 0.0;
98        for i in 0..n {
99            sum_lr += left[i] * right[i];
100            sum_l2 += left[i] * left[i];
101            sum_r2 += right[i] * right[i];
102        }
103        let denom = (sum_l2 * sum_r2).sqrt();
104        self.correlation = if denom > 1e-10 { sum_lr / denom } else { 1.0 };
105    }
106}
107
108/// Loudness meter — ITU-R BS.1770 simplified LUFS measurement.
109///
110/// This is a simplified implementation: K-weighting filter + integrated
111/// loudness over a sliding window. Full BS.1770 includes channel weighting
112/// and gating; this version handles mono/stereo.
113#[derive(Debug, Clone)]
114pub struct LoudnessMeter {
115    /// Current momentary loudness (LUFS).
116    pub momentary_lufs: f64,
117    /// Current short-term loudness (LUFS).
118    pub short_term_lufs: f64,
119    // K-weighting filter state (high-pass shelf + high-pass RLB)
120    hp_x1: f64,
121    hp_x2: f64,
122    hp_y1: f64,
123    hp_y2: f64,
124    rlb_x1: f64,
125    rlb_x2: f64,
126    rlb_y1: f64,
127    rlb_y2: f64,
128    // Integration window
129    window: Vec<f64>,
130    window_pos: usize,
131    window_size: usize,
132}
133
134impl LoudnessMeter {
135    /// Create a meter with a 400 ms integration window sized for
136    /// `sample_rate`; starts at -70 LUFS.
137    pub fn new(sample_rate: f64) -> Self {
138        // 400ms window for momentary, 3s for short-term.
139        let window_size = (0.4 * sample_rate) as usize;
140        Self {
141            momentary_lufs: -70.0,
142            short_term_lufs: -70.0,
143            hp_x1: 0.0,
144            hp_x2: 0.0,
145            hp_y1: 0.0,
146            hp_y2: 0.0,
147            rlb_x1: 0.0,
148            rlb_x2: 0.0,
149            rlb_y1: 0.0,
150            rlb_y2: 0.0,
151            window: vec![0.0; window_size],
152            window_pos: 0,
153            window_size,
154        }
155    }
156
157    /// K-weighting filter (ITU-R BS.1770 stage 1 high-shelf + stage 2 high-pass RLB).
158    fn k_weight(&mut self, input: f64) -> f64 {
159        // Stage 1: high-shelf boost (48kHz biquad approximation).
160        let b0 = 1.53512485958697;
161        let b1 = -2.69169618940638;
162        let b2 = 1.19839281085285;
163        let a1 = -1.69065929318241;
164        let a2 = 0.73248077421585;
165
166        let hs_out =
167            b0 * input + b1 * self.hp_x1 + b2 * self.hp_x2 - a1 * self.hp_y1 - a2 * self.hp_y2;
168        self.hp_x2 = self.hp_x1;
169        self.hp_x1 = input;
170        self.hp_y2 = self.hp_y1;
171        self.hp_y1 = hs_out;
172
173        // Stage 2: high-pass (RLB filter) applied to the high-shelf output.
174        let rlb_out =
175            hs_out - 2.0 * self.rlb_x1 + self.rlb_x2 + 1.99 * self.rlb_y1 - 0.99 * self.rlb_y2;
176        self.rlb_x2 = self.rlb_x1;
177        self.rlb_x1 = hs_out;
178        self.rlb_y2 = self.rlb_y1;
179        self.rlb_y1 = rlb_out;
180
181        rlb_out
182    }
183
184    /// Process one sample.
185    pub fn tick(&mut self, input: f64) -> f64 {
186        let weighted = self.k_weight(input);
187        let sq = weighted * weighted;
188        self.window[self.window_pos] = sq;
189        self.window_pos = (self.window_pos + 1) % self.window_size;
190
191        // Compute momentary loudness.
192        let mean_sq: f64 = self.window.iter().sum::<f64>() / self.window_size as f64;
193        self.momentary_lufs = if mean_sq > 1e-12 {
194            -0.691 + 10.0 * mean_sq.log10()
195        } else {
196            -70.0
197        };
198        weighted
199    }
200
201    /// Process a buffer.
202    pub fn process(&mut self, samples: &[f64]) {
203        for &s in samples {
204            self.tick(s);
205        }
206    }
207}
208
209#[cfg(test)]
210mod tests {
211    use super::*;
212
213    #[test]
214    fn waveform_meter_peak_rms() {
215        let mut meter = WaveformMeter::new();
216        let samples: Vec<f64> = (0..1000).map(|i| (i as f64 * 0.01).sin()).collect();
217        meter.analyse(&samples);
218        assert!(meter.peak > 0.0);
219        assert!(meter.rms > 0.0);
220        assert!(meter.rms <= meter.peak);
221    }
222
223    #[test]
224    fn waveform_meter_silence() {
225        let mut meter = WaveformMeter::new();
226        meter.analyse(&[0.0; 100]);
227        assert_eq!(meter.peak, 0.0);
228        assert_eq!(meter.rms, 0.0);
229    }
230
231    #[test]
232    fn waveform_display_basic() {
233        let samples: Vec<f64> = (0..1000).map(|i| (i as f64 * 0.1).sin()).collect();
234        let display = WaveformMeter::waveform_display(&samples, 10);
235        assert_eq!(display.len(), 10);
236        for (min, max) in &display {
237            assert!(min <= max);
238        }
239    }
240
241    #[test]
242    fn phase_meter_correlated() {
243        let mut meter = PhaseMeter::new();
244        let signal: Vec<f64> = (0..1000).map(|i| (i as f64 * 0.01).sin()).collect();
245        meter.analyse(&signal, &signal);
246        assert!((meter.correlation - 1.0).abs() < 0.01);
247    }
248
249    #[test]
250    fn phase_meter_anticorrelated() {
251        let mut meter = PhaseMeter::new();
252        let left: Vec<f64> = (0..1000).map(|i| (i as f64 * 0.01).sin()).collect();
253        let right: Vec<f64> = left.iter().map(|&x| -x).collect();
254        meter.analyse(&left, &right);
255        assert!((meter.correlation + 1.0).abs() < 0.01);
256    }
257
258    #[test]
259    fn phase_meter_uncorrelated() {
260        let mut meter = PhaseMeter::new();
261        let left: Vec<f64> = (0..1000).map(|i| (i as f64 * 0.01).sin()).collect();
262        let right: Vec<f64> = (0..1000).map(|i| (i as f64 * 0.03).cos()).collect();
263        meter.analyse(&left, &right);
264        assert!(meter.correlation.abs() < 0.3);
265    }
266
267    #[test]
268    fn loudness_meter_silence() {
269        let mut meter = LoudnessMeter::new(44100.0);
270        meter.process(&[0.0; 1000]);
271        assert!(meter.momentary_lufs < -60.0);
272    }
273
274    #[test]
275    fn loudness_meter_loud_signal() {
276        let mut meter = LoudnessMeter::new(44100.0);
277        // Use a 1kHz sine wave — K-weighting includes a high-pass that removes DC.
278        let signal: Vec<f64> = (0..20000)
279            .map(|i| (2.0 * std::f64::consts::PI * 1000.0 * i as f64 / 44100.0).sin() * 0.5)
280            .collect();
281        meter.process(&signal);
282        // A loud sine should produce a finite, non-silence LUFS.
283        assert!(
284            meter.momentary_lufs > -70.0,
285            "momentary_lufs={}",
286            meter.momentary_lufs
287        );
288    }
289}