Skip to main content

qualia_audio/features/mel/
mel_bands.rs

1//! `mel_bands` — apply a precomputed triangular bank to one power (or magnitude)
2//! spectrum frame, allocation-free (the zero-heap hot path).
3
4use crate::types::AudioError;
5
6/// Apply a `n_mel × n_fft_bins` bank (row-major, from
7/// [`super::mel_bank::build_mel_bank`]) to one `power_spectrum` frame.
8///
9/// For each filter row `m`, computes the dot product `Σ_b bank[m,b] * power[b]`
10/// and writes it to `out[m]`. This is a pure matrix-vector apply: no allocation,
11/// no logarithm (callers wanting log-mel take `ln` themselves, or use
12/// [`super::mfcc::mfcc`]). The number of FFT bins is inferred from
13/// `bank_weights.len() / n_mel`, and `power_spectrum` must cover at least that many.
14///
15/// Returns [`AudioError::InvalidParameter`] if `n_mel == 0` or the bank length is
16/// not a positive multiple of `n_mel`, and [`AudioError::OutputBufferTooSmall`] if
17/// `out` is shorter than `n_mel` or `power_spectrum` is shorter than the bank width.
18pub fn mel_bands(
19    power_spectrum: &[f32],
20    bank_weights: &[f32],
21    n_mel: usize,
22    out: &mut [f32],
23) -> Result<(), AudioError> {
24    if n_mel == 0 || bank_weights.is_empty() || bank_weights.len() % n_mel != 0 {
25        return Err(AudioError::InvalidParameter);
26    }
27    let n_fft_bins = bank_weights.len() / n_mel;
28    if out.len() < n_mel || power_spectrum.len() < n_fft_bins {
29        return Err(AudioError::OutputBufferTooSmall);
30    }
31
32    for m in 0..n_mel {
33        let row = &bank_weights[m * n_fft_bins..(m + 1) * n_fft_bins];
34        let mut acc = 0.0f32;
35        for (w, p) in row.iter().zip(power_spectrum.iter()) {
36            acc += w * p;
37        }
38        out[m] = acc;
39    }
40    Ok(())
41}
42
43#[cfg(test)]
44mod tests {
45    use super::*;
46    use crate::features::mel::mel_bank::build_mel_bank;
47
48    #[test]
49    fn flat_spectrum_gives_nonzero_bands() {
50        let n_bins = 257;
51        let n_mel = 20;
52        let mut bank = vec![0.0f32; n_mel * n_bins];
53        build_mel_bank(n_bins, n_mel, 16_000.0, 0.0, 8000.0, &mut bank).unwrap();
54        let power = vec![1.0f32; n_bins];
55        let mut out = vec![0.0f32; n_mel];
56        mel_bands(&power, &bank, n_mel, &mut out).unwrap();
57        for (m, &e) in out.iter().enumerate() {
58            assert!(
59                e > 0.0,
60                "band {m} energy should be positive under flat input"
61            );
62        }
63    }
64
65    #[test]
66    fn tone_lands_in_a_single_band_region() {
67        // Delta at a specific bin should energise the bands whose triangles cover it.
68        let n_bins = 257;
69        let n_mel = 20;
70        let sr = 16_000.0;
71        let mut bank = vec![0.0f32; n_mel * n_bins];
72        build_mel_bank(n_bins, n_mel, sr, 0.0, 8000.0, &mut bank).unwrap();
73        let mut power = vec![0.0f32; n_bins];
74        power[128] = 5.0; // ~4 kHz
75        let mut out = vec![0.0f32; n_mel];
76        mel_bands(&power, &bank, n_mel, &mut out).unwrap();
77        let total: f32 = out.iter().sum();
78        assert!(total > 0.0);
79        // At most a couple of adjacent bands should carry the delta.
80        let active = out.iter().filter(|&&e| e > 1e-4).count();
81        assert!(active <= 3, "delta spread across too many bands: {active}");
82    }
83
84    #[test]
85    fn rejects_short_out() {
86        let bank = vec![0.0f32; 40];
87        let power = vec![0.0f32; 20];
88        let mut out = vec![0.0f32; 1];
89        assert_eq!(
90            mel_bands(&power, &bank, 2, &mut out),
91            Err(AudioError::OutputBufferTooSmall)
92        );
93    }
94}