craft-captions: SCC and MCC time codes count from the document's start timecode

Ported from the caption-format part of storytold/filmcraft#4131
(filmcraft#4130). Document::start_timecode is the label of time zero; the SCC
and MCC writers count from the 29.97 frame with the same label, so the label
carries across rates. Readers note the rate and drop-frame mode of a file's
labels in Document::labels, and Document::count_from counts cues back from a
start time code. charset_warnings names the time codes the file has, which
that pull request's review found missing.
This commit is contained in:
JonRC
2026-11-11 23:38:02 +00:00
committed by Dylan M. Taylor
parent 8698a4f7f2
commit 268a922dcc
4 changed files with 145 additions and 6 deletions
+6 -1
View File
@@ -58,7 +58,12 @@ lists at most 20 characters per stream.
All cue times are exact `Tick`s. Milliseconds convert exactly (1 ms = 254 016 000 ticks); SCC
frames map through `FrameRate::FPS_29_97`. `Document::snap_to_frames` snaps cues to a frame grid and
removes overlaps.
removes overlaps. SCC and MCC time codes count from `Document::start_timecode`, a time code
label read as a time (`label_time`), so the label carries across rates: 01:00:00:00 at 25 fps is
written as 01:00:00;00 drop-frame or 01:00:00:00 non-drop (`label_frame`). Readers leave it at
zero and keep the file's own time codes, noting the rate and drop-frame mode of its labels in
`Document::labels`; `Document::count_from` then counts the cues back from a start time code, when
every cue is at or after it.
### TTML tick timing
+73 -1
View File
@@ -149,12 +149,55 @@ pub struct Document {
pub blocks: Vec<String>,
/// Non-fatal problems found while reading (skipped cues…).
pub warnings: Vec<String>,
/// SCC / MCC: the time code label of time zero, read as a time ([`label_time`]: a sequence's
/// start timecode on export). The writers count their time codes from the label it reads as,
/// so 01:00:00:00 at 25 fps is 01:00:00;00 or 01:00:00:00 at 29.97. Readers leave it at zero.
pub start_timecode: Tick,
/// SCC / MCC read from a file: the frame rate of its time code labels and whether they are
/// drop-frame. [`Document::count_from`] needs it.
pub labels: Option<(FrameRate, bool)>,
/// BCP 47 language tag of the text, when known: TTML's `xml:lang` on import, the caption
/// track's language on export. TTML and DFXP write it (else `en`).
pub language: Option<String>,
}
/// Frame `frame` of a `rate` time code (drop-frame or not) as its label read as a time: hours,
/// minutes, seconds and the frame's share of a second at the label's nominal rate (25 for 25 fps,
/// 30 for 29.97). Negative frames read as zero.
pub fn label_time(frame: i64, rate: FrameRate, drop_frame: bool) -> Tick {
let base = rate.timecode_base();
let (_, h, m, s, f) = crate::time::frames_to_fields(frame.max(0), rate, drop_frame && rate.supports_drop_frame());
let seconds = h.saturating_mul(3600).saturating_add(m.saturating_mul(60)).saturating_add(s);
Tick(TICKS_PER_SECOND.saturating_mul(seconds)) + FrameRate::new(base, 1).tick_of(f)
}
/// The frame of a `rate` time code (drop-frame or not) whose label reads as `label` (as
/// [`label_time`] gives it), to the nearest frame of the label's nominal rate.
pub fn label_frame(label: Tick, rate: FrameRate, drop_frame: bool) -> i64 {
let nominal = FrameRate::new(rate.timecode_base(), 1);
let n = nominal.frame_at(nominal.snap_nearest(label.max(Tick::ZERO)));
let (_, h, m, s, f) = crate::time::frames_to_fields(n, nominal, false);
crate::time::fields_to_frames(h, m, s, f, rate, drop_frame && rate.supports_drop_frame())
}
impl Document {
/// SCC / MCC read from a file: count cue times from the time code labelled `start` (as
/// [`Document::start_timecode`]) rather than from 00:00:00:00, the inverse of what the writers
/// do. Only when every cue is at or after it, so a file that counts from zero keeps its times.
/// Returns whether the cues moved.
pub fn count_from(&mut self, start: Tick) -> bool {
let Some((rate, drop_frame)) = self.labels else { return false };
let origin = rate.tick_of(label_frame(start, rate, drop_frame));
if origin <= Tick::ZERO || self.cues.iter().any(|c| c.start < origin) {
return false;
}
for c in &mut self.cues {
c.start -= origin;
c.end -= origin;
}
true
}
/// Snap cue times to frame boundaries of `rate` (nearest), keeping every cue at least one frame
/// long and removing overlaps (a cue is cut where the next one starts).
pub fn snap_to_frames(&mut self, rate: FrameRate) {
@@ -332,7 +375,8 @@ fn lossy_chars(doc: &Document, stream: &str, shown_as: impl Fn(char) -> Option<c
let times = |n: usize| if n == 1 { "once".to_string() } else { format!("{n} times") };
for &(c, shown, n, frame) in lost.iter().take(LISTED_CHARS) {
let what = shown.map_or_else(|| "dropped".to_string(), |s| format!("written as \"{s}\""));
let at = scc::format_timecode(frame, drop_frame);
// the time code the file has for it: counted from the start time code, as the writers do
let at = scc::format_timecode(frame.saturating_add(label_frame(doc.start_timecode, scc::RATE, drop_frame)), drop_frame);
out.push(format!("{stream} has no \"{c}\" (U+{:04X}): {what} {}, first in the caption at {at}", c as u32, times(n)));
}
if let Some(rest) = lost.get(LISTED_CHARS..).filter(|rest| !rest.is_empty()) {
@@ -415,6 +459,31 @@ pub fn format_clock(t: Tick, sep: char) -> String {
mod tests {
use super::*;
/// A start time code keeps its label from a sequence's rate to the SCC / MCC 29.97 grid.
#[test]
fn start_timecode_labels_carry_across_rates() {
let secs = |s: i64| Tick(TICKS_PER_SECOND * s);
let scc = FrameRate::FPS_29_97;
// 01:00:00:00 at 25, 24 and 29.97 drop-frame all read as one hour
assert_eq!(label_time(90_000, FrameRate::FPS_25, false), secs(3600));
assert_eq!(label_time(86_400, FrameRate::FPS_23_976, false), secs(3600));
assert_eq!(label_time(107_892, scc, true), secs(3600));
assert_eq!(label_time(108_000, scc, false), secs(3600));
// 01:00:02:00 at 25 fps is 01:00:02;00 drop-frame and 01:00:02:00 non-drop at 29.97
let two = label_time(90_050, FrameRate::FPS_25, false);
assert_eq!(crate::time::format_timecode_frames(label_frame(two, scc, true), scc, true), "01;00;02;00");
assert_eq!(crate::time::format_timecode_frames(label_frame(two, scc, false), scc, false), "01:00:02:00");
// a frame's share of a second goes to the nearest 29.97 label frame
assert_eq!(label_frame(label_time(90_001, FrameRate::FPS_25, false), scc, false), 108_001);
// drop-frame on a rate that has none counts non-drop
assert_eq!(label_time(90_000, FrameRate::FPS_25, true), secs(3600));
// hostile values neither panic nor go negative
assert_eq!(label_time(-5, FrameRate::FPS_25, false), Tick::ZERO);
assert!(label_time(i64::MAX, FrameRate::FPS_25, false) > Tick::ZERO);
assert_eq!(label_frame(Tick(i64::MIN), scc, true), 0);
assert!(label_frame(Tick(i64::MAX), scc, true) > 0);
}
#[test]
fn clock() {
assert_eq!(parse_clock("00:00:01,500"), Some(Tick(TICKS_PER_SECOND * 3 / 2)));
@@ -467,6 +536,9 @@ mod tests {
// CEA-708 carries … (G2) and ’ but not the em dash, which 608 does carry
let em_dash = "CEA-708 has no \"—\" (U+2014): written as \"?\" once, first in the caption at 00:00:00;00";
assert_eq!(charset_warnings(&doc, Format::Mcc, opts), [dropped, replaced, em_dash]);
// a document that starts at 01:00:00:00 names the time codes its file has
let master = Document { start_timecode: Tick(3600 * TICKS_PER_SECOND), ..doc.clone() };
assert!(charset_warnings(&master, Format::Scc, opts)[0].ends_with("first in the caption at 01:00:00;00"));
let ndf = charset_warnings(&doc, Format::Scc, WriteOptions { drop_frame: false, ..opts });
assert!(ndf[0].ends_with("00:00:00:00"), "{ndf:?}");
for f in [Format::Srt, Format::WebVtt, Format::Ttml, Format::Dfxp] {
+32 -2
View File
@@ -603,6 +603,7 @@ pub fn write_with(doc: &Document, drop_frame: bool, cea608: bool, cea708: bool,
let program = header_value(program);
let f1 = if cea608 { scc::schedule(doc) } else { BTreeMap::new() };
let dtv = if cea708 { schedule_708(doc) } else { BTreeMap::new() };
let origin = crate::label_frame(doc.start_timecode, RATE, drop_frame); // time codes count from the start time code
let mut out = String::from("File Format=MacCaption_MCC V1.0\n\n");
out.push_str("///////////////////////////////////////////////////////////////////////////////////\n");
out.push_str(&format!("// Closed captions written by {program}: SMPTE ST 334-2 caption distribution packets\n"));
@@ -633,7 +634,7 @@ pub fn write_with(doc: &Document, drop_frame: bool, cea608: bool, cea708: bool,
f1: f1.next_if(|(frame, _)| *frame == f).map(|(_, pair)| pair),
dtvcc: dtv.next_if(|(frame, _)| *frame == f).map(|(_, pairs)| pairs).unwrap_or_default(),
};
let (_, hh, mm, ss, ff) = frames_to_fields(f, RATE, drop_frame);
let (_, hh, mm, ss, ff) = frames_to_fields(f.saturating_add(origin), RATE, drop_frame);
let sep = if drop_frame { ';' } else { ':' };
out.push_str(&format!("{hh:02}:{mm:02}:{ss:02}{sep}{ff:02}\t{}\n", compress(&build_cdp(seq, &data))));
seq = seq.wrapping_add(1);
@@ -685,7 +686,9 @@ pub fn parse(text: &str) -> Result<Document> {
let Some([h, m, s, f]) = parts.as_deref() else {
return Err(Error::Syntax { line: n + 1, msg: format!("bad timecode \"{tc}\"") });
};
let frame = fields_to_frames(*h, *m, *s, *f, rate.0, rate.1 || tc.contains(';'));
let drop_frame = rate.1 || tc.contains(';');
doc.labels.get_or_insert((rate.0, drop_frame));
let frame = fields_to_frames(*h, *m, *s, *f, rate.0, drop_frame);
let Some(bytes) = expand(data) else {
doc.warnings.push(format!("line {}: bad caption data", n + 1));
continue;
@@ -839,6 +842,33 @@ mod tests {
}
}
/// Time codes count from the label of the document's start time code, drop-frame or not; the
/// packets do not change, and `Document::count_from` reads the cues back from it.
#[test]
fn time_codes_count_from_the_start_timecode() {
let doc = Document { cues: vec![cue(60, 120, "Caption")], ..Default::default() };
let hour = crate::time::Tick(3600 * crate::time::TICKS_PER_SECOND); // the label 01:00:00:00
let master = Document { start_timecode: hour, ..doc.clone() };
let lines = |text: &str| -> Vec<(i64, String)> {
text.lines().filter_map(|l| l.split_once('\t')).map(|(tc, data)| (scc::parse_timecode(tc).unwrap(), data.to_string())).collect()
};
for (drop_frame, origin) in [(true, 107_892), (false, 108_000)] {
let plain = lines(&write(&doc, drop_frame));
let shifted: Vec<_> = plain.iter().map(|(f, data)| (f + origin, data.clone())).collect();
let text = write(&master, drop_frame);
assert_eq!(lines(&text), shifted);
assert!(text.contains("\n01:00:0"), "{text}");
let mut back = parse(&text).unwrap();
assert_eq!(back.labels, Some((RATE, drop_frame)));
assert_eq!(back.cues[0].start, RATE.tick_of(origin + 60));
assert!(back.count_from(hour));
assert_eq!(back.cues, parse(&write(&doc, drop_frame)).unwrap().cues, "read back from the start time code");
}
let negative = Document { start_timecode: crate::time::Tick(-1), ..doc.clone() };
assert_eq!(lines(&write(&negative, true)), lines(&write(&doc, true)), "a negative start counts from zero");
assert!(write(&Document { start_timecode: crate::time::Tick(i64::MAX), ..doc }, true).contains('\t'));
}
/// Bound output for distant or long cues near the tick limit without changing their timing.
#[test]
fn distant_and_long_cues_round_trip_near_tick_limit() {
+34 -2
View File
@@ -292,6 +292,8 @@ pub fn parse(text: &str) -> Result<Document> {
let Some(frame) = parse_timecode(tc) else {
return Err(Error::Syntax { line: n + 1, msg: format!("bad timecode \"{tc}\"") });
};
// the first time code says how the file counts (drop-frame or not)
doc.labels.get_or_insert((RATE, tc.contains([';', '.', ','])));
for (k, w) in it.enumerate() {
let Ok(v) = u16::from_str_radix(w, 16) else {
doc.warnings.push(format!("line {}: bad code word \"{w}\"", n + 1));
@@ -498,6 +500,7 @@ pub fn code_word(p: (u8, u8)) -> u16 {
pub fn write(doc: &Document, drop_frame: bool) -> String {
let occ = schedule(doc);
let origin = crate::label_frame(doc.start_timecode, RATE, drop_frame); // time codes count from the start time code
let mut out = String::from(HEADER);
out.push_str("\n\n");
let mut line: Option<(i64, Vec<String>)> = None;
@@ -506,13 +509,13 @@ pub fn write(doc: &Document, drop_frame: bool) -> String {
if f != last + 1
&& let Some((start, words)) = line.take()
{
out.push_str(&format!("{}\t{}\n\n", format_timecode(start, drop_frame), words.join(" ")));
out.push_str(&format!("{}\t{}\n\n", format_timecode(start.saturating_add(origin), drop_frame), words.join(" ")));
}
line.get_or_insert_with(|| (f, Vec::new())).1.push(format!("{:04x}", word(p)));
last = f;
}
if let Some((start, words)) = line {
out.push_str(&format!("{}\t{}\n\n", format_timecode(start, drop_frame), words.join(" ")));
out.push_str(&format!("{}\t{}\n\n", format_timecode(start.saturating_add(origin), drop_frame), words.join(" ")));
}
out
}
@@ -554,6 +557,35 @@ mod tests {
assert_eq!(parse_timecode("00:10:00;00"), Some(17982));
}
/// Time codes count from the label of the document's start time code, drop-frame or not; the
/// code words do not change, and `Document::count_from` reads the cues back from it.
#[test]
fn time_codes_count_from_the_start_timecode() {
let doc = Document { cues: vec![cue(60, 120, "Hello")], ..Default::default() };
let hour = Tick(3600 * crate::time::TICKS_PER_SECOND); // the label 01:00:00:00
let master = Document { start_timecode: hour, ..doc.clone() };
let lines = |text: &str| -> Vec<(i64, String)> {
text.lines().filter_map(|l| l.split_once('\t')).map(|(tc, words)| (parse_timecode(tc).unwrap(), words.to_string())).collect()
};
for (drop_frame, origin) in [(true, 107_892), (false, 108_000)] {
let plain = lines(&write(&doc, drop_frame));
let shifted: Vec<_> = plain.iter().map(|(f, words)| (f + origin, words.clone())).collect();
let text = write(&master, drop_frame);
assert_eq!(lines(&text), shifted);
assert!(text.contains("\n01:00:0"), "{text}");
let mut back = parse(&text).unwrap();
assert_eq!(back.labels, Some((RATE, drop_frame)));
assert_eq!(back.cues[0].start, RATE.tick_of(origin + 60));
assert!(back.count_from(hour));
assert_eq!(back.cues, parse(&write(&doc, drop_frame)).unwrap().cues, "read back from the start time code");
assert!(!back.count_from(hour), "a cue before the start time code keeps its time");
}
for t in [Tick(i64::MIN), Tick(-1)] {
assert_eq!(write(&Document { start_timecode: t, ..doc.clone() }, true), write(&doc, true), "a negative start counts from zero");
}
assert!(write(&Document { start_timecode: Tick(i64::MAX), ..doc }, true).contains('\t'));
}
#[test]
fn decode_known_popon() {
// "HELLO" on row 15 at 00:00:01;00, cleared at 00:00:03;00