avbridge 2.2.0 → 2.3.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

@@ -24,6 +24,8 @@ import {
 export interface RemuxPipeline {
   start(fromTime?: number, autoPlay?: boolean): Promise<void>;
   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;
   destroy(): Promise<void>;
   stats(): Record<string, unknown>;
 }
@@ -248,6 +250,10 @@ export async function createRemuxPipeline(
         console.error("[avbridge] remux pipeline reseek failed:", err);
       });
     },
+    setAutoPlay(autoPlay) {
+      pendingAutoPlay = autoPlay;
+      if (sink) sink.setPlayOnSeek(autoPlay);
+    },
     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/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-http-reader.ts

@@ -102,9 +102,13 @@ export async function prepareLibavInput(
   libav: LibavLikeWithBlob,
   filename: string,
   source: import("./source.js").NormalizedSource,
+  transport?: import("../types.js").TransportConfig,
 ): Promise<LibavInputHandle> {
   if (source.kind === "url") {
-    const handle = await attachLibavHttpReader(libav, filename, source.url);
+    const handle = await attachLibavHttpReader(libav, filename, source.url, {
+      requestInit: transport?.requestInit,
+      fetchFn: transport?.fetchFn,
+    });
     return {
       filename,
       transport: "http-range",

package/src/util/source.ts

@@ -1,4 +1,6 @@
-import type { ContainerKind, MediaInput } from "../types.js";
+import type { ContainerKind, MediaInput, TransportConfig } from "../types.js";
+import { mergeFetchInit, fetchWith } from "./transport.js";
+import { AvbridgeError, ERR_PROBE_FETCH_FAILED } from "../errors.js";
 
 /**
  * Bytes needed by the sniffer to identify every container we recognize.
@@ -59,7 +61,10 @@ export function isInMemorySource(source: NormalizedSource): source is Extract<No
  *
  * For non-URL inputs, the bytes are already in memory and we just wrap them.
  */
-export async function normalizeSource(source: MediaInput): Promise<NormalizedSource> {
+export async function normalizeSource(
+  source: MediaInput,
+  transport?: TransportConfig,
+): Promise<NormalizedSource> {
   if (source instanceof File) {
     return {
       kind: "blob",
@@ -82,7 +87,7 @@ export async function normalizeSource(source: MediaInput): Promise<NormalizedSou
   }
   if (typeof source === "string" || source instanceof URL) {
     const url = source instanceof URL ? source.toString() : source;
-    return await fetchUrlForSniff(url, source);
+    return await fetchUrlForSniff(url, source, transport);
   }
   throw new TypeError("unsupported source type");
 }
@@ -93,20 +98,35 @@ export async function normalizeSource(source: MediaInput): Promise<NormalizedSou
  * 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> {
+async function fetchUrlForSniff(
+  url: string,
+  originalSource: MediaInput,
+  transport?: TransportConfig,
+): Promise<NormalizedSource> {
   const name = url.split("/").pop()?.split("?")[0] ?? undefined;
+  const doFetch = fetchWith(transport);
 
   // First attempt: Range request for the sniff window.
   let res: Response;
   try {
-    res = await fetch(url, {
+    res = await doFetch(url, mergeFetchInit(transport?.requestInit, {
       headers: { Range: `bytes=0-${URL_SNIFF_RANGE_BYTES - 1}` },
-    });
+    })!);
   } catch (err) {
-    throw new Error(`failed to fetch source ${url}: ${(err as Error).message}`);
+    throw new AvbridgeError(
+      ERR_PROBE_FETCH_FAILED,
+      `Failed to fetch source ${url}: ${(err as Error).message}`,
+      "Check that the URL is reachable and CORS is configured. If the source requires authentication, pass requestInit with credentials/headers.",
+    );
   }
   if (!res.ok && res.status !== 206) {
-    throw new Error(`failed to fetch source ${url}: ${res.status} ${res.statusText}`);
+    throw new AvbridgeError(
+      ERR_PROBE_FETCH_FAILED,
+      `Failed to fetch source ${url}: ${res.status} ${res.statusText}`,
+      res.status === 403 || res.status === 401
+        ? "The server rejected the request. Pass requestInit with the required Authorization header or credentials."
+        : "Check that the URL is correct and the server is reachable.",
+    );
   }
 
   // Determine the total file size from Content-Range (preferred) or Content-Length.

package/src/util/transport.ts

@@ -0,0 +1,26 @@
+import type { FetchFn, TransportConfig } from "../types.js";
+
+/**
+ * Merge two RequestInit objects. Headers are merged (not overwritten) so
+ * the caller's auth headers coexist with the player's Range headers.
+ * Other fields (credentials, mode, signal, etc.) in `extra` override `base`.
+ */
+export function mergeFetchInit(
+  base: RequestInit | undefined,
+  extra: RequestInit | undefined,
+): RequestInit | undefined {
+  if (!base && !extra) return undefined;
+  return {
+    ...base,
+    ...extra,
+    headers: {
+      ...(base?.headers as Record<string, string> | undefined ?? {}),
+      ...(extra?.headers as Record<string, string> | undefined ?? {}),
+    },
+  };
+}
+
+/** Return the fetch function from a TransportConfig, falling back to globalThis.fetch. */
+export function fetchWith(transport?: TransportConfig): FetchFn {
+  return transport?.fetchFn ?? globalThis.fetch;
+}