@torrent-tv/proxy 2.11.0 → 2.12.0

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 2.12.0
+
+- **Fix**: A rung warmed for a switch the viewer did not make is stopped. Only becoming active stopped the rung being left, so trying two rungs in a row left the first encoding for nobody — three encoders at once on a host sized for one, which is the opposite of what warming is for.
+- **Fix**: The warm-up closes the handle it opened. It answers without sending the bytes, and on formats whose segments are served straight off disk that left a file descriptor behind on every quality pick; enough of them and every read fails, segments included.
+
+- **New**: A quality rung is prepared before the player is told to switch to it — `GET /transcode/:id/v/:height/warm?position=<seconds>`. A rung is an encoder that does not exist until it is asked for, so switching first and waiting second put the whole of its cold start on screen as a spinner: measured 2026-08-11, the first segment of a 240p rung producing at 1.2x took 15 988 ms, and the viewer watched all of it. The rung on screen deliberately keeps its own encoder until the player actually moves, so the wait happens behind a picture that is still playing. Both encoders run for the length of the warm-up, which is what the switch costs to be invisible.
+- **Fix**: A viewer who names a resolution keeps the ladder beneath it. Forcing a rung disabled the realtime budget outright, so on 2026-08-11 a viewer picked 480p on a host that encodes it at 0.27-0.78x and the stream simply never caught up — nothing could step in, because the one thing that steps in had been switched off. The encode now STARTS at the size asked for and may still be stepped down under it. The rung's height is its name and does not move with a downshift, so the player goes on addressing it by the height it chose; what changes is the picture, and a smaller picture that plays beats a correct label that freezes.
+- **New**: When a produced segment starts somewhere other than the playlist says, the line now names which boundary it DOES fall on. The two possible faults need opposite fixes and the numbers alone do not separate them: matching boundary #N-1 means this proxy's own numbering is shifted, matching none means the container's index describes times the file does not have. Measured 2026-08-11 on a 1080p Matroska, three samples out by 3.5-4.6 s, all matching #N-1.
+
 ## 2.11.0
 
 - **Fix**: A quality change places the new rung where the PLAYER asked for it, not where the rung being left had read to. After a level switch hls.js discards what it had buffered ahead and fetches from the picture's own position, so its first request for the new rung IS that position; the read head is a whole buffer further on. Measured 2026-08-11 on a switch back up to 400p: a 240p rung encoding at 5-6x had read 56 s past the picture, the run was placed at 3084 s, the player needed 3028 s, and nothing it asked for was ever produced.

package/package.json

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

package/routes/transcode/session-file/get.js

