Skip to main content

qualia_audio/midi/sequencer/
transport.rs

1//! Transport state machine — play / stop / pause, tempo, position, and looping.
2//!
3//! [`Transport`] holds a fractional tick position and advances it in wall-clock
4//! time via [`Transport::advance`]: at `bpm` quarter notes/minute with `ppq`
5//! ticks/quarter, `Δticks = Δseconds * (bpm / 60) * ppq`. When looping is
6//! enabled and the position reaches `loop_end`, it wraps back to `loop_start`
7//! (carrying the remainder), so a long block never skips past the loop. The
8//! whole type is `Copy`, stack-only, and allocation-free — safe on the audio
9//! thread.
10
11use crate::types::AudioError;
12
13/// Play/stop/pause state of the [`Transport`].
14#[derive(Debug, Clone, Copy, PartialEq, Eq)]
15pub enum TransportState {
16    /// Stopped; `advance` does nothing and position is anchored.
17    Stopped,
18    /// Paused; position is held but not reset.
19    Paused,
20    /// Playing; `advance` moves the position forward.
21    Playing,
22}
23
24/// A sequencer transport: position, tempo, run-state, and an optional loop.
25#[derive(Debug, Clone, Copy)]
26pub struct Transport {
27    state: TransportState,
28    /// Fractional tick position (sub-tick precision across blocks).
29    position: f64,
30    bpm: f64,
31    ppq: u32,
32    loop_enabled: bool,
33    loop_start: u64,
34    loop_end: u64,
35}
36
37impl Transport {
38    /// A stopped transport at position 0 with the given resolution and tempo.
39    ///
40    /// Errors if `ppq == 0` or `bpm` is not a positive finite number.
41    pub fn new(ppq: u32, bpm: f64) -> Result<Self, AudioError> {
42        if ppq == 0 || !(bpm > 0.0) || !bpm.is_finite() {
43            return Err(AudioError::InvalidParameter);
44        }
45        Ok(Self {
46            state: TransportState::Stopped,
47            position: 0.0,
48            bpm,
49            ppq,
50            loop_enabled: false,
51            loop_start: 0,
52            loop_end: 0,
53        })
54    }
55
56    /// Current run-state.
57    #[inline]
58    pub fn state(&self) -> TransportState {
59        self.state
60    }
61
62    /// Current integer tick position (floor of the fractional position).
63    #[inline]
64    pub fn position_ticks(&self) -> u64 {
65        self.position.max(0.0) as u64
66    }
67
68    /// Current fractional tick position.
69    #[inline]
70    pub fn position_ticks_f64(&self) -> f64 {
71        self.position
72    }
73
74    /// Current tempo in BPM.
75    #[inline]
76    pub fn bpm(&self) -> f64 {
77        self.bpm
78    }
79
80    /// Ticks per quarter note.
81    #[inline]
82    pub fn ppq(&self) -> u32 {
83        self.ppq
84    }
85
86    /// Begin playback from the current position.
87    #[inline]
88    pub fn play(&mut self) {
89        self.state = TransportState::Playing;
90    }
91
92    /// Pause, holding the current position.
93    #[inline]
94    pub fn pause(&mut self) {
95        self.state = TransportState::Paused;
96    }
97
98    /// Stop and rewind the position to 0.
99    #[inline]
100    pub fn stop(&mut self) {
101        self.state = TransportState::Stopped;
102        self.position = 0.0;
103    }
104
105    /// Jump to an absolute tick position (does not change run-state).
106    #[inline]
107    pub fn seek(&mut self, tick: u64) {
108        self.position = tick as f64;
109    }
110
111    /// Set the tempo. Errors if `bpm` is not positive/finite.
112    pub fn set_tempo(&mut self, bpm: f64) -> Result<(), AudioError> {
113        if !(bpm > 0.0) || !bpm.is_finite() {
114            return Err(AudioError::InvalidParameter);
115        }
116        self.bpm = bpm;
117        Ok(())
118    }
119
120    /// Enable a loop over `[start, end)` ticks. Errors if `end <= start`.
121    pub fn set_loop(&mut self, start: u64, end: u64) -> Result<(), AudioError> {
122        if end <= start {
123            return Err(AudioError::InvalidParameter);
124        }
125        self.loop_start = start;
126        self.loop_end = end;
127        self.loop_enabled = true;
128        Ok(())
129    }
130
131    /// Disable looping.
132    #[inline]
133    pub fn clear_loop(&mut self) {
134        self.loop_enabled = false;
135    }
136
137    /// Advance the position by `delta_seconds` of wall-clock time. Only moves
138    /// while [`TransportState::Playing`]. Honors the loop if enabled.
139    ///
140    /// Errors if `delta_seconds` is negative or not finite.
141    pub fn advance(&mut self, delta_seconds: f64) -> Result<(), AudioError> {
142        if !delta_seconds.is_finite() || delta_seconds < 0.0 {
143            return Err(AudioError::InvalidParameter);
144        }
145        if self.state != TransportState::Playing {
146            return Ok(());
147        }
148        let delta_ticks = delta_seconds * (self.bpm / 60.0) * self.ppq as f64;
149        self.position += delta_ticks;
150
151        if self.loop_enabled {
152            let start = self.loop_start as f64;
153            let end = self.loop_end as f64;
154            let span = end - start;
155            if span > 0.0 && self.position >= end {
156                // Wrap, carrying any overshoot; handles multi-loop long blocks.
157                let over = (self.position - start) % span;
158                self.position = start + over;
159            }
160        }
161        Ok(())
162    }
163}
164
165#[cfg(test)]
166mod tests {
167    use super::*;
168
169    #[test]
170    fn golden_half_second_at_120bpm_moves_480_ticks() {
171        let mut t = Transport::new(480, 120.0).unwrap();
172        t.play();
173        t.advance(0.5).unwrap();
174        assert!(
175            (t.position_ticks_f64() - 480.0).abs() < 1e-6,
176            "got {}",
177            t.position_ticks_f64()
178        );
179        assert_eq!(t.position_ticks(), 480);
180    }
181
182    #[test]
183    fn stopped_does_not_advance() {
184        let mut t = Transport::new(480, 120.0).unwrap();
185        t.advance(1.0).unwrap();
186        assert_eq!(t.position_ticks(), 0);
187    }
188
189    #[test]
190    fn pause_holds_stop_rewinds() {
191        let mut t = Transport::new(480, 120.0).unwrap();
192        t.play();
193        t.advance(0.5).unwrap();
194        t.pause();
195        t.advance(0.5).unwrap();
196        assert_eq!(t.position_ticks(), 480);
197        t.stop();
198        assert_eq!(t.position_ticks(), 0);
199    }
200
201    #[test]
202    fn loop_wraps() {
203        let mut t = Transport::new(480, 120.0).unwrap();
204        t.set_loop(0, 480).unwrap();
205        t.play();
206        t.advance(0.6).unwrap(); // 576 ticks -> wraps to 96
207        assert!(
208            (t.position_ticks_f64() - 96.0).abs() < 1e-6,
209            "got {}",
210            t.position_ticks_f64()
211        );
212    }
213}