@torrent-tv/proxy 2.41.0 → 2.42.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## 2.41.0
 
+- **New**: Embedded text subtitles are read out of the clusters the film is already downloading, and no longer extracted with ffmpeg. Measured 2026-08-19 on `Minions.and.Monsters.1080p.mkv`: the browser asked for a track, gave up at its own 60 s limit, and the proxy answered **752 seconds later** with 3040 bytes — because a subtitle stream is sparse and ffmpeg walks the whole container whatever range is asked of it. Measured twice more to be sure: `-ss 1200 -t 4` read to the end of the file and pulled the download from 2.7 % to 81 % of 6.5 GB, and `-copyts -ss 600 -to 604` took 154 s on a copy already 81 % local and still emitted the whole track. A subtitle block sits in the same cluster as the picture around it, so those clusters are in hand anyway: the cue points of the subtitle track name them, the blocks are read where every piece covering them is already downloaded, and nothing is requested from the swarm. **Cost: zero extra bytes**, and the cues for the part being watched are ready before the viewer reaches it — which is the rule this was held to, subtitles arriving like the picture or not at all. On the field file the plan reads in 3.8 s over the swarm and names all four tracks with their languages, and the cues come out with their real times (`118.41s → 125.71s «МАГИЯ ГОЛЛИВУДА»`). A file this cannot be read from falls back to the old extraction, unchanged. `S_TEXT/UTF8` needs no conversion; `S_TEXT/ASS` and `S_TEXT/SSA` have their dialogue fields stripped; image subtitles (PGS, VobSub) are deliberately not offered, since this path cannot show them.
+- **Chore**: The Matroska block reader is its own module with its own tests (`services/container-index/matroska-blocks.js`): cluster time plus the block's own offset, the duration out of the block group, other tracks skipped, negative offsets placed correctly, and lacing stepped over rather than read as text.
+
+## 2.41.0
+
 - **Fix**: An embedded subtitle track is prepared in the background and kept, instead of being extracted afresh inside a request the browser cannot hold open. Extracting one makes ffmpeg read the WHOLE film, because subtitles are interleaved through it — measured 2026-08-19 on a release with three tracks: track 0 produced **3040 bytes over 752 seconds**, track 1 76 KB over 193 s, track 2 68 KB over 55 s, with the data channel idle throughout (`maxBuffered=0`, the time all in reading the body). The browser gives up at sixty seconds, and every retry started the same twelve-minute scan again, so the first track never arrived at all. The route now starts the work once per `(source, file, track)`, answers `202 { pending: true }` while it runs, and serves the kept result the moment it exists. The scan still takes what it takes; what changes is that it happens once and its result is not thrown away.
 - **New**: Every read says which way it claimed its pieces, whatever the outcome. The arm — `flat` or `bands`, chosen at random per read so the two accumulate side by side — was named only beside a WAIT, and across eight sessions on 2026-08-19 there were none: the swarm kept up, the log recorded nothing, and the comparison the arms exist for could not tell whether either had ever run. A read now reports its arm, what it delivered, how long it took and how much of that was spent waiting, at its end and under every outcome. "No wait" is the result worth counting, and it was the one being discarded.
 

package/package.json

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

package/routes/api/subtitles/get.js

@@ -96,6 +96,27 @@ export async function handleApiSubtitlesGet(req, reply, { sourceRegistry, torren
     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.
+  const held = await cuesFromDownloadedClusters(torrentPool, torrent, fileIndex, trackIndex);
+  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));
+    reply.raw.setHeader(
+      "Access-Control-Expose-Headers",
+      "X-Subtitle-Language, X-Subtitle-Language-Name, X-Subtitle-Covered-Clusters, X-Subtitle-Indexed-Clusters"
+    );
+    return reply.send(held.vtt);
+  }
+
   const inputUrl = new URL("/stream", `${localBaseUrl}/`);
   inputUrl.searchParams.set("sourceKey", sourceKey);
   inputUrl.searchParams.set("fileIndex", String(fileIndex));
