@kromatv/sdk 0.1.39-canary.3579809

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

@@ -0,0 +1,268 @@
+use super::*;
+
+const fn copy() -> StreamMode {
+    StreamMode::new(VideoMode::Copy, AudioMode::Copy)
+}
+
+const fn audio(audio: AudioMode) -> StreamMode {
+    StreamMode::new(VideoMode::Copy, audio)
+}
+
+const fn re_encoded() -> StreamMode {
+    StreamMode::new(VideoMode::H264, AudioMode::Copy)
+}
+
+// The Chromecast HD's own ceiling, which is square because its decoders
+// declare one size limit for both axes.
+const CHROMECAST_HD: (u32, u32) = (1920, 1920);
+
+const AVPLAYER: &str = "hevc,h264";
+
+#[test]
+fn scales_a_source_larger_than_the_decoder_the_client_declared() {
+    let scaled = copy().for_client_frame(Some((3840, 2160)), Some(CHROMECAST_HD));
+
+    assert_eq!(scaled.video, VideoMode::H264At(Rung::P1080));
+    assert_eq!(scaled.audio, AudioMode::Copy);
+    assert_eq!(scaled.token(), "h264-1080-copy");
+}
+
+#[test]
+fn scales_a_scope_frame_that_is_only_too_wide() {
+    // 1604 rows clears a 1920 ceiling; 3840 columns do not.
+    let scaled = copy().for_client_frame(Some((3840, 1604)), Some(CHROMECAST_HD));
+
+    assert_eq!(scaled.video, VideoMode::H264At(Rung::P1080));
+}
+
+#[test]
+fn leaves_a_picture_the_client_can_already_take() {
+    assert_eq!(
+        copy().for_client_frame(Some((1920, 1080)), Some(CHROMECAST_HD)),
+        copy()
+    );
+    assert_eq!(copy().for_client_frame(Some((3840, 2160)), None), copy());
+    assert_eq!(copy().for_client_frame(None, Some(CHROMECAST_HD)), copy());
+}
+
+#[test]
+fn overrides_a_full_size_re_encode_too_because_it_is_just_as_unplayable() {
+    let full = StreamMode::new(VideoMode::H264, AudioMode::Aac);
+
+    let scaled = full.for_client_frame(Some((3840, 2160)), Some(CHROMECAST_HD));
+
+    assert_eq!(scaled.video, VideoMode::H264At(Rung::P1080));
+    assert_eq!(scaled.audio, AudioMode::Aac);
+}
+
+#[test]
+fn drops_to_the_largest_rung_a_smaller_decoder_still_holds() {
+    assert_eq!(
+        copy()
+            .for_client_frame(Some((3840, 2160)), Some((1280, 800)))
+            .video,
+        VideoMode::H264At(Rung::P720)
+    );
+    assert_eq!(
+        copy()
+            .for_client_frame(Some((3840, 2160)), Some((640, 480)))
+            .video,
+        VideoMode::Copy
+    );
+}
+
+#[test]
+fn copy_becomes_aac_when_the_client_cannot_decode_the_codec() {
+    // The AC-3-only Android TV case: a copy request the device can't play.
+    assert_eq!(
+        copy().for_client_audio(Some("ac3"), Some("aac")),
+        audio(AudioMode::Aac)
+    );
+}
+
+#[test]
+fn copy_stays_copy_when_the_client_can_decode_or_passthrough() {
+    assert_eq!(
+        copy().for_client_audio(Some("ac3"), Some("aac,ac3,eac3")),
+        copy()
+    );
+    assert_eq!(
+        copy().for_client_audio(Some("AC3"), Some("aac, ac3")),
+        copy()
+    );
+}
+
+#[test]
+fn no_declared_capability_leaves_the_requested_mode_untouched() {
+    assert_eq!(copy().for_client_audio(Some("ac3"), None), copy());
+}
+
+#[test]
+fn an_empty_capability_set_transcodes_every_known_codec() {
+    assert_eq!(
+        copy().for_client_audio(Some("aac"), Some("")),
+        audio(AudioMode::Aac)
+    );
+}
+
+#[test]
+fn an_unknown_codec_is_never_forced_to_transcode() {
+    assert_eq!(copy().for_client_audio(None, Some("aac")), copy());
+    assert_eq!(copy().for_client_audio(None, Some("")), copy());
+}
+
+#[test]
+fn a_transcode_or_filter_request_is_never_second_guessed() {
+    for mode in [AudioMode::Aac, AudioMode::AacStandard, AudioMode::AacNight] {
+        assert_eq!(
+            audio(mode).for_client_audio(Some("ac3"), Some("")),
+            audio(mode)
+        );
+    }
+}
+
+#[test]
+fn video_copy_becomes_h264_when_the_client_cannot_decode_the_codec() {
+    // The HEVC-Main10-on-an-8-bit-decoder case, declared as "I decode H.264 only".
+    assert_eq!(
+        copy().for_client_video(Some("hevc"), None, Some("h264")),
+        re_encoded()
+    );
+}
+
+#[test]
+fn video_stays_a_copy_when_the_declared_set_holds_the_codec() {
+    assert_eq!(
+        copy().for_client_video(Some("hevc"), None, Some("h264,hevc,av1")),
+        copy()
+    );
+    assert_eq!(
+        copy().for_client_video(Some("HEVC"), None, Some("h264, hevc")),
+        copy()
+    );
+}
+
+#[test]
+fn a_client_that_declares_no_video_never_pays_for_a_transcode() {
+    assert_eq!(copy().for_client_video(Some("hevc"), None, None), copy());
+    assert_eq!(copy().for_client_video(Some("vp9"), None, None), copy());
+    assert_eq!(
+        copy().for_client_video(Some("h264"), Some(10), None),
+        copy()
+    );
+}
+
+#[test]
+fn an_empty_video_set_transcodes_every_known_codec() {
+    assert_eq!(
+        copy().for_client_video(Some("h264"), None, Some("")),
+        re_encoded()
+    );
+}
+
+#[test]
+fn an_unknown_video_codec_is_never_forced_to_transcode() {
+    assert_eq!(copy().for_client_video(None, None, Some("h264")), copy());
+    assert_eq!(copy().for_client_video(None, Some(10), Some("")), copy());
+}
+
+#[test]
+fn an_h264_request_is_never_second_guessed() {
+    let forced = re_encoded();
+    assert_eq!(
+        forced.for_client_video(Some("h264"), None, Some("h264")),
+        forced
+    );
+    assert_eq!(forced.for_client_video(Some("hevc"), None, None), forced);
+    assert_eq!(
+        forced.for_client_video(Some("h264"), Some(10), Some("h264")),
+        forced
+    );
+}
+
+#[test]
+fn ten_bit_h264_is_re_encoded_for_a_client_that_declared_h264_alone() {
+    assert_eq!(
+        copy().for_client_video(Some("h264"), Some(10), Some(AVPLAYER)),
+        re_encoded()
+    );
+    assert_eq!(
+        copy().for_client_video(Some("h264"), Some(12), Some(AVPLAYER)),
+        re_encoded()
+    );
+}
+
+#[test]
+fn ten_bit_h264_stays_a_copy_for_a_client_that_declared_it_decodes_one() {
+    assert_eq!(
+        copy().for_client_video(Some("h264"), Some(10), Some("h264,h26410bit")),
+        copy()
+    );
+    assert_eq!(
+        copy().for_client_video(Some("H264"), Some(10), Some("h264, H26410bit")),
+        copy()
+    );
+}
+
+#[test]
+fn eight_bit_h264_stays_a_copy_for_a_client_that_declared_only_h264() {
+    assert_eq!(
+        copy().for_client_video(Some("h264"), Some(8), Some(AVPLAYER)),
+        copy()
+    );
+}
+
+#[test]
+fn a_depth_nothing_read_keeps_the_copy_the_codec_name_earned() {
+    assert_eq!(
+        copy().for_client_video(Some("h264"), None, Some(AVPLAYER)),
+        copy()
+    );
+}
+
+#[test]
+fn the_deep_declaration_does_not_stand_in_for_plain_h264() {
+    assert_eq!(
+        copy().for_client_video(Some("h264"), Some(8), Some("h26410bit")),
+        re_encoded()
+    );
+}
+
+#[test]
+fn ten_bit_hevc_is_still_matched_on_its_name_alone() {
+    assert_eq!(
+        copy().for_client_video(Some("hevc"), Some(10), Some("hevc")),
+        copy()
+    );
+}
+
+#[test]
+fn the_two_axes_move_independently() {
+    let both = copy()
+        .for_client_audio(Some("dts"), Some("aac"))
+        .for_client_video(Some("hevc"), None, Some("h264"));
+    assert_eq!(both, StreamMode::new(VideoMode::H264, AudioMode::Aac));
+    assert_eq!(both.token(), "h264-aac");
+    assert_eq!(
+        audio(AudioMode::AacNight).for_client_video(Some("hevc"), None, Some("h264")),
+        StreamMode::new(VideoMode::H264, AudioMode::AacNight)
+    );
+    assert_eq!(
+        re_encoded().for_client_audio(Some("dts"), Some("aac")),
+        StreamMode::new(VideoMode::H264, AudioMode::Aac)
+    );
+}
+
+#[test]
+fn a_video_declaration_alone_never_moves_the_audio_axis() {
+    assert_eq!(
+        copy()
+            .for_client_video(Some("hevc"), None, Some("h264"))
+            .audio,
+        AudioMode::Copy
+    );
+    assert_eq!(
+        copy().for_client_audio(Some("dts"), Some("aac")).video,
+        VideoMode::Copy
+    );
+}

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

