Skip to main content

qualia_audio/features/pitch_midi/
note_segmentation.rs

1//! Segment a per-frame `(f0, confidence)` pitch track into MIDI note ON/OFF
2//! events.
3//!
4//! Each voiced frame is quantised to a MIDI note number (via
5//! [`hz_to_midi`]). A *note* is a maximal run
6//! of consecutive frames that quantise to the **same** note number; the run ends
7//! when the pitch crosses the half-semitone quantisation boundary into a
8//! different note (the pitch-change threshold) or when a low-confidence /
9//! unvoiced *gap* interrupts voicing. Runs shorter than `min_note_frames` are
10//! discarded as transients, so a single glitchy frame does not become a note.
11//!
12//! Epistemic contract: every emitted [`NoteEvent`] is a *proposal*, not an
13//! authoritative transcription. It carries the mean voicing `confidence` of its
14//! frames, and `velocity` is derived from that same confidence — downstream code
15//! can weight or reject a proposal on it. Transcribed MIDI must never be treated
16//! as ground truth the way imported MIDI is.
17//!
18//! Zero-heap hot path: note events are written into the caller-supplied `out`
19//! slice; the function allocates nothing.
20
21use crate::features::pitch_midi::pitch_to_midi::hz_to_midi;
22use crate::types::AudioError;
23
24/// Minimum voicing confidence for a frame to count as pitched. Frames below this
25/// (or with `f0 <= 0`) are treated as an unvoiced gap that ends the current note.
26pub const MIN_VOICED_CONFIDENCE: f32 = 0.5;
27
28/// One transcribed note proposal.
29///
30/// `start_frame` is the index of the first frame of the note; `end_frame` is the
31/// index one past its last frame (exclusive), so `end_frame − start_frame` is the
32/// note's duration in frames. `note` is the MIDI note number, `velocity` is a
33/// `1..=127` value derived from voicing confidence, and `confidence` is the mean
34/// voicing confidence over the note's frames.
35#[repr(C)]
36#[derive(Debug, Clone, Copy, PartialEq)]
37pub struct NoteEvent {
38    pub note: u8,
39    pub velocity: u8,
40    pub start_frame: u32,
41    pub end_frame: u32,
42    pub confidence: f32,
43}
44
45impl NoteEvent {
46    /// A zeroed placeholder, useful for initialising a caller-owned `out` array.
47    #[inline]
48    pub const fn empty() -> Self {
49        Self {
50            note: 0,
51            velocity: 0,
52            start_frame: 0,
53            end_frame: 0,
54            confidence: 0.0,
55        }
56    }
57}
58
59/// Map a mean voicing confidence in `[0, 1]` to a MIDI velocity in `1..=127`.
60#[inline]
61fn confidence_to_velocity(mean_conf: f32) -> u8 {
62    let c = if mean_conf.is_finite() {
63        mean_conf.clamp(0.0, 1.0)
64    } else {
65        0.0
66    };
67    // 0 → 1, 1 → 127. A voiced note always has velocity ≥ 1 (audible).
68    (c * 126.0 + 1.0).round() as u8
69}
70
71/// An in-progress note accumulator (reset between notes; lives on the stack).
72struct OpenNote {
73    note: u8,
74    start_frame: u32,
75    end_frame: u32,
76    conf_sum: f32,
77    conf_n: u32,
78}
79
80/// Segment a per-frame pitch track into note events.
81///
82/// - `f0_hz`: per-frame fundamental in Hz (`0.0` = unvoiced). Length ≥ `n_frames`.
83/// - `confidence`: per-frame voicing confidence in `[0, 1]`. Length ≥ `n_frames`.
84/// - `n_frames`: number of valid frames to read from the two tracks.
85/// - `ref_a4_hz`: reference tuning for A4 (default `440.0`).
86/// - `min_note_frames`: minimum note length in frames; shorter runs are dropped
87///   (a value of `0` is treated as `1`).
88/// - `out`: caller-owned destination for the note events.
89///
90/// Returns the number of notes written into `out`.
91///
92/// # Errors
93/// - [`AudioError::InvalidParameter`] if either input track is shorter than
94///   `n_frames`, or `ref_a4_hz` is not positive/finite.
95/// - [`AudioError::OutputBufferTooSmall`] if `out` cannot hold every note.
96pub fn segment_notes(
97    f0_hz: &[f32],
98    confidence: &[f32],
99    n_frames: usize,
100    ref_a4_hz: f32,
101    min_note_frames: usize,
102    out: &mut [NoteEvent],
103) -> Result<usize, AudioError> {
104    if f0_hz.len() < n_frames || confidence.len() < n_frames {
105        return Err(AudioError::InvalidParameter);
106    }
107    if !ref_a4_hz.is_finite() || ref_a4_hz <= 0.0 {
108        return Err(AudioError::InvalidParameter);
109    }
110    let min_len = min_note_frames.max(1) as u32;
111
112    let mut count = 0usize;
113    let mut open: Option<OpenNote> = None;
114
115    for i in 0..n_frames {
116        let f0 = f0_hz[i];
117        let conf = confidence[i];
118        let voiced =
119            f0.is_finite() && f0 > 0.0 && conf.is_finite() && conf >= MIN_VOICED_CONFIDENCE;
120
121        if voiced {
122            let (note, _cents) = hz_to_midi(f0, ref_a4_hz);
123            match open.as_mut() {
124                // Continue the current note: same quantised pitch.
125                Some(cur) if cur.note == note => {
126                    cur.end_frame = i as u32 + 1;
127                    cur.conf_sum += conf;
128                    cur.conf_n += 1;
129                }
130                // Pitch changed (or nothing open): flush then open a fresh note.
131                _ => {
132                    if let Some(cur) = open.take() {
133                        flush(&cur, min_len, out, &mut count)?;
134                    }
135                    open = Some(OpenNote {
136                        note,
137                        start_frame: i as u32,
138                        end_frame: i as u32 + 1,
139                        conf_sum: conf,
140                        conf_n: 1,
141                    });
142                }
143            }
144        } else {
145            // Low-confidence / unvoiced gap ends the current note.
146            if let Some(cur) = open.take() {
147                flush(&cur, min_len, out, &mut count)?;
148            }
149        }
150    }
151
152    // Flush a note still open at the end of the track.
153    if let Some(cur) = open.take() {
154        flush(&cur, min_len, out, &mut count)?;
155    }
156
157    Ok(count)
158}
159
160/// Emit `cur` into `out[*count]` if it meets the minimum duration.
161#[inline]
162fn flush(
163    cur: &OpenNote,
164    min_len: u32,
165    out: &mut [NoteEvent],
166    count: &mut usize,
167) -> Result<(), AudioError> {
168    let duration = cur.end_frame - cur.start_frame;
169    if duration < min_len {
170        return Ok(());
171    }
172    if *count >= out.len() {
173        return Err(AudioError::OutputBufferTooSmall);
174    }
175    let mean_conf = if cur.conf_n > 0 {
176        cur.conf_sum / cur.conf_n as f32
177    } else {
178        0.0
179    };
180    out[*count] = NoteEvent {
181        note: cur.note,
182        velocity: confidence_to_velocity(mean_conf),
183        start_frame: cur.start_frame,
184        end_frame: cur.end_frame,
185        confidence: mean_conf,
186    };
187    *count += 1;
188    Ok(())
189}
190
191#[cfg(test)]
192mod tests {
193    use super::*;
194
195    /// Build a constant-confidence track holding `f_a` for `n_a` frames then
196    /// `f_b` for `n_b` frames.
197    fn two_tone(f_a: f32, n_a: usize, f_b: f32, n_b: usize, conf: f32) -> (Vec<f32>, Vec<f32>) {
198        let mut f0 = Vec::new();
199        let mut c = Vec::new();
200        for _ in 0..n_a {
201            f0.push(f_a);
202            c.push(conf);
203        }
204        for _ in 0..n_b {
205            f0.push(f_b);
206            c.push(conf);
207        }
208        (f0, c)
209    }
210
211    #[test]
212    fn jump_a4_to_b4_yields_two_notes() {
213        // 440 Hz (A4=69) for 10 frames, then 493.88 Hz (B4=71) for 8 frames.
214        let (f0, conf) = two_tone(440.0, 10, 493.88, 8, 0.9);
215        let mut out = [NoteEvent::empty(); 8];
216        let n = segment_notes(&f0, &conf, 18, 440.0, 3, &mut out).expect("segment");
217        assert_eq!(n, 2, "expected exactly two notes");
218
219        assert_eq!(out[0].note, 69);
220        assert_eq!(out[0].start_frame, 0);
221        assert_eq!(out[0].end_frame, 10);
222
223        assert_eq!(out[1].note, 71);
224        assert_eq!(out[1].start_frame, 10);
225        assert_eq!(out[1].end_frame, 18);
226    }
227
228    #[test]
229    fn low_confidence_gap_ends_the_note() {
230        // A4 for 6 frames, a 3-frame low-confidence gap, then A4 again for 6.
231        let mut f0 = vec![440.0f32; 15];
232        let mut conf = vec![0.9f32; 15];
233        for i in 6..9 {
234            conf[i] = 0.1; // below MIN_VOICED_CONFIDENCE
235        }
236        // f0 during the gap is irrelevant, but zero it to mimic unvoiced.
237        for i in 6..9 {
238            f0[i] = 0.0;
239        }
240        let mut out = [NoteEvent::empty(); 8];
241        let n = segment_notes(&f0, &conf, 15, 440.0, 3, &mut out).expect("segment");
242        assert_eq!(n, 2, "gap must split into two notes");
243        assert_eq!(out[0].note, 69);
244        assert_eq!(out[0].start_frame, 0);
245        assert_eq!(out[0].end_frame, 6);
246        assert_eq!(out[1].note, 69);
247        assert_eq!(out[1].start_frame, 9);
248        assert_eq!(out[1].end_frame, 15);
249    }
250
251    #[test]
252    fn short_run_is_discarded() {
253        // A 2-frame note below min_note_frames = 4 is dropped.
254        let (f0, conf) = two_tone(440.0, 2, 493.88, 8, 0.9);
255        let mut out = [NoteEvent::empty(); 8];
256        let n = segment_notes(&f0, &conf, 10, 440.0, 4, &mut out).expect("segment");
257        assert_eq!(n, 1, "only the long note survives");
258        assert_eq!(out[0].note, 71);
259        assert_eq!(out[0].start_frame, 2);
260    }
261
262    #[test]
263    fn velocity_and_confidence_track_voicing() {
264        let (f0, conf) = two_tone(440.0, 8, 440.0, 0, 1.0);
265        let mut out = [NoteEvent::empty(); 4];
266        let n = segment_notes(&f0, &conf, 8, 440.0, 3, &mut out).expect("segment");
267        assert_eq!(n, 1);
268        assert_eq!(out[0].velocity, 127, "full confidence → max velocity");
269        assert!((out[0].confidence - 1.0).abs() < 1e-6);
270    }
271
272    #[test]
273    fn output_buffer_too_small_is_reported() {
274        // Three distinct notes but out capacity 1.
275        let mut f0 = Vec::new();
276        let mut conf = Vec::new();
277        for &f in &[440.0f32, 493.88, 523.25] {
278            for _ in 0..4 {
279                f0.push(f);
280                conf.push(0.9);
281            }
282        }
283        let mut out = [NoteEvent::empty(); 1];
284        let err = segment_notes(&f0, &conf, 12, 440.0, 3, &mut out).unwrap_err();
285        assert_eq!(err, AudioError::OutputBufferTooSmall);
286    }
287
288    #[test]
289    fn short_input_track_is_rejected() {
290        let f0 = [440.0f32; 4];
291        let conf = [0.9f32; 4];
292        let mut out = [NoteEvent::empty(); 4];
293        let err = segment_notes(&f0, &conf, 8, 440.0, 3, &mut out).unwrap_err();
294        assert_eq!(err, AudioError::InvalidParameter);
295    }
296}