@torrent-tv/proxy 2.74.0 → 2.74.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 2.74.1
+
+- **Chore**: The subtitle path chose a container twice, from two different kinds of evidence, and the two had to agree. Once by file extension, to decide which class to build; once by whether a track carried a sample list, to decide how to read its cues. Nothing enforced the agreement — a `.mkv` whose track somehow carried samples would have called a method Matroska does not have. There is one choice now and it is made from the BYTES: `ContainerFactory` sniffs the header, because that is what the muxer wrote while a name is what somebody typed, and only where the head is not downloaded — the cue walk asks the swarm for nothing — does the name answer instead. `Container.readHeldCues(plan, track, progress)` is then the one question: Matroska walks the clusters its Cues table names and fills every track from one walk, an MP4 reads the samples its own table states, and the caller chooses between them nowhere.
+- **Chore**: A subtitle plan has one shape whichever container answers it. `Mp4Container` used to hand back its own raw table for the caller to reshape, inside the branch that has now gone; it returns the common shape itself, and says in its own words why `declared` is empty for an MP4 — the format has no element meaning "show this subtitle track by default", so nothing is shown unasked.
+- **Chore**: `ContainerFactory.create` passes its parameters through whole, so a caller with a torrent's two readers gets a container that has both instead of one built with the fetching reader only.
+
 ## 2.74.0
 
 - **Chore**: Everything about subtitles is now in the classes that own it, and six loose modules are gone. `matroska-subtitles.js`, `matroska-blocks.js` and `mp4-subtitles.js` were a container's own specification written outside the container: the track table, the Cues, the blocks inside a cluster, the sample table. They are `MatroskaContainer` and `Mp4Container` now. `subtitle-markup.js` and the cue half of `subtitle-convert.js` were a codec's own rules written outside the track — which markup a codec carries, how to take it off, how to write the cues out as WebVTT — and are `TextSubtitleTrack`. Reading a subtitle FILE is `SubtitleFileContainer`, and reconciling ffmpeg's banner with a container's own table (`subtitle-defaults.js`) is `Container`. Folding them in exposed the duplication that having two homes had allowed: one Matroska helper and three MP4 box helpers existed twice over, with different parameter names and the same behaviour, and twenty-two element-id constants were declared in both places — checked pair by pair for disagreement before the second copy was dropped, and there was none.

package/package.json

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

package/services/container/Container.js

@@ -114,6 +114,52 @@ export class Container {
     throw new Error("readTracks not implemented");
   }
 