@@ -215,3 +236,115 @@ function readFileFully(file, maxBytes) {
     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 the subtitle streams, as ffprobe lists them — while Matroska blocks
+ * carry the file's own track number. The plan lists the text tracks in file
+ * order, so the browser's Nth subtitle stream is the Nth entry.
+ *
+ * @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) {
+  if (typeof torrentPool?.getSubtitleTracks !== "function") {
+    return null;
+  }
+  let tracks;
+  try {
+    tracks = await torrentPool.getSubtitleTracks(torrent, fileIndex);
+  } catch {
+    return null;
+  }
+  const track = Array.isArray(tracks) ? tracks[trackIndex] : 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;
+  }
+  const vtt = cuesToVtt(held.cues, held.codecId);
+  const language = held.cues.length > 0
+    ? detectLanguage(held.cues.map((cue) => cue.text).join("\n"))
+    : null;
+  return {
+    vtt,
+    language,
+    coveredClusters: held.coveredClusters ?? 0,
+    indexedClusters: held.indexedClusters ?? 0
+  };
+}
+
+/**
+ * WebVTT from cues read out of the container.
+ *
+ * A cue with no duration — a SimpleBlock, which subtitles rarely use — is given
+ * the time until the next one, and the last such cue a few seconds. That is not
+ * an invention about the film: it is what a player does with an open-ended cue,
+ * made explicit here so the file is valid.
+ *
+ * @param {{ startSeconds: number, endSeconds: number | null, text: string }[]} cues
+ * @param {string} codecId
+ * @returns {string}
+ */
+function cuesToVtt(cues, codecId) {
+  const lines = ["WEBVTT", ""];
+  const isAss = codecId === "S_TEXT/ASS" || codecId === "S_TEXT/SSA";
+  cues.forEach((cue, index) => {
+    const next = cues[index + 1];
+    const end = cue.endSeconds ?? (next ? next.startSeconds : cue.startSeconds + 4);
+    const text = isAss ? assDialogueToText(cue.text) : cue.text.trim();
+    if (!text) {
+      return;
+    }
+    lines.push(`${vttTime(cue.startSeconds)} --> ${vttTime(end)}`);
+    lines.push(text);
+    lines.push("");
+  });
+  return lines.join("\n");
+}
+
+/**
+ * The visible text of an ASS dialogue row.
+ *
+ * A block carries the fields after `Dialogue:` without their header — nine of
+ * them, then the text, which itself holds override groups in braces.
+ *
+ * @param {string} raw
+ * @returns {string}
+ */
+function assDialogueToText(raw) {
+  const fields = raw.split(",");
+  const text = fields.length > 9 ? fields.slice(9).join(",") : raw;
+  return text
+    .replace(/\{[^}]*\}/g, "")
+    .replace(/\\N/gi, "\n")
+    .trim();
+}
+
+/**
+ * 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-index/matroska-blocks.js

@@ -0,0 +1,202 @@
+/**
+ * @file Subtitle blocks out of Matroska clusters, from bytes already in hand.
+ *
+ * A subtitle track is sparse — a few kilobytes spread across a whole film — and
+ * ffmpeg cannot extract a time range of one without walking the container to
+ * the end. Measured 2026-08-19 on `Minions.and.Monsters.1080p.mkv`: asking for
+ * four seconds at minute twenty read the file through and pulled the download
+ * from 2.7 % to 81 %; asking with `-copyts -ss -to` took 154 s on a copy that
+ * was already 81 % local and still emitted the whole track. So the subtitles
+ * are not asked of ffmpeg.
+ *
+ * They do not have to be. A subtitle block sits in the same cluster as the
+ * picture around it, and those clusters are being downloaded anyway for the
+ * viewer to watch. Reading them as they arrive costs no network at all, and it
+ * puts the cues ahead of the playhead by construction — which is the whole
+ * requirement: subtitles arrive like the picture does, or they are not offered.
+ *
+ * This module is the byte-level half: given a cluster's bytes, it returns the
+ * blocks of one track with their times. It reads element headers and skips
+ * payloads by their declared length; nothing is decoded.
+ *
+ * Structure, from RFC 9559 §5.1.3 and §5.1.4:
+ *
+ *   Cluster (0x1F43B675)
+ *     Timestamp (0xE7)            — the cluster's own time, in ticks
+ *     SimpleBlock (0xA3)          — a block with no duration of its own
+ *     BlockGroup (0xA0)
+ *       Block (0xA1)              — the same header, and where subtitles live
+ *       BlockDuration (0x9B)      — how long the cue stays on screen
+ *
+ * A block's header is: the track number as a variable-length integer, a signed
+ * 16-bit timestamp relative to the cluster, and one byte of flags. Subtitles
+ * are normally in a BlockGroup, because a cue without a duration has no end.
+ */
+
+import { iterateElements, readUint, readVint } from "./ebml-reader.js";
+
+const ID_TIMESTAMP = 0xe7;
+const ID_SIMPLE_BLOCK = 0xa3;
+const ID_BLOCK_GROUP = 0xa0;
+const ID_BLOCK = 0xa1;
+const ID_BLOCK_DURATION = 0x9b;
+
+/** Bits 1-2 of the flags byte say how a block is laced, or that it is not. */
+const LACING_MASK = 0x06;
+const LACING_NONE = 0x00;
+const LACING_XIPH = 0x02;
+const LACING_FIXED = 0x04;
+const LACING_EBML = 0x06;
+
+/**
+ * @typedef {object} SubtitleBlock
+ * @property {number} startSeconds - When the cue appears.
+ * @property {number | null} durationSeconds - How long it stays, or null when
+ *   the block carried no duration (a SimpleBlock; the caller decides).
+ * @property {Buffer} payload - The block's own bytes, still in the codec's form.
+ */
+
+/**
+ * Read one block's header.
+ *
+ * @param {Buffer} buffer
+ * @param {number} start - First byte of the block's payload.
+ * @param {number} end - One past its last byte.
+ * @returns {{ trackNumber: number, relativeTicks: number, flags: number, dataOffset: number } | null}
+ */
+function readBlockHeader(buffer, start, end) {
+  const track = readVint(buffer, start, false);
+  if (!track || track.value === null) {
+    return null;
+  }
+  const timestampAt = start + track.length;
+  // Signed, and it can be negative: a block may belong slightly before the
+  // cluster it is stored in.
+  if (timestampAt + 3 > end) {
+    return null;
+  }
+  return {
+    trackNumber: Number(track.value),
+    relativeTicks: buffer.readInt16BE(timestampAt),
+    flags: buffer[timestampAt + 2],
+    dataOffset: timestampAt + 3
+  };
+}
+
+/**
+ * Where a laced block's first frame begins.
+ *
+ * Subtitles are rarely laced, but a block that IS laced starts with a frame
+ * count and a table of sizes, and reading the payload without stepping over
+ * them yields the table as though it were text.
+ *
+ * @param {Buffer} buffer
+ * @param {number} dataOffset - First byte after the block header.
+ * @param {number} end
+ * @param {number} flags
+ * @returns {number | null} The offset of the first frame, or null when the
+ *   lacing cannot be read.
+ */
+function firstFrameOffset(buffer, dataOffset, end, flags) {
+  const lacing = flags & LACING_MASK;
+  if (lacing === LACING_NONE) {
+    return dataOffset;
+  }
+  if (dataOffset >= end) {
+    return null;
+  }
+  const frames = buffer[dataOffset] + 1;
+  let at = dataOffset + 1;
+  if (lacing === LACING_FIXED) {
+    return at;
+  }
+  if (lacing === LACING_XIPH) {
+    // Each size but the last is a run of 0xFF bytes ending in a smaller one.
+    for (let frame = 0; frame < frames - 1; frame += 1) {
+      while (at < end && buffer[at] === 0xff) {
+        at += 1;
+      }
+      at += 1;
+    }
+    return at <= end ? at : null;
+  }
+  if (lacing === LACING_EBML) {
+    // The first size is a plain variable-length integer, the rest are signed
+    // differences from it; either way each is one such integer to step over.
+    for (let frame = 0; frame < frames - 1; frame += 1) {
+      const size = readVint(buffer, at, false);
+      if (!size) {
+        return null;
+      }
+      at += size.length;
+    }
+    return at <= end ? at : null;
+  }
+  return null;
+}
+
+/**
+ * Every block of one track inside one cluster.
+ *
+ * @param {Buffer} buffer - Bytes holding the cluster's payload.
+ * @param {{ dataOffset: number, size: number }} cluster - Where that payload is.
+ * @param {number} trackNumber - The track to keep.
+ * @param {number} secondsPerTick - From the segment's timestamp scale.
+ * @returns {SubtitleBlock[]}
+ */
+export function blocksOfTrack(buffer, cluster, trackNumber, secondsPerTick) {
+  const end = Math.min(buffer.length, cluster.dataOffset + cluster.size);
+  /** @type {SubtitleBlock[]} */
+  const blocks = [];
+  let clusterTicks = null;
+
+  const take = (blockStart, blockEnd, durationTicks) => {
+    const header = readBlockHeader(buffer, blockStart, blockEnd);
+    if (!header || header.trackNumber !== trackNumber || clusterTicks === null) {
+      return;
+    }
+    const payloadAt = firstFrameOffset(buffer, header.dataOffset, blockEnd, header.flags);
+    if (payloadAt === null || payloadAt >= blockEnd) {
+      return;
+    }
+    blocks.push({
+      startSeconds: (clusterTicks + header.relativeTicks) * secondsPerTick,
+      durationSeconds: durationTicks === null ? null : durationTicks * secondsPerTick,
+      payload: buffer.subarray(payloadAt, blockEnd)
+    });
+  };
+
+  for (const element of iterateElements(buffer, cluster.dataOffset, end)) {
+    const elementEnd = Math.min(end, element.dataOffset + element.size);
+    if (element.id === ID_TIMESTAMP) {
+      clusterTicks = readUint(buffer, element.dataOffset, element.size);
+      continue;
+    }
+    if (element.id === ID_SIMPLE_BLOCK) {
+      take(element.dataOffset, elementEnd, null);
+      continue;
+    }
+    if (element.id !== ID_BLOCK_GROUP) {
+      continue;
+    }
+    // A group holds the block and, for a subtitle, the duration that says when
+    // the cue leaves the screen. Both are read before either is used, because
+    // the duration may be written after the block.
+    let blockStart = null;
+    let blockEnd = null;
+    let durationTicks = null;
+    for (const field of iterateElements(buffer, element.dataOffset, elementEnd)) {
+      const fieldEnd = Math.min(elementEnd, field.dataOffset + field.size);
+      if (field.id === ID_BLOCK) {
+        blockStart = field.dataOffset;
+        blockEnd = fieldEnd;
+      } else if (field.id === ID_BLOCK_DURATION) {
+        durationTicks = readUint(buffer, field.dataOffset, field.size);
+      }
+    }
+    if (blockStart !== null) {
+      take(blockStart, blockEnd, durationTicks);
+    }
+  }
+  return blocks;
+}

