@kromatv/sdk 0.1.39-canary.3579809

package/rust/kroma-media/src/external_subtitles/mod.rs

@@ -0,0 +1,247 @@
+//! Text subtitle files that sit beside a video rather than inside it.
+
+mod convert;
+mod decode;
+mod language;
+mod layout;
+mod name;
+
+use std::path::{Path, PathBuf};
+
+pub use convert::to_vtt;
+pub use layout::SUBTITLE_FOLDERS;
+
+use layout::Release;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ExternalSubtitle {
+    pub path: PathBuf,
+    pub language: Option<&'static str>,
+    pub forced: bool,
+    pub hearing_impaired: bool,
+    pub codec: &'static str,
+}
+
+impl ExternalSubtitle {
+    /// The track's title: the flags its name carried, in one spelling, or `None`
+    /// where it carried none.
+    pub fn title(&self) -> Option<String> {
+        name::title_of(self.forced, self.hearing_impaired)
+    }
+
+    pub fn named_after(&self, stem: &str) -> String {
+        let ext = self
+            .path
+            .extension()
+            .and_then(std::ffi::OsStr::to_str)
+            .unwrap_or("srt");
+        let marks = [
+            self.language,
+            self.forced.then_some("forced"),
+            self.hearing_impaired.then_some("sdh"),
+        ];
+        let tail: String = marks
+            .into_iter()
+            .flatten()
+            .map(|mark| format!(".{mark}"))
+            .collect();
+        format!("{stem}{tail}.{ext}")
+    }
+}
+
+/// The text subtitle files of `video` among `files`, in a stable order.
+///
+/// Picture subtitles (`.sub`/`.idx`, `.sup`) are absent: they are bitmaps and no
+/// client renders them as text. `files` is every path the caller can see, the
+/// video included; a release holding one video also lends it the loose files in
+/// its `Subs/` folder, which in a season pack would belong to every episode.
+pub fn beside(video: &Path, files: &[PathBuf]) -> Vec<ExternalSubtitle> {
+    let holds = match files
+        .iter()
+        .filter(|file| crate::video::has_video_extension(file))
+        .count()
+    {
+        0 | 1 => Release::OneVideo,
+        _ => Release::Several,
+    };
+    let mut found: Vec<ExternalSubtitle> = files
+        .iter()
+        .filter_map(|file| read_as_external(video, file, holds))
+        .collect();
+    found.sort_by_key(|track| track.path.to_string_lossy().to_lowercase());
+    found.dedup_by(|a, b| a.path == b.path);
+    found
+}
+
+fn read_as_external(video: &Path, file: &Path, holds: Release) -> Option<ExternalSubtitle> {
+    let codec = text_codec_of(file)?;
+    let marks = name::marks_of(&layout::describing_tail(video, file, holds)?);
+    Some(ExternalSubtitle {
+        path: file.to_path_buf(),
+        language: marks.language,
+        forced: marks.forced,
+        hearing_impaired: marks.hearing_impaired,
+        codec,
+    })
+}
+
+// A `.sub` is VobSub as often as it is MicroDVD, and neither is offered as text.
+fn text_codec_of(file: &Path) -> Option<&'static str> {
+    let ext = file.extension().and_then(std::ffi::OsStr::to_str)?;
+    match ext.to_lowercase().as_str() {
+        "srt" => Some("subrip"),
+        "ass" => Some("ass"),
+        "ssa" => Some("ssa"),
+        "vtt" | "webvtt" => Some("webvtt"),
+        _ => None,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const FILM: &str = "/movies/Sintel (2010)/Sintel (2010).mkv";
+
+    fn beside_film(names: &[&str]) -> Vec<ExternalSubtitle> {
+        let files: Vec<PathBuf> = names.iter().map(PathBuf::from).collect();
+        beside(Path::new(FILM), &files)
+    }
+
+    #[test]
+    fn a_film_with_nothing_beside_it_has_no_external_track() {
+        assert!(beside_film(&[FILM]).is_empty());
+    }
+
+    #[test]
+    fn a_file_named_after_the_film_is_its_track() {
+        let found = beside_film(&[FILM, "/movies/Sintel (2010)/Sintel (2010).en.srt"]);
+
+        assert_eq!(found.len(), 1);
+        assert_eq!(found[0].language, Some("en"));
+        assert_eq!(found[0].codec, "subrip");
+        assert!(!found[0].forced);
+    }
+
+    #[test]
+    fn a_picture_subtitle_is_never_offered_as_text() {
+        let found = beside_film(&[
+            FILM,
+            "/movies/Sintel (2010)/Sintel (2010).en.sub",
+            "/movies/Sintel (2010)/Sintel (2010).en.idx",
+            "/movies/Sintel (2010)/Sintel (2010).en.sup",
+        ]);
+
+        assert!(found.is_empty());
+    }
+
+    #[test]
+    fn every_text_format_is_offered_under_the_codec_the_catalogue_names_it_by() {
+        let found = beside_film(&[
+            FILM,
+            "/movies/Sintel (2010)/Sintel (2010).de.ass",
+            "/movies/Sintel (2010)/Sintel (2010).es.SSA",
+            "/movies/Sintel (2010)/Sintel (2010).it.vtt",
+        ]);
+
+        let codecs: Vec<&str> = found.iter().map(|track| track.codec).collect();
+        assert_eq!(codecs, vec!["ass", "ssa", "webvtt"]);
+    }
+
+    #[test]
+    fn a_forced_track_and_a_track_for_the_deaf_carry_what_the_name_said() {
+        let found = beside_film(&[
+            FILM,
+            "/movies/Sintel (2010)/Sintel (2010).fr.forced.srt",
+            "/movies/Sintel (2010)/Sintel (2010).en.sdh.srt",
+        ]);
+
+        let said: Vec<(Option<&str>, bool, Option<String>)> = found
+            .iter()
+            .map(|track| (track.language, track.forced, track.title()))
+            .collect();
+        assert_eq!(
+            said,
+            vec![
+                (Some("en"), false, Some("SDH".to_string())),
+                (Some("fr"), true, Some("Forced".to_string())),
+            ]
+        );
+    }
+
+    #[test]
+    fn a_subs_folder_of_a_single_film_release_lends_it_every_loose_track() {
+        let found = beside_film(&[
+            FILM,
+            "/movies/Sintel (2010)/Subs/2_English.srt",
+            "/movies/Sintel (2010)/Subs/3_French.srt",
+        ]);
+
+        let languages: Vec<Option<&str>> = found.iter().map(|track| track.language).collect();
+        assert_eq!(languages, vec![Some("en"), Some("fr")]);
+    }
+
+    #[test]
+    fn a_season_pack_gives_each_episode_the_folder_named_after_it() {
+        let episode = Path::new("/shows/Kaamelott/Kaamelott.S01E02.mkv");
+        let files: Vec<PathBuf> = [
+            "/shows/Kaamelott/Kaamelott.S01E01.mkv",
+            "/shows/Kaamelott/Kaamelott.S01E02.mkv",
+            "/shows/Kaamelott/Subs/Kaamelott.S01E01/2_French.srt",
+            "/shows/Kaamelott/Subs/Kaamelott.S01E02/2_French.srt",
+        ]
+        .map(PathBuf::from)
+        .to_vec();
+
+        let found = beside(episode, &files);
+
+        assert_eq!(found.len(), 1);
+        assert_eq!(
+            found[0].path,
+            PathBuf::from("/shows/Kaamelott/Subs/Kaamelott.S01E02/2_French.srt")
+        );
+    }
+
+    #[test]
+    fn the_order_a_track_is_offered_in_does_not_depend_on_the_order_it_was_found_in() {
+        let names = [
+            FILM,
+            "/movies/Sintel (2010)/Sintel (2010).fr.srt",
+            "/movies/Sintel (2010)/Sintel (2010).en.srt",
+        ];
+        let reversed: Vec<&str> = names.iter().rev().copied().collect();
+
+        let one_way = beside_film(&names);
+        let other_way = beside_film(&reversed);
+
+        assert_eq!(one_way, other_way);
+        assert_eq!(one_way[0].language, Some("en"));
+    }
+
+    fn found(name: &str) -> ExternalSubtitle {
+        let video = Path::new("/movies/Old Name/Old Name.mkv");
+        let file = PathBuf::from(format!("/movies/Old Name/{name}"));
+        beside(video, &[file]).remove(0)
+    }
+
+    #[test]
+    fn a_track_keeps_its_language_under_the_videos_new_name() {
+        let renamed = found("Old Name.fr.srt").named_after("The Matrix (1999) [Bluray-1080p]");
+
+        assert_eq!(renamed, "The Matrix (1999) [Bluray-1080p].fr.srt");
+    }
+
+    #[test]
+    fn a_track_keeps_every_flag_its_name_carried() {
+        let renamed = found("Old Name.fr.forced.sdh.ass").named_after("The Matrix (1999)");
+
+        assert_eq!(renamed, "The Matrix (1999).fr.forced.sdh.ass");
+    }
+
+    #[test]
+    fn a_track_that_named_no_language_takes_the_stem_alone() {
+        let renamed = found("Old Name.srt").named_after("The Matrix (1999)");
+
+        assert_eq!(renamed, "The Matrix (1999).srt");
+    }
+}

