@torrent-tv/proxy 2.9.36 → 2.9.38

package/CHANGELOG.md

@@ -1,6 +1,17 @@
-## 2.9.35
+## 2.9.38
+
+- **New**: Adaptive bitrate for thin viewer links (OpenSpec change `adaptive-bitrate`). Field evidence (iPhone on cellular): uncapped complex scenes produced 4 s segments of ~18 Mbit/s against a 1–6 Mbit/s link — 45 s prebuffer and a draining buffer. Two parts. (a) Software encodes are now constrained-CRF: `-maxrate`/`-bufsize` per resolution rung (1080p→5000K, 720p→2800K, 480p→1400K, 360p→800K, 240p→400K nominal; ×1.3/×1.5 — webtor's production multipliers), so peaks stay bounded. (b) New data-channel route `POST /api/transcode-sessions/:id/net-report` accepts the browser's measured link throughput + buffered seconds; the realtime-budget loop gains a second downshift trigger — a FRESH report showing the usable link (×0.8 safety) sustainedly (15 s) below the observed produced bitrate while the viewer's buffer is low (<10 s) steps the encode one rung down via the existing machinery (shared 30 s cooldown, step cap, no upswitch). Log reason `viewer-link-bound` distinguishes it from CPU downshifts. Manual-quality sessions are exempt (no budget ladder); old clients that never report simply keep today's behaviour plus the caps.
+
+## 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/adaptive-bitrate/design.md

@@ -0,0 +1,92 @@
+# Design: Adaptive bitrate (proxy)
+
+Read before coding: `services/hwaccel.js` (`chooseSoftwareEncodeSettings`,
+the software descriptor's `buildVideoArgs`), `services/hls-session-manager.js`
+(the `BUDGET_*` constants, `#chooseEncodeBudget`, the budget interval check
+`#enforceRealtimeBudget`, `#classifyTranscodeBound`, `#applyBudgetDownshift`,
+session fields around `budgetLadder`), `routes/api/transcode-sessions/`
+(route file conventions), `server.js` (route wiring, deps injection).
+
+## (a) Caps — constrained CRF
+
+Nominal H.264 rates by rung height (nearest rung wins for odd heights):
+
+    RUNG_NOMINAL_KBPS = { 1080: 5000, 720: 2800, 480: 1400, 360: 800, 240: 400 }
+    CAP_MAXRATE_FACTOR = 1.3
+    CAP_BUFSIZE_FACTOR = 1.5
+
+In the software descriptor's video args (where `-crf`/`-preset` are emitted),
+add for encode height H (the actual encode height after budget/manual
+selection, not the source height):
+
+    -maxrate <round(nominal(H) * 1.3)>k
+    -bufsize <round(nominal(H) * 1.5)>k
+
+CRF stays the quality driver; the caps only bound peaks (standard
+constrained-CRF). Do NOT touch hardware descriptors in this change.
+
+## (b) Net report intake
+
+Route: `POST /api/transcode-sessions/:id/net-report` (data-channel path, so
+add the prefix to the allowlist regex in `data-channel-handler.js` if not
+covered by the existing `/api/` rule — verify). Body:
+
+    { linkMbps: number, bufferedAheadSec: number }
+
+Validation: both finite numbers, `linkMbps > 0`, else 400. Unknown session →
+404. On success 204. Handler stores on the session:
+
+    session.netReport = { linkMbps, bufferedAheadSec, at: Date.now() }
+
+## (b) Budget-loop trigger
+
+Constants (near the other BUDGET_ constants):
+
+    LINK_REPORT_FRESH_MS = 30_000   // ignore stale reports
+    LINK_SAFETY = 0.8               // usable share of reported link
+    LINK_SLOW_WINDOW_MS = 15_000    // sustained deficit before acting
+    LINK_LOW_BUFFER_SEC = 10        // only act while the viewer runs dry
+
+In the periodic budget check, for each active software-transcode session,
+alongside the CPU check:
+
+    report fresh (now - at < LINK_REPORT_FRESH_MS)?
+    manualQuality not set?
+    observed = observed stream bitrate, Mbit/s — recent produced segment
+               bytes / segment duration (reuse/extend whatever the CPU path
+               reads; a rolling average over the last ~5 segments)
+    deficit = report.linkMbps * LINK_SAFETY < observed
+    if deficit AND report.bufferedAheadSec < LINK_LOW_BUFFER_SEC:
+        accumulate slow-time (same pattern as the CPU slow window)
+        if slow ≥ LINK_SLOW_WINDOW_MS → #applyBudgetDownshift(session,
+            reason "link")   // existing cooldown + step cap + floor apply
+    else: reset the link slow window
+
+`#applyBudgetDownshift` is reused as-is except the log line carries the
+reason: `budget downshift (link) …` vs the current CPU wording, so the
+client-log pipeline can tell them apart in the field.
+
+No upswitch in v1 (mirrors the CPU budget's conservatism). A downshifted
+session stays down until re-opened.
+
+## Interactions
+
+- Caps make `observed` honest: without (a) a complex scene can spike far
+  above nominal and flap the trigger; with caps observed ≤ maxrate.
+- CPU trigger and link trigger share the cooldown inside
+  `#applyBudgetDownshift` — they cannot double-fire.
+- `manualQuality` set → link trigger skipped entirely (user pinned quality
+  explicitly; the proxy respects it, matching the manual-quality contract).
+- Old browsers never POST reports → trigger never fires → behaviour
+  identical to today plus caps.
+
+## Verification
+
+- Unit: nominal table lookup (exact rungs + nearest for odd heights); ffmpeg
+  arg assembly contains the caps; trigger logic with a fake clock (fresh vs
+  stale report, deficit accumulating to a downshift, buffer-high suppresses,
+  manualQuality suppresses).
+- `node --check` on touched files.
+- Field (after the server change ships): cellular session shows
+  `budget downshift (link)` and the stream settles at a rung whose bitrate
+  fits the link; segment sizes bounded (~maxrate × segDur / 8 max).

package/openspec/changes/adaptive-bitrate/proposal.md

@@ -0,0 +1,56 @@
+# Proposal: Adaptive bitrate for thin viewer links (proxy side)
+
+## Why
+
+Field evidence (iPhone on cellular, 2026-07-10, session `14cc1017`): encode
+bitrate is unbounded — transcoded segments reached 9 MB per 4 s (~18 Mbit/s)
+against a measured 1–5.8 Mbit/s cellular link. Result: 45 s prebuffer, buffer
+draining during playback (`bottleneck delta=-7.1s`), "было так себе". The
+realtime budget protects the PROXY's CPU but nothing protects the VIEWER's
+link: quality never adapts to how fast the viewer can actually download.
+
+## What Changes
+
+Two parts, one release:
+
+- **(a) Bitrate caps (constrained CRF).** Software video encodes gain
+  `-maxrate`/`-bufsize` sized per resolution rung from a nominal-rate table
+  (H.264 ladder: 1080p→5000K, 720p→2800K, 480p→1400K, 360p→800K, 240p→400K;
+  nearest rung by encode height). Multipliers from webtor's production
+  ladder: `maxrate = 1.3×` nominal, `bufsize = 1.5×` nominal. CRF/preset
+  selection stays — the caps only bound the peaks that killed the cellular
+  session. Applies to the software (libx264) path; hardware encoders keep
+  their current args (follow-up — their rate-control flags differ and any
+  change must pass the strict startup test on real hardware).
+- **(b) Viewer-link downshift trigger.** A new data-channel route lets the
+  browser report its measured link state (`linkMbps` — rolling median of
+  per-segment transfer throughput; `bufferedAheadSec`) every ~10 s. The
+  existing realtime-budget loop gains a SECOND downshift trigger: when
+  reports are fresh, `manualQuality` is not set, the viewer's link is
+  sustainedly slower than the produced stream (`linkMbps × 0.8 <` observed
+  segment bitrate for ≥ 15 s) AND the viewer's buffer is low (< 10 s), step
+  one rung down via the existing `#applyBudgetDownshift` (same cooldown,
+  step cap, no upswitch v1). Distinct log reason (`reason=link`) so field
+  logs distinguish CPU-bound from link-bound downshifts.
+
+Missing/stale reports change nothing (old clients keep working — the trigger
+simply never fires). Manual quality pins win: when `manualQuality` is set the
+trigger is skipped.
+
+## Capabilities
+
+### Modified Capabilities
+
+- `transcode-quality`: encodes are bitrate-capped per rung; the budget loop
+  adapts to the viewer's link, not only to the proxy's CPU.
+
+## Impact
+
+- `services/hwaccel.js` — nominal-rate table + caps in the software
+  descriptor's video args.
+- `services/hls-session-manager.js` — accept/store net reports per session;
+  link trigger in the budget check; log line.
+- `routes/api/transcode-sessions/net-report/post.js` (new) + `server.js`
+  wiring — report intake.
+- Proxy release + ha-addon bump. The server-side reporter is a separate
+  change (`server/viewer-net-report`); release proxy+addon FIRST.

package/openspec/changes/adaptive-bitrate/specs/adaptive-bitrate/spec.md

@@ -0,0 +1,51 @@
+# adaptive-bitrate — delta spec (proxy)
+
+## ADDED Requirements
+
+### Requirement: Software encodes are bitrate-capped per resolution rung
+
+Software video encodes SHALL carry `-maxrate`/`-bufsize` derived from a
+per-rung nominal-rate table (1.3× / 1.5× of the rung's nominal), keeping the
+existing CRF/preset quality selection (constrained CRF). The cap follows the
+ACTUAL encode height after budget or manual selection.
+
+#### Scenario: Complex scene on a capped encode
+- **WHEN** a transcoded scene would spike far above the rung's nominal rate
+- **THEN** the produced segments stay bounded by the cap instead of reaching
+  multi-megabyte sizes that a thin viewer link cannot download in time
+
+### Requirement: The proxy accepts viewer link reports
+
+A data-channel route SHALL accept periodic reports
+`{ linkMbps, bufferedAheadSec }` for an active transcode session and store
+the latest report with its arrival time. Invalid bodies are rejected;
+unknown sessions get 404; missing reports are not an error condition.
+
+#### Scenario: Old client
+- **WHEN** a browser never sends net reports
+- **THEN** the session behaves exactly as before this change (plus caps)
+
+### Requirement: The budget loop downshifts on a sustained link deficit
+
+When a fresh report shows the viewer's usable link (reported × safety
+margin) sustainedly below the observed produced bitrate AND the viewer's
+buffer is low, the existing budget downshift SHALL step the encode one rung
+down (same cooldown, step cap and floor as the CPU trigger; no upswitch).
+The trigger SHALL be skipped when `manualQuality` is set, when reports are
+stale, or when the viewer's buffer is comfortable. The downshift log line
+SHALL name the reason (`link`) distinctly from the CPU reason.
+
+#### Scenario: Cellular viewer, stream too fat
+- **WHEN** reports show 3 Mbit/s usable link against 6 Mbit/s produced
+  bitrate for longer than the slow window, with a draining buffer
+- **THEN** the encode steps down one rung and the log shows a link-reason
+  downshift
+
+#### Scenario: Slow link but full buffer
+- **WHEN** the link is slower than the stream but the viewer's buffer stays
+  comfortable (e.g. paused playback filling ahead)
+- **THEN** no downshift happens
+
+#### Scenario: Manual quality pinned
+- **WHEN** the viewer picked a forced quality
+- **THEN** link reports never trigger a downshift

package/openspec/changes/adaptive-bitrate/tasks.md

@@ -0,0 +1,40 @@
+# Tasks: Adaptive bitrate (proxy)
+
+## 1. Caps
+
+- [x] 1.1 `hwaccel.js`: `RUNG_NOMINAL_KBPS` table + nearest-rung lookup;
+      software descriptor's video args emit `-maxrate`/`-bufsize`
+      (1.3× / 1.5× nominal for the actual encode height). Hardware
+      descriptors untouched.
+
+## 2. Net report intake
+
+- [x] 2.1 `routes/api/transcode-sessions/net-report/post.js`: validate
+      `{ linkMbps, bufferedAheadSec }`, store
+      `session.netReport = { linkMbps, bufferedAheadSec, at }`, 204/400/404.
+- [x] 2.2 Wire in `server.js`; verify the data-channel path allowlist covers
+      the route.
+
+## 3. Budget trigger
+
+- [x] 3.1 Constants `LINK_REPORT_FRESH_MS`, `LINK_SAFETY`,
+      `LINK_SLOW_WINDOW_MS`, `LINK_LOW_BUFFER_SEC`.
+- [x] 3.2 Observed produced bitrate (rolling, last ~5 segments) available to
+      the budget check.
+- [x] 3.3 Link deficit accumulation + `#applyBudgetDownshift(session,
+      reason "link")`; skip on manualQuality/stale/comfortable buffer; log
+      reason distinctly.
+
+## 4. Verification
+
+- [x] 4.1 Unit: table lookup, arg assembly, trigger logic (fake clock):
+      deficit→downshift, stale report→no-op, high buffer→no-op,
+      manualQuality→no-op.
+- [x] 4.2 `node --check` on touched files.
+
+## 5. Release
+
+- [ ] 5.1 CHANGELOG (next patch) + `npm run patch` (user OTP), then addon
+      bump + push + HA update. Release BEFORE the server reporter change.
+- [ ] 5.2 Field: cellular Poirot/Mavka run shows `budget downshift (link)`
+      and bounded segment sizes; correlate via client-log pipeline.

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.38",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {

package/routes/api/transcode-sessions/net-report/post.js

@@ -0,0 +1,31 @@
+/**
+ * Accept a viewer link report for a transcode session (adaptive bitrate).
+ * The browser measures its own data-channel throughput per segment fetch and
+ * posts a rolling median + its buffered seconds; the session manager's budget
+ * loop uses the latest report as the link-deficit downshift trigger.
+ *
+ * POST /api/transcode-sessions/:sessionId/net-report
+ * Body: { linkMbps: number, bufferedAheadSec: number }
+ *
+ * Best-effort telemetry: invalid body → 400, unknown session → 404, ok → 204.
+ *
+ * @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 handleApiTranscodeSessionNetReportPost(req, reply, { hlsSessionManager }) {
+  const sessionId = typeof req.params.sessionId === "string" ? req.params.sessionId : "";
+  const body = req.body && typeof req.body === "object" && !Array.isArray(req.body) ? req.body : {};
+  const linkMbps = Number(body.linkMbps);
+  const bufferedAheadSec = Number(body.bufferedAheadSec);
+  if (!sessionId || !Number.isFinite(linkMbps) || linkMbps <= 0 || !Number.isFinite(bufferedAheadSec) || bufferedAheadSec < 0) {
+    return reply.code(400).send({ error: "linkMbps (>0) and bufferedAheadSec (>=0) are required." });
+  }
+
+  const recorded = hlsSessionManager.recordNetReport(sessionId, { linkMbps, bufferedAheadSec });
+  if (!recorded) {
+    return reply.code(404).send({ error: "Transcode session was not found." });
+  }
+  return reply.code(204).send();
+}

package/server.js

@@ -24,6 +24,7 @@ import { handleApiSubtitlesGet } from "./routes/api/subtitles/get.js";
 import { handleApiTranscodeSessionsPost } from "./routes/api/transcode-sessions/post.js";
 import { handleApiTranscodeSessionsProgressGet } from "./routes/api/transcode-sessions/progress/get.js";
 import { handleApiTranscodeSessionReleasePost } from "./routes/api/transcode-sessions/release/post.js";
+import { handleApiTranscodeSessionNetReportPost } from "./routes/api/transcode-sessions/net-report/post.js";
 import { handleStreamGet } from "./routes/stream/get.js";
 import { handleTranscodeSessionFileGet } from "./routes/transcode/session-file/get.js";
 import { createSourceRegistry } from "./store/source-registry.js";
@@ -186,6 +187,9 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin,
   app.get("/api/transcode-sessions/:sessionId/progress", async (req, reply) =>
     handleApiTranscodeSessionsProgressGet(req, reply, { hlsSessionManager })
   );
+  app.post("/api/transcode-sessions/:sessionId/net-report", async (req, reply) =>
+    handleApiTranscodeSessionNetReportPost(req, reply, { hlsSessionManager })
+  );
   app.get("/transcode/:sessionId/:fileName", async (req, reply) =>
     handleTranscodeSessionFileGet(req, reply, { hlsSessionManager })
   );

package/services/hls-session-manager.js

@@ -8,7 +8,7 @@
  */
 
 import { createReadStream } from "node:fs";
-import { access, mkdir, readdir, readFile, rm } from "node:fs/promises";
+import { access, mkdir, readdir, readFile, rm, stat } from "node:fs/promises";
 import { Readable } from "node:stream";
 import os from "node:os";
 import path from "node:path";
@@ -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
@@ -73,6 +84,24 @@ const BUDGET_MAX_DOWNSHIFTS = 3;
 // multiple of the source's average byte rate. Below it (and not yet fully
 // downloaded), a low speed is download-bound, not CPU-bound → do NOT downscale.
 const BUDGET_DOWNLOAD_OK_FACTOR = 1.0;
+// Viewer-link adaptation (adaptive bitrate, part b). The browser reports its
+// measured data-channel throughput + buffered seconds every ~10 s; when a
+// FRESH report shows the usable link (reported × safety margin) sustainedly
+// below the observed produced bitrate AND the viewer's buffer is low, the
+// budget loop steps the encode one rung down — same machinery, cooldown and
+// floor as the CPU trigger. Manual-quality sessions are inherently exempt
+// (their budgetLadder is null).
+const LINK_REPORT_FRESH_MS = 30_000;
+// Usable share of the reported link (protocol overhead + measurement noise).
+const LINK_SAFETY = 0.8;
+// Deficit must persist this long before acting (absorbs one slow segment).
+const LINK_SLOW_WINDOW_MS = 15_000;
+// Only act while the viewer is actually running dry; a comfortable buffer
+// (e.g. paused playback filling ahead) suppresses the trigger.
+const LINK_LOW_BUFFER_SEC = 10;
+// Observed produced bitrate: average over this many recently completed
+// segments (the newest file on disk may still be written and is excluded).
+const LINK_OBSERVED_SEGMENTS = 5;
 const MICROSECONDS_PER_SECOND = 1_000_000;
 const PROGRESS_LOG_INTERVAL_MS = 5_000;
 // Read segment files in large blocks so the body is delivered to the data
@@ -862,6 +891,10 @@ export class HlsSessionManager {
       budgetDownshifts: 0,
       budgetSlowSince: 0,
       budgetLastActionAt: 0,
+      // Latest viewer link report ({ linkMbps, bufferedAheadSec, at }) and the
+      // link-deficit slow window (mirrors budgetSlowSince for the CPU path).
+      netReport: null,
+      linkSlowSince: 0,
       sourceWidth,
       sourceHeight,
       // Container start time (seconds); subtracted on the copy path so the
@@ -884,6 +917,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,
@@ -1070,6 +1109,110 @@ export class HlsSessionManager {
    *
    * @returns {Promise<void>}
    */
+  /**
+   * Record the latest viewer link report for a session (adaptive bitrate).
+   * Returns false for an unknown/disposed session.
+   *
+   * @param {string} sessionId
+   * @param {{ linkMbps: number, bufferedAheadSec: number }} report
+   * @returns {boolean}
+   */
+  recordNetReport(sessionId, { linkMbps, bufferedAheadSec }) {
+    const session = this.sessionsById.get(sessionId);
+    if (!session || session.state === "disposed") {
+      return false;
+    }
+    session.netReport = { linkMbps, bufferedAheadSec, at: Date.now() };
+    return true;
+  }
+
+  /**
+   * Observed produced bitrate (Mbit/s) averaged over the last few COMPLETED
+   * segment files (the newest file may still be being written and is
+   * excluded). Transcode sessions only — their segment grid is uniform, so
+   * bytes / (count × segDur) is exact. Returns null when there is not enough
+   * material to measure.
+   *
+   * @param {HlsSession} session
+   * @returns {Promise<number | null>}
+   */
+  async #observedStreamMbps(session) {
+    let names;
+    try {
+      names = await readdir(session.dirPath);
+    } catch {
+      return null;
+    }
+    const indices = [];
+    for (const name of names) {
+      const match = /^segment-(\d{5})\.ts$/.exec(name);
+      if (match) {
+        indices.push(parseInt(match[1], 10));
+      }
+    }
+    if (indices.length < 3) {
+      return null; // need ≥2 completed segments after dropping the newest
+    }
+    indices.sort((a, b) => a - b);
+    const completed = indices.slice(0, -1).slice(-LINK_OBSERVED_SEGMENTS);
+    let bytes = 0;
+    try {
+      for (const index of completed) {
+        const st = await stat(path.join(session.dirPath, `segment-${String(index).padStart(5, "0")}.ts`));
+        bytes += st.size;
+      }
+    } catch {
+      return null; // a segment vanished mid-measure (seek-restart cleanup)
+    }
+    return (bytes * 8) / (completed.length * this.segmentDurationSec) / 1e6;
+  }
+
+  /**
+   * Viewer-link deficit check for one session (adaptive bitrate, part b).
+   * Mirrors the CPU slow-window pattern; shares the action cooldown and the
+   * downshift machinery. Returns true when a downshift was applied this tick.
+   *
+   * @param {HlsSession} session
+   * @param {number} now
+   * @returns {Promise<boolean>}
+   */
+  async #checkLinkBudget(session, now) {
+    const report = session.netReport;
+    if (!report || now - report.at > LINK_REPORT_FRESH_MS) {
+      session.linkSlowSince = 0; // no fresh data — old clients / stopped reporter
+      return false;
+    }
+    if (report.bufferedAheadSec >= LINK_LOW_BUFFER_SEC) {
+      session.linkSlowSince = 0; // viewer is comfortable — nothing to fix
+      return false;
+    }
+    const observed = await this.#observedStreamMbps(session);
+    if (observed === null) {
+      return false; // not enough produced material to compare against
+    }
+    if (report.linkMbps * LINK_SAFETY >= observed) {
+      session.linkSlowSince = 0; // link keeps up
+      return false;
+    }
+    if (session.linkSlowSince === 0) {
+      session.linkSlowSince = now;
+      return false;
+    }
+    if (now - session.linkSlowSince < LINK_SLOW_WINDOW_MS) {
+      return false; // not sustained yet
+    }
+    if (now - session.budgetLastActionAt < BUDGET_ACTION_COOLDOWN_MS) {
+      return false; // let the previous action settle
+    }
+    this.#applyBudgetDownshift(
+      session,
+      `link=${report.linkMbps.toFixed(2)}Mbps stream=${observed.toFixed(2)}Mbps buffer=${report.bufferedAheadSec.toFixed(1)}s`,
+      "link"
+    );
+    session.linkSlowSince = 0;
+    return true;
+  }
+
   async #enforceRealtimeBudget() {
     if (this.videoEncoder?.kind !== "software") {
       return;
@@ -1093,6 +1236,13 @@ export class HlsSessionManager {
       ) {
         continue;
       }
+      // Viewer-link deficit first (adaptive bitrate): independent of encoder
+      // speed — a thin cellular link starves even a faster-than-realtime
+      // encode. When it acts, skip the CPU check this tick (shared cooldown
+      // guards double-firing anyway).
+      if (await this.#checkLinkBudget(session, now)) {
+        continue;
+      }
       const speed = this.#parseSpeed(session.progress?.speed);
       if (speed === null) {
         continue; // no measurement yet
@@ -1126,7 +1276,7 @@ export class HlsSessionManager {
         session.budgetSlowSince = 0; // re-evaluate fresh; don't thrash on this
         continue;
       }
-      this.#applyBudgetDownshift(session, speed, bound);
+      this.#applyBudgetDownshift(session, `speed=${speed.toFixed(2)}x`, bound);
     }
   }
 
@@ -1172,11 +1322,11 @@ export class HlsSessionManager {
    * encode at the current segment with the lighter profile.
    *
    * @param {HlsSession} session
-   * @param {number} speed - The measured (sub-realtime) speed, for logging.
-   * @param {"cpu" | "unknown"} bound
+   * @param {string} reasonText - Measurement summary for the log line.
+   * @param {"cpu" | "unknown" | "link"} bound
    * @returns {void}
    */
-  #applyBudgetDownshift(session, speed, bound) {
+  #applyBudgetDownshift(session, reasonText, bound) {
     const nextIndex = session.budgetRungIndex + 1;
     const rung = session.budgetLadder[nextIndex];
     if (!rung) {
@@ -1197,9 +1347,11 @@ export class HlsSessionManager {
       ? session.progress.processedSeconds
       : this.#segmentStartTime(session, head);
     const currentSeg = Math.max(head, this.#segmentIndexForTime(session, processed));
+    const boundLabel =
+      bound === "link" ? "viewer-link-bound" : bound === "unknown" ? "assuming CPU-bound" : "CPU-bound";
     logger.info(
-      `[budget] transcode ${session.id} ${bound === "unknown" ? "assuming CPU-bound" : "CPU-bound"} ` +
-        `speed=${speed.toFixed(2)}x → downscale to ${rung.width}x${rung.height}/${session.softwarePreset} ` +
+      `[budget] transcode ${session.id} ${boundLabel} ` +
+        `${reasonText} → downscale to ${rung.width}x${rung.height}/${session.softwarePreset} ` +
         `(rung ${nextIndex + 1}/${session.budgetLadder.length}, downshift ${session.budgetDownshifts}/${BUDGET_MAX_DOWNSHIFTS}), ` +
         `restart at segment #${currentSeg} "${session.fileName}"`
     );
@@ -1492,22 +1644,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 +1925,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);

package/services/hwaccel.js

@@ -75,6 +75,54 @@ export function chooseOutputFps(sourceFps, cap = MAX_OUTPUT_FPS) {
 // Software x264 on weak ARM hosts is the transcode bottleneck — use all cores.
 const CPU_THREADS = Math.max(1, os.cpus().length);
 
+// Bitrate caps (constrained CRF). CRF stays the quality driver; -maxrate/
+// -bufsize only bound the peaks. Field evidence (iPhone on cellular,
+// 2026-07-10): uncapped complex scenes produced 4 s segments of ~18 Mbit/s
+// against a 1-6 Mbit/s viewer link — 45 s prebuffer, draining buffer.
+// Nominal H.264 rates per rung height; multipliers from webtor's production
+// ladder (content-transcoder): maxrate = 1.3x nominal, bufsize = 1.5x.
+const RUNG_NOMINAL_KBPS = [
+  [1080, 5000],
+  [720, 2800],
+  [480, 1400],
+  [360, 800],
+  [240, 400]
+];
+const CAP_MAXRATE_FACTOR = 1.3;
+const CAP_BUFSIZE_FACTOR = 1.5;
+
+/**
+ * Nominal kbps for an encode height: nearest rung wins (odd heights snap to
+ * the closest standard rung; anything above the top rung uses the top one).
+ *
+ * @param {number} height
+ * @returns {number}
+ */
+export function nominalKbpsForHeight(height) {
+  const h = Number.isFinite(height) && height > 0 ? height : 720;
+  let best = RUNG_NOMINAL_KBPS[0];
+  for (const rung of RUNG_NOMINAL_KBPS) {
+    if (Math.abs(rung[0] - h) < Math.abs(best[0] - h)) {
+      best = rung;
+    }
+  }
+  return best[1];
+}
+
+/**
+ * `-maxrate`/`-bufsize` args for an encode height (constrained CRF).
+ *
+ * @param {number} height
+ * @returns {string[]}
+ */
+function bitrateCapArgs(height) {
+  const nominal = nominalKbpsForHeight(height);
+  return [
+    "-maxrate", `${Math.round(nominal * CAP_MAXRATE_FACTOR)}k`,
+    "-bufsize", `${Math.round(nominal * CAP_BUFSIZE_FACTOR)}k`
+  ];
+}
+
 // libx264 presets to benchmark, ordered slowest/highest-quality → fastest.
 const BENCHMARK_PRESETS = ["fast", "faster", "veryfast", "superfast", "ultrafast"];
 const BENCHMARK_REF_W = 640;
@@ -140,6 +188,11 @@ export function softwareDescriptor() {
         // faster than realtime); falls back to the static default.
         "-preset", chosenPreset,
         "-crf", SOFTWARE_CRF,
+        // Constrained CRF: bound peak bitrate per rung so a complex scene
+        // cannot produce segments a thin viewer link (cellular) can't
+        // download in time. Sized by the TARGET box height (the rung the
+        // budget/manual selection chose).
+        ...bitrateCapArgs(h),
         "-threads", String(CPU_THREADS),
         "-pix_fmt", "yuv420p",
         // Fixed GOP: a keyframe exactly every (segmentDurationSec × fps) frames,