avbridge 2.12.0 → 2.12.1

package/dist/{remux-VPKCLHHM.cjs → remux-NSBJFMLG.cjs}

@@ -1,7 +1,7 @@
 'use strict';
 
-var chunkGJBNLPGI_cjs = require('./chunk-GJBNLPGI.cjs');
-require('./chunk-HBHSUGNI.cjs');
+var chunkE5MAM2P4_cjs = require('./chunk-E5MAM2P4.cjs');
+require('./chunk-VLI3Y6IJ.cjs');
 require('./chunk-2IJ66NTD.cjs');
 require('./chunk-QDJLQR53.cjs');
 require('./chunk-HZUVMXBN.cjs');
@@ -13,23 +13,23 @@ require('./chunk-F3LQJKXK.cjs');
 
 Object.defineProperty(exports, "createOutputFormat", {
   enumerable: true,
-  get: function () { return chunkGJBNLPGI_cjs.createOutputFormat; }
+  get: function () { return chunkE5MAM2P4_cjs.createOutputFormat; }
 });
 Object.defineProperty(exports, "generateFilename", {
   enumerable: true,
-  get: function () { return chunkGJBNLPGI_cjs.generateFilename; }
+  get: function () { return chunkE5MAM2P4_cjs.generateFilename; }
 });
 Object.defineProperty(exports, "mimeForFormat", {
   enumerable: true,
-  get: function () { return chunkGJBNLPGI_cjs.mimeForFormat; }
+  get: function () { return chunkE5MAM2P4_cjs.mimeForFormat; }
 });
 Object.defineProperty(exports, "remux", {
   enumerable: true,
-  get: function () { return chunkGJBNLPGI_cjs.remux; }
+  get: function () { return chunkE5MAM2P4_cjs.remux; }
 });
 Object.defineProperty(exports, "validateRemuxEligibility", {
   enumerable: true,
-  get: function () { return chunkGJBNLPGI_cjs.validateRemuxEligibility; }
+  get: function () { return chunkE5MAM2P4_cjs.validateRemuxEligibility; }
 });
-//# sourceMappingURL=remux-VPKCLHHM.cjs.map
-//# sourceMappingURL=remux-VPKCLHHM.cjs.map
+//# sourceMappingURL=remux-NSBJFMLG.cjs.map
+//# sourceMappingURL=remux-NSBJFMLG.cjs.map

