@torrent-tv/proxy 2.9.32 → 2.9.34

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2.9.34
+
+- **New**: Cold-start reduction (OpenSpec change `cold-start`). Creating a transcode session no longer runs a second full ffmpeg input scan: the playback planner caches the media info (duration/resolution/fps/start-time/HDR) parsed from the probe it already ran, and `createSession` reuses it (falling back to its own probe only when the cache cannot serve — e.g. after a restart, or a missing critical field). The banner parsers now live in a shared `ffmpeg-banner.js` so both sides parse identically. Once a plan probe succeeds the proxy also warms the START of the file body (~16 MB, fire-and-forget) so the first segment's encode reads downloaded data instead of waiting on pieces. Session startup is now measurable in the log: `cold-start <id>: media-info=<ms> (cached|probed) keyframes=<ms|skipped> create-total=<ms>` and, once per session, `cold-start <id>: first-segment ready +<ms>`.
+
+## 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/cold-start/design.md

@@ -0,0 +1,98 @@
+# Design: Cold-start reduction (proxy side)
+
+Written to be executed as specified. Read before coding:
+
+- `services/playback-planner.js`: `probeStreamCodecs` (how the ffmpeg banner
+  is parsed today), `getPlan` (prefetch → probe → pending loop → plan cache
+  and its key/invalidation).
+- `services/hls-session-manager.js`: `probeInputMediaInfo` (~line 383 — what
+  it parses: durationSeconds, width, height, fps, startTime, isHdr),
+  `createSession` (~line 806: the probe call at ~817, keyframe probe at
+  ~854), the segment-ready path (where segment 00000 first becomes
+  servable — grep the long-poll the `routes/transcode/session-file/get.js`
+  route uses).
+- `services/torrent-pool.js`: `prefetchFileEdges` (~line 608) — signature
+  `(torrent, fileIndex, { headBytes, tailBytes, timeoutMs })`.
+- `server.js`: how `playbackPlanner` and `hlsSessionManager` are constructed
+  and injected.
+
+## 1. Media-info reuse (kill ffmpeg scan #2)
+
+Both probes run ffmpeg over the same input URL and parse the same stderr
+banner; they just extract different fields. Unify:
+
+1. Extract the banner-parsing helpers that `probeInputMediaInfo` uses
+   (duration/width/height/fps/startTime/HDR detection) so the planner can
+   apply them to ITS probe's stderr. Where they live is the executor's
+   choice (export from hls-session-manager or move to a small shared
+   module) — do NOT duplicate the parsing logic.
+2. In the planner, on a probe whose codecs were detected (the same condition
+   that allows caching the plan), build a `mediaInfo` object
+   `{ durationSeconds, width, height, fps, startTime, isHdr }` and cache it
+   ALONGSIDE the plan — same key, same lifetime, same invalidation. A
+   pending (empty) probe caches nothing, exactly like the plan.
+3. Planner exposes `getCachedMediaInfo({ sourceKey, fileIndex })` →
+   `MediaInfo | null`.
+4. `server.js` passes it into HlsSessionManager (new constructor option
+   `getCachedMediaInfo`).
+5. `createSession`:
+
+       const cached = this.getCachedMediaInfo?.({ sourceKey, fileIndex }) ?? null;
+       const usable = cached
+         && Number.isFinite(cached.durationSeconds) && cached.durationSeconds > 0
+         && Number.isFinite(cached.width) && cached.width > 0
+         && Number.isFinite(cached.height) && cached.height > 0;
+       const mediaInfo = usable ? cached : await probeInputMediaInfo(this.ffmpegBin, inputUrl.toString());
+
+   Duration/width/height gate the cache because downstream logic depends on
+   them (synthetic VOD playlist, resolution ladder); fps/startTime/isHdr
+   have safe defaults and do not gate. The probe stays as the fallback —
+   behaviour is unchanged whenever the cache cannot serve.
+
+Keyframe probe (`probeVideoKeyframeTimes`) is NOT touched: it runs only on
+the video-copy path and probes different data (packet flags, not the
+banner).
+
+## 2. Body-start prefetch
+
+In `getPlan`, at the point where the probe succeeded and the plan is about
+to be cached/returned, fire and FORGET:
+
+    void torrentPool.prefetchFileEdges(torrent, fileIndex, {
+      headBytes: BODY_PREFETCH_BYTES, // 16 MB
+      tailBytes: 0,
+      timeoutMs: 60_000
+    }).catch(() => {});
+
+    const BODY_PREFETCH_BYTES = 16 * 1024 * 1024;
+
+No new torrent-pool method — `prefetchFileEdges` with `tailBytes: 0` is
+exactly a head prefetch. Not awaited: the client's session-create follows
+within a couple of seconds and ffmpeg reads sequentially behind the
+prefetch. 16 MB ≈ 25 s of typical 5 Mbit media — covers the first segments
+without denting the disk cap. Do NOT start it on pending polls (the header
+prefetch must keep absolute priority while the probe is starving).
+
+## 3. Stage timings
+
+- `createSession` measures and logs (one line, existing logger, prefix
+  matches the session log style):
+
+      cold-start <sessionId8>: media-info=<ms> (cached|probed) keyframes=<ms|skipped> create-total=<ms>
+
+- When the FIRST segment file of a fresh session becomes servable (the
+  long-poll in the session-file path returns it), log once per session:
+
+      cold-start <sessionId8>: first-segment ready +<ms since createSession entry>
+
+  Store the create-entry timestamp on the session object; guard with a
+  boolean so the line logs once.
+
+## Rules — do NOT
+
+- Do NOT change probe semantics, the pending/poll contract, or the plan
+  cache key.
+- Do NOT prioritise body bytes before the probe has succeeded.
+- Do NOT make session create fail on a cache problem — any doubt → fall
+  back to the probe.
+- No behavioural change for the video-copy path beyond the timing lines.

