avbridge 2.2.1 → 2.3.0

package/dist/element-browser.js

@@ -31,6 +31,51 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 
+// src/util/transport.ts
+function mergeFetchInit(base, extra) {
+  if (!base && !extra) return void 0;
+  return {
+    ...base,
+    ...extra,
+    headers: {
+      ...base?.headers ?? {},
+      ...extra?.headers ?? {}
+    }
+  };
+}
+function fetchWith(transport) {
+  return transport?.fetchFn ?? globalThis.fetch;
+}
+var init_transport = __esm({
+  "src/util/transport.ts"() {
+  }
+});
+
+// src/errors.ts
+var AvbridgeError, ERR_PROBE_FAILED, ERR_PROBE_UNKNOWN_CONTAINER, ERR_PROBE_FETCH_FAILED, ERR_ALL_STRATEGIES_EXHAUSTED, ERR_PLAYER_NOT_READY, ERR_LIBAV_NOT_REACHABLE, ERR_MSE_NOT_SUPPORTED, ERR_MSE_CODEC_NOT_SUPPORTED;
+var init_errors = __esm({
+  "src/errors.ts"() {
+    AvbridgeError = class extends Error {
+      constructor(code, message, recovery, options) {
+        super(message, options);
+        this.code = code;
+        this.recovery = recovery;
+      }
+      code;
+      recovery;
+      name = "AvbridgeError";
+    };
+    ERR_PROBE_FAILED = "ERR_AVBRIDGE_PROBE_FAILED";
+    ERR_PROBE_UNKNOWN_CONTAINER = "ERR_AVBRIDGE_PROBE_UNKNOWN_CONTAINER";
+    ERR_PROBE_FETCH_FAILED = "ERR_AVBRIDGE_PROBE_FETCH_FAILED";
+    ERR_ALL_STRATEGIES_EXHAUSTED = "ERR_AVBRIDGE_ALL_STRATEGIES_EXHAUSTED";
+    ERR_PLAYER_NOT_READY = "ERR_AVBRIDGE_PLAYER_NOT_READY";
+    ERR_LIBAV_NOT_REACHABLE = "ERR_AVBRIDGE_LIBAV_NOT_REACHABLE";
+    ERR_MSE_NOT_SUPPORTED = "ERR_AVBRIDGE_MSE_NOT_SUPPORTED";
+    ERR_MSE_CODEC_NOT_SUPPORTED = "ERR_AVBRIDGE_MSE_CODEC_NOT_SUPPORTED";
+  }
+});
+
 // src/util/source.ts
 var source_exports = {};
 __export(source_exports, {
@@ -43,7 +88,7 @@ __export(source_exports, {
 function isInMemorySource(source) {
   return source.kind === "blob";
 }
-async function normalizeSource(source) {
+async function normalizeSource(source, transport) {
   if (source instanceof File) {
     return {
       kind: "blob",
@@ -66,22 +111,31 @@ async function normalizeSource(source) {
   }
   if (typeof source === "string" || source instanceof URL) {
     const url2 = source instanceof URL ? source.toString() : source;
-    return await fetchUrlForSniff(url2, source);
+    return await fetchUrlForSniff(url2, source, transport);
   }
   throw new TypeError("unsupported source type");
 }
-async function fetchUrlForSniff(url2, originalSource) {
+async function fetchUrlForSniff(url2, originalSource, transport) {
   const name = url2.split("/").pop()?.split("?")[0] ?? void 0;
+  const doFetch = fetchWith(transport);
   let res;
   try {
-    res = await fetch(url2, {
+    res = await doFetch(url2, mergeFetchInit(transport?.requestInit, {
       headers: { Range: `bytes=0-${URL_SNIFF_RANGE_BYTES - 1}` }
-    });
+    }));
   } catch (err) {
-    throw new Error(`failed to fetch source ${url2}: ${err.message}`);
+    throw new AvbridgeError(
+      ERR_PROBE_FETCH_FAILED,
+      `Failed to fetch source ${url2}: ${err.message}`,
+      "Check that the URL is reachable and CORS is configured. If the source requires authentication, pass requestInit with credentials/headers."
+    );
   }
   if (!res.ok && res.status !== 206) {
-    throw new Error(`failed to fetch source ${url2}: ${res.status} ${res.statusText}`);
+    throw new AvbridgeError(
+      ERR_PROBE_FETCH_FAILED,
+      `Failed to fetch source ${url2}: ${res.status} ${res.statusText}`,
+      res.status === 403 || res.status === 401 ? "The server rejected the request. Pass requestInit with the required Authorization header or credentials." : "Check that the URL is correct and the server is reachable."
+    );
   }
   let byteLength;
   const contentRange = res.headers.get("content-range");
@@ -186,6 +240,8 @@ async function readBlobBytes(blob, limit) {
 var SNIFF_BYTES_NEEDED, URL_SNIFF_RANGE_BYTES;
 var init_source = __esm({
   "src/util/source.ts"() {
+    init_transport();
+    init_errors();
     SNIFF_BYTES_NEEDED = 380;
     URL_SNIFF_RANGE_BYTES = 32 * 1024;
   }
@@ -29453,9 +29509,12 @@ __export(libav_http_reader_exports, {
   attachLibavHttpReader: () => attachLibavHttpReader,
   prepareLibavInput: () => prepareLibavInput
 });
-async function prepareLibavInput(libav, filename, source) {
+async function prepareLibavInput(libav, filename, source, transport) {
   if (source.kind === "url") {
-    const handle = await attachLibavHttpReader(libav, filename, source.url);
+    const handle = await attachLibavHttpReader(libav, filename, source.url, {
+      requestInit: transport?.requestInit,
+      fetchFn: transport?.fetchFn
+    });
     return {
       filename,
       transport: "http-range",
@@ -30009,6 +30068,12 @@ function ffmpegToAvbridgeAudio(name) {
       return "sipr";
     case "atrac3":
       return "atrac3";
+    case "dca":
+    case "dts":
+      return "dts";
+    case "truehd":
+    case "mlp":
+      return "truehd";
     default:
       return name;
   }
@@ -31152,6 +31217,7 @@ async function safe(fn) {
 }
 
 // src/probe/index.ts
+init_errors();
 var MEDIABUNNY_CONTAINERS = /* @__PURE__ */ new Set([
   "mp4",
   "mov",
@@ -31164,12 +31230,22 @@ var MEDIABUNNY_CONTAINERS = /* @__PURE__ */ new Set([
   "adts",
   "mpegts"
 ]);
-async function probe(source) {
-  const normalized = await normalizeSource(source);
+async function probe(source, transport) {
+  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);
+      const hasUnknownCodec = result.videoTracks.some((t) => t.codec === "unknown") || result.audioTracks.some((t) => t.codec === "unknown");
+      if (hasUnknownCodec) {
+        try {
+          const { probeWithLibav: probeWithLibav2 } = await Promise.resolve().then(() => (init_avi(), avi_exports));
+          return await probeWithLibav2(normalized, sniffed);
+        } catch {
+          return result;
+        }
+      }
+      return result;
     } catch (mediabunnyErr) {
       console.warn(
         `[avbridge] mediabunny rejected ${sniffed} file, falling back to libav:`,
@@ -31181,8 +31257,10 @@ async function probe(source) {
       } catch (libavErr) {
         const mbMsg = mediabunnyErr.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."
         );
       }
     }
@@ -31193,8 +31271,17 @@ async function probe(source) {
   } catch (err) {
     const inner = err instanceof Error ? err.message : String(err);
     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 \u2014 see browser console for the original error)"}` : `${sniffed.toUpperCase()} files require libav.js, which failed to load: ${inner || "(no message \u2014 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."
     );
   }
 }
@@ -31295,7 +31382,9 @@ var FALLBACK_AUDIO_CODECS = /* @__PURE__ */ new Set([
   "ra_144",
   "ra_288",
   "sipr",
-  "atrac3"
+  "atrac3",
+  "dts",
+  "truehd"
 ]);
 var NATIVE_CONTAINERS = /* @__PURE__ */ new Set([
   "mp4",
@@ -31357,7 +31446,16 @@ function classifyContext(ctx) {
       reason: `video codec "${video.codec}" has no browser decoder; WASM fallback required`
     };
   }
-  if (audio && FALLBACK_AUDIO_CODECS.has(audio.codec)) {
+  const audioNeedsFallback = audio && (FALLBACK_AUDIO_CODECS.has(audio.codec) || !NATIVE_AUDIO_CODECS.has(audio.codec));
+  if (audioNeedsFallback) {
+    if (NATIVE_VIDEO_CODECS.has(video.codec) && webCodecsAvailable()) {
+      return {
+        class: "HYBRID_CANDIDATE",
+        strategy: "hybrid",
+        reason: `video "${video.codec}" is hardware-decodable via WebCodecs; audio "${audio.codec}" decoded in software by libav`,
+        fallbackChain: ["fallback"]
+      };
+    }
     return {
       class: "FALLBACK_REQUIRED",
       strategy: "fallback",
@@ -31642,14 +31740,23 @@ function sourceToVideoUrl(source) {
 }
 
 // src/strategies/remux/mse.ts
+init_errors();
 var MseSink = class {
   constructor(options) {
     this.options = options;
     if (typeof MediaSource === "undefined") {
-      throw new Error("MSE not supported in this environment");
+      throw new AvbridgeError(
+        ERR_MSE_NOT_SUPPORTED,
+        "MediaSource Extensions (MSE) are not supported in this environment.",
+        "MSE is required for the remux strategy. Use a browser that supports MSE, or try the fallback strategy."
+      );
     }
     if (!MediaSource.isTypeSupported(options.mime)) {
-      throw new Error(`MSE does not support MIME "${options.mime}" \u2014 cannot remux`);
+      throw new AvbridgeError(
+        ERR_MSE_CODEC_NOT_SUPPORTED,
+        `This browser's MSE does not support "${options.mime}".`,
+        "The codec combination can't be played via remux in this browser. The player will try the next strategy automatically."
+      );
     }
     this.mediaSource = new MediaSource();
     this.objectUrl = URL.createObjectURL(this.mediaSource);
@@ -32065,6 +32172,10 @@ async function createRemuxSession(context, video) {
 }
 
 // src/strategies/fallback/video-renderer.ts
+function isDebug() {
+  return typeof globalThis !== "undefined" && !!globalThis.AVBRIDGE_DEBUG;
+}
+var lastDebugLog = 0;
 var VideoRenderer = class {
   constructor(target, clock, fps = 30) {
     this.target = target;
@@ -32111,6 +32222,20 @@ var VideoRenderer = class {
   lastPaintWall = 0;
   /** Minimum ms between paints — paces video at roughly source fps. */
   paintIntervalMs;
+  /** Cumulative count of frames skipped because all PTS are in the future. */
+  ticksWaiting = 0;
+  /** Cumulative count of ticks where PTS mode painted a frame. */
+  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.
+   */
+  ptsCalibrationUs = 0;
+  ptsCalibrated = false;
+  lastCalibrationWall = 0;
   /** Resolves once the first decoded frame has been enqueued. */
   firstFrameReady;
   resolveFirstFrame;
@@ -32159,21 +32284,81 @@ var VideoRenderer = class {
       }
       return;
     }
-    const wallNow = performance.now();
-    if (wallNow - this.lastPaintWall < this.paintIntervalMs - 2) return;
-    if (this.queue.length === 0) return;
-    if (this.framesPainted > 0 && this.framesPainted % 30 === 0) {
-      const audioNowUs = this.clock.now() * 1e6;
-      const headTs = this.queue[0].timestamp ?? 0;
-      const driftUs = headTs - audioNowUs;
-      if (driftUs < -15e4) {
-        this.queue.shift()?.close();
-        this.framesDroppedLate++;
-        if (this.queue.length === 0) return;
-      } else if (driftUs > 15e4) {
+    const rawAudioNowUs = this.clock.now() * 1e6;
+    const headTs = this.queue[0].timestamp ?? 0;
+    const hasPts = headTs > 0 || this.queue.length > 1;
+    if (hasPts) {
+      const wallNow2 = performance.now();
+      if (!this.ptsCalibrated || wallNow2 - this.lastCalibrationWall > 1e4) {
+        this.ptsCalibrationUs = headTs - rawAudioNowUs;
+        this.ptsCalibrated = true;
+        this.lastCalibrationWall = wallNow2;
+      }
+      const audioNowUs = rawAudioNowUs + this.ptsCalibrationUs;
+      const frameDurationUs = this.paintIntervalMs * 1e3;
+      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;
+        }
+      }
+      if (bestIdx < 0) {
+        this.ticksWaiting++;
+        if (isDebug()) {
+          const now = performance.now();
+          if (now - lastDebugLog > 1e3) {
+            const headPtsMs = (headTs / 1e3).toFixed(1);
+            const audioMs = (audioNowUs / 1e3).toFixed(1);
+            const rawDriftMs = ((headTs - rawAudioNowUs) / 1e3).toFixed(1);
+            const calibMs = (this.ptsCalibrationUs / 1e3).toFixed(1);
+            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;
       }
+      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 > 1e3) {
+          const paintedTs = this.queue[0]?.timestamp ?? 0;
+          const audioMs = (audioNowUs / 1e3).toFixed(1);
+          const ptsMs = (paintedTs / 1e3).toFixed(1);
+          const rawDriftMs = ((paintedTs - rawAudioNowUs) / 1e3).toFixed(1);
+          const calibMs = (this.ptsCalibrationUs / 1e3).toFixed(1);
+          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 frame2 = this.queue.shift();
+      this.paint(frame2);
+      frame2.close();
+      this.lastPaintWall = performance.now();
+      return;
     }
+    const wallNow = performance.now();
+    if (wallNow - this.lastPaintWall < this.paintIntervalMs - 2) return;
     const frame = this.queue.shift();
     this.paint(frame);
     frame.close();
@@ -32195,8 +32380,13 @@ var VideoRenderer = class {
   }
   /** Discard all queued frames. Used by seek to drop stale buffers. */
   flush() {
+    const count = this.queue.length;
     while (this.queue.length > 0) this.queue.shift()?.close();
     this.prerolled = false;
+    this.ptsCalibrated = false;
+    if (isDebug() && count > 0) {
+      console.log(`[avbridge:renderer] FLUSH discarded=${count} painted=${this.framesPainted} drops=${this.framesDroppedLate}`);
+    }
   }
   stats() {
     return {
@@ -32241,11 +32431,38 @@ var AudioOutput = class {
   pendingQueue = [];
   framesScheduled = 0;
   destroyed = false;
+  /** User-set volume (0..1). Applied to the gain node. */
+  _volume = 1;
+  /** User-set muted flag. When true, gain is forced to 0. */
+  _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) {
+    this._volume = Math.max(0, Math.min(1, v));
+    this.applyGain();
+  }
+  getVolume() {
+    return this._volume;
+  }
+  /** Set muted. When true, output is silenced regardless of volume. */
+  setMuted(m) {
+    this._muted = m;
+    this.applyGain();
+  }
+  getMuted() {
+    return this._muted;
+  }
+  applyGain() {
+    const target = this._muted ? 0 : this._volume;
+    try {
+      this.gain.gain.value = target;
+    } catch {
+    }
+  }
   /**
    * Switch into wall-clock fallback mode. Called by the decoder when no
    * audio decoder could be initialized for the source. Once set, this
@@ -32395,6 +32612,7 @@ var AudioOutput = class {
     }
     this.gain = this.ctx.createGain();
     this.gain.connect(this.ctx.destination);
+    this.applyGain();
     this.pendingQueue = [];
     this.mediaTimeOfAnchor = newMediaTime;
     this.mediaTimeOfNext = newMediaTime;
@@ -32423,27 +32641,19 @@ var AudioOutput = class {
 
 // src/strategies/hybrid/decoder.ts
 init_libav_loader();
+init_debug();
 
 // src/strategies/fallback/variant-routing.ts
 var LEGACY_CONTAINERS = /* @__PURE__ */ new Set(["avi", "asf", "flv"]);
-var LEGACY_VIDEO_CODECS = /* @__PURE__ */ new Set([
-  "wmv3",
-  "vc1",
-  "mpeg4",
-  // MPEG-4 Part 2 / DivX / Xvid
-  "rv40",
-  "mpeg2",
-  "mpeg1",
-  "theora"
-]);
-var LEGACY_AUDIO_CODECS = /* @__PURE__ */ new Set(["wmav2", "wmapro", "ac3", "eac3"]);
+var WEBCODECS_AUDIO = /* @__PURE__ */ new Set(["aac", "mp3", "opus", "vorbis", "flac"]);
+var WEBCODECS_VIDEO = /* @__PURE__ */ new Set(["h264", "h265", "vp8", "vp9", "av1"]);
 function pickLibavVariant(ctx) {
   if (LEGACY_CONTAINERS.has(ctx.container)) return "avbridge";
   for (const v of ctx.videoTracks) {
-    if (LEGACY_VIDEO_CODECS.has(v.codec)) return "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";
 }
@@ -32454,7 +32664,7 @@ async function startHybridDecoder(opts) {
   const libav = await loadLibav(variant);
   const bridge = await loadBridge();
   const { prepareLibavInput: prepareLibavInput2 } = await Promise.resolve().then(() => (init_libav_http_reader(), libav_http_reader_exports));
-  const inputHandle = await prepareLibavInput2(libav, opts.filename, opts.source);
+  const inputHandle = await prepareLibavInput2(libav, 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);
   const videoStream = streams.find((s) => s.codec_type === libav.AVMEDIA_TYPE_VIDEO) ?? null;
@@ -32525,6 +32735,56 @@ async function startHybridDecoder(opts) {
     });
     throw new Error("hybrid decoder: could not initialize any decoders");
   }
+  let bsfCtx = null;
+  let bsfPkt = 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 {
+        console.warn("[avbridge] mpeg4_unpack_bframes BSF not available in hybrid decoder");
+        bsfCtx = null;
+      }
+    } catch (err) {
+      console.warn("[avbridge] hybrid: failed to init BSF:", err.message);
+      bsfCtx = null;
+      bsfPkt = null;
+    }
+  }
+  async function applyBSF(packets) {
+    if (!bsfCtx || !bsfPkt) return packets;
+    const out = [];
+    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() {
+    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 {
+    }
+  }
   let destroyed = false;
   let pumpToken = 0;
   let pumpRunning = null;
@@ -32552,8 +32812,15 @@ async function startHybridDecoder(opts) {
       if (myToken !== pumpToken || destroyed) return;
       const videoPackets = videoStream ? packets[videoStream.index] : void 0;
       const audioPackets = audioStream ? packets[audioStream.index] : void 0;
+      if (audioDec && audioPackets && audioPackets.length > 0) {
+        await decodeAudioBatch(audioPackets, myToken);
+      }
+      if (myToken !== pumpToken || destroyed) return;
+      await new Promise((r) => setTimeout(r, 0));
+      if (myToken !== pumpToken || destroyed) return;
       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;
@@ -32573,9 +32840,6 @@ async function startHybridDecoder(opts) {
           }
         }
       }
-      if (audioDec && audioPackets && audioPackets.length > 0) {
-        await decodeAudioBatch(audioPackets, myToken);
-      }
       packetsRead += (videoPackets?.length ?? 0) + (audioPackets?.length ?? 0);
       while (!destroyed && myToken === pumpToken && (videoDecoder && videoDecoder.decodeQueueSize > 10 || opts.audio.bufferAhead() > 2 || opts.renderer.queueDepth() >= opts.renderer.queueHighWater)) {
         await new Promise((r) => setTimeout(r, 50));
@@ -32598,20 +32862,43 @@ async function startHybridDecoder(opts) {
   }
   async function decodeAudioBatch(pkts, myToken, flush = false) {
     if (!audioDec || destroyed || myToken !== pumpToken) return;
-    let frames;
-    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;
+    const AUDIO_SUB_BATCH = 4;
+    let allFrames = [];
+    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 frames2 = await libav.ff_decode_multi(
+          audioDec.c,
+          audioDec.pkt,
+          audioDec.frame,
+          slice,
+          isLast && flush ? { fin: true, ignoreErrors: true } : { ignoreErrors: true }
+        );
+        allFrames = allFrames.concat(frames2);
+      } catch (err) {
+        console.error("[avbridge] hybrid audio decode failed:", err);
+        return;
+      }
+      if (!isLast) await new Promise((r) => setTimeout(r, 0));
+    }
+    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;
       sanitizeFrameTimestamp(
@@ -32648,6 +32935,14 @@ async function startHybridDecoder(opts) {
         await pumpRunning;
       } catch {
       }
+      try {
+        if (bsfCtx) await libav.av_bsf_free(bsfCtx);
+      } catch {
+      }
+      try {
+        if (bsfPkt) await libav.av_packet_free?.(bsfPkt);
+      } catch {
+      }
       try {
         if (videoDecoder && videoDecoder.state !== "closed") videoDecoder.close();
       } catch {
@@ -32701,6 +32996,7 @@ async function startHybridDecoder(opts) {
         if (audioDec) await libav.avcodec_flush_buffers?.(audioDec.c);
       } catch {
       }
+      await flushBSF();
       syntheticVideoUs = Math.round(timeSec * 1e6);
       syntheticAudioUs = Math.round(timeSec * 1e6);
       pumpRunning = pumpLoop(newToken).catch(
@@ -32714,6 +33010,7 @@ async function startHybridDecoder(opts) {
         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",
@@ -32890,7 +33187,7 @@ async function loadBridge() {
 // src/strategies/hybrid/index.ts
 var READY_AUDIO_BUFFER_SECONDS = 0.3;
 var READY_TIMEOUT_SECONDS = 10;
-async function createHybridSession(ctx, target) {
+async function createHybridSession(ctx, target, transport) {
   const { normalizeSource: normalizeSource2 } = await Promise.resolve().then(() => (init_source(), source_exports));
   const source = await normalizeSource2(ctx.source);
   const fps = ctx.videoTracks[0]?.fps ?? 30;
@@ -32903,7 +33200,8 @@ async function createHybridSession(ctx, target) {
       filename: ctx.name ?? "input.bin",
       context: ctx,
       renderer,
-      audio
+      audio,
+      transport
     });
   } catch (err) {
     audio.destroy();
@@ -32921,6 +33219,22 @@ async function createHybridSession(ctx, target) {
     configurable: true,
     get: () => !audio.isPlaying()
   });
+  Object.defineProperty(target, "volume", {
+    configurable: true,
+    get: () => audio.getVolume(),
+    set: (v) => {
+      audio.setVolume(v);
+      target.dispatchEvent(new Event("volumechange"));
+    }
+  });
+  Object.defineProperty(target, "muted", {
+    configurable: true,
+    get: () => audio.getMuted(),
+    set: (m) => {
+      audio.setMuted(m);
+      target.dispatchEvent(new Event("volumechange"));
+    }
+  });
   if (ctx.duration && Number.isFinite(ctx.duration)) {
     Object.defineProperty(target, "duration", {
       configurable: true,
@@ -32960,10 +33274,13 @@ async function createHybridSession(ctx, target) {
       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) {
       await doSeek(time);
@@ -32986,6 +33303,8 @@ async function createHybridSession(ctx, target) {
         delete target.currentTime;
         delete target.duration;
         delete target.paused;
+        delete target.volume;
+        delete target.muted;
       } catch {
       }
     },
@@ -32997,12 +33316,13 @@ async function createHybridSession(ctx, target) {
 
 // src/strategies/fallback/decoder.ts
 init_libav_loader();
+init_debug();
 async function startDecoder(opts) {
   const variant = pickLibavVariant(opts.context);
   const libav = await loadLibav(variant);
   const bridge = await loadBridge2();
   const { prepareLibavInput: prepareLibavInput2 } = await Promise.resolve().then(() => (init_libav_http_reader(), libav_http_reader_exports));
-  const inputHandle = await prepareLibavInput2(libav, opts.filename, opts.source);
+  const inputHandle = await prepareLibavInput2(libav, 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);
   const videoStream = streams.find((s) => s.codec_type === libav.AVMEDIA_TYPE_VIDEO) ?? null;
@@ -33058,6 +33378,56 @@ async function startDecoder(opts) {
       `fallback decoder: could not initialize any libav decoders (${codecs}).${hint}`
     );
   }
+  let bsfCtx = null;
+  let bsfPkt = 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 {
+        console.warn("[avbridge] mpeg4_unpack_bframes BSF not available \u2014 decoding without it");
+        bsfCtx = null;
+      }
+    } catch (err) {
+      console.warn("[avbridge] failed to init mpeg4_unpack_bframes BSF:", err.message);
+      bsfCtx = null;
+      bsfPkt = null;
+    }
+  }
+  async function applyBSF(packets) {
+    if (!bsfCtx || !bsfPkt) return packets;
+    const out = [];
+    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() {
+    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 {
+    }
+  }
   let destroyed = false;
   let pumpToken = 0;
   let pumpRunning = null;
@@ -33093,7 +33463,8 @@ async function startDecoder(opts) {
       }
       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);
       if (videoFramesDecoded > 0) {
@@ -33239,6 +33610,14 @@ async function startDecoder(opts) {
         await pumpRunning;
       } catch {
       }
+      try {
+        if (bsfCtx) await libav.av_bsf_free(bsfCtx);
+      } catch {
+      }
+      try {
+        if (bsfPkt) await libav.av_packet_free?.(bsfPkt);
+      } catch {
+      }
       try {
         if (videoDec) await libav.ff_free_decoder?.(videoDec.c, videoDec.pkt, videoDec.frame);
       } catch {
@@ -33290,6 +33669,7 @@ async function startDecoder(opts) {
         if (audioDec) await libav.avcodec_flush_buffers?.(audioDec.c);
       } catch {
       }
+      await flushBSF();
       syntheticVideoUs = Math.round(timeSec * 1e6);
       syntheticAudioUs = Math.round(timeSec * 1e6);
       pumpRunning = pumpLoop(newToken).catch(
@@ -33302,6 +33682,7 @@ async function startDecoder(opts) {
         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
@@ -33458,7 +33839,7 @@ async function loadBridge2() {
 init_debug();
 var READY_AUDIO_BUFFER_SECONDS2 = 0.04;
 var READY_TIMEOUT_SECONDS2 = 3;
-async function createFallbackSession(ctx, target) {
+async function createFallbackSession(ctx, target, transport) {
   const { normalizeSource: normalizeSource2 } = await Promise.resolve().then(() => (init_source(), source_exports));
   const source = await normalizeSource2(ctx.source);
   const fps = ctx.videoTracks[0]?.fps ?? 30;
@@ -33471,7 +33852,8 @@ async function createFallbackSession(ctx, target) {
       filename: ctx.name ?? "input.bin",
       context: ctx,
       renderer,
-      audio
+      audio,
+      transport
     });
   } catch (err) {
     audio.destroy();
@@ -33489,6 +33871,22 @@ async function createFallbackSession(ctx, target) {
     configurable: true,
     get: () => !audio.isPlaying()
   });
+  Object.defineProperty(target, "volume", {
+    configurable: true,
+    get: () => audio.getVolume(),
+    set: (v) => {
+      audio.setVolume(v);
+      target.dispatchEvent(new Event("volumechange"));
+    }
+  });
+  Object.defineProperty(target, "muted", {
+    configurable: true,
+    get: () => audio.getMuted(),
+    set: (m) => {
+      audio.setMuted(m);
+      target.dispatchEvent(new Event("volumechange"));
+    }
+  });
   if (ctx.duration && Number.isFinite(ctx.duration)) {
     Object.defineProperty(target, "duration", {
       configurable: true,
@@ -33552,10 +33950,13 @@ async function createFallbackSession(ctx, target) {
       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) {
       await doSeek(time);
@@ -33575,6 +33976,8 @@ async function createFallbackSession(ctx, target) {
         delete target.currentTime;
         delete target.duration;
         delete target.paused;
+        delete target.volume;
+        delete target.muted;
       } catch {
       }
     },
@@ -33598,12 +34001,12 @@ var remuxPlugin = {
 var hybridPlugin = {
   name: "hybrid",
   canHandle: () => typeof VideoDecoder !== "undefined",
-  execute: (ctx, video) => createHybridSession(ctx, video)
+  execute: (ctx, video, transport) => createHybridSession(ctx, video, transport)
 };
 var fallbackPlugin = {
   name: "fallback",
   canHandle: () => true,
-  execute: (ctx, video) => createFallbackSession(ctx, video)
+  execute: (ctx, video, transport) => createFallbackSession(ctx, video, transport)
 };
 function registerBuiltins(registry) {
   registry.register(nativePlugin);
@@ -33612,6 +34015,9 @@ function registerBuiltins(registry) {
   registry.register(fallbackPlugin);
 }
 
+// src/subtitles/index.ts
+init_transport();
+
 // src/subtitles/srt.ts
 function srtToVtt(srt) {
   if (srt.charCodeAt(0) === 65279) srt = srt.slice(1);
@@ -33689,7 +34095,8 @@ var SubtitleResourceBag = class {
     this.urls.clear();
   }
 };
-async function attachSubtitleTracks(video, tracks, bag, onError) {
+async function attachSubtitleTracks(video, tracks, bag, onError, transport) {
+  const doFetch = fetchWith(transport);
   for (const t of Array.from(video.querySelectorAll("track[data-avbridge]"))) {
     t.remove();
   }
@@ -33698,13 +34105,13 @@ async function attachSubtitleTracks(video, tracks, bag, onError) {
     try {
       let url2 = t.sidecarUrl;
       if (t.format === "srt") {
-        const res = await fetch(t.sidecarUrl);
+        const res = await doFetch(t.sidecarUrl, transport?.requestInit);
         const text = await res.text();
         const vtt = srtToVtt(text);
         const blob = new Blob([vtt], { type: "text/vtt" });
         url2 = bag ? bag.createObjectURL(blob) : URL.createObjectURL(blob);
       } else if (t.format === "vtt") {
-        const res = await fetch(t.sidecarUrl);
+        const res = await doFetch(t.sidecarUrl, transport?.requestInit);
         const text = await res.text();
         if (!isVtt(text)) {
           console.warn("[avbridge] subtitle missing WEBVTT header:", t.sidecarUrl);
@@ -33726,6 +34133,7 @@ async function attachSubtitleTracks(video, tracks, bag, onError) {
 
 // src/player.ts
 init_debug();
+init_errors();
 var UnifiedPlayer = class _UnifiedPlayer {
   /**
    * @internal Use {@link createPlayer} or {@link UnifiedPlayer.create} instead.
@@ -33733,6 +34141,10 @@ var UnifiedPlayer = class _UnifiedPlayer {
   constructor(options, registry) {
     this.options = options;
     this.registry = registry;
+    const { requestInit, fetchFn } = options;
+    if (requestInit || fetchFn) {
+      this.transport = { requestInit, fetchFn };
+    }
   }
   options;
   registry;
@@ -33752,11 +34164,23 @@ var UnifiedPlayer = class _UnifiedPlayer {
   // listener outlives the player and accumulates on elements that swap
   // source (e.g. <avbridge-video>).
   endedListener = 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).
+  userIntent = "pause";
+  autoPausedForVisibility = false;
+  visibilityListener = null;
   // Serializes escalation / setStrategy calls
   switchingPromise = Promise.resolve();
   // Owns blob URLs created during sidecar discovery + SRT->VTT conversion.
   // Revoked at destroy() so repeated source swaps don't leak.
   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.
+  transport;
   static async create(options) {
     const registry = new PluginRegistry();
     registerBuiltins(registry);
@@ -33780,7 +34204,7 @@ var UnifiedPlayer = class _UnifiedPlayer {
     const bootstrapStart = performance.now();
     try {
       dbg.info("bootstrap", "start");
-      const ctx = await dbg.timed("probe", "probe", 3e3, () => probe(this.options.source));
+      const ctx = await dbg.timed("probe", "probe", 3e3, () => 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}`
@@ -33828,7 +34252,8 @@ var UnifiedPlayer = class _UnifiedPlayer {
           this.subtitleResources,
           (err, track) => {
             console.warn(`[avbridge] subtitle ${track.id} failed: ${err.message}`);
-          }
+          },
+          this.transport
         );
       }
       this.emitter.emitSticky("tracks", {
@@ -33839,6 +34264,10 @@ var UnifiedPlayer = class _UnifiedPlayer {
       this.startTimeupdateLoop();
       this.endedListener = () => this.emitter.emit("ended", void 0);
       this.options.target.addEventListener("ended", this.endedListener);
+      if (this.options.backgroundBehavior !== "continue" && typeof document !== "undefined") {
+        this.visibilityListener = () => this.onVisibilityChange();
+        document.addEventListener("visibilitychange", this.visibilityListener);
+      }
       this.emitter.emitSticky("ready", void 0);
       const bootstrapElapsed = performance.now() - bootstrapStart;
       dbg.info("bootstrap", `ready in ${bootstrapElapsed.toFixed(0)}ms`);
@@ -33865,7 +34294,7 @@ var UnifiedPlayer = class _UnifiedPlayer {
       throw new Error(`no plugin available for strategy "${strategy}"`);
     }
     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 chain2 = this.classification?.fallbackChain;
       if (chain2 && chain2.length > 0) {
@@ -33938,7 +34367,7 @@ var UnifiedPlayer = class _UnifiedPlayer {
         continue;
       }
       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}`);
@@ -33961,8 +34390,10 @@ var UnifiedPlayer = class _UnifiedPlayer {
       }
       return;
     }
-    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."
     ));
   }
   // ── Stall supervision ─────────────────────────────────────────────────
@@ -34014,7 +34445,7 @@ var UnifiedPlayer = class _UnifiedPlayer {
   // ── Public: manual strategy switch ────────────────────────────────────
   /** Manually switch to a different playback strategy. Preserves current position and play/pause state. Concurrent calls are serialized. */
   async setStrategy(strategy, reason) {
-    if (!this.mediaContext) throw new Error("player not ready");
+    if (!this.mediaContext) throw new AvbridgeError(ERR_PLAYER_NOT_READY, "Player not ready \u2014 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(
       () => this.doSetStrategy(strategy, reason)
@@ -34043,7 +34474,7 @@ var UnifiedPlayer = 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,
       reason: switchReason
@@ -34077,26 +34508,56 @@ var UnifiedPlayer = class _UnifiedPlayer {
   }
   /** Begin or resume playback. Throws if the player is not ready. */
   async play() {
-    if (!this.session) throw new Error("player not ready");
+    if (!this.session) throw new AvbridgeError(ERR_PLAYER_NOT_READY, "Player not ready \u2014 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() {
+    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).
+   */
+  onVisibilityChange() {
+    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 \u2014 auto-paused");
+      this.session.pause();
+    } else if (action === "resume") {
+      this.autoPausedForVisibility = false;
+      dbg.info("visibility", "tab visible \u2014 auto-resuming");
+      void this.session.play().catch((err) => {
+        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) {
-    if (!this.session) throw new Error("player not ready");
+    if (!this.session) throw new AvbridgeError(ERR_PLAYER_NOT_READY, "Player not ready \u2014 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) {
-    if (!this.session) throw new Error("player not ready");
+    if (!this.session) throw new AvbridgeError(ERR_PLAYER_NOT_READY, "Player not ready \u2014 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) {
-    if (!this.session) throw new Error("player not ready");
+    if (!this.session) throw new AvbridgeError(ERR_PLAYER_NOT_READY, "Player not ready \u2014 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);
   }
   /** Return a snapshot of current diagnostics: container, codecs, strategy, runtime stats, and strategy history. */
@@ -34128,6 +34589,10 @@ var UnifiedPlayer = class _UnifiedPlayer {
       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;
@@ -34139,6 +34604,14 @@ var UnifiedPlayer = class _UnifiedPlayer {
 async function createPlayer(options) {
   return UnifiedPlayer.create(options);
 }
+function decideVisibilityAction(state) {
+  if (state.hidden) {
+    if (state.userIntent === "play" && state.sessionIsPlaying) return "pause";
+    return "noop";
+  }
+  if (state.autoPausedForVisibility) return "resume";
+  return "noop";
+}
 function buildInitialDecision(initial, ctx) {
   const natural = classifyContext(ctx);
   const cls = strategyToClass(initial, natural);