@torrent-tv/proxy 2.86.0 → 2.87.1

package/services/media/keyframe-probe.js

@@ -0,0 +1,157 @@
+/**
+ * @file Where a file's keyframes are, found by DECODING it rather than by
+ * reading what its container states.
+ *
+ * The SECOND reader of one fact, and the weaker of the two: the container's own
+ * index is two point reads of 16 KB and names every keyframe, while this scans
+ * the media over a torrent-backed input and on a large file often does not
+ * finish — measured 2026-08-02, 77 keyframes in 45 s against all 570 in 0.8 s
+ * from the index. So it is never waited for and never displaces an index that
+ * answered; `KeyframeTable.learn` keeps the fuller answer whichever arrives
+ * second.
+ *
+ * It exists because some containers state no index at all, and a keyframe is
+ * still needed for something both encode branches need: choosing a SOURCE seek
+ * position ffmpeg can land on. `-ss` before `-i` trusts the container's
+ * on-the-fly seek, which for some containers (observed: AVI with VBR MP3 audio)
+ * can point at a position with no valid frame boundary at all — ffmpeg then
+ * fails outright ("Seek failed" / "Header missing"), not merely imprecisely.
+ *
+ * **Why it is here and not in `container/`.** It runs a process and reads the
+ * file over the address this proxy serves it at. A container is built from four
+ * functions and takes byte ranges; it spawns nothing and knows no URL. Both are
+ * readings of the same file, so both are this layer's — and they are separate
+ * files because one of them needs a machine and the other needs sixteen
+ * kilobytes.
+ */
+
+import { spawn } from "node:child_process";
+
+/**
+ * The ffprobe that sits beside a given ffmpeg.
+ *
+ * @param {string} ffmpegBin
+ * @returns {string}
+ */
+export function ffprobeBinFor(ffmpegBin) {
+  if (typeof ffmpegBin !== "string" || ffmpegBin.length === 0) {
+    return "ffprobe";
+  }
+  if (/ffmpeg(\.exe)?$/i.test(ffmpegBin)) {
+    return ffmpegBin.replace(/ffmpeg(\.exe)?$/i, "ffprobe$1");
+  }
+  return "ffprobe";
+}
+
+/**
+ * Where this file's keyframes are, found by DECODING it rather than by reading
+ * what its container states.
+ *
+ * The second reader of one fact, and the weaker of the two: the container's own
+ * index is two point reads of 16 KB and names every keyframe, while this scans
+ * the media over a torrent-backed input and on a large file often does not
+ * finish — measured 2026-08-02, 77 keyframes in 45 s against all 570 in 0.8 s
+ * from the index. So it is never waited for and never displaces an index that
+ * answered; `KeyframeTable.learn` keeps the fuller answer whichever arrives
+ * second.
+ *
+ * It exists because some containers state no index at all, and a keyframe is
+ * still needed for something both branches need: choosing a SOURCE seek
+ * position ffmpeg can land on. `-ss` before `-i` trusts the container's
+ * on-the-fly seek, which for some containers (observed: AVI with VBR MP3 audio)
+ * can point at a position with no valid frame boundary at all — ffmpeg then
+ * fails outright ("Seek failed" / "Header missing"), not merely imprecisely.
+ *
+ * It lives here, beside the codec probe, because it is the same kind of thing:
+ * a reading of the file made by running ffmpeg's own tools over the address
+ * this proxy serves it at. The container layer takes byte ranges and spawns
+ * nothing.
+ *
+ * @param {string} ffmpegBin
+ * @param {string | URL} inputUrl
+ * @param {number} [timeoutMs]
+ * @returns {Promise<number[] | null>} Sorted keyframe times, or null.
+ */
+export async function probeVideoKeyframeTimes(ffmpegBin, inputUrl, timeoutMs = 25_000) {
+  return new Promise((resolve) => {
+    let proc;
+    try {
+      proc = spawn(
+        ffprobeBinFor(ffmpegBin),
+        [
+          "-v", "error",
+          // `-skip_frame nokey` makes the decoder discard non-keyframes, so the
+          // probe reads only what it needs. Without it a full packet scan of a
+          // ~5 GB MKV cannot finish inside any sane budget over a torrent-backed
+          // input, the probe returns nothing, and the playlist falls back to a
+          // uniform grid — which on the COPY path is a lie: cuts land on the
+          // source's real keyframes, not on a 4 s ruler. The player then finds
+          // the declared times do not match the media, stops trusting the
+          // playlist and walks the file from segment #1 to locate the seek
+          // position by hand (field 2026-08-02: a seek to 1:30 produced requests
+          // #1, #2, #45, #86, #123 … #1187, taking minutes and never arriving).
+          "-skip_frame", "nokey",
+          "-select_streams", "v:0",
+          "-show_entries", "packet=pts_time,flags",
+          "-of", "csv=p=0",
+          String(inputUrl)
+        ],
+        { stdio: ["ignore", "pipe", "ignore"], windowsHide: true }
+      );
+    } catch {
+      resolve(null);
+      return;
+    }
+    let stdout = "";
+    let settled = false;
+    const finish = (value) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      resolve(value);
+    };
+    const timer = setTimeout(() => {
+      try {
+        if (!proc.killed) {
+          proc.kill("SIGTERM");
+        }
+      } catch {
+        // ignore
+      }
+      finish(null);
+    }, timeoutMs);
+    proc.stdout.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+    proc.on("error", () => {
+      clearTimeout(timer);
+      finish(null);
+    });
+    proc.on("exit", (code) => {
+      clearTimeout(timer);
+      if (code !== 0) {
+        finish(null);
+        return;
+      }
+      const times = [];
+      for (const line of stdout.split("\n")) {
+        // Each line: "<pts_time>,<flags>" e.g. "12.345000,K__"
+        const comma = line.indexOf(",");
+        if (comma < 0) {
+          continue;
+        }
+        const flags = line.slice(comma + 1);
+        if (!flags.includes("K")) {
+          continue;
+        }
+        const t = Number(line.slice(0, comma));
+        if (Number.isFinite(t)) {
+          times.push(t);
+        }
+      }
+      times.sort((a, b) => a - b);
+      finish(times.length > 0 ? times : null);
+    });
+  });
+}

