Skip to main content

qualia_audio/features/spectral/
energy_band.rs

1//! Energy contained in a `[f_lo, f_hi]` frequency band.
2
3use crate::types::AudioError;
4
5/// Spectral energy of a one-sided magnitude spectrum `mag` within the frequency
6/// band `[f_lo, f_hi]` (Hz, inclusive).
7///
8/// `mag` spans DC..Nyquist inclusive, so bin `k` sits at
9/// `k · sample_rate / (2·(N-1))` Hz for an `N`-bin spectrum. Energy is the sum
10/// of squared magnitudes `Σ |X[k]|^2` over the bins whose centre frequency
11/// falls in `[f_lo, f_hi]`.
12///
13/// Zero-heap: single pass, scalar result.
14///
15/// # Errors
16/// - [`AudioError::InvalidParameter`] if `sample_rate` is not a positive finite,
17///   if `mag` has fewer than 2 bins, if `f_lo` is negative, or if
18///   `f_hi < f_lo`.
19pub fn energy_band(mag: &[f32], sample_rate: f32, f_lo: f32, f_hi: f32) -> Result<f32, AudioError> {
20    if sample_rate <= 0.0 || !sample_rate.is_finite() {
21        return Err(AudioError::InvalidParameter);
22    }
23    if mag.len() < 2 {
24        return Err(AudioError::InvalidParameter);
25    }
26    if f_lo < 0.0 || f_hi < f_lo || !f_lo.is_finite() || !f_hi.is_finite() {
27        return Err(AudioError::InvalidParameter);
28    }
29
30    let bin_hz = sample_rate as f64 / (2.0 * (mag.len() - 1) as f64);
31    let mut acc = 0.0f64;
32    for (k, m) in mag.iter().enumerate() {
33        let f = k as f64 * bin_hz;
34        if f >= f_lo as f64 && f <= f_hi as f64 {
35            acc += (*m as f64) * (*m as f64);
36        }
37    }
38    Ok(acc as f32)
39}
40
41#[cfg(test)]
42mod tests {
43    use super::*;
44
45    #[test]
46    fn sums_only_in_band() {
47        let sr = 8000.0f32;
48        // 9 bins -> fft 16 -> bin_hz = 8000/16 = 500 Hz. Bins at 0,500,...,4000.
49        let mut mag = [0.0f32; 9];
50        mag[2] = 2.0; // 1000 Hz -> in band
51        mag[4] = 3.0; // 2000 Hz -> in band
52        mag[7] = 5.0; // 3500 Hz -> out of band
53                      // Band [900, 2100] Hz captures bins 2 and 4 -> 4 + 9 = 13.
54        let e = energy_band(&mag, sr, 900.0, 2100.0).expect("energy");
55        assert!((e - 13.0).abs() < 1e-4, "energy={e}");
56    }
57
58    #[test]
59    fn full_band_is_total_energy() {
60        let sr = 8000.0f32;
61        let mag = [1.0f32, 1.0, 1.0, 1.0, 1.0];
62        let e = energy_band(&mag, sr, 0.0, 4000.0).expect("energy");
63        assert!((e - 5.0).abs() < 1e-4, "energy={e}");
64    }
65
66    #[test]
67    fn empty_band_is_zero() {
68        let sr = 8000.0f32;
69        let mag = [1.0f32; 5];
70        // Sub-bin window between bins -> no bin centre inside -> 0.
71        let e = energy_band(&mag, sr, 100.0, 200.0).expect("energy");
72        assert!(e.abs() < 1e-6, "energy={e}");
73    }
74
75    #[test]
76    fn rejects_bad_params() {
77        let mag = [1.0f32; 5];
78        assert_eq!(
79            energy_band(&mag, 0.0, 0.0, 100.0),
80            Err(AudioError::InvalidParameter)
81        );
82        assert_eq!(
83            energy_band(&mag, 8000.0, 200.0, 100.0),
84            Err(AudioError::InvalidParameter)
85        );
86        assert_eq!(
87            energy_band(&[1.0], 8000.0, 0.0, 100.0),
88            Err(AudioError::InvalidParameter)
89        );
90    }
91}