mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-16 23:24:24 +00:00
343 lines
14 KiB
Rust
343 lines
14 KiB
Rust
//! Time as text: SMPTE timecode (drop and non-drop), frames, feet + frames, audio samples and
|
|
//! seconds, formatted and parsed the way Premiere's timecode fields do.
|
|
//!
|
|
//! Timecode is only a display of [`Tick`]s. The words around the values (the display names in a
|
|
//! menu, the error notices) are the UI's.
|
|
|
|
use crate::rates::{FrameRate, SampleRate};
|
|
use crate::time::{TICKS_PER_SECOND, Tick};
|
|
|
|
/// How time is shown (Premiere: Timecode, Feet + Frames 16 mm / 35 mm, Frames, Audio Samples;
|
|
/// After Effects' frame numbers; seconds for scripts).
|
|
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
|
|
pub enum TimeDisplay {
|
|
/// `HH:MM:SS:FF`, `HH;MM;SS;FF` for drop-frame; three frame digits from 100 fps.
|
|
#[default]
|
|
Timecode,
|
|
/// The frame number, counted from [`TimeFormat::frame_offset`] (After Effects' Start
|
|
/// Numbering Frames At).
|
|
Frames,
|
|
/// `feet+frames` at 40 frames a foot.
|
|
Feet16,
|
|
/// `feet+frames` at 16 frames a foot.
|
|
Feet35,
|
|
/// `HH:MM:SS:sssss`, the samples past the second.
|
|
AudioSamples,
|
|
/// Seconds with three decimals.
|
|
Seconds,
|
|
}
|
|
|
|
impl TimeDisplay {
|
|
/// The order of Premiere's Time Display menu.
|
|
pub const ALL: [TimeDisplay; 6] =
|
|
[TimeDisplay::Timecode, TimeDisplay::Feet35, TimeDisplay::Feet16, TimeDisplay::Frames, TimeDisplay::AudioSamples, TimeDisplay::Seconds];
|
|
}
|
|
|
|
/// Everything a time display needs: the rate, drop-frame, the display, the sample rate (for
|
|
/// [`TimeDisplay::AudioSamples`]) and the first frame's number.
|
|
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
|
|
pub struct TimeFormat {
|
|
/// The frame rate the display counts in.
|
|
pub rate: FrameRate,
|
|
/// Count in drop-frame timecode; ignored for rates without drop-frame support.
|
|
pub drop_frame: bool,
|
|
/// How the time is shown.
|
|
pub display: TimeDisplay,
|
|
/// The rate for [`TimeDisplay::AudioSamples`].
|
|
pub sample_rate: SampleRate,
|
|
/// Added to the frame number in [`TimeDisplay::Frames`] (0 or 1 in After Effects).
|
|
pub frame_offset: i64,
|
|
}
|
|
|
|
impl TimeFormat {
|
|
/// Timecode at `rate`, non-drop.
|
|
pub fn timecode(rate: FrameRate) -> Self {
|
|
Self { rate, ..Self::default() }
|
|
}
|
|
|
|
/// This format with drop-frame set to `on`.
|
|
pub fn drop_frame(mut self, on: bool) -> Self {
|
|
self.drop_frame = on;
|
|
self
|
|
}
|
|
|
|
/// This format with the given display.
|
|
pub fn display(mut self, display: TimeDisplay) -> Self {
|
|
self.display = display;
|
|
self
|
|
}
|
|
}
|
|
|
|
/// SMPTE fields of a frame count.
|
|
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
|
|
pub struct TimecodeFields {
|
|
/// Whether the time is before zero.
|
|
pub negative: bool,
|
|
/// Hours, from zero.
|
|
pub hours: i64,
|
|
/// Minutes, 0 to 59.
|
|
pub minutes: i64,
|
|
/// Seconds, 0 to 59.
|
|
pub seconds: i64,
|
|
/// Frames within the second, below the nominal frame rate.
|
|
pub frames: i64,
|
|
}
|
|
|
|
/// Why typed time was refused. The UI shows it as a notice through its own words.
|
|
#[derive(Clone, Debug, PartialEq, Eq)]
|
|
pub enum TimecodeError {
|
|
/// Nothing typed.
|
|
Empty,
|
|
/// Not a time in the field's display (`"1:x"`); carries the input.
|
|
NotATime(String),
|
|
}
|
|
|
|
impl std::fmt::Display for TimecodeError {
|
|
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
|
|
match self {
|
|
TimecodeError::Empty => f.write_str("empty timecode"),
|
|
TimecodeError::NotATime(s) => write!(f, "not a timecode: `{s}`"),
|
|
}
|
|
}
|
|
}
|
|
|
|
impl std::error::Error for TimecodeError {}
|
|
|
|
/// The SMPTE fields of `frame` at `rate`. Drop-frame (when asked and the rate supports it) skips
|
|
/// `base / 15` labels at the start of each minute except every tenth: 2 at 29.97, 4 at 59.94.
|
|
// filmcraft: crates/time/src/lib.rs:363 `frames_to_fields` (and `df_params` above it).
|
|
pub fn frames_to_fields(frame: i64, rate: FrameRate, drop_frame: bool) -> TimecodeFields {
|
|
let negative = frame < 0;
|
|
let mut n = i128::from(frame).abs();
|
|
let (drop, base) = df_params(rate);
|
|
if drop_frame && rate.supports_drop_frame() {
|
|
let per_min = base * 60 - drop;
|
|
let per_10 = per_min * 10 + drop;
|
|
let d = n / per_10;
|
|
let m = n % per_10;
|
|
n = n.saturating_add(drop * 9 * d);
|
|
if m > drop {
|
|
n = n.saturating_add(drop * ((m - drop) / per_min));
|
|
}
|
|
}
|
|
TimecodeFields {
|
|
negative,
|
|
hours: clamp_i64(n / (base * 3600)),
|
|
minutes: clamp_i64((n / (base * 60)) % 60),
|
|
seconds: clamp_i64((n / base) % 60),
|
|
frames: clamp_i64(n % base),
|
|
}
|
|
}
|
|
|
|
/// The frame count of SMPTE fields; the inverse of [`frames_to_fields`], in i128 so nominal
|
|
/// drop-frame labels past `i64` still give a frame that fits.
|
|
// filmcraft: crates/time/src/lib.rs:386 `fields_to_frames`.
|
|
pub fn fields_to_frames(fields: TimecodeFields, rate: FrameRate, drop_frame: bool) -> i64 {
|
|
let (drop, base) = df_params(rate);
|
|
let seconds = i128::from(fields.hours) * 3600 + i128::from(fields.minutes) * 60 + i128::from(fields.seconds);
|
|
let mut n = seconds.saturating_mul(base).saturating_add(i128::from(fields.frames));
|
|
if drop_frame && rate.supports_drop_frame() {
|
|
let total_min = i128::from(fields.hours) * 60 + i128::from(fields.minutes);
|
|
n = n.saturating_sub(drop * (total_min - total_min / 10));
|
|
}
|
|
clamp_i64(n)
|
|
}
|
|
|
|
/// `t` as text in `format`: timecode `00:00:10:00` (`;` separators for drop-frame, three frame
|
|
/// digits from a 100 fps base, a leading `-` for negative times); frames `250` (plus the
|
|
/// offset); feet + frames `15+10` (16 frames a foot for 35 mm, 40 for 16 mm); samples
|
|
/// `00:00:10:00000` (five digits of samples past the second); seconds `10.000` (`-0.000` shown
|
|
/// as `0.000`).
|
|
// filmcraft: crates/time/src/lib.rs:399 `format_timecode_frames`, `:408` `format_time`.
|
|
pub fn format_time(t: Tick, format: &TimeFormat) -> String {
|
|
let rate = format.rate;
|
|
let frame = rate.frame_at(t);
|
|
match format.display {
|
|
TimeDisplay::Timecode => format_timecode_frames(frame, rate, format.drop_frame),
|
|
TimeDisplay::Frames => frame.saturating_add(format.frame_offset).to_string(),
|
|
TimeDisplay::Feet35 | TimeDisplay::Feet16 => {
|
|
let per_foot = feet_divisor(format.display);
|
|
let a = frame.unsigned_abs();
|
|
format!("{}{}+{:02}", sign(frame < 0), a / per_foot, a % per_foot)
|
|
}
|
|
TimeDisplay::AudioSamples => {
|
|
let a = t.0.unsigned_abs();
|
|
let tps = TICKS_PER_SECOND.unsigned_abs();
|
|
let secs = a / tps;
|
|
let samples = Tick((a % tps) as i64).to_units_floor(i64::from(format.sample_rate.hz()));
|
|
format!("{}{:02}:{:02}:{:02}:{samples:05}", sign(t.0 < 0), secs / 3600, (secs / 60) % 60, secs % 60)
|
|
}
|
|
TimeDisplay::Seconds => {
|
|
let s = format!("{:.3}", t.seconds());
|
|
if s == "-0.000" { "0.000".to_string() } else { s }
|
|
}
|
|
}
|
|
}
|
|
|
|
/// Typed time in `format` as a tick, the way Premiere's fields read it:
|
|
/// - `01:02:03:04`, `01;02;03;04`, `1.2.3.4` (any of `:;.,` separates fields);
|
|
/// - bare digits are right-aligned as `HHMMSSFF` (`1000` is 00:00:10:00);
|
|
/// - a leading `+` or `-` is relative to `current` (`+15` is 15 frames later, `-1.00` one
|
|
/// second earlier);
|
|
/// - in [`TimeDisplay::Frames`] a bare number is a frame number (less the offset); in
|
|
/// [`TimeDisplay::Seconds`] a decimal number of seconds; feet + frames reads `ft+ff`.
|
|
///
|
|
/// The result is the first tick of the frame.
|
|
// filmcraft: crates/time/src/lib.rs:450 `parse_timecode`; soundcraft: crates/time/src/format.rs:90
|
|
// `parse_position` (the other displays).
|
|
pub fn parse_time(input: &str, format: &TimeFormat, current: Tick) -> Result<Tick, TimecodeError> {
|
|
let text = input.trim();
|
|
if text.is_empty() {
|
|
return Err(TimecodeError::Empty);
|
|
}
|
|
let bad = || TimecodeError::NotATime(input.to_string());
|
|
let rate = format.rate;
|
|
let (relative, body) = match text.as_bytes()[0] {
|
|
b'+' => (Some(1), &text[1..]),
|
|
b'-' => (Some(-1), &text[1..]),
|
|
_ => (None, text),
|
|
};
|
|
let current_frame = rate.frame_at(current);
|
|
let tick = |frame: i64| rate.tick_of(frame);
|
|
match format.display {
|
|
TimeDisplay::Timecode => {
|
|
let frames = parse_timecode_frames(body, relative, format, current_frame).ok_or_else(bad)?;
|
|
Ok(tick(frames))
|
|
}
|
|
TimeDisplay::Frames => {
|
|
let n = parse_digits(body).ok_or_else(bad)?;
|
|
Ok(tick(match relative {
|
|
Some(sign) => current_frame.saturating_add(n.saturating_mul(sign)),
|
|
None => n.saturating_sub(format.frame_offset),
|
|
}))
|
|
}
|
|
TimeDisplay::Feet16 | TimeDisplay::Feet35 => {
|
|
let per_foot = feet_divisor(format.display) as i64;
|
|
let Some((feet, frames)) = body.split_once('+') else {
|
|
// A bare number is a relative frame count: `+15`, `-3`.
|
|
let n = parse_digits(body).ok_or_else(bad)?;
|
|
return relative.map(|sign| tick(current_frame.saturating_add(n.saturating_mul(sign)))).ok_or_else(bad);
|
|
};
|
|
let total = parse_digits(feet.trim())
|
|
.zip(parse_digits(frames.trim()))
|
|
.map(|(ft, fr)| ft.saturating_mul(per_foot).saturating_add(fr))
|
|
.ok_or_else(bad)?;
|
|
Ok(tick(match relative {
|
|
Some(1) => current_frame.saturating_add(total),
|
|
Some(_) => total.saturating_neg(),
|
|
None => total,
|
|
}))
|
|
}
|
|
TimeDisplay::AudioSamples => {
|
|
let parts: Vec<i64> = body.split([':', ';', '.', ',']).map(parse_digits).collect::<Option<_>>().ok_or_else(bad)?;
|
|
let [h, m, s, samples] = parts[..] else { return Err(bad()) };
|
|
let seconds = i128::from(h) * 3600 + i128::from(m) * 60 + i128::from(s);
|
|
let ticks = seconds
|
|
.saturating_mul(i128::from(TICKS_PER_SECOND))
|
|
.saturating_add(i128::from(Tick::from_units(samples, i64::from(format.sample_rate.hz())).0));
|
|
let t = Tick(clamp_i64(ticks));
|
|
Ok(match relative {
|
|
Some(sign) => current + if sign < 0 { -t } else { t },
|
|
None => t,
|
|
})
|
|
}
|
|
TimeDisplay::Seconds => {
|
|
let value: f64 = body.trim().parse().map_err(|_| bad())?;
|
|
if !value.is_finite() || body.trim().starts_with(['+', '-']) {
|
|
return Err(bad());
|
|
}
|
|
let t = Tick::from_seconds_f64(value);
|
|
Ok(rate.snap(match relative {
|
|
Some(sign) => current + if sign < 0 { -t } else { t },
|
|
None => t,
|
|
}))
|
|
}
|
|
}
|
|
}
|
|
|
|
/// Drop-frame parameters: labels dropped per minute and the nominal base (30 gives 2, 60 gives 4).
|
|
fn df_params(rate: FrameRate) -> (i128, i128) {
|
|
let base = rate.timecode_base();
|
|
(i128::from(base / 15), i128::from(base))
|
|
}
|
|
|
|
fn clamp_i64(value: i128) -> i64 {
|
|
value.clamp(i128::from(i64::MIN), i128::from(i64::MAX)) as i64
|
|
}
|
|
|
|
fn sign(negative: bool) -> &'static str {
|
|
if negative { "-" } else { "" }
|
|
}
|
|
|
|
/// Frames in a foot of film for a feet display.
|
|
fn feet_divisor(display: TimeDisplay) -> u64 {
|
|
if display == TimeDisplay::Feet35 { 16 } else { 40 }
|
|
}
|
|
|
|
fn format_timecode_frames(frame: i64, rate: FrameRate, drop_frame: bool) -> String {
|
|
let drop = drop_frame && rate.supports_drop_frame();
|
|
let f = frames_to_fields(frame, rate, drop);
|
|
let sep = if drop { ';' } else { ':' };
|
|
let width = if rate.timecode_base() >= 100 { 3 } else { 2 };
|
|
format!("{}{:02}{sep}{:02}{sep}{:02}{sep}{:0width$}", sign(f.negative), f.hours, f.minutes, f.seconds, f.frames)
|
|
}
|
|
|
|
/// A string of ASCII digits as a number; `None` when empty, not all digits or too large.
|
|
fn parse_digits(s: &str) -> Option<i64> {
|
|
if s.is_empty() || !s.bytes().all(|b| b.is_ascii_digit()) {
|
|
return None;
|
|
}
|
|
s.parse().ok()
|
|
}
|
|
|
|
/// Typed timecode as a frame count: separated fields, or bare digits read right-aligned in pairs
|
|
/// (a relative bare number is a frame count). Fields may overflow their unit (90 frames).
|
|
fn parse_timecode_frames(body: &str, relative: Option<i64>, format: &TimeFormat, current: i64) -> Option<i64> {
|
|
let rate = format.rate;
|
|
let parts: Vec<&str> = body.split([':', ';', '.', ',']).collect();
|
|
let nums: Vec<i64> = if parts.len() == 1 {
|
|
let digits = parts[0];
|
|
if relative.is_some() {
|
|
vec![parse_digits(digits)?]
|
|
} else {
|
|
if digits.is_empty() || !digits.bytes().all(|b| b.is_ascii_digit()) {
|
|
return None;
|
|
}
|
|
let mut v = Vec::new();
|
|
let mut end = digits.len();
|
|
while end > 0 {
|
|
let start = end.saturating_sub(2);
|
|
v.push(digits[start..end].parse::<i64>().unwrap_or(0));
|
|
end = start;
|
|
}
|
|
v.reverse();
|
|
v
|
|
}
|
|
} else {
|
|
parts.iter().map(|p| if p.is_empty() { Some(0) } else { parse_digits(p) }).collect::<Option<_>>()?
|
|
};
|
|
if nums.len() > 4 {
|
|
return None;
|
|
}
|
|
let mut fields = [0i64; 4];
|
|
fields[4 - nums.len()..].copy_from_slice(&nums);
|
|
let [h, m, s, f] = fields;
|
|
let base = rate.timecode_base();
|
|
let frames = if nums.len() == 1 && relative.is_some() {
|
|
f
|
|
} else if format.drop_frame && rate.supports_drop_frame() {
|
|
// Fields past their range carry into the next one first, then drop-frame counting applies:
|
|
// 01;00;00;30 is the frame 01;00;01;00 names.
|
|
let (s, f) = (s.saturating_add(f / base), f % base);
|
|
let (m, s) = (m.saturating_add(s / 60), s % 60);
|
|
let (h, m) = (h.saturating_add(m / 60), m % 60);
|
|
fields_to_frames(TimecodeFields { negative: false, hours: h, minutes: m, seconds: s, frames: f }, rate, true)
|
|
} else {
|
|
h.saturating_mul(3600).saturating_add(m.saturating_mul(60)).saturating_add(s).saturating_mul(base).saturating_add(f)
|
|
};
|
|
Some(match relative {
|
|
Some(sign) => current.saturating_add(frames.saturating_mul(sign)),
|
|
None => frames,
|
|
})
|
|
}
|