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}