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 @@ -56,7 +56,7 @@ support the publisher's codecs.
What that means for you:

- **The publisher declares the interval.** Only a broadcast whose catalog carries `sync.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.
- **Every rendition shares the grid.** A group spans from its start 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. 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.
Expand Down
9 changes: 5 additions & 4 deletions drafts/draft-lcurley-moq-hang.md
Original file line number Diff line number Diff line change
Expand Up @@ -654,7 +654,7 @@ A second group would present a gap as if it were a complete log; ending the trac

A consumer MUST NOT skip to the newest group, since a later group does not supersede an earlier one the way a `snapshot` group does.
It reads the one group the track carries, and MUST fail the read if the track carries a second, since whatever would have completed the first group is gone and yielding the remainder would present that gap as a continuous log.
This is why a consumer takes groups in arrival order rather than by ascending sequence: groups are separate streams, so a second group MAY arrive with a lower sequence than the first, and skipping it would report a truncated log as a whole one.
This is why a consumer takes groups in arrival order rather than by ascending start: groups are separate streams, so a second group MAY arrive with a lower start than the first, and skipping it would report a truncated log as a whole one.

A consumer MUST NOT wait for the first group to end before it looks for a second.
A publisher that opens a second group while the first is still open is broken in exactly the way this rule exists to catch, and a consumer that only checks at the group boundary waits forever on a group that publisher may never finish.
Expand Down Expand Up @@ -914,11 +914,11 @@ A consumer MUST NOT submit the marker to a decoder.
Empty groups (zero objects) are permitted and mean nothing.
After a discontinuity the timeline continues forward.
A publisher that stops producing and may resume on the same track (e.g. an encoder idle for lack of demand) SHOULD publish a discontinuity marker when it stops, so the group before the pause does not reach across the gap and read as live.
The first timestamp of a group MUST NOT be lower than the first timestamp of any group with a lower sequence, and no frame of a group may be lower than the first timestamp of the group before it; a group that breaks either is malformed.
The first timestamp of a group MUST NOT be lower than the first timestamp of any group with a lower start, and no frame of a group may be lower than the first timestamp of the group before it; a group that breaks either is malformed.
A group MAY start at the same timestamp as the previous group.
Frames MAY present below the previous group's content (B-frames, or a keyframe overlapping the previous group's last frame).
A publisher whose source restarts below the previous group's start begins a new broadcast instead.
A delivered sequence hole is a playhead event unless the boundary is contiguous within 1 ms.
A hole between delivered groups is a playhead event unless the publisher declared the starts between them skipped or the boundary is contiguous within 1 ms.
A consumer re-applies startup delay and skip at a playhead event; it does not reset codec state.

## legacy
Expand Down Expand Up @@ -982,7 +982,7 @@ The grid draws a line at every multiple of that segment length in presentation t
An edge derives the length from the interval alone, so every edge agrees.
A broadcast without `sync.interval` is not served as HLS or DASH.

A group spans from its first frame's timestamp to the next group's.
A group spans from its start to the next group's start, or from its first frame's timestamp where the track has no timescale.
It belongs to one segment: the first line it contains, so segment N starts at the group containing N times the segment length, or, when it contains none, the line it starts after.
A segment holds whole groups, since one starting mid-group is not independent.
Every rendition numbers its segments on the one grid, so they share segment numbers while each cuts its boundaries at its own groups.
Expand Down Expand Up @@ -1046,6 +1046,7 @@ This document has no IANA actions.
## moq-hang-04
{:numbered="false"}

- An HLS or DASH edge places a group on the segment grid by its start rather than its first frame's timestamp, and a hole between groups whose skipped starts the publisher declared is no playhead event.
- A reader refuses a JSON frame in which an object repeats a member name.
- A catalog update takes effect at its frame's timestamp on the media timeline, not when a consumer reads it, and a publisher keeps superseded catalog groups as fresh as its media's for consumers behind the live edge; an untimed catalog track's updates apply on arrival.
- Removed `catalog.json.z` and the data track `compression` field: compression is a track property the transport carries ({{compression}}), so each compressed track is one name, and the catalog, `stats` and `echo` snapshots, and JSON data tracks SHOULD be compressed.
Expand Down
87 changes: 87 additions & 0 deletions js/hang/src/container/consumer.nonsequential.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -174,3 +174,90 @@ test("Consumer reads one-packet Opus groups at sparse sequences back to back", a
track.finish();
track.close();
});

// A track at hang's microsecond timescale, whose groups are keyed by their start timestamps.
function micro(): Track.Producer {
return new Track.Producer("test").accept({ timescale: Time.Timescale.MICRO, maxAge: null });
}

// Groups keyed by their start timestamps are never consecutive integers. Appending declares the starts
// between them skipped, so a slow head the age skip passes is no loss when the next group follows it,
// even where frames carry no duration to prove the timeline unbroken.
test("Consumer reads on without a gap past an aged group the publisher's skips follow", async () => {
const track = micro();
const consumer = new Consumer(track.subscribe(), {
format: new LegacyFormat("data"),
delay: { max: Duration.millis(500) },
});
const append = (timestamps: number[]) => {
const group = track.appendGroup(Time.Timestamp.fromMicros(timestamps[0]));
for (const timestamp of timestamps) {
group.writeFrame({
payload: encodeLegacyFrame(timestamp, new Uint8Array([0x01])),
timestamp: Time.Timestamp.fromMicros(timestamp),
});
}
return group;
};

const first = append([0, 100_000, 200_000, 300_000, 400_000]);
for (let i = 0; i < 5; i++) expect((await nextFrame(consumer))?.group).toBe(0n);
first.finish();
await clock.advance(Duration.ZERO);
// Far past the first group's last frame, and past the age bound, so the age skip passes it.
append([1_000_000, 2_000_000]).finish();
await clock.advance(Duration.ZERO);
expect(await poll(consumer.next())).toMatchObject({ kind: "frame", group: 1_000_000n });

consumer.close();
track.finish();
track.close();
});

// A buffered range runs across group boundaries wherever nothing lies between: the starts between were
// declared skipped, or the next group starts where the media before it ends.
test("Consumer buffers groups at sparse starts as one range", async () => {
const opus = AudioConfigSchema.parse({
codec: "opus",
container: { kind: "legacy" },
sampleRate: 48_000,
numberOfChannels: 2,
});
const packet = new Uint8Array([31 << 3, 0]);
for (const [name, format, create] of [
// No duration: only the declared skips prove nothing is missing.
[
"declared",
new LegacyFormat("data"),
(track: Track.Producer, start: number) => track.appendGroup(Time.Timestamp.fromMicros(start)),
],
// Nothing declared: each 20 ms packet ends where the next group starts.
[
"contiguous",
new LegacyFormat(opus),
(track: Track.Producer, start: number) => track.createGroup(BigInt(start)),
],
] as const) {
const track = micro();
const delay = { min: Duration.millis(100), max: Duration.millis(5000) };
// Reaching back past the first group, so the start keeps every one.
const consumer = new Consumer(track.subscribe({ delay }), { format, delay });
for (const start of [0, 20_000, 40_000]) {
const group = create(track, start);
group.writeFrame({
payload: encodeLegacyFrame(start, packet),
timestamp: Time.Timestamp.fromMicros(start),
});
group.finish();
}
await clock.advance(Duration.ZERO);
expect(
consumer.buffered.peek().map((range) => [range.start.asMicros(), range.end.asMicros()]),
name,
).toEqual([[0, 40_000]]);

consumer.close();
track.finish();
track.close();
}
});
Loading