@torrent-tv/proxy 2.9.60 → 2.9.61

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2.9.61
+
+- **Chore**: Measurement build for the iOS player question. A request for a not-yet-produced segment is now held up to 60 s (was 2 s) and each hold logs `[hold] <file> <outcome> after <ms>` — where the outcome distinguishes the segment arriving, our own limit expiring, and **the client aborting the connection**. The 2 s refusal was introduced (2.9.57) to dodge a reported iOS AVPlayer ~3.5 s response-header deadline, but that error code never appears in our own logs, and all five reference projects hold instead of refusing (Jellyfin and hls-vod-too unbounded, hls-media-server 10 s — see research/hls-seek-prior-art-2026-08-02.md). This build measures the player's real patience on our own hardware so the final value comes from observation rather than from a number read elsewhere. Not a permanent setting.
+
 ## 2.9.60
 
 - **Fix**: Seeking restarted the encoder at the position it was **already encoding**, destroying the very work being waited for — visible in the field log 2026-08-02 as `restart at #865` twice within ten seconds, each killing a run that was encoding #865. While the target segment is being produced the player keeps re-requesting it, and every such request looks "far" from where the encoder USED to be, so each one re-triggered a restart at the position we had only just moved to; playback data kept appearing and vanishing, and a seek only completed when a segment happened to reach the player before the next restart. A settled seek whose target equals the current runs start index is now ignored outright. This is distinct from the 2.9.58 guard, which only decides whether to let the current run finish its first segment — not whether a new run is needed at all; that guard behaved correctly here (it logged `run produced 4.5s (first segment done)`) and still let the pointless restart through.

package/package.json

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

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

@@ -0,0 +1,50 @@
+/**
+ * @file POST /api/transcode-sessions/:sessionId/seek — the viewer's seek target.
+ *
+ * The browser reports WHERE THE VIEWER ACTUALLY SEEKED, explicitly, the moment
+ * the scrub ends. This is the only authoritative source of that intent: the
+ * position lives in the browser (`video.currentTime`) and nowhere else.
+ *
+ * Why this route exists at all: our synthetic VOD playlist advertises every
+ * segment of the file, but segments only exist once ffmpeg has produced them.
+ * A player is entitled by the HLS contract to fetch any advertised segment and
+ * get it immediately, so when one 503s it legitimately probes elsewhere —
+ * field log 2026-08-02 shows a correct target burst (#973..#985, the real seek)
+ * followed by scattered probing across the whole file (#125, #173, #251, #326,
+ * #478...). Inferring the target from that request stream made the encoder
+ * restart at #519 — a probe, not the seek — and the viewer waited ten seconds
+ * for a segment nobody wanted. Segment requests are data fetches, not commands;
+ * the seek target now arrives here instead of being guessed from them.
+ *
+ * Mirrors how Jellyfin/Plex handle server-side seeking (an explicit start
+ * position from the client), rather than heuristics over request patterns.
+ */
+
+/**
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{ hlsSessionManager: import("../../../../services/hls-session-manager.js").HlsSessionManager }} deps
+ * @returns {Promise<void>}
+ */
+export async function handleApiTranscodeSessionSeekPost(req, reply, { hlsSessionManager }) {
+  const sessionId = req.params?.sessionId;
+  const body = req.body && typeof req.body === "object" ? req.body : {};
+  const positionSeconds = Number(body.positionSeconds);
+
+  if (!Number.isFinite(positionSeconds) || positionSeconds < 0) {
+    reply.code(400);
+    return reply.send({ error: "positionSeconds must be a non-negative number." });
+  }
+
+  const applied = hlsSessionManager.requestSeek(sessionId, positionSeconds);
+  if (!applied) {
+    // Unknown or disposed session — nothing to steer. Not an error worth
+    // surfacing to the viewer: the seek will be handled by whatever session
+    // replaces it.
+    reply.code(404);
+    return reply.send({ error: "No such transcode session." });
+  }
+
+  reply.code(204);
+  return reply.send();
+}

package/routes/transcode/session-file/get.js

