avbridge 1.0.0

package/src/strategies/remux/pipeline.ts

@@ -0,0 +1,254 @@
+import type { MediaContext } from "../../types.js";
+import { MseSink } from "./mse.js";
+import {
+  avbridgeVideoToMediabunny,
+  avbridgeAudioToMediabunny,
+  buildMediabunnySourceFromInput,
+} from "../../probe/mediabunny.js";
+
+/**
+ * Remux pipeline built against mediabunny's real API.
+ *
+ * Key design notes:
+ *
+ * - mediabunny's fMP4 muxer is a streaming muxer that requires monotonically
+ *   increasing timestamps. It cannot accept out-of-order packets after a seek.
+ *   Therefore, on each seek we create a **fresh** Output + sources + StreamTarget.
+ *   The MseSink handles the SourceBuffer reset via `invalidate()`.
+ *
+ * - Backpressure is enforced at two levels: in the WritableStream write handler
+ *   (limits append queue depth and total buffered time) and in the pump loop
+ *   (limits buffered-ahead and total buffered time). Without this, long files
+ *   dump gigabytes into the SourceBuffer and exhaust memory.
+ */
+export interface RemuxPipeline {
+  start(fromTime?: number, autoPlay?: boolean): Promise<void>;
+  seek(time: number, autoPlay?: boolean): Promise<void>;
+  destroy(): Promise<void>;
+  stats(): Record<string, unknown>;
+}
+
+export async function createRemuxPipeline(
+  ctx: MediaContext,
+  video: HTMLVideoElement,
+): Promise<RemuxPipeline> {
+  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.
+  const mbVideoCodec = avbridgeVideoToMediabunny(videoTrackInfo.codec);
+  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.
+  const input = new mb.Input({
+    source: await buildMediabunnySourceFromInput(mb, ctx.source),
+    formats: mb.ALL_FORMATS,
+  });
+  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.
+  const videoConfig = await inputVideo.getDecoderConfig();
+  const audioConfig = inputAudio && inputAudio.isAudioTrack() ? await inputAudio.getDecoderConfig() : null;
+
+  // Packet sinks (input side) — reused across seeks.
+  const videoSink = new mb.EncodedPacketSink(inputVideo);
+  const audioSink = inputAudio?.isAudioTrack() ? new mb.EncodedPacketSink(inputAudio) : null;
+
+  // MSE sink — created lazily on first output write, reused across seeks.
+  let sink: MseSink | null = null;
+  const stats = { videoPackets: 0, audioPackets: 0, bytesWritten: 0, fragments: 0 };
+
+  let destroyed = false;
+  let pumpToken = 0;
+  let pendingAutoPlay = false;
+  let pendingStartTime = 0;
+
+  // The current Output instance. Recreated on each seek because mediabunny's
+  // fMP4 muxer requires monotonically increasing timestamps.
+  let currentOutput: InstanceType<typeof mb.Output> | null = null;
+
+  /**
+   * Create a fresh mediabunny Output wired to the MSE sink. Called once at
+   * start and again on each seek.
+   */
+  function createOutput() {
+    // Cancel the previous output if it exists.
+    if (currentOutput) {
+      try { void currentOutput.cancel(); } catch { /* ignore */ }
+    }
+
+    let mimePromise: Promise<string> | null = null;
+
+    const writable = new WritableStream<{
+      type: "write";
+      data: Uint8Array<ArrayBuffer>;
+      position: number;
+    }>({
+      write: async (chunk) => {
+        if (destroyed) return;
+        if (!sink) {
+          const mime = await (mimePromise ??= output.getMimeType());
+          sink = new MseSink({ mime, video });
+          await sink.ready();
+          // Apply deferred seek + autoPlay for the initial start.
+          if (pendingStartTime > 0) {
+            sink.invalidate(pendingStartTime);
+          }
+          sink.setPlayOnSeek(pendingAutoPlay);
+        }
+        // Backpressure: wait for the SourceBuffer append queue to drain.
+        while (sink && !destroyed && (sink.queueLength() > 10 || sink.bufferedAhead() > 60 || sink.totalBuffered() > 120)) {
+          await new Promise((r) => setTimeout(r, 500));
+        }
+        if (destroyed) return;
+        sink.append(chunk.data);
+        stats.bytesWritten += chunk.data.byteLength;
+        stats.fragments++;
+      },
+    });
+
+    const target = new mb.StreamTarget(writable);
+    const output = new mb.Output({
+      format: new mb.Mp4OutputFormat({ fastStart: "fragmented" }),
+      target,
+    });
+
+    // Build the output sources.
+    const videoSource = new mb.EncodedVideoPacketSource(mbVideoCodec!);
+    output.addVideoTrack(videoSource);
+
+    type AudioSourceCtorArg = ConstructorParameters<typeof mb.EncodedAudioPacketSource>[0];
+    let audioSource: InstanceType<typeof mb.EncodedAudioPacketSource> | null = null;
+    if (mbAudioCodec && inputAudio?.isAudioTrack()) {
+      audioSource = new mb.EncodedAudioPacketSource(mbAudioCodec as AudioSourceCtorArg);
+      output.addAudioTrack(audioSource);
+    }
+
+    currentOutput = output;
+    return { output, videoSource, audioSource };
+  }
+
+  async function pumpLoop(token: number, fromTime: number) {
+    const { output, videoSource, audioSource } = createOutput();
+
+    await output.start();
+
+
+    // Find the starting key packet so we never push partial GOPs.
+    const startVideoPacket =
+      fromTime > 0
+        ? (await videoSink.getKeyPacket(fromTime)) ?? (await videoSink.getFirstPacket())
+        : await videoSink.getFirstPacket();
+    if (!startVideoPacket) return;
+
+    const startAudioPacket = audioSink
+      ? (audioSink && fromTime > 0
+          ? (await audioSink.getPacket(fromTime)) ?? (await audioSink.getFirstPacket())
+          : await audioSink.getFirstPacket())
+      : null;
+
+    const videoIter = videoSink.packets(startVideoPacket);
+    const audioIter = audioSink && startAudioPacket ? audioSink.packets(startAudioPacket) : null;
+
+    let vNext = await videoIter.next();
+    let aNext = audioIter ? await audioIter.next() : { done: true as const, value: undefined };
+    let firstVideo = true;
+    let firstAudio = true;
+
+    while (!destroyed && pumpToken === token && (!vNext.done || !aNext.done)) {
+      // Backpressure: pause pumping when we've buffered enough.
+      while (
+        !destroyed &&
+        pumpToken === token &&
+        sink &&
+        (sink.bufferedAhead() > 30 || sink.queueLength() > 20 || sink.totalBuffered() > 90)
+      ) {
+        await new Promise((r) => setTimeout(r, 500));
+      }
+      if (destroyed || pumpToken !== token) break;
+
+      const vTs = !vNext.done ? vNext.value.timestamp : Number.POSITIVE_INFINITY;
+      const aTs = !aNext.done ? aNext.value.timestamp : Number.POSITIVE_INFINITY;
+
+      if (!vNext.done && vTs <= aTs) {
+        await videoSource.add(
+          vNext.value,
+          firstVideo && videoConfig ? { decoderConfig: videoConfig } : undefined,
+        );
+        firstVideo = false;
+        stats.videoPackets++;
+        vNext = await videoIter.next();
+      } else if (audioIter && audioSource && !aNext.done) {
+        await audioSource.add(
+          aNext.value,
+          firstAudio && audioConfig ? { decoderConfig: audioConfig } : undefined,
+        );
+        firstAudio = false;
+        stats.audioPackets++;
+        aNext = await audioIter.next();
+      } else {
+        break;
+      }
+    }
+
+    if (!destroyed && pumpToken === token) {
+      await output.finalize();
+      sink?.endOfStream();
+    }
+  }
+
+  return {
+    async start(fromTime = 0, autoPlay = false) {
+      // Store autoPlay/seekTime so the MseSink (created lazily on first
+      // write) can apply the deferred seek and auto-play.
+      pendingAutoPlay = autoPlay;
+      pendingStartTime = fromTime;
+      pumpLoop(++pumpToken, fromTime).catch((err) => {
+        // eslint-disable-next-line no-console
+        console.error("[avbridge] remux pipeline failed:", err);
+        try { sink?.destroy(); } catch { /* ignore */ }
+      });
+    },
+    async seek(time, autoPlay = false) {
+      if (sink) {
+        sink.setPlayOnSeek(autoPlay);
+        sink.invalidate(time);
+      } else {
+        pendingAutoPlay = autoPlay;
+        pendingStartTime = time;
+      }
+      pumpLoop(++pumpToken, time).catch((err) => {
+        // eslint-disable-next-line no-console
+        console.error("[avbridge] remux pipeline reseek failed:", err);
+      });
+    },
+    async destroy() {
+      destroyed = true;
+      pumpToken++;
+      try { if (currentOutput) await currentOutput.cancel(); } catch { /* ignore */ }
+      try { await input.dispose(); } catch { /* ignore */ }
+      sink?.destroy();
+    },
+    stats() {
+      return { ...stats, decoderType: "remux" };
+    },
+  };
+}
+

