@kromatv/sdk 0.1.39-canary.3579809

package/rust/kroma-media/src/hls/tests.rs

@@ -0,0 +1,171 @@
+use std::time::Duration;
+
+use super::*;
+
+const COPY: StreamMode = StreamMode::new(VideoMode::Copy, AudioMode::Copy);
+
+fn engine(root: &Path) -> HlsEngine {
+    HlsEngine::new(root.join("hls"), 2, 0)
+}
+
+async fn remux(engine: &HlsEngine, input: &Path) -> String {
+    engine
+        .master("it1", input.to_str().unwrap(), 0, COPY, 0, Some((320, 180)))
+        .await
+        .expect("a playlist out of a file ffmpeg can read")
+        .0
+}
+
+async fn finished_playlist(engine: &HlsEngine) -> String {
+    for _ in 0..200 {
+        let Some((bytes, _)) = engine.file("it1", COPY, 0, 0, "index.m3u8").await else {
+            panic!("the session went away while its playlist was being read");
+        };
+        let text = String::from_utf8(bytes).expect("a text playlist");
+        if text.contains("#EXT-X-ENDLIST") {
+            return text;
+        }
+        tokio::time::sleep(Duration::from_millis(50)).await;
+    }
+    panic!("the remux never finished the clip");
+}
+
+#[tokio::test]
+async fn the_length_a_file_carries_is_read_once_and_kept() {
+    let dir = kroma_testing::temp_dir("hls-duration");
+    let input = kroma_testing::clip(dir.path());
+    let engine = engine(dir.path());
+    let path = input.to_str().unwrap();
+
+    let first = engine.input_duration_ms(path).await;
+    let again = engine.input_duration_ms(path).await;
+
+    assert_eq!(first, again);
+    assert!(
+        matches!(first, Some(ms) if (4_000..6_000).contains(&ms)),
+        "read {first:?} off a five second clip"
+    );
+}
+
+#[tokio::test]
+async fn a_file_nothing_can_open_has_no_length_and_is_not_probed_twice() {
+    let dir = kroma_testing::temp_dir("hls-no-duration");
+    let engine = engine(dir.path());
+
+    let first = engine.input_duration_ms("/nowhere/absent.mkv").await;
+    let again = engine.input_duration_ms("/nowhere/absent.mkv").await;
+
+    assert_eq!(first, None);
+    assert_eq!(again, None);
+}
+
+#[tokio::test]
+async fn what_a_session_wrote_is_what_the_cache_weighs() {
+    let dir = kroma_testing::temp_dir("hls-bytes");
+    let input = kroma_testing::clip(dir.path());
+    let engine = engine(dir.path());
+
+    remux(&engine, &input).await;
+
+    assert!(engine.cache_bytes() > 0);
+}
+
+#[tokio::test]
+async fn the_disk_budget_is_retuned_without_restarting_the_engine() {
+    let dir = kroma_testing::temp_dir("hls-budget");
+    let engine = engine(dir.path());
+
+    engine.set_cache_budget(4 * 1024 * 1024);
+    engine.spawn_reaper();
+
+    assert_eq!(engine.cache_bytes(), 0);
+}
+
+#[tokio::test]
+async fn a_running_remux_says_what_it_is_producing_and_on_what_silicon() {
+    let dir = kroma_testing::temp_dir("hls-live");
+    let input = kroma_testing::clip(dir.path());
+    let engine = engine(dir.path());
+
+    remux(&engine, &input).await;
+
+    let live = engine.live().await;
+    assert_eq!(live.len(), 1);
+    assert_eq!(live[0].item_id, "it1");
+    assert_eq!(live[0].video, "copy");
+    assert_eq!(live[0].audio, "copy");
+    assert_eq!(live[0].source_width, Some(320));
+    assert!(!live[0].transcodes_video);
+}
+
+#[test]
+fn the_pipeline_this_host_settled_on_comes_with_the_reason_for_it() {
+    let hardware = HlsEngine::hardware();
+
+    assert!(!hardware.reason.is_empty());
+    assert_eq!(hardware.accel, HlsEngine::hardware().accel);
+}
+
+#[tokio::test]
+async fn a_child_name_reaching_out_of_the_session_is_refused_outright() {
+    let dir = kroma_testing::temp_dir("hls-escape");
+    let input = kroma_testing::clip(dir.path());
+    let engine = engine(dir.path());
+    remux(&engine, &input).await;
+
+    let escaped = engine.file("it1", COPY, 0, 0, "../../etc/passwd").await;
+
+    assert!(escaped.is_none());
+}
+
+#[tokio::test]
+async fn a_finished_remux_is_seekable_vod_rather_than_a_live_edge() {
+    let dir = kroma_testing::temp_dir("hls-endlist");
+    let input = kroma_testing::clip(dir.path());
+    let engine = engine(dir.path());
+    remux(&engine, &input).await;
+
+    let finished = finished_playlist(&engine).await;
+
+    assert!(finished.contains("#EXT-X-TARGETDURATION"));
+    assert!(finished.contains("seg_00000.m4s"));
+}
+
+#[tokio::test]
+async fn a_segment_served_out_of_a_session_knows_what_it_is() {
+    let dir = kroma_testing::temp_dir("hls-segment");
+    let input = kroma_testing::clip(dir.path());
+    let engine = engine(dir.path());
+    remux(&engine, &input).await;
+    finished_playlist(&engine).await;
+
+    let init = engine.file("it1", COPY, 0, 0, "init.mp4").await;
+    let segment = engine.file("it1", COPY, 0, 0, "seg_00000.m4s").await;
+
+    assert_eq!(init.map(|(_, ct)| ct), Some("video/mp4"));
+    assert_eq!(segment.map(|(_, ct)| ct), Some("video/iso.segment"));
+}
+
+fn session_dirs(root: &Path) -> usize {
+    std::fs::read_dir(root.join("hls"))
+        .map(|entries| entries.flatten().filter(|e| e.path().is_dir()).count())
+        .unwrap_or(0)
+}
+
+#[tokio::test]
+async fn a_re_anchor_into_a_session_already_running_is_answered_out_of_it() {
+    let dir = kroma_testing::temp_dir("hls-reanchor");
+    let input = kroma_testing::clip(dir.path());
+    let engine = engine(dir.path());
+    remux(&engine, &input).await;
+    finished_playlist(&engine).await;
+
+    let (playlist, start) = engine
+        .master("it1", input.to_str().unwrap(), 0, COPY, 2, Some((320, 180)))
+        .await
+        .expect("the anchor sits inside what the running session has produced");
+
+    assert_eq!(session_dirs(dir.path()), 1, "no second ffmpeg was started");
+    assert_eq!(start, 0.0, "the client is told where the stream it gets begins");
+    assert!(playlist.contains("seg_00000.m4s"));
+}

