Skip to main content

qualia_audio/aqa/intrusive/
log_spectral_distance.rs

1//! Log-spectral distance (LSD) between a reference and a degraded magnitude
2//! spectrum.
3//!
4//! LSD is the classic intrusive spectral-envelope error: the root-mean-square,
5//! over frequency bins, of the difference between the two log-magnitude spectra,
6//! expressed in dB. Zero for identical spectra; grows with envelope mismatch.
7//!
8//! This operates on already-computed magnitude spectra (e.g. from
9//! [`crate::features::fft::real_fft_magnitude`]) so it stays pure, allocation-free
10//! and reusable per-frame. Caller supplies both magnitude slices; a single scalar
11//! is returned.
12
13use crate::types::AudioError;
14
15/// Log-spectral distance in dB between two magnitude spectra.
16///
17/// - `reference_mag`: reference magnitude spectrum (`|X_ref[k]|`, linear, ≥ 0).
18/// - `degraded_mag`: degraded magnitude spectrum, same number of bins.
19///
20/// Each bin is converted to a power dB value `10*log10(mag^2 + eps)` (equivalently
21/// `20*log10(mag)` with a small floor to bound silence), and the result is
22/// `sqrt(mean_k (dB_ref[k] - dB_deg[k])^2)`.
23///
24/// Returns [`AudioError::InvalidParameter`] if the slices are empty or of
25/// differing length.
26pub fn log_spectral_distance(
27    reference_mag: &[f32],
28    degraded_mag: &[f32],
29) -> Result<f32, AudioError> {
30    if reference_mag.is_empty() || reference_mag.len() != degraded_mag.len() {
31        return Err(AudioError::InvalidParameter);
32    }
33
34    // Power floor: bins below this are treated as silence, bounding the log so a
35    // zero-vs-zero comparison is 0 dB rather than -inf. -100 dB-ish floor.
36    const POWER_EPS: f32 = 1.0e-10;
37
38    let mut acc = 0.0f32;
39    for k in 0..reference_mag.len() {
40        let pr = reference_mag[k] * reference_mag[k] + POWER_EPS;
41        let pd = degraded_mag[k] * degraded_mag[k] + POWER_EPS;
42        let db_ref = 10.0 * pr.log10();
43        let db_deg = 10.0 * pd.log10();
44        let diff = db_ref - db_deg;
45        acc += diff * diff;
46    }
47
48    Ok((acc / reference_mag.len() as f32).sqrt())
49}
50
51#[cfg(test)]
52mod tests {
53    use super::*;
54
55    #[test]
56    fn identical_spectra_are_zero() {
57        let mag = [0.0, 1.0, 4.0, 2.0, 0.5, 0.0, 3.0, 1.5];
58        let lsd = log_spectral_distance(&mag, &mag).expect("valid");
59        assert!(lsd.abs() < 1e-3, "identical LSD should be ~0, got {lsd}");
60    }
61
62    #[test]
63    fn different_spectra_are_positive_and_grow() {
64        let a = [1.0f32, 2.0, 3.0, 4.0];
65        // A 6 dB-per-bin level offset (factor 2 in magnitude ≈ 6.02 dB power).
66        let b: Vec<f32> = a.iter().map(|&v| v * 2.0).collect();
67        let lsd_small = log_spectral_distance(&a, &b).expect("valid");
68        assert!(lsd_small > 0.0, "different spectra must be positive");
69
70        // A bigger offset (factor 8 ≈ 18 dB) must yield a larger distance.
71        let c: Vec<f32> = a.iter().map(|&v| v * 8.0).collect();
72        let lsd_big = log_spectral_distance(&a, &c).expect("valid");
73        assert!(
74            lsd_big > lsd_small,
75            "larger spectral mismatch {lsd_big} must exceed smaller {lsd_small}"
76        );
77
78        // A uniform factor-of-2 offset is ~6.02 dB on every bin → RMS ≈ 6.02.
79        assert!(
80            (lsd_small - 6.02).abs() < 0.2,
81            "uniform 6 dB offset LSD ≈ 6.02, got {lsd_small}"
82        );
83    }
84
85    #[test]
86    fn rejects_bad_shapes() {
87        assert_eq!(
88            log_spectral_distance(&[], &[]),
89            Err(AudioError::InvalidParameter)
90        );
91        assert_eq!(
92            log_spectral_distance(&[1.0, 2.0], &[1.0]),
93            Err(AudioError::InvalidParameter)
94        );
95    }
96}