Skip to main content

qualia_audio/features/mel/
mel_bank.rs

1//! `build_mel_bank` — precompute a triangular mel filterbank into a caller-owned
2//! table. This REPLACES the fake linear-band "log_mel" averaging that lived in
3//! `stft_stream.rs`: the bank spaces filters on the perceptual HTK mel scale and
4//! places true triangular responses (peak 1.0 at each centre), overlapping into
5//! their neighbours — the standard Slaney/HTK filterbank geometry.
6//!
7//! Build once (cold path); apply per-frame allocation-free via
8//! [`super::mel_bands::mel_bands`].
9
10use crate::features::mel::{hz_mel::hz_to_mel, mel_to_hz::mel_to_hz};
11use crate::types::AudioError;
12
13/// Build a triangular mel filterbank as a row-major `n_mel × n_fft_bins` table of
14/// weights, written into `weights_out`.
15///
16/// - `n_fft_bins`: number of magnitude/power bins per frame (`n_fft/2 + 1`).
17/// - `n_mel`: number of mel filters (rows).
18/// - `sample_rate`: sampling rate in Hz (used to map each FFT bin to a frequency).
19/// - `fmin` / `fmax`: passband edges in Hz (`fmax <= 0` or above Nyquist → Nyquist).
20/// - `weights_out`: at least `n_mel * n_fft_bins` floats; fully overwritten.
21///
22/// Each filter `m` rises linearly from its lower edge to its centre (peak 1.0),
23/// then falls to its upper edge; centres are equally spaced in mel between `fmin`
24/// and `fmax`, so adjacent triangles share an edge and overlap. Weights are
25/// non-negative. Returns [`AudioError::InvalidParameter`] on degenerate sizes /
26/// rates and [`AudioError::OutputBufferTooSmall`] if `weights_out` is short.
27pub fn build_mel_bank(
28    n_fft_bins: usize,
29    n_mel: usize,
30    sample_rate: f32,
31    fmin: f32,
32    fmax: f32,
33    weights_out: &mut [f32],
34) -> Result<(), AudioError> {
35    if n_fft_bins < 2 || n_mel == 0 || sample_rate <= 0.0 {
36        return Err(AudioError::InvalidParameter);
37    }
38    if weights_out.len() < n_mel * n_fft_bins {
39        return Err(AudioError::OutputBufferTooSmall);
40    }
41
42    let nyquist = sample_rate * 0.5;
43    let f_lo = fmin.max(0.0);
44    let f_hi = if fmax <= 0.0 || fmax > nyquist {
45        nyquist
46    } else {
47        fmax
48    };
49    if f_lo >= f_hi {
50        return Err(AudioError::InvalidParameter);
51    }
52
53    // `n_mel + 2` mel-spaced edge frequencies: edges[m], edges[m+1]=centre, edges[m+2].
54    let mel_lo = hz_to_mel(f_lo);
55    let mel_hi = hz_to_mel(f_hi);
56    let mel_step = (mel_hi - mel_lo) / (n_mel as f32 + 1.0);
57
58    // FFT-bin spacing in Hz: bin b sits at b * sample_rate / n_fft, n_fft = 2*(bins-1).
59    let n_fft = 2 * (n_fft_bins - 1);
60    let hz_per_bin = sample_rate / n_fft as f32;
61
62    weights_out[..n_mel * n_fft_bins].fill(0.0);
63
64    for m in 0..n_mel {
65        let left = mel_to_hz(mel_lo + m as f32 * mel_step);
66        let center = mel_to_hz(mel_lo + (m as f32 + 1.0) * mel_step);
67        let right = mel_to_hz(mel_lo + (m as f32 + 2.0) * mel_step);
68        let up = center - left;
69        let down = right - center;
70        let row = &mut weights_out[m * n_fft_bins..(m + 1) * n_fft_bins];
71        for (b, w) in row.iter_mut().enumerate() {
72            let f = b as f32 * hz_per_bin;
73            let tri = if f >= left && f <= center && up > 0.0 {
74                (f - left) / up
75            } else if f > center && f <= right && down > 0.0 {
76                (right - f) / down
77            } else {
78                0.0
79            };
80            *w = tri.max(0.0);
81        }
82    }
83    Ok(())
84}
85
86#[cfg(test)]
87mod tests {
88    use super::*;
89
90    fn argmax(row: &[f32]) -> usize {
91        let mut best = 0usize;
92        for (b, &v) in row.iter().enumerate() {
93            if v > row[best] {
94                best = b;
95            }
96        }
97        best
98    }
99
100    #[test]
101    fn filters_peak_at_one_and_are_nonnegative() {
102        // High FFT resolution so the analytic triangle is well sampled: every
103        // filter reaches ≈1.0 at its centre and none exceeds 1.0.
104        let n_bins = 2049; // n_fft = 4096
105        let n_mel = 20;
106        let sr = 16_000.0;
107        let mut w = vec![0.0f32; n_mel * n_bins];
108        build_mel_bank(n_bins, n_mel, sr, 0.0, 8000.0, &mut w).unwrap();
109
110        for m in 0..n_mel {
111            let row = &w[m * n_bins..(m + 1) * n_bins];
112            let peak = row.iter().cloned().fold(0.0f32, f32::max);
113            let active = row.iter().filter(|&&v| v > 1e-4).count();
114            // Ceiling always holds; non-negativity always holds.
115            assert!(peak <= 1.0001, "filter {m} peak exceeds 1: {peak}");
116            for &v in row {
117                assert!(v >= 0.0, "negative weight in filter {m}");
118            }
119            // A well-resolved filter (spanning several bins) reaches ~1.0 at its centre.
120            if active >= 4 {
121                assert!(
122                    peak > 0.9,
123                    "filter {m} peak too low: {peak} (active {active})"
124                );
125            }
126        }
127    }
128
129    #[test]
130    fn peak_converges_to_one_at_the_centre() {
131        // The analytic triangle peaks at 1.0 at its centre; with fine FFT resolution
132        // a bin lands ~on the centre, so the sampled peak → 1.0 (and never exceeds it).
133        let n_bins = 8193; // n_fft = 16384, hz/bin ≈ 0.977
134        let sr = 16_000.0;
135        let mut w = vec![0.0f32; n_bins];
136        build_mel_bank(n_bins, 1, sr, 0.0, 8000.0, &mut w).unwrap();
137        let peak = w.iter().cloned().fold(0.0f32, f32::max);
138        assert!(
139            peak > 0.999 && peak <= 1.0001,
140            "centre peak not ~1.0: {peak}"
141        );
142    }
143
144    #[test]
145    fn adjacent_filters_overlap() {
146        let n_bins = 257;
147        let n_mel = 26;
148        let sr = 16_000.0;
149        let mut w = vec![0.0f32; n_mel * n_bins];
150        build_mel_bank(n_bins, n_mel, sr, 0.0, 8000.0, &mut w).unwrap();
151
152        let mut overlap_found = false;
153        for b in 0..n_bins {
154            for m in 0..n_mel - 1 {
155                if w[m * n_bins + b] > 1e-4 && w[(m + 1) * n_bins + b] > 1e-4 {
156                    overlap_found = true;
157                }
158            }
159        }
160        assert!(overlap_found, "adjacent mel filters never overlap");
161    }
162
163    #[test]
164    fn centres_ascend_in_frequency() {
165        let n_bins = 513; // n_fft = 1024
166        let n_mel = 40;
167        let sr = 22_050.0;
168        let mut w = vec![0.0f32; n_mel * n_bins];
169        build_mel_bank(n_bins, n_mel, sr, 0.0, 0.0, &mut w).unwrap();
170        let mut last = 0usize;
171        for m in 0..n_mel {
172            let a = argmax(&w[m * n_bins..(m + 1) * n_bins]);
173            assert!(a >= last, "filter {m} centre bin {a} < prev {last}");
174            last = a;
175        }
176    }
177
178    #[test]
179    fn rejects_small_output() {
180        let mut w = vec![0.0f32; 10];
181        assert_eq!(
182            build_mel_bank(257, 26, 16_000.0, 0.0, 8000.0, &mut w),
183            Err(AudioError::OutputBufferTooSmall)
184        );
185    }
186}