@torrent-tv/proxy 2.63.0 → 2.64.1

package/services/container/MatroskaContainer.js

@@ -0,0 +1,289 @@
+/**
+ * @file Matroska/WebM container — RFC 9559.
+ *
+ * Reads Tracks in one pass for all media types (video, audio, subtitle).
+ * Implements spec-accurate flag handling:
+ *  - FlagEnabled 0xB9 default 1, zero-length element = default (not disabled)
+ *  - FlagDefault 0x88 default 1, declaresDefault tracks whether element was written
+ *  - FlagForced 0x55AA only for subtitles, FlagHearingImpaired 0x55AB, FlagVisualImpaired 0x55AC,
+ *    FlagTextDescriptions 0x55AD, FlagOriginal 0x55AE, FlagCommentary 0x55AF
+ *  - Language 0x22B59C default "eng", LanguageBCP47 0x22B59D MUST — when present, Language ignored
+ *  - CodecID 0x86, CodecPrivate 0x63A2, Name 0x536E, TrackType 0x83 (1 video, 2 audio, 17 subtitle)
+ *
+ * Delegates low-level Cues/cluster and keyframe work to existing readers
+ * (ebml-reader, matroska.js, matroska-subtitles.js) but centralizes the single Tracks walk.
+ */
+
+import { Container } from "./Container.js";
+import { isMatroska, readMatroskaKeyframeTimes } from "../container-index/matroska.js";
+import { readSubtitlePlan } from "../container-index/matroska-subtitles.js";
+import { VideoTrack } from "../tracks/VideoTrack.js";
+import { AudioTrack } from "../tracks/AudioTrack.js";
+import { TextSubtitleTrack, TEXT_CODECS_MATROSKA } from "../tracks/TextSubtitleTrack.js";
+import { ImageSubtitleTrack } from "../tracks/ImageSubtitleTrack.js";
+import { ContainerTrack } from "../tracks/ContainerTrack.js";
+import { findElement, iterateElements, readUint } from "../container-index/ebml-reader.js";
+
+const HEAD_BYTES = 64 * 1024;
+const ID_TRACKS = 0x1654ae6b;
+const ID_TRACK_ENTRY = 0xae;
+const ID_TRACK_NUMBER = 0xd7;
+const ID_TRACK_TYPE = 0x83;
+const ID_FLAG_ENABLED = 0xb9;
+const ID_FLAG_DEFAULT = 0x88;
+const ID_FLAG_FORCED = 0x55aa;
+const ID_FLAG_HEARING = 0x55ab;
+const ID_FLAG_VISUAL = 0x55ac;
+const ID_FLAG_TEXT_DESCR = 0x55ad;
+const ID_FLAG_ORIGINAL = 0x55ae;
+const ID_FLAG_COMMENTARY = 0x55af;
+const ID_CODEC_ID = 0x86;
+const ID_CODEC_PRIVATE = 0x63a2;
+const ID_LANGUAGE = 0x22b59c;
+const ID_LANGUAGE_BCP47 = 0x22b59d;
+const ID_NAME = 0x536e;
+const ID_VIDEO = 0xe0;
+const ID_AUDIO = 0xe1;
+const ID_PIXEL_WIDTH = 0xb0;
+const ID_PIXEL_HEIGHT = 0xba;
+const ID_DISPLAY_WIDTH = 0x54b0;
+const ID_DISPLAY_HEIGHT = 0x54ba;
+const ID_SAMPLING_FREQUENCY = 0xb5;
+const ID_CHANNELS = 0x9f;
+
+function readString(buf, el) {
+  return buf.toString("utf8", el.dataOffset, el.dataOffset + el.size).replace(/\0+$/, "");
+}
+
+export class MatroskaContainer extends Container {
+  get formatName() {
+    return "matroska";
+  }
+
+  static detect(head) {
+    return isMatroska(head);
+  }
+
+  async readTracks() {
+    const head = await this.readRange(0, Math.min(HEAD_BYTES - 1, this.fileSize - 1));
+    if (!head || !isMatroska(head)) return [];
+
+    // Delegate to subtitle plan reader for subtitle tracks (already handles Flags spec-correct),
+    // but we need video/audio tracks too. Do a dedicated Tracks walk here for all types,
+    // then merge subtitle detail (clusterPositions, declaresDefault etc.) from the plan.
+    const seg = findElement(head, 0x18538067, []);
+    if (!seg) return [];
+    const tracksEl = findElement(head, ID_TRACKS, [], seg.dataOffset);
+    if (!tracksEl) return [];
+
+    const tracksEnd = Math.min(head.length, tracksEl.dataOffset + tracksEl.size);
+    /** @type {import("../tracks/index.js").ContainerTrack[]} */
+    const result = [];
+    // Subtitle declaredIndex is position among subtitle tracks, not global — track per-type counters.
+    let subtitleDeclaredIndex = -1;
+    let audioDeclaredIndex = -1;
+    let videoDeclaredIndex = -1;
+
+    // For subtitle flag enrichment, read the existing plan (it already does Cues walk)
+    let subtitlePlan = null;
+    try {
+      const shim = async (s, e) => this.readRange(s, Math.min(e, this.fileSize - 1));
+      subtitlePlan = await readSubtitlePlan(shim, this.fileSize);
+    } catch {
+      subtitlePlan = null;
+    }
+    const declaredByNumber = new Map();
+    const planTracksByNumber = new Map();
+    if (subtitlePlan?.declared) {
+      for (const d of subtitlePlan.declared) declaredByNumber.set(d.trackNumber, d);
+    }
+    if (subtitlePlan?.tracks) {
+      for (const t of subtitlePlan.tracks) planTracksByNumber.set(t.trackNumber, t);
+    }
+
+    for (const entry of iterateElements(head, tracksEl.dataOffset, tracksEnd)) {
+      if (entry.id !== ID_TRACK_ENTRY) continue;
+      const entryEnd = Math.min(tracksEnd, entry.dataOffset + entry.size);
+      let trackNumber = null;
+      let typeNum = null;
+      let codecId = "";
+      let language = "";
+      let languageBcp47 = "";
+      let name = "";
+      let codecPrivateB64 = "";
+      let isEnabled = true;
+      let isDefault = true;
+      let declaresDefault = false;
+      let isForced = false;
+      let isHearing = false;
+      let isVisual = false;
+      let isOriginal = false;
+      let isCommentary = false;
+      let pixelWidth = null;
+      let pixelHeight = null;
+      let displayWidth = null;
+      let displayHeight = null;
+      let samplingFreq = null;
+      let channels = null;
+
+      for (const f of iterateElements(head, entry.dataOffset, entryEnd)) {
+        switch (f.id) {
+          case ID_TRACK_NUMBER: trackNumber = readUint(head, f.dataOffset, f.size); break;
+          case ID_TRACK_TYPE: typeNum = readUint(head, f.dataOffset, f.size); break;
+          case ID_CODEC_ID: codecId = readString(head, f); break;
+          case ID_CODEC_PRIVATE: codecPrivateB64 = head.toString("base64", f.dataOffset, f.dataOffset + f.size); break;
+          case ID_LANGUAGE: language = readString(head, f); break;
+          case ID_LANGUAGE_BCP47: languageBcp47 = readString(head, f); break;
+          case ID_NAME: name = readString(head, f); break;
+          case ID_FLAG_ENABLED: isEnabled = f.size === 0 || readUint(head, f.dataOffset, f.size) !== 0; break;
+          case ID_FLAG_DEFAULT: isDefault = f.size === 0 || readUint(head, f.dataOffset, f.size) === 1; declaresDefault = true; break;
+          case ID_FLAG_FORCED: isForced = f.size > 0 && readUint(head, f.dataOffset, f.size) !== 0; break;
+          case ID_FLAG_HEARING: isHearing = f.size > 0 && readUint(head, f.dataOffset, f.size) !== 0; break;
+          case ID_FLAG_VISUAL: isVisual = f.size > 0 && readUint(head, f.dataOffset, f.size) !== 0; break;
+          case ID_FLAG_TEXT_DESCR: break;
+          case ID_FLAG_ORIGINAL: isOriginal = f.size > 0 && readUint(head, f.dataOffset, f.size) !== 0; break;
+          case ID_FLAG_COMMENTARY: isCommentary = f.size > 0 && readUint(head, f.dataOffset, f.size) !== 0; break;
+          default: break;
+        }
+        // Video/Audio sub-elements are nested, not at entry level — read separately below.
+      }
+      if (trackNumber === null) continue;
+
+      // Parse Video/Audio sub-elements if present
+      const videoEl = findElement(head, ID_VIDEO, [], entry.dataOffset, entryEnd);
+      if (videoEl) {
+        for (const vf of iterateElements(head, videoEl.dataOffset, Math.min(entryEnd, videoEl.dataOffset + videoEl.size))) {
+          if (vf.id === ID_PIXEL_WIDTH) pixelWidth = readUint(head, vf.dataOffset, vf.size);
+          else if (vf.id === ID_PIXEL_HEIGHT) pixelHeight = readUint(head, vf.dataOffset, vf.size);
+          else if (vf.id === ID_DISPLAY_WIDTH) displayWidth = readUint(head, vf.dataOffset, vf.size);
+          else if (vf.id === ID_DISPLAY_HEIGHT) displayHeight = readUint(head, vf.dataOffset, vf.size);
+        }
+      }
+      const audioEl = findElement(head, ID_AUDIO, [], entry.dataOffset, entryEnd);
+      if (audioEl) {
+        for (const af of iterateElements(head, audioEl.dataOffset, Math.min(entryEnd, audioEl.dataOffset + audioEl.size))) {
+          if (af.id === ID_SAMPLING_FREQUENCY) {
+            // SamplingFrequency is float64
+            if (af.size === 8) samplingFreq = head.readDoubleBE(af.dataOffset);
+            else samplingFreq = readUint(head, af.dataOffset, af.size);
+          } else if (af.id === ID_CHANNELS) channels = readUint(head, af.dataOffset, af.size);
+        }
+      }
+
+      // RFC 9559 LanguageBCP47 MUST — when present, Language ignored
+      const resolvedLang = languageBcp47 || language;
+      const bcpTag = languageBcp47;
+
+      if (typeNum === 1) {
+        videoDeclaredIndex += 1;
+        result.push(new VideoTrack({
+          trackNumber,
+          declaredIndex: videoDeclaredIndex,
+          codecId,
+          language: resolvedLang,
+          languageBcp47: bcpTag,
+          name,
+          isEnabled,
+          isDefault,
+          declaresDefault,
+          codecPrivateB64,
+          width: pixelWidth,
+          height: pixelHeight,
+          displayWidth,
+          displayHeight
+        }));
+      } else if (typeNum === 2) {
+        audioDeclaredIndex += 1;
+        result.push(new AudioTrack({
+          trackNumber,
+          declaredIndex: audioDeclaredIndex,
+          codecId,
+          language: resolvedLang,
+          languageBcp47: bcpTag,
+          name,
+          isEnabled,
+          isDefault,
+          declaresDefault,
+          codecPrivateB64,
+          isOriginal,
+          isCommentary,
+          isVisualImpaired: isVisual,
+          channels,
+          samplingFrequency: samplingFreq
+        }));
+      } else if (typeNum === 17) {
+        subtitleDeclaredIndex += 1;
+        // Only Forced/Hearing belong to subtitles; Original/Commentary must not leak.
+        const declared = declaredByNumber.get(trackNumber);
+        const planTrack = planTracksByNumber.get(trackNumber);
+        // Prefer plan's flags when available (already spec-correct), else use parsed.
+        const finalForced = planTrack ? !!planTrack.isForced : isForced;
+        const finalHearing = planTrack ? !!planTrack.isHearingImpaired : isHearing;
+        const finalEnabled = declared ? declared.isEnabled !== false : isEnabled;
+        const finalDefault = declared ? !!declared.isDefault : isDefault;
+        const finalDeclares = declared ? !!declared.declaresDefault : declaresDefault;
+        const clusterPositions = planTrack ? planTrack.clusterPositions ?? [] : [];
+        const isText = TEXT_CODECS_MATROSKA.has(codecId);
+        // disabled image/text tracks still counted (declaredIndex above) — offerable flag controls visibility
+        if (isText && finalEnabled) {
+          result.push(new TextSubtitleTrack({
+            trackNumber,
+            declaredIndex: subtitleDeclaredIndex,
+            codecId,
+            language: resolvedLang,
+            languageBcp47: bcpTag,
+            name,
+            isEnabled: finalEnabled,
+            isDefault: finalDefault,
+            declaresDefault: finalDeclares,
+            codecPrivateB64,
+            isForced: finalForced,
+            isHearingImpaired: finalHearing,
+            clusterPositions
+          }));
+        } else {
+          // Image or disabled — keep declaredIndex, not offerable if disabled
+          const Target = isText ? TextSubtitleTrack : ImageSubtitleTrack;
+          result.push(new Target({
+            trackNumber,
+            declaredIndex: subtitleDeclaredIndex,
+            codecId,
+            language: resolvedLang,
+            languageBcp47: bcpTag,
+            name,
+            isEnabled: finalEnabled,
+            isDefault: finalDefault,
+            declaresDefault: finalDeclares,
+            codecPrivateB64,
+            isForced: finalForced,
+            isHearingImpaired: finalHearing,
+            clusterPositions: isText ? clusterPositions : []
+          }));
+        }
+      } else {
+        // Other TrackType (complex, logo, buttons, control) — keep as generic, not video
+        result.push(new ContainerTrack({
+          trackNumber,
+          declaredIndex: -1,
+          type: "other",
+          codecId,
+          language: resolvedLang,
+          languageBcp47: bcpTag,
+          name,
+          isEnabled,
+          isDefault,
+          declaresDefault,
+          codecPrivateB64
+        }));
+      }
+    }
+    return result;
+  }
+
+  async readKeyframeIndex() {
+    const times = await readMatroskaKeyframeTimes(this.readRange, this.fileSize);
+    if (!times) return null;
+    if (Array.isArray(times)) return { times, tolerance: 0 };
+    return times;
+  }
+}

