Skip to main content

qualia_audio/features/spectral/
log_spectrum.rs

1//! Log-magnitude spectrum into a caller buffer (dB).
2
3use crate::types::AudioError;
4
5/// Convert a one-sided magnitude spectrum `mag` to a log-magnitude (dB)
6/// spectrum written into `out_log`.
7///
8/// Each bin becomes `20·log10(max(|X[k]|, floor_linear))` dB, where
9/// `floor_linear = 10^(floor_db / 20)`. The floor bounds silent bins so their
10/// dB value clamps to `floor_db` instead of `-inf`.
11///
12/// Zero-heap: single pass into the caller-supplied `out_log`.
13///
14/// # Errors
15/// - [`AudioError::InvalidParameter`] if `floor_db` is not finite.
16/// - [`AudioError::OutputBufferTooSmall`] if `out_log` is shorter than `mag`.
17pub fn log_spectrum(mag: &[f32], floor_db: f32, out_log: &mut [f32]) -> Result<usize, AudioError> {
18    if !floor_db.is_finite() {
19        return Err(AudioError::InvalidParameter);
20    }
21    if out_log.len() < mag.len() {
22        return Err(AudioError::OutputBufferTooSmall);
23    }
24    let floor_linear = 10.0f32.powf(floor_db / 20.0);
25    for (o, m) in out_log.iter_mut().zip(mag.iter()) {
26        *o = 20.0 * m.abs().max(floor_linear).log10();
27    }
28    Ok(mag.len())
29}
30
31#[cfg(test)]
32mod tests {
33    use super::*;
34
35    #[test]
36    fn unit_magnitude_is_zero_db() {
37        let mag = [1.0f32, 1.0, 1.0];
38        let mut out = [0.0f32; 3];
39        let n = log_spectrum(&mag, -120.0, &mut out).expect("log");
40        assert_eq!(n, 3);
41        for o in out {
42            assert!(o.abs() < 1e-4, "dB={o}");
43        }
44    }
45
46    #[test]
47    fn tenfold_is_twenty_db() {
48        // 10.0 -> 20 dB, 0.1 -> -20 dB.
49        let mag = [10.0f32, 0.1];
50        let mut out = [0.0f32; 2];
51        log_spectrum(&mag, -120.0, &mut out).expect("log");
52        assert!((out[0] - 20.0).abs() < 1e-3, "{}", out[0]);
53        assert!((out[1] + 20.0).abs() < 1e-3, "{}", out[1]);
54    }
55
56    #[test]
57    fn floor_clamps_silence() {
58        let mag = [0.0f32, 1.0];
59        let mut out = [0.0f32; 2];
60        log_spectrum(&mag, -80.0, &mut out).expect("log");
61        assert!((out[0] + 80.0).abs() < 1e-3, "floored={}", out[0]);
62        assert!(out[1].abs() < 1e-4, "unit={}", out[1]);
63    }
64
65    #[test]
66    fn rejects_small_output() {
67        let mag = [1.0f32; 4];
68        let mut out = [0.0f32; 3];
69        assert_eq!(
70            log_spectrum(&mag, -120.0, &mut out),
71            Err(AudioError::OutputBufferTooSmall)
72        );
73    }
74
75    #[test]
76    fn rejects_nonfinite_floor() {
77        let mag = [1.0f32; 2];
78        let mut out = [0.0f32; 2];
79        assert_eq!(
80            log_spectrum(&mag, f32::INFINITY, &mut out),
81            Err(AudioError::InvalidParameter)
82        );
83    }
84}