package/rust/kroma-media/src/hls/window.rs

@@ -0,0 +1,137 @@
+//! How much of a session's output is kept behind the people reading it.
+//!
+//! A remux only moves forward, so a segment deleted is a segment gone: the
+//! window has to be measured from the SLOWEST reader, not the furthest ahead. A
+//! player that prefetches minutes of buffer, and a second viewer further back on
+//! the same key, both used to drag the cutoff past the trailing reader and 404
+//! the segments it was about to play.
+
+use std::sync::atomic::{AtomicU64, Ordering};
+
+// History kept behind the slowest reader, so it bounds a backward seek rather
+// than a buffer depth.
+pub(super) const KEEP_BEHIND_SEGS: u64 = 45;
+
+pub(super) struct Window {
+    // Lowest segment asked for since the last reap, i.e. the trailing edge of
+    // what someone is actually reading. `u64::MAX` = nothing asked for yet.
+    low: AtomicU64,
+    pruned: AtomicU64,
+}
+
+impl Window {
+    pub(super) const fn new() -> Self {
+        Window {
+            low: AtomicU64::new(u64::MAX),
+            pruned: AtomicU64::new(0),
+        }
+    }
+
+    /// Folds a request into the retention floor. `false` when the segment is
+    /// already pruned, in which case the floor is left alone: an index from
+    /// behind the prune mark would underflow the cutoff, hold the whole window
+    /// open, and keep the session too fresh for anything to reclaim it.
+    pub(super) fn note(&self, idx: u64) -> bool {
+        if self.is_pruned(idx) {
+            return false;
+        }
+        self.low.fetch_min(idx, Ordering::Relaxed);
+        true
+    }
+
+    pub(super) fn is_pruned(&self, idx: u64) -> bool {
+        idx < self.pruned.load(Ordering::Relaxed)
+    }
+
+    /// How far the retention window may advance, or `None` to keep everything.
+    ///
+    /// Taking the floor also resets it: a session nobody read this round keeps
+    /// everything it has rather than pruning against a stale mark.
+    pub(super) fn cutoff(&self) -> Option<u64> {
+        let floor = self.low.swap(u64::MAX, Ordering::Relaxed);
+        if floor == u64::MAX {
+            return None;
+        }
+        let cutoff = floor.checked_sub(KEEP_BEHIND_SEGS).filter(|c| *c > 0)?;
+        self.pruned.fetch_max(cutoff, Ordering::Relaxed);
+        Some(cutoff)
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn window(low: Option<u64>) -> Window {
+        let w = Window::new();
+        if let Some(idx) = low {
+            w.note(idx);
+        }
+        w
+    }
+
+    #[test]
+    fn a_session_nobody_read_this_round_keeps_everything() {
+        assert_eq!(window(None).cutoff(), None);
+    }
+
+    #[test]
+    fn the_window_is_kept_behind_the_trailing_reader() {
+        let w = window(Some(KEEP_BEHIND_SEGS + 10));
+
+        assert_eq!(w.cutoff(), Some(10));
+        assert!(w.is_pruned(9));
+        assert!(!w.is_pruned(10));
+    }
+
+    #[test]
+    fn a_prefetch_far_ahead_does_not_prune_what_the_reader_still_needs() {
+        let w = window(Some(5));
+        w.note(5_000);
+
+        assert_eq!(w.cutoff(), None);
+        assert!(!w.is_pruned(0));
+    }
+
+    // Two viewers share a session key: the one further ahead must not evict the
+    // segments the one behind is about to play.
+    #[test]
+    fn a_reader_further_ahead_does_not_prune_a_reader_behind_it() {
+        let w = window(Some(KEEP_BEHIND_SEGS + 2));
+        w.note(KEEP_BEHIND_SEGS * 4);
+
+        assert_eq!(w.cutoff(), Some(2));
+        assert!(!w.is_pruned(2));
+    }
+
+    #[test]
+    fn a_request_for_a_pruned_segment_does_not_reopen_the_window() {
+        let w = window(Some(KEEP_BEHIND_SEGS + 100));
+        assert_eq!(w.cutoff(), Some(100));
+
+        assert!(!w.note(5), "a backward seek the reaper already deleted");
+        assert_eq!(w.cutoff(), None);
+
+        w.note(KEEP_BEHIND_SEGS + 200);
+        assert_eq!(
+            w.cutoff(),
+            Some(200),
+            "a servable request still advances it"
+        );
+    }
+
+    #[test]
+    fn the_floor_resets_each_round_so_a_seek_back_is_not_pruned() {
+        let w = window(Some(KEEP_BEHIND_SEGS + 100));
+        assert_eq!(w.cutoff(), Some(100));
+
+        w.note(KEEP_BEHIND_SEGS + 120);
+
+        assert_eq!(
+            w.cutoff(),
+            Some(120),
+            "a later round never prunes past its own floor"
+        );
+        assert!(w.is_pruned(119));
+    }
+}

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

@@ -0,0 +1,7 @@
+use axum::http::StatusCode;
+use axum::response::{IntoResponse, Response};
+use axum::Json;
+
+pub(crate) fn json_error(status: StatusCode, message: &str) -> Response {
+    (status, Json(serde_json::json!({ "error": message }))).into_response()
+}

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

@@ -0,0 +1,26 @@
+//! Reading and re-encoding one media input, for whoever holds it.
+//!
+//! Nothing here knows a catalog: an input is a path or a URL, a program is
+//! named by whoever asked for it, and the engine is told the directory it may
+//! write in rather than deriving one. A module links this crate and a database
+//! never comes with it.
+
+pub mod external_subtitles;
+pub mod ffmpeg_gate;
+pub mod ffmpeg_run;
+pub mod hls;
+pub mod playlist;
+pub mod probe;
+pub mod program;
+pub mod storyboard;
+pub mod stream;
+pub mod subtitles;
+pub mod tmp_file;
+pub mod video;
+
+mod credential;
+mod json_error;
+mod meter;
+
+pub use credential::Credential;
+pub use meter::{ByteMeter, Unmetered};

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

@@ -0,0 +1,13 @@
+/// Where a response body reports the bytes it handed the socket. Implemented by
+/// whoever is counting; [`Unmetered`] is the answer for a stream that should not
+/// count at all.
+pub trait ByteMeter: Clone + Send + Unpin + 'static {
+    fn add(&self, bytes: u64);
+}
+
+#[derive(Clone, Copy, Debug, Default)]
+pub struct Unmetered;
+
+impl ByteMeter for Unmetered {
+    fn add(&self, _bytes: u64) {}
+}

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

