Skip to main content

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}