package/src/subtitles/index.ts

@@ -0,0 +1,91 @@
+import type { SubtitleTrackInfo } from "../types.js";
+import { srtToVtt } from "./srt.js";
+import { isVtt } from "./vtt.js";
+
+export { srtToVtt } from "./srt.js";
+export { SubtitleOverlay } from "./render.js";
+
+/**
+ * Discover sidecar `.srt` / `.vtt` files next to the source. Requires the
+ * caller to pass a `FileSystemDirectoryHandle` (e.g. via the File System
+ * Access API). Without that handle we can't enumerate sibling files.
+ */
+export interface DiscoveredSidecar {
+  url: string;
+  format: "srt" | "vtt";
+  language?: string;
+}
+
+export async function discoverSidecar(
+  file: File,
+  directory: FileSystemDirectoryHandle,
+): Promise<DiscoveredSidecar[]> {
+  const baseName = file.name.replace(/\.[^.]+$/, "");
+  const found: DiscoveredSidecar[] = [];
+
+  // Walk the directory and look for `${baseName}*.srt` / `*.vtt`.
+  for await (const [name, handle] of (directory as unknown as AsyncIterable<[string, FileSystemHandle]>)) {
+    if (handle.kind !== "file") continue;
+    if (!name.startsWith(baseName)) continue;
+    const lower = name.toLowerCase();
+    let format: "srt" | "vtt" | null = null;
+    if (lower.endsWith(".srt")) format = "srt";
+    else if (lower.endsWith(".vtt")) format = "vtt";
+    if (!format) continue;
+
+    const sidecarFile = await (handle as FileSystemFileHandle).getFile();
+    const url = URL.createObjectURL(sidecarFile);
+
+    // Try to extract a language tag (eg. movie.en.srt → "en").
+    const langMatch = name.slice(baseName.length).match(/[._-]([a-z]{2,3})(?:[._-]|\.)/i);
+    found.push({
+      url,
+      format,
+      language: langMatch?.[1],
+    });
+  }
+
+  return found;
+}
+
+/**
+ * Attach `<track>` elements for each subtitle to the player's `<video>`. SRT
+ * sources are converted to VTT first via blob URLs because `<track>` only
+ * accepts WebVTT.
+ */
+export async function attachSubtitleTracks(
+  video: HTMLVideoElement,
+  tracks: SubtitleTrackInfo[],
+): Promise<void> {
+  // Clear existing dynamically-attached tracks.
+  for (const t of Array.from(video.querySelectorAll("track[data-avbridge]"))) {
+    t.remove();
+  }
+
+  for (const t of tracks) {
+    if (!t.sidecarUrl) continue;
+    let url = t.sidecarUrl;
+    if (t.format === "srt") {
+      const res = await fetch(t.sidecarUrl);
+      const text = await res.text();
+      const vtt = srtToVtt(text);
+      const blob = new Blob([vtt], { type: "text/vtt" });
+      url = URL.createObjectURL(blob);
+    } else if (t.format === "vtt") {
+      // Validate quickly so a malformed file fails loudly here.
+      const res = await fetch(t.sidecarUrl);
+      const text = await res.text();
+      if (!isVtt(text)) {
+        // eslint-disable-next-line no-console
+        console.warn("[avbridge] subtitle missing WEBVTT header:", t.sidecarUrl);
+      }
+    }
+    const track = document.createElement("track");
+    track.kind = "subtitles";
+    track.src = url;
+    track.srclang = t.language ?? "und";
+    track.label = t.language ?? `Subtitle ${t.id}`;
+    track.dataset.avbridge = "true";
+    video.appendChild(track);
+  }
+}