package/services/media/media-info-probe.js

@@ -0,0 +1,93 @@
+/**
+ * @file What a stream's own header says: duration, picture size, frame rate,
+ * start time, stream counts and HDR — from one short ffmpeg run that stops as
+ * soon as the header has been printed.
+ */
+
+import { spawn } from "node:child_process";
+import {
+  parseFfmpegBitrateKbps,
+  parseFfmpegDurationSeconds,
+  parseFfmpegHdr,
+  parseFfmpegStartTimeSeconds,
+  parseFfmpegStreamCounts,
+  parseFfmpegVideoDimensions,
+  parseFfmpegVideoFps
+} from "./ffmpeg-banner.js";
+
+/**
+ * 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
+ * (before any decoding), so this returns as soon as they are seen; an 8 s
+ * timeout guards the rest.
+ *
+ * @param {string} ffmpegBin - Path to the ffmpeg executable.
+ * @param {string | URL} inputUrl - URL of the stream to probe.
+ * @returns {Promise<{ durationSeconds: number | null, width: number | null, height: number | null, fps: number | null, startTime: number, isHdr: boolean }>}
+ */
+export async function probeInputMediaInfo(ffmpegBin, inputUrl) {
+  return new Promise((resolve) => {
+    const ffmpeg = spawn(ffmpegBin, ["-hide_banner", "-loglevel", "info", "-i", inputUrl, "-f", "null", "-"], {
+      stdio: ["ignore", "ignore", "pipe"],
+      windowsHide: true
+    });
+    let stderr = "";
+    let settled = false;
+    const finish = () => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      const dims = parseFfmpegVideoDimensions(stderr);
+      resolve({
+        durationSeconds: parseFfmpegDurationSeconds(stderr),
+        bitrateKbps: parseFfmpegBitrateKbps(stderr),
+        width: dims.width,
+        height: dims.height,
+        fps: parseFfmpegVideoFps(stderr),
+        startTime: parseFfmpegStartTimeSeconds(stderr),
+        // Only ever read when a run fails, and read HERE because by then the
+        // banner is long gone: this probe is the one place the source says what
+        // it holds.
+        streamCounts: parseFfmpegStreamCounts(stderr),
+        isHdr: parseFfmpegHdr(stderr)
+      });
+    };
+    const timeoutId = setTimeout(() => {
+      if (!ffmpeg.killed) {
+        ffmpeg.kill("SIGTERM");
+      }
+      finish();
+    }, 8_000);
+    ffmpeg.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+      // The header ("Duration:" then the "Video: … WxH" stream line) is printed
+      // before any decoding. Bail as soon as both are present instead of letting
+      // `-f null -` decode the whole stream until the 8 s timeout.
+      //
+      // This probe asks about the PICTURE and nothing else now: a file with no
+      // video track is read by the container layer, which answers from 64 KB of
+      // header. It used to take an `expectVideo: false` for exactly that case,
+      // and the branch cost 8121 ms of every cold start (2026-09-03) because
+      // the exit still waited for a parsed DURATION, which a partly downloaded
+      // file prints as `N/A`.
+      const duration = parseFfmpegDurationSeconds(stderr);
+      const dims = parseFfmpegVideoDimensions(stderr);
+      if (duration != null && dims.width != null) {
+        clearTimeout(timeoutId);
+        if (!ffmpeg.killed) {
+          ffmpeg.kill("SIGTERM");
+        }
+        finish();
+      }
+    });
+    ffmpeg.on("error", () => {
+      clearTimeout(timeoutId);
+      finish();
+    });
+    ffmpeg.on("exit", () => {
+      clearTimeout(timeoutId);
+      finish();
+    });
+  });
+}