package/rust/kroma-media/src/external_subtitles/name.rs

@@ -0,0 +1,107 @@
+use super::language;
+
+#[derive(Debug, Default, PartialEq, Eq)]
+pub struct Marks {
+    pub language: Option<&'static str>,
+    pub forced: bool,
+    pub hearing_impaired: bool,
+}
+
+pub fn title_of(forced: bool, hearing_impaired: bool) -> Option<String> {
+    let words: Vec<&str> = [(forced, "Forced"), (hearing_impaired, "SDH")]
+        .into_iter()
+        .filter_map(|(set, word)| set.then_some(word))
+        .collect();
+    (!words.is_empty()).then(|| words.join(" · "))
+}
+
+const FORCED: &[&str] = &["forced", "force", "forcé", "forcée", "forces", "forcés"];
+const HEARING_IMPAIRED: &[&str] = &[
+    "sdh",
+    "cc",
+    "impaired",
+    "malentendants",
+    "sourds",
+    "hearingimpaired",
+];
+
+/// `hi` is Hindi on its own and hearing-impaired once another language has been
+/// named, which is the only spelling a subtitle file uses it in.
+pub fn marks_of(tail: &str) -> Marks {
+    let mut marks = Marks::default();
+    for word in tail.split(['.', '-', '_', ' ', '(', ')', '[', ']']) {
+        let lowered = word.to_lowercase();
+        if FORCED.contains(&lowered.as_str()) {
+            marks.forced = true;
+        } else if HEARING_IMPAIRED.contains(&lowered.as_str())
+            || (lowered == "hi" && marks.language.is_some())
+        {
+            marks.hearing_impaired = true;
+        } else if marks.language.is_none() {
+            marks.language = language::code_of(word);
+        }
+    }
+    marks
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn a_name_that_says_only_a_language_says_nothing_else() {
+        let marks = marks_of(".en");
+
+        assert_eq!(
+            marks,
+            Marks {
+                language: Some("en"),
+                forced: false,
+                hearing_impaired: false,
+            }
+        );
+        assert_eq!(title_of(marks.forced, marks.hearing_impaired), None);
+    }
+
+    #[test]
+    fn a_forced_track_is_read_in_english_and_in_french() {
+        assert!(marks_of(".fr.forced").forced);
+        assert!(marks_of(".fr.forcés").forced);
+    }
+
+    #[test]
+    fn every_spelling_of_a_track_for_the_deaf_reads_as_one() {
+        let spellings = [".en.sdh", ".en.cc", ".en.hi", ".en.hearing-impaired"];
+
+        assert!(spellings.iter().all(|tail| marks_of(tail).hearing_impaired));
+    }
+
+    #[test]
+    fn hindi_on_its_own_is_a_language_and_not_a_track_for_the_deaf() {
+        let marks = marks_of(".hi");
+
+        assert_eq!(marks.language, Some("hi"));
+        assert!(!marks.hearing_impaired);
+    }
+
+    #[test]
+    fn a_name_flagging_both_titles_the_track_with_both() {
+        let marks = marks_of(".fr.forced.sdh");
+
+        assert_eq!(
+            title_of(marks.forced, marks.hearing_impaired).unwrap(),
+            "Forced · SDH"
+        );
+    }
+
+    #[test]
+    fn a_numbered_track_out_of_a_subs_folder_reads_its_language() {
+        assert_eq!(marks_of("2_English").language, Some("en"));
+        assert_eq!(marks_of("3_French.forced").language, Some("fr"));
+    }
+
+    #[test]
+    fn a_name_that_says_nothing_says_nothing() {
+        assert_eq!(marks_of(""), Marks::default());
+    }
+}