package/dist/{remux-VPKCLHHM.cjs.map → remux-NSBJFMLG.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"remux-VPKCLHHM.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"remux-NSBJFMLG.cjs"}

package/dist/{remux-7TA4FKTY.js → remux-PHUHO3VV.js}

@@ -1,10 +1,10 @@
-export { createOutputFormat, generateFilename, mimeForFormat, remux, validateRemuxEligibility } from './chunk-5Y5BTB5D.js';
-import './chunk-2LNXMGT6.js';
+export { createOutputFormat, generateFilename, mimeForFormat, remux, validateRemuxEligibility } from './chunk-B76QWPFM.js';
+import './chunk-5CX7BVVV.js';
 import './chunk-CPJLFFCC.js';
 import './chunk-LUFA47FP.js';
 import './chunk-3YKWU4FM.js';
 import './chunk-3AI5WFFN.js';
 import './chunk-5DMTJVIU.js';
 import './chunk-5YAWWKA3.js';
-//# sourceMappingURL=remux-7TA4FKTY.js.map
-//# sourceMappingURL=remux-7TA4FKTY.js.map
+//# sourceMappingURL=remux-PHUHO3VV.js.map
+//# sourceMappingURL=remux-PHUHO3VV.js.map

package/dist/{remux-7TA4FKTY.js.map → remux-PHUHO3VV.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"remux-7TA4FKTY.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"remux-PHUHO3VV.js"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "avbridge",
-  "version": "2.12.0",
+  "version": "2.12.1",
   "description": "Play and convert arbitrary video files in the browser. Native, remux, hybrid, fallback, and transcode — one API.",
   "license": "MIT",
   "author": "Keishi Hattori",

package/src/element/avbridge-player.ts

@@ -752,10 +752,13 @@ export class AvbridgePlayerElement extends HTMLElement {
 
   // ── Stats for nerds ────────────────────────────────────────────────────
 
+  private _statsPrev: { ts: number; rt: Record<string, unknown> } | null = null;
+
   private _toggleStats(): void {
     this._statsOpen = !this._statsOpen;
     this._statsEl.classList.toggle("open", this._statsOpen);
     if (this._statsOpen) {
+      this._statsPrev = null; // reset delta baseline
       this._updateStats();
       this._statsInterval = setInterval(() => this._updateStats(), 1000);
     } else {
@@ -767,23 +770,92 @@ export class AvbridgePlayerElement extends HTMLElement {
     const d = this._video.getDiagnostics() as Record<string, unknown> | null;
     if (!d) { this._statsEl.textContent = "No diagnostics"; return; }
     const rt = (d.runtime ?? {}) as Record<string, unknown>;
-    const lines: string[] = [
-      `Container: ${d.container ?? "?"}`,
-      `Video: ${d.videoCodec ?? "?"} ${d.width ?? "?"}×${d.height ?? "?"}`,
-      `Audio: ${d.audioCodec ?? "none"}`,
-      `Strategy: ${d.strategy ?? "?"}  Class: ${d.strategyClass ?? "?"}`,
-      `Transport: ${d.transport ?? "?"} Range: ${d.rangeSupported ?? "?"}`,
-      `Duration: ${typeof d.duration === "number" ? d.duration.toFixed(1) + "s" : "?"}`,
-    ];
-    if (rt.framesDecoded != null) lines.push(`Frames: ${rt.framesDecoded} decoded, ${rt.framesDropped ?? 0} dropped`);
-    if (rt.framesPainted != null) lines.push(`Painted: ${rt.framesPainted} Late: ${rt.framesDroppedLate ?? 0} Overflow: ${rt.framesDroppedOverflow ?? 0}`);
-    if (rt.videoFramesDecoded != null) lines.push(`Video decoded: ${rt.videoFramesDecoded} Chunks fed: ${rt.videoChunksFed ?? "?"}`);
-    if (rt.audioFramesDecoded != null) lines.push(`Audio decoded: ${rt.audioFramesDecoded}`);
-    if (rt.packetsRead != null) lines.push(`Packets read: ${rt.packetsRead}`);
-    if (rt.bsfApplied && (rt.bsfApplied as string[]).length > 0) lines.push(`BSF: ${(rt.bsfApplied as string[]).join(", ")}`);
-    if (rt.audioState != null) lines.push(`Audio state: ${rt.audioState} Clock: ${rt.clockMode ?? "?"}`);
+    const now = performance.now();
+    const prev = this._statsPrev;
+    const dtSec = prev ? Math.max(0.001, (now - prev.ts) / 1000) : 0;
+    const delta = (key: string): number | null => {
+      if (!prev) return null;
+      const a = rt[key];
+      const b = prev.rt[key];
+      if (typeof a === "number" && typeof b === "number") return a - b;
+      return null;
+    };
+    const rate = (key: string): number | null => {
+      const d_ = delta(key);
+      return d_ != null ? d_ / dtSec : null;
+    };
+    const fmt = (n: number | null, digits = 1) => (n == null ? "?" : n.toFixed(digits));
+
+    const sourceFps = (typeof rt.sourceFps === "number" ? rt.sourceFps : d.fps) as number | undefined;
+    const lines: string[] = [];
+
+    // ── Identity ──────────────────────────────────────────────────────
+    lines.push(`Container: ${d.container ?? "?"}   Strategy: ${d.strategy ?? "?"} (${d.strategyClass ?? "?"})`);
+    lines.push(`Video: ${d.videoCodec ?? "?"} ${d.width ?? "?"}×${d.height ?? "?"}${sourceFps ? ` @ ${sourceFps.toFixed(3)} fps` : ""}`);
+    lines.push(`Audio: ${d.audioCodec ?? "none"}   Transport: ${d.transport ?? "?"}${d.rangeSupported === true ? "/range" : ""}`);
+    lines.push(`Duration: ${typeof d.duration === "number" ? d.duration.toFixed(1) + "s" : "?"}   Playback rate: ${this._video.playbackRate.toFixed(2)}x`);
+
+    // ── Realtime rates (deltas per second) ─────────────────────────────
+    if (rt.videoFramesDecoded != null) {
+      const decFps = rate("videoFramesDecoded");
+      const paintFps = rate("framesPainted");
+      const dropLateFps = rate("framesDroppedLate");
+      const dropOverflowFps = rate("framesDroppedOverflow");
+      const pct = sourceFps && decFps != null ? ` (${((decFps / sourceFps) * 100).toFixed(0)}% of realtime)` : "";
+      lines.push(`Decode fps: ${fmt(decFps)}${pct}   Paint fps: ${fmt(paintFps)}`);
+      lines.push(`Drops/sec: late=${fmt(dropLateFps)} overflow=${fmt(dropOverflowFps)}   Totals: painted=${rt.framesPainted} dropped=${rt.framesDroppedLate}`);
+    }
+
+    // ── Decode-time breakdown (wall ms spent inside libav) ────────────
+    if (typeof rt.videoDecodeMsTotal === "number") {
+      const msDelta = delta("videoDecodeMsTotal");
+      const batchesDelta = delta("videoDecodeBatches");
+      const perBatch = msDelta != null && batchesDelta && batchesDelta > 0 ? msDelta / batchesDelta : null;
+      const share = msDelta != null && dtSec > 0 ? (msDelta / (dtSec * 1000)) * 100 : null;
+      lines.push(
+        `Video decode: ${fmt(perBatch)}ms/batch avg   ${fmt(share)}% of wall   slowest=${fmt(rt.slowestVideoBatchMs as number)}ms`,
+      );
+    }
+    if (typeof rt.audioDecodeMsTotal === "number") {
+      const msDelta = delta("audioDecodeMsTotal");
+      const share = msDelta != null && dtSec > 0 ? (msDelta / (dtSec * 1000)) * 100 : null;
+      lines.push(`Audio decode: ${fmt(share)}% of wall`);
+    }
+    if (typeof rt.pumpThrottleMsTotal === "number") {
+      const msDelta = delta("pumpThrottleMsTotal");
+      const share = msDelta != null && dtSec > 0 ? (msDelta / (dtSec * 1000)) * 100 : null;
+      lines.push(`Producer throttled: ${fmt(share)}% of wall`);
+    }
+
+    // ── Queue health ──────────────────────────────────────────────────
+    if (rt.queueDepth != null) {
+      lines.push(
+        `Queue: depth=${rt.queueDepth} span=${fmt(rt.queueSpanMs as number)}ms ` +
+        `head=${fmt(rt.queueHeadMs as number)}ms tail=${fmt(rt.queueTailMs as number)}ms`,
+      );
+    }
+    if (typeof rt.newestVideoPtsMs === "number") {
+      lines.push(`Newest decoded PTS: ${(rt.newestVideoPtsMs / 1000).toFixed(2)}s`);
+    }
+
+    // ── Audio ─────────────────────────────────────────────────────────
+    if (rt.audioState != null) {
+      lines.push(`Audio state: ${rt.audioState}   bufferAhead=${fmt(rt.bufferAhead as number, 2)}s   clock=${rt.clockMode ?? "?"}`);
+    }
+
+    // ── BSF + warnings ────────────────────────────────────────────────
+    if (typeof rt.ptsRegressions === "number" && rt.ptsRegressions > 0) {
+      lines.push(`PTS REGRESSIONS: ${rt.ptsRegressions} (worst=${fmt(rt.worstPtsRegressionMs as number)}ms) — decoder emitting out of order`);
+    }
+    if (rt.bsfApplied && (rt.bsfApplied as string[]).length > 0) lines.push(`BSF active: ${(rt.bsfApplied as string[]).join(", ")}`);
+    if (rt.bsfMissing && (rt.bsfMissing as string[]).length > 0) {
+      lines.push(`BSF MISSING: ${(rt.bsfMissing as string[]).join(", ")} (rebuild libav with avbsf)`);
+    }
+
     if (d.probedBy) lines.push(`Probed by: ${d.probedBy}`);
+
     this._statsEl.textContent = lines.join("\n");
+    this._statsPrev = { ts: now, rt: { ...rt } };
   }
 
   // ── Controls: fullscreen ───────────────────────────────────────────────

package/src/probe/avi.ts

@@ -77,7 +77,7 @@ export async function probeWithLibav(
         codec: ffmpegToAvbridgeVideo(codecName),
         width: codecpar?.width ?? 0,
         height: codecpar?.height ?? 0,
-        fps: framerate(stream),
+        fps: await framerate(libav, stream),
       });
     } else if (stream.codec_type === libav.AVMEDIA_TYPE_AUDIO) {
       audioTracks.push({
@@ -111,7 +111,27 @@ export async function probeWithLibav(
   };
 }
 
-function framerate(stream: LibavStream): number | undefined {
+/**
+ * Read frame rate from the stream's `AVCodecParameters.framerate`.
+ *
+ * `avg_frame_rate` / `r_frame_rate` live on the AVStream in C but libav.js
+ * doesn't expose them as JS properties on the stream record — only via
+ * dedicated accessor functions we don't ship. `codecpar.framerate` IS
+ * accessible via `AVCodecParameters_framerate_num/_den` and is populated
+ * for most containers (for AVI it's parsed from `dwRate`/`dwScale` in the
+ * stream header).
+ *
+ * Returns undefined if unavailable so the caller can fall back to a
+ * container-appropriate default (currently 30 fps, which is wrong for
+ * 25 fps PAL and 23.976 fps film content — hence the importance of
+ * reading this correctly).
+ */
+async function framerate(
+  libav: LibavInstance,
+  stream: LibavStream,
+): Promise<number | undefined> {
+  // The stream record may still carry these (new libav.js versions) —
+  // prefer them when present.
   if (typeof stream.avg_frame_rate_num === "number" && stream.avg_frame_rate_den) {
     return stream.avg_frame_rate_num / stream.avg_frame_rate_den;
   }
@@ -119,6 +139,15 @@ function framerate(stream: LibavStream): number | undefined {
     if (stream.avg_frame_rate.den === 0) return undefined;
     return stream.avg_frame_rate.num / stream.avg_frame_rate.den;
   }
+  try {
+    const num = await libav.AVCodecParameters_framerate_num?.(stream.codecpar);
+    const den = await libav.AVCodecParameters_framerate_den?.(stream.codecpar);
+    if (typeof num === "number" && typeof den === "number" && den > 0 && num > 0) {
+      return num / den;
+    }
+  } catch {
+    // Fall through.
+  }
   return undefined;
 }
 
@@ -250,6 +279,9 @@ interface LibavInstance {
   AVFormatContext_durationhi?(ctx: number): Promise<number>;
   i64tof64?(lo: number, hi: number): number;
 
+  AVCodecParameters_framerate_num?(codecpar: number): Promise<number>;
+  AVCodecParameters_framerate_den?(codecpar: number): Promise<number>;
+
   AVMEDIA_TYPE_VIDEO: number;
   AVMEDIA_TYPE_AUDIO: number;
 }

package/src/strategies/fallback/decoder.ts

@@ -169,6 +169,7 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
   // garbled frame ordering.
   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");
@@ -179,15 +180,24 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
         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");
+        bsfRequiredButMissing = true;
         bsfCtx = null;
       }
     } catch (err) {
-      // eslint-disable-next-line no-console
-      console.warn("[avbridge] failed to init mpeg4_unpack_bframes BSF:", (err as Error).message);
+      bsfRequiredButMissing = true;
       bsfCtx = null;
       bsfPkt = null;
+      dbg.warn("bsf", `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 (backwards PTS jumps, heavy " +
+        "late-drop stuttering). Rebuild the libav variant with the `avbsf` " +
+        "fragment included. See docs/dev/POSTMORTEMS.md for details.",
+      );
     }
   }
 
@@ -199,7 +209,12 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
       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
+        // BSF rejected — DON'T pass the original through. `ff_copyin_packet`
+        // above may have transferred pkt.data's ArrayBuffer into the worker,
+        // in which case re-posting the same packet to the decoder fails
+        // with DataCloneError on a detached buffer. Skipping the packet is
+        // safer; the decoder's error recovery will resync at the next
+        // keyframe if this was transient.
         continue;
       }
       while (true) {
@@ -215,10 +230,23 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
   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;
+      // `av_bsf_flush` resets the BSF state without putting it in EOF
+      // mode. The old approach — sending a NULL packet — is the EOF
+      // signal; after that every subsequent `av_bsf_send_packet` fails,
+      // which made `applyBSF` fall back to pushing the ORIGINAL packet
+      // through (with its buffer already transferred to WASM by
+      // `ff_copyin_packet`). That detached buffer then failed to
+      // `postMessage` into the decoder worker with DataCloneError on
+      // the first post-seek batch.
+      if (libav.av_bsf_flush) {
+        await libav.av_bsf_flush(bsfCtx);
+      } else {
+        // Fallback for older libav.js variants without av_bsf_flush:
+        // drain any internal packets but DON'T send NULL-EOF.
+        while (true) {
+          const err = await libav.av_bsf_receive_packet(bsfCtx, bsfPkt);
+          if (err < 0) break;
+        }
       }
     } catch { /* ignore flush errors */ }
   }
@@ -251,6 +279,25 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
   let syntheticVideoUs = 0;
   let syntheticAudioUs = 0;
 
+  // Throughput instrumentation — answers "is the decoder keeping up?".
+  // All counters are cumulative since bootstrap (not reset on seek), so
+  // the stats panel can compute rolling deltas. Times are wall-ms spent
+  // inside the respective libav call; JS↔WASM boundary is inside the
+  // worker so this is the real cost the producer pays per batch.
+  let videoDecodeMsTotal = 0;
+  let audioDecodeMsTotal = 0;
+  let videoDecodeBatches = 0;
+  let audioDecodeBatches = 0;
+  let readMsTotal = 0;
+  let readBatches = 0;
+  let pumpThrottleMsTotal = 0;
+  let pumpThrottleEntries = 0;
+  let slowestVideoBatchMs = 0;
+  let newestVideoPtsUs = 0; // set by decodeVideoBatch after each emitted frame
+  let lastEmittedPtsUs = -1; // previous emitted frame's pts, for monotonicity check
+  let ptsRegressions = 0;
+  let worstPtsRegressionMs = 0;
+
   const videoTrackInfo = opts.context.videoTracks.find((t) => t.id === videoStream?.index);
   const videoFps = videoTrackInfo?.fps && videoTrackInfo.fps > 0 ? videoTrackInfo.fps : 30;
   const videoFrameStepUs = Math.max(1, Math.round(1_000_000 / videoFps));
@@ -274,9 +321,12 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
         // typical bitrates, so the worst-case queue spike stays under
         // `queueHighWater` and the throttle has a chance to apply
         // backpressure *between* batches rather than within one.
+        const _readStart = performance.now();
         [readErr, packets] = await libav.ff_read_frame_multi(fmt_ctx, readPkt, {
           limit: 16 * 1024,
         });
+        readMsTotal += performance.now() - _readStart;
+        readBatches++;
       } catch (err) {
         console.error("[avbridge] ff_read_frame_multi failed:", err);
         return;
@@ -388,13 +438,22 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
       //   - Renderer queue depth >= queueHighWater — the canvas can't
       //     drain fast enough. Without this, fast software decode of
       //     small frames piles up in the renderer and overflows.
-      while (
-        !destroyed &&
-        myToken === pumpToken &&
-        (opts.audio.bufferAhead() > 2.0 ||
-          opts.renderer.queueDepth() >= opts.renderer.queueHighWater)
-      ) {
-        await new Promise((r) => setTimeout(r, 50));
+      {
+        const _throttleStart = performance.now();
+        let _throttled = false;
+        while (
+          !destroyed &&
+          myToken === pumpToken &&
+          (opts.audio.bufferAhead() > 2.0 ||
+            opts.renderer.queueDepth() >= opts.renderer.queueHighWater)
+        ) {
+          _throttled = true;
+          await new Promise((r) => setTimeout(r, 50));
+        }
+        if (_throttled) {
+          pumpThrottleMsTotal += performance.now() - _throttleStart;
+          pumpThrottleEntries++;
+        }
       }
 
       if (readErr === libav.AVERROR_EOF) {
@@ -412,6 +471,7 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
   async function decodeVideoBatch(pkts: LibavPacket[], myToken: number, flush = false) {
     if (!videoDec || destroyed || myToken !== pumpToken) return;
     let frames: LibavFrame[];
+    const _t0 = performance.now();
     try {
       frames = await libav.ff_decode_multi(
         videoDec.c,
@@ -424,6 +484,12 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
       console.error("[avbridge] video decode batch failed:", err);
       return;
     }
+    {
+      const _dt = performance.now() - _t0;
+      videoDecodeMsTotal += _dt;
+      videoDecodeBatches++;
+      if (_dt > slowestVideoBatchMs) slowestVideoBatchMs = _dt;
+    }
     if (myToken !== pumpToken || destroyed) return;
 
     for (const f of frames) {
@@ -431,14 +497,54 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
       sanitizeFrameTimestamp(
         f,
         () => {
-          const ts = syntheticVideoUs;
-          syntheticVideoUs += videoFrameStepUs;
-          return ts;
+          // Anchor the synthetic timestamp to the last emitted frame's
+          // pts + one frame step. A plain counter (the old behavior)
+          // started at 0 and only advanced on invalid frames, which
+          // made the occasional AV_NOPTS_VALUE output get assigned a
+          // timestamp near the stream start — causing the renderer to
+          // paint backwards and drop healthy frames around it. Anchoring
+          // to `lastEmittedPtsUs` keeps invalid frames monotonic with
+          // their valid neighbors.
+          const base =
+            lastEmittedPtsUs >= 0
+              ? lastEmittedPtsUs + videoFrameStepUs
+              : syntheticVideoUs;
+          syntheticVideoUs = base + videoFrameStepUs;
+          return base;
         },
         videoTimeBase,
       );
       // sanitizeFrameTimestamp normalizes pts to µs, so the bridge can
       // always use the 1/1e6 timebase.
+      const _fPts = (f.ptshi ?? 0) * 0x100000000 + (f.pts ?? 0);
+      if (_fPts > newestVideoPtsUs) newestVideoPtsUs = _fPts;
+      if (lastEmittedPtsUs >= 0 && _fPts < lastEmittedPtsUs) {
+        // Decoder emitted a frame with lower PTS than the previous
+        // output. Dropping out-of-order frames here is the right move:
+        // the renderer's paint loop assumes monotonic queue order and
+        // breaks (stale frame stuck at head, newer frames drop as late,
+        // paint cadence collapses) if we let them through. Two scenarios
+        // produce this in practice:
+        //   - Post-seek tail of a B-frame reorder buffer that survives
+        //     avcodec_flush_buffers + av_bsf_flush (rare but observed
+        //     on mpeg4 after large seeks).
+        //   - A BSF that doesn't repair packed B-frames perfectly and
+        //     lets a DTS/PTS swap through.
+        // The decoder will catch up at the next I-frame.
+        ptsRegressions++;
+        const regressMs = (lastEmittedPtsUs - _fPts) / 1000;
+        if (regressMs > worstPtsRegressionMs) worstPtsRegressionMs = regressMs;
+        if (ptsRegressions <= 10) {
+          // eslint-disable-next-line no-console
+          console.warn(
+            `[avbridge:decoder] dropped out-of-order frame #${ptsRegressions}: ` +
+            `pts=${(_fPts / 1000).toFixed(1)}ms < previous=${(lastEmittedPtsUs / 1000).toFixed(1)}ms ` +
+            `(regression=${regressMs.toFixed(1)}ms). Typically a post-seek B-frame reorder tail.`,
+          );
+        }
+        continue; // skip enqueue
+      }
+      lastEmittedPtsUs = _fPts;
       try {
         const vf = bridge.laFrameToVideoFrame(f, { timeBase: [1, 1_000_000] });
         opts.renderer.enqueue(vf);
@@ -454,6 +560,7 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
   async function decodeAudioBatch(pkts: LibavPacket[], myToken: number, flush = false) {
     if (!audioDec || destroyed || myToken !== pumpToken) return;
     let frames: LibavFrame[];
+    const _t0 = performance.now();
     try {
       frames = await libav.ff_decode_multi(
         audioDec.c,
@@ -466,6 +573,8 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
       console.error("[avbridge] audio decode batch failed:", err);
       return;
     }
+    audioDecodeMsTotal += performance.now() - _t0;
+    audioDecodeBatches++;
     if (myToken !== pumpToken || destroyed) return;
 
     for (const f of frames) {
@@ -575,6 +684,7 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
 
       syntheticVideoUs = Math.round(timeSec * 1_000_000);
       syntheticAudioUs = Math.round(timeSec * 1_000_000);
+      lastEmittedPtsUs = -1;
 
       pumpRunning = pumpLoop(newToken).catch((err) =>
         console.error("[avbridge] fallback pump failed (post-setAudioTrack):", err),
@@ -633,6 +743,7 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
       // decoded frames start at the right media time.
       syntheticVideoUs = Math.round(timeSec * 1_000_000);
       syntheticAudioUs = Math.round(timeSec * 1_000_000);
+      lastEmittedPtsUs = -1;
 
       // The renderer & audio output are reset by the fallback session
       // wrapper that called us — see strategies/fallback/index.ts.
@@ -653,7 +764,24 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
         packetsRead,
         videoFramesDecoded,
         audioFramesDecoded,
+        // Throughput instrumentation — the stats panel turns these into
+        // "decode fps actual / realtime target" and shows slowest batch
+        // + producer throttle share.
+        videoDecodeMsTotal,
+        videoDecodeBatches,
+        audioDecodeMsTotal,
+        audioDecodeBatches,
+        readMsTotal,
+        readBatches,
+        pumpThrottleMsTotal,
+        pumpThrottleEntries,
+        slowestVideoBatchMs,
+        newestVideoPtsMs: Math.round(newestVideoPtsUs / 1000),
+        ptsRegressions,
+        worstPtsRegressionMs,
+        sourceFps: videoFps,
         bsfApplied: bsfCtx ? ["mpeg4_unpack_bframes"] : [],
+        bsfMissing: bsfRequiredButMissing ? ["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
@@ -776,6 +904,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>;
 
   // Packet copy helpers — bridge JS packet objects to/from C-level pointers

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,
     };
   }