@@ -0,0 +1,101 @@
+//! Narrowing a requested [`StreamMode`] to what the client says it can take:
+//! the codecs it declared it decodes, the bit depth behind one of those names,
+//! and the frame size its decoder holds.
+
+use super::{AudioMode, Rung, StreamMode, VideoMode};
+
+const H264_10BIT: &str = "h26410bit";
+const H264: &str = "h264";
+
+impl StreamMode {
+    /// The mode whose audio will actually reach the speakers, given the selected
+    /// track's codec and the comma-separated set the client declared it can decode
+    /// (`None` = declared nothing, and the request stands). Only an audio copy is
+    /// ever overridden, and only the audio axis moves.
+    pub fn for_client_audio(self, codec: Option<&str>, client_decodes: Option<&str>) -> Self {
+        match (self.audio, client_decodes) {
+            (AudioMode::Copy, Some(set)) if !client_can_play(codec, set) => Self {
+                audio: AudioMode::Aac,
+                ..self
+            },
+            _ => self,
+        }
+    }
+
+    /// The mode whose picture will actually reach the screen, read the same way as
+    /// [`Self::for_client_audio`] from the source video stream and the set the
+    /// client declared. Two things play black on a copy: a codec the device has no
+    /// decoder for, and H.264 above 8 bits, which the client declares as
+    /// `h26410bit` beside `h264` because no codec name carries a depth. A depth
+    /// nothing read is matched on the codec name alone. Only a video copy is
+    /// overridden, and never speculatively - a client that declares nothing keeps
+    /// its stream copy.
+    pub fn for_client_video(
+        self,
+        codec: Option<&str>,
+        bit_depth: Option<u32>,
+        client_decodes: Option<&str>,
+    ) -> Self {
+        match (self.video, client_decodes) {
+            (VideoMode::Copy, Some(set)) if !client_can_draw(codec, bit_depth, set) => Self {
+                video: VideoMode::H264,
+                ..self
+            },
+            _ => self,
+        }
+    }
+
+    /// The mode whose picture actually fits the decoder it is going to. A decoder
+    /// has a size ceiling as surely as it has a codec list, and no player works
+    /// around one: a frame over it either refuses to open or falls to a software
+    /// decoder that cannot keep up. `source` is the file's own size and `max`
+    /// what the client declared; either absent leaves the mode alone.
+    ///
+    /// Both axes count. Overrides a copy AND a full-size re-encode, because a
+    /// re-encode at the source's size is just as unplayable as the source.
+    pub fn for_client_frame(self, source: Option<(u32, u32)>, max: Option<(u32, u32)>) -> Self {
+        let (Some(source), Some(max)) = (source, max) else {
+            return self;
+        };
+        if source.0 <= max.0 && source.1 <= max.1 {
+            return self;
+        }
+        Rung::under(max).map_or(self, |rung| Self {
+            video: VideoMode::H264At(rung),
+            ..self
+        })
+    }
+}
+
+// An unprobed stream is assumed playable: with no codec there is nothing honest
+// to override, and forcing a transcode would punish the common case.
+fn client_can_play(codec: Option<&str>, client_set: &str) -> bool {
+    let Some(codec) = codec else { return true };
+    declares(client_set, codec)
+}
+
+fn client_can_draw(codec: Option<&str>, bit_depth: Option<u32>, client_set: &str) -> bool {
+    let Some(codec) = codec else { return true };
+    declares(client_set, declared_as(codec, bit_depth))
+}
+
+// HEVC is deliberately absent: its 10-bit profile has no token of its own, so a
+// client that cannot draw one declares no `hevc` at all. Adding a token for it
+// would hand a NEW client on an OLD server the black picture it declares its way
+// out of today.
+fn declared_as(codec: &str, bit_depth: Option<u32>) -> &str {
+    if codec.eq_ignore_ascii_case(H264) && bit_depth.is_some_and(|depth| depth > 8) {
+        H264_10BIT
+    } else {
+        codec
+    }
+}
+
+fn declares(client_set: &str, token: &str) -> bool {
+    client_set
+        .split(',')
+        .any(|declared| declared.trim().eq_ignore_ascii_case(token))
+}
+
+#[cfg(test)]
+mod tests;

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