package/services/{playback-planner.js → media/playback-planner.js}

@@ -7,10 +7,9 @@
  */
 
 import { spawn } from "node:child_process";
-import { logger } from "../utils/logger.js";
+import { logger } from "../../utils/logger.js";
 import { Container } from "./container/Container.js";
 import { buildAudioInventory } from "./audio-inventory.js";
-import { contentsOf } from "./torrent/Contents.js";
 import {
   parseFfmpegDurationSeconds,
   parseFfmpegStartTimeSeconds,
@@ -50,6 +49,18 @@ const TEXT_SUBTITLE_CODECS = new Set(["subrip", "srt", "ass", "ssa", "webvtt", "
  * @param {string} ffmpegOutput
  * @returns {Array<{ streamIndex: number, type: string, codec: string, language: string, title: string, isDefault: boolean }>}
  */
+/**
+ * The bitrate a stream line states for that stream, in kbit/s, or null.
+ *
+ * @param {string} line
+ * @returns {number | null}
+ */
+function kbpsFromStreamLine(line) {
+  const match = line.match(/,\s*(\d+)\s*kb\/s/);
+  const kbps = match ? Number(match[1]) : Number.NaN;
+  return Number.isFinite(kbps) && kbps > 0 ? kbps : null;
+}
+
 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.
@@ -68,12 +79,21 @@ function parseStreams(ffmpegOutput) {
         codec: String(streamMatch[4]).toLowerCase(),
         language: (streamMatch[2] ?? "").toLowerCase(),
         title: "",
-        isDefault: /\(default\)/.test(line)
+        isDefault: /\(default\)/.test(line),
+        // What the stream line states for THIS stream, e.g. "…, 128 kb/s". A
+        // Matroska stream usually states none here and carries its rate as a
+        // statistics tag instead (`BPS`, read below). Never the file's total.
+        bitrateKbps: kbpsFromStreamLine(line)
       };
       streams.push(current);
       continue;
     }
     if (current) {
+      const bpsMatch = line.match(/^\s+BPS(?:-[A-Za-z]+)?\s*:\s*(\d+)\s*$/);
+      if (bpsMatch && current.bitrateKbps === null) {
+        current.bitrateKbps = Math.round(Number(bpsMatch[1]) / 1000);
+        continue;
+      }
       const titleMatch = line.match(/^\s+title\s*:\s*(.+)$/);
       if (titleMatch && current.title.length === 0) {
         current.title = titleMatch[1].trim();
@@ -94,7 +114,7 @@ function parseStreams(ffmpegOutput) {
  * @param {string} ffmpegOutput
  * @returns {{ audioCodec: string, videoCodec: string }}
  */
-function parseStreamCodecs(ffmpegOutput) {
+export 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, …").
@@ -127,7 +147,8 @@ function parseStreamCodecs(ffmpegOutput) {
       codec: s.codec,
       language: s.language,
       title: s.title,
-      isDefault: s.isDefault
+      isDefault: s.isDefault,
+      bitrateKbps: s.bitrateKbps
     }));
   const subtitleTracks = streams
     .filter((s) => s.type === "subtitle")
@@ -262,8 +283,8 @@ function buildDirectUrl(localBaseUrl, sourceKey, fileIndex) {
  * @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
+ * @property {ReturnType<import("../../store/source-registry.js").createSourceRegistry>} sourceRegistry
+ * @property {import("../torrent/torrent-pool.js").TorrentPool} torrentPool
  */
 
 /**
@@ -285,10 +306,22 @@ export function createPlaybackPlanner({
   // merely keeps up with realtime, and showed 15 s where 3.8 s were left.
   expectedFirstSegmentMs,
   expectedSessionCreateMs,
+  // What the torrent holds beside this picture — its dubs, its subtitle files,
+  // its contact sheets — grouped by whoever knows what a torrent contains. This
+  // layer answers about ONE file and must not read a torrent's file list.
+  sidecarsFromTorrent = null,
+  // What a file DECLARES about its own tracks, read from its header. Handed in
+  // rather than asked of the torrent pool: this layer used to call
+  // `torrentPool.getDeclaredAudioTracks` and friends, which is the media layer
+  // asking the torrent layer to parse a container on its behalf — the parse
+  // happened in the torrent thread and came back over the channel. It happens
+  // on this thread now, and what is passed here is the ordinary container read.
+  declaredTracksOf = null,
   // 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.
+  // codec probe instead of after it. It goes straight to `KeyframeTables`,
+  // which owns that table: it used to be routed through the session manager,
+  // which held a second copy of it and a second reader for it.
   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
@@ -339,27 +372,30 @@ export function createPlaybackPlanner({
   /**
    * The files beside this picture that belong to it, in three groups.
    *
-   * Asked of what the torrent says about itself, which works the grouping out
-   * once and keeps it. It used to be worked out here on every call, and again
-   * on the warm-up's own path over the same list, so one opened film paired the
-   * same files several times and neither side could be sure of the other's
-   * answer.
+   * HANDED IN, because what a torrent contains is the torrent layer's to say
+   * and this is the media layer. It works the grouping out once and keeps it;
+   * it used to be worked out here on every call, and again on the warm-up's own
+   * path over the same list, so one opened film paired the same files several
+   * times and neither side could be sure of the other's answer.
+   *
+   * Absent, a file has no companions — which is what a proxy with no torrent
+   * behind it should answer, rather than failing.
    *
    * @param {object} torrent
    * @param {number} fileIndex
    * @returns {{ audio: object[], subtitles: object[], images: object[] }}
    */
   function sidecarsOf(torrent, fileIndex) {
-    return contentsOf(torrent ?? {}).sidecarsOf(fileIndex);
+    return sidecarsFromTorrent?.(torrent ?? {}, fileIndex) ?? { audio: [], subtitles: [], images: [] };
   }
 
-  async function withContainerDefaults(torrent, fileIndex, subtitleTracks) {
-    if (subtitleTracks.length === 0 || typeof torrentPool?.getDeclaredSubtitleTracks !== "function") {
+  async function withContainerDefaults(sourceKey, torrent, fileIndex, subtitleTracks) {
+    if (subtitleTracks.length === 0 || typeof declaredTracksOf !== "function") {
       return subtitleTracks.map((track) => ({ ...track, declaresDefault: false }));
     }
     let declared = [];
     try {
-      declared = await torrentPool.getDeclaredSubtitleTracks(torrent, fileIndex);
+      declared = (await declaredTracksOf({ sourceKey, fileIndex })).filter((track) => track?.type === "subtitle");
     } catch (error) {
       logger.info(`subtitle defaults: the container could not be read (${error?.message ?? error})`);
     }
@@ -385,12 +421,13 @@ export function createPlaybackPlanner({
    * menu and the number in the `a/<n>/` address are the same number by
    * construction rather than by agreement.
    *
+   * @param {string} sourceKey
    * @param {object} torrent
    * @param {number} fileIndex
    * @param {object[]} bannerAudioTracks - The probe's own audio streams.
    * @returns {Promise<import("./audio-inventory.js").AudioInventoryEntry[]>}
    */
-  async function buildInventory(torrent, fileIndex, bannerAudioTracks) {
+  async function buildInventory(sourceKey, torrent, fileIndex, bannerAudioTracks) {
     const banner = Array.isArray(bannerAudioTracks) ? bannerAudioTracks : [];
     /**
      * Read a file's declared audio tracks, or give up quickly.
@@ -410,13 +447,15 @@ export function createPlaybackPlanner({
      * @returns {Promise<object[]>}
      */
     const declaredAudioOf = async (wantedFileIndex, label) => {
-      if (typeof torrentPool?.getDeclaredAudioTracks !== "function") {
+      if (typeof declaredTracksOf !== "function") {
         return [];
       }
       let timer = null;
       try {
         return await Promise.race([
-          torrentPool.getDeclaredAudioTracks(torrent, wantedFileIndex),
+          declaredTracksOf({ sourceKey, fileIndex: wantedFileIndex }).then((tracks) => tracks
+            .filter((track) => track?.type === "audio")
+            .sort((left, right) => (left.declaredIndex ?? 0) - (right.declaredIndex ?? 0))),
           new Promise((resolve) => {
             timer = setTimeout(() => resolve(null), SIDECAR_HEADER_WAIT_MS);
             timer.unref?.();
@@ -499,7 +538,12 @@ export function createPlaybackPlanner({
       offeredHeights: plan.mediaInfoForOffer
         ? (predictOfferedHeights?.(plan.mediaInfoForOffer) ?? null)
         : null,
-      mediaInfoForOffer: undefined
+      // The description the rest of the pool answers by arithmetic. Carried
+      // on every plan, not only on a refusal here: the output opened next can
+      // still be refused for want of a place on this machine (roadmap item 97,
+      // step 14), and the page then asks the pool the same question before
+      // anything plays — which it can only do with this in hand.
+      mediaInfoForOffer: plan.mediaInfoForOffer
     };
     // Refused rather than served badly. Both lists empty means this machine
     // cannot sustain this file at ANY height — not even by copying the picture,
@@ -513,13 +557,12 @@ export function createPlaybackPlanner({
     if (offer && offer.copy.length === 0 && offer.transcode.length === 0) {
       withOffer.cannotServe =
         "This proxy cannot keep up with this file at any quality right now.";
-      // The description travels with the refusal, and only with it. It is what
-      // lets the browser ask the rest of the pool the same question without
-      // anybody else adding the torrent, fetching a byte or running ffmpeg —
-      // the expensive half of finding out what this file IS has been paid here,
+      // The description travels with the plan (above). It is what lets the
+      // browser ask the rest of the pool the same question without anybody
+      // else adding the torrent, fetching a byte or running ffmpeg — the
+      // expensive half of finding out what this file IS has been paid here,
       // once. Everyone else answers by arithmetic against their own startup
       // benchmarks.
-      withOffer.mediaInfoForOffer = plan.mediaInfoForOffer;
     }
     return withOffer;
   }
@@ -634,14 +677,9 @@ export function createPlaybackPlanner({
       // 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
-      });
+      // first segment. Fire and forget: a session that finds the table
+      // unanswered joins this very read rather than starting a second one.
+      warmKeyframeIndex?.({ sourceKey, fileIndex, logName: file.name });
       let probe = await probeStreamCodecs({ ffmpegBin, inputUrl: directUrl, userAgent });
       const probeDeadline = Date.now() + Math.max(0, maxWaitMs);
       let attempt = 0;
@@ -669,9 +707,14 @@ export function createPlaybackPlanner({
       // banner, while the `VideoTrack` the container declares was read and used
       // for nothing but a line in the log.
       let declaredVideo = null;
-      if (typeof torrentPool?.getDeclaredVideoTrack === "function") {
+      if (typeof declaredTracksOf === "function") {
         try {
-          declaredVideo = await torrentPool.getDeclaredVideoTrack(torrent, fileIndex);
+          // One, because ffmpeg's `0:v:0` is what everything downstream is built
+          // on and a second video stream is a cover image far more often than a
+          // second film.
+          declaredVideo = (await declaredTracksOf({ sourceKey, fileIndex }))
+            .filter((track) => track?.type === "video")
+            .sort((left, right) => (left.declaredIndex ?? 0) - (right.declaredIndex ?? 0))[0] ?? null;
         } catch (error) {
           logger.info(`video track: could not be read (${error?.message ?? error})`);
         }
@@ -714,8 +757,8 @@ export function createPlaybackPlanner({
         // Full track inventory for the browser's audio/subtitle menus. The audio
         // half spans the picture's own tracks AND the soundtracks shipped as
         // files beside it, under one numbering — see `buildInventory`.
-        audioTracks: await buildInventory(torrent, fileIndex, audioTracks ?? []),
-        subtitleTracks: await withContainerDefaults(torrent, fileIndex, subtitleTracks ?? []),
+        audioTracks: await buildInventory(sourceKey, torrent, fileIndex, audioTracks ?? []),
+        subtitleTracks: await withContainerDefaults(sourceKey, torrent, fileIndex, subtitleTracks ?? []),
         // The files BESIDE this picture that belong to it, and what each one's
         // own path says about the track in it. Both answers are made here, by
         // one grammar, because the browser used to make them again: it paired