From bec5f126f5950bde2b3da7216c2153d71369072c Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 15:41:13 -0800 Subject: [PATCH 01/11] chore(quest): claim quest/m2/delay-hole-wait.md Quest-Claim: 633fdc2df032869a From 651b760417d4b8772f2fa32be051018817f143ef Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 16:33:10 -0800 Subject: [PATCH 02/11] feat(mux,hang)!: a hole is waited for the subscription's delay.min A missing group is waited for Delay::min, or Delay::max when no min is stated, in moq-mux and @moq/hang alike. set_wait and ConsumerProps.wait are gone. Native audio states its live estimate as its subscription's min, so it still skips a hole once its playout delay has passed. Exporters and other readers that play nothing out state no min, keeping the max-delay wait. Co-Authored-By: Claude Opus 5.5 --- dart/moq/lib/src/aliases.dart | 7 +- doc/concept/audio-jitter.md | 4 +- go/wrapper/records.go | 10 +- js/hang/api/container.api.md | 1 - .../src/container/consumer.backlog.test.ts | 7 +- js/hang/src/container/consumer.holes.test.ts | 21 ++- .../container/consumer.nonsequential.test.ts | 4 +- .../src/container/consumer.outoforder.test.ts | 2 +- js/hang/src/container/consumer.skips.test.ts | 2 +- .../src/container/consumer.startup.test.ts | 2 +- js/hang/src/container/consumer.test.ts | 6 +- js/hang/src/container/consumer.ts | 36 ++--- js/net/src/track.ts | 6 +- js/watch/src/audio/decoder.ts | 5 +- js/watch/src/audio/replay.ts | 1 - .../kotlin/dev/moq/Aliases.kt | 9 +- py/moq-rs/moq/_records.py | 5 +- quest/m2/README.md | 1 - .../audio-playout/browser-audio-hole-skip.md | 11 +- quest/m2/delay-hole-wait.md | 82 ---------- quest/m3/release/api-review.md | 6 +- rs/hang/examples/subscribe.rs | 5 +- rs/moq-audio/src/decode/consumer.rs | 100 ++++++++++-- rs/moq-c/src/api.rs | 11 +- rs/moq-cli/src/subscribe.rs | 9 +- rs/moq-ffi/src/consumer.rs | 11 +- rs/moq-gst/src/source/imp.rs | 9 +- rs/moq-mux/src/container/consumer.rs | 153 ++++++++++++------ rs/moq-mux/src/container/ts/export.rs | 17 +- rs/moq-mux/src/container/ts/release.rs | 4 +- rs/moq-mux/tests/legacy_audio.rs | 7 +- rs/moq-net/src/model/subscription.rs | 4 +- swift/Sources/Moq/Aliases.swift | 5 +- 33 files changed, 311 insertions(+), 252 deletions(-) delete mode 100644 quest/m2/delay-hole-wait.md diff --git a/dart/moq/lib/src/aliases.dart b/dart/moq/lib/src/aliases.dart index 163033153b6..7fe8b176fbd 100644 --- a/dart/moq/lib/src/aliases.dart +++ b/dart/moq/lib/src/aliases.dart @@ -169,9 +169,10 @@ 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, 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 21f79ac572a..861769dc506 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 its clock reaches the group past the hole: a viewer resuming behind a replayed backlog, which arrives diff --git a/go/wrapper/records.go b/go/wrapper/records.go index fdc03bdda23..0ff13b5ed2a 100644 --- a/go/wrapper/records.go +++ b/go/wrapper/records.go @@ -76,11 +76,13 @@ 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, while the subscription keeps it unstated, so it never pulls the + // aggregate across subscribers to zero. 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 293892e4005..1e7b6333488 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 () => { @@ -65,7 +65,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 () => { @@ -122,7 +122,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 () => { @@ -166,7 +166,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 () => { @@ -273,7 +273,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 () => { @@ -353,7 +353,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 () => { @@ -404,8 +404,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 () => { @@ -493,8 +492,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[] = []; @@ -545,8 +543,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 c7a9f00b9a2..6dfd429e205 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 4bc403aaa23..9abed4405f3 100644 --- a/js/hang/src/container/consumer.outoforder.test.ts +++ b/js/hang/src/container/consumer.outoforder.test.ts @@ -82,7 +82,7 @@ test("the head of the window arriving after the live edge is delivered first", a }); const consumer = new Consumer( track.subscribe({ delay: { max: Duration.millis(5000) }, ranges: [{ start: { absolute: 1n } }] }), - { format: new LegacyFormat("data"), delay: { max: Duration.millis(5000) } }, + { format: new LegacyFormat("data"), 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 9b9e6e1b253..d6d18474585 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 sent = Time.Timestamp.now(); const write = (sequence: bigint, timestamp: number) => { diff --git a/js/hang/src/container/consumer.startup.test.ts b/js/hang/src/container/consumer.startup.test.ts index 67e32c7be63..6921826c8a0 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 5163029d6d3..8bc9eea73b2 100644 --- a/js/hang/src/container/consumer.test.ts +++ b/js/hang/src/container/consumer.test.ts @@ -1770,7 +1770,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. @@ -1862,7 +1862,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). @@ -1897,7 +1897,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 4734cd33836..9a7023f2b9c 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 media time it presents now 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. + * live edge moves on once the clock passes the hole, not a whole `delay.min` later. */ playhead?: Playhead; } @@ -202,7 +196,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. @@ -293,7 +286,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); @@ -934,7 +926,7 @@ export class Consumer { const startup = this.#start === undefined && !this.#floored; const contiguous = 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 @@ -1071,8 +1063,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; @@ -1112,10 +1103,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 23e42f16d75..24b2ae2ae1f 100644 --- a/js/net/src/track.ts +++ b/js/net/src/track.ts @@ -310,8 +310,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 00bc3ce885f..efbbd98d3f2 100644 --- a/js/watch/src/audio/decoder.ts +++ b/js/watch/src/audio/decoder.ts @@ -364,8 +364,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); @@ -922,7 +922,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: this.sync, diff --git a/js/watch/src/audio/replay.ts b/js/watch/src/audio/replay.ts index 29a02c9dfcc..f9112740e7c 100644 --- a/js/watch/src/audio/replay.ts +++ b/js/watch/src/audio/replay.ts @@ -257,7 +257,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, }, ); diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt index 7584e82076b..fa04da51286 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt @@ -216,10 +216,11 @@ 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` - * past `max` starts at `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, null to leave it unstated (a + * decoder starts it as zero and waits a missing group for `max`), 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 f6414926bf4..3cf1e746f52 100644 --- a/py/moq-rs/moq/_records.py +++ b/py/moq-rs/moq/_records.py @@ -228,8 +228,9 @@ 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 + 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, while the subscription keeps it unstated, so it never pulls the aggregate across subscribers to zero. 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 diff --git a/quest/m2/README.md b/quest/m2/README.md index ac612dd0da7..1f8fd8fa90b 100644 --- a/quest/m2/README.md +++ b/quest/m2/README.md @@ -60,7 +60,6 @@ removal, a rename, or a wire, catalog, or format change that is free until [finish](/quest/m2/finish-sweep.md), [TS outcomes](/quest/m2/ts-typed-outcomes.md), and [moq-json writes](/quest/m2/json-write-at.md). - **Native media and gateways.** [The video producer](/quest/m2/video-producer.md), - [the hole wait](/quest/m2/delay-hole-wait.md), [device and cursor](/quest/m2/native-media-config.md), [sink names](/quest/m2/audio-sink-names.md), [moq-vaapi's exports](/quest/m2/vaapi-exports.md), diff --git a/quest/m2/audio-playout/browser-audio-hole-skip.md b/quest/m2/audio-playout/browser-audio-hole-skip.md index 075ac73b448..791c5c8b4c6 100644 --- a/quest/m2/audio-playout/browser-audio-hole-skip.md +++ b/quest/m2/audio-playout/browser-audio-hole-skip.md @@ -21,20 +21,17 @@ stretch held `bursty` level but left `congestion` worse than the native estimate wait (A/V lag p95 808 to 946 ms against 288 to 631 ms over three runs each). `moq play` gives the clock to video only for that reason. -`js/watch/src/audio/decoder.ts` passes `playhead: this.sync` with a -`wait` of `sync.out.maxDelay`, so the browser has the rule that measured +`js/watch/src/audio/decoder.ts` passes `playhead: this.sync`, and a hole +waits at most its `delay.min` (`sync.out.delay`), so the browser has the rule that measured worst natively. First measure: the Chromium `bursty` and `congestion` rows with and without that `playhead`, a few runs each, since `congestion` is noisy. If the browser regressed, recommended: audio waits a hole out for its playout estimate from the arrival of the group past it, as native audio does -(`rs/moq-audio/src/decode/consumer.rs`, `set_wait(self.delay())`), instead of -the playhead. That still ends the resume hole within one playout delay. +(`rs/moq-audio/src/decode/consumer.rs` states its estimate as `delay.min`), +instead of the playhead. That still ends the resume hole within one playout delay. Confirm with #8799's repro, `taskset -c 4-5 nix develop --command just test media --media-engines firefox --media-cases rename,pause`. Video keeps the playhead. -## Related - -- [A hole is waited for by the subscription's delay](/quest/m2/delay-hole-wait.md) - removes the separate wait this would keep for browser audio, so the two settle the same rule diff --git a/quest/m2/delay-hole-wait.md b/quest/m2/delay-hole-wait.md deleted file mode 100644 index b93b764d5b9..00000000000 --- a/quest/m2/delay-hole-wait.md +++ /dev/null @@ -1,82 +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. - -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 keeps a hole a late burst still fills](/quest/m2/audio-playout/browser-audio-hole-skip.md) - measures whether the browser's audio playhead over-skips, which decides the rule this quest applies to both languages diff --git a/quest/m3/release/api-review.md b/quest/m3/release/api-review.md index 866d733ba58..98d6066d5fc 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` go in [the media sweep](/quest/m2/unused-api/media.md); moq-sock's ICMP error queue and `qmux::Config::fixed_receive_window` in 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/moq-audio/src/decode/consumer.rs b/rs/moq-audio/src/decode/consumer.rs index d29328b761d..bee5198f7e8 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: @@ -165,6 +166,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, once the start no longer depends on it. + stated: Option, /// Where arrival times are measured from. origin: Instant, /// Packets read and observed but not yet decoded, held by the [`Backpressure`] gate, @@ -190,6 +194,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. @@ -269,6 +278,7 @@ impl Consumer { Ok(Self { target: Target::new(delay, options.estimate, catalog.jitter), + stated: None, decoder, track, resampler: None, @@ -325,7 +335,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)); } @@ -337,7 +347,13 @@ 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 once the + // start no longer depends on it. + fn stated(&self) -> Delay { + self.options.delay.with_min(self.stated.or(self.options.delay.min)) } /// Sample rate samples are actually delivered at, which is @@ -591,11 +607,19 @@ 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. An unfloored start waits for media the min reaches back to, which + // the estimate would measure as jitter, so that start keeps the configured min until + // reading started; a start at the live edge is floored there. 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. + let placed = self.started || self.options.start == Start::Latest; + if placed && self.stated != Some(self.delay()) { + self.stated = Some(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() { @@ -2851,6 +2875,64 @@ 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.close().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"); + } + /// 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-c/src/api.rs b/rs/moq-c/src/api.rs index 7e29823d7e9..1ab91f9b27c 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/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,9 @@ 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, while the subscription keeps it unstated, so it never pulls the + /// aggregate across subscribers to zero. pub min_unstated: bool, } diff --git a/rs/moq-cli/src/subscribe.rs b/rs/moq-cli/src/subscribe.rs index abf09dbe255..8b7c50db733 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 mut file = tokio::fs::File::create_new(&path) .await @@ -451,7 +452,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?; @@ -466,7 +467,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 69a27d6da31..853c286f278 100644 --- a/rs/moq-ffi/src/consumer.rs +++ b/rs/moq-ffi/src/consumer.rs @@ -24,11 +24,12 @@ 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, 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 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 514ae40e072..4ebb2e8d2f0 100644 --- a/rs/moq-gst/src/source/imp.rs +++ b/rs/moq-gst/src/source/imp.rs @@ -1725,9 +1725,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 db5d060d290..e8fedf8c46a 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 a377c5cc1cc..02a4c8d2200 100644 --- a/rs/moq-mux/src/container/ts/export.rs +++ b/rs/moq-mux/src/container/ts/export.rs @@ -2627,7 +2627,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)) { @@ -2653,7 +2653,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)) { @@ -2685,7 +2685,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, @@ -2738,7 +2738,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) { @@ -2746,7 +2746,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 @@ -2757,7 +2757,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 { @@ -2796,7 +2796,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) { @@ -2807,7 +2807,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 { @@ -4023,6 +4023,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 4db7d842c3b..461ab708cfa 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 7a8c2ed4812..d95b79b7979 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 0910a33c75d..81bc2de56ab 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 8b292e5c50e..f66d7646638 100644 --- a/swift/Sources/Moq/Aliases.swift +++ b/swift/Sources/Moq/Aliases.swift @@ -71,8 +71,9 @@ 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`), 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 From 51be9f57895de0f409773113702ce81c67ca4f30 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 18:53:52 -0800 Subject: [PATCH 03/11] fix(audio): state the estimate once the container fixed its start, not once decoding began Co-Authored-By: Claude Opus 5.5 --- rs/moq-audio/src/decode/consumer.rs | 75 +++++++++++++++++++++++++++-- 1 file changed, 70 insertions(+), 5 deletions(-) diff --git a/rs/moq-audio/src/decode/consumer.rs b/rs/moq-audio/src/decode/consumer.rs index bee5198f7e8..dd91a4c1876 100644 --- a/rs/moq-audio/src/decode/consumer.rs +++ b/rs/moq-audio/src/decode/consumer.rs @@ -169,6 +169,9 @@ pub struct Consumer { /// The playout delay the subscription states as its [`Delay::min`] in place of /// [`Options::delay`]'s, once the start no longer depends on it. stated: Option, + /// Whether the container's start no longer depends on the min: floored at the live edge, + /// or fixed once it handed over a packet, gap, or end. + placed: bool, /// Where arrival times are measured from. origin: Instant, /// Packets read and observed but not yet decoded, held by the [`Backpressure`] gate, @@ -279,6 +282,7 @@ impl Consumer { Ok(Self { target: Target::new(delay, options.estimate, catalog.jitter), stated: None, + placed: options.start == Start::Latest, decoder, track, resampler: None, @@ -612,11 +616,10 @@ impl Consumer { // waited out to the max delay would read as jitter. Late groups that did arrive still // play up to the max. An unfloored start waits for media the min reaches back to, which // the estimate would measure as jitter, so that start keeps the configured min until - // reading started; a start at the live edge is floored there. 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. - let placed = self.started || self.options.start == Start::Latest; - if placed && self.stated != Some(self.delay()) { + // the container hands over its first item. 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.placed && self.stated != Some(self.delay()) { self.stated = Some(self.delay()); self.track.set_delay(self.stated()); } @@ -669,6 +672,8 @@ impl Consumer { self.ended = Some(Some(moq_net::Error::TimestampMismatch.into())); } Some(Ok(Some(read))) => { + // The container hands over nothing before its start is fixed. + self.placed = true; // The estimator times arrivals, so it learns of a declared silence as the // packets around it arrive rather than as they decode. The end's own group // carries the stopped encoder's final packets, which end the speech before @@ -2933,6 +2938,66 @@ mod tests { .expect("the packet past the hole"); } + /// Backpressure holding the first packet encoded doesn't keep the estimate from the hole wait: + /// the container fixed its start when it handed that packet over, so a hole after it waits + /// out the estimate rather than the zero min an unfloored start was configured with. + #[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.close().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"]); + } + /// 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 From 110362cbf4d48faf846d37c138e88b418b401ca4 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 20:07:18 -0800 Subject: [PATCH 04/11] fix(audio): state the playout estimate as the min from the subscribe A start the publisher resolves is fixed before the container hands over anything, so a hole at it would have waited the configured zero min. Co-Authored-By: Claude Opus 5.5 --- rs/moq-audio/src/decode/consumer.rs | 100 +++++++++++++++++++++------- 1 file changed, 75 insertions(+), 25 deletions(-) diff --git a/rs/moq-audio/src/decode/consumer.rs b/rs/moq-audio/src/decode/consumer.rs index dd91a4c1876..d72272973da 100644 --- a/rs/moq-audio/src/decode/consumer.rs +++ b/rs/moq-audio/src/decode/consumer.rs @@ -167,11 +167,8 @@ pub struct Consumer { /// 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, once the start no longer depends on it. - stated: Option, - /// Whether the container's start no longer depends on the min: floored at the live edge, - /// or fixed once it handed over a packet, gap, or end. - placed: bool, + /// [`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, @@ -232,7 +229,16 @@ 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 @@ -280,9 +286,8 @@ impl Consumer { let track = playout.consumer(track, container); Ok(Self { - target: Target::new(delay, options.estimate, catalog.jitter), - stated: None, - placed: options.start == Start::Latest, + target, + stated, decoder, track, resampler: None, @@ -354,10 +359,9 @@ impl Consumer { from_millis(self.target.millis()) } - // The delay the subscription carries: the options', with the playout delay as the min once the - // start no longer depends on it. + // 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.or(self.options.delay.min)) + self.options.delay.with_min(self.stated) } /// Sample rate samples are actually delivered at, which is @@ -614,13 +618,10 @@ impl Consumer { // 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. An unfloored start waits for media the min reaches back to, which - // the estimate would measure as jitter, so that start keeps the configured min until - // the container hands over its first item. 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.placed && self.stated != Some(self.delay()) { - self.stated = Some(self.delay()); + // 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. @@ -672,8 +673,6 @@ impl Consumer { self.ended = Some(Some(moq_net::Error::TimestampMismatch.into())); } Some(Ok(Some(read))) => { - // The container hands over nothing before its start is fixed. - self.placed = true; // The estimator times arrivals, so it learns of a declared silence as the // packets around it arrive rather than as they decode. The end's own group // carries the stopped encoder's final packets, which end the speech before @@ -2771,16 +2770,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 { @@ -2939,8 +2940,7 @@ mod tests { } /// Backpressure holding the first packet encoded doesn't keep the estimate from the hole wait: - /// the container fixed its start when it handed that packet over, so a hole after it waits - /// out the estimate rather than the zero min an unfloored start was configured with. + /// 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 _; @@ -2998,6 +2998,56 @@ mod tests { 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.close().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 From aa978d33f0e6adf635a20849f52d8df83d48de73 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Mon, 16 Nov 2026 20:13:59 -0800 Subject: [PATCH 05/11] style(audio): format Co-Authored-By: Claude Opus 5.5 --- rs/moq-audio/src/decode/consumer.rs | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/rs/moq-audio/src/decode/consumer.rs b/rs/moq-audio/src/decode/consumer.rs index d72272973da..1707d34330b 100644 --- a/rs/moq-audio/src/decode/consumer.rs +++ b/rs/moq-audio/src/decode/consumer.rs @@ -229,11 +229,7 @@ impl Consumer { let name = name.into(); let warmup = catalog.warmup.unwrap_or_default().min(moq_mux::container::DELAY_MAX); - let target = Target::new( - options.delay.min.unwrap_or_default(), - options.estimate, - catalog.jitter, - ); + 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`). @@ -3035,7 +3031,11 @@ mod tests { }; write(6); - assert!(kio::clock::timeout(Duration::from_millis(10), consumer.read()).await.is_err()); + assert!( + kio::clock::timeout(Duration::from_millis(10), consumer.read()) + .await + .is_err() + ); write(5); let mut read = Vec::new(); for _ in 0..2 { From 46fba198888af90e67a443d76cd1a3cb5c9c86ce Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 11:47:27 -0800 Subject: [PATCH 06/11] fix(audio): finish test groups the way main names it --- rs/moq-audio/src/decode/consumer.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/rs/moq-audio/src/decode/consumer.rs b/rs/moq-audio/src/decode/consumer.rs index 5a97693f549..219980dbc81 100644 --- a/rs/moq-audio/src/decode/consumer.rs +++ b/rs/moq-audio/src/decode/consumer.rs @@ -3055,7 +3055,7 @@ mod tests { keyframe: true, }; container.write(&mut group, &[frame]).unwrap(); - group.close().unwrap(); + group.finish().unwrap(); }; write(0); @@ -3113,7 +3113,7 @@ mod tests { keyframe: true, }; container.write(&mut group, &[frame]).unwrap(); - group.close().unwrap(); + group.finish().unwrap(); }; write(0); @@ -3171,7 +3171,7 @@ mod tests { keyframe: true, }; container.write(&mut group, &[frame]).unwrap(); - group.close().unwrap(); + group.finish().unwrap(); }; write(6); From 601bf0dccab0efeabb0deba6510a0237682ddfc9 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 12:22:12 -0800 Subject: [PATCH 07/11] fix(interop): readers that play nothing out state no min, so a hole waits for the max Co-Authored-By: Claude Sonnet 5.5 --- test/interop/clients/c/subscribe.c | 2 +- test/interop/clients/cpp/main.cpp | 2 ++ test/interop/clients/go/main.go | 4 ++-- test/interop/clients/js-native/finish.ts | 4 ++-- test/interop/clients/js-native/subscribe.ts | 8 ++++---- test/interop/clients/python/interop.py | 4 ++-- test/interop/clients/rust/finish.rs | 2 +- 7 files changed, 14 insertions(+), 12 deletions(-) diff --git a/test/interop/clients/c/subscribe.c b/test/interop/clients/c/subscribe.c index 21e38d5da2e..aa095378f48 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 8d397649285..6a799781ef8 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: { absolute: 0n } }] }); - const media = new Container.Consumer(subscription, { format, delay: { max: maxDelay } }); + .subscribe({ delay: { min: null, max: maxDelay }, ranges: [{ start: { absolute: 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..bc1095a38ba 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,10 @@ 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, From 1f548255f66505fd94984c3c0b11dc0ba207ed08 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 13:42:45 -0800 Subject: [PATCH 08/11] style(interop): format the js-native audio subscribe call Co-Authored-By: Claude Sonnet 5.5 --- test/interop/clients/js-native/subscribe.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/test/interop/clients/js-native/subscribe.ts b/test/interop/clients/js-native/subscribe.ts index bc1095a38ba..16530a128f1 100644 --- a/test/interop/clients/js-native/subscribe.ts +++ b/test/interop/clients/js-native/subscribe.ts @@ -188,7 +188,9 @@ 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: { min: null, 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: { min: null, max: AUDIO_MAX_DELAY }, From 92abd0b1539e3f802340c533bea46f0d383bb0bb Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 16:43:30 -0800 Subject: [PATCH 09/11] docs: an audio decoder plays an unstated Delay min as zero, not a wait for the max --- dart/moq/lib/src/aliases.dart | 3 ++- go/wrapper/records.go | 3 ++- kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt | 7 ++++--- py/moq-rs/moq/_records.py | 3 ++- rs/moq-c/src/api.rs | 3 ++- rs/moq-ffi/src/consumer.rs | 3 ++- swift/Sources/Moq/Aliases.swift | 3 ++- 7 files changed, 16 insertions(+), 9 deletions(-) diff --git a/dart/moq/lib/src/aliases.dart b/dart/moq/lib/src/aliases.dart index 5f2084318ad..d555022acc8 100644 --- a/dart/moq/lib/src/aliases.dart +++ b/dart/moq/lib/src/aliases.dart @@ -173,7 +173,8 @@ extension type Delay._(MoqDelay _delay) implements MoqDelay { /// `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, and an + /// decoder starts as zero, waiting a missing group for `max` instead (an audio decoder plays it as + /// zero and waits only its playout estimate), 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/go/wrapper/records.go b/go/wrapper/records.go index 3f56b257c3a..6c26983be8e 100644 --- a/go/wrapper/records.go +++ b/go/wrapper/records.go @@ -81,7 +81,8 @@ type Delay struct { // upstream. Min time.Duration // MinUnstated leaves Min unstated, ignoring it. A decoder starts it as zero and waits a - // missing group for Max, while the subscription keeps it unstated, so it never pulls the + // missing group for Max (an audio decoder plays it as zero and waits only its playout + // estimate), while the subscription keeps it unstated, so it never pulls the // aggregate across subscribers to zero. MinUnstated bool // Max is how far a non-latest group may fall behind the live edge before it is skipped. Zero diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt index 70e4380aa99..1dc6b39c368 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt @@ -218,9 +218,10 @@ typealias Subscription = uniffi.moq.MoqSubscription /** * 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`), 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`. + * decoder starts it as zero and waits a missing group for `max`, except an audio decoder, which + * plays it as zero and waits only its playout estimate), 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 c9d6a769091..350b0d1056e 100644 --- a/py/moq-rs/moq/_records.py +++ b/py/moq-rs/moq/_records.py @@ -230,7 +230,8 @@ class Delay: ``min`` is the target latency: the playout or jitter-buffer delay held behind the 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, while the subscription keeps it unstated, so it never pulls the + ``max`` instead (an audio decoder plays it as zero and waits only its playout estimate), + while the subscription keeps it unstated, so it never pulls the aggregate across subscribers to zero. 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 diff --git a/rs/moq-c/src/api.rs b/rs/moq-c/src/api.rs index d7127146694..c608069b870 100644 --- a/rs/moq-c/src/api.rs +++ b/rs/moq-c/src/api.rs @@ -812,7 +812,8 @@ pub struct moq_delay { /// 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 starts it as zero and waits a missing group - /// for the max instead, while the subscription keeps it unstated, so it never pulls the + /// for the max instead (an audio decoder plays it as zero and waits only its playout + /// estimate), while the subscription keeps it unstated, so it never pulls the /// aggregate across subscribers to zero. pub min_unstated: bool, } diff --git a/rs/moq-ffi/src/consumer.rs b/rs/moq-ffi/src/consumer.rs index f3aa479fa97..7a56c6cec14 100644 --- a/rs/moq-ffi/src/consumer.rs +++ b/rs/moq-ffi/src/consumer.rs @@ -27,7 +27,8 @@ pub struct MoqDelay { /// 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, while the subscription keeps it unstated, so it never + /// missing group for `max` instead (an audio decoder plays it as zero and waits only its + /// playout estimate), 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 and waits at `max`, since the publisher serves nothing older. pub min: Option, diff --git a/swift/Sources/Moq/Aliases.swift b/swift/Sources/Moq/Aliases.swift index 68cd3bcc48a..cad4f0862ab 100644 --- a/swift/Sources/Moq/Aliases.swift +++ b/swift/Sources/Moq/Aliases.swift @@ -73,7 +73,8 @@ public typealias AnnounceEvent = MoqFFI.MoqAnnounceEvent public typealias Subscription = MoqFFI.MoqSubscription /// 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`), and `max`, +/// (a decoder starts it as zero and waits a missing group for `max`, except an audio decoder, which +/// plays it as zero and waits only its playout estimate), 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 From ab2976fceb764c60ffe8f51757523412d4db2161 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 17:00:26 -0800 Subject: [PATCH 10/11] docs: an unstated Delay min can be stated by a warmup or an audio playout estimate Co-Authored-By: Claude Sonnet 5.5 --- dart/moq/lib/src/aliases.dart | 5 +++-- go/wrapper/records.go | 7 ++++--- kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt | 4 +++- py/moq-rs/moq/_records.py | 7 ++++--- rs/libmoq/src/api.rs | 7 ++++--- rs/moq-ffi/src/consumer.rs | 7 ++++--- swift/Sources/Moq/Aliases.swift | 3 ++- 7 files changed, 24 insertions(+), 16 deletions(-) diff --git a/dart/moq/lib/src/aliases.dart b/dart/moq/lib/src/aliases.dart index 8b818846177..cbf8f275bde 100644 --- a/dart/moq/lib/src/aliases.dart +++ b/dart/moq/lib/src/aliases.dart @@ -173,8 +173,9 @@ extension type Delay._(MoqDelay _delay) implements MoqDelay { /// `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 plays it as - /// zero and waits only its playout estimate), and an + /// 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/go/wrapper/records.go b/go/wrapper/records.go index 6c26983be8e..1aab965a857 100644 --- a/go/wrapper/records.go +++ b/go/wrapper/records.go @@ -81,9 +81,10 @@ type Delay struct { // upstream. Min time.Duration // MinUnstated leaves Min unstated, ignoring it. A decoder starts it as zero and waits a - // missing group for Max (an audio decoder plays it as zero and waits only its playout - // estimate), while the subscription keeps it unstated, so it never pulls the - // aggregate across subscribers to zero. + // 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/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt index afcb520bc5a..e85c57007b7 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt @@ -219,7 +219,9 @@ typealias Subscription = uniffi.moq.MoqSubscription * 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 - * plays it as zero and waits only its playout estimate), and `max`, null for no subscriber limit, + * 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`. */ diff --git a/py/moq-rs/moq/_records.py b/py/moq-rs/moq/_records.py index 57dc2ed5164..c35fb6007f6 100644 --- a/py/moq-rs/moq/_records.py +++ b/py/moq-rs/moq/_records.py @@ -230,9 +230,10 @@ class Delay: ``min`` is the target latency: the playout or jitter-buffer delay held behind the 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 plays it as zero and waits only its playout estimate), - while the subscription keeps it unstated, so it never pulls the - aggregate across subscribers to zero. A ``min`` past ``max`` starts at ``max``. + ``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/rs/libmoq/src/api.rs b/rs/libmoq/src/api.rs index 0603ae3c2d5..5d7413aec03 100644 --- a/rs/libmoq/src/api.rs +++ b/rs/libmoq/src/api.rs @@ -812,9 +812,10 @@ pub struct moq_delay { /// 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 starts it as zero and waits a missing group - /// for the max instead (an audio decoder plays it as zero and waits only its playout - /// estimate), while the subscription keeps it unstated, so it never pulls the - /// aggregate across subscribers to zero. + /// 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-ffi/src/consumer.rs b/rs/moq-ffi/src/consumer.rs index 7a56c6cec14..a3b6bbd2c59 100644 --- a/rs/moq-ffi/src/consumer.rs +++ b/rs/moq-ffi/src/consumer.rs @@ -27,9 +27,10 @@ pub struct MoqDelay { /// 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 plays it as zero and waits only its - /// playout estimate), while the subscription keeps it unstated, so it never - /// pulls the aggregate across subscribers to zero. moq-lite-07 sends it upstream. A `min` + /// 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 diff --git a/swift/Sources/Moq/Aliases.swift b/swift/Sources/Moq/Aliases.swift index 2c24a34d769..dbe07dc1f05 100644 --- a/swift/Sources/Moq/Aliases.swift +++ b/swift/Sources/Moq/Aliases.swift @@ -74,7 +74,8 @@ public typealias Subscription = MoqFFI.MoqSubscription /// 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 -/// plays it as zero and waits only its playout estimate), and `max`, +/// 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 From 939f09396eebb7f138ea0115ec6e4e658bc0a332 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 17 Nov 2026 17:17:32 -0800 Subject: [PATCH 11/11] style(kt): reflow the Delay doc Co-Authored-By: Claude Sonnet 5.5 --- kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt index e85c57007b7..cc2eff6c594 100644 --- a/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt +++ b/kt/moq/src/jvmAndAndroidMain/kotlin/dev/moq/Aliases.kt @@ -221,9 +221,8 @@ typealias Subscription = uniffi.moq.MoqSubscription * 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`. + * 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