avbridge 2.3.0 → 2.5.0

package/src/strategies/fallback/video-renderer.ts

@@ -1,4 +1,5 @@
 import type { ClockSource } from "./audio-output.js";
+import { SubtitleOverlay } from "../../subtitles/render.js";
 
 /**
  * Renders decoded `VideoFrame`s into a 2D canvas overlaid on the user's
@@ -47,6 +48,16 @@ export class VideoRenderer {
   /** Cumulative count of ticks where PTS mode painted a frame. */
   private ticksPainted = 0;
 
+  /**
+   * Subtitle overlay div attached to the stage wrapper alongside the
+   * canvas. Created lazily when subtitle tracks are attached via the
+   * target's `<track>` children. Canvas strategies (hybrid, fallback)
+   * hide the <video>, so we can't rely on the browser's native cue
+   * rendering; we read TextTrack.cues and render into this overlay.
+   */
+  private subtitleOverlay: SubtitleOverlay | null = null;
+  private subtitleTrack: TextTrack | null = null;
+
   /**
    * Calibration offset (microseconds) between video PTS and audio clock.
    * Video PTS and AudioContext.currentTime can drift ~0.1% relative to
@@ -111,6 +122,15 @@ export class VideoRenderer {
     }
     target.style.visibility = "hidden";
 
+    // Create a subtitle overlay on the same parent as the canvas so cues
+    // appear over the rendered video. Shows nothing until a TextTrack
+    // gets attached via attachSubtitleTracks.
+    const overlayParent = parent instanceof HTMLElement ? parent : document.body;
+    this.subtitleOverlay = new SubtitleOverlay(overlayParent);
+    // Watch for <track> children on the target <video>. When one is
+    // added, grab its TextTrack and poll cues from it each tick.
+    this.watchTextTracks(target);
+
     const ctx = this.canvas.getContext("2d");
     if (!ctx) throw new Error("video renderer: failed to acquire 2D context");
     this.ctx = ctx;
@@ -156,10 +176,95 @@ export class VideoRenderer {
     }
   }
 
+  /**
+   * Watch the target <video>'s textTracks list. When a track is added,
+   * grab it and start polling cues on each render tick. Existing tracks
+   * (if any) are picked up immediately.
+   */
+  private watchTextTracks(target: HTMLVideoElement): void {
+    const pick = () => {
+      if (this.subtitleTrack) return;
+      const tracks = target.textTracks;
+      if (isDebug()) {
+        // eslint-disable-next-line no-console
+        console.log(`[avbridge:subs] watchTextTracks pick() — ${tracks.length} tracks`);
+      }
+      for (let i = 0; i < tracks.length; i++) {
+        const t = tracks[i];
+        if (isDebug()) {
+          // eslint-disable-next-line no-console
+          console.log(`[avbridge:subs] track ${i}: kind=${t.kind} mode=${t.mode} cues=${t.cues?.length ?? 0}`);
+        }
+        if (t.kind === "subtitles" || t.kind === "captions") {
+          this.subtitleTrack = t;
+          t.mode = "hidden"; // hidden means "cues available via API, don't render"
+          if (isDebug()) {
+            // eslint-disable-next-line no-console
+            console.log(`[avbridge:subs] picked track, mode=hidden`);
+          }
+          // Listen for cue load completion
+          const trackEl = target.querySelector(`track[srclang="${t.language}"]`) as HTMLTrackElement | null;
+          if (trackEl) {
+            trackEl.addEventListener("load", () => {
+              if (isDebug()) {
+                // eslint-disable-next-line no-console
+                console.log(`[avbridge:subs] track element loaded, cues=${t.cues?.length ?? 0}`);
+              }
+            });
+            trackEl.addEventListener("error", (ev) => {
+              // eslint-disable-next-line no-console
+              console.warn(`[avbridge:subs] track element error:`, ev);
+            });
+          }
+          break;
+        }
+      }
+    };
+    pick();
+    if (typeof target.textTracks.addEventListener === "function") {
+      target.textTracks.addEventListener("addtrack", (e) => {
+        if (isDebug()) {
+          // eslint-disable-next-line no-console
+          console.log("[avbridge:subs] addtrack event fired");
+        }
+        void e;
+        pick();
+      });
+    }
+  }
+
+  private _loggedCues = false;
+
+  /** Find the active cue (if any) for the given media time. */
+  private updateSubtitles(): void {
+    if (!this.subtitleOverlay || !this.subtitleTrack) return;
+    const cues = this.subtitleTrack.cues;
+    if (!cues || cues.length === 0) return;
+    if (isDebug() && !this._loggedCues) {
+      this._loggedCues = true;
+      // eslint-disable-next-line no-console
+      console.log(`[avbridge:subs] cues available: ${cues.length}, first start=${cues[0].startTime}, last end=${cues[cues.length-1].endTime}`);
+    }
+    const t = this.clock.now();
+    let activeText = "";
+    for (let i = 0; i < cues.length; i++) {
+      const c = cues[i];
+      if (t >= c.startTime && t <= c.endTime) {
+        const vttCue = c as VTTCue & { text?: string };
+        activeText = vttCue.text ?? "";
+        break;
+      }
+    }
+    // Strip VTT tags for plain rendering (e.g. <c.en> voice tags)
+    this.subtitleOverlay.setText(activeText.replace(/<[^>]+>/g, ""));
+  }
+
   private tick(): void {
     if (this.destroyed) return;
     this.rafHandle = requestAnimationFrame(this.tick);
 
+    this.updateSubtitles();
+
     if (this.queue.length === 0) return;
 
     const playing = this.clock.isPlaying();
@@ -331,6 +436,8 @@ export class VideoRenderer {
     this.destroyed = true;
     if (this.rafHandle != null) cancelAnimationFrame(this.rafHandle);
     this.flush();
+    if (this.subtitleOverlay) { this.subtitleOverlay.destroy(); this.subtitleOverlay = null; }
+    this.subtitleTrack = null;
     this.canvas.remove();
     this.target.style.visibility = "";
   }

package/src/strategies/hybrid/decoder.ts

@@ -20,10 +20,17 @@ import { AudioOutput } from "../fallback/audio-output.js";
 import type { MediaContext } from "../../types.js";
 import { dbg } from "../../util/debug.js";
 import { pickLibavVariant } from "../fallback/variant-routing.js";
+import {
+  sanitizePacketTimestamp,
+  sanitizeFrameTimestamp,
+  libavFrameToInterleavedFloat32,
+} from "../../util/libav-demux.js";
 
 export interface HybridDecoderHandles {
   destroy(): Promise<void>;
   seek(timeSec: number): Promise<void>;
+  /** Swap the active audio track — rebuilds the libav audio decoder + reseeks. */
+  setAudioTrack(trackId: number, timeSec: number): Promise<void>;
   stats(): Record<string, unknown>;
   onFatalError(handler: (reason: string) => void): void;
 }
@@ -52,7 +59,14 @@ export async function startHybridDecoder(opts: StartHybridDecoderOptions): Promi
   const readPkt = await libav.av_packet_alloc();
   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 (setAudioTrack swaps it). Prefer the id the
+  // probe layer listed first so both entry points agree.
+  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("hybrid decoder: file has no decodable streams");
@@ -388,6 +402,79 @@ export async function startHybridDecoder(opts: StartHybridDecoderOptions): Promi
       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] hybrid: setAudioTrack — no stream with id", trackId);
