@kromatv/sdk 0.1.39-canary.3579809

package/rust/kroma-media/src/hls/hwaccel/probe.rs

@@ -0,0 +1,237 @@
+//! Which device this host actually has, and why it does not have the others.
+//!
+//! Listing an encoder proves nothing: `h264_vaapi` appears in every build
+//! configured with VAAPI whether or not the box has a driver, a render node, or
+//! permission to open one. A device that is present, listed and unusable is
+//! indistinguishable from no device at all unless something says so out loud, so
+//! every candidate is made to encode three frames before it is believed, and the
+//! sentence explaining the outcome is kept for the log and the admin.
+
+use std::path::Path;
+use std::sync::OnceLock;
+use std::time::Duration;
+
+use super::super::ffmpeg::ffmpeg_output;
+use super::super::naming::contains;
+use super::{render_node, HwAccel};
+
+const VALIDATE_TIMEOUT: Duration = Duration::from_secs(20);
+// Three frames of nothing: enough to open the device, allocate its surfaces and
+// get a packet back, which is every step that fails when a driver is missing.
+const TEST_SOURCE: &str = "color=c=black:s=320x240:r=25";
+
+/// The pipeline the host settled on, and the sentence explaining it. The reason
+/// is the whole point: "software" with no explanation is the shape a missing
+/// driver, an unreadable render node and a genuinely device-less box all take.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct Detection {
+    pub accel: HwAccel,
+    pub reason: String,
+}
+
+static DETECTED: OnceLock<Detection> = OnceLock::new();
+
+/// The best pipeline this host offers, probed once. Override with
+/// `KROMA_HWACCEL=<label>`, which is how an operator picks between two devices
+/// or pins the software path to rule it out of a problem.
+pub fn detect() -> HwAccel {
+    detected().accel
+}
+
+/// [`detect`] with the sentence that explains it.
+pub fn detected() -> &'static Detection {
+    DETECTED.get_or_init(run)
+}
+
+/// Probe now rather than on the first frame anyone asks for. The validation
+/// encodes shell out, and the alternative is paying for them inside the request
+/// that starts a session.
+pub fn prime() {
+    let d = detected();
+    if d.accel.is_device() {
+        tracing::info!(accel = d.accel.label(), reason = %d.reason, "video re-encodes run on hardware");
+    } else {
+        tracing::warn!(reason = %d.reason, "video re-encodes run on the CPU");
+    }
+}
+
+fn run() -> Detection {
+    if let Some(accel) = pinned() {
+        return Detection {
+            accel,
+            reason: format!("pinned by KROMA_HWACCEL={}", accel.label()),
+        };
+    }
+    let encoders = ffmpeg_output(&["-hide_banner", "-encoders"]);
+    let listed = candidates(&encoders);
+    if listed.is_empty() {
+        return Detection {
+            accel: HwAccel::Software,
+            reason: "this ffmpeg build lists no hardware H.264 encoder \
+                     (h264_qsv, h264_vaapi, h264_nvenc, h264_videotoolbox)"
+                .to_owned(),
+        };
+    }
+    let mut refused = Vec::new();
+    for accel in listed {
+        match usable(accel) {
+            Ok(()) => {
+                return Detection {
+                    accel,
+                    reason: format!("{} encoded a test frame", encoder_of(accel)),
+                };
+            }
+            Err(why) => refused.push(format!("{}: {why}", accel.label())),
+        }
+    }
+    Detection {
+        accel: HwAccel::Software,
+        reason: format!(
+            "every listed device refused a test encode ({})",
+            refused.join("; ")
+        ),
+    }
+}
+
+fn pinned() -> Option<HwAccel> {
+    match std::env::var("KROMA_HWACCEL").ok().as_deref()? {
+        "videotoolbox" => Some(HwAccel::VideoToolbox),
+        "qsv" => Some(HwAccel::Qsv),
+        "vaapi" => Some(HwAccel::Vaapi),
+        "nvenc" => Some(HwAccel::Nvenc),
+        "software" | "none" => Some(HwAccel::Software),
+        _ => None,
+    }
+}
+
+// Ordered by how little the host has to be trusted for it to work: an Apple
+// block is always there and always right; QSV beats VAAPI on the Intel parts
+// that have both; NVENC needs a card the encoder list alone does not prove.
+fn candidates(encoders: &[u8]) -> Vec<HwAccel> {
+    let has = |accel: HwAccel| contains(encoders, encoder_of(accel).as_bytes());
+    let mut out = Vec::new();
+    if cfg!(target_os = "macos") && has(HwAccel::VideoToolbox) {
+        out.push(HwAccel::VideoToolbox);
+    }
+    for accel in [HwAccel::Qsv, HwAccel::Vaapi, HwAccel::Nvenc] {
+        if has(accel) {
+            out.push(accel);
+        }
+    }
+    out
+}
+
+const fn encoder_of(accel: HwAccel) -> &'static str {
+    match accel {
+        HwAccel::VideoToolbox => "h264_videotoolbox",
+        HwAccel::Qsv => "h264_qsv",
+        HwAccel::Vaapi => "h264_vaapi",
+        HwAccel::Nvenc => "h264_nvenc",
+        HwAccel::Software => "libx264",
+    }
+}
+
+// The render node is opened here rather than left to ffmpeg because the failure
+// an operator has to act on - the service user is not in the group that owns it -
+// is otherwise buried in a driver's own error text.
+fn openable(node: &str) -> Result<(), String> {
+    if !Path::new(node).exists() {
+        return Err(format!("{node} does not exist"));
+    }
+    std::fs::OpenOptions::new()
+        .read(true)
+        .write(true)
+        .open(node)
+        .map(|_| ())
+        .map_err(|e| match e.kind() {
+            std::io::ErrorKind::PermissionDenied => format!(
+                "{node} is not readable by this user (on DSM, the package user must \
+                 join the `videodriver` group; in Docker, pass --device {node})"
+            ),
+            _ => format!("{node} could not be opened: {e}"),
+        })
+}
+
+fn usable(accel: HwAccel) -> Result<(), String> {
+    let node = render_node();
+    if matches!(accel, HwAccel::Qsv | HwAccel::Vaapi) {
+        openable(node)?;
+    }
+    let mut cmd = std::process::Command::new("ffmpeg");
+    cmd.args(["-v", "error", "-nostdin"]);
+    match accel {
+        HwAccel::Vaapi => {
+            cmd.args(["-vaapi_device", node]);
+        }
+        HwAccel::Qsv => {
+            let derive_from = format!("vaapi=va:{node}");
+            cmd.args(["-init_hw_device", derive_from.as_str()]).args([
+                "-init_hw_device",
+                "qsv=hw@va",
+                "-filter_hw_device",
+                "hw",
+            ]);
+        }
+        _ => {}
+    }
+    cmd.args(["-f", "lavfi", "-i", TEST_SOURCE, "-frames:v", "3"]);
+    if matches!(accel, HwAccel::Qsv | HwAccel::Vaapi) {
+        cmd.args(["-vf", "format=nv12,hwupload"]);
+    }
+    cmd.args(["-c:v", encoder_of(accel)]);
+    if matches!(accel, HwAccel::VideoToolbox | HwAccel::Nvenc) {
+        cmd.args(["-b:v", "1000k"]);
+    }
+    cmd.args(["-f", "null", "-"]);
+    crate::ffmpeg_run::run_capturing(cmd, VALIDATE_TIMEOUT)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const SOFTWARE_ONLY: &[u8] = b"V..... libx264 libx264 H.264\nV..... libx265 libx265\n";
+
+    #[test]
+    fn a_build_with_no_hardware_encoder_names_the_build_as_the_reason() {
+        // The static ffmpeg the NAS package used to ship: x264 and nothing else.
+        assert!(candidates(SOFTWARE_ONLY).is_empty());
+    }
+
+    #[test]
+    fn only_encoders_the_build_actually_lists_are_tried() {
+        let vaapi_only = b"V..... libx264 libx264\nV..... h264_vaapi VAAPI H.264\n".as_slice();
+
+        assert_eq!(candidates(vaapi_only), vec![HwAccel::Vaapi]);
+    }
+
+    #[test]
+    fn qsv_is_tried_before_vaapi_on_a_build_that_has_both() {
+        let both = b"V..... h264_vaapi VAAPI\nV..... h264_qsv QSV\nV..... h264_nvenc NVENC\n";
+
+        assert_eq!(
+            candidates(both.as_slice()),
+            vec![HwAccel::Qsv, HwAccel::Vaapi, HwAccel::Nvenc]
+        );
+    }
+
+    #[test]
+    fn a_render_node_that_is_not_there_says_so_rather_than_failing_silently() {
+        let why = openable("/dev/dri/renderD-nope").unwrap_err();
+
+        assert!(why.contains("does not exist"), "{why}");
+    }
+
+    #[test]
+    fn every_pipeline_names_the_encoder_it_is_probed_by() {
+        for accel in [
+            HwAccel::VideoToolbox,
+            HwAccel::Qsv,
+            HwAccel::Vaapi,
+            HwAccel::Nvenc,
+            HwAccel::Software,
+        ] {
+            assert!(encoder_of(accel).contains("264"), "{}", accel.label());
+        }
+    }
+}

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

