@torrent-tv/proxy 2.9.90 → 2.9.92

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 2.9.92
+
+- **Fix**: A seek acts on what the viewer asked for, instead of waiting out guards built for a signal that no longer exists. Three delays sat in front of every seek, all of them there because a far segment REQUEST used to steer the encoder and the player's playlist scan produced dozens of them. Requests stopped steering anything when the position became explicit, so what arrives now is only ever a position the viewer stated. The settle window drops from 1.2 s to 300 ms (the browser already collapses a drag into one report at 300 ms — this was a second debounce on an already-debounced signal, and it cost 1.2 s of every measured seek). The floor between restarts drops from 4 s to 500 ms, now a guard against a client spamming the endpoint rather than a policy about noise. And a run in progress is no longer protected for up to 30 s while it reaches its first segment: finishing a segment for a position the viewer has left is work nobody wants, and the hold could delay a genuine second seek by the whole grace. Measured cost of the old behaviour, 2026-08-04: two seeks 1.3 s apart produced two restarts 4.4 s apart, the first encoding 119.5 s of content before the second killed it.
+- **Chore**: Removed `ENCODER_STALL_MS`, declared with a paragraph describing a watchdog that was never wired to anything.
+
+## 2.9.91
+
+- **Fix**: The encoder no longer runs away from the viewer. Nothing bounded how far ahead it produced: measured 2026-08-04, three minutes after a film was opened the encode had reached 00:39:24 of a 01:26:51 source at 12.8x while the viewer was still at the start, and the torrent had pulled 80% of 4.7 GB to feed it — the pool owner's bandwidth and disk spent on a viewer who may watch two minutes, the pieces being read evicted from memory by pieces forty minutes ahead, and the swarm busy with anything but the segment being waited for. An encoder more than two minutes of content ahead of the last segment its viewer asked for is now **suspended**, and released once the viewer is within a minute of it — or at once when a segment is requested. Suspended rather than killed on purpose: restarting costs about nine seconds on this hardware, so a viewer reaching the end of the produced range would stall every time, while suspending keeps the process, its input and its position. POSIX only; where `SIGSTOP` does not exist the attempt fails once, is logged, and that session keeps the old behaviour. Every path that terminates an encoder now releases it first — a suspended process does not act on `SIGTERM` until it is continued, which would have hung the wait a seek performs before starting its replacement.
+- **New**: A reader reports what it waited for. When a read blocks a second or more on a piece, the log names the piece, its position in the read, and the offset the read started at. The first segment after a seek-restart costs 9.2-9.4 s and there was no way to tell whether that is the swarm, the piece picker or ffmpeg; now there is.
+
 ## 2.9.90
 
 - **New**: The output container is chosen per session, by the viewer, instead of once per proxy. `POST /api/transcode-sessions` accepts `segmentFormat`; `--segment-format` remains the default for a client that expresses no preference, and an unrecognised value falls back to it rather than to the library default. The browser is the only party that knows what its media stack will accept for the tracks it asked to be copied: a copied MP3 track cannot be appended from fMP4 at all (`audio/mp4; codecs="mp4a.69"` is refused by MediaSource) but works from MPEG-TS, which hls.js demuxes itself and hands to a plain `audio/mpeg` buffer — the same file, the same browser, silent loop one way and normal playback the other. Sessions are keyed by container too, so two viewers wanting different ones do not share an encoder. Nothing branches on the format outside `services/segment-formats/`; the manager now reads it off the session.

package/package.json

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

package/services/hls-session-manager.js

@@ -43,26 +43,32 @@ const DEFAULT_SEGMENT_DURATION_SEC = 4;
 // is allowed to be before we restart ffmpeg at that position (server-side seek).
 // Requests within the window are served by waiting for the running encode.
 const MAX_LOOKAHEAD_SEGMENTS = 8;