+
+  /**
+   * This container's subtitle tracks and where their cues are, in ONE shape
+   * whichever container answers.
+   *
+   * `tracks` carries a `clusterPositions` list for a container that stores cues
+   * in clusters and a `samples` list for one that states each cue's own byte
+   * range; a caller reads neither, and asks {@link Container#readHeldCues}
+   * instead. `declared` is what the container says about its subtitle tracks in
+   * its own order, and empty means the container said nothing — a real answer,
+   * not a missing one.
+   *
+   * @returns {Promise<{ tracks: object[], declared: object[], secondsPerTick: number, segmentDataOffset: number } | null>}
+   *   Null where this container declares no subtitles at all.
+   */
+  async readSubtitlePlan() {
+    return null;
+  }
+
+  /**
+   * The cues this container can read RIGHT NOW for one track, without fetching.
+   *
+   * Every container answers this, and each reads what its own specification
+   * says: Matroska walks the clusters its Cues table names, an MP4 reads the
+   * samples its table states. The caller therefore chooses a container once —
+   * from the bytes — and never again. It used to choose twice, once by file
+   * extension for the container and once by whether a track carried a sample
+   * list for the reading, and two choices that must agree and are made from
+   * different evidence are a disagreement waiting to happen.
+   *
+   * `progress` is what has already been read, kept by the caller because it
+   * belongs to the file rather than to one pass: `walked` holds cluster
+   * positions, `harvested` holds sample offsets per track. Each container adds
+   * to the one it uses.
+   *
+   * @param {object} _plan - This file's subtitle plan.
+   * @param {object} _track - The track asked about.
+   * @param {{ walked: Set<number>, harvested: Map<number, Set<number>> }} _progress
+   * @returns {Promise<{ found: Map<number, object[]>, covered: number, indexed: number }>}
+   *   `found` is track number to the cues found in THIS pass — Matroska fills
+   *   every track from one walk, so it is a map and not a list.
+   */
+  async readHeldCues(_plan, _track, _progress) {
+    return { found: new Map(), covered: 0, indexed: 0 };
+  }
+
   /**
    * Keyframe times for the video track, ascending seconds. Null when index absent (MPEG-TS, fragmented MP4, truncated).
    * @returns {Promise<{times:number[],tolerance:number}|null>}

package/services/container/ContainerFactory.js

@@ -1,31 +1,55 @@
-/**
- * @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;
-  }
-}
+/**
+ * @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 {
+  /**
+   * The container these bytes are, built over them.
+   *
+   * `params` is passed through whole, so a caller with a torrent's two readers
+   * gets a container that has both — see {@link Container}'s constructor.
+   *
+   * @param {{ readRange: (start:number,end:number)=>Promise<Buffer|null>, fileSize: number, label?: string, readHeld?: Function, isHeld?: Function }} params
+   * @returns {Promise<import("./Container.js").Container|null>}
+   */
+  static async create(params) {
+    const { readRange, fileSize } = params;
+    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(params);
+    if (Mp4Container.detect(head)) return new Mp4Container(params);
+    if (AviContainer.detect(head)) return new AviContainer(params);
+    return null;
+  }
+
+  /**
+   * The container a file NAME suggests, for the moment the bytes cannot be
+   * sniffed.
+   *
+   * The head of a file nobody has opened is not downloaded, and the cue walk
+   * asks the swarm for nothing — so on that one path the name is all there is.
+   * It is a fallback and never a preference: the bytes decide wherever they can
+   * be read, because a name is what somebody typed and a header is what the
+   * muxer wrote.
+   *
+   * @param {string} name
+   * @returns {typeof MatroskaContainer | typeof Mp4Container | null}
+   */
+  static byName(name) {
+    const text = String(name ?? "");
+    if (/\.(mp4|m4v|m4a)$/i.test(text)) return Mp4Container;
+    if (/\.(mkv|mka|webm)$/i.test(text)) return MatroskaContainer;
+    return null;
+  }
+}

package/services/container/MatroskaContainer.js