package/services/container/Mp4Container.js

@@ -0,0 +1,242 @@
+/**
+ * @file MP4/MOV container — ISO/IEC 14496-12.
+ *
+ * Parses moov for all track types in one walk:
+ *  - tkhd: track_ID, flags track_enabled (0x000001), alternate_group, width/height
+ *  - mdhd: timescale, language (packed 5-bit), version handling
+ *  - hdlr: handler_type (vide/soun/text/sbtl/subt/subp/clcp)
+ *  - elng: extendedLanguage BCP47 (when present, replaces mdhd language per spec)
+ *  - stsd: sample entry format (avc1/hev1/mp4a/tx3g/wvtt/stpp)
+ *  - stbl tables for subtitle cue ranges (stts/stsz/stsc/stco/co64) and video keyframes (stss/stts/ctts/elst)
+ *
+ * Delegates keyframe and subtitle sample reading to existing mp4.js / mp4-subtitles.js
+ * but centralizes track creation so FlagEnabled / LanguageBCP47 / alternate_group
+ * are handled once for every media type.
+ */
+
+import { Container } from "./Container.js";
+import { isMp4, readMp4KeyframeTimes } from "../container-index/mp4.js";
+import { readMp4SubtitlePlan } from "../container-index/mp4-subtitles.js";
+import { VideoTrack } from "../tracks/VideoTrack.js";
+import { AudioTrack } from "../tracks/AudioTrack.js";
+import { TextSubtitleTrack, TEXT_FORMATS_MP4 } from "../tracks/TextSubtitleTrack.js";
+import { ImageSubtitleTrack } from "../tracks/ImageSubtitleTrack.js";
+
+export class Mp4Container extends Container {
+  get formatName() {
+    return "mp4";
+  }
+
+  static detect(head) {
+    return isMp4(head);
+  }
+
+  async readTracks() {
+    const head = await this.readRange(0, Math.min(64 - 1, this.fileSize - 1));
+    if (!head || !isMp4(head)) return [];
+
+    // Use the subtitle plan reader's moov parsing as source for subtitle tracks,
+    // and a direct moov walk for video/audio to collect tkhd/mdhd/hdlr/elng uniformly.
+    // For simplicity, delegate entirely to readMp4SubtitlePlan for subtitles and
+    // do a lightweight moov walk for video/audio here — then merge.
+    const subtitlePlan = await readMp4SubtitlePlan(this.readRange, this.fileSize).catch(() => null);
+    const subtitleByDecl = new Map();
+    if (subtitlePlan?.tracks) {
+      for (const t of subtitlePlan.tracks) subtitleByDecl.set(t.declaredIndex, t);
+    }
+
+    // Minimal moov walk for video/audio: reuse isMp4 + findMoov logic by reading via existing helper
+    // Instead of duplicating, parse tracks via a second full moov read that collects vide/soun.
+    // We read moov box directly to extract video/audio tracks.
+    const tracks = await this.#readVideoAudioTracks();
+    // Append subtitle tracks from plan, converting to domain objects
+    if (subtitlePlan?.tracks) {
+      for (const s of subtitlePlan.tracks) {
+        const isText = TEXT_FORMATS_MP4.has(s.format);
+        const Cls = isText ? TextSubtitleTrack : ImageSubtitleTrack;
+        tracks.push(new Cls({
+          trackNumber: s.trackId,
+          declaredIndex: s.declaredIndex,
+          codecId: s.format,
+          language: s.language,
+          languageBcp47: "",
+          name: "",
+          isEnabled: true,
+          isDefault: s.declaredIndex === 0,
+          declaresDefault: false,
+          codecPrivateB64: "",
+          isForced: false,
+          isHearingImpaired: false,
+          clusterPositions: [],
+          samples: s.samples
+        }));
+      }
+      // Count non-text subtitle handlers (subp/clcp/stpp) for declaredIndex correctness — they are already
+      // accounted for in subtitlePlan's declaredIndex via SUBTITLE_HANDLERS, but we didn't create objects for
+      // them above when they were stpp (non-text not in plan's tracks). The plan already excludes stpp from tracks
+      // but increments declaredIndex, so alignment holds: we don't need extra placeholders.
+    }
+    return tracks;
+  }
+
+  async #readVideoAudioTracks() {
+    // Lightweight: scan moov for trak with hdlr vide/soun. We reuse readMp4SubtitlePlan's findMoov
+    // by reimplementing a minimal header walk here.
+    const PROBE = 64;
+    const MAX_MOOV = 32 * 1024 * 1024;
+    // find moov offset
+    let at = 0;
+    let moovBox = null;
+    while (at < this.fileSize) {
+      const probe = await this.readRange(at, Math.min(this.fileSize - 1, at + PROBE - 1));
+      if (!probe || probe.length < 8) break;
+      let size = probe.readUInt32BE(0);
+      const type = probe.toString("latin1", 4, 8);
+      let header = 8;
+      if (size === 1) {
+        if (probe.length < 16) break;
+        size = Number(probe.readBigUInt64BE(8));
+        header = 16;
+      }
+      if (size <= 0) break;
+      if (type === "moov") { moovBox = { offset: at, size, header }; break; }
+      at += size;
+    }
+    if (!moovBox || moovBox.size > MAX_MOOV) return [];
+    const moov = await this.readRange(moovBox.offset, Math.min(this.fileSize - 1, moovBox.offset + moovBox.size - 1));
+    if (!moov) return [];
+
+    const result = [];
+    let videoIdx = -1;
+    let audioIdx = -1;
+    // iterate trak boxes inside moov
+    const readBox = (buf, off) => {
+      if (off + 8 > buf.length) return null;
+      let sz = buf.readUInt32BE(off);
+      const tp = buf.toString("latin1", off + 4, off + 8);
+      let hb = 8;
+      if (sz === 1) { if (off + 16 > buf.length) return null; sz = Number(buf.readBigUInt64BE(off + 8)); hb = 16; }
+      if (sz < hb) return null;
+      return { type: tp, size: sz, dataOffset: off + hb, end: off + sz };
+    };
+    const childrenOf = (buf, start, end, type) => {
+      const out = [];
+      let p = start;
+      while (p + 8 <= end) {
+        const b = readBox(buf, p);
+        if (!b) break;
+        if (b.type === type) out.push(b);
+        p = b.end;
+      }
+      return out;
+    };
+    const childOf = (buf, s, e, t) => childrenOf(buf, s, e, t)[0] ?? null;
+
+    const moovContentStart = moovBox.header;
+    const moovEnd = moov.length;
+    for (const trak of childrenOf(moov, moovContentStart, moovEnd, "trak")) {
+      const mdia = childOf(moov, trak.dataOffset, trak.end, "mdia");
+      if (!mdia) continue;
+      const hdlr = childOf(moov, mdia.dataOffset, mdia.end, "hdlr");
+      const handler = hdlr ? moov.toString("latin1", hdlr.dataOffset + 8, hdlr.dataOffset + 12) : "";
+      const mdhd = childOf(moov, mdia.dataOffset, mdia.end, "mdhd");
+      const tkhd = childOf(moov, trak.dataOffset, trak.end, "tkhd");
+      let language = "";
+      if (mdhd) {
+        const ver = moov[mdhd.dataOffset];
+        const langAt = ver === 1 ? mdhd.dataOffset + 32 : mdhd.dataOffset + 20;
+        if (langAt + 2 <= mdhd.end) {
+          const packed = moov.readUInt16BE(langAt);
+          language = [10, 5, 0].map((s) => String.fromCharCode(((packed >> s) & 0x1f) + 0x60)).join("").replace(/[^a-z]/g, "");
+        }
+      }
+      // elng overrides mdhd language per spec §8.4.6
+      let languageBcp47 = "";
+      const elng = childOf(moov, mdia.dataOffset, mdia.end, "elng");
+      if (elng && elng.end - elng.dataOffset >= 4) {
+        languageBcp47 = moov.toString("utf8", elng.dataOffset + 4, elng.end).replace(/\0+$/, "");
+      }
+      let trackId = 0;
+      let isEnabled = true;
+      let alternateGroup = 0;
+      let width = null;
+      let height = null;
+      if (tkhd) {
+        const ver = moov[tkhd.dataOffset];
+        const flags = moov.readUInt32BE(tkhd.dataOffset + 1) & 0xffffff; // 3 bytes after version
+        isEnabled = (flags & 0x000001) !== 0;
+        trackId = moov.readUInt32BE(ver === 1 ? tkhd.dataOffset + 20 : tkhd.dataOffset + 12);
+        alternateGroup = moov.readUInt16BE(ver === 1 ? tkhd.dataOffset + 26 : tkhd.dataOffset + 18);
+        // width/height are 16.16 fixed point at end of tkhd
+        if (tkhd.end - tkhd.dataOffset >= 84) {
+          const w = moov.readUInt32BE(ver === 1 ? tkhd.dataOffset + 76 : tkhd.dataOffset + 68);
+          const h = moov.readUInt32BE(ver === 1 ? tkhd.dataOffset + 80 : tkhd.dataOffset + 72);
+          width = w / 65536;
+          height = h / 65536;
+        }
+      }
+      const resolvedLang = languageBcp47 || language;
+      if (handler === "vide") {
+        videoIdx += 1;
+        // stsd format for codecId
+        let codecId = "";
+        const minf = childOf(moov, mdia.dataOffset, mdia.end, "minf");
+        const stbl = minf && childOf(moov, minf.dataOffset, minf.end, "stbl");
+        const stsd = stbl && childOf(moov, stbl.dataOffset, stbl.end, "stsd");
+        if (stsd) {
+          const first = readBox(moov, stsd.dataOffset + 8);
+          if (first) codecId = first.type;
+        }
+        result.push(new VideoTrack({
+          trackNumber: trackId,
+          declaredIndex: videoIdx,
+          codecId,
+          language: resolvedLang,
+          languageBcp47,
+          name: "",
+          isEnabled,
+          isDefault: true,
+          declaresDefault: false,
+          codecPrivateB64: "",
+          alternateGroup,
+          width,
+          height
+        }));
+      } else if (handler === "soun") {
+        audioIdx += 1;
+        let codecId = "";
+        const minf = childOf(moov, mdia.dataOffset, mdia.end, "minf");
+        const stbl = minf && childOf(moov, minf.dataOffset, minf.end, "stbl");
+        const stsd = stbl && childOf(moov, stbl.dataOffset, stbl.end, "stsd");
+        if (stsd) {
+          const first = readBox(moov, stsd.dataOffset + 8);
+          if (first) codecId = first.type;
+        }
+        result.push(new AudioTrack({
+          trackNumber: trackId,
+          declaredIndex: audioIdx,
+          codecId,
+          language: resolvedLang,
+          languageBcp47,
+          name: "",
+          isEnabled,
+          isDefault: true,
+          declaresDefault: false,
+          codecPrivateB64: "",
+          alternateGroup,
+          isOriginal: false,
+          isCommentary: false,
+          isVisualImpaired: false
+        }));
+      }
+    }
+    return result;
+  }
+
+  async readKeyframeIndex() {
+    const r = await readMp4KeyframeTimes(this.readRange, this.fileSize);
+    if (!r) return null;
+    if (Array.isArray(r)) return { times: r, tolerance: 0 };
+    return r;
+  }
+}