@@ -0,0 +1,115 @@
+//! Writing the media credential into the playlist text.
+//!
+//! hls.js, AVPlay, Safari and mpv all resolve a playlist's URIs against the
+//! playlist's own URL and carry none of its query, so a credential on the master
+//! reaches no segment unless the body the player reads carries it too.
+
+use crate::Credential;
+
+const BYTES_PER_URI: usize = 32;
+
+/// The same playlist with `credential` appended to every URI a player will
+/// fetch. A caller whose credential is empty gets its playlist back untouched.
+pub fn with_credential(playlist: &str, credential: &Credential) -> String {
+    let credential = credential.query();
+    if credential.is_empty() {
+        return playlist.to_string();
+    }
+    let mut out =
+        String::with_capacity(playlist.len() + playlist.len() / BYTES_PER_URI * credential.len());
+    for line in playlist.lines() {
+        if line.starts_with('#') {
+            push_attribute(&mut out, line, credential);
+        } else if !line.is_empty() {
+            out.push_str(line);
+            out.push_str(credential);
+        }
+        out.push('\n');
+    }
+    out
+}
+
+// `#EXT-X-MAP:URI="init.mp4"` points at the initialisation segment, which the
+// player fetches like any other child.
+fn push_attribute(out: &mut String, tag: &str, credential: &str) {
+    const URI: &str = "URI=\"";
+    let Some(start) = tag.find(URI).map(|i| i + URI.len()) else {
+        out.push_str(tag);
+        return;
+    };
+    let Some(end) = tag[start..].find('"').map(|i| start + i) else {
+        out.push_str(tag);
+        return;
+    };
+    out.push_str(&tag[..start]);
+    out.push_str(&tag[start..end]);
+    out.push_str(credential);
+    out.push_str(&tag[end..]);
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn ticket() -> Credential {
+        Credential::new("t", Some("dev.999.sig"))
+    }
+
+    #[test]
+    fn every_uri_a_player_will_fetch_leaves_the_playlist_credentialed() {
+        let playlist = concat!(
+            "#EXTM3U\n",
+            "#EXT-X-TARGETDURATION:4\n",
+            "#EXT-X-MAP:URI=\"init.mp4\"\n",
+            "#EXTINF:4.000000,\n",
+            "seg00001.m4s\n",
+            "#EXTINF:4.000000,\n",
+            "seg00002.m4s\n",
+        );
+
+        let stamped = with_credential(playlist, &ticket());
+
+        assert_eq!(
+            stamped,
+            concat!(
+                "#EXTM3U\n",
+                "#EXT-X-TARGETDURATION:4\n",
+                "#EXT-X-MAP:URI=\"init.mp4?t=dev.999.sig\"\n",
+                "#EXTINF:4.000000,\n",
+                "seg00001.m4s?t=dev.999.sig\n",
+                "#EXTINF:4.000000,\n",
+                "seg00002.m4s?t=dev.999.sig\n",
+            )
+        );
+    }
+
+    #[test]
+    fn a_tag_with_no_uri_and_a_blank_line_are_left_alone() {
+        let stamped = with_credential(
+            "#EXT-X-ENDLIST\n\n#EXT-X-MAP:BYTERANGE=0\n",
+            &Credential::new("t", Some("tkt")),
+        );
+
+        assert_eq!(stamped, "#EXT-X-ENDLIST\n\n#EXT-X-MAP:BYTERANGE=0\n");
+    }
+
+    #[test]
+    fn an_unterminated_uri_attribute_is_handed_back_rather_than_mangled() {
+        let stamped = with_credential(
+            "#EXT-X-MAP:URI=\"init.mp4\n",
+            &Credential::new("t", Some("tkt")),
+        );
+
+        assert_eq!(stamped, "#EXT-X-MAP:URI=\"init.mp4\n");
+    }
+
+    #[test]
+    fn a_playlist_nobody_has_to_present_a_credential_for_is_not_rewritten() {
+        let playlist = "#EXTM3U\r\nseg00001.m4s\r\n";
+
+        assert_eq!(
+            with_credential(playlist, &Credential::new("t", None)),
+            playlist
+        );
+    }
+}

