@torrent-tv/proxy 2.55.14 → 2.56.0

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2.56.0
+
+- **Fix**: A subtitle track is asked for by ffmpeg's own number, `0:s:N`, which counts EVERY subtitle stream the file carries — and the container plan counted only the ones it can turn into text, dropping PGS and VobSub before numbering. On a release whose picture-based track comes first the two numberings ran a place apart, with two consequences, both silent: a pushed cue named a track the browser does not know and was dropped, and the browser's own request found no track at all and fell through to the ffmpeg extraction, which reads the whole film for a few kilobytes of text (752 s measured on one file, 2026-08-19). Every text track now carries `declaredIndex` — its position among all the file's subtitle tracks, counted by what a track IS and not by what this code can read — and both the push and `/api/subtitles?trackIndex=` use it. In an MP4 that count includes the `subp` and `clcp` handlers, which ffmpeg also calls subtitle streams.
+- **Fix**: One walk of a file at a time. The walk marks a cluster as read only after fetching and parsing it — two suspension points — while it is started both on every verified piece and on a 3 s timer, so on a fast download several passes read and parsed the same cluster and could push one line twice under different found-order numbers. Each of those reads is a WebTorrent file stream, which selects and deselects its pieces, so the repetition reached the piece picker as well. Walks are now serialized per file, the plan is read once even when two callers arrive together, a warmup triggered while the previous one is still walking is dropped rather than queued, and forgetting a file waits for its walk instead of leaving one running beside a fresh copy of the state.
+- **Fix**: A read of already-downloaded bytes that never ends is given up after 30 s, with a line saying so. It had no bound, and with walks now serialized one such read would have held that file's queue — the browser's own request for its subtitles included — for the rest of the session.
+- **New**: A subtitle push says what it is ABOUT: the film-time span its new cues cover, how many of the file's indexed clusters have been walked, and the found-order cursor. Read against the position being played — which the browser now logs beside it — that separates cues that arrived late from cues that arrived early for a stretch nobody is watching. Report 2026-08-26: embedded subtitles appear "after some time", and no line on either side could say whether the cues held covered the playhead (`research/subtitle-delay-2026-08-26.md`).
+- **New**: The push carries a `cursor`, so a browser that loses the subscription — which a reconnect does, since the subscription belongs to the channel — can ask for exactly what it missed instead of the whole track.
+
 ## 2.55.14
 
 - **Fix**: `utp-native` moves to 2.5.3-ttv.5, which carries ten defects found by reading the whole binding after the seventh crash of this family named its frame. Three callbacks read the connection pointer without checking it exists — and the socket carries none unless it was accepted or dialled, while its destructor announces itself regardless; the ttv.4 patch created one such path itself. The read callback copied at an accumulated offset without ever consulting the buffer length it maintains, so a peer sending more between two hand-offs wrote past the end — heap corruption does not fault where it happens, which is what six deaths inside libuv bookkeeping look like. A connection could be destroyed twice, deleting already-deleted napi references, and the socket pointer was never cleared. The callback macro checked none of the three napi results it then used. Plus IPv6, which the module never had at all, and the resolver that fed it addresses it could not use. Tests on the target: 77 checks, no failures — two of them were failing or hanging before.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.55.14",
+  "version": "2.56.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

@@ -268,9 +268,10 @@ function readFileFully(file, maxBytes) {
  * 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.
+ * among ALL the subtitle streams, as ffmpeg lists them — while Matroska blocks
+ * carry the file's own track number. The plan lists only the tracks that can
+ * become text, so it is matched on `declaredIndex`, which each track carries
+ * for exactly this: its place in the file's full list of subtitle tracks.
  *
  * @param {object} torrentPool
  * @param {object} torrent
@@ -289,7 +290,15 @@ async function cuesFromDownloadedClusters(torrentPool, torrent, fileIndex, track
   } catch {
     return null;
   }
-  const track = Array.isArray(tracks) ? tracks[trackIndex] : null;
+  // BY the browser's number, not by position in this list. The list holds only
+  // the tracks that can become WebVTT, while the browser counts every subtitle
+  // stream ffmpeg lists — so on a file carrying a PGS or VobSub track the two
+  // ran one apart, and the request either found the wrong track or found none
+  // and fell through to the ffmpeg extraction below, which reads the whole film
+  // (752 s measured, 2026-08-19) for cues already in hand.
+  const track = Array.isArray(tracks)
+    ? tracks.find((candidate) => candidate.declaredIndex === trackIndex) ?? null
+    : null;
   if (!track) {
     return null;
   }

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

@@ -63,6 +63,11 @@ 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 {number} declaredIndex - Its position among ALL of the file's
+ *   subtitle tracks, picture-based ones included — which is the number ffmpeg
+ *   gives the same stream in `0:s:N`, and therefore the only number the browser
+ *   ever names. Text tracks alone are not a numbering: a file whose PGS track
+ *   comes first would have every text track one lower here than in the browser.
  * @property {string} codecId
  * @property {string} language - The three-letter code the file declares.
  * @property {string} name - What the file calls the track, if anything.
@@ -178,6 +183,7 @@ export async function readSubtitlePlan(readRange, fileSize) {
     }
     tracks.push({
       trackNumber,
+      declaredIndex: declared.length - 1,
       codecId,
       language,
       name,

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

@@ -29,6 +29,15 @@ const MAX_MOOV_BYTES = 32 * 1024 * 1024;
 
 /** Handlers that mean "this track is text on screen". */
 const TEXT_HANDLERS = new Set(["text", "sbtl", "subt"]);
+/**
+ * Every handler ffmpeg's mov demuxer turns into a SUBTITLE stream, whether or
+ * not this file can read it — `subp` is a DVD subpicture and `clcp` closed
+ * captions, both pictures or caption data rather than text. They are counted
+ * because `declaredIndex` has to equal ffmpeg's `0:s:N`, and a track left out
+ * of the count shifts every text track after it, which is the very defect
+ * `declaredIndex` exists to remove.
+ */
+const SUBTITLE_HANDLERS = new Set([...TEXT_HANDLERS, "subp", "clcp"]);
 /** Sample formats this can turn into cues. `stpp` (TTML) is XML and is not one. */
 const TEXT_FORMATS = new Set(["tx3g", "text", "wvtt"]);
 
@@ -218,6 +227,11 @@ function sampleOffsets(moov, stsc, chunkOffsets, sizes) {
 /**
  * @typedef {object} Mp4SubtitleTrack
  * @property {number} trackId
+ * @property {number} declaredIndex - Its position among ALL of the file's
+ *   subtitle tracks, including the ones whose sample format this cannot turn
+ *   into cues (`stpp` TTML). That is the number ffmpeg gives the same stream in
+ *   `0:s:N`, which is the number the browser names; counting only the readable
+ *   ones would shift every track after a TTML one.
  * @property {string} format - `tx3g`, `text` or `wvtt`.
  * @property {string} language - Three letters, as the file declares them.
  * @property {Mp4SubtitleSample[]} samples - In time order.
@@ -246,6 +260,9 @@ export async function readMp4SubtitlePlan(readRange, fileSize) {
 
   /** @type {Mp4SubtitleTrack[]} */
   const tracks = [];
+  // Counts every subtitle track the file has, whether or not this can read it,
+  // so the number handed out matches ffmpeg's `0:s:N`. See `declaredIndex`.
+  let declaredIndex = -1;
   for (const trak of childrenOf(moov, moovBox.dataOffset, moov.length, "trak")) {
     const mdia = childOf(moov, trak.dataOffset, trak.end, "mdia");
     if (!mdia) {
@@ -253,6 +270,13 @@ export async function readMp4SubtitlePlan(readRange, fileSize) {
     }
     const hdlr = childOf(moov, mdia.dataOffset, mdia.end, "hdlr");
     const handler = hdlr ? moov.toString("latin1", hdlr.dataOffset + 8, hdlr.dataOffset + 12) : "";
+    if (!SUBTITLE_HANDLERS.has(handler)) {
+      continue;
+    }
+    // Counted before the readability checks below, and before the handler is
+    // narrowed to the text ones: this number is the track's place in the file,
+    // not its place among the tracks this code can turn into cues.
+    declaredIndex += 1;
     if (!TEXT_HANDLERS.has(handler)) {
       continue;
     }
@@ -337,7 +361,7 @@ export async function readMp4SubtitlePlan(readRange, fileSize) {
         });
       }
     }
-    tracks.push({ trackId, format, language, samples });
+    tracks.push({ trackId, declaredIndex, format, language, samples });
   }
   return { tracks };
 }

package/services/data-channel-handler.js

@@ -21,7 +21,7 @@
  * { type: "response-start", requestId, status, headers }   (JSON string)
  * { type: "response-error", requestId, error: string }     (JSON string)
  * { type: "pong",           id }                            (JSON string)
- * { type: "subtitle-cues",  fileIndex, trackIndex, cues, language } (JSON string)
+ * { type: "subtitle-cues",  fileIndex, trackIndex, cues, language, cursor } (JSON string)
  * ```
  * The last one is unsolicited — sent the moment new cues are read from a
  * file's already-downloaded pieces, to whichever channel last asked for that
@@ -385,10 +385,10 @@ export function createDataChannelHandler({ proxyPort, onLog, getTransportSnapsho
    * are tiny (kilobytes at most for a whole track), so this is one message,
    * not a stream.
    *
-   * @param {{ sourceKey: string, fileIndex: number, trackIndex: number, cues: object[], language: string }} event
+   * @param {{ sourceKey: string, fileIndex: number, trackIndex: number, cues: object[], language: string, cursor: number }} event
    * @returns {void}
    */
-  function publishSubtitleCues({ sourceKey, fileIndex, trackIndex, cues, language }) {
+  function publishSubtitleCues({ sourceKey, fileIndex, trackIndex, cues, language, cursor }) {
     const set = subtitleSubscribers.get(`${sourceKey}:${fileIndex}`);
     if (!set || set.size === 0) {
       log(
@@ -397,7 +397,7 @@ export function createDataChannelHandler({ proxyPort, onLog, getTransportSnapsho
       );
       return;
     }
-    const message = { type: "subtitle-cues", fileIndex, trackIndex, cues, language };
+    const message = { type: "subtitle-cues", fileIndex, trackIndex, cues, language, cursor };
     const total = set.size;
     let sent = 0;
     for (const channel of set) {

package/services/torrent-worker/client.js

@@ -194,7 +194,8 @@ export class TorrentWorkerClient {
             fileIndex: message.fileIndex,
             trackIndex: message.trackIndex,
             cues: message.cues,
-            language: message.language
+            language: message.language,
+            cursor: message.cursor
           });
           break;
         default:

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

@@ -30,6 +30,8 @@ const CLUSTER_HEADER_PROBE = 64;
  * reading it would be a large read for nothing.
  */
 const MAX_CLUSTER_BYTES = 32 * 1024 * 1024;
+/** How long a read of already-held bytes may take before it is given up. */
+const READ_ABANDON_MS = 30_000;
 
 /** @type {Map<string, { plan: object | null, harvested: Map<number, Set<number>>, cues: Map<number, object[]> }>} */
 const byFile = new Map();
@@ -78,9 +80,38 @@ function readHeld(file, start, end) {
       resolve(null);
       return;
     }
+    let settled = false;
+    /** @type {ReturnType<typeof setTimeout> | null} */
+    let abandon = null;
+    const settle = (value) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (abandon !== null) {
+        clearTimeout(abandon);
+      }
+      if (value === null) {
+        stream.destroy?.();
+      }
+      resolve(value);
+    };
+    // A read of bytes the torrent already holds either answers or it does not.
+    // This is not a measurement of anything and no figure is derived from it:
+    // it is the point past which such a read is presumed lost, so that one
+    // stream which never ends cannot hold this file's walk — and with it the
+    // browser's own request for its subtitles — for the rest of the session.
+    abandon = setTimeout(() => {
+      logger.info(
+        `subtitles: a read of ${start}-${end} in "${String(file.name).slice(0, 40)}" ` +
+        `did not finish in ${READ_ABANDON_MS / 1000}s and was given up`
+      );
+      settle(null);
+    }, READ_ABANDON_MS);
+    abandon.unref?.();
     stream.on("data", (chunk) => chunks.push(chunk));
-    stream.on("end", () => resolve(Buffer.concat(chunks)));
-    stream.on("error", () => resolve(null));
+    stream.on("end", () => settle(Buffer.concat(chunks)));
+    stream.on("error", () => settle(null));
   });
 }
 
@@ -97,10 +128,41 @@ function readHeld(file, start, end) {
  * @returns {Promise<object | null>}
  */
 async function planFor(torrent, fileIndex, key) {
+  const state = stateFor(key);
+  if (state.plan !== null) {
+    return state.plan;
+  }
+  // The head and the Cues table are two reads that DO wait on the swarm, so two
+  // callers arriving together would both make them. One promise, awaited by
+  // whoever asks while it is in flight.
+  if (!state.planPromise) {
+    state.planPromise = readPlan(torrent, fileIndex, state).finally(() => {
+      state.planPromise = null;
+    });
+  }
+  return state.planPromise;
+}
+
+/**
+ * The state kept for one file, created on first use.
+ *
+ * @param {string} key - `sourceKey:fileIndex`.
+ * @returns {object}
+ */
+function stateFor(key) {
   let state = byFile.get(key);
+  // A state that has been forgotten is not handed out again, even in the moment
+  // between the call and the walk that was still running finishing.
+  if (state?.forgotten === true) {
+    state = undefined;
+  }
   if (!state) {
     state = {
       plan: null,
+      planPromise: null,
+      forgotten: false,
+      // One walk of a file at a time — see `serialize`.
+      chain: Promise.resolve(),
       harvested: new Map(),
       cues: new Map(),
       seq: new Map(),
@@ -112,9 +174,45 @@ async function planFor(torrent, fileIndex, key) {
     };
     byFile.set(key, state);
   }
-  if (state.plan !== null) {
-    return state.plan;
-  }
+  return state;
+}
+
+/**
+ * Run `work` after every walk of this file already started, and before any
+ * started after it.
+ *
+ * Both entry points here — a browser's own pull and the warmup that runs ahead
+ * of it — mark a cluster as walked only AFTER reading and parsing it, which is
+ * two suspension points later. Until 2.56.0 nothing stopped a second call
+ * arriving in between: `warmActiveFiles` runs on every verified piece AND on a
+ * 3 s timer, so on a fast download the same cluster was read and parsed several
+ * times over and the same line could be pushed twice under different `seq`
+ * numbers. Each of those reads is a WebTorrent file stream, which selects and
+ * deselects its pieces, so the repetition reached the piece picker as well.
+ *
+ * @template T
+ * @param {object} state
+ * @param {() => Promise<T>} work
+ * @returns {Promise<T>}
+ */
+function serialize(state, work) {
+  const run = state.chain.then(work, work);
+  // The queue must survive a failed walk, so what is chained is the settled
+  // form; the caller still sees the rejection.
+  state.chain = run.then(() => undefined, () => undefined);
+  return run;
+}
+
+/**
+ * Read one file's subtitle plan — the tracks it declares and where the clusters
+ * holding them are. Called once per file; see `planFor`.
+ *
+ * @param {object} torrent
+ * @param {number} fileIndex
+ * @param {object} state
+ * @returns {Promise<object>}
+ */
+async function readPlan(torrent, fileIndex, state) {
   const file = torrent?.files?.[fileIndex];
   // `declared` is what the container itself says about its subtitle tracks, in
   // its own order. Empty means the container said nothing — which is a real
@@ -139,6 +237,7 @@ async function planFor(torrent, fileIndex, key) {
         ...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: "",
@@ -159,10 +258,13 @@ async function planFor(torrent, fileIndex, key) {
   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) — ` +
+      `subtitles: "${String(file.name).slice(0, 40)}" has ${state.plan.tracks.length} text track(s) ` +
+      `of ${state.plan.declared.length} declared — ` +
       state.plan.tracks
-        .map((track) => `${track.trackNumber}:${track.language || "?"}${track.name ? `/${track.name}` : ""}` +
-          `(${track.clusterPositions.length} indexed)`)
+        // `s:N` is the number the browser names (ffmpeg's own), and it differs
+        // from the file's track number whenever a picture track sits among them.
+        .map((track) => `s:${track.declaredIndex}=${track.trackNumber}:${track.language || "?"}` +
+          `${track.name ? `/${track.name}` : ""}(${track.clusterPositions.length} indexed)`)
         .join(" ")
     );
   }
@@ -206,11 +308,27 @@ function nextSeq(state, trackNumber) {
 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 state = stateFor(key);
   const track = plan?.tracks?.find((candidate) => candidate.trackNumber === trackNumber) ?? null;
   if (!track) {
     return { cues: [], coveredClusters: 0, indexedClusters: 0, track: null };
   }
+  return serialize(state, () => walkFor(torrent, fileIndex, state, plan, track, trackNumber));
+}
+
+/**
+ * The walk itself. Only ever entered through `cuesHeldFor`, which is what keeps
+ * one file to one walk at a time.
+ *
+ * @param {object} torrent
+ * @param {number} fileIndex
+ * @param {object} state
+ * @param {object} plan
+ * @param {object} track
+ * @param {number} trackNumber
+ * @returns {Promise<{ cues: object[], coveredClusters: number, indexedClusters: number, track: object | null }>}
+ */
+async function walkFor(torrent, fileIndex, state, plan, track, trackNumber) {
   const file = torrent.files[fileIndex];
   let harvested = state.harvested.get(trackNumber);
   if (!harvested) {
@@ -343,18 +461,20 @@ export async function cuesHeldFor(torrent, fileIndex, sourceKey, trackNumber) {
  * @param {string} sourceKey
  * @returns {Promise<{ trackIndex: number, cues: object[], language: string }[]>}
  *   One entry per track that gained at least one cue since the last call.
- *   `trackIndex` is the track's position among `plan.tracks` — the same
- *   indexing `/api/subtitles?trackIndex=` and the browser's menu use, NOT the
- *   container's own track number, which the browser never sees.
+ *   `trackIndex` is `declaredIndex` — the track's position among ALL the file's
+ *   subtitle tracks, which is ffmpeg's `0:s:N` and the only number the browser
+ *   knows. NOT the container's own track number, and not the position among the
+ *   readable tracks either: counting those alone puts every text track after a
+ *   picture-based one in the wrong place.
  */
 export async function warmSubtitleCues(torrent, fileIndex, sourceKey) {
   const key = `${sourceKey}:${fileIndex}`;
   const plan = await planFor(torrent, fileIndex, key);
-  const state = byFile.get(key);
+  const state = stateFor(key);
   const fresh = [];
   const tracks = plan?.tracks ?? [];
-  for (let trackIndex = 0; trackIndex < tracks.length; trackIndex += 1) {
-    const track = tracks[trackIndex];
+  for (let order = 0; order < tracks.length; order += 1) {
+    const track = tracks[order];
     const held = await cuesHeldFor(torrent, fileIndex, sourceKey, track.trackNumber);
     const since = state.pushed.get(track.trackNumber) ?? 0;
     const newCues = held.cues.filter((cue) => (Number(cue.seq) || 0) > since);
@@ -363,10 +483,21 @@ export async function warmSubtitleCues(torrent, fileIndex, sourceKey) {
     }
     const highest = newCues.reduce((max, cue) => Math.max(max, Number(cue.seq) || 0), since);
     state.pushed.set(track.trackNumber, highest);
+    const cues = finalizeCues(newCues, held.track?.codecId ?? track.codecId);
     fresh.push({
-      trackIndex,
-      cues: finalizeCues(newCues, held.track?.codecId ?? track.codecId),
-      language: held.track?.language ?? ""
+      // ffmpeg's own numbering, which is the only one the browser knows.
+      trackIndex: Number.isInteger(track.declaredIndex) ? track.declaredIndex : order,
+      cues,
+      language: held.track?.language ?? "",
+      // Where the browser should resume from if it has to ask again — after a
+      // reconnect, which loses the subscription these pushes ride on.
+      cursor: highest,
+      // What this batch is ABOUT, in film time, so a log can be read against
+      // the position being played.
+      spanStartSeconds: cues.length > 0 ? cues[0].startSeconds : null,
+      spanEndSeconds: cues.length > 0 ? cues[cues.length - 1].endSeconds : null,
+      walkedClusters: held.coveredClusters ?? 0,
+      indexedClusters: held.indexedClusters ?? 0
     });
   }
   return fresh;
@@ -430,8 +561,9 @@ function assDialogueToText(raw) {
  */
 export async function subtitleTracksOf(torrent, fileIndex, sourceKey) {
   const plan = await planFor(torrent, fileIndex, `${sourceKey}:${fileIndex}`);
-  return (plan?.tracks ?? []).map((track) => ({
+  return (plan?.tracks ?? []).map((track, order) => ({
     trackNumber: track.trackNumber,
+    declaredIndex: Number.isInteger(track.declaredIndex) ? track.declaredIndex : order,
     codecId: track.codecId,
     language: track.language,
     name: track.name,
@@ -471,10 +603,39 @@ export function forgetSubtitles(sourceKey, fileIndex) {
   if (fileIndex === undefined) {
     for (const key of [...byFile.keys()]) {
       if (key.startsWith(`${sourceKey}:`)) {
-        byFile.delete(key);
+        forgetOne(key);
       }
     }
     return;
   }
-  byFile.delete(`${sourceKey}:${fileIndex}`);
+  forgetOne(`${sourceKey}:${fileIndex}`);
+}
+
+/**
+ * Drop one file's state, but not while a walk of it is still running: the
+ * record of which clusters have been read lives in that state, and a walk left
+ * writing into a discarded copy while a new one starts beside it is the one
+ * path that defeats the serialization above.
+ *
+ * @param {string} key
+ * @returns {void}
+ */
+function forgetOne(key) {
+  const state = byFile.get(key);
+  if (!state) {
+    return;
+  }
+  // Held, so that a walk started before this call is not left orphaned; the
+  // entry is dropped the moment the queue empties, and nothing is handed this
+  // state in the meantime.
+  state.forgotten = true;
+  void state.chain.then(() => {
+    if (byFile.get(key) === state) {
+      byFile.delete(key);
+    }
+  }, () => {
+    if (byFile.get(key) === state) {
+      byFile.delete(key);
+    }
+  });
 }

package/services/torrent-worker/worker.js

@@ -522,12 +522,27 @@ function warmActiveFiles(sourceKey, torrent) {
     return;
   }
   for (const fileIndex of usage.keys()) {
+    const key = `${sourceKey}:${fileIndex}`;
+    // A trigger that arrives while the previous pass is still walking is
+    // dropped, not queued. `verified` fires per piece, so on a fast download
+    // these arrive many times a second; the walk is serialized per file anyway,
+    // and a queue of identical passes would only postpone the one that has
+    // something new to find.
+    if (warmupInFlight.has(key)) {
+      continue;
+    }
+    warmupInFlight.add(key);
     warmSubtitleCues(torrent, fileIndex, sourceKey)
       .then((fresh) => {
         for (const entry of fresh) {
+          const span = entry.spanStartSeconds === null
+            ? "empty"
+            : `${entry.spanStartSeconds.toFixed(1)}-${entry.spanEndSeconds.toFixed(1)}s`;
           log(
             `subtitle push ${sourceKey.slice(0, 8)}:${fileIndex} track ${entry.trackIndex}: ` +
-            `${entry.cues.length} new cue(s) found, posting to main thread`
+            `${entry.cues.length} new cue(s) covering ${span}, ` +
+            `clusters walked ${entry.walkedClusters}/${entry.indexedClusters}, cursor ${entry.cursor}, ` +
+            "posting to main thread"
           );
           parentPort.postMessage({
             type: Event.SUBTITLE_CUES_READY,
@@ -535,16 +550,27 @@ function warmActiveFiles(sourceKey, torrent) {
             fileIndex,
             trackIndex: entry.trackIndex,
             cues: entry.cues,
-            language: entry.language
+            language: entry.language,
+            cursor: entry.cursor
           });
         }
       })
       .catch((error) => {
         log(`subtitle warmup ${sourceKey}:${fileIndex} failed: ${error instanceof Error ? error.message : error}`);
+      })
+      .finally(() => {
+        warmupInFlight.delete(key);
       });
   }
 }
 
+/**
+ * Files whose warmup pass has not finished yet, by `sourceKey:fileIndex`.
+ *
+ * @type {Set<string>}
+ */
+const warmupInFlight = new Set();
+
 /**
  * Torrents already wired to warm their subtitle cues the moment a piece
  * verifies, so the same torrent is not listened to twice.

package/test/subtitle-track-numbering.test.js

@@ -0,0 +1,262 @@
+/**
+ * @file The number a subtitle track is asked for by, and one walk per file.
+ *
+ * Two rules, both found by reading on 2026-08-26 after the report that embedded
+ * subtitles appear late (`research/subtitle-delay-2026-08-26.md`):
+ *
+ * 1. The browser names a track by ffmpeg's `0:s:N`, which counts EVERY subtitle
+ *    stream. The container plan drops the picture-based ones — PGS, VobSub —
+ *    because they cannot become WebVTT, so counting the kept ones is a
+ *    different numbering as soon as a file carries one of each. What that cost:
+ *    the push landed on a track the browser does not know, and the browser's
+ *    own request found no track at all and fell through to the ffmpeg
+ *    extraction, which reads the whole film (752 s measured, 2026-08-19).
+ * 2. A file is walked once at a time. The walk marks a cluster as read only
+ *    after two suspension points, and it is started both on every verified
+ *    piece and on a 3 s timer, so two passes could read and parse the same
+ *    cluster and push the same line twice.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { Readable } from "node:stream";
+import { readSubtitlePlan } from "../services/container-index/matroska-subtitles.js";
+import { cuesHeldFor, forgetSubtitles } from "../services/torrent-worker/subtitle-cues.js";
+
+const ID_EBML = 0x1a45dfa3;
+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_LANGUAGE = 0x22b59c;
+const ID_CUES = 0x1c53bb6b;
+const ID_CUE_POINT = 0xbb;
+const ID_CUE_TIME = 0xb3;
+const ID_CUE_TRACK_POSITIONS = 0xb7;
+const ID_CUE_TRACK = 0xf7;
+const ID_CUE_CLUSTER_POSITION = 0xf1;
+const ID_CLUSTER = 0x1f43b675;
+const ID_TIMESTAMP = 0xe7;
+
+/** An element id, as the bytes the specification gives it. */
+function idBytes(id) {
+  const bytes = [];
+  let rest = id;
+  while (rest > 0) {
+    bytes.unshift(rest & 0xff);
+    rest = Math.floor(rest / 256);
+  }
+  return Buffer.from(bytes);
+}
+
+/** A size, as a four-byte EBML variable-length integer. */
+function sizeBytes(size) {
+  const buffer = Buffer.alloc(4);
+  buffer.writeUInt32BE(size, 0);
+  buffer[0] |= 0x10;
+  return buffer;
+}
+
+function element(id, payload) {
+  return Buffer.concat([idBytes(id), sizeBytes(payload.length), payload]);
+}
+
+function uintElement(id, value) {
+  const bytes = [];
+  let rest = value;
+  do {
+    bytes.unshift(rest & 0xff);
+    rest = Math.floor(rest / 256);
+  } while (rest > 0);
+  return element(id, Buffer.from(bytes));
+}
+
+function stringElement(id, value) {
+  return element(id, Buffer.from(value, "utf8"));
+}
+
+/**
+ * An unsigned value at a FIXED four bytes. A cue's cluster position has to be
+ * written twice — once to measure the table, once with the position that
+ * measurement produced — and a value-sized element would make the second table
+ * a different length from the first, moving the very cluster it names.
+ */
+function uint32Element(id, value) {
+  const payload = Buffer.alloc(4);
+  payload.writeUInt32BE(value, 0);
+  return element(id, payload);
+}
+
+function trackEntry({ number, type, codecId, language }) {
+  return element(ID_TRACK_ENTRY, Buffer.concat([
+    uintElement(ID_TRACK_NUMBER, number),
+    uintElement(ID_TRACK_TYPE, type),
+    stringElement(ID_CODEC_ID, codecId),
+    stringElement(ID_LANGUAGE, language)
+  ]));
+}
+
+/**
+ * A file whose subtitle tracks are, in the container's own order: a picture
+ * one, then two text ones. ffmpeg numbers those `0:s:0`, `0:s:1`, `0:s:2`;
+ * the plan can only read the last two.
+ *
+ * The Cues table points both text tracks at one cluster, which is written after
+ * the table so its position can be stated.
+ *
+ * @returns {{ file: Buffer, clusterAt: number }}
+ */
+function buildFile() {
+  const info = element(ID_INFO, uintElement(ID_TIMESTAMP_SCALE, 1_000_000));
+  const tracks = element(ID_TRACKS, Buffer.concat([
+    trackEntry({ number: 1, type: 1, codecId: "V_MPEG4/ISO/AVC", language: "und" }),
+    trackEntry({ number: 2, type: 17, codecId: "S_HDMV/PGS", language: "eng" }),
+    trackEntry({ number: 3, type: 17, codecId: "S_TEXT/UTF8", language: "rus" }),
+    trackEntry({ number: 4, type: 17, codecId: "S_TEXT/ASS", language: "eng" })
+  ]));
+
+  // Built twice: the cue points state where the cluster is, and that position
+  // is only known once everything before it has its final length. Every size
+  // and position here is written at a fixed width, so the draft and the final
+  // table are the same length.
+  const cuesWith = (clusterAt) => element(ID_CUES, Buffer.concat([
+    element(ID_CUE_POINT, Buffer.concat([
+      uintElement(ID_CUE_TIME, 1000),
+      element(ID_CUE_TRACK_POSITIONS, Buffer.concat([
+        uintElement(ID_CUE_TRACK, 3),
+        uint32Element(ID_CUE_CLUSTER_POSITION, clusterAt)
+      ])),
+      element(ID_CUE_TRACK_POSITIONS, Buffer.concat([
+        uintElement(ID_CUE_TRACK, 4),
+        uint32Element(ID_CUE_CLUSTER_POSITION, clusterAt)
+      ]))
+    ]))
+  ]));
+
+  const seekEntry = (targetId, position) => element(ID_SEEK, Buffer.concat([
+    element(ID_SEEK_ID, idBytes(targetId)),
+    element(ID_SEEK_POSITION, (() => {
+      const buffer = Buffer.alloc(4);
+      buffer.writeUInt32BE(position, 0);
+      return buffer;
+    })())
+  ]));
+  const seekHeadWith = (infoAt, tracksAt, cuesAt) => element(ID_SEEK_HEAD, Buffer.concat([
+    seekEntry(ID_INFO, infoAt),
+    seekEntry(ID_TRACKS, tracksAt),
+    seekEntry(ID_CUES, cuesAt)
+  ]));
+
+  const headLength = seekHeadWith(0, 0, 0).length;
+  const infoAt = headLength;
+  const tracksAt = infoAt + info.length;
+  const cuesAt = tracksAt + tracks.length;
+  // A position in the Cues table is measured from the Segment's payload, and so
+  // is the one the reader turns it into.
+  const clusterRelative = cuesAt + cuesWith(0).length;
+
+  // Enough of a cluster to be read and recognised: its own header and a
+  // timestamp. No blocks, so it yields no cues — what the walk test counts is
+  // that its bytes are fetched once, and that does not depend on their content.
+  const cluster = element(ID_CLUSTER, uintElement(ID_TIMESTAMP, 1000));
+
+  const segmentPayload = Buffer.concat([
+    seekHeadWith(infoAt, tracksAt, cuesAt),
+    info,
+    tracks,
+    cuesWith(clusterRelative),
+    cluster
+  ]);
+  const ebml = element(ID_EBML, Buffer.from([0x42, 0x86, 0x81, 0x01]));
+  const segment = element(ID_SEGMENT, segmentPayload);
+  const segmentDataOffset = ebml.length + segment.length - segmentPayload.length;
+  return {
+    file: Buffer.concat([ebml, segment]),
+    clusterAt: segmentDataOffset + clusterRelative
+  };
+}
+
+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 is numbered as ffmpeg numbers it, past the picture ones", async () => {
+  const { file } = buildFile();
+
+  const plan = await readSubtitlePlan(readerOver(file), file.length);
+
+  assert.equal(plan.declared.length, 3, "all three subtitle tracks are declared");
+  assert.deepEqual(plan.tracks.map((track) => track.trackNumber), [3, 4], "only the text ones are readable");
+  assert.deepEqual(
+    plan.tracks.map((track) => track.declaredIndex),
+    [1, 2],
+    "the PGS track is 0:s:0, so the text tracks are 0:s:1 and 0:s:2 — not 0 and 1"
+  );
+});
+
+/**
+ * A torrent holding one file entirely, counting the byte ranges read from it.
+ *
+ * @param {Buffer} bytes
+ * @returns {{ torrent: object, reads: Array<{ start: number, end: number }> }}
+ */
+function torrentOver(bytes) {
+  const reads = [];
+  const file = {
+    name: "film.mkv",
+    length: bytes.length,
+    offset: 0,
+    createReadStream({ start = 0, end = bytes.length - 1 } = {}) {
+      reads.push({ start, end });
+      // Asynchronous on purpose: a read that resolves in the same tick would
+      // hide exactly the interleaving this test is about.
+      return Readable.from((async function* chunks() {
+        await new Promise((resolve) => setImmediate(resolve));
+        yield bytes.subarray(start, end + 1);
+      })());
+    }
+  };
+  return {
+    reads,
+    torrent: {
+      pieceLength: 1024,
+      bitfield: { get: () => true },
+      files: [file]
+    }
+  };
+}
+
+test("two walks of one file at the same time read each cluster once", async () => {
+  const { file, clusterAt } = buildFile();
+  const { torrent, reads } = torrentOver(file);
+  const sourceKey = "torrent:numbering-test";
+  forgetSubtitles(sourceKey);
+
+  // Both text tracks at once, which is what the warmup does on every verified
+  // piece and every three seconds.
+  const [first, second] = await Promise.all([
+    cuesHeldFor(torrent, 0, sourceKey, 3),
+    cuesHeldFor(torrent, 0, sourceKey, 4)
+  ]);
+
+  assert.equal(first.coveredClusters, 1, "the cluster the table names was walked");
+  assert.equal(second.coveredClusters, 1, "and the second track sees the same walk, not its own");
+  const clusterReads = reads.filter((range) => range.start === clusterAt);
+  assert.equal(
+    clusterReads.length,
+    2,
+    "one probe of the cluster's header and one read of its body — not two of each"
+  );
+  forgetSubtitles(sourceKey);
+});