Skip to main content

qualia_core_db/audio/dsp/
midi_transport.rs

1//! MIDI note utilities and transport state machine.
2
3/// MIDI note names to frequencies (A4 = 440 Hz).
4pub fn midi_note_to_freq(note: u8) -> f64 {
5    440.0 * 2.0_f64.powf((note as f64 - 69.0) / 12.0)
6}
7
8/// Convert frequency to nearest MIDI note number.
9pub fn freq_to_midi_note(freq: f64) -> u8 {
10    let note = 69.0 + 12.0 * (freq / 440.0).log2();
11    note.round() as u8
12}
13
14/// Note name (e.g. "C4") to MIDI note number.
15pub fn note_name_to_midi(name: &str) -> Option<u8> {
16    let name = name.trim();
17    if name.is_empty() {
18        return None;
19    }
20    let bytes = name.as_bytes();
21    let pitch_class = match bytes[0].to_ascii_uppercase() {
22        b'C' => 0,
23        b'D' => 2,
24        b'E' => 4,
25        b'F' => 5,
26        b'G' => 7,
27        b'A' => 9,
28        b'B' => 11,
29        _ => return None,
30    };
31    let mut idx = 1;
32    let mut semitone = pitch_class as i32;
33    // Sharp/flat.
34    if idx < bytes.len() && bytes[idx] == b'#' {
35        semitone += 1;
36        idx += 1;
37    } else if idx < bytes.len() && (bytes[idx] == b'b' || bytes[idx] == b'B') {
38        semitone -= 1;
39        idx += 1;
40    }
41    // Octave number.
42    let octave_str = &name[idx..];
43    let octave: i32 = octave_str.parse().ok()?;
44    // MIDI note = (octave + 1) * 12 + semitone.
45    let midi = (octave + 1) * 12 + semitone;
46    if (0..=127).contains(&midi) {
47        Some(midi as u8)
48    } else {
49        None
50    }
51}
52
53/// MIDI note number to note name.
54pub fn midi_to_note_name(note: u8) -> String {
55    let names = [
56        "C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B",
57    ];
58    let pitch_class = note % 12;
59    let octave = (note as i32 / 12) - 1;
60    format!("{}{}", names[pitch_class as usize], octave)
61}
62
63/// Quantize a beat position to the nearest grid division.
64pub fn quantize(position_beats: f64, grid_division: f64) -> f64 {
65    if grid_division <= 0.0 {
66        return position_beats;
67    }
68    (position_beats / grid_division).round() * grid_division
69}
70
71/// Transpose a MIDI note by semitones (clamped to 0-127).
72pub fn transpose(note: u8, semitones: i32) -> u8 {
73    let result = note as i32 + semitones;
74    result.clamp(0, 127) as u8
75}
76
77/// Transport state machine — play, stop, record, loop.
78#[derive(Debug, Clone, Copy, PartialEq, Eq)]
79pub enum TransportState {
80    /// Not running; position resets on `stop`.
81    Stopped,
82    /// Playing — position advances on `tick`.
83    Playing,
84    /// Paused — position is retained.
85    Paused,
86    /// Recording — position advances; capture is caller-managed.
87    Recording,
88}
89
90/// Playback/record transport — position, tempo, loop, and metronome state.
91#[derive(Debug, Clone)]
92pub struct Transport {
93    /// Current state-machine state.
94    pub state: TransportState,
95    /// Tempo in BPM (clamped to ≥ 1 by `set_tempo`).
96    pub tempo: f64,
97    /// Sample rate used for beat/second conversion.
98    pub sample_rate: f64,
99    /// Playhead position in samples.
100    pub position_samples: u64,
101    /// Loop start in samples, when looping is armed.
102    pub loop_start: Option<u64>,
103    /// Loop end in samples, when looping is armed.
104    pub loop_end: Option<u64>,
105    /// True when a loop region is armed.
106    pub is_looping: bool,
107    is_metronome_on: bool,
108    metronome_phase: f64,
109}
110
111impl Transport {
112    /// Create a stopped transport at position 0, no loop, metronome off.
113    pub fn new(tempo: f64, sample_rate: f64) -> Self {
114        Self {
115            state: TransportState::Stopped,
116            tempo,
117            sample_rate,
118            position_samples: 0,
119            loop_start: None,
120            loop_end: None,
121            is_looping: false,
122            is_metronome_on: false,
123            metronome_phase: 0.0,
124        }
125    }
126
127    /// Enter `Playing` (position is retained).
128    pub fn play(&mut self) {
129        self.state = TransportState::Playing;
130    }
131
132    /// Enter `Stopped` and rewind the playhead to 0.
133    pub fn stop(&mut self) {
134        self.state = TransportState::Stopped;
135        self.position_samples = 0;
136    }
137
138    /// Pause playback; no-op unless currently `Playing`.
139    pub fn pause(&mut self) {
140        if self.state == TransportState::Playing {
141            self.state = TransportState::Paused;
142        }
143    }
144
145    /// Enter `Recording`.
146    pub fn record(&mut self) {
147        self.state = TransportState::Recording;
148    }
149
150    /// Set tempo in BPM (clamped to ≥ 1).
151    pub fn set_tempo(&mut self, bpm: f64) {
152        self.tempo = bpm.max(1.0);
153    }
154
155    /// Arm a loop region `[start, end)` in samples.
156    pub fn set_loop(&mut self, start: u64, end: u64) {
157        self.loop_start = Some(start);
158        self.loop_end = Some(end);
159        self.is_looping = true;
160    }
161
162    /// Disarm the loop region.
163    pub fn clear_loop(&mut self) {
164        self.loop_start = None;
165        self.loop_end = None;
166        self.is_looping = false;
167    }
168
169    /// Enable/disable the metronome click.
170    pub fn set_metronome(&mut self, on: bool) {
171        self.is_metronome_on = on;
172    }
173
174    /// Advance one sample. Returns true if at a beat boundary (for metronome).
175    pub fn tick(&mut self) -> bool {
176        if self.state == TransportState::Stopped {
177            return false;
178        }
179
180        let samples_per_beat = 60.0 * self.sample_rate / self.tempo;
181        let beat_position = self.position_samples as f64 / samples_per_beat;
182        let beat_phase = beat_position - beat_position.floor();
183        self.metronome_phase = beat_phase;
184
185        // Metronome click at beat boundaries.
186        let click = self.is_metronome_on && beat_phase < 1.0 / samples_per_beat;
187
188        self.position_samples += 1;
189
190        // Loop handling.
191        if self.is_looping {
192            if let Some(end) = self.loop_end {
193                if self.position_samples >= end {
194                    if let Some(start) = self.loop_start {
195                        self.position_samples = start;
196                    }
197                }
198            }
199        }
200
201        click
202    }
203
204    /// Current metronome phase within the active beat [0.0, 1.0).
205    pub fn metronome_phase(&self) -> f64 {
206        self.metronome_phase
207    }
208
209    /// Generate an audio sample for the metronome click (1kHz pulse decaying over 20ms).
210    pub fn metronome_sample(&self) -> f64 {
211        if !self.is_metronome_on || self.state == TransportState::Stopped {
212            return 0.0;
213        }
214        let samples_per_beat = 60.0 * self.sample_rate / self.tempo;
215        let sample_in_beat = self.metronome_phase * samples_per_beat;
216        let click_len = (0.02 * self.sample_rate).min(samples_per_beat * 0.5);
217        if sample_in_beat < click_len {
218            let decay = 1.0 - (sample_in_beat / click_len);
219            let freq = 1000.0;
220            let sine =
221                (2.0 * std::f64::consts::PI * freq * (sample_in_beat / self.sample_rate)).sin();
222            sine * decay * 0.5
223        } else {
224            0.0
225        }
226    }
227
228    /// Current position in beats.
229    pub fn position_beats(&self) -> f64 {
230        let samples_per_beat = 60.0 * self.sample_rate / self.tempo;
231        self.position_samples as f64 / samples_per_beat
232    }
233
234    /// Current position in seconds.
235    pub fn position_seconds(&self) -> f64 {
236        self.position_samples as f64 / self.sample_rate
237    }
238}
239
240#[cfg(test)]
241mod tests {
242    use super::*;
243
244    #[test]
245    fn midi_note_freq_a4() {
246        assert!((midi_note_to_freq(69) - 440.0).abs() < 0.01);
247    }
248
249    #[test]
250    fn midi_note_freq_c0() {
251        // C0 = MIDI 12, freq ≈ 16.35
252        assert!((midi_note_to_freq(12) - 16.35).abs() < 0.1);
253    }
254
255    #[test]
256    fn freq_to_midi_a4() {
257        assert_eq!(freq_to_midi_note(440.0), 69);
258    }
259
260    #[test]
261    fn note_name_to_midi_basic() {
262        assert_eq!(note_name_to_midi("A4"), Some(69));
263        assert_eq!(note_name_to_midi("C4"), Some(60));
264        assert_eq!(note_name_to_midi("C#4"), Some(61));
265        assert_eq!(note_name_to_midi("Bb3"), Some(58));
266    }
267
268    #[test]
269    fn note_name_to_midi_invalid() {
270        assert_eq!(note_name_to_midi("H4"), None);
271        assert_eq!(note_name_to_midi(""), None);
272    }
273
274    #[test]
275    fn midi_to_note_name_roundtrip() {
276        assert_eq!(midi_to_note_name(69), "A4");
277        assert_eq!(midi_to_note_name(60), "C4");
278        assert_eq!(midi_to_note_name(61), "C#4");
279    }
280
281    #[test]
282    fn quantize_to_quarter() {
283        let result = quantize(1.3, 0.25);
284        assert!((result - 1.25).abs() < 1e-10);
285    }
286
287    #[test]
288    fn quantize_to_eighth() {
289        let result = quantize(1.1, 0.5);
290        assert!((result - 1.0).abs() < 1e-10);
291    }
292
293    #[test]
294    fn transpose_up() {
295        assert_eq!(transpose(60, 5), 65);
296    }
297
298    #[test]
299    fn transpose_down() {
300        assert_eq!(transpose(60, -12), 48);
301    }
302
303    #[test]
304    fn transpose_clamped() {
305        assert_eq!(transpose(0, -5), 0);
306        assert_eq!(transpose(127, 5), 127);
307    }
308
309    #[test]
310    fn transport_play_stop() {
311        let mut t = Transport::new(120.0, 44100.0);
312        assert_eq!(t.state, TransportState::Stopped);
313        t.play();
314        assert_eq!(t.state, TransportState::Playing);
315        t.stop();
316        assert_eq!(t.state, TransportState::Stopped);
317        assert_eq!(t.position_samples, 0);
318    }
319
320    #[test]
321    fn transport_pause() {
322        let mut t = Transport::new(120.0, 44100.0);
323        t.play();
324        for _ in 0..100 {
325            t.tick();
326        }
327        t.pause();
328        assert_eq!(t.state, TransportState::Paused);
329    }
330
331    #[test]
332    fn transport_position() {
333        let mut t = Transport::new(120.0, 44100.0);
334        t.play();
335        for _ in 0..44100 {
336            t.tick();
337        }
338        // At 120 BPM, samples_per_beat = 60 * 44100 / 120 = 22050.
339        // 44100 samples = 2 beats.
340        assert!((t.position_beats() - 2.0).abs() < 0.01);
341    }
342
343    #[test]
344    fn transport_loop() {
345        let mut t = Transport::new(120.0, 44100.0);
346        t.set_loop(100, 200);
347        t.play();
348        for _ in 0..200 {
349            t.tick();
350        }
351        // Should have looped back to start.
352        assert!(t.position_samples < 200);
353    }
354
355    #[test]
356    fn transport_metronome_click() {
357        let mut t = Transport::new(120.0, 44100.0);
358        t.set_metronome(true);
359        t.play();
360        // At 120 BPM, one beat = 22050 samples. First tick should click.
361        let click = t.tick();
362        assert!(click);
363    }
364
365    #[test]
366    fn transport_tempo_change() {
367        let mut t = Transport::new(120.0, 44100.0);
368        t.set_tempo(60.0);
369        assert_eq!(t.tempo, 60.0);
370    }
371}