@@ -140,7 +140,7 @@ export async function serveSessionFile(req, reply, { hlsSessionManager, sessionI
  * @param {number} timeoutMs
  * @returns {Promise<Awaited<ReturnType<import("../../../services/hls-session-manager.js").HlsSessionManager["getFileStream"]>>>}
  */
-async function waitForSessionFile(hlsSessionManager, sessionId, fileName, timeoutMs) {
+export async function waitForSessionFile(hlsSessionManager, sessionId, fileName, timeoutMs) {
   const startedAt = Date.now();
   // One sequence number for THIS request, reused by every poll below, so the
   // session can tell a newly-arrived request apart from an old one polling

package/routes/transcode/variant-warm/get.js

@@ -0,0 +1,71 @@
+/**
+ * @file GET /transcode/:sessionId/v/:height/warm?position=<seconds> — prepare a
+ * quality rung before the player is told to switch to it.
+ *
+ * A rung is an encoder that does not exist until someone asks for it, so a
+ * switch made first and waited for second shows the viewer a spinner for as
+ * long as the first segment takes to produce — 15 988 ms, measured 2026-08-11
+ * on a rung producing at 1.2x. Asking first and switching second moves that
+ * wait to where it cannot be seen: the rung on screen goes on playing, and it
+ * keeps its own encoder until the player actually moves.
+ *
+ * Answers when the segment at that position is ready, so the caller can switch
+ * knowing there is something to fetch.
+ */
+
+import { waitForSessionFile } from "../session-file/get.js";
+
+/** How long to hold the warm-up request before telling the caller to retry. */
+const WARM_WAIT_MS = 30_000;
+
+/**
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{ hlsSessionManager: import("../../../services/hls-session-manager.js").HlsSessionManager }} deps
+ * @returns {Promise<void>}
+ */
+export async function handleTranscodeVariantWarmGet(req, reply, { hlsSessionManager }) {
+  const baseSessionId = typeof req.params.sessionId === "string" ? req.params.sessionId : "";
+  const height = Number(req.params.height);
+  const positionSeconds = Number(req.query?.position);
+
+  if (!Number.isInteger(height) || height <= 0 || !Number.isFinite(positionSeconds) || positionSeconds < 0) {
+    return reply.code(400).send({ error: "A height and a non-negative position are required." });
+  }
+
+  let prepared;
+  try {
+    prepared = await hlsSessionManager.prepareVariant(baseSessionId, height, positionSeconds);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    reply.header("Retry-After", "1");
+    return reply.code(503).send({ error: `Could not prepare the quality variant: ${message}` });
+  }
+  if (!prepared) {
+    return reply.code(404).send({ error: "No such quality variant for this transcode session." });
+  }
+
+  const result = await waitForSessionFile(
+    hlsSessionManager,
+    prepared.sessionId,
+    prepared.fileName,
+    WARM_WAIT_MS
+  );
+  if (result.kind === "file") {
+    // The bytes are not sent — the player fetches them itself the moment it
+    // switches, and by then they are on disk — but the handle opened to reach
+    // them is ours to close. Some formats answer with a real file descriptor
+    // rather than bytes already in memory, and one left behind per quality pick
+    // walks a long-running proxy to EMFILE, where every read fails, segments
+    // included.
+    result.stream?.destroy?.();
+    return reply.code(204).send();
+  }
+  if (result.kind === "failed") {
+    return reply.code(500).send({ error: result.message });
+  }
+  // Still being produced. The caller may switch anyway — it will simply wait
+  // where it would have waited before — or ask again.
+  reply.header("Retry-After", "1");
+  return reply.code(503).send({ error: "The quality variant is still warming up." });
+}

package/server.js

@@ -30,6 +30,7 @@ import { handleApiTranscodeSessionSeekPost } from "./routes/api/transcode-sessio
 import { handleStreamGet } from "./routes/stream/get.js";
 import { handleTranscodeSessionFileGet } from "./routes/transcode/session-file/get.js";
 import { handleTranscodeVariantFileGet } from "./routes/transcode/variant-file/get.js";
+import { handleTranscodeVariantWarmGet } from "./routes/transcode/variant-warm/get.js";
 import { createSourceRegistry } from "./store/source-registry.js";
 import { WorkerTorrentPool } from "./services/torrent-worker/pool-adapter.js";
 import { HlsSessionManager } from "./services/hls-session-manager.js";
@@ -219,6 +220,12 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin,
   // A quality variant's files. Registered before the static handler for the
   // same reason as the line above, and kept a separate route rather than a
   // wildcard so the height stays a parsed parameter.
+  // Registered BEFORE the variant file route: `warm` is not a file name, and
+  // Fastify matches a static segment ahead of a parameter either way — stated
+  // here so the order is not "tidied" into a bug.
+  app.get("/transcode/:sessionId/v/:height/warm", async (req, reply) =>
+    handleTranscodeVariantWarmGet(req, reply, { hlsSessionManager })
+  );
   app.get("/transcode/:sessionId/v/:height/:fileName", async (req, reply) =>
     handleTranscodeVariantFileGet(req, reply, { hlsSessionManager })
   );

package/services/hls-session-manager.js

@@ -155,6 +155,34 @@ export function noteIndexDeviation(check, index, deviationSec) {
   }
 }
 
+/**
+ * The same budget, starting at the top of its own ladder.
+ *
+ * The automatic choice takes the highest rung this host can encode faster than
+ * realtime. A viewer who names a resolution has already made that choice, so
+ * the encode starts where they said — and the ladder stays, because a host that
+ * turns out unable to keep up must still have somewhere to go.
+ *
+ * @param {{ ladder: { width: number, height: number }[], rungIndex: number } | null} budget
+ * @param {number} outputFps
+ * @param {unknown} benchmark
+ * @returns {object | null}
+ */
+function startAtLadderTop(budget, outputFps, benchmark) {
+  const top = budget?.ladder?.[0];
+  if (!top) {
+    return null;
+  }
+  const fps = Number.isInteger(outputFps) && outputFps > 0 ? outputFps : TRANSCODE_FPS;
+  return {
+    ...budget,
+    width: top.width,
+    height: top.height,
+    preset: pickSoftwarePreset(benchmark, top.width * top.height * fps),
+    rungIndex: 0
+  };
+}
+
 /**
  * The consumer a base session registers on its variants.
  *
@@ -1414,16 +1442,23 @@ export class HlsSessionManager {
     // resolution, so encode exactly that box (capped to source by the scale
     // filter) with the default preset, and the runtime downswitch is skipped
     // for the session (budgetLadder stays null).
-    const encodeBudget = forceManualQuality
-      ? null
-      : this.#chooseEncodeBudget({
-          transcodeVideo,
-          targetWidth: normalizedTargetWidth,
-          targetHeight: normalizedTargetHeight,
-          sourceWidth,
-          sourceHeight,
-          outputFps
-        });
+    const chosenBudget = this.#chooseEncodeBudget({
+      transcodeVideo,
+      targetWidth: normalizedTargetWidth,
+      targetHeight: normalizedTargetHeight,
+      sourceWidth,
+      sourceHeight,
+      outputFps
+    });
+    // A forced resolution starts at exactly that size — the viewer asked for it
+    // — but KEEPS the ladder beneath it. Discarding the ladder is what left a
+    // viewer with no picture at all on 2026-08-11: they picked 480p on a host
+    // that encodes it at 0.27-0.78x, and with the runtime downshift disabled
+    // nothing could step in, so the stream simply never caught up. A smaller
+    // picture that plays beats a correct label that freezes. The rung's NAME is
+    // settled separately and does not move with a downshift, so the player goes
+    // on addressing it by the height it chose.
+    const encodeBudget = forceManualQuality ? startAtLadderTop(chosenBudget, outputFps, this.softwarePresetBenchmark) : chosenBudget;
     const softwarePreset = encodeBudget?.preset ?? null;
     // Effective encode box: the budget's downscaled resolution when applied,
     // otherwise the client target (0 = keep source, handled by buildVideoArgs).
@@ -1607,8 +1642,12 @@ export class HlsSessionManager {
         `${sourceWidth && sourceHeight ? `src=${sourceWidth}x${sourceHeight} ` : ""}` +
         // Effective encode resolution: budget-on (auto downscale from the
         // ceiling), manual (user-forced, budget off), or unset (keep source).
-        `${transcodeVideo && encodeBudget ? `enc=${encodeWidth}x${encodeHeight}@${outputFps} budget=on ` : ""}` +
-        `${transcodeVideo && forceManualQuality ? `enc=${encodeWidth || "src"}x${encodeHeight || "src"}@${outputFps} quality=manual ` : ""}` +
+        `${transcodeVideo && encodeBudget
+          ? `enc=${encodeWidth}x${encodeHeight}@${outputFps} ` +
+            `quality=${forceManualQuality ? "manual" : "auto"} ` +
+            `budget=${encodeBudget.ladder ? `rung ${encodeBudget.rungIndex + 1}/${encodeBudget.ladder.length}` : "off"} `
+          : ""}` +
+        `${transcodeVideo && !encodeBudget && forceManualQuality ? `enc=${encodeWidth || "src"}x${encodeHeight || "src"}@${outputFps} quality=manual budget=off ` : ""}` +
         // HDR source and whether the tone-map chain was applied (vs washed-out
         // fallback when the filters are missing or on a hardware encoder).
         `${transcodeVideo && mediaInfo.isHdr ? `hdr=1 tonemap=${applyTonemap ? "on" : "off"} ` : ""}` +
@@ -3735,9 +3774,18 @@ export class HlsSessionManager {
     session.indexCheck ??= newIndexCheck();
     noteIndexDeviation(session.indexCheck, index, deviation);
     if (deviation > SEGMENT_START_DISAGREEMENT_SEC) {
+      // Which boundary the true start DOES match, if any. This is what tells
+      // the two possible faults apart, and they need opposite fixes: matching
+      // boundary #N-1 means our numbering is shifted by one — a fault in this
+      // code, where the run begins — while matching nothing means the container
+      // index describes times the file does not have. Measured 2026-08-11,
+      // three samples all matched N-1, which is why the line now says so
+      // instead of leaving it to be inferred from the numbers.
+      const at = this.#boundaryIndexAt(session, trueStart);
       logger.warn(
         `transcode ${session.id} segment #${index} really starts at ` +
-        `${trueStart.toFixed(3)}s, the playlist says ${declaredStart.toFixed(3)}s — ` +
+        `${trueStart.toFixed(3)}s (boundary ${at === null ? "none" : `#${at}`}), ` +
+        `the playlist says ${declaredStart.toFixed(3)}s — ` +
         (session.transcodeVideo
           // A re-encode was TOLD to put a keyframe here and did not, so this
           // rung's segments no longer stand where the stream it accompanies
@@ -3748,6 +3796,29 @@ export class HlsSessionManager {
     }
   }
 
+  /**
+   * The boundary a time falls on, or null when it falls on none of them.
+   *
+   * Within the same tolerance a disagreement is judged by, so "matches boundary
+   * #N-1" and "matches nothing" mean what they say.
+   *
+   * @param {HlsSession} session
+   * @param {number} seconds
+   * @returns {number | null}
+   */
+  #boundaryIndexAt(session, seconds) {
+    const boundaries = session.segmentBoundaries;
+    if (!Array.isArray(boundaries)) {
+      return null;
+    }
+    for (let index = 0; index < boundaries.length; index += 1) {
+      if (Math.abs(boundaries[index] - seconds) <= SEGMENT_START_DISAGREEMENT_SEC) {
+        return index;
+      }
+    }
+    return null;
+  }
+
   /**
    * What this session learned about its container's keyframe index, as one
    * line, at the end.
@@ -4133,6 +4204,68 @@ export class HlsSessionManager {
     return { sessionId: variant.id };
   }
 
+  /**
+   * Prepare a rung the viewer is about to switch to, without switching to it.
+   *
+   * The rung does not exist until it is asked for, so the moment the player is
+   * told to switch it has nothing to fetch and the viewer watches a spinner
+   * while an encoder starts from nothing — measured 2026-08-11 at 15 988 ms for
+   * the first segment of a rung producing at 1.2x. Nothing can make that
+   * production instant; what CAN be done is to have it happen while the rung
+   * the viewer is on is still playing.
+   *
+   * So this creates and positions the variant and says which segment to wait
+   * for, and deliberately does NOT mark it active: the rung on screen keeps its
+   * encoder until the player actually moves. Both encoders run for the length
+   * of the warm-up, which is the price of the switch not being visible.
+   *
+   * @param {string} baseSessionId
+   * @param {number} height
+   * @param {number} positionSeconds - Where the switch will happen.
+   * @returns {Promise<{ sessionId: string, fileName: string } | null>}
+   */
+  async prepareVariant(baseSessionId, height, positionSeconds) {
+    if (!isSafeSessionId(baseSessionId)) {
+      return null;
+    }
+    const base = this.sessionsById.get(baseSessionId);
+    if (!base || base.state === "disposed") {
+      return null;
+    }
+    if (!this.#variantHeights(base).includes(height)) {
+      return null;
+    }
+    const index = this.#segmentIndexForTime(base, positionSeconds);
+    const variant = await this.resolveVariantSession(baseSessionId, height, index);
+    if (!variant) {
+      return null;
+    }
+    // A rung warmed for a switch that was never made. Nothing else would ever
+    // stop it: only becoming active stops the rung being left, so a viewer
+    // trying two rungs in a row would leave the first encoding for nobody until
+    // the look-ahead cap suspended it — three encoders at once on a host sized
+    // for one, which is the opposite of what warming is for.
+    const stillWarming = base.warmingVariantId;
+    if (stillWarming && stillWarming !== variant.id) {
+      const abandoned = this.sessionsById.get(stillWarming);
+      if (abandoned && abandoned.id !== this.#activeVariant(base).id) {
+        this.#stopEncodeRun(abandoned, "warmed for a switch the viewer did not make");
+      }
+    }
+    base.warmingVariantId = variant.id === base.id ? null : variant.id;
+    // An existing rung may be parked wherever it was left, so it is pointed at
+    // the switch position exactly as an activation would — the difference is
+    // only that the rung on screen keeps its own encoder meanwhile.
+    variant.lastAccessedAt = Date.now();
+    if (variant.id !== base.id) {
+      this.requestSeek(variant.id, this.#segmentStartTime(base, index));
+    }
+    logger.info(
+      `transcode ${base.id} warming ${height}p at ${positionSeconds.toFixed(1)}s (segment #${index})`
+    );
+    return { sessionId: variant.id, fileName: variant.segmentFormat.segmentFileName(index) };
+  }
+
   /**
    * Record which variant the viewer is watching, and give it the encoder.
    *
@@ -4148,6 +4281,18 @@ export class HlsSessionManager {
    */
   #noteVariantActive(base, variant, wantedIndex = -1) {
     const previous = this.#activeVariant(base);
+    // Whatever was warmed is decided now: either it is the rung being switched
+    // to, or the viewer went elsewhere and it must stop like any other rung
+    // nobody is watching. Nothing else would ever stop it — only the rung being
+    // LEFT is stopped below.
+    const warmed = base.warmingVariantId;
+    base.warmingVariantId = null;
+    if (warmed && warmed !== variant.id && warmed !== previous.id) {
+      const abandoned = this.sessionsById.get(warmed);
+      if (abandoned) {
+        this.#stopEncodeRun(abandoned, "warmed for a switch the viewer did not make");
+      }
+    }
     if (previous.id === variant.id) {
       return;
     }

package/test/quality-variants.test.js

@@ -283,6 +283,33 @@ test("a rung is placed where the player asked it for, not where the other rung h
   );
 });
 
+test("warming a rung prepares it without taking the encoder from the one on screen", async (t) => {
+  const { manager, base, dirPath } = await managerWithBase();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  const variant = fakeSession({ id: VARIANT_ID, encodeHeight: 540, dirPath });
+  variant.variantHeight = 540;
+  variant.variantBases = new Set([BASE_ID]);
+  manager.sessionsById.set(VARIANT_ID, variant);
+  base.variants = new Map([[540, VARIANT_ID]]);
+  const encoder = fakeEncoder();
+  base.ffmpeg = encoder;
+
+  const prepared = await manager.prepareVariant(BASE_ID, 540, 240);
+
+  assert.deepEqual(
+    prepared,
+    { sessionId: VARIANT_ID, fileName: "segment-00060.mp4" },
+    "the caller is told which segment to wait for — 240 s on a four-second grid"
+  );
+  assert.equal(variant.seekTarget, 59, "the rung is pointed at the switch position, one back for the keyframe");
+  assert.equal(base.activeVariantId, undefined, "nothing has switched yet");
+  assert.equal(base.ffmpeg, encoder, "the picture on screen keeps its encoder until the player actually moves");
+  assert.deepEqual(encoder.signals, [], "stopping it here is what would put the spinner back");
+});
+
 test("the viewer's position is kept current by the segments they ask for", async (t) => {
   const { manager, base, dirPath } = await managerWithBase();
   t.after(async () => {