@torrent-tv/proxy 2.55.3 → 2.55.5

package/CHANGELOG.md

@@ -1,4 +1,11 @@
-## 2.55.3
+## 2.55.5
+
+- **New**: Subtitle cues are now PUSHED to the browser the moment they are read, over the WebRTC data channel — not fetched by the browser on a timer. Every declared track was already being warmed off the piece-`verified` event (2.55.4); what changed is that the result now travels to the browser unprompted instead of sitting on the proxy until the next poll asked for it. `data-channel-handler.js` remembers which channel last asked about a file's subtitles (piggy-backing on the browser's own first `/api/subtitles?trackIndex=` request — no separate subscribe message) and sends new cues there directly (`{ type: "subtitle-cues", fileIndex, trackIndex, cues, language }`), for every track the container declares, not only the one on screen. Rides the existing `proxy-control` data channel — the same one the request itself used, which is never the one carrying segment bytes, so a push cannot queue behind video. `finalizeCues` (end-time synthesis + ASS-dialogue stripping) is factored out of the HTTP route into `services/torrent-worker/subtitle-cues.js` so a pushed cue and a pulled one are built the same way. A browser's one-off seed fetch per track (for whatever is already read at the moment a file opens) and the external-subtitle-FILE path (`.srt`/`.ass` beside the video — a single whole-file read, no incremental delivery to begin with) are unchanged.
+- **Chore**: The push subscription only fires for an embedded-track request (`trackIndex` present) — an external subtitle file's request carries a different file's own index in `fileIndex` and was being registered under a key nothing ever publishes to. Harmless (the worker's plan for a non-container file is empty, so nothing was ever sent there), but pointless bookkeeping is still a bug waiting to be one.
+
+## 2.55.4
+
+- **Fix**: A file's subtitle cues are now walked the moment a piece verifies, not on a 3 s poll. The poll (2.55.3) closed the worst of it but still left every new cluster waiting up to 3 s after its piece arrived, and "waiting" at all was the thing objected to — a cue's readiness must not depend on which of two independent timers happens to fire first. `torrent.on("verified", …)` is WebTorrent's own signal for exactly this instant, set in the same place the bitfield itself is (`_markVerified`), so the walk now runs off the same event that makes a piece a piece rather than off a schedule. The 3 s poll stays as a fallback — it only matters for a listener attached after some pieces already verified, or if a `verified` handler ever throws — so nothing that used to be caught can now be missed.
 
 - **Fix**: A track's subtitle cues are now walked ahead of being asked for, instead of only when a browser first requests them. `cuesHeldFor` only ever read clusters on demand, inside the `/api/subtitles` request itself — cheap once caught up, but the FIRST call for a track had to walk the whole backlog of already-downloaded-but-unparsed clusters serially, with no `pending`/streaming pattern the way the ffmpeg fallback has one. On a film well into playback that backlog is not small (`Minions.and.Monsters.1080p.mkv` indexes over a thousand cluster positions per track), so a viewer who turned subtitles on after watching for a while waited on that catch-up instead of seeing cues appear at once — the opposite of the rule this file states its own reason for existing ("the region the viewer is watching is downloaded before they reach it, so its cues are ready before they are needed"): true of the DATA, not of when it got READ. A new periodic pass in the torrent worker (`warmSubtitleCues`, every 3 s, one per actively-read file) walks new clusters as they arrive, reusing `cuesHeldFor`'s own memoized state — a file nobody has opened costs nothing, and a file being watched is caught up by the time a track is switched on.
 

package/bin/cli.js

@@ -179,6 +179,9 @@ let udpPortMapper = null;
 /** @type {ReturnType<typeof createWebRtcManager> | null} */
 let webRtcManager = null;
 
+/** @type {ReturnType<typeof createDataChannelHandler> | null} */
+let dataChannelHandler = null;
+
 /** @type {import("../services/nat-classifier.js").NatClassification | null} Latest NAT classification (for WebRTC port prediction). */
 let natInfo = null;
 
@@ -289,7 +292,11 @@ try {
     maxDiskBytes,
     memoryBytes,
     segmentFormat: options.segmentFormat,
-    stateDir: options.stateDir
+    stateDir: options.stateDir,
+    // Late-bound the same way `webRtcManager` is below: the torrent pool is
+    // built inside `startProxyServer`, before `dataChannelHandler` — the
+    // thing that actually owns a channel to push down — exists.
+    onSubtitleCues: (event) => dataChannelHandler?.publishSubtitleCues(event)
   });
   app = started.app;
   actualPort = started.port;
@@ -411,7 +418,7 @@ try {
     onLog: (message) => logger.info(message)
   });
 
-  const dataChannelHandler = createDataChannelHandler({
+  dataChannelHandler = createDataChannelHandler({
     proxyPort: actualPort,
     onLog: (message) => logger.info(message),
     // Lets a stuck send queue ask the transport what it is doing. Late-bound:

package/package.json

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

package/routes/api/subtitles/get.js

@@ -27,6 +27,7 @@
 import { spawn } from "node:child_process";
 import { convertSubtitleToVtt, decodeSubtitleBytes } from "../../../services/subtitle-convert.js";
 import { detectLanguage } from "../../../services/language-detect.js";
+import { finalizeCues } from "../../../services/torrent-worker/subtitle-cues.js";
 import { logger } from "../../../utils/logger.js";
 
 // Safety cap: no embedded extraction may outlive this.
@@ -324,12 +325,10 @@ async function cuesFromDownloadedClusters(torrentPool, torrent, fileIndex, track
 }
 
 /**
- * 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.
+ * WebVTT from cues read out of the container. The end-time synthesis and ASS
+ * stripping are shared with the push path — see `finalizeCues` in
+ * `services/torrent-worker/subtitle-cues.js` — so a pulled cue and a pushed
+ * one read identically; this function only adds the WebVTT framing.
  *
  * @param {{ startSeconds: number, endSeconds: number | null, text: string }[]} cues
  * @param {string} codecId
@@ -337,39 +336,14 @@ async function cuesFromDownloadedClusters(torrentPool, torrent, fileIndex, track
  */
 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);
+  for (const cue of finalizeCues(cues, codecId)) {
+    lines.push(`${vttTime(cue.startSeconds)} --> ${vttTime(cue.endSeconds)}`);
+    lines.push(cue.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.
  *

package/server.js

@@ -80,7 +80,9 @@ function buildPortCandidates(startPort, maxAttempts = 51) {
  * @param {ProxyServerOptions} options
  * @returns {Promise<{ app: import("fastify").FastifyInstance, port: number }>}
  */
-export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin, maxDiskBytes, memoryBytes, segmentFormat, stateDir }) {
+export async function startProxyServer({
+  host, port, transcodeAudio, ffmpegBin, maxDiskBytes, memoryBytes, segmentFormat, stateDir, onSubtitleCues
+}) {
   const app = Fastify({
     // No practical body-size limit — the proxy server is localhost-only and
     // receives torrent source payloads that may be arbitrarily large.
@@ -112,7 +114,7 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin,
   // idled. Serving a segment shared that thread, so reading an already-finished
   // 10 MB file took 12-23 s against 125 ms to hand it to the channel. The
   // adapter keeps TorrentPool's interface, so nothing downstream changed.
-  const torrentPool = new WorkerTorrentPool({ maxDiskBytes, memoryBytes });
+  const torrentPool = new WorkerTorrentPool({ maxDiskBytes, memoryBytes, onSubtitleCues });
   const selectedPort = await getPort({
     port: buildPortCandidates(port)
   });

package/services/data-channel-handler.js

@@ -19,7 +19,11 @@
  * { 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)
  * ```
+ * 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
+ * file's subtitles over `/api/subtitles`. Not a response to any `requestId`.
  *
  * Response bodies are sent as BINARY data-channel messages (not JSON), to
  * avoid the ~33% base64 overhead and the JSON encode/decode cost. Each binary
@@ -296,6 +300,66 @@ export function encodeFrame(idBytes, bytes, done) {
 }
 
 export function createDataChannelHandler({ proxyPort, onLog, getTransportSnapshot }) {
+  /**
+   * Channels currently interested in one file's subtitle cues, keyed by
+   * `sourceKey:fileIndex`. Populated the moment a browser asks for an
+   * embedded track — there is no separate subscribe message on the wire, the
+   * existing `/api/subtitles` request already says which file a viewer opened
+   * subtitles for. Pruned on channel close and, defensively, on a failed send.
+   *
+   * @type {Map<string, Set<DataChannel>>}
+   */
+  const subtitleSubscribers = new Map();
+
+  /**
+   * @param {string} sourceKey
+   * @param {number} fileIndex
+   * @param {DataChannel} channel
+   * @returns {void}
+   */
+  function subscribeSubtitles(sourceKey, fileIndex, channel) {
+    const key = `${sourceKey}:${fileIndex}`;
+    let set = subtitleSubscribers.get(key);
+    if (!set) {
+      set = new Set();
+      subtitleSubscribers.set(key, set);
+    }
+    set.add(channel);
+  }
+
+  /** @param {DataChannel} channel */
+  function unsubscribeSubtitlesAll(channel) {
+    for (const set of subtitleSubscribers.values()) {
+      set.delete(channel);
+    }
+  }
+
+  /**
+   * Send new cues to every channel watching this file — the push side of
+   * subtitles arriving as they download rather than being polled for. Cues
+   * 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
+   * @returns {void}
+   */
+  function publishSubtitleCues({ sourceKey, fileIndex, trackIndex, cues, language }) {
+    const set = subtitleSubscribers.get(`${sourceKey}:${fileIndex}`);
+    if (!set || set.size === 0) {
+      return;
+    }
+    const message = { type: "subtitle-cues", fileIndex, trackIndex, cues, language };
+    for (const channel of set) {
+      try {
+        channel.sendMessage(JSON.stringify(message));
+      } catch {
+        // Closed between the subscription and this send; onClosed will not
+        // fire for a channel that is already gone, so drop it here too.
+        set.delete(channel);
+      }
+    }
+  }
+
   /** Request id → its ASCII bytes; see {@link requestIdBytes}. */
   const requestIdCache = new Map();
 
@@ -460,6 +524,7 @@ export function createDataChannelHandler({ proxyPort, onLog, getTransportSnapsho
         clearTimeout(entry.timer);
       }
       partials.clear();
+      unsubscribeSubtitlesAll(channel);
       log(`[dc] Session ${tag}: channel closed`);
     });
 
@@ -490,6 +555,25 @@ export function createDataChannelHandler({ proxyPort, onLog, getTransportSnapsho
       return;
     }
 
+    // Piggy-backs on the browser's own request for an EMBEDDED track — no
+    // separate subscribe message. `trackIndex` is what tells the two request
+    // shapes apart: an external subtitle FILE (no trackIndex) names a
+    // different file's own index in `fileIndex` — the subtitle file's, not the
+    // video's — and subscribing under that would just be a key nothing ever
+    // publishes to (an external file is one whole-file read, not something
+    // this walks incrementally). `fileIndex` alone would also scope this to
+    // the wrong grain for the real case — a torrent can carry several playable
+    // files — so the pair is what a push is ever addressed to.
+    if (path === "/api/subtitles" && typeof query === "string") {
+      const params = new URLSearchParams(query);
+      const sourceKey = params.get("sourceKey");
+      const fileIndex = Number(params.get("fileIndex"));
+      const hasTrackIndex = params.get("trackIndex") !== null && params.get("trackIndex") !== "";
+      if (sourceKey && Number.isInteger(fileIndex) && hasTrackIndex) {
+        subscribeSubtitles(sourceKey, fileIndex, channel);
+      }
+    }
+
     const queryInfo = query ? `?${query}` : "";
     const bodyInfo =
       body != null && typeof body === "string" && body.length > 0
@@ -698,7 +782,7 @@ export function createDataChannelHandler({ proxyPort, onLog, getTransportSnapsho
     }
   }
 
-  return { handleChannel };
+  return { handleChannel, publishSubtitleCues };
 }
 
 /**

package/services/torrent-worker/client.js

@@ -67,14 +67,18 @@ export class TorrentWorkerClient {
   /** Reads consuming fragments in place, keyed by request id. */
   #fragmentReaders = new Map();
 
+  /** @type {(event: { sourceKey: string, fileIndex: number, trackIndex: number, cues: object[], language: string }) => void} */
+  #onSubtitleCues;
+
   /**
-   * @param {{ maxDiskBytes?: number, memoryBytes?: number }} [options]
+   * @param {{ maxDiskBytes?: number, memoryBytes?: number, onSubtitleCues?: (event: object) => void }} [options]
    */
-  constructor({ maxDiskBytes, memoryBytes } = {}) {
+  constructor({ maxDiskBytes, memoryBytes, onSubtitleCues } = {}) {
     this.#worker = new Worker(fileURLToPath(WORKER_URL), {
       workerData: { maxDiskBytes, memoryBytes }
     });
     this.#caller = createCaller(this.#worker);
+    this.#onSubtitleCues = onSubtitleCues ?? (() => undefined);
 
     this.#worker.on("message", (message) => {
       // A failed read must fail its stream. This is checked BEFORE the caller
@@ -184,6 +188,15 @@ export class TorrentWorkerClient {
         case Event.LOG:
           logger.info(`torrent-worker: ${message.message}`);
           break;
+        case Event.SUBTITLE_CUES_READY:
+          this.#onSubtitleCues({
+            sourceKey: message.sourceKey,
+            fileIndex: message.fileIndex,
+            trackIndex: message.trackIndex,
+            cues: message.cues,
+            language: message.language
+          });
+          break;
         default:
           break;
       }

package/services/torrent-worker/protocol.js

@@ -103,7 +103,14 @@ export const Event = {
   /** The main thread consumed a chunk — see {@link STREAM_HIGH_WATER_CHUNKS}. */
   CHUNK_ACK: "chunk-ack",
   /** A log line, so worker output reaches the same place as everything else. */
-  LOG: "log"
+  LOG: "log",
+  /**
+   * New subtitle cues were read for one track, unprompted — the worker found
+   * them off its own `verified`-piece walk, not in answer to a
+   * {@link Command.SUBTITLE_CUES} call. Lets the main thread PUSH them to
+   * whichever browser is watching instead of waiting to be asked.
+   */
+  SUBTITLE_CUES_READY: "subtitle-cues-ready"
 };
 
 /**

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

@@ -99,7 +99,17 @@ function readHeld(file, start, end) {
 async function planFor(torrent, fileIndex, key) {
   let state = byFile.get(key);
   if (!state) {
-    state = { plan: null, harvested: new Map(), cues: new Map(), seq: new Map(), walked: new Set() };
+    state = {
+      plan: null,
+      harvested: new Map(),
+      cues: new Map(),
+      seq: new Map(),
+      walked: new Set(),
+      // The found-order cursor of the last cue PUSHED for each track, so a
+      // second warmup pass sends only what a first one did not — the same
+      // found-order idea `?since=` uses for a browser's own pull.
+      pushed: new Map()
+    };
     byFile.set(key, state);
   }
   if (state.plan !== null) {
@@ -318,25 +328,96 @@ export async function cuesHeldFor(torrent, fileIndex, sourceKey, trackNumber) {
 
 /**
  * Walk whatever clusters have newly arrived, for every text track a file
- * carries — so the browser's first request for a track finds its cues already
- * caught up instead of paying for the whole backlog inside that request.
+ * carries, and report what is new since the last call — so the cues can be
+ * PUSHED to a browser rather than left for it to come back and ask.
  *
  * `cuesHeldFor` already skips positions it has walked before (`state.walked`),
- * so calling this on a timer is cheap once a file is caught up: the only cost
- * is deciding there is nothing new to read. It is `getSubtitleCues` run ahead
- * of being asked, on the same state that call itself would build — nothing is
- * duplicated, and a browser that never asks costs nothing beyond this.
+ * so calling this on a timer or on every verified piece is cheap once a file
+ * is caught up: the only cost is deciding there is nothing new to read. It is
+ * `getSubtitleCues` run ahead of being asked, on the same state that call
+ * itself would build — nothing is duplicated, and a file nobody has opened
+ * costs nothing beyond this.
  *
  * @param {object} torrent
  * @param {number} fileIndex
  * @param {string} sourceKey
- * @returns {Promise<void>}
+ * @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.
  */
 export async function warmSubtitleCues(torrent, fileIndex, sourceKey) {
-  const plan = await planFor(torrent, fileIndex, `${sourceKey}:${fileIndex}`);
-  for (const track of plan?.tracks ?? []) {
-    await cuesHeldFor(torrent, fileIndex, sourceKey, track.trackNumber);
+  const key = `${sourceKey}:${fileIndex}`;
+  const plan = await planFor(torrent, fileIndex, key);
+  const state = byFile.get(key);
+  const fresh = [];
+  const tracks = plan?.tracks ?? [];
+  for (let trackIndex = 0; trackIndex < tracks.length; trackIndex += 1) {
+    const track = tracks[trackIndex];
+    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);
+    if (newCues.length === 0) {
+      continue;
+    }
+    const highest = newCues.reduce((max, cue) => Math.max(max, Number(cue.seq) || 0), since);
+    state.pushed.set(track.trackNumber, highest);
+    fresh.push({
+      trackIndex,
+      cues: finalizeCues(newCues, held.track?.codecId ?? track.codecId),
+      language: held.track?.language ?? ""
+    });
   }
+  return fresh;
+}
+
+/**
+ * Resolve a cue's end time and strip codec-specific formatting, turning a raw
+ * block-derived cue into text a player can show directly. The same step
+ * `routes/api/subtitles/get.js` applies when building WebVTT for a pull —
+ * factored out here so a pushed cue and a pulled one read identically.
+ *
+ * A cue with no duration — a SimpleBlock, which subtitles rarely use — is
+ * given the time until the next one IN THIS LIST, and the last such cue a few
+ * seconds. Not an invention about the film: it is what a player does with an
+ * open-ended cue, made explicit so every consumer agrees on it.
+ *
+ * @param {{ startSeconds: number, endSeconds: number | null, text: string }[]} cues
+ * @param {string} codecId
+ * @returns {{ startSeconds: number, endSeconds: number, text: string }[]}
+ */
+export function finalizeCues(cues, codecId) {
+  const isAss = codecId === "S_TEXT/ASS" || codecId === "S_TEXT/SSA";
+  const result = [];
+  cues.forEach((cue, index) => {
+    const next = cues[index + 1];
+    const endSeconds = cue.endSeconds ?? (next ? next.startSeconds : cue.startSeconds + 4);
+    const text = isAss ? assDialogueToText(cue.text) : cue.text.trim();
+    if (!text) {
+      return;
+    }
+    result.push({ startSeconds: cue.startSeconds, endSeconds, text });
+  });
+  return result;
+}
+
+/**
+ * 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();
 }
 
 /**

package/services/torrent-worker/worker.js

@@ -507,25 +507,82 @@ setInterval(() => {
   }
 }, STORE_REPORT_INTERVAL_MS).unref();
 
+/**
+ * Walk subtitle cues for every actively-read file of one torrent, and PUSH
+ * whatever came out new to the main thread — which is what makes a browser's
+ * copy current without it having asked.
+ *
+ * @param {string} sourceKey
+ * @param {object} torrent
+ * @returns {void}
+ */
+function warmActiveFiles(sourceKey, torrent) {
+  const usage = pool.fileUsageByTorrent.get(torrent);
+  if (!usage) {
+    return;
+  }
+  for (const fileIndex of usage.keys()) {
+    warmSubtitleCues(torrent, fileIndex, sourceKey)
+      .then((fresh) => {
+        for (const entry of fresh) {
+          parentPort.postMessage({
+            type: Event.SUBTITLE_CUES_READY,
+            sourceKey,
+            fileIndex,
+            trackIndex: entry.trackIndex,
+            cues: entry.cues,
+            language: entry.language
+          });
+        }
+      })
+      .catch((error) => {
+        log(`subtitle warmup ${sourceKey}:${fileIndex} failed: ${error instanceof Error ? error.message : error}`);
+      });
+  }
+}
+
+/**
+ * Torrents already wired to warm their subtitle cues the moment a piece
+ * verifies, so the same torrent is not listened to twice.
+ *
+ * @type {WeakSet<object>}
+ */
+const subtitleWarmupWired = new WeakSet();
+
+/**
+ * A piece becoming readable is the actual event a cue can be pulled from —
+ * "downloaded", not "about to be encoded or copied": what a viewer reaches is
+ * decided by the read window ahead of the playhead, not by which of the two
+ * paths a segment takes, and the piece exists (and is worth reading for
+ * subtitles) whichever one that is. `verified` is WebTorrent's own signal for
+ * exactly that instant, set at the same place the bitfield itself is (`
+ * _markVerified`), so nothing here is guessing at readiness a different way.
+ *
+ * @param {string} sourceKey
+ * @param {object} torrent
+ * @returns {void}
+ */
+function ensureSubtitleWarmupWired(sourceKey, torrent) {
+  if (subtitleWarmupWired.has(torrent)) {
+    return;
+  }
+  subtitleWarmupWired.add(torrent);
+  torrent.on("verified", () => warmActiveFiles(sourceKey, torrent));
+}
+
 /**
  * How often an actively-read file's subtitle cues are walked ahead of being
- * asked for. Cheap once caught up (`warmSubtitleCues` skips clusters it has
- * already read), so this can run often; every read.js pass is one it does not
- * have to do.
+ * asked for, as a fallback beside the per-piece `verified` listener above —
+ * catches a listener attached after pieces already verified, and anything the
+ * event path might otherwise miss. Cheap once caught up (`warmSubtitleCues`
+ * skips clusters it has already read).
  */
 const SUBTITLE_WARMUP_INTERVAL_MS = 3_000;
 
 setInterval(() => {
   for (const [sourceKey, torrent] of pool.torrents) {
-    const usage = pool.fileUsageByTorrent.get(torrent);
-    if (!usage) {
-      continue;
-    }
-    for (const fileIndex of usage.keys()) {
-      warmSubtitleCues(torrent, fileIndex, sourceKey).catch((error) => {
-        log(`subtitle warmup ${sourceKey}:${fileIndex} failed: ${error instanceof Error ? error.message : error}`);
-      });
-    }
+    ensureSubtitleWarmupWired(sourceKey, torrent);
+    warmActiveFiles(sourceKey, torrent);
   }
 }, SUBTITLE_WARMUP_INTERVAL_MS).unref();