@torrent-tv/proxy 2.9.32 → 2.9.33

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2.9.33
+
+- **New**: HDR / 10-bit tone mapping (OpenSpec change `transcode-quality`, part 3). An HDR source (BT.2020 with a PQ `smpte2084` or HLG `arib-std-b67` transfer) re-encoded to 8-bit SDR without tone mapping looks washed-out and desaturated. The proxy now detects HDR from the probe and, when re-encoding video on the software path, inserts a `zscale`+`tonemap` (hable) chain to convert HDR→BT.709 SDR properly. It is **gated on filter availability**: at startup the proxy checks this ffmpeg build for the `zscale` (libzimg) and `tonemap` filters (`hwaccel: HDR tone mapping available/unavailable …`); when either is missing it falls back to the previous plain 8-bit convert (still plays, just washed-out). The tone map runs after the downscale (cheaper on ARM). Logged per session as `hdr=1 tonemap=on|off`. Hardware encoders keep their current path for now (tone mapping there is a follow-up). No client change — the browser plays the resulting SDR HLS.
+
 ## 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.

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

@@ -117,3 +117,23 @@ behaviour.
 - **WHEN** the viewer selects Auto
 - **THEN** the proxy applies the realtime budget (startup selection + runtime
   downswitch) as before
+
+### Requirement: HDR sources are tone-mapped when re-encoded to SDR
+
+The proxy SHALL apply an HDR→BT.709 SDR tone-map chain when re-encoding an HDR
+source (a BT.2020 PQ `smpte2084` or HLG `arib-std-b67` transfer) to 8-bit SDR on
+the software path, so the output is not washed-out — provided this ffmpeg build
+has the required filters. The proxy SHALL detect filter availability (`zscale`
+and `tonemap`) at startup and, when either is missing, SHALL fall back to a
+plain 8-bit convert without failing playback.
+
+#### Scenario: HDR source, filters available
+- **WHEN** an HDR source is re-encoded on the software path and the build has
+  `zscale` + `tonemap`
+- **THEN** the tone-map chain is inserted and the output is BT.709 SDR (not
+  washed-out)
+
+#### Scenario: HDR source, filters missing
+- **WHEN** an HDR source is re-encoded but the build lacks `zscale`/`tonemap`
+- **THEN** playback still proceeds with a plain 8-bit convert (no tone map) and
+  the limitation is logged

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

@@ -34,10 +34,16 @@
       at the switch point.
 - [ ] 2.3 `-maxrate`/`-bufsize`
 
-## 3. HDR tone mapping (planned)
-
-- [ ] 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
+## 3. HDR tone mapping
+
+- [x] 3.1 Detect HDR from the probe (PQ `smpte2084` / HLG `arib-std-b67`
+      transfer); insert a `zscale`+`tonemap` (hable) BT.2020→BT.709 SDR chain
+      when re-encoding video on the software path (after the downscale).
+- [x] 3.2 Guard on tonemap-filter availability: startup `detectTonemapSupport`
+      checks `ffmpeg -filters` for `zscale` + `tonemap`; when missing, HDR
+      falls back to the plain 8-bit convert (washed-out but plays). Logged.
+      NOTE (follow-up 3.3): hardware-encoder tone mapping (tonemap_vaapi / npp /
+      opencl) — software path only for now.
 
 ## 4. Manual quality
 

package/package.json

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

package/server.js

@@ -30,7 +30,7 @@ import { createSourceRegistry } from "./store/source-registry.js";
 import { TorrentPool } from "./services/torrent-pool.js";
 import { HlsSessionManager } from "./services/hls-session-manager.js";
 import { createPlaybackPlanner } from "./services/playback-planner.js";
-import { detectVideoEncoder, benchmarkSoftwarePresets } from "./services/hwaccel.js";
+import { detectVideoEncoder, benchmarkSoftwarePresets, detectTonemapSupport } from "./services/hwaccel.js";
 import { logger } from "./utils/logger.js";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -111,6 +111,12 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin,
   const softwarePresetBenchmark = videoEncoder?.kind === "software"
     ? await benchmarkSoftwarePresets({ ffmpegBin, logger })
     : null;
+  // Whether this ffmpeg build can tone-map HDR→SDR (zscale + tonemap filters).
+  // Detected once; the session manager applies the tonemap chain only for HDR
+  // sources on the software path when available.
+  const tonemapSupported = transcodeAudio
+    ? await detectTonemapSupport({ ffmpegBin, logger })
+    : false;
   const hlsSessionManager = new HlsSessionManager({
     enabled: transcodeAudio,
     ffmpegBin,
@@ -118,6 +124,7 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin,
     localPort: selectedPort,
     videoEncoder,
     softwarePresetBenchmark,
+    tonemapSupported,
     // 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) => {

package/services/hls-session-manager.js

@@ -348,6 +348,30 @@ function parseFfmpegVideoFps(stderrText) {
   return Number.isFinite(value) && value > 0 ? value : null;
 }
 
+/**
+ * Detect an HDR / wide-gamut source from the ffmpeg "Video:" line's colour
+ * metadata. HDR is identified by the transfer function — `smpte2084` (PQ /
+ * HDR10) or `arib-std-b67` (HLG). Re-encoding such a source to 8-bit SDR
+ * without tone mapping produces a washed-out, desaturated picture, so this
+ * gates the tonemap filter chain.
+ *
+ * @param {string} stderrText
+ * @returns {boolean}
+ */
+function parseFfmpegHdr(stderrText) {
+  if (typeof stderrText !== "string" || stderrText.length === 0) {
+    return false;
+  }
+  const videoLine = stderrText.match(/Video:[^\n]*/i);
+  if (!videoLine) {
+    return false;
+  }
+  // ffmpeg prints the colour info in parentheses, e.g.
+  // "yuv420p10le(tv, bt2020nc/bt2020/smpte2084)". The transfer (last token) is
+  // the reliable HDR signal.
+  return /\b(smpte2084|arib-std-b67|arib_std_b67)\b/i.test(videoLine[0]);
+}
+
 /**
  * Run a short ffmpeg probe to extract the total duration AND video resolution
  * of a stream from the container header. Both are printed almost immediately
@@ -356,7 +380,7 @@ function parseFfmpegVideoFps(stderrText) {
  *
  * @param {string} ffmpegBin - Path to the ffmpeg executable.
  * @param {string | URL} inputUrl - URL of the stream to probe.
- * @returns {Promise<{ durationSeconds: number | null, width: number | null, height: number | null }>}
+ * @returns {Promise<{ durationSeconds: number | null, width: number | null, height: number | null, fps: number | null, startTime: number, isHdr: boolean }>}
  */
 async function probeInputMediaInfo(ffmpegBin, inputUrl) {
   return new Promise((resolve) => {
@@ -377,7 +401,8 @@ async function probeInputMediaInfo(ffmpegBin, inputUrl) {
         width: dims.width,
         height: dims.height,
         fps: parseFfmpegVideoFps(stderr),
-        startTime: parseFfmpegStartTimeSeconds(stderr)
+        startTime: parseFfmpegStartTimeSeconds(stderr),
+        isHdr: parseFfmpegHdr(stderr)
       });
     };
     const timeoutId = setTimeout(() => {
@@ -656,7 +681,8 @@ export class HlsSessionManager {
     startupWaitMs = DEFAULT_STARTUP_WAIT_MS,
     videoEncoder = null,
     softwarePresetBenchmark = null,
-    getSourceStats = null
+    getSourceStats = null,
+    tonemapSupported = false
   }) {
     this.enabled = Boolean(enabled);
     this.ffmpegBin = ffmpegBin;
@@ -672,6 +698,9 @@ export class HlsSessionManager {
     // used to pick the best preset per stream. Null when unavailable (hardware
     // encoder, or benchmark skipped/failed).
     this.softwarePresetBenchmark = Array.isArray(softwarePresetBenchmark) ? softwarePresetBenchmark : null;
+    // Whether this ffmpeg build can tone-map HDR→SDR (zscale + tonemap filters).
+    // Gates the tonemap chain for HDR sources on the software path.
+    this.tonemapSupported = Boolean(tonemapSupported);
     this.segmentDurationSec = segmentDurationSec;
     this.sessionTtlMs = sessionTtlMs;
     this.startupWaitMs = startupWaitMs;
@@ -790,6 +819,15 @@ export class HlsSessionManager {
     const sourceWidth = mediaInfo.width;
     const sourceHeight = mediaInfo.height;
     const sourceStartTime = Number.isFinite(mediaInfo.startTime) ? mediaInfo.startTime : 0;
+    // Tone-map an HDR source to SDR only when re-encoding video on the software
+    // path and this ffmpeg has the filters. Hardware encoders keep their own
+    // (untone-mapped) path for now; when unavailable, HDR falls back to a plain
+    // 8-bit convert (washed-out but playable).
+    const applyTonemap =
+      transcodeVideo === true &&
+      mediaInfo.isHdr === true &&
+      this.tonemapSupported &&
+      this.videoEncoder?.kind === "software";
     // Output frame rate inherited from the source (integer, capped) so 25/30
     // fps content is not resampled to 24. Fixed-GOP encoders keep the fps↔GOP
     // relationship exact; time-based-keyframe encoders just use it as the rate.
@@ -888,6 +926,8 @@ export class HlsSessionManager {
       // software hosts, else the client target). 0 = keep source.
       encodeWidth,
       encodeHeight,
+      // Whether to insert the HDR→SDR tone-map chain (software path only).
+      applyTonemap,
       // 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
@@ -947,6 +987,9 @@ export class HlsSessionManager {
         // 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 ` : ""}` +
+        // HDR source and whether the tone-map chain was applied (vs washed-out
+        // fallback when the filters are missing or on a hardware encoder).
+        `${transcodeVideo && mediaInfo.isHdr ? `hdr=1 tonemap=${applyTonemap ? "on" : "off"} ` : ""}` +
         `${sourceStartTime ? `start=${sourceStartTime.toFixed(3)} ` : ""}` +
         `duration=${hasDuration ? formatSeconds(durationSeconds) : "unknown"} segments=${segmentCount}`
     );
@@ -1282,7 +1325,9 @@ export class HlsSessionManager {
           // use time-based keyframes just apply it as the frame rate.
           fps: session.outputFps,
           // Software-only; hardware descriptors ignore it.
-          preset: session.softwarePreset ?? undefined
+          preset: session.softwarePreset ?? undefined,
+          // HDR→SDR tone map (software path only; gated on filter availability).
+          tonemap: session.applyTonemap === true
         })
       : ["-c:v", "copy"];
     const audioCodecArgs = session.transcodeAudio

package/services/hwaccel.js

@@ -27,6 +27,14 @@ import path from "node:path";
 
 const SOFTWARE_PRESET = "ultrafast";
 const SOFTWARE_CRF = "24";
+// HDR→SDR tone-map chain (software). Converts a BT.2020 PQ/HLG source to BT.709
+// 8-bit SDR so the re-encode is not washed-out/desaturated. Requires the
+// `zscale` (libzimg) and `tonemap` filters — gated by detectTonemapSupport;
+// when unavailable the encode falls back to a plain 8-bit convert (no tonemap).
+// npl=100 targets ~100-nit SDR; hable is a well-behaved tone-mapping operator.
+const TONEMAP_FILTER_CHAIN =
+  "zscale=t=linear:npl=100,format=gbrpf32le,zscale=p=bt709," +
+  "tonemap=tonemap=hable:desat=0,zscale=t=bt709:m=bt709:r=tv,format=yuv420p";
 // Default output frame rate when the source rate is unknown, and the rate used
 // by the synthetic startup test-encode / preset benchmark. The real encode
 // inherits the source rate (rounded to an integer, capped) — see
@@ -108,20 +116,24 @@ export function softwareDescriptor() {
     kind: "software",
     device: null,
     inputArgs: [],
-    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec, preset, fps }) {
+    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec, preset, fps, tonemap }) {
       const { w, h } = safeDimensions(targetWidth, targetHeight);
       const chosenPreset = typeof preset === "string" && preset.length > 0 ? preset : SOFTWARE_PRESET;
       // Output frame rate: inherited from the source (rounded/capped) by the
       // session manager, TRANSCODE_FPS by default. MUST be an integer and MUST
       // equal the value used in the GOP below, or keyframes drift off the grid.
       const outFps = Number.isInteger(fps) && fps > 0 ? fps : TRANSCODE_FPS;
+      // HDR→SDR tone-map, inserted AFTER the downscale so it runs on the smaller
+      // frame (cheaper on ARM); only when the source is HDR and the filters are
+      // present (session manager gates on both).
+      const tonemapPart = tonemap === true ? `,${TONEMAP_FILTER_CHAIN}` : "";
       return [
         // Never upscale: cap the target box to the source size (min with
         // iw/ih), so a small source (e.g. 720x400) is encoded at its own
         // resolution instead of being scaled up to the viewport — far fewer
         // pixels, much faster on ARM. force_original_aspect_ratio keeps aspect.
         "-vf",
-        `scale='min(${w},iw)':'min(${h},ih)':force_original_aspect_ratio=decrease:force_divisible_by=2,fps=${outFps}`,
+        `scale='min(${w},iw)':'min(${h},ih)':force_original_aspect_ratio=decrease:force_divisible_by=2${tonemapPart},fps=${outFps}`,
         "-c:v", "libx264",
         // Preset is chosen per stream by the session manager from the startup
         // benchmark (highest quality that still encodes the source resolution
@@ -496,6 +508,33 @@ export async function detectVideoEncoder({ ffmpegBin, logger, segmentDurationSec
   return software;
 }
 
+/**
+ * Detect whether this ffmpeg build has the filters needed for the HDR→SDR
+ * tone-map chain (`zscale`, from libzimg, and `tonemap`). Both are required;
+ * when either is missing, HDR sources are re-encoded without tone mapping
+ * (washed-out but playable). Always resolves.
+ *
+ * @param {{ ffmpegBin: string, logger?: { info: (m: string) => void, warn: (m: string) => void } }} options
+ * @returns {Promise<boolean>}
+ */
+export async function detectTonemapSupport({ ffmpegBin, logger }) {
+  const log = logger ?? { info: () => {}, warn: () => {} };
+  const { code, stdout } = await runFfmpeg(ffmpegBin, ["-hide_banner", "-filters"], 10000);
+  if (code !== 0) {
+    log.warn("hwaccel: could not list ffmpeg filters; HDR tone mapping disabled");
+    return false;
+  }
+  // `-filters` prints one filter per line: "... zscale  ...", "... tonemap ...".
+  const hasZscale = /\bzscale\b/.test(stdout);
+  const hasTonemap = /\btonemap\b/.test(stdout);
+  const supported = hasZscale && hasTonemap;
+  log.info(
+    `hwaccel: HDR tone mapping ${supported ? "available" : "unavailable"} ` +
+      `(zscale=${hasZscale} tonemap=${hasTonemap})`
+  );
+  return supported;
+}
+
 /**
  * Benchmark software libx264 presets on this host. Encodes a short synthetic
  * clip at a fixed reference resolution with each preset and measures encoder