@torrent-tv/proxy 2.11.0 → 2.12.1

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 2.12.1
+
+- **Fix**: The grid a copied stream is cut on now describes the FILE, not the container's index. A copy can only be cut where a keyframe already is, and nothing cheaper than the index can say where that is before a byte is encoded — but an index can be wrong. Reproduced 2026-08-12 against one file, both ways: with an honest index every produced segment started exactly where declared; with the index moved 1.8 s, every segment started 1.8 s early and matched no boundary at all. The field showed the second shape, so the mechanism was never at fault and the data was. The truth arrives anyway, one segment at a time — a produced piece states where it really begins — and it is now written back into the grid, which the whole family shares. That is what lets a re-encoded rung be cut to match a copied one: it is forced onto times the copy really uses. A correction that would cross its neighbours is refused, since that is a reading from a run that began somewhere else.
+- **Fix**: A warm-up is no longer cancelled by the stream that is still playing. The cancellation stood before the check for whether the active rung had actually changed, and the rung on screen asks for its own segments every few seconds — so the rung being prepared was stopped 117 ms and 1.5 s after two warm-ups began (measured 2026-08-12), and the viewer then waited out the full thirty-second warm-up for a segment nobody was making, and waited again for the switch. One switch took 43.6 s.
+- **Fix**: Warming the height the base session itself serves repositions it. It was skipped because it "is the base", but the base is parked wherever the viewer left it with its encoder stopped: warming 400p found it still at `run from #0`, so the switch had nothing to fetch.
+- **Fix**: Repositioning inside this class names the session it means. `requestSeek` forwards to the rung on screen, which is right for the browser — it knows only the base id — and wrong for everything internal: warming a rung moved the rung already playing instead. Split into the public forwarding call and an internal literal one.
+
+## 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.1",
   "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.
  *
@@ -1391,15 +1419,23 @@ export class HlsSessionManager {
       Array.isArray(keyframeTimes) &&
       keyframeTimes.length > 0 &&
       (!transcodeVideo || inheritedGrid != null);
-    const segmentBoundaries = hasDuration
-      ? computeSegmentBoundaries({
-          useKeyframeGrid,
-          durationSeconds,
-          segDur: this.segmentDurationSec,
-          keyframeTimes,
-          startTime: sourceStartTime
-        })
-      : [];
+    // A rung takes the grid it was handed, rather than working one out again
+    // from the same index. The two are not the same table: the one it is handed
+    // has been CORRECTED wherever a produced segment showed the index to be
+    // wrong, and it is those corrected times the copy actually cuts at. Building
+    // it afresh here would put the rung back on the index's fiction and undo the
+    // alignment it exists for.
+    const segmentBoundaries = Array.isArray(inheritedGrid?.boundaries) && inheritedGrid.boundaries.length > 1
+      ? [...inheritedGrid.boundaries]
+      : (hasDuration
+        ? computeSegmentBoundaries({
+            useKeyframeGrid,
+            durationSeconds,
+            segDur: this.segmentDurationSec,
+            keyframeTimes,
+            startTime: sourceStartTime
+          })
+        : []);
     const usingKeyframeBoundaries = useKeyframeGrid;
     const segmentCount = segmentBoundaries.length > 1 ? segmentBoundaries.length - 1 : 0;
 
@@ -1414,16 +1450,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 +1650,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"} ` : ""}` +
@@ -3315,7 +3362,27 @@ export class HlsSessionManager {
     // variants, so a seek it reports means the stream on screen.
     named.viewerPositionSeconds = positionSeconds;
     named.lastAccessedAt = Date.now();
-    const session = this.#activeVariant(named);
+    return this.#seekSession(this.#activeVariant(named), positionSeconds);
+  }
+
+  /**
+   * Reposition THIS session, with no forwarding.
+   *
+   * {@link requestSeek} exists for the browser, which names the base session and
+   * means the rung on screen. Everything inside this class means the session it
+   * is holding: warming a rung has to move THAT rung, and forwarding sent the
+   * seek to the one already playing instead — measured 2026-08-12, warming the
+   * base's own height moved the 540p rung and left the base parked at the start,
+   * so the switch had nothing to fetch.
+   *
+   * @param {HlsSession} session
+   * @param {number} positionSeconds
+   * @returns {boolean}
+   */
+  #seekSession(session, positionSeconds) {
+    if (!session || session.state === "disposed") {
+      return false;
+    }
     session.viewerPositionSeconds = positionSeconds;
     session.lastAccessedAt = Date.now();
     // Every segment request being held right now was made for the position the
@@ -3735,9 +3802,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
@@ -3746,6 +3822,115 @@ export class HlsSessionManager {
           : "the container's keyframe index disagrees with the file; using the file")
       );
     }