package/openspec/changes/cold-start/proposal.md

@@ -0,0 +1,62 @@
+# Proposal: Cold-start reduction (proxy side)
+
+## Why
+
+Field recordings (mobile tester, 2026-07-08) show ~90 seconds from picking an
+episode to a picture. The proxy owns two chunks of that:
+
+1. **A redundant ffmpeg input scan.** The playback planner probes the input
+   (`probeStreamCodecs`) and CACHES the plan — then `createSession` in
+   hls-session-manager immediately probes the SAME input again
+   (`probeInputMediaInfo`) for duration/resolution/fps/startTime/HDR. Each
+   probe is a full ffmpeg startup + banner scan over the torrent-backed HTTP
+   stream — seconds on the HA host, on the critical path, twice.
+2. **First-segment piece latency.** The planner prefetches only the file
+   EDGES (256 KB head + 2 MB tail — what the codec probe needs). The first
+   segment's encode then needs the first ~10–20 MB of the file BODY, whose
+   pieces start downloading only when ffmpeg asks for them — while the swarm
+   sat mostly idle during the plan poll.
+
+There is also no per-stage timing in the logs, so field regressions in
+session startup are invisible.
+
+## What Changes
+
+- **Reuse the planner's probe in session create.** The planner parses and
+  caches the full media info (duration, width/height, fps, startTime, isHdr)
+  from the probe it already runs; hls-session-manager consults that cache
+  and skips its own `probeInputMediaInfo` on a hit (probe stays as the
+  fallback). One full ffmpeg scan disappears from the critical path.
+- **Prefetch the file-body start once the plan is ready.** After a successful
+  probe, fire-and-forget prefetch of the first 16 MB of the file, so the
+  session's ffmpeg reads hit already-downloaded data instead of paying piece
+  latency at encode time.
+- **Stage timings in the log.** Session create logs probe ms (and
+  cache-hit/probed), keyframe-probe ms, and the time from create to the
+  first servable segment — so cold-start is measurable per stage in the
+  field, next to the client-side summary line (server `cold-start` change).
+
+Client-side counterparts (phase instrumentation, earlier prebuffer start)
+live in the server repo's `cold-start` change. The two changes are
+independent — no wire-format coupling, either releases alone.
+
+NOT in this change (candidates for later, kept out deliberately):
+next-episode speculative prefetch (bandwidth cost needs field data first);
+encoder-side first-segment speed-ups (faster warm-up preset would need a
+mid-stream switch — parked with transcode-quality 2.2b).
+
+## Capabilities
+
+### New Capabilities
+
+- `cold-start`: proxy-side session startup latency behaviour.
+
+## Impact
+
+- `services/playback-planner.js` — parse + cache full media info; expose
+  `getCachedMediaInfo`; body-start prefetch after a successful probe.
+- `services/hls-session-manager.js` — consult the cache in `createSession`;
+  stage-timing log lines.
+- `server.js` — wire `getCachedMediaInfo` into the HlsSessionManager deps.
+- Release: proxy `npm run patch` + ha-addon version bump (standard order:
+  proxy first, then addon).

