Skip to main content

qualia_audio/features/loudness/
dynamic_complexity.rs

1//! Dynamic complexity — average absolute deviation of loudness over time.
2//!
3//! Given a per-frame loudness series (dB or LUFS), dynamic complexity is the
4//! mean absolute deviation of the frames from their own mean: a low value means
5//! a consistent level, a high value means large loudness swings. Zero-heap
6//! (two scalar passes, no allocation).
7
8/// Average absolute deviation of a loudness series from its mean.
9///
10/// Returns `0.0` for an empty series or a single frame. Non-finite frames
11/// (e.g. `−inf` for silent frames) are ignored so a stray silent frame does not
12/// blow the statistic to infinity.
13pub fn dynamic_complexity(loudness_frames: &[f32]) -> f32 {
14    let mut mean = 0.0f64;
15    let mut n = 0u64;
16    for &l in loudness_frames {
17        if l.is_finite() {
18            mean += l as f64;
19            n += 1;
20        }
21    }
22    if n < 2 {
23        return 0.0;
24    }
25    mean /= n as f64;
26
27    let mut dev = 0.0f64;
28    for &l in loudness_frames {
29        if l.is_finite() {
30            dev += (l as f64 - mean).abs();
31        }
32    }
33    (dev / n as f64) as f32
34}
35
36#[cfg(test)]
37mod tests {
38    use super::*;
39
40    #[test]
41    fn constant_level_has_zero_complexity() {
42        assert!(dynamic_complexity(&[-18.0; 64]).abs() < 1e-6);
43    }
44
45    #[test]
46    fn symmetric_swing_matches_closed_form() {
47        // [−10, −20, −10, −20]: mean −15, each |dev| = 5 → MAD = 5.
48        let c = dynamic_complexity(&[-10.0, -20.0, -10.0, -20.0]);
49        assert!((c - 5.0).abs() < 1e-6, "complexity {c}");
50    }
51
52    #[test]
53    fn empty_and_single_are_zero() {
54        assert_eq!(dynamic_complexity(&[]), 0.0);
55        assert_eq!(dynamic_complexity(&[-12.0]), 0.0);
56    }
57
58    #[test]
59    fn silent_frames_ignored() {
60        // The −inf frame must not poison the deviation.
61        let c = dynamic_complexity(&[-10.0, f32::NEG_INFINITY, -20.0, -10.0, -20.0]);
62        assert!((c - 5.0).abs() < 1e-6, "complexity {c}");
63    }
64}