@kromatv/sdk 0.1.39-canary.3579809

package/rust/kroma-media/src/hls/session/testing.rs

@@ -0,0 +1,110 @@
+//! Fixtures shared by the serving and reclamation test modules: a session
+//! with a stand-in child process, and a registry pre-populated with them.
+
+use std::path::PathBuf;
+use std::process::Stdio;
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+
+use tokio::process::Command;
+use tokio::sync::Mutex;
+
+use super::super::hwaccel::{HwAccel, Pipeline};
+use super::super::live::Plan;
+use super::super::naming::session_dir;
+use super::super::software::Effort;
+use super::super::window::Window;
+use super::super::{AudioMode, StreamMode, VideoMode};
+use super::{Session, Sessions};
+
+pub(in crate::hls) const LIVE: Duration = Duration::from_secs(1);
+
+pub(in crate::hls) const PLAYLIST: &str = "#EXTM3U\n\
+    #EXT-X-VERSION:7\n\
+    #EXT-X-TARGETDURATION:6\n\
+    #EXT-X-MEDIA-SEQUENCE:0\n\
+    #EXT-X-PLAYLIST-TYPE:EVENT\n\
+    #EXT-X-MAP:URI=\"init.mp4\"\n\
+    #EXTINF:6.000000,\n\
+    seg_00000.m4s\n\
+    #EXTINF:6.000000,\n\
+    seg_00001.m4s\n\
+    #EXTINF:4.000000,\n\
+    seg_00002.m4s\n";
+
+pub(in crate::hls) fn fake_session(dir: PathBuf, age: Duration) -> Arc<Session> {
+    let child = Command::new("sleep")
+        .arg("30")
+        .stdin(Stdio::null())
+        .stdout(Stdio::null())
+        .stderr(Stdio::null())
+        .kill_on_drop(true)
+        .spawn()
+        .expect("spawn the stand-in child");
+    let last = Instant::now()
+        .checked_sub(age)
+        .expect("monotonic clock older than the test window");
+    let plan = Plan::new(
+        "it:copy:0:a0",
+        0,
+        StreamMode::new(VideoMode::Copy, AudioMode::Copy),
+        Pipeline {
+            accel: HwAccel::Software,
+            effort: Effort::Quality,
+        },
+        None,
+        child.id(),
+        0.0,
+    );
+    Arc::new(Session {
+        dir,
+        child: Mutex::new(child),
+        last_access: Mutex::new(last),
+        window: Window::new(),
+        plan,
+        start: 0.0,
+        superseded: std::sync::atomic::AtomicBool::new(false),
+        _cpu: None,
+    })
+}
+
+// `budget = 0` so only the concurrency cap is exercised. The guard comes back
+// with the registry: its segment directories live under that temp root.
+pub(in crate::hls) async fn registry(
+    name: &str,
+    cap: usize,
+    sessions: &[(&str, Duration)],
+) -> (Sessions, kroma_testing::TempDir) {
+    registry_with_budget(name, cap, 0, sessions).await
+}
+
+pub(in crate::hls) async fn registry_with_budget(
+    name: &str,
+    cap: usize,
+    budget: u64,
+    sessions: &[(&str, Duration)],
+) -> (Sessions, kroma_testing::TempDir) {
+    let data = kroma_testing::temp_dir(&format!("hls-test-{name}"));
+    let s = Sessions::new(data.path().join("hls"), cap, budget);
+    let mut map = s.inner.lock().await;
+    for (key, age) in sessions {
+        let dir = s.root.join(session_dir(key));
+        tokio::fs::create_dir_all(&dir).await.expect("session dir");
+        map.insert((*key).to_string(), fake_session(dir, *age));
+    }
+    drop(map);
+    (s, data)
+}
+
+/// Give a session's directory a measurable size, so the byte budget has
+/// something to trim.
+pub(in crate::hls) fn fill(s: &Sessions, key: &str, bytes: usize) {
+    let dir = s.root.join(session_dir(key));
+    std::fs::write(dir.join("seg_00001.m4s"), vec![b'x'; bytes]).expect("segment bytes");
+}
+
+pub(in crate::hls) async fn keys(s: &Sessions) -> Vec<String> {
+    let mut keys: Vec<String> = s.inner.lock().await.keys().cloned().collect();
+    keys.sort();
+    keys
+}

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

