Skip to main content

qualia_audio/features/spectral/
complexity.rs

1//! Spectral complexity — count of significant peaks in a magnitude spectrum.
2
3use crate::features::peaks::detect_peaks;
4use crate::types::AudioError;
5
6/// Spectral complexity of a one-sided magnitude spectrum `mag`.
7///
8/// Complexity is the number of significant spectral peaks: local maxima at or
9/// above `threshold`, no two closer than `min_distance` bins (the weaker of a
10/// too-close pair is dropped). A pure tone yields ~1; a dense, noisy, or
11/// polyphonic spectrum yields many. Implemented over
12/// [`detect_peaks`].
13///
14/// `scratch_pos` / `scratch_mag` are caller-supplied working buffers (they
15/// receive the peak positions and magnitudes as a side effect); their common
16/// length bounds how many peaks can be counted.
17///
18/// Zero-heap: all storage is caller-supplied.
19///
20/// # Errors
21/// - [`AudioError::InvalidParameter`] if `threshold` is not finite.
22/// - [`AudioError::OutputBufferTooSmall`] if more significant peaks are present
23///   than the scratch buffers can hold.
24pub fn spectral_complexity(
25    mag: &[f32],
26    threshold: f32,
27    min_distance: usize,
28    scratch_pos: &mut [f32],
29    scratch_mag: &mut [f32],
30) -> Result<usize, AudioError> {
31    detect_peaks(mag, threshold, min_distance, scratch_pos, scratch_mag)
32}
33
34#[cfg(test)]
35mod tests {
36    use super::*;
37
38    #[test]
39    fn single_tone_low_complexity() {
40        // One resolved peak in an otherwise quiet spectrum.
41        let mut mag = [0.0f32; 32];
42        mag[9] = 0.5;
43        mag[10] = 1.0;
44        mag[11] = 0.5;
45        let mut pos = [0.0f32; 8];
46        let mut mg = [0.0f32; 8];
47        let c = spectral_complexity(&mag, 0.25, 1, &mut pos, &mut mg).expect("complexity");
48        assert_eq!(c, 1, "complexity={c}");
49    }
50
51    #[test]
52    fn polyphonic_higher_complexity() {
53        // Three well-separated peaks.
54        let mut mag = [0.0f32; 32];
55        for c in [5usize, 15, 25] {
56            mag[c - 1] = 0.4;
57            mag[c] = 1.0;
58            mag[c + 1] = 0.4;
59        }
60        let mut pos = [0.0f32; 8];
61        let mut mg = [0.0f32; 8];
62        let c = spectral_complexity(&mag, 0.25, 1, &mut pos, &mut mg).expect("complexity");
63        assert_eq!(c, 3, "complexity={c}");
64    }
65
66    #[test]
67    fn threshold_suppresses_weak_peaks() {
68        let mut mag = [0.0f32; 32];
69        mag[5] = 0.1; // weak
70        mag[15] = 1.0; // strong
71        let mut pos = [0.0f32; 8];
72        let mut mg = [0.0f32; 8];
73        let c = spectral_complexity(&mag, 0.5, 1, &mut pos, &mut mg).expect("complexity");
74        assert_eq!(c, 1, "complexity={c}");
75    }
76
77    #[test]
78    fn rejects_nan_threshold() {
79        let mag = [0.0f32, 1.0, 0.0];
80        let mut pos = [0.0f32; 2];
81        let mut mg = [0.0f32; 2];
82        assert_eq!(
83            spectral_complexity(&mag, f32::NAN, 1, &mut pos, &mut mg),
84            Err(AudioError::InvalidParameter)
85        );
86    }
87}