@torrent-tv/proxy 2.12.2 → 2.14.0

package/assets/calibration/NOTICE.md

@@ -0,0 +1,30 @@
+# Calibration clips — attribution
+
+The three clips in this folder are excerpts from **"Meridian"**, part of
+[Netflix Open Content](https://opencontent.netflix.com/), licensed under the
+**Creative Commons Attribution 4.0 International (CC BY 4.0)** licence:
+<https://creativecommons.org/licenses/by/4.0/>.
+
+They were cut from `Meridian/Meridian_UHD4k5994_HDR_P3PQ.mp4` and re-encoded to
+H.264 High, 24 fps, 5.04 s (121 frames), no audio:
+
+| file | resolution | bitrate |
+|---|---|---|
+| `cal-1080-hi.mp4` | 1920×1080 | 11.38 Mbit/s |
+| `cal-1080-lo.mp4` | 1920×1080 | 0.97 Mbit/s |
+| `cal-720.mp4` | 1280×720 | 2.25 Mbit/s |
+
+## Why these three, and why real footage
+
+`services/hwaccel.js` decodes them at startup and solves the host's decode cost,
+`a × Mpixel/s + b × Mbit/s + c`, from the three measurements. The first two
+clips share a pixel count and differ 11.7× in bitrate; the third changes the
+pixel count. Three points, three unknowns.
+
+Real, grainy live action rather than a generated pattern: measured 2026-08-14 on
+the addon host, this material decodes 11 % away from the film being served,
+where a generated `testsrc2` clip is 158 % away.
+
+Replacing a clip is allowed — the benchmark reads each clip's dimensions, frame
+rate and bitrate from ffmpeg's own output rather than from this table — but the
+three must keep spanning the two axes, or the fit has nothing to separate.

package/bin/cli.js

@@ -76,6 +76,10 @@ program
   .option("--max-disk-bytes <bytes>", "Cap total downloaded torrent data (0 = disabled; default min(10GB, half free disk))")
   .option("--memory-bytes <bytes>", "Per-torrent budget for pieces kept in memory before spilling to disk (default 512MB)")
   .option("--ffmpeg-bin <path>", "Path to ffmpeg binary")
+  .option(
+    "--state-dir <path>",
+    "Where to keep what this host has measured about itself (default: beside the installed proxy)"
+  )
   .option(
     "--segment-format <format>",
     `HLS output container: ${SEGMENT_FORMAT_IDS.join(" | ")}`,
@@ -273,7 +277,8 @@ try {
     ffmpegBin,
     maxDiskBytes,
     memoryBytes,
-    segmentFormat: options.segmentFormat
+    segmentFormat: options.segmentFormat,
+    stateDir: options.stateDir
   });
   app = started.app;
   actualPort = started.port;

package/package.json

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

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

@@ -73,6 +73,11 @@ export async function handleApiTranscodeSessionsPost(req, reply, { hlsSessionMan
   // (capped to source), with the realtime budget's auto-downscale + runtime
   // downswitch disabled for the session.
   const manualQuality = payload.manualQuality === true;
+  // Whether this browser will take its audio from a separate rendition group in
+  // the master playlist rather than muxed into the picture. It has to say so:
+  // publishing renditions AND muxing the same audio would play it twice, while
+  // a browser that does not know about them would get no sound at all.
+  const audioRenditions = payload.audioRenditions === true;
   const startPositionSeconds = Number(payload.startPositionSeconds);
   const audioTrackIndex = Number(payload.audioTrackIndex);
   // Which container to produce. The browser knows what its media stack will
@@ -96,6 +101,7 @@ export async function handleApiTranscodeSessionsPost(req, reply, { hlsSessionMan
       targetWidth: Number.isInteger(targetWidth) && targetWidth > 0 ? targetWidth : 0,
       targetHeight: Number.isInteger(targetHeight) && targetHeight > 0 ? targetHeight : 0,
       manualQuality,
+      audioRenditions,
       startPositionSeconds:
         Number.isFinite(startPositionSeconds) && startPositionSeconds > 0
           ? startPositionSeconds
@@ -129,6 +135,13 @@ export async function handleApiTranscodeSessionsPost(req, reply, { hlsSessionMan
             variantHeight: hlsSessionManager.variantHeightOf(session)
           }
         : {}),
+      // The heights this host will actually serve this file at, largest first
+      // — the ladder minus every rung it cannot produce faster than it is
+      // watched. The browser needs it whether or not a master exists: without
+      // it, it fell back to a ladder of its own invention and offered rungs the
+      // proxy had just refused, and picking one re-opened the session at a
+      // height measured at a third of realtime.
+      offeredHeights: hlsSessionManager.offeredHeights(session),
       // What this session's output will carry, stated rather than left to be
       // discovered. The browser checks what it actually got against this: a
       // track that never arrives is otherwise noticed only by its absence,

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

@@ -0,0 +1,45 @@
+/**
+ * @file GET /transcode/:sessionId/a/:trackIndex/:fileName — one file of an audio
+ * rendition.
+ *
+ * A rendition is one audio track of the file, encoded once and shared by every
+ * quality rung, published in the master playlist as `#EXT-X-MEDIA`. It is an
+ * ordinary session underneath, living one directory level below the base
+ * session so every relative name inside its playlist resolves to it unchanged —
+ * the same arrangement quality variants use.
+ *
+ * Unlike a variant, a rendition is fetched ALONGSIDE the picture rather than
+ * instead of it: both encoders run, one for the rung and one for the audio.
+ */
+
+import { serveSessionFile } from "../session-file/get.js";
+
+/**
+ * @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 handleTranscodeAudioFileGet(req, reply, { hlsSessionManager }) {
+  const baseSessionId = typeof req.params.sessionId === "string" ? req.params.sessionId : "";
+  const trackIndex = Number(req.params.trackIndex);
+  const fileName = typeof req.params.fileName === "string" ? req.params.fileName : "";
+
+  const resolved = await hlsSessionManager.resolveAudioRenditionFile(baseSessionId, trackIndex, fileName);
+  if (resolved.error) {
+    // Retryable, like every other not-ready answer on this path: a 500 for a
+    // rendition playlist would end the stream over something the next attempt
+    // may well get past.
+    reply.header("Retry-After", "1");
+    return reply.code(503).send({ error: `Could not prepare the audio rendition: ${resolved.error}` });
+  }
+  if (!resolved.sessionId) {
+    return reply.code(404).send({ error: "No such audio rendition for this transcode session." });
+  }
+
+  return serveSessionFile(req, reply, {
+    hlsSessionManager,
+    sessionId: resolved.sessionId,
+    fileName
+  });
+}

package/server.js

@@ -30,12 +30,13 @@ import { handleApiTranscodeSessionSeekPost } from "./routes/api/transcode-sessio
 import { handleStreamGet } from "./routes/stream/get.js";
 import { handleTranscodeSessionFileGet } from "./routes/transcode/session-file/get.js";
 import { handleTranscodeVariantFileGet } from "./routes/transcode/variant-file/get.js";
+import { handleTranscodeAudioFileGet } from "./routes/transcode/audio-file/get.js";
 import { handleTranscodeVariantWarmGet } from "./routes/transcode/variant-warm/get.js";
 import { createSourceRegistry } from "./store/source-registry.js";
 import { WorkerTorrentPool } from "./services/torrent-worker/pool-adapter.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 { detectVideoEncoder, benchmarkSoftwarePresets, benchmarkDecodeCost, detectTonemapSupport } from "./services/hwaccel.js";
 import { logger } from "./utils/logger.js";
 
 const __filename = fileURLToPath(import.meta.url);
@@ -68,6 +69,7 @@ function buildPortCandidates(startPort, maxAttempts = 51) {
  * @property {number}  [maxDiskBytes] - Global disk cap for torrent data (undefined = pool default).
  * @property {number}  [memoryBytes]  - Per-torrent budget for pieces held in memory (undefined = store default).
  * @property {string}  [segmentFormat] - HLS output container: "fmp4" (default) or "mpegts".
+ * @property {string}  [stateDir] - Where to keep what this host has measured about itself.
  */
 
 /**
@@ -76,7 +78,7 @@ function buildPortCandidates(startPort, maxAttempts = 51) {
  * @param {ProxyServerOptions} options
  * @returns {Promise<{ app: import("fastify").FastifyInstance, port: number }>}
  */
-export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin, maxDiskBytes, memoryBytes, segmentFormat }) {
+export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin, maxDiskBytes, memoryBytes, segmentFormat, stateDir }) {
   const app = Fastify({
     // No practical body-size limit — the proxy server is localhost-only and
     // receives torrent source payloads that may be arbitrarily large.
@@ -124,6 +126,18 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin,
   const softwarePresetBenchmark = videoEncoder?.kind === "software"
     ? await benchmarkSoftwarePresets({ ffmpegBin, logger })
     : null;
+  // A re-encode pays for decoding as well, and the preset benchmark measures
+  // only the encoder — which is how a rung this host runs at 0.39x came to be
+  // offered as if it cleared realtime 2.5× over (measured 2026-08-14). Solve
+  // the decode cost from the bundled calibration clips once at startup; every
+  // source is then priced from figures the probe already has.
+  // Only the software path can read it: the budget and the ladder both bail
+  // on a missing preset benchmark, and that is only produced for libx264. A
+  // host with a hardware encoder would pay three decodes at every start for a
+  // figure nothing would ever ask for.
+  const decodeCostModel = videoEncoder?.kind === "software"
+    ? await benchmarkDecodeCost({ 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.
@@ -137,8 +151,10 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin,
     localPort: selectedPort,
     videoEncoder,
     softwarePresetBenchmark,
+    decodeCostModel,
     tonemapSupported,
     segmentFormatId: segmentFormat,
+    stateDir,
     // 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) => {
@@ -158,7 +174,10 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin,
     // 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)
+    getCachedMediaInfo: (params) => playbackPlanner.getCachedMediaInfo(params),
+    // The file's audio tracks, for the master playlist's rendition group. Already
+    // probed for the browser's audio menu; read from there rather than probed again.
+    getCachedAudioTracks: (params) => playbackPlanner.getCachedAudioTracks(params)
   });
   const playbackPlanner = createPlaybackPlanner({
     ffmpegBin,
@@ -168,7 +187,11 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin,
     torrentPool,
     warmKeyframeIndex: (params) => hlsSessionManager.warmKeyframeIndex(params),
     expectedFirstSegmentMs: () => hlsSessionManager.expectedFirstSegmentMs(),
-    expectedSessionCreateMs: () => hlsSessionManager.expectedSessionCreateMs()
+    expectedSessionCreateMs: () => hlsSessionManager.expectedSessionCreateMs(),
+    // The quality menu is on screen from the moment a file is opened, so the
+    // heights this host can actually serve have to be answerable before any
+    // encoder exists — from the probe and the startup benchmarks alone.
+    predictOfferedHeights: (mediaInfo) => hlsSessionManager.predictOfferedHeights(mediaInfo)
   });
 
   app.get("/health", async (req, reply) => handleHealthGet(req, reply, { version }));
@@ -226,6 +249,9 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin,
   app.get("/transcode/:sessionId/v/:height/warm", async (req, reply) =>
     handleTranscodeVariantWarmGet(req, reply, { hlsSessionManager })
   );
+  app.get("/transcode/:sessionId/a/:trackIndex/:fileName", async (req, reply) =>
+    handleTranscodeAudioFileGet(req, reply, { hlsSessionManager })
+  );
   app.get("/transcode/:sessionId/v/:height/:fileName", async (req, reply) =>
     handleTranscodeVariantFileGet(req, reply, { hlsSessionManager })
   );

package/services/ffmpeg-banner.js

@@ -54,6 +54,48 @@ export function parseFfmpegStartTimeSeconds(stderrText) {
   return Number.isFinite(value) ? value : 0;
 }
 
+/**
+ * Parse the bitrate (kbit/s) that the decode cost is priced from: the VIDEO
+ * stream's own, falling back to the container's when the stream does not state
+ * one. Returns null when neither is present.
+ *
+ * The distinction is not cosmetic. The calibration clips carry video alone and
+ * are decoded with `-an`, so the fitted bitrate term describes VIDEO bits; the
+ * container figure adds every audio and subtitle track. A Russian release with
+ * two or three AC-3/DTS tracks carries 1-2 Mbit/s of audio, and on this host's
+ * own fit that inflates the predicted decode cost by 10-25 % — refusing rungs
+ * on the strength of audio the benchmark never decoded. And the term is not the
+ * weak one it was once described as: on the shipped clips an 11.7× bitrate
+ * change moved the cost 2.47×, and it accounts for about two thirds of the
+ * predicted cost of a high-bitrate 1080p source.
+ *
+ * @param {string} stderrText
+ * @returns {number | null}
+ */
+export function parseFfmpegBitrateKbps(stderrText) {
+  if (typeof stderrText !== "string" || stderrText.length === 0) {
+    return null;
+  }
+  // `Stream #0:0 … Video: h264 … 11375 kb/s, 24 fps` — the stream's own rate,
+  // stated per stream and therefore free of the other tracks. Only the INPUT
+  // section is read: everything from "Stream mapping:" onwards describes what
+  // ffmpeg is about to produce, and that line carries a bitrate of its own.
+  const inputSection = stderrText.split(/^Stream mapping:/m)[0];
+  const perStream = inputSection.match(/Stream\s+#[^\n]*?Video:[^\n]*?,\s*(\d+)\s*kb\/s/i);
+  if (perStream) {
+    const streamValue = Number(perStream[1]);
+    if (Number.isFinite(streamValue) && streamValue > 0) {
+      return streamValue;
+    }
+  }
+  const match = stderrText.match(/Duration:[^\n]*?bitrate:\s*(\d+)\s*kb\/s/i);
+  if (!match) {
+    return null;
+  }
+  const value = Number(match[1]);
+  return Number.isFinite(value) && value > 0 ? value : null;
+}
+
 /**
  * Parse the source video resolution from ffmpeg's stderr (the "Stream … Video:
  * … WxH" line). Returns `{ width: null, height: null }` when absent.