@@ -0,0 +1,151 @@
+use super::*;
+
+const EVERY: [HwAccel; 5] = [
+    HwAccel::VideoToolbox,
+    HwAccel::Qsv,
+    HwAccel::Vaapi,
+    HwAccel::Nvenc,
+    HwAccel::Software,
+];
+
+#[test]
+fn scales_in_the_memory_each_device_decodes_into() {
+    assert_eq!(
+        HwAccel::Vaapi
+            .video_filter(Some((1920, 1080)), Effort::Quality)
+            .unwrap(),
+        "scale_vaapi=w=1920:h=1080:force_original_aspect_ratio=decrease:force_divisible_by=2:format=nv12"
+    );
+    assert_eq!(
+        HwAccel::Qsv
+            .video_filter(Some((1280, 720)), Effort::Quality)
+            .unwrap(),
+        "scale_qsv=w=1280:h=720:force_original_aspect_ratio=decrease:force_divisible_by=2:format=nv12"
+    );
+    assert!(HwAccel::Nvenc
+        .video_filter(Some((1920, 1080)), Effort::Quality)
+        .unwrap()
+        .starts_with("scale_cuda="));
+    assert!(HwAccel::Software
+        .video_filter(Some((1920, 1080)), Effort::Quality)
+        .unwrap()
+        .starts_with("scale=w=1920"));
+}
+
+#[test]
+fn fits_inside_the_box_rather_than_stretching_to_it() {
+    // Every scaler must keep the shape: a scope frame ends width-limited.
+    for accel in EVERY {
+        let filter = accel
+            .video_filter(Some((1920, 1080)), Effort::Quality)
+            .unwrap();
+
+        assert!(
+            filter.contains("force_original_aspect_ratio=decrease"),
+            "{}: {filter}",
+            accel.label()
+        );
+    }
+}
+
+#[test]
+fn only_the_scalers_that_run_on_the_cpu_take_the_cheaper_kernel() {
+    for accel in [HwAccel::Software, HwAccel::VideoToolbox] {
+        let filter = accel
+            .video_filter(Some((1920, 1080)), Effort::Realtime)
+            .unwrap();
+
+        assert!(
+            filter.ends_with(":flags=fast_bilinear"),
+            "{}: {filter}",
+            accel.label()
+        );
+    }
+    for accel in [HwAccel::Qsv, HwAccel::Vaapi, HwAccel::Nvenc] {
+        let filter = accel
+            .video_filter(Some((1920, 1080)), Effort::Realtime)
+            .unwrap();
+
+        assert!(
+            !filter.contains("fast_bilinear"),
+            "{}: {filter}",
+            accel.label()
+        );
+    }
+}
+
+#[test]
+fn drops_the_depth_on_a_device_even_where_nothing_is_resized() {
+    // A 10-bit or 4:4:4 source decodes into surfaces no encoder here takes, so a
+    // full-size re-encode still needs an 8-bit 4:2:0 format handed over.
+    for accel in [HwAccel::Qsv, HwAccel::Vaapi, HwAccel::Nvenc] {
+        for size in [None, Some((1920, 1080))] {
+            let filter = accel.video_filter(size, Effort::Quality).unwrap();
+
+            assert!(
+                filter.contains("format=nv12") || filter.contains("format=yuv420p"),
+                "{}: {filter}",
+                accel.label()
+            );
+        }
+    }
+}
+
+#[test]
+fn leaves_the_depth_to_the_encoder_where_the_frames_are_in_system_memory() {
+    assert_eq!(HwAccel::Software.video_filter(None, Effort::Quality), None);
+    assert_eq!(
+        HwAccel::VideoToolbox.video_filter(None, Effort::Quality),
+        None
+    );
+    for accel in [HwAccel::Software, HwAccel::VideoToolbox] {
+        assert!(
+            accel.encoder_args(Effort::Quality).contains(&"yuv420p"),
+            "{}",
+            accel.label()
+        );
+    }
+}
+
+#[test]
+fn every_device_encodes_to_the_h264_every_target_reads() {
+    for accel in EVERY {
+        let args = accel.encoder_args(Effort::Quality).join(" ");
+
+        assert!(args.contains("264"), "{}: {args}", accel.label());
+    }
+}
+
+#[test]
+fn the_effort_tier_only_reaches_the_encoder_the_cpu_runs() {
+    for accel in [
+        HwAccel::VideoToolbox,
+        HwAccel::Qsv,
+        HwAccel::Vaapi,
+        HwAccel::Nvenc,
+    ] {
+        assert_eq!(
+            accel.encoder_args(Effort::Quality),
+            accel.encoder_args(Effort::Realtime),
+            "{}",
+            accel.label()
+        );
+        assert!(accel.is_device(), "{}", accel.label());
+    }
+    assert_ne!(
+        HwAccel::Software.encoder_args(Effort::Quality),
+        HwAccel::Software.encoder_args(Effort::Realtime)
+    );
+    assert!(!HwAccel::Software.is_device());
+}
+
+#[test]
+fn a_device_decodes_on_the_device_and_the_cpu_path_takes_the_tiers_flags() {
+    assert!(HwAccel::Vaapi
+        .input_args(Effort::Quality)
+        .contains(&"vaapi"));
+    assert!(HwAccel::Software.input_args(Effort::Quality).is_empty());
+    assert!(HwAccel::Software
+        .input_args(Effort::Realtime)
+        .contains(&"-skip_loop_filter"));
+}

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

