@torrent-tv/proxy 2.55.4 → 2.55.5

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 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.

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.4",
+  "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

@@ -508,7 +508,9 @@ setInterval(() => {
 }, STORE_REPORT_INTERVAL_MS).unref();
 
 /**
- * Walk subtitle cues for every actively-read file of one torrent.
+ * 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
@@ -520,9 +522,22 @@ function warmActiveFiles(sourceKey, torrent) {
     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}`);
-    });
+    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}`);
+      });
   }
 }