avbridge 1.0.0 → 2.0.0

package/CHANGELOG.md

@@ -4,7 +4,138 @@ All notable changes to **avbridge** 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).
 
-## [Unreleased]
+## [2.0.0]
+
+### Breaking changes
+
+- **`createPlayer({ forceStrategy })` renamed to `{ initialStrategy }`.**
+  The old name implied a hard force, but the player has always walked the
+  fallback chain on failure regardless. The new name matches the actual
+  semantics: the named strategy is the *initial* pick, and escalation still
+  applies if it fails. **Migration:** rename the option key. Behavior is
+  unchanged for consumers who passed a strategy that successfully started.
+
+- **`discoverSidecar()` renamed to `discoverSidecars()`.** The function
+  always returned an array; the singular name was misleading. **Migration:**
+  rename the import. No semantic change.
+
+- **`<avbridge-player>` was renamed to `<avbridge-video>`.** The element is
+  semantically an `HTMLMediaElement`-compatible primitive — it has no UI,
+  no controls, and is intended as a drop-in replacement for `<video>`. The
+  old name oversold what it does. The new name matches the contract.
+  - The class export is now `AvbridgeVideoElement` (was `AvbridgePlayerElement`).
+  - The source file is `src/element/avbridge-video.ts`.
+  - The subpath import is unchanged: `import "avbridge/element"` still
+    registers the element. It now registers `<avbridge-video>` instead of
+    `<avbridge-player>`.
+  - **Migration**: rename every `<avbridge-player>` tag, every
+    `AvbridgePlayerElement` reference, and any CSS selectors targeting the
+    old tag. There is no compatibility shim — `<avbridge-player>` is **not**
+    registered in 2.0 because the name is reserved for the future
+    controls-bearing element.
+
+### Reserved
+
+- **`<avbridge-player>` is reserved** for a future controls-bearing element
+  that ships built-in player UI (seek bar, play/pause, subtitle/audio menus,
+  drag-and-drop, etc.). It does not exist yet. Importing `avbridge/element`
+  registers only `<avbridge-video>`.
+
+### Fixed
+
+- **Unknown video/audio codecs no longer silently relabel as `h264`/`aac`.**
+  `mediabunnyVideoToAvbridge()` and `mediabunnyAudioToAvbridge()` used to
+  default unknown inputs to the most common codec name, which sent
+  unsupported media down the native/remux path and produced opaque "playback
+  failed" errors. They now preserve the original codec string (or return
+  `"unknown"` for `null`/`undefined`), and the classifier routes anything
+  outside `NATIVE_VIDEO_CODECS` / `NATIVE_AUDIO_CODECS` to fallback as
+  intended. Reported in CODE_REVIEW finding #1.
+
+- **Strategy escalation now walks the entire fallback chain.** Previously,
+  if an intermediate fallback step failed to start, `doEscalate()` emitted
+  an error and gave up — even when later viable strategies remained in the
+  chain. This was inconsistent with the initial bootstrap path
+  (`startSession`), which already recurses. Escalation now loops until a
+  strategy starts or the chain is exhausted, and the final error message
+  lists every attempted strategy with its individual failure reason.
+  Reported in CODE_REVIEW finding #4.
+
+- **`initialStrategy` now reports the correct `strategyClass` in
+  diagnostics.** The old `forceStrategy` path hard-coded
+  `class: "NATIVE"` regardless of the picked strategy, so any downstream
+  logic that trusted `strategyClass` got the wrong answer for forced
+  remux/hybrid/fallback runs. The class is now derived from the actual
+  picked strategy. Reported in CODE_REVIEW finding #2.
+
+- **`<avbridge-video>`'s `preferredStrategy` is now wired through to
+  `createPlayer({ initialStrategy })`.** It was previously inert — settable
+  but ignored at bootstrap. Reported in CODE_REVIEW finding #7.
+
+- **Subtitle attachment is awaited during bootstrap and per-track failures
+  are caught.** `attachSubtitleTracks()` was previously called without
+  `await`, so fetch/parse errors became unhandled rejections and `ready`
+  could fire before subtitle tracks existed. The call is now awaited, and
+  individual track failures are caught via an `onError` callback so a
+  single bad sidecar doesn't break bootstrap. The player logs them via
+  `console.warn`; promoting that to a typed `subtitleerror` event on the
+  player is a follow-up. Subtitles are not load-bearing for playback.
+  Reported in CODE_REVIEW finding #3.
+
+- **Subtitle blob URLs are now revoked at player teardown.** Sidecar
+  discovery and SRT→VTT conversion both created blob URLs that were never
+  revoked, leaking memory across repeated source swaps in long-lived SPAs.
+  A new `SubtitleResourceBag` owns every URL the player creates and
+  releases them in `destroy()`. Reported in CODE_REVIEW finding #5.
+
+- **Diagnostics no longer claim `rangeSupported: true` for URL inputs by
+  default.** The old code inferred Range support from the input type
+  (`typeof src === "string" → rangeSupported: true`), but the native and
+  remux URL paths rely on the browser's or mediabunny's own Range handling
+  and don't fail-fast on a non-supporting server, so the claim could be a
+  lie. The field is now `undefined` until a strategy actively confirms it
+  via the new `Diagnostics.recordTransport()` hook. Reported in
+  CODE_REVIEW finding #6.
+
+## [1.1.0]
+
+### Added
+
+- **`<avbridge-player>` is now a true `<video>` drop-in.** The element gained
+  the missing slice of the `HTMLMediaElement` surface so existing code that
+  reaches for a `<video>` can swap to `<avbridge-player>` with no behavioural
+  changes:
+  - **Properties**: `poster`, `volume`, `playbackRate`, `videoWidth`,
+    `videoHeight`, `played`, `seekable`, `crossOrigin`, `disableRemotePlayback`.
+  - **Method**: `canPlayType(mimeType)` — passes through to the underlying
+    `<video>`. Note that this answers about the *browser's* native support,
+    not avbridge's full capabilities.
+  - **Attributes** (reflected to the inner `<video>`): `poster`, `playsinline`,
+    `crossorigin`, `disableremoteplayback`.
+  - **Event forwarding**: 17 standard `HTMLMediaElement` events are forwarded
+    from the inner `<video>` to the wrapper element — `loadstart`,
+    `loadedmetadata`, `loadeddata`, `canplay`, `canplaythrough`, `play`,
+    `playing`, `pause`, `seeking`, `seeked`, `volumechange`, `ratechange`,
+    `durationchange`, `waiting`, `stalled`, `emptied`, `resize`. Consumers can
+    `el.addEventListener("loadedmetadata", …)` exactly like a real `<video>`.
+  - **`<track>` children**: light-DOM `<track>` elements declared as children
+    of `<avbridge-player>` are now mirrored into the shadow `<video>` and kept
+    in sync via a `MutationObserver`. This works for static HTML markup as
+    well as dynamic insertion / removal.
+  - **`videoElement` getter**: escape hatch returning the underlying shadow
+    `<video>` for native APIs the wrapper doesn't expose
+    (`requestPictureInPicture`, browser-native `audioTracks`, `captureStream`,
+    library integrations needing a real `HTMLVideoElement`). Caveat: when the
+    active strategy is `"fallback"` or `"hybrid"`, frames render to a canvas
+    overlay rather than into this `<video>`, so APIs that depend on the actual
+    pixels won't show the playing content in those modes.
+
+### Changed
+
+- The element's `observedAttributes` list grew to include `poster`,
+  `playsinline`, `crossorigin`, and `disableremoteplayback`.
+
+## [1.0.0]
 
 ### Added
 

