diff --git a/dart/moq/lib/src/aliases.dart b/dart/moq/lib/src/aliases.dart index 3a488d7368d..cbf8f275bde 100644 --- a/dart/moq/lib/src/aliases.dart +++ b/dart/moq/lib/src/aliases.dart @@ -170,9 +170,12 @@ extension type Timestamp._(MoqTimestamp _timestamp) implements MoqTimestamp { /// How far behind the live edge a subscriber or decoder plays: where it starts, and how late it may fall. extension type Delay._(MoqDelay _delay) implements MoqDelay { - /// `min` is the target latency and where a cold join starts, and `max` is how far a - /// non-latest group may fall behind before it is skipped. Both default to zero, moq-net's - /// default. An explicit null `min` leaves it unstated, which a decoder plays as zero, and an + /// `min` is the target latency, where a cold join starts, and how long a decoder waits for a + /// missing group, and `max` is how far a non-latest group may fall behind before it is skipped. + /// Both default to zero, moq-net's default. An explicit null `min` leaves it unstated, which a + /// decoder starts as zero, waiting a missing group for `max` instead (an audio decoder floors it + /// at zero and waits only its playout estimate, which can be larger; a catalog warmup or an audio + /// decoder's playout delay still states a `min` to the publisher), and an /// explicit null `max` sets no subscriber limit. A `min` past `max` starts at `max`. Delay({Duration? min = Duration.zero, Duration? max = Duration.zero}) : this._(MoqDelay(min: min, max: max)); diff --git a/doc/concept/audio-jitter.md b/doc/concept/audio-jitter.md index e572ab997e1..25d058302e4 100644 --- a/doc/concept/audio-jitter.md +++ b/doc/concept/audio-jitter.md @@ -46,8 +46,8 @@ Natively that holds only as far as the caller lets it. The container consumer reads groups in sequence order and applies its age budget inside `read()`, so a group skipped for age is never observed, and a frame queued behind a stalled group is observed when the stall clears. A missing group, one that has delivered -no frame, is waited for only the playout delay plus any lookahead, since past that -it would play late: a reordered backlog's holes waited out to the whole budget +no frame, is waited for only the playout delay, the subscription's `delay.min`, +since past that it would play late: a reordered backlog's holes waited out to the whole budget would delay the frames behind them, which the estimator would measure as jitter. The browser player waits less still, only until the group past the hole trails its clock by the stretch threshold, past which the ring would skip the diff --git a/go/wrapper/records.go b/go/wrapper/records.go index 9b0743272c8..1aab965a857 100644 --- a/go/wrapper/records.go +++ b/go/wrapper/records.go @@ -76,11 +76,15 @@ type DatagramInfo = ffi.MoqDatagramInfo // starts at the newest group and skips a superseded group at once. type Delay struct { // Min is the target latency: the playout or jitter-buffer delay held behind the live edge, - // and where a cold join starts. A Min past Max starts at Max, since the publisher serves - // nothing older. moq-lite-07 sends it upstream. + // where a cold join starts, and how long a decoder waits for a missing group. A Min past Max + // starts and waits at Max, since the publisher serves nothing older. moq-lite-07 sends it + // upstream. Min time.Duration - // MinUnstated leaves Min unstated, ignoring it. A decoder plays it as zero, while the - // subscription keeps it unstated, so it never pulls the aggregate across subscribers to zero. + // MinUnstated leaves Min unstated, ignoring it. A decoder starts it as zero and waits a + // missing group for Max (an audio decoder floors it at zero and waits only its playout + // estimate, which can be larger), while the subscription keeps it unstated, so it never + // pulls the aggregate across subscribers to zero, unless a catalog warmup or an audio + // decoder's playout delay states one. MinUnstated bool // Max is how far a non-latest group may fall behind the live edge before it is skipped. Zero // skips immediately; a larger value tolerates that much reordering. It caps every range, diff --git a/js/hang/api/container.api.md b/js/hang/api/container.api.md index 352ed965642..6438d36ea00 100644 --- a/js/hang/api/container.api.md +++ b/js/hang/api/container.api.md @@ -28,7 +28,6 @@ export interface ConsumerProps { format: Format; playhead?: Playhead; predecessor?: Consumer; - wait?: Signals.GetterInit; warmup?: Net.Clock.Duration; } diff --git a/js/hang/src/container/consumer.backlog.test.ts b/js/hang/src/container/consumer.backlog.test.ts index 3a3a3709466..6202f742375 100644 --- a/js/hang/src/container/consumer.backlog.test.ts +++ b/js/hang/src/container/consumer.backlog.test.ts @@ -33,8 +33,7 @@ async function play(events: Event[], backlog: (group: number) => boolean): Promi const track = new Track.Producer("audio"); const consumer = new Consumer(track.subscribe({ delay: { max: Duration.millis(2000) } }), { format: new Format("audio"), - delay: { max: Duration.millis(2000) }, - wait: Duration.millis(100), + delay: { min: Duration.millis(100), max: Duration.millis(2000) }, }); const oracle = new Jitter(); const base = now().since(Instant.ZERO).asMillis(); @@ -149,8 +148,7 @@ test("the join's boundary is the publisher's answer, not a group that raced it", }); const consumer = new Consumer(raced, { format: new Format("audio"), - delay: { max: Duration.millis(2000) }, - wait: Duration.millis(100), + delay: { min: Duration.millis(100), max: Duration.millis(2000) }, }); const write = (sequence: number, media: number) => { const group = track.createGroup(BigInt(sequence)); @@ -209,7 +207,6 @@ test("the join's boundary is the publisher's answer, not the largest by the firs const consumer = new Consumer(raced, { format: new Format("audio"), delay: { max: Duration.millis(2000) }, - wait: Duration.millis(100), }); const write = (sequence: number, media: number) => { const group = track.createGroup(BigInt(sequence)); diff --git a/js/hang/src/container/consumer.holes.test.ts b/js/hang/src/container/consumer.holes.test.ts index 523004d0ecd..b6e8bd0e40e 100644 --- a/js/hang/src/container/consumer.holes.test.ts +++ b/js/hang/src/container/consumer.holes.test.ts @@ -14,7 +14,7 @@ test.each([0, 100])("a sequence hole before a paused data marker expires at %sms const track = new Track.Producer("data"); const consumer = new Consumer(track.subscribe({ delay: { max: Duration.millis(30_000) } }), { format: new Format("data"), - delay: { max: Duration.millis(budget) }, + delay: { min: null, max: Duration.millis(budget) }, }); const results: Read[] = []; const reading = (async () => { @@ -66,7 +66,7 @@ test("a filled hole cancels its timer and the next hole gets a fresh budget", as const track = new Track.Producer("data"); const consumer = new Consumer(track.subscribe({ delay: { max: Duration.millis(30_000) } }), { format: new Format("data"), - delay: { max: Duration.millis(100) }, + delay: { min: null, max: Duration.millis(100) }, }); const results: Read[] = []; const reading = (async () => { @@ -124,7 +124,7 @@ test("the holes a stalled source left behind share one budget", async () => { const track = new Track.Producer("data"); const consumer = new Consumer(track.subscribe({ delay: { max: Duration.millis(30_000) } }), { format: new Format("data"), - delay: { max: Duration.millis(100) }, + delay: { min: null, max: Duration.millis(100) }, }); const results: Read[] = []; const reading = (async () => { @@ -168,7 +168,7 @@ test("a hole is late from the earliest arrival past it", async () => { const track = new Track.Producer("data"); const consumer = new Consumer(track.subscribe({ delay: { max: Duration.millis(30_000) } }), { format: new Format("data"), - delay: { max: Duration.millis(100) }, + delay: { min: null, max: Duration.millis(100) }, }); const results: Read[] = []; const reading = (async () => { @@ -275,7 +275,7 @@ test.each([true, false])("the head after a declared end is waited for (arrives: const track = new Track.Producer("audio"); const consumer = new Consumer(track.subscribe({ delay: { max: Duration.millis(30_000) } }), { format: new Format("audio"), - delay: { max: Duration.millis(300) }, + delay: { min: null, max: Duration.millis(300) }, }); const results: Read[] = []; const reading = (async () => { @@ -355,7 +355,7 @@ test("a newest-first flush past a hole delivers the groups landing behind its ne const track = new Track.Producer("audio"); const consumer = new Consumer(track.subscribe({ delay: { max: Duration.millis(30_000) } }), { format: new Format("audio"), - delay: { max: Duration.millis(80) }, + delay: { min: null, max: Duration.millis(80) }, }); const results: Read[] = []; const reading = (async () => { @@ -408,8 +408,7 @@ test("a hole is waited for the wait while an arrived group plays up to the max d const track = new Track.Producer("audio"); const consumer = new Consumer(track.subscribe({ delay: { max: Duration.millis(30_000) } }), { format: new Format("audio"), - delay: { max: Duration.millis(1000) }, - wait: Duration.millis(100), + delay: { min: Duration.millis(100), max: Duration.millis(1000) }, }); const results: Read[] = []; const reading = (async () => { @@ -497,8 +496,7 @@ test.each([ const track = new Track.Producer("audio"); const consumer = new Consumer(track.subscribe({ delay: { max: Duration.millis(30_000) } }), { format: new Format("audio"), - delay: { max: Duration.millis(2_000) }, - wait: Duration.millis(500), + delay: { min: Duration.millis(500), max: Duration.millis(2_000) }, playhead, }); const results: Read[] = []; @@ -549,8 +547,7 @@ test("a hole ends once the playout clock jumps past the group past it", async () const track = new Track.Producer("audio"); const consumer = new Consumer(track.subscribe({ delay: { max: Duration.millis(30_000) } }), { format: new Format("audio"), - delay: { max: Duration.millis(2_000) }, - wait: Duration.millis(500), + delay: { min: Duration.millis(500), max: Duration.millis(2_000) }, playhead: { now: () => position, anchor }, }); const results: Read[] = []; diff --git a/js/hang/src/container/consumer.nonsequential.test.ts b/js/hang/src/container/consumer.nonsequential.test.ts index 54d145e19fc..cce3350b1d0 100644 --- a/js/hang/src/container/consumer.nonsequential.test.ts +++ b/js/hang/src/container/consumer.nonsequential.test.ts @@ -60,7 +60,7 @@ test("Consumer waits on a non-sequential hang group because it has no per-frame const track = new Track.Producer("test"); const consumer = new Consumer(track.subscribe(), { format: new LegacyFormat("data"), - delay: { max: Duration.millis(5000) }, + delay: { min: null, max: Duration.millis(5000) }, }); // Group A at a large sequence, completed so the cursor advances past it. @@ -149,7 +149,7 @@ test("Consumer reads one-packet Opus groups at sparse sequences back to back", a }); const consumer = new Consumer(track.subscribe(), { format: new LegacyFormat(config), - delay: { max: Duration.millis(5000) }, + delay: { min: null, max: Duration.millis(5000) }, }); // One 20 ms CELT packet per group, each read before the next lands. The group starting at 40 ms // never arrives. diff --git a/js/hang/src/container/consumer.outoforder.test.ts b/js/hang/src/container/consumer.outoforder.test.ts index 208e8920de6..e20ab70d2de 100644 --- a/js/hang/src/container/consumer.outoforder.test.ts +++ b/js/hang/src/container/consumer.outoforder.test.ts @@ -86,7 +86,7 @@ test("the head of the window arriving after the live edge is delivered first", a subscriber.start = async () => 10n; const consumer = new Consumer(subscriber, { format: new LegacyFormat("data"), - delay: { max: Duration.millis(5000) }, + delay: { min: null, max: Duration.millis(5000) }, }); // The live edge lands first, and delivery waits for the floor rather than starting there. diff --git a/js/hang/src/container/consumer.skips.test.ts b/js/hang/src/container/consumer.skips.test.ts index 821e10da6d0..b4bf2c25c93 100644 --- a/js/hang/src/container/consumer.skips.test.ts +++ b/js/hang/src/container/consumer.skips.test.ts @@ -195,7 +195,7 @@ test("a blocking group is kept until its successor starts a budget behind the ne const track = new Track.Producer("tone"); const consumer = new Consumer(track.subscribe({ delay: { max: Duration.millis(30_000) } }), { format: new Format("data"), - delay: { max: Duration.millis(150) }, + delay: { min: null, max: Duration.millis(150) }, }); const write = (sequence: bigint, timestamp: number) => { const group = track.createGroup(sequence); diff --git a/js/hang/src/container/consumer.startup.test.ts b/js/hang/src/container/consumer.startup.test.ts index 6a340d6ec60..024d1d8f5ba 100644 --- a/js/hang/src/container/consumer.startup.test.ts +++ b/js/hang/src/container/consumer.startup.test.ts @@ -13,7 +13,7 @@ function setup(maxDelay = 100) { const track = new Track.Producer("video"); const consumer = new Consumer(track.subscribe({ delay: { max: Duration.millis(30_000) } }), { format: new Format("video"), - delay: { max: Duration.millis(maxDelay) }, + delay: { min: null, max: Duration.millis(maxDelay) }, }); const results: Read[] = []; const warn = spyOn(console, "warn").mockImplementation(() => {}); diff --git a/js/hang/src/container/consumer.test.ts b/js/hang/src/container/consumer.test.ts index 2aef91023af..c89a62a1798 100644 --- a/js/hang/src/container/consumer.test.ts +++ b/js/hang/src/container/consumer.test.ts @@ -1781,7 +1781,7 @@ test("Consumer waits on a PTS gap instead of skipping to a later buffered group const track = new Track.Producer("test"); const consumer = new Consumer(replay(track), { format: timedLegacy, - delay: { max: Duration.millis(10_000) }, + delay: { min: null, max: Duration.millis(10_000) }, }); // Group A (seq 1_000_000): content ends at 33_333µs. @@ -1873,7 +1873,7 @@ test("Consumer plays the head once a waited-out gap exceeds the budget (Legacy)" const track = new Track.Producer("test"); const consumer = new Consumer(replay(track), { format: timedLegacy, - delay: { max: Duration.millis(100) }, + delay: { min: null, max: Duration.millis(100) }, }); // A (seq 1000): one frame, ends at 3000 ticks (33_333µs). @@ -1908,7 +1908,7 @@ test("Consumer waits on a gap within the budget, then plays the head once it exc const track = new Track.Producer("test"); const consumer = new Consumer(replay(track), { format: timedLegacy, - delay: { max: Duration.millis(100) }, + delay: { min: null, max: Duration.millis(100) }, }); // A (seq 1000): one frame, ends at 3000 ticks (33_333µs). diff --git a/js/hang/src/container/consumer.ts b/js/hang/src/container/consumer.ts index f6101021181..ea361469e86 100644 --- a/js/hang/src/container/consumer.ts +++ b/js/hang/src/container/consumer.ts @@ -20,9 +20,13 @@ export interface ConsumerProps { * * The start is the group covering the live edge less `min`, plus any {@link ConsumerProps.warmup}, waiting * for it when the newest group arrives first; an unstated (`null`) `min` reads as zero. A `min` - * past `max` starts at `max`, since the publisher serves nothing older. `max` is measured as - * the span from the oldest buffered frame to the newest, so it bounds how long a late group is - * waited for, and a missing one unless {@link ConsumerProps.wait} is shorter. It is the local + * past `max` starts at `max`, since the publisher serves nothing older. A missing group is waited + * for `min`, the reader's own buffer, since past it the group would play late, or for `max` when + * `min` is `null`, never longer than `max`. The wait expires this much monotonic time after the + * first group past it arrived, even when that group is a marker on a paused track, or sooner once + * where that group begins falls `max` behind the newest content. `max` is measured as + * the span from the oldest buffered frame to the newest, so it bounds how long a late group that + * did arrive is waited for, letting a player catch up on late media its holes skipped past. It is the local * half of the subscription's `delay.max`; both measure the same budget, one on the wire and one * as frames are read. It bounds a join's lateness too: a backlog that landed before the first * read starts at the first group whose first frame is within it, plus any warmup, of the @@ -31,16 +35,6 @@ export interface ConsumerProps { */ // Read-only: a Getter (e.g. another component's output) is accepted directly. delay?: GetterInit; - /** - * How long a missing group is waited for before the consumer skips past it, at most `delay.max` - * (default: `delay.max`). It expires this much monotonic time after the first group past it - * arrived, even when that group is a marker on a paused track, or sooner once where that group - * begins falls `delay.max` behind the newest content. Groups that did arrive still play until they age past - * `delay.max`, so a player can wait on holes for its playout delay alone while still receiving - * the late media it catches up on. - */ - // Read-only: a Getter (e.g. another component's output) is accepted directly. - wait?: GetterInit; /** * Cap the bytes of decoded frames held ahead of the reader, counting the whole wire payload they * share and each frame's and group's own overhead (default: one group at the transport's size @@ -84,7 +78,7 @@ export interface ConsumerProps { * The playout clock this reader feeds, such as the player's `Sync` (default: none). A missing * group whose successor starts at or before the oldest media the clock still plays could only * arrive too late to play, so it is skipped then rather than waited for: a reader resuming behind - * the live edge moves on once the clock passes the hole, not a whole {@link ConsumerProps.wait} later. + * the live edge moves on once the clock passes the hole, not a whole `delay.min` later. */ playhead?: Playhead; } @@ -205,7 +199,6 @@ export class Consumer { #track: Moq.Track.Subscriber; #format: Format; #delay: Getter; - #wait: Getter; #playhead?: Playhead; #maxBuffer: number; // How much further than the min delay the start reaches, and the age skip tolerates while warming. @@ -296,7 +289,6 @@ export class Consumer { this.#track = track; this.#format = props.format; this.#delay = getter(props.delay ?? {}); - this.#wait = getter(props.wait); this.#playhead = props.playhead; this.#maxBuffer = props.maxBuffer ?? DEFAULT_MAX_BUFFER; this.#warmup = (props.warmup ?? Duration.ZERO).min(DELAY_MAX); @@ -941,7 +933,7 @@ export class Consumer { this.#track.isSkipped(this.#active, head.consumer.start) || ptsContiguous(this.#presentedEnd, head.frames.at(0)?.timestamp.asMicros()); const empty = head.empty && head.consumer.done; - const wait = this.#holeWait(this.#delay.peek(), this.#wait.peek()); + const wait = this.#holeWait(this.#delay.peek()); const bound = this.#bound(); const edge = this.#liveEdge(); // Measured against the max delay, not the wait: a reader starved of CPU takes in a burst of @@ -1073,8 +1065,7 @@ export class Consumer { // A clock that jumps moves when it reaches the group past a hole. if (this.#playhead) effect.get(this.#playhead.anchor); // The start waits out its reach, and a hole the wait, which an unlimited one never does. - const budget = - starting === undefined ? this.#holeWait(delay, effect.get(this.#wait)) : this.#reach(delay); + const budget = starting === undefined ? this.#holeWait(delay) : this.#reach(delay); let left = Number.isFinite(budget) ? Duration.micros(budget).saturatingSub(now().since(since)) : undefined; @@ -1114,10 +1105,11 @@ export class Consumer { return Math.max(0, bound - playhead); } - // How long a missing group is waited for, in microseconds: the wait, at most the max delay. - #holeWait(delay: Moq.Track.Delay, wait: Duration | undefined): number { + // How long a missing group is waited for, in microseconds: the min delay, the reader's own buffer, + // or the max delay when the min is unstated, at most the max delay. Mirrors Rust's `hole_wait`. + #holeWait(delay: Moq.Track.Delay): number { const max = maxMicros(delay); - return wait === undefined ? max : Math.min(wait.asMicros(), max); + return delay.min === null ? max : Math.min(delay.min?.asMicros() ?? 0, max); } // How far behind the live edge the start reaches, in microseconds: the min delay plus the warmup. diff --git a/js/net/src/track.ts b/js/net/src/track.ts index ad1a0149b68..1c5ea22ddb9 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -308,8 +308,10 @@ export interface Range { export interface Delay { /** * The target latency, the playout or jitter-buffer delay held behind the live edge. Omitted - * means `0`; `null` means not stated, which only a peer whose wire cannot carry it (moq-lite - * before 07, moq-transport) sends. A media consumer reads an unstated minimum as `0`. + * means `0`; `null` means not stated, which a peer whose wire cannot carry it (moq-lite + * before 07, moq-transport) sends. A media consumer also waits this long for a missing group, + * since past it the group would play late, and starts an unstated minimum as `0` but waits a + * missing group for {@link Delay.max} instead. * * A live join, `{ start: { relative: 0n } }` with no end, starts this far behind the live edge: * at the newest group that began at or before the live edge minus this, so a player's buffer diff --git a/js/watch/src/audio/decoder.ts b/js/watch/src/audio/decoder.ts index 84409af017c..e17fb475dca 100644 --- a/js/watch/src/audio/decoder.ts +++ b/js/watch/src/audio/decoder.ts @@ -370,8 +370,8 @@ export class Decoder { // estimate rising one bucket at a time. The container // consumer drops aged media at the same max delay, since it observes each frame before applying // it, and carves out the warmup the subscription adds once it has warmed, as Rust's does. It waits - // on a missing group only for the delay plus the lookahead: past that the group would play late, - // and a reordered backlog's holes waited out to the max would read as jitter to the estimator. + // on a missing group only for the delay, its min: past that the group would play late, and a + // reordered backlog's holes waited out to the max would read as jitter to the estimator. // See doc/concept/audio-jitter.md. #runSubscribeMaxDelay(effect: Effect): void { const budget = this.#budget(effect); @@ -951,7 +951,6 @@ export class Decoder { const consumer = new Container.Consumer(sub, { format, delay: this.#delay, - wait: this.sync.out.maxDelay, warmup: Duration.millis(config.warmup ?? 0).min(DELAY_MAX), predecessor: continues ? outgoing.consumer : undefined, playhead: playable(this.sync, this.#output), diff --git a/js/watch/src/audio/replay.ts b/js/watch/src/audio/replay.ts index fcc98ceac75..c059501b774 100644 --- a/js/watch/src/audio/replay.ts +++ b/js/watch/src/audio/replay.ts @@ -258,7 +258,6 @@ export async function* replay(trace: Arrival[], options: Options): AsyncGenerato { format: new Container.Legacy.Format("audio"), delay: new Derived([sync.out.delay, maxDelay], (min, max) => ({ min, max })), - wait: sync.out.maxDelay, playhead: playable(sync), }, ); diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt index c2e33504612..cc2eff6c594 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt @@ -216,9 +216,12 @@ typealias RouteInfo = uniffi.moq.MoqRouteInfo typealias Subscription = uniffi.moq.MoqSubscription /** - * How far behind the live edge a subscriber or decoder plays: `min` is the target latency and where - * a cold join starts, null to leave it unstated (a decoder plays it as zero), and `max`, null for - * no subscriber limit, is how far a non-latest group may fall behind before it is skipped. A `min` + * How far behind the live edge a subscriber or decoder plays: `min` is the target latency, where a + * cold join starts, and how long a decoder waits for a missing group, null to leave it unstated (a + * decoder starts it as zero and waits a missing group for `max`, except an audio decoder, which + * floors it at zero and waits only its playout estimate, which can be larger; a catalog warmup or + * an audio decoder's playout delay still states a `min` to the publisher), and `max`, null for no + * subscriber limit, is how far a non-latest group may fall behind before it is skipped. A `min` * past `max` starts at `max`. */ typealias Delay = uniffi.moq.MoqDelay diff --git a/py/moq-rs/moq/_records.py b/py/moq-rs/moq/_records.py index 36702a24c8f..c35fb6007f6 100644 --- a/py/moq-rs/moq/_records.py +++ b/py/moq-rs/moq/_records.py @@ -228,9 +228,12 @@ class Delay: """How far behind the live edge a subscriber or decoder plays, mirroring moq-net's ``track::Delay``. ``min`` is the target latency: the playout or jitter-buffer delay held behind the - live edge, and where a cold join starts. ``None`` leaves it unstated, which a decoder - plays as zero while the subscription keeps it unstated, so it never pulls the - aggregate across subscribers to zero. A ``min`` past ``max`` starts at ``max``. + live edge, where a cold join starts, and how long a decoder waits for a missing group. + ``None`` leaves it unstated, which a decoder starts as zero, waiting a missing group for + ``max`` instead (an audio decoder floors it at zero and waits only its playout estimate, + which can be larger), while the subscription keeps it unstated, so it never pulls the + aggregate across subscribers to zero, unless a catalog warmup or an audio decoder's + playout delay states one. A ``min`` past ``max`` starts at ``max``. ``max`` is how far a non-latest group may fall behind before it is skipped; zero skips at once, ``None`` sets no subscriber limit and leaves the publisher's max age alone to bound it, and it caps every range. diff --git a/quest/m1/export-delay-wire.md b/quest/m1/export-delay-wire.md index 27893f0f9b6..29f24c7c3c3 100644 --- a/quest/m1/export-delay-wire.md +++ b/quest/m1/export-delay-wire.md @@ -64,4 +64,3 @@ Caused by, for the fix PR's `## Caused by`: ## Related - [Export order](/quest/m3/export-order.md) - the drain after an outage, the rest of the loss in #8559 -- [A hole is waited for by the subscription's delay](/quest/m2/delay-hole-wait.md) - makes the consumer's hole wait follow `Delay::min`, which this sets diff --git a/quest/m2/README.md b/quest/m2/README.md index e016b269b8f..9c5049998b5 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -46,8 +46,7 @@ removal, a rename, or a wire, catalog, or format change that is free until (the `sync` section, a version per entry, no video `warmup`, `m2ts` under `mpegts`, one strict rule); [declared ends](/quest/m2/time-addressing/consumers.md), back from m3. -- **Native media and gateways.** [The video producer](/quest/m2/video-producer.md), - [the hole wait](/quest/m2/delay-hole-wait.md), and +- **Native media and gateways.** [The video producer](/quest/m2/video-producer.md) and [upstream str0m](https://github.com/moq-dev/moq/pull/8963), which reverses the 2026-10-30 vendoring. - **Bindings.** The C API as `libmoq` (done), reversing 2026-10-25. diff --git a/quest/m2/audio-playout/browser-audio-hole-skip.md b/quest/m2/audio-playout/browser-audio-hole-skip.md index e1f8ac7c76c..94a78d40555 100644 --- a/quest/m2/audio-playout/browser-audio-hole-skip.md +++ b/quest/m2/audio-playout/browser-audio-hole-skip.md @@ -69,5 +69,4 @@ Work: ## Related -- [A hole is waited for by the subscription's delay](/quest/m2/delay-hole-wait.md) - settles the wait rule this moves into the transport - [moq-net's last pub items with a single container-reader caller go private](/quest/m2/unused-api/net.md) - the Rust container reader moving onto `Gap`, this quest's native counterpart diff --git a/quest/m2/delay-hole-wait.md b/quest/m2/delay-hole-wait.md deleted file mode 100644 index d57368f874d..00000000000 --- a/quest/m2/delay-hole-wait.md +++ /dev/null @@ -1,90 +0,0 @@ -# [M] A hole is waited for by the subscription's delay, with no third knob - -## Goal - -The container consumer has no separate hole wait: `set_wait` in -`moq_mux::container::Consumer` and `ConsumerProps.wait` in `@moq/hang` are -gone. A missing group is waited for the subscription's stated `Delay::min`, -or `Delay::max` when no minimum is stated, in Rust and JS alike. A native -audio player whose playout delay is a live estimate still skips a hole once -that delay has passed, as it does today. - -## Plan - -Decided 2026-11-16 (maintainer, /quest-plan of the pre-cut audit): - -- ✅ Fold the hole wait into `Delay` (rejected: keep `set_wait` as a third - delay knob and stop calling it a duplicate; drop it with no replacement - rule). `Delay { min, max }` already says how far behind live the reader - plays and how late a group stays useful; a third duration set through a - setter is one more thing each player has to keep in step. - -Facts found by the audit: - -- `set_wait` (`rs/moq-mux/src/container/consumer.rs:1381`) caps the wait at - the max delay (`:840`). Its one production caller is native audio, which - refreshes it before every poll with `self.delay()` - (`rs/moq-audio/src/decode/consumer.rs:598`), the live jitter estimate when - `Options::estimate` is on (`:339`). So the [API review](/quest/m3/release/api-review.md)'s - note that native audio "sets it to the `min` it already passes" is not - always true, and a plain delete regresses - [moq-dev/moq#8531](https://github.com/moq-dev/moq/pull/8531). -- JS mirrors the knob as `ConsumerProps.wait` - (`js/hang/src/container/consumer.ts:43`), passed by two callers, both as - `sync.out.maxDelay` (`js/watch/src/audio/decoder.ts:921`, - `js/watch/src/audio/replay.ts:260`). -- Three days after #8531, - [moq-dev/moq#8799](https://github.com/moq-dev/moq/pull/8799) gave the JS - consumer the player's clock (`playhead`): a hole ends when the clock - reaches the group past it. The clock already trails live by the estimate, - so it carries the moving value the wait was added for. - -- The Rust consumer has the clock too - (`moq_mux::container::Consumer::set_playhead`), and `moq play` gives it to - video only. Given to native audio it measured worse than the estimate wait - (`just test audio-quality --runtimes native --codecs opus --duration 40 - --seed 7`): ending a hole at the clock cost `bursty` 155 underruns a minute - against 3, since a late burst's successor is already due when the missing - group lands a moment later; ending it at the clock plus the 200 ms stretch - held `bursty` and `mild` level, but over three runs each `congestion` ran - 1714 to 1925 underruns a minute against 1307 to 1767 without it, and an A/V - lag p95 of 808 to 946 ms against 288 to 631 ms. The estimate wait gives - every hole the estimate from the arrival of the group past it, which a late - burst needs. -- Browser audio ends a hole once the group past it trails the clock by the - ring's stretch bound, the furthest the ring plays late audio - ([moq-dev/moq#8982](https://github.com/moq-dev/moq/pull/8982)): the - variant that lost natively on `congestion`. In the browser it graded no - worse than the bare clock or the wait alone on the Chromium `bursty` and - `congestion` rows, and the replays show the bare clock skipping holes a - burst fills 1 ms later. The estimate wait alone (no clock) left the Firefox - resume window silent longer (9 to 41 samples against 6 to 12). - -For the PR, settle the home of native audio's live estimate first. Two ways: - -1. The playhead is the home: the clock ends a hole, and the static rule - (`min`, else `max`) is only the fallback for a reader with no clock. The - measurements above count against it for audio unless a variant beats the - estimate wait on `bursty` and `congestion`. Prove any variant by deleting - the `set_wait` call and running #8531's regression tests - (`rs/moq-mux/src/container/consumer.rs:2161`, `:2308`, `:2369` and - moq-audio's reorder tests) with the playhead in place, plus those rows. -2. moq-audio writes its estimate into the subscription's `Delay::min` as it - moves. `min` is Subscriber Min Age on the lite-07 wire, so each change is - a SUBSCRIBE_UPDATE, and since a cold join reaches back by it - it would also move where a join starts. Take this only with a coarse step - and a measured update rate, and say why the playhead did not do. - -Then delete the setter and the prop, apply the one rule in both languages, -and update the consumer docs that name the wait -(`rs/moq-mux/src/container/consumer.rs:74`, the `ConsumerProps` docs). If -neither way keeps #8531's behaviour, report it on the PR before keeping the -knob: the maintainer rejected that end state. - -Public API: `moq-mux` loses `container::Consumer::set_wait`; `@moq/hang` -loses `ConsumerProps.wait`. Wire: none. - -## Related - -- [Native audio playout is a library](/quest/m3/audio-playout-library.md) - moves the placement this wait feeds into moq-audio -- [Browser audio takes its holes from the ordered reader](/quest/m2/audio-playout/browser-audio-hole-skip.md) - moves the browser audio hole rule this settles into `@moq/net`'s ordered reader diff --git a/quest/m2/unused-api/net.md b/quest/m2/unused-api/net.md index 246c9978c0e..d26237a297f 100644 --- a/quest/m2/unused-api/net.md +++ b/quest/m2/unused-api/net.md @@ -15,13 +15,12 @@ without a caller. Findings (2026-11-17, from reading the code when this quest was claimed as `[S]`): moving the reader onto `Gap` is not an `Ordered` swap, so the quest -is `[L]` and waits for the hole wait to settle. +is `[L]`. - `moq-mux`'s `container::Consumer` reads in arrival order (`poll_recv_group`) into its own `pending` queue and judges a hole at `current` while the groups past it are already buffered: the wall-time wait - since a later group arrived (`hole_wait`, which - [the hole wait quest](/quest/m2/delay-hole-wait.md) turns into + since a later group arrived (`hole_wait`, now `Delay::min`), media-timestamp `aged` against the newest buffered content, the playout clock `passed`, a full max buffer, and container continuity (`poll_continues`, 1 ms contiguity). @@ -75,10 +74,6 @@ Steps: Public API: breaking, removals only unless step 1 adds `Ordered` inputs. Wire: none. -## Required - -- [A hole is waited for by the subscription's delay](/quest/m2/delay-hole-wait.md) - the one hole wait the reader judges holes by, which this designs `Ordered`'s policy around - ## Related - [Browser audio holes](/quest/m2/audio-playout/browser-audio-hole-skip.md) - the browser counterpart of the reader moving onto `Gap` diff --git a/quest/m3/release/api-review.md b/quest/m3/release/api-review.md index 9042a95fd00..9e82f86892e 100644 --- a/quest/m3/release/api-review.md +++ b/quest/m3/release/api-review.md @@ -68,10 +68,8 @@ re-read this list, so it is settled: stay: both have callers (the first pass's claim fell on a re-read). - The byte-stream rung of `MoqMediaProducer`'s simulcast ladder stays: removing it changes `lower`'s type in every binding again. -- `moq_mux`'s `set_wait` folds into `Delay` - ([the hole wait](/quest/m2/delay-hole-wait.md)). The first pass was wrong - that native audio sets it to the `min` it already passes: it passes its - live estimate, which that quest gives a home. +- `moq_mux`'s `set_wait` folded into `Delay`: a hole is waited for + `Delay::min`, and native audio states its live estimate there. - `Rendition::applied()` and `moq_video::encode::Applied` stay: the media sweep found moq.pro's transcode bench reading them. moq-sock's ICMP error queue and `qmux::Config::fixed_receive_window` went in the transport sweep, diff --git a/rs/hang/examples/subscribe.rs b/rs/hang/examples/subscribe.rs index c174a8970a4..382b7e14dae 100644 --- a/rs/hang/examples/subscribe.rs +++ b/rs/hang/examples/subscribe.rs @@ -123,14 +123,15 @@ async fn play(broadcast: moq_net::broadcast::Consumer) -> anyhow::Result<()> { "subscribing to video track" ); - // Subscribe to the video track. + // Subscribe to the video track. No min delay, since this plays nothing out: a missing group is + // waited for the whole latency budget. let latency = Duration::from_millis(500); let track_consumer = broadcast .track(hang::catalog::Reference::track(config, name))? .subscribe( moq_net::track::Subscription::default() .with_priority(1) - .with_delay(moq_net::track::Delay::default().with_max(latency)), + .with_delay(moq_net::track::Delay::default().with_min(None).with_max(latency)), ) .await?; let mut ordered = diff --git a/rs/libmoq/src/api.rs b/rs/libmoq/src/api.rs index 407baf96288..5d7413aec03 100644 --- a/rs/libmoq/src/api.rs +++ b/rs/libmoq/src/api.rs @@ -800,9 +800,9 @@ pub enum moq_demand { #[derive(Clone, Copy, Default)] pub struct moq_delay { /// The target latency in microseconds: the playout or jitter-buffer delay held behind - /// the live edge, and where a cold join starts. moq-lite-07 sends it upstream. A - /// `min_us` past the max starts at the max, since the publisher serves nothing older. - /// Ignored when `min_unstated` is set. + /// the live edge, where a cold join starts, and how long a media consumer waits for a + /// missing group. moq-lite-07 sends it upstream. A `min_us` past the max starts and waits + /// at the max, since the publisher serves nothing older. Ignored when `min_unstated` is set. pub min_us: u64, /// How far a non-latest group may fall behind the live edge before it is skipped, in /// microseconds. Zero skips immediately. Enforced by the publisher's cache and by any @@ -811,8 +811,11 @@ pub struct moq_delay { pub max_us: u64, /// No subscriber max: wait on a stalled group as long as the publisher's max age allows. pub max_unlimited: bool, - /// Leave the minimum unstated. A media consumer plays it as zero, while the subscription - /// keeps it unstated, so it never pulls the aggregate across subscribers to zero. + /// Leave the minimum unstated. A media consumer starts it as zero and waits a missing group + /// for the max instead (an audio decoder floors it at zero and waits only its playout + /// estimate, which can be larger), while the subscription keeps it unstated, so it never + /// pulls the aggregate across subscribers to zero, unless a catalog warmup or an audio + /// decoder's playout delay states one. pub min_unstated: bool, } diff --git a/rs/moq-audio/src/decode/consumer.rs b/rs/moq-audio/src/decode/consumer.rs index 381e5a2b467..219980dbc81 100644 --- a/rs/moq-audio/src/decode/consumer.rs +++ b/rs/moq-audio/src/decode/consumer.rs @@ -83,8 +83,9 @@ pub struct Options { /// /// [`Delay::min`] is the playout delay: the jitter buffer a player holds ahead of the /// playhead, reported by [`Consumer::delay`], and where a cold join starts. With - /// [`estimate`](Self::estimate) it is a floor under the measured delay instead. A `min` - /// beyond the track's max age is refused. [`Delay::max`] is how far a group may fall + /// [`estimate`](Self::estimate) it is a floor under the measured delay instead. The + /// subscription states whichever delay the player holds as its min, following the estimate, + /// so a missing group is waited for that long. A `min` beyond the track's max age is refused. [`Delay::max`] is how far a group may fall /// behind the live edge before the subscription skips it; it adds no buffering. pub delay: Delay, /// Measure the playout delay from arrival timing, never below [`Delay::min`] (default: @@ -168,6 +169,9 @@ pub struct Consumer { terminal_start: Option, /// The playout delay, fixed or estimated from arrivals. target: Target, + /// The playout delay the subscription states as its [`Delay::min`] in place of + /// [`Options::delay`]'s. + stated: Duration, /// Where arrival times are measured from. origin: Instant, /// Packets read and observed but not yet decoded, held by the [`Backpressure`] gate, @@ -193,6 +197,11 @@ struct ActivitySpan { activity: Activity, } +/// A target in `f64` milliseconds as a [`Duration`]. +fn from_millis(millis: f64) -> Duration { + Duration::from_secs_f64(millis / 1000.0) +} + impl Consumer { /// Subscribe to `name` in `broadcast`, using the catalog entry to pick the /// codec. @@ -223,7 +232,12 @@ impl Consumer { let name = name.into(); let warmup = catalog.warmup.unwrap_or_default().min(moq_mux::container::DELAY_MAX); - let playout = moq_mux::container::Playout::new(options.delay, warmup); + let target = Target::new(options.delay.min.unwrap_or_default(), options.estimate, catalog.jitter); + // The subscription states the playout delay as its min from the start, the estimate's cold + // start included: the container places an unfloored start and waits a missing group out + // by it (see `next`). + let stated = from_millis(target.millis()); + let playout = moq_mux::container::Playout::new(options.delay.with_min(stated), warmup); let track = broadcast.track(hang::catalog::Reference::track(catalog, &name))?; // The whole delay from the start, as the container keeps it: the transport enforces the // max too, so a narrower one while joining would drop the groups queued behind a reader @@ -271,7 +285,8 @@ impl Consumer { let track = playout.consumer(track, container); Ok(Self { - target: Target::new(delay, options.estimate, catalog.jitter), + target, + stated, decoder, track, resampler: None, @@ -329,7 +344,7 @@ impl Consumer { /// behind it, as `moq play` keeps it at the delay plus its time stretch. pub fn set_max_delay(&mut self, max: std::time::Duration) { self.options.delay = self.options.delay.with_max(max); - self.track.set_delay(self.options.delay); + self.track.set_delay(self.stated()); self.max_delay = max.min(self.max_age.unwrap_or(std::time::Duration::MAX)); } @@ -341,7 +356,12 @@ impl Consumer { /// frame is handled and let the playback buffer absorb the jitter, rather than /// pacing reads to the speaker. pub fn delay(&self) -> Duration { - Duration::from_secs_f64(self.target.millis() / 1000.0) + from_millis(self.target.millis()) + } + + // The delay the subscription carries: the options', with the playout delay as the min. + fn stated(&self) -> Delay { + self.options.delay.with_min(self.stated) } /// Sample rate samples are actually delivered at, which is @@ -606,11 +626,15 @@ impl Consumer { /// that arrives meanwhile, or `None` once the track ends. async fn next(&mut self) -> Result, Error> { loop { - // A missing group is waited for only the playout delay, since past it the group - // would play late, and a reordered backlog's holes waited out to the max delay - // would read as jitter. Late groups that did arrive still play up to the max. - // Refreshed before every poll, since each arrival and each decoded frame can move it. - self.track.set_wait(self.delay()); + // The container waits a missing group out for the subscription's min, so it states the + // playout delay: past it the group would play late, and a reordered backlog's holes + // waited out to the max delay would read as jitter. Late groups that did arrive still + // play up to the max. Checked before every poll, since each arrival and each decoded + // frame can move it; the estimate moves in whole buckets, so each move is one update. + if self.stated != self.delay() { + self.stated = self.delay(); + self.track.set_delay(self.stated()); + } // Read before judging the head, so any update after that wakes the wait. let seen = self.gate.as_ref().map_or(0, |gate| gate.read().version); let deadline = match self.pending.front() { @@ -2886,16 +2910,18 @@ mod tests { /// Write `events`, `(arrival, group, media)` in ms in arrival order, through the whole /// decode path, one PCM packet per group, reading each one `read` admits as it lands. - /// Returns the delay once they have all landed, and whether the container reported a + /// The publisher answers that its feed starts at the first event's group, as a session's + /// does. Returns the delay once they have all landed, and whether the container reported a /// backlog. async fn play(events: &[(u64, u64, u64)], read: impl Fn(u64) -> bool) -> (f64, bool) { use moq_mux::container::Container as _; let catalog = hang::catalog::AudioConfig::new(hang::catalog::AudioCodec::Pcm, 8_000, 1); let broadcast = moq_net::broadcast::Info::new().produce(); - let track = broadcast + let mut track = broadcast .create_track("audio", hang::container::track_info(hang::catalog::PRIORITY.audio)) .unwrap(); + track.start_at(events[0].1).unwrap(); let subscriber = broadcast.consume(); // The estimate's 2 s ceiling past the delay, as `moq play` subscribes. let options = Options { @@ -2995,6 +3021,177 @@ mod tests { ); } + /// A missing packet is waited out for the playout estimate, the delay the subscription states + /// once reading started: not skipped at once, and not held to the max delay, which would hold + /// every packet behind it that long. + #[tokio::test(start_paused = true)] + async fn a_hole_is_waited_out_for_the_playout_estimate() { + use moq_mux::container::Container as _; + + let catalog = hang::catalog::AudioConfig::new(hang::catalog::AudioCodec::Pcm, 8_000, 1); + let broadcast = moq_net::broadcast::Info::new().produce(); + let track = broadcast + .create_track("audio", hang::container::track_info(hang::catalog::PRIORITY.audio)) + .unwrap(); + let subscriber = broadcast.consume(); + let max = Duration::from_secs(2); + let options = Options { + delay: Delay { + max: Some(max), + ..Delay::default() + }, + estimate: true, + ..Options::new() + }; + let mut consumer = Consumer::new(&subscriber, &catalog, "audio", options).await.unwrap(); + let container = moq_mux::catalog::hang::Container::Legacy(moq_mux::container::Kind::Audio); + let payload: Bytes = vec![0u8; 160 * size_of::()].into(); + let write = |sequence: u64| { + let mut group = track.create_group(moq_net::group::Info { start: sequence }).unwrap(); + let frame = moq_mux::container::Frame { + timestamp: Timestamp::from_micros(sequence * 20_000).unwrap(), + duration: None, + payload: payload.clone(), + keyframe: true, + }; + container.write(&mut group, &[frame]).unwrap(); + group.finish().unwrap(); + }; + + write(0); + next_frame(&mut consumer).await.unwrap().expect("the first packet"); + let estimate = consumer.delay(); + assert!(!estimate.is_zero() && estimate < max, "estimate {estimate:?}"); + + // Packet 1 never arrives; packet 2 lands 20 ms later, as it would have anyway. + tokio::time::advance(Duration::from_millis(20)).await; + write(2); + let since = kio::clock::now(); + assert!(matches!(consumer.read().await.unwrap(), Some(Read::Gap { .. }))); + assert_eq!( + since.elapsed(), + estimate, + "the hole was not waited out for the estimate" + ); + next_frame(&mut consumer) + .await + .unwrap() + .expect("the packet past the hole"); + } + + /// Backpressure holding the first packet encoded doesn't keep the estimate from the hole wait: + /// a hole right after it waits out the estimate, not the configured zero min. + #[tokio::test(start_paused = true)] + async fn a_hole_behind_a_held_first_packet_waits_out_the_estimate() { + use moq_mux::container::Container as _; + + let catalog = hang::catalog::AudioConfig::new(hang::catalog::AudioCodec::Pcm, 8_000, 1); + let broadcast = moq_net::broadcast::Info::new().produce(); + let track = broadcast + .create_track("audio", hang::container::track_info(hang::catalog::PRIORITY.audio)) + .unwrap(); + let options = Options { + delay: Delay { + max: Some(Duration::from_secs(2)), + ..Delay::default() + }, + ..Options::new() + }; + let mut consumer = Consumer::new(&broadcast.consume(), &catalog, "audio", options) + .await + .unwrap(); + let backpressure = consumer.backpressure(); + backpressure.set_latency(Duration::from_millis(100), Duration::from_secs(2)); + let container = moq_mux::catalog::hang::Container::Legacy(moq_mux::container::Kind::Audio); + let payload: Bytes = vec![0u8; 160 * size_of::()].into(); + let write = |sequence: u64| { + let mut group = track.create_group(moq_net::group::Info { start: sequence }).unwrap(); + let frame = moq_mux::container::Frame { + timestamp: Timestamp::from_micros(sequence * 20_000).unwrap(), + duration: None, + payload: payload.clone(), + keyframe: true, + }; + container.write(&mut group, &[frame]).unwrap(); + group.finish().unwrap(); + }; + + write(0); + assert!(kio::clock::timeout(Duration::ZERO, consumer.read()).await.is_err()); + assert_eq!(consumer.pending.len(), 1, "the first packet is held encoded"); + write(2); + assert!( + kio::clock::timeout(Duration::from_millis(10), consumer.read()) + .await + .is_err() + ); + write(1); + drop(backpressure); + let mut read = Vec::new(); + for _ in 0..3 { + read.push(match consumer.read().await.unwrap().unwrap() { + Read::Frame(frame) => format!("frame {}", Duration::try_from(frame.timestamp).unwrap().as_millis()), + Read::Gap { .. } => "gap".to_string(), + Read::End { .. } => "end".to_string(), + }); + } + assert_eq!(read, ["frame 0", "frame 20", "frame 40"]); + } + + /// The group the publisher says its feed starts at, landing just behind the one after it, is + /// waited out for the estimate, not skipped as a hole at the configured zero min. + #[tokio::test(start_paused = true)] + async fn the_publishers_start_landing_late_waits_out_the_estimate() { + use moq_mux::container::Container as _; + + let catalog = hang::catalog::AudioConfig::new(hang::catalog::AudioCodec::Pcm, 8_000, 1); + let broadcast = moq_net::broadcast::Info::new().produce(); + let mut track = broadcast + .create_track("audio", hang::container::track_info(hang::catalog::PRIORITY.audio)) + .unwrap(); + track.start_at(5).unwrap(); + let options = Options { + delay: Delay { + max: Some(Duration::from_secs(2)), + ..Delay::default() + }, + ..Options::new() + }; + let mut consumer = Consumer::new(&broadcast.consume(), &catalog, "audio", options) + .await + .unwrap(); + let container = moq_mux::catalog::hang::Container::Legacy(moq_mux::container::Kind::Audio); + let payload: Bytes = vec![0u8; 160 * size_of::()].into(); + let write = |sequence: u64| { + let mut group = track.create_group(moq_net::group::Info { start: sequence }).unwrap(); + let frame = moq_mux::container::Frame { + timestamp: Timestamp::from_micros(sequence * 20_000).unwrap(), + duration: None, + payload: payload.clone(), + keyframe: true, + }; + container.write(&mut group, &[frame]).unwrap(); + group.finish().unwrap(); + }; + + write(6); + assert!( + kio::clock::timeout(Duration::from_millis(10), consumer.read()) + .await + .is_err() + ); + write(5); + let mut read = Vec::new(); + for _ in 0..2 { + read.push(match consumer.read().await.unwrap().unwrap() { + Read::Frame(frame) => format!("frame {}", Duration::try_from(frame.timestamp).unwrap().as_millis()), + Read::Gap { .. } => "gap".to_string(), + Read::End { .. } => "end".to_string(), + }); + } + assert_eq!(read, ["frame 100", "frame 120"]); + } + /// A path that delivers every fifth packet 300 ms late from the start: each lands after /// the cursor passed it and is dropped unread, but was produced after the subscription /// began, so it is no backlog and holds no join open. The estimator measures the path diff --git a/rs/moq-cli/src/subscribe.rs b/rs/moq-cli/src/subscribe.rs index c82f5feab71..961a8f585c6 100644 --- a/rs/moq-cli/src/subscribe.rs +++ b/rs/moq-cli/src/subscribe.rs @@ -362,8 +362,9 @@ impl Subscribe { // Fmp4 builds the merged init segment from the first catalog snapshot, then // yields moof+mdat fragments in timestamp order across tracks. let stream = self.stream().await?; + // No min: an export plays nothing out, so a missing group is waited for the whole max delay. let mut fmp4 = moq_mux::container::fmp4::Export::new(self.source, stream) - .with_delay(Delay::default().with_max(self.args.max_delay)) + .with_delay(Delay::default().with_min(None).with_max(self.args.max_delay)) .with_fragment_duration(self.args.fragment_duration); while let Some(chunk) = fmp4.next().await? { @@ -384,7 +385,7 @@ impl Subscribe { () = finish.cancelled() => return Ok(()), }; let mut mp4 = moq_mux::container::mp4::Export::new(self.source, stream) - .with_delay(Delay::default().with_max(self.args.max_delay)) + .with_delay(Delay::default().with_min(None).with_max(self.args.max_delay)) .with_fragment_duration(self.args.fragment_duration); let file = tokio::fs::File::create_new(&path) .await @@ -464,7 +465,7 @@ impl Subscribe { let stream = self.stream().await?; let mut h264 = moq_mux::codec::h264::Export::new(self.source, stream) - .with_delay(Delay::default().with_max(self.args.max_delay)); + .with_delay(Delay::default().with_min(None).with_max(self.args.max_delay)); while let Some(chunk) = h264.next().await? { stdout.write_all(&chunk).await?; @@ -479,7 +480,7 @@ impl Subscribe { let stream = self.stream().await?; let mut h265 = moq_mux::codec::h265::Export::new(self.source, stream) - .with_delay(Delay::default().with_max(self.args.max_delay)); + .with_delay(Delay::default().with_min(None).with_max(self.args.max_delay)); while let Some(chunk) = h265.next().await? { stdout.write_all(&chunk).await?; diff --git a/rs/moq-ffi/src/consumer.rs b/rs/moq-ffi/src/consumer.rs index 599c7fa99fe..a3b6bbd2c59 100644 --- a/rs/moq-ffi/src/consumer.rs +++ b/rs/moq-ffi/src/consumer.rs @@ -24,11 +24,14 @@ fn raw_frame(frame: moq_net::frame::Frame) -> MoqFrame { /// an omitted one to zero, and a bare C or C++ record leaves both unset. #[derive(Clone, Copy, Debug, uniffi::Record)] pub struct MoqDelay { - /// The target latency: the playout or jitter-buffer delay held behind the live edge, and - /// where a cold join starts, or null to leave it unstated. A media consumer plays an - /// unstated minimum as zero, while the subscription keeps it unstated, so it never pulls - /// the aggregate across subscribers to zero. moq-lite-07 sends it upstream. A `min` past - /// `max` starts at `max`, since the publisher serves nothing older. + /// The target latency: the playout or jitter-buffer delay held behind the live edge, where + /// a cold join starts, and how long a media consumer waits for a missing group, or null to + /// leave it unstated. A media consumer starts an unstated minimum as zero and waits a + /// missing group for `max` instead (an audio decoder floors it at zero and waits only its + /// playout estimate, which can be larger), while the subscription keeps it unstated, so it + /// never pulls the aggregate across subscribers to zero, unless a catalog warmup or an + /// audio decoder's playout delay states one. moq-lite-07 sends it upstream. A `min` + /// past `max` starts and waits at `max`, since the publisher serves nothing older. pub min: Option, /// How far a non-latest group may fall behind the live edge before it is skipped, or null /// for no subscriber limit, leaving the publisher's max age alone to bound it. `0` skips diff --git a/rs/moq-gst/src/source/imp.rs b/rs/moq-gst/src/source/imp.rs index 690ff47d73f..81efc7bacbf 100644 --- a/rs/moq-gst/src/source/imp.rs +++ b/rs/moq-gst/src/source/imp.rs @@ -1712,9 +1712,12 @@ impl Reader { // ending a broadcast produces for a name nobody served). A publisher that answers neither // leaves this waiting, so racing `cancel` keeps such a reader reapable, and holding the // wait here keeps it off every other rendition. - // The catalog warmup reaches that much further back for a decoder to start clean. - let playout = - moq_mux::container::Playout::new(moq_net::track::Delay::default().with_max(max_delay), shape.warmup); + // The catalog warmup reaches that much further back for a decoder to start clean. No min: + // the pipeline's own latency is unknown here, so a missing group is waited for the max delay. + let playout = moq_mux::container::Playout::new( + moq_net::track::Delay::default().with_min(None).with_max(max_delay), + shape.warmup, + ); let subscriber = tokio::select! { _ = cancel.changed() => return Exit::Done, subscriber = async { diff --git a/rs/moq-mux/src/container/consumer.rs b/rs/moq-mux/src/container/consumer.rs index 3918fc11d57..4cc5635cb4b 100644 --- a/rs/moq-mux/src/container/consumer.rs +++ b/rs/moq-mux/src/container/consumer.rs @@ -71,8 +71,10 @@ pub(crate) enum Item { /// does) holds no group, and the consumer steps over it at once. Any other run may hold a /// missing group, which gets the same tolerance: there is no way to tell a stream that lost the /// delivery race from one the cache evicted, and a reader starved of CPU may take the missing -/// group in the same burst as the ones past it. Its wait, [`set_wait`](Self::set_wait) or the -/// max delay, also expires that much monotonic time after the first group past it arrived, so a +/// group in the same burst as the ones past it. A missing group is also skipped once waited out +/// for the reader's [`Delay::min`], or the max delay when no min is stated, since past its own +/// buffer a reader would play it late. That wait runs in monotonic time from when the first group +/// past it arrived, so a /// marker behind a hole is delivered even when the track is paused, and the holes a stalled /// source left behind expire together rather than one wait each. A reader feeding a playout clock /// ([`set_playhead`](Self::set_playhead)) also skips a hole once that clock reaches where the @@ -160,8 +162,10 @@ pub struct Consumer { // How the cursor chooses its first group. startup: Startup, - // How far behind the live edge an unfloored start reaches, before the warmup: see `Delay::min`. - min_delay: std::time::Duration, + // How far behind the live edge the reader plays, before the warmup: see `Delay::min`. An unfloored + // start reaches back by it, reading `None` as zero, and a missing group is waited for it, or for + // the max delay when `None`. + min_delay: Option, // How much further than the min delay an unfloored start reaches: see `Playout`. warmup: std::time::Duration, @@ -176,9 +180,6 @@ pub struct Consumer { // How far we may drift from the live edge before skipping a group. max_delay: std::time::Duration, - // How long a missing group is waited for, capped at the max delay; `None` waits the max delay. - wait: Option, - // Wakes the reader once the hole at the cursor, or the start's wait, expires. hole_timer: Option>>, @@ -436,12 +437,11 @@ impl Consumer { memory: Memory::new(DEFAULT_MAX_BUFFER), gated: false, startup: Startup::Earliest { anchor: None }, - min_delay: subscription.delay.min.unwrap_or_default(), + min_delay: subscription.delay.min, warmup: std::time::Duration::ZERO, target: None, warmed: None, max_delay, - wait: None, hole_timer: None, playhead: None, edge: None, @@ -863,7 +863,7 @@ impl Consumer { // stops moving, a backlog with every other group missing would otherwise drain one // budget per hole, which reads downstream as a source far slower than real time. let since = front.late; - let wait = self.wait.map_or(self.max_delay, |wait| wait.min(self.max_delay)); + let wait = self.hole_wait(); let elapsed = since.elapsed() >= wait; let aged = next_group.is_some_and(|(_, start)| max_timestamp.saturating_sub(start) >= self.max_delay); // Once the playout clock reaches where the first group past it begins, that group's @@ -981,6 +981,12 @@ impl Consumer { } } + // How long a missing group is waited for: the min delay, the reader's own buffer, since past it the + // group would play late, or the max delay when the reader states no min. Never past the max. + fn hole_wait(&self) -> std::time::Duration { + self.min_delay.map_or(self.max_delay, |min| min.min(self.max_delay)) + } + // Before the first item, move the cursor past its group when that group's first frame trails the // newest content by more than the budget and the next group still starts at or before the live // edge less the reach, so it is not what the start covers, and repeat for the group it lands on. @@ -1019,7 +1025,11 @@ impl Consumer { break; } // The group the start reaches back to is kept: the next one begins past that point. - let reach = self.min_delay.min(self.max_delay).saturating_add(self.warmup); + let reach = self + .min_delay + .unwrap_or_default() + .min(self.max_delay) + .saturating_add(self.warmup); if !reach.is_zero() && next_start > newest.saturating_sub(reach) { break; } @@ -1099,7 +1109,11 @@ impl Consumer { let lowest = self.pending.front().expect("a group has a frame").start; // The publisher serves nothing older than the max delay, so a min delay past it reaches no // further. - let reach = self.min_delay.min(self.max_delay).saturating_add(self.warmup); + let reach = self + .min_delay + .unwrap_or_default() + .min(self.max_delay) + .saturating_add(self.warmup); // The newest group covers a zero reach. if reach.is_zero() { return Some(lowest); @@ -1395,16 +1409,16 @@ impl Consumer { /// Set the [`Delay`], mid-stream or before the first read. /// /// [`Delay::max`] is clamped to the track's max age like [`new`](Self::new). The - /// subscription keeps the requested delay verbatim, its max plus any - /// [`Playout::warmup`]. An unstated [`Delay::min`] reads as zero here, and moves - /// only a start still to come. A min past the max starts at the max, since the publisher serves - /// nothing older. + /// subscription keeps the requested delay verbatim, plus any [`Playout::warmup`]. A + /// [`Delay::min`] moves a start still to come, reading an unstated one as zero, and how long + /// a missing group is waited for from now on. A min past the max starts at the max, since the + /// publisher serves nothing older. pub fn set_delay(&mut self, delay: Delay) { // An ended reader has no subscription left to tune. let (Reader::Reading(track) | Reader::Failed(track, _)) = &mut self.reader else { return; }; - self.min_delay = delay.min.unwrap_or_default(); + self.min_delay = delay.min; self.max_delay = delay .max .unwrap_or(std::time::Duration::MAX) @@ -1420,22 +1434,11 @@ impl Consumer { } } - /// Wait at most `wait` of monotonic time, after the first group past a missing one arrives, - /// before skipping past it (default: the max delay). Content age skips it once that group - /// begins the max delay behind the newest content, whatever the wait. - /// - /// It never exceeds [`Delay::max`]. Groups that did arrive still play until they age past the - /// max delay, so a player can wait on holes for its playout delay alone while still receiving - /// the late media it catches up on. - pub fn set_wait(&mut self, wait: std::time::Duration) { - self.wait = Some(wait); - } - /// Skip a missing group once `playhead`, the playout clock this reader feeds, reaches where the /// first group past it begins (default: no clock), rather than waiting out the whole - /// [`set_wait`](Self::set_wait). Suits media where a late item is worthless once the next is due, - /// such as video, whose next due picture replaces it. Audio that still plays late, catching up - /// by time stretch, keeps the wait. + /// [`Delay::min`]. Suits media where a late item is worthless once the next is due, such as + /// video, whose next due picture replaces it. Audio that still plays late, catching up by time + /// stretch, keeps the wait. pub fn set_playhead(&mut self, playhead: crate::sync::Consumer) { self.playhead = Some(playhead); } @@ -2101,8 +2104,9 @@ mod tests { async fn a_sequence_hole_before_a_paused_data_marker_expires() { for budget in [Duration::ZERO, Duration::from_millis(100)] { let mut track = track_producer("data", hang::container::track_info(hang::catalog::PRIORITY.audio)); - let subscriber = - track.subscribe(moq_net::track::Subscription::default().with_delay(Delay::default().with_max(budget))); + let subscriber = track.subscribe( + moq_net::track::Subscription::default().with_delay(Delay::default().with_min(None).with_max(budget)), + ); let mut reader = Consumer::new(subscriber, Container::Legacy(crate::container::Kind::Data)); write_group(&mut track, 0, &[ts(10_000)]); assert!(matches!(reader.read().await.unwrap(), Some(Read::Frame { .. }))); @@ -2142,7 +2146,8 @@ mod tests { async fn a_filled_sequence_hole_gives_the_next_hole_a_fresh_budget() { let mut track = track_producer("data", hang::container::track_info(hang::catalog::PRIORITY.audio)); let subscriber = track.subscribe( - moq_net::track::Subscription::default().with_delay(Delay::default().with_max(Duration::from_millis(100))), + moq_net::track::Subscription::default() + .with_delay(Delay::default().with_min(None).with_max(Duration::from_millis(100))), ); let mut reader = Consumer::new(subscriber, Container::Legacy(crate::container::Kind::Data)); write_group(&mut track, 0, &[ts(0)]); @@ -2222,7 +2227,11 @@ mod tests { moq_net::track::Subscription::default().with_delay(Delay::default().with_max(Duration::from_secs(10))), ); let mut reader = Consumer::new(subscriber, Container::Legacy(crate::container::Kind::Audio)); - reader.set_wait(Duration::from_millis(50)); + reader.set_delay( + Delay::default() + .with_min(Duration::from_millis(50)) + .with_max(Duration::from_secs(10)), + ); // The publisher stood at group 5 as the subscription began. write_group(&mut track, 5, &[ts(100_000)]); @@ -2336,8 +2345,9 @@ mod tests { async fn holes_behind_a_stalled_source_share_one_budget() { let budget = Duration::from_millis(100); let mut track = track_producer("data", hang::container::track_info(hang::catalog::PRIORITY.audio)); - let subscriber = - track.subscribe(moq_net::track::Subscription::default().with_delay(Delay::default().with_max(budget))); + let subscriber = track.subscribe( + moq_net::track::Subscription::default().with_delay(Delay::default().with_min(None).with_max(budget)), + ); let mut reader = Consumer::new(subscriber, Container::Legacy(crate::container::Kind::Data)); write_group(&mut track, 0, &[ts(0)]); assert!(matches!( @@ -2360,6 +2370,35 @@ mod tests { assert_eq!(read, ["gap", "frame 2", "gap", "frame 4", "gap", "frame 6"]); } + /// A missing group is waited for the stated min delay, capped at the max, or the max delay when + /// no min is stated. + #[tokio::test(start_paused = true)] + async fn a_hole_is_waited_for_the_min_delay_or_the_max_when_none_is_stated() { + let max = Duration::from_secs(1); + for (min, waited) in [ + (Some(Duration::ZERO), Duration::ZERO), + (Some(Duration::from_millis(100)), Duration::from_millis(100)), + (Some(Duration::from_secs(5)), max), + (None, max), + ] { + let mut track = track_producer("data", hang::container::track_info(hang::catalog::PRIORITY.audio)); + let subscriber = track.subscribe( + moq_net::track::Subscription::default().with_delay(Delay::default().with_min(min).with_max(max)), + ); + let mut reader = Consumer::new(subscriber, Container::Legacy(crate::container::Kind::Data)); + write_group(&mut track, 0, &[ts(0)]); + assert!(matches!( + reader.read().await.unwrap(), + Some(Read::Frame { group: 0, .. }) + )); + // Group 1 never arrives, and group 2 starts right after it, so only the wait ends it. + write_group(&mut track, 2, &[ts(40_000)]); + let since = kio::clock::now(); + assert!(matches!(reader.read().await.unwrap(), Some(Read::Gap { .. }))); + assert_eq!(since.elapsed(), waited, "min {min:?}"); + } + } + /// A burst of later groups spanning past the wait doesn't age out a missing group that lands in /// the same burst: a reader starved of CPU takes in every stream at once. #[tokio::test(start_paused = true)] @@ -2369,7 +2408,11 @@ mod tests { moq_net::track::Subscription::default().with_delay(Delay::default().with_max(Duration::from_secs(1))), ); let mut reader = Consumer::new(subscriber, Container::Legacy(crate::container::Kind::Data)); - reader.set_wait(Duration::from_millis(100)); + reader.set_delay( + Delay::default() + .with_min(Duration::from_millis(100)) + .with_max(Duration::from_secs(1)), + ); write_group(&mut track, 0, &[ts(0)]); assert!(matches!( reader.read().await.unwrap(), @@ -2396,8 +2439,9 @@ mod tests { async fn a_hole_is_late_from_the_earliest_arrival_past_it() { let budget = Duration::from_millis(100); let mut track = track_producer("data", hang::container::track_info(hang::catalog::PRIORITY.audio)); - let subscriber = - track.subscribe(moq_net::track::Subscription::default().with_delay(Delay::default().with_max(budget))); + let subscriber = track.subscribe( + moq_net::track::Subscription::default().with_delay(Delay::default().with_min(None).with_max(budget)), + ); let mut reader = Consumer::new(subscriber, Container::Legacy(crate::container::Kind::Data)); write_group(&mut track, 0, &[ts(0)]); assert!(matches!( @@ -2424,13 +2468,17 @@ mod tests { /// A player waits on a hole for its playout delay, while groups that did arrive play until the /// max delay. #[tokio::test(start_paused = true)] - async fn a_hole_is_waited_for_the_wait_while_an_arrived_group_plays_up_to_the_max_delay() { + async fn a_hole_is_waited_for_the_min_delay_while_an_arrived_group_plays_up_to_the_max_delay() { let mut track = track_producer("data", hang::container::track_info(hang::catalog::PRIORITY.audio)); let subscriber = track.subscribe( moq_net::track::Subscription::default().with_delay(Delay::default().with_max(Duration::from_secs(1))), ); let mut reader = Consumer::new(subscriber, Container::Legacy(crate::container::Kind::Data)); - reader.set_wait(Duration::from_millis(100)); + reader.set_delay( + Delay::default() + .with_min(Duration::from_millis(100)) + .with_max(Duration::from_secs(1)), + ); let drain = |reader: &mut Consumer| { let mut read = Vec::new(); while let Poll::Ready(Ok(Some(item))) = reader.poll_read(&kio::Waiter::noop()) { @@ -2520,7 +2568,11 @@ mod tests { moq_net::track::Subscription::default().with_delay(Delay::default().with_max(Duration::from_secs(2))), ); let mut reader = Consumer::new(subscriber, Container::Legacy(crate::container::Kind::Data)); - reader.set_wait(Duration::from_millis(500)); + reader.set_delay( + Delay::default() + .with_min(Duration::from_millis(500)) + .with_max(Duration::from_secs(2)), + ); if let Some(playhead) = playhead { reader.set_playhead(playhead); } @@ -2592,7 +2644,11 @@ mod tests { moq_net::track::Subscription::default().with_delay(Delay::default().with_max(Duration::from_secs(2))), ); let mut reader = Consumer::new(subscriber, Container::Legacy(crate::container::Kind::Data)); - reader.set_wait(Duration::from_millis(500)); + reader.set_delay( + Delay::default() + .with_min(Duration::from_millis(500)) + .with_max(Duration::from_secs(2)), + ); reader.set_playhead(clock.consume()); let waiter = kio::Waiter::noop(); // The tail before the pause, a group per 100 ms of media and of wall time. @@ -3466,7 +3522,8 @@ mod tests { let mut track = track_producer("test", hang::container::track_info(hang::catalog::PRIORITY.audio)); let mut consumer = Consumer::new( track.subscribe( - moq_net::track::Subscription::default().with_delay(Delay::default().with_max(Duration::from_secs(30))), + moq_net::track::Subscription::default() + .with_delay(Delay::default().with_min(None).with_max(Duration::from_secs(30))), ), Container::Legacy(crate::container::Kind::Audio), ); @@ -4058,7 +4115,8 @@ mod tests { tokio::time::pause(); let mut track = track_producer("test", hang::container::track_info(hang::catalog::PRIORITY.video)); let consumer_track = track.subscribe( - moq_net::track::Subscription::default().with_delay(Delay::default().with_max(Duration::from_millis(500))), + moq_net::track::Subscription::default() + .with_delay(Delay::default().with_min(None).with_max(Duration::from_millis(500))), ); let mut consumer = Consumer::new(consumer_track, Container::Legacy(crate::container::Kind::Data)); @@ -5405,7 +5463,8 @@ mod tests { track.start_at(8).unwrap(); let mut consumer = Consumer::new( track.subscribe( - moq_net::track::Subscription::default().with_delay(Delay::default().with_max(Duration::from_secs(10))), + moq_net::track::Subscription::default() + .with_delay(Delay::default().with_min(None).with_max(Duration::from_secs(10))), ), Container::Legacy(crate::container::Kind::Data), ); diff --git a/rs/moq-mux/src/container/ts/export.rs b/rs/moq-mux/src/container/ts/export.rs index 4bd03355795..d92e496d6a2 100644 --- a/rs/moq-mux/src/container/ts/export.rs +++ b/rs/moq-mux/src/container/ts/export.rs @@ -2580,7 +2580,7 @@ where &self.program.source, name, config, - moq_net::track::Delay::default().with_max(self.budget()), + moq_net::track::Delay::default().with_min(None).with_max(self.budget()), )? .map(|s| at_edge(s, self.program.replay)) { @@ -2606,7 +2606,7 @@ where &self.program.source, name, config, - moq_net::track::Delay::default().with_max(self.budget()), + moq_net::track::Delay::default().with_min(None).with_max(self.budget()), )? .map(|s| at_edge(s, self.program.replay)) { @@ -2638,7 +2638,7 @@ where ExportSource::for_stream( &self.program.source, name, - moq_net::track::Delay::default().with_max(self.budget()), + moq_net::track::Delay::default().with_min(None).with_max(self.budget()), )?, &kind, self.program.replay, @@ -2691,7 +2691,7 @@ where &self.program.source, name, config, - moq_net::track::Delay::default().with_max(budget), + moq_net::track::Delay::default().with_min(None).with_max(budget), )? .map(|s| at_edge(s, self.program.replay)) } else if let Some(config) = catalog.audio.renditions.get(name) { @@ -2699,7 +2699,7 @@ where &self.program.source, name, config, - moq_net::track::Delay::default().with_max(budget), + moq_net::track::Delay::default().with_min(None).with_max(budget), )? .map(|s| at_edge(s, self.program.replay)) } else if mpegts @@ -2710,7 +2710,7 @@ where let source = ExportSource::for_stream( &self.program.source, name, - moq_net::track::Delay::default().with_max(budget), + moq_net::track::Delay::default().with_min(None).with_max(budget), )?; Some(stream_edge(source, &track.kind, self.program.replay)) } else { @@ -2749,7 +2749,7 @@ where &self.program.source, name, config, - moq_net::track::Delay::default().with_max(budget), + moq_net::track::Delay::default().with_min(None).with_max(budget), )?; (source, video_kind(config, name)?) } else if let Some(config) = catalog.audio.renditions.get(name) { @@ -2760,7 +2760,7 @@ where &self.program.source, name, config, - moq_net::track::Delay::default().with_max(budget), + moq_net::track::Delay::default().with_min(None).with_max(budget), )?; (source, audio_kind(config, name)?) } else { @@ -3972,6 +3972,7 @@ where /// How far a stalled group may fall behind the newest content before each source skips it: /// half the delay. A skip comes once the next group's start is that far behind, and its /// frames are only read then, so with the whole delay they would arrive at their deadline. + /// Sources state it with no min delay, so a missing group is waited for it too. fn budget(&self) -> Duration { self.program.delay / 2 } diff --git a/rs/moq-mux/src/container/ts/release.rs b/rs/moq-mux/src/container/ts/release.rs index 20398b29828..5fd720fc395 100644 --- a/rs/moq-mux/src/container/ts/release.rs +++ b/rs/moq-mux/src/container/ts/release.rs @@ -201,7 +201,9 @@ impl Release { let source = ExportSource::for_stream( &self.source, &m2ts.track, - moq_net::track::Delay::default().with_max(self.delay / 2), + // Half the delay, as the export's budget, and no min, so a missing group is + // waited for it too. + moq_net::track::Delay::default().with_min(None).with_max(self.delay / 2), )?; let source = match self.replay { true => source, diff --git a/rs/moq-mux/tests/legacy_audio.rs b/rs/moq-mux/tests/legacy_audio.rs index c521a08309f..6a9b6c188cd 100644 --- a/rs/moq-mux/tests/legacy_audio.rs +++ b/rs/moq-mux/tests/legacy_audio.rs @@ -135,8 +135,11 @@ async fn a_dropped_run_waits_for_the_next_groups_first_packet() { .expect("announced") .expect("remote broadcast") .unwrap(); - let subscription = moq_net::track::Subscription::default() - .with_delay(moq_net::track::Delay::default().with_max(Duration::from_secs(5))); + let subscription = moq_net::track::Subscription::default().with_delay( + moq_net::track::Delay::default() + .with_min(None) + .with_max(Duration::from_secs(5)), + ); let subscribed = kio::clock::timeout(TIMEOUT, remote.track("audio").expect("track").subscribe(subscription)) .await .expect("subscribed") diff --git a/rs/moq-net/src/model/subscription.rs b/rs/moq-net/src/model/subscription.rs index 74ee182629a..126a4178e30 100644 --- a/rs/moq-net/src/model/subscription.rs +++ b/rs/moq-net/src/model/subscription.rs @@ -67,7 +67,9 @@ pub struct Delay { /// included, and a resumed subscription ignore it, and changing it later moves nothing /// already started. /// - /// A media consumer reads an unstated minimum as zero. The aggregate across subscribers is + /// A media consumer also waits this long for a missing group, since past it the group would + /// play late, and starts an unstated minimum as zero but waits a missing group for + /// [`Self::max`] instead. The aggregate across subscribers is /// the largest stated one, which a relay forwards upstream, so the copy it fills reaches /// back for the reader that buffers most; each reader's own minimum then bounds what it /// reads of that copy. moq-lite before 07 and moq-transport cannot carry it. diff --git a/swift/Sources/Moq/Aliases.swift b/swift/Sources/Moq/Aliases.swift index 0d2f24aa334..dbe07dc1f05 100644 --- a/swift/Sources/Moq/Aliases.swift +++ b/swift/Sources/Moq/Aliases.swift @@ -71,8 +71,11 @@ public typealias AnnounceEvent = MoqFFI.MoqAnnounceEvent /// Per-subscription delivery preferences: priority, delay, the ranges of the track to /// deliver, and group ordering. public typealias Subscription = MoqFFI.MoqSubscription -/// How far behind the live edge a subscriber or decoder plays: `min` is the target latency and -/// where a cold join starts, `nil` to leave it unstated (a decoder plays it as zero), and `max`, +/// How far behind the live edge a subscriber or decoder plays: `min` is the target latency, where a +/// cold join starts, and how long a decoder waits for a missing group, `nil` to leave it unstated +/// (a decoder starts it as zero and waits a missing group for `max`, except an audio decoder, which +/// floors it at zero and waits only its playout estimate, which can be larger; a catalog warmup or +/// an audio decoder's playout delay still states a `min` to the publisher), and `max`, /// `nil` for no subscriber limit, is how far a non-latest group may fall behind before it is /// skipped. A `min` past `max` starts at `max`. public typealias Delay = MoqFFI.MoqDelay diff --git a/test/interop/clients/c/subscribe.c b/test/interop/clients/c/subscribe.c index ddefc2b4169..e0a18cab2fc 100644 --- a/test/interop/clients/c/subscribe.c +++ b/test/interop/clients/c/subscribe.c @@ -347,7 +347,7 @@ static void on_catalog(void *ud, int32_t catalog) { moq_video_config vcfg; memset(&vcfg, 0, sizeof(vcfg)); if (moq_consume_video_config((uint32_t)catalog, 0, &vcfg) == 0) { - moq_delay delay = {.max_us = MAX_DELAY_US}; + moq_delay delay = {.min_unstated = true, .max_us = MAX_DELAY_US}; int32_t track = moq_consume_video((uint32_t)catalog, 0, &delay, on_frame, ud); if (track > 0) { pthread_mutex_lock(&c->mu); diff --git a/test/interop/clients/cpp/main.cpp b/test/interop/clients/cpp/main.cpp index e9e211f5bc6..5bd2655e6a1 100644 --- a/test/interop/clients/cpp/main.cpp +++ b/test/interop/clients/cpp/main.cpp @@ -403,6 +403,8 @@ int subscribe( const auto &[id, video] = *catalog->video.begin(); auto subscription = moq::subscription_defaults(); + // A video reader that plays nothing out states no min, so a hole is waited for the max. + subscription.delay.min = std::nullopt; subscription.delay.max = finish ? std::chrono::duration_cast(std::chrono::duration(timeout)) : MAX_DELAY; auto media = until( diff --git a/test/interop/clients/go/main.go b/test/interop/clients/go/main.go index 9165504ded1..2f22e344845 100644 --- a/test/interop/clients/go/main.go +++ b/test/interop/clients/go/main.go @@ -347,7 +347,7 @@ func finishSubscribe(ctx context.Context, client *moq.Client, broadcast string, for id, video = range catalog.Video { break } - media, err := moqmedia.NewTrackConsumer(ctx, consumer, moqmedia.TrackConfig{Rendition: moqmedia.VideoRendition(id, video), Subscription: &moq.Subscription{Delay: moq.Delay{Max: maxDelay}}}) + media, err := moqmedia.NewTrackConsumer(ctx, consumer, moqmedia.TrackConfig{Rendition: moqmedia.VideoRendition(id, video), Subscription: &moq.Subscription{Delay: moq.Delay{MinUnstated: true, Max: maxDelay}}}) if err != nil { return err } @@ -576,7 +576,7 @@ func subscribe(ctx context.Context, url, broadcast string, opts dialOptions, tim break } - media, err := moqmedia.NewTrackConsumer(ctx, consumer, moqmedia.TrackConfig{Rendition: moqmedia.VideoRendition(id, video), Subscription: &moq.Subscription{Delay: moq.Delay{Max: maxDelay}}}) + media, err := moqmedia.NewTrackConsumer(ctx, consumer, moqmedia.TrackConfig{Rendition: moqmedia.VideoRendition(id, video), Subscription: &moq.Subscription{Delay: moq.Delay{MinUnstated: true, Max: maxDelay}}}) if err != nil { return err } diff --git a/test/interop/clients/js-native/finish.ts b/test/interop/clients/js-native/finish.ts index caab8a70029..a77d5fe9ae5 100644 --- a/test/interop/clients/js-native/finish.ts +++ b/test/interop/clients/js-native/finish.ts @@ -37,8 +37,8 @@ export async function readFinish( if (!format) throw new Error("unsupported finish media container"); const subscription = broadcast .track(Catalog.track(name, config)) - .subscribe({ delay: { max: maxDelay }, ranges: [{ start: { time: 0n } }] }); - const media = new Container.Consumer(subscription, { format, delay: { max: maxDelay } }); + .subscribe({ delay: { min: null, max: maxDelay }, ranges: [{ start: { time: 0n } }] }); + const media = new Container.Consumer(subscription, { format, delay: { min: null, max: maxDelay } }); let count = 0; try { for (;;) { diff --git a/test/interop/clients/js-native/subscribe.ts b/test/interop/clients/js-native/subscribe.ts index aaf04ba7957..16530a128f1 100644 --- a/test/interop/clients/js-native/subscribe.ts +++ b/test/interop/clients/js-native/subscribe.ts @@ -121,10 +121,10 @@ function containerFormat(config: Catalog.VideoConfig | Catalog.AudioConfig, kind } async function video(bc: Moq.Broadcast.Consumer, name: string, config: Catalog.VideoConfig): Promise { - const sub = bc.track(name).subscribe({ priority: 0, delay: { max: MAX_DELAY } }); + const sub = bc.track(name).subscribe({ priority: 0, delay: { min: null, max: MAX_DELAY } }); const consumer = new Container.Consumer(sub, { format: containerFormat(config, "video"), - delay: { max: MAX_DELAY }, + delay: { min: null, max: MAX_DELAY }, }); try { for (;;) { @@ -188,10 +188,12 @@ async function audio(bc: Moq.Broadcast.Consumer, name: string, config: Catalog.A description: config.codec === "opus" || !config.description ? undefined : Hex.toBytes(config.description), }); - const sub = bc.track(name).subscribe({ priority: Catalog.PRIORITY.audio, delay: { max: AUDIO_MAX_DELAY } }); + const sub = bc + .track(name) + .subscribe({ priority: Catalog.PRIORITY.audio, delay: { min: null, max: AUDIO_MAX_DELAY } }); const consumer = new Container.Consumer(sub, { format: containerFormat(config, "audio"), - delay: { max: AUDIO_MAX_DELAY }, + delay: { min: null, max: AUDIO_MAX_DELAY }, }); const feed = (async () => { // The consumer also hands back the backlog the relay served behind the live edge, older diff --git a/test/interop/clients/python/interop.py b/test/interop/clients/python/interop.py index 67090dd92ad..e759872bfb3 100644 --- a/test/interop/clients/python/interop.py +++ b/test/interop/clients/python/interop.py @@ -204,7 +204,7 @@ async def _finish_subscribe(client: moq.Client, broadcast: str, frames: int) -> raise RuntimeError("catalog ended without video") id, video = next(iter(catalog.video.items())) async with await moq.media.TrackConsumer.subscribe( - consumer, id, video, subscription=moq.Subscription(delay=moq.Delay(max=MAX_DELAY)) + consumer, id, video, subscription=moq.Subscription(delay=moq.Delay(min=None, max=MAX_DELAY)) ) as media: count = 0 async for frame in media: @@ -322,7 +322,7 @@ async def subscribe( id, video = next(iter(catalog.video.items())) media = await moq.media.TrackConsumer.subscribe( - consumer, id, video, subscription=moq.Subscription(delay=moq.Delay(max=MAX_DELAY)) + consumer, id, video, subscription=moq.Subscription(delay=moq.Delay(min=None, max=MAX_DELAY)) ) total = 0 diff --git a/test/interop/clients/rust/finish.rs b/test/interop/clients/rust/finish.rs index 99b9e0be60a..57aa0f0f6f1 100644 --- a/test/interop/clients/rust/finish.rs +++ b/test/interop/clients/rust/finish.rs @@ -141,7 +141,7 @@ async fn main() -> anyhow::Result<()> { .track(name)? .subscribe(Some( moq_net::track::Subscription::default() - .with_delay(moq_net::track::Delay::default().with_max(args.timeout)) + .with_delay(moq_net::track::Delay::default().with_min(None).with_max(args.timeout)) .with_ranges([moq_net::track::Range { start: moq_net::track::Anchor::Time(0), end: None,