package/services/container-index/matroska-subtitles.js

@@ -0,0 +1,262 @@
+/**
+ * @file The subtitle tracks of a Matroska file, and where their cues live.
+ *
+ * Two halves, both reading only what is asked for by byte range:
+ *
+ *   - {@link readSubtitlePlan} — once per file: which tracks are text
+ *     subtitles, in what codec, and the cluster positions their cue points
+ *     name. Two short reads, the head and the Cues element, exactly as the
+ *     keyframe reader already does.
+ *   - {@link harvestCluster} — per cluster, over bytes already downloaded:
+ *     the cues inside it, ready to be shown.
+ *
+ * Kept apart from `matroska.js` because that file answers one question (where
+ * are the keyframes) and is read on the path that starts playback; this one is
+ * only ever consulted for a viewer who asked for subtitles.
+ */
+
+import { findElement, iterateElements, readUint } from "./ebml-reader.js";
+import { blocksOfTrack } from "./matroska-blocks.js";
+
+const ID_SEGMENT = 0x18538067;
+const ID_SEEK_HEAD = 0x114d9b74;
+const ID_SEEK = 0x4dbb;
+const ID_SEEK_ID = 0x53ab;
+const ID_SEEK_POSITION = 0x53ac;
+const ID_INFO = 0x1549a966;
+const ID_TIMESTAMP_SCALE = 0x2ad7b1;
+const ID_TRACKS = 0x1654ae6b;
+const ID_TRACK_ENTRY = 0xae;
+const ID_TRACK_NUMBER = 0xd7;
+const ID_TRACK_TYPE = 0x83;
+const ID_CODEC_ID = 0x86;
+const ID_CODEC_PRIVATE = 0x63a2;
+const ID_LANGUAGE = 0x22b59c;
+const ID_NAME = 0x536e;
+const ID_FLAG_DEFAULT = 0x88;
+const ID_CUES = 0x1c53bb6b;
+const ID_CUE_POINT = 0xbb;
+const ID_CUE_TRACK_POSITIONS = 0xb7;
+const ID_CUE_TRACK = 0xf7;
+const ID_CUE_CLUSTER_POSITION = 0xf1;
+
+/** TrackType 17 is subtitles; 1 is video and 2 audio. */
+const TRACK_TYPE_SUBTITLE = 17;
+/** How much of the file start to read: the same window the keyframe reader uses. */
+const HEAD_BYTES = 64 * 1024;
+/** Cap on the Cues read; a long film indexes to tens of KB. */
+const MAX_CUES_BYTES = 8 * 1024 * 1024;
+const DEFAULT_TIMESTAMP_SCALE = 1_000_000;
+
+/**
+ * The codecs whose blocks are text this proxy can turn into WebVTT.
+ *
+ * `S_TEXT/UTF8` is a plain line of text and needs nothing. `S_TEXT/ASS` and
+ * `S_TEXT/SSA` carry a dialogue row whose fields have to be stripped, and their
+ * header lives in CodecPrivate — supported, with the stripping done where the
+ * cue is turned into WebVTT. `S_HDMV/PGS` and `S_VOBSUB` are pictures, not
+ * text, and are deliberately absent: offering them would promise something this
+ * path cannot deliver.
+ */
+const TEXT_CODECS = new Set(["S_TEXT/UTF8", "S_TEXT/ASS", "S_TEXT/SSA"]);
+
+/**
+ * @typedef {object} SubtitleTrackPlan
+ * @property {number} trackNumber - As the blocks name it.
+ * @property {string} codecId
+ * @property {string} language - The three-letter code the file declares.
+ * @property {string} name - What the file calls the track, if anything.
+ * @property {boolean} isDefault
+ * @property {string} codecPrivate - The ASS/SSA header, base64, or "".
+ * @property {number[]} clusterPositions - File offsets of clusters whose cue
+ *   points name this track, ascending. Empty when the file indexes only its
+ *   picture, and then the caller has to walk clusters as they arrive instead.
+ */
+
+/**
+ * Read a string element, trimming the padding some muxers leave.
+ *
+ * @param {Buffer} buffer
+ * @param {{ dataOffset: number, size: number }} element
+ * @returns {string}
+ */
+function readString(buffer, element) {
+  return buffer
+    .toString("utf8", element.dataOffset, element.dataOffset + element.size)
+    .replace(/\0+$/, "");
+}
+
+/**
+ * Everything about a file's text subtitle tracks that can be learned without
+ * reading the film.
+ *
+ * @param {(start: number, end: number) => Promise<Buffer | null>} readRange
+ * @param {number} fileSize
+ * @returns {Promise<{ tracks: SubtitleTrackPlan[], secondsPerTick: number, segmentDataOffset: number } | null>}
+ */
+export async function readSubtitlePlan(readRange, fileSize) {
+  const head = await readRange(0, Math.min(HEAD_BYTES, Math.max(0, fileSize - 1)));
+  if (!head || head.length < 4 || head.readUInt32BE(0) !== 0x1a45dfa3) {
+    return null;
+  }
+  const segment = findElement(head, ID_SEGMENT, []);
+  if (!segment) {
+    return null;
+  }
+  const base = segment.dataOffset;
+
+  const info = findElement(head, ID_INFO, [], base);
+  let scale = DEFAULT_TIMESTAMP_SCALE;
+  if (info) {
+    const declared = findElement(head, ID_TIMESTAMP_SCALE, [], info.dataOffset, info.dataOffset + info.size);
+    if (declared) {
+      const value = readUint(head, declared.dataOffset, declared.size);
+      if (value > 0) {
+        scale = value;
+      }
+    }
+  }
+
+  const tracksElement = findElement(head, ID_TRACKS, [], base);
+  if (!tracksElement) {
+    return null;
+  }
+  const tracksEnd = Math.min(head.length, tracksElement.dataOffset + tracksElement.size);
+  /** @type {SubtitleTrackPlan[]} */
+  const tracks = [];
+  for (const entry of iterateElements(head, tracksElement.dataOffset, tracksEnd)) {
+    if (entry.id !== ID_TRACK_ENTRY) {
+      continue;
+    }
+    const entryEnd = Math.min(tracksEnd, entry.dataOffset + entry.size);
+    let trackNumber = null;
+    let type = null;
+    let codecId = "";
+    let language = "";
+    let name = "";
+    let codecPrivate = "";
+    let isDefault = true;
+    for (const field of iterateElements(head, entry.dataOffset, entryEnd)) {
+      if (field.id === ID_TRACK_NUMBER) {
+        trackNumber = readUint(head, field.dataOffset, field.size);
+      } else if (field.id === ID_TRACK_TYPE) {
+        type = readUint(head, field.dataOffset, field.size);
+      } else if (field.id === ID_CODEC_ID) {
+        codecId = readString(head, field);
+      } else if (field.id === ID_LANGUAGE) {
+        language = readString(head, field);
+      } else if (field.id === ID_NAME) {
+        name = readString(head, field);
+      } else if (field.id === ID_FLAG_DEFAULT) {
+        isDefault = readUint(head, field.dataOffset, field.size) === 1;
+      } else if (field.id === ID_CODEC_PRIVATE) {
+        codecPrivate = head.toString("base64", field.dataOffset, field.dataOffset + field.size);
+      }
+    }
+    if (type !== TRACK_TYPE_SUBTITLE || trackNumber === null || !TEXT_CODECS.has(codecId)) {
+      continue;
+    }
+    tracks.push({
+      trackNumber,
+      codecId,
+      language,
+      name,
+      isDefault,
+      codecPrivate,
+      clusterPositions: []
+    });
+  }
+  if (tracks.length === 0) {
+    return { tracks, secondsPerTick: scale / 1e9, segmentDataOffset: base };
+  }
+
+  // Where the clusters holding those tracks are. A file that indexes only its
+  // picture leaves these empty, which is not a failure: the caller then reads
+  // the clusters the viewer's own playback brings in.
+  const seekHead = findElement(head, ID_SEEK_HEAD, [], base);
+  let cuesRelative;
+  if (seekHead) {
+    const seekEnd = Math.min(head.length, seekHead.dataOffset + seekHead.size);
+    for (const seek of iterateElements(head, seekHead.dataOffset, seekEnd)) {
+      if (seek.id !== ID_SEEK) {
+        continue;
+      }
+      let target = null;
+      let position = null;
+      for (const field of iterateElements(head, seek.dataOffset, Math.min(seekEnd, seek.dataOffset + seek.size))) {
+        if (field.id === ID_SEEK_ID) {
+          target = readUint(head, field.dataOffset, field.size);
+        } else if (field.id === ID_SEEK_POSITION) {
+          position = readUint(head, field.dataOffset, field.size);
+        }
+      }
+      if (target === ID_CUES && position !== null) {
+        cuesRelative = position;
+      }
+    }
+  }
+  if (cuesRelative !== undefined) {
+    const cuesAt = base + cuesRelative;
+    if (cuesAt > 0 && cuesAt < fileSize) {
+      const chunk = await readRange(cuesAt, Math.min(fileSize - 1, cuesAt + MAX_CUES_BYTES));
+      const element = chunk && [...iterateElements(chunk, 0, chunk.length)][0];
+      if (element && element.id === ID_CUES) {
+        const body = chunk.subarray(element.dataOffset, Math.min(chunk.length, element.dataOffset + element.size));
+        const byTrack = new Map(tracks.map((track) => [track.trackNumber, new Set()]));
+        for (const point of iterateElements(body, 0, body.length)) {
+          if (point.id !== ID_CUE_POINT) {
+            continue;
+          }
+          const pointEnd = Math.min(body.length, point.dataOffset + point.size);
+          for (const field of iterateElements(body, point.dataOffset, pointEnd)) {
+            if (field.id !== ID_CUE_TRACK_POSITIONS) {
+              continue;
+            }
+            let cueTrack = null;
+            let position = null;
+            for (const inner of iterateElements(body, field.dataOffset, Math.min(pointEnd, field.dataOffset + field.size))) {
+              if (inner.id === ID_CUE_TRACK) {
+                cueTrack = readUint(body, inner.dataOffset, inner.size);
+              } else if (inner.id === ID_CUE_CLUSTER_POSITION) {
+                position = readUint(body, inner.dataOffset, inner.size);
+              }
+            }
+            if (position !== null && byTrack.has(cueTrack)) {
+              byTrack.get(cueTrack).add(base + position);
+            }
+          }
+        }
+        for (const track of tracks) {
+          track.clusterPositions = [...byTrack.get(track.trackNumber)].sort((left, right) => left - right);
+        }
+      }
+    }
+  }
+  return { tracks, secondsPerTick: scale / 1e9, segmentDataOffset: base };
+}
+
+/**
+ * The cues of one track inside one cluster.
+ *
+ * @param {Buffer} bytes - The cluster, from its own element header onward.
+ * @param {number} trackNumber
+ * @param {number} secondsPerTick
+ * @returns {{ startSeconds: number, endSeconds: number | null, text: string }[]}
+ */
+export function harvestCluster(bytes, trackNumber, secondsPerTick) {
+  const header = [...iterateElements(bytes, 0, bytes.length)][0];
+  if (!header) {
+    return [];
+  }
+  const blocks = blocksOfTrack(
+    bytes,
+    { dataOffset: header.dataOffset, size: header.size },
+    trackNumber,
+    secondsPerTick
+  );
+  return blocks.map((block) => ({
+    startSeconds: block.startSeconds,
+    endSeconds: block.durationSeconds === null ? null : block.startSeconds + block.durationSeconds,
+    text: block.payload.toString("utf8")
+  }));
+}

