avbridge 2.2.1 → 2.5.0

package/src/player.ts

@@ -15,8 +15,10 @@ import type {
   PlayerEventMap,
   PlayerEventName,
   StrategyName,
+  TransportConfig,
   Listener,
 } from "./types.js";
+import { AvbridgeError, ERR_PLAYER_NOT_READY, ERR_ALL_STRATEGIES_EXHAUSTED } from "./errors.js";
 
 export class UnifiedPlayer {
   private emitter = new TypedEmitter<PlayerEventMap>();
@@ -39,6 +41,15 @@ export class UnifiedPlayer {
   // source (e.g. <avbridge-video>).
   private endedListener: (() => void) | null = null;
 
+  // Background tab handling. userIntent is what the user last asked for
+  // (play vs pause) — used to decide whether to auto-resume on visibility
+  // return. autoPausedForVisibility tracks whether we paused because the
+  // tab was hidden, so we don't resume playback the user deliberately
+  // paused (e.g. via media keys while hidden).
+  private userIntent: "play" | "pause" = "pause";
+  private autoPausedForVisibility = false;
+  private visibilityListener: (() => void) | null = null;
+
   // Serializes escalation / setStrategy calls
   private switchingPromise: Promise<void> = Promise.resolve();
 
@@ -46,13 +57,23 @@ export class UnifiedPlayer {
   // Revoked at destroy() so repeated source swaps don't leak.
   private subtitleResources = new SubtitleResourceBag();
 
+  // Transport config extracted from CreatePlayerOptions. Threaded to probe,
+  // subtitle fetches, and strategy session creators. Not stored on MediaContext
+  // because it's runtime config, not media analysis.
+  private readonly transport: TransportConfig | undefined;
+
   /**
    * @internal Use {@link createPlayer} or {@link UnifiedPlayer.create} instead.
    */
   private constructor(
     private readonly options: CreatePlayerOptions,
     private readonly registry: PluginRegistry,
-  ) {}
+  ) {
+    const { requestInit, fetchFn } = options;
+    if (requestInit || fetchFn) {
+      this.transport = { requestInit, fetchFn };
+    }
+  }
 
   static async create(options: CreatePlayerOptions): Promise<UnifiedPlayer> {
     const registry = new PluginRegistry();
@@ -74,7 +95,7 @@ export class UnifiedPlayer {
     const bootstrapStart = performance.now();
     try {
       dbg.info("bootstrap", "start");
-      const ctx = await dbg.timed("probe", "probe", 3000, () => probe(this.options.source));
+      const ctx = await dbg.timed("probe", "probe", 3000, () => probe(this.options.source, this.transport));
       dbg.info("probe",
         `container=${ctx.container} video=${ctx.videoTracks[0]?.codec ?? "-"} ` +
         `audio=${ctx.audioTracks[0]?.codec ?? "-"} probedBy=${ctx.probedBy}`,
@@ -126,21 +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}`);
-          },
-        );
-      }
+      // 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,
@@ -151,6 +172,15 @@ export class UnifiedPlayer {
       this.startTimeupdateLoop();
       this.endedListener = () => this.emitter.emit("ended", undefined);
       this.options.target.addEventListener("ended", this.endedListener);
+
+      // Auto-pause on background tab (unless explicitly opted out).
+      // Chrome throttles rAF and setTimeout in hidden tabs, so playback
+      // degrades anyway — better to pause cleanly and resume on return.
+      if (this.options.backgroundBehavior !== "continue" && typeof document !== "undefined") {
+        this.visibilityListener = () => this.onVisibilityChange();
+        document.addEventListener("visibilitychange", this.visibilityListener);
+      }
+
       this.emitter.emitSticky("ready", undefined);
       const bootstrapElapsed = performance.now() - bootstrapStart;
       dbg.info("bootstrap", `ready in ${bootstrapElapsed.toFixed(0)}ms`);
@@ -181,7 +211,7 @@ export class UnifiedPlayer {
     }
 
     try {
-      this.session = await plugin.execute(this.mediaContext!, this.options.target);
+      this.session = await plugin.execute(this.mediaContext!, this.options.target, this.transport);
     } catch (err) {
       // Try the fallback chain
       const chain = this.classification?.fallbackChain;
@@ -275,7 +305,7 @@ export class UnifiedPlayer {
       }
 
       try {
-        this.session = await plugin.execute(this.mediaContext!, this.options.target);
+        this.session = await plugin.execute(this.mediaContext!, this.options.target, this.transport);
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         errors.push(`${nextStrategy}: ${msg}`);
@@ -302,8 +332,10 @@ export class UnifiedPlayer {
     }
 
     // Chain exhausted with no working strategy.
-    this.emitter.emit("error", new Error(
-      `all fallback strategies failed: ${errors.join("; ")}`,
+    this.emitter.emit("error", new AvbridgeError(
+      ERR_ALL_STRATEGIES_EXHAUSTED,
+      `All playback strategies failed: ${errors.join("; ")}`,
+      "This file may require a codec or container that isn't available in this browser. Try the fallback strategy or check browser codec support.",
     ));
   }
 
@@ -366,7 +398,7 @@ export class UnifiedPlayer {
 
   /** Manually switch to a different playback strategy. Preserves current position and play/pause state. Concurrent calls are serialized. */
   async setStrategy(strategy: StrategyName, reason?: string): Promise<void> {
-    if (!this.mediaContext) throw new Error("player not ready");
+    if (!this.mediaContext) throw new AvbridgeError(ERR_PLAYER_NOT_READY, "Player not ready — wait for the 'ready' event before calling playback methods.", "Await the 'ready' event or check player.readyState before calling play/pause/seek.");
     if (this.session?.strategy === strategy) return;
 
     this.switchingPromise = this.switchingPromise.then(() =>
@@ -398,7 +430,7 @@ export class UnifiedPlayer {
     const plugin = this.registry.findFor(this.mediaContext!, strategy);
     if (!plugin) throw new Error(`no plugin available for strategy "${strategy}"`);
 
-    this.session = await plugin.execute(this.mediaContext!, this.options.target);
+    this.session = await plugin.execute(this.mediaContext!, this.options.target, this.transport);
 
     this.emitter.emitSticky("strategy", {
       strategy,
@@ -441,30 +473,62 @@ export class UnifiedPlayer {
 
   /** Begin or resume playback. Throws if the player is not ready. */
   async play(): Promise<void> {
-    if (!this.session) throw new Error("player not ready");
+    if (!this.session) throw new AvbridgeError(ERR_PLAYER_NOT_READY, "Player not ready — wait for the 'ready' event before calling playback methods.", "Await the 'ready' event or check player.readyState before calling play/pause/seek.");
+    this.userIntent = "play";
+    this.autoPausedForVisibility = false;
     await this.session.play();
   }
 
   /** Pause playback. No-op if the player is not ready or already paused. */
   pause(): void {
+    this.userIntent = "pause";
+    this.autoPausedForVisibility = false;
     this.session?.pause();
   }
 
+  /**
+   * Handle browser tab visibility changes. On hide: pause if the user
+   * had been playing. On show: resume if we were the one who paused.
+   * Skips when `backgroundBehavior: "continue"` is set (listener isn't
+   * installed in that case).
+   */
+  private onVisibilityChange(): void {
+    if (!this.session) return;
+    const action = decideVisibilityAction({
+      hidden: document.hidden,
+      userIntent: this.userIntent,
+      sessionIsPlaying: !this.options.target.paused,
+      autoPausedForVisibility: this.autoPausedForVisibility,
+    });
+    if (action === "pause") {
+      this.autoPausedForVisibility = true;
+      dbg.info("visibility", "tab hidden — auto-paused");
+      this.session.pause();
+    } else if (action === "resume") {
+      this.autoPausedForVisibility = false;
+      dbg.info("visibility", "tab visible — auto-resuming");
+      void this.session.play().catch((err) => {
+        // eslint-disable-next-line no-console
+        console.warn("[avbridge] auto-resume after tab return failed:", err);
+      });
+    }
+  }
+
   /** Seek to the given time in seconds. Throws if the player is not ready. */
   async seek(time: number): Promise<void> {
-    if (!this.session) throw new Error("player not ready");
+    if (!this.session) throw new AvbridgeError(ERR_PLAYER_NOT_READY, "Player not ready — wait for the 'ready' event before calling playback methods.", "Await the 'ready' event or check player.readyState before calling play/pause/seek.");
     await this.session.seek(time);
   }
 
   /** Switch the active audio track by track ID. Throws if the player is not ready. */
   async setAudioTrack(id: number): Promise<void> {
-    if (!this.session) throw new Error("player not ready");
+    if (!this.session) throw new AvbridgeError(ERR_PLAYER_NOT_READY, "Player not ready — wait for the 'ready' event before calling playback methods.", "Await the 'ready' event or check player.readyState before calling play/pause/seek.");
     await this.session.setAudioTrack(id);
   }
 
   /** Switch the active subtitle track by track ID, or pass `null` to disable subtitles. */
   async setSubtitleTrack(id: number | null): Promise<void> {
-    if (!this.session) throw new Error("player not ready");
+    if (!this.session) throw new AvbridgeError(ERR_PLAYER_NOT_READY, "Player not ready — wait for the 'ready' event before calling playback methods.", "Await the 'ready' event or check player.readyState before calling play/pause/seek.");
     await this.session.setSubtitleTrack(id);
   }
 
@@ -500,6 +564,10 @@ export class UnifiedPlayer {
       this.options.target.removeEventListener("ended", this.endedListener);
       this.endedListener = null;
     }
+    if (this.visibilityListener) {
+      document.removeEventListener("visibilitychange", this.visibilityListener);
+      this.visibilityListener = null;
+    }
     if (this.session) {
       await this.session.destroy();
       this.session = null;
@@ -515,6 +583,29 @@ export async function createPlayer(options: CreatePlayerOptions): Promise<Unifie
   return UnifiedPlayer.create(options);
 }
 
+/**
+ * Pure decision function for visibility-change handling. Separated from
+ * the class method so it can be unit-tested without a full player
+ * instance.
+ *
+ * @internal — exported for unit tests; not part of the public API.
+ */
+export function decideVisibilityAction(state: {
+  hidden: boolean;
+  userIntent: "play" | "pause";
+  sessionIsPlaying: boolean;
+  autoPausedForVisibility: boolean;
+}): "pause" | "resume" | "noop" {
+  if (state.hidden) {
+    // Tab hidden: pause if user had been playing and session is active
+    if (state.userIntent === "play" && state.sessionIsPlaying) return "pause";
+    return "noop";
+  }
+  // Tab visible: resume only if we're the one who paused
+  if (state.autoPausedForVisibility) return "resume";
+  return "noop";
+}
+
 /**
  * Build a synthetic classification for an explicit `initialStrategy` override.
  * The `class` is derived from the chosen strategy so diagnostics and any

package/src/plugins/builtin.ts

@@ -20,13 +20,13 @@ const remuxPlugin: Plugin = {
 const hybridPlugin: Plugin = {
   name: "hybrid",
   canHandle: () => typeof VideoDecoder !== "undefined",
-  execute: (ctx, video) => createHybridSession(ctx, video),
+  execute: (ctx, video, transport) => createHybridSession(ctx, video, transport),
 };
 
 const fallbackPlugin: Plugin = {
   name: "fallback",
   canHandle: () => true,
-  execute: (ctx, video) => createFallbackSession(ctx, video),
+  execute: (ctx, video, transport) => createFallbackSession(ctx, video, transport),
 };
 
 export function registerBuiltins(registry: PluginRegistry): void {

package/src/probe/avi.ts

@@ -205,6 +205,10 @@ function ffmpegToAvbridgeAudio(name: string): AudioCodec {
     case "ra_288": return "ra_288";
     case "sipr":   return "sipr";
     case "atrac3": return "atrac3";
+    case "dca":
+    case "dts":    return "dts";
+    case "truehd":
+    case "mlp":    return "truehd";
     default:       return name as AudioCodec;
   }
 }

package/src/probe/index.ts

@@ -1,6 +1,7 @@
-import type { ContainerKind, MediaContext, MediaInput } from "../types.js";
+import type { ContainerKind, MediaContext, MediaInput, TransportConfig } from "../types.js";
 import { normalizeSource, sniffNormalizedSource } from "../util/source.js";
 import { probeWithMediabunny } from "./mediabunny.js";
+import { AvbridgeError, ERR_PROBE_FAILED, ERR_PROBE_UNKNOWN_CONTAINER, ERR_LIBAV_NOT_REACHABLE } from "../errors.js";
 
 /** Containers mediabunny can demux. Sniff results outside this set go straight to libav. */
 const MEDIABUNNY_CONTAINERS = new Set<ContainerKind>([
@@ -32,13 +33,33 @@ const MEDIABUNNY_CONTAINERS = new Set<ContainerKind>([
  *    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);
+export async function probe(
+  source: MediaInput,
+  transport?: TransportConfig,
+): Promise<MediaContext> {
+  const normalized = await normalizeSource(source, transport);
   const sniffed = await sniffNormalizedSource(normalized);
 
   if (MEDIABUNNY_CONTAINERS.has(sniffed)) {
     try {
-      return await probeWithMediabunny(normalized, sniffed);
+      const result = await probeWithMediabunny(normalized, sniffed);
+      // If mediabunny returned unknown codecs, try libav which recognizes
+      // a wider range (DTS, TrueHD, etc.). Only escalate if there ARE
+      // tracks with unknown codecs — otherwise mediabunny's result is fine.
+      const hasUnknownCodec =
+        result.videoTracks.some((t) => t.codec === "unknown") ||
+        result.audioTracks.some((t) => t.codec === "unknown");
+      if (hasUnknownCodec) {
+        try {
+          const { probeWithLibav } = await import("./avi.js");
+          return await probeWithLibav(normalized, sniffed);
+        } catch {
+          // libav also failed — return mediabunny's result (unknown codecs
+          // are better than no result at all)
+          return result;
+        }
+      }
+      return result;
     } 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.
@@ -56,8 +77,10 @@ export async function probe(source: MediaInput): Promise<MediaContext> {
       } 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}.`,
+        throw new AvbridgeError(
+          ERR_PROBE_FAILED,
+          `Failed to probe ${sniffed.toUpperCase()} file. mediabunny: ${mbMsg}. libav: ${lvMsg}.`,
+          "The file may be corrupt, truncated, or in an unsupported format. Enable AVBRIDGE_DEBUG for detailed logs.",
         );
       }
     }
@@ -71,10 +94,17 @@ export async function probe(source: MediaInput): Promise<MediaContext> {
     const inner = err instanceof Error ? err.message : String(err);
     // eslint-disable-next-line no-console
     console.error("[avbridge] libav probe failed for", sniffed, "file:", err);
-    throw new Error(
-      sniffed === "unknown"
-        ? `unable to probe source: container could not be identified, and the libav.js fallback also failed: ${inner || "(no message — see browser console for the original error)"}`
-        : `${sniffed.toUpperCase()} files require libav.js, which failed to load: ${inner || "(no message — see browser console for the original error)"}`,
+    if (sniffed === "unknown") {
+      throw new AvbridgeError(
+        ERR_PROBE_UNKNOWN_CONTAINER,
+        `Unable to probe source: container format could not be identified. libav fallback: ${inner || "(no details)"}`,
+        "The file may be corrupt or in a format avbridge doesn't recognize. Check the file plays in VLC or ffprobe.",
+      );
+    }
+    throw new AvbridgeError(
+      ERR_LIBAV_NOT_REACHABLE,
+      `${sniffed.toUpperCase()} files require libav.js, which failed to load: ${inner || "(no details)"}`,
+      "Install @libav.js/variant-webcodecs, or check that AVBRIDGE_LIBAV_BASE points to the correct path.",
     );
   }
 }

package/src/strategies/fallback/audio-output.ts

@@ -76,12 +76,42 @@ export class AudioOutput implements ClockSource {
   private framesScheduled = 0;
   private destroyed = false;
 
+  /** User-set volume (0..1). Applied to the gain node. */
+  private _volume = 1;
+  /** User-set muted flag. When true, gain is forced to 0. */
+  private _muted = false;
+
   constructor() {
     this.ctx = new AudioContext();
     this.gain = this.ctx.createGain();
     this.gain.connect(this.ctx.destination);
   }
 
+  /** Set volume (0..1). Applied immediately to the gain node. */
+  setVolume(v: number): void {
+    this._volume = Math.max(0, Math.min(1, v));
+    this.applyGain();
+  }
+
+  getVolume(): number {
+    return this._volume;
+  }
+
+  /** Set muted. When true, output is silenced regardless of volume. */
+  setMuted(m: boolean): void {
+    this._muted = m;
+    this.applyGain();
+  }
+
+  getMuted(): boolean {
+    return this._muted;
+  }
+
+  private applyGain(): void {
+    const target = this._muted ? 0 : this._volume;
+    try { this.gain.gain.value = target; } catch { /* ignore */ }
+  }
+
   /**
    * Switch into wall-clock fallback mode. Called by the decoder when no
    * audio decoder could be initialized for the source. Once set, this
@@ -287,6 +317,7 @@ export class AudioOutput implements ClockSource {
     try { this.gain.disconnect(); } catch { /* ignore */ }
     this.gain = this.ctx.createGain();
     this.gain.connect(this.ctx.destination);
+    this.applyGain();
 
     this.pendingQueue = [];
     this.mediaTimeOfAnchor = newMediaTime;