pub struct MtcDecoder { /* private fields */ }Expand description
Turns MIDI Time Code messages into checked positions.
Feed every complete MIDI message with the time it arrived. Quarter frames form a position only
when all eight pieces arrive consecutively in one direction, so a locate, a lost or repeated
piece, a direction change or joining mid-cycle never yields a position that mixes two cycles.
Full frames reset the cycle and yield a Motion::Located position.
Times are durations since any fixed instant the caller chooses, such as a MIDI backend’s timestamp or a monotonic clock. Use one clock per decoder. The decoder never reads a clock, allocates or blocks, so it can run inside a MIDI callback.
use core::time::Duration;
use smpte_timecode::{Direction, FrameRate, Motion, MtcDecoder, MtcEncoder, Timecode};
let start = Timecode::parse("01:00:00:00", FrameRate::FPS_25)?;
let mut encoder = MtcEncoder::new(start, Direction::Forward)?;
let mut decoder = MtcDecoder::new();
let mut events = Vec::new();
for (index, message) in encoder.by_ref().take(8).enumerate() {
let at = Duration::from_millis(10 * index as u64);
events.extend(decoder.feed(&message, at)?);
}
assert_eq!(events.len(), 1);
assert_eq!(events[0].timecode.to_string(), "01:00:00:02");
assert_eq!(events[0].motion, Motion::Forward);Implementations§
Source§impl MtcDecoder
impl MtcDecoder
Sourcepub const DEFAULT_QUARTER_FRAME_TIMEOUT: Duration
pub const DEFAULT_QUARTER_FRAME_TIMEOUT: Duration
The default longest gap between consecutive quarter frames of one cycle.
Sourcepub const DEFAULT_STALE_AFTER: Duration
pub const DEFAULT_STALE_AFTER: Duration
The default age after which the last position is LockState::Stale.
Sourcepub const fn with_quarter_frame_timeout(self, timeout: Duration) -> Self
pub const fn with_quarter_frame_timeout(self, timeout: Duration) -> Self
Sets the longest gap between consecutive quarter frames that still continues a cycle. A longer gap starts a new cycle.
Sourcepub const fn with_stale_after(self, stale_after: Duration) -> Self
pub const fn with_stale_after(self, stale_after: Duration) -> Self
Sets the age after which MtcDecoder::lock_state reports LockState::Stale.
Sourcepub const fn set_rate_hint(&mut self, hint: Option<FrameRate>)
pub const fn set_rate_hint(&mut self, hint: Option<FrameRate>)
Sets the rate the source is known to run at, such as a DAW session rate.
The two-bit rate code cannot tell 29.97 from 30, 23.976 from 24, or mark 30 as drop-frame. While the hint has the same nominal frame count as the incoming code, positions use the hint. A hint at twice the code’s count is a session that sends half-count MTC, as Pro Tools sends 48, 50, 59.94 and 60 sessions with the codes of 24, 25 and 30: positions then use the half rate with the hint’s 1000/1001 factor and drop-frame counting, such as 29.97 for 59.94, 29.97 DF for 59.94 DF, 23.976 for 47.952 and 30 DF for 60 DF. They keep the half-count labels the stream carries; converting them to labels at the session rate is the caller’s. Otherwise the stream wins, because reading its frames at another count would shift positions or reject frame numbers the hint cannot hold.
Sourcepub fn feed(
&mut self,
message: &[u8],
at: Duration,
) -> Result<Option<MtcEvent>, MtcError>
pub fn feed( &mut self, message: &[u8], at: Duration, ) -> Result<Option<MtcEvent>, MtcError>
Decodes one complete MIDI message received at at.
Returns a position when the message completes a quarter-frame cycle or is a full frame,
and None for a partial cycle or a message that is not MIDI Time Code.
§Errors
MtcError::MalformedMessage for a quarter frame or full frame with the wrong shape, and
MtcError::InvalidTimecode when a complete message names a position that does not exist.
A malformed message discards the partial cycle. An invalid complete position consumes the
cycle as a valid one would. Neither error replaces or refreshes the last valid position.
Sourcepub const fn lock_state(&self, now: Duration) -> LockState
pub const fn lock_state(&self, now: Duration) -> LockState
Whether the decoder is following a source at now, on the same clock as
MtcDecoder::feed.