package/README.md

@@ -348,7 +348,7 @@ core (native + remux for modern containers) doesn't need any of this.
 - libav.js **threading is disabled** due to bugs in v6.8.8 — decode runs single-threaded with SIMD acceleration.
 - `transcode()` v1 only accepts mediabunny-readable inputs (MP4/MKV/WebM/OGG/MOV/MP3/FLAC/WAV). AVI/ASF/FLV transcoding is planned for v1.1.
 - `transcode()` uses **WebCodecs encoders only** — codec availability depends on the browser. AV1 encoding is not yet universal.
-- For the **hybrid and fallback strategies**, `<avbridge-player>.buffered` returns an empty `TimeRanges` because the canvas-based renderers don't track buffered ranges yet. Native and remux strategies expose the full `<video>.buffered` set as expected.
+- For the **hybrid and fallback strategies**, `<avbridge-video>.buffered` returns an empty `TimeRanges` because the canvas-based renderers don't track buffered ranges yet. Native and remux strategies expose the full `<video>.buffered` set as expected.
 
 ## Demos
 

package/dist/{chunk-FKM7QBZU.js → chunk-HZF5JDOO.js}

@@ -90,7 +90,7 @@ function mediabunnyVideoToAvbridge(c) {
     case "av1":
       return "av1";
     default:
-      return "h264";
+      return c ? c : "unknown";
   }
 }
 function avbridgeVideoToMediabunny(c) {
@@ -126,7 +126,7 @@ function mediabunnyAudioToAvbridge(c) {
     case "eac3":
       return "eac3";
     default:
-      return c ?? "aac";
+      return c ? c : "unknown";
   }
 }
 function avbridgeAudioToMediabunny(c) {
@@ -533,19 +533,38 @@ var Diagnostics = class {
     if (typeof src === "string" || src instanceof URL) {
       this.sourceType = "url";
       this.transport = "http-range";
-      this.rangeSupported = true;
+      this.rangeSupported = void 0;
     } else {
       this.sourceType = "blob";
       this.transport = "memory";
+      this.rangeSupported = false;
     }
   }
+  /**
+   * Called by a strategy once it has a confirmed answer about how the
+   * source bytes are actually flowing (e.g. after the libav HTTP block
+   * reader's initial Range probe succeeded). Lets diagnostics report the
+   * truth instead of an input-type heuristic.
+   */
+  recordTransport(transport, rangeSupported) {
+    this.transport = transport;
+    this.rangeSupported = rangeSupported;
+  }
   recordClassification(c) {
     this.strategy = c.strategy;
     this.strategyClass = c.class;
     this.reason = c.reason;
   }
   recordRuntime(stats) {
-    this.runtime = { ...this.runtime, ...stats };
+    const {
+      _transport,
+      _rangeSupported,
+      ...rest
+    } = stats;
+    if (_transport != null && typeof _rangeSupported === "boolean") {
+      this.recordTransport(_transport, _rangeSupported);
+    }
+    this.runtime = { ...this.runtime, ...rest };
   }
   recordStrategySwitch(strategy, reason) {
     this.strategy = strategy;
@@ -1707,6 +1726,9 @@ async function startHybridDecoder(opts) {
         videoChunksFed,
         audioFramesDecoded,
         videoDecodeQueueSize: videoDecoder?.decodeQueueSize ?? 0,
+        // Confirmed transport info — see fallback decoder for the pattern.
+        _transport: inputHandle.transport === "http-range" ? "http-range" : "memory",
+        _rangeSupported: inputHandle.transport === "http-range",
         ...opts.renderer.stats(),
         ...opts.audio.stats()
       };
@@ -2248,6 +2270,12 @@ async function startDecoder(opts) {
         packetsRead,
         videoFramesDecoded,
         audioFramesDecoded,
+        // 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
+        // these `_`-prefixed keys to the typed fields.
+        _transport: inputHandle.transport === "http-range" ? "http-range" : "memory",
+        _rangeSupported: inputHandle.transport === "http-range",
         ...opts.renderer.stats(),
         ...opts.audio.stats()
       };
@@ -2529,7 +2557,7 @@ function isVtt(text) {
 }
 
 // src/subtitles/index.ts
-async function discoverSidecar(file, directory) {
+async function discoverSidecars(file, directory) {
   const baseName = file.name.replace(/\.[^.]+$/, "");
   const found = [];
   for await (const [name, handle] of directory) {
@@ -2551,33 +2579,56 @@ async function discoverSidecar(file, directory) {
   }
   return found;
 }
-async function attachSubtitleTracks(video, tracks) {
+var SubtitleResourceBag = class {
+  urls = /* @__PURE__ */ new Set();
+  /** Track an externally-created blob URL (e.g. from `discoverSidecars`). */
+  track(url) {
+    this.urls.add(url);
+  }
+  /** Convenience: create a blob URL and track it in one call. */
+  createObjectURL(blob) {
+    const url = URL.createObjectURL(blob);
+    this.urls.add(url);
+    return url;
+  }
+  /** Revoke every tracked URL. Idempotent — safe to call multiple times. */
+  revokeAll() {
+    for (const u of this.urls) URL.revokeObjectURL(u);
+    this.urls.clear();
+  }
+};
+async function attachSubtitleTracks(video, tracks, bag, onError) {
   for (const t of Array.from(video.querySelectorAll("track[data-avbridge]"))) {
     t.remove();
   }
   for (const t of tracks) {
     if (!t.sidecarUrl) continue;
-    let url = t.sidecarUrl;
-    if (t.format === "srt") {
-      const res = await fetch(t.sidecarUrl);
-      const text = await res.text();
-      const vtt = srtToVtt(text);
-      const blob = new Blob([vtt], { type: "text/vtt" });
-      url = URL.createObjectURL(blob);
-    } else if (t.format === "vtt") {
-      const res = await fetch(t.sidecarUrl);
-      const text = await res.text();
-      if (!isVtt(text)) {
-        console.warn("[avbridge] subtitle missing WEBVTT header:", t.sidecarUrl);
-      }
-    }
-    const track = document.createElement("track");
-    track.kind = "subtitles";
-    track.src = url;
-    track.srclang = t.language ?? "und";
-    track.label = t.language ?? `Subtitle ${t.id}`;
-    track.dataset.avbridge = "true";
-    video.appendChild(track);
+    try {
+      let url = t.sidecarUrl;
+      if (t.format === "srt") {
+        const res = await fetch(t.sidecarUrl);
+        const text = await res.text();
+        const vtt = srtToVtt(text);
+        const blob = new Blob([vtt], { type: "text/vtt" });
+        url = bag ? bag.createObjectURL(blob) : URL.createObjectURL(blob);
+      } else if (t.format === "vtt") {
+        const res = await fetch(t.sidecarUrl);
+        const text = await res.text();
+        if (!isVtt(text)) {
+          console.warn("[avbridge] subtitle missing WEBVTT header:", t.sidecarUrl);
+        }
+      }
+      const trackEl = document.createElement("track");
+      trackEl.kind = "subtitles";
+      trackEl.src = url;
+      trackEl.srclang = t.language ?? "und";
+      trackEl.label = t.language ?? `Subtitle ${t.id}`;
+      trackEl.dataset.avbridge = "true";
+      video.appendChild(trackEl);
+    } catch (err) {
+      const e = err instanceof Error ? err : new Error(String(err));
+      onError?.(e, t);
+    }
   }
 }
 
@@ -2606,6 +2657,9 @@ var UnifiedPlayer = class _UnifiedPlayer {
   errorListener = 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();
   static async create(options) {
     const registry = new PluginRegistry();
     registerBuiltins(registry);
@@ -2641,8 +2695,9 @@ var UnifiedPlayer = class _UnifiedPlayer {
         }
       }
       if (this.options.directory && this.options.source instanceof File) {
-        const found = await discoverSidecar(this.options.source, this.options.directory);
+        const found = await discoverSidecars(this.options.source, this.options.directory);
         for (const s of found) {
+          this.subtitleResources.track(s.url);
           ctx.subtitleTracks.push({
             id: ctx.subtitleTracks.length,
             format: s.format,
@@ -2651,11 +2706,7 @@ var UnifiedPlayer = class _UnifiedPlayer {
           });
         }
       }
-      const decision = this.options.forceStrategy ? {
-        class: "NATIVE",
-        strategy: this.options.forceStrategy,
-        reason: `forced via options.forceStrategy=${this.options.forceStrategy}`
-      } : classifyContext(ctx);
+      const decision = this.options.initialStrategy ? buildInitialDecision(this.options.initialStrategy, ctx) : classifyContext(ctx);
       this.classification = decision;
       this.diag.recordClassification(decision);
       this.emitter.emitSticky("strategy", {
@@ -2664,7 +2715,14 @@ var UnifiedPlayer = class _UnifiedPlayer {
       });
       await this.startSession(decision.strategy, decision.reason);
       if (this.session.strategy !== "fallback" && this.session.strategy !== "hybrid") {
-        attachSubtitleTracks(this.options.target, ctx.subtitleTracks);
+        await attachSubtitleTracks(
+          this.options.target,
+          ctx.subtitleTracks,
+          this.subtitleResources,
+          (err, track) => {
+            console.warn(`[avbridge] subtitle ${track.id} failed: ${err.message}`);
+          }
+        );
       }
       this.emitter.emitSticky("tracks", {
         video: ctx.videoTracks,
@@ -2739,15 +2797,6 @@ var UnifiedPlayer = class _UnifiedPlayer {
     const currentTime = this.session?.getCurrentTime() ?? 0;
     const wasPlaying = this.session ? !this.options.target.paused : false;
     const fromStrategy = this.session?.strategy ?? "native";
-    const nextStrategy = chain.shift();
-    console.warn(`[avbridge] escalating from ${fromStrategy} to ${nextStrategy}: ${reason}`);
-    this.emitter.emit("strategychange", {
-      from: fromStrategy,
-      to: nextStrategy,
-      reason,
-      currentTime
-    });
-    this.diag.recordStrategySwitch(nextStrategy, reason);
     this.clearSupervisor();
     if (this.session) {
       try {
@@ -2756,31 +2805,49 @@ var UnifiedPlayer = class _UnifiedPlayer {
       }
       this.session = null;
     }
-    const plugin = this.registry.findFor(this.mediaContext, nextStrategy);
-    if (!plugin) {
-      this.emitter.emit("error", new Error(`no plugin for fallback strategy "${nextStrategy}"`));
-      return;
-    }
-    try {
-      this.session = await plugin.execute(this.mediaContext, this.options.target);
-    } catch (err) {
-      this.emitter.emit("error", err instanceof Error ? err : new Error(String(err)));
+    const errors = [];
+    while (chain.length > 0) {
+      const nextStrategy = chain.shift();
+      console.warn(`[avbridge] escalating from ${fromStrategy} to ${nextStrategy}: ${reason}`);
+      this.emitter.emit("strategychange", {
+        from: fromStrategy,
+        to: nextStrategy,
+        reason,
+        currentTime
+      });
+      this.diag.recordStrategySwitch(nextStrategy, reason);
+      const plugin = this.registry.findFor(this.mediaContext, nextStrategy);
+      if (!plugin) {
+        errors.push(`${nextStrategy}: no plugin available`);
+        continue;
+      }
+      try {
+        this.session = await plugin.execute(this.mediaContext, this.options.target);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        errors.push(`${nextStrategy}: ${msg}`);
+        console.warn(`[avbridge] ${nextStrategy} failed during escalation, trying next: ${msg}`);
+        continue;
+      }
+      this.emitter.emitSticky("strategy", {
+        strategy: nextStrategy,
+        reason: `escalated: ${reason}`
+      });
+      this.session.onFatalError?.((fatalReason) => {
+        void this.escalate(fatalReason);
+      });
+      this.attachSupervisor();
+      try {
+        await this.session.seek(currentTime);
+        if (wasPlaying) await this.session.play();
+      } catch (err) {
+        console.warn("[avbridge] failed to restore position after escalation:", err);
+      }
       return;
     }
-    this.emitter.emitSticky("strategy", {
-      strategy: nextStrategy,
-      reason: `escalated: ${reason}`
-    });
-    this.session.onFatalError?.((fatalReason) => {
-      void this.escalate(fatalReason);
-    });
-    this.attachSupervisor();
-    try {
-      await this.session.seek(currentTime);
-      if (wasPlaying) await this.session.play();
-    } catch (err) {
-      console.warn("[avbridge] failed to restore position after escalation:", err);
-    }
+    this.emitter.emit("error", new Error(
+      `all fallback strategies failed: ${errors.join("; ")}`
+    ));
   }
   // ── Stall supervision ─────────────────────────────────────────────────
   attachSupervisor() {
@@ -2945,13 +3012,49 @@ var UnifiedPlayer = class _UnifiedPlayer {
       await this.session.destroy();
       this.session = null;
     }
+    this.subtitleResources.revokeAll();
     this.emitter.removeAll();
   }
 };
 async function createPlayer(options) {
   return UnifiedPlayer.create(options);
 }
+function buildInitialDecision(initial, ctx) {
+  const natural = classifyContext(ctx);
+  const cls = strategyToClass(initial, natural);
+  return {
+    class: cls,
+    strategy: initial,
+    reason: `initial strategy "${initial}" requested via options.initialStrategy`,
+    fallbackChain: natural.fallbackChain ?? defaultFallbackChain(initial)
+  };
+}
+function strategyToClass(strategy, natural) {
+  if (natural.strategy === strategy) return natural.class;
+  switch (strategy) {
+    case "native":
+      return "NATIVE";
+    case "remux":
+      return "REMUX_CANDIDATE";
+    case "hybrid":
+      return "HYBRID_CANDIDATE";
+    case "fallback":
+      return "FALLBACK_REQUIRED";
+  }
+}
+function defaultFallbackChain(strategy) {
+  switch (strategy) {
+    case "native":
+      return ["remux", "hybrid", "fallback"];
+    case "remux":
+      return ["hybrid", "fallback"];
+    case "hybrid":
+      return ["fallback"];
+    case "fallback":
+      return [];
+  }
+}
 
 export { UnifiedPlayer, avbridgeAudioToMediabunny, avbridgeVideoToMediabunny, buildMediabunnySourceFromInput, classifyContext, createPlayer, probe, srtToVtt };
-//# sourceMappingURL=chunk-FKM7QBZU.js.map
-//# sourceMappingURL=chunk-FKM7QBZU.js.map
+//# sourceMappingURL=chunk-HZF5JDOO.js.map
+//# sourceMappingURL=chunk-HZF5JDOO.js.map