avbridge 2.2.1 → 2.5.0

package/src/strategies/remux/mse.ts

@@ -3,6 +3,8 @@
  * `SourceBuffer` with an append queue that respects `updateend` backpressure.
  */
 
+import { AvbridgeError, ERR_MSE_NOT_SUPPORTED, ERR_MSE_CODEC_NOT_SUPPORTED } from "../../errors.js";
+
 export interface MseSinkOptions {
   mime: string;
   video: HTMLVideoElement;
@@ -23,10 +25,18 @@ export class MseSink {
 
   constructor(private readonly options: MseSinkOptions) {
     if (typeof MediaSource === "undefined") {
-      throw new Error("MSE not supported in this environment");
+      throw new AvbridgeError(
+        ERR_MSE_NOT_SUPPORTED,
+        "MediaSource Extensions (MSE) are not supported in this environment.",
+        "MSE is required for the remux strategy. Use a browser that supports MSE, or try the fallback strategy.",
+      );
     }
     if (!MediaSource.isTypeSupported(options.mime)) {
-      throw new Error(`MSE does not support MIME "${options.mime}" — cannot remux`);
+      throw new AvbridgeError(
+        ERR_MSE_CODEC_NOT_SUPPORTED,
+        `This browser's MSE does not support "${options.mime}".`,
+        "The codec combination can't be played via remux in this browser. The player will try the next strategy automatically.",
+      );
     }
 
     this.mediaSource = new MediaSource();

package/src/strategies/remux/pipeline.ts

@@ -26,6 +26,11 @@ export interface RemuxPipeline {
   seek(time: number, autoPlay?: boolean): Promise<void>;
   /** Update the autoplay intent mid-flight — used when play() arrives after seek() but before the MseSink has been constructed. */
   setAutoPlay(autoPlay: boolean): void;
+  /**
+   * Switch the active audio track. Tears down the current Output, rebuilds
+   * with the new audio source, and resumes pumping at the given time.
+   */
+  setAudioTrack(trackId: number, timeSec: number, autoPlay: boolean): Promise<void>;
   destroy(): Promise<void>;
   stats(): Record<string, unknown>;
 }
@@ -37,7 +42,6 @@ export async function createRemuxPipeline(
   const mb = await import("mediabunny");
 
   const videoTrackInfo = ctx.videoTracks[0];
-  const audioTrackInfo = ctx.audioTracks[0];
   if (!videoTrackInfo) throw new Error("remux: source has no video track");
 
   // Map avbridge codec names back to mediabunny's enum strings.
@@ -45,7 +49,6 @@ export async function createRemuxPipeline(
   if (!mbVideoCodec) {
     throw new Error(`remux: video codec "${videoTrackInfo.codec}" is not supported by mediabunny output`);
   }
-  const mbAudioCodec = audioTrackInfo ? avbridgeAudioToMediabunny(audioTrackInfo.codec) : null;
 
   // Open the input. URL sources go through mediabunny's UrlSource so the
   // muxer streams via Range requests instead of buffering the whole file.
@@ -55,23 +58,52 @@ export async function createRemuxPipeline(
   });
   const allTracks = await input.getTracks();
   const inputVideo = allTracks.find((t) => t.id === videoTrackInfo.id && t.isVideoTrack());
-  const inputAudio = audioTrackInfo
-    ? allTracks.find((t) => t.id === audioTrackInfo.id && t.isAudioTrack())
-    : null;
   if (!inputVideo || !inputVideo.isVideoTrack()) {
     throw new Error("remux: video track not found in input");
   }
-  if (audioTrackInfo && (!inputAudio || !inputAudio.isAudioTrack())) {
-    throw new Error("remux: audio track not found in input");
-  }
 
-  // Pull WebCodecs decoder configs once — used as `meta` on the first packet.
+  // Pull the video WebCodecs decoder config once — used as `meta` on the
+  // first packet after every Output rebuild.
   const videoConfig = await inputVideo.getDecoderConfig();
-  const audioConfig = inputAudio && inputAudio.isAudioTrack() ? await inputAudio.getDecoderConfig() : null;
 
-  // Packet sinks (input side) — reused across seeks.
+  // Packet sink for video — reused across seeks.
   const videoSink = new mb.EncodedPacketSink(inputVideo);
-  const audioSink = inputAudio?.isAudioTrack() ? new mb.EncodedPacketSink(inputAudio) : null;
+
+  // Audio selection is mutable: setAudioTrack() can swap it. The selected
+  // audio derived state (input track, codec, sink, config) is rebuilt via
+  // rebuildAudio() whenever the id changes.
+  type InputAudioTrack = InstanceType<typeof mb.InputAudioTrack>;
+  type AudioDecCfg = Awaited<ReturnType<InputAudioTrack["getDecoderConfig"]>>;
+
+  let selectedAudioTrackId: number | null = ctx.audioTracks[0]?.id ?? null;
+  let inputAudio: InputAudioTrack | null = null;
+  let mbAudioCodec: ReturnType<typeof avbridgeAudioToMediabunny> | null = null;
+  let audioSink: InstanceType<typeof mb.EncodedPacketSink> | null = null;
+  let audioConfig: AudioDecCfg | null = null;
+
+  async function rebuildAudio(): Promise<void> {
+    if (selectedAudioTrackId == null) {
+      inputAudio = null;
+      mbAudioCodec = null;
+      audioSink = null;
+      audioConfig = null;
+      return;
+    }
+    const trackInfo = ctx.audioTracks.find((t) => t.id === selectedAudioTrackId);
+    if (!trackInfo) {
+      throw new Error(`remux: no audio track with id ${selectedAudioTrackId}`);
+    }
+    const newInput = allTracks.find((t) => t.id === trackInfo.id && t.isAudioTrack());
+    if (!newInput || !newInput.isAudioTrack()) {
+      throw new Error("remux: audio track not found in input");
+    }
+    inputAudio = newInput;
+    mbAudioCodec = avbridgeAudioToMediabunny(trackInfo.codec);
+    audioSink = new mb.EncodedPacketSink(newInput);
+    audioConfig = await newInput.getDecoderConfig();
+  }
+
+  await rebuildAudio();
 
   // MSE sink — created lazily on first output write, reused across seeks.
   let sink: MseSink | null = null;
@@ -254,6 +286,34 @@ export async function createRemuxPipeline(
       pendingAutoPlay = autoPlay;
       if (sink) sink.setPlayOnSeek(autoPlay);
     },
+    async setAudioTrack(trackId, time, autoPlay) {
+      if (selectedAudioTrackId === trackId) return;
+      if (!ctx.audioTracks.some((t) => t.id === trackId)) {
+        console.warn("[avbridge] remux: setAudioTrack — unknown track id", trackId);
+        return;
+      }
+      // Stop the current pump. The next pumpLoop() will build a fresh
+      // Output that uses the newly-selected audio source.
+      pumpToken++;
+      selectedAudioTrackId = trackId;
+      await rebuildAudio().catch((err) => {
+        console.warn("[avbridge] remux: rebuildAudio failed:", (err as Error).message);
+      });
+      // Tear down the existing MseSink — the audio codec may have changed,
+      // and the SourceBuffer's mime is fixed at construction time. The next
+      // createOutput will recompute `getMimeType()` and the write handler
+      // will lazily build a new sink.
+      if (sink) {
+        try { sink.destroy(); } catch { /* ignore */ }
+        sink = null;
+      }
+      pendingAutoPlay = autoPlay;
+      pendingStartTime = time;
+      pumpLoop(++pumpToken, time).catch((err) => {
+        // eslint-disable-next-line no-console
+        console.error("[avbridge] remux pipeline setAudioTrack pump failed:", err);
+      });
+    },
     async destroy() {
       destroyed = true;
       pumpToken++;

package/src/subtitles/index.ts

@@ -1,4 +1,5 @@
-import type { SubtitleTrackInfo } from "../types.js";
+import type { SubtitleTrackInfo, TransportConfig } from "../types.js";
+import { fetchWith } from "../util/transport.js";
 import { srtToVtt } from "./srt.js";
 import { isVtt } from "./vtt.js";
 
@@ -98,7 +99,10 @@ export async function attachSubtitleTracks(
   tracks: SubtitleTrackInfo[],
   bag?: SubtitleResourceBag,
   onError?: (err: Error, track: SubtitleTrackInfo) => void,
+  transport?: TransportConfig,
 ): Promise<void> {
+  const doFetch = fetchWith(transport);
+
   // Clear existing dynamically-attached tracks.
   for (const t of Array.from(video.querySelectorAll("track[data-avbridge]"))) {
     t.remove();
@@ -109,14 +113,14 @@ export async function attachSubtitleTracks(
     try {
       let url = t.sidecarUrl;
       if (t.format === "srt") {
-        const res = await fetch(t.sidecarUrl);
+        const res = await doFetch(t.sidecarUrl, transport?.requestInit);
         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") {
         // Validate quickly so a malformed file fails loudly here.
-        const res = await fetch(t.sidecarUrl);
+        const res = await doFetch(t.sidecarUrl, transport?.requestInit);
         const text = await res.text();
         if (!isVtt(text)) {
           // eslint-disable-next-line no-console

package/src/subtitles/render.ts

@@ -32,6 +32,14 @@ export class SubtitleOverlay {
     this.el.textContent = active?.text ?? "";
   }
 
+  /** Set the currently-displayed text directly (bypasses loadVtt/update). */
+  setText(text: string): void {
+    // Only touch the DOM if it actually changed — rAF tick runs 60Hz.
+    if (this.el.textContent !== text) {
+      this.el.textContent = text;
+    }
+  }
+
   destroy(): void {
     this.el.remove();
     this.cues = [];

package/src/types.ts

@@ -69,6 +69,8 @@ export type AudioCodec =
   | "ra_288" // RealAudio 2.0 (28.8 kbps)
   | "sipr" // RealAudio Sipr (voice codec)
   | "atrac3" // Sony ATRAC3 (sometimes seen in .rm)
+  | "dts" // DTS (common in Blu-ray MKV rips)
+  | "truehd" // Dolby TrueHD (Blu-ray lossless)
   | (string & {});
 
 export interface VideoTrackInfo {
@@ -219,7 +221,7 @@ export interface Plugin {
   name: string;
   canHandle(context: MediaContext): boolean;
   /** Returns a session if it claims the context, otherwise throws. */
-  execute(context: MediaContext, target: HTMLVideoElement): Promise<PlaybackSession>;
+  execute(context: MediaContext, target: HTMLVideoElement, transport?: TransportConfig): Promise<PlaybackSession>;
 }
 
 /** Player creation options. */
@@ -256,6 +258,38 @@ export interface CreatePlayerOptions {
    * strategy in the fallback chain on failure or stall.
    */
   autoEscalate?: boolean;
+  /**
+   * Behavior when the browser tab becomes hidden.
+   * - `"pause"` (default): auto-pause on hide, auto-resume on visible
+   *   if the user had been playing. Matches YouTube, Netflix, and
+   *   native media players. Prevents degraded playback from Chrome's
+   *   background throttling of requestAnimationFrame and setTimeout.
+   * - `"continue"`: keep playing. Playback will degrade anyway due to
+   *   browser throttling, but useful for consumers who want full
+   *   control of visibility handling themselves.
+   */
+  backgroundBehavior?: "pause" | "continue";
+  /**
+   * Extra {@link RequestInit} merged into every HTTP request the player
+   * makes (probe Range requests, subtitle fetches, libav HTTP reader).
+   * Headers are merged, not overwritten — so you can add `Authorization`
+   * without losing the player's `Range` header.
+   */
+  requestInit?: RequestInit;
+  /**
+   * Custom fetch implementation. Defaults to `globalThis.fetch`. Useful
+   * for interceptors, logging, or environments without a global fetch.
+   */
+  fetchFn?: FetchFn;
+}
+
+/** Signature-compatible with `globalThis.fetch`. */
+export type FetchFn = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+/** Internal transport config bundle. Not part of the public API. */
+export interface TransportConfig {
+  requestInit?: RequestInit;
+  fetchFn?: FetchFn;
 }
 
 /** Events emitted by {@link UnifiedPlayer}. Strongly typed. */
@@ -293,6 +327,24 @@ export interface ConvertOptions {
   onProgress?: (info: ProgressInfo) => void;
   /** When true, reject on any uncertain codec/container combo. Default: `false` (best-effort). */
   strict?: boolean;
+  /**
+   * Write output progressively to a `WritableStream` instead of accumulating
+   * in memory. Use with the File System Access API (`showSaveFilePicker()`) to
+   * transcode files larger than available memory.
+   *
+   * When set, the returned `ConvertResult.blob` will be an empty Blob (the
+   * real data went to the stream). The caller is responsible for closing the
+   * stream after the returned promise resolves.
+   *
+   * @example
+   * ```ts
+   * const handle = await showSaveFilePicker({ suggestedName: "output.mp4" });
+   * const writable = await handle.createWritable();
+   * const result = await transcode(file, { outputStream: writable });
+   * await writable.close();
+   * ```
+   */
+  outputStream?: WritableStream;
 }
 
 /** Progress information passed to {@link ConvertOptions.onProgress}. */

package/src/util/libav-demux.ts

@@ -0,0 +1,405 @@
+/**
+ * Shared libav demux session. Opens a libav demuxer over a NormalizedSource
+ * and provides a linear, cancellable packet pump.
+ *
+ * Phase 1 API: deliberately minimal. The first consumer is the AVI/ASF/FLV
+ * transcode path (src/convert/transcode-libav.ts), which is strictly linear.
+ * No seek, no track swapping — those were added to hybrid/fallback's
+ * private pumps for playback reasons. When those paths migrate here, the
+ * API will grow to cover their needs.
+ *
+ * The shared timestamp sanitizers (sanitizePacketTimestamp,
+ * sanitizeFrameTimestamp) also live here. They were previously duplicated
+ * in convert/remux.ts and strategies/hybrid/decoder.ts. The duplicates
+ * stay put in Phase 1 with TODO pointers; migration is a follow-up.
+ */
+
+import { loadLibav, type LibavVariant } from "../strategies/fallback/libav-loader.js";
+import { pickLibavVariant } from "../strategies/fallback/variant-routing.js";
+import { prepareLibavInput } from "./libav-http-reader.js";
+import type { MediaContext, TransportConfig } from "../types.js";
+import type { NormalizedSource } from "./source.js";
+
+// ─────────────────────────────────────────────────────────────────────────
+// Structural types (mirror libav.js' shape without dragging in its types)
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface LibavStream {
+  index: number;
+  codec_type: number;
+  codec_id: number;
+  codecpar: number;
+  time_base_num?: number;
+  time_base_den?: number;
+}
+
+export interface LibavPacket {
+  data: Uint8Array;
+  pts: number;
+  ptshi?: number;
+  duration?: number;
+  durationhi?: number;
+  flags: number;
+  stream_index: number;
+  time_base_num?: number;
+  time_base_den?: number;
+}
+
+export interface LibavFrame {
+  data: unknown;
+  format: number;
+  channels?: number;
+  ch_layout_nb_channels?: number;
+  sample_rate?: number;
+  nb_samples?: number;
+  pts?: number;
+  ptshi?: number;
+  width?: number;
+  height?: number;
+}
+
+interface LibavRuntime {
+  AVMEDIA_TYPE_VIDEO: number;
+  AVMEDIA_TYPE_AUDIO: number;
+  AVERROR_EOF: number;
+  EAGAIN: number;
+
+  mkreadaheadfile(name: string, blob: Blob): Promise<void>;
+  unlinkreadaheadfile(name: string): Promise<void>;
+  ff_init_demuxer_file(name: string): Promise<[number, LibavStream[]]>;
+  ff_read_frame_multi(
+    fmt_ctx: number,
+    pkt: number,
+    opts?: { limit?: number },
+  ): Promise<[number, Record<number, LibavPacket[]>]>;
+  av_packet_alloc(): Promise<number>;
+  av_packet_free?(pkt: number): Promise<void>;
+  avformat_close_input_js(ctx: number): Promise<void>;
+  f64toi64?(val: number): [number, number];
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Session
+// ─────────────────────────────────────────────────────────────────────────
+
+export interface LibavDemuxSession {
+  readonly libav: LibavRuntime;
+  readonly fmtCtx: number;
+  readonly streams: LibavStream[];
+  readonly videoStream: LibavStream | null;
+  readonly audioStream: LibavStream | null;
+  /** True when the input is being streamed via HTTP Range requests. */
+  readonly transport: "http-range" | "blob";
+  /**
+   * Linear read-to-EOF pump. Invokes the callbacks for each
+   * ff_read_frame_multi batch (audio is handed over before video per
+   * batch, matching the audio-first ordering that the hybrid/fallback
+   * playback pumps use — see POSTMORTEMS.md entry 1).
+   *
+   * Honors the AbortSignal between batches. Invokes `onEof` once when
+   * the demuxer returns EOF. Does NOT handle seek.
+   */
+  pump(cb: {
+    onVideoPackets?: (pkts: LibavPacket[]) => Promise<void>;
+    onAudioPackets?: (pkts: LibavPacket[]) => Promise<void>;
+    onEof?: () => Promise<void>;
+    signal?: AbortSignal;
+  }): Promise<void>;
+  destroy(): Promise<void>;
+}
+
+export interface OpenLibavDemuxOptions {
+  source: NormalizedSource;
+  filename: string;
+  context: MediaContext;
+  transport?: TransportConfig;
+  /** Override automatic variant picking. Defaults to pickLibavVariant(context). */
+  variant?: LibavVariant;
+}
+
+export async function openLibavDemux(opts: OpenLibavDemuxOptions): Promise<LibavDemuxSession> {
+  const variant: LibavVariant = opts.variant ?? pickLibavVariant(opts.context);
+  const libav = (await loadLibav(variant)) as unknown as LibavRuntime;
+
+  const inputHandle = await prepareLibavInput(
+    libav as unknown as Parameters<typeof prepareLibavInput>[0],
+    opts.filename,
+    opts.source,
+    opts.transport,
+  );
+
+  const readPkt = await libav.av_packet_alloc();
+  const [fmtCtx, 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;
+
+  let destroyed = false;
+
+  async function pump(cb: Parameters<LibavDemuxSession["pump"]>[0]): Promise<void> {
+    while (!destroyed) {
+      if (cb.signal?.aborted) return;
+
+      let readErr: number;
+      let packets: Record<number, LibavPacket[]>;
+      try {
+        [readErr, packets] = await libav.ff_read_frame_multi(fmtCtx, readPkt, {
+          // 16 KB batch — chosen so each read produces a handful of
+          // packets, keeping downstream queues bounded. Same rationale
+          // as the hybrid/fallback pumps (see CLAUDE.md note).
+          limit: 16 * 1024,
+        });
+      } catch (err) {
+        throw new Error(`libav-demux: ff_read_frame_multi failed: ${(err as Error).message}`);
+      }
+
+      if (destroyed || cb.signal?.aborted) return;
+
+      const videoPackets = videoStream ? packets[videoStream.index] : undefined;
+      const audioPackets = audioStream ? packets[audioStream.index] : undefined;
+
+      // Audio-first ordering. Audio decode is cheap; video decode can
+      // be expensive. Feeding audio first ensures the audio consumer
+      // has samples to work with before any long video-decode block.
+      if (cb.onAudioPackets && audioPackets && audioPackets.length > 0) {
+        await cb.onAudioPackets(audioPackets);
+      }
+      if (destroyed || cb.signal?.aborted) return;
+      if (cb.onVideoPackets && videoPackets && videoPackets.length > 0) {
+        await cb.onVideoPackets(videoPackets);
+      }
+
+      if (readErr === libav.AVERROR_EOF) {
+        if (cb.onEof) await cb.onEof();
+        return;
+      }
+      if (readErr && readErr !== 0 && readErr !== -libav.EAGAIN) {
+        throw new Error(`libav-demux: ff_read_frame_multi returned ${readErr}`);
+      }
+    }
+  }
+
+  async function destroy(): Promise<void> {
+    destroyed = true;
+    try { await libav.av_packet_free?.(readPkt); } catch { /* ignore */ }
+    try { await libav.avformat_close_input_js(fmtCtx); } catch { /* ignore */ }
+    try { await inputHandle.detach(); } catch { /* ignore */ }
+  }
+
+  return {
+    libav,
+    fmtCtx,
+    streams,
+    videoStream,
+    audioStream,
+    transport: inputHandle.transport,
+    pump,
+    destroy,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Timestamp sanitizers (extracted from convert/remux.ts + hybrid/decoder.ts)
+//
+// libav can hand us packets/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. Downstream consumers
+// that treat pts as int64 overflow and throw.
+//
+// The sanitizer replaces invalid pts with a synthetic microsecond counter,
+// and normalizes valid pts to a 1/1e6 time_base so consumers don't need
+// to track the source time_base per packet.
+// ─────────────────────────────────────────────────────────────────────────
+
+/**
+ * Sanitize a libav packet's timestamp. Mutates `pkt` in place.
+ * If the packet has AV_NOPTS_VALUE, replaces pts with `nextUs()`.
+ * Otherwise normalizes to µs with time_base = 1/1_000_000.
+ */
+export function sanitizePacketTimestamp(
+  pkt: LibavPacket,
+  nextUs: () => number,
+  fallbackTimeBase?: [number, number],
+): void {
+  const lo = pkt.pts ?? 0;
+  const hi = pkt.ptshi ?? 0;
+  const isInvalid = (hi === -2147483648 && lo === 0) || !Number.isFinite(lo);
+  if (isInvalid) {
+    const us = nextUs();
+    pkt.pts = us;
+    pkt.ptshi = 0;
+    pkt.time_base_num = 1;
+    pkt.time_base_den = 1_000_000;
+    return;
+  }
+  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) {
+    pkt.pts = us;
+    pkt.ptshi = us < 0 ? -1 : 0;
+    pkt.time_base_num = 1;
+    pkt.time_base_den = 1_000_000;
+    return;
+  }
+  const fallback = nextUs();
+  pkt.pts = fallback;
+  pkt.ptshi = 0;
+  pkt.time_base_num = 1;
+  pkt.time_base_den = 1_000_000;
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+// Audio frame → interleaved Float32 (extracted from
+// strategies/hybrid/decoder.ts + strategies/fallback/decoder.ts).
+//
+// libav hands us decoded audio frames in whichever sample format the codec
+// uses (FLTP, S16P, etc.). Most downstream consumers (Web Audio, WebCodecs
+// AudioEncoder) want interleaved Float32. This does the conversion without
+// any dependencies.
+// ─────────────────────────────────────────────────────────────────────────
+
+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;
+
+export interface InterleavedSamples {
+  data: Float32Array;
+  channels: number;
+  sampleRate: number;
+}
+
+export 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:
+      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);
+}
+
+/**
+ * Sanitize a decoded frame's timestamp. Mutates `frame` in place.
+ * Returns nothing; callers that want derived metadata (e.g. a
+ * VideoFrame timestamp in µs) should read `frame.pts` after calling.
+ */
+export function sanitizeFrameTimestamp(
+  frame: LibavFrame,
+  nextUs: () => number,
+  fallbackTimeBase?: [number, number],
+): void {
+  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;
+  }
+  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;
+  }
+  const fallback = nextUs();
+  frame.pts = fallback;
+  frame.ptshi = 0;
+}