@torrent-tv/proxy 2.9.31 → 2.9.32

package/CHANGELOG.md

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

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

@@ -94,3 +94,26 @@ steps, and a resolution floor, and SHALL reset its slow window on every encode
 - **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

@@ -39,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.31",
+  "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/services/hls-session-manager.js

@@ -709,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({
@@ -721,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.");
@@ -739,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),
@@ -747,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);
@@ -835,14 +839,21 @@ export class HlsSessionManager {
     // 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.
-    const encodeBudget = this.#chooseEncodeBudget({
-      transcodeVideo,
-      targetWidth: normalizedTargetWidth,
-      targetHeight: normalizedTargetHeight,
-      sourceWidth,
-      sourceHeight,
-      outputFps
-    });
+    //
+    // 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).
@@ -932,9 +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 and whether the realtime budget downscaled
-        // it below the client target (the orientation-independent ceiling).
+        // 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}`
     );

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 ?? []