feat(arr): convert VTT and ASS downloads to SRT

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<String> {
+        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<Vec<Cue>, 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<Duration, String> {
+    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::<u64>().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<Vec<Cue>, 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<Duration, String> {
+    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::<u64>().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:?}");
+    }
+}

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<T> = std::result::Result<T, Error>;
@@ -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.

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