package/rust/kroma-media/src/ffmpeg_gate.rs

@@ -0,0 +1,198 @@
+//! A process-wide cap on how many heavy ffmpeg passes run at once.
+//!
+//! Every CPU-heavy media source (storyboard tiles/montage/jpeg, subtitle
+//! extraction, marker fingerprinting, on-demand storyboard scrubbing) draws
+//! from one budget here instead of each subsystem sizing its own worker pool
+//! blind to the others. The budget is live: [`set_capacity`] is called at
+//! startup from the `mediaConcurrency` admin setting and again whenever it
+//! changes, so an operator can retune it without a restart.
+//!
+//! A hand-rolled counting semaphore (Mutex + Condvar): every caller runs on a
+//! blocking thread, so a blocking acquire is correct and avoids pulling an
+//! async runtime into the leaf process plumbing. No caller holds a permit
+//! while waiting on another, so the single-budget gate cannot deadlock.
+//!
+//! [`reserve`] is the other half: work a viewer is waiting on does not draw from
+//! the budget, it takes the budget away, because a box that is finishing a
+//! storyboard is a box that is not finishing the next segment.
+
+use std::sync::{Condvar, Mutex, OnceLock};
+
+struct Gate {
+    inner: Mutex<Inner>,
+    changed: Condvar,
+}
+
+struct Inner {
+    capacity: usize,
+    in_use: usize,
+    reserved: usize,
+}
+
+// What background work is left while the box is reserved. Not zero: a paused
+// library is worse than a slow one, and one pass at a time still finishes.
+const RESERVED_FLOOR: usize = 1;
+
+impl Inner {
+    fn effective(&self) -> usize {
+        if self.reserved > 0 {
+            RESERVED_FLOOR.min(self.capacity)
+        } else {
+            self.capacity
+        }
+    }
+}
+
+static GATE: OnceLock<Gate> = OnceLock::new();
+
+/// The budget used before [`set_capacity`] runs (e.g. an on-demand storyboard
+/// generated before `AppState::new` seeds the setting) and the fallback when the
+/// setting says "auto". `KROMA_FFMPEG_CONCURRENCY` overrides for ops/debugging;
+/// otherwise `cores - 1` so the box always keeps a core, floored at 1.
+pub fn auto_capacity() -> usize {
+    if let Some(n) = std::env::var("KROMA_FFMPEG_CONCURRENCY")
+        .ok()
+        .and_then(|v| v.trim().parse::<usize>().ok())
+        .filter(|n| *n > 0)
+    {
+        return n;
+    }
+    let cores = std::thread::available_parallelism()
+        .map(std::num::NonZeroUsize::get)
+        .unwrap_or(4);
+    cores.saturating_sub(1).max(1)
+}
+
+/// The ffmpeg budget an operator's `mediaConcurrency` asks for: 1..=32, and
+/// `0` or less is [`auto_capacity`].
+pub fn capacity_from(setting: i64) -> usize {
+    match setting {
+        n if n > 0 => (n as usize).clamp(1, 32),
+        _ => auto_capacity(),
+    }
+}
+
+fn gate() -> &'static Gate {
+    GATE.get_or_init(|| Gate {
+        inner: Mutex::new(Inner {
+            capacity: auto_capacity(),
+            in_use: 0,
+            reserved: 0,
+        }),
+        changed: Condvar::new(),
+    })
+}
+
+/// Set the live budget (clamped to >= 1). Growing it wakes any blocked waiters so
+/// the extra slots are taken up immediately; shrinking it just lets the current
+/// passes drain (a permit already granted is never revoked mid-flight).
+pub fn set_capacity(permits: usize) {
+    let gate = gate();
+    {
+        let mut inner = gate.inner.lock().unwrap();
+        inner.capacity = permits.max(1);
+    }
+    gate.changed.notify_all();
+}
+
+/// Held for the lifetime of one ffmpeg pass; returns its slot to the pool on drop
+/// (including on panic or an early `?` return), so a slot is never leaked.
+pub struct Permit;
+
+impl Drop for Permit {
+    fn drop(&mut self) {
+        let gate = gate();
+        {
+            let mut inner = gate.inner.lock().unwrap();
+            inner.in_use = inner.in_use.saturating_sub(1);
+        }
+        gate.changed.notify_one();
+    }
+}
+
+/// Block until a slot is free, then take it. Call right before spawning ffmpeg and
+/// keep the returned permit alive (bind it, do not `let _ = `) until the process
+/// has exited.
+#[must_use]
+pub fn acquire() -> Permit {
+    let gate = gate();
+    let mut inner = gate.inner.lock().unwrap();
+    while inner.in_use >= inner.effective() {
+        inner = gate.changed.wait(inner).unwrap();
+    }
+    inner.in_use += 1;
+    Permit
+}
+
+/// Held for as long as something the viewer is waiting on owns the box: the
+/// background budget drops to one pass until it is dropped.
+///
+/// A live software re-encode is the case this exists for. It runs outside the
+/// gate (it is not a pass, it is the stream), so nothing stopped a storyboard
+/// fan-out from taking `cores - 1` of a four-core NAS while a player waited on
+/// the next segment. A permit already granted is never revoked, so the pass in
+/// flight finishes and the next one queues.
+pub struct Reservation;
+
+impl Drop for Reservation {
+    fn drop(&mut self) {
+        let gate = gate();
+        {
+            let mut inner = gate.inner.lock().unwrap();
+            inner.reserved = inner.reserved.saturating_sub(1);
+        }
+        gate.changed.notify_all();
+    }
+}
+
+#[must_use]
+pub fn reserve() -> Reservation {
+    let mut inner = gate().inner.lock().unwrap();
+    inner.reserved += 1;
+    Reservation
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const fn inner(capacity: usize, reserved: usize) -> Inner {
+        Inner {
+            capacity,
+            in_use: 0,
+            reserved,
+        }
+    }
+
+    #[test]
+    fn an_unreserved_box_spends_its_whole_budget() {
+        assert_eq!(inner(7, 0).effective(), 7);
+    }
+
+    #[test]
+    fn a_reservation_leaves_background_work_one_pass_at_a_time() {
+        assert_eq!(inner(7, 1).effective(), 1);
+    }
+
+    #[test]
+    fn two_viewers_do_not_take_the_box_away_twice_over() {
+        assert_eq!(inner(7, 2).effective(), 1);
+    }
+
+    #[test]
+    fn the_floor_never_hands_out_more_than_the_operator_allowed() {
+        assert_eq!(inner(1, 1).effective(), 1);
+    }
+
+    #[test]
+    fn an_operator_asking_for_more_than_the_box_allows_gets_the_ceiling() {
+        assert_eq!(capacity_from(4), 4);
+        assert_eq!(capacity_from(99), 32);
+    }
+
+    #[test]
+    fn a_setting_of_zero_leaves_the_box_to_size_itself() {
+        assert_eq!(capacity_from(0), auto_capacity());
+        assert_eq!(capacity_from(-1), auto_capacity());
+    }
+}

