Skip to main content

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}