Skip to main content

qualia_audio/features/mel/
bark_bank.rs

1//! `build_bark_bank` — triangular filterbank on the Bark critical-band scale
2//! (Traunmüller 1990), with Bark scale conversions delegated to [`etalon_signal::loudness`].
3
4use crate::types::AudioError;
5
6/// Hz → Bark (Traunmüller): `z = 26.81*f/(1960+f) - 0.53`.
7#[inline]
8fn hz_to_bark(hz: f32) -> f32 {
9    etalon_signal::loudness::hz_to_bark(hz)
10}
11
12/// Bark → Hz, inverse of [`hz_to_bark`]: `f = 1960*z / (26.81 - z)` with `z = bark + 0.53`.
13#[inline]
14fn bark_to_hz(bark: f32) -> f32 {
15    etalon_signal::loudness::bark_to_hz(bark)
16}
17
18/// Build a triangular Bark filterbank as a row-major `n_bands × n_fft_bins` weight table.
19pub fn build_bark_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 b_lo = hz_to_bark(f_lo);
46    let b_hi = hz_to_bark(f_hi);
47    let step = (b_hi - b_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 = bark_to_hz(b_lo + m as f32 * step);
56        let center = bark_to_hz(b_lo + (m as f32 + 1.0) * step);
57        let right = bark_to_hz(b_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 bark_scale_round_trips() {
82        for &hz in &[100.0f32, 500.0, 1000.0, 4000.0] {
83            let back = bark_to_hz(hz_to_bark(hz));
84            assert!((back - hz).abs() / hz < 1e-3, "{hz} -> {back}");
85        }
86    }
87
88    #[test]
89    fn bark_filters_peak_at_one_and_overlap() {
90        let n_bins = 257;
91        let n_bands = 24;
92        let sr = 16_000.0;
93        let mut w = vec![0.0f32; n_bands * n_bins];
94        build_bark_bank(n_bins, n_bands, sr, 0.0, 8000.0, &mut w).unwrap();
95        for m in 0..n_bands {
96            let row = &w[m * n_bins..(m + 1) * n_bins];
97            let peak = row.iter().cloned().fold(0.0f32, f32::max);
98            assert!(peak > 0.85 && peak <= 1.0001, "band {m} peak {peak}");
99            assert!(row.iter().all(|&v| v >= 0.0));
100        }
101        let mut overlap = false;
102        for b in 0..n_bins {
103            for m in 0..n_bands - 1 {
104                if w[m * n_bins + b] > 1e-4 && w[(m + 1) * n_bins + b] > 1e-4 {
105                    overlap = true;
106                }
107            }
108        }
109        assert!(overlap, "bark bands do not overlap");
110    }
111}