package/openspec/changes/cold-start/specs/cold-start/spec.md

@@ -0,0 +1,47 @@
+# cold-start — delta spec (proxy)
+
+## ADDED Requirements
+
+### Requirement: Session create reuses the planner's probe
+
+Creating an HLS transcode session SHALL NOT re-probe an input whose media
+info the playback planner already probed and cached for the same source and
+file. The cached info is used only when its critical fields (duration,
+width, height) are present and valid; otherwise the session SHALL probe as
+before. Cache lifetime and invalidation follow the plan cache exactly.
+
+#### Scenario: Warm plan, immediate session
+- **WHEN** the browser requests a transcode session right after receiving a
+  playback plan for the same file
+- **THEN** the session starts without a second ffmpeg input scan and its
+  playlist/ladder decisions are identical to what the probe would have
+  produced
+
+#### Scenario: Cache cannot serve
+- **WHEN** no cached media info exists (e.g. proxy restarted between plan
+  and session) or a critical field is missing
+- **THEN** the session probes the input itself, exactly as before this
+  change
+
+### Requirement: The file-body start is warm before the encoder needs it
+
+Once a playback plan probe succeeds, the proxy SHALL prefetch the beginning
+of the file body (bounded, ~16 MB) in the background, without delaying the
+plan response and without competing with a still-running header probe.
+
+#### Scenario: First segment does not wait for pieces
+- **WHEN** the viewer confirms playback within the normal flow (seconds
+  after the plan)
+- **THEN** the encoder's initial reads are served from already-downloaded
+  data and the first segment's production is not blocked on piece download
+
+### Requirement: Session startup is measurable per stage
+
+Session creation SHALL log the media-info acquisition time (and whether it
+was cached or probed), the keyframe-probe time when it runs, and — once per
+session — the time from session-create entry to the first servable segment.
+
+#### Scenario: Field regression triage
+- **WHEN** a tester reports a slow start
+- **THEN** the proxy log shows, for that session, where the time went:
+  media info, keyframes, or first-segment production

package/openspec/changes/cold-start/tasks.md

@@ -0,0 +1,48 @@
+# Tasks: Cold-start reduction (proxy side)
+
+Execute in order; design.md is normative. Read the code regions listed at
+the top of design.md first.
+
+## 1. Media-info reuse
+
+- [ ] 1.1 Make the banner-parse helpers of `probeInputMediaInfo` reusable by
+      the planner (export or shared module — no duplication). `node --check`
+      both files.
+- [ ] 1.2 playback-planner: build + cache `mediaInfo` alongside the plan on
+      a codecs-detected probe; expose `getCachedMediaInfo({ sourceKey,
+      fileIndex })`. Pending probes cache nothing.
+- [ ] 1.3 server.js: pass `getCachedMediaInfo` into HlsSessionManager;
+      hls-session-manager: consult it in `createSession` with the
+      critical-fields gate (duration/width/height), probe as fallback.
+- [ ] 1.4 Verify equivalence: for one file, run plan → session with the
+      cache and (by temporarily disabling the wiring) without it — the
+      session log line (duration, segments, ladder/rung) must be identical.
+
+## 2. Body-start prefetch
+
+- [ ] 2.1 playback-planner: fire-and-forget 16 MB head prefetch
+      (`prefetchFileEdges` with `tailBytes: 0`) at the probe-success point;
+      never on pending polls; never awaited.
+- [ ] 2.2 Verify: on a fresh well-seeded magnet, proxy log/order shows the
+      prefetch starting right after the plan while the session that follows
+      produces its first segment without a piece-wait stall (compare
+      first-segment ms with task 3 timings before/after).
+
+## 3. Stage timings
+
+- [ ] 3.1 `createSession`: one `cold-start …: media-info=<ms> (cached|probed)
+      keyframes=<ms|skipped> create-total=<ms>` line.
+- [ ] 3.2 First-segment-ready line (`+<ms>` since create entry), once per
+      session (timestamp on the session object + boolean guard).
+
+## 4. Verification and release
+
+- [ ] 4.1 Regression: normal HLS transcode start, video-copy start (keyframe
+      probe still runs), seek-restart, quality switch — behaviour unchanged;
+      timings visible in the log.
+- [ ] 4.2 Before/after numbers on the dev HA proxy for one cold magnet:
+      media-info ms (probed → cached) and first-segment ms. Record them in
+      this file.
+- [ ] 4.3 CHANGELOG entry (current version + 1 patch); `npm run patch`; bump
+      ha-addon `config.yaml` + its CHANGELOG; push; update the addon in HA
+      (proxy FIRST, then addon — release order per root CLAUDE.md).

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.34",
   "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) => {
