@torrent-tv/proxy 2.63.0 → 2.64.1

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2.64.0
+
+- **Fix**: A reader sizes its window from the memory the store may hold NOW, not from the allowance it was created with. 2.63.0 made the allowance follow the machine but left the `capacity` getter answering the original reservation, and that getter is what `ceilingPieces` reads — so a reader would have gone on claiming pieces against an allowance the machine had already withdrawn.
+- **New**: Container and track domain — `Container` (RFC 9559 / ISO 14496-12) with `MatroskaContainer` / `Mp4Container` / `AviContainer` via `ContainerFactory` (16-byte sniff), and `ContainerTrack` → `VideoTrack` / `AudioTrack` (`FlagOriginal`/`FlagCommentary`/`FlagVisualImpaired`) / `SubtitleTrack` → `TextSubtitleTrack` (`S_TEXT/UTF8`, `tx3g`, `wvtt`) / `ImageSubtitleTrack` (`PGS`, `VobSub`, `subp`) + `ExternalSubtitleFile`. Every class constructed from its spec section: `FlagForced` only on subtitles (RFC 9559 §5.1.4.1 0x55AA), `FlagEnabled`/`FlagDefault` + `LanguageBCP47` MUST on base, `track_enabled`/`alternate_group`/`elng` on MP4, `AVIIF_KEYFRAME` on AVI. `LanguageBCP47` overrides `Language` per MUST, disabled tracks kept for `declaredIndex` alignment with ffmpeg `0:s:N` (roadmap 62).
+- **New**: Application layer — `ContainerOrchestrator` (per-file cache, `getTracks`/`getKeyframeIndex`) and `SubtitleOrchestrator` (wraps `torrent-worker/subtitle-cues.js` cluster walk behind track abstraction).
+- **New**: Interface layer — `PlaybackController` / `SubtitleController`; `routes/api/playback-plan/post.js` and `routes/api/subtitles/get.js` delegate to controllers instead of calling services directly.
+- **Chore**: `proxy/docs/container-architecture.md` with mermaid class/sequence diagrams and flags matrix; `proxy/CLAUDE.md` layout updated; `services/container-index/` marked as internal detail used by `container/*`.
+
 ## 2.63.0
 
 - **New**: The piece store says what it has TAKEN, not only what it holds. `committed` and `on-disk` stand beside `resident` in its line. The two are different quantities and the difference is the growth that had no explanation: the pool only ever grows — `SharedArrayBuffer` has no shrink — so a piece spilled to disk returns its slot to the free list and its memory to nobody. On 2026-08-28 the store reported "144MB" while the process held 893 MB.

package/CLAUDE.md

