Skip to main content

qualia_audio/features/spectral/
power_spectrum.rs

1//! Power spectrum of a windowed real frame (magnitude spectrum, squared).
2
3use crate::features::fft::real_fft_magnitude;
4use crate::types::AudioError;
5
6/// Power spectrum of `N` real (already-windowed) samples.
7///
8/// A thin wrapper over [`real_fft_magnitude`]: it produces the `N/2 + 1`
9/// one-sided magnitude bins `|X[k]|` and then squares each in place, so
10/// `out_power[k] == |X[k]|^2`.
11///
12/// - `input`: `N` real samples, `N` a power of two.
13/// - `scratch`: exactly `2 * N` floats, clobbered on return.
14/// - `out_power`: at least `N/2 + 1` floats; bins `0..=N/2` are written.
15///
16/// Zero-heap: all working storage is caller-supplied.
17///
18/// # Errors
19/// - [`AudioError::InvalidParameter`] if `N` is 0 or not a power of two.
20/// - [`AudioError::OutputBufferTooSmall`] if `scratch` or `out_power` are short.
21pub fn power_spectrum(
22    input: &[f32],
23    scratch: &mut [f32],
24    out_power: &mut [f32],
25) -> Result<(), AudioError> {
26    real_fft_magnitude(input, scratch, out_power)?;
27    let bins = input.len() / 2 + 1;
28    for p in out_power.iter_mut().take(bins) {
29        *p *= *p;
30    }
31    Ok(())
32}
33
34#[cfg(test)]
35mod tests {
36    use super::*;
37    use core::f32::consts::TAU;
38
39    #[test]
40    fn dc_power_is_magnitude_squared() {
41        let n = 16usize;
42        let input = vec![1.0f32; n];
43        let mut scratch = vec![0.0f32; 2 * n];
44        let mut power = vec![0.0f32; n / 2 + 1];
45        power_spectrum(&input, &mut scratch, &mut power).expect("power");
46        // DC magnitude == n, so DC power == n^2.
47        assert!((power[0] - (n * n) as f32).abs() < 1e-2, "dc={}", power[0]);
48        for p in &power[1..] {
49            assert!(*p < 1e-3);
50        }
51    }
52
53    #[test]
54    fn tone_power_concentrates_in_bin() {
55        let n = 1024usize;
56        let fs = 44_100.0f32;
57        let k0 = 40usize;
58        let freq = k0 as f32 * fs / n as f32;
59        let input: Vec<f32> = (0..n).map(|i| (TAU * freq * i as f32 / fs).cos()).collect();
60        let mut scratch = vec![0.0f32; 2 * n];
61        let mut power = vec![0.0f32; n / 2 + 1];
62        power_spectrum(&input, &mut scratch, &mut power).expect("power");
63        let mut peak = 1usize;
64        for (b, p) in power.iter().enumerate().skip(1) {
65            if *p > power[peak] {
66                peak = b;
67            }
68        }
69        assert_eq!(peak, k0, "peak power in bin {k0}, found {peak}");
70        // Power is non-negative everywhere.
71        assert!(power.iter().all(|p| *p >= 0.0));
72    }
73
74    #[test]
75    fn rejects_non_power_of_two() {
76        let input = vec![0.0f32; 6];
77        let mut scratch = vec![0.0f32; 12];
78        let mut power = vec![0.0f32; 4];
79        assert_eq!(
80            power_spectrum(&input, &mut scratch, &mut power),
81            Err(AudioError::InvalidParameter)
82        );
83    }
84}