package/services/container/index.js

@@ -0,0 +1,5 @@
+export { Container } from "./Container.js";
+export { MatroskaContainer } from "./MatroskaContainer.js";
+export { Mp4Container } from "./Mp4Container.js";
+export { AviContainer } from "./AviContainer.js";
+export { ContainerFactory } from "./ContainerFactory.js";

package/services/controllers/PlaybackController.js

@@ -0,0 +1,33 @@
+/**
+ * @file Playback controller — interface layer over playback planning.
+ *
+ * Thin adapter between HTTP/routes and the application orchestrators.
+ * Does not parse containers itself — delegates to containerOrchestrator and
+ * the existing playback-planner service. Exists so routes depend on a
+ * controller contract, not on service internals.
+ */
+
+import { containerOrchestrator } from "../orchestrators/ContainerOrchestrator.js";
+
+export class PlaybackController {
+  /**
+   * @param {object} deps
+   * @param {import("../torrent-pool.js").TorrentPool} deps.torrentPool
+   * @param {ReturnType<import("../../store/source-registry.js").createSourceRegistry>} deps.sourceRegistry
+   * @param {string} deps.ffmpegBin
+   * @param {string} deps.localBaseUrl
+   * @param {ReturnType<import("../playback-planner.js").createPlaybackPlanner>} deps.playbackPlanner
+   */
+  constructor({ torrentPool, sourceRegistry, ffmpegBin, localBaseUrl, playbackPlanner }) {
+    this.torrentPool = torrentPool;
+    this.sourceRegistry = sourceRegistry;
+    this.ffmpegBin = ffmpegBin;
+    this.localBaseUrl = localBaseUrl;
+    this.playbackPlanner = playbackPlanner;
+    this.containers = containerOrchestrator;
+  }
+
+  async getPlan(params) {
+    return this.playbackPlanner.getPlan(params);
+  }
+}