@torrent-tv/proxy 2.44.0 → 2.45.0

package/services/playback-planner.js

@@ -1,339 +1,375 @@
-/**
- * @file Playback planner service.
- *
- * Determines whether a torrent file can be served directly or requires
- * HLS audio transcoding by probing the stream codecs with ffmpeg.
- * Results are cached indefinitely (keyed by source + file index).
- */
-
-import { spawn } from "node:child_process";
-import { logger } from "../utils/logger.js";
-import {
-  parseFfmpegDurationSeconds,
-  parseFfmpegStartTimeSeconds,
-  parseFfmpegVideoDimensions,
-  parseFfmpegBitrateKbps,
-  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"]);
-
-/**
- * Parse every stream from the ffmpeg `-i` banner: type, codec, language tag,
- * default disposition and (when present) the stream's `title` metadata line.
- *
- * @param {string} ffmpegOutput
- * @returns {Array<{ streamIndex: number, type: string, codec: string, language: string, title: string, isDefault: boolean }>}
- */
-function parseStreams(ffmpegOutput) {
-  // Only the Input section: ffmpeg prints Stream lines for the null OUTPUT
-  // too (wrapped_avframe / pcm_s16le), which would duplicate every track.
-  const inputSection = ffmpegOutput.split(/^(?:Output #|Stream mapping:)/m)[0] ?? ffmpegOutput;
-  const lines = inputSection.split(/\r?\n/);
-  const streams = [];
-  let current = null;
-  for (const line of lines) {
-    const streamMatch = line.match(
-      /^\s*Stream #0:(\d+)(?:\[[^\]]*\])?(?:\(([A-Za-z0-9]{2,3})\))?: (Audio|Video|Subtitle): ([A-Za-z0-9_]+)/
-    );
-    if (streamMatch) {
-      current = {
-        streamIndex: Number(streamMatch[1]),
-        type: streamMatch[3].toLowerCase(),
-        codec: String(streamMatch[4]).toLowerCase(),
-        language: (streamMatch[2] ?? "").toLowerCase(),
-        title: "",
-        isDefault: /\(default\)/.test(line)
-      };
-      streams.push(current);
-      continue;
-    }
-    if (current) {
-      const titleMatch = line.match(/^\s+title\s*:\s*(.+)$/);
-      if (titleMatch && current.title.length === 0) {
-        current.title = titleMatch[1].trim();
-        continue;
-      }
-      // A new top-level section (non-indented line) ends the stream's block.
-      if (!/^\s/.test(line)) {
-        current = null;
-      }
-    }
-  }
-  return streams;
-}
-
-/**
- * Parse audio and video codec names from ffmpeg stderr output.
- *
- * @param {string} ffmpegOutput
- * @returns {{ audioCodec: string, videoCodec: string }}
- */
-function parseStreamCodecs(ffmpegOutput) {
-  const audioMatch = ffmpegOutput.match(/Audio:\s*([A-Za-z0-9_]+)/i);
-  const videoMatch = ffmpegOutput.match(/Video:\s*([A-Za-z0-9_]+)/i);
-  // Coded resolution from the video Stream line ("Video: h264 …, 1280x720, …").
-  // The first WxH is the coded size (any trailing "[SAR …]" is ignored).
-  const videoLineMatch = ffmpegOutput.match(/Video:[^\n]*/i);
-  let videoWidth = 0;
-  let videoHeight = 0;
-  if (videoLineMatch) {
-    const dim = videoLineMatch[0].match(/\b(\d{2,5})x(\d{2,5})\b/);
-    if (dim) {
-      videoWidth = Number(dim[1]);
-      videoHeight = Number(dim[2]);
-    }
-  }
-  const containerMatch = ffmpegOutput.match(/Input #0,\s*([^,]+(?:,[^,]+)*?),\s*from/i);
-  const durationMatch = ffmpegOutput.match(/Duration:\s*(\d+):(\d+):(\d+(?:\.\d+)?)/i);
-  let durationSeconds = 0;
-  if (durationMatch) {
-    const value =
-      Number(durationMatch[1]) * 3600 + Number(durationMatch[2]) * 60 + Number(durationMatch[3]);
-    durationSeconds = Number.isFinite(value) ? value : 0;
-  }
-  const streams = parseStreams(ffmpegOutput);
-  const audioTracks = streams
-    .filter((s) => s.type === "audio")
-    .map((s, i) => ({
-      // Type-relative index — what ffmpeg's `-map 0:a:N` selects.
-      index: i,
-      streamIndex: s.streamIndex,
-      codec: s.codec,
-      language: s.language,
-      title: s.title,
-      isDefault: s.isDefault
-    }));
-  const subtitleTracks = streams
-    .filter((s) => s.type === "subtitle")
-    .map((s, i) => ({
-      // Type-relative index — what ffmpeg's `-map 0:s:N` selects.
-      index: i,
-      streamIndex: s.streamIndex,
-      codec: s.codec,
-      language: s.language,
-      title: s.title,
-      isDefault: s.isDefault,
-      // Image-based subtitles (PGS/VobSub) cannot become WebVTT.
-      textBased: TEXT_SUBTITLE_CODECS.has(s.codec)
-    }));
-  return {
-    audioCodec: audioMatch ? String(audioMatch[1]).toLowerCase() : "",
-    videoCodec: videoMatch ? String(videoMatch[1]).toLowerCase() : "",
-    container: containerMatch ? String(containerMatch[1]).trim().toLowerCase() : "",
-    durationSeconds,
-    videoWidth,
-    videoHeight,
-    audioTracks,
-    subtitleTracks
-  };
-}
-
-/**
- * Run a brief ffmpeg probe to identify the audio and video codecs of a stream.
- * Times out after `timeoutMs` and returns empty strings on failure.
- *
- * @param {object} options
- * @param {string} options.ffmpegBin
- * @param {string} options.inputUrl
- * @param {string} [options.userAgent=""]
- * @param {number} [options.timeoutMs=8000]
- * @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) => {
-    const args = ["-hide_banner", "-loglevel", "info"];
-    if (typeof userAgent === "string" && userAgent.trim().length > 0) {
-      args.push("-user_agent", userAgent.trim());
-    }
-    // Decode a tiny slice of all streams (no per-stream -map, so video-only
-    // files probe correctly too).  The ffmpeg banner that precedes decoding
-    // gives us audio/video codecs, the container format and the duration in a
-    // single pass.
-    args.push("-i", inputUrl, "-t", "0.1", "-f", "null", "-");
-
-    const ffmpeg = spawn(ffmpegBin, args, {
-      stdio: ["ignore", "ignore", "pipe"],
-      windowsHide: true
-    });
-    let stderr = "";
-    let settled = false;
-
-    const finish = (codecs) => {
-      if (settled) {
-        return;
-      }
-      settled = true;
-      resolve(codecs);
-    };
-
-    const timeoutId = setTimeout(() => {
-      if (!ffmpeg.killed) {
-        ffmpeg.kill("SIGTERM");
-      }
-      finish({ ...parseStreamCodecs(stderr), stderr });
-    }, timeoutMs);
-
-    ffmpeg.stderr.on("data", (chunk) => {
-      stderr += String(chunk);
-    });
-
-    ffmpeg.on("error", () => {
-      clearTimeout(timeoutId);
-      finish({ audioCodec: "", videoCodec: "", stderr: "" });
-    });
-
-    ffmpeg.on("exit", () => {
-      clearTimeout(timeoutId);
-      finish({ ...parseStreamCodecs(stderr), stderr });
-    });
-  });
-}
-
-/**
- * Resolve after a given number of milliseconds.
- *
- * @param {number} ms
- * @returns {Promise<void>}
- */
-function delay(ms) {
-  return new Promise((resolve) => {
-    setTimeout(resolve, ms);
-  });
-}
-
-/**
- * Build the direct stream URL for a source file served by the local proxy.
- *
- * @param {string} localBaseUrl - e.g. "http://127.0.0.1:9090"
- * @param {string} sourceKey
- * @param {number} fileIndex
- * @returns {string}
- */
-function buildDirectUrl(localBaseUrl, sourceKey, fileIndex) {
-  const directUrl = new URL("/stream", `${localBaseUrl}/`);
-  directUrl.searchParams.set("sourceKey", sourceKey);
-  directUrl.searchParams.set("fileIndex", String(fileIndex));
-  return directUrl.toString();
-}
-
-/**
- * @typedef {Object} PlaybackPlan
- * @property {"direct" | "hls"} mode
- * @property {string} directUrl
- * @property {string} reason   - Human-readable explanation of the chosen mode.
- * @property {string} audioCodec
- * @property {string} videoCodec
- * @property {string} container         - Demuxer/container name(s) reported by ffmpeg.
- * @property {number} durationSeconds   - Total media duration in seconds (0 if unknown).
- * @property {number} videoWidth        - Source coded width (0 if unknown).
- * @property {number} videoHeight       - Source coded height (0 if unknown).
- */
-
-/**
- * @typedef {Object} PlaybackPlannerOptions
- * @property {string}  ffmpegBin
- * @property {boolean} transcodeAudioEnabled
- * @property {string}  localBaseUrl
- * @property {ReturnType<import("../store/source-registry.js").createSourceRegistry>} sourceRegistry
- * @property {import("./torrent-pool.js").TorrentPool} torrentPool
- */
-
-/**
- * Create a playback planner that decides the optimal streaming mode for
- * a torrent file. Plans are cached per (sourceKey, fileIndex) pair.
- *
- * @param {PlaybackPlannerOptions} options
- * @returns {{ getPlan: (params: { sourceKey: string, fileIndex: number, userAgent?: string }) => Promise<PlaybackPlan> }}
- */
-export function createPlaybackPlanner({
-  ffmpegBin,
-  transcodeAudioEnabled,
-  localBaseUrl,
-  sourceRegistry,
-  torrentPool,
-  // Optional. Reports what this host typically takes to produce a session's
-  // first segment. The browser needs it for the gap between "the file is
-  // downloaded" and "a segment exists": until now it assumed the pipeline
-  // merely keeps up with realtime, and showed 15 s where 3.8 s were left.
-  expectedFirstSegmentMs,
-  expectedSessionCreateMs,
-  // Optional. Called once the file's edges are downloaded, so the keyframe
-  // index — which reads the same tail of the file — is fetched alongside the
-  // codec probe instead of after it. Late-bound to the HLS session manager,
-  // which owns the cache both of them share.
-  warmKeyframeIndex,
-  // Optional. The heights this host could actually serve this source at, for
-  // both playback branches, so the quality menu is right from the moment the
-  // file is opened rather than from the moment an encoder exists.
-  predictOfferedHeights
-}) {
-  /** @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();
-
-  /**
-   * Attach what this host currently measures itself taking to create a session
-   * and to produce a first segment.
-   *
-   * Read at RESPONSE time, deliberately. Both are medians of sessions that have
-   * already finished on this host, so at the moment a plan is BUILT the very
-   * first file opened after a restart has none and gets `null` — and the plan
-   * is then cached, so that file kept answering `null` for the life of the
-   * process however many sessions ran afterwards. Measured 2026-08-05: a fresh
-   * 2.9.103 answered `null` for both, then produced the session in 6 ms and the
-   * first segment in 21 479 ms. The figures existed; the plan could not carry
-   * them, and the browser's estimate fell back to its own guess in exactly the
-   * cold-start case the feature was built for.
-   *
-   * @param {PlaybackPlan} plan
-   * @returns {PlaybackPlan}
-   */
-  function withHostTimings(plan) {
-    return {
-      ...plan,
-      expectedFirstSegmentMs: expectedFirstSegmentMs?.() ?? null,
-      expectedSessionCreateMs: expectedSessionCreateMs?.() ?? null,
-      // Answered here for the same reason as the two above: a plan is cached for
-      // the life of the process, and what this host will serve a file at is not.
-      // It starts as a prediction from the startup benchmarks and is replaced by
-      // what an encoder running on this very source turns out to cost — frozen
-      // into the cache, every later open of the file would hand the browser the
-      // first guess again and undo that. This is the 2.9.106 defect exactly.
-      offeredHeights: plan.mediaInfoForOffer
-        ? (predictOfferedHeights?.(plan.mediaInfoForOffer) ?? null)
-        : null,
-      mediaInfoForOffer: undefined
-    };
-  }
-
-  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}
-     */
+/**
+ * @file Playback planner service.
+ *
+ * Determines whether a torrent file can be served directly or requires
+ * HLS audio transcoding by probing the stream codecs with ffmpeg.
+ * Results are cached indefinitely (keyed by source + file index).
+ */
+
+import { spawn } from "node:child_process";
+import { logger } from "../utils/logger.js";
+import { mergeContainerSubtitleFlags } from "./subtitle-defaults.js";
+import {
+  parseFfmpegDurationSeconds,
+  parseFfmpegStartTimeSeconds,
+  parseFfmpegVideoDimensions,
+  parseFfmpegBitrateKbps,
+  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"]);
+
+/**
+ * Parse every stream from the ffmpeg `-i` banner: type, codec, language tag,
+ * default disposition and (when present) the stream's `title` metadata line.
+ *
+ * @param {string} ffmpegOutput
+ * @returns {Array<{ streamIndex: number, type: string, codec: string, language: string, title: string, isDefault: boolean }>}
+ */
+function parseStreams(ffmpegOutput) {
+  // Only the Input section: ffmpeg prints Stream lines for the null OUTPUT
+  // too (wrapped_avframe / pcm_s16le), which would duplicate every track.
+  const inputSection = ffmpegOutput.split(/^(?:Output #|Stream mapping:)/m)[0] ?? ffmpegOutput;
+  const lines = inputSection.split(/\r?\n/);
+  const streams = [];
+  let current = null;
+  for (const line of lines) {
+    const streamMatch = line.match(
+      /^\s*Stream #0:(\d+)(?:\[[^\]]*\])?(?:\(([A-Za-z0-9]{2,3})\))?: (Audio|Video|Subtitle): ([A-Za-z0-9_]+)/
+    );
+    if (streamMatch) {
+      current = {
+        streamIndex: Number(streamMatch[1]),
+        type: streamMatch[3].toLowerCase(),
+        codec: String(streamMatch[4]).toLowerCase(),
+        language: (streamMatch[2] ?? "").toLowerCase(),
+        title: "",
+        isDefault: /\(default\)/.test(line)
+      };
+      streams.push(current);
+      continue;
+    }
+    if (current) {
+      const titleMatch = line.match(/^\s+title\s*:\s*(.+)$/);
+      if (titleMatch && current.title.length === 0) {
+        current.title = titleMatch[1].trim();
+        continue;
+      }
+      // A new top-level section (non-indented line) ends the stream's block.
+      if (!/^\s/.test(line)) {
+        current = null;
+      }
+    }
+  }
+  return streams;
+}
+
+/**
+ * Parse audio and video codec names from ffmpeg stderr output.
+ *
+ * @param {string} ffmpegOutput
+ * @returns {{ audioCodec: string, videoCodec: string }}
+ */
+function parseStreamCodecs(ffmpegOutput) {
+  const audioMatch = ffmpegOutput.match(/Audio:\s*([A-Za-z0-9_]+)/i);
+  const videoMatch = ffmpegOutput.match(/Video:\s*([A-Za-z0-9_]+)/i);
+  // Coded resolution from the video Stream line ("Video: h264 …, 1280x720, …").
+  // The first WxH is the coded size (any trailing "[SAR …]" is ignored).
+  const videoLineMatch = ffmpegOutput.match(/Video:[^\n]*/i);
+  let videoWidth = 0;
+  let videoHeight = 0;
+  if (videoLineMatch) {
+    const dim = videoLineMatch[0].match(/\b(\d{2,5})x(\d{2,5})\b/);
+    if (dim) {
+      videoWidth = Number(dim[1]);
+      videoHeight = Number(dim[2]);
+    }
+  }
+  const containerMatch = ffmpegOutput.match(/Input #0,\s*([^,]+(?:,[^,]+)*?),\s*from/i);
+  const durationMatch = ffmpegOutput.match(/Duration:\s*(\d+):(\d+):(\d+(?:\.\d+)?)/i);
+  let durationSeconds = 0;
+  if (durationMatch) {
+    const value =
+      Number(durationMatch[1]) * 3600 + Number(durationMatch[2]) * 60 + Number(durationMatch[3]);
+    durationSeconds = Number.isFinite(value) ? value : 0;
+  }
+  const streams = parseStreams(ffmpegOutput);
+  const audioTracks = streams
+    .filter((s) => s.type === "audio")
+    .map((s, i) => ({
+      // Type-relative index — what ffmpeg's `-map 0:a:N` selects.
+      index: i,
+      streamIndex: s.streamIndex,
+      codec: s.codec,
+      language: s.language,
+      title: s.title,
+      isDefault: s.isDefault
+    }));
+  const subtitleTracks = streams
+    .filter((s) => s.type === "subtitle")
+    .map((s, i) => ({
+      // Type-relative index — what ffmpeg's `-map 0:s:N` selects.
+      index: i,
+      streamIndex: s.streamIndex,
+      codec: s.codec,
+      language: s.language,
+      title: s.title,
+      isDefault: s.isDefault,
+      // Image-based subtitles (PGS/VobSub) cannot become WebVTT.
+      textBased: TEXT_SUBTITLE_CODECS.has(s.codec)
+    }));
+  return {
+    audioCodec: audioMatch ? String(audioMatch[1]).toLowerCase() : "",
+    videoCodec: videoMatch ? String(videoMatch[1]).toLowerCase() : "",
+    container: containerMatch ? String(containerMatch[1]).trim().toLowerCase() : "",
+    durationSeconds,
+    videoWidth,
+    videoHeight,
+    audioTracks,
+    subtitleTracks
+  };
+}
+
+/**
+ * Run a brief ffmpeg probe to identify the audio and video codecs of a stream.
+ * Times out after `timeoutMs` and returns empty strings on failure.
+ *
+ * @param {object} options
+ * @param {string} options.ffmpegBin
+ * @param {string} options.inputUrl
+ * @param {string} [options.userAgent=""]
+ * @param {number} [options.timeoutMs=8000]
+ * @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) => {
+    const args = ["-hide_banner", "-loglevel", "info"];
+    if (typeof userAgent === "string" && userAgent.trim().length > 0) {
+      args.push("-user_agent", userAgent.trim());
+    }
+    // Decode a tiny slice of all streams (no per-stream -map, so video-only
+    // files probe correctly too).  The ffmpeg banner that precedes decoding
+    // gives us audio/video codecs, the container format and the duration in a
+    // single pass.
+    args.push("-i", inputUrl, "-t", "0.1", "-f", "null", "-");
+
+    const ffmpeg = spawn(ffmpegBin, args, {
+      stdio: ["ignore", "ignore", "pipe"],
+      windowsHide: true
+    });
+    let stderr = "";
+    let settled = false;
+
+    const finish = (codecs) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      resolve(codecs);
+    };
+
+    const timeoutId = setTimeout(() => {
+      if (!ffmpeg.killed) {
+        ffmpeg.kill("SIGTERM");
+      }
+      finish({ ...parseStreamCodecs(stderr), stderr });
+    }, timeoutMs);
+
+    ffmpeg.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+
+    ffmpeg.on("error", () => {
+      clearTimeout(timeoutId);
+      finish({ audioCodec: "", videoCodec: "", stderr: "" });
+    });
+
+    ffmpeg.on("exit", () => {
+      clearTimeout(timeoutId);
+      finish({ ...parseStreamCodecs(stderr), stderr });
+    });
+  });
+}
+
+/**
+ * Resolve after a given number of milliseconds.
+ *
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function delay(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+/**
+ * Build the direct stream URL for a source file served by the local proxy.
+ *
+ * @param {string} localBaseUrl - e.g. "http://127.0.0.1:9090"
+ * @param {string} sourceKey
+ * @param {number} fileIndex
+ * @returns {string}
+ */
+function buildDirectUrl(localBaseUrl, sourceKey, fileIndex) {
+  const directUrl = new URL("/stream", `${localBaseUrl}/`);
+  directUrl.searchParams.set("sourceKey", sourceKey);
+  directUrl.searchParams.set("fileIndex", String(fileIndex));
+  return directUrl.toString();
+}
+
+/**
+ * @typedef {Object} PlaybackPlan
+ * @property {"direct" | "hls"} mode
+ * @property {string} directUrl
+ * @property {string} reason   - Human-readable explanation of the chosen mode.
+ * @property {string} audioCodec
+ * @property {string} videoCodec
+ * @property {string} container         - Demuxer/container name(s) reported by ffmpeg.
+ * @property {number} durationSeconds   - Total media duration in seconds (0 if unknown).
+ * @property {number} videoWidth        - Source coded width (0 if unknown).
+ * @property {number} videoHeight       - Source coded height (0 if unknown).
+ */
+
+/**
+ * @typedef {Object} PlaybackPlannerOptions
+ * @property {string}  ffmpegBin
+ * @property {boolean} transcodeAudioEnabled
+ * @property {string}  localBaseUrl
+ * @property {ReturnType<import("../store/source-registry.js").createSourceRegistry>} sourceRegistry
+ * @property {import("./torrent-pool.js").TorrentPool} torrentPool
+ */
+
+/**
+ * Create a playback planner that decides the optimal streaming mode for
+ * a torrent file. Plans are cached per (sourceKey, fileIndex) pair.
+ *
+ * @param {PlaybackPlannerOptions} options
+ * @returns {{ getPlan: (params: { sourceKey: string, fileIndex: number, userAgent?: string }) => Promise<PlaybackPlan> }}
+ */
+export function createPlaybackPlanner({
+  ffmpegBin,
+  transcodeAudioEnabled,
+  localBaseUrl,
+  sourceRegistry,
+  torrentPool,
+  // Optional. Reports what this host typically takes to produce a session's
+  // first segment. The browser needs it for the gap between "the file is
+  // downloaded" and "a segment exists": until now it assumed the pipeline
+  // merely keeps up with realtime, and showed 15 s where 3.8 s were left.
+  expectedFirstSegmentMs,
+  expectedSessionCreateMs,
+  // Optional. Called once the file's edges are downloaded, so the keyframe
+  // index — which reads the same tail of the file — is fetched alongside the
+  // codec probe instead of after it. Late-bound to the HLS session manager,
+  // which owns the cache both of them share.
+  warmKeyframeIndex,
+  // Optional. The heights this host could actually serve this source at, for
+  // both playback branches, so the quality menu is right from the moment the
+  // file is opened rather than from the moment an encoder exists.
+  predictOfferedHeights
+}) {
+  /** @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();
+
+  /**
+   * Attach what this host currently measures itself taking to create a session
+   * and to produce a first segment.
+   *
+   * Read at RESPONSE time, deliberately. Both are medians of sessions that have
+   * already finished on this host, so at the moment a plan is BUILT the very
+   * first file opened after a restart has none and gets `null` — and the plan
+   * is then cached, so that file kept answering `null` for the life of the
+   * process however many sessions ran afterwards. Measured 2026-08-05: a fresh
+   * 2.9.103 answered `null` for both, then produced the session in 6 ms and the
+   * first segment in 21 479 ms. The figures existed; the plan could not carry
+   * them, and the browser's estimate fell back to its own guess in exactly the
+   * cold-start case the feature was built for.
+   *
+   * @param {PlaybackPlan} plan
+   * @returns {PlaybackPlan}
+   */
+  /**
+   * The probe's subtitle tracks, with `FlagDefault` read from the container
+   * instead of inferred from ffmpeg's banner.
+   *
+   * Best-effort by construction: a container that cannot be read this way, or a
+   * reading that does not line up with the probe, leaves the tracks as they
+   * were with `declaresDefault: false` — which the browser reads as "the file
+   * has no opinion", and then nothing is shown unasked.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @param {object[]} subtitleTracks
+   * @returns {Promise<object[]>}
+   */
+  async function withContainerDefaults(torrent, fileIndex, subtitleTracks) {
+    if (subtitleTracks.length === 0 || typeof torrentPool?.getDeclaredSubtitleTracks !== "function") {
+      return subtitleTracks.map((track) => ({ ...track, declaresDefault: false }));
+    }
+    let declared = [];
+    try {
+      declared = await torrentPool.getDeclaredSubtitleTracks(torrent, fileIndex);
+    } catch (error) {
+      logger.info(`subtitle defaults: the container could not be read (${error?.message ?? error})`);
+    }
+    const merged = mergeContainerSubtitleFlags(subtitleTracks, declared);
+    logger.info(
+      merged.aligned
+        ? "subtitle defaults: the container wrote FlagDefault on " +
+          `${merged.tracks.filter((track) => track.declaresDefault).length} of ${merged.tracks.length} ` +
+          `subtitle tracks, marking ${merged.tracks.filter((track) => track.declaresDefault && track.isDefault).length}`
+        : `subtitle defaults: using the probe's own flags — ${merged.reason}`
+    );
+    return merged.tracks;
+  }
+
+  function withHostTimings(plan) {
+    return {
+      ...plan,
+      expectedFirstSegmentMs: expectedFirstSegmentMs?.() ?? null,
+      expectedSessionCreateMs: expectedSessionCreateMs?.() ?? null,
+      // Answered here for the same reason as the two above: a plan is cached for
+      // the life of the process, and what this host will serve a file at is not.
+      // It starts as a prediction from the startup benchmarks and is replaced by
+      // what an encoder running on this very source turns out to cost — frozen
+      // into the cache, every later open of the file would hand the browser the
+      // first guess again and undo that. This is the 2.9.106 defect exactly.
+      offeredHeights: plan.mediaInfoForOffer
+        ? (predictOfferedHeights?.(plan.mediaInfoForOffer) ?? null)
+        : null,
+      mediaInfoForOffer: undefined
+    };
+  }
+
+  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}
+     */
     /**
      * The audio tracks this file was probed to have, or an empty list. The
      * master playlist publishes one rendition per track, and the inventory is
@@ -348,205 +384,205 @@ export function createPlaybackPlanner({
       return Array.isArray(plan?.audioTracks) ? plan.audioTracks : [];
     },
 
-    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"`
-     * when the source or file cannot be located.
-     *
-     * When the file header has not downloaded yet (cold torrent, peers still
-     * connecting) the codec probe cannot succeed. Rather than block the HTTP
-     * response until it can, the planner prioritises the header, probes for at
-     * most `maxWaitMs`, and if still undetectable returns a plan flagged
-     * `pending: true` (NOT cached). The caller polls again — each call keeps the
-     * header prioritised and downloading — until a real plan comes back. This
-     * avoids a single long request racing the transport's request timeout.
-     *
-     * @param {object} params
-     * @param {string} params.sourceKey
-     * @param {number} params.fileIndex
-     * @param {string} [params.userAgent=""]
-     * @param {number} [params.maxWaitMs=60000] - Max time to wait for the header within ONE call.
-     * @returns {Promise<PlaybackPlan & { pending?: boolean }>}
-     */
-    async getPlan({ sourceKey, fileIndex, userAgent = "", maxWaitMs = 60_000 }) {
-      const cacheKey = `${sourceKey}:${fileIndex}`;
-      const cached = cache.get(cacheKey);
-      if (cached) {
-        return withHostTimings(cached);
-      }
-      // Where the time before playback goes. `cold-start` already breaks down
-      // everything from the transcode-session request onwards, but the plan
-      // runs BEFORE that and was a single opaque wait: a field session spent
-      // 5.7 s here on a torrent already in the store, with the codec probe
-      // cached, and nothing said which part of it was slow.
-      const planEntryMs = Date.now();
-      let torrentReadyMs = 0;
-      let edgesReadyMs = 0;
-
-      const sourceRecord = sourceRegistry.get(sourceKey);
-      if (!sourceRecord) {
-        const error = new Error("Source key was not found.");
-        error.code = "SOURCE_NOT_FOUND";
-        throw error;
-      }
-
-      const torrent = await torrentPool.getTorrent(sourceRecord.sourceType, sourceRecord.source);
-      torrentReadyMs = Date.now() - planEntryMs;
-      const file = torrent.files[fileIndex];
-      if (!file) {
-        const error = new Error("File index was not found in torrent.");
-        error.code = "FILE_NOT_FOUND";
-        throw error;
-      }
-
-      const directUrl = buildDirectUrl(localBaseUrl, sourceKey, fileIndex);
-      if (!transcodeAudioEnabled) {
-        const plan = {
-          mode: "direct",
-          directUrl,
-          reason: "transcode-disabled",
-          audioCodec: "",
-          videoCodec: "",
-          container: "",
-          durationSeconds: 0,
-          videoWidth: 0,
-          videoHeight: 0,
-          audioTracks: [],
-          subtitleTracks: []
-        };
-        cache.set(cacheKey, plan);
-        return withHostTimings(plan);
-      }
-
-      // Pre-fetch file edges (head + tail), then probe — retrying while the
-      // file header is still downloading. In a multi-file torrent the pieces
-      // for a given file arrive unevenly, so the first probe can return empty
-      // codecs. A transient empty probe must NOT be cached: otherwise the wrong
-      // plan (file treated as directly playable) sticks permanently for this
-      // file, and an unsupported codec like xvid gets copied → black video.
-      await torrentPool.prefetchFileEdges(torrent, fileIndex);
-      edgesReadyMs = Date.now() - planEntryMs;
-      // The keyframe index reads the tail of the file, which the probe has just
-      // waited for as well. Started here it overlaps the probe instead of
-      // following the whole plan — worth 311-430 ms of the time before the
-      // first segment. Fire and forget: the session reads it itself if this has
-      // not finished, and both share one cache entry.
-      warmKeyframeIndex?.({
-        sourceKey,
-        fileIndex,
-        inputUrl: new URL(directUrl),
-        logName: file.name
-      });
-      let probe = await probeStreamCodecs({ ffmpegBin, inputUrl: directUrl, userAgent });
-      const probeDeadline = Date.now() + Math.max(0, maxWaitMs);
-      let attempt = 0;
-      while (
-        probe.audioCodec.length === 0 &&
-        probe.videoCodec.length === 0 &&
-        Date.now() < probeDeadline
-      ) {
-        attempt += 1;
-        await delay(Math.min(3_000, 500 + attempt * 250));
-        await torrentPool.prefetchFileEdges(torrent, fileIndex);
-        probe = await probeStreamCodecs({ ffmpegBin, inputUrl: directUrl, userAgent });
-      }
-      const { audioCodec, videoCodec, container, durationSeconds, videoWidth, videoHeight, audioTracks, subtitleTracks } = probe;
-      const codecsDetected = audioCodec.length > 0 || videoCodec.length > 0;
-      logger.info(
-        `plan ${sourceKey.slice(0, 8)}:${fileIndex} torrent-ready=${torrentReadyMs}ms ` +
-          `file-edges=${edgesReadyMs - torrentReadyMs}ms probe=${Date.now() - planEntryMs - edgesReadyMs}ms ` +
-          `total=${Date.now() - planEntryMs}ms attempts=${attempt + 1} ` +
-          `${codecsDetected ? `${videoCodec || "-"}/${audioCodec || "-"}` : "codecs NOT detected (will be polled again)"}`
-      );
-
-      // `mode` is advisory only (audio-codec based). The browser makes the
-      // authoritative decision independently per stream via canPlayType /
-      // mediaCapabilities, transcoding only what it cannot play.
-      const requiresTranscode = audioCodec.length > 0 && !DIRECT_AUDIO_CODECS.has(audioCodec);
-      const plan = {
-        mode: requiresTranscode ? "hls" : "direct",
-        directUrl,
-        reason: requiresTranscode ? "audio-codec-transcode-required" : "audio-codec-supported",
-        audioCodec,
-        videoCodec,
-        container,
-        durationSeconds,
-        // Source coded resolution — drives the browser's manual quality menu
-        // (list of forced resolutions <= source). 0 when unknown.
-        videoWidth,
-        videoHeight,
-        // Full track inventory for the browser's audio/subtitle menus.
-        audioTracks: audioTracks ?? [],
-        subtitleTracks: subtitleTracks ?? [],
-        // Both host timings are filled in by `withHostTimings` on the way out,
-        // never here: read at build time they would be frozen into the cached
-        // plan, which is the bug fixed in 2.9.106.
-        expectedFirstSegmentMs: null,
-        expectedSessionCreateMs: null,
-        offeredHeights: null,
-        // What the offer is computed FROM, kept on the cached plan so the offer
-        // itself can be recomputed on every response. The figures are the
-        // probe's own and never change for a file; the answer derived from them
-        // does, as the host learns what this source costs. Stripped on the way
-        // out — it is not part of the plan the browser is given.
-        mediaInfoForOffer: {
-          width: videoWidth,
-          height: videoHeight,
-          fps: parseFfmpegVideoFps(probe.stderr),
-          bitrateKbps: parseFfmpegBitrateKbps(probe.stderr),
-          // Which file this is, so the offer can be answered from what an
-          // encoder has already learned about THIS source rather than from the
-          // startup clips — the same correction a live session applies.
-          sourceKey,
-          fileIndex
-        }
-      };
-      // Only cache a plan whose codecs were actually detected. An empty probe is
-      // a "header not downloaded yet" signal, not a valid result — caching it
-      // would permanently mis-plan the file. In that case flag the plan
-      // `pending` so the caller polls again (the header keeps downloading,
-      // 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, {
-          // The codecs, because the session manager asks this cache which
-          // tracks the output will carry — and they were never stored here. It
-          // read `videoCodec`/`audioCodec` off an object that has only ever had
-          // dimensions and duration, got `undefined` for both, and declared
-          // `{video: false, audio: false}` for EVERY session since the check was
-          // written. Measured 2026-08-11: `declared tracks video=false
-          // audio=false`, which left the browser unable to tell "this file has
-          // no video" from "the video was lost on the way", and left the init
-          // guard expecting zero tracks and therefore accepting any header.
-          videoCodec: plan.videoCodec,
-          audioCodec: plan.audioCodec,
-          durationSeconds: parseFfmpegDurationSeconds(probe.stderr),
-          width: dims.width,
-          height: dims.height,
-          bitrateKbps: parseFfmpegBitrateKbps(probe.stderr),
-          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 withHostTimings(plan);
-      }
-      return withHostTimings({ ...plan, pending: true });
-    }
-  };
-}
+    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"`
+     * when the source or file cannot be located.
+     *
+     * When the file header has not downloaded yet (cold torrent, peers still
+     * connecting) the codec probe cannot succeed. Rather than block the HTTP
+     * response until it can, the planner prioritises the header, probes for at
+     * most `maxWaitMs`, and if still undetectable returns a plan flagged
+     * `pending: true` (NOT cached). The caller polls again — each call keeps the
+     * header prioritised and downloading — until a real plan comes back. This
+     * avoids a single long request racing the transport's request timeout.
+     *
+     * @param {object} params
+     * @param {string} params.sourceKey
+     * @param {number} params.fileIndex
+     * @param {string} [params.userAgent=""]
+     * @param {number} [params.maxWaitMs=60000] - Max time to wait for the header within ONE call.
+     * @returns {Promise<PlaybackPlan & { pending?: boolean }>}
+     */
+    async getPlan({ sourceKey, fileIndex, userAgent = "", maxWaitMs = 60_000 }) {
+      const cacheKey = `${sourceKey}:${fileIndex}`;
+      const cached = cache.get(cacheKey);
+      if (cached) {
+        return withHostTimings(cached);
+      }
+      // Where the time before playback goes. `cold-start` already breaks down
+      // everything from the transcode-session request onwards, but the plan
+      // runs BEFORE that and was a single opaque wait: a field session spent
+      // 5.7 s here on a torrent already in the store, with the codec probe
+      // cached, and nothing said which part of it was slow.
+      const planEntryMs = Date.now();
+      let torrentReadyMs = 0;
+      let edgesReadyMs = 0;
+
+      const sourceRecord = sourceRegistry.get(sourceKey);
+      if (!sourceRecord) {
+        const error = new Error("Source key was not found.");
+        error.code = "SOURCE_NOT_FOUND";
+        throw error;
+      }
+
+      const torrent = await torrentPool.getTorrent(sourceRecord.sourceType, sourceRecord.source);
+      torrentReadyMs = Date.now() - planEntryMs;
+      const file = torrent.files[fileIndex];
+      if (!file) {
+        const error = new Error("File index was not found in torrent.");
+        error.code = "FILE_NOT_FOUND";
+        throw error;
+      }
+
+      const directUrl = buildDirectUrl(localBaseUrl, sourceKey, fileIndex);
+      if (!transcodeAudioEnabled) {
+        const plan = {
+          mode: "direct",
+          directUrl,
+          reason: "transcode-disabled",
+          audioCodec: "",
+          videoCodec: "",
+          container: "",
+          durationSeconds: 0,
+          videoWidth: 0,
+          videoHeight: 0,
+          audioTracks: [],
+          subtitleTracks: []
+        };
+        cache.set(cacheKey, plan);
+        return withHostTimings(plan);
+      }
+
+      // Pre-fetch file edges (head + tail), then probe — retrying while the
+      // file header is still downloading. In a multi-file torrent the pieces
+      // for a given file arrive unevenly, so the first probe can return empty
+      // codecs. A transient empty probe must NOT be cached: otherwise the wrong
+      // plan (file treated as directly playable) sticks permanently for this
+      // file, and an unsupported codec like xvid gets copied → black video.
+      await torrentPool.prefetchFileEdges(torrent, fileIndex);
+      edgesReadyMs = Date.now() - planEntryMs;
+      // The keyframe index reads the tail of the file, which the probe has just
+      // waited for as well. Started here it overlaps the probe instead of
+      // following the whole plan — worth 311-430 ms of the time before the
+      // first segment. Fire and forget: the session reads it itself if this has
+      // not finished, and both share one cache entry.
+      warmKeyframeIndex?.({
+        sourceKey,
+        fileIndex,
+        inputUrl: new URL(directUrl),
+        logName: file.name
+      });
+      let probe = await probeStreamCodecs({ ffmpegBin, inputUrl: directUrl, userAgent });
+      const probeDeadline = Date.now() + Math.max(0, maxWaitMs);
+      let attempt = 0;
+      while (
+        probe.audioCodec.length === 0 &&
+        probe.videoCodec.length === 0 &&
+        Date.now() < probeDeadline
+      ) {
+        attempt += 1;
+        await delay(Math.min(3_000, 500 + attempt * 250));
+        await torrentPool.prefetchFileEdges(torrent, fileIndex);
+        probe = await probeStreamCodecs({ ffmpegBin, inputUrl: directUrl, userAgent });
+      }
+      const { audioCodec, videoCodec, container, durationSeconds, videoWidth, videoHeight, audioTracks, subtitleTracks } = probe;
+      const codecsDetected = audioCodec.length > 0 || videoCodec.length > 0;
+      logger.info(
+        `plan ${sourceKey.slice(0, 8)}:${fileIndex} torrent-ready=${torrentReadyMs}ms ` +
+          `file-edges=${edgesReadyMs - torrentReadyMs}ms probe=${Date.now() - planEntryMs - edgesReadyMs}ms ` +
+          `total=${Date.now() - planEntryMs}ms attempts=${attempt + 1} ` +
+          `${codecsDetected ? `${videoCodec || "-"}/${audioCodec || "-"}` : "codecs NOT detected (will be polled again)"}`
+      );
+
+      // `mode` is advisory only (audio-codec based). The browser makes the
+      // authoritative decision independently per stream via canPlayType /
+      // mediaCapabilities, transcoding only what it cannot play.
+      const requiresTranscode = audioCodec.length > 0 && !DIRECT_AUDIO_CODECS.has(audioCodec);
+      const plan = {
+        mode: requiresTranscode ? "hls" : "direct",
+        directUrl,
+        reason: requiresTranscode ? "audio-codec-transcode-required" : "audio-codec-supported",
+        audioCodec,
+        videoCodec,
+        container,
+        durationSeconds,
+        // Source coded resolution — drives the browser's manual quality menu
+        // (list of forced resolutions <= source). 0 when unknown.
+        videoWidth,
+        videoHeight,
+        // Full track inventory for the browser's audio/subtitle menus.
+        audioTracks: audioTracks ?? [],
+        subtitleTracks: await withContainerDefaults(torrent, fileIndex, subtitleTracks ?? []),
+        // Both host timings are filled in by `withHostTimings` on the way out,
+        // never here: read at build time they would be frozen into the cached
+        // plan, which is the bug fixed in 2.9.106.
+        expectedFirstSegmentMs: null,
+        expectedSessionCreateMs: null,
+        offeredHeights: null,
+        // What the offer is computed FROM, kept on the cached plan so the offer
+        // itself can be recomputed on every response. The figures are the
+        // probe's own and never change for a file; the answer derived from them
+        // does, as the host learns what this source costs. Stripped on the way
+        // out — it is not part of the plan the browser is given.
+        mediaInfoForOffer: {
+          width: videoWidth,
+          height: videoHeight,
+          fps: parseFfmpegVideoFps(probe.stderr),
+          bitrateKbps: parseFfmpegBitrateKbps(probe.stderr),
+          // Which file this is, so the offer can be answered from what an
+          // encoder has already learned about THIS source rather than from the
+          // startup clips — the same correction a live session applies.
+          sourceKey,
+          fileIndex
+        }
+      };
+      // Only cache a plan whose codecs were actually detected. An empty probe is
+      // a "header not downloaded yet" signal, not a valid result — caching it
+      // would permanently mis-plan the file. In that case flag the plan
+      // `pending` so the caller polls again (the header keeps downloading,
+      // 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, {
+          // The codecs, because the session manager asks this cache which
+          // tracks the output will carry — and they were never stored here. It
+          // read `videoCodec`/`audioCodec` off an object that has only ever had
+          // dimensions and duration, got `undefined` for both, and declared
+          // `{video: false, audio: false}` for EVERY session since the check was
+          // written. Measured 2026-08-11: `declared tracks video=false
+          // audio=false`, which left the browser unable to tell "this file has
+          // no video" from "the video was lost on the way", and left the init
+          // guard expecting zero tracks and therefore accepting any header.
+          videoCodec: plan.videoCodec,
+          audioCodec: plan.audioCodec,
+          durationSeconds: parseFfmpegDurationSeconds(probe.stderr),
+          width: dims.width,
+          height: dims.height,
+          bitrateKbps: parseFfmpegBitrateKbps(probe.stderr),
+          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 withHostTimings(plan);
+      }
+      return withHostTimings({ ...plan, pending: true });
+    }
+  };
+}