package/src/subtitles/render.ts

@@ -0,0 +1,62 @@
+/**
+ * Custom subtitle overlay for the fallback strategy. We don't have a `<video>`
+ * with text tracks here, so we render cues into a positioned div ourselves.
+ *
+ * v1 only handles plain-text WebVTT cues with `HH:MM:SS.mmm` timing. Cue
+ * settings, voice tags, and styling are ignored.
+ */
+
+interface Cue {
+  start: number;
+  end: number;
+  text: string;
+}
+
+export class SubtitleOverlay {
+  private el: HTMLDivElement;
+  private cues: Cue[] = [];
+
+  constructor(parent: HTMLElement) {
+    this.el = document.createElement("div");
+    this.el.style.cssText =
+      "position:absolute;left:0;right:0;bottom:8%;text-align:center;color:white;text-shadow:0 0 4px black;font-family:sans-serif;font-size:1.4em;pointer-events:none;";
+    parent.appendChild(this.el);
+  }
+
+  loadVtt(text: string): void {
+    this.cues = parseVtt(text);
+  }
+
+  update(currentTime: number): void {
+    const active = this.cues.find((c) => currentTime >= c.start && currentTime <= c.end);
+    this.el.textContent = active?.text ?? "";
+  }
+
+  destroy(): void {
+    this.el.remove();
+    this.cues = [];
+  }
+}
+
+function parseVtt(text: string): Cue[] {
+  const cues: Cue[] = [];
+  const blocks = text.replace(/\r\n/g, "\n").split(/\n{2,}/);
+  for (const block of blocks) {
+    const lines = block.split("\n").filter(Boolean);
+    if (lines.length === 0 || lines[0] === "WEBVTT") continue;
+    const timingIdx = lines.findIndex((l) => l.includes("-->"));
+    if (timingIdx < 0) continue;
+    const m = /(\d{2}):(\d{2}):(\d{2})\.(\d{3})\s*-->\s*(\d{2}):(\d{2}):(\d{2})\.(\d{3})/.exec(
+      lines[timingIdx],
+    );
+    if (!m) continue;
+    const t = (h: string, mm: string, s: string, ms: string) =>
+      Number(h) * 3600 + Number(mm) * 60 + Number(s) + Number(ms) / 1000;
+    cues.push({
+      start: t(m[1], m[2], m[3], m[4]),
+      end: t(m[5], m[6], m[7], m[8]),
+      text: lines.slice(timingIdx + 1).join("\n"),
+    });
+  }
+  return cues;
+}

