@torrent-tv/proxy 2.55.2 → 2.55.4

package/CHANGELOG.md

@@ -1,4 +1,8 @@
-## 2.55.2
+## 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.
 
 - **Fix**: The decode pipe's sanity log carried a fixed editorial line — "a reading where these are far apart is worth a second look" — printed on every single reading regardless of whether the two figures actually were, which was noise the first time it ran in the field. The comparison is also now taken over the same window the speed itself is (bytes are snapshotted alongside each progress sample), rather than over the whole run from process start, which read systematically low for no reason but that mismatch. The line only says "worth a second look" when the two figures are actually more than 1.5x apart.
 

package/package.json

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

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

@@ -316,6 +316,29 @@ 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.
+ *
+ * `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.
+ *
+ * @param {object} torrent
+ * @param {number} fileIndex
+ * @param {string} sourceKey
+ * @returns {Promise<void>}
+ */
+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);
+  }
+}
+
 /**
  * The text subtitle tracks of a file, for the menu the viewer sees.
  *

package/services/torrent-worker/worker.js

@@ -27,7 +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, declaredSubtitleTracksOf, subtitleTracksOf } from "./subtitle-cues.js";
+import { cuesHeldFor, declaredSubtitleTracksOf, subtitleTracksOf, warmSubtitleCues } from "./subtitle-cues.js";
 import { Command, Event } from "./protocol.js";
 
 // Imported dynamically, and that is load-bearing: static imports are RESOLVED
@@ -507,4 +507,68 @@ setInterval(() => {
   }
 }, STORE_REPORT_INTERVAL_MS).unref();
 
+/**
+ * Walk subtitle cues for every actively-read file of one torrent.
+ *
+ * @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).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, 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) {
+    ensureSubtitleWarmupWired(sourceKey, torrent);
+    warmActiveFiles(sourceKey, torrent);
+  }
+}, SUBTITLE_WARMUP_INTERVAL_MS).unref();
+
 log("torrent worker started");