@torrent-tv/proxy 2.65.0 → 2.66.1

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 2.64.10
+
+- **Fix**: When a re-encode cannot keep up and nothing LOWER is on offer, the budget asks for the COPY instead of leaving the viewer where they are. "Cheaper" in that rule meant "fewer pixels", and it had no way to express that a copied rung costs no encoder at all, whatever its size — so it looked down, found every rung below refused, and gave up. Field 2026-08-31 and it cost the whole film: a 444x240 ultrafast encode ran at 0.43-0.94x for fifty minutes while the source's own 1038p sat on offer beside it, copied and free; the line `nothing lower is on offer; leaving the picture alone` printed fifty times and the picture stood still 161 times for 940 seconds. On a copied source the way out is up, and it is both the fastest thing the host can serve and the best picture it has (`research/session-2026-08-31-seeks-and-the-copy.md`).
+
+## 2.66.0
+
+- **New**: A soundtrack that ships beside the picture is fetched WHOLE once the swarm has capacity to spare, so a later switch to it does not wait. It is a twentieth of the picture — 30 MB against 566 MB on the field torrent — and having it on disk is the difference between an instant switch and one that pays for its own first pieces. The moment it starts is not a guess about the swarm: it is when the encoder is already as far ahead of the viewer as `--lookahead` lets it get, which is the cushion figure the session already measures and prints. Once per file, and only for a soundtrack in a file of its own.
+- **Chore**: That fetch is a bounded READ of the file's length, deliberately not `file.select()`. Selecting a whole file alongside the readers' own moving windows is the mistake `#syncSelections` in `torrent-pool.js` was written against — a claim covering everything always outranked the window, and a seek to 89.1 % of a 4.7 GB film waited 93 s while the swarm fetched 2.47 GB in file order. The comment there records it; this goes through the same path the edge warm-up uses.
+
 ## 2.65.0
 
 - **New**: A soundtrack that ships as its own file beside the picture is offered like any other. Releases commonly put a dub in `Rus Sound/<name>.mka` and subtitles in `Sub/[team]/<name>.ass`; until now the video played with its original sound and nothing said the rest of the release existed. The pairing is by name — equal base names, or a shared release hash — and a torrent holding exactly one picture takes every sidecar beside it, since there is nothing else they could belong to. A torrent with several episodes never relaxes that: a wrong pairing would put the sound of one episode over the picture of another, and nothing downstream could notice.

package/package.json

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

package/server.js

