qualia_audio/features/mel/
mel_bank.rs1use crate::features::mel::{hz_mel::hz_to_mel, mel_to_hz::mel_to_hz};
11use crate::types::AudioError;
12
13pub 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 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 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 let n_bins = 2049; 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 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 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 let n_bins = 8193; 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; 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}