package/rust/kroma-media/src/probe/ffprobe_output.rs

@@ -0,0 +1,97 @@
+//! ffprobe's `-of json` output as types. Every field is optional because every
+//! field is absent for some container, and the spellings are ffprobe's own.
+
+use serde::Deserialize;
+
+// ffprobe spells the Dolby Vision record "DOVI configuration record".
+const DOVI: &str = "DOVI configuration record";
+
+#[derive(Debug, Deserialize)]
+pub(super) struct FfprobeOutput {
+    #[serde(default)]
+    pub(super) streams: Vec<FfStream>,
+    #[serde(default)]
+    pub(super) format: Option<FfFormat>,
+    #[serde(default)]
+    pub(super) chapters: Vec<FfChapter>,
+}
+
+#[derive(Debug, Deserialize)]
+pub(super) struct FfFormat {
+    pub(super) duration: Option<String>,
+}
+
+// `start_time`/`end_time` are seconds, as strings.
+#[derive(Debug, Deserialize)]
+pub(super) struct FfChapter {
+    pub(super) start_time: Option<String>,
+    pub(super) end_time: Option<String>,
+    #[serde(default)]
+    pub(super) tags: Option<FfChapterTags>,
+}
+
+#[derive(Debug, Deserialize)]
+pub(super) struct FfChapterTags {
+    pub(super) title: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+pub(super) struct FfStream {
+    pub(super) codec_type: Option<String>,
+    pub(super) codec_name: Option<String>,
+    pub(super) width: Option<u32>,
+    pub(super) height: Option<u32>,
+    pub(super) channels: Option<u32>,
+    pub(super) pix_fmt: Option<String>,
+    pub(super) color_transfer: Option<String>,
+    pub(super) color_primaries: Option<String>,
+    // ffprobe's name for the matrix coefficients.
+    pub(super) color_space: Option<String>,
+    pub(super) bits_per_raw_sample: Option<String>,
+    #[serde(default)]
+    pub(super) tags: Option<FfTags>,
+    #[serde(default)]
+    pub(super) disposition: Option<FfDisposition>,
+    #[serde(default)]
+    pub(super) side_data_list: Vec<FfSideData>,
+}
+
+#[derive(Debug, Deserialize)]
+pub(super) struct FfSideData {
+    pub(super) side_data_type: Option<String>,
+    pub(super) dv_profile: Option<u32>,
+}
+
+#[derive(Debug, Deserialize)]
+pub(super) struct FfTags {
+    pub(super) language: Option<String>,
+    pub(super) title: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+pub(super) struct FfDisposition {
+    pub(super) default: Option<u8>,
+    pub(super) forced: Option<u8>,
+}
+
+impl FfStream {
+    pub(super) fn dovi(&self) -> Option<&FfSideData> {
+        self.side_data_list
+            .iter()
+            .find(|d| d.side_data_type.as_deref() == Some(DOVI))
+    }
+
+    pub(super) fn language(&self) -> Option<String> {
+        self.tags
+            .as_ref()
+            .and_then(|t| t.language.clone())
+            .filter(|l| !l.is_empty() && l != "und")
+    }
+
+    pub(super) fn title(&self) -> Option<String> {
+        self.tags
+            .as_ref()
+            .and_then(|t| t.title.clone())
+            .filter(|t| !t.trim().is_empty())
+    }
+}

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

@@ -0,0 +1,37 @@
+//! Metadata extraction via the `ffprobe` CLI, never transcoding. A missing
+//! ffprobe or output KROMA cannot parse falls back to a container-extension
+//! guess; a file ffprobe itself refused is recorded as unreadable instead.
+
+mod ffprobe_output;
+mod parse;
+mod run;
+
+use kroma_module_wire::{AudioStream, SubtitleTrack, VideoStream};
+
+pub use run::*;
+
+fn duration_of(printed: &[u8]) -> Option<u64> {
+    let secs: f64 = String::from_utf8_lossy(printed).trim().parse().ok()?;
+    (secs > 0.0).then_some((secs * 1000.0) as u64)
+}
+
+/// All fields are best-effort. A set `unreadable` carries ffprobe's reason the
+/// container would not open, and every other field is then empty.
+#[derive(Debug, Default)]
+pub struct ProbeResult {
+    pub duration_ms: Option<u64>,
+    pub video: Option<VideoStream>,
+    pub audio: Option<AudioStream>,
+    // In container order: an audio-relative index is a position in here.
+    pub audio_tracks: Vec<AudioStream>,
+    pub subtitles: Vec<SubtitleTrack>,
+    pub chapters: Vec<Chapter>,
+    pub unreadable: Option<String>,
+}
+
+#[derive(Debug, Clone)]
+pub struct Chapter {
+    pub start_ms: u64,
+    pub end_ms: u64,
+    pub title: Option<String>,
+}