qualia_audio/features/pitch_midi/
note_segmentation.rs1use crate::features::pitch_midi::pitch_to_midi::hz_to_midi;
22use crate::types::AudioError;
23
24pub const MIN_VOICED_CONFIDENCE: f32 = 0.5;
27
28#[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 #[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#[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 (c * 126.0 + 1.0).round() as u8
69}
70
71struct OpenNote {
73 note: u8,
74 start_frame: u32,
75 end_frame: u32,
76 conf_sum: f32,
77 conf_n: u32,
78}
79
80pub 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 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 _ => {
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 if let Some(cur) = open.take() {
147 flush(&cur, min_len, out, &mut count)?;
148 }
149 }
150 }
151
152 if let Some(cur) = open.take() {
154 flush(&cur, min_len, out, &mut count)?;
155 }
156
157 Ok(count)
158}
159
160#[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 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 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 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; }
236 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 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 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}