@torrent-tv/proxy 2.41.0 → 2.43.0

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

@@ -0,0 +1,291 @@
+/**
+ * @file Subtitle cues gathered from the clusters a viewer has already brought
+ * in, never from clusters they have not.
+ *
+ * The rule this file exists to keep (stated by the user 2026-08-20): subtitles
+ * arrive the way the picture does, or they are not offered. So nothing here
+ * requests a byte. It looks at what the torrent already holds, reads the
+ * clusters inside it, and returns what it found; the region the viewer is
+ * watching is downloaded before they reach it, so its cues are ready before
+ * they are needed. A region nobody has watched has no cues, and that is
+ * correct — there is nobody to show them to.
+ *
+ * Why not ffmpeg: measured 2026-08-19, extracting one subtitle track of
+ * `Minions.and.Monsters.1080p.mkv` took **752 seconds** and pulled the download
+ * from 2.7 % to 81 % of a 6.5 GB film, because a subtitle stream is sparse and
+ * the demuxer walks the container to the end whatever range is asked of it.
+ * Reading the clusters costs nothing extra at all.
+ */
+
+import { readSubtitlePlan, harvestCluster } from "../container-index/matroska-subtitles.js";
+import { decodeSubtitleSample, readMp4SubtitlePlan } from "../container-index/mp4-subtitles.js";
+import { iterateElements } from "../container-index/ebml-reader.js";
+import { logger } from "../../utils/logger.js";
+
+/** Enough to read any cluster's own element header. */
+const CLUSTER_HEADER_PROBE = 64;
+/**
+ * The largest cluster this will read whole. Real muxers write clusters of a few
+ * megabytes; anything past this is not a cluster boundary we recognised and
+ * reading it would be a large read for nothing.
+ */
+const MAX_CLUSTER_BYTES = 32 * 1024 * 1024;
+
+/** @type {Map<string, { plan: object | null, harvested: Map<number, Set<number>>, cues: Map<number, object[]> }>} */
+const byFile = new Map();
+
+/**
+ * Whether every piece covering a byte range is already downloaded.
+ *
+ * @param {object} torrent
+ * @param {object} file
+ * @param {number} start - Offset within the FILE.
+ * @param {number} end - Inclusive.
+ * @returns {boolean}
+ */
+function rangeIsHeld(torrent, file, start, end) {
+  const pieceLength = Number(torrent?.pieceLength);
+  const offset = Number(file?.offset) || 0;
+  if (!Number.isFinite(pieceLength) || pieceLength <= 0 || !torrent?.bitfield) {
+    return false;
+  }
+  const first = Math.floor((offset + start) / pieceLength);
+  const last = Math.floor((offset + end) / pieceLength);
+  for (let index = first; index <= last; index += 1) {
+    if (!torrent.bitfield.get(index)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Read a byte range of a file straight from the store, without asking the swarm
+ * for anything.
+ *
+ * @param {object} file
+ * @param {number} start
+ * @param {number} end - Inclusive.
+ * @returns {Promise<Buffer | null>}
+ */
+function readHeld(file, start, end) {
+  return new Promise((resolve) => {
+    const chunks = [];
+    let stream;
+    try {
+      stream = file.createReadStream({ start, end });
+    } catch {
+      resolve(null);
+      return;
+    }
+    stream.on("data", (chunk) => chunks.push(chunk));
+    stream.on("end", () => resolve(Buffer.concat(chunks)));
+    stream.on("error", () => resolve(null));
+  });
+}
+
+/**
+ * The subtitle tracks of a file, read once and kept.
+ *
+ * The head and the Cues table are two short reads, and they ARE fetched if
+ * missing — they are kilobytes, they are needed before anything can be offered,
+ * and the codec probe has already pulled the head for every file that plays.
+ *
+ * @param {object} torrent
+ * @param {number} fileIndex
+ * @param {string} key - `sourceKey:fileIndex`.
+ * @returns {Promise<object | null>}
+ */
+async function planFor(torrent, fileIndex, key) {
+  let state = byFile.get(key);
+  if (!state) {
+    state = { plan: null, harvested: new Map(), cues: new Map() };
+    byFile.set(key, state);
+  }
+  if (state.plan !== null) {
+    return state.plan;
+  }
+  const file = torrent?.files?.[fileIndex];
+  const empty = { tracks: [], secondsPerTick: 0.001, segmentDataOffset: 0 };
+  if (!file) {
+    state.plan = empty;
+    return state.plan;
+  }
+  const readRange = async (start, end) => readHeld(file, start, Math.min(end, file.length - 1));
+  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 readMp4SubtitlePlan(readRange, file.length);
+    state.plan = mp4
+      ? {
+        ...empty,
+        tracks: mp4.tracks.map((track, order) => ({
+          trackNumber: track.trackId,
+          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)) {
+    state.plan = empty;
+    return state.plan;
+  }
+  const plan = await readSubtitlePlan(readRange, file.length);
+  state.plan = plan ?? empty;
+  if (state.plan.tracks.length > 0) {
+    logger.info(
+      `subtitles: "${String(file.name).slice(0, 40)}" has ${state.plan.tracks.length} text track(s) — ` +
+      state.plan.tracks
+        .map((track) => `${track.trackNumber}:${track.language || "?"}${track.name ? `/${track.name}` : ""}` +
+          `(${track.clusterPositions.length} indexed)`)
+        .join(" ")
+    );
+  }
+  return state.plan;
+}
+
+/**
+ * Every cue of one track that can be read from what is already downloaded.
+ *
+ * @param {object} torrent
+ * @param {number} fileIndex
+ * @param {string} sourceKey
+ * @param {number} trackNumber
+ * @returns {Promise<{ cues: object[], coveredClusters: number, indexedClusters: number, track: object | null }>}
+ */
+export async function cuesHeldFor(torrent, fileIndex, sourceKey, trackNumber) {
+  const key = `${sourceKey}:${fileIndex}`;
+  const plan = await planFor(torrent, fileIndex, key);
+  const state = byFile.get(key);
+  const track = plan?.tracks?.find((candidate) => candidate.trackNumber === trackNumber) ?? null;
+  if (!track) {
+    return { cues: [], coveredClusters: 0, indexedClusters: 0, track: null };
+  }
+  const file = torrent.files[fileIndex];
+  let harvested = state.harvested.get(trackNumber);
+  if (!harvested) {
+    harvested = new Set();
+    state.harvested.set(trackNumber, harvested);
+  }
+  let cues = state.cues.get(trackNumber);
+  if (!cues) {
+    cues = [];
+    state.cues.set(trackNumber, cues);
+  }
+
+  if (Array.isArray(track.samples)) {
+    // An MP4: every cue's bytes are stated, so only those bytes are read, and
+    // only where they are already downloaded.
+    for (const sample of track.samples) {
+      if (harvested.has(sample.offset)) {
+        continue;
+      }
+      const last = Math.min(file.length - 1, sample.offset + sample.size - 1);
+      if (!rangeIsHeld(torrent, file, sample.offset, last)) {
+        continue;
+      }
+      const bytes = await readHeld(file, sample.offset, last);
+      if (!bytes) {
+        continue;
+      }
+      harvested.add(sample.offset);
+      const text = decodeSubtitleSample(bytes, track.codecId);
+      if (text) {
+        cues.push({ startSeconds: sample.startSeconds, endSeconds: sample.endSeconds, text });
+      }
+    }
+    cues.sort((left, right) => left.startSeconds - right.startSeconds);
+    return {
+      cues,
+      coveredClusters: harvested.size,
+      indexedClusters: track.samples.length,
+      track
+    };
+  }
+
+  for (const position of track.clusterPositions) {
+    if (harvested.has(position)) {
+      continue;
+    }
+    // The header first: it says how long the cluster is, and a cluster whose
+    // bytes are not all here is left for the next time round.
+    if (!rangeIsHeld(torrent, file, position, Math.min(file.length - 1, position + CLUSTER_HEADER_PROBE - 1))) {
+      continue;
+    }
+    const probe = await readHeld(file, position, Math.min(file.length - 1, position + CLUSTER_HEADER_PROBE - 1));
+    const header = probe && [...iterateElements(probe, 0, probe.length)][0];
+    if (!header || header.size <= 0 || header.size > MAX_CLUSTER_BYTES) {
+      harvested.add(position); // not a cluster we can read; do not look again
+      continue;
+    }
+    const last = Math.min(file.length - 1, position + header.dataOffset + header.size - 1);
+    if (!rangeIsHeld(torrent, file, position, last)) {
+      continue;
+    }
+    const bytes = await readHeld(file, position, last);
+    if (!bytes) {
+      continue;
+    }
+    harvested.add(position);
+    for (const cue of harvestCluster(bytes, trackNumber, plan.secondsPerTick)) {
+      cues.push(cue);
+    }
+  }
+  cues.sort((left, right) => left.startSeconds - right.startSeconds);
+  return {
+    cues,
+    coveredClusters: harvested.size,
+    indexedClusters: track.clusterPositions.length,
+    track
+  };
+}
+
+/**
+ * The text subtitle tracks of a file, for the menu the viewer sees.
+ *
+ * @param {object} torrent
+ * @param {number} fileIndex
+ * @param {string} sourceKey
+ * @returns {Promise<object[]>}
+ */
+export async function subtitleTracksOf(torrent, fileIndex, sourceKey) {
+  const plan = await planFor(torrent, fileIndex, `${sourceKey}:${fileIndex}`);
+  return (plan?.tracks ?? []).map((track) => ({
+    trackNumber: track.trackNumber,
+    codecId: track.codecId,
+    language: track.language,
+    name: track.name,
+    isDefault: track.isDefault,
+    indexedClusters: track.clusterPositions.length
+  }));
+}
+
+/**
+ * Forget a file's cues — the torrent is gone, and holding them would keep the
+ * text of a film nobody is watching.
+ *
+ * @param {string} sourceKey
+ * @param {number} [fileIndex]
+ * @returns {void}
+ */
+export function forgetSubtitles(sourceKey, fileIndex) {
+  if (fileIndex === undefined) {
+    for (const key of [...byFile.keys()]) {
+      if (key.startsWith(`${sourceKey}:`)) {
+        byFile.delete(key);
+      }
+    }
+    return;
+  }
+  byFile.delete(`${sourceKey}:${fileIndex}`);
+}

package/services/torrent-worker/worker.js

@@ -27,6 +27,7 @@ import { parentPort, workerData } from "node:worker_threads";
 import { createSendStream } from "./channel.js";
 import { createFileClaims } from "./file-claims.js";
 import { readFragments, supplyFiguresFor } from "./piece-reader.js";
+import { cuesHeldFor, subtitleTracksOf } from "./subtitle-cues.js";
 import { Command, Event } from "./protocol.js";
 
 // Imported dynamically, and that is load-bearing: static imports are RESOLVED
@@ -356,6 +357,24 @@ async function runCommand(command, params, id) {
       return { downloaded, uploaded };
     }
 
+    case Command.SUBTITLE_TRACKS: {
+      const torrent = await requireTorrent(params.sourceKey);
+      return { tracks: await subtitleTracksOf(torrent, params.fileIndex, params.sourceKey) };
+    }
+
+    case Command.SUBTITLE_CUES: {
+      const torrent = await requireTorrent(params.sourceKey);
+      const held = await cuesHeldFor(torrent, params.fileIndex, params.sourceKey, params.trackNumber);
+      return {
+        cues: held.cues,
+        coveredClusters: held.coveredClusters,
+        indexedClusters: held.indexedClusters,
+        codecId: held.track?.codecId ?? "",
+        codecPrivate: held.track?.codecPrivate ?? "",
+        language: held.track?.language ?? ""
+      };
+    }
+
     case Command.FILE_STATS: {
       const torrent = await requireTorrent(params.sourceKey);
       const stats = pool.getFileStats(torrent, params.fileIndex, {

package/test/mp4-subtitles.test.js

@@ -0,0 +1,127 @@
+/**
+ * @file Reading an MP4's text subtitle track out of its sample table.
+ *
+ * The file is built here, so every answer is known in advance: two cues at
+ * stated times, in stated places, with an empty sample between them — the way
+ * the format says "nothing on screen just now".
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { decodeSubtitleSample, readMp4SubtitlePlan } from "../services/container-index/mp4-subtitles.js";
+
+function box(type, payload) {
+  const header = Buffer.alloc(8);
+  header.writeUInt32BE(payload.length + 8, 0);
+  header.write(type, 4, "latin1");
+  return Buffer.concat([header, payload]);
+}
+
+function fullBox(type, payload) {
+  return box(type, Buffer.concat([Buffer.from([0, 0, 0, 0]), payload]));
+}
+
+function u32(...values) {
+  const buffer = Buffer.alloc(values.length * 4);
+  values.forEach((value, index) => buffer.writeUInt32BE(value, index * 4));
+  return buffer;
+}
+
+/** A `tx3g` sample: a two-byte length, then the text. */
+function textSample(text) {
+  const bytes = Buffer.from(text, "utf8");
+  const length = Buffer.alloc(2);
+  length.writeUInt16BE(bytes.length, 0);
+  return Buffer.concat([length, bytes]);
+}
+
+/**
+ * A file with one text track: three samples, the middle one empty.
+ *
+ * @returns {{ file: Buffer, samples: Buffer[] }}
+ */
+function buildFile() {
+  const samples = [textSample("First line"), Buffer.alloc(2), textSample("Second line")];
+  const timescale = 1000;
+
+  const mdhd = fullBox("mdhd", Buffer.concat([
+    u32(0, 0, timescale, 60_000),
+    // Language "eng", five bits a letter offset from 0x60, then a spare word.
+    Buffer.from([0x15, 0xc7, 0, 0])
+  ]));
+  const hdlr = fullBox("hdlr", Buffer.concat([u32(0), Buffer.from("sbtl", "latin1"), u32(0, 0, 0)]));
+  const tkhd = fullBox("tkhd", u32(0, 0, 7, 0, 60_000));
+
+  const stsd = fullBox("stsd", Buffer.concat([u32(1), box("tx3g", Buffer.alloc(24))]));
+  // Two seconds a sample, so the cues sit at 0-2, 2-4 and 4-6 seconds.
+  const stts = fullBox("stts", Buffer.concat([u32(1), u32(3, 2000)]));
+  const stsz = fullBox("stsz", Buffer.concat([u32(0, 3), u32(...samples.map((s) => s.length))]));
+  const stsc = fullBox("stsc", Buffer.concat([u32(1), u32(1, 3, 1)]));
+
+  const stbl = box("stbl", Buffer.concat([stsd, stts, stsz, stsc, fullBox("stco", Buffer.concat([u32(1), u32(0)]))]));
+  const minf = box("minf", stbl);
+  const mdia = box("mdia", Buffer.concat([mdhd, hdlr, minf]));
+  const trak = box("trak", Buffer.concat([tkhd, mdia]));
+  const moovDraft = box("moov", trak);
+
+  // The samples sit after moov, so the chunk offset is known only now. Its
+  // length does not change when the placeholder becomes the real value.
+  const mdatStart = moovDraft.length + 8;
+  const stcoReal = fullBox("stco", Buffer.concat([u32(1), u32(mdatStart)]));
+  const stblReal = box("stbl", Buffer.concat([stsd, stts, stsz, stsc, stcoReal]));
+  const moov = box("moov", box("trak", Buffer.concat([
+    tkhd,
+    box("mdia", Buffer.concat([mdhd, hdlr, box("minf", stblReal)]))
+  ])));
+  const mdat = box("mdat", Buffer.concat(samples));
+  return { file: Buffer.concat([moov, mdat]), samples };
+}
+
+function readerOver(file) {
+  return async (start, end) => {
+    const last = Math.min(end, file.length - 1);
+    return start > last ? null : file.subarray(start, last + 1);
+  };
+}
+
+test("a text track's cues are found with their times and their byte ranges", async () => {
+  const { file, samples } = buildFile();
+
+  const plan = await readMp4SubtitlePlan(readerOver(file), file.length);
+
+  assert.equal(plan.tracks.length, 1);
+  const track = plan.tracks[0];
+  assert.equal(track.format, "tx3g");
+  assert.equal(track.language, "eng");
+  assert.equal(track.samples.length, 2, "the empty sample is a gap, not a cue");
+  assert.deepEqual(
+    track.samples.map((sample) => [sample.startSeconds, sample.endSeconds]),
+    [[0, 2], [4, 6]],
+    "times come from the duration table, and the gap keeps its place in it"
+  );
+  // The bytes the plan points at are the ones that hold the text.
+  const first = file.subarray(track.samples[0].offset, track.samples[0].offset + track.samples[0].size);
+  assert.equal(decodeSubtitleSample(first, "tx3g"), "First line");
+  const second = file.subarray(track.samples[1].offset, track.samples[1].offset + track.samples[1].size);
+  assert.equal(decodeSubtitleSample(second, "tx3g"), "Second line");
+  assert.equal(second.length, samples[2].length);
+});
+
+test("a file with no text track offers nothing", async () => {
+  const moov = box("moov", box("trak", box("mdia", Buffer.concat([
+    fullBox("mdhd", Buffer.concat([u32(0, 0, 1000, 100), Buffer.from([0, 0, 0, 0])])),
+    fullBox("hdlr", Buffer.concat([u32(0), Buffer.from("vide", "latin1"), u32(0, 0, 0)]))
+  ]))));
+  const file = Buffer.concat([moov, box("mdat", Buffer.alloc(4))]);
+
+  const plan = await readMp4SubtitlePlan(readerOver(file), file.length);
+
+  assert.deepEqual(plan.tracks, []);
+});
+
+test("a WebVTT sample gives up the text inside its payload box", () => {
+  const payl = box("payl", Buffer.from("Hello there", "utf8"));
+  const sample = box("vttc", payl);
+
+  assert.equal(decodeSubtitleSample(sample, "wvtt"), "Hello there");
+});