Skip to content

fix(watch): buffered legacy audio starts at a small delay - #9260

Open
kixelated wants to merge 1 commit into
releasefrom
fix/watch-warmup-stall
Open

kixelated wants to merge 1 commit into
releasefrom
fix/watch-warmup-stall

Conversation

@kixelated

@kixelated kixelated commented Nov 21, 2026 •

Copy link
Copy Markdown
Collaborator

Problem

Buffered playback of a legacy (non-CMAF) audio track never starts when the delay is two or three frames, e.g. 20 or 40 ms of 20 ms Opus frames. While the ring is unanchored, the backpressure gate admits frames from the first one until one reaches the floor. The legacy decoder discards its first three outputs (Warmup(3)). So every admitted frame's output is thrown away, the ring never anchors, and the gate waits on it forever: silent audio.

release only. main dropped Warmup in moq-dev/moq#5569, too large to backport.

Approach

An input whose output the warm-up discards fills no ring space, so it skips ring.wait. Warmup.ungated() counts those inputs the way drop() counts the outputs. The gate then starts its refill at the first frame that will actually reach the ring.

Impact

  • No public API or wire change. Ships as an @moq/watch patch.

Validation

  • New warmup.test.ts case runs the decode loop against a 40 ms buffered ring with 20 ms frames. Without the fix (ungated() always false) the ring stays stalled; with it the ring fills and un-stalls.
  • @moq/watch tests (272 pass), tsc --noEmit, and biome pass in the dev shell.
  • just check origin/release fails only on API-report drift (Stats → Stats_2) in @moq/net, @moq/watch, and @moq/publish, which this PR doesn't touch; the local toolchain generates a different alias.
  • Not run in a browser.

Caused by

  • moq-dev/moq#6500 - its refill gate counts from the first released frame, including the inputs whose outputs the decoder warm-up discards (found by reviewer)

Alternatives

  • Reset the gate's refill once the first output reaches the ring. Needs the decoder callback to talk to the gate; skipping the wait for discarded inputs keeps it in the decode loop.

Follow-ups

  • The buffered head hold in js/watch/src/audio/order.ts has no bound against a publisher that repeats timestamps; handled separately.

Models

Size: XS
Implementer: Claude Code, claude-opus-5-5, unknown effort

(Written by Claude Opus 5.5)

🤖 Generated with Claude Code

Review

Rewritten by quest review after each round.

  • Head: 47f0458

  • Base: origin/release at 17afa89

  • Risk: medium, the base has no RISK.md to name what is always high or customer-facing, so every change is medium

  • Classified: medium by default

  • Reviewer: Codex, gpt-6.1-sol, medium effort

  • Session: 01a1fba3-5cb8-7161-81d7-7c04fd82d823, round 1

  • Score: 9/10, Source review found no actionable defects in excluding discarded warm-up inputs from ring backpressure while preserving normal gating afterward, but builds, tests, and browser validation were not run as instructed.

  • Rounds: 1; first round 0; findings 0: fixed 0, refuted 0, open 0

  • Findings: none

The decoder discards its first three outputs, but those inputs still
counted toward the ring's refill, so at a floor of two or three frames
nothing reached the ring and the gate waited on it forever.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated
kixelated marked this pull request as ready for review November 21, 2026 01:06

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Approach: sound. The fix leaves the warm-up inputs out of the ring's refill gate instead of teaching the gate about discarded outputs. That keeps the change in the decode loop, and it matches how Backpressure anchors #first on the first timestamp it waits on.

Reviewed changes — the full diff of the single commit, checked against Backpressure in js/watch/src/audio/buffer.ts and the legacy decode loop.

  • Warmup.ungated(): a second counter that counts decoder inputs the same way drop() counts outputs. Both make the same 1-input-to-1-output assumption.
  • #play gating: the legacy path passes warmup in, so the first LEGACY_WARMUP_CALLBACKS admitted frames skip ring.wait. The CMAF path has no warm-up and is unchanged.
  • Regression test: drives a real shared-transport createAudioBuffer with a 40 ms floor and 20 ms frames, then asserts the ring un-stalls once the gated outputs land.

Pullfrog  | View workflow run | Using claude-opus-5-5 | 𝕏

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant