From 8450b06e769a52c22bceaef2c9c120bd596b427f Mon Sep 17 00:00:00 2001 From: Miguel Palhas Date: Mon, 24 Aug 2026 23:13:17 +0100 Subject: [PATCH] feat(arr): convert VTT and ASS downloads to SRT --- crates/arr-subs/src/convert.rs | 338 +++++++++++++++++++++++++++++++++ crates/arr-subs/src/error.rs | 15 +- crates/arr-subs/src/lib.rs | 1 + 3 files changed, 353 insertions(+), 1 deletion(-) create mode 100644 crates/arr-subs/src/convert.rs diff --git a/crates/arr-subs/src/convert.rs b/crates/arr-subs/src/convert.rs new file mode 100644 index 0000000..347c0c7 --- /dev/null +++ b/crates/arr-subs/src/convert.rs @@ -0,0 +1,338 @@ +//! Convert a downloaded subtitle to SRT. +//! +//! Sidecars on disk are SRT (DESIGN.md §15); providers serve other things +//! (#184). [`Fetched::to_srt`] is where that gets settled: SRT passes +//! through untouched, VTT and ASS are parsed into [`Cue`]s and handed to +//! [`srt::render`] — the shape #190 already writes — and anything else +//! ([`SubtitleFormat::Other`]) is a failed conversion, not a silent skip. +//! Styling is dropped along the way: §15 accepts that cost for a single +//! format on disk. + +use std::time::Duration; + +use crate::error::Error; +use crate::model::{Fetched, SubtitleFormat}; +use crate::srt::{self, Cue}; + +impl Fetched { + /// Decode this subtitle and convert it to rendered SRT text. + /// + /// # Errors + /// + /// [`Error::Decode`] when the bytes do not decode to UTF-8. + /// [`Error::Convert`] when the format cannot be turned into SRT: a VTT or + /// ASS file its parser rejects, or [`SubtitleFormat::Other`]. + pub fn to_srt(&self) -> crate::Result { + let text = self.decode()?; + let convert = |detail: String| Error::Convert { + candidate: self.id.clone(), + format: self.format.clone(), + detail, + }; + + match &self.format { + SubtitleFormat::Srt => Ok(text), + SubtitleFormat::Vtt => Ok(srt::render(&parse_vtt(&text).map_err(convert)?)), + SubtitleFormat::Ass => Ok(srt::render(&parse_ass(&text).map_err(convert)?)), + SubtitleFormat::Other(name) => Err(convert(format!("no parser for {name:?}"))), + } + } +} + +/// Parse `WebVTT` cues, tolerant of an identifier line and of `NOTE`, +/// `STYLE` and `REGION` blocks — including the leading `WEBVTT` signature — +/// which are skipped rather than rejected. +fn parse_vtt(input: &str) -> Result, String> { + let input = input.strip_prefix('\u{feff}').unwrap_or(input); + let mut cues = Vec::new(); + let mut lines = input.lines().peekable(); + + while let Some(line) = lines.next() { + if line.trim().is_empty() { + continue; + } + if !line.contains("-->") { + if matches!(lines.peek(), Some(next) if next.contains("-->")) { + continue; // a cue identifier; the timing line follows next + } + for header_line in lines.by_ref() { + if header_line.trim().is_empty() { + break; + } + } + continue; + } + + let (start, end) = parse_vtt_timing(line)?; + let mut text_lines = Vec::new(); + for text_line in lines.by_ref() { + if text_line.trim().is_empty() { + break; + } + text_lines.push(text_line); + } + cues.push(Cue { + start, + end, + text: text_lines.join("\n"), + }); + } + + Ok(cues) +} + +/// Split `start --> end`, ignoring any cue settings after `end`. +fn parse_vtt_timing(line: &str) -> Result<(Duration, Duration), String> { + let (start, rest) = line + .split_once("-->") + .ok_or_else(|| format!("expected a timing line, got {line:?}"))?; + let end = rest.split_whitespace().next().unwrap_or(""); + + Ok(( + parse_vtt_timestamp(start.trim())?, + parse_vtt_timestamp(end)?, + )) +} + +/// Parse one `[HH:]MM:SS.mmm` timestamp; hours are optional in `WebVTT`. +fn parse_vtt_timestamp(text: &str) -> Result { + let bad = || format!("bad timestamp {text:?}"); + + let mut clock = text.splitn(3, ':'); + let (first, second, third) = (clock.next(), clock.next(), clock.next()); + let (hours, minutes, rest) = match (first, second, third) { + (Some(hours), Some(minutes), Some(rest)) => (hours, minutes, rest), + (Some(minutes), Some(rest), None) => ("0", minutes, rest), + _ => return Err(bad()), + }; + let (seconds, millis) = rest.split_once('.').ok_or_else(bad)?; + + let field = |s: &str| s.trim().parse::().map_err(|_| bad()); + let (hours, minutes, seconds, millis) = ( + field(hours)?, + field(minutes)?, + field(seconds)?, + field(millis)?, + ); + if minutes >= 60 || seconds >= 60 || millis >= 1_000 { + return Err(bad()); + } + + Ok(Duration::from_millis( + ((hours * 60 + minutes) * 60 + seconds) * 1_000 + millis, + )) +} + +/// Parse `Dialogue:` events from the `[Events]` section of an ASS/SSA +/// script, in time order, with override tags stripped. +fn parse_ass(input: &str) -> Result, String> { + let mut in_events = false; + let mut events = Vec::new(); + + for line in input.lines() { + let line = line.trim(); + if line.is_empty() { + continue; + } + if let Some(section) = line.strip_prefix('[').and_then(|s| s.strip_suffix(']')) { + in_events = section.eq_ignore_ascii_case("events"); + continue; + } + if !in_events { + continue; + } + let Some(fields) = line.strip_prefix("Dialogue:") else { + continue; // a Format: line, a Comment:, or blank noise + }; + + // Standard v4+ order: Layer, Start, End, Style, Name, MarginL, + // MarginR, MarginV, Effect, Text. Text is last and may itself + // contain commas, so only the first nine fields are split off. + let fields: Vec<&str> = fields.splitn(10, ',').collect(); + let [_layer, start, end, _style, _name, _margin_l, _margin_r, _margin_v, _effect, text] = + fields[..] + else { + return Err(format!( + "dialogue line has {} fields, expected 10", + fields.len() + )); + }; + + let start = parse_ass_timestamp(start.trim())?; + let end = parse_ass_timestamp(end.trim())?; + events.push((start, end, strip_ass_tags(text))); + } + + events.sort_by_key(|&(start, ..)| start); + Ok(events + .into_iter() + .map(|(start, end, text)| Cue { start, end, text }) + .collect()) +} + +/// Parse one `H:MM:SS.cc` timestamp; ASS times centiseconds, not milliseconds. +fn parse_ass_timestamp(text: &str) -> Result { + let bad = || format!("bad timestamp {text:?}"); + + let mut clock = text.splitn(3, ':'); + let (Some(hours), Some(minutes), Some(rest)) = (clock.next(), clock.next(), clock.next()) + else { + return Err(bad()); + }; + let (seconds, centis) = rest.split_once('.').ok_or_else(bad)?; + + let field = |s: &str| s.trim().parse::().map_err(|_| bad()); + let (hours, minutes, seconds, centis) = ( + field(hours)?, + field(minutes)?, + field(seconds)?, + field(centis)?, + ); + if minutes >= 60 || seconds >= 60 || centis >= 100 { + return Err(bad()); + } + + Ok(Duration::from_millis( + ((hours * 60 + minutes) * 60 + seconds) * 1_000 + centis * 10, + )) +} + +/// Strip `{...}` override blocks and turn `\N`/`\n` line breaks into real +/// newlines. Everything else in the text survives untouched. +fn strip_ass_tags(text: &str) -> String { + let mut out = String::new(); + let mut depth = 0u32; + let mut chars = text.chars().peekable(); + + while let Some(c) = chars.next() { + match c { + '{' => depth += 1, + '}' => depth = depth.saturating_sub(1), + '\\' if depth == 0 && matches!(chars.peek(), Some('N' | 'n')) => { + out.push('\n'); + chars.next(); + } + _ if depth == 0 => out.push(c), + _ => {} + } + } + + out +} + +#[cfg(test)] +mod tests { + use std::time::Duration; + + use arr_core::Language; + + use super::Fetched; + use crate::model::{CandidateId, SubtitleFormat}; + use crate::srt::Cue; + use crate::Error; + + fn fetched(format: SubtitleFormat, content: &str) -> Fetched { + Fetched { + id: CandidateId::new("1"), + language: Language::PortuguesePortugal, + format, + content: content.as_bytes().to_vec(), + } + } + + #[test] + fn srt_passes_through_untouched() { + let content = "1\n00:00:01,000 --> 00:00:02,000\nhello\n"; + let converted = fetched(SubtitleFormat::Srt, content) + .to_srt() + .expect("already SRT"); + assert_eq!(converted, content); + } + + #[test] + fn vtt_header_and_settings_are_stripped_and_cues_renumbered() { + let content = "WEBVTT - some note\n\n\ + NOTE this is ignored\n\n\ + cue-1\n00:00:01.000 --> 00:00:02.500 line:0 position:50%\nfirst\n\n\ + 00:01:03.250 --> 00:01:04.000\nsecond\nline\n"; + let converted = fetched(SubtitleFormat::Vtt, content) + .to_srt() + .expect("well-formed VTT"); + assert_eq!( + converted, + "1\n00:00:01,000 --> 00:00:02,500\nfirst\n\n\ + 2\n00:01:03,250 --> 00:01:04,000\nsecond\nline\n" + ); + } + + #[test] + fn vtt_timestamps_without_hours_are_accepted() { + let cues = super::parse_vtt("WEBVTT\n\n00:01.000 --> 00:02.000\nhi\n") + .expect("MM:SS.mmm is valid WebVTT"); + assert_eq!( + cues, + [Cue { + start: Duration::from_secs(1), + end: Duration::from_secs(2), + text: "hi".to_owned(), + }] + ); + } + + #[test] + fn ass_events_are_taken_in_time_order_with_tags_stripped() { + let content = "[Script Info]\nScriptType: v4.00+\n\n\ + [V4+ Styles]\nFormat: Name, Fontname\nStyle: Default,Arial\n\n\ + [Events]\n\ + Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text\n\ + Dialogue: 0,0:00:03.00,0:00:04.50,Default,,0,0,0,,second, with a comma\n\ + Dialogue: 0,0:00:01.00,0:00:02.00,Default,,0,0,0,,{\\an8}first{\\i1} line{\\i0}\n"; + let converted = fetched(SubtitleFormat::Ass, content) + .to_srt() + .expect("well-formed ASS"); + assert_eq!( + converted, + "1\n00:00:01,000 --> 00:00:02,000\nfirst line\n\n\ + 2\n00:00:03,000 --> 00:00:04,500\nsecond, with a comma\n" + ); + } + + #[test] + fn ass_line_breaks_become_real_newlines() { + let cues = super::parse_ass( + "[Events]\nDialogue: 0,0:00:01.00,0:00:02.00,Default,,0,0,0,,one\\Ntwo\n", + ) + .expect("well-formed ASS"); + assert_eq!(cues[0].text, "one\ntwo"); + } + + #[test] + fn an_unsupported_format_fails_rather_than_skipping() { + let error = fetched(SubtitleFormat::Other("sub".to_owned()), "anything") + .to_srt() + .expect_err("no parser for a raw MicroDVD .sub"); + assert!(matches!(error, Error::Convert { .. }), "{error:?}"); + } + + #[test] + fn a_malformed_vtt_file_fails_rather_than_parsing_empty() { + let error = fetched( + SubtitleFormat::Vtt, + "WEBVTT\n\n00:00:01.000 --> nonsense\ntext\n", + ) + .to_srt() + .expect_err("timestamp is nonsense"); + assert!(matches!(error, Error::Convert { .. }), "{error:?}"); + } + + #[test] + fn a_malformed_ass_file_fails_rather_than_parsing_empty() { + let error = fetched( + SubtitleFormat::Ass, + "[Events]\nDialogue: 0,not-a-time,0:00:02.00\n", + ) + .to_srt() + .expect_err("dialogue line is short and its timing is nonsense"); + assert!(matches!(error, Error::Convert { .. }), "{error:?}"); + } +} diff --git a/crates/arr-subs/src/error.rs b/crates/arr-subs/src/error.rs index 7e57d26..f0e5d56 100644 --- a/crates/arr-subs/src/error.rs +++ b/crates/arr-subs/src/error.rs @@ -2,7 +2,7 @@ use std::{path::PathBuf, time::Duration}; -use crate::model::{CandidateId, ProviderId}; +use crate::model::{CandidateId, ProviderId, SubtitleFormat}; /// Result alias for every fallible operation in this crate. pub type Result = std::result::Result; @@ -88,6 +88,19 @@ pub enum Error { detail: String, }, + /// A downloaded subtitle could not be converted to SRT (DESIGN.md §15): + /// its format is [`SubtitleFormat::Other`], or its own parser rejected + /// the text. + #[error("{candidate} could not be converted from {format} to SRT: {detail}")] + Convert { + /// The candidate whose bytes failed to convert. + candidate: CandidateId, + /// The format conversion was attempted from. + format: SubtitleFormat, + /// What was wrong, short enough to log. + detail: String, + }, + /// The provider could not be constructed: a bad base URL, or its HTTP /// client failed to build. Always a caller bug — a hardcoded URL or a /// test override — never a fact about the live service. diff --git a/crates/arr-subs/src/lib.rs b/crates/arr-subs/src/lib.rs index 4aedaba..a22dde2 100644 --- a/crates/arr-subs/src/lib.rs +++ b/crates/arr-subs/src/lib.rs @@ -20,6 +20,7 @@ use std::{fmt, future::Future, pin::Pin}; +pub mod convert; pub mod decode; // `unused_crate_dependencies` is a per-target lint; `wiremock` is only used // from the `tests/podnapisi.rs` integration target, not from this library