mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-18 23:12:11 +00:00
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:
@@ -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
|
||||
|
||||
|
||||
@@ -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] {
|
||||
|
||||
@@ -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() {
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user