@torrent-tv/proxy 2.9.61 → 2.9.63

package/package.json

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

package/services/hls-session-manager.js

@@ -69,6 +69,22 @@ const ENCODER_STALL_MS = 12_000;
 // 367,732,369,368,370 seconds apart) collapses to ONE restart at the position
 // the player ended on, instead of ping-ponging ffmpeg between positions and
 // producing nothing.
+// How many segments BEFORE the requested position the encoder starts.
+//
+// Required by how HLS players seek, per Apple's HLS authoring guidance: given a
+// position, the player locates the nearest IDR (keyframe) *preceding* it,
+// decodes from there, and only then presents from the requested point. So it
+// always fetches segments BELOW the target — measured 2026-08-02 on iOS: a seek
+// to #1082 fetched from #1074 (8 back), one to #1358 fetched from #1301 (57
+// back), and in the latter case the player asked for NOTHING at or above the
+// target, so an encoder starting exactly on it produced only files nobody was
+// waiting for and playback hung indefinitely.
+//
+// The observed backoff is not constant, so this is a floor, not the whole
+// answer: #fireSettledSeek also pulls the start down to the lowest segment the
+// player is actually waiting on when that is lower still. Costs a few seconds
+// of extra encoding per seek.
+const SEEK_BACKOFF_SEGMENTS = 12;
 const SEEK_SETTLE_MS = 1_200;
 // Hard cap on the total settle wait, measured from the first far request of a
 // burst, so a still-moving scrubber cannot delay a genuine seek forever.
