avbridge 2.2.0 → 2.3.0

package/src/player.ts

@@ -15,8 +15,10 @@ import type {
   PlayerEventMap,
   PlayerEventName,
   StrategyName,
+  TransportConfig,
   Listener,
 } from "./types.js";
+import { AvbridgeError, ERR_PLAYER_NOT_READY, ERR_ALL_STRATEGIES_EXHAUSTED } from "./errors.js";
 
 export class UnifiedPlayer {
   private emitter = new TypedEmitter<PlayerEventMap>();
@@ -34,6 +36,20 @@ export class UnifiedPlayer {
   private lastProgressPosition = -1;
   private errorListener: (() => void) | null = null;
 
+  // Bound so we can removeEventListener in destroy(); without this the
+  // listener outlives the player and accumulates on elements that swap
+  // source (e.g. <avbridge-video>).
+  private endedListener: (() => void) | null = null;
+
+  // Background tab handling. userIntent is what the user last asked for
+  // (play vs pause) — used to decide whether to auto-resume on visibility
+  // return. autoPausedForVisibility tracks whether we paused because the
+  // tab was hidden, so we don't resume playback the user deliberately
+  // paused (e.g. via media keys while hidden).
+  private userIntent: "play" | "pause" = "pause";
+  private autoPausedForVisibility = false;
+  private visibilityListener: (() => void) | null = null;
+
   // Serializes escalation / setStrategy calls
   private switchingPromise: Promise<void> = Promise.resolve();
 
@@ -41,13 +57,23 @@ export class UnifiedPlayer {
   // Revoked at destroy() so repeated source swaps don't leak.
   private subtitleResources = new SubtitleResourceBag();
 
+  // Transport config extracted from CreatePlayerOptions. Threaded to probe,
+  // subtitle fetches, and strategy session creators. Not stored on MediaContext
+  // because it's runtime config, not media analysis.
+  private readonly transport: TransportConfig | undefined;
+
   /**
    * @internal Use {@link createPlayer} or {@link UnifiedPlayer.create} instead.
    */
   private constructor(
     private readonly options: CreatePlayerOptions,
     private readonly registry: PluginRegistry,
-  ) {}
+  ) {
+    const { requestInit, fetchFn } = options;
+    if (requestInit || fetchFn) {
+      this.transport = { requestInit, fetchFn };
+    }
+  }
 
   static async create(options: CreatePlayerOptions): Promise<UnifiedPlayer> {
     const registry = new PluginRegistry();
@@ -69,7 +95,7 @@ export class UnifiedPlayer {
     const bootstrapStart = performance.now();
     try {
       dbg.info("bootstrap", "start");
-      const ctx = await dbg.timed("probe", "probe", 3000, () => probe(this.options.source));
+      const ctx = await dbg.timed("probe", "probe", 3000, () => probe(this.options.source, this.transport));
       dbg.info("probe",
         `container=${ctx.container} video=${ctx.videoTracks[0]?.codec ?? "-"} ` +
         `audio=${ctx.audioTracks[0]?.codec ?? "-"} probedBy=${ctx.probedBy}`,
@@ -121,12 +147,10 @@ export class UnifiedPlayer {
       // Try the primary strategy, falling through the chain on failure
       await this.startSession(decision.strategy, decision.reason);
 
-      // Apply subtitles for non-canvas strategies. Awaited so fetch/parse
-      // failures surface deterministically — but per-track failures are
-      // caught inside attachSubtitleTracks and logged via console.warn so
-      // a single bad sidecar doesn't break bootstrap. Subtitles are not
-      // load-bearing for playback. (Promoting this to a typed `subtitleerror`
-      // event is a nice-to-have follow-up.)
+      // Apply subtitles for non-canvas strategies. Per-track failures are
+      // caught inside attachSubtitleTracks and logged via console.warn —
+      // subtitles are not load-bearing, so a bad sidecar must not break
+      // bootstrap.
       if (this.session!.strategy !== "fallback" && this.session!.strategy !== "hybrid") {
         await attachSubtitleTracks(
           this.options.target,
@@ -136,6 +160,7 @@ export class UnifiedPlayer {
             // eslint-disable-next-line no-console
             console.warn(`[avbridge] subtitle ${track.id} failed: ${err.message}`);
           },
+          this.transport,
         );
       }
 
@@ -146,7 +171,17 @@ export class UnifiedPlayer {
       });
 
       this.startTimeupdateLoop();
-      this.options.target.addEventListener("ended", () => this.emitter.emit("ended", undefined));
+      this.endedListener = () => this.emitter.emit("ended", undefined);
+      this.options.target.addEventListener("ended", this.endedListener);
+
+      // Auto-pause on background tab (unless explicitly opted out).
+      // Chrome throttles rAF and setTimeout in hidden tabs, so playback
+      // degrades anyway — better to pause cleanly and resume on return.
+      if (this.options.backgroundBehavior !== "continue" && typeof document !== "undefined") {
+        this.visibilityListener = () => this.onVisibilityChange();
+        document.addEventListener("visibilitychange", this.visibilityListener);
+      }
+
       this.emitter.emitSticky("ready", undefined);
       const bootstrapElapsed = performance.now() - bootstrapStart;
       dbg.info("bootstrap", `ready in ${bootstrapElapsed.toFixed(0)}ms`);
@@ -177,7 +212,7 @@ export class UnifiedPlayer {
     }
 
     try {
-      this.session = await plugin.execute(this.mediaContext!, this.options.target);
+      this.session = await plugin.execute(this.mediaContext!, this.options.target, this.transport);
     } catch (err) {
       // Try the fallback chain
       const chain = this.classification?.fallbackChain;
@@ -271,7 +306,7 @@ export class UnifiedPlayer {
       }
 
       try {
-        this.session = await plugin.execute(this.mediaContext!, this.options.target);
+        this.session = await plugin.execute(this.mediaContext!, this.options.target, this.transport);
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         errors.push(`${nextStrategy}: ${msg}`);
@@ -298,8 +333,10 @@ export class UnifiedPlayer {
     }
 
     // Chain exhausted with no working strategy.
-    this.emitter.emit("error", new Error(
-      `all fallback strategies failed: ${errors.join("; ")}`,
+    this.emitter.emit("error", new AvbridgeError(
+      ERR_ALL_STRATEGIES_EXHAUSTED,
+      `All playback strategies failed: ${errors.join("; ")}`,
+      "This file may require a codec or container that isn't available in this browser. Try the fallback strategy or check browser codec support.",
     ));
   }
 
@@ -362,7 +399,7 @@ export class UnifiedPlayer {
 
   /** Manually switch to a different playback strategy. Preserves current position and play/pause state. Concurrent calls are serialized. */
   async setStrategy(strategy: StrategyName, reason?: string): Promise<void> {
-    if (!this.mediaContext) throw new Error("player not ready");
+    if (!this.mediaContext) throw new AvbridgeError(ERR_PLAYER_NOT_READY, "Player not ready — wait for the 'ready' event before calling playback methods.", "Await the 'ready' event or check player.readyState before calling play/pause/seek.");
     if (this.session?.strategy === strategy) return;
 
     this.switchingPromise = this.switchingPromise.then(() =>
@@ -394,7 +431,7 @@ export class UnifiedPlayer {
     const plugin = this.registry.findFor(this.mediaContext!, strategy);
     if (!plugin) throw new Error(`no plugin available for strategy "${strategy}"`);
 
-    this.session = await plugin.execute(this.mediaContext!, this.options.target);
+    this.session = await plugin.execute(this.mediaContext!, this.options.target, this.transport);
 
     this.emitter.emitSticky("strategy", {
       strategy,
@@ -437,30 +474,62 @@ export class UnifiedPlayer {
 
   /** Begin or resume playback. Throws if the player is not ready. */
   async play(): Promise<void> {
-    if (!this.session) throw new Error("player not ready");
+    if (!this.session) throw new AvbridgeError(ERR_PLAYER_NOT_READY, "Player not ready — wait for the 'ready' event before calling playback methods.", "Await the 'ready' event or check player.readyState before calling play/pause/seek.");
+    this.userIntent = "play";
+    this.autoPausedForVisibility = false;
     await this.session.play();
   }
 
   /** Pause playback. No-op if the player is not ready or already paused. */
   pause(): void {
+    this.userIntent = "pause";
+    this.autoPausedForVisibility = false;
     this.session?.pause();
   }
 
+  /**
+   * Handle browser tab visibility changes. On hide: pause if the user
+   * had been playing. On show: resume if we were the one who paused.
+   * Skips when `backgroundBehavior: "continue"` is set (listener isn't
+   * installed in that case).
+   */
+  private onVisibilityChange(): void {
+    if (!this.session) return;
+    const action = decideVisibilityAction({
+      hidden: document.hidden,
+      userIntent: this.userIntent,
+      sessionIsPlaying: !this.options.target.paused,
+      autoPausedForVisibility: this.autoPausedForVisibility,
+    });
+    if (action === "pause") {
+      this.autoPausedForVisibility = true;
+      dbg.info("visibility", "tab hidden — auto-paused");
+      this.session.pause();
+    } else if (action === "resume") {
+      this.autoPausedForVisibility = false;
+      dbg.info("visibility", "tab visible — auto-resuming");
+      void this.session.play().catch((err) => {
+        // eslint-disable-next-line no-console
+        console.warn("[avbridge] auto-resume after tab return failed:", err);
+      });
+    }
+  }
+
   /** Seek to the given time in seconds. Throws if the player is not ready. */
   async seek(time: number): Promise<void> {
-    if (!this.session) throw new Error("player not ready");
+    if (!this.session) throw new AvbridgeError(ERR_PLAYER_NOT_READY, "Player not ready — wait for the 'ready' event before calling playback methods.", "Await the 'ready' event or check player.readyState before calling play/pause/seek.");
     await this.session.seek(time);
   }
 
   /** Switch the active audio track by track ID. Throws if the player is not ready. */
   async setAudioTrack(id: number): Promise<void> {
-    if (!this.session) throw new Error("player not ready");
+    if (!this.session) throw new AvbridgeError(ERR_PLAYER_NOT_READY, "Player not ready — wait for the 'ready' event before calling playback methods.", "Await the 'ready' event or check player.readyState before calling play/pause/seek.");
     await this.session.setAudioTrack(id);
   }
 
   /** Switch the active subtitle track by track ID, or pass `null` to disable subtitles. */
   async setSubtitleTrack(id: number | null): Promise<void> {
-    if (!this.session) throw new Error("player not ready");
+    if (!this.session) throw new AvbridgeError(ERR_PLAYER_NOT_READY, "Player not ready — wait for the 'ready' event before calling playback methods.", "Await the 'ready' event or check player.readyState before calling play/pause/seek.");
     await this.session.setSubtitleTrack(id);
   }
 
@@ -492,6 +561,14 @@ export class UnifiedPlayer {
       this.timeupdateInterval = null;
     }
     this.clearSupervisor();
+    if (this.endedListener) {
+      this.options.target.removeEventListener("ended", this.endedListener);
+      this.endedListener = null;
+    }
+    if (this.visibilityListener) {
+      document.removeEventListener("visibilitychange", this.visibilityListener);
+      this.visibilityListener = null;
+    }
     if (this.session) {
       await this.session.destroy();
       this.session = null;
@@ -508,14 +585,35 @@ export async function createPlayer(options: CreatePlayerOptions): Promise<Unifie
 }
 
 /**
- * Build a synthetic classification when the consumer asked for a specific
- * initial strategy. We ask `classify()` for the natural decision so we can
- * inherit the correct fallback chain, then override the strategy + class.
+ * Pure decision function for visibility-change handling. Separated from
+ * the class method so it can be unit-tested without a full player
+ * instance.
  *
- * Why this matters: hard-coding `class: "NATIVE"` (the old behavior) made
- * diagnostics lie for every initialStrategy that wasn't actually native, and
- * any downstream logic that trusted `strategyClass` could make the wrong
- * decision. We now derive the class from the picked strategy.
+ * @internal — exported for unit tests; not part of the public API.
+ */
+export function decideVisibilityAction(state: {
+  hidden: boolean;
+  userIntent: "play" | "pause";
+  sessionIsPlaying: boolean;
+  autoPausedForVisibility: boolean;
+}): "pause" | "resume" | "noop" {
+  if (state.hidden) {
+    // Tab hidden: pause if user had been playing and session is active
+    if (state.userIntent === "play" && state.sessionIsPlaying) return "pause";
+    return "noop";
+  }
+  // Tab visible: resume only if we're the one who paused
+  if (state.autoPausedForVisibility) return "resume";
+  return "noop";
+}
+
+/**
+ * Build a synthetic classification for an explicit `initialStrategy` override.
+ * The `class` is derived from the chosen strategy so diagnostics and any
+ * downstream consumer of `strategyClass` see the real strategy. The fallback
+ * chain is inherited from the natural classification but must never contain
+ * `initial` itself — otherwise `startSession` would retry the strategy that
+ * just failed before escalating.
  *
  * @internal — exported for unit tests; not part of the public API.
  */
@@ -525,11 +623,13 @@ export function buildInitialDecision(
 ): Classification {
   const natural = classify(ctx);
   const cls = strategyToClass(initial, natural);
+  const inherited = natural.fallbackChain ?? defaultFallbackChain(initial);
+  const fallbackChain = inherited.filter((s) => s !== initial);
   return {
     class: cls,
     strategy: initial,
     reason: `initial strategy "${initial}" requested via options.initialStrategy`,
-    fallbackChain: natural.fallbackChain ?? defaultFallbackChain(initial),
+    fallbackChain,
   };
 }
 

package/src/plugins/builtin.ts

@@ -20,13 +20,13 @@ const remuxPlugin: Plugin = {
 const hybridPlugin: Plugin = {
   name: "hybrid",
   canHandle: () => typeof VideoDecoder !== "undefined",
-  execute: (ctx, video) => createHybridSession(ctx, video),
+  execute: (ctx, video, transport) => createHybridSession(ctx, video, transport),
 };
 
 const fallbackPlugin: Plugin = {
   name: "fallback",
   canHandle: () => true,
-  execute: (ctx, video) => createFallbackSession(ctx, video),
+  execute: (ctx, video, transport) => createFallbackSession(ctx, video, transport),
 };
 
 export function registerBuiltins(registry: PluginRegistry): void {

package/src/probe/avi.ts

@@ -205,6 +205,10 @@ function ffmpegToAvbridgeAudio(name: string): AudioCodec {
     case "ra_288": return "ra_288";
     case "sipr":   return "sipr";
     case "atrac3": return "atrac3";
+    case "dca":
+    case "dts":    return "dts";
+    case "truehd":
+    case "mlp":    return "truehd";
     default:       return name as AudioCodec;
   }
 }

package/src/probe/index.ts

@@ -1,6 +1,7 @@
-import type { ContainerKind, MediaContext, MediaInput } from "../types.js";
+import type { ContainerKind, MediaContext, MediaInput, TransportConfig } from "../types.js";
 import { normalizeSource, sniffNormalizedSource } from "../util/source.js";
 import { probeWithMediabunny } from "./mediabunny.js";
+import { AvbridgeError, ERR_PROBE_FAILED, ERR_PROBE_UNKNOWN_CONTAINER, ERR_LIBAV_NOT_REACHABLE } from "../errors.js";
 
 /** Containers mediabunny can demux. Sniff results outside this set go straight to libav. */
 const MEDIABUNNY_CONTAINERS = new Set<ContainerKind>([
@@ -32,13 +33,33 @@ const MEDIABUNNY_CONTAINERS = new Set<ContainerKind>([
  *    mediabunny can't read those containers at all, so there's no fast path
  *    to try.
  */
-export async function probe(source: MediaInput): Promise<MediaContext> {
-  const normalized = await normalizeSource(source);
+export async function probe(
+  source: MediaInput,
+  transport?: TransportConfig,
+): Promise<MediaContext> {
+  const normalized = await normalizeSource(source, transport);
   const sniffed = await sniffNormalizedSource(normalized);
 
   if (MEDIABUNNY_CONTAINERS.has(sniffed)) {
     try {
-      return await probeWithMediabunny(normalized, sniffed);
+      const result = await probeWithMediabunny(normalized, sniffed);
+      // If mediabunny returned unknown codecs, try libav which recognizes
+      // a wider range (DTS, TrueHD, etc.). Only escalate if there ARE
+      // tracks with unknown codecs — otherwise mediabunny's result is fine.
+      const hasUnknownCodec =
+        result.videoTracks.some((t) => t.codec === "unknown") ||
+        result.audioTracks.some((t) => t.codec === "unknown");
+      if (hasUnknownCodec) {
+        try {
+          const { probeWithLibav } = await import("./avi.js");
+          return await probeWithLibav(normalized, sniffed);
+        } catch {
+          // libav also failed — return mediabunny's result (unknown codecs
+          // are better than no result at all)
+          return result;
+        }
+      }
+      return result;
     } catch (mediabunnyErr) {
       // mediabunny rejected the file. Before giving up, try libav — it can
       // demux a much wider range of codec combinations in ISOBMFF/MKV/etc.
@@ -56,8 +77,10 @@ export async function probe(source: MediaInput): Promise<MediaContext> {
       } catch (libavErr) {
         const mbMsg = (mediabunnyErr as Error).message || String(mediabunnyErr);
         const lvMsg = libavErr instanceof Error ? libavErr.message : String(libavErr);
-        throw new Error(
-          `failed to probe ${sniffed} file. mediabunny: ${mbMsg}. libav fallback: ${lvMsg}.`,
+        throw new AvbridgeError(
+          ERR_PROBE_FAILED,
+          `Failed to probe ${sniffed.toUpperCase()} file. mediabunny: ${mbMsg}. libav: ${lvMsg}.`,
+          "The file may be corrupt, truncated, or in an unsupported format. Enable AVBRIDGE_DEBUG for detailed logs.",
         );
       }
     }
@@ -71,10 +94,17 @@ export async function probe(source: MediaInput): Promise<MediaContext> {
     const inner = err instanceof Error ? err.message : String(err);
     // eslint-disable-next-line no-console
     console.error("[avbridge] libav probe failed for", sniffed, "file:", err);
-    throw new Error(
-      sniffed === "unknown"
-        ? `unable to probe source: container could not be identified, and the libav.js fallback also failed: ${inner || "(no message — see browser console for the original error)"}`
-        : `${sniffed.toUpperCase()} files require libav.js, which failed to load: ${inner || "(no message — see browser console for the original error)"}`,
+    if (sniffed === "unknown") {
+      throw new AvbridgeError(
+        ERR_PROBE_UNKNOWN_CONTAINER,
+        `Unable to probe source: container format could not be identified. libav fallback: ${inner || "(no details)"}`,
+        "The file may be corrupt or in a format avbridge doesn't recognize. Check the file plays in VLC or ffprobe.",
+      );
+    }
+    throw new AvbridgeError(
+      ERR_LIBAV_NOT_REACHABLE,
+      `${sniffed.toUpperCase()} files require libav.js, which failed to load: ${inner || "(no details)"}`,
+      "Install @libav.js/variant-webcodecs, or check that AVBRIDGE_LIBAV_BASE points to the correct path.",
     );
   }
 }

package/src/strategies/fallback/audio-output.ts

@@ -76,12 +76,42 @@ export class AudioOutput implements ClockSource {
   private framesScheduled = 0;
   private destroyed = false;
 
+  /** User-set volume (0..1). Applied to the gain node. */
+  private _volume = 1;
+  /** User-set muted flag. When true, gain is forced to 0. */
+  private _muted = false;
+
   constructor() {
     this.ctx = new AudioContext();
     this.gain = this.ctx.createGain();
     this.gain.connect(this.ctx.destination);
   }
 
+  /** Set volume (0..1). Applied immediately to the gain node. */
+  setVolume(v: number): void {
+    this._volume = Math.max(0, Math.min(1, v));
+    this.applyGain();
+  }
+
+  getVolume(): number {
+    return this._volume;
+  }
+
+  /** Set muted. When true, output is silenced regardless of volume. */
+  setMuted(m: boolean): void {
+    this._muted = m;
+    this.applyGain();
+  }
+
+  getMuted(): boolean {
+    return this._muted;
+  }
+
+  private applyGain(): void {
+    const target = this._muted ? 0 : this._volume;
+    try { this.gain.gain.value = target; } catch { /* ignore */ }
+  }
+
   /**
    * Switch into wall-clock fallback mode. Called by the decoder when no
    * audio decoder could be initialized for the source. Once set, this
@@ -287,6 +317,7 @@ export class AudioOutput implements ClockSource {
     try { this.gain.disconnect(); } catch { /* ignore */ }
     this.gain = this.ctx.createGain();
     this.gain.connect(this.ctx.destination);
+    this.applyGain();
 
     this.pendingQueue = [];
     this.mediaTimeOfAnchor = newMediaTime;

package/src/strategies/fallback/decoder.ts

@@ -28,6 +28,7 @@ import { VideoRenderer } from "./video-renderer.js";
 import { AudioOutput } from "./audio-output.js";
 import type { MediaContext } from "../../types.js";
 import { pickLibavVariant } from "./variant-routing.js";
+import { dbg } from "../../util/debug.js";
 
 export interface DecoderHandles {
   destroy(): Promise<void>;
@@ -43,6 +44,7 @@ export interface StartDecoderOptions {
   context: MediaContext;
   renderer: VideoRenderer;
   audio: AudioOutput;
+  transport?: import("../../types.js").TransportConfig;
 }
 
 export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHandles> {
@@ -54,7 +56,7 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
   // 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);
 
   // Pre-allocate one AVPacket for ff_read_frame_multi to reuse.
   const readPkt = await libav.av_packet_alloc();
@@ -126,6 +128,67 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
     );
   }
 
+  // ── Bitstream filter for MPEG-4 Part 2 packed B-frames ───────────────
+  // Applied unconditionally for mpeg4 video — the BSF is a no-op when
+  // the stream doesn't actually have packed B-frames, so false positives
+  // are harmless. Without it, DivX files with packed B-frames produce
+  // garbled frame ordering.
+  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");
+      } else {
+        // eslint-disable-next-line no-console
+        console.warn("[avbridge] mpeg4_unpack_bframes BSF not available — decoding without it");
+        bsfCtx = null;
+      }
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.warn("[avbridge] failed to init mpeg4_unpack_bframes BSF:", (err as Error).message);
+      bsfCtx = null;
+      bsfPkt = null;
+    }
+  }
+
+  /** Run video packets through the BSF. Returns original packets if no BSF active. */
+  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); // BSF rejected — pass through original
+        continue;
+      }
+      while (true) {
+        const recvErr = await libav.av_bsf_receive_packet(bsfCtx, bsfPkt);
+        if (recvErr < 0) break; // EAGAIN or EOF
+        out.push(await libav.ff_copyout_packet(bsfPkt));
+      }
+    }
+    return out;
+  }
+
+  /** Flush the BSF (on seek or EOF) to drain any internally buffered packets. */
+  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 flush errors */ }
+  }
+
   // ── Mutable state shared across pump loops ───────────────────────────
   let destroyed = false;
   let pumpToken = 0;            // bumped on seek; pump loops bail when token changes
@@ -202,7 +265,8 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
       }
       if (myToken !== pumpToken || destroyed) return;
       if (videoDec && videoPackets && videoPackets.length > 0) {
-        await decodeVideoBatch(videoPackets, myToken);
+        const processed = await applyBSF(videoPackets);
+        await decodeVideoBatch(processed, myToken);
       }
 
       packetsRead += (videoPackets?.length ?? 0) + (audioPackets?.length ?? 0);
@@ -382,6 +446,8 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
       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 (videoDec) await libav.ff_free_decoder?.(videoDec.c, videoDec.pkt, videoDec.frame); } 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 */ }
@@ -435,6 +501,7 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
       try {
         if (audioDec) await libav.avcodec_flush_buffers?.(audioDec.c);
       } catch { /* ignore */ }
+      await flushBSF();
 
       // Reset synthetic timestamp counters to the seek target so newly
       // decoded frames start at the right media time.
@@ -456,6 +523,7 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
         packetsRead,
         videoFramesDecoded,
         audioFramesDecoded,
+        bsfApplied: bsfCtx ? ["mpeg4_unpack_bframes"] : [],
         // Confirmed transport info: once prepareLibavInput returns
         // successfully, we *know* whether the source is http-range (probe
         // succeeded and returned 206) or in-memory blob. Diagnostics hoists
@@ -740,6 +808,19 @@ interface LibavRuntime {
   avformat_close_input_js(ctx: number): Promise<void>;
   /** Sync helper exposed by libav.js: split a JS number into (lo, hi) int64. */
   f64toi64?(val: number): [number, number];
+
+  // BSF (bitstream filter) methods — used for mpeg4_unpack_bframes
+  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>;
+
+  // Packet copy helpers — bridge JS packet objects to/from C-level pointers
+  ff_copyin_packet(pktPtr: number, packet: LibavPacket): Promise<void>;
+  ff_copyout_packet(pkt: number): Promise<LibavPacket>;
 }
 
 interface BridgeModule {