package/src/subtitles/srt.ts

@@ -0,0 +1,62 @@
+/**
+ * SRT → WebVTT converter.
+ *
+ * SRT cues:
+ *
+ *     1
+ *     00:00:20,000 --> 00:00:24,400
+ *     Subtitle text, possibly multiple lines.
+ *
+ * WebVTT cues:
+ *
+ *     WEBVTT
+ *
+ *     00:00:20.000 --> 00:00:24.400
+ *     Subtitle text, possibly multiple lines.
+ *
+ * The differences in v1 are:
+ *  - leading `WEBVTT` magic line
+ *  - `,` → `.` for milliseconds
+ *  - cue index lines are stripped (WebVTT allows them but SRT-style ints can
+ *    confuse some parsers; we drop them)
+ *  - BOM is stripped
+ */
+export function srtToVtt(srt: string): string {
+  // Strip BOM
+  if (srt.charCodeAt(0) === 0xfeff) srt = srt.slice(1);
+  // Normalize line endings
+  const normalized = srt.replace(/\r\n/g, "\n").replace(/\r/g, "\n").trim();
+
+  const blocks = normalized.split(/\n{2,}/);
+  const out: string[] = ["WEBVTT", ""];
+
+  for (const block of blocks) {
+    const lines = block.split("\n");
+    // Drop the leading numeric index, if present.
+    if (lines.length > 0 && /^\d+$/.test(lines[0].trim())) {
+      lines.shift();
+    }
+    if (lines.length === 0) continue;
+
+    const timing = lines.shift()!;
+    const vttTiming = convertTiming(timing);
+    if (!vttTiming) continue; // skip malformed cue
+
+    out.push(vttTiming);
+    for (const l of lines) out.push(l);
+    out.push("");
+  }
+
+  return out.join("\n");
+}
+
+function convertTiming(line: string): string | null {
+  // SRT: HH:MM:SS,mmm --> HH:MM:SS,mmm  (optional cue settings after)
+  const m = /^(\d{1,2}):(\d{2}):(\d{2})[,.](\d{1,3})\s*-->\s*(\d{1,2}):(\d{2}):(\d{2})[,.](\d{1,3})(.*)$/.exec(
+    line.trim(),
+  );
+  if (!m) return null;
+  const fmt = (h: string, mm: string, s: string, ms: string) =>
+    `${h.padStart(2, "0")}:${mm}:${s}.${ms.padEnd(3, "0").slice(0, 3)}`;
+  return `${fmt(m[1], m[2], m[3], m[4])} --> ${fmt(m[5], m[6], m[7], m[8])}${m[9] ?? ""}`;
+}

package/src/subtitles/vtt.ts

@@ -0,0 +1,5 @@
+/** Light validation for incoming VTT — we do not parse cues, just confirm header. */
+export function isVtt(text: string): boolean {
+  const trimmed = text.replace(/^\ufeff/, "").trimStart();
+  return trimmed.startsWith("WEBVTT");
+}

package/src/types-shim.d.ts

@@ -0,0 +1,3 @@
+// Type shims live in src/libav-stubs.d.ts (referenced via tsconfig `paths`).
+// Keep this file as a placeholder for any future global ambient declarations.
+