@torrent-tv/proxy 2.9.36 → 2.9.37

package/CHANGELOG.md

@@ -1,6 +1,13 @@
-## 2.9.35
+## 2.9.37
+
+- **Fix**: Scrubbing (server-side seek) no longer hangs the player. A far segment request restarts ffmpeg at that position; native players (notably iOS HLS) issue a burst of scattered far requests after a scrub (observed: `367 → 732 → 369 → 368 → 370`, tens of seconds apart), and the old fixed 4 s cooldown only suppressed restarts within 4 s of the last — so each scattered request restarted ffmpeg and it ping-ponged between positions, producing nothing and stalling playback. Far requests are now **debounced**: the target index is recorded and a short settle timer armed (1.2 s quiet period, 2.5 s hard cap from the burst's first request); further far requests re-arm it and update the target to the latest index; when it settles, ffmpeg restarts once at that index. "Last index wins" self-corrects — a wrong target costs at most one extra settle, never the old infinite loop. The settle timer is cleared on session disposal. (OpenSpec change `seek-debounce`.)
+
+## 2.9.36
 
 - **New**: Chunked request bodies over the data channel (OpenSpec change `chunked-request-bodies`). Large request bodies — notably the source registration, whose body is the base64 `.torrent` (hundreds of KB for a multi-season pack) — now arrive as bounded binary frames (the response-frame layout) announced by a `request-start` message, and are reassembled and run through the same path as a single-message request. Bounded: 32 MB per-body cap, a 60 s TTL for incomplete bodies, an abort frame that drops partial state at once, and all per-channel state freed on channel close. This removes the single-message size ceiling symmetrically with responses (which already stream in chunks). Logged as `body=<bytes> bytes (chunked)`.
+
+## 2.9.35
+
 - **Fix**: Large torrents (many files / seasons) no longer fail with "Trying to send message larger than max-message-size" when a file is picked. The browser sends the source registration body — the base64-encoded `.torrent` — in a single data-channel message; a big multi-season pack's `.torrent` carries thousands of piece hashes (e.g. Poirot, 13 seasons: 420 KB → ~560 KB base64), exceeding libdatachannel's default advertised limit of 256 KB, so the browser's `channel.send()` threw. The proxy now advertises a 16 MB `a=max-message-size`, so a large single send still works while already-open tabs run the old bundle. Verified the SDP now carries `a=max-message-size:16777216` (was `262144`).
 
 ## 2.9.34

package/openspec/changes/seek-debounce/design.md

@@ -0,0 +1,118 @@
+# Design: Debounce server-side seek restarts
+
+Normative — member names, constants, and edge cases as written. Read before
+coding:
+
+- `services/hls-session-manager.js`: `#ensureEncodingFor(session, index)`
+  (line ~1478 — the restart decision), the session object shape where
+  `lastRestartAt` / `pendingRestartIndex` / `encodeStartIndex` live (~883),
+  `#startEncodeRun`, `disposeSession` (must clear timers), and the constants
+  block (~36–58).
+
+## Current behaviour (what we are replacing)
+
+`#ensureEncodingFor` runs per segment request:
+
+1. Compute the look-ahead window `[head, currentSeg + MAX_LOOKAHEAD_SEGMENTS]`.
+2. In window → return (the running encode will reach it).
+3. Out of window (a seek) → if `now - lastRestartAt < RESTART_COOLDOWN_MS`,
+   skip; else `#startEncodeRun(session, index)` immediately.
+
+The cooldown is a fixed 4 s gap. Requests spaced wider than 4 s each restart
+→ ping-pong. That is the bug.
+
+## New behaviour: settle window (debounce)
+
+Keep steps 1–2. Replace step 3 with a debounce:
+
+    far request (index outside window):
+      session.seekTarget = index                       // last far index wins
+      if (!session.seekSettleTimer):
+        session.seekFirstFarAt = now()
+      else:
+        clearTimeout(session.seekSettleTimer)
+      const waited = now() - session.seekFirstFarAt
+      const delay = waited >= SEEK_SETTLE_MAX_MS ? 0
+                    : Math.min(SEEK_SETTLE_MS, SEEK_SETTLE_MAX_MS - waited)
+      session.seekSettleTimer = setTimeout(() => fireSettledSeek(session), delay)
+      return                                            // do NOT restart now
+
+    fireSettledSeek(session):
+      const target = session.seekTarget
+      session.seekSettleTimer = null
+      session.seekTarget = null
+      session.seekFirstFarAt = 0
+      if (session disposed or target == null) return
+      // Minimum gap between actual restarts (defensive; the settle already
+      // collapses bursts). If still cooling down, re-arm once for the
+      // remaining cooldown instead of restarting.
+      const sinceRestart = now() - (session.lastRestartAt ?? 0)
+      if (sinceRestart < RESTART_COOLDOWN_MS):
+        session.seekFirstFarAt = now()
+        session.seekTarget = target
+        session.seekSettleTimer = setTimeout(() => fireSettledSeek(session),
+                                             RESTART_COOLDOWN_MS - sinceRestart)
+        return
+      log(`transcode ${id} seek settle → restart at #${target}`)
+      this.#startEncodeRun(session, target)             // sets lastRestartAt
+
+Notes:
+- `timer.unref?.()` on each `setTimeout` so a pending settle never keeps the
+  process alive (mirror the codebase's other timers).
+- A far request whose `index` equals the current `seekTarget` still re-arms
+  the timer (the player is still asking for the same place — that is fine, it
+  just extends the quiet period up to the cap).
+- If, while a settle is pending, the running encode advances so a later
+  request falls back INSIDE the window, that request returns at step 2 and
+  does not touch the settle. The pending settle still fires for the recorded
+  target; that is acceptable (it restarts at a position the player recently
+  wanted). Simplicity over cleverness.
+
+## Constants (add to the constants block)
+
+    // Quiet period after a far (seek) segment request before ffmpeg is
+    // restarted at it. Further far requests within the period re-arm it, so a
+    // scrub that emits a burst of scattered requests collapses to ONE restart
+    // at the position the player ended on.
+    SEEK_SETTLE_MS = 1200
+    // Hard cap on the total settle wait measured from the first far request of
+    // a burst, so a still-moving scrubber cannot delay a real seek forever.
+    SEEK_SETTLE_MAX_MS = 2500
+
+`MAX_LOOKAHEAD_SEGMENTS` and `RESTART_COOLDOWN_MS` keep their current values;
+`RESTART_COOLDOWN_MS` is now only the floor between actual restarts.
+
+## Session state (add where lastRestartAt is initialised, ~883)
+
+    seekSettleTimer: null,   // pending settle timer handle or null
+    seekTarget: null,        // pending far segment index to restart at
+    seekFirstFarAt: 0,       // timestamp of the first far request in the burst
+
+## Disposal
+
+`disposeSession` (and any teardown that abandons a session) MUST
+`clearTimeout(session.seekSettleTimer)` and null it, so a settle cannot fire
+after disposal and restart a dead session.
+
+## Why proxy-side, not client-side (the user's original framing)
+
+The user asked for a scrubber-release debounce. On the in-page media-chrome
+control that is possible but fragile, and — decisively — it cannot cover the
+iOS **native fullscreen** player, whose scrubber the web app does not control;
+the failing session was exactly iOS. The proxy sees the segment requests from
+EVERY client (native iOS, hls.js, direct `<video>`), so debouncing the
+restart here is the one place that fixes all of them. An in-page scrubber
+debounce may still be added later as a responsiveness nicety; it is not a
+substitute and is out of scope here.
+
+## Verification
+
+- Unit-test the timing/target logic in isolation (a fake session + a fake
+  clock/`setTimeout`): a burst of far requests `367,732,369,368,370` within
+  the window collapses to a single `#startEncodeRun` at the LAST index (370),
+  and a lone later far request triggers exactly one more restart.
+- `node --check`.
+- Field: the earlier hang scenario (scrub Poirot on iOS) should now produce a
+  single `seek settle → restart` log line per scrub instead of a train of
+  `seek → restart` lines, and playback should resume after one settle + the
+  (separate, unavoidable) cold-segment wait.

package/openspec/changes/seek-debounce/proposal.md

@@ -0,0 +1,59 @@
+# Proposal: Debounce server-side seek restarts
+
+## Why
+
+Field evidence (iPhone/Safari, Poirot, 2026-07-09): after a scrub the player
+hung indefinitely. The proxy restarts ffmpeg at a requested segment when the
+request lands outside the look-ahead window (server-side seek). The native
+iOS player issued scattered segment requests after the seek —
+`367 → 732 → 369 → 368 → 370` — each 25–35 s apart. The existing guard
+(`RESTART_COOLDOWN_MS = 4000`) only suppresses restarts within 4 s of the
+last one, so with requests spaced far wider than that, EVERY scattered
+request restarted ffmpeg at a new position. ffmpeg ping-ponged between
+positions and never finished a single segment, so playback stalled at
+`currentTime` with `bufferedAhead=0` — "заглохло наглухо".
+
+The fix is the user's idea placed where every client is covered (including
+the iOS native fullscreen player, whose scrubber the web app cannot control):
+don't act on the first far request — wait for the burst to settle, then
+restart ONCE at the position the player ended on.
+
+## What Changes
+
+- Replace the fixed post-restart cooldown as the anti-thrash mechanism with a
+  **settle window**. When a segment request lands outside the look-ahead
+  window (a seek), the proxy does NOT restart immediately: it records the
+  requested index as the pending seek target and arms a short quiet-period
+  timer. Each further far request updates the target to the latest index and
+  re-arms the timer (debounce). When the quiet period elapses with no new far
+  request, ffmpeg restarts ONCE at the pending target. A hard cap bounds the
+  total wait so a genuine seek is never delayed more than a fixed budget even
+  while the scrubber is still moving.
+- Meanwhile the segment route behaves exactly as today — it long-polls and
+  the client retries — so the player simply waits out the (short) settle
+  instead of driving restarts.
+- "Last far index wins" self-corrects: if the settle resolves on the wrong
+  position (e.g. a lone probe request), the player's next request re-arms one
+  more settle — at most one extra cycle, never the old infinite ping-pong.
+
+Out of scope (documented in design.md): an optional client-side scrubber
+debounce for the in-page media-chrome control (helps responsiveness but does
+NOT cover iOS native fullscreen, so the proxy-side settle is the must-have);
+the cold-torrent piece-download and weak-host encode latency that make the
+FIRST post-seek segment slow regardless — the settle removes the infinite
+thrash, not the one-time seek latency.
+
+## Capabilities
+
+### Modified Capabilities
+
+- `seek-debounce` (server-side HLS seeking): far-segment requests are
+  debounced into a single ffmpeg restart at the settled position.
+
+## Impact
+
+- `services/hls-session-manager.js` — `#ensureEncodingFor` gains the settle
+  window; per-session settle state; `disposeSession` clears the timer;
+  constants. `RESTART_COOLDOWN_MS` is retained only as a minimum gap between
+  actual restarts.
+- Proxy release + ha-addon version bump (per release rules).

package/openspec/changes/seek-debounce/specs/seek-debounce/spec.md

@@ -0,0 +1,41 @@
+# seek-debounce — delta spec (proxy)
+
+## ADDED Requirements
+
+### Requirement: Scattered post-seek segment requests collapse to one restart
+
+When segment requests land outside the running encode's look-ahead window
+(server-side seeks), the proxy SHALL NOT restart ffmpeg on each one. It SHALL
+wait a short settle period, treating further out-of-window requests as
+re-arming the period and updating the target to the most recently requested
+index, and then restart the encoder exactly once at the settled target. A
+fixed cap SHALL bound the total settle wait so a genuine seek is not delayed
+indefinitely while the scrubber is still moving. During the settle the
+segment route behaves as before (long-poll / client retry).
+
+#### Scenario: Scrub emits a burst of scattered requests
+- **WHEN** a player, after a seek, requests several far-apart segments in
+  quick succession (e.g. 367, 732, 369, 368, 370)
+- **THEN** ffmpeg is restarted only once, at the last requested index, and
+  produces a continuous run from there — no ping-pong between positions
+
+#### Scenario: Settle resolves on the wrong position
+- **WHEN** the settled restart target turns out not to be where the player
+  ultimately needs to play (e.g. it was a lone probe request)
+- **THEN** the player's next out-of-window request arms exactly one more
+  settle and one more restart — never an unbounded restart loop
+
+#### Scenario: Request falls back inside the window
+- **WHEN** a requested segment is within the current run's look-ahead window
+- **THEN** it is served by the running encode with no restart and without
+  affecting any pending settle
+
+### Requirement: A pending settle never outlives its session
+
+When a session is disposed, any pending settle timer SHALL be cleared so it
+cannot fire and restart a disposed session.
+
+#### Scenario: Session disposed mid-settle
+- **WHEN** a session with a pending seek-settle timer is disposed (idle TTL,
+  shutdown, or teardown)
+- **THEN** the timer is cleared and no encode restart occurs afterwards

package/openspec/changes/seek-debounce/tasks.md

@@ -0,0 +1,33 @@
+# Tasks: Debounce server-side seek restarts
+
+## 1. Implementation (proxy)
+
+- [x] 1.1 Add `SEEK_SETTLE_MS = 1200` and `SEEK_SETTLE_MAX_MS = 2500` to the
+      constants block in `hls-session-manager.js`.
+- [x] 1.2 Add session state `seekSettleTimer: null`, `seekTarget: null`,
+      `seekFirstFarAt: 0` where `lastRestartAt` is initialised.
+- [x] 1.3 Rewrite the out-of-window branch of `#ensureEncodingFor` as the
+      settle/debounce (design.md): record target, arm/re-arm the timer with
+      the capped delay, restart once on fire (`#fireSettledSeek`), re-arm for
+      the cooldown remainder if still cooling down. `timer.unref?.()`.
+- [x] 1.4 `disposeSession`: clear `seekSettleTimer` and null it.
+- [x] 1.5 Restart log line: `transcode <id> seek settle → restart at segment #<target>`.
+
+## 2. Verification
+
+- [x] 2.1 Timing/target logic verified with a fake-clock replica: burst
+      `367,732,369,368,370` → one restart at 370; lone later far request →
+      exactly one more restart (900); disposal mid-settle → no restart; the
+      2.5 s cap forces a fire while the scrubber keeps moving. (Replica, not
+      the wired private method — the methods are private and `#startEncodeRun`
+      spawns ffmpeg; the wired code mirrors the replica.)
+- [x] 2.2 `node --check services/hls-session-manager.js`.
+
+## 3. Release
+
+- [ ] 3.1 CHANGELOG (proxy, next patch) + `npm run patch` (user OTP).
+- [ ] 3.2 Bump `ha-addon/torrent_tv_proxy/config.yaml` + CHANGELOG; push;
+      update the addon in HA.
+- [ ] 3.3 Field: scrub Poirot on iOS → a single `seek settle → restart` per
+      scrub (not a train of `seek → restart`), playback resumes after the
+      settle + the unavoidable cold-segment wait.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.9.36",
+  "version": "2.9.37",
   "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,6 +43,17 @@ const MAX_LOOKAHEAD_SEGMENTS = 8;
 // succession (stall-recovery seeks); without a cooldown ffmpeg ping-pongs
 // between positions, restarting endlessly and producing nothing.
 const RESTART_COOLDOWN_MS = 4_000;
+// 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
+// a scrub that emits a burst of scattered requests (e.g. iOS native HLS firing
+// 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.
+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.
+const SEEK_SETTLE_MAX_MS = 2_500;
 // Idle TTL: a session is disposed this long after the last segment/playlist
 // access. Kept short so an ffmpeg process does not keep burning CPU after the
 // viewer stops or navigates away. Active playback refreshes the timer on every
@@ -884,6 +895,12 @@ export class HlsSessionManager {
       pendingRestartIndex: -1,
       // Timestamp of the last encode (re)start, for the restart cooldown.
       lastRestartAt: 0,
+      // Seek debounce: pending settle timer, the far segment index to restart
+      // at once the burst settles, and the timestamp of the burst's first far
+      // request (for the SEEK_SETTLE_MAX_MS cap).
+      seekSettleTimer: null,
+      seekTarget: null,
+      seekFirstFarAt: 0,
       progress: {
         state: "starting",
         processedSeconds: 0,
@@ -1492,22 +1509,52 @@ export class HlsSessionManager {
     if (withinWindow) {
       return;
     }
-    if (session.pendingRestartIndex === index) {
+    // 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?.();
+  }
+
+  /**
+   * Fire a settled server-side seek: restart the encoder once at the target
+   * recorded during the settle window. Enforces the restart cooldown as a
+   * floor between actual restarts (re-arming for the remainder if still
+   * cooling down). No-op for a disposed session or a cleared target.
+   *
+   * @param {HlsSession} session
+   * @returns {void}
+   */
+  #fireSettledSeek(session) {
+    const target = session.seekTarget;
+    session.seekSettleTimer = null;
+    if (!session || session.state === "disposed" || target == null) {
+      session.seekTarget = null;
+      session.seekFirstFarAt = 0;
       return;
     }
-    // Restart cooldown: a stalled player requests several distant segments in
-    // quick succession; without this guard ffmpeg ping-pongs between them and
-    // never makes progress. Skip the restart during the cooldown — the caller
-    // long-polls / the client retries, and a genuine seek is honored once the
-    // cooldown elapses.
+    // Minimum gap between actual restarts (the settle already collapses bursts;
+    // this only guards back-to-back seeks). If still cooling down, re-arm once
+    // for the remaining cooldown instead of restarting now.
     const sinceLastRestart = Date.now() - (session.lastRestartAt ?? 0);
     if (sinceLastRestart < RESTART_COOLDOWN_MS) {
+      session.seekSettleTimer = setTimeout(() => this.#fireSettledSeek(session), RESTART_COOLDOWN_MS - sinceLastRestart);
+      session.seekSettleTimer.unref?.();
       return;
     }
-    logger.info(
-      `transcode ${session.id} seek → restart at segment #${index} (encode head #${head}, current #${currentSeg})`
-    );
-    this.#startEncodeRun(session, index);
+    session.seekTarget = null;
+    session.seekFirstFarAt = 0;
+    logger.info(`transcode ${session.id} seek settle → restart at segment #${target}`);
+    this.#startEncodeRun(session, target);
   }
 
   /**
@@ -1743,6 +1790,13 @@ export class HlsSessionManager {
     this.sessionsById.delete(sessionId);
     this.sessionIdBySource.delete(session.sourceMapKey);
 
+    // Clear any pending seek-settle timer so it cannot fire and restart a
+    // disposed session.
+    if (session.seekSettleTimer) {
+      clearTimeout(session.seekSettleTimer);
+      session.seekSettleTimer = null;
+    }
+
     if (session.ffmpeg && !session.ffmpeg.killed) {
       session.ffmpeg.kill("SIGTERM");
       await waitForChildExit(session.ffmpeg);