avbridge 2.11.0 → 2.12.1

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

@@ -141,11 +141,22 @@ export class VideoRenderer {
     this.rafHandle = requestAnimationFrame(this.tick);
   }
 
-  /** True once at least one frame has been enqueued. */
+  /**
+   * True once at least one frame has been enqueued *since the last flush*.
+   * Used by `readyState` — initial cold-start reports HAVE_NOTHING until
+   * any frame has arrived, and after a seek we want the same semantics
+   * (HAVE_NOTHING until post-seek frames arrive), so the cumulative
+   * `framesPainted > 0` that used to live here was wrong: it kept the
+   * state "true forever" after the first frame ever, so post-seek
+   * `waitForBuffer()` would exit immediately with an empty queue and
+   * leave video frozen while audio kept going.
+   */
   hasFrames(): boolean {
-    return this.queue.length > 0 || this.framesPainted > 0;
+    return this.queue.length > 0 || this.hasEverEnqueuedSinceFlush;
   }
 
+  private hasEverEnqueuedSinceFlush = false;
+
   /** Current depth of the frame queue. Used by the decoder for backpressure. */
   queueDepth(): number {
     return this.queue.length;
@@ -166,6 +177,7 @@ export class VideoRenderer {
       return;
     }
     this.queue.push(frame);
+    this.hasEverEnqueuedSinceFlush = true;
     if (this.queue.length === 1 && this.framesPainted === 0) {
       this.resolveFirstFrame();
     }
@@ -342,7 +354,16 @@ export class VideoRenderer {
       }
 
       // Only drop frames that are more than 2 frame-durations behind.
-      const dropThresholdUs = audioNowUs - frameDurationUs * 2;
+      // Diagnostic escape hatch: `globalThis.AVBRIDGE_RELAX_DROP = true`
+      // pushes the threshold so far back that frames are effectively
+      // never dropped as late. The display will run behind the audio
+      // clock but won't stutter from drop bursts. Useful for isolating
+      // "is the problem decode throughput or drop policy?".
+      const _relaxDrop =
+        (globalThis as { AVBRIDGE_RELAX_DROP?: boolean }).AVBRIDGE_RELAX_DROP === true;
+      const dropThresholdUs = _relaxDrop
+        ? audioNowUs - 60 * 1_000_000 /* 60 s */
+        : audioNowUs - frameDurationUs * 2;
       let dropped = 0;
       while (bestIdx > 0) {
         const ts = this.queue[0].timestamp ?? 0;
@@ -419,6 +440,7 @@ export class VideoRenderer {
     while (this.queue.length > 0) this.queue.shift()?.close();
     this.prerolled = false;
     this.ptsCalibrated = false; // recalibrate at new seek position
+    this.hasEverEnqueuedSinceFlush = false; // so waitForBuffer() waits for post-flush frames
     if (isDebug() && count > 0) {
       // eslint-disable-next-line no-console
       console.log(`[avbridge:renderer] FLUSH discarded=${count} painted=${this.framesPainted} drops=${this.framesDroppedLate}`);
@@ -426,11 +448,27 @@ export class VideoRenderer {
   }
 
   stats(): Record<string, unknown> {
+    // Queue span — the gap between the oldest and newest queued frame's
+    // PTS, in ms. If this collapses while audio keeps advancing, the
+    // producer has stalled. If it stays wide with stale head, the
+    // producer is bursting faster than realtime but the renderer can't
+    // catch up.
+    let queueSpanMs = 0;
+    let queueHeadMs = 0;
+    let queueTailMs = 0;
+    if (this.queue.length > 0) {
+      queueHeadMs = Math.round((this.queue[0].timestamp ?? 0) / 1000);
+      queueTailMs = Math.round((this.queue[this.queue.length - 1].timestamp ?? 0) / 1000);
+      queueSpanMs = Math.max(0, queueTailMs - queueHeadMs);
+    }
     return {
       framesPainted: this.framesPainted,
       framesDroppedLate: this.framesDroppedLate,
       framesDroppedOverflow: this.framesDroppedOverflow,
       queueDepth: this.queue.length,
+      queueHeadMs,
+      queueTailMs,
+      queueSpanMs,
     };
   }
 

package/src/strategies/hybrid/decoder.ts

@@ -165,6 +165,7 @@ export async function startHybridDecoder(opts: StartHybridDecoderOptions): Promi
   // ── Bitstream filter for MPEG-4 Part 2 packed B-frames ───────────────
   let bsfCtx: number | null = null;
   let bsfPkt: number | null = null;
+  let bsfRequiredButMissing = false;
   if (videoStream && opts.context.videoTracks[0]?.codec === "mpeg4") {
     try {
       bsfCtx = await libav.av_bsf_list_parse_str_js("mpeg4_unpack_bframes");
@@ -175,15 +176,23 @@ export async function startHybridDecoder(opts: StartHybridDecoderOptions): Promi
         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");
+        bsfRequiredButMissing = true;
         bsfCtx = null;
       }
     } catch (err) {
-      // eslint-disable-next-line no-console
-      console.warn("[avbridge] hybrid: failed to init BSF:", (err as Error).message);
+      bsfRequiredButMissing = true;
       bsfCtx = null;
       bsfPkt = null;
+      dbg.warn("bsf", `hybrid: mpeg4_unpack_bframes BSF init failed: ${(err as Error).message}`);
+    }
+    if (bsfRequiredButMissing) {
+      // eslint-disable-next-line no-console
+      console.error(
+        "[avbridge] MPEG-4 Part 2 (DivX/Xvid) detected but mpeg4_unpack_bframes " +
+        "BSF is unavailable in this libav variant. Files with packed B-frames " +
+        "will play with incorrect frame ordering. Rebuild the libav variant " +
+        "with the `avbsf` fragment included.",
+      );
     }
   }
 
@@ -193,7 +202,13 @@ export async function startHybridDecoder(opts: StartHybridDecoderOptions): Promi
     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; }
+      if (sendErr < 0) {
+        // BSF rejected — DON'T pass the original through. Its buffer may
+        // have been transferred into the worker by ff_copyin_packet, so
+        // re-posting it would throw DataCloneError on a detached
+        // ArrayBuffer. See fallback/decoder.ts for the full explanation.
+        continue;
+      }
       while (true) {
         const recvErr = await libav.av_bsf_receive_packet(bsfCtx, bsfPkt);
         if (recvErr < 0) break;
@@ -206,10 +221,18 @@ export async function startHybridDecoder(opts: StartHybridDecoderOptions): Promi
   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;
+      // Use av_bsf_flush to reset the BSF without putting it in EOF mode.
+      // See the matching comment in src/strategies/fallback/decoder.ts —
+      // sending NULL as the flush signal puts the BSF into EOF state so
+      // subsequent sends fail, which corrupts the post-seek pipeline with
+      // detached-buffer DataCloneErrors.
+      if (libav.av_bsf_flush) {
+        await libav.av_bsf_flush(bsfCtx);
+      } else {
+        while (true) {
+          const err = await libav.av_bsf_receive_packet(bsfCtx, bsfPkt);
+          if (err < 0) break;
+        }
       }
     } catch { /* ignore */ }
   }
@@ -562,6 +585,7 @@ export async function startHybridDecoder(opts: StartHybridDecoderOptions): Promi
         videoChunksFed,
         audioFramesDecoded,
         bsfApplied: bsfCtx ? ["mpeg4_unpack_bframes"] : [],
+        bsfMissing: bsfRequiredButMissing ? ["mpeg4_unpack_bframes"] : [],
         videoDecodeQueueSize: videoDecoder?.decodeQueueSize ?? 0,
         // Confirmed transport info — see fallback decoder for the pattern.
         _transport: inputHandle.transport === "http-range" ? "http-range" : "memory",
@@ -687,6 +711,7 @@ interface LibavRuntime {
   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_flush?(ctx: number): Promise<void>;
   av_bsf_free(ctx: number): Promise<void>;
   ff_copyin_packet(pktPtr: number, packet: LibavPacket): Promise<void>;
   ff_copyout_packet(pkt: number): Promise<LibavPacket>;

package/src/types.ts

@@ -287,6 +287,14 @@ export interface CreatePlayerOptions {
    * for interceptors, logging, or environments without a global fetch.
    */
   fetchFn?: FetchFn;
+  /**
+   * Byte budget for the libav HTTP reader's LRU cache of fetched ranges.
+   * Defaults to 8 MB. Set to `0` to disable caching. Raise this when the
+   * app plays seek-heavy legacy-container media from URLs — hot regions
+   * (header/moov, tail index, current window) stay resident instead of
+   * being re-fetched on every bounce.
+   */
+  cacheBytes?: number;
 }
 
 /** Signature-compatible with `globalThis.fetch`. */
@@ -296,6 +304,13 @@ export type FetchFn = (input: RequestInfo | URL, init?: RequestInit) => Promise<
 export interface TransportConfig {
   requestInit?: RequestInit;
   fetchFn?: FetchFn;
+  /**
+   * Byte budget for the libav HTTP reader's LRU cache of fetched ranges.
+   * Defaults to 8 MB. Set to `0` to disable caching entirely. Higher
+   * values help seek-heavy network playback keep hot regions
+   * (header/moov, tail index, current read) resident.
+   */
+  cacheBytes?: number;
 }
 
 /** Events emitted by {@link UnifiedPlayer}. Strongly typed. */

package/src/util/libav-http-reader.ts

@@ -32,8 +32,13 @@
  *   clamped to `[256 KB, 1 MB]`. Small reads get amortized; pathological
  *   large requests don't OOM us.
  *
- * - **Last-block cache.** Only the most-recent fetched block is kept.
- *   Re-fetches via Range are cheap; an LRU cache is post-1.0.
+ * - **LRU block cache.** Fetched blocks are kept in a Map keyed by start
+ *   position, bounded by a byte budget (default 8 MB, configurable via
+ *   `cacheBytes`). Map insertion order doubles as recency; re-accessing
+ *   a block promotes it via delete+set. Eviction walks oldest-first
+ *   until total bytes fit the budget. Typical seek pattern has three
+ *   hot regions — header/moov at the front, index at the tail, current
+ *   read position — all of which fit comfortably under the default.
  *
  * - **Safe detach.** `detach()` clears `libav.onblockread`, sets a
  *   destroyed flag, and ignores any in-flight fetch resolutions so we
@@ -42,6 +47,7 @@
 
 const MIN_READ = 256 * 1024;
 const MAX_READ = 1 * 1024 * 1024;
+const DEFAULT_CACHE_BYTES = 8 * 1024 * 1024;
 
 interface LibavLike {
   mkblockreaderdev(name: string, size: number): Promise<void>;
@@ -69,6 +75,12 @@ export interface AttachLibavHttpReaderOptions {
   requestInit?: RequestInit;
   /** Override fetch (for testing). Defaults to globalThis.fetch. */
   fetchFn?: typeof fetch;
+  /**
+   * Byte budget for the LRU block cache. Defaults to 8 MB. Set to `0`
+   * to disable caching. Raise this (e.g. 32 MB) for apps that play
+   * seek-heavy legacy-container media over the network.
+   */
+  cacheBytes?: number;
 }
 
 /**
@@ -108,6 +120,7 @@ export async function prepareLibavInput(
     const handle = await attachLibavHttpReader(libav, filename, source.url, {
       requestInit: transport?.requestInit,
       fetchFn: transport?.fetchFn,
+      cacheBytes: transport?.cacheBytes,
     });
     return {
       filename,
@@ -192,9 +205,12 @@ export async function attachLibavHttpReader(
   // ── State ───────────────────────────────────────────────────────────────
 
   let detached = false;
-  // Most-recently fetched block. Cached so re-reads of the same region
-  // (e.g. demuxer re-walks the header) don't issue another HTTP request.
-  let cached: { pos: number; bytes: Uint8Array } | null = null;
+  // LRU cache of fetched blocks, keyed by start position. Map insertion
+  // order = recency. Bounded by `cacheBudget` bytes; evicts oldest-first
+  // on overflow. Set budget to 0 to disable caching.
+  const cache = new Map<number, Uint8Array>();
+  let cacheBytes = 0;
+  const cacheBudget = Math.max(0, options.cacheBytes ?? DEFAULT_CACHE_BYTES);
   // The currently in-flight fetch, if any. Used both for serialization
   // (we await this before starting another) and for in-flight dedup.
   let inflight: Promise<void> | null = null;
@@ -206,17 +222,39 @@ export async function attachLibavHttpReader(
     return doubled;
   }
 
-  /** True if the cached block fully covers `[pos, pos+length)`. */
-  function cacheCovers(pos: number, length: number): boolean {
-    if (!cached) return false;
-    return pos >= cached.pos && pos + length <= cached.pos + cached.bytes.byteLength;
+  /**
+   * Look up a cached block that fully covers `[pos, pos+length)`. On hit,
+   * promote the block to most-recent and return the slice. On miss, null.
+   */
+  function cacheLookup(pos: number, length: number): Uint8Array | null {
+    for (const [blockPos, bytes] of cache) {
+      if (pos >= blockPos && pos + length <= blockPos + bytes.byteLength) {
+        cache.delete(blockPos);
+        cache.set(blockPos, bytes);
+        const offset = pos - blockPos;
+        return bytes.subarray(offset, offset + length);
+      }
+    }
+    return null;
   }
 
-  /** Slice the requested window out of the cached block. */
-  function sliceFromCache(pos: number, length: number): Uint8Array {
-    if (!cached) throw new Error("sliceFromCache called with no cache");
-    const offset = pos - cached.pos;
-    return cached.bytes.subarray(offset, offset + length);
+  /** Insert a fetched block; evict least-recently-used until under budget. */
+  function cacheInsert(pos: number, bytes: Uint8Array): void {
+    const existing = cache.get(pos);
+    if (existing) {
+      cacheBytes -= existing.byteLength;
+      cache.delete(pos);
+    }
+    cache.set(pos, bytes);
+    cacheBytes += bytes.byteLength;
+    while (cacheBytes > cacheBudget && cache.size > 0) {
+      const oldestKey = cache.keys().next().value as number | undefined;
+      if (oldestKey === undefined) break;
+      const oldest = cache.get(oldestKey);
+      if (!oldest) break;
+      cache.delete(oldestKey);
+      cacheBytes -= oldest.byteLength;
+    }
   }
 
   /** Fetch one Range and update the cache. */
@@ -235,7 +273,7 @@ export async function attachLibavHttpReader(
       );
     }
     const buf = new Uint8Array(await res.arrayBuffer());
-    cached = { pos, bytes: buf };
+    cacheInsert(pos, buf);
     return buf;
   }
 
@@ -252,9 +290,9 @@ export async function attachLibavHttpReader(
     if (detached) return;
 
     // Cache hit — reply directly without a network round-trip.
-    if (cacheCovers(pos, length)) {
-      const data = sliceFromCache(pos, length);
-      try { await libav.ff_block_reader_dev_send(name, pos, data); } catch { /* ignore — libav may have torn down */ }
+    const hit = cacheLookup(pos, length);
+    if (hit) {
+      try { await libav.ff_block_reader_dev_send(name, pos, hit); } catch { /* ignore — libav may have torn down */ }
       return;
     }
 
@@ -312,7 +350,8 @@ export async function attachLibavHttpReader(
         try { await inflight; } catch { /* ignore */ }
       }
       // Drop the cache and unlink the virtual file.
-      cached = null;
+      cache.clear();
+      cacheBytes = 0;
       try { await libav.unlinkreadaheadfile(filename); } catch { /* ignore */ }
     },
   };