From 9758ec9e73dbe21083f1a093d001a12be6d008f2 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 14 Nov 2026 21:12:48 -0800 Subject: [PATCH 1/2] quest(m2/audio-playout): replay the publisher's largest group at tune-in Co-Authored-By: Claude Opus 5.5 --- quest/m2/audio-playout/replay-largest.md | 73 ++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 quest/m2/audio-playout/replay-largest.md diff --git a/quest/m2/audio-playout/replay-largest.md b/quest/m2/audio-playout/replay-largest.md new file mode 100644 index 00000000000..7c10c7dd8d4 --- /dev/null +++ b/quest/m2/audio-playout/replay-largest.md @@ -0,0 +1,73 @@ +# [S] Replay the publisher's largest group at tune-in + +## Goal + +The audio-quality replay measures the join's backlog the way a live player +does. Each recorded trace carries the publisher's largest group as the +subscription began, and the replay's consumer learns that number as a wire +subscriber learns it from the publisher's answer. `relay-mic-rtt40`'s target +p95 then falls from 320 ms to 120 ms, and its budget row tracks the consumers' +backlog reports, so a regression there fails the row. + +Boundaries: the native decode path's replay is still owed separately (see the +epic's README). No API is added to `@moq/net` or the container consumer for the +replay's sake, and the checked-in recordings are not re-recorded. + +## Plan + +Since [moq-dev/moq#8761](https://github.com/moq-dev/moq/pull/8761), both +consumers report a group they skip unread as join backlog when its sequence is +at or below the publisher's largest group at subscribe time. The replay +(`js/watch/src/audio/replay.ts`) writes a trace into a local +`Track.Producer`, whose largest comes from the first group to land. For +`relay-mic-rtt40` that is the stale tune-in frame, group 7499, below the +backlog the consumer closes, so the replay reports nothing and still measures +320 ms. + +Decided 2026-11-15 (maintainer: plan it in m2, under this epic). The rest was +settled from the trace and a local measurement: + +1. **The trace carries it.** `Trace` (`test/audio-quality/clients/js/src/schema.ts`) + gains a required `largest: number`, the publisher's largest group as the + subscription began, and its `version` goes to 4. Every checked-in trace gets + one, so no trace means "the track's own" by leaving it out. +2. **New captures record it.** The capture observer + (`test/audio-quality/clients/js/src/capture.ts`) reads its subscription's + `largest()` the way `js/hang`'s consumer does: once the track's info or + first group shows the subscription established and `start()` resolved, so a + cached group racing the answer, or live groups landing after it, don't set + it. `record.ts` writes it into the trace. +3. **Checked-in traces derive it.** None of them recorded the subscribe + answer, and re-recording would need a person at the MacBook's microphone and + would move every other column of the baseline. Each gets the newest group + whose media timestamp plus the path's lowest lag (the smallest + `at - timestamp` over the trace) falls at or before the first arrival: the + live edge as the first frame arrived. Its `source` names the derivation. + For `relay-mic-rtt40` that is group 8994. The backlog the relay held + reaches about 9047, and the live frames after it settle at that lag from + about 1.3 s in. +4. **The replay answers it.** The replay hands its consumer a subscriber whose + `largest()` answers the trace's `largest` first, as a wire subscriber's does + once the publisher answered, then each newer group as it lands. It + delegates everything else to the local subscriber. Rejected: creating an + empty group head at `largest`, which delivers a group the recording never + saw and moves the start; a consumer option, which is API for a test. +5. **Budgets follow.** Replay budgets equal what they measure, so every row + that moves is re-budgeted in the same PR, and the note in `budgets.json` + loses its sentence about the stale tune-in frame. Measured locally on + #8761's branch with `largest` 8994 injected, `relay-mic-rtt40` reads target + p95 120 (from 320). It also moves underruns/min 0.3 to 0.7, player skips/min + 0.3 to 0, trimmed ms/min 83 to 0, accelerated ms/min 88.3 to 97.7, A/V lag + p50 0.6 to 2.3 and p95 6.9 to 8.6, and recover ms 250.7 to 749.3: the + trade #8761's pick 3 accepted. Group 9047 measured the same row, so the + derived number is not on a knife's edge. +6. **Docs.** `test/audio-quality/README.md`'s Traces section documents the + field, how a capture records it and how the old traces derive it. + +## Waiting + +- moq-dev/moq: [#8761](https://github.com/moq-dev/moq/pull/8761) merges, which puts the backlog reports on `main`; check with `gh pr view 8761 --repo moq-dev/moq --json state` + +## Related + +- [moq-dev/moq#8761](https://github.com/moq-dev/moq/pull/8761) - the consumers' backlog reports this replay measures From cacec2a874fb12cd84427e9bba09780687a8a3f3 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Sat, 14 Nov 2026 21:35:53 -0800 Subject: [PATCH 2/2] test(hang): race the backlog helper's read with the scoped helper Derive the read's settle once per read and race it with race(), so each pass adds no listener to the outstanding read. The replay quest no longer waits on #8761, which merged. Co-Authored-By: Claude Opus 5.5 --- js/hang/src/container/consumer.backlog.test.ts | 8 +++++--- quest/m2/audio-playout/replay-largest.md | 6 +----- 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/js/hang/src/container/consumer.backlog.test.ts b/js/hang/src/container/consumer.backlog.test.ts index 39a430f245a..3a3a3709466 100644 --- a/js/hang/src/container/consumer.backlog.test.ts +++ b/js/hang/src/container/consumer.backlog.test.ts @@ -6,6 +6,7 @@ import { afterEach, beforeEach, expect, spyOn, test } from "bun:test"; import { Duration, type Installed, Instant, now } from "@moq/clock"; import { Manual } from "@moq/clock/test"; import { Time, Track, Varint } from "@moq/net"; +import { race } from "@moq/signals"; import { Consumer } from "./consumer.ts"; import { Jitter } from "./jitter.ts"; import { Format } from "./legacy.ts"; @@ -37,7 +38,8 @@ async function play(events: Event[], backlog: (group: number) => boolean): Promi }); const oracle = new Jitter(); const base = now().since(Instant.ZERO).asMillis(); - let read = consumer.next(); + // Settles once the outstanding read does, derived once per read so each pass adds no listener to it. + let read = consumer.next().then(() => true); try { for (const [at, sequence, media] of events) { await clock.advance(Duration.millis(base + at).saturatingSub(now().since(Instant.ZERO))); @@ -50,10 +52,10 @@ async function play(events: Event[], backlog: (group: number) => boolean): Promi // Read whatever is ready, so the cursor moves as a player's does. for (;;) { const flushed = clock.advance(Duration.ZERO); - const done = await Promise.race([read.then(() => true), flushed.then(() => false)]); + const done = await race([read, flushed.then(() => false)]); await flushed; if (!done) break; - read = consumer.next(); + read = consumer.next().then(() => true); } } return [consumer.spread.peek().asMillis(), oracle.measured]; diff --git a/quest/m2/audio-playout/replay-largest.md b/quest/m2/audio-playout/replay-largest.md index 7c10c7dd8d4..1b45561ae13 100644 --- a/quest/m2/audio-playout/replay-largest.md +++ b/quest/m2/audio-playout/replay-largest.md @@ -55,7 +55,7 @@ settled from the trace and a local measurement: 5. **Budgets follow.** Replay budgets equal what they measure, so every row that moves is re-budgeted in the same PR, and the note in `budgets.json` loses its sentence about the stale tune-in frame. Measured locally on - #8761's branch with `largest` 8994 injected, `relay-mic-rtt40` reads target + #8761's head with `largest` 8994 injected, `relay-mic-rtt40` reads target p95 120 (from 320). It also moves underruns/min 0.3 to 0.7, player skips/min 0.3 to 0, trimmed ms/min 83 to 0, accelerated ms/min 88.3 to 97.7, A/V lag p50 0.6 to 2.3 and p95 6.9 to 8.6, and recover ms 250.7 to 749.3: the @@ -64,10 +64,6 @@ settled from the trace and a local measurement: 6. **Docs.** `test/audio-quality/README.md`'s Traces section documents the field, how a capture records it and how the old traces derive it. -## Waiting - -- moq-dev/moq: [#8761](https://github.com/moq-dev/moq/pull/8761) merges, which puts the backlog reports on `main`; check with `gh pr view 8761 --repo moq-dev/moq --json state` - ## Related - [moq-dev/moq#8761](https://github.com/moq-dev/moq/pull/8761) - the consumers' backlog reports this replay measures