@@ -131,7 +138,11 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin,
       } catch {
         return null;
       }
-    }
+    },
+    // Reuse the media info the planner already probed for this file (same
+    // ffmpeg scan) so createSession skips its own probe. Late-bound: invoked
+    // only at session-create time, after playbackPlanner is initialised.
+    getCachedMediaInfo: (params) => playbackPlanner.getCachedMediaInfo(params)
   });
   const playbackPlanner = createPlaybackPlanner({
     ffmpegBin,

package/services/ffmpeg-banner.js

@@ -0,0 +1,125 @@
+/**
+ * @file ffmpeg banner parsers.
+ *
+ * Pure helpers that extract media info from the ffmpeg `-i` stderr banner
+ * (printed before any decoding): duration, start time, video resolution,
+ * frame rate and HDR transfer. Shared by the playback planner (which runs the
+ * codec probe) and the HLS session manager (which needs the same fields when
+ * building a session), so a session can reuse the planner's probe instead of
+ * running a second ffmpeg scan of the same input.
+ */
+
+/**
+ * Extract the total duration in seconds from ffmpeg stderr output.
+ * Returns `null` if the duration line is absent or unparseable.
+ *
+ * @param {string} stderrText
+ * @returns {number | null}
+ */
+export function parseFfmpegDurationSeconds(stderrText) {
+  if (typeof stderrText !== "string" || stderrText.length === 0) {
+    return null;
+  }
+  const match = stderrText.match(/Duration:\s*(\d+):(\d+):(\d+(?:\.\d+)?)/i);
+  if (!match) {
+    return null;
+  }
+  const hours = Number(match[1]);
+  const minutes = Number(match[2]);
+  const seconds = Number(match[3]);
+  if (![hours, minutes, seconds].every((item) => Number.isFinite(item))) {
+    return null;
+  }
+  return hours * 3600 + minutes * 60 + seconds;
+}
+
+/**
+ * Parse the container start time (seconds) from ffmpeg's "Duration: …, start:
+ * X, …" line. Many MKVs report a small non-zero start (e.g. 0.1 s); preserving
+ * it via `-copyts` would put a hole at the beginning, so we normalize it away.
+ * Returns 0 when absent.
+ *
+ * @param {string} stderrText
+ * @returns {number}
+ */
+export function parseFfmpegStartTimeSeconds(stderrText) {
+  if (typeof stderrText !== "string" || stderrText.length === 0) {
+    return 0;
+  }
+  const match = stderrText.match(/Duration:[^\n]*?start:\s*(-?\d+(?:\.\d+)?)/i);
+  if (!match) {
+    return 0;
+  }
+  const value = Number(match[1]);
+  return Number.isFinite(value) ? value : 0;
+}
+
+/**
+ * Parse the source video resolution from ffmpeg's stderr (the "Stream … Video:
+ * … WxH" line). Returns `{ width: null, height: null }` when absent.
+ *
+ * @param {string} stderrText
+ * @returns {{ width: number | null, height: number | null }}
+ */
+export function parseFfmpegVideoDimensions(stderrText) {
+  if (typeof stderrText !== "string" || stderrText.length === 0) {
+    return { width: null, height: null };
+  }
+  const match = stderrText.match(/Video:[^\n]*?\b(\d{2,5})x(\d{2,5})\b/i);
+  if (!match) {
+    return { width: null, height: null };
+  }
+  const width = Number(match[1]);
+  const height = Number(match[2]);
+  return {
+    width: Number.isFinite(width) && width > 0 ? width : null,
+    height: Number.isFinite(height) && height > 0 ? height : null
+  };
+}
+
+/**
+ * Parse the source frame rate from the ffmpeg "Video:" line
+ * (e.g. "… 23.98 fps," / "… 25 fps,"). Returns null when absent.
+ *
+ * @param {string} stderrText
+ * @returns {number | null}
+ */
+export function parseFfmpegVideoFps(stderrText) {
+  if (typeof stderrText !== "string" || stderrText.length === 0) {
+    return null;
+  }
+  const videoLine = stderrText.match(/Video:[^\n]*/i);
+  if (!videoLine) {
+    return null;
+  }
+  const match = videoLine[0].match(/([\d.]+)\s*fps/i);
+  if (!match) {
+    return null;
+  }
+  const value = Number(match[1]);
+  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}
+ */
+export 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]);
+}

