avbridge 2.2.0 → 2.3.0

package/src/strategies/fallback/index.ts

@@ -1,4 +1,4 @@
-import type { MediaContext, PlaybackSession } from "../../types.js";
+import type { MediaContext, PlaybackSession, TransportConfig } from "../../types.js";
 import { VideoRenderer } from "./video-renderer.js";
 import { AudioOutput } from "./audio-output.js";
 import { startDecoder, type DecoderHandles } from "./decoder.js";
@@ -56,6 +56,7 @@ const READY_TIMEOUT_SECONDS = 3;
 export async function createFallbackSession(
   ctx: MediaContext,
   target: HTMLVideoElement,
+  transport?: TransportConfig,
 ): Promise<PlaybackSession> {
   // Normalize the source so URL inputs go through the libav HTTP block
   // reader instead of being buffered into memory.
@@ -74,6 +75,7 @@ export async function createFallbackSession(
       context: ctx,
       renderer,
       audio,
+      transport,
     });
   } catch (err) {
     audio.destroy();
@@ -93,6 +95,31 @@ export async function createFallbackSession(
       void doSeek(v);
     },
   });
+  // Mirror `paused` / `volume` / `muted` from the audio output — the
+  // underlying <video> never has its own src, so its native state is
+  // meaningless. This lets HTMLMediaElement consumers (<avbridge-player>
+  // controls) see the real values and control volume through the audio
+  // output's GainNode.
+  Object.defineProperty(target, "paused", {
+    configurable: true,
+    get: () => !audio.isPlaying(),
+  });
+  Object.defineProperty(target, "volume", {
+    configurable: true,
+    get: () => audio.getVolume(),
+    set: (v: number) => {
+      audio.setVolume(v);
+      target.dispatchEvent(new Event("volumechange"));
+    },
+  });
+  Object.defineProperty(target, "muted", {
+    configurable: true,
+    get: () => audio.getMuted(),
+    set: (m: boolean) => {
+      audio.setMuted(m);
+      target.dispatchEvent(new Event("volumechange"));
+    },
+  });
   // Mirror duration so the demo's controls can use target.duration too.
   if (ctx.duration && Number.isFinite(ctx.duration)) {
     Object.defineProperty(target, "duration", {
@@ -215,11 +242,14 @@ export async function createFallbackSession(
       if (!audio.isPlaying()) {
         await waitForBuffer();
         await audio.start();
+        target.dispatchEvent(new Event("play"));
+        target.dispatchEvent(new Event("playing"));
       }
     },
 
     pause() {
       void audio.pause();
+      target.dispatchEvent(new Event("pause"));
     },
 
     async seek(time) {
@@ -244,6 +274,9 @@ export async function createFallbackSession(
       try {
         delete (target as unknown as Record<string, unknown>).currentTime;
         delete (target as unknown as Record<string, unknown>).duration;
+        delete (target as unknown as Record<string, unknown>).paused;
+        delete (target as unknown as Record<string, unknown>).volume;
+        delete (target as unknown as Record<string, unknown>).muted;
       } catch { /* ignore */ }
     },
 

package/src/strategies/fallback/variant-routing.ts

@@ -19,25 +19,19 @@ import type { LibavVariant } from "./libav-loader.js";
 
 const LEGACY_CONTAINERS = new Set(["avi", "asf", "flv"]);
 
-const LEGACY_VIDEO_CODECS = new Set<VideoCodec>([
-  "wmv3",
-  "vc1",
-  "mpeg4", // MPEG-4 Part 2 / DivX / Xvid
-  "rv40",
-  "mpeg2",
-  "mpeg1",
-  "theora",
-]);
-
-const LEGACY_AUDIO_CODECS = new Set<AudioCodec>(["wmav2", "wmapro", "ac3", "eac3"]);
+/** Codecs the webcodecs variant can handle (native browser codecs only).
+ * Anything not in these sets needs the custom avbridge variant. */
+const WEBCODECS_AUDIO = new Set<AudioCodec>(["aac", "mp3", "opus", "vorbis", "flac"]);
+const WEBCODECS_VIDEO = new Set<VideoCodec>(["h264", "h265", "vp8", "vp9", "av1"]);
 
 export function pickLibavVariant(ctx: MediaContext): LibavVariant {
   if (LEGACY_CONTAINERS.has(ctx.container)) return "avbridge";
   for (const v of ctx.videoTracks) {
-    if (LEGACY_VIDEO_CODECS.has(v.codec)) return "avbridge";
+    // Any codec the webcodecs variant can't handle → need avbridge
+    if (!WEBCODECS_VIDEO.has(v.codec)) return "avbridge";
   }
   for (const a of ctx.audioTracks) {
-    if (LEGACY_AUDIO_CODECS.has(a.codec)) return "avbridge";
+    if (!WEBCODECS_AUDIO.has(a.codec)) return "avbridge";
   }
   return "webcodecs";
 }

package/src/strategies/fallback/video-renderer.ts

@@ -20,6 +20,13 @@ import type { ClockSource } from "./audio-output.js";
  * decoder was still warming up, and every frame was already in the past by
  * the time it landed in the queue.
  */
+// Periodic debug log — throttled to once per second so it doesn't
+// flood the console at 60Hz rAF rate.
+function isDebug(): boolean {
+  return typeof globalThis !== "undefined" && !!(globalThis as Record<string, unknown>).AVBRIDGE_DEBUG;
+}
+let lastDebugLog = 0;
+
 export class VideoRenderer {
   private canvas: HTMLCanvasElement;
   private ctx: CanvasRenderingContext2D;
@@ -35,6 +42,21 @@ export class VideoRenderer {
   private lastPaintWall = 0;
   /** Minimum ms between paints — paces video at roughly source fps. */
   private paintIntervalMs: number;
+  /** Cumulative count of frames skipped because all PTS are in the future. */
+  private ticksWaiting = 0;
+  /** Cumulative count of ticks where PTS mode painted a frame. */
+  private ticksPainted = 0;
+
+  /**
+   * Calibration offset (microseconds) between video PTS and audio clock.
+   * Video PTS and AudioContext.currentTime can drift ~0.1% relative to
+   * each other (different clock domains). Over 45 minutes that's 2.6s.
+   * We measure the offset on the first painted frame and update it
+   * periodically so the PTS comparison stays calibrated.
+   */
+  private ptsCalibrationUs = 0;
+  private ptsCalibrated = false;
+  private lastCalibrationWall = 0;
 
   /** Resolves once the first decoded frame has been enqueued. */
   readonly firstFrameReady: Promise<void>;
@@ -51,8 +73,12 @@ export class VideoRenderer {
     });
 
     this.canvas = document.createElement("canvas");
+    // object-fit:contain letterboxes the canvas bitmap (sized to
+    // frame.displayWidth × displayHeight in paint()) inside the stage so
+    // portrait / non-stage-aspect content isn't stretched. Canvas is a
+    // replaced element, so object-fit applies.
     this.canvas.style.cssText =
-      "position:absolute;left:0;top:0;width:100%;height:100%;background:black;";
+      "position:absolute;left:0;top:0;width:100%;height:100%;background:black;object-fit:contain;";
 
     // Attach the canvas next to the video. When the video lives inside an
     // `<avbridge-video>` shadow root, `target.parentElement` is the
@@ -150,45 +176,109 @@ export class VideoRenderer {
       return;
     }
 
-    // Wall-clock-paced painting with coarse A/V drift correction.
-    //
-    // Base policy: paint one frame every `paintIntervalMs` of wall time,
-    // regardless of the frame's synthetic timestamp. This avoids the old
-    // per-frame audio-gate that caused massive overflow during decode bursts.
-    //
-    // Drift correction (runs every ~1 sec):
-    //   - Video > 150 ms behind audio → drop one frame (catch up)
-    //   - Video > 150 ms ahead of audio → skip one paint (let audio catch up)
+    // PTS-based painting: find the latest frame whose presentation time
+    // has arrived (timestamp ≤ audio clock), paint it, and discard any
+    // older frames. This produces correct cadence at any display refresh
+    // rate and any source fps — no 3:2 pulldown artifacts.
     //
-    // This keeps long-run sync robust even for legacy AVI/DivX with messy
-    // timestamps, packed B-frames, and odd frame durations. The correction
-    // is deliberately gentle (one frame at a time) so it doesn't cause
-    // visible stuttering.
-    const wallNow = performance.now();
-    if (wallNow - this.lastPaintWall < this.paintIntervalMs - 2) return;
+    // Fallback: if frame timestamps are unreliable (all zero, synthetic),
+    // fall back to wall-clock pacing as before.
+    const rawAudioNowUs = this.clock.now() * 1_000_000;
+    const headTs = this.queue[0].timestamp ?? 0;
+    const hasPts = headTs > 0 || this.queue.length > 1;
 
-    if (this.queue.length === 0) return;
+    if (hasPts) {
+      // Calibration: video PTS and audio clock (AudioContext.currentTime)
+      // live in different clock domains with a fixed offset (different epoch)
+      // plus a small rate drift (~7ms/s). We snap the offset on first paint
+      // and re-snap every 10 seconds. Between snaps, max drift is ~70ms
+      // (under 2 frames at 24fps, below lip-sync perception threshold).
+      const wallNow = performance.now();
+      if (!this.ptsCalibrated || wallNow - this.lastCalibrationWall > 10_000) {
+        this.ptsCalibrationUs = headTs - rawAudioNowUs;
+        this.ptsCalibrated = true;
+        this.lastCalibrationWall = wallNow;
+      }
+
+      const audioNowUs = rawAudioNowUs + this.ptsCalibrationUs;
+      const frameDurationUs = this.paintIntervalMs * 1000;
+      const deadlineUs = audioNowUs + frameDurationUs;
+
+      let bestIdx = -1;
+      for (let i = 0; i < this.queue.length; i++) {
+        const ts = this.queue[i].timestamp ?? 0;
+        if (ts <= deadlineUs) {
+          bestIdx = i;
+        } else {
+          break;
+        }
+      }
 
-    // Coarse drift correction: compare the head frame's timestamp to
-    // audio.now() every ~1 sec (every 30 frames at 30fps). The frame ts
-    // and audio.now() are both in seconds of media time. Drift beyond
-    // 150ms triggers gentle correction — one frame per check, not a burst.
-    if (this.framesPainted > 0 && this.framesPainted % 30 === 0) {
-      const audioNowUs = this.clock.now() * 1_000_000;
-      const headTs = this.queue[0].timestamp ?? 0;
-      const driftUs = headTs - audioNowUs;
-
-      if (driftUs < -150_000) {
-        // Video behind audio by > 150ms — drop one frame to catch up.
-        this.queue.shift()?.close();
-        this.framesDroppedLate++;
-        if (this.queue.length === 0) return;
-      } else if (driftUs > 150_000) {
-        // Video ahead of audio by > 150ms — skip this paint cycle.
+      if (bestIdx < 0) {
+        this.ticksWaiting++;
+        if (isDebug()) {
+          const now = performance.now();
+          if (now - lastDebugLog > 1000) {
+            const headPtsMs = (headTs / 1000).toFixed(1);
+            const audioMs = (audioNowUs / 1000).toFixed(1);
+            const rawDriftMs = ((headTs - rawAudioNowUs) / 1000).toFixed(1);
+            const calibMs = (this.ptsCalibrationUs / 1000).toFixed(1);
+            // eslint-disable-next-line no-console
+            console.log(
+              `[avbridge:renderer] WAIT q=${this.queue.length} headPTS=${headPtsMs}ms calibAudio=${audioMs}ms ` +
+              `rawDrift=${rawDriftMs}ms calib=${calibMs}ms painted=${this.framesPainted} dropped=${this.framesDroppedLate}`,
+            );
+            lastDebugLog = now;
+          }
+        }
         return;
       }
+
+      // Only drop frames that are more than 2 frame-durations behind.
+      const dropThresholdUs = audioNowUs - frameDurationUs * 2;
+      let dropped = 0;
+      while (bestIdx > 0) {
+        const ts = this.queue[0].timestamp ?? 0;
+        if (ts < dropThresholdUs) {
+          this.queue.shift()?.close();
+          this.framesDroppedLate++;
+          bestIdx--;
+          dropped++;
+        } else {
+          break;
+        }
+      }
+
+      this.ticksPainted++;
+
+      if (isDebug()) {
+        const now = performance.now();
+        if (now - lastDebugLog > 1000) {
+          const paintedTs = (this.queue[0]?.timestamp ?? 0);
+          const audioMs = (audioNowUs / 1000).toFixed(1);
+          const ptsMs = (paintedTs / 1000).toFixed(1);
+          const rawDriftMs = ((paintedTs - rawAudioNowUs) / 1000).toFixed(1);
+          const calibMs = (this.ptsCalibrationUs / 1000).toFixed(1);
+          // eslint-disable-next-line no-console
+          console.log(
+            `[avbridge:renderer] PAINT q=${this.queue.length} calibAudio=${audioMs}ms nextPTS=${ptsMs}ms ` +
+            `rawDrift=${rawDriftMs}ms calib=${calibMs}ms dropped=${dropped} total_drops=${this.framesDroppedLate} painted=${this.framesPainted}`,
+          );
+          lastDebugLog = now;
+        }
+      }
+
+      const frame = this.queue.shift()!;
+      this.paint(frame);
+      frame.close();
+      this.lastPaintWall = performance.now();
+      return;
     }
 
+    // Wall-clock fallback: used when timestamps are unreliable (all zero).
+    const wallNow = performance.now();
+    if (wallNow - this.lastPaintWall < this.paintIntervalMs - 2) return;
+
     const frame = this.queue.shift()!;
     this.paint(frame);
     frame.close();
@@ -218,8 +308,14 @@ export class VideoRenderer {
 
   /** Discard all queued frames. Used by seek to drop stale buffers. */
   flush(): void {
+    const count = this.queue.length;
     while (this.queue.length > 0) this.queue.shift()?.close();
     this.prerolled = false;
+    this.ptsCalibrated = false; // recalibrate at new seek position
+    if (isDebug() && count > 0) {
+      // eslint-disable-next-line no-console
+      console.log(`[avbridge:renderer] FLUSH discarded=${count} painted=${this.framesPainted} drops=${this.framesDroppedLate}`);
+    }
   }
 
   stats(): Record<string, unknown> {

package/src/strategies/hybrid/decoder.ts

@@ -18,6 +18,7 @@ import { loadLibav, type LibavVariant } from "../fallback/libav-loader.js";
 import { VideoRenderer } from "../fallback/video-renderer.js";
 import { AudioOutput } from "../fallback/audio-output.js";
 import type { MediaContext } from "../../types.js";
+import { dbg } from "../../util/debug.js";
 import { pickLibavVariant } from "../fallback/variant-routing.js";
 
 export interface HybridDecoderHandles {
@@ -34,6 +35,7 @@ export interface StartHybridDecoderOptions {
   context: MediaContext;
   renderer: VideoRenderer;
   audio: AudioOutput;
+  transport?: import("../../types.js").TransportConfig;
 }
 
 export async function startHybridDecoder(opts: StartHybridDecoderOptions): Promise<HybridDecoderHandles> {
@@ -45,7 +47,7 @@ export async function startHybridDecoder(opts: StartHybridDecoderOptions): Promi
   // libav demuxes via Range requests. For Blob sources, it falls back to
   // mkreadaheadfile (in-memory). The returned handle owns cleanup.
   const { prepareLibavInput } = await import("../../util/libav-http-reader.js");
-  const inputHandle = await prepareLibavInput(libav as unknown as Parameters<typeof prepareLibavInput>[0], opts.filename, opts.source);
+  const inputHandle = await prepareLibavInput(libav as unknown as Parameters<typeof prepareLibavInput>[0], opts.filename, opts.source, opts.transport);
 
   const readPkt = await libav.av_packet_alloc();
   const [fmt_ctx, streams] = await libav.ff_init_demuxer_file(opts.filename);
@@ -134,6 +136,58 @@ export async function startHybridDecoder(opts: StartHybridDecoderOptions): Promi
     throw new Error("hybrid decoder: could not initialize any decoders");
   }
 
+  // ── Bitstream filter for MPEG-4 Part 2 packed B-frames ───────────────
+  let bsfCtx: number | null = null;
+  let bsfPkt: number | null = null;
+  if (videoStream && opts.context.videoTracks[0]?.codec === "mpeg4") {
+    try {
+      bsfCtx = await libav.av_bsf_list_parse_str_js("mpeg4_unpack_bframes");
+      if (bsfCtx != null && bsfCtx >= 0) {
+        const parIn = await libav.AVBSFContext_par_in(bsfCtx);
+        await libav.avcodec_parameters_copy(parIn, videoStream.codecpar);
+        await libav.av_bsf_init(bsfCtx);
+        bsfPkt = await libav.av_packet_alloc();
+        dbg.info("bsf", "mpeg4_unpack_bframes BSF active (hybrid)");
+      } else {
+        // eslint-disable-next-line no-console
+        console.warn("[avbridge] mpeg4_unpack_bframes BSF not available in hybrid decoder");
+        bsfCtx = null;
+      }
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn("[avbridge] hybrid: failed to init BSF:", (err as Error).message);
+      bsfCtx = null;
+      bsfPkt = null;
+    }
+  }
+
+  async function applyBSF(packets: LibavPacket[]): Promise<LibavPacket[]> {
+    if (!bsfCtx || !bsfPkt) return packets;
+    const out: LibavPacket[] = [];
+    for (const pkt of packets) {
+      await libav.ff_copyin_packet(bsfPkt, pkt);
+      const sendErr = await libav.av_bsf_send_packet(bsfCtx, bsfPkt);
+      if (sendErr < 0) { out.push(pkt); continue; }
+      while (true) {
+        const recvErr = await libav.av_bsf_receive_packet(bsfCtx, bsfPkt);
+        if (recvErr < 0) break;
+        out.push(await libav.ff_copyout_packet(bsfPkt));
+      }
+    }
+    return out;
+  }
+
+  async function flushBSF(): Promise<void> {
+    if (!bsfCtx || !bsfPkt) return;
+    try {
+      await libav.av_bsf_send_packet(bsfCtx, 0);
+      while (true) {
+        const err = await libav.av_bsf_receive_packet(bsfCtx, bsfPkt);
+        if (err < 0) break;
+      }
+    } catch { /* ignore */ }
+  }
+
   // ── Mutable state ─────────────────────────────────────────────────────
   let destroyed = false;
   let pumpToken = 0;
@@ -171,9 +225,27 @@ export async function startHybridDecoder(opts: StartHybridDecoderOptions): Promi
       const videoPackets = videoStream ? packets[videoStream.index] : undefined;
       const audioPackets = audioStream ? packets[audioStream.index] : undefined;
 
-      // Feed video packets to WebCodecs VideoDecoder
+      // Decode audio BEFORE video. Same rationale as fallback decoder
+      // (POSTMORTEMS.md entry 1, fix #2): audio decode via libav's
+      // ff_decode_multi is a blocking WASM call that prevents rAF from
+      // firing. For heavy codecs like DTS, a single batch can take
+      // 10-50 ms. Processing audio first ensures the audio scheduler is
+      // fed before video decode starts, reducing perceived stutter.
+      if (audioDec && audioPackets && audioPackets.length > 0) {
+        await decodeAudioBatch(audioPackets, myToken);
+      }
+      if (myToken !== pumpToken || destroyed) return;
+
+      // Yield to the event loop so the video renderer's rAF callback
+      // can fire between the audio decode (blocking) and the video feed
+      // (async). Without this, the renderer starves during DTS decode.
+      await new Promise((r) => setTimeout(r, 0));
+      if (myToken !== pumpToken || destroyed) return;
+
+      // Feed video packets to WebCodecs VideoDecoder (after BSF if applicable)
       if (videoDecoder && videoPackets && videoPackets.length > 0) {
-        for (const pkt of videoPackets) {
+        const processed = await applyBSF(videoPackets);
+        for (const pkt of processed) {
           if (myToken !== pumpToken || destroyed) return;
           sanitizePacketTimestamp(pkt, () => {
             const ts = syntheticVideoUs;
@@ -194,11 +266,6 @@ export async function startHybridDecoder(opts: StartHybridDecoderOptions): Promi
         }
       }
 
-      // Decode audio with libav software decoder
-      if (audioDec && audioPackets && audioPackets.length > 0) {
-        await decodeAudioBatch(audioPackets, myToken);
-      }
-
       packetsRead += (videoPackets?.length ?? 0) + (audioPackets?.length ?? 0);
 
       // Backpressure: WebCodecs decodeQueueSize + audio buffer + renderer queue
@@ -230,20 +297,49 @@ export async function startHybridDecoder(opts: StartHybridDecoderOptions): Promi
 
   async function decodeAudioBatch(pkts: LibavPacket[], myToken: number, flush = false) {
     if (!audioDec || destroyed || myToken !== pumpToken) return;
-    let frames: LibavFrame[];
-    try {
-      frames = await libav.ff_decode_multi(
-        audioDec.c,
-        audioDec.pkt,
-        audioDec.frame,
-        pkts,
-        flush ? { fin: true, ignoreErrors: true } : { ignoreErrors: true },
-      );
-    } catch (err) {
-      console.error("[avbridge] hybrid audio decode failed:", err);
-      return;
+
+    // For heavy codecs (DTS, AC3), decode in small sub-batches and yield
+    // between them so the event loop can run rAF for video painting.
+    // Each ff_decode_multi call is a blocking WASM invocation.
+    const AUDIO_SUB_BATCH = 4; // packets per sub-batch
+    let allFrames: LibavFrame[] = [];
+
+    for (let i = 0; i < pkts.length; i += AUDIO_SUB_BATCH) {
+      if (myToken !== pumpToken || destroyed) return;
+      const slice = pkts.slice(i, i + AUDIO_SUB_BATCH);
+      const isLast = i + AUDIO_SUB_BATCH >= pkts.length;
+      try {
+        const frames = await libav.ff_decode_multi(
+          audioDec.c,
+          audioDec.pkt,
+          audioDec.frame,
+          slice,
+          isLast && flush ? { fin: true, ignoreErrors: true } : { ignoreErrors: true },
+        );
+        allFrames = allFrames.concat(frames);
+      } catch (err) {
+        console.error("[avbridge] hybrid audio decode failed:", err);
+        return;
+      }
+      // Yield between sub-batches so rAF can fire
+      if (!isLast) await new Promise((r) => setTimeout(r, 0));
     }
+
+    // Handle flush-only call (empty pkts array)
+    if (pkts.length === 0 && flush) {
+      try {
+        allFrames = await libav.ff_decode_multi(
+          audioDec.c, audioDec.pkt, audioDec.frame, [],
+          { fin: true, ignoreErrors: true },
+        );
+      } catch (err) {
+        console.error("[avbridge] hybrid audio flush failed:", err);
+        return;
+      }
+    }
+
     if (myToken !== pumpToken || destroyed) return;
+    const frames = allFrames;
 
     for (const f of frames) {
       if (myToken !== pumpToken || destroyed) return;
@@ -283,6 +379,8 @@ export async function startHybridDecoder(opts: StartHybridDecoderOptions): Promi
       destroyed = true;
       pumpToken++;
       try { await pumpRunning; } catch { /* ignore */ }
+      try { if (bsfCtx) await libav.av_bsf_free(bsfCtx); } catch { /* ignore */ }
+      try { if (bsfPkt) await libav.av_packet_free?.(bsfPkt); } catch { /* ignore */ }
       try { if (videoDecoder && videoDecoder.state !== "closed") videoDecoder.close(); } catch { /* ignore */ }
       try { if (audioDec) await libav.ff_free_decoder?.(audioDec.c, audioDec.pkt, audioDec.frame); } catch { /* ignore */ }
       try { await libav.av_packet_free?.(readPkt); } catch { /* ignore */ }
@@ -324,6 +422,7 @@ export async function startHybridDecoder(opts: StartHybridDecoderOptions): Promi
       try {
         if (audioDec) await libav.avcodec_flush_buffers?.(audioDec.c);
       } catch { /* ignore */ }
+      await flushBSF();
 
       syntheticVideoUs = Math.round(timeSec * 1_000_000);
       syntheticAudioUs = Math.round(timeSec * 1_000_000);
@@ -340,6 +439,7 @@ export async function startHybridDecoder(opts: StartHybridDecoderOptions): Promi
         videoFramesDecoded,
         videoChunksFed,
         audioFramesDecoded,
+        bsfApplied: bsfCtx ? ["mpeg4_unpack_bframes"] : [],
         videoDecodeQueueSize: videoDecoder?.decodeQueueSize ?? 0,
         // Confirmed transport info — see fallback decoder for the pattern.
         _transport: inputHandle.transport === "http-range" ? "http-range" : "memory",
@@ -636,6 +736,17 @@ interface LibavRuntime {
   avcodec_flush_buffers?(c: number): Promise<void>;
   avformat_close_input_js(ctx: number): Promise<void>;
   f64toi64?(val: number): [number, number];
+
+  // BSF methods
+  av_bsf_list_parse_str_js(str: string): Promise<number>;
+  AVBSFContext_par_in(ctx: number): Promise<number>;
+  avcodec_parameters_copy(dst: number, src: number): Promise<number>;
+  av_bsf_init(ctx: number): Promise<number>;
+  av_bsf_send_packet(ctx: number, pkt: number): Promise<number>;
+  av_bsf_receive_packet(ctx: number, pkt: number): Promise<number>;
+  av_bsf_free(ctx: number): Promise<void>;
+  ff_copyin_packet(pktPtr: number, packet: LibavPacket): Promise<void>;
+  ff_copyout_packet(pkt: number): Promise<LibavPacket>;
 }
 
 interface BridgeModule {

package/src/strategies/hybrid/index.ts

@@ -1,4 +1,4 @@
-import type { MediaContext, PlaybackSession } from "../../types.js";
+import type { MediaContext, PlaybackSession, TransportConfig } from "../../types.js";
 import { VideoRenderer } from "../fallback/video-renderer.js";
 import { AudioOutput } from "../fallback/audio-output.js";
 import { startHybridDecoder, type HybridDecoderHandles } from "./decoder.js";
@@ -20,6 +20,7 @@ const READY_TIMEOUT_SECONDS = 10;
 export async function createHybridSession(
   ctx: MediaContext,
   target: HTMLVideoElement,
+  transport?: TransportConfig,
 ): Promise<PlaybackSession> {
   // Normalize the source so URL inputs go through the libav HTTP block
   // reader instead of being buffered into memory.
@@ -38,6 +39,7 @@ export async function createHybridSession(
       context: ctx,
       renderer,
       audio,
+      transport,
     });
   } catch (err) {
     audio.destroy();
@@ -45,12 +47,36 @@ export async function createHybridSession(
     throw err;
   }
 
-  // Patch <video> element for the unified player layer
+  // Patch <video> element for the unified player layer. The underlying
+  // <video> never has its own src; all playback state lives in the audio
+  // clock + canvas renderer. We expose that state via property getters
+  // so standard HTMLMediaElement consumers (like <avbridge-player>'s
+  // controls UI) see the real values.
   Object.defineProperty(target, "currentTime", {
     configurable: true,
     get: () => audio.now(),
     set: (v: number) => { void doSeek(v); },
   });
+  Object.defineProperty(target, "paused", {
+    configurable: true,
+    get: () => !audio.isPlaying(),
+  });
+  Object.defineProperty(target, "volume", {
+    configurable: true,
+    get: () => audio.getVolume(),
+    set: (v: number) => {
+      audio.setVolume(v);
+      target.dispatchEvent(new Event("volumechange"));
+    },
+  });
+  Object.defineProperty(target, "muted", {
+    configurable: true,
+    get: () => audio.getMuted(),
+    set: (m: boolean) => {
+      audio.setMuted(m);
+      target.dispatchEvent(new Event("volumechange"));
+    },
+  });
   if (ctx.duration && Number.isFinite(ctx.duration)) {
     Object.defineProperty(target, "duration", {
       configurable: true,
@@ -95,11 +121,16 @@ export async function createHybridSession(
       if (!audio.isPlaying()) {
         await waitForBuffer();
         await audio.start();
+        // Dispatch play/playing events so HTMLMediaElement consumers
+        // (e.g. <avbridge-player>'s controls UI) update their state.
+        target.dispatchEvent(new Event("play"));
+        target.dispatchEvent(new Event("playing"));
       }
     },
 
     pause() {
       void audio.pause();
+      target.dispatchEvent(new Event("pause"));
     },
 
     async seek(time) {
@@ -129,6 +160,9 @@ export async function createHybridSession(
       try {
         delete (target as unknown as Record<string, unknown>).currentTime;
         delete (target as unknown as Record<string, unknown>).duration;
+        delete (target as unknown as Record<string, unknown>).paused;
+        delete (target as unknown as Record<string, unknown>).volume;
+        delete (target as unknown as Record<string, unknown>).muted;
       } catch { /* ignore */ }
     },
 

package/src/strategies/remux/index.ts

@@ -36,7 +36,19 @@ export async function createRemuxSession(
         await pipeline.start(video.currentTime || 0, true);
         return;
       }
-      await video.play();
+      // seek() may have already started the pump with autoPlay=false
+      // (strategy-switch flow calls seek before play). Flip the pipeline's
+      // pending autoPlay so the MseSink fires video.play() once buffered
+      // data lands, and also attempt an immediate video.play() in case the
+      // sink is already wired up. The immediate call can reject when
+      // video.src hasn't been set yet — that's fine, the deferred path will
+      // catch it.
+      pipeline.setAutoPlay(true);
+      try {
+        await video.play();
+      } catch {
+        /* sink not ready yet; setAutoPlay will handle playback on first buffered write */
+      }
     },
     pause() {
       wantPlay = false;