qualia_audio/features/pitch_midi/audio_to_midi.rs
1//! End-to-end audio → MIDI note transcription.
2//!
3//! Pipeline: slice the mono signal into overlapping analysis frames → estimate a
4//! per-frame fundamental with [`yin_pitch`] →
5//! [`segment_notes`] that pitch track
6//! into MIDI note events. This is the composed convenience entry point; the two
7//! stages remain usable on their own.
8//!
9//! Epistemic contract: the emitted notes are *proposals* carrying the mean
10//! voicing confidence of their frames — transcribed MIDI is never authoritative
11//! the way imported MIDI is.
12//!
13//! Zero-heap hot path: the caller supplies the frame/hop geometry, the two
14//! per-frame track buffers (`f0_scratch`, `conf_scratch`), the YIN work buffer
15//! (`yin_scratch`), and the `out` note array. This function allocates nothing.
16
17use crate::features::pitch::yin_pitch;
18use crate::features::pitch_midi::note_segmentation::{segment_notes, NoteEvent};
19use crate::types::AudioError;
20
21/// Transcribe a mono `samples` buffer into MIDI note events.
22///
23/// - `samples`: mono PCM in `[-1, 1]`.
24/// - `sample_rate`: sampling rate in Hz (> 0).
25/// - `frame_size`: analysis window length in samples (≥ 8).
26/// - `hop_size`: advance between frame starts in samples (> 0).
27/// - `min_hz` / `max_hz`: YIN fundamental search band (`0 < min_hz < max_hz`).
28/// - `yin_threshold`: YIN absolute CMND threshold (typical `0.10..0.20`).
29/// - `ref_a4_hz`: reference tuning for A4 (default `440.0`).
30/// - `min_note_frames`: minimum note length in frames (short runs are dropped).
31/// - `f0_scratch` / `conf_scratch`: per-frame track buffers; each must hold at
32/// least `n_frames = (samples.len() − frame_size) / hop_size + 1` floats.
33/// - `yin_scratch`: YIN difference/CMND work buffer (see [`yin_pitch`]).
34/// - `out`: caller-owned destination for the note events.
35///
36/// Returns the number of notes written into `out`.
37///
38/// # Errors
39/// - [`AudioError::InvalidParameter`] for a non-positive rate/hop, a
40/// `frame_size < 8`, an inconsistent search band, or a signal shorter than one
41/// frame.
42/// - [`AudioError::WorkspaceTooSmall`] if `f0_scratch`/`conf_scratch` cannot hold
43/// every frame.
44/// - [`AudioError::OutputBufferTooSmall`] if `out` cannot hold every note.
45/// - Any error propagated by [`yin_pitch`] (e.g. a too-small `yin_scratch`).
46#[allow(clippy::too_many_arguments)]
47pub fn audio_to_midi(
48 samples: &[f32],
49 sample_rate: f32,
50 frame_size: usize,
51 hop_size: usize,
52 min_hz: f32,
53 max_hz: f32,
54 yin_threshold: f32,
55 ref_a4_hz: f32,
56 min_note_frames: usize,
57 f0_scratch: &mut [f32],
58 conf_scratch: &mut [f32],
59 yin_scratch: &mut [f32],
60 out: &mut [NoteEvent],
61) -> Result<usize, AudioError> {
62 if !sample_rate.is_finite() || sample_rate <= 0.0 || hop_size == 0 || frame_size < 8 {
63 return Err(AudioError::InvalidParameter);
64 }
65 if samples.len() < frame_size {
66 return Err(AudioError::InvalidParameter);
67 }
68 // Number of complete frames that fit with this hop.
69 let n_frames = (samples.len() - frame_size) / hop_size + 1;
70 if f0_scratch.len() < n_frames || conf_scratch.len() < n_frames {
71 return Err(AudioError::WorkspaceTooSmall);
72 }
73
74 // Stage 1: per-frame fundamental estimation.
75 for f in 0..n_frames {
76 let start = f * hop_size;
77 let frame = &samples[start..start + frame_size];
78 let est = yin_pitch(
79 frame,
80 sample_rate,
81 min_hz,
82 max_hz,
83 yin_threshold,
84 yin_scratch,
85 )?;
86 f0_scratch[f] = est.f0_hz;
87 conf_scratch[f] = est.confidence;
88 }
89
90 // Stage 2: segment the pitch track into note proposals.
91 segment_notes(
92 &f0_scratch[..n_frames],
93 &conf_scratch[..n_frames],
94 n_frames,
95 ref_a4_hz,
96 min_note_frames,
97 out,
98 )
99}
100
101#[cfg(test)]
102mod tests {
103 use super::*;
104 use core::f32::consts::PI;
105
106 /// Synthesise a pure sine of `freq` Hz for `n` samples at `sr`.
107 fn sine(freq: f32, sr: f32, n: usize) -> Vec<f32> {
108 (0..n)
109 .map(|i| (2.0 * PI * freq * i as f32 / sr).sin())
110 .collect()
111 }
112
113 #[test]
114 fn synth_a4_tone_yields_one_note_69() {
115 let sr = 44_100.0f32;
116 let frame_size = 2048usize;
117 let hop = 512usize;
118 // ~0.35 s of clean 440 Hz — enough for several overlapping frames.
119 let samples = sine(440.0, sr, 16_000);
120
121 let n_frames = (samples.len() - frame_size) / hop + 1;
122 let mut f0 = vec![0.0f32; n_frames];
123 let mut conf = vec![0.0f32; n_frames];
124 // YIN scratch: max_lag = sr/min_hz + 1; min_hz = 80 → ~552.
125 let mut yin_scratch = vec![0.0f32; frame_size / 2 + 1];
126 let mut out = [NoteEvent::empty(); 16];
127
128 let n = audio_to_midi(
129 &samples,
130 sr,
131 frame_size,
132 hop,
133 80.0,
134 1000.0,
135 0.15,
136 440.0,
137 3,
138 &mut f0,
139 &mut conf,
140 &mut yin_scratch,
141 &mut out,
142 )
143 .expect("audio_to_midi");
144
145 assert_eq!(n, 1, "a single sustained tone → one note");
146 assert_eq!(out[0].note, 69, "440 Hz → MIDI 69 (A4)");
147 assert!(out[0].confidence > 0.5, "clean sine is confidently voiced");
148 assert_eq!(out[0].start_frame, 0);
149 assert_eq!(out[0].end_frame, n_frames as u32);
150 }
151
152 #[test]
153 fn rejects_too_short_signal() {
154 let mut f0 = [0.0f32; 4];
155 let mut conf = [0.0f32; 4];
156 let mut yin_scratch = [0.0f32; 64];
157 let mut out = [NoteEvent::empty(); 4];
158 let err = audio_to_midi(
159 &[0.0f32; 10],
160 44_100.0,
161 2048,
162 512,
163 80.0,
164 1000.0,
165 0.15,
166 440.0,
167 3,
168 &mut f0,
169 &mut conf,
170 &mut yin_scratch,
171 &mut out,
172 )
173 .unwrap_err();
174 assert_eq!(err, AudioError::InvalidParameter);
175 }
176
177 #[test]
178 fn rejects_undersized_track_scratch() {
179 let sr = 44_100.0f32;
180 let samples = sine(440.0, sr, 8000);
181 let mut f0 = [0.0f32; 2]; // too small
182 let mut conf = [0.0f32; 2];
183 let mut yin_scratch = vec![0.0f32; 1025];
184 let mut out = [NoteEvent::empty(); 8];
185 let err = audio_to_midi(
186 &samples,
187 sr,
188 2048,
189 512,
190 80.0,
191 1000.0,
192 0.15,
193 440.0,
194 3,
195 &mut f0,
196 &mut conf,
197 &mut yin_scratch,
198 &mut out,
199 )
200 .unwrap_err();
201 assert_eq!(err, AudioError::WorkspaceTooSmall);
202 }
203}