Files
craft-libs/crates/captions/src/srt.rs
T
fdbb9c2471 craft-captions: TTML import keeps inherited styles; literal < and & stay text (#983)
* craft-captions: TTML cue text collapses only XML whitespace and keeps edge line breaks

Ported from storytold/filmcraft#3145. char::is_whitespace also matched U+00A0,
U+2009 and U+3000, so no-break spaces became ordinary spaces on import, and a
leading or trailing <br/> was trimmed away.

* craft-captions: TTML/DFXP export drops characters XML 1.0 forbids

Ported from storytold/filmcraft#4467. A control character in cue text made the
exported file unreadable. The filter also covers U+FFFE and U+FFFF, which the
review of that pull request asked for.

* craft-captions: WebVTT cue-text arrow escape is reversible

Ported from storytold/filmcraft#4437. A literal --&gt; in cue text came back as
--> after a write and parse; the writer now adds one amp; level and the reader
removes exactly one.

* craft-captions: a WebVTT speaker name with > no longer spills into the cue text

Ported from storytold/filmcraft#4470. The writer puts the lookalike U+203A in
place of > inside the voice tag. Also from that pull request's review: a line
break in a name is written as a space, and a name ending in - is kept apart
from the tag's closing >.

* craft-captions: an SRT text line that looks like a timing line survives a round trip

Ported from storytold/filmcraft#4448. The writer marks such a line with a
leading zero-width space and the reader removes it, so the cue is not split.

* craft-captions: back-to-back SCC captions with the same text stay separate cues

Ported from storytold/filmcraft#3808. Every End of Caption now closes the open
cue. MCC's CEA-608 path uses the same decoder.

* craft-captions: an SCC pop-on load may run across the previous caption's erase

Ported from storytold/filmcraft#1837 (filmcraft#1791). A caption that closely
follows another popped on about a second late, because its load had to be one
unbroken run of free frames. Doubled codes stay adjacent; pauses are allowed
between them.

* craft-captions: CEA-708 export starts each caption at its window's top left

Ported from storytold/filmcraft#4043 (filmcraft#4042). Each window load now
sends DeleteWindows before DefineWindow in place of the ClearWindows after it:
a window made anew is empty with the pen at its top left in any decoder, for
the same number of bytes, so cue timing is unchanged.

* craft-captions: TTML/DFXP export keeps literal < and > text

Ported from storytold/filmcraft#2830. The writer treated every < with a later >
as a tag and wrote nothing for unknown names, so "1 < 2 and 3 > 2" lost its
middle. Only a well-formed tag is markup now; a > inside a quoted attribute
value does not end the tag.

* craft-captions: TTML/DFXP export keeps cue IDs unique and valid Unicode IDs as written

Ported from the TTML commit of storytold/filmcraft#1839. A cue named s1 could
collide with the style ID, and a generated c1 could take the ID of a later cue.
Valid explicit IDs are reserved first; missing, invalid or repeated ones get a
replacement that is in no one's way. IDs are checked as XML NCNames.

* craft-captions: compare the craft-xml and roxmltree views of TTML documents

The TTML reader moved from roxmltree to craft-xml. This dev-only test checks
that both hand it the same elements, attributes and text, by namespace, on
TTML documents and on the writer's output. roxmltree becomes a dev-dependency,
which the cue ID tests use too.

* craft-captions: use craft-timeline's exact time instead of a private copy

craft-captions carried a 290-line subset of the tick, frame rate and timecode
field code because craft-libs had none when it was added. craft-timeline now
has the whole module with the same tick unit. craft_captions::time is a
re-export of craft_timeline::time, so every public path still resolves and
the types are now the same ones craft-timeline's callers hold.

* 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.

* craft-captions: MCC export can write a packet on every frame

Ported from the caption-format part of storytold/filmcraft#4037
(filmcraft#4024). WriteOptions::every_frame_until fills every 29.97 fps frame
before that time that has no caption data with a packet of CEA-608 nulls and
CEA-708 padding, as SDI and frame-wrapped MXF carry one per frame. Off by
default, at most 24 hours (mcc::MAX_PADDED_FRAMES), and write_to streams the
file line by line.

* craft-captions: README has its MCC writer section, with the every-frame option

The section's text was cut off when the crate was added; only a stray heading
marker was left.

* craft-captions: export warnings name STL's ? and text cut to fit

Ported from storytold/filmcraft#4157 (filmcraft#4155, filmcraft#4156).
charset_warnings now names the characters EBU STL writes as ? (from the
writer's own encoder, at the STL file's time code) and each caption that
CEA-608's 15 rows or the CEA-708 window's 12 rows cut, with how much it lost.
The CEA-708 writer loads only the 12 rows its window holds. The time codes
count from the document's start time code, as the files do.

* craft-captions: TTML import keeps inherited and reset text styles

Ported from the TTML style part of storytold/filmcraft#1723
(filmcraft#1721). Italic, bold and underline set on <body> or on a timed
<span> cue root now reach the cue text; normal, noUnderline and inherit reset
or restore the parent value; styling is read from the TTML styling
namespaces (modern and 2006 drafts) with unqualified attributes as a
fallback, and foreign namespaces are ignored. The inline text collector is
iterative. Line breaks at the start or end of a cue are kept, as #3145's port
does, so this differs from the source pull request there.

* craft-captions: literal < and & stay text beside cue style tags

Ported from the literal-text part of storytold/filmcraft#1723. The TTML and
EBU STL readers keep a literal < as &lt; (and an & that would read as an
entity as &amp;), as a WebVTT import already keeps its entities, so text
like "&lt;b&gt;" in a TTML file never becomes a bold tag. The TTML and STL
writers decode those entities, so a cue read from WebVTT with "1 &lt; 2" is
no longer written as "1 &amp;lt; 2". entity_at and decode_entities are
shared with plain_text.

---------

Co-authored-by: NetterSilver <133535268+Silvertree2010@users.noreply.github.com>
Co-authored-by: SeeRay11 <searay112023@gmail.com>
Co-authored-by: jnohclee-rgb <336857373+jnohclee-rgb@users.noreply.github.com>
Co-authored-by: JonRC <jonarc06@gmail.com>
Co-authored-by: sanyamsingh001 <314051937+sanyamsingh001@users.noreply.github.com>
Co-authored-by: nuclearspike <liquidmonkey@gmail.com>
2026-11-11 20:16:34 -05:00

193 lines
7.1 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! SubRip (`.srt`).
//!
//! ```text
//! 1
//! 00:00:01,000 --> 00:00:03,500
//! First line
//! <i>second line</i>
//!
//! 2
//! …
//! ```
//!
//! Reading accepts what real files contain: missing or wrong indexes, `.` instead of `,`, 1–3
//! digit fractions, missing hours, extra spaces, trailing SSA position coordinates
//! (`X1:… Y2:…`), and cues not separated by a blank line (a new cue starts at a timing line, or at
//! an integer line directly followed by one). Writing renumbers from 1 and rounds to milliseconds.
use crate::time::Tick;
use crate::{Cue, Document, Error, Result, format_clock, parse_clock};
/// Parse `start --> end[ settings]` (SRT or VTT timing line). Returns (start, end, settings).
pub fn parse_timing_line(line: &str) -> Option<(Tick, Tick, &str)> {
let (a, rest) = line.split_once("-->")?;
let start = parse_clock(a.trim())?;
let rest = rest.trim_start();
let end_len = rest.find(char::is_whitespace).unwrap_or(rest.len());
let end = parse_clock(&rest[..end_len])?;
Some((start, end, rest[end_len..].trim()))
}
fn is_index(line: &str) -> bool {
let l = line.trim();
!l.is_empty() && l.len() <= 10 && l.bytes().all(|b| b.is_ascii_digit())
}
const ZWSP: char = '\u{200B}';
/// Keep a text line from reading as a timing line: such a line gains a leading zero-width space.
fn escape(line: &str) -> String {
if parse_timing_line(line.trim_start_matches(ZWSP)).is_some() { format!("{ZWSP}{line}") } else { line.to_string() }
}
/// Reverse [`escape`]: drop one leading zero-width space when the rest still looks like a timing line.
fn unescape_line(line: &str) -> &str {
match line.strip_prefix(ZWSP) {
Some(r) if parse_timing_line(r.trim_start_matches(ZWSP)).is_some() => r,
_ => line,
}
}
pub fn parse(text: &str) -> Result<Document> {
let text = text.strip_prefix('\u{feff}').unwrap_or(text);
let lines: Vec<&str> = text.lines().collect();
let mut doc = Document::default();
let mut i = 0;
let mut found_any = false;
while i < lines.len() {
let Some((start, end, _settings)) = parse_timing_line(lines[i]) else {
let l = lines[i].trim();
if !l.is_empty() && !is_index(l) && found_any {
doc.warnings.push(format!("line {}: ignored stray text \"{l}\"", i + 1));
}
i += 1;
continue;
};
found_any = true;
i += 1;
let mut text_lines: Vec<&str> = Vec::new();
while i < lines.len() {
let l = lines[i];
if l.trim().is_empty() {
break;
}
if parse_timing_line(l).is_some() {
break;
}
if is_index(l) && lines.get(i + 1).is_some_and(|n| parse_timing_line(n).is_some()) {
break;
}
text_lines.push(unescape_line(l.trim_end()));
i += 1;
}
if end <= start {
doc.warnings.push(format!("cue at {} has end before start; skipped", format_clock(start, ',')));
continue;
}
doc.cues.push(Cue { start, end, text: text_lines.join("\n"), ..Default::default() });
}
if !found_any && !text.trim().is_empty() {
return Err(Error::NotFormat("SubRip"));
}
Ok(doc)
}
pub fn write(doc: &Document) -> String {
let mut out = String::new();
for (n, c) in doc.cues.iter().enumerate() {
out.push_str(&format!("{}\n{} --> {}\n", n + 1, format_clock(c.start, ','), format_clock(c.end, ',')));
// blank lines inside text would end the cue: drop them
for l in c.text.lines().filter(|l| !l.trim().is_empty()) {
// stored entities stay as they are, so a literal bracket does not become a tag on reimport
out.push_str(&escape(l));
out.push('\n');
}
out.push('\n');
}
out
}
#[cfg(test)]
mod tests {
use super::*;
use crate::TICKS_PER_MS;
fn ms(v: i64) -> Tick {
Tick(v * TICKS_PER_MS)
}
#[test]
fn entities_stay_distinct_from_style_tags_after_reimport() {
let mut d = Document::default();
d.cues.push(Cue { start: ms(1000), end: ms(2000), text: "1 &lt; 2 &amp; <i>x</i>".into(), ..Default::default() });
let encoded = write(&d);
assert_eq!(encoded, "1\n00:00:01,000 --> 00:00:02,000\n1 &lt; 2 &amp; <i>x</i>\n\n");
let decoded = parse(&encoded).unwrap();
assert_eq!(decoded.cues, d.cues);
assert_eq!(crate::plain_text(&decoded.cues[0].text), "1 < 2 & x");
}
#[test]
fn basic() {
let d = parse("1\n00:00:01,000 --> 00:00:02,500\nHello\n<i>World</i>\n\n2\n00:00:03,000 --> 00:00:04,000\nBye\n").unwrap();
assert_eq!(d.cues.len(), 2);
assert_eq!(d.cues[0].start, ms(1000));
assert_eq!(d.cues[0].end, ms(2500));
assert_eq!(d.cues[0].text, "Hello\n<i>World</i>");
assert_eq!(write(&d), "1\n00:00:01,000 --> 00:00:02,500\nHello\n<i>World</i>\n\n2\n00:00:03,000 --> 00:00:04,000\nBye\n\n");
}
#[test]
fn sloppy() {
// no indexes, period ms, short fractions, no hours, coordinates, no blank line between cues
let src = "00:00:01.5 --> 00:00:02.25 X1:10 X2:20 Y1:1 Y2:2\nA\n7\n00:03,000 --> 00:04,000\nB\n00:00:05,000-->00:00:06,000\n42\n\n\n";
let d = parse(src).unwrap();
let got: Vec<(i64, i64, &str)> = d.cues.iter().map(|c| (c.start.0 / TICKS_PER_MS, c.end.0 / TICKS_PER_MS, c.text.as_str())).collect();
assert_eq!(got, vec![(1500, 2250, "A"), (3000, 4000, "B"), (5000, 6000, "42")]);
}
#[test]
fn round_trips_text_line_that_looks_like_timing() {
let mut d = parse("1\n00:00:01,000 --> 00:00:02,000\nx\n").unwrap();
d.cues[0].text = "Shift:\n9:00 --> 10:00".into();
let back = parse(&write(&d)).unwrap();
assert_eq!(back.cues.len(), 1);
assert_eq!(back.cues[0].text, "Shift:\n9:00 --> 10:00");
}
#[test]
fn round_trips_arrow_and_marker_text() {
for text in ["a --&gt; b", "a --&amp;gt; b", "a --> b", "Shift:\n9:00 --> 10:00\n\u{200B}9:00 --> 10:00", "5\n9:00 --> 10:00"] {
let mut d = parse("1\n00:00:01,000 --> 00:00:02,000\nx\n").unwrap();
d.cues[0].text = text.into();
let back = parse(&write(&d)).unwrap();
assert_eq!(back.cues.len(), 1, "{text:?}");
assert_eq!(back.cues[0].text, text);
}
}
#[test]
fn ignores_byte_order_mark() {
let d = parse("\u{feff}00:00:01,000 --> 00:00:02,000\nHi\n").unwrap();
assert_eq!(d.cues.len(), 1);
assert_eq!(d.cues[0].start, ms(1000));
assert_eq!(d.cues[0].text, "Hi");
let d = parse("\u{feff}00:00:01,000 --> 00:00:02,000\nHi\n\n2\n00:00:03,000 --> 00:00:04,000\nBye\n").unwrap();
assert_eq!(d.cues.len(), 2);
}
#[test]
fn rejects_garbage() {
assert!(parse("hello world\nthis is not srt").is_err());
assert!(parse("").unwrap().cues.is_empty());
}
#[test]
fn skips_inverted_cue() {
let d = parse("1\n00:00:05,000 --> 00:00:04,000\nX\n\n2\n00:00:06,000 --> 00:00:07,000\nY\n").unwrap();
assert_eq!(d.cues.len(), 1);
assert_eq!(d.warnings.len(), 1);
}
}