@@ -1065,6 +1081,9 @@ export class HlsSessionManager {
       // #wireEncodeProcess and MAX_SEEK_FAILURES.
       seekFailureTarget: -1,
       seekFailureCount: 0,
+      // Lowest segment index the player is currently waiting for; -1 when
+      // nothing is pending. See getFileStream and #fireSettledSeek.
+      lowestAwaitedIndex: -1,
       progress: {
         state: "starting",
         processedSeconds: 0,
@@ -1953,20 +1972,26 @@ export class HlsSessionManager {
     if (index === session.seekFailureTarget && session.seekFailureCount >= MAX_SEEK_FAILURES) {
       return;
     }
-    // Far request = a server-side seek. Do NOT restart on the first one:
-    // debounce a burst of scattered requests into a single restart at the
-    // position the player ended on. Record the latest target and (re)arm the
-    // settle timer; the caller long-polls / the client retries meanwhile.
-    session.seekTarget = index;
-    if (session.seekSettleTimer) {
-      clearTimeout(session.seekSettleTimer);
-    } else {
-      session.seekFirstFarAt = Date.now();
-    }
-    const waited = Date.now() - session.seekFirstFarAt;
-    const delay = waited >= SEEK_SETTLE_MAX_MS ? 0 : Math.min(SEEK_SETTLE_MS, SEEK_SETTLE_MAX_MS - waited);
-    session.seekSettleTimer = setTimeout(() => this.#fireSettledSeek(session), delay);
-    session.seekSettleTimer.unref?.();
+    // A far request is NOT treated as a seek. Measured 2026-08-02: on a single
+    // viewer seek the player opens ~25 CONCURRENT requests spanning #904..#1101
+    // and holds them all for the full 60 s without aborting any — normal
+    // read-ahead, not probing. There is therefore no such thing as "the segment
+    // the player ended on": at any instant a couple of dozen different indices
+    // are outstanding, so any rule picking one of them picks noise. Doing so
+    // produced NINE encoder restarts in one minute (#576→#885→#609→#591→#673→
+    // #833→#624→#1071→#1101), each killed 5-8 s in, turning a seek into a
+    // ~70 s ordeal.
+    //
+    // The seek target now arrives explicitly from the browser (requestSeek,
+    // POST /api/transcode-sessions/:id/seek) — the only place the viewer's
+    // intent actually exists. Same split as Jellyfin (startTimeTicks) and
+    // webtor (?t=): requests fetch data, they do not steer the encoder.
+    //
+    // Requests are still valuable, just not as commands: they are a queue of
+    // claims. Held open until produced (the player waits), served from disk
+    // when behind the encoder, and the LOWEST outstanding index marks where the
+    // viewer is actually stalled — the honest input for what to produce first.
+    // See research/hls-seek-prior-art-2026-08-02.md.
   }
 
   /**
@@ -1997,6 +2022,64 @@ export class HlsSessionManager {
     return Math.max(0, processed - startPosition);
   }
 
+  /**
+   * The viewer seeked. Called from POST /api/transcode-sessions/:id/seek with
+   * the position the browser read off its own player once the scrub ended.
+   *
+   * This is the ONLY thing that repositions the encoder. It replaces inferring
+   * the target from segment requests, which cannot work: a single seek leaves
+   * ~25 concurrent requests outstanding across a wide span (measured), so no
+   * rule over them can recover which one the viewer meant.
+   *
+   * The existing settle/cooldown/first-segment guards still apply — they
+   * protect against restarting too eagerly, which is orthogonal to knowing
+   * WHERE to restart.
+   *
+   * @param {string} sessionId
+   * @param {number} positionSeconds - Absolute position on the source timeline.
+   * @returns {boolean} False when the session is unknown or disposed.
+   */
+  requestSeek(sessionId, positionSeconds) {
+    const session = this.sessionsById.get(sessionId);
+    if (!session || session.state === "disposed") {
+      return false;
+    }
+    const index = this.#segmentIndexForTime(session, positionSeconds);
+    const head = session.encodeStartIndex;
+    const processed = Number.isFinite(session.progress?.processedSeconds)
+      ? session.progress.processedSeconds
+      : this.#segmentStartTime(session, head);
+    const currentSeg = Math.max(head, this.#segmentIndexForTime(session, processed));
+    // Already covered by the running encode — the data is on its way, so
+    // restarting would only destroy work the viewer is waiting for.
+    if (index >= head && index <= currentSeg + MAX_LOOKAHEAD_SEGMENTS) {
+      logger.info(
+        `transcode ${session.id} seek to ${positionSeconds.toFixed(1)}s (#${index}) ` +
+          `already within the running encode (#${head}..#${currentSeg}) — not restarting`
+      );
+      return true;
+    }
+    // Start BEFORE the requested position (see SEEK_BACKOFF_SEGMENTS): the
+    // player needs a segment containing the preceding keyframe, so one that
+    // begins exactly at the target is useless to it.
+    const startIndex = Math.max(0, index - SEEK_BACKOFF_SEGMENTS);
+    logger.info(
+      `transcode ${session.id} viewer seek to ${positionSeconds.toFixed(1)}s → segment #${index}, ` +
+        `starting at #${startIndex} (${SEEK_BACKOFF_SEGMENTS} back for the preceding keyframe)`
+    );
+    session.seekTarget = startIndex;
+    if (session.seekSettleTimer) {
+      clearTimeout(session.seekSettleTimer);
+    } else {
+      session.seekFirstFarAt = Date.now();
+    }
+    const waited = Date.now() - session.seekFirstFarAt;
+    const delay = waited >= SEEK_SETTLE_MAX_MS ? 0 : Math.min(SEEK_SETTLE_MS, SEEK_SETTLE_MAX_MS - waited);
+    session.seekSettleTimer = setTimeout(() => this.#fireSettledSeek(session), delay);
+    session.seekSettleTimer.unref?.();
+    return true;
+  }
+
   #fireSettledSeek(session) {
     const target = session.seekTarget;
     session.seekSettleTimer = null;
@@ -2081,10 +2164,22 @@ export class HlsSessionManager {
       : producedThisRun >= this.segmentDurationSec
         ? `run produced ${producedThisRun.toFixed(1)}s (first segment done)`
         : `grace of ${RUN_FIRST_SEGMENT_GRACE_MS / 1000}s expired`;
+    // The player may be waiting on something below our fixed backoff — its own
+    // requests say exactly how far back it needs the keyframe, so honour that
+    // rather than a guess. Only ever pulls the start EARLIER, never later.
+    const awaited = session.lowestAwaitedIndex;
+    const effectiveTarget = awaited >= 0 && awaited < target ? awaited : target;
+    if (effectiveTarget !== target) {
+      logger.info(
+        `transcode ${session.id} pulling encode start #${target} → #${effectiveTarget} ` +
+          `(lowest segment the player is waiting on)`
+      );
+    }
     session.seekTarget = null;
     session.seekFirstFarAt = 0;
-    logger.info(`transcode ${session.id} seek settle → restart at segment #${target} (${allowedBecause})`);
-    void this.#startEncodeRun(session, target);
+    session.lowestAwaitedIndex = -1;
+    logger.info(`transcode ${session.id} seek settle → restart at segment #${effectiveTarget} (${allowedBecause})`);
+    void this.#startEncodeRun(session, effectiveTarget);
   }
 
   /**
@@ -2287,9 +2382,20 @@ export class HlsSessionManager {
     // to wait for the current encode run to reach it or to restart the encoder
     // at this position (server-side seeking).  The caller long-polls.
     if (!isPlaylist) {
+      const requestedIndex = this.segmentFormat.segmentIndexFromName(fileName);
+      // Remember the LOWEST segment currently being waited on. The player
+      // always fetches below the seek target (it needs the preceding keyframe),
+      // and by how much varies — 8 segments in one measured seek, 57 in
+      // another. This is that figure straight from the player, and
+      // #fireSettledSeek uses it to pull the encode start down when the fixed
+      // SEEK_BACKOFF_SEGMENTS floor is not deep enough. Reset whenever a run
+      // starts, so it only ever describes the pending seek.
+      if (requestedIndex >= 0 && (session.lowestAwaitedIndex < 0 || requestedIndex < session.lowestAwaitedIndex)) {
+        session.lowestAwaitedIndex = requestedIndex;
+      }
       this.#ensureEncodingFor(
         session,
-        this.segmentFormat.segmentIndexFromName(fileName),
+        requestedIndex,
         Number.isFinite(options?.requestSeq) ? options.requestSeq : Number.MAX_SAFE_INTEGER
       );
     }