package/rust/kroma-media/src/ffmpeg_run.rs

@@ -0,0 +1,99 @@
+//! The cancellable, stderr-capturing ffmpeg runner shared by the media stages
+//! (storyboard render + subtitle extraction). A sync stand-in for
+//! `tokio::time::timeout`, since generation/extraction run on blocking threads.
+//!
+//! Every pass draws one slot from the process-wide [`crate::ffmpeg_gate`]
+//! budget so the tile fan-out, montage, jpeg and subtitle demux never
+//! oversubscribe the box.
+
+use std::process::Command;
+use std::time::{Duration, Instant};
+
+/// A cheap "should I stop?" poll threaded through a pass so cancelling the work
+/// behind it interrupts ffmpeg at the next tick. `Sync`, so a scoped pool can
+/// share the one closure.
+pub type Cancel<'a> = &'a (dyn Fn() -> bool + Sync);
+
+/// Spawn `cmd`, wait up to `dur` (killing it on timeout), and **capture stderr**
+/// so a failure can explain itself. `Ok(())` on a clean exit; `Err(reason)` on a
+/// spawn error (ffmpeg missing), a non-zero exit (with the stderr tail), or a
+/// timeout.
+pub fn run_capturing(cmd: Command, dur: Duration) -> Result<(), String> {
+    run_capturing_cancellable(cmd, dur, &|| false)
+}
+
+/// [`run_capturing`] that also polls `cancel` each tick, killing the child and
+/// returning `Err("cancelled")` the moment it flips so a cancelled job/stage stops
+/// the in-flight ffmpeg (a tile seek can otherwise hang up to its timeout) instead
+/// of waiting out `dur`.
+pub fn run_capturing_cancellable(
+    mut cmd: Command,
+    dur: Duration,
+    cancel: &dyn Fn() -> bool,
+) -> Result<(), String> {
+    use std::io::Read;
+    // One slot from the process-wide ffmpeg budget (see `crate::ffmpeg_gate`),
+    // held until this pass exits.
+    let _permit = crate::ffmpeg_gate::acquire();
+    cmd.stdin(std::process::Stdio::null())
+        .stdout(std::process::Stdio::null())
+        .stderr(std::process::Stdio::piped());
+    let mut child = cmd
+        .spawn()
+        .map_err(|e| format!("could not start ffmpeg (is it installed and on PATH?): {e}"))?;
+    // Drain stderr on a side thread so a chatty child can never deadlock on a full
+    // pipe buffer while we poll for the timeout.
+    let drain = child.stderr.take().map(|mut s| {
+        std::thread::spawn(move || {
+            let mut buf = String::new();
+            let _ = s.read_to_string(&mut buf);
+            buf
+        })
+    });
+    let start = Instant::now();
+    // Poll with exponential backoff: a sub-second tile seek is noticed in a few
+    // ms (a fixed 200 ms sleep would waste up to that per tile, and there are
+    // hundreds), while a long montage never busy-spins.
+    let mut backoff = Duration::from_millis(2);
+    let outcome = loop {
+        match child.try_wait() {
+            Ok(Some(status)) => break Ok(status),
+            Ok(None) => {
+                if cancel() {
+                    let _ = child.kill();
+                    let _ = child.wait();
+                    break Err("cancelled".to_string());
+                }
+                if start.elapsed() >= dur {
+                    let _ = child.kill();
+                    let _ = child.wait();
+                    break Err(format!("timed out after {}s", dur.as_secs()));
+                }
+                std::thread::sleep(backoff);
+                backoff = (backoff * 2).min(Duration::from_millis(100));
+            }
+            Err(e) => break Err(format!("waiting on ffmpeg failed: {e}")),
+        }
+    };
+    let stderr = drain.and_then(|h| h.join().ok()).unwrap_or_default();
+    match outcome {
+        Ok(status) if status.success() => Ok(()),
+        Ok(status) => {
+            let code = status
+                .code()
+                .map_or_else(|| "killed by signal".to_string(), |c| format!("exit {c}"));
+            Err(format!("{code}{}", stderr_tail(&stderr)))
+        }
+        Err(reason) => Err(reason),
+    }
+}
+
+fn stderr_tail(stderr: &str) -> String {
+    let cleaned: String = stderr.split_whitespace().collect::<Vec<_>>().join(" ");
+    if cleaned.is_empty() {
+        return String::new();
+    }
+    let n = cleaned.chars().count();
+    let tail: String = cleaned.chars().skip(n.saturating_sub(300)).collect();
+    format!(" ({tail})")
+}