@@ -25,6 +25,23 @@ Linux-only host (e.g. POSIX-only signals must degrade elsewhere).
     long-polls while a segment is being produced, returns retryable 503 (never
     202 — hls.js can't consume it).
 - `services/`:
+  - `container/` — domain layer: `Container` (abstract, RFC 9559 / ISO 14496-12),
+    `MatroskaContainer` / `Mp4Container` / `AviContainer`, `ContainerFactory`
+    (sniff 16 bytes → precise subclass). See `docs/container-architecture.md`.
+  - `tracks/` — domain layer: `ContainerTrack` (base: TrackNumber, declaredIndex,
+    language/BCP47, isEnabled/isDefault) → `VideoTrack` / `AudioTrack` /
+    `SubtitleTrack` → `TextSubtitleTrack` / `ImageSubtitleTrack`,
+    `ExternalSubtitleFile`. Spec-accurate flags (FlagForced only on subtitles per
+    RFC 9559 §5.1.4.1, FlagOriginal/Commentary only on audio, tkhd
+    track_enabled / alternate_group, elng BCP47).
+  - `orchestrators/` — application layer: `ContainerOrchestrator` (detect + per-file
+    cache, `getTracks`/`getKeyframeIndex`), `SubtitleOrchestrator` (wraps
+    `torrent-worker/subtitle-cues.js` cluster walk + `Container` tracks, warm/push).
+  - `controllers/` — interface layer: `PlaybackController` / `SubtitleController`
+    (thin adapters over orchestrators; routes depend on controllers, not services).
+    `routes/*` are now thin HTTP translators.
+  - `container-index/` — legacy readers (ebml-reader, matroska/mp4/avi keyframe and
+    subtitle tables) — used internally by `container/*`, deprecated as direct import.
   - `playback-planner.js` — single ffmpeg probe returns audioCodec, videoCodec,
     container, durationSeconds. `mode` is advisory; the browser decides.
   - `hls-session-manager.js` — one ffmpeg per (source, file, settings). Serves a

package/docs/container-architecture.md

@@ -0,0 +1,86 @@
+# Container & Track architecture
+
+Domain → Application → Interface, per RFC 9559 (Matroska) and ISO/IEC 14496-12 (MP4).
+
+## Layers
+
+```mermaid
+flowchart TB
+  subgraph Domain
+    C[Container<br/>abstract<br/>RFC9559 / 14496-12]
+    MC[MatroskaContainer]
+    MpC[Mp4Container]
+    AC[AviContainer]
+    CT[ContainerTrack<br/>isEnabled/isDefault/language]
+    VT[VideoTrack]
+    AT[AudioTrack]
+    ST[SubtitleTrack]
+    TST[TextSubtitleTrack<br/>S_TEXT/UTF8 tx3g wvtt]
+    IST[ImageSubtitleTrack<br/>PGS VobSub subp]
+    C --> MC & MpC & AC
+    CT --> VT & AT & ST
+    ST --> TST & IST
+    MC & MpC & AC -- readTracks --> CT
+  end
+  subgraph Application
+    CF[ContainerFactory<br/>detect 16 bytes]
+    CO[ContainerOrchestrator<br/>cache + getTracks/getKeyframeIndex]
+    SO[SubtitleOrchestrator<br/>wrap subtitle-cues.js]
+    CF --> CO
+    CO --> SO
+  end
+  subgraph Interface
+    PC[PlaybackController]
+    SC[SubtitleController]
+    R1[routes/api/playback-plan]
+    R2[routes/api/subtitles]
+    PC --> R1
+    SC --> R2
+    CO --> PC
+    SO --> SC
+  end
+```
+
+## Class responsibilities (spec-grounded)
+
+| Class | Spec section | Fields | Not responsible |
+|---|---|---|---|
+| `ContainerTrack` | RFC9559 TrackEntry common + ISO 14496-12 tkhd/mdhd/hdlr/elng | `trackNumber`, `declaredIndex`, `codecId`, `language`/`languageBcp47` (MUST rule), `name`, `isEnabled` (0xB9 / track_enabled), `isDefault`+`declaresDefault` (0x88) | Type-specific flags |
+| `VideoTrack` | RFC9559 Video, ISO 14496-12 tkhd width/height, stsd | `width/height/display*`, `fps`, `isHdr`, `bitDepth` | Subtitle flags |
+| `AudioTrack` | RFC9559 FlagOriginal 0x55AE, FlagCommentary 0x55AF, FlagVisualImpaired 0x55AC | `isOriginal/isCommentary/isVisualImpaired`, `channels/samplingFrequency` | FlagForced |
+| `SubtitleTrack` | RFC9559 FlagForced 0x55AA (subtitle-only), FlagHearingImpaired 0x55AB | `isForced/isHearingImpaired`, `clusterPositions`/`samples` | Video dims |
+| `TextSubtitleTrack` | `S_TEXT/UTF8, S_TEXT/ASS, tx3g, wvtt` | `toVtt()` convertible | Image tracks |
+| `ImageSubtitleTrack` | `S_HDMV/PGS, S_VOBSUB, subp, clcp` | kept for `declaredIndex` alignment | Conversion |
+| `MatroskaContainer` | RFC9559 SeekHead, Tracks, Cues, Clusters | single Tracks walk for all types, EBML via `ebml-reader.js` | HTTP |
+| `Mp4Container` | ISO 14496-12 moov/trak/tkhd/mdhd/hdlr/elng/stbl | `alternate_group` grouping, packed language, `tx3g` forced bits | Torrent |
+| `AviContainer` | RIFF AVI idx1 | `AVIIF_KEYFRAME` keyframe times | Tracks beyond video |
+
+`VideoTrack` never carries `isForced` — spec states FlagForced "Applies only to subtitles". Placing it in base would pollute video with irrelevant state.
+
+## Orchestrators & Controllers
+
+- `ContainerFactory.create({readRange,fileSize})` — sniffs 16 bytes, returns precise `Container` subclass. No torrent knowledge.
+- `ContainerOrchestrator` — per-file cache (`sourceKey:fileIndex`), `getTracks()` / `getKeyframeIndex()`. Transport-agnostic.
+- `SubtitleOrchestrator` — wraps `torrent-worker/subtitle-cues.js` (`planFor`, `cuesHeldFor`, `warmSubtitleCues`) behind `ContainerTrack` abstraction. Routes depend on this, not on worker directly.
+- `PlaybackController` / `SubtitleController` — thin interface adapters; `routes/api/*` delegate to them, handle HTTP headers (`X-Subtitle-Language`, `X-Subtitle-Cursor`) only.
+
+## Legacy
+
+`services/container-index/` remains as internal detail used by `container/*`. Direct imports from routes are deprecated — use `orchestrators/` and `controllers/` instead.
+
+## Flags matrix
+
+| Flag | Matroska ID | Applies to | Base or subclass |
+|---|---|---|---|
+| `FlagEnabled` | 0xB9 default 1 | all | `ContainerTrack` |
+| `FlagDefault` | 0x88 default 1 | all | `ContainerTrack` (`declaresDefault`) |
+| `Language` | 0x22B59C | all | `ContainerTrack` |
+| `LanguageBCP47` | 0x22B59D MUST | all | `ContainerTrack` |
+| `FlagForced` | 0x55AA | subtitle only | `SubtitleTrack` |
+| `FlagHearingImpaired` | 0x55AB | subtitle | `SubtitleTrack` |
+| `FlagVisualImpaired` | 0x55AC | audio (descriptive) + subtitle | `AudioTrack`/`SubtitleTrack` |
+| `FlagOriginal` | 0x55AE | audio | `AudioTrack` |
+| `FlagCommentary` | 0x55AF | audio | `AudioTrack` |
+| `track_enabled` | tkhd 0x000001 | all | `ContainerTrack` |
+| `alternate_group` | tkhd | audio/video alternates | `ContainerTrack.alternateGroup` |
+| `elng` | 14496-12 §8.4.6 | all | `ContainerTrack.languageBcp47` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.63.0",
+  "version": "2.64.1",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {

package/routes/api/playback-plan/post.js

@@ -24,7 +24,7 @@ function getPayload(body) {
   return {};
 }
 
-export async function handleApiPlaybackPlanPost(req, reply, { playbackPlanner }) {
+export async function handleApiPlaybackPlanPost(req, reply, { playbackPlanner, sourceRegistry, torrentPool, ffmpegBin, localBaseUrl }) {
   const payload = getPayload(req.body);
   const sourceKey = typeof payload.sourceKey === "string" ? payload.sourceKey.trim() : "";
   const fileIndex = Number(payload.fileIndex);
@@ -34,12 +34,11 @@ export async function handleApiPlaybackPlanPost(req, reply, { playbackPlanner })
     return reply.code(400).send({ error: "sourceKey and valid fileIndex are required." });
   }
 
+  // Interface delegates to PlaybackController (orchestrator + domain). Keeps route thin.
+  const { PlaybackController } = await import("../../../services/controllers/PlaybackController.js");
+  const controller = new PlaybackController({ torrentPool, sourceRegistry, ffmpegBin, localBaseUrl, playbackPlanner });
   try {
-    // Short per-request budget: if the file header is not downloaded yet the
-    // planner returns quickly with `pending: true` instead of blocking up to
-    // the transport's 60 s request timeout. The browser polls again (the header
-    // keeps downloading, prioritised on each call). Well under that 60 s limit.
-    const plan = await playbackPlanner.getPlan({ sourceKey, fileIndex, userAgent, maxWaitMs: 8_000 });
+    const plan = await controller.getPlan({ sourceKey, fileIndex, userAgent, maxWaitMs: 8_000 });
     return reply.send(plan);
   } catch (error) {
     if (error instanceof Error && error.code === "SOURCE_NOT_FOUND") {

package/routes/api/subtitles/get.js

@@ -25,15 +25,12 @@
  */
 
 import { spawn } from "node:child_process";
-import { convertSubtitleToVtt, decodeSubtitleBytes } from "../../../services/subtitle-convert.js";
 import { detectLanguage } from "../../../services/language-detect.js";
-import { finalizeCues } from "../../../services/torrent-worker/subtitle-cues.js";
+import { SubtitleController } from "../../../services/controllers/SubtitleController.js";
 import { logger } from "../../../utils/logger.js";
 
 // Safety cap: no embedded extraction may outlive this.
 const EXTRACTION_TIMEOUT_MS = 30 * 60 * 1000;
-// External subtitle files are small; cap the read to guard against a bad index.
-const EXTERNAL_MAX_BYTES = 8 * 1024 * 1024;
 
 /** Set the detected-language response headers (no-op when detection failed). */
 function setLanguageHeaders(reply, lang) {
@@ -58,92 +55,54 @@ export async function handleApiSubtitlesGet(req, reply, { sourceRegistry, torren
     return reply.code(400).send({ error: "sourceKey and fileIndex are required." });
   }
 
-  const sourceRecord = sourceRegistry.get(sourceKey);
-  if (!sourceRecord) {
-    return reply.code(404).send({ error: "Source key was not found." });
-  }
-  const torrent = await torrentPool.getTorrent(sourceRecord.sourceType, sourceRecord.source);
-  const file = torrent.files[fileIndex];
-  if (!file) {
-    return reply.code(404).send({ error: "File index was not found in torrent." });
-  }
+  // Interface layer delegates to SubtitleController (orchestrator + domain),
+  // which owns external-file vs embedded-track branching and the cluster walk.
+  const controller = new SubtitleController({ sourceRegistry, torrentPool });
+  const since = Number.parseInt(String(req.query?.since ?? ""), 10);
+  const after = Number.parseFloat(String(req.query?.after ?? ""));
+  const result = await controller.getSubtitle({
+    sourceKey,
+    fileIndex,
+    trackIndex: hasTrackIndex ? trackIndex : undefined,
+    since: Number.isInteger(since) ? since : null,
+    after: Number.isFinite(after) ? after : null
+  });
 
-  // ---- External subtitle FILE (no trackIndex) -----------------------------
-  if (!hasTrackIndex) {
-    const name = typeof file.name === "string" ? file.name : "";
-    const ext = name.slice(name.lastIndexOf(".")).toLowerCase();
-    const release = torrentPool.acquireFile(torrent, fileIndex);
-    try {
-      const bytes = await readFileFully(file, EXTERNAL_MAX_BYTES);
-      const text = decodeSubtitleBytes(bytes);
-      const vtt = convertSubtitleToVtt(text, ext);
-      if (!vtt) {
-        return reply.code(422).send({ error: `Unsupported subtitle format: ${ext}` });
-      }
-      setLanguageHeaders(reply, detectLanguage(text));
+  if (result.error) {
+    return reply.code(result.status ?? 400).send({ error: result.error });
+  }
+  if (result.vtt !== undefined) {
+    if (result.vtt !== null) {
+      // External file or cluster-held cues — controller already detected language.
+      const lang = result.language ?? null;
+      if (lang) setLanguageHeaders(reply, lang);
       reply.header("content-type", "text/vtt; charset=utf-8");
       reply.header("cache-control", "no-store");
-      return reply.send(vtt);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      return reply.code(502).send({ error: `Could not read subtitle file: ${message}` });
-    } finally {
-      release();
+      if (hasTrackIndex) {
+        reply.header("access-control-allow-origin", "*");
+        if (result.headers) {
+          for (const [k, v] of Object.entries(result.headers)) reply.header(k, String(v));
+          reply.raw.setHeader(
+            "Access-Control-Expose-Headers",
+            "X-Subtitle-Language, X-Subtitle-Language-Name, X-Subtitle-Covered-Clusters, X-Subtitle-Indexed-Clusters, X-Subtitle-Cursor"
+          );
+        }
+      }
+      return reply.send(result.vtt);
     }
   }
+  // If controller returned pending, fall through to ffmpeg extraction below.
 
-  // ---- Embedded track (ffmpeg extraction, streamed) -----------------------
+  // ---- Embedded track — controller had no held cues, try cluster path directly for headers compatibility
+  // The controller's getSubtitle already attempted the cluster walk; reaching here means it returned pending.
+  if (!hasTrackIndex) {
+    // Should have been handled above — pending for external is unsupported format
+    return reply.code(422).send({ error: "Unsupported subtitle format" });
+  }
   if (!Number.isInteger(trackIndex) || trackIndex < 0) {
     return reply.code(400).send({ error: "trackIndex must be a non-negative integer." });
   }
 
-  // From the clusters the viewer has already downloaded, if this file can be
-  // read that way. Costs no network at all and answers with the part of the
-  // film they are watching; the rest arrives as they watch it. Only when the
-  // container cannot be read this way does the old extraction run.
-  // How many cues this browser has already been sent, counted in the order
-  // they were FOUND. Sending them again is bytes for nothing: measured
-  // 2026-08-19, one track is 76 KB and the browser asked for it every few
-  // seconds while the film downloaded. Absent or unparsable means "send
-  // everything", which is what a browser asking for the first time wants.
-  //
-  // Found-order, not time. A cue's time cannot serve as a cursor here: the
-  // cues are read out of whichever clusters are downloaded, and those are not
-  // contiguous, so the set grows in the middle as well as at the end. The old
-  // `?after=<seconds>` therefore threw away every cue that turned up BEHIND
-  // the furthest one already sent — which is the stretch the viewer is about
-  // to watch. Measured 2026-08-20: a viewer at 272 s was sent cues out to
-  // 1176 s, and from that moment nothing between the two could ever reach
-  // them, with 59 of 276 clusters read. `after` is still honoured so an older
-  // browser keeps working.
-  const since = Number.parseInt(String(req.query?.since ?? ""), 10);
-  const after = Number.parseFloat(String(req.query?.after ?? ""));
-  const held = await cuesFromDownloadedClusters(
-    torrentPool,
-    torrent,
-    fileIndex,
-    trackIndex,
-    Number.isFinite(after) ? after : null,
-    Number.isInteger(since) ? since : null
-  );
-  if (held !== null) {
-    setLanguageHeaders(reply, held.language);
-    reply.header("content-type", "text/vtt; charset=utf-8");
-    reply.header("cache-control", "no-store");
-    reply.header("access-control-allow-origin", "*");
-    // How much of the film these cues cover, so the browser knows to ask again
-    // as playback moves into clusters that were not downloaded yet.
-    reply.header("X-Subtitle-Covered-Clusters", String(held.coveredClusters));
-    reply.header("X-Subtitle-Indexed-Clusters", String(held.indexedClusters));
-    // What to send back as `?since=` next time.
-    reply.header("X-Subtitle-Cursor", String(held.cursor));
-    reply.raw.setHeader(
-      "Access-Control-Expose-Headers",
-      "X-Subtitle-Language, X-Subtitle-Language-Name, X-Subtitle-Covered-Clusters, X-Subtitle-Indexed-Clusters, X-Subtitle-Cursor"
-    );
-    return reply.send(held.vtt);
-  }
-
   const inputUrl = new URL("/stream", `${localBaseUrl}/`);
   inputUrl.searchParams.set("sourceKey", sourceKey);
   inputUrl.searchParams.set("fileIndex", String(fileIndex));
@@ -238,132 +197,4 @@ function startExtraction({ key, ffmpegBin, localBaseUrl, sourceKey, fileIndex, t
   ffmpeg.once("error", settle);
 }
 
-/**
- * Read a torrent file fully into a Buffer, bounded by `maxBytes`.
- *
- * @param {{ createReadStream: () => import("node:stream").Readable, length?: number }} file
- * @param {number} maxBytes
- * @returns {Promise<Buffer>}
- */
-function readFileFully(file, maxBytes) {
-  return new Promise((resolve, reject) => {
-    const stream = file.createReadStream();
-    const chunks = [];
-    let total = 0;
-    stream.on("data", (chunk) => {
-      total += chunk.length;
-      if (total > maxBytes) {
-        stream.destroy();
-        reject(new Error("subtitle file exceeds the size cap"));
-        return;
-      }
-      chunks.push(chunk);
-    });
-    stream.on("end", () => resolve(Buffer.concat(chunks)));
-    stream.on("error", reject);
-  });
-}
-
-/**
- * The cues of a track from clusters already downloaded, as WebVTT.
- *
- * `trackIndex` is the browser's number for the subtitle stream — its position
- * among ALL the subtitle streams, as ffmpeg lists them — while Matroska blocks
- * carry the file's own track number. The plan lists only the tracks that can
- * become text, so it is matched on `declaredIndex`, which each track carries
- * for exactly this: its place in the file's full list of subtitle tracks.
- *
- * @param {object} torrentPool
- * @param {object} torrent
- * @param {number} fileIndex
- * @param {number} trackIndex
- * @returns {Promise<{ vtt: string, language: object | null, coveredClusters: number, indexedClusters: number } | null>}
- *   Null when this file cannot be read this way, and then the caller falls back.
- */
-async function cuesFromDownloadedClusters(torrentPool, torrent, fileIndex, trackIndex, after = null, since = null) {
-  if (typeof torrentPool?.getSubtitleTracks !== "function") {
-    return null;
-  }
-  let tracks;
-  try {
-    tracks = await torrentPool.getSubtitleTracks(torrent, fileIndex);
-  } catch {
-    return null;
-  }
-  // BY the browser's number, not by position in this list. The list holds only
-  // the tracks that can become WebVTT, while the browser counts every subtitle
-  // stream ffmpeg lists — so on a file carrying a PGS or VobSub track the two
-  // ran one apart, and the request either found the wrong track or found none
-  // and fell through to the ffmpeg extraction below, which reads the whole film
-  // (752 s measured, 2026-08-19) for cues already in hand.
-  const track = Array.isArray(tracks)
-    ? tracks.find((candidate) => candidate.declaredIndex === trackIndex) ?? null
-    : null;
-  if (!track) {
-    return null;
-  }
-  let held;
-  try {
-    held = await torrentPool.getSubtitleCues(torrent, fileIndex, track.trackNumber);
-  } catch {
-    return null;
-  }
-  if (!held || !Array.isArray(held.cues)) {
-    return null;
-  }
-  // Only what the browser does not have. The language is still detected from
-  // EVERYTHING held, because three new lines say much less about a language
-  // than the whole track does.
-  const cursor = held.cues.reduce((highest, cue) => Math.max(highest, Number(cue.seq) || 0), 0);
-  const fresh = Number.isInteger(since)
-    ? held.cues.filter((cue) => (Number(cue.seq) || 0) > since)
-    : Number.isFinite(after)
-      ? held.cues.filter((cue) => cue.startSeconds > after)
-      : held.cues;
-  const vtt = cuesToVtt(fresh, held.codecId);
-  const language = held.cues.length > 0
-    ? detectLanguage(held.cues.map((cue) => cue.text).join("\n"))
-    : null;
-  return {
-    vtt,
-    language,
-    cursor,
-    coveredClusters: held.coveredClusters ?? 0,
-    indexedClusters: held.indexedClusters ?? 0
-  };
-}
-
-/**
- * WebVTT from cues read out of the container. The end-time synthesis and ASS
- * stripping are shared with the push path — see `finalizeCues` in
- * `services/torrent-worker/subtitle-cues.js` — so a pulled cue and a pushed
- * one read identically; this function only adds the WebVTT framing.
- *
- * @param {{ startSeconds: number, endSeconds: number | null, text: string }[]} cues
- * @param {string} codecId
- * @returns {string}
- */
-function cuesToVtt(cues, codecId) {
-  const lines = ["WEBVTT", ""];
-  for (const cue of finalizeCues(cues, codecId)) {
-    lines.push(`${vttTime(cue.startSeconds)} --> ${vttTime(cue.endSeconds)}`);
-    lines.push(cue.text);
-    lines.push("");
-  }
-  return lines.join("\n");
-}
 
-/**
- * A time in the form WebVTT requires.
- *
- * @param {number} seconds
- * @returns {string}
- */
-function vttTime(seconds) {
-  const safe = Math.max(0, seconds);
-  const hours = Math.floor(safe / 3600);
-  const minutes = Math.floor((safe % 3600) / 60);
-  const rest = safe % 60;
-  return `${String(hours).padStart(2, "0")}:${String(minutes).padStart(2, "0")}:` +
-    `${rest.toFixed(3).padStart(6, "0")}`;
-}

package/services/container/AviContainer.js

@@ -0,0 +1,45 @@
+/**
+ * @file AVI container — RIFF.
+ *
+ * Minimal: only keyframe index via idx1 (AVIIF_KEYFRAME). Tracks are not
+ * used by current product beyond video — expose a single VideoTrack if needed.
+ * Spec: RIFF AVI, idx1 chunk at file end, OpenDML may lack idx1 → no index.
+ */
+
+import { Container } from "./Container.js";
+import { isAvi, readAviKeyframeTimes } from "../container-index/avi.js";
+import { VideoTrack } from "../tracks/VideoTrack.js";
+
+export class AviContainer extends Container {
+  get formatName() {
+    return "avi";
+  }
+
+  static detect(head) {
+    return isAvi(head);
+  }
+
+  async readTracks() {
+    const head = await this.readRange(0, Math.min(4095, this.fileSize - 1));
+    if (!head || !isAvi(head)) return [];
+    // AVI track table is minimal — expose one video track for uniformity.
+    return [new VideoTrack({
+      trackNumber: 1,
+      declaredIndex: 0,
+      codecId: "",
+      language: "",
+      languageBcp47: "",
+      name: "",
+      isEnabled: true,
+      isDefault: true,
+      declaresDefault: false
+    })];
+  }
+
+  async readKeyframeIndex() {
+    const r = await readAviKeyframeTimes(this.readRange, this.fileSize);
+    if (!r) return null;
+    if (Array.isArray(r)) return { times: r, tolerance: 0 };
+    return r;
+  }
+}

package/services/container/Container.js

@@ -0,0 +1,59 @@
+/**
+ * @file Base Container — abstract per RFC 9559 / ISO 14496-12.
+ *
+ * A Container knows how to read its own format's track table and index.
+ * Concrete containers (MatroskaContainer, Mp4Container, AviContainer) implement
+ * spec-specific parsing. All byte access goes through `readRange(start,end)` so
+ * the class works over torrent piece windows.
+ *
+ * Spec refs:
+ *  - Matroska RFC 9559 §5: EBML, Segment, SeekHead, Tracks, Cues, Clusters
+ *  - MP4 ISO/IEC 14496-12 §8: ftyp, moov, trak, tkhd, mdhd, hdlr, elng, stbl
+ *  - AVI RIFF §: LIST hdrl, idx1
+ */
+
+export class Container {
+  /**
+   * @param {object} params
+   * @param {(start:number,end:number)=>Promise<Buffer|null>} params.readRange
+   * @param {number} params.fileSize
+   * @param {string} [params.label]
+   */
+  constructor({ readRange, fileSize, label = "" }) {
+    this.readRange = readRange;
+    this.fileSize = fileSize;
+    this.label = label;
+  }
+
+  /** @returns {string} Human name: "matroska" | "mp4" | "avi" | "unknown" */
+  get formatName() {
+    return "unknown";
+  }
+
+  /** Whether `head` (first bytes) looks like this container. */
+  static detect(_head) {
+    return false;
+  }
+
+  /**
+   * All tracks declared by the container, in container order.
+   * Includes disabled tracks (isEnabled=false) to preserve declaredIndex alignment with ffmpeg.
+   * @returns {Promise<import("../tracks/index.js").ContainerTrack[]>}
+   */
+  async readTracks() {
+    throw new Error("readTracks not implemented");
+  }
+
+  /**
+   * Keyframe times for the video track, ascending seconds. Null when index absent (MPEG-TS, fragmented MP4, truncated).
+   * @returns {Promise<{times:number[],tolerance:number}|null>}
+   */
+  async readKeyframeIndex() {
+    return null;
+  }
+
+  /**
+   * Subtitle-specific: where cues live (Matroska cluster positions or MP4 sample ranges).
+   * Returned via track objects' clusterPositions/samples, so base has no extra method — tracks carry it.
+   */
+}

package/services/container/ContainerFactory.js

@@ -0,0 +1,31 @@
+/**
+ * @file Container factory — detects format and returns the precise Container subclass.
+ *
+ * Sniffs first 16 bytes (same as container-index/index.js) and instantiates
+ * MatroskaContainer / Mp4Container / AviContainer. Falls back to null (unknown).
+ * Orchestrators depend on this, not on concrete constructors.
+ */
+
+import { MatroskaContainer } from "./MatroskaContainer.js";
+import { Mp4Container } from "./Mp4Container.js";
+import { AviContainer } from "./AviContainer.js";
+
+const SNIFF_BYTES = 16;
+
+export class ContainerFactory {
+  /**
+   * @param {(start:number,end:number)=>Promise<Buffer|null>} readRange
+   * @param {number} fileSize
+   * @param {string} label
+   * @returns {Promise<import("./Container.js").Container|null>}
+   */
+  static async create({ readRange, fileSize, label = "" }) {
+    if (typeof readRange !== "function" || !Number.isFinite(fileSize) || fileSize <= 0) return null;
+    const head = await readRange(0, Math.min(SNIFF_BYTES - 1, fileSize - 1));
+    if (!head) return null;
+    if (MatroskaContainer.detect(head)) return new MatroskaContainer({ readRange, fileSize, label });
+    if (Mp4Container.detect(head)) return new Mp4Container({ readRange, fileSize, label });
+    if (AviContainer.detect(head)) return new AviContainer({ readRange, fileSize, label });
+    return null;
+  }
+}