avbridge 2.8.2 → 2.8.4

package/CHANGELOG.md

@@ -4,6 +4,50 @@ All notable changes to **avbridge.js** are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.8.4]
+
+Decode-stall detection — the robustness follow-up that addresses the
+v2.8.1 "Known deferred" item.
+
+### Added
+
+- **Silent-video watchdog in the stall supervisor.** Catches the class
+  of bug where MSE reports a codec as supported but the decoder can't
+  actually decode it — audio plays, `currentTime` advances, but the
+  video decoder never produces frames. The supervisor now samples
+  `HTMLVideoElement.getVideoPlaybackQuality().totalVideoFrames` (or
+  `webkitDecodedFrameCount` on older Safari) and triggers strategy
+  escalation when audio is advancing but frames haven't for 3 s. The
+  Firefox HEVC case (MSE lies about `hev1.*`) is the motivating
+  example, but the watchdog is codec- and browser-agnostic.
+- **`fallbackChain` on `REMUX_CANDIDATE` classifications.** Previously
+  the supervisor had nowhere to escalate to from a plain remux
+  classification, so stalls sat there forever. The chain is
+  `["hybrid", "fallback"]` (or `["fallback"]` without WebCodecs) —
+  initial strategy is still remux; the chain only engages on stall.
+- **`evaluateDecodeHealth(input)` and `readDecodedFrameCount(target)`
+  extracted as pure helpers** in `src/player.ts` (not re-exported from
+  the package root; same pattern as `buildInitialDecision`) so the
+  supervisor's decision logic is unit-testable without a browser.
+
+### Fixed
+
+- **Firefox HEVC** in `tests/browser/playback.spec.ts` should now
+  un-skip once this ships — the watchdog gives Firefox a mechanism to
+  escalate off the lying MSE path to hybrid / fallback automatically.
+
+## [2.8.3]
+
+### Added
+
+- **`showControls(durationMs?)` on `<avbridge-player>`.** Public method
+  to reveal the auto-hiding chrome (top toolbar + bottom controls)
+  and re-start the auto-hide timer. Intended for app-level "flash the
+  UI" moments like a carousel slide change or focus handoff — one call
+  instead of reaching into `data-controls-hidden`. Custom duration
+  overrides the default 3 s; pointer movement during the flash resets
+  the timer so there's no flicker if the user interacts mid-flash.
+
 ## [2.8.2]
 
 Small ergonomics release driven by downstream `<avbridge-player>`

package/dist/{chunk-JSQOBUQB.js → chunk-KBWQRGHS.js}

@@ -231,10 +231,12 @@ function classifyContext(ctx) {
         reason: `${ctx.container} container with ${video.codec}${audio ? "/" + audio.codec : ""}; MSE rejects the remux target mime and WebCodecs is unavailable \u2014 falling back to WASM decode`
       };
     }