@@ -0,0 +1,259 @@
+//! One continuous ffmpeg per (item, audio-mode), writing fMP4 segments served as
+//! it produces them. Per-segment `-ss … -c:v copy -t <dur>` cuts are unreliable on
+//! MKV (the cue index is only a keyframe subset, so the copy over-runs and desyncs
+//! A/V); one process splits at real keyframes and owns the playlist. A seek the
+//! client cannot reach re-anchors by reloading the master at `?t=<secs>`.
+//!
+//! This half starts sessions and serves out of them; [`super::reclaim`] is what
+//! takes them away again, and [`super::live`] is what the admin sees of them.
+
+use std::collections::HashMap;
+use std::path::{Path, PathBuf};
+use std::sync::atomic::{AtomicBool, AtomicU64};
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+
+use tokio::process::Child;
+use tokio::sync::Mutex;
+use tokio::time::sleep;
+use tracing::{info, warn};
+
+use super::covered::Serving;
+use super::ffmpeg::{detect_burst, keyframe_before, spawn_stream};
+use super::hwaccel::Pipeline;
+use super::live::Plan;
+use super::naming::{contains, content_type, is_safe_name, seg_index, session_dir};
+use super::window::Window;
+use super::{StreamMode, VideoMode};
+use crate::ffmpeg_gate;
+
+const FILE_WAIT: Duration = Duration::from_secs(20);
+
+pub(super) struct Session {
+    pub(super) dir: PathBuf,
+    pub(super) child: Mutex<Child>,
+    pub(super) last_access: Mutex<Instant>,
+    pub(super) window: Window,
+    // How this session was started, so the admin can be told what the box is
+    // spending its cycles on without re-deriving it from the key.
+    pub(super) plan: Plan,
+    // Real stream start (s): the keyframe at-or-before the requested anchor,
+    // which the client uses as `baseSec`.
+    pub(super) start: f64,
+    pub(super) superseded: AtomicBool,
+    // Held only where the picture is re-encoded on the CPU, and dropped with the
+    // session: for as long as it lives, background media passes are held to one
+    // at a time (see [`crate::ffmpeg_gate`]).
+    _cpu: Option<ffmpeg_gate::Reservation>,
+}
+
+impl Session {
+    async fn touch(&self) {
+        *self.last_access.lock().await = Instant::now();
+        self.keep();
+    }
+
+    pub(super) async fn finished(&self) -> bool {
+        matches!(self.child.lock().await.try_wait(), Ok(Some(_)))
+    }
+}
+
+/// Remux sessions keyed per program + anchor (see `session_key`).
+pub struct Sessions {
+    pub(super) root: PathBuf,
+    pub(super) cap: usize,
+    // On-disk byte budget for the whole cache; 0 = unlimited.
+    pub(super) budget: AtomicU64,
+    burst: bool,
+    pub(super) inner: Mutex<HashMap<String, Arc<Session>>>,
+    pub(super) serving: Serving,
+}
+
+impl Sessions {
+    pub fn new(root: PathBuf, cap: usize, budget: u64) -> Self {
+        let _ = std::fs::remove_dir_all(&root);
+        let _ = std::fs::create_dir_all(&root);
+        Sessions {
+            root,
+            cap: cap.max(1),
+            budget: AtomicU64::new(budget),
+            burst: detect_burst(),
+            inner: Mutex::new(HashMap::new()),
+            serving: Serving::default(),
+        }
+    }
+
+    /// Retune the disk budget at runtime; 0 = unlimited.
+    pub fn set_budget(&self, bytes: u64) {
+        self.budget
+            .store(bytes, std::sync::atomic::Ordering::Relaxed);
+    }
+
+    pub fn bytes(&self) -> u64 {
+        super::reclaim::dir_bytes(&self.root)
+    }
+
+    /// Returns the media playlist bytes plus the real stream start (s) for `baseSec`.
+    ///
+    /// `source` is the file's own frame size where the catalog knows it: it is
+    /// what the picture costs to decode, and so half of what the box is being
+    /// asked to keep up with.
+    pub async fn master(
+        &self,
+        key: &str,
+        input: &Path,
+        audio: u32,
+        mode: StreamMode,
+        start_secs: f64,
+        source: Option<(u32, u32)>,
+    ) -> Option<(Vec<u8>, f64)> {
+        if let Some(reused) = self.reuse(key, start_secs).await {
+            reused.session.touch().await;
+            self.serving.note(key, &reused.key).await;
+            info!(session = %key, serving = %reused.key, "answered a re-anchor out of a running session");
+            return Some((ended(&reused.session, reused.playlist).await, reused.start));
+        }
+        self.serving.forget(key).await;
+        let session = match self
+            .ensure(key, input, audio, mode, start_secs, source)
+            .await
+        {
+            Ok(s) => s,
+            Err(e) => {
+                warn!(error = %e, session = %key, "failed to start HLS remux");
+                return None;
+            }
+        };
+        let start = session.start;
+        let path = session.dir.join("index.m3u8");
+        let deadline = Instant::now() + FILE_WAIT;
+        loop {
+            if let Ok(bytes) = tokio::fs::read(&path).await {
+                // A media playlist is only valid once it carries a target duration.
+                if contains(&bytes, b"#EXT-X-TARGETDURATION") {
+                    return Some((bytes, start));
+                }
+            }
+            if Instant::now() >= deadline {
+                return tokio::fs::read(&path).await.ok().map(|b| (b, start));
+            }
+            sleep(Duration::from_millis(80)).await;
+        }
+    }
+
+    /// A finished playlist gains `#EXT-X-ENDLIST` so it becomes seekable VOD; a
+    /// not-yet-produced segment is polled for until ffmpeg flushes it.
+    pub async fn file(&self, key: &str, name: &str) -> Option<(Vec<u8>, &'static str)> {
+        if !is_safe_name(name) {
+            return None;
+        }
+        let session = self.serving_session(key).await?;
+        session.touch().await;
+        let idx = seg_index(name);
+        // A pruned segment is never reproduced (the remux only moves forward), so
+        // 404 now instead of burning FILE_WAIT on a poll that cannot succeed.
+        if idx.is_some_and(|i| !session.window.note(i)) {
+            return None;
+        }
+        let path = session.dir.join(name);
+        let deadline = Instant::now() + FILE_WAIT;
+        loop {
+            if let Ok(bytes) = tokio::fs::read(&path).await {
+                let bytes = if name.ends_with(".m3u8") {
+                    ended(&session, bytes).await
+                } else {
+                    bytes
+                };
+                return Some((bytes, content_type(name)));
+            }
+            // A reap during the wait can delete what this poll is waiting for.
+            if idx.is_some_and(|i| session.window.is_pruned(i)) {
+                return None;
+            }
+            if Instant::now() >= deadline {
+                return None;
+            }
+            sleep(Duration::from_millis(80)).await;
+        }
+    }
+
+    async fn ensure(
+        &self,
+        key: &str,
+        input: &Path,
+        audio: u32,
+        mode: StreamMode,
+        start_secs: f64,
+        source: Option<(u32, u32)>,
+    ) -> std::io::Result<Arc<Session>> {
+        // The anchor is part of the key, so an existing session is always the right one.
+        {
+            let map = self.inner.lock().await;
+            if let Some(s) = map.get(key) {
+                s.touch().await;
+                return Ok(s.clone());
+            }
+        }
+        self.retire_superseded(key).await;
+        // Both shell out on their first call: must not run under the lock.
+        let start = keyframe_before(input, start_secs).await;
+        // Off the reactor: the first call makes every candidate device encode a
+        // test frame, and this one runs inside the request that starts a session.
+        let target = mode.video.box_size();
+        let pipeline = tokio::task::spawn_blocking(move || Pipeline::choose(source, target))
+            .await
+            .unwrap_or_else(|_| Pipeline::choose(source, target));
+        // The one case worth taking the box away from background work: no device,
+        // and a picture that has to be rebuilt frame by frame while someone waits.
+        let on_the_cpu = pipeline.on_the_cpu() && !matches!(mode.video, VideoMode::Copy);
+
+        let mut map = self.inner.lock().await;
+        if let Some(s) = map.get(key) {
+            s.touch().await; // another task created it while we probed
+            return Ok(s.clone());
+        }
+        self.make_room(&mut map).await;
+        let dir = self.root.join(session_dir(key));
+        super::reclaim::discard_dir(&dir);
+        tokio::fs::create_dir_all(&dir).await?;
+        let child = spawn_stream(input, &dir, audio, mode, start_secs, self.burst, pipeline)?;
+        info!(session = %key, audio, mode = ?mode, anchor = start_secs, start, accel = pipeline.accel.label(), effort = pipeline.effort.label(), "started HLS remux");
+        let session = Arc::new(Session {
+            plan: Plan::new(key, audio, mode, pipeline, source, child.id(), start_secs),
+            dir,
+            child: Mutex::new(child),
+            last_access: Mutex::new(Instant::now()),
+            window: Window::new(),
+            start,
+            superseded: AtomicBool::new(false),
+            _cpu: on_the_cpu.then(ffmpeg_gate::reserve),
+        });
+        map.insert(key.to_string(), session.clone());
+        Ok(session)
+    }
+
+    async fn retire_superseded(&self, key: &str) {
+        let mut map = self.inner.lock().await;
+        self.reap_superseded(&mut map, key).await;
+    }
+
+    async fn serving_session(&self, key: &str) -> Option<Arc<Session>> {
+        if let Some(session) = self.inner.lock().await.get(key).cloned() {
+            return Some(session);
+        }
+        let serving = self.serving.answering(key).await?;
+        self.inner.lock().await.get(&serving).cloned()
+    }
+}
+
+// A finished remux writes no `#EXT-X-ENDLIST` of its own under an EVENT
+// playlist, and without one the playlist is never seekable VOD to a player.
+async fn ended(session: &Session, mut playlist: Vec<u8>) -> Vec<u8> {
+    if session.finished().await && !contains(&playlist, b"#EXT-X-ENDLIST") {
+        playlist.extend_from_slice(b"#EXT-X-ENDLIST\n");
+    }
+    playlist
+}
+
+#[cfg(test)]
+pub(super) mod testing;

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

