Skip to main content

qualia_audio/features/mel/
erb_bank.rs

1//! `build_erb_bank` — triangular filterbank on the ERB-rate scale (Glasberg &
2//! Moore 1990), with ERB conversions delegated to [`etalon_signal::loudness`].
3
4use crate::types::AudioError;
5
6/// Hz → ERB-rate number: `E = 21.4 * log10(1 + 0.00437*f)` (Glasberg & Moore).
7#[inline]
8fn hz_to_erb_rate(hz: f32) -> f32 {
9    etalon_signal::loudness::hz_to_erb(hz)
10}
11
12/// ERB-rate → Hz, inverse of [`hz_to_erb_rate`]: `f = (10^(E/21.4) - 1) / 0.00437`.
13#[inline]
14fn erb_rate_to_hz(erb: f32) -> f32 {
15    etalon_signal::loudness::erb_to_hz(erb)
16}
17
18/// Build a triangular ERB filterbank as a row-major `n_bands × n_fft_bins` weight table.
19pub fn build_erb_bank(
20    n_fft_bins: usize,
21    n_bands: usize,
22    sample_rate: f32,
23    fmin: f32,
24    fmax: f32,
25    weights_out: &mut [f32],
26) -> Result<(), AudioError> {
27    if n_fft_bins < 2 || n_bands == 0 || sample_rate <= 0.0 {
28        return Err(AudioError::InvalidParameter);
29    }
30    if weights_out.len() < n_bands * n_fft_bins {
31        return Err(AudioError::OutputBufferTooSmall);
32    }
33
34    let nyquist = sample_rate * 0.5;
35    let f_lo = fmin.max(0.0);
36    let f_hi = if fmax <= 0.0 || fmax > nyquist {
37        nyquist
38    } else {
39        fmax
40    };
41    if f_lo >= f_hi {
42        return Err(AudioError::InvalidParameter);
43    }
44
45    let e_lo = hz_to_erb_rate(f_lo);
46    let e_hi = hz_to_erb_rate(f_hi);
47    let step = (e_hi - e_lo) / (n_bands as f32 + 1.0);
48
49    let n_fft = 2 * (n_fft_bins - 1);
50    let hz_per_bin = sample_rate / n_fft as f32;
51
52    weights_out[..n_bands * n_fft_bins].fill(0.0);
53
54    for m in 0..n_bands {
55        let left = erb_rate_to_hz(e_lo + m as f32 * step);
56        let center = erb_rate_to_hz(e_lo + (m as f32 + 1.0) * step);
57        let right = erb_rate_to_hz(e_lo + (m as f32 + 2.0) * step);
58        let up = center - left;
59        let down = right - center;
60        let row = &mut weights_out[m * n_fft_bins..(m + 1) * n_fft_bins];
61        for (b, w) in row.iter_mut().enumerate() {
62            let f = b as f32 * hz_per_bin;
63            let tri = if f >= left && f <= center && up > 0.0 {
64                (f - left) / up
65            } else if f > center && f <= right && down > 0.0 {
66                (right - f) / down
67            } else {
68                0.0
69            };
70            *w = tri.max(0.0);
71        }
72    }
73    Ok(())
74}
75
76#[cfg(test)]
77mod tests {
78    use super::*;
79
80    #[test]
81    fn erb_scale_round_trips() {
82        for &hz in &[100.0f32, 500.0, 1000.0, 4000.0] {
83            let back = erb_rate_to_hz(hz_to_erb_rate(hz));
84            assert!((back - hz).abs() / hz < 1e-3, "{hz} -> {back}");
85        }
86    }
87
88    #[test]
89    fn erb_bandwidth_grows_with_frequency() {
90        let n_bins = 513;
91        let n_bands = 32;
92        let sr = 22_050.0;
93        let mut w = vec![0.0f32; n_bands * n_bins];
94        build_erb_bank(n_bins, n_bands, sr, 50.0, 0.0, &mut w).unwrap();
95        let width = |m: usize| {
96            w[m * n_bins..(m + 1) * n_bins]
97                .iter()
98                .filter(|&&v| v > 1e-4)
99                .count()
100        };
101        assert!(
102            width(n_bands - 2) > width(1),
103            "ERB bands do not widen with freq"
104        );
105    }
106
107    #[test]
108    fn erb_filters_peak_at_one() {
109        let n_bins = 2049;
110        let n_bands = 24;
111        let sr = 16_000.0;
112        let mut w = vec![0.0f32; n_bands * n_bins];
113        build_erb_bank(n_bins, n_bands, sr, 0.0, 8000.0, &mut w).unwrap();
114        for m in 0..n_bands {
115            let row = &w[m * n_bins..(m + 1) * n_bins];
116            let peak = row.iter().cloned().fold(0.0f32, f32::max);
117            let active = row.iter().filter(|&&v| v > 1e-4).count();
118            assert!(peak <= 1.0001, "band {m} peak exceeds 1: {peak}");
119            assert!(row.iter().all(|&v| v >= 0.0));
120            if active >= 4 {
121                assert!(
122                    peak > 0.9,
123                    "band {m} peak too low: {peak} (active {active})"
124                );
125            }
126        }
127    }
128}