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 @@ -58,7 +58,7 @@ What that means for you:
- **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.
- **Segments are timed by the grid.** A segment is listed once a later one starts or the track ends. It starts at its first group's timestamp, or at its line when that group starts after it (as one resuming from a pause does), or a gap at its line, and lasts until the next segment starts, so a segment's bytes never change with a catalog estimate. A GOP longer than the segment is listed at its first line, so its duration understates its media.
- **Segments are timed by the grid.** A segment is listed once a later one starts or the track ends. A GOP that starts off a line is placed as soon as one of its frames passes the next line, without waiting for the next keyframe, so the segment before it lists then. A keyframe may overlap the previous GOP's last frames (a TS content join does), so when that overlap straddles a line, an edge that saw the earlier GOP lists it in the line's segment, while an edge that joined at the overlapping keyframe lists that segment without it. This one segment differs across edges, for that broadcast only (accepted, 2026-11-15). It starts at its first group's timestamp, or at its line when that group starts after it (as one resuming from a pause does), or a gap at its line, and lasts until the next segment starts, so a segment's bytes never change with a catalog estimate. A GOP longer than the segment is listed at its first line, so its duration understates its media.
- **The target duration is twice the segment.** Every media playlist keeps one `EXT-X-TARGETDURATION` while its rendition stays in the catalog, even across a reconfigure: twice the segment length, rounded up to whole seconds (twice the interval for a GOP of a second or more, 2 s for 20 ms audio groups), since the GOP containing a grid line starts at most one interval before it, and a gap ends under two segment lengths after its line. Only a final GOP longer than that is listed past it, against RFC 8216's rule: hls.js plays it, but Apple's `mediastreamvalidator` flags it, so keep keyframe intervals within the declared interval.
- **A reconfigure keeps the playlist.** A rendition whose decoder config changes (its resolution, say) keeps its media playlist: the segments already listed stay, under the init they were muxed for, and the new config's segments follow behind an `EXT-X-DISCONTINUITY` and a new `EXT-X-MAP`, as RFC 8216 requires. The old config's segments end at the keyframe declaring the new size, even when that group reaches the export before the catalog update. A resize that opens a segment lists that segment under the new init. One partway through a segment cuts the old config's last segment short there, and the new config lists from the next segment, so the media between them is never listed. The DASH manifest lists only the new config's segments.
- **Disabled renditions are hidden.** A rendition the catalog marks `enabled: false` leaves the multivariant playlist and DASH manifest until it re-enables. Its media playlist keeps serving, so a player already on it is not ended with `EXT-X-ENDLIST`.
Expand Down
59 changes: 0 additions & 59 deletions quest/m3/hls-listing-lag.md

This file was deleted.

90 changes: 82 additions & 8 deletions rs/moq-hls/src/export/grid.rs
Original file line number Diff line number Diff line change
Expand Up @@ -9,12 +9,19 @@
//!
//! A group spans from its first frame's pts to the next group's. It belongs to one segment: the
//! first line it contains, so segment N starts at the group containing pts N × length; or, if it
//! contains none, the line it starts after, `floor(pts / length)`. Groups are never split, since a
//! segment starting mid-GOP is not independent. A grid slot no group starts a segment in, because
//! an overrun or a pause skipped it, is listed as a gap, so the numbering never skips: on a 2s grid,
//! a group A = [0s, 7s) is segment 0, slots 1 and 2 are gaps, and a contiguous B = [7s, 7.2s)
//! starts segment 3. An edge joining at B derives that from B's and its successor's timestamps,
//! without A.
//! contains none, the line it starts after, `floor(pts / length)`. A group off the grid is placed
//! once its successor starts, or sooner once one of its own frames passes the next line, since it
//! then contains that line unless its successor overlaps it; the segment before it completes then,
//! not a group later. A keyframe may overlap the previous group's last frames (a TS content join
//! does), so when that overlap straddles a line, an edge that saw the earlier group lists it in the
//! line's segment while one that joined at the overlapping group lists that segment without it.
//! That one segment differs across edges, for that broadcast alone (accepted by the maintainer,
//! 2026-11-15, for listing every off-grid segment up to a group sooner). Groups are never split,
//! since a segment starting mid-GOP is not independent. A grid slot no group starts a
//! segment in, because an overrun or a pause skipped it, is listed as a gap, so the numbering never
//! skips: on a 2s grid, a group A = [0s, 7s) is segment 0, slots 1 and 2 are gaps, and a contiguous
//! B = [7s, 7.2s) starts segment 3. An edge joining at B derives that from B's and its successor's
//! timestamps, without A.
//!
//! A segment starts at its first group's pts, or at its line when that group starts after it, as
//! a group resuming from a pause does, and a gap at its line; its `EXTINF` runs to the next
Expand Down Expand Up @@ -139,7 +146,8 @@ pub(crate) enum Slot {
Reset,
}

