qualia_audio/features/rhythm/
beat_tracker.rs1use crate::features::peaks::detect_peaks;
7use crate::features::rhythm::tempogram::tempogram;
8use crate::types::AudioError;
9
10const BPM_MIN: f32 = 40.0;
13const BPM_MAX: f32 = 240.0;
14const SAL_BINS: usize = 201;
16const ACF_CAP: usize = 4096;
18const MAX_PEAKS: usize = 101;
20
21pub fn track_beats(
45 onset_env: &[f32],
46 frame_rate_hz: f32,
47 out_beat_frames: &mut [u32],
48) -> Result<(usize, f32), AudioError> {
49 if onset_env.is_empty() || !(frame_rate_hz > 0.0) {
50 return Err(AudioError::InvalidParameter);
51 }
52
53 let eff_bpm_min = BPM_MIN.max(frame_rate_hz * 60.0 / ((ACF_CAP - 2) as f32));
55 if !(eff_bpm_min < BPM_MAX) {
56 return Err(AudioError::InvalidParameter);
57 }
58
59 let mut sal = [0.0f32; SAL_BINS];
60 let mut scratch = [0.0f32; ACF_CAP];
61 let bins = tempogram(
62 onset_env,
63 frame_rate_hz,
64 eff_bpm_min,
65 BPM_MAX,
66 &mut sal,
67 &mut scratch,
68 )?;
69
70 let mut pos = [0.0f32; MAX_PEAKS];
72 let mut mag = [0.0f32; MAX_PEAKS];
73 let peak_bin = match detect_peaks(&sal[..bins], 0.0, 2, &mut pos, &mut mag) {
74 Ok(np) if np > 0 => {
75 let mut best = 0usize;
76 for k in 1..np {
77 if mag[k] > mag[best] {
78 best = k;
79 }
80 }
81 pos[best]
82 }
83 _ => {
85 let mut best = 0usize;
86 for b in 1..bins {
87 if sal[b] > sal[best] {
88 best = b;
89 }
90 }
91 best as f32
92 }
93 };
94
95 let bpm = if bins > 1 {
96 eff_bpm_min + (BPM_MAX - eff_bpm_min) * peak_bin / ((bins - 1) as f32)
97 } else {
98 eff_bpm_min
99 };
100 if !(bpm > 0.0) {
101 return Err(AudioError::InvalidParameter);
102 }
103
104 let period = frame_rate_hz * 60.0 / bpm;
105 let n_beats = place_beats(onset_env, period, out_beat_frames)?;
106 Ok((n_beats, bpm))
107}
108
109fn place_beats(onset_env: &[f32], period: f32, out: &mut [u32]) -> Result<usize, AudioError> {
113 let len = onset_env.len();
114 let step = period.max(1.0);
115 let p_round = (step.round() as usize).max(1);
116
117 let mut best_off = 0usize;
119 let mut best_score = f32::NEG_INFINITY;
120 for off in 0..p_round {
121 let mut score = 0.0f32;
122 let mut p = off as f32;
123 loop {
124 let idx = p.round() as usize;
125 if idx >= len {
126 break;
127 }
128 score += onset_env[idx];
129 p += step;
130 }
131 if score > best_score {
132 best_score = score;
133 best_off = off;
134 }
135 }
136
137 let mut w = 0usize;
139 let mut p = best_off as f32;
140 loop {
141 let idx = p.round() as usize;
142 if idx >= len {
143 break;
144 }
145 if w == out.len() {
146 return Err(AudioError::OutputBufferTooSmall);
147 }
148 out[w] = idx as u32;
149 w += 1;
150 p += step;
151 }
152 Ok(w)
153}
154
155#[cfg(test)]
156mod tests {
157 use super::*;
158
159 fn click_train(n: usize, period: usize) -> Vec<f32> {
161 let mut env = vec![0.0f32; n];
162 let mut i = 0;
163 while i < n {
164 env[i] = 1.0;
165 i += period;
166 }
167 env
168 }
169
170 #[test]
172 fn recovers_120_bpm() {
173 let frame_rate = 100.0f32; let period = 50usize; let env = click_train(1000, period);
176 let mut beats = [0u32; 64];
177 let (n_beats, bpm) = track_beats(&env, frame_rate, &mut beats).expect("track");
178 assert!(
179 (bpm - 120.0).abs() <= 120.0 * 0.05,
180 "bpm = {bpm} (want ~120)"
181 );
182 assert_eq!(n_beats, 20, "n_beats = {n_beats}");
184 assert_eq!(beats[0], 0);
186 assert_eq!(beats[1], 50);
187 assert_eq!(beats[2], 100);
188 }
189
190 #[test]
192 fn recovers_100_bpm() {
193 let frame_rate = 100.0f32;
194 let period = 60usize; let env = click_train(1200, period);
196 let mut beats = [0u32; 64];
197 let (_n, bpm) = track_beats(&env, frame_rate, &mut beats).expect("track");
198 assert!(
199 (bpm - 100.0).abs() <= 100.0 * 0.05,
200 "bpm = {bpm} (want ~100)"
201 );
202 }
203
204 #[test]
206 fn phase_locks_to_offset_onsets() {
207 let frame_rate = 100.0f32;
208 let period = 50usize;
209 let mut env = vec![0.0f32; 1000];
211 let mut i = 17usize;
212 while i < 1000 {
213 env[i] = 1.0;
214 i += period;
215 }
216 let mut beats = [0u32; 64];
217 let (n_beats, bpm) = track_beats(&env, frame_rate, &mut beats).expect("track");
218 assert!((bpm - 120.0).abs() <= 120.0 * 0.05, "bpm = {bpm}");
219 assert!(n_beats > 0);
220 assert_eq!(beats[0], 17, "first beat phase = {}", beats[0]);
221 }
222
223 #[test]
224 fn rejects_bad_input() {
225 let mut beats = [0u32; 8];
226 assert_eq!(
227 track_beats(&[], 100.0, &mut beats),
228 Err(AudioError::InvalidParameter)
229 );
230 let env = [1.0f32, 0.0, 1.0];
231 assert_eq!(
232 track_beats(&env, 0.0, &mut beats),
233 Err(AudioError::InvalidParameter)
234 );
235 }
236
237 #[test]
238 fn beat_buffer_too_small_errors() {
239 let env = click_train(1000, 50);
240 let mut beats = [0u32; 4]; assert_eq!(
242 track_beats(&env, 100.0, &mut beats),
243 Err(AudioError::OutputBufferTooSmall)
244 );
245 }
246
247 #[test]
248 fn silence_bounds_gracefully() {
249 let env = vec![1.0f32; 500];
252 let mut beats = [0u32; 512];
253 let res = track_beats(&env, 100.0, &mut beats);
254 assert!(res.is_ok());
255 let (_n, bpm) = res.expect("ok");
256 assert!(bpm >= BPM_MIN && bpm <= BPM_MAX, "bpm = {bpm}");
257 }
258}