@@ -0,0 +1,198 @@
+//! What this host can hand a picture to.
+//!
+//! A re-encode is the one thing in the delivery path that costs real CPU, so it
+//! is the one thing worth putting on fixed-function silicon: an Intel iGPU, an
+//! Apple VideoToolbox block or an NVIDIA encoder turns a 4K→1080p downscale from
+//! "one stream saturates the box" into single-digit percent. Probed once per
+//! process, because the answer cannot change while it runs.
+//!
+//! [`probe`] is where the answer comes from, and why it is worth reporting: a
+//! device that is present, listed and unusable looks exactly like no device at
+//! all from the outside, and the operator is the only one who can fix it.
+
+mod probe;
+
+use std::sync::OnceLock;
+
+use super::software::Effort;
+
+pub use probe::{detect, detected, prime, Detection};
+
+/// What one re-encode runs on: the device that shrinks the picture and, where
+/// that device is the CPU, how hard it is allowed to work per frame. The two are
+/// one decision - the tier only means anything on the software path - so they
+/// are chosen and carried together.
+#[derive(Clone, Copy, PartialEq, Eq, Debug)]
+pub struct Pipeline {
+    pub accel: HwAccel,
+    pub effort: Effort,
+}
+
+impl Pipeline {
+    /// The device this host has, and the tier this job can afford on it, from the
+    /// picture going in and the box it is fitted into.
+    pub fn choose(source: Option<(u32, u32)>, target: Option<(u32, u32)>) -> Self {
+        Self {
+            accel: detect(),
+            effort: Effort::choose(source, target),
+        }
+    }
+
+    /// Whether the frames are rebuilt by the CPU, which is the only case where
+    /// the box has to be taken away from background work.
+    pub const fn on_the_cpu(self) -> bool {
+        !self.accel.is_device()
+    }
+}
+
+/// The pipeline the picture takes when it has to be re-encoded. `Software` is
+/// the floor, not a failure: it is what a host with no usable device gets.
+#[derive(Clone, Copy, PartialEq, Eq, Debug)]
+pub enum HwAccel {
+    VideoToolbox,
+    Qsv,
+    Vaapi,
+    Nvenc,
+    Software,
+}
+
+/// The Linux render node VAAPI and QSV open when nothing says otherwise. A host
+/// with several (an iGPU beside a card) names the one it means with
+/// `KROMA_RENDER_NODE`, because that choice belongs to an operator, not a probe.
+const DEFAULT_RENDER_NODE: &str = "/dev/dri/renderD128";
+
+pub(super) fn render_node() -> &'static str {
+    static NODE: OnceLock<&str> = OnceLock::new();
+    NODE.get_or_init(|| match std::env::var("KROMA_RENDER_NODE") {
+        Ok(v) if !v.trim().is_empty() => Box::leak(v.trim().to_owned().into_boxed_str()),
+        _ => DEFAULT_RENDER_NODE,
+    })
+}
+
+impl HwAccel {
+    /// How it reads in a log line or an admin field.
+    pub const fn label(self) -> &'static str {
+        match self {
+            Self::VideoToolbox => "videotoolbox",
+            Self::Qsv => "qsv",
+            Self::Vaapi => "vaapi",
+            Self::Nvenc => "nvenc",
+            Self::Software => "software",
+        }
+    }
+
+    /// Whether the picture is shrunk by fixed-function silicon rather than by
+    /// the CPU, which is what decides whether the effort tier matters at all.
+    pub const fn is_device(self) -> bool {
+        !matches!(self, Self::Software)
+    }
+
+    /// Args that must precede `-i`: they choose the decoder and say which memory
+    /// the decoded frames land in. `effort` only reaches the software path, whose
+    /// decoder is the CPU.
+    pub fn input_args(self, effort: Effort) -> Vec<&'static str> {
+        match self {
+            Self::VideoToolbox => vec!["-hwaccel", "videotoolbox"],
+            Self::Qsv => vec!["-hwaccel", "qsv", "-hwaccel_output_format", "qsv"],
+            Self::Vaapi => vec![
+                "-hwaccel",
+                "vaapi",
+                "-hwaccel_device",
+                render_node(),
+                "-hwaccel_output_format",
+                "vaapi",
+            ],
+            Self::Nvenc => vec!["-hwaccel", "cuda", "-hwaccel_output_format", "cuda"],
+            Self::Software => effort.decoder_args().to_vec(),
+        }
+    }
+
+    /// The `-vf` this device needs to reach the encoder, or None where the
+    /// picture already arrives in a shape it takes.
+    ///
+    /// Given a box, the picture is fitted inside it without changing shape:
+    /// `decrease` is what makes it a box rather than a size, so a scope frame
+    /// comes out width-limited and short and a 16:9 one height-limited, and
+    /// `force_divisible_by=2` because H.264 has no odd dimensions.
+    ///
+    /// With or without one, a device pipeline must still be told the format to
+    /// hand over: the decoder keeps a 10-bit source in 10-bit surfaces and none
+    /// of these encoders takes 10-bit H.264, so the filter is where the depth is
+    /// dropped. The software and VideoToolbox paths carry frames in system
+    /// memory, where the encoder's own `-pix_fmt` does it instead.
+    ///
+    /// Each device scales in the memory it decoded into, which is why this is
+    /// five filters and not one with a flag.
+    pub fn video_filter(self, size: Option<(u32, u32)>, effort: Effort) -> Option<String> {
+        let fit = size.map(|(w, h)| {
+            format!("w={w}:h={h}:force_original_aspect_ratio=decrease:force_divisible_by=2")
+        });
+        let device = |name: &str, format: &str| {
+            Some(match &fit {
+                Some(fit) => format!("{name}={fit}:format={format}"),
+                None => format!("{name}=format={format}"),
+            })
+        };
+        match self {
+            // Frames leave VideoToolbox for the scaler, so this one runs on the
+            // CPU: it is the only part of the pipeline that does.
+            Self::VideoToolbox | Self::Software => {
+                fit.as_ref().map(|fit| match effort.sws_flags() {
+                    Some(flags) => format!("scale={fit}:flags={flags}"),
+                    None => format!("scale={fit}"),
+                })
+            }
+            Self::Qsv => device("scale_qsv", "nv12"),
+            Self::Vaapi => device("scale_vaapi", "nv12"),
+            Self::Nvenc => device("scale_cuda", "yuv420p"),
+        }
+    }
+
+    /// The encoder and its rate control. 8-bit H.264 whatever the device: the
+    /// re-encode exists for players the source defeats, so it must land on the
+    /// one profile every target reads.
+    pub fn encoder_args(self, effort: Effort) -> Vec<&'static str> {
+        match self {
+            // VideoToolbox has no CRF: quality is a bitrate, and `-realtime`
+            // keeps the encoder from buffering a whole GOP ahead of the player.
+            Self::VideoToolbox => vec![
+                "-c:v",
+                "h264_videotoolbox",
+                "-realtime",
+                "1",
+                "-b:v",
+                "8000k",
+                "-pix_fmt",
+                "yuv420p",
+            ],
+            Self::Qsv => vec![
+                "-c:v",
+                "h264_qsv",
+                "-global_quality",
+                "23",
+                "-look_ahead",
+                "0",
+            ],
+            Self::Vaapi => vec!["-c:v", "h264_vaapi", "-qp", "23"],
+            Self::Nvenc => vec![
+                "-c:v",
+                "h264_nvenc",
+                "-preset",
+                "p4",
+                "-rc",
+                "vbr",
+                "-cq",
+                "23",
+            ],
+            Self::Software => {
+                let mut args = vec!["-c:v", "libx264"];
+                args.extend_from_slice(effort.x264_args());
+                args.extend_from_slice(&["-pix_fmt", "yuv420p"]);
+                args
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests;