@torrent-tv/proxy 2.9.37 → 2.9.38

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 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`.)

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.9.37",
+  "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";
@@ -84,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
@@ -873,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
@@ -1087,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;
@@ -1110,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
@@ -1143,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);
     }
   }
 
@@ -1189,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) {
@@ -1214,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}"`
     );

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,