From 268a922dccbcf2c556f049ba2304d4fbcb175ddf Mon Sep 17 00:00:00 2001 From: JonRC Date: Wed, 11 Nov 2026 23:38:02 +0000 Subject: [PATCH] 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. --- crates/captions/README.md | 7 +++- crates/captions/src/lib.rs | 74 +++++++++++++++++++++++++++++++++++++- crates/captions/src/mcc.rs | 34 ++++++++++++++++-- crates/captions/src/scc.rs | 36 +++++++++++++++++-- 4 files changed, 145 insertions(+), 6 deletions(-) diff --git a/crates/captions/README.md b/crates/captions/README.md index e91972554..60fed235b 100644 --- a/crates/captions/README.md +++ b/crates/captions/README.md @@ -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 diff --git a/crates/captions/src/lib.rs b/crates/captions/src/lib.rs index db543dbad..752976f11 100644 --- a/crates/captions/src/lib.rs +++ b/crates/captions/src/lib.rs @@ -149,12 +149,55 @@ pub struct Document { pub blocks: Vec, /// Non-fatal problems found while reading (skipped cues…). pub warnings: Vec, + /// 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, } +/// 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 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] { diff --git a/crates/captions/src/mcc.rs b/crates/captions/src/mcc.rs index 7169a4ec7..7b13ac3c2 100644 --- a/crates/captions/src/mcc.rs +++ b/crates/captions/src/mcc.rs @@ -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 { 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() { diff --git a/crates/captions/src/scc.rs b/crates/captions/src/scc.rs index e0000cff9..d9ca1deed 100644 --- a/crates/captions/src/scc.rs +++ b/crates/captions/src/scc.rs @@ -292,6 +292,8 @@ pub fn parse(text: &str) -> Result { 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)> = 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