@@ -0,0 +1,115 @@
+//! The session key, `{item_id}:{mode}:{anchor_secs}:a{audio}`, and the
+//! predicates that read a program out of one. The mode is part of the key
+//! because filtered, transcoded and clean programs must never share segment
+//! URLs (segments are cached immutably per URL).
+
+use super::StreamMode;
+
+pub(super) fn session_key(item_id: &str, mode: StreamMode, anchor: u64, audio: u32) -> String {
+    format!("{item_id}:{}:{anchor}:a{audio}", mode.token())
+}
+
+// Split from the right because an item id may itself contain a colon.
+fn without_anchor(key: &str) -> Option<(&str, &str)> {
+    let (head, audio) = key.rsplit_once(':')?;
+    let (item_and_mode, _anchor) = head.rsplit_once(':')?;
+    Some((item_and_mode, audio))
+}
+
+// The `(item_id, a{audio})` a key identifies, apart from mode and anchor.
+pub(super) fn program_of(key: &str) -> Option<(&str, &str)> {
+    let (item_and_mode, audio) = without_anchor(key)?;
+    let (item, _mode) = item_and_mode.rsplit_once(':')?;
+    Some((item, audio))
+}
+
+pub(super) fn same_but_the_anchor(a: &str, b: &str) -> bool {
+    match (without_anchor(a), without_anchor(b)) {
+        (Some(x), Some(y)) => x == y,
+        _ => false,
+    }
+}
+
+// Whether two session keys play the same program and differ only in mode /
+// anchor - used by the session registry to pick a victim under the
+// concurrency cap (see `Sessions::make_room`).
+pub(super) fn same_program(a: &str, b: &str) -> bool {
+    match (program_of(a), program_of(b)) {
+        (Some(x), Some(y)) => x == y,
+        _ => false,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::hls::{AudioMode, VideoMode};
+
+    const fn audio(audio: AudioMode) -> StreamMode {
+        StreamMode::new(VideoMode::Copy, audio)
+    }
+
+    #[test]
+    fn session_keys_keep_filtered_programs_apart() {
+        let clean = session_key("it1", audio(AudioMode::Aac), 30, 1);
+        let night = session_key("it1", audio(AudioMode::AacNight), 30, 1);
+        assert_eq!(clean, "it1:aac:30:a1");
+        assert_eq!(night, "it1:aac-night:30:a1");
+        assert_ne!(clean, night);
+    }
+
+    #[test]
+    fn session_keys_keep_a_transcoded_picture_apart_from_a_copied_one() {
+        let copied = session_key("it1", audio(AudioMode::Aac), 30, 1);
+        let recoded = session_key(
+            "it1",
+            StreamMode::new(VideoMode::H264, AudioMode::Aac),
+            30,
+            1,
+        );
+        assert_eq!(recoded, "it1:h264-aac:30:a1");
+        assert_ne!(copied, recoded);
+    }
+
+    #[test]
+    fn same_program_spans_anchors_and_modes_only() {
+        let key = session_key("it1", audio(AudioMode::Aac), 30, 1);
+        assert!(same_program(
+            &key,
+            &session_key("it1", audio(AudioMode::Aac), 900, 1)
+        ));
+        assert!(same_program(
+            &key,
+            &session_key("it1", audio(AudioMode::AacNight), 30, 1)
+        ));
+        assert!(same_program(
+            &key,
+            &session_key(
+                "it1",
+                StreamMode::new(VideoMode::H264, AudioMode::Aac),
+                30,
+                1
+            )
+        ));
+        assert!(!same_program(
+            &key,
+            &session_key("it1", audio(AudioMode::Aac), 30, 2)
+        ));
+        assert!(!same_program(
+            &key,
+            &session_key("it2", audio(AudioMode::Aac), 30, 1)
+        ));
+        assert!(!same_program(&key, "nonsense"));
+        assert!(!same_program("nonsense", "nonsense"));
+    }
+
+    #[test]
+    fn program_of_tolerates_a_colon_in_the_item_id() {
+        assert_eq!(
+            program_of("tv:s1e2:aac-night:30:a1"),
+            Some(("tv:s1e2", "a1"))
+        );
+        assert_eq!(program_of("it1:copy:0:a0"), Some(("it1", "a0")));
+        assert_eq!(program_of("bogus"), None);
+    }
+}

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

@@ -0,0 +1,138 @@
+use super::super::hwaccel::HwAccel;
+use super::super::software::Effort;
+use super::super::Rung;
+use super::*;
+
+fn plan(key: &str, mode: StreamMode, accel: HwAccel) -> Plan {
+    Plan::new(
+        key,
+        1,
+        mode,
+        Pipeline {
+            accel,
+            effort: Effort::Realtime,
+        },
+        Some((3840, 2160)),
+        Some(4242),
+        30.0,
+    )
+}
+
+fn seeded_dir(name: &str) -> (kroma_testing::TempDir, std::path::PathBuf) {
+    let data = kroma_testing::temp_dir(name);
+    let dir = data.path().join("s");
+    std::fs::create_dir_all(&dir).expect("session dir");
+    (data, dir)
+}
+
+#[test]
+fn a_downscale_reports_the_box_it_is_fitting_the_picture_into() {
+    let (_data, dir) = seeded_dir("hls-live-box");
+    let mode = StreamMode::new(VideoMode::H264At(Rung::P1080), AudioMode::Aac);
+
+    let t = report(
+        &plan("it1:h264-1080-aac:30:a1", mode, HwAccel::Vaapi),
+        &dir,
+        true,
+    );
+
+    assert_eq!(t.video, "h264-1080");
+    assert_eq!((t.target_width, t.target_height), (Some(1920), Some(1080)));
+    assert_eq!((t.source_width, t.source_height), (Some(3840), Some(2160)));
+    assert!(t.transcodes_video);
+    assert!(t.transcodes_audio);
+    assert_eq!(t.accel, "vaapi");
+    assert!(!t.on_the_cpu);
+    assert_eq!(t.item_id, "it1");
+    assert_eq!(t.pid, Some(4242));
+}
+
+#[test]
+fn a_stream_copy_says_it_is_costing_the_box_nothing() {
+    let (_data, dir) = seeded_dir("hls-live-copy");
+    let mode = StreamMode::new(VideoMode::Copy, AudioMode::Copy);
+
+    let t = report(&plan("it1:copy:0:a1", mode, HwAccel::Software), &dir, true);
+
+    assert_eq!(t.video, "copy");
+    assert!(!t.transcodes_video);
+    assert!(!t.transcodes_audio);
+    assert_eq!((t.target_width, t.target_height), (None, None));
+    assert!(
+        t.on_the_cpu,
+        "software is the pipeline even where nothing re-encodes"
+    );
+}
+
+#[test]
+fn the_rate_the_encoder_is_holding_comes_from_the_progress_file() {
+    let (_data, dir) = seeded_dir("hls-live-speed");
+    std::fs::write(
+        dir.join(progress::FILE),
+        "frame=300\nfps=25.00\nout_time_us=12000000\ndrop_frames=2\n\
+         speed=0.42x\nprogress=continue\n",
+    )
+    .expect("progress file");
+
+    let mode = StreamMode::new(VideoMode::H264, AudioMode::Aac);
+    let t = report(
+        &plan("it1:h264-aac:0:a1", mode, HwAccel::Software),
+        &dir,
+        true,
+    );
+
+    assert!(
+        (t.speed - 0.42).abs() < 1e-3,
+        "the box is losing to the film"
+    );
+    assert_eq!(t.frames, 300);
+    assert_eq!(t.dropped, 2);
+    assert_eq!(t.out_time_ms, 12_000);
+}
+
+#[test]
+fn a_session_with_no_progress_file_yet_reports_zeroes_rather_than_nothing() {
+    let (_data, dir) = seeded_dir("hls-live-early");
+    let mode = StreamMode::new(VideoMode::H264, AudioMode::Copy);
+
+    let t = report(
+        &plan("it1:h264-copy:0:a1", mode, HwAccel::Software),
+        &dir,
+        true,
+    );
+
+    assert_eq!(t.speed, 0.0);
+    assert_eq!(t.segments, 0);
+    assert!(t.running);
+}
+
+#[test]
+fn segments_are_counted_apart_from_everything_else_in_the_directory() {
+    let (_data, dir) = seeded_dir("hls-live-stats");
+    for name in ["seg_00001.m4s", "seg_00002.m4s", "init.mp4", "index.m3u8"] {
+        std::fs::write(dir.join(name), vec![b'x'; 100]).expect("file");
+    }
+
+    let (segments, bytes) = dir_stats(&dir);
+
+    assert_eq!(segments, 2);
+    assert_eq!(
+        bytes, 400,
+        "every file counts toward the disk it is holding"
+    );
+}
+
+#[test]
+fn a_finished_run_stops_reading_as_running() {
+    let (_data, dir) = seeded_dir("hls-live-done");
+    std::fs::write(
+        dir.join(progress::FILE),
+        "frame=9\nspeed=2.0x\nprogress=end\n",
+    )
+    .expect("progress file");
+
+    let mode = StreamMode::new(VideoMode::Copy, AudioMode::Aac);
+    let t = report(&plan("it1:aac:0:a1", mode, HwAccel::Software), &dir, true);
+
+    assert!(!t.running);
+}