package/services/hls-session-manager.js

@@ -22,6 +22,13 @@ import {
   TRANSCODE_FPS,
   chooseOutputFps
 } from "./hwaccel.js";
+import {
+  parseFfmpegDurationSeconds,
+  parseFfmpegStartTimeSeconds,
+  parseFfmpegVideoDimensions,
+  parseFfmpegVideoFps,
+  parseFfmpegHdr
+} from "./ffmpeg-banner.js";
 
 const PLAYLIST_FILE_NAME = "index.m3u8";
 const SEGMENT_FILE_NAME_PATTERN = /^segment-\d{5}\.ts$/;
@@ -206,51 +213,6 @@ function parseFfmpegTimestamp(value) {
   return hours * 3600 + minutes * 60 + seconds;
 }
 
-/**
- * Extract the total duration in seconds from ffmpeg stderr output.
- * Returns `null` if the duration line is absent or unparseable.
- *
- * @param {string} stderrText
- * @returns {number | null}
- */
-function parseFfmpegDurationSeconds(stderrText) {
-  if (typeof stderrText !== "string" || stderrText.length === 0) {
-    return null;
-  }
-  const match = stderrText.match(/Duration:\s*(\d+):(\d+):(\d+(?:\.\d+)?)/i);
-  if (!match) {
-    return null;
-  }
-  const hours = Number(match[1]);
-  const minutes = Number(match[2]);
-  const seconds = Number(match[3]);
-  if (![hours, minutes, seconds].every((item) => Number.isFinite(item))) {
-    return null;
-  }
-  return hours * 3600 + minutes * 60 + seconds;
-}
-
-/**
- * Parse the container start time (seconds) from ffmpeg's "Duration: …, start:
- * X, …" line. Many MKVs report a small non-zero start (e.g. 0.1 s); preserving
- * it via `-copyts` would put a hole at the beginning, so we normalize it away.
- * Returns 0 when absent.
- *
- * @param {string} stderrText
- * @returns {number}
- */
-function parseFfmpegStartTimeSeconds(stderrText) {
-  if (typeof stderrText !== "string" || stderrText.length === 0) {
-    return 0;
-  }
-  const match = stderrText.match(/Duration:[^\n]*?start:\s*(-?\d+(?:\.\d+)?)/i);
-  if (!match) {
-    return 0;
-  }
-  const value = Number(match[1]);
-  return Number.isFinite(value) ? value : 0;
-}
-
 /**
  * Format a seconds value as `HH:MM:SS`, or `"n/a"` if not finite.
  *
@@ -302,52 +264,6 @@ function computeProgressMetrics(processedSeconds, totalSeconds, startPositionSec
   };
 }
 
-/**
- * Parse the source video resolution from ffmpeg's stderr (the "Stream … Video:
- * … WxH" line). Returns `{ width: null, height: null }` when absent.
- *
- * @param {string} stderrText
- * @returns {{ width: number | null, height: number | null }}
- */
-function parseFfmpegVideoDimensions(stderrText) {
-  if (typeof stderrText !== "string" || stderrText.length === 0) {
-    return { width: null, height: null };
-  }
-  const match = stderrText.match(/Video:[^\n]*?\b(\d{2,5})x(\d{2,5})\b/i);
-  if (!match) {
-    return { width: null, height: null };
-  }
-  const width = Number(match[1]);
-  const height = Number(match[2]);
-  return {
-    width: Number.isFinite(width) && width > 0 ? width : null,
-    height: Number.isFinite(height) && height > 0 ? height : null
-  };
-}
-
-/**
- * Parse the source frame rate from the ffmpeg "Video:" line
- * (e.g. "… 23.98 fps," / "… 25 fps,"). Returns null when absent.
- *
- * @param {string} stderrText
- * @returns {number | null}
- */
-function parseFfmpegVideoFps(stderrText) {
-  if (typeof stderrText !== "string" || stderrText.length === 0) {
-    return null;
-  }
-  const videoLine = stderrText.match(/Video:[^\n]*/i);
-  if (!videoLine) {
-    return null;
-  }
-  const match = videoLine[0].match(/([\d.]+)\s*fps/i);
-  if (!match) {
-    return null;
-  }
-  const value = Number(match[1]);
-  return Number.isFinite(value) && value > 0 ? value : null;
-}
-
 /**
  * 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 +272,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 +293,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,10 +573,15 @@ export class HlsSessionManager {
     startupWaitMs = DEFAULT_STARTUP_WAIT_MS,
     videoEncoder = null,
     softwarePresetBenchmark = null,
-    getSourceStats = null
+    getSourceStats = null,
+    tonemapSupported = false,
+    getCachedMediaInfo = null
   }) {
     this.enabled = Boolean(enabled);
     this.ffmpegBin = ffmpegBin;
+    // Optional accessor for media info the playback planner already probed for
+    // (sourceKey, fileIndex), so session create can skip its own ffmpeg scan.
+    this.getCachedMediaInfo = typeof getCachedMediaInfo === "function" ? getCachedMediaInfo : null;
     // 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>.
@@ -672,6 +594,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;
@@ -775,21 +700,48 @@ export class HlsSessionManager {
     }
 
     const sessionId = randomUUID();
+    const createEntryMs = Date.now();
     const sessionDir = createSessionDirPath(sessionId);
     await mkdir(sessionDir, { recursive: true });
     const inputUrl = new URL("/stream", `${this.localBaseUrl}/`);
     inputUrl.searchParams.set("sourceKey", sourceKey);
     inputUrl.searchParams.set("fileIndex", String(fileIndex));
 
-    // Probe the full media duration up-front so we can serve a complete VOD
-    // playlist (terminated with #EXT-X-ENDLIST) immediately.  This gives the
-    // player the correct total duration and a fully seekable timeline before a
-    // single segment has been transcoded.
-    const mediaInfo = await probeInputMediaInfo(this.ffmpegBin, inputUrl.toString());
+    // Media info (duration/resolution/fps/startTime/HDR) up front, so we can
+    // serve a complete VOD playlist (#EXT-X-ENDLIST) with the correct total
+    // duration and a fully seekable timeline before a single segment exists.
+    // Reuse the planner's probe when it is available and complete — the plan
+    // request just ran the same ffmpeg scan over the same input. Fall back to
+    // a fresh probe otherwise (proxy restarted between plan and session, or a
+    // critical field is missing).
+    const mediaInfoStartMs = Date.now();
+    const cachedMediaInfo = this.getCachedMediaInfo?.({ sourceKey, fileIndex }) ?? null;
+    const cachedUsable =
+      cachedMediaInfo &&
+      Number.isFinite(cachedMediaInfo.durationSeconds) &&
+      cachedMediaInfo.durationSeconds > 0 &&
+      Number.isFinite(cachedMediaInfo.width) &&
+      cachedMediaInfo.width > 0 &&
+      Number.isFinite(cachedMediaInfo.height) &&
+      cachedMediaInfo.height > 0;
+    const mediaInfo = cachedUsable
+      ? cachedMediaInfo
+      : await probeInputMediaInfo(this.ffmpegBin, inputUrl.toString());
+    const mediaInfoMs = Date.now() - mediaInfoStartMs;
+    const mediaInfoSource = cachedUsable ? "cached" : "probed";
     const durationSeconds = mediaInfo.durationSeconds;
     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.
@@ -809,11 +761,14 @@ export class HlsSessionManager {
     // uniform grid (current behaviour). Re-encoded video uses a uniform grid
     // (its fixed GOP makes the cuts land there).
     let keyframeTimes = null;
+    let keyframeMs = -1; // -1 = not run (skipped)
     if (hasDuration && !transcodeVideo) {
       // Short timeout: mp4 keyframes come from the moov index (fast); containers
       // that force a full packet scan time out and fall back to a uniform grid,
       // so this never adds more than ~6 s to session start.
+      const keyframeStartMs = Date.now();
       keyframeTimes = await probeVideoKeyframeTimes(this.ffmpegBin, inputUrl.toString(), 6_000);
+      keyframeMs = Date.now() - keyframeStartMs;
       if (!keyframeTimes) {
         logger.warn(
           `transcode ${sessionId}: keyframe probe unavailable; using uniform grid ` +
@@ -821,6 +776,10 @@ export class HlsSessionManager {
         );
       }
     }
+    logger.info(
+      `cold-start ${sessionId.slice(0, 8)}: media-info=${mediaInfoMs}ms (${mediaInfoSource}) ` +
+        `keyframes=${keyframeMs < 0 ? "skipped" : `${keyframeMs}ms`} create-total=${Date.now() - createEntryMs}ms`
+    );
     const segmentBoundaries = hasDuration
       ? computeSegmentBoundaries({
           transcodeVideo,
@@ -870,6 +829,10 @@ export class HlsSessionManager {
       lastAccessedAt: Date.now(),
       ffmpeg: null,
       lastError: "",
+      // Cold-start timing: entry timestamp + a once-guard so the first servable
+      // segment logs its latency exactly once.
+      createEntryMs,
+      firstSegmentLogged: false,
       consumers: new Set(consumerId ? [consumerId] : []),
       // Transcode parameters retained so the encode run can be restarted at an
       // arbitrary segment when the player seeks (server-side seeking).
@@ -888,6 +851,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 +912,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 +1250,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
@@ -1628,6 +1598,14 @@ export class HlsSessionManager {
     try {
       await access(filePath);
       const isPlaylist = fileName === PLAYLIST_FILE_NAME;
+      // Cold-start: log the first servable SEGMENT of this session exactly once
+      // — the time from session-create entry to a playable first segment.
+      if (!isPlaylist && !session.firstSegmentLogged) {
+        session.firstSegmentLogged = true;
+        logger.info(
+          `cold-start ${sessionId.slice(0, 8)}: first-segment ready +${Date.now() - session.createEntryMs}ms`
+        );
+      }
       return {
         kind: "file",
         stream: isPlaylist

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

package/services/playback-planner.js

@@ -7,10 +7,23 @@
  */
 
 import { spawn } from "node:child_process";
+import {
+  parseFfmpegDurationSeconds,
+  parseFfmpegStartTimeSeconds,
+  parseFfmpegVideoDimensions,
+  parseFfmpegVideoFps,
+  parseFfmpegHdr
+} from "./ffmpeg-banner.js";
 
 /** Audio codecs that browsers can decode natively without transcoding. */
 const DIRECT_AUDIO_CODECS = new Set(["aac", "mp3", "opus", "vorbis", "flac"]);
 
+// Once the plan probe succeeds, warm the START of the file body so the
+// transcode session's ffmpeg reads hit downloaded data instead of paying
+// piece latency at encode time (the edge prefetch only covers head+tail for
+// the codec probe). ~16 MB ≈ the first segments of typical media.
+const BODY_PREFETCH_BYTES = 16 * 1024 * 1024;
+
 /** Subtitle codecs that can be converted to WebVTT (text-based). */
 const TEXT_SUBTITLE_CODECS = new Set(["subrip", "srt", "ass", "ssa", "webvtt", "vtt", "mov_text", "text"]);
 
@@ -134,7 +147,9 @@ function parseStreamCodecs(ffmpegOutput) {
  * @param {string} options.inputUrl
  * @param {string} [options.userAgent=""]
  * @param {number} [options.timeoutMs=8000]
- * @returns {Promise<{ audioCodec: string, videoCodec: string }>}
+ * @returns {Promise<{ audioCodec: string, videoCodec: string, container: string, durationSeconds: number, videoWidth: number, videoHeight: number, audioTracks: object[], subtitleTracks: object[], stderr: string }>}
+ *   Parsed banner fields plus the raw `stderr`, so the caller can derive the
+ *   full media info (fps/startTime/HDR) without a second ffmpeg scan.
  */
 function probeStreamCodecs({ ffmpegBin, inputUrl, userAgent = "", timeoutMs = 8_000 }) {
   return new Promise((resolve) => {
@@ -167,7 +182,7 @@ function probeStreamCodecs({ ffmpegBin, inputUrl, userAgent = "", timeoutMs = 8_
       if (!ffmpeg.killed) {
         ffmpeg.kill("SIGTERM");
       }
-      finish(parseStreamCodecs(stderr));
+      finish({ ...parseStreamCodecs(stderr), stderr });
     }, timeoutMs);
 
     ffmpeg.stderr.on("data", (chunk) => {
@@ -176,12 +191,12 @@ function probeStreamCodecs({ ffmpegBin, inputUrl, userAgent = "", timeoutMs = 8_
 
     ffmpeg.on("error", () => {
       clearTimeout(timeoutId);
-      finish({ audioCodec: "", videoCodec: "" });
+      finish({ audioCodec: "", videoCodec: "", stderr: "" });
     });
 
     ffmpeg.on("exit", () => {
       clearTimeout(timeoutId);
-      finish(parseStreamCodecs(stderr));
+      finish({ ...parseStreamCodecs(stderr), stderr });
     });
   });
 }
@@ -251,8 +266,26 @@ export function createPlaybackPlanner({
 }) {
   /** @type {Map<string, PlaybackPlan>} */
   const cache = new Map();
+  /**
+   * Full media info parsed from the SAME probe that produced the plan, cached
+   * under the same key so a transcode session can reuse it instead of running
+   * a second ffmpeg scan. Only set when the plan is cached (codecs detected).
+   * @type {Map<string, { durationSeconds: number | null, width: number | null, height: number | null, fps: number | null, startTime: number, isHdr: boolean }>}
+   */
+  const mediaInfoCache = new Map();
 
   return {
+    /**
+     * Media info the planner already probed for this file, or `null`. Lets the
+     * HLS session manager skip its own duplicate `probeInputMediaInfo` scan.
+     *
+     * @param {{ sourceKey: string, fileIndex: number }} params
+     * @returns {{ durationSeconds: number | null, width: number | null, height: number | null, fps: number | null, startTime: number, isHdr: boolean } | null}
+     */
+    getCachedMediaInfo({ sourceKey, fileIndex }) {
+      return mediaInfoCache.get(`${sourceKey}:${fileIndex}`) ?? null;
+    },
+
     /**
      * Return the playback plan for the given source file.
      * Throws with `error.code === "SOURCE_NOT_FOUND"` or `"FILE_NOT_FOUND"`
@@ -364,6 +397,26 @@ export function createPlaybackPlanner({
       // prioritised by the prefetch above).
       if (codecsDetected) {
         cache.set(cacheKey, plan);
+        // Cache the full media info from THIS probe's banner (same helpers the
+        // session manager uses) so createSession can skip its own probe.
+        const dims = parseFfmpegVideoDimensions(probe.stderr);
+        mediaInfoCache.set(cacheKey, {
+          durationSeconds: parseFfmpegDurationSeconds(probe.stderr),
+          width: dims.width,
+          height: dims.height,
+          fps: parseFfmpegVideoFps(probe.stderr),
+          startTime: parseFfmpegStartTimeSeconds(probe.stderr),
+          isHdr: parseFfmpegHdr(probe.stderr)
+        });
+        // Warm the file-body start for the transcode session that follows.
+        // Fire-and-forget: never delays the plan response.
+        void torrentPool
+          .prefetchFileEdges(torrent, fileIndex, {
+            headBytes: BODY_PREFETCH_BYTES,
+            tailBytes: 0,
+            timeoutMs: 60_000
+          })
+          .catch(() => {});
         return plan;
       }
       return { ...plan, pending: true };