@@ -344,6 +344,17 @@ export class MatroskaContainer extends Container {
    * @returns {Promise<Map<number, {startSeconds: number, endSeconds: number|null, text: string}[]>>}
    *   Track number to the cues found in THIS pass.
    */
+  async readHeldCues(plan, track, progress) {
+    const found = await this.walkHeldClusters(plan, progress.walked);
+    return {
+      found,
+      // Every track is filled by the same walk, so this is a fact about the
+      // FILE and reads the same whichever track asked.
+      covered: progress.walked.size,
+      indexed: track?.clusterPositions?.length ?? 0
+    };
+  }
+
   async walkHeldClusters(plan, walked) {
     /** @type {Map<number, object[]>} */
     const found = new Map();

package/services/container/Mp4Container.js

@@ -118,8 +118,34 @@ export class Mp4Container extends Container {
    *
    * @returns {Promise<object|null>}
    */
-  readSubtitlePlan() {
-    return Mp4Container.readSubtitlePlan(this.readRange, this.fileSize);
+  async readSubtitlePlan() {
+    const plan = await Mp4Container.readSubtitlePlan(this.readRange, this.fileSize);
+    if (!plan) {
+      return null;
+    }
+    // An MP4 states every sample's byte range in its own table, so a cue costs
+    // its own few dozen bytes rather than the cluster around it — which is why
+    // there are `samples` here and no `clusterPositions`.
+    //
+    // An MP4 has no element meaning "show this subtitle track by default", so
+    // `declared` is empty: the container states nothing, and nothing is shown
+    // unasked.
+    return {
+      tracks: plan.tracks.map((track, order) => ({
+        trackNumber: track.trackId,
+        declaredIndex: Number.isInteger(track.declaredIndex) ? track.declaredIndex : order,
+        codecId: track.format,
+        language: track.language,
+        name: "",
+        isDefault: order === 0,
+        codecPrivate: "",
+        clusterPositions: [],
+        samples: track.samples
+      })),
+      declared: [],
+      secondsPerTick: 0.001,
+      segmentDataOffset: 0
+    };
   }
 
 
@@ -138,6 +164,20 @@ export class Mp4Container extends Container {
    * @returns {Promise<{startSeconds: number, endSeconds: number, text: string}[]>}
    *   The cues found in THIS pass.
    */
+  async readHeldCues(_plan, track, progress) {
+    let harvested = progress.harvested.get(track.trackNumber);
+    if (!harvested) {
+      harvested = new Set();
+      progress.harvested.set(track.trackNumber, harvested);
+    }
+    const cues = await this.readHeldSamples(track, harvested);
+    return {
+      found: cues.length > 0 ? new Map([[track.trackNumber, cues]]) : new Map(),
+      covered: harvested.size,
+      indexed: track?.samples?.length ?? 0
+    };
+  }
+
   async readHeldSamples(track, harvested) {
     const found = [];
     for (const sample of track?.samples ?? []) {

package/services/torrent-worker/subtitle-cues.js

@@ -17,8 +17,7 @@
  * Reading the clusters costs nothing extra at all.
  */
 
-import { MatroskaContainer } from "../container/MatroskaContainer.js";
-import { Mp4Container } from "../container/Mp4Container.js";
+import { ContainerFactory } from "../container/ContainerFactory.js";
 import { TextSubtitleTrack } from "../tracks/TextSubtitleTrack.js";
 import { detectLanguage } from "../language-detect.js";
 import { logger } from "../../utils/logger.js";
@@ -111,18 +110,25 @@ function readHeld(file, start, end) {
 /**
  * A container over one file of a torrent, told how to read it.
  *
- * The container is given two functions and never the torrent: whether a byte
- * range is already downloaded, and how to read one without asking the swarm for
- * anything. That is the whole of what this layer knows that the container does
- * not, and reducing it to two functions is what lets the reading itself live
- * where the format is specified.
+ * The container is given two readers and a predicate and never the torrent:
+ * whether a byte range is already downloaded, how to read one without asking
+ * the swarm, and how to read one that may need fetching. That is the whole of
+ * what this layer knows and the container does not.
  *
+ * WHICH container is decided from the bytes, by the factory's sniff — the
+ * header is what the muxer wrote, and a file name is what somebody typed. Only
+ * where the head is not downloaded, and so cannot be sniffed without asking the
+ * swarm, does the name answer instead. One choice either way: the caller never
+ * decides a second time from a track's shape, which is two decisions from
+ * different evidence that have to agree.
+ *
+ * @param {object} state - This file's state; the container is kept on it.
  * @param {object} torrent
  * @param {object} file
- * @returns {MatroskaContainer | Mp4Container}
+ * @returns {Promise<import("../container/Container.js").Container | null>}
  */
-function containerOver(state, torrent, file) {
-  if (state.container) {
+async function containerOver(state, torrent, file) {
+  if (state.container !== null) {
     return state.container;
   }
   const held = async (start, end) => readHeld(file, start, Math.min(end, file.length - 1));
@@ -133,8 +139,13 @@ function containerOver(state, torrent, file) {
     fileSize: file.length,
     label: String(file.name ?? "")
   };
-  const name = String(file.name ?? "");
-  state.container = /\.(mp4|m4v)$/i.test(name) ? new Mp4Container(params) : new MatroskaContainer(params);
+  const sniffed = await ContainerFactory.create(params);
+  if (sniffed) {
+    state.container = sniffed;
+    return state.container;
+  }
+  const ByName = ContainerFactory.byName(file.name);
+  state.container = ByName ? new ByName(params) : null;
   return state.container;
 }
 
@@ -251,33 +262,8 @@ async function readPlan(torrent, fileIndex, state) {
     state.plan = empty;
     return state.plan;
   }
-  const container = containerOver(state, torrent, file);
-  const name = String(file.name);
-  if (/\.mp4$/i.test(name) || /\.m4v$/i.test(name)) {
-    // An MP4 states every sample's byte range in its own table, so a cue costs
-    // its own few dozen bytes rather than the cluster around it. The samples
-    // are carried as `clusterPositions` of one byte range each, so the harvest
-    // treats both containers the same way.
-    const mp4 = await container.readSubtitlePlan();
-    state.plan = mp4
-      ? {
-        ...empty,
-        tracks: mp4.tracks.map((track, order) => ({
-          trackNumber: track.trackId,
-          declaredIndex: Number.isInteger(track.declaredIndex) ? track.declaredIndex : order,
-          codecId: track.format,
-          language: track.language,
-          name: "",
-          isDefault: order === 0,
-          codecPrivate: "",
-          clusterPositions: [],
-          samples: track.samples
-        }))
-      }
-      : empty;
-    return state.plan;
-  }
-  if (!/\.mkv$/i.test(name) && !/\.webm$/i.test(name)) {
+  const container = await containerOver(state, torrent, file);
+  if (!container) {
     state.plan = empty;
     return state.plan;
   }
@@ -372,52 +358,33 @@ export async function cuesHeldFor(torrent, fileIndex, sourceKey, trackNumber) {
  */
 async function walkFor(torrent, fileIndex, state, plan, track, trackNumber) {
   const file = torrent.files[fileIndex];
-  const container = containerOver(state, torrent, file);
-  const cuesOf = (number) => {
-    let held = state.cues.get(number);
-    if (!held) {
-      held = [];
-      state.cues.set(number, held);
-    }
-    return held;
-  };
-
-  if (Array.isArray(track.samples)) {
-    // An MP4 states every cue's byte range, so the container reads per sample.
-    let harvested = state.harvested.get(trackNumber);
-    if (!harvested) {
-      harvested = new Set();
-      state.harvested.set(trackNumber, harvested);
-    }
-    const cues = cuesOf(trackNumber);
-    for (const cue of await container.readHeldSamples(track, harvested)) {
-      cues.push({ ...cue, seq: nextSeq(state, trackNumber) });
-    }
-    cues.sort((left, right) => left.startSeconds - right.startSeconds);
-    return {
-      cues,
-      coveredClusters: harvested.size,
-      indexedClusters: track.samples.length,
-      track
-    };
+  const container = await containerOver(state, torrent, file);
+  if (!container) {
+    return { cues: [], coveredClusters: 0, indexedClusters: 0, track };
   }
 
-  // Matroska: one walk of the file fills every track, because a cluster carries
-  // the blocks of every track that has anything to say over its span.
-  const found = await container.walkHeldClusters(plan, state.walked);
+  // One question, whichever container this is. Matroska walks the clusters its
+  // Cues table names and fills every track from one walk; an MP4 reads the
+  // samples its own table states for this track. Nothing here chooses between
+  // them, which is the point: the container was chosen once, from the bytes.
+  const { found, covered, indexed } = await container.readHeldCues(plan, track, state);
+
   for (const [number, cues] of found) {
-    const into = cuesOf(number);
+    let into = state.cues.get(number);
+    if (!into) {
+      into = [];
+      state.cues.set(number, into);
+    }
     for (const cue of cues) {
       into.push({ ...cue, seq: nextSeq(state, number) });
     }
     into.sort((left, right) => left.startSeconds - right.startSeconds);
   }
+
   return {
     cues: state.cues.get(trackNumber) ?? [],
-    // Every track is filled by the same walk, so this is a fact about the FILE
-    // and reads the same whichever track asked.
-    coveredClusters: state.walked.size,
-    indexedClusters: track.clusterPositions.length,
+    coveredClusters: covered,
+    indexedClusters: indexed,
     track
   };
 }