Skip to main content

qualia_audio/aqa/intrusive/
seg_snr.rs

1//! Segmental signal-to-noise ratio (seg-SNR) between a reference and a degraded
2//! signal.
3//!
4//! Classic intrusive metric: split both signals into fixed-length frames, compute
5//! the per-frame SNR in dB (reference energy over error energy), clamp each frame
6//! to a sensible dynamic range, and average across frames. Unlike a global SNR,
7//! the segmental variant weights quiet and loud passages more evenly, which
8//! correlates better with perceived quality.
9//!
10//! Pure-Rust, no licence encumbrance, zero heap: a single scalar `f32` is
11//! returned and the two input slices are read in place.
12
13use crate::types::AudioError;
14
15/// Per-frame SNR is clamped to `[MIN_FRAME_SNR_DB, MAX_FRAME_SNR_DB]` before
16/// averaging. These match the conventional seg-SNR range used in speech-quality
17/// literature and keep silent/identical frames from dominating the mean with
18/// `+inf`.
19pub const MAX_FRAME_SNR_DB: f32 = 35.0;
20pub const MIN_FRAME_SNR_DB: f32 = -10.0;
21
22/// Segmental SNR in dB between `reference` and `degraded`.
23///
24/// - `reference`: the clean/reference signal.
25/// - `degraded`: the processed/degraded signal, aligned sample-for-sample with
26///   `reference`. Must be the same length.
27/// - `frame_len`: samples per frame (e.g. 256). Must be non-zero.
28///
29/// The error signal is `degraded - reference`. For each full frame the SNR is
30/// `10 * log10(ref_energy / err_energy)`, clamped to
31/// `[MIN_FRAME_SNR_DB, MAX_FRAME_SNR_DB]`; a frame whose error energy is zero
32/// (identical) clamps to `MAX_FRAME_SNR_DB`. The returned value is the mean over
33/// all full frames. A trailing partial frame shorter than `frame_len` is ignored.
34///
35/// Returns [`AudioError::InvalidParameter`] if `frame_len` is 0 or the lengths
36/// differ, and [`AudioError::MalformedAudio`] if there is not even one full frame.
37pub fn segmental_snr(
38    reference: &[f32],
39    degraded: &[f32],
40    frame_len: usize,
41) -> Result<f32, AudioError> {
42    if frame_len == 0 || reference.len() != degraded.len() {
43        return Err(AudioError::InvalidParameter);
44    }
45    let n_frames = reference.len() / frame_len;
46    if n_frames == 0 {
47        return Err(AudioError::MalformedAudio);
48    }
49
50    // Tiny floor so an all-silent reference frame does not divide by zero; well
51    // below any real signal energy.
52    const EPS: f32 = 1.0e-12;
53
54    let mut acc_db = 0.0f32;
55    for f in 0..n_frames {
56        let base = f * frame_len;
57        let mut ref_energy = 0.0f32;
58        let mut err_energy = 0.0f32;
59        for i in 0..frame_len {
60            let r = reference[base + i];
61            let d = degraded[base + i];
62            let e = d - r;
63            ref_energy += r * r;
64            err_energy += e * e;
65        }
66
67        let snr_db = if err_energy <= EPS {
68            // Identical (or numerically identical) frame → best case.
69            MAX_FRAME_SNR_DB
70        } else {
71            let ratio = (ref_energy + EPS) / err_energy;
72            10.0 * ratio.log10()
73        };
74        acc_db += snr_db.clamp(MIN_FRAME_SNR_DB, MAX_FRAME_SNR_DB);
75    }
76
77    Ok(acc_db / n_frames as f32)
78}
79
80#[cfg(test)]
81mod tests {
82    use super::*;
83    use core::f32::consts::TAU;
84
85    fn tone(n: usize, freq_bin: f32) -> Vec<f32> {
86        (0..n)
87            .map(|i| (TAU * freq_bin * i as f32 / n as f32).sin())
88            .collect()
89    }
90
91    #[test]
92    fn identical_signals_hit_clamped_maximum() {
93        let x = tone(2048, 20.0);
94        let snr = segmental_snr(&x, &x, 256).expect("valid");
95        // Identical → every frame clamps to the max.
96        assert!((snr - MAX_FRAME_SNR_DB).abs() < 1e-4, "snr={snr}");
97        assert!(snr > 30.0);
98    }
99
100    #[test]
101    fn noisy_signal_has_lower_finite_snr_than_clean() {
102        let x = tone(4096, 30.0);
103
104        // Deterministic pseudo-noise added to the reference.
105        let mut state: u32 = 0x1234_5678;
106        let noisy: Vec<f32> = x
107            .iter()
108            .map(|&v| {
109                state = state.wrapping_mul(1_664_525).wrapping_add(1_013_904_223);
110                let u = (state >> 8) as f32 / (1u32 << 24) as f32; // [0,1)
111                v + (u - 0.5) * 0.4
112            })
113            .collect();
114
115        let snr_clean = segmental_snr(&x, &x, 256).expect("valid");
116        let snr_noisy = segmental_snr(&x, &noisy, 256).expect("valid");
117
118        assert!(snr_noisy.is_finite(), "noisy snr must be finite");
119        assert!(
120            snr_clean > snr_noisy,
121            "clean {snr_clean} should exceed noisy {snr_noisy}"
122        );
123        // Noisy result stays inside the clamped band.
124        assert!(snr_noisy >= MIN_FRAME_SNR_DB && snr_noisy <= MAX_FRAME_SNR_DB);
125    }
126
127    #[test]
128    fn more_noise_lowers_snr_monotonically() {
129        let x = tone(4096, 24.0);
130        let make = |amp: f32| -> Vec<f32> {
131            let mut state: u32 = 99;
132            x.iter()
133                .map(|&v| {
134                    state = state.wrapping_mul(1_664_525).wrapping_add(1_013_904_223);
135                    let u = (state >> 8) as f32 / (1u32 << 24) as f32;
136                    v + (u - 0.5) * amp
137                })
138                .collect()
139        };
140        let low = segmental_snr(&x, &make(0.1), 256).expect("valid");
141        let high = segmental_snr(&x, &make(0.8), 256).expect("valid");
142        assert!(low > high, "less noise {low} should beat more noise {high}");
143    }
144
145    #[test]
146    fn rejects_bad_parameters() {
147        let x = tone(512, 10.0);
148        assert_eq!(segmental_snr(&x, &x, 0), Err(AudioError::InvalidParameter));
149        assert_eq!(
150            segmental_snr(&x, &x[..256], 128),
151            Err(AudioError::InvalidParameter)
152        );
153        let short = tone(100, 5.0);
154        assert_eq!(
155            segmental_snr(&short, &short, 256),
156            Err(AudioError::MalformedAudio)
157        );
158    }
159}