@urun-sh/core 0.2.52 → 0.2.53

package/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 ## Unreleased
 
+- **Audio receiver jitter-buffer cap** (`AudioPlayoutOptions`, new export). A
+  muxed A/V egress reaches the browser as TWO RTP tracks with independent
+  receive buffers, and the receiver integrates delivery gaps asymmetrically:
+  video renders on arrival (a gap freezes, then drops/fast-forwards — no
+  standing delay), while audio's NetEq conceals every gap and plays the late
+  real audio AFTER the concealment, so gaps ACCUMULATE standing playout delay.
+  The RTCP-SR sync group is the only payback mechanism, and where an SFU
+  re-mints sender reports per consumer (each anchored at its own forwarding
+  instant, audio's refreshed 5x less often) it structurally cannot pay it back
+  — liveavatar measured 2.2–2.7s of standing audio delay behind video.
+
+  `_onConsume` now caps every inbound AUDIO consumer through the receiver's own
+  W3C knob: `RTCRtpReceiver.jitterBufferTarget` (milliseconds) plus the legacy
+  Chromium `playoutDelayHint` (seconds) where an engine still exposes it, so
+  either vintage is capped. Default **300ms**, tunable via
+  `AppOptions.audioPlayout.jitterBufferTargetMs` (a constructor option by
+  design — never an env var); `<= 0` sets no target at all. **Video receivers
+  are never touched** — video renders on arrival and must not be delayed.
+  Nothing bespoke: no resampling, no `playbackRate` nudging, no NetEq shadow.
+
+  Two new diagnostics make the edges observable instead of silent:
+  `audio-jitter-buffer-unsupported` (`debug`) when an engine exposes NEITHER
+  property — Firefox and Safari today, a receiver capability the SDK cannot
+  emulate, so the cap is inert there — and `audio-jitter-buffer-invalid`
+  (`warning`) for a non-finite configured target, which would otherwise slip
+  past the `<= 0` check and throw on assignment to the WebIDL double, aborting
+  the consume before `resumeConsumer`.
+
 - **`SessionDiagnostic.level` gains `'debug'`** (union widened: an exhaustive
   `switch`/`Record` over the level needs a new arm). `debug` diagnostics mirror
   to `console.debug` — hidden at the browser console's default verbosity —

package/README.md

@@ -54,6 +54,33 @@ consumes the runtime's output. A second producer on the same name fails loud wit
 media encode; the client only attaches the inbound `track` to a media element. Tracks arrive
 asynchronously — subscribe with `.on('track', …)`.
 
+## Muxed A/V arrives as two tracks — play them through one element
+
+A runtime that egresses `ctx.stream("av", video_codec=…, audio_codec=…)` puts TWO RTP tracks on
+the wire. Put both into ONE `MediaStream` on ONE media element so the browser's native A/V sync
+machinery owns the alignment (`@urun-sh/react`'s `<Video stream="av" muted={false} />` is that
+shape, prebaked):
+
+```ts
+const stream = new MediaStream()
+element.srcObject = stream
+session.stream('video').on('track', (t) => t && stream.addTrack(t))
+session.stream('audio').on('track', (t) => t && stream.addTrack(t))
+```
+
+Two separate elements give the browser two independently-buffered playout paths with nothing
+aligning them: the video track renders on arrival (a delivery gap freezes, then drops — no
+standing delay), while the audio track's jitter buffer conceals each gap and plays the late
+audio after it, so gaps ACCUMULATE into standing playout delay. RTCP sender reports are the
+only payback mechanism, and an SFU that re-mints them per track weakens it.
+
+The SDK therefore also caps every inbound AUDIO receiver's jitter buffer at 300 ms
+(`RTCRtpReceiver.jitterBufferTarget`, plus the legacy `playoutDelayHint` where present), which
+bounds that accumulation regardless of sender-report quality. Retune it with
+`App(appId, { audioPlayout: { jitterBufferTargetMs: 500 } })`; `<= 0` sets no target at all.
+Engines exposing neither property (Firefox, Safari today) are unaffected and emit an
+`audio-jitter-buffer-unsupported` diagnostic so the gap is visible rather than silent.
+
 ## The control doc is the reactive desired-state surface
 
 The client does NOT call an imperative `start/update/stop`. It writes `desired.*` keys into a