Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion doc/bin/hls.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ support the publisher's codecs.

What that means for you:

- **The publisher declares the interval.** Only a broadcast whose catalog carries `media.join.interval` gets playlists. Rust publishers built on `moq-mux` (the CLI, the RTMP, SRT, and WebRTC gateways, and the native bindings) declare it: an encoder that knows its GOP passes it as a hint, and an ingest without one measures each track over its first second or group, whichever is longer, then declares the longest. `@moq/publish` declares its encoders' `join`.
- **The publisher declares the interval.** Only a broadcast whose catalog carries `media.join.interval` gets playlists. Rust publishers built on `moq-mux` (the CLI, the RTMP, SRT, and WebRTC gateways, and the native bindings) declare it: an encoder that knows its GOP passes it as a hint, and an ingest without one measures each track over its first second or group, whichever is longer, then declares the longest. `@moq/publish` declares its encoders' `join`. A `moq-transcode` derivative declares its source's, since its rungs cut where the source does.
- **Every rendition shares the grid.** A group spans from its first frame's timestamp to the next group's and belongs to the first grid line it contains, or, containing none, the line it starts after. Segment N therefore starts at the group containing N times the segment length, every rendition numbers its segments alike, and each cuts its boundaries at its own keyframes. A grid line no group starts a segment at, because a GOP ran past it or the content paused, is listed as an `EXT-X-GAP` so the numbering never skips: on a 2 s grid, a GOP from 0 to 7 s is segment 0, segments 1 and 2 are gaps, and the next GOP starts segment 3. Timestamps that go back start a discontinuity on that rendition alone; `EXT-X-PROGRAM-DATE-TIME`, written after every discontinuity when the catalog has a clock, lets players resync.
- **Include media starts on selection.** The HTTP multivariant playlist reads each root `include` entry's catalog and lists its audio and video beside the broadcast's own. An include shares the broadcast's timeline: its renditions are segmented on the broadcast's join interval and clock, whatever its own catalog declares, so publish it on the same timestamps. One not yet routed is listed once its broadcast is announced. Reading its catalog starts no encoding: only a request to one of its rendition URLs subscribes to that rendition's media. Demand lasts through active responses and, after the last one finishes, for three target durations or the playlist window plus one target duration, whichever is longer (20 s by default); a later request starts it again. The broadcast's own renditions stay subscribed. A segment is servable for as long as the relay's [cache](/bin/relay/config#cache) retains it. Keep `--window` (the playlist length, default 16 s) within that retention and within the media's max age (30 s by default), after which a superseded segment's groups are stale.
- **Live joins cost the window.** The exporter subscribes 30 s behind the live edge and lists at most 256 segments. One joining partway through a segment lists nothing before the first segment it sees start.
Expand Down
32 changes: 21 additions & 11 deletions rs/moq-transcode/src/catalog.rs
Original file line number Diff line number Diff line change
Expand Up @@ -371,16 +371,17 @@ pub(crate) fn populate(
out.video.insert(&published.rung.name, published.entry.clone())?;
}

let Some(rel) = source_rel else {
return Ok(());
};

// The source's renditions are listed too, and they promise only the source's join interval,
// so the derivative joins on it unless its own tracks already declared one. Fixed once set.
// Every rung mirrors the source's groups one for one, so it promises the source's join
// interval, and nothing else measures one for tracks written group by group. An HLS export
// numbers segments on it, so the rungs share the source's segment numbers. Fixed once set.
if out.media.join.is_none() {
out.media.join = source.media.join;
}

let Some(rel) = source_rel else {
return Ok(());
};

for (name, config) in &source.video.renditions {
if config.broadcast.is_some() {
// Already a reference into another broadcast; composing relative
Expand Down Expand Up @@ -1007,19 +1008,28 @@ mod tests {
assert_eq!(out.media.clock, Some(clock), "a derivative keeps the child's clock");
}

/// A derivative listing the source's renditions joins on the source's interval, unless its own
/// tracks already declared one; one listing only its rungs declares its own.
/// A derivative joins on the source's interval, whether it lists only its rungs or the source's
/// renditions too, and keeps the first one declared.
#[test]
fn populate_carries_the_source_interval_with_its_renditions() {
fn populate_carries_the_source_interval() {
let interval = |secs| hang::catalog::Join::new(std::time::Duration::from_secs(secs));
let mut child = moq_mux::catalog::hang::Catalog::<()>::default();
child.media.join = interval(4);
let rel = Relative::new(".").unwrap();

// The source declares its interval only once it has measured one.
let mut out = moq_mux::catalog::hang::Catalog::<()>::default();
populate(&mut out, &child, &[], None).unwrap();
assert_eq!(out.media.join, None, "only rungs: the derivative measures its own");
assert_eq!(out.media.join, None, "nothing to promise yet");

child.media.join = interval(4);
populate(&mut out, &child, &[], None).unwrap();
assert_eq!(
out.media.join,
interval(4),
"only rungs: they cut where the source does"
);

let mut out = moq_mux::catalog::hang::Catalog::<()>::default();
populate(&mut out, &child, &[], Some(&rel)).unwrap();
assert_eq!(out.media.join, interval(4));

Expand Down