-// After a seek-restart, ignore competing restart requests for this long. The
-// synthetic VOD playlist lets the player request distant segments in quick
-// succession (stall-recovery seeks); without a cooldown ffmpeg ping-pongs
-// between positions, restarting endlessly and producing nothing.
-const RESTART_COOLDOWN_MS = 4_000;
-// How long a seek restart waits for the CURRENT run to produce its first
-// segment before it is allowed to pre-empt it anyway. Generous, because the
-// first segment after a seek is the slowest thing this pipeline does (ffmpeg
-// restart + torrent pieces for a fresh position); still bounded so a wedged
-// run cannot block seeking forever. See #fireSettledSeek.
-const RUN_FIRST_SEGMENT_GRACE_MS = 30_000;
-// Encoder stall watchdog. A running ffmpeg emits `-progress` output on stdout
-// continuously while it encodes; when it hangs mid-file (alive, but producing
-// no output and no stderr — a deadlock, e.g. a stalled input read), that output
-// stops and `progress.updatedAt` freezes. If a segment INSIDE the look-ahead
-// window is being demanded but progress has not advanced for this long, the
-// encoder is wedged (observed: the segment 503s forever). Treat it like a seek
-// and restart ffmpeg at the demanded segment. Conservative — a slow-but-moving
-// encode keeps advancing `updatedAt`, so this only fires on a true freeze.
-const ENCODER_STALL_MS = 12_000;
+// Floor between actual restarts. It used to be 4 s, from when a far segment
+// REQUEST could steer the encoder and a playlist scan produced a burst of them.
+// Requests no longer steer anything (see #ensureEncodingFor) — every restart
+// now comes from a position the viewer stated — so this is no longer a policy
+// about noise, only a guard against a client that spams the seek endpoint.
+// Measured cost of the old value 2026-08-04: two seeks 1.3 s apart produced two
+// restarts 4.4 s apart, the first encoding 119.5 s of content nobody wanted
+// before the second killed it.
+const RESTART_COOLDOWN_MS = 500;
+// How far ahead of the viewer the encoder may run before it is stopped, and how
+// far it must fall back to before it is let go again.
+//
+// Nothing used to bound this. Measured 2026-08-04 on the copy path: three
+// minutes after a film was opened the encode had reached 00:39:24 of a 01:26:51
+// source at 12.8x while the viewer was still at the start, and the torrent had
+// pulled 80% of 4.7 GB to feed it. That costs the pool owner's bandwidth and
+// disk for a viewer who may watch two minutes, evicts from memory the pieces
+// the viewer is actually reading, and competes for the swarm with the segment
+// being waited on.
+//
+// In seconds of content rather than segments, because a segment is 4 s of
+// re-encoded video but a whole keyframe interval on the copy path. Generous
+// enough that ordinary watching never touches it: the encoder fills two minutes
+// ahead, stops, and is released as soon as the viewer has spent a minute of it.
+const LOOKAHEAD_PAUSE_SECONDS = 120;
+const LOOKAHEAD_RESUME_SECONDS = 60;
 // Seek debounce. A far (out-of-window) segment request is a server-side seek.
 // Rather than restart ffmpeg on the first one, wait a short quiet period:
 // further far requests re-arm it and update the target to the latest index, so
@@ -84,10 +90,17 @@ const ENCODER_STALL_MS = 12_000;
 // encoding 125 s of content before reaching the viewer's position. Field
 // 2026-08-02: a seek took 56 s, of which ~50 s was this backoff.
 const SEEK_BACKOFF_SEGMENTS = 1;
-const SEEK_SETTLE_MS = 1_200;
-// Hard cap on the total settle wait, measured from the first far request of a
+// How long to wait for a scrub to stop moving before acting on it. Small,
+// because the browser already collapses a drag into ONE report
+// (`SEEK_REPORT_DEBOUNCE_MS`, 300 ms) and only reports where it settled — this
+// is a second debounce on an already-debounced signal, and every millisecond of
+// it is dead time in front of the viewer. It was 1.2 s when the encoder was
+// also steered by segment requests, which arrive in bursts of dozens; measured
+// 2026-08-04, that cost 1.2 s of every seek.
+const SEEK_SETTLE_MS = 300;
+// Hard cap on the total settle wait, measured from the first request of a
 // burst, so a still-moving scrubber cannot delay a genuine seek forever.
-const SEEK_SETTLE_MAX_MS = 2_500;
+const SEEK_SETTLE_MAX_MS = 1_000;
 // Grace period to wait for the PREVIOUS ffmpeg process to exit (per signal
 // escalation step: SIGTERM, then SIGKILL) before spawning its replacement into
 // the same session directory. See #startEncodeRun.
