avbridge 1.0.0

package/src/util/libav-http-reader.ts

@@ -0,0 +1,315 @@
+/**
+ * libav.js HTTP block reader.
+ *
+ * Wraps `libav.mkblockreaderdev` + `libav.onblockread` +
+ * `libav.ff_block_reader_dev_send` so that libav can demux a remote file
+ * via HTTP Range requests instead of needing the entire file in memory.
+ *
+ * Used by the AVI/ASF/FLV probe path and the libav-backed playback /
+ * conversion strategies whenever the source is a URL.
+ *
+ * Design notes:
+ *
+ * - **Range support detection** is done by issuing a `Range: bytes=0-0`
+ *   probe request. We do NOT trust `Accept-Ranges` headers — some servers
+ *   support ranges but don't advertise them, others advertise but don't.
+ *   The probe request is the canonical signal: a `206 Partial Content`
+ *   response means we can stream; anything else fails fast with a clear
+ *   error. We never silently fall back to a full download.
+ *
+ * - **Sequential reads.** libav can issue overlapping `onblockread`
+ *   callbacks. The reader serializes them through a single async queue
+ *   so a) `ff_block_reader_dev_send` calls are well-ordered and b) we
+ *   never have two in-flight fetches for unrelated reads. Throughput
+ *   for v1 is "good enough"; correctness > parallelism.
+ *
+ * - **In-flight dedup.** If libav asks for `(pos=1000, len=4096)` twice
+ *   in a row before the first request resolves, the second call awaits
+ *   the first instead of issuing a duplicate fetch. This handles the
+ *   "demuxer re-reads the same header" pattern cheaply.
+ *
+ * - **Read-ahead clamp.** libav's requested length is doubled, then
+ *   clamped to `[256 KB, 1 MB]`. Small reads get amortized; pathological
+ *   large requests don't OOM us.
+ *
+ * - **Last-block cache.** Only the most-recent fetched block is kept.
+ *   Re-fetches via Range are cheap; an LRU cache is post-1.0.
+ *
+ * - **Safe detach.** `detach()` clears `libav.onblockread`, sets a
+ *   destroyed flag, and ignores any in-flight fetch resolutions so we
+ *   never write into a torn-down demuxer.
+ */
+
+const MIN_READ = 256 * 1024;
+const MAX_READ = 1 * 1024 * 1024;
+
+interface LibavLike {
+  mkblockreaderdev(name: string, size: number): Promise<void>;
+  unlinkreadaheadfile(name: string): Promise<void>;
+  ff_block_reader_dev_send(
+    name: string,
+    pos: number,
+    data: Uint8Array | null,
+    opts?: { errorCode?: number; error?: unknown },
+  ): Promise<void>;
+  onblockread?: (filename: string, pos: number, length: number) => void;
+}
+
+export interface LibavHttpReaderHandle {
+  /** Total file size (bytes) reported by the server. */
+  readonly size: number;
+  /** Always `"http-range"` for now. Reserved for future transports. */
+  readonly transport: "http-range";
+  /** Stop serving reads, clear the libav callback, and ignore late fetches. */
+  detach(): Promise<void>;
+}
+
+export interface AttachLibavHttpReaderOptions {
+  /** Optional `RequestInit` extras (mode, credentials, headers, etc.). */
+  requestInit?: RequestInit;
+  /** Override fetch (for testing). Defaults to globalThis.fetch. */
+  fetchFn?: typeof fetch;
+}
+
+/**
+ * Result of preparing a libav-readable file from a normalized source.
+ * Either an in-memory Blob (created via `mkreadaheadfile`) or a streaming
+ * HTTP reader (created via `attachLibavHttpReader`). Callers should
+ * `await detach()` when done so resources are cleaned up symmetrically.
+ */
+export interface LibavInputHandle {
+  /** The virtual filename libav sees — pass to `ff_init_demuxer_file`. */
+  readonly filename: string;
+  /** "blob" for in-memory, "http-range" for streaming URL. */
+  readonly transport: "blob" | "http-range";
+  /** Total file size in bytes if known, otherwise undefined. */
+  readonly size: number | undefined;
+  /** Tear down the virtual file (and any HTTP reader state). */
+  detach(): Promise<void>;
+}
+
+interface LibavLikeWithBlob extends LibavLike {
+  mkreadaheadfile(name: string, blob: Blob): Promise<void>;
+}
+
+/**
+ * Convenience for the libav-backed strategies. Given a normalized source,
+ * either creates an in-memory readahead file (for Blob inputs) or attaches
+ * the HTTP block reader (for URL inputs). Returns a handle the caller
+ * should detach when done.
+ */
+export async function prepareLibavInput(
+  libav: LibavLikeWithBlob,
+  filename: string,
+  source: import("./source.js").NormalizedSource,
+): Promise<LibavInputHandle> {
+  if (source.kind === "url") {
+    const handle = await attachLibavHttpReader(libav, filename, source.url);
+    return {
+      filename,
+      transport: "http-range",
+      size: handle.size,
+      detach: () => handle.detach(),
+    };
+  }
+  await libav.mkreadaheadfile(filename, source.blob);
+  return {
+    filename,
+    transport: "blob",
+    size: source.byteLength,
+    detach: async () => {
+      try { await libav.unlinkreadaheadfile(filename); } catch { /* ignore */ }
+    },
+  };
+}
+
+/**
+ * Attach an HTTP block reader to a libav.js instance. After this resolves,
+ * libav can `ff_init_demuxer_file(filename)` and the demuxer will pull
+ * bytes via Range requests instead of needing a Blob.
+ *
+ * Fails fast (before any libav setup) if the server doesn't support
+ * Range requests.
+ */
+export async function attachLibavHttpReader(
+  libav: LibavLike,
+  filename: string,
+  url: string,
+  options: AttachLibavHttpReaderOptions = {},
+): Promise<LibavHttpReaderHandle> {
+  const fetchFn = options.fetchFn ?? fetch;
+
+  // 1. Probe the server with a single-byte Range request.
+  let probeRes: Response;
+  try {
+    probeRes = await fetchFn(url, {
+      ...options.requestInit,
+      headers: {
+        ...(options.requestInit?.headers ?? {}),
+        Range: "bytes=0-0",
+      },
+    });
+  } catch (err) {
+    throw new Error(
+      `libav HTTP reader: failed to reach ${url}: ${(err as Error).message}`,
+    );
+  }
+  if (probeRes.status !== 206) {
+    // 200 means the server ignored Range and would have sent the whole
+    // file. We refuse to silently slurp gigabytes.
+    throw new Error(
+      `libav HTTP reader: ${url} does not support HTTP Range requests ` +
+      `(server returned ${probeRes.status} for a Range probe; need 206 Partial Content). ` +
+      `Remote AVI/ASF/FLV playback requires a server that honors byte-range requests.`,
+    );
+  }
+
+  // 2. Parse total file size from Content-Range: "bytes 0-0/12345678"
+  const contentRange = probeRes.headers.get("content-range") ?? "";
+  const sizeMatch = contentRange.match(/\/(\d+)$/);
+  if (!sizeMatch) {
+    throw new Error(
+      `libav HTTP reader: ${url} returned 206 but no parseable Content-Range header (got: "${contentRange}")`,
+    );
+  }
+  const size = parseInt(sizeMatch[1], 10);
+  if (!Number.isFinite(size) || size <= 0) {
+    throw new Error(
+      `libav HTTP reader: ${url} reported invalid file size ${size}`,
+    );
+  }
+
+  // Drain the probe body so the connection can be reused.
+  try { await probeRes.arrayBuffer(); } catch { /* ignore */ }
+
+  // 3. Create the virtual file libav will read from.
+  await libav.mkblockreaderdev(filename, size);
+
+  // ── State ───────────────────────────────────────────────────────────────
+
+  let detached = false;
+  // Most-recently fetched block. Cached so re-reads of the same region
+  // (e.g. demuxer re-walks the header) don't issue another HTTP request.
+  let cached: { pos: number; bytes: Uint8Array } | null = null;
+  // The currently in-flight fetch, if any. Used both for serialization
+  // (we await this before starting another) and for in-flight dedup.
+  let inflight: Promise<void> | null = null;
+
+  function clampReadLength(requested: number): number {
+    const doubled = requested * 2;
+    if (doubled < MIN_READ) return MIN_READ;
+    if (doubled > MAX_READ) return MAX_READ;
+    return doubled;
+  }
+
+  /** True if the cached block fully covers `[pos, pos+length)`. */
+  function cacheCovers(pos: number, length: number): boolean {
+    if (!cached) return false;
+    return pos >= cached.pos && pos + length <= cached.pos + cached.bytes.byteLength;
+  }
+
+  /** Slice the requested window out of the cached block. */
+  function sliceFromCache(pos: number, length: number): Uint8Array {
+    if (!cached) throw new Error("sliceFromCache called with no cache");
+    const offset = pos - cached.pos;
+    return cached.bytes.subarray(offset, offset + length);
+  }
+
+  /** Fetch one Range and update the cache. */
+  async function fetchRange(pos: number, length: number): Promise<Uint8Array> {
+    const end = Math.min(pos + length - 1, size - 1);
+    const res = await fetchFn(url, {
+      ...options.requestInit,
+      headers: {
+        ...(options.requestInit?.headers ?? {}),
+        Range: `bytes=${pos}-${end}`,
+      },
+    });
+    if (res.status !== 206 && res.status !== 200) {
+      throw new Error(
+        `libav HTTP reader: Range request bytes=${pos}-${end} returned ${res.status}`,
+      );
+    }
+    const buf = new Uint8Array(await res.arrayBuffer());
+    cached = { pos, bytes: buf };
+    return buf;
+  }
+
+  /**
+   * Handle a single libav read request. Serializes against any in-flight
+   * read by chaining off `inflight`. Honors `detached` at every async
+   * boundary so a torn-down reader never writes back into libav.
+   */
+  async function handleRead(name: string, pos: number, length: number): Promise<void> {
+    // Wait for any preceding read to finish so we don't interleave.
+    if (inflight) {
+      try { await inflight; } catch { /* ignore — that read's own caller handled it */ }
+    }
+    if (detached) return;
+
+    // Cache hit — reply directly without a network round-trip.
+    if (cacheCovers(pos, length)) {
+      const data = sliceFromCache(pos, length);
+      try { await libav.ff_block_reader_dev_send(name, pos, data); } catch { /* ignore — libav may have torn down */ }
+      return;
+    }
+
+    // Cache miss — fetch via Range. Read-ahead amortizes small reads.
+    const fetchLen = clampReadLength(length);
+    const fetched = (async () => {
+      try {
+        const buf = await fetchRange(pos, fetchLen);
+        if (detached) return;
+        // Slice exactly what libav asked for and send it back.
+        const reply = buf.subarray(0, Math.min(length, buf.byteLength));
+        try { await libav.ff_block_reader_dev_send(name, pos, reply); } catch { /* ignore */ }
+      } catch (err) {
+        if (detached) return;
+        // Signal EOF + error code to libav so the demuxer surfaces it.
+        try {
+          await libav.ff_block_reader_dev_send(name, pos, null, {
+            error: err,
+          });
+        } catch { /* ignore */ }
+      }
+    })();
+    inflight = fetched;
+    try { await fetched; } finally { if (inflight === fetched) inflight = null; }
+  }
+
+  // 4. Wire the callback. The signature accepts `(name, pos, length)` and
+  // we hand it to handleRead which does all the work asynchronously.
+  // Note: libav.js dispatches this synchronously from a worker message,
+  // so we kick off handleRead but don't await — the queue inside handleRead
+  // serializes things.
+  const previousCallback = libav.onblockread;
+  libav.onblockread = (name: string, pos: number, length: number) => {
+    if (detached || name !== filename) {
+      // Forward to any previous callback (e.g. another reader on the same
+      // libav instance). This is rare in practice but cheap to support.
+      previousCallback?.(name, pos, length);
+      return;
+    }
+    void handleRead(name, pos, length);
+  };
+
+  return {
+    size,
+    transport: "http-range",
+    async detach() {
+      if (detached) return;
+      detached = true;
+      // Restore the previous callback (if any) so we don't break unrelated
+      // readers on the same libav instance.
+      libav.onblockread = previousCallback;
+      // Wait for the last in-flight read to settle so we don't tear down
+      // the virtual file while libav is still expecting a response.
+      if (inflight) {
+        try { await inflight; } catch { /* ignore */ }
+      }
+      // Drop the cache and unlink the virtual file.
+      cached = null;
+      try { await libav.unlinkreadaheadfile(filename); } catch { /* ignore */ }
+    },
+  };
+}

