avbridge 2.3.0 → 2.5.0

package/src/convert/transcode.ts

@@ -16,6 +16,8 @@
 import { probe } from "../probe/index.js";
 import { buildMediabunnySourceFromInput } from "../probe/mediabunny.js";
 import { createOutputFormat, mimeForFormat, generateFilename } from "./remux.js";
+import { isLibavTranscodeContainer, transcodeViaLibav } from "./transcode-libav.js";
+import { AvbridgeError, ERR_CONTAINER_NOT_SUPPORTED } from "../errors.js";
 import type {
   MediaInput,
   MediaContext,
@@ -54,11 +56,17 @@ export async function transcode(
   const ctx = await probe(source);
   options.signal?.throwIfAborted();
 
+  // AVI/ASF/FLV → the libav-demux-backed pipeline (Phase 1: MP4 output only).
+  if (isLibavTranscodeContainer(ctx.container)) {
+    return transcodeViaLibav(ctx, options);
+  }
+
   if (!MEDIABUNNY_CONTAINERS.has(ctx.container)) {
-    throw new Error(
-      `Cannot transcode "${ctx.container}" sources in v1. ` +
-      `transcode() only supports inputs that mediabunny can read (MP4, MKV, WebM, OGG, MP3, FLAC, WAV, MOV). ` +
-      `For AVI/ASF/FLV sources, use the player's playback strategies instead.`,
+    throw new AvbridgeError(
+      ERR_CONTAINER_NOT_SUPPORTED,
+      `Cannot transcode "${ctx.container}" sources. ` +
+      `transcode() supports mediabunny-readable containers (MP4, MKV, WebM, OGG, MP3, FLAC, WAV, MOV) and legacy containers via the libav path (AVI, ASF, FLV).`,
+      `If this is a legacy container we don't yet support, use createPlayer() to play it. Transcode support for more containers is on the roadmap.`,
     );
   }
 

package/src/element/avbridge-player.ts

@@ -824,6 +824,22 @@ export class AvbridgePlayerElement extends HTMLElement {
   get strategyClass(): string | undefined { return this._video.strategyClass ?? undefined; }
   get audioTracks(): unknown[] { return this._video.audioTracks ?? []; }
   get subtitleTracks(): unknown[] { return this._video.subtitleTracks ?? []; }
+
+  /**
+   * External subtitle files to attach when the source loads. Forwarded
+   * to the inner <avbridge-video>. Takes effect on next bootstrap.
+   */
+  get subtitles(): unknown {
+    return (this._video as unknown as { subtitles: unknown }).subtitles;
+  }
+  set subtitles(value: unknown) {
+    (this._video as unknown as { subtitles: unknown }).subtitles = value;
+  }
+
+  /** Attach a subtitle track to the current playback without a reload. */
+  async addSubtitle(subtitle: { url: string; language?: string; format?: "vtt" | "srt" }): Promise<void> {
+    return (this._video as unknown as { addSubtitle: (s: unknown) => Promise<void> }).addSubtitle(subtitle);
+  }
   get player(): unknown { return this._video.player; }
   get videoElement(): HTMLVideoElement { return this._video.videoElement; }
 

package/src/element/avbridge-video.ts

@@ -147,6 +147,14 @@ export class AvbridgeVideoElement extends HTMLElementCtor {
   private _audioTracks: AudioTrackInfo[] = [];
   private _subtitleTracks: SubtitleTrackInfo[] = [];
 
+  /**
+   * External subtitle list forwarded to `createPlayer()` on the next
+   * bootstrap. Setting this after bootstrap queues it for the next
+   * source change; consumers that need to swap subtitles mid-playback
+   * should set `source` to reload.
+   */
+  private _subtitles: Array<{ url: string; language?: string; format?: "vtt" | "srt" }> | null = null;
+
   /**
    * Initial strategy preference. `"auto"` means "let the classifier decide";
    * any other value is passed to `createPlayer({ initialStrategy })` and
@@ -358,6 +366,7 @@ export class AvbridgeVideoElement extends HTMLElementCtor {
         ...(this._preferredStrategy !== "auto"
           ? { initialStrategy: this._preferredStrategy }
           : {}),
+        ...(this._subtitles ? { subtitles: this._subtitles } : {}),
       });
     } catch (err) {
       // Stale or destroyed — silently abandon.
@@ -709,6 +718,51 @@ export class AvbridgeVideoElement extends HTMLElementCtor {
     return this._subtitleTracks;
   }
 
+  /**
+   * External subtitle files to attach when the source loads. Takes effect
+   * on the next bootstrap — set before assigning `source`, or reload via
+   * `load()` after changing. For dynamic post-bootstrap addition, use
+   * `addSubtitle()` instead.
+   *
+   * @example
+   * el.subtitles = [{ url: "/en.srt", format: "srt", language: "en" }];
+   * el.src = "/movie.mp4";
+   */
+  get subtitles(): Array<{ url: string; language?: string; format?: "vtt" | "srt" }> | null {
+    return this._subtitles;
+  }
+
+  set subtitles(value: Array<{ url: string; language?: string; format?: "vtt" | "srt" }> | null) {
+    this._subtitles = value;
+  }
+
+  /**
+   * Attach a subtitle track to the current playback without rebuilding
+   * the player. Works while the element is playing — converts SRT to
+   * VTT if needed, adds a `<track>` to the inner `<video>`. Canvas
+   * strategies pick up the new track via their textTracks watcher.
+   */
+  async addSubtitle(subtitle: { url: string; language?: string; format?: "vtt" | "srt" }): Promise<void> {
+    const { attachSubtitleTracks } = await import("../subtitles/index.js");
+    const format = subtitle.format ?? (subtitle.url.endsWith(".srt") ? "srt" : "vtt");
+    const track = {
+      id: this._subtitleTracks.length,
+      format,
+      language: subtitle.language,
+      sidecarUrl: subtitle.url,
+    };
+    this._subtitleTracks.push(track);
+    await attachSubtitleTracks(
+      this._videoEl,
+      this._subtitleTracks,
+      undefined,
+      (err, t) => {
+        // eslint-disable-next-line no-console
+        console.warn(`[avbridge] subtitle ${t.id} failed: ${err.message}`);
+      },
+    );
+  }
+
   // ── Public methods ─────────────────────────────────────────────────────
 
   /** Force a (re-)bootstrap if a source is currently set. */

package/src/errors.ts

@@ -45,3 +45,9 @@ export const ERR_LIBAV_NOT_REACHABLE = "ERR_AVBRIDGE_LIBAV_NOT_REACHABLE";
 // MSE
 export const ERR_MSE_NOT_SUPPORTED = "ERR_AVBRIDGE_MSE_NOT_SUPPORTED";
 export const ERR_MSE_CODEC_NOT_SUPPORTED = "ERR_AVBRIDGE_MSE_CODEC_NOT_SUPPORTED";
+
+// Transcode
+export const ERR_TRANSCODE_ABORTED = "ERR_AVBRIDGE_TRANSCODE_ABORTED";
+export const ERR_TRANSCODE_UNSUPPORTED_COMBO = "ERR_AVBRIDGE_TRANSCODE_UNSUPPORTED_COMBO";
+export const ERR_TRANSCODE_DECODE = "ERR_AVBRIDGE_TRANSCODE_DECODE";
+export const ERR_CONTAINER_NOT_SUPPORTED = "ERR_AVBRIDGE_CONTAINER_NOT_SUPPORTED";

package/src/player.ts

@@ -147,22 +147,21 @@ export class UnifiedPlayer {
       // Try the primary strategy, falling through the chain on failure
       await this.startSession(decision.strategy, decision.reason);
 
-      // Apply subtitles for non-canvas strategies. Per-track failures are
-      // caught inside attachSubtitleTracks and logged via console.warn —
-      // subtitles are not load-bearing, so a bad sidecar must not break
-      // bootstrap.
-      if (this.session!.strategy !== "fallback" && this.session!.strategy !== "hybrid") {
-        await attachSubtitleTracks(
-          this.options.target,
-          ctx.subtitleTracks,
-          this.subtitleResources,
-          (err, track) => {
-            // eslint-disable-next-line no-console
-            console.warn(`[avbridge] subtitle ${track.id} failed: ${err.message}`);
-          },
-          this.transport,
-        );
-      }
+      // Apply subtitles for all strategies. Native/remux render them via
+      // the inner <video>'s native text-track engine. Hybrid/fallback
+      // hide the <video> and render cues into the canvas overlay — see
+      // each session's SubtitleOverlay wiring. The <track> elements are
+      // attached in both cases so cues are parsed by the browser.
+      await attachSubtitleTracks(
+        this.options.target,
+        ctx.subtitleTracks,
+        this.subtitleResources,
+        (err, track) => {
+          // eslint-disable-next-line no-console
+          console.warn(`[avbridge] subtitle ${track.id} failed: ${err.message}`);
+        },
+        this.transport,
+      );
 
       this.emitter.emitSticky("tracks", {
         video: ctx.videoTracks,

package/src/strategies/fallback/decoder.ts

@@ -29,11 +29,22 @@ import { AudioOutput } from "./audio-output.js";
 import type { MediaContext } from "../../types.js";
 import { pickLibavVariant } from "./variant-routing.js";
 import { dbg } from "../../util/debug.js";
+import {
+  sanitizeFrameTimestamp,
+  libavFrameToInterleavedFloat32,
+} from "../../util/libav-demux.js";
 
 export interface DecoderHandles {
   destroy(): Promise<void>;
   /** Seek to the given time in seconds. Returns once the new pump has been kicked off. */
   seek(timeSec: number): Promise<void>;
+  /**
+   * Switch the active audio track. The decoder tears down the current audio
+   * decoder, initializes one for the stream whose container id matches
+   * `trackId` (== libav `stream.index`), seeks the demuxer to `timeSec`, and
+   * restarts the pump. No-op if the track is already active.
+   */
+  setAudioTrack(trackId: number, timeSec: number): Promise<void>;
   stats(): Record<string, unknown>;
 }
 
@@ -63,7 +74,15 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
 
   const [fmt_ctx, streams] = await libav.ff_init_demuxer_file(opts.filename);
   const videoStream = streams.find((s) => s.codec_type === libav.AVMEDIA_TYPE_VIDEO) ?? null;
-  const audioStream = streams.find((s) => s.codec_type === libav.AVMEDIA_TYPE_AUDIO) ?? null;
+  // Audio stream is mutable so setAudioTrack() can swap it. Default to the
+  // track the context picked first (matches probe ordering). We resolve by
+  // container id so the selection survives stream reordering.
+  const firstAudioTrackId = opts.context.audioTracks[0]?.id;
+  let audioStream: LibavStream | null =
+    (firstAudioTrackId != null
+      ? streams.find((s) => s.codec_type === libav.AVMEDIA_TYPE_AUDIO && s.index === firstAudioTrackId)
+      : undefined) ??
+    streams.find((s) => s.codec_type === libav.AVMEDIA_TYPE_AUDIO) ?? null;
 
   if (!videoStream && !audioStream) {
     throw new Error("fallback decoder: file has no decodable streams");
@@ -376,7 +395,7 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
 
     for (const f of frames) {
       if (myToken !== pumpToken || destroyed) return;
-      const bridgeOpts = sanitizeFrameTimestamp(
+      sanitizeFrameTimestamp(
         f,
         () => {
           const ts = syntheticVideoUs;
@@ -385,8 +404,10 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
         },
         videoTimeBase,
       );
+      // sanitizeFrameTimestamp normalizes pts to µs, so the bridge can
+      // always use the 1/1e6 timebase.
       try {
-        const vf = bridge.laFrameToVideoFrame(f, bridgeOpts);
+        const vf = bridge.laFrameToVideoFrame(f, { timeBase: [1, 1_000_000] });
         opts.renderer.enqueue(vf);
         videoFramesDecoded++;
       } catch (err) {
@@ -455,6 +476,78 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
       try { await inputHandle.detach(); } catch { /* ignore */ }
     },
 
+    async setAudioTrack(trackId, timeSec) {
+      if (audioStream && audioStream.index === trackId) return;
+      const newStream = streams.find(
+        (s) => s.codec_type === libav.AVMEDIA_TYPE_AUDIO && s.index === trackId,
+      );
+      if (!newStream) {
+        console.warn("[avbridge] fallback: setAudioTrack — no stream with id", trackId);
+        return;
+      }
+
+      // Stop the pump before touching libav state. Same discipline as seek().
+      const newToken = ++pumpToken;
+      if (pumpRunning) {
+        try { await pumpRunning; } catch { /* ignore */ }
+      }
+      if (destroyed) return;
+
+      // Tear down the old audio decoder and init a fresh one for the new stream.
+      if (audioDec) {
+        try { await libav.ff_free_decoder?.(audioDec.c, audioDec.pkt, audioDec.frame); } catch { /* ignore */ }
+        audioDec = null;
+      }
+      try {
+        const [, c, pkt, frame] = await libav.ff_init_decoder(newStream.codec_id, {
+          codecpar: newStream.codecpar,
+        });
+        audioDec = { c, pkt, frame };
+        audioTimeBase = newStream.time_base_num && newStream.time_base_den
+          ? [newStream.time_base_num, newStream.time_base_den]
+          : undefined;
+      } catch (err) {
+        console.warn(
+          "[avbridge] fallback: setAudioTrack init failed — falling back to no-audio mode:",
+          (err as Error).message,
+        );
+        audioDec = null;
+        opts.audio.setNoAudio();
+      }
+
+      audioStream = newStream;
+
+      // Re-seek so packets resume from the user's current position for the
+      // new track (and the same video position).
+      try {
+        const tsUs = Math.floor(timeSec * 1_000_000);
+        const [tsLo, tsHi] = libav.f64toi64
+          ? libav.f64toi64(tsUs)
+          : [tsUs | 0, Math.floor(tsUs / 0x100000000)];
+        await libav.av_seek_frame(
+          fmt_ctx,
+          -1,
+          tsLo,
+          tsHi,
+          libav.AVSEEK_FLAG_BACKWARD ?? 0,
+        );
+      } catch (err) {
+        console.warn("[avbridge] fallback: setAudioTrack seek failed:", err);
+      }
+
+      // Flush the video decoder too — we just moved the demuxer back to a
+      // keyframe boundary.
+      try { if (videoDec) await libav.avcodec_flush_buffers?.(videoDec.c); } catch { /* ignore */ }
+      await flushBSF();
+
+      syntheticVideoUs = Math.round(timeSec * 1_000_000);
+      syntheticAudioUs = Math.round(timeSec * 1_000_000);
+
+      pumpRunning = pumpLoop(newToken).catch((err) =>
+        console.error("[avbridge] fallback pump failed (post-setAudioTrack):", err),
+      );
+    },
+
     async seek(timeSec) {
       // Cancel the current pump and wait for it to actually exit before
       // we start moving file pointers around — concurrent ff_decode_multi
@@ -537,176 +630,6 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
   };
 }
 
-// ─────────────────────────────────────────────────────────────────────────────
-// Frame timestamp sanitizer.
-//
-// libav can hand back decoded frames with `pts = AV_NOPTS_VALUE` (encoded as
-// ptshi = -2147483648, pts = 0) for inputs whose demuxer can't determine
-// presentation times. AVI is the canonical example. The bridge's
-// `laFrameToVideoFrame` then multiplies pts × 1e6 × tbNum / tbDen and
-// overflows int64, throwing "Value is outside the 'long long' value range".
-//
-// Fix: replace any invalid pts with a synthetic microsecond counter, force
-// the frame's pts/ptshi to that value, and tell the bridge to use a 1/1e6
-// timebase so it does an identity conversion.
-// ─────────────────────────────────────────────────────────────────────────────
-
-interface BridgeOpts {
-  timeBase?: [number, number];
-  transfer?: boolean;
-}
-
-function sanitizeFrameTimestamp(
-  frame: LibavFrame,
-  nextUs: () => number,
-  fallbackTimeBase?: [number, number],
-): BridgeOpts {
-  const lo = frame.pts ?? 0;
-  const hi = frame.ptshi ?? 0;
-  const isInvalid = (hi === -2147483648 && lo === 0) || !Number.isFinite(lo);
-  if (isInvalid) {
-    const us = nextUs();
-    frame.pts = us;
-    frame.ptshi = 0;
-    return { timeBase: [1, 1_000_000] };
-  }
-  const tb = fallbackTimeBase ?? [1, 1_000_000];
-  const pts64 = hi * 0x100000000 + lo;
-  const us = Math.round((pts64 * 1_000_000 * tb[0]) / tb[1]);
-  if (Number.isFinite(us) && Math.abs(us) <= Number.MAX_SAFE_INTEGER) {
-    frame.pts = us;
-    frame.ptshi = us < 0 ? -1 : 0;
-    return { timeBase: [1, 1_000_000] };
-  }
-  const fallback = nextUs();
-  frame.pts = fallback;
-  frame.ptshi = 0;
-  return { timeBase: [1, 1_000_000] };
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// libav decoded `Frame` → interleaved Float32Array (the format AudioOutput
-// schedules).
-// ─────────────────────────────────────────────────────────────────────────────
-
-const AV_SAMPLE_FMT_U8 = 0;
-const AV_SAMPLE_FMT_S16 = 1;
-const AV_SAMPLE_FMT_S32 = 2;
-const AV_SAMPLE_FMT_FLT = 3;
-const AV_SAMPLE_FMT_U8P = 5;
-const AV_SAMPLE_FMT_S16P = 6;
-const AV_SAMPLE_FMT_S32P = 7;
-const AV_SAMPLE_FMT_FLTP = 8;
-
-interface InterleavedSamples {
-  data: Float32Array;
-  channels: number;
-  sampleRate: number;
-}
-
-function libavFrameToInterleavedFloat32(frame: LibavFrame): InterleavedSamples | null {
-  const channels = frame.channels ?? frame.ch_layout_nb_channels ?? 1;
-  const sampleRate = frame.sample_rate ?? 44100;
-  const nbSamples = frame.nb_samples ?? 0;
-  if (nbSamples === 0) return null;
-
-  const out = new Float32Array(nbSamples * channels);
-
-  switch (frame.format) {
-    case AV_SAMPLE_FMT_FLTP: {
-      const planes = ensurePlanes(frame.data, channels);
-      for (let ch = 0; ch < channels; ch++) {
-        const plane = asFloat32(planes[ch]);
-        for (let i = 0; i < nbSamples; i++) out[i * channels + ch] = plane[i];
-      }
-      return { data: out, channels, sampleRate };
-    }
-    case AV_SAMPLE_FMT_FLT: {
-      const flat = asFloat32(frame.data);
-      for (let i = 0; i < nbSamples * channels; i++) out[i] = flat[i];
-      return { data: out, channels, sampleRate };
-    }
-    case AV_SAMPLE_FMT_S16P: {
-      const planes = ensurePlanes(frame.data, channels);
-      for (let ch = 0; ch < channels; ch++) {
-        const plane = asInt16(planes[ch]);
-        for (let i = 0; i < nbSamples; i++) out[i * channels + ch] = plane[i] / 32768;
-      }
-      return { data: out, channels, sampleRate };
-    }
-    case AV_SAMPLE_FMT_S16: {
-      const flat = asInt16(frame.data);
-      for (let i = 0; i < nbSamples * channels; i++) out[i] = flat[i] / 32768;
-      return { data: out, channels, sampleRate };
-    }
-    case AV_SAMPLE_FMT_S32P: {
-      const planes = ensurePlanes(frame.data, channels);
-      for (let ch = 0; ch < channels; ch++) {
-        const plane = asInt32(planes[ch]);
-        for (let i = 0; i < nbSamples; i++) out[i * channels + ch] = plane[i] / 2147483648;
-      }
-      return { data: out, channels, sampleRate };
-    }
-    case AV_SAMPLE_FMT_S32: {
-      const flat = asInt32(frame.data);
-      for (let i = 0; i < nbSamples * channels; i++) out[i] = flat[i] / 2147483648;
-      return { data: out, channels, sampleRate };
-    }
-    case AV_SAMPLE_FMT_U8P: {
-      const planes = ensurePlanes(frame.data, channels);
-      for (let ch = 0; ch < channels; ch++) {
-        const plane = asUint8(planes[ch]);
-        for (let i = 0; i < nbSamples; i++) out[i * channels + ch] = (plane[i] - 128) / 128;
-      }
-      return { data: out, channels, sampleRate };
-    }
-    case AV_SAMPLE_FMT_U8: {
-      const flat = asUint8(frame.data);
-      for (let i = 0; i < nbSamples * channels; i++) out[i] = (flat[i] - 128) / 128;
-      return { data: out, channels, sampleRate };
-    }
-    default:
-      if (!(globalThis as { __avbridgeLoggedSampleFmt?: number }).__avbridgeLoggedSampleFmt) {
-        (globalThis as { __avbridgeLoggedSampleFmt?: number }).__avbridgeLoggedSampleFmt = frame.format;
-        console.warn(`[avbridge] unsupported audio sample format from libav: ${frame.format}`);
-      }
-      return null;
-  }
-}
-
-function ensurePlanes(data: unknown, channels: number): unknown[] {
-  if (Array.isArray(data)) return data;
-  const arr = data as { length: number; subarray?: (a: number, b: number) => unknown };
-  const len = arr.length;
-  const perChannel = Math.floor(len / channels);
-  const planes: unknown[] = [];
-  for (let ch = 0; ch < channels; ch++) {
-    planes.push(arr.subarray ? arr.subarray(ch * perChannel, (ch + 1) * perChannel) : arr);
-  }
-  return planes;
-}
-
-function asFloat32(x: unknown): Float32Array {
-  if (x instanceof Float32Array) return x;
-  const ta = x as { buffer: ArrayBuffer; byteOffset: number; byteLength: number };
-  return new Float32Array(ta.buffer, ta.byteOffset, ta.byteLength / 4);
-}
-function asInt16(x: unknown): Int16Array {
-  if (x instanceof Int16Array) return x;
-  const ta = x as { buffer: ArrayBuffer; byteOffset: number; byteLength: number };
-  return new Int16Array(ta.buffer, ta.byteOffset, ta.byteLength / 2);
-}
-function asInt32(x: unknown): Int32Array {
-  if (x instanceof Int32Array) return x;
-  const ta = x as { buffer: ArrayBuffer; byteOffset: number; byteLength: number };
-  return new Int32Array(ta.buffer, ta.byteOffset, ta.byteLength / 4);
-}
-function asUint8(x: unknown): Uint8Array {
-  if (x instanceof Uint8Array) return x;
-  const ta = x as { buffer: ArrayBuffer; byteOffset: number; byteLength: number };
-  return new Uint8Array(ta.buffer, ta.byteOffset, ta.byteLength);
-}
-
 // ─────────────────────────────────────────────────────────────────────────────
 // Bridge loader (lazy via the static-import wrapper).
 // ─────────────────────────────────────────────────────────────────────────────

package/src/strategies/fallback/index.ts

@@ -256,8 +256,25 @@ export async function createFallbackSession(
       await doSeek(time);
     },
 
-    async setAudioTrack(_id) {
-      // Multi-track audio is post-MVP for the fallback strategy.
+    async setAudioTrack(id) {
+      // Verify the id refers to a real track.
+      if (!ctx.audioTracks.some((t) => t.id === id)) {
+        console.warn("[avbridge] fallback: setAudioTrack — unknown track id", id);
+        return;
+      }
+      const wasPlaying = audio.isPlaying();
+      const currentTime = audio.now();
+      // Suspend audio, rebuild the decoder + seek, reset audio output, re-gate.
+      await audio.pause().catch(() => {});
+      await handles.setAudioTrack(id, currentTime).catch((err) =>
+        console.warn("[avbridge] fallback: handles.setAudioTrack failed:", err),
+      );
+      await audio.reset(currentTime);
+      renderer.flush();
+      if (wasPlaying) {
+        await waitForBuffer();
+        await audio.start();
+      }
     },
 
     async setSubtitleTrack(_id) {

package/src/strategies/fallback/libav-import.ts

@@ -23,5 +23,13 @@ export interface BridgeModule {
   audioStreamToConfig(libav: unknown, stream: unknown): Promise<AudioDecoderConfig | null>;
   packetToEncodedVideoChunk(pkt: unknown, stream: unknown): EncodedVideoChunk;
   packetToEncodedAudioChunk(pkt: unknown, stream: unknown): EncodedAudioChunk;
-  libavFrameToVideoFrame?(frame: unknown, stream: unknown): VideoFrame | null;
+  /**
+   * Convert a libav-decoded frame (software OR hardware decode) into a
+   * WebCodecs VideoFrame. `opts.timeBase` overrides the frame's per-packet
+   * timebase; useful when callers have already normalized pts to µs.
+   */
+  laFrameToVideoFrame(
+    frame: unknown,
+    opts?: { timeBase?: [number, number]; transfer?: boolean },
+  ): VideoFrame;
 }