@@ -787,6 +800,7 @@ export class HlsSessionManager {
     // benchmark (the only path that can pick/step resolution). Cheap no-op scan
     // otherwise.
     this.budgetTimer = setInterval(() => {
+      this.#enforceLookAhead();
       void this.#enforceRealtimeBudget();
     }, BUDGET_CHECK_INTERVAL_MS);
     this.budgetTimer.unref();
@@ -1160,6 +1174,12 @@ export class HlsSessionManager {
       // Bumped by every viewer seek; a held segment request that started under
       // an older value gives up at once. See requestSeek.
       waitEpoch: 0,
+      // Highest segment the viewer has actually asked for, and whether the
+      // encoder is currently suspended for running too far past it.
+      // See #enforceLookAhead.
+      lastRequestedSegment: null,
+      encoderPaused: false,
+      encoderPauseUnsupported: false,
       seekFirstFarAt: 0,
       // Circuit breaker: consecutive FAST failures (see SEEK_FAST_FAIL_MS) at
       // seekFailureTarget. Reset whenever a run starts at a DIFFERENT target or
@@ -1549,6 +1569,94 @@ export class HlsSessionManager {
     return true;
   }
 
+  /**
+   * Stop encoders that have run too far ahead of their viewer, and release
+   * those the viewer has caught up with.
+   *
+   * The encoder is SUSPENDED, not killed. Killing would be simpler, but
+   * restarting it costs about nine seconds on this hardware — the torrent has
+   * to serve a fresh position and ffmpeg has to reach its first keyframe — so a
+   * viewer reaching the end of the produced range would stall every time.
+   * Suspending keeps the process, its open input and its position, and costs
+   * nothing to undo.
+   *
+   * POSIX only. `SIGSTOP` does not exist on Windows, where `process.kill`
+   * throws; the attempt is made once per session and, if it fails, that session
+   * simply keeps its old unbounded behaviour rather than breaking.
+   *
+   * @returns {void}
+   */
+  #enforceLookAhead() {
+    for (const session of this.sessionsById.values()) {
+      if (!session || session.state === "disposed" || !session.ffmpeg) {
+        continue;
+      }
+      const encodedTo = Number(session.progress?.processedSeconds);
+      if (!Number.isFinite(encodedTo)) {
+        continue;
+      }
+      // Where the viewer is. Before the first segment request, the position the
+      // run started at — so a session nobody has read from yet is bounded too.
+      const viewerAt = Number.isInteger(session.lastRequestedSegment)
+        ? this.#segmentStartTime(session, session.lastRequestedSegment)
+        : this.#segmentStartTime(session, session.encodeStartIndex ?? 0);
+      const ahead = encodedTo - viewerAt;
+      if (!session.encoderPaused && ahead > LOOKAHEAD_PAUSE_SECONDS) {
+        this.#pauseEncoder(session, `${Math.round(ahead)}s ahead of the viewer`);
+      } else if (session.encoderPaused && ahead <= LOOKAHEAD_RESUME_SECONDS) {
+        this.#resumeEncoder(session, `${Math.round(ahead)}s ahead of the viewer`);
+      }
+    }
+  }
+
+  /**
+   * Suspend a session's encoder. No-op when already paused or unsupported here.
+   *
+   * @param {HlsSession} session
+   * @param {string} reason
+   * @returns {void}
+   */
+  #pauseEncoder(session, reason) {
+    if (session.encoderPaused || session.encoderPauseUnsupported || !session.ffmpeg?.pid) {
+      return;
+    }
+    try {
+      process.kill(session.ffmpeg.pid, "SIGSTOP");
+    } catch (error) {
+      session.encoderPauseUnsupported = true;
+      logger.info(
+        `transcode ${session.id} cannot suspend the encoder on this platform ` +
+          `(${error instanceof Error ? error.message : String(error)}); look-ahead stays unbounded`
+      );
+      return;
+    }
+    session.encoderPaused = true;
+    logger.info(
+      `transcode ${session.id} encoder suspended — ${reason} ` +
+        `"${session.fileName}"`
+    );
+  }
+
+  /**
+   * Let a suspended encoder run again.
+   *
+   * @param {HlsSession} session
+   * @param {string} reason
+   * @returns {void}
+   */
+  #resumeEncoder(session, reason) {
+    if (!session.encoderPaused || !session.ffmpeg?.pid) {
+      return;
+    }
+    try {
+      process.kill(session.ffmpeg.pid, "SIGCONT");
+    } catch {
+      // The process is gone; the exit handler will deal with it.
+    }
+    session.encoderPaused = false;
+    logger.info(`transcode ${session.id} encoder resumed — ${reason} "${session.fileName}"`);
+  }
+
   async #enforceRealtimeBudget() {
     if (this.videoEncoder?.kind !== "software") {
       return;
@@ -1728,6 +1836,9 @@ export class HlsSessionManager {
   async #startEncodeRun(session, startIndex) {
     const generation = ++session.encodeRunGeneration;
     const previousFfmpeg = session.ffmpeg;
+    // A suspended process does not act on SIGTERM until it is continued, so the
+    // wait below would never end. Let it run before asking it to stop.
+    this.#resumeEncoder(session, "terminating for a new run");
     if (previousFfmpeg && !hasChildExited(previousFfmpeg)) {
       try {
         previousFfmpeg.kill("SIGTERM");
@@ -1760,6 +1871,7 @@ export class HlsSessionManager {
     // Terminate any existing encode process before starting a new one.  The
     // old process's exit handler no-ops because session.ffmpeg is reassigned
     // below (it checks identity).
+    this.#resumeEncoder(session, "terminating");
     if (session.ffmpeg && !session.ffmpeg.killed) {
       try {
         session.ffmpeg.kill("SIGTERM");
@@ -1933,6 +2045,7 @@ export class HlsSessionManager {
     // judged finished — see getFileStream.
     session.usesExplicitCuts = Boolean(cutTimes && cutTimes.length > 0);
     session.encodeStartIndex = safeIndex;
+    session.encoderPaused = false;
     session.pendingRestartIndex = -1;
     session.lastRestartAt = Date.now();
     session.state = session.state === "disposed" ? "disposed" : "starting";
@@ -2347,48 +2460,21 @@ export class HlsSessionManager {
       session.seekSettleTimer.unref?.();
       return;
     }
-    // Let the CURRENT run finish what it started. Restarting a run that has not
-    // yet produced a single segment destroys all its work and starts the wait
-    // over — and after a seek the first segment is always the slowest, so this
-    // is self-perpetuating: field log (2026-08-02, one user seek) shows
-    // restarts at #617 → #717 → #732 → #732 every 5-7 s, none of which ever
-    // produced anything, leaving the viewer with a flickering loading pill and
-    // no playback at all.
-    //
-    // These extra targets are NOT further user seeks: when the player cannot
-    // get its segment it SCANS the playlist (every segment is listed in our
-    // synthetic VOD playlist, so from its point of view they all exist), and
-    // each far-enough probe looked like a fresh seek to us. Waiting for the
-    // first segment makes the scan harmless — it can no longer steer the
-    // encoder — and one genuine seek now reliably completes.
-    //
-    // Bounded by RUN_FIRST_SEGMENT_GRACE_MS so a wedged run cannot block seeks
-    // forever; the encoder-stall watchdog and the exit handler cover a run that
-    // dies outright.
+    // A run in progress is NOT protected any more. It used to be: a restart was
+    // held for up to 30 s while the current run reached its first segment,
+    // because a far segment REQUEST could steer the encoder and the player's
+    // playlist scan produced dozens of them — restarts at #617 → #717 → #732 →
+    // #732 every 5-7 s, none producing anything (field 2026-08-02). Requests
+    // stopped steering anything when the position became explicit, so the only
+    // thing that can arrive here is a position the viewer has stated, and
+    // finishing a segment for where they no longer are is work nobody wants.
+    // Holding it was also expensive in the other direction: a genuine second
+    // seek could be delayed by the whole grace.
     const producedThisRun = this.#producedSecondsThisRun(session);
     const runIsAlive = session.ffmpeg != null && !hasChildExited(session.ffmpeg);
-    if (
-      runIsAlive &&
-      producedThisRun < this.segmentDurationSec &&
-      sinceLastRestart < RUN_FIRST_SEGMENT_GRACE_MS
-    ) {
-      logger.info(
-        `transcode ${session.id} seek #${target} HELD — current run has produced ` +
-          `${producedThisRun.toFixed(1)}s of the ${this.segmentDurationSec}s first segment ` +
-          `(${(sinceLastRestart / 1000).toFixed(1)}s into a ${RUN_FIRST_SEGMENT_GRACE_MS / 1000}s grace)`
-      );
-      session.seekSettleTimer = setTimeout(() => this.#fireSettledSeek(session), SEEK_SETTLE_MS);
-      session.seekSettleTimer.unref?.();
-      return;
-    }
-    // Why the restart was allowed — the counterpart of the HELD line above.
-    // Without it a restart is indistinguishable from the runaway ping-pong this
-    // guard exists to stop, and diagnosing a field report becomes guesswork.
     const allowedBecause = !runIsAlive
       ? "run is dead"
-      : producedThisRun >= this.segmentDurationSec
-        ? `run produced ${producedThisRun.toFixed(1)}s (first segment done)`
-        : `grace of ${RUN_FIRST_SEGMENT_GRACE_MS / 1000}s expired`;
+      : `viewer moved; run had produced ${producedThisRun.toFixed(1)}s`;
     // The start is exactly what requestSeek computed — one segment before the
     // viewer's position — and nothing else may move it.
     //
@@ -2585,6 +2671,17 @@ export class HlsSessionManager {
 
     const filePath = path.join(session.dirPath, fileName);
     const isPlaylist = fileName === PLAYLIST_FILE_NAME;
+    if (!isPlaylist) {
+      // Where the viewer actually is. Recorded for every segment request,
+      // served or not, because it is what bounds how far ahead the encoder is
+      // allowed to run — see #enforceLookAhead.
+      const requested = session.segmentFormat.segmentIndexFromName(fileName);
+      if (requested >= 0) {
+        session.lastRequestedSegment = requested;
+        // A viewer who has caught up must not wait out the monitor's interval.
+        this.#resumeEncoder(session, "a segment was requested");
+      }
+    }
     try {
       await access(filePath);
 
@@ -2793,6 +2890,7 @@ export class HlsSessionManager {
       session.seekSettleTimer = null;
     }
 
+    this.#resumeEncoder(session, "session disposed");
     if (session.ffmpeg && !session.ffmpeg.killed) {
       session.ffmpeg.kill("SIGTERM");
       await waitForChildExit(session.ffmpeg);

package/services/torrent-worker/piece-reader.js

@@ -21,6 +21,10 @@
  */
 
 import { findSharedStore } from "../piece-store/shared-piece-store.js";
+import { logger } from "../../utils/logger.js";
+
+/** Only waits at least this long are reported; sequential reading stays silent. */
+const PIECE_WAIT_LOG_MS = 1_000;
 
 /**
  * How far ahead of the read head pieces are asked for.
@@ -318,7 +322,21 @@ export async function* readFragments({
         criticalMark = markCritical(torrent, pieceIndex, Math.min(lastPiece, pieceIndex + criticalRun), criticalMark);
       }
 
+      const waitStartedAt = Date.now();
       await whenPieceReady(torrent, pieceIndex, cancellation);
+      // What a reader spent waiting for data, attributed to the exact piece. A
+      // seek's cost is dominated by the first segment after the encoder
+      // restarts (measured 9.2-9.4 s), and without this there is no way to say
+      // whether that is the swarm, the picker, or ffmpeg. Logged only when the
+      // wait is long enough to matter, so ordinary sequential reading is silent.
+      const waitedMs = Date.now() - waitStartedAt;
+      if (waitedMs >= PIECE_WAIT_LOG_MS) {
+        logger.info(
+          `piece-reader: waited ${waitedMs}ms for piece ${pieceIndex} ` +
+            `(${pieceIndex - firstPiece + 1} of ${lastPiece - firstPiece + 1} in a read from ` +
+            `${(start / 1024 / 1024).toFixed(0)}MB of "${file.name}")`
+        );
+      }
 
       // Pinned BEFORE it is located, and before any await that could let an
       // eviction run: the offset is only meaningful while the piece is held.