@torrent-tv/proxy 2.9.33 → 2.9.34

package/CHANGELOG.md

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

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

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.9.33",
+  "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

@@ -138,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,76 +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;
-}
-
-/**
- * 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
@@ -682,10 +574,14 @@ export class HlsSessionManager {
     videoEncoder = null,
     softwarePresetBenchmark = null,
     getSourceStats = null,
-    tonemapSupported = false
+    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>.
@@ -804,17 +700,35 @@ 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;
@@ -847,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 ` +
@@ -859,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,
@@ -908,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).
@@ -1673,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/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 };