smpte-timecode
smpte-timecode converts SMPTE timecode to and from frames, seconds and samples with exact drop-frame handling, and decodes and encodes MIDI Time Code.
- Parse and format
HH:MM:SS:FFand drop-frameHH:MM:SS;FFlabels at 19 frame rates, from 23.976 to 120 DF, with frame arithmetic that wraps at midnight. - Convert positions to exact rational seconds, and to and from sample positions with an explicit rounding rule. NTSC rates such as 29.97 rarely land on a whole sample.
- Apply exact 0.1% and 4% pull-up and pull-down factors to frame rates and sample rates.
- Decode MIDI Time Code quarter frames and full frames into checked positions. A position is produced only from eight consecutive pieces in one direction, so locates, lost pieces and direction changes never mix two positions. Forward positions are compensated for the two-frame cycle latency, and the decoder reports its direction and lock state.
- Encode quarter-frame streams and full-frame messages.
The crate is no_std, does not allocate and has no dependencies. The minimum supported Rust
version is 1.85.
Install
[]
= "0.1.1"
Example
use Duration;
use ;
Scope and limits
- A
Timecodeis a position within one 24-hour day. Subframes are not represented. - 29.97 DF and 59.94 DF skip 2 and 4 labels per minute as SMPTE ST 12-1 defines. 30 DF, 60 DF, 119.88 DF and 120 DF apply the same rule with 2, 4, 8 and 8 labels, matching Pro Tools labels.
- MIDI Time Code rate codes name only 24, 25, 29.97 DF and 30. The encoder sends 23.976 as 24, 29.97 as 30 and 30 DF as 29.97 DF, and cannot send 48 frames per second or faster. Give the decoder a rate hint, such as the DAW session rate, to recover the rates the code cannot name when their nominal frame counts match. A session at twice the code's count sends half-count MTC, as Pro Tools does at 48, 50, 59.94 and 60: positions then run at the half rate with the session's 1000/1001 factor and drop-frame counting, such as 29.97 for 59.94, and keep the half-count labels. Otherwise the decoder follows the stream rate.
- The decoder takes complete MIDI messages. It does not open ports, assemble SysEx from a raw byte stream, read user bits, MIDI Machine Control or MIDI Cueing, or estimate speed. The encoder builds bytes; the caller sends them at the interval it reports.
- LTC and VITC are not supported.
The API reference documents every type, and
llms.txt summarizes the contract.
Development
Use the toolchain in rust-toolchain.toml with rustfmt and Clippy. Dependency checks use
cargo-deny. The Pro Tools capture notes
document the recording procedure and verification limits.
RUSTDOCFLAGS='-D warnings'
License
Licensed under either the Apache License, Version 2.0 or the MIT license, at your option. Both license texts are included in the published crate.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.