+    const fallbackChain = webCodecsAvailable() ? ["hybrid", "fallback"] : ["fallback"];
     return {
       class: "REMUX_CANDIDATE",
       strategy: "remux",
-      reason: `${ctx.container} container with native-supported codecs \u2014 remux to fragmented MP4 for reliable playback`
+      reason: `${ctx.container} container with native-supported codecs \u2014 remux to fragmented MP4 for reliable playback`,
+      fallbackChain
     };
   }
   if (webCodecsAvailable()) {
@@ -2858,6 +2860,29 @@ function registerBuiltins(registry) {
 }
 
 // src/player.ts
+function readDecodedFrameCount(target) {
+  if (typeof HTMLVideoElement === "undefined" || !(target instanceof HTMLVideoElement)) return 0;
+  const vq = target.getVideoPlaybackQuality;
+  if (typeof vq === "function") {
+    try {
+      return vq.call(target).totalVideoFrames;
+    } catch {
+    }
+  }
+  const legacy = target.webkitDecodedFrameCount;
+  return typeof legacy === "number" ? legacy : 0;
+}
+function evaluateDecodeHealth(input) {
+  const timeThreshold = input.timeStallThresholdMs ?? 5e3;
+  const frameThreshold = input.frameStallThresholdMs ?? 3e3;
+  if (!input.timeAdvanced && input.now - input.lastProgressTime > timeThreshold) {
+    return { escalate: true, kind: "time-stall" };
+  }
+  if (input.hasVideoTrack && input.timeAdvanced && !input.framesAdvanced && input.now - input.lastFrameProgressTime > frameThreshold) {
+    return { escalate: true, kind: "silent-video" };
+  }
+  return { escalate: false };
+}
 var UnifiedPlayer = class _UnifiedPlayer {
   /**
    * @internal Use {@link createPlayer} or {@link UnifiedPlayer.create} instead.
@@ -2883,6 +2908,13 @@ var UnifiedPlayer = class _UnifiedPlayer {
   stallTimer = null;
   lastProgressTime = 0;
   lastProgressPosition = -1;
+  /** Last observed `HTMLVideoElement.getVideoPlaybackQuality().totalVideoFrames`
+   *  (or `webkitDecodedFrameCount` fallback). Used by the silent-video
+   *  watchdog — catches cases where `currentTime` advances (audio plays)
+   *  but the decoder produces no frames, e.g. Firefox claiming `hev1.*`
+   *  via MSE when the decoder actually can't decode HEVC. */
+  lastVideoFrameCount = 0;
+  lastVideoFrameProgressTime = 0;
   errorListener = null;
   // Bound so we can removeEventListener in destroy(); without this the
   // listener outlives the player and accumulates on elements that swap
@@ -3127,22 +3159,41 @@ var UnifiedPlayer = class _UnifiedPlayer {
     if (strategy === "native" || strategy === "remux") {
       this.lastProgressPosition = this.options.target.currentTime;
       this.lastProgressTime = performance.now();
+      this.lastVideoFrameCount = readDecodedFrameCount(this.options.target);
+      this.lastVideoFrameProgressTime = performance.now();
+      const hasVideoTrack = (this.mediaContext?.videoTracks.length ?? 0) > 0;
       this.stallTimer = setInterval(() => {
         const t = this.options.target;
+        const now = performance.now();
         if (t.paused || t.ended || t.readyState < 2) {
           this.lastProgressPosition = t.currentTime;
-          this.lastProgressTime = performance.now();
+          this.lastProgressTime = now;
+          this.lastVideoFrameCount = readDecodedFrameCount(t);
+          this.lastVideoFrameProgressTime = now;
           return;
         }
-        if (t.currentTime !== this.lastProgressPosition) {
+        const timeAdvanced = t.currentTime !== this.lastProgressPosition;
+        const frames = readDecodedFrameCount(t);
+        const framesAdvanced = frames > this.lastVideoFrameCount;
+        const health = evaluateDecodeHealth({
+          hasVideoTrack,
+          timeAdvanced,
+          framesAdvanced,
+          now,
+          lastProgressTime: this.lastProgressTime,
+          lastFrameProgressTime: this.lastVideoFrameProgressTime
+        });
+        if (timeAdvanced) {
           this.lastProgressPosition = t.currentTime;
-          this.lastProgressTime = performance.now();
-          return;
+          this.lastProgressTime = now;
         }
-        if (performance.now() - this.lastProgressTime > 5e3) {
-          void this.escalate(
-            `${strategy} strategy stalled for 5s at ${t.currentTime.toFixed(1)}s`
-          );
+        if (framesAdvanced) {
+          this.lastVideoFrameCount = frames;
+          this.lastVideoFrameProgressTime = now;
+        }
+        if (health.escalate) {
+          const reason = health.kind === "time-stall" ? `${strategy} strategy stalled for 5s at ${t.currentTime.toFixed(1)}s` : `${strategy} strategy: audio is advancing but the video decoder has produced no new frames for 3s \u2014 likely a silent codec failure`;
+          void this.escalate(reason);
         }
       }, 1e3);
       const onError = () => {
@@ -3373,5 +3424,5 @@ function defaultFallbackChain(strategy) {
 }
 
 export { FALLBACK_AUDIO_CODECS, FALLBACK_VIDEO_CODECS, NATIVE_AUDIO_CODECS, NATIVE_VIDEO_CODECS, UnifiedPlayer, classifyContext, createPlayer };
-//# sourceMappingURL=chunk-JSQOBUQB.js.map
-//# sourceMappingURL=chunk-JSQOBUQB.js.map
+//# sourceMappingURL=chunk-KBWQRGHS.js.map
+//# sourceMappingURL=chunk-KBWQRGHS.js.map