@kromatv/sdk 0.1.39-canary.3579809

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

@@ -0,0 +1,225 @@
+use std::collections::HashMap;
+use std::sync::Arc;
+
+use tokio::sync::Mutex;
+
+use super::cut::{from_the_second, Cut};
+use super::key::same_but_the_anchor;
+use super::session::{Session, Sessions};
+
+pub(super) struct Covered {
+    pub(super) key: String,
+    pub(super) session: Arc<Session>,
+    pub(super) playlist: Vec<u8>,
+    pub(super) start: f64,
+}
+
+#[derive(Default)]
+pub(super) struct Serving(Mutex<HashMap<String, String>>);
+
+impl Serving {
+    pub(super) async fn answering(&self, asked: &str) -> Option<String> {
+        self.0.lock().await.get(asked).cloned()
+    }
+
+    pub(super) async fn note(&self, asked: &str, serving: &str) {
+        self.0
+            .lock()
+            .await
+            .insert(asked.to_string(), serving.to_string());
+    }
+
+    pub(super) async fn forget(&self, asked: &str) {
+        self.0.lock().await.remove(asked);
+    }
+
+    pub(super) async fn keep_only(&self, live: &HashMap<String, Arc<Session>>) {
+        self.0
+            .lock()
+            .await
+            .retain(|_, serving| live.contains_key(serving));
+    }
+}
+
+impl Sessions {
+    /// A key that has a session of its own is answered out of it, because that
+    /// is where its segment names are served from. A sibling answers only a key
+    /// with none, and once one has answered it keeps answering: a second ffmpeg
+    /// at this anchor would write the names the viewer is already reading.
+    pub(super) async fn reuse(&self, key: &str, anchor: f64) -> Option<Covered> {
+        if self.inner.lock().await.contains_key(key) {
+            return None;
+        }
+        match self.noted(key, anchor).await {
+            Some(noted) => Some(noted),
+            None => self.covering(key, anchor).await,
+        }
+    }
+
+    async fn noted(&self, key: &str, anchor: f64) -> Option<Covered> {
+        let noted = self.serving.answering(key).await?;
+        let session = self.inner.lock().await.get(&noted).cloned()?;
+        let cut = listed_cut(&session, anchor).await?;
+        Some(covered(noted, session, cut))
+    }
+
+    async fn covering(&self, key: &str, anchor: f64) -> Option<Covered> {
+        let siblings: Vec<(String, Arc<Session>)> = {
+            let map = self.inner.lock().await;
+            map.iter()
+                .filter(|(other, _)| other.as_str() != key && same_but_the_anchor(other, key))
+                .map(|(other, session)| (other.clone(), session.clone()))
+                .collect()
+        };
+        let mut best: Option<Covered> = None;
+        for (other, session) in siblings {
+            if session.start > anchor {
+                continue;
+            }
+            if best
+                .as_ref()
+                .is_some_and(|held| held.session.start >= session.start)
+            {
+                continue;
+            }
+            let Some(cut) = whole_cut(&session, anchor).await else {
+                continue;
+            };
+            best = Some(covered(other, session, cut));
+        }
+        best
+    }
+}
+
+fn covered(key: String, session: Arc<Session>, cut: Cut) -> Covered {
+    Covered {
+        start: session.start + cut.offset,
+        key,
+        session,
+        playlist: cut.playlist.into_bytes(),
+    }
+}
+
+async fn listed_cut(session: &Session, anchor: f64) -> Option<Cut> {
+    let playlist = tokio::fs::read_to_string(session.dir.join("index.m3u8"))
+        .await
+        .ok()?;
+    from_the_second(&playlist, anchor - session.start)
+}
+
+async fn whole_cut(session: &Session, anchor: f64) -> Option<Cut> {
+    let cut = listed_cut(session, anchor).await?;
+    if session.window.is_pruned(cut.sequence) {
+        return None;
+    }
+    tokio::fs::metadata(session.dir.join(&cut.first))
+        .await
+        .ok()?;
+    Some(cut)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::naming::session_dir;
+    use super::super::session::testing::{registry, LIVE, PLAYLIST};
+    use super::*;
+
+    fn produced(sessions: &Sessions, key: &str, playlist: &str) {
+        let dir = sessions.root.join(session_dir(key));
+        std::fs::write(dir.join("index.m3u8"), playlist).expect("the playlist");
+        for name in ["seg_00000.m4s", "seg_00001.m4s", "seg_00002.m4s"] {
+            std::fs::write(dir.join(name), b"x").expect("a segment");
+        }
+    }
+
+    #[tokio::test]
+    async fn a_re_anchor_lands_in_the_session_that_already_produced_that_second() {
+        let (s, _dir) = registry("covered", 8, &[("itA:copy:0:a0", LIVE)]).await;
+        produced(&s, "itA:copy:0:a0", PLAYLIST);
+
+        let covered = s.reuse("itA:copy:12:a0", 12.0).await.expect("the session");
+
+        assert_eq!(covered.key, "itA:copy:0:a0");
+        assert_eq!(covered.start, 12.0);
+    }
+
+    #[tokio::test]
+    async fn a_re_anchor_past_what_any_session_has_produced_starts_its_own() {
+        let (s, _dir) = registry("covered-past", 8, &[("itA:copy:0:a0", LIVE)]).await;
+        produced(&s, "itA:copy:0:a0", PLAYLIST);
+
+        let covered = s.reuse("itA:copy:600:a0", 600.0).await;
+
+        assert!(covered.is_none());
+    }
+
+    #[tokio::test]
+    async fn a_session_producing_another_mode_never_answers_in_its_place() {
+        let (s, _dir) = registry("covered-mode", 8, &[("itA:aac:0:a0", LIVE)]).await;
+        produced(&s, "itA:aac:0:a0", PLAYLIST);
+
+        let covered = s.reuse("itA:copy:12:a0", 12.0).await;
+
+        assert!(covered.is_none());
+    }
+
+    #[tokio::test]
+    async fn a_segment_the_reaper_has_already_taken_is_not_offered_in_its_place() {
+        let (s, _dir) = registry("covered-pruned", 8, &[("itA:copy:0:a0", LIVE)]).await;
+        produced(&s, "itA:copy:0:a0", PLAYLIST);
+        std::fs::remove_file(
+            s.root
+                .join(session_dir("itA:copy:0:a0"))
+                .join("seg_00002.m4s"),
+        )
+        .expect("the swept segment");
+
+        let covered = s.reuse("itA:copy:12:a0", 12.0).await;
+
+        assert!(covered.is_none());
+    }
+
+    #[tokio::test]
+    async fn a_key_that_has_a_session_of_its_own_is_never_answered_by_a_sibling() {
+        let (s, _dir) = registry(
+            "covered-own",
+            8,
+            &[("itA:copy:0:a0", LIVE), ("itA:copy:12:a0", LIVE)],
+        )
+        .await;
+        produced(&s, "itA:copy:0:a0", PLAYLIST);
+        produced(&s, "itA:copy:12:a0", PLAYLIST);
+
+        let reused = s.reuse("itA:copy:12:a0", 12.0).await;
+
+        assert!(reused.is_none());
+    }
+
+    #[tokio::test]
+    async fn a_sibling_already_answering_a_key_answers_it_after_its_first_segment_is_swept() {
+        let (s, _dir) = registry("covered-kept", 8, &[("itA:copy:0:a0", LIVE)]).await;
+        produced(&s, "itA:copy:0:a0", PLAYLIST);
+        s.serving.note("itA:copy:12:a0", "itA:copy:0:a0").await;
+        std::fs::remove_file(
+            s.root
+                .join(session_dir("itA:copy:0:a0"))
+                .join("seg_00002.m4s"),
+        )
+        .expect("the swept segment");
+
+        let again = s.reuse("itA:copy:12:a0", 12.0).await.expect("the sibling");
+
+        assert_eq!(again.key, "itA:copy:0:a0");
+        assert_eq!(again.start, 12.0);
+    }
+
+    #[tokio::test]
+    async fn a_key_answered_by_another_session_is_forgotten_when_that_one_goes() {
+        let serving = Serving::default();
+        serving.note("itA:copy:300:a0", "itA:copy:0:a0").await;
+
+        serving.keep_only(&HashMap::new()).await;
+
+        assert_eq!(serving.answering("itA:copy:300:a0").await, None);
+    }
+}

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

@@ -0,0 +1,114 @@
+use super::naming::seg_index;
+
+pub(super) struct Cut {
+    pub(super) playlist: String,
+    pub(super) first: String,
+    pub(super) sequence: u64,
+    pub(super) offset: f64,
+}
+
+/// `#EXT-X-MEDIA-SEQUENCE` names the first segment kept, which RFC 8216
+/// §4.3.3.2 requires of a playlist that does not begin at sequence zero.
+pub(super) fn from_the_second(playlist: &str, second: f64) -> Option<Cut> {
+    let mut header = String::new();
+    let mut kept = String::new();
+    let mut cut: Option<(String, u64, f64)> = None;
+    let mut spanned = 0.0;
+    let mut span = 0.0;
+    let mut pending = "";
+    for line in playlist.lines() {
+        if let Some(seconds) = line.strip_prefix("#EXTINF:") {
+            span = seconds.trim_end_matches(',').trim().parse().unwrap_or(0.0);
+            pending = line;
+            continue;
+        }
+        if line.starts_with("#EXT-X-ENDLIST") {
+            if cut.is_some() {
+                kept.push_str("#EXT-X-ENDLIST\n");
+            }
+            continue;
+        }
+        if line.is_empty() {
+            continue;
+        }
+        if line.starts_with('#') {
+            if cut.is_none() && !line.starts_with("#EXT-X-MEDIA-SEQUENCE") {
+                header.push_str(line);
+                header.push('\n');
+            }
+            continue;
+        }
+        let name = line.trim();
+        if cut.is_none() && second < spanned + span {
+            cut = Some((name.to_string(), seg_index(name)?, spanned));
+        }
+        if cut.is_some() {
+            kept.push_str(pending);
+            kept.push('\n');
+            kept.push_str(name);
+            kept.push('\n');
+        }
+        spanned += span;
+    }
+    let (first, sequence, offset) = cut?;
+    Some(Cut {
+        playlist: format!("{header}#EXT-X-MEDIA-SEQUENCE:{sequence}\n{kept}"),
+        first,
+        sequence,
+        offset,
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::session::testing::PLAYLIST;
+    use super::*;
+
+    #[test]
+    fn a_playlist_cut_at_a_second_starts_on_the_segment_carrying_it() {
+        let cut = from_the_second(PLAYLIST, 7.0).expect("inside the playlist");
+
+        assert_eq!(cut.first, "seg_00001.m4s");
+        assert_eq!(cut.sequence, 1);
+        assert_eq!(cut.offset, 6.0);
+    }
+
+    #[test]
+    fn a_cut_playlist_keeps_the_header_and_names_where_it_now_begins() {
+        let cut = from_the_second(PLAYLIST, 13.0).expect("inside the playlist");
+
+        assert!(cut.playlist.starts_with("#EXTM3U\n"), "{}", cut.playlist);
+        assert!(cut.playlist.contains("#EXT-X-MAP:URI=\"init.mp4\""));
+        assert!(cut.playlist.contains("#EXT-X-MEDIA-SEQUENCE:2\n"));
+        assert!(!cut.playlist.contains("#EXT-X-MEDIA-SEQUENCE:0"));
+        assert!(!cut.playlist.contains("seg_00001.m4s"));
+        assert_eq!(cut.playlist.matches("#EXTINF:").count(), 1);
+    }
+
+    #[test]
+    fn a_playlist_cut_at_its_own_beginning_is_the_playlist() {
+        let cut = from_the_second(PLAYLIST, 0.0).expect("inside the playlist");
+
+        assert_eq!(cut.offset, 0.0);
+        assert_eq!(cut.playlist.matches("#EXTINF:").count(), 3);
+    }
+
+    #[test]
+    fn a_second_the_playlist_has_not_reached_cuts_nothing() {
+        assert!(from_the_second(PLAYLIST, 16.0).is_none());
+        assert!(from_the_second("#EXTM3U\n", 0.0).is_none());
+    }
+
+    #[test]
+    fn a_finished_playlist_keeps_saying_so_after_the_cut() {
+        let ended = format!("{PLAYLIST}#EXT-X-ENDLIST\n");
+
+        let cut = from_the_second(&ended, 7.0).expect("inside the playlist");
+
+        assert!(
+            cut.playlist.ends_with("#EXT-X-ENDLIST\n"),
+            "{}",
+            cut.playlist
+        );
+    }
+}

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

@@ -0,0 +1,253 @@
+//! The remux process: what is spawned, and the one probe that decides where it
+//! starts. Everything here shells out; nothing here touches the session map.
+
+use std::path::Path;
+use std::process::Stdio;
+
+#[cfg(test)]
+use std::path::PathBuf;
+
+use tokio::process::{Child, Command};
+
+use super::hwaccel::Pipeline;
+use super::naming::contains;
+use super::{StreamMode, VideoMode};
+
+const SEGMENT_SECONDS: u32 = 6;
+/// The write pattern handed to `-hls_segment_filename`; `naming::seg_index`
+/// parses what it produces.
+pub const SEGMENT_PATTERN: &str = "seg_%05d.m4s";
+// Multiple of realtime ffmpeg may read at, so concurrent sessions don't
+// thrash the mount; above 1.0 so clients can still build a forward buffer.
+const READRATE: &str = "2.0";
+// Seconds read at full speed before READRATE throttling starts (ffmpeg >= 6.1).
+const READRATE_BURST: &str = "60";
+
+/// A keyframe every segment, counted from the first frame OUT rather than from
+/// the source clock: a seek runs under `-copyts`, so an expression in absolute
+/// time would force a keyframe on every frame until `n_forced * SEGMENT_SECONDS`
+/// caught up with the anchor.
+///
+/// Left alone, the encoder keys on its own schedule (~10 s at libx264's default
+/// keyint) and the HLS muxer can only cut where it finds one, so segments run
+/// half again as long as the playlist asks for and the first one costs that much
+/// media before anything can be played.
+fn keyframe_cadence() -> String {
+    format!("expr:if(isnan(prev_forced_t),1,gte(t,prev_forced_t+{SEGMENT_SECONDS}))")
+}
+
+/// What `ffmpeg <args>` printed, both streams together because which one carries
+/// the answer varies by build. Empty where ffmpeg could not be run at all.
+pub(super) fn ffmpeg_output(args: &[&str]) -> Vec<u8> {
+    std::process::Command::new("ffmpeg")
+        .args(args)
+        .output()
+        .map(|o| {
+            let mut s = o.stdout;
+            s.extend_from_slice(&o.stderr);
+            s
+        })
+        .unwrap_or_default()
+}
+
+/// `-readrate_initial_burst` only exists from ffmpeg 6.1; older builds get a
+/// plain `-readrate` and a slightly slower first segment.
+pub fn detect_burst() -> bool {
+    contains(
+        &ffmpeg_output(&["-hide_banner", "-h", "full"]),
+        b"readrate_initial_burst",
+    )
+}
+
+/// The keyframe at-or-before `anchor`, which is where the remux really starts
+/// and what the client uses as `baseSec`. Falls back to `anchor` itself where
+/// the container answers nothing.
+///
+/// Read as one frame FROM the anchor, not a scan of the window before it: the
+/// demuxer's seek is the seek `-ss` will make, so the first frame handed back is
+/// the answer, and a scan would demux every byte of that window instead.
+pub async fn keyframe_before(input: &Path, anchor: f64) -> f64 {
+    if anchor <= 0.5 {
+        return 0.0;
+    }
+    let out = Command::new("ffprobe")
+        .args([
+            "-v",
+            "error",
+            "-select_streams",
+            "v:0",
+            "-skip_frame",
+            "nokey",
+        ])
+        .arg("-read_intervals")
+        .arg(format!("{anchor:.3}%+#1"))
+        .args(["-show_entries", "frame=pts_time", "-of", "csv=p=0"])
+        .arg(input)
+        .output()
+        .await;
+    let Ok(out) = out else {
+        return anchor;
+    };
+    String::from_utf8_lossy(&out.stdout)
+        .lines()
+        .filter_map(|l| l.trim().trim_end_matches(',').parse::<f64>().ok())
+        .filter(|t| *t <= anchor + 0.01)
+        .fold(None, |best: Option<f64>, t| {
+            Some(best.map_or(t, |b| b.max(t)))
+        })
+        .unwrap_or(anchor)
+}
+
+// The selected audio track is MUXED into one media playlist rather than exposed as
+// an alternate rendition: hls.js keeps playing rendition 0 regardless of selection.
+// A language switch is therefore a reload with a different `audio` (a new session).
+pub fn spawn_stream(
+    input: &Path,
+    dir: &Path,
+    audio: u32,
+    mode: StreamMode,
+    start_secs: f64,
+    burst: bool,
+    pipeline: Pipeline,
+) -> std::io::Result<Child> {
+    let seeking = start_secs > 0.5;
+    let copying_video = matches!(mode.video, VideoMode::Copy);
+    let mut cmd = Command::new("ffmpeg");
+    cmd.args(["-v", "error", "-nostdin"]);
+    // `-threads` lands on the DECODER here (before `-i`): a remux never decodes
+    // video, so a pool is pure overhead - but a transcode does, and one thread
+    // cannot keep a 4K source ahead of the player.
+    if copying_video {
+        cmd.args(["-threads", "1"]);
+    } else {
+        // Puts the decode on the device too where there is one, so a 4K source
+        // never touches the CPU on its way to a 1080p screen.
+        cmd.args(pipeline.accel.input_args(pipeline.effort));
+    }
+    if seeking {
+        // Required for A/V sync: an accurate seek backs the video to a keyframe but
+        // decodes-and-discards audio to the exact `-ss`, starting it a GOP late.
+        cmd.arg("-noaccurate_seek")
+            .arg("-ss")
+            .arg(format!("{start_secs:.3}"));
+    }
+    // Input option: must come before `-i`.
+    cmd.args(["-readrate", READRATE]);
+    if burst {
+        cmd.args(["-readrate_initial_burst", READRATE_BURST]);
+    }
+    cmd.arg("-i").arg(input);
+    if seeking {
+        cmd.arg("-copyts"); // keep source timestamps so video + audio stay on one timeline
+    }
+    cmd.args(["-map", "0:v:0"])
+        .arg("-map")
+        .arg(format!("0:a:{audio}"));
+    if copying_video {
+        cmd.args(["-c:v", "copy"]);
+    } else {
+        // The picture only shrinks when the client said its decoder needs it to;
+        // the filter runs in whatever memory the device decoded into.
+        if let Some(filter) = pipeline
+            .accel
+            .video_filter(mode.video.box_size(), pipeline.effort)
+        {
+            cmd.arg("-vf").arg(filter);
+        }
+        // 8-bit H.264 whatever the device, because the re-encode exists for
+        // decoders the source defeats and must land on the one profile every
+        // target reads. HDR sources are not tone-mapped (no zimg) and come out
+        // washed-out.
+        cmd.args(pipeline.accel.encoder_args(pipeline.effort));
+        cmd.arg("-force_key_frames").arg(keyframe_cadence());
+    }
+    if mode.audio.transcode() {
+        if let Some(af) = mode.audio.filter_chain() {
+            cmd.args(["-af", af]);
+        }
+        cmd.args(["-c:a", "aac", "-ac", "2", "-b:a", "192k"]);
+    } else {
+        cmd.args(["-c:a", "copy"]);
+    }
+    // A second is fine-grained enough for a dashboard and cheap enough that a
+    // two-hour session's log is about a megabyte, inside the directory the
+    // reclaim sweep takes away with the rest of it.
+    cmd.arg("-progress")
+        .arg(dir.join(super::progress::FILE))
+        .args(["-stats_period", "1"]);
+    let hls_time = SEGMENT_SECONDS.to_string();
+    cmd.args(["-f", "hls", "-hls_time", hls_time.as_str()])
+        .args(["-hls_playlist_type", "event"])
+        .args(["-hls_segment_type", "fmp4"])
+        .args(["-hls_fmp4_init_filename", "init.mp4"])
+        .arg("-hls_segment_filename")
+        .arg(dir.join(SEGMENT_PATTERN))
+        .args(["-hls_flags", "independent_segments+temp_file"])
+        .arg(dir.join("index.m3u8"))
+        .stdin(Stdio::null())
+        .stdout(Stdio::null())
+        .kill_on_drop(true);
+    match std::fs::File::create(dir.join("ffmpeg.log")) {
+        Ok(f) => {
+            cmd.stderr(Stdio::from(f));
+        }
+        Err(_) => {
+            cmd.stderr(Stdio::null());
+        }
+    }
+    cmd.spawn()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn clip(dir: &Path) -> Option<PathBuf> {
+        let path = dir.join("clip.mp4");
+        std::process::Command::new("ffmpeg")
+            .args(["-v", "error", "-f", "lavfi", "-i"])
+            .arg("testsrc=duration=20:size=64x48:rate=25")
+            .args(["-c:v", "libx264", "-g", "50", "-y"])
+            .arg(&path)
+            .status()
+            .ok()?
+            .success()
+            .then_some(path)
+    }
+
+    #[tokio::test]
+    async fn a_seek_starts_on_the_keyframe_at_or_before_the_second_asked_for() {
+        let dir = kroma_testing::temp_dir("hls-keyframe");
+        let Some(path) = clip(dir.path()) else {
+            return;
+        };
+
+        let start = keyframe_before(&path, 11.0).await;
+
+        assert!((start - 10.0).abs() < 0.05, "{start}");
+    }
+
+    #[tokio::test]
+    async fn a_second_the_container_cannot_answer_for_keeps_the_anchor() {
+        let start = keyframe_before(Path::new("http://127.0.0.1:1/clip.mp4"), 42.0).await;
+
+        assert_eq!(start, 42.0);
+    }
+
+    #[test]
+    fn the_keyframe_cadence_is_measured_from_the_first_frame_out() {
+        let expr = keyframe_cadence();
+
+        assert!(expr.contains("prev_forced_t"), "{expr}");
+        assert!(expr.contains("isnan"), "{expr}");
+        // Never `n_forced * 6`: under `-copyts` a seek starts the output at the
+        // anchor, and an expression in absolute time forces a keyframe on every
+        // frame until the count has caught up with it.
+        assert!(!expr.contains("n_forced"), "{expr}");
+    }
+
+    #[test]
+    fn a_keyframe_lands_on_every_segment_boundary() {
+        assert!(keyframe_cadence().contains(&format!("+{SEGMENT_SECONDS})")));
+    }
+}