@@ -1,111 +1,145 @@
-/**
- * How long a request for a not-yet-produced file is held before answering with
- * a retryable 503. Must stay comfortably below iOS AVPlayer's ~3.5 s
- * response-header deadline (see the call site for the full rationale).
- */
-const SEGMENT_WAIT_MS = 2_000;
-
-/**
- * Serve HLS playlist and segment files from an active transcode session.
- *
- * Briefly waits for the requested file to appear, then answers with a
- * retryable 503 rather than holding the connection, so clients — in
- * particular iOS's native HLS player — never hit their own response
- * deadline while a segment is still being produced.
- *
- * GET /transcode/:sessionId/:fileName
- *
- * @param {import("fastify").FastifyRequest} req
- * @param {import("fastify").FastifyReply} reply
- * @param {{ hlsSessionManager: import("../../../services/hls-session-manager.js").HlsSessionManager }} deps
- * @returns {Promise<void>}
- */
-export async function handleTranscodeSessionFileGet(req, reply, { hlsSessionManager }) {
-  const sessionId = typeof req.params.sessionId === "string" ? req.params.sessionId : "";
-  const fileName = typeof req.params.fileName === "string" ? req.params.fileName : "";
-  // Hold the request only briefly, then answer "retry" instead of waiting for
-  // the segment. iOS's native HLS player (AVPlayer) enforces a hard ~3.5 s
-  // deadline on RESPONSE HEADERS and raises -12889 ("No response for media
-  // file") when it passes — it then cancels in-flight requests, probes
-  // neighbouring positions and can restart the stream from the beginning. That
-  // is exactly the post-seek "player thrashing" seen in the field, because a
-  // seek restarts ffmpeg and the first segment then takes far longer than 3.5 s
-  // to appear. Holding the connection for 30 s (as this did) guaranteed the
-  // timeout on every seek. A short hold keeps the fast path intact (a ready or
-  // nearly-ready segment is still served on the first request) while a slow one
-  // gets a prompt retryable answer, which resets the player's own deadline.
-  // hls.js is unaffected: it consumes the 503 through its retry policy, whose
-  // budget the client widens to match (see hls-player.js fragLoadPolicy).
-  const result = await waitForSessionFile(hlsSessionManager, sessionId, fileName, SEGMENT_WAIT_MS);
-
-  if (result.kind === "not-found") {
-    return reply.code(404).send({ error: "Transcode session file was not found." });
-  }
-  if (result.kind === "warming-up") {
-    // The segment is still being produced (e.g. just after a seek-restart).
-    // Return a retryable 503 — never 202, which hls.js cannot consume as a
-    // media segment — so the player retries the fetch shortly.
-    reply.header("Retry-After", "1");
-    // `Retry-After` tells the player to re-request THIS segment after a short
-    // pause. Without it a bare 503 reads as "nothing here", and the player goes
-    // looking elsewhere: because our synthetic VOD playlist lists every segment
-    // of the file, it believes they all exist and SCANS them (field log: one
-    // user seek produced probes at #617, #717, #732…). That scan is what used
-    // to steer the encoder off the real target. Whether iOS's native player
-    // honours the hint is not guaranteed — its behaviour is closed — but this
-    // is the standard, correct way to say "wait, don't look elsewhere", and
-    // hls.js already retries the same fragment regardless.
-    reply.header("Retry-After", "1");
-    return reply.code(503).send({ error: "Transcode segment is still being produced." });
-  }
-  if (result.kind === "failed") {
-    return reply.code(500).send({ error: result.message });
-  }
-
-  if (result.isPlaylist) {
-    reply.header("Cache-Control", "no-store");
-  } else {
-    reply.header("Cache-Control", "public, max-age=60");
-  }
-  reply.header("Content-Type", result.contentType);
-  return reply.send(result.stream);
-}
-
-/**
- * Poll `hlsSessionManager.getFileStream()` until the file is available,
- * the session fails, or the timeout elapses.
- *
- * @param {import("../../../services/hls-session-manager.js").HlsSessionManager} hlsSessionManager
- * @param {string} sessionId
- * @param {string} fileName
- * @param {number} timeoutMs
- * @returns {Promise<Awaited<ReturnType<import("../../../services/hls-session-manager.js").HlsSessionManager["getFileStream"]>>>}
- */
-async function waitForSessionFile(hlsSessionManager, sessionId, fileName, timeoutMs) {
-  const startedAt = Date.now();
-  // One sequence number for THIS request, reused by every poll below, so the
-  // session can tell a newly-arrived request apart from an old one polling
-  // again — see HlsSessionManager#ensureEncodingFor for the encoder ping-pong
-  // this prevents when one seek-bar scrub fires several segment requests.
-  const requestSeq = hlsSessionManager.nextRequestSeq(sessionId);
-  while (Date.now() - startedAt < timeoutMs) {
-    const result = await hlsSessionManager.getFileStream(sessionId, fileName, { requestSeq });
-    if (result.kind !== "warming-up") {
-      return result;
-    }
-    await delay(300);
-  }
-  return { kind: "warming-up" };
-}
-
-/**
- * Resolve after a given number of milliseconds.
- *
- * @param {number} ms
- * @returns {Promise<void>}
- */
-function delay(ms) {
-  return new Promise((resolve) => {
-    setTimeout(resolve, ms);
-  });
-}
+import { logger } from "../../../utils/logger.js";
+
+/**
+ * How long a request for a not-yet-produced file is held before answering with
+ * a retryable 503.
+ *
+ * MEASUREMENT MODE (2026-08-02): deliberately far above any plausible player
+ * deadline, so OUR limit never fires first. Whatever ends the wait is then the
+ * player's own behaviour — which is exactly what we need to observe. The
+ * `[hold]` log line at the call site records, per request, whether the segment
+ * arrived, whether we gave up, or whether the CLIENT aborted, and after how
+ * long.
+ *
+ * The previous value (2 s) was chosen to dodge a reported iOS AVPlayer ~3.5 s
+ * response-header deadline. That deadline never appears in our own logs (no
+ * -12889 across six hours of production logs), and every reference project
+ * holds rather than refusing: Jellyfin and hls-vod-too hold unbounded,
+ * hls-media-server holds 10 s. The early refusal is what made the player probe
+ * scattered positions, which then steered the encoder off target. Choose the
+ * final value from what this measurement shows, not from a number read
+ * elsewhere.
+ */
+const SEGMENT_WAIT_MS = 60_000;
+
+/**
+ * Serve HLS playlist and segment files from an active transcode session.
+ *
+ * Briefly waits for the requested file to appear, then answers with a
+ * retryable 503 rather than holding the connection, so clients — in
+ * particular iOS's native HLS player — never hit their own response
+ * deadline while a segment is still being produced.
+ *
+ * GET /transcode/:sessionId/:fileName
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{ hlsSessionManager: import("../../../services/hls-session-manager.js").HlsSessionManager }} deps
+ * @returns {Promise<void>}
+ */
+export async function handleTranscodeSessionFileGet(req, reply, { hlsSessionManager }) {
+  const sessionId = typeof req.params.sessionId === "string" ? req.params.sessionId : "";
+  const fileName = typeof req.params.fileName === "string" ? req.params.fileName : "";
+  // Hold the request only briefly, then answer "retry" instead of waiting for
+  // the segment. iOS's native HLS player (AVPlayer) enforces a hard ~3.5 s
+  // deadline on RESPONSE HEADERS and raises -12889 ("No response for media
+  // file") when it passes — it then cancels in-flight requests, probes
+  // neighbouring positions and can restart the stream from the beginning. That
+  // is exactly the post-seek "player thrashing" seen in the field, because a
+  // seek restarts ffmpeg and the first segment then takes far longer than 3.5 s
+  // to appear. Holding the connection for 30 s (as this did) guaranteed the
+  // timeout on every seek. A short hold keeps the fast path intact (a ready or
+  // nearly-ready segment is still served on the first request) while a slow one
+  // gets a prompt retryable answer, which resets the player's own deadline.
+  // hls.js is unaffected: it consumes the 503 through its retry policy, whose
+  // budget the client widens to match (see hls-player.js fragLoadPolicy).
+  // Instrumented wait. `clientAborted` flips when the player drops the
+  // connection while we are still holding it — the single most informative
+  // signal about its real patience, and observable only from this side.
+  const holdStartedAt = Date.now();
+  let clientAborted = false;
+  const onClientAbort = () => { clientAborted = true; };
+  req.raw.on("close", onClientAbort);
+
+  const result = await waitForSessionFile(hlsSessionManager, sessionId, fileName, SEGMENT_WAIT_MS);
+
+  req.raw.off("close", onClientAbort);
+  const heldMs = Date.now() - holdStartedAt;
+  if (result.isPlaylist !== true) {
+    const outcome = clientAborted
+      ? "client-aborted"
+      : result.kind === "ok" ? "served" : result.kind;
+    logger.info(`[hold] ${fileName} ${outcome} after ${heldMs}ms`);
+  }
+
+  if (result.kind === "not-found") {
+    return reply.code(404).send({ error: "Transcode session file was not found." });
+  }
+  if (result.kind === "warming-up") {
+    // The segment is still being produced (e.g. just after a seek-restart).
+    // Return a retryable 503 — never 202, which hls.js cannot consume as a
+    // media segment — so the player retries the fetch shortly.
+    reply.header("Retry-After", "1");
+    // `Retry-After` tells the player to re-request THIS segment after a short
+    // pause. Without it a bare 503 reads as "nothing here", and the player goes
+    // looking elsewhere: because our synthetic VOD playlist lists every segment
+    // of the file, it believes they all exist and SCANS them (field log: one
+    // user seek produced probes at #617, #717, #732…). That scan is what used
+    // to steer the encoder off the real target. Whether iOS's native player
+    // honours the hint is not guaranteed — its behaviour is closed — but this
+    // is the standard, correct way to say "wait, don't look elsewhere", and
+    // hls.js already retries the same fragment regardless.
+    reply.header("Retry-After", "1");
+    return reply.code(503).send({ error: "Transcode segment is still being produced." });
+  }
+  if (result.kind === "failed") {
+    return reply.code(500).send({ error: result.message });
+  }
+
+  if (result.isPlaylist) {
+    reply.header("Cache-Control", "no-store");
+  } else {
+    reply.header("Cache-Control", "public, max-age=60");
+  }
+  reply.header("Content-Type", result.contentType);
+  return reply.send(result.stream);
+}
+
+/**
+ * Poll `hlsSessionManager.getFileStream()` until the file is available,
+ * the session fails, or the timeout elapses.
+ *
+ * @param {import("../../../services/hls-session-manager.js").HlsSessionManager} hlsSessionManager
+ * @param {string} sessionId
+ * @param {string} fileName
+ * @param {number} timeoutMs
+ * @returns {Promise<Awaited<ReturnType<import("../../../services/hls-session-manager.js").HlsSessionManager["getFileStream"]>>>}
+ */
+async function waitForSessionFile(hlsSessionManager, sessionId, fileName, timeoutMs) {
+  const startedAt = Date.now();
+  // One sequence number for THIS request, reused by every poll below, so the
+  // session can tell a newly-arrived request apart from an old one polling
+  // again — see HlsSessionManager#ensureEncodingFor for the encoder ping-pong
+  // this prevents when one seek-bar scrub fires several segment requests.
+  const requestSeq = hlsSessionManager.nextRequestSeq(sessionId);
+  while (Date.now() - startedAt < timeoutMs) {
+    const result = await hlsSessionManager.getFileStream(sessionId, fileName, { requestSeq });
+    if (result.kind !== "warming-up") {
+      return result;
+    }
+    await delay(300);
+  }
+  return { kind: "warming-up" };
+}
+
+/**
+ * Resolve after a given number of milliseconds.
+ *
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function delay(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}

package/server.js

@@ -1,216 +1,220 @@
-/**
- * @file Proxy HTTP server bootstrap.
- *
- * Creates and configures the Fastify application, registers all routes and
- * plugins, then starts listening on the first available port at or above the
- * requested one.
- */
-
-import Fastify from "fastify";
-import fastifyCors from "@fastify/cors";
-import fastifyHelmet from "@fastify/helmet";
-import fastifyStatic from "@fastify/static";
-import getPort from "get-port";
-import path from "node:path";
-import { createRequire } from "node:module";
-import { fileURLToPath } from "node:url";
-import { handleHealthGet } from "./routes/health/get.js";
-import { handleHealthzGet } from "./routes/healthz/get.js";
-import { handleApiSourcesPost } from "./routes/api/sources/post.js";
-import { handleApiSourceStatsGet } from "./routes/api/sources/stats/get.js";
-import { handleApiSourceFilesGet } from "./routes/api/sources/files/get.js";
-import { handleApiPlaybackPlanPost } from "./routes/api/playback-plan/post.js";
-import { handleApiSubtitlesGet } from "./routes/api/subtitles/get.js";
-import { handleApiTranscodeSessionsPost } from "./routes/api/transcode-sessions/post.js";
-import { handleApiTranscodeSessionsProgressGet } from "./routes/api/transcode-sessions/progress/get.js";
-import { handleApiTranscodeSessionReleasePost } from "./routes/api/transcode-sessions/release/post.js";
-import { handleApiTranscodeSessionNetReportPost } from "./routes/api/transcode-sessions/net-report/post.js";
-import { handleStreamGet } from "./routes/stream/get.js";
-import { handleTranscodeSessionFileGet } from "./routes/transcode/session-file/get.js";
-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, detectTonemapSupport } from "./services/hwaccel.js";
-import { logger } from "./utils/logger.js";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-const require = createRequire(import.meta.url);
-const { version } = require("./package.json");
-const publicRoot = path.resolve(__dirname, "./public");
-
-/**
- * Build a list of candidate port numbers starting at `startPort`.
- *
- * @param {number} startPort
- * @param {number} [maxAttempts=51]
- * @returns {number[]}
- */
-function buildPortCandidates(startPort, maxAttempts = 51) {
-  const ports = [];
-  for (let index = 0; index < maxAttempts; index += 1) {
-    ports.push(startPort + index);
-  }
-  return ports;
-}
-
-/**
- * @typedef {Object} ProxyServerOptions
- * @property {string}  host           - Bind host (e.g. "127.0.0.1" or "0.0.0.0").
- * @property {number}  port           - Preferred listen port.
- * @property {boolean} transcodeAudio - Whether HLS audio transcoding is enabled.
- * @property {string}  ffmpegBin      - Path to the ffmpeg executable.
- * @property {number}  [maxDiskBytes] - Global disk cap for torrent data (undefined = pool default).
- * @property {string}  [segmentFormat] - HLS output container: "fmp4" (default) or "mpegts".
- */
-
-/**
- * Create, configure, and start the proxy HTTP server.
- *
- * @param {ProxyServerOptions} options
- * @returns {Promise<{ app: import("fastify").FastifyInstance, port: number }>}
- */
-export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin, maxDiskBytes, segmentFormat }) {
-  const app = Fastify({
-    // No practical body-size limit — the proxy server is localhost-only and
-    // receives torrent source payloads that may be arbitrarily large.
-    bodyLimit: 256 * 1024 * 1024 // 256 MB
-  });
-
-  await app.register(fastifyHelmet, {
-    // Proxy serves media to a different origin (registry UI), so CORP must allow cross-origin usage.
-    crossOriginResourcePolicy: {
-      policy: "cross-origin"
-    }
-  });
-  await app.register(fastifyCors, {
-    origin: true,
-    methods: ["GET", "POST", "OPTIONS"],
-    allowedHeaders: ["Content-Type", "Range"]
-  });
-
-  // Allow browser requests from an HTTPS page to this private-network proxy
-  // without triggering Chromium's Private Network Access permission prompt.
-  app.addHook("onRequest", async (_req, reply) => {
-    reply.header("Access-Control-Allow-Private-Network", "true");
-  });
-
-  const sourceRegistry = createSourceRegistry(200);
-  const torrentPool = new TorrentPool({ maxDiskBytes });
-  const selectedPort = await getPort({
-    port: buildPortCandidates(port)
-  });
-  // Auto-detect the best available H.264 encoder (hardware-accelerated or
-  // software) once at startup, with a real test-encode and graceful fallback.
-  // Only needed when transcoding can occur.
-  const videoEncoder = transcodeAudio
-    ? await detectVideoEncoder({ ffmpegBin, logger })
-    : null;
-  // For software libx264, benchmark preset throughput once at startup so the
-  // session manager can pick the highest-quality preset that still encodes each
-  // stream faster than realtime. Hardware encoders use their own fixed preset.
-  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,
-    localBindHost: host,
-    localPort: selectedPort,
-    videoEncoder,
-    softwarePresetBenchmark,
-    tonemapSupported,
-    segmentFormatId: segmentFormat,
-    // Live download stats accessor for the realtime budget: lets it tell a
-    // CPU-bound transcode from a download-starved input before downscaling.
-    getSourceStats: async (sourceKey, fileIndex) => {
-      const record = sourceRegistry.get(sourceKey);
-      if (!record) {
-        return null;
-      }
-      try {
-        const torrent = await torrentPool.getTorrent(record.sourceType, record.source);
-        return torrentPool.getFileStats(torrent, Number.isInteger(fileIndex) ? fileIndex : null);
-      } catch {
-        return null;
-      }
-    },
-    // 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,
-    transcodeAudioEnabled: transcodeAudio,
-    localBaseUrl: hlsSessionManager.localBaseUrl,
-    sourceRegistry,
-    torrentPool
-  });
-
-  app.get("/health", async (req, reply) => handleHealthGet(req, reply, { version }));
-  app.get("/healthz", async (req, reply) => handleHealthzGet(req, reply, { version }));
-  app.post("/api/sources", async (req, reply) =>
-    handleApiSourcesPost(req, reply, { sourceRegistry })
-  );
-  app.get("/api/sources/:sourceKey/stats", async (req, reply) =>
-    handleApiSourceStatsGet(req, reply, { sourceRegistry, torrentPool })
-  );
-  app.get("/api/sources/:sourceKey/files", async (req, reply) =>
-    handleApiSourceFilesGet(req, reply, { sourceRegistry, torrentPool })
-  );
-  app.post("/api/playback-plan", async (req, reply) =>
-    handleApiPlaybackPlanPost(req, reply, { playbackPlanner })
-  );
-  app.get("/api/subtitles", async (req, reply) =>
-    handleApiSubtitlesGet(req, reply, {
-      sourceRegistry,
-      torrentPool,
-      ffmpegBin,
-      localBaseUrl: hlsSessionManager.localBaseUrl
-    })
-  );
-  app.get("/stream", async (req, reply) =>
-    handleStreamGet(req, reply, { sourceRegistry, torrentPool })
-  );
-  app.post("/api/transcode-sessions", async (req, reply) =>
-    handleApiTranscodeSessionsPost(req, reply, { hlsSessionManager })
-  );
-  app.post("/api/transcode-sessions/:sessionId/release", async (req, reply) =>
-    handleApiTranscodeSessionReleasePost(req, reply, { hlsSessionManager })
-  );
-  app.get("/api/transcode-sessions/:sessionId/progress", async (req, reply) =>
-    handleApiTranscodeSessionsProgressGet(req, reply, { hlsSessionManager })
-  );
-  app.post("/api/transcode-sessions/:sessionId/net-report", async (req, reply) =>
-    handleApiTranscodeSessionNetReportPost(req, reply, { hlsSessionManager })
-  );
-  app.get("/transcode/:sessionId/:fileName", async (req, reply) =>
-    handleTranscodeSessionFileGet(req, reply, { hlsSessionManager })
-  );
-  await app.register(fastifyStatic, {
-    root: publicRoot,
-    prefix: "/",
-    serveDotFiles: true
-  });
-
-  app.addHook("onClose", async () => {
-    // Order matters: stop the ffmpeg readers (HLS sessions) before destroying
-    // the torrents whose files they read from, then remove the torrent data.
-    await hlsSessionManager.disposeAll();
-    await torrentPool.destroyAll();
-  });
-
-  await app.listen({ host, port: selectedPort });
-  return {
-    app,
-    port: selectedPort
-  };
-}
+/**
+ * @file Proxy HTTP server bootstrap.
+ *
+ * Creates and configures the Fastify application, registers all routes and
+ * plugins, then starts listening on the first available port at or above the
+ * requested one.
+ */
+
+import Fastify from "fastify";
+import fastifyCors from "@fastify/cors";
+import fastifyHelmet from "@fastify/helmet";
+import fastifyStatic from "@fastify/static";
+import getPort from "get-port";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import { handleHealthGet } from "./routes/health/get.js";
+import { handleHealthzGet } from "./routes/healthz/get.js";
+import { handleApiSourcesPost } from "./routes/api/sources/post.js";
+import { handleApiSourceStatsGet } from "./routes/api/sources/stats/get.js";
+import { handleApiSourceFilesGet } from "./routes/api/sources/files/get.js";
+import { handleApiPlaybackPlanPost } from "./routes/api/playback-plan/post.js";
+import { handleApiSubtitlesGet } from "./routes/api/subtitles/get.js";
+import { handleApiTranscodeSessionsPost } from "./routes/api/transcode-sessions/post.js";
+import { handleApiTranscodeSessionsProgressGet } from "./routes/api/transcode-sessions/progress/get.js";
+import { handleApiTranscodeSessionReleasePost } from "./routes/api/transcode-sessions/release/post.js";
+import { handleApiTranscodeSessionNetReportPost } from "./routes/api/transcode-sessions/net-report/post.js";
+import { handleApiTranscodeSessionSeekPost } from "./routes/api/transcode-sessions/seek/post.js";
+import { handleStreamGet } from "./routes/stream/get.js";
+import { handleTranscodeSessionFileGet } from "./routes/transcode/session-file/get.js";
+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, detectTonemapSupport } from "./services/hwaccel.js";
+import { logger } from "./utils/logger.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const require = createRequire(import.meta.url);
+const { version } = require("./package.json");
+const publicRoot = path.resolve(__dirname, "./public");
+
+/**
+ * Build a list of candidate port numbers starting at `startPort`.
+ *
+ * @param {number} startPort
+ * @param {number} [maxAttempts=51]
+ * @returns {number[]}
+ */
+function buildPortCandidates(startPort, maxAttempts = 51) {
+  const ports = [];
+  for (let index = 0; index < maxAttempts; index += 1) {
+    ports.push(startPort + index);
+  }
+  return ports;
+}
+
+/**
+ * @typedef {Object} ProxyServerOptions
+ * @property {string}  host           - Bind host (e.g. "127.0.0.1" or "0.0.0.0").
+ * @property {number}  port           - Preferred listen port.
+ * @property {boolean} transcodeAudio - Whether HLS audio transcoding is enabled.
+ * @property {string}  ffmpegBin      - Path to the ffmpeg executable.
+ * @property {number}  [maxDiskBytes] - Global disk cap for torrent data (undefined = pool default).
+ * @property {string}  [segmentFormat] - HLS output container: "fmp4" (default) or "mpegts".
+ */
+
+/**
+ * Create, configure, and start the proxy HTTP server.
+ *
+ * @param {ProxyServerOptions} options
+ * @returns {Promise<{ app: import("fastify").FastifyInstance, port: number }>}
+ */
+export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin, maxDiskBytes, segmentFormat }) {
+  const app = Fastify({
+    // No practical body-size limit — the proxy server is localhost-only and
+    // receives torrent source payloads that may be arbitrarily large.
+    bodyLimit: 256 * 1024 * 1024 // 256 MB
+  });
+
+  await app.register(fastifyHelmet, {
+    // Proxy serves media to a different origin (registry UI), so CORP must allow cross-origin usage.
+    crossOriginResourcePolicy: {
+      policy: "cross-origin"
+    }
+  });
+  await app.register(fastifyCors, {
+    origin: true,
+    methods: ["GET", "POST", "OPTIONS"],
+    allowedHeaders: ["Content-Type", "Range"]
+  });
+
+  // Allow browser requests from an HTTPS page to this private-network proxy
+  // without triggering Chromium's Private Network Access permission prompt.
+  app.addHook("onRequest", async (_req, reply) => {
+    reply.header("Access-Control-Allow-Private-Network", "true");
+  });
+
+  const sourceRegistry = createSourceRegistry(200);
+  const torrentPool = new TorrentPool({ maxDiskBytes });
+  const selectedPort = await getPort({
+    port: buildPortCandidates(port)
+  });
+  // Auto-detect the best available H.264 encoder (hardware-accelerated or
+  // software) once at startup, with a real test-encode and graceful fallback.
+  // Only needed when transcoding can occur.
+  const videoEncoder = transcodeAudio
+    ? await detectVideoEncoder({ ffmpegBin, logger })
+    : null;
+  // For software libx264, benchmark preset throughput once at startup so the
+  // session manager can pick the highest-quality preset that still encodes each
+  // stream faster than realtime. Hardware encoders use their own fixed preset.
+  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,
+    localBindHost: host,
+    localPort: selectedPort,
+    videoEncoder,
+    softwarePresetBenchmark,
+    tonemapSupported,
+    segmentFormatId: segmentFormat,
+    // Live download stats accessor for the realtime budget: lets it tell a
+    // CPU-bound transcode from a download-starved input before downscaling.
+    getSourceStats: async (sourceKey, fileIndex) => {
+      const record = sourceRegistry.get(sourceKey);
+      if (!record) {
+        return null;
+      }
+      try {
+        const torrent = await torrentPool.getTorrent(record.sourceType, record.source);
+        return torrentPool.getFileStats(torrent, Number.isInteger(fileIndex) ? fileIndex : null);
+      } catch {
+        return null;
+      }
+    },
+    // 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,
+    transcodeAudioEnabled: transcodeAudio,
+    localBaseUrl: hlsSessionManager.localBaseUrl,
+    sourceRegistry,
+    torrentPool
+  });
+
+  app.get("/health", async (req, reply) => handleHealthGet(req, reply, { version }));
+  app.get("/healthz", async (req, reply) => handleHealthzGet(req, reply, { version }));
+  app.post("/api/sources", async (req, reply) =>
+    handleApiSourcesPost(req, reply, { sourceRegistry })
+  );
+  app.get("/api/sources/:sourceKey/stats", async (req, reply) =>
+    handleApiSourceStatsGet(req, reply, { sourceRegistry, torrentPool })
+  );
+  app.get("/api/sources/:sourceKey/files", async (req, reply) =>
+    handleApiSourceFilesGet(req, reply, { sourceRegistry, torrentPool })
+  );
+  app.post("/api/playback-plan", async (req, reply) =>
+    handleApiPlaybackPlanPost(req, reply, { playbackPlanner })
+  );
+  app.get("/api/subtitles", async (req, reply) =>
+    handleApiSubtitlesGet(req, reply, {
+      sourceRegistry,
+      torrentPool,
+      ffmpegBin,
+      localBaseUrl: hlsSessionManager.localBaseUrl
+    })
+  );
+  app.get("/stream", async (req, reply) =>
+    handleStreamGet(req, reply, { sourceRegistry, torrentPool })
+  );
+  app.post("/api/transcode-sessions", async (req, reply) =>
+    handleApiTranscodeSessionsPost(req, reply, { hlsSessionManager })
+  );
+  app.post("/api/transcode-sessions/:sessionId/release", async (req, reply) =>
+    handleApiTranscodeSessionReleasePost(req, reply, { hlsSessionManager })
+  );
+  app.get("/api/transcode-sessions/:sessionId/progress", async (req, reply) =>
+    handleApiTranscodeSessionsProgressGet(req, reply, { hlsSessionManager })
+  );
+  app.post("/api/transcode-sessions/:sessionId/net-report", async (req, reply) =>
+    handleApiTranscodeSessionNetReportPost(req, reply, { hlsSessionManager })
+  );
+  app.post("/api/transcode-sessions/:sessionId/seek", async (req, reply) =>
+    handleApiTranscodeSessionSeekPost(req, reply, { hlsSessionManager })
+  );
+  app.get("/transcode/:sessionId/:fileName", async (req, reply) =>
+    handleTranscodeSessionFileGet(req, reply, { hlsSessionManager })
+  );
+  await app.register(fastifyStatic, {
+    root: publicRoot,
+    prefix: "/",
+    serveDotFiles: true
+  });
+
+  app.addHook("onClose", async () => {
+    // Order matters: stop the ffmpeg readers (HLS sessions) before destroying
+    // the torrents whose files they read from, then remove the torrent data.
+    await hlsSessionManager.disposeAll();
+    await torrentPool.destroyAll();
+  });
+
+  await app.listen({ host, port: selectedPort });
+  return {
+    app,
+    port: selectedPort
+  };
+}