avbridge 2.1.0 → 2.1.2

package/dist/index.d.cts

@@ -11,12 +11,16 @@ declare function classifyContext(ctx: MediaContext): Classification;
  *
  * Routing:
  * 1. Sniff the magic header. Cheap, deterministic, ignores file extensions.
- * 2. If the container is one mediabunny supports → mediabunny. If mediabunny
- *    rejects, surface the real error rather than blindly falling through to
- *    libav (which would mask the real failure with a confusing libav error).
- * 3. If sniffing identifies AVI/ASF/FLV (or `unknown`) → libav.js, lazy-loaded.
- *    `unknown` is included so genuinely unfamiliar files at least get a shot
- *    at the broader libav demuxer set.
+ * 2. If the container is one mediabunny supports → try mediabunny first
+ *    (fast path — it's a single pass of WASM-free JS parsing). If mediabunny
+ *    throws (e.g. an assertion on an unsupported sample entry like `mp4v`
+ *    for MPEG-4 Part 2 in ISOBMFF, or an exotic MKV codec), fall through to
+ *    libav.js which handles the long tail of codecs mediabunny doesn't.
+ *    The combined-error case surfaces *both* failures so the user sees
+ *    which path each step took.
+ * 3. If sniffing identifies AVI/ASF/FLV (or `unknown`) → libav.js directly.
+ *    mediabunny can't read those containers at all, so there's no fast path
+ *    to try.
  */
 declare function probe(source: MediaInput): Promise<MediaContext>;
 

package/dist/index.d.ts

@@ -11,12 +11,16 @@ declare function classifyContext(ctx: MediaContext): Classification;
  *
  * Routing:
  * 1. Sniff the magic header. Cheap, deterministic, ignores file extensions.
- * 2. If the container is one mediabunny supports → mediabunny. If mediabunny
- *    rejects, surface the real error rather than blindly falling through to
- *    libav (which would mask the real failure with a confusing libav error).
- * 3. If sniffing identifies AVI/ASF/FLV (or `unknown`) → libav.js, lazy-loaded.
- *    `unknown` is included so genuinely unfamiliar files at least get a shot
- *    at the broader libav demuxer set.
+ * 2. If the container is one mediabunny supports → try mediabunny first
+ *    (fast path — it's a single pass of WASM-free JS parsing). If mediabunny
+ *    throws (e.g. an assertion on an unsupported sample entry like `mp4v`
+ *    for MPEG-4 Part 2 in ISOBMFF, or an exotic MKV codec), fall through to
+ *    libav.js which handles the long tail of codecs mediabunny doesn't.
+ *    The combined-error case surfaces *both* failures so the user sees
+ *    which path each step took.
+ * 3. If sniffing identifies AVI/ASF/FLV (or `unknown`) → libav.js directly.
+ *    mediabunny can't read those containers at all, so there's no fast path
+ *    to try.
  */
 declare function probe(source: MediaInput): Promise<MediaContext>;
 

package/dist/index.js

@@ -1,5 +1,5 @@
-import { probe, avbridgeVideoToMediabunny, avbridgeAudioToMediabunny, buildMediabunnySourceFromInput } from './chunk-CUQD23WO.js';
-export { UnifiedPlayer, classifyContext as classify, createPlayer, probe, srtToVtt } from './chunk-CUQD23WO.js';
+import { probe, avbridgeVideoToMediabunny, avbridgeAudioToMediabunny, buildMediabunnySourceFromInput } from './chunk-3AUGRKPY.js';
+export { UnifiedPlayer, classifyContext as classify, createPlayer, probe, srtToVtt } from './chunk-3AUGRKPY.js';
 import { normalizeSource } from './chunk-PQTZS7OA.js';
 import { prepareLibavInput } from './chunk-WD2ZNQA7.js';
 import './chunk-EJH67FXG.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "avbridge",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "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-video.ts

@@ -170,11 +170,22 @@ export class AvbridgeVideoElement extends HTMLElementCtor {
   constructor() {
     super();
     const root = this.attachShadow({ mode: "open" });
+
+    // A positioned wrapper inside the shadow root. The fallback strategy
+    // overlays a canvas on top of the <video> via `target.parentNode` —
+    // that only works if the parent is a real Element with layout. Without
+    // this wrapper, `target.parentElement` would be null (ShadowRoot is
+    // not an Element) and the canvas would never attach to the DOM.
+    const stage = document.createElement("div");
+    stage.setAttribute("part", "stage");
+    stage.style.cssText = "position:relative;width:100%;height:100%;display:block;";
+    root.appendChild(stage);
+
     this._videoEl = document.createElement("video");
     this._videoEl.setAttribute("part", "video");
     this._videoEl.style.cssText = "width:100%;height:100%;display:block;background:#000;";
     this._videoEl.playsInline = true;
-    root.appendChild(this._videoEl);
+    stage.appendChild(this._videoEl);
 
     // Forward the underlying <video>'s `progress` event so consumers can
     // observe buffered-range updates without reaching into the shadow DOM.

package/src/probe/index.ts

@@ -21,12 +21,16 @@ const MEDIABUNNY_CONTAINERS = new Set<ContainerKind>([
  *
  * Routing:
  * 1. Sniff the magic header. Cheap, deterministic, ignores file extensions.
- * 2. If the container is one mediabunny supports → mediabunny. If mediabunny
- *    rejects, surface the real error rather than blindly falling through to
- *    libav (which would mask the real failure with a confusing libav error).
- * 3. If sniffing identifies AVI/ASF/FLV (or `unknown`) → libav.js, lazy-loaded.
- *    `unknown` is included so genuinely unfamiliar files at least get a shot
- *    at the broader libav demuxer set.
+ * 2. If the container is one mediabunny supports → try mediabunny first
+ *    (fast path — it's a single pass of WASM-free JS parsing). If mediabunny
+ *    throws (e.g. an assertion on an unsupported sample entry like `mp4v`
+ *    for MPEG-4 Part 2 in ISOBMFF, or an exotic MKV codec), fall through to
+ *    libav.js which handles the long tail of codecs mediabunny doesn't.
+ *    The combined-error case surfaces *both* failures so the user sees
+ *    which path each step took.
+ * 3. If sniffing identifies AVI/ASF/FLV (or `unknown`) → libav.js directly.
+ *    mediabunny can't read those containers at all, so there's no fast path
+ *    to try.
  */
 export async function probe(source: MediaInput): Promise<MediaContext> {
   const normalized = await normalizeSource(source);
@@ -35,10 +39,27 @@ export async function probe(source: MediaInput): Promise<MediaContext> {
   if (MEDIABUNNY_CONTAINERS.has(sniffed)) {
     try {
       return await probeWithMediabunny(normalized, sniffed);
-    } catch (err) {
-      throw new Error(
-        `mediabunny failed to probe a ${sniffed} file: ${(err as Error).message}`,
+    } catch (mediabunnyErr) {
+      // mediabunny rejected the file. Before giving up, try libav — it can
+      // demux a much wider range of codec combinations in ISOBMFF/MKV/etc.
+      // than mediabunny's pure-JS parser (e.g. mp4v, wmv3-in-asf, flac in
+      // an MP4 container). This is "escalation", not "masking": if libav
+      // also fails we surface both errors below.
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[avbridge] mediabunny rejected ${sniffed} file, falling back to libav:`,
+        (mediabunnyErr as Error).message,
       );
+      try {
+        const { probeWithLibav } = await import("./avi.js");
+        return await probeWithLibav(normalized, sniffed);
+      } catch (libavErr) {
+        const mbMsg = (mediabunnyErr as Error).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}.`,
+        );
+      }
     }
   }
 

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

@@ -53,11 +53,36 @@ export class VideoRenderer {
     this.canvas = document.createElement("canvas");
     this.canvas.style.cssText =
       "position:absolute;left:0;top:0;width:100%;height:100%;background:black;";
-    const parent = target.parentElement;
-    if (parent && getComputedStyle(parent).position === "static") {
-      parent.style.position = "relative";
+
+    // Attach the canvas next to the video. When the video lives inside an
+    // `<avbridge-video>` shadow root, `target.parentElement` is the
+    // positioned `<div part="stage">` wrapper the element created
+    // precisely for this purpose. When the video is used standalone
+    // (legacy `createPlayer({ target: videoEl })` path), we fall back to
+    // `parentNode` — which handles plain Elements, and also ShadowRoots
+    // if someone inserts a bare <video> inside their own shadow DOM
+    // without a wrapper.
+    const parent: ParentNode | null =
+      (target.parentElement as ParentNode | null) ?? target.parentNode;
+    if (parent && parent instanceof HTMLElement) {
+      if (getComputedStyle(parent).position === "static") {
+        parent.style.position = "relative";
+      }
+    }
+    if (parent) {
+      parent.insertBefore(this.canvas, target);
+    } else {
+      // No parent at all — the target is detached. Fall back to appending
+      // the canvas to document.body so at least the frames are visible
+      // somewhere while the consumer fixes their DOM layout. This is a
+      // loud fallback: log a warning so the misuse is obvious.
+      // eslint-disable-next-line no-console
+      console.warn(
+        "[avbridge] fallback renderer: target <video> has no parent; " +
+        "appending canvas to document.body as a fallback.",
+      );
+      document.body.appendChild(this.canvas);
     }
-    parent?.insertBefore(this.canvas, target);
     target.style.visibility = "hidden";
 
     const ctx = this.canvas.getContext("2d");

package/src/strategies/remux/pipeline.ts

@@ -187,7 +187,16 @@ export async function createRemuxPipeline(
       const vTs = !vNext.done ? vNext.value.timestamp : Number.POSITIVE_INFINITY;
       const aTs = !aNext.done ? aNext.value.timestamp : Number.POSITIVE_INFINITY;
 
-      if (!vNext.done && vTs <= aTs) {
+      // Mediabunny's muxer requires the first packet on a fresh Output to
+      // be a key packet. We fetched `startVideoPacket` via
+      // `videoSink.getKeyPacket(fromTime)` so the first video packet is
+      // guaranteed to be a keyframe — but a demuxer can hand us an audio
+      // packet with a lower timestamp, which mediabunny rejects with
+      // "First packet must be a key packet." Force the first video
+      // packet out before we let any audio through.
+      const forceVideoFirst = firstVideo && !vNext.done;
+
+      if (!vNext.done && (forceVideoFirst || vTs <= aTs)) {
         await videoSource.add(
           vNext.value,
           firstVideo && videoConfig ? { decoderConfig: videoConfig } : undefined,