+    this.correctBoundaryFromSegment(session, index, trueStart);
+  }
+
+  /**
+   * Replace a boundary the index got wrong with the time the file actually has.
+   *
+   * The grid of a copied stream comes from the container's keyframe index,
+   * because a copy can only be cut where a keyframe already is and nothing
+   * cheaper than the index can say where that is before a single byte is
+   * encoded. An index can be wrong — proven 2026-08-12 by reproducing both
+   * cases against the same file: with an honest index every produced segment
+   * started exactly where declared, and with one moved 1.8 s the segments
+   * started 1.8 s early, matching no boundary at all. The field showed the
+   * second shape.
+   *
+   * The truth arrives anyway, one segment at a time: a produced piece states
+   * where it really begins. Writing it back makes the grid describe the file
+   * instead of the index — and it is what lets a re-encoded rung be cut to
+   * match a copied one, because the rung is then forced onto times the copy
+   * really uses. The alternative considered and rejected was to stop offering
+   * quality on files with a bad index, which is not a fix but a withdrawal.
+   *
+   * The whole family shares one grid, so a correction reaches all of it: a rung
+   * created afterwards inherits a table that is true wherever anyone has looked.
+   *
+   * @param {HlsSession} session
+   * @param {number} index
+   * @param {number} trueStart
+   * @returns {void}
+   */
+  correctBoundaryFromSegment(session, index, trueStart) {
+    const boundaries = session.segmentBoundaries;
+    if (!Array.isArray(boundaries) || index <= 0 || index >= boundaries.length - 1) {
+      // Index 0 is the start of the file and the last entry is its end; neither
+      // is a cut, and neither can be learned from a segment.
+      return;
+    }
+    if (Math.abs(boundaries[index] - trueStart) <= SEGMENT_START_DISAGREEMENT_SEC) {
+      return;
+    }
+    // A correction that would put this boundary at or past its neighbours is not
+    // a correction — it is a reading from a run that started somewhere else, and
+    // applying it would make the table describe nothing at all.
+    if (trueStart <= boundaries[index - 1] || trueStart >= boundaries[index + 1]) {
+      return;
+    }
+    const wasAt = boundaries[index];
+    for (const member of this.#familyOf(session)) {
+      if (Array.isArray(member.segmentBoundaries) && member.segmentBoundaries.length === boundaries.length) {
+        member.segmentBoundaries[index] = trueStart;
+      }
+    }
+    logger.info(
+      `transcode ${session.id} boundary #${index} corrected ${wasAt.toFixed(3)}s → ` +
+      `${trueStart.toFixed(3)}s from the file itself`
+    );
+  }
+
+  /**
+   * Every session cut on one grid: a base and its quality rungs.
+   *
+   * @param {HlsSession} session
+   * @returns {HlsSession[]}
+   */
+  #familyOf(session) {
+    const bases = session.variantBases instanceof Set
+      ? [...session.variantBases]
+      : [];
+    const roots = bases.length > 0 ? bases : [session.id];
+    const family = new Set([session]);
+    for (const rootId of roots) {
+      const root = this.sessionsById.get(rootId);
+      if (!root) {
+        continue;
+      }
+      family.add(root);
+      if (root.variants instanceof Map) {
+        for (const variantId of root.variants.values()) {
+          const variant = this.sessionsById.get(variantId);
+          if (variant) {
+            family.add(variant);
+          }
+        }
+      }
+    }
+    return [...family];
+  }
+
+  /**
+   * 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;
   }
 
   /**
@@ -4032,7 +4217,13 @@ export class HlsSessionManager {
       // be interchangeable with it. A base on the uniform grid needs nothing
       // passed: the variant computes the same even grid from the same duration.
       inheritedGrid: base.cutGrid === "keyframe"
-        ? { keyframeTimes: base.keyframeTimes, containerFormat: base.containerFormat }
+        ? {
+            // The table as it stands NOW, corrections included — not the index
+            // it was first built from.
+            boundaries: base.segmentBoundaries,
+            keyframeTimes: base.keyframeTimes,
+            containerFormat: base.containerFormat
+          }
         : null,
       acquireSource: base.acquireSource
     })
@@ -4133,6 +4324,74 @@ 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();
+    // Anything that is not the rung on screen has to be pointed at the switch
+    // position — INCLUDING the base. Skipping it because it is the base was a
+    // defect: the base is parked wherever it was when the viewer left it, and
+    // its encoder was stopped then. Measured 2026-08-12, warming 400p at
+    // 6506.5s found the base still at `run from #0`, so the segment the switch
+    // needed was never produced and the viewer got nothing at all.
+    if (variant.id !== this.#activeVariant(base).id) {
+      this.#seekSession(variant, 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.
    *
@@ -4149,8 +4408,27 @@ export class HlsSessionManager {
   #noteVariantActive(base, variant, wantedIndex = -1) {
     const previous = this.#activeVariant(base);
     if (previous.id === variant.id) {
+      // The rung on screen asking for more of itself, which it does every few
+      // seconds. Nothing is being decided here — and deciding anything was the
+      // defect: the warm-up was cancelled by the next segment the CURRENT rung
+      // fetched, measured 2026-08-12 at 117 ms and 1.5 s after two warm-ups
+      // began, so the rung being prepared was stopped before it had encoded
+      // anything and the viewer waited out the full thirty-second warm-up for a
+      // segment nobody was making, then waited again for the switch itself.
       return;
     }
+    // A rung is being left, so whatever was warmed is decided: either it is the
+    // rung now being switched to, or the viewer went somewhere else 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");
+      }
+    }
     const position = this.#variantStartSeconds(base, wantedIndex);
     base.activeVariantId = variant.id;
     logger.info(
@@ -4165,10 +4443,12 @@ export class HlsSessionManager {
     this.#stopEncodeRun(previous, `the viewer moved to ${this.variantHeightOf(variant)}p`);
     if (position > 0) {
       variant.viewerPositionSeconds = position;
-      // A variant just created already starts here, and requestSeek says so
-      // rather than restarting it. One that existed before is parked where it
-      // was left, and this is what brings it to the viewer.
-      this.requestSeek(variant.id, position);
+      // The rung being switched TO, named literally: a warm-up may have left
+      // the family pointing elsewhere, and forwarding would move that one
+      // instead. A rung just created already starts here and is told so rather
+      // than restarted; one that existed before is parked where it was left,
+      // and this is what brings it to the viewer.
+      this.#seekSession(variant, position);
     }
   }
 

package/test/keyframe-index-accuracy.test.js

@@ -56,6 +56,67 @@ test("a deviation within tolerance is not a disagreement, but still shows in the
   assert.equal(check.maxDeviationSec, 0.2, "and it is still worth knowing how close to the line it ran");
 });
 
+test("a boundary the index got wrong is replaced by the time the file really has", async (t) => {
+  const { HlsSessionManager } = await import("../services/hls-session-manager.js");
+  const manager = new HlsSessionManager({
+    enabled: true,
+    ffmpegBin: "ffmpeg",
+    localBindHost: "127.0.0.1",
+    localPort: 9090
+  });
+  t.after(() => manager.disposeAll());
+  const base = {
+    id: "aaaaaaaa-1111-2222-3333-444444444444",
+    fileName: "film.mkv",
+    state: "ready",
+    transcodeVideo: false,
+    segmentBoundaries: [0, 10, 20, 30, 40],
+    indexCheck: newIndexCheck(),
+    variants: new Map(),
+    segmentFormat: { segmentFileName: (index) => `segment-${index}.mp4` }
+  };
+  const rung = {
+    id: "bbbbbbbb-1111-2222-3333-444444444444",
+    fileName: "film.mkv",
+    state: "ready",
+    transcodeVideo: true,
+    segmentBoundaries: [0, 10, 20, 30, 40],
+    indexCheck: newIndexCheck(),
+    variantBases: new Set([base.id])
+  };
+  base.variants.set(540, rung.id);
+  manager.sessionsById.set(base.id, base);
+  manager.sessionsById.set(rung.id, rung);
+
+  // The copy produced segment #2, and it really begins at 17.4 s — the index
+  // said 20. This is the shape reproduced from the field on 2026-08-12.
+  manager.correctBoundaryFromSegment(base, 2, 17.4);
+
+  assert.equal(
+    base.segmentBoundaries[2],
+    17.4,
+    "the grid must describe the file, not the index — a rung forced onto 20 s would not join the copy"
+  );
+  assert.equal(
+    rung.segmentBoundaries[2],
+    17.4,
+    "the family shares one grid, so a correction reaches the rungs cut against it"
+  );
+  assert.deepEqual(
+    base.segmentBoundaries,
+    [0, 10, 17.4, 30, 40],
+    "only the boundary that was shown to be wrong moves"
+  );
+
+  // A reading that cannot be a boundary is not evidence about one. It comes
+  // from a run that started somewhere else, and applying it would leave the
+  // table describing nothing.
+  manager.correctBoundaryFromSegment(base, 2, 35);
+  manager.correctBoundaryFromSegment(base, 2, 5);
+  manager.correctBoundaryFromSegment(base, 0, 3);
+  assert.deepEqual(base.segmentBoundaries, [0, 10, 17.4, 30, 40], "out-of-order readings are refused");
+});
+
 test("a segment requested again is not new evidence", () => {
   const check = newIndexCheck();
 

package/test/quality-variants.test.js

@@ -283,6 +283,89 @@ 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 rung on screen fetching its own segments does not cancel a warm-up", 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 warmedEncoder = fakeEncoder();
+  variant.ffmpeg = warmedEncoder;
+  base.ffmpeg = fakeEncoder();
+  await manager.prepareVariant(BASE_ID, 540, 100);
+
+  // The viewer has not moved: the rung they are watching goes on asking for its
+  // own segments, every few seconds, for as long as they watch.
+  await manager.resolveVariantFile(BASE_ID, 812, "segment-00026.mp4");
+  await manager.resolveVariantFile(BASE_ID, 812, "segment-00027.mp4");
+
+  assert.equal(base.warmingVariantId, VARIANT_ID, "the rung being prepared is still being prepared");
+  assert.deepEqual(
+    warmedEncoder.signals,
+    [],
+    "cancelling it here left the viewer waiting out the whole warm-up for a segment nobody was making"
+  );
+});
+
+test("warming the height the base itself serves still points it at the switch", async (t) => {
+  const { manager, base, dirPath } = await managerWithBase();
+  t.after(async () => {
+    await manager.disposeAll();
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  // The viewer is on another rung; the base is parked where they left it, with
+  // its encoder stopped. Warming its height must bring it back.
+  const variant = fakeSession({ id: VARIANT_ID, encodeHeight: 540, dirPath });
+  variant.variantHeight = 540;
+  manager.sessionsById.set(VARIANT_ID, variant);
+  base.variants = new Map([[540, VARIANT_ID]]);
+  base.activeVariantId = VARIANT_ID;
+  base.ffmpeg = null;
+  base.encodeStartIndex = 0;
+
+  await manager.prepareVariant(BASE_ID, 812, 400);
+
+  // 400 s falls on the boundary between #99 and #100, and a run starts one
+  // segment back so the player has the preceding keyframe.
+  assert.equal(
+    base.seekTarget,
+    98,
+    "the base is parked at the start, so warming its height must reposition it like any other rung"
+  );
+});
+
 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 () => {