@@ -192,7 +192,30 @@ export async function startProxyServer({
     getCachedMediaInfo: (params) => playbackPlanner.getCachedMediaInfo(params),
     // The file's audio tracks, for the master playlist's rendition group. Already
     // probed for the browser's audio menu; read from there rather than probed again.
-    getCachedAudioTracks: (params) => playbackPlanner.getCachedAudioTracks(params)
+    getCachedAudioTracks: (params) => playbackPlanner.getCachedAudioTracks(params),
+    // Pull one whole file onto the disk. Used for a soundtrack that ships beside
+    // the picture, once the encoder is as far ahead of the viewer as it is
+    // allowed to get — the one moment the swarm's capacity is demonstrably
+    // spare. A bounded read of the file's whole length, NOT `file.select()`:
+    // selecting a file alongside the readers' own windows is what made a seek
+    // wait 93 s while the swarm fetched 2.47 GB in file order (see
+    // `#syncSelections` in `torrent-pool.js`).
+    fetchWholeFile: async ({ sourceKey, fileIndex }) => {
+      const record = sourceRegistry.get(sourceKey);
+      if (!record) {
+        return;
+      }
+      const torrent = await torrentPool.getTorrent(record.sourceType, record.source);
+      const file = torrent?.files?.[fileIndex];
+      if (!file || !Number.isFinite(file.length) || file.length <= 0) {
+        return;
+      }
+      await torrentPool.prefetchFileEdges(torrent, fileIndex, {
+        headBytes: file.length,
+        tailBytes: 0,
+        timeoutMs: 600_000
+      });
+    }
   });
   const playbackPlanner = createPlaybackPlanner({
     ffmpegBin,

package/services/hls-session-manager.js

@@ -1626,6 +1626,7 @@ export class HlsSessionManager {
     tonemapSupported = false,
     getCachedMediaInfo = null,
     getCachedAudioTracks = null,
+    fetchWholeFile = null,
     segmentFormatId = undefined,
     stateDir = "",
     getTorrentTotals}) {
@@ -1645,6 +1646,12 @@ export class HlsSessionManager {
     // The file's audio tracks, for the master playlist's rendition group. Same
     // inventory the browser's audio menu is built from.
     this.getCachedAudioTracks = typeof getCachedAudioTracks === "function" ? getCachedAudioTracks : null;
+    // Fetch one whole file of a source, as a bounded read rather than a
+    // selection. Used to pull a soundtrack that ships beside the picture onto
+    // the disk while the swarm has capacity to spare — see
+    // `#fetchSpareSoundtracks`. Optional: a proxy wired without it simply reads
+    // such a soundtrack when it is played.
+    this.fetchWholeFile = typeof fetchWholeFile === "function" ? fetchWholeFile : null;
     // Optional async accessor for a source's live download stats, used by the
     // realtime budget to tell a CPU limit from a download-starved input:
     // (sourceKey, fileIndex) => Promise<{ downloadSpeed, fileLength, fileProgress } | null>.
@@ -3588,6 +3595,82 @@ export class HlsSessionManager {
         `${viewers} viewer(s) holding up to ` +
         `${deepestBuffer === null ? "?" : deepestBuffer.toFixed(1)}s`
     );
+    this.#fetchSpareSoundtracks(session, aheadOfPicture);
+  }
+
+  /**
+   * Fetch the soundtracks that ship beside this picture, whole, while the swarm
+   * has capacity to spare.
+   *
+   * WHY IT WAITS FOR THE CUSHION. A soundtrack nobody has chosen is worth having
+   * on disk — it is a twentieth of the picture (30 MB against 566 MB on the
+   * field torrent) and having it makes every later switch instant instead of
+   * paying for its first pieces. But fetching it takes swarm capacity from the
+   * picture, and there is exactly one moment when that capacity is demonstrably
+   * spare: when the encoder is already as far ahead of the viewer as it is
+   * allowed to get. That is not a guess about the swarm — it is the measurement
+   * the line above just printed.
+   *
+   * WHY IT IS A READ AND NOT A SELECTION. `file.select()` claims every piece of
+   * a file at once, and `#syncSelections` in `torrent-pool.js` records what that
+   * cost when it was done alongside the readers' own windows: a claim covering
+   * everything always outranked the window, and a seek to 89.1% of a 4.7 GB film
+   * waited 93 s while the swarm fetched 2.47 GB in file order. So this goes
+   * through the same bounded read the edge warm-up uses, which claims a moving
+   * window like any other reader and gives it back when it ends.
+   *
+   * Once per file, and only for a soundtrack in a file of its own — the
+   * picture's own tracks are already in the bytes being played.
+   *
+   * @param {HlsSession} session
+   * @param {number} aheadOfPicture - Seconds of film ready ahead of the viewer.
+   * @returns {void}
+   */
+  #fetchSpareSoundtracks(session, aheadOfPicture) {
+    if (typeof this.fetchWholeFile !== "function") {
+      return;
+    }
+    // The encoder is held at this distance and no further, so reaching it is the
+    // signal that nothing more is being asked of the swarm on the picture's
+    // behalf.
+    if (!(aheadOfPicture >= this.lookaheadSeconds)) {
+      return;
+    }
+    const inventory = this.getCachedAudioTracks?.({
+      sourceKey: session.sourceKey,
+      fileIndex: session.fileIndex
+    }) ?? [];
+    if (!(this.spareSoundtracksFetched instanceof Set)) {
+      this.spareSoundtracksFetched = new Set();
+    }
+    const wanted = new Set(
+      inventory
+        .filter((entry) => entry?.kind === "sidecar" && Number.isInteger(entry.fileIndex))
+        .map((entry) => entry.fileIndex)
+    );
+    for (const fileIndex of wanted) {
+      const key = `${session.sourceKey}:${fileIndex}`;
+      if (this.spareSoundtracksFetched.has(key)) {
+        continue;
+      }
+      this.spareSoundtracksFetched.add(key);
+      logger.info(
+        `transcode ${session.id.slice(0, 8)} the picture is ${Math.round(aheadOfPicture)}s ahead of ` +
+          `the viewer, so file ${fileIndex} — a soundtrack beside it — is fetched whole now; ` +
+          "a switch to it will not wait for the swarm"
+      );
+      // Not awaited: nothing depends on it finishing, and a failure costs only
+      // that the switch pays for its own pieces, as it did before this existed.
+      Promise.resolve(this.fetchWholeFile({ sourceKey: session.sourceKey, fileIndex })).catch(
+        (error) => {
+          logger.info(
+            `transcode: fetching soundtrack file ${fileIndex} whole failed ` +
+              `(${error instanceof Error ? error.message : String(error)}) — ` +
+              "it will be read when it is played"
+          );
+        }
+      );
+    }
   }
 
   /**
@@ -4357,6 +4440,27 @@ export class HlsSessionManager {
     const next = this.#splicableHeights(base)
       .find((height) => height < current && offered.includes(height));
     if (next === undefined) {
+      // Nothing lower — but "lower" is not the same question as "cheaper", and
+      // on a source that is COPIED the answer is above, not below. A copied
+      // rung costs no encoder at all, whatever its size, so when a re-encode
+      // cannot keep up it is both the fastest thing this host can serve AND the
+      // best picture it has.
+      //
+      // Field 2026-08-31, and it cost the viewer the whole film: an ultrafast
+      // 444x240 encode ran at 0.43-0.94x for fifty minutes while the source's
+      // own 1038p sat on offer beside it, copied and free. This line printed
+      // fifty times — "nothing lower is on offer; leaving the picture alone" —
+      // and the picture stood still 161 times for 940 seconds. The rescue was
+      // on the screen the whole time and the rule could only look down.
+      const copied = this.#copiedHeightOf(base);
+      if (copied > 0 && copied !== current && offered.includes(copied)) {
+        logger.info(
+          `[budget] transcode ${session.id} ${reasonText} at ${current}p and nothing lower is on offer, ` +
+            `but ${copied}p is COPIED on this file — no encoder at all, and a better picture. ` +
+            `Asking for it instead of leaving the viewer on an encode that cannot keep up`
+        );
+        return this.#askQualityHeight(base, copied, reasonText);
+      }
       logger.info(
         `[budget] transcode ${session.id} ${reasonText} at ${current}p, but nothing lower is on offer ` +
           `for "${session.fileName}"; leaving the picture alone`
@@ -4366,6 +4470,25 @@ export class HlsSessionManager {
     return this.#askQualityHeight(base, next, reasonText);
   }
 
+  /**
+   * The height this family serves by COPY, or zero when every rung is encoded.
+   *
+   * The one rung whose cost does not depend on the machine: the source's own
+   * height, on a base whose video is not re-encoded. `offeredHeights` never
+   * withdraws it for that reason, so it is always available as somewhere to
+   * return to — which is exactly what {@link HlsSessionManager##askLowerHeight}
+   * had no way to say.
+   *
+   * @param {HlsSession} base
+   * @returns {number}
+   */
+  #copiedHeightOf(base) {
+    if (!base || base.transcodeVideo === true) {
+      return 0;
+    }
+    return Math.round(Number(base.sourceHeight) || 0);
+  }
+
   /**
    * Record a request to the viewer's player to move to another variant.
    *