@@ -0,0 +1,171 @@
+//! What a host with no encoder device can afford to spend per frame.
+//!
+//! On fixed-function silicon a downscale costs the same whatever it is set to,
+//! and the question never arises. libx264 is the case where the box either stays
+//! ahead of the player or does not, and the cost is set by the pixels crossing
+//! the pipeline rather than by the title: a 4K source decoded down to 1080p is
+//! four times the decode of a 1080p one and lands on the same encoder.
+
+/// How much the software pipeline may spend per frame.
+///
+/// `Quality` is what a box with headroom uses. `Realtime` buys throughput with a
+/// softer downscale and a slightly larger stream, which is the right trade on the
+/// path it lives on: a re-encode only exists for a device that cannot play the
+/// source at all, so a picture that arrives is worth more than a picture that is
+/// 10% better and late.
+#[derive(Clone, Copy, PartialEq, Eq, Debug)]
+pub enum Effort {
+    Quality,
+    Realtime,
+}
+
+// Frame rate assumed of a source nobody probed. 30 rather than 24: reading the
+// load high costs a slightly softer picture, reading it low costs playback.
+const ASSUMED_FPS: f64 = 30.0;
+// Megapixels a second one logical core is trusted with before the tier drops.
+// Set low on purpose: reading a box as weaker than it is costs a softer picture
+// on a fallback path, reading it as stronger than it is costs playback, and the
+// box this has to hold for is a four-thread 1.5 GHz Celeron.
+const CORE_BUDGET: f64 = 15.0;
+
+impl Effort {
+    /// The tier for one transcode, from the picture going in, the box it is
+    /// fitted into (`None` = the source's own size) and this host's core count.
+    /// `KROMA_ENCODE_EFFORT=quality|realtime` pins it, which is how an operator
+    /// rules the tier out of a problem.
+    ///
+    /// A source nobody probed reads as `Realtime`: it may well be the 4K the
+    /// re-encode exists for, and guessing low here is the guess that stalls.
+    pub fn choose(source: Option<(u32, u32)>, target: Option<(u32, u32)>) -> Self {
+        match std::env::var("KROMA_ENCODE_EFFORT").ok().as_deref() {
+            Some("quality") => return Self::Quality,
+            Some("realtime") => return Self::Realtime,
+            _ => {}
+        }
+        let Some(source) = source else {
+            return Self::Realtime;
+        };
+        Self::for_load(load(source, target.unwrap_or(source), cores()))
+    }
+
+    /// The decoder flags this tier asks for, which precede `-i`.
+    ///
+    /// `noref` is the conservative rung of `-skip_loop_filter`: deblocking is
+    /// dropped only on frames nothing else is predicted from, so the artefact it
+    /// leaves cannot propagate, and a 2:1 downscale washes out most of what the
+    /// filter would have smoothed. It is the only lever the decode side has, and
+    /// on a 4K source the decode is the half that does not fit.
+    pub const fn decoder_args(self) -> &'static [&'static str] {
+        match self {
+            Self::Realtime => &["-skip_loop_filter", "noref"],
+            Self::Quality => &[],
+        }
+    }
+
+    /// The swscale kernel for the downscale, or None to leave ffmpeg its default
+    /// (bicubic). Only the paths that scale in system memory read this.
+    pub const fn sws_flags(self) -> Option<&'static str> {
+        match self {
+            Self::Realtime => Some("fast_bilinear"),
+            Self::Quality => None,
+        }
+    }
+
+    /// libx264's rate control and speed.
+    ///
+    /// `ultrafast` is not one of the options on purpose: it turns CABAC off, and
+    /// the stream it makes at a fixed CRF is large enough that the muxer, the disk
+    /// and the LAN give back much of what the cheaper analysis won - on a path
+    /// that exists because the client was already the constrained end.
+    pub const fn x264_args(self) -> &'static [&'static str] {
+        match self {
+            Self::Quality => &["-preset", "veryfast", "-crf", "21"],
+            Self::Realtime => &["-preset", "superfast", "-crf", "23"],
+        }
+    }
+
+    /// How it reads in a log line.
+    pub const fn label(self) -> &'static str {
+        match self {
+            Self::Quality => "quality",
+            Self::Realtime => "realtime",
+        }
+    }
+
+    const fn for_load(load: f64) -> Self {
+        if load <= CORE_BUDGET {
+            Self::Quality
+        } else {
+            Self::Realtime
+        }
+    }
+}
+
+// Megapixels a second, per logical core, that this job asks of the box: the
+// source is what has to be decoded and the target is what has to be encoded.
+fn load(source: (u32, u32), target: (u32, u32), cores: usize) -> f64 {
+    let mpix = |(w, h): (u32, u32)| f64::from(w) * f64::from(h) / 1_000_000.0;
+    (mpix(source) + mpix(target)) * ASSUMED_FPS / cores.max(1) as f64
+}
+
+fn cores() -> usize {
+    std::thread::available_parallelism()
+        .map(std::num::NonZeroUsize::get)
+        .unwrap_or(4)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const UHD: (u32, u32) = (3840, 2160);
+    const HD: (u32, u32) = (1920, 1080);
+
+    #[test]
+    fn a_four_core_nas_downscaling_4k_cannot_afford_the_quality_tier() {
+        // A DS918+: four threads of 1.5 GHz Celeron against 10 megapixels a frame.
+        assert_eq!(Effort::for_load(load(UHD, HD, 4)), Effort::Realtime);
+    }
+
+    #[test]
+    fn a_box_with_headroom_keeps_the_quality_tier() {
+        assert_eq!(Effort::for_load(load(HD, HD, 12)), Effort::Quality);
+    }
+
+    #[test]
+    fn the_same_job_gets_cheaper_as_cores_are_added() {
+        assert!(load(UHD, HD, 16) < load(UHD, HD, 4));
+    }
+
+    #[test]
+    fn an_unprobed_source_reads_as_the_4k_the_re_encode_exists_for() {
+        assert_eq!(Effort::choose(None, Some(HD)), Effort::Realtime);
+    }
+
+    #[test]
+    fn a_downscale_costs_more_than_the_same_picture_left_alone() {
+        // The source is decoded either way, so the target is the only term that moves.
+        assert!(load(UHD, HD, 4) < load(UHD, UHD, 4));
+    }
+
+    #[test]
+    fn the_realtime_tier_is_cheaper_at_every_stage() {
+        assert!(!Effort::Realtime.decoder_args().is_empty());
+        assert!(Effort::Quality.decoder_args().is_empty());
+        assert_eq!(Effort::Realtime.sws_flags(), Some("fast_bilinear"));
+        assert_eq!(Effort::Quality.sws_flags(), None);
+        assert!(Effort::Realtime.x264_args().contains(&"superfast"));
+        assert!(Effort::Quality.x264_args().contains(&"veryfast"));
+    }
+
+    #[test]
+    fn no_tier_reaches_for_ultrafast() {
+        for effort in [Effort::Quality, Effort::Realtime] {
+            assert!(
+                !effort.x264_args().contains(&"ultrafast"),
+                "{}",
+                effort.label()
+            );
+        }
+    }
+}