+        return;
+      }
+
+      const newToken = ++pumpToken;
+      if (pumpRunning) {
+        try { await pumpRunning; } catch { /* ignore */ }
+      }
+      if (destroyed) return;
+
+      // Tear down old audio decoder, build new one.
+      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] hybrid: setAudioTrack init failed — switching to no-audio:",
+          (err as Error).message,
+        );
+        audioDec = null;
+        opts.audio.setNoAudio();
+      }
+
+      audioStream = newStream;
+
+      // Re-seek demuxer to current time for the new track.
+      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] hybrid: setAudioTrack seek failed:", err);
+      }
+
+      // Flush video decoder too — demuxer moved back to a keyframe.
+      try {
+        if (videoDecoder && videoDecoder.state === "configured") {
+          await videoDecoder.flush();
+        }
+      } 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] hybrid pump failed (post-setAudioTrack):", err),
+      );
+    },
+
     async seek(timeSec) {
       const newToken = ++pumpToken;
       if (pumpRunning) {
@@ -459,185 +546,6 @@ export async function startHybridDecoder(opts: StartHybridDecoderOptions): Promi
 // time_base to avoid overflow.
 // ─────────────────────────────────────────────────────────────────────────────
 
-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;
-}
-
-// Frame timestamp sanitizer (same as fallback/decoder.ts, for audio frames)
-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;
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Audio frame → interleaved Float32 (duplicated from fallback/decoder.ts)
-// ─────────────────────────────────────────────────────────────────────────────
-
-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:
-      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
 // ─────────────────────────────────────────────────────────────────────────────

package/src/strategies/hybrid/index.ts

@@ -137,8 +137,23 @@ export async function createHybridSession(
       await doSeek(time);
     },
 
-    async setAudioTrack(_id) {
-      // Post-MVP for hybrid strategy
+    async setAudioTrack(id) {
+      if (!ctx.audioTracks.some((t) => t.id === id)) {
+        console.warn("[avbridge] hybrid: setAudioTrack — unknown track id", id);
+        return;
+      }
+      const wasPlaying = audio.isPlaying();
+      const currentTime = audio.now();
+      await audio.pause().catch(() => {});
+      await handles.setAudioTrack(id, currentTime).catch((err) =>
+        console.warn("[avbridge] hybrid: handles.setAudioTrack failed:", err),
+      );
+      await audio.reset(currentTime);
+      renderer.flush();
+      if (wasPlaying) {
+        await waitForBuffer();
+        await audio.start();
+      }
     },
 
     async setSubtitleTrack(_id) {

package/src/strategies/native.ts

@@ -49,10 +49,13 @@ export async function createNativeSession(
       video.currentTime = time;
     },
     async setAudioTrack(id) {
-      // HTMLMediaElement.audioTracks is not exposed in all browsers, so we
-      // try-catch and no-op if not available.
+      // HTMLMediaElement.audioTracks isn't exposed on all browsers (Chrome
+      // needs the MediaCapabilities flag for many containers). Best-effort:
+      // try by string id match first, then by index. If the list doesn't
+      // exist, silently no-op — the user will still hear whatever track the
+      // browser picked by default.
       const tracks = (video as unknown as { audioTracks?: { length: number; [i: number]: { id: string; enabled: boolean } } }).audioTracks;
-      if (!tracks) return;
+      if (!tracks || tracks.length === 0) return;
       for (let i = 0; i < tracks.length; i++) {
         tracks[i].enabled = tracks[i].id === String(id) || i === id;
       }

package/src/strategies/remux/index.ts

@@ -66,8 +66,20 @@ export async function createRemuxSession(
       const wasPlaying = !video.paused;
       await pipeline.seek(time, wasPlaying || wantPlay);
     },
-    async setAudioTrack(_id) {
-      // v1: single-track output. Multi-audio remuxing is post-MVP.
+    async setAudioTrack(id) {
+      if (!context.audioTracks.some((t) => t.id === id)) {
+        console.warn("[avbridge] remux: setAudioTrack — unknown track id", id);
+        return;
+      }
+      const wasPlaying = !video.paused;
+      const time = video.currentTime || 0;
+      // Not yet started? Just note the selection and let play()/seek() drive.
+      if (!started) {
+        started = true;
+        await pipeline.setAudioTrack(id, time, wantPlay || wasPlaying);
+        return;
+      }
+      await pipeline.setAudioTrack(id, time, wasPlaying || wantPlay);
     },
     async setSubtitleTrack(id) {
       const tracks = video.textTracks;

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/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 = [];