package/services/torrent-worker/client.js

@@ -242,6 +242,26 @@ export class TorrentWorkerClient {
     return this.#caller.call(Command.FILE_STATS, { sourceKey, fileIndex, resumeAnchorByteStart });
   }
 
+  /**
+   * The text subtitle tracks a file carries.
+   *
+   * @param {{ sourceKey: string, fileIndex: number }} params
+   * @returns {Promise<{ tracks: object[] }>}
+   */
+  async getSubtitleTracks({ sourceKey, fileIndex }) {
+    return this.#caller.call(Command.SUBTITLE_TRACKS, { sourceKey, fileIndex });
+  }
+
+  /**
+   * The cues of one subtitle track that can be read from what is downloaded.
+   *
+   * @param {{ sourceKey: string, fileIndex: number, trackNumber: number }} params
+   * @returns {Promise<object>}
+   */
+  async getSubtitleCues({ sourceKey, fileIndex, trackNumber }) {
+    return this.#caller.call(Command.SUBTITLE_CUES, { sourceKey, fileIndex, trackNumber });
+  }
+
   /**
    * Bytes every torrent on the worker has moved, downloaded and uploaded apart.
    *

package/services/torrent-worker/pool-adapter.js

@@ -141,6 +141,38 @@ export class WorkerTorrentPool {
     });
   }
 
+  /**
+   * The text subtitle tracks a file carries, read from its own header.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @returns {Promise<object[]>}
+   */
+  async getSubtitleTracks(torrent, fileIndex) {
+    const sourceKey = torrent?.sourceKey;
+    if (!sourceKey) {
+      return [];
+    }
+    const answer = await this.#client.getSubtitleTracks({ sourceKey, fileIndex });
+    return Array.isArray(answer?.tracks) ? answer.tracks : [];
+  }
+
+  /**
+   * The cues of one subtitle track that the downloaded clusters already carry.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @param {number} trackNumber
+   * @returns {Promise<object | null>}
+   */
+  async getSubtitleCues(torrent, fileIndex, trackNumber) {
+    const sourceKey = torrent?.sourceKey;
+    if (!sourceKey) {
+      return null;
+    }
+    return this.#client.getSubtitleCues({ sourceKey, fileIndex, trackNumber });
+  }
+
   /**
    * Reorder piece selection around a read position.
    *

package/services/torrent-worker/protocol.js

@@ -65,6 +65,10 @@ export const Command = {
   CANCEL_READ: "cancel-read",
   /** Pre-fetch the head and tail a codec probe needs. */
   PREFETCH_EDGES: "prefetch-edges",
+  /** The text subtitle tracks a file carries, for the viewer's menu. */
+  SUBTITLE_TRACKS: "subtitle-tracks",
+  /** Cues of one subtitle track, from the clusters already downloaded. */
+  SUBTITLE_CUES: "subtitle-cues",
   /** Shut the client down, optionally deleting downloaded data. */
   DESTROY_ALL: "destroy-all"
 };

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

@@ -0,0 +1,233 @@
+/**
+ * @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 { 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];
+  if (!file || !/\.mkv$/i.test(String(file.name))) {
+    // Only Matroska is read this way. An MP4's text track is cheaper still —
+    // its sample table gives exact byte offsets — and is not written yet.
+    state.plan = { tracks: [], secondsPerTick: 0.001, segmentDataOffset: 0 };
+    return state.plan;
+  }
+  const readRange = async (start, end) => readHeld(file, start, Math.min(end, file.length - 1));
+  const plan = await readSubtitlePlan(readRange, file.length);
+  state.plan = plan ?? { tracks: [], secondsPerTick: 0.001, segmentDataOffset: 0 };
+  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);
+  }
+
+  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, {