/// A group seen but not yet placed: placing it needs its end, the next group's pts.
/// A group seen but not yet placed: placing it needs its end, the next group's pts, unless one of
/// its frames passes the next line first.
#[derive(Clone, Copy, Debug)]
struct Group {
start: u64,
Expand Down Expand Up @@ -171,7 +179,7 @@ impl Open {
pub(crate) struct Grid {
/// The segment length in nanoseconds, at least one.
length: u128,
/// The newest group, until the next one bounds it.
/// The newest group, until the next one bounds it or a frame past the next line places it.
pending: Option<Group>,
open: Option<Open>,
/// The newest group's pts, which the next must not precede.
Expand Down Expand Up @@ -295,6 +303,29 @@ impl Grid {
out
}

/// A frame of the newest group starts at `pts`. Once that is past the line after the group's
/// start, the group contains the line, so it is placed in that line's segment now rather than
/// when its successor starts: the same segment its successor's pts would give it, which starts
/// after all of its frames. Returns the segments it completes.
pub fn reach(&mut self, pts: Timestamp) -> Vec<Slot> {
let mut out = Vec::new();
let Some(pending) = self.pending else {
return out;
};
let slot = super::nanos(pending.pts) / self.length;
if super::nanos(pts) > (slot + 1) * self.length {
self.pending = None;
self.place(pending, slot as u64 + 1, &mut out);
}
out
}

/// Whether the newest group waits for its end to be placed, which [`reach`](Self::reach) may
/// settle early.
pub fn pending(&self) -> bool {
self.pending.is_some()
}

/// A discontinuity marker at `at` stopped the content: the newest group ends there rather than
/// where the next group starts. Returns the segments it completes.
pub fn stop(&mut self, at: Timestamp) -> Vec<Slot> {
Expand Down Expand Up @@ -611,7 +642,21 @@ mod test {
slots.extend(grid.group(sequence as u64, ms(*start)));
}
slots.extend(grid.finish(Some(ms(end - 1)), Some(ms(end))));
// Frames read before the next group starts, in any order, list the same
// segments, only sooner.
let mut early = Grid::new(Duration::from_millis(length), 256);
let mut early_slots = Vec::new();
for (sequence, start) in starts.iter().enumerate().skip(join) {
early_slots.extend(early.group(sequence as u64, ms(*start)));
let until = starts.get(sequence + 1).copied().unwrap_or(end);
for _ in 0..3 {
early_slots.extend(early.reach(ms(start + next(until - start))));
}
}
early_slots.extend(early.finish(Some(ms(end - 1)), Some(ms(end))));
let early = listed(early_slots);
let listed = listed(slots);
assert_eq!(early, listed, "{interval} ms: {starts:?}");
for (index, (segment, _, start, end)) in listed.iter().enumerate() {
let extinf = end - start;
let fits = ((extinf as f64) / 1_000.0).round() as u64 <= target;
Expand Down Expand Up @@ -656,6 +701,35 @@ mod test {
[(1, 2..3, 2000, 3500)],
"3.5s reaches 4s"
);

// A frame past the next line settles the newest group without its successor.
let mut grid = Grid::new(Duration::from_secs(2), 256);
assert!(grid.group(0, ms(500)).is_empty());
assert!(
grid.reach(ms(1900)).is_empty(),
"short of the line, it may still end before it"
);
assert!(
grid.reach(ms(2000)).is_empty(),
"its successor may still start on the line"
);
assert!(
grid.reach(ms(2033)).is_empty(),
"it opens segment 1, which nothing completes yet"
);
assert!(!grid.pending());
assert!(grid.group(1, ms(2500)).is_empty());
assert_eq!(
listed(grid.reach(ms(4100))),
[(1, 0..1, 500, 2500)],
"listed at 4.1s rather than when group 2 starts at 4.5s"
);
assert!(grid.reach(ms(4200)).is_empty(), "already placed");
assert!(grid.group(2, ms(4500)).is_empty());
assert_eq!(
listed(grid.finish(Some(ms(5000)), Some(ms(5000)))),
[(2, 1..3, 2500, 5000)]
);
}

/// A long pause lists only the newest gaps, the ones a playlist window can still hold.
Expand Down
65 changes: 65 additions & 0 deletions rs/moq-hls/src/export/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -4014,6 +4014,71 @@ mod tests {
assert!(test.drain_failed("video0").await.is_empty());
}

// A live segment lists once a frame of the group after it passes the next line, not once the
// group after that starts: off the grid, that is a whole GOP sooner.
#[tokio::test(start_paused = true)]
async fn a_segment_lists_once_the_next_group_passes_its_line() {
let test = Groups::with(&["video0"], &[]);
let mut video0 = test.publish("video0");
let frame = |group: &mut moq_net::group::Producer, pts_ms: u64| {
let frame = vp8_frame(pts_ms * 1_000, false);
hang::container::Frame {
timestamp: frame.timestamp,
payload: frame.payload,
}
.write_to(group)
.unwrap();
};
// Group 0 holds line 2s, so it is segment 1; group 1 may still end before line 4s.
video0.at(0, 500);
let mut next = video0.open(1, 2_500);
frame(&mut next, 3_900);
kio::clock::sleep(Duration::from_secs(1)).await;
assert!(
test.rendition("video0").snapshot().segments.is_empty(),
"group 1 may still end before 4s and join segment 1"
);

frame(&mut next, 4_100);
let snapshot = test.listed("video0", 1).await;
let listed: Vec<_> = snapshot.segments.iter().map(|s| (s.segment, s.duration)).collect();
assert_eq!(listed, [(1, Duration::from_millis(2_000))], "group 2 never started");
drop(next);

// A CMAF group carried whole in one fragment passes the line in its first frame.
let muxer = moq_mux::container::fmp4::Muxer::video(&video_config()).unwrap();
let mut config = video_config();
config.container = hang::catalog::Container::Cmaf {
init: muxer.init().unwrap().expect("a VP8 init from the coded size"),
};
let mut catalog = joined();
catalog.media.join = hang::catalog::Join::new(INTERVAL);
catalog.video.renditions.insert("video0".to_string(), config);
let broadcast = moq_net::broadcast::Info::new().produce();
let test = Groups {
renditions: Groups::export(&broadcast, &catalog),
broadcast,
catalog,
};
let track = test.broadcast.create_track("video0", timed()).unwrap();
// Samples 100ms apart from `pts_ms` up to `last_ms`, in one fragment.
let fragment = |sequence: u64, pts_ms: u64, last_ms: u64| {
let frames: Vec<_> = (pts_ms..=last_ms)
.step_by(100)
.map(|ms| vp8_frame(ms * 1_000, ms == pts_ms))
.collect();
let mut group = track.create_group(moq_net::group::Info { start: sequence }).unwrap();
let bytes = muxer.fragment(sequence as u32, &frames, None).unwrap();
group.write_frame(frames[0].timestamp, bytes).unwrap();
group.close().unwrap();
};
fragment(0, 500, 2_400);
fragment(1, 2_500, 4_400);
let snapshot = test.listed("video0", 1).await;
let listed: Vec<_> = snapshot.segments.iter().map(|s| (s.segment, s.duration)).collect();
assert_eq!(listed, [(1, Duration::from_millis(2_000))], "group 2 never started");
}

// A recording refuses a listed segment whose media is gone, but reports a grid slot the
// rendition holds nothing for (after an overrun) as a gap that keeps its number, so a recorder
// can tell it from rows it missed.
Expand Down
Loading