@torrent-tv/proxy 2.55.3 → 2.55.4

package/CHANGELOG.md

@@ -1,4 +1,6 @@
-## 2.55.3
+## 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/package.json

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

@@ -507,25 +507,67 @@ 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. 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();