package/src/util/source.ts

@@ -0,0 +1,274 @@
+import type { ContainerKind, MediaInput } from "../types.js";
+
+/**
+ * Bytes needed by the sniffer to identify every container we recognize.
+ * MPEG-TS needs the most: a sync byte at offset 0 *and* offset 188 (one TS
+ * packet apart). Allow a little extra for the M2TS variant (offset 4/192).
+ */
+const SNIFF_BYTES_NEEDED = 380;
+
+/**
+ * Bytes to fetch from a URL during the initial sniff. We grab a slightly
+ * larger range than `SNIFF_BYTES_NEEDED` so the cache has some headroom for
+ * the demuxer's first read after sniffing, in case it wants to look at
+ * a few extra bytes (e.g. mp4 ftyp + first moov box).
+ */
+const URL_SNIFF_RANGE_BYTES = 32 * 1024;
+
+/**
+ * `NormalizedSource` is a discriminated union: every consumer (probe,
+ * strategies) decides what to do based on `kind`. URL sources are NOT
+ * fetched eagerly; we only do a Range request for the first ~32 KB so the
+ * sniffer has bytes to look at. The strategies are then handed the URL
+ * directly so they can stream the rest via Range requests.
+ *
+ * For File / Blob / ArrayBuffer / Uint8Array sources, the bytes are
+ * already in memory, so we wrap them as a `blob` variant.
+ */
+export type NormalizedSource =
+  | {
+      kind: "blob";
+      blob: Blob;
+      name?: string;
+      byteLength: number;
+      original: MediaInput;
+    }
+  | {
+      kind: "url";
+      url: string;
+      /** Bytes pulled via Range request for the sniffer. NOT the full file. */
+      sniffBytes: Uint8Array;
+      name?: string;
+      /** Total file size from Content-Length / Content-Range. May be undefined. */
+      byteLength: number | undefined;
+      original: MediaInput;
+    };
+
+/** True if this source carries the entire file's bytes (vs. streaming). */
+export function isInMemorySource(source: NormalizedSource): source is Extract<NormalizedSource, { kind: "blob" }> {
+  return source.kind === "blob";
+}
+
+
+/**
+ * Normalize a `MediaInput` for the probe + strategy layers. **Does not**
+ * download URL sources in full — only fetches the first ~32 KB via a
+ * Range request, which is enough for the sniffer to identify the
+ * container. The strategies are then expected to stream the rest via
+ * mediabunny's `UrlSource` (Range requests, prefetch, parallelism, cache).
+ *
+ * For non-URL inputs, the bytes are already in memory and we just wrap them.
+ */
+export async function normalizeSource(source: MediaInput): Promise<NormalizedSource> {
+  if (source instanceof File) {
+    return {
+      kind: "blob",
+      blob: source,
+      name: source.name,
+      byteLength: source.size,
+      original: source,
+    };
+  }
+  if (source instanceof Blob) {
+    return { kind: "blob", blob: source, byteLength: source.size, original: source };
+  }
+  if (source instanceof ArrayBuffer) {
+    const blob = new Blob([source]);
+    return { kind: "blob", blob, byteLength: blob.size, original: source };
+  }
+  if (source instanceof Uint8Array) {
+    const blob = new Blob([source as BlobPart]);
+    return { kind: "blob", blob, byteLength: blob.size, original: source };
+  }
+  if (typeof source === "string" || source instanceof URL) {
+    const url = source instanceof URL ? source.toString() : source;
+    return await fetchUrlForSniff(url, source);
+  }
+  throw new TypeError("unsupported source type");
+}
+
+/**
+ * Fetch the first ~32 KB of a URL via a Range request. Falls back to a
+ * full GET if the server doesn't support range requests, but in that case
+ * we only read the first 32 KB and abort the rest of the response so we
+ * don't accidentally buffer a large file.
+ */
+async function fetchUrlForSniff(url: string, originalSource: MediaInput): Promise<NormalizedSource> {
+  const name = url.split("/").pop()?.split("?")[0] ?? undefined;
+
+  // First attempt: Range request for the sniff window.
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      headers: { Range: `bytes=0-${URL_SNIFF_RANGE_BYTES - 1}` },
+    });
+  } catch (err) {
+    throw new Error(`failed to fetch source ${url}: ${(err as Error).message}`);
+  }
+  if (!res.ok && res.status !== 206) {
+    throw new Error(`failed to fetch source ${url}: ${res.status} ${res.statusText}`);
+  }
+
+  // Determine the total file size from Content-Range (preferred) or Content-Length.
+  let byteLength: number | undefined;
+  const contentRange = res.headers.get("content-range");
+  if (contentRange) {
+    // "bytes 0-32767/12345678" — parse the part after the slash
+    const m = contentRange.match(/\/(\d+)$/);
+    if (m) byteLength = parseInt(m[1], 10);
+  }
+  if (byteLength === undefined) {
+    const cl = res.headers.get("content-length");
+    if (cl) {
+      const n = parseInt(cl, 10);
+      if (Number.isFinite(n)) {
+        // If the server returned 200 (full body), Content-Length is the
+        // FILE size. If 206 (partial), it's the chunk size — only use it
+        // as a total if no Content-Range was present (server doesn't do
+        // ranges) AND the full response is smaller than our sniff window.
+        if (res.status === 200) byteLength = n;
+        else if (res.status === 206 && !contentRange) byteLength = n;
+      }
+    }
+  }
+
+  // Read the sniff bytes. If the server ignored the Range header and is
+  // streaming the full file, only read the first window and let the rest
+  // be GC'd. We use a reader so we can stop early.
+  const reader = res.body?.getReader();
+  if (!reader) {
+    // No streamed body (some test environments). Fall back to .arrayBuffer()
+    // and slice — this might pull more than we wanted, but only for the
+    // initial sniff, not the full file.
+    const buf = new Uint8Array(await res.arrayBuffer());
+    const sniffBytes = buf.slice(0, URL_SNIFF_RANGE_BYTES);
+    return { kind: "url", url, sniffBytes, name, byteLength, original: originalSource };
+  }
+
+  const chunks: Uint8Array[] = [];
+  let collected = 0;
+  while (collected < URL_SNIFF_RANGE_BYTES) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.push(value);
+    collected += value.byteLength;
+  }
+  // Cancel the response so we don't keep downloading.
+  await reader.cancel().catch(() => { /* ignore */ });
+
+  // Concatenate up to URL_SNIFF_RANGE_BYTES.
+  const total = Math.min(collected, URL_SNIFF_RANGE_BYTES);
+  const sniffBytes = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    if (offset >= total) break;
+    const room = total - offset;
+    sniffBytes.set(chunk.subarray(0, Math.min(chunk.byteLength, room)), offset);
+    offset += chunk.byteLength;
+  }
+
+  return { kind: "url", url, sniffBytes, name, byteLength, original: originalSource };
+}
+
+/**
+ * Identify the container family from a small byte buffer. Used by the
+ * probe layer for both file (Blob → first 380 bytes) and URL (Range
+ * request → first 32 KB) inputs.
+ *
+ * Sniffing intentionally does not trust file extensions.
+ */
+export function sniffContainerFromBytes(head: Uint8Array): ContainerKind {
+  // MPEG-TS: sync byte 0x47 every 188 bytes. Verify at least two sync
+  // bytes in the right places to avoid false positives. Some captures
+  // start with a few junk bytes — also try offsets 4 and 192 (M2TS).
+  if (head.length >= 376 && head[0] === 0x47 && head[188] === 0x47) {
+    return "mpegts";
+  }
+  if (head.length >= 380 && head[4] === 0x47 && head[192] === 0x47) {
+    return "mpegts"; // M2TS — 4-byte timestamp prefix per packet
+  }
+  // RIFF....AVI  →  AVI
+  if (
+    head[0] === 0x52 && head[1] === 0x49 && head[2] === 0x46 && head[3] === 0x46 &&
+    head[8] === 0x41 && head[9] === 0x56 && head[10] === 0x49
+  ) return "avi";
+  // RIFF....WAVE → WAV
+  if (
+    head[0] === 0x52 && head[1] === 0x49 && head[2] === 0x46 && head[3] === 0x46 &&
+    head[8] === 0x57 && head[9] === 0x41 && head[10] === 0x56 && head[11] === 0x45
+  ) return "wav";
+  // EBML start: 1A 45 DF A3 → MKV/WebM. Distinguish later via DocType.
+  if (head[0] === 0x1a && head[1] === 0x45 && head[2] === 0xdf && head[3] === 0xa3) {
+    return "mkv";
+  }
+  // ftyp at offset 4 → MP4 family
+  if (head[4] === 0x66 && head[5] === 0x74 && head[6] === 0x79 && head[7] === 0x70) {
+    // brand at bytes 8..11
+    const brand = String.fromCharCode(head[8], head[9], head[10], head[11]);
+    if (brand.startsWith("qt")) return "mov";
+    return "mp4";
+  }
+  // ASF / WMV: 30 26 B2 75 8E 66 CF 11
+  if (
+    head[0] === 0x30 && head[1] === 0x26 && head[2] === 0xb2 && head[3] === 0x75 &&
+    head[4] === 0x8e && head[5] === 0x66 && head[6] === 0xcf && head[7] === 0x11
+  ) return "asf";
+  // FLV: 46 4C 56
+  if (head[0] === 0x46 && head[1] === 0x4c && head[2] === 0x56) return "flv";
+  // OggS: 4F 67 67 53
+  if (head[0] === 0x4f && head[1] === 0x67 && head[2] === 0x67 && head[3] === 0x53) return "ogg";
+  // FLAC: 66 4C 61 43
+  if (head[0] === 0x66 && head[1] === 0x4c && head[2] === 0x61 && head[3] === 0x43) return "flac";
+  // ID3v2: 49 44 33  → MP3 (with id3)
+  if (head[0] === 0x49 && head[1] === 0x44 && head[2] === 0x33) return "mp3";
+  // MPEG audio frame sync: FF Fx
+  if (head[0] === 0xff && (head[1] & 0xe0) === 0xe0) {
+    // ADTS: FF F1 / FF F9
+    if ((head[1] & 0xf6) === 0xf0) return "adts";
+    return "mp3";
+  }
+  return "unknown";
+}
+
+/**
+ * Convenience: sniff a `NormalizedSource` regardless of kind. For URL
+ * sources, uses the pre-fetched `sniffBytes`. For blob sources, reads the
+ * first 380 bytes.
+ */
+export async function sniffNormalizedSource(source: NormalizedSource): Promise<ContainerKind> {
+  if (source.kind === "url") {
+    return sniffContainerFromBytes(source.sniffBytes);
+  }
+  const buf = await readBlobBytes(source.blob, SNIFF_BYTES_NEEDED);
+  return sniffContainerFromBytes(new Uint8Array(buf));
+}
+
+/**
+ * Backwards-compatible wrapper for code that still passes a Blob directly.
+ * Prefer `sniffNormalizedSource` going forward.
+ */
+export async function sniffContainer(blob: Blob): Promise<ContainerKind> {
+  const buf = await readBlobBytes(blob, SNIFF_BYTES_NEEDED);
+  return sniffContainerFromBytes(new Uint8Array(buf));
+}
+
+/**
+ * Read up to `limit` bytes from a Blob. Tries `Blob.arrayBuffer()` first
+ * (modern browsers), then falls back to `FileReader` (works under jsdom).
+ */
+async function readBlobBytes(blob: Blob, limit: number): Promise<ArrayBuffer> {
+  const slice = blob.slice(0, limit);
+  if (typeof (slice as Blob & { arrayBuffer?: () => Promise<ArrayBuffer> }).arrayBuffer === "function") {
+    try {
+      return await (slice as Blob & { arrayBuffer: () => Promise<ArrayBuffer> }).arrayBuffer();
+    } catch {
+      /* fall through to FileReader */
+    }
+  }
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(reader.result as ArrayBuffer);
+    reader.onerror = () => reject(reader.error ?? new Error("FileReader failed"));
+    reader.readAsArrayBuffer(slice);
+  });
+}