qualia_audio/features/rhythm/spectral_flux_onset.rs
1//! Onset detection from consecutive magnitude frames via true spectral flux and
2//! a causal adaptive threshold. One public function; caller-buffered; zero-heap
3//! hot path (a bounded fixed-size stack ring is the only working state).
4
5use crate::features::spectral::spectral_flux;
6use crate::types::AudioError;
7
8/// Length of the causal moving-mean window (in flux frames) used to form the
9/// adaptive threshold. Fixed → the ring buffer lives on the stack.
10const THRESH_WINDOW: usize = 8;
11/// Adaptive-threshold multiplier applied to the causal mean flux.
12const LAMBDA: f32 = 1.5;
13/// A candidate must also exceed this fraction of the running-max flux, which
14/// rejects small ripples in near-silent stretches.
15const NOISE_FLOOR_FRAC: f32 = 0.10;
16/// Minimum spacing between accepted onsets, in frames (de-bounces one attack).
17const MIN_ONSET_GAP: usize = 3;
18
19/// Detect note/percussion onsets in a magnitude spectrogram.
20///
21/// `mags` is a row-major spectrogram of `n_frames` consecutive one-sided
22/// magnitude spectra, each `n_bins` long (frame `f` occupies
23/// `mags[f*n_bins .. (f+1)*n_bins]`), exactly the layout produced by
24/// [`crate::features::stft_stream::magnitude_stft_chunk`]. Between every
25/// adjacent pair of frames the **true per-bin** spectral flux
26/// (`Σ_k max(cur[k]-prev[k], 0)`, via [`spectral_flux`]) forms an onset novelty
27/// curve; the flux value for the transition `f-1 → f` is attributed to frame
28/// `f`.
29///
30/// A frame is emitted as an onset when its flux is a local maximum
31/// (`flux[f] > flux[f-1] && flux[f] >= flux[f+1]`), exceeds the adaptive
32/// threshold `LAMBDA · mean(previous THRESH_WINDOW flux values)`, exceeds
33/// `NOISE_FLOOR_FRAC · running_max_flux`, and is at least `MIN_ONSET_GAP` frames
34/// after the previous accepted onset. Onset **frame indices** are written to
35/// `out_onsets` in ascending order.
36///
37/// The novelty curve is consumed with a three-tap sliding delay, so no
38/// per-frame heap buffer is needed; the only state is a fixed
39/// `THRESH_WINDOW`-element stack ring. This replaces the frame-energy novelty
40/// placeholder in `music.rs::detect_onsets` with real per-bin flux.
41///
42/// Returns the number of onsets written.
43///
44/// # Errors
45/// - [`AudioError::InvalidParameter`] if `n_bins == 0`, or `n_frames*n_bins`
46/// exceeds `mags.len()`.
47/// - [`AudioError::OutputBufferTooSmall`] if more onsets are found than
48/// `out_onsets` can hold.
49pub fn onset_detection(
50 mags: &[f32],
51 n_frames: usize,
52 n_bins: usize,
53 out_onsets: &mut [u32],
54) -> Result<usize, AudioError> {
55 if n_bins == 0 {
56 return Err(AudioError::InvalidParameter);
57 }
58 let needed = n_frames
59 .checked_mul(n_bins)
60 .ok_or(AudioError::InvalidParameter)?;
61 if needed > mags.len() {
62 return Err(AudioError::InvalidParameter);
63 }
64 if n_frames < 3 {
65 return Ok(0);
66 }
67
68 // Causal moving-mean ring over past flux values.
69 let mut ring = [0.0f32; THRESH_WINDOW];
70 let mut ring_len = 0usize;
71 let mut ring_pos = 0usize;
72 let mut ring_sum = 0.0f64;
73
74 // Three-tap flux delay: f_prev2 (frame fi-2), f_prev1 (frame fi-1, the
75 // candidate under test), and the current flux at frame fi.
76 let mut f_prev2 = 0.0f32;
77 let mut f_prev1 = 0.0f32;
78 let mut running_max = 0.0f32;
79 // Frame index of the last accepted onset (sentinel keeps the first eligible
80 // candidate un-gated).
81 let mut last_onset: i64 = -(MIN_ONSET_GAP as i64) - 1;
82 let mut w = 0usize;
83
84 for fi in 1..n_frames {
85 let prev = &mags[(fi - 1) * n_bins..fi * n_bins];
86 let cur = &mags[fi * n_bins..(fi + 1) * n_bins];
87 let flux = spectral_flux(prev, cur)?;
88 if flux > running_max {
89 running_max = flux;
90 }
91
92 // Finalize the candidate at frame fi-1 once its right neighbour (this
93 // flux) is known. Requires fi >= 2 so f_prev2 is a real value.
94 if fi >= 2 {
95 let cand_frame = fi - 1;
96 let mean = if ring_len > 0 {
97 (ring_sum / ring_len as f64) as f32
98 } else {
99 0.0
100 };
101 let threshold = LAMBDA * mean;
102 let is_local_max = f_prev1 > f_prev2 && f_prev1 >= flux;
103 let above_thresh = f_prev1 >= threshold;
104 let above_floor = f_prev1 >= NOISE_FLOOR_FRAC * running_max && f_prev1 > 0.0;
105 let gap_ok = (cand_frame as i64 - last_onset) >= MIN_ONSET_GAP as i64;
106 if is_local_max && above_thresh && above_floor && gap_ok {
107 if w == out_onsets.len() {
108 return Err(AudioError::OutputBufferTooSmall);
109 }
110 out_onsets[w] = cand_frame as u32;
111 w += 1;
112 last_onset = cand_frame as i64;
113 }
114
115 // Slide the past-value ring forward by admitting f_prev2 (frame
116 // fi-2), which now sits strictly before every future candidate.
117 if ring_len < THRESH_WINDOW {
118 ring[ring_pos] = f_prev2;
119 ring_sum += f_prev2 as f64;
120 ring_len += 1;
121 } else {
122 ring_sum -= ring[ring_pos] as f64;
123 ring[ring_pos] = f_prev2;
124 ring_sum += f_prev2 as f64;
125 }
126 ring_pos = (ring_pos + 1) % THRESH_WINDOW;
127 }
128
129 f_prev2 = f_prev1;
130 f_prev1 = flux;
131 }
132
133 Ok(w)
134}
135
136#[cfg(test)]
137mod tests {
138 use super::*;
139
140 /// Build a spectrogram: a flat baseline spectrum in every frame, with a
141 /// one-frame energy jump at each `onset_frames` position. Each jump yields a
142 /// single positive-flux spike at that frame (the return to baseline is
143 /// rectified away), so onset detection must recover exactly those frames.
144 fn synth_spectrogram(
145 n_frames: usize,
146 n_bins: usize,
147 onset_frames: &[usize],
148 baseline: f32,
149 peak: f32,
150 ) -> Vec<f32> {
151 let mut m = vec![baseline; n_frames * n_bins];
152 for &f in onset_frames {
153 for b in 0..n_bins {
154 m[f * n_bins + b] = peak;
155 }
156 }
157 m
158 }
159
160 #[test]
161 fn recovers_known_impulse_pattern() {
162 let n_bins = 4;
163 let n_frames = 40;
164 let onsets = [5usize, 15, 25, 35];
165 let mags = synth_spectrogram(n_frames, n_bins, &onsets, 0.1, 1.0);
166 let mut out = [0u32; 16];
167 let n = onset_detection(&mags, n_frames, n_bins, &mut out).expect("onset");
168 assert_eq!(n, onsets.len(), "onset count");
169 for (k, &f) in onsets.iter().enumerate() {
170 assert_eq!(out[k], f as u32, "onset {k} position");
171 }
172 }
173
174 #[test]
175 fn silence_has_no_onsets() {
176 let n_bins = 8;
177 let n_frames = 32;
178 let mags = vec![0.0f32; n_frames * n_bins];
179 let mut out = [0u32; 16];
180 let n = onset_detection(&mags, n_frames, n_bins, &mut out).expect("onset");
181 assert_eq!(n, 0);
182 }
183
184 #[test]
185 fn min_gap_debounces_adjacent_frames() {
186 // Two spikes only two frames apart -> the second is inside MIN_ONSET_GAP
187 // of the first and must be suppressed.
188 let n_bins = 4;
189 let n_frames = 20;
190 let mags = synth_spectrogram(n_frames, n_bins, &[8, 10], 0.1, 1.0);
191 let mut out = [0u32; 8];
192 let n = onset_detection(&mags, n_frames, n_bins, &mut out).expect("onset");
193 assert_eq!(n, 1);
194 assert_eq!(out[0], 8);
195 }
196
197 #[test]
198 fn rejects_bad_dimensions() {
199 let mags = [0.0f32; 12];
200 assert_eq!(
201 onset_detection(&mags, 4, 0, &mut [0u32; 4]),
202 Err(AudioError::InvalidParameter)
203 );
204 // n_frames*n_bins = 20 > 12
205 assert_eq!(
206 onset_detection(&mags, 5, 4, &mut [0u32; 4]),
207 Err(AudioError::InvalidParameter)
208 );
209 }
210
211 #[test]
212 fn buffer_too_small_errors() {
213 let n_bins = 4;
214 let n_frames = 40;
215 let onsets = [5usize, 15, 25, 35];
216 let mags = synth_spectrogram(n_frames, n_bins, &onsets, 0.1, 1.0);
217 let mut out = [0u32; 2];
218 assert_eq!(
219 onset_detection(&mags, n_frames, n_bins, &mut out),
220 Err(AudioError::OutputBufferTooSmall)
221 );
222 }
223}