@torrent-tv/proxy 2.9.30 → 2.9.32

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 2.9.32
+
+- **New**: Manual quality support (OpenSpec change `transcode-quality`, part 4). The playback plan now reports the source coded resolution (`videoWidth`/`videoHeight`, parsed from the ffprobe banner) so the browser can offer a quality menu. `POST /api/transcode-sessions` accepts `manualQuality: true`: the requested target box is then encoded exactly (capped to the source, never upscaled) with the realtime budget disabled for that session — no startup auto-downscale and no runtime downswitch — so a viewer-forced resolution stays constant for the whole session. `manualQuality` is part of the session key (a forced-quality session is distinct from Auto). Logged as `enc=WxH@fps quality=manual`. Auto (no flag) is unchanged: the realtime budget decides. Pairs with the server release that adds the player quality menu.
+
+## 2.9.31
+
+- **New**: Realtime transcode budget — startup resolution + preset selection (OpenSpec change `transcode-quality`, part 2.1). For the software encoder the proxy now picks the output RESOLUTION as well as the libx264 preset from the startup benchmark: the client-requested box (capped to the source, never upscaled) is the ceiling, and the proxy chooses the highest resolution rung at or below it that the benchmark predicts encodes faster than realtime (with the existing margin), then the best preset at that resolution. On a weak host this downscales (e.g. a 720p60→30 stream that ran at ~0.9× on a Home Assistant box now encodes at ~480p in realtime) instead of dropping into sub-realtime playback with constant stalls. Capable hosts keep full resolution and spend the headroom on a higher-quality preset; hardware encoders and the no-benchmark case are unchanged. Also fixed the realtime-need calculation to use the session's actual output frame rate instead of the fixed 24 fps constant (it under-counted for 25/30 fps content). The chosen encode resolution is logged (`enc=WxH@fps budget=on`). This scales down from the orientation-independent ceiling the browser now sends (server 0.8.43).
+- **New**: Realtime transcode budget — runtime downswitch (OpenSpec change `transcode-quality`, part 2.2). If a software transcode runs below realtime for a sustained window (ffmpeg `speed` < ~0.95× for ~15 s), the proxy steps the resolution one rung down the ladder and restarts the encode at the segment the viewer is on, so a stream that starts fine but bogs down on a heavy passage recovers instead of stalling. It first checks the bottleneck: if the torrent download can't sustain the source's byte rate (and the file isn't fully downloaded), the limit is the download, not the encoder — the proxy logs that and does NOT degrade quality. Conservative guards prevent thrash: a 30 s post-action cooldown, at most 3 downshifts, a resolution floor, the slow window reset on every (re)start, and no automatic upswitch yet. The switch point uses a hard encoder restart (a brief blip is possible there; a seamless discontinuity/parallel tier is a later refinement). Logged as `[budget] … CPU-bound speed=… → downscale to WxH` or `… download-limited; not downscaling`.
+
 ## 2.9.30
 
 - **New**: The proxy owns subtitle conversion and detects the language from content (OpenSpec change `subtitle-language`). `GET /api/subtitles` now also serves EXTERNAL subtitle files (no `trackIndex`): it reads the file, decodes its encoding (UTF-8 or Windows-1251 — common for Russian `.srt`), converts `.srt`/`.ass`/`.ssa` → WebVTT on the proxy (the browser no longer converts), and reports the language in `X-Subtitle-Language`/`X-Subtitle-Language-Name`. Language is detected with `franc` (n-gram, MIT) restricted to a curated language set — it distinguishes Russian from Ukrainian (and Latin languages) and avoids short-text false positives, returning no header when undetermined. Embedded tracks detect from the first chunk of extracted VTT. Pairs with the server release that fetches VTT from here and applies the filename → content → audio-language priority.

package/openspec/changes/transcode-quality/specs/transcode-quality/spec.md

@@ -35,3 +35,85 @@ chosen encoder places keyframes:
 - **WHEN** the source frame rate cannot be probed on the software path
 - **THEN** the output falls back to the default rate and playback still
   segments correctly
+
+### Requirement: Software encode fits a realtime budget at startup
+
+For the software encoder, the proxy SHALL choose the output resolution and
+libx264 preset a startup benchmark predicts this host can encode faster than
+realtime (with a margin), rather than always encoding at the client-requested
+resolution. The client-requested box, capped to the source resolution (never
+upscaled), is the ceiling; the proxy SHALL pick the highest resolution rung at
+or below that ceiling that clears the realtime margin, then the highest-quality
+preset that still clears it at that resolution. When even the lowest rung
+cannot clear the margin, the proxy SHALL use the lowest rung (best effort). The
+realtime need SHALL be computed from the session's actual output frame rate.
+Hardware encoders and the no-benchmark case SHALL keep the ceiling resolution
+and the default preset.
+
+#### Scenario: Weak host, source above realtime capacity
+- **WHEN** the software benchmark shows the host cannot encode the source-capped
+  resolution faster than realtime (e.g. 720p60→30 that runs below 1×)
+- **THEN** the proxy downscales to the highest ladder rung that clears the
+  realtime margin (e.g. 480p) instead of encoding sub-realtime at full size
+
+#### Scenario: Capable host
+- **WHEN** the benchmark shows ample headroom at the ceiling resolution
+- **THEN** the proxy keeps the ceiling resolution and spends the headroom on a
+  higher-quality (slower) preset
+
+#### Scenario: Hardware encoder
+- **WHEN** a hardware encoder is selected
+- **THEN** no benchmark-based downscale is applied and the ceiling resolution
+  is used
+
+### Requirement: Software encode downswitches at runtime when CPU-bound
+
+The proxy SHALL, for the software encoder, step the output resolution one rung
+down the ladder and restart the encode at the segment currently being watched
+when a transcode runs below realtime for a sustained window. Before downscaling
+it SHALL determine whether the limit is the encoder or a download-starved
+input — comparing the torrent download rate with the source's average byte rate
+(a fully-downloaded file is never download-bound) — and SHALL NOT downscale when
+the limit is the download (it SHALL log that instead). The downswitch SHALL be
+bounded by a sustained-slow window, a post-action cooldown, a maximum number of
+steps, and a resolution floor, and SHALL reset its slow window on every encode
+(re)start. There SHALL be no automatic upswitch in this version.
+
+#### Scenario: Sustained CPU-bound transcode
+- **WHEN** a software transcode's encoder speed stays below realtime for the
+  sustained window while the input download keeps up
+- **THEN** the proxy downscales one rung and restarts at the current segment,
+  up to the step cap / resolution floor
+
+#### Scenario: Download-limited, not CPU-limited
+- **WHEN** the encoder speed is below realtime but the torrent cannot download
+  the source's byte rate and the file is not fully downloaded
+- **THEN** the proxy does not downscale and logs that the download is the limit
+
+#### Scenario: No thrash after a switch
+- **WHEN** a downswitch (or a viewer seek) has just restarted the encode
+- **THEN** the slow window is reset and no further downswitch occurs until a new
+  sustained-slow window elapses after the cooldown
+
+### Requirement: Manual quality forces a constant resolution
+
+The viewer SHALL be able to force a specific output resolution instead of Auto.
+When a resolution is forced the proxy SHALL encode exactly that box (capped to
+the source, never upscaled) with the realtime budget disabled — no startup
+auto-downscale and no runtime downswitch — so the resolution stays constant for
+the whole session. The browser SHALL offer Auto plus resolutions at or below the
+source height, built from the source resolution reported in the playback plan.
+Selecting a quality SHALL re-open the stream at the new resolution with the
+playback position preserved. Auto SHALL keep the current realtime-budget
+behaviour.
+
+#### Scenario: Forced resolution is constant
+- **WHEN** the viewer forces a resolution (e.g. 480p)
+- **THEN** the proxy encodes at that resolution for the whole session, with no
+  budget downscale or runtime downswitch, and playback resumes at the same
+  position
+
+#### Scenario: Auto
+- **WHEN** the viewer selects Auto
+- **THEN** the proxy applies the realtime budget (startup selection + runtime
+  downswitch) as before

package/openspec/changes/transcode-quality/tasks.md

@@ -11,11 +11,27 @@
 - [x] 1.3 Unit-verify fps choice and fps↔GOP consistency (25→100, 24→96,
       default→96); syntax checks
 
-## 2. Realtime budget (planned)
-
-- [ ] 2.1 Benchmark picks encoder/preset/resolution/fps within a realtime
-      margin; downscale instead of refuse
-- [ ] 2.2 Runtime `speed<1` watch → restart with a lighter profile
+## 2. Realtime budget
+
+- [x] 2.1 Startup: benchmark picks resolution + preset within a realtime
+      margin; downscale below the client-target ceiling instead of refusing
+      (`chooseSoftwareEncodeSettings`/`buildResolutionLadder` in hwaccel;
+      `#chooseEncodeBudget` + `encodeWidth`/`encodeHeight` in the session
+      manager; fixed the needed-pixels calc to use the session's `outputFps`
+      not the fixed `TRANSCODE_FPS`). Verified on the FIFA host profile
+      (720p60→480p) + strong/weak/no-benchmark profiles.
+- [x] 2.2 Runtime `speed<1` watch → step down the resolution ladder + restart
+      at the current segment (hard-restart tier). Gate on CPU-bound only:
+      compare `getFileStats().downloadSpeed` with the source byte-rate so a
+      download-starved input is NOT misread as an encoder limit (don't degrade
+      quality for a download bottleneck — log it instead). Hysteresis +
+      cooldown + floor + max steps; slow window reset on every (re)start; no
+      upswitch in v1 (oscillation risk). `#enforceRealtimeBudget` +
+      `#classifyTranscodeBound` + `#applyBudgetDownshift` in the session
+      manager; `getSourceStats` injected from server.js.
+      NOTE (follow-up 2.2b): seamless switch via `EXT-X-DISCONTINUITY` /
+      parallel encoder tier keyed by host resources — the hard restart can blip
+      at the switch point.
 - [ ] 2.3 `-maxrate`/`-bufsize`
 
 ## 3. HDR tone mapping (planned)
@@ -23,10 +39,17 @@
 - [ ] 3.1 Detect 10-bit/HDR; insert tonemap chain when re-encoding to 8-bit
 - [ ] 3.2 Guard on tonemap-filter availability in the ffmpeg build
 
-## 4. Manual quality (planned)
-
-- [ ] 4.1 Proxy honours requested target height (already partly there)
-- [ ] 4.2 Server Quality menu (Auto + forced resolutions)
+## 4. Manual quality
+
+- [x] 4.1 Proxy honours a forced resolution: `manualQuality` flag on the
+      transcode-session request encodes the requested box exactly (capped to
+      source, budget + runtime downswitch disabled); `manualQuality` in the
+      session key; playback plan reports source `videoWidth`/`videoHeight`.
+- [x] 4.2 Server Quality menu (Auto + forced resolutions <= source). Custom
+      media-chrome submenu mirroring the audio menu; selection re-opens the
+      stream at the forced resolution with the position preserved (reuses the
+      audio-switch machinery); shared settings button shows for audio OR
+      quality.
 
 ## 5. Release
 

package/package.json

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

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

@@ -33,6 +33,10 @@ export async function handleApiTranscodeSessionsPost(req, reply, { hlsSessionMan
   const fileName = typeof payload.fileName === "string" ? payload.fileName.trim() : "";
   const targetWidth = Number(payload.targetWidth);
   const targetHeight = Number(payload.targetHeight);
+  // Manual quality: the target box is a user-forced resolution, encoded exactly
+  // (capped to source), with the realtime budget's auto-downscale + runtime
+  // downswitch disabled for the session.
+  const manualQuality = payload.manualQuality === true;
   const startPositionSeconds = Number(payload.startPositionSeconds);
   const audioTrackIndex = Number(payload.audioTrackIndex);
 
@@ -50,6 +54,7 @@ export async function handleApiTranscodeSessionsPost(req, reply, { hlsSessionMan
       fileName,
       targetWidth: Number.isInteger(targetWidth) && targetWidth > 0 ? targetWidth : 0,
       targetHeight: Number.isInteger(targetHeight) && targetHeight > 0 ? targetHeight : 0,
+      manualQuality,
       startPositionSeconds:
         Number.isFinite(startPositionSeconds) && startPositionSeconds > 0
           ? startPositionSeconds

package/server.js

@@ -117,7 +117,21 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin,
     localBindHost: host,
     localPort: selectedPort,
     videoEncoder,
-    softwarePresetBenchmark
+    softwarePresetBenchmark,
+    // Live download stats accessor for the realtime budget: lets it tell a
+    // CPU-bound transcode from a download-starved input before downscaling.
+    getSourceStats: async (sourceKey, fileIndex) => {
+      const record = sourceRegistry.get(sourceKey);
+      if (!record) {
+        return null;
+      }
+      try {
+        const torrent = await torrentPool.getTorrent(record.sourceType, record.source);
+        return torrentPool.getFileStats(torrent, Number.isInteger(fileIndex) ? fileIndex : null);
+      } catch {
+        return null;
+      }
+    }
   });
   const playbackPlanner = createPlaybackPlanner({
     ffmpegBin,

package/services/hls-session-manager.js

@@ -15,7 +15,13 @@ import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
 import { logger } from "../utils/logger.js";
-import { softwareDescriptor, pickSoftwarePreset, TRANSCODE_FPS, chooseOutputFps } from "./hwaccel.js";
+import {
+  softwareDescriptor,
+  chooseSoftwareEncodeSettings,
+  pickSoftwarePreset,
+  TRANSCODE_FPS,
+  chooseOutputFps
+} from "./hwaccel.js";
 
 const PLAYLIST_FILE_NAME = "index.m3u8";
 const SEGMENT_FILE_NAME_PATTERN = /^segment-\d{5}\.ts$/;
@@ -36,6 +42,30 @@ const RESTART_COOLDOWN_MS = 4_000;
 // segment fetch, so it never expires mid-watch.
 const DEFAULT_SESSION_TTL_MS = 120 * 1000;
 const DEFAULT_STARTUP_WAIT_MS = 5_000;
+// Realtime budget — runtime downswitch (software encoder only). Periodically
+// check each active software-transcode session's ffmpeg `speed`; when it stays
+// below realtime for a sustained window AND the input is not download-starved
+// (so the limit is the encoder, not the torrent), step down one resolution rung
+// and restart at the current segment. Conservative so it never thrashes: a long
+// sustained window, a post-action cooldown, a step cap, and no upswitch (v1).
+const BUDGET_CHECK_INTERVAL_MS = 5_000;
+// Speed below this (cumulative ffmpeg average) counts as "slow"; recovery to
+// realtime resets the slow window (hysteresis).
+const BUDGET_SPEED_SLOW = 0.95;
+const BUDGET_SPEED_OK = 1.0;
+// Slow must persist this long before a downshift (absorbs warm-up + brief
+// complex scenes; the cumulative average won't dip this long unless the host
+// genuinely can't keep up).
+const BUDGET_SUSTAINED_MS = 15_000;
+// After a downshift, wait this long before another (lets the new profile settle
+// and a fresh cumulative average build).
+const BUDGET_ACTION_COOLDOWN_MS = 30_000;
+// Never step down more than this many rungs below the startup choice.
+const BUDGET_MAX_DOWNSHIFTS = 3;
+// The input counts as "keeping up" when the torrent downloads at least this
+// 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;
 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
@@ -625,10 +655,15 @@ export class HlsSessionManager {
     sessionTtlMs = DEFAULT_SESSION_TTL_MS,
     startupWaitMs = DEFAULT_STARTUP_WAIT_MS,
     videoEncoder = null,
-    softwarePresetBenchmark = null
+    softwarePresetBenchmark = null,
+    getSourceStats = null
   }) {
     this.enabled = Boolean(enabled);
     this.ffmpegBin = ffmpegBin;
+    // Optional async accessor for a source's live download stats, used by the
+    // realtime budget to tell a CPU limit from a download-starved input:
+    // (sourceKey, fileIndex) => Promise<{ downloadSpeed, fileLength, fileProgress } | null>.
+    this.getSourceStats = typeof getSourceStats === "function" ? getSourceStats : null;
     // Detected H.264 encoder descriptor (hardware or software). Defaults to
     // software libx264 when no detection result is supplied. May be downgraded
     // to software at runtime if a hardware encode fails.
@@ -647,6 +682,13 @@ export class HlsSessionManager {
       void this.cleanupExpired();
     }, CLEANUP_INTERVAL_MS);
     this.cleanupTimer.unref();
+    // Realtime-budget monitor: only meaningful for the software encoder with a
+    // benchmark (the only path that can pick/step resolution). Cheap no-op scan
+    // otherwise.
+    this.budgetTimer = setInterval(() => {
+      void this.#enforceRealtimeBudget();
+    }, BUDGET_CHECK_INTERVAL_MS);
+    this.budgetTimer.unref();
   }
 
   /**
@@ -667,6 +709,7 @@ export class HlsSessionManager {
    * @param {number}  [options.targetHeight=0]           - Target video height (0 = keep source).
    * @param {number}  [options.startPositionSeconds=0]   - Seek start position in seconds.
    * @param {number}  [options.audioTrackIndex=0]        - Type-relative audio track to map (0:a:N).
+   * @param {boolean} [options.manualQuality=false]      - User-forced resolution: encode the target box exactly (capped to source), no budget downscale / runtime downswitch.
    * @returns {Promise<HlsSession>}
    */
   async createOrGetSession({
@@ -679,7 +722,8 @@ export class HlsSessionManager {
     targetWidth = 0,
     targetHeight = 0,
     startPositionSeconds = 0,
-    audioTrackIndex = 0
+    audioTrackIndex = 0,
+    manualQuality = false
   }) {
     if (!this.enabled) {
       const error = new Error("Audio transcoding is disabled on this proxy.");
@@ -697,6 +741,7 @@ export class HlsSessionManager {
         : 0;
     const normalizedAudioTrack =
       Number.isInteger(audioTrackIndex) && audioTrackIndex > 0 ? audioTrackIndex : 0;
+    const forceManualQuality = manualQuality === true && transcodeVideo;
     const sourceMapKey = [
       sourceKey,
       String(fileIndex),
@@ -705,6 +750,7 @@ export class HlsSessionManager {
       `t${normalizedAudioTrack}`,
       String(normalizedTargetWidth),
       String(normalizedTargetHeight),
+      forceManualQuality ? "q-manual" : "q-auto",
       String(normalizedStartPosition)
     ].join(":");
     const existingId = this.sessionIdBySource.get(sourceMapKey);
@@ -787,17 +833,32 @@ export class HlsSessionManager {
     const usingKeyframeBoundaries = hasDuration && !transcodeVideo && Array.isArray(keyframeTimes);
     const segmentCount = segmentBoundaries.length > 1 ? segmentBoundaries.length - 1 : 0;
 
-    // Pick the highest-quality software preset that still encodes the actual
-    // (source-capped) output resolution faster than realtime. Null for hardware
-    // encoders or when the source size / benchmark is unavailable — buildVideoArgs
-    // then uses its static default preset.
-    const softwarePreset = this.#chooseSoftwarePreset({
-      transcodeVideo,
-      targetWidth: normalizedTargetWidth,
-      targetHeight: normalizedTargetHeight,
-      sourceWidth,
-      sourceHeight
-    });
+    // Realtime budget (software encoder): pick the output resolution + libx264
+    // preset this host can encode faster than realtime. On a weak host this
+    // downscales below the client target (the orientation-independent ceiling)
+    // instead of dropping into sub-realtime playback. Null for hardware
+    // encoders or when the source size / benchmark is unavailable — the encode
+    // then keeps the client target box and buildVideoArgs's default preset.
+    //
+    // Manual quality bypasses the budget entirely: the user forced a specific
+    // resolution, so encode exactly that box (capped to source by the scale
+    // filter) with the default preset, and the runtime downswitch is skipped
+    // for the session (budgetLadder stays null).
+    const encodeBudget = forceManualQuality
+      ? null
+      : this.#chooseEncodeBudget({
+          transcodeVideo,
+          targetWidth: normalizedTargetWidth,
+          targetHeight: normalizedTargetHeight,
+          sourceWidth,
+          sourceHeight,
+          outputFps
+        });
+    const softwarePreset = encodeBudget?.preset ?? null;
+    // Effective encode box: the budget's downscaled resolution when applied,
+    // otherwise the client target (0 = keep source, handled by buildVideoArgs).
+    const encodeWidth = encodeBudget?.width ?? normalizedTargetWidth;
+    const encodeHeight = encodeBudget?.height ?? normalizedTargetHeight;
 
     const session = {
       id: sessionId,
@@ -818,8 +879,24 @@ export class HlsSessionManager {
       transcodeAudio,
       audioTrackIndex: normalizedAudioTrack,
       outputFps,
+      // Client-requested target box (the orientation-independent ceiling). Kept
+      // for the session key and reference; the actual encode uses encodeWidth/
+      // encodeHeight, which the realtime budget may have downscaled below this.
       targetWidth: normalizedTargetWidth,
       targetHeight: normalizedTargetHeight,
+      // Effective encode resolution handed to ffmpeg (budget-selected on weak
+      // software hosts, else the client target). 0 = keep source.
+      encodeWidth,
+      encodeHeight,
+      // Realtime-budget runtime state (software encoder only). The ladder is the
+      // resolution rungs from the ceiling down; rungIndex is the current rung.
+      // The monitor steps rungIndex down when the encoder is sustainedly
+      // CPU-bound and restarts ffmpeg at the current segment.
+      budgetLadder: encodeBudget?.ladder ?? null,
+      budgetRungIndex: Number.isInteger(encodeBudget?.rungIndex) ? encodeBudget.rungIndex : 0,
+      budgetDownshifts: 0,
+      budgetSlowSince: 0,
+      budgetLastActionAt: 0,
       sourceWidth,
       sourceHeight,
       // Container start time (seconds); subtracted on the copy path so the
@@ -866,6 +943,10 @@ export class HlsSessionManager {
         `branch=${transcodeVideo ? "A(reencode,fixed-gop)" : "B(copy,copyts)"} ` +
         `seg=${usingKeyframeBoundaries ? "keyframe" : "uniform"} ` +
         `${sourceWidth && sourceHeight ? `src=${sourceWidth}x${sourceHeight} ` : ""}` +
+        // Effective encode resolution: budget-on (auto downscale from the
+        // ceiling), manual (user-forced, budget off), or unset (keep source).
+        `${transcodeVideo && encodeBudget ? `enc=${encodeWidth}x${encodeHeight}@${outputFps} budget=on ` : ""}` +
+        `${transcodeVideo && forceManualQuality ? `enc=${encodeWidth || "src"}x${encodeHeight || "src"}@${outputFps} quality=manual ` : ""}` +
         `${sourceStartTime ? `start=${sourceStartTime.toFixed(3)} ` : ""}` +
         `duration=${hasDuration ? formatSeconds(durationSeconds) : "unknown"} segments=${segmentCount}`
     );
@@ -971,25 +1052,190 @@ export class HlsSessionManager {
   }
 
   /**
-   * Choose the libx264 preset for a software video transcode: the highest
-   * quality the startup benchmark says this host can encode at the actual
-   * (source-capped) output resolution faster than realtime. Returns null when
-   * not applicable (no video transcode, hardware encoder, or missing
-   * benchmark/source size) — buildVideoArgs then uses its default preset.
+   * Realtime budget (software encoder only): choose the output resolution AND
+   * libx264 preset this host can encode faster than realtime, from the startup
+   * benchmark. The ceiling is the client-requested box capped to the source
+   * (never upscaled); the budget picks the highest resolution rung at or below
+   * that ceiling that clears realtime × margin, then the best preset at that
+   * resolution. On a weak host this downscales below the client target instead
+   * of dropping into sub-realtime playback. Returns null when not applicable
+   * (no video transcode, hardware encoder, or missing benchmark/source size) —
+   * the encode then keeps the ceiling resolution and the default preset.
    *
-   * @param {{ transcodeVideo: boolean, targetWidth: number, targetHeight: number, sourceWidth: number | null, sourceHeight: number | null }} params
-   * @returns {string | null}
+   * @param {{ transcodeVideo: boolean, targetWidth: number, targetHeight: number, sourceWidth: number | null, sourceHeight: number | null, outputFps: number }} params
+   * @returns {{ width: number, height: number, preset: string } | null}
    */
-  #chooseSoftwarePreset({ transcodeVideo, targetWidth, targetHeight, sourceWidth, sourceHeight }) {
+  #chooseEncodeBudget({ transcodeVideo, targetWidth, targetHeight, sourceWidth, sourceHeight, outputFps }) {
     if (!transcodeVideo || this.videoEncoder?.kind !== "software" || !this.softwarePresetBenchmark) {
       return null;
     }
-    const out = computeOutputDimensions(targetWidth, targetHeight, sourceWidth, sourceHeight);
-    if (!out) {
+    const ceiling = computeOutputDimensions(targetWidth, targetHeight, sourceWidth, sourceHeight);
+    if (!ceiling) {
+      return null;
+    }
+    return chooseSoftwareEncodeSettings(this.softwarePresetBenchmark, { width: ceiling.w, height: ceiling.h }, outputFps);
+  }
+
+  /**
+   * Parse ffmpeg's `speed` progress value (e.g. "0.903x", "1.6x", "N/A") into a
+   * number. Returns null when it cannot be parsed (no data yet).
+   *
+   * @param {string} value
+   * @returns {number | null}
+   */
+  #parseSpeed(value) {
+    if (typeof value !== "string" || value.length === 0) {
       return null;
     }
-    const pixelsPerSecNeeded = out.w * out.h * TRANSCODE_FPS;
-    return pickSoftwarePreset(this.softwarePresetBenchmark, pixelsPerSecNeeded);
+    const numeric = Number.parseFloat(value);
+    return Number.isFinite(numeric) && numeric > 0 ? numeric : null;
+  }
+
+  /**
+   * Realtime budget monitor (software encoder only). For each active
+   * software-transcode session, watch the encoder's cumulative `speed`: when it
+   * stays below realtime for a sustained window AND the input is not
+   * download-starved (so the limit is the encoder, not the torrent), step the
+   * resolution one rung down the ladder and restart the encode at the current
+   * segment. Conservative: sustained window, post-action cooldown, a step cap,
+   * and a resolution floor (the last ladder rung). No upswitch in v1.
+   *
+   * @returns {Promise<void>}
+   */
+  async #enforceRealtimeBudget() {
+    if (this.videoEncoder?.kind !== "software") {
+      return;
+    }
+    const now = Date.now();
+    for (const session of this.sessionsById.values()) {
+      if (
+        !session ||
+        session.state === "disposed" ||
+        session.state === "failed" ||
+        !session.transcodeVideo ||
+        !Array.isArray(session.budgetLadder) ||
+        session.budgetLadder.length < 2
+      ) {
+        continue;
+      }
+      // Already at the floor or out of steps — nothing more to give.
+      if (
+        session.budgetRungIndex >= session.budgetLadder.length - 1 ||
+        session.budgetDownshifts >= BUDGET_MAX_DOWNSHIFTS
+      ) {
+        continue;
+      }
+      const speed = this.#parseSpeed(session.progress?.speed);
+      if (speed === null) {
+        continue; // no measurement yet
+      }
+      if (speed >= BUDGET_SPEED_OK) {
+        session.budgetSlowSince = 0; // recovered — reset the slow window
+        continue;
+      }
+      if (speed >= BUDGET_SPEED_SLOW) {
+        continue; // in the hysteresis band; neither slow nor ok
+      }
+      // speed < BUDGET_SPEED_SLOW — track how long it has been slow.
+      if (session.budgetSlowSince === 0) {
+        session.budgetSlowSince = now;
+        continue;
+      }
+      if (now - session.budgetSlowSince < BUDGET_SUSTAINED_MS) {
+        continue; // not sustained yet
+      }
+      if (now - session.budgetLastActionAt < BUDGET_ACTION_COOLDOWN_MS) {
+        continue; // let the previous action settle
+      }
+      // Sustained sub-realtime. Only downscale if the encoder — not a
+      // download-starved input — is the limit.
+      const bound = await this.#classifyTranscodeBound(session);
+      if (bound === "download") {
+        logger.info(
+          `[budget] transcode ${session.id} speed=${speed.toFixed(2)}x but download-limited ` +
+            `"${session.fileName}"; not downscaling (torrent is the bottleneck)`
+        );
+        session.budgetSlowSince = 0; // re-evaluate fresh; don't thrash on this
+        continue;
+      }
+      this.#applyBudgetDownshift(session, speed, bound);
+    }
+  }
+
+  /**
+   * Decide whether a sustained sub-realtime transcode is limited by the encoder
+   * (CPU) or by a download-starved input. Compares the torrent's download rate
+   * with the source's average byte rate; a fully-downloaded file can never be
+   * download-bound. Returns "cpu" | "download" | "unknown" ("unknown" is treated
+   * as CPU by the caller — the common case, logged as such).
+   *
+   * @param {HlsSession} session
+   * @returns {Promise<"cpu" | "download" | "unknown">}
+   */
+  async #classifyTranscodeBound(session) {
+    if (!this.getSourceStats) {
+      return "unknown";
+    }
+    let stats;
+    try {
+      stats = await this.getSourceStats(session.sourceKey, session.fileIndex);
+    } catch {
+      return "unknown";
+    }
+    if (!stats) {
+      return "unknown";
+    }
+    // A fully (or almost fully) downloaded file cannot be download-bound.
+    if (typeof stats.fileProgress === "number" && stats.fileProgress >= 0.999) {
+      return "cpu";
+    }
+    const duration = Number.isFinite(session.totalDurationSeconds) ? session.totalDurationSeconds : 0;
+    const length = Number.isFinite(stats.fileLength) && stats.fileLength > 0 ? stats.fileLength : 0;
+    const downloadSpeed = Number.isFinite(stats.downloadSpeed) ? stats.downloadSpeed : 0;
+    if (duration <= 0 || length <= 0) {
+      return "unknown"; // cannot compute the source byte rate
+    }
+    const sourceByteRate = length / duration;
+    return downloadSpeed >= sourceByteRate * BUDGET_DOWNLOAD_OK_FACTOR ? "cpu" : "download";
+  }
+
+  /**
+   * Step a session one resolution rung down the budget ladder and restart the
+   * 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
+   * @returns {void}
+   */
+  #applyBudgetDownshift(session, speed, bound) {
+    const nextIndex = session.budgetRungIndex + 1;
+    const rung = session.budgetLadder[nextIndex];
+    if (!rung) {
+      return;
+    }
+    const fps = Number.isInteger(session.outputFps) && session.outputFps > 0 ? session.outputFps : TRANSCODE_FPS;
+    session.budgetRungIndex = nextIndex;
+    session.budgetDownshifts += 1;
+    session.budgetLastActionAt = Date.now();
+    session.budgetSlowSince = 0;
+    session.encodeWidth = rung.width;
+    session.encodeHeight = rung.height;
+    session.softwarePreset = pickSoftwarePreset(this.softwarePresetBenchmark, rung.width * rung.height * fps);
+    // Restart at the current live-edge segment so the lighter profile takes over
+    // from where the viewer is watching (hard-restart tier).
+    const head = session.encodeStartIndex;
+    const processed = Number.isFinite(session.progress?.processedSeconds)
+      ? session.progress.processedSeconds
+      : this.#segmentStartTime(session, head);
+    const currentSeg = Math.max(head, this.#segmentIndexForTime(session, processed));
+    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} ` +
+        `(rung ${nextIndex + 1}/${session.budgetLadder.length}, downshift ${session.budgetDownshifts}/${BUDGET_MAX_DOWNSHIFTS}), ` +
+        `restart at segment #${currentSeg} "${session.fileName}"`
+    );
+    this.#startEncodeRun(session, currentSeg);
   }
 
   /**
@@ -1027,8 +1273,10 @@ export class HlsSessionManager {
     // codec args (including keyframe alignment on segment boundaries).
     const videoCodecArgs = session.transcodeVideo
       ? this.videoEncoder.buildVideoArgs({
-          targetWidth: session.targetWidth,
-          targetHeight: session.targetHeight,
+          // Budget-selected encode box (may be below the client target on weak
+          // software hosts); falls back to the client target for hardware.
+          targetWidth: session.encodeWidth,
+          targetHeight: session.encodeHeight,
           segmentDurationSec: this.segmentDurationSec,
           // Source-inherited output rate (integer, capped); descriptors that
           // use time-based keyframes just apply it as the frame rate.
@@ -1115,6 +1363,11 @@ export class HlsSessionManager {
     session.progress.processedSeconds = startSeconds;
     session.progress.startPositionSeconds = startSeconds;
     session.progress.updatedAt = Date.now();
+    // Any (re)start resets the cumulative `speed` ffmpeg reports, so reset the
+    // realtime-budget slow window too — otherwise warm-up right after a user
+    // seek could be mis-counted as sustained sub-realtime and trigger a
+    // premature downscale.
+    session.budgetSlowSince = 0;
 
     logger.info(
       `transcode ${session.id} encode-run from segment #${safeIndex} ` +
@@ -1533,6 +1786,7 @@ export class HlsSessionManager {
    */
   async disposeAll() {
     clearInterval(this.cleanupTimer);
+    clearInterval(this.budgetTimer);
     const activeIds = Array.from(this.sessionsById.keys());
     for (const sessionId of activeIds) {
       await this.disposeSession(sessionId);

package/services/hwaccel.js

@@ -558,3 +558,87 @@ export function pickSoftwarePreset(benchmark, pixelsPerSecNeeded) {
   }
   return benchmark[benchmark.length - 1].preset;
 }
+
+// Resolution-ladder heights (output height rungs), high→low. The ladder is
+// derived per-stream from the ceiling (the client-requested, source-capped
+// output box): only rungs at or below the ceiling height are used, so the
+// budget never upscales past what the client asked for. Standard heights keep
+// the downscaled output at familiar resolutions.
+const RESOLUTION_LADDER_HEIGHTS = [2160, 1440, 1080, 720, 540, 480, 360, 240];
+
+/**
+ * Build the resolution ladder for a ceiling box. Returns candidate output
+ * dimensions from the ceiling downward, preserving the ceiling's aspect ratio,
+ * each even-sized. The ceiling itself is always the top rung; ladder heights
+ * at or above it are skipped (never upscale). Deduped by height.
+ *
+ * @param {number} ceilingWidth
+ * @param {number} ceilingHeight
+ * @returns {Array<{ width: number, height: number }>} high→low
+ */
+export function buildResolutionLadder(ceilingWidth, ceilingHeight) {
+  const cw = Number.isInteger(ceilingWidth) && ceilingWidth > 0 ? ceilingWidth : 0;
+  const ch = Number.isInteger(ceilingHeight) && ceilingHeight > 0 ? ceilingHeight : 0;
+  if (!cw || !ch) {
+    return [];
+  }
+  const even = (v) => {
+    const r = Math.round(v);
+    return Math.max(2, r - (r % 2));
+  };
+  /** @type {Array<{ width: number, height: number }>} */
+  const rungs = [{ width: cw, height: ch }];
+  for (const h of RESOLUTION_LADDER_HEIGHTS) {
+    if (h >= ch) {
+      continue; // at/above the ceiling — the ceiling rung already covers it
+    }
+    rungs.push({ width: even(cw * (h / ch)), height: h });
+  }
+  const seen = new Set();
+  return rungs.filter((rung) => {
+    if (seen.has(rung.height)) {
+      return false;
+    }
+    seen.add(rung.height);
+    return true;
+  });
+}
+
+/**
+ * Choose the software encode settings (resolution + preset) that fit the
+ * realtime budget on this host. From the resolution ladder (ceiling downward),
+ * pick the HIGHEST rung whose encode throughput — predicted from the startup
+ * benchmark's fastest preset — clears realtime × PRESET_SPEED_MARGIN. Then, at
+ * that resolution, pick the highest-quality preset that still clears the
+ * margin. When even the lowest rung cannot clear it, use the lowest rung with
+ * the fastest preset (best effort — a smaller picture beats sub-realtime
+ * playback at full size). Returns null when no benchmark or ceiling is
+ * available (the caller keeps the ceiling resolution and the default preset).
+ *
+ * @param {Array<{ preset: string, pixelsPerSec: number }>} benchmark - slowest→fastest
+ * @param {{ width: number, height: number }} ceiling
+ * @param {number} outputFps
+ * @returns {{ width: number, height: number, preset: string, ladder: Array<{ width: number, height: number }>, rungIndex: number } | null}
+ */
+export function chooseSoftwareEncodeSettings(benchmark, ceiling, outputFps) {
+  if (!Array.isArray(benchmark) || benchmark.length === 0) {
+    return null;
+  }
+  const fps = Number.isFinite(outputFps) && outputFps > 0 ? outputFps : TRANSCODE_FPS;
+  const ladder = buildResolutionLadder(ceiling?.width, ceiling?.height);
+  if (ladder.length === 0) {
+    return null;
+  }
+  const fastest = benchmark[benchmark.length - 1].pixelsPerSec; // ultrafast throughput
+  let chosenIndex = ladder.length - 1; // default: lowest rung (best effort)
+  for (let i = 0; i < ladder.length; i += 1) {
+    const needed = ladder[i].width * ladder[i].height * fps;
+    if (fastest >= needed * PRESET_SPEED_MARGIN) {
+      chosenIndex = i;
+      break;
+    }
+  }
+  const chosen = ladder[chosenIndex];
+  const preset = pickSoftwarePreset(benchmark, chosen.width * chosen.height * fps);
+  return { width: chosen.width, height: chosen.height, preset, ladder, rungIndex: chosenIndex };
+}

package/services/playback-planner.js

@@ -68,6 +68,18 @@ function parseStreams(ffmpegOutput) {
 function parseStreamCodecs(ffmpegOutput) {
   const audioMatch = ffmpegOutput.match(/Audio:\s*([A-Za-z0-9_]+)/i);
   const videoMatch = ffmpegOutput.match(/Video:\s*([A-Za-z0-9_]+)/i);
+  // Coded resolution from the video Stream line ("Video: h264 …, 1280x720, …").
+  // The first WxH is the coded size (any trailing "[SAR …]" is ignored).
+  const videoLineMatch = ffmpegOutput.match(/Video:[^\n]*/i);
+  let videoWidth = 0;
+  let videoHeight = 0;
+  if (videoLineMatch) {
+    const dim = videoLineMatch[0].match(/\b(\d{2,5})x(\d{2,5})\b/);
+    if (dim) {
+      videoWidth = Number(dim[1]);
+      videoHeight = Number(dim[2]);
+    }
+  }
   const containerMatch = ffmpegOutput.match(/Input #0,\s*([^,]+(?:,[^,]+)*?),\s*from/i);
   const durationMatch = ffmpegOutput.match(/Duration:\s*(\d+):(\d+):(\d+(?:\.\d+)?)/i);
   let durationSeconds = 0;
@@ -106,6 +118,8 @@ function parseStreamCodecs(ffmpegOutput) {
     videoCodec: videoMatch ? String(videoMatch[1]).toLowerCase() : "",
     container: containerMatch ? String(containerMatch[1]).trim().toLowerCase() : "",
     durationSeconds,
+    videoWidth,
+    videoHeight,
     audioTracks,
     subtitleTracks
   };
@@ -208,6 +222,8 @@ function buildDirectUrl(localBaseUrl, sourceKey, fileIndex) {
  * @property {string} videoCodec
  * @property {string} container         - Demuxer/container name(s) reported by ffmpeg.
  * @property {number} durationSeconds   - Total media duration in seconds (0 if unknown).
+ * @property {number} videoWidth        - Source coded width (0 if unknown).
+ * @property {number} videoHeight       - Source coded height (0 if unknown).
  */
 
 /**
@@ -289,6 +305,8 @@ export function createPlaybackPlanner({
           videoCodec: "",
           container: "",
           durationSeconds: 0,
+          videoWidth: 0,
+          videoHeight: 0,
           audioTracks: [],
           subtitleTracks: []
         };
@@ -316,7 +334,7 @@ export function createPlaybackPlanner({
         await torrentPool.prefetchFileEdges(torrent, fileIndex);
         probe = await probeStreamCodecs({ ffmpegBin, inputUrl: directUrl, userAgent });
       }
-      const { audioCodec, videoCodec, container, durationSeconds, audioTracks, subtitleTracks } = probe;
+      const { audioCodec, videoCodec, container, durationSeconds, videoWidth, videoHeight, audioTracks, subtitleTracks } = probe;
       const codecsDetected = audioCodec.length > 0 || videoCodec.length > 0;
 
       // `mode` is advisory only (audio-codec based). The browser makes the
@@ -331,6 +349,10 @@ export function createPlaybackPlanner({
         videoCodec,
         container,
         durationSeconds,
+        // Source coded resolution — drives the browser's manual quality menu
+        // (list of forced resolutions <= source). 0 when unknown.
+        videoWidth,
+        videoHeight,
         // Full track inventory for the browser's audio/subtitle menus.
         audioTracks: audioTracks ?? [],
         subtitleTracks: subtitleTracks ?? []