@torrent-tv/proxy 2.94.3 → 2.95.0

package/services/encode/hwaccel.js

@@ -37,6 +37,7 @@ import {
 
 import { keyFrameArgs, TRANSCODE_FPS } from "./args.js";
 import { throughputAt } from "./throughput.js";
+import { freeShareDuring, sampleHost } from "./host-load.js";
 import { LADDER_HEIGHTS } from "./output/ladder.js";
 // The five kinds, one class each. Detection and benchmarking stay in this file;
 // how a kind is driven belongs to the kind.
@@ -481,6 +482,28 @@ const CALIBRATION_SETS = {
     "cal-hevc10-1080-lo.mp4",
     "cal-hevc10-480-hi.mp4",
     "cal-hevc10-480-lo.mp4"
+  ],
+  // MPEG-4 Part 2 is what XviD and DivX releases carry — about 8 % of the
+  // releases surveyed on 2026-07-10 — and it was priced as H.264 until these
+  // (torrent-tv/meta#3). MPEG-2 is what DVD rips carry, AV1 a growing share of
+  // recent releases. VC-1 has no set: ffmpeg has no VC-1 encoder to make one.
+  mpeg4: [
+    "cal-mpeg4-1080-hi.mp4",
+    "cal-mpeg4-1080-lo.mp4",
+    "cal-mpeg4-480-hi.mp4",
+    "cal-mpeg4-480-lo.mp4"
+  ],
+  mpeg2: [
+    "cal-mpeg2-1080-hi.mp4",
+    "cal-mpeg2-1080-lo.mp4",
+    "cal-mpeg2-480-hi.mp4",
+    "cal-mpeg2-480-lo.mp4"
+  ],
+  av1: [
+    "cal-av1-1080-hi.mp4",
+    "cal-av1-1080-lo.mp4",
+    "cal-av1-480-hi.mp4",
+    "cal-av1-480-lo.mp4"
   ]
 };
 export const CALIBRATION_REFERENCE_CLIP = "cal-h264-1080-hi.mp4";
@@ -675,6 +698,9 @@ export async function benchmarkDecodeCost({ ffmpegBin, logger, clipsDir = CALIBR
   log.info(
     `hwaccel: decode cost measured for ${Object.keys(families).join(", ")}` +
       (missing.length > 0 ? `; ${missing.join(" and ")} priced as H.264` : "") +
+      // Said, because it is a fact about every film in those codecs: VC-1 has
+      // no set (ffmpeg cannot encode one), and neither do DivX 3 or 10-bit AV1.
+      "; every other codec is priced as H.264" +
       ` (in ${((Date.now() - startedAllAt) / 1000).toFixed(1)}s)`
   );
   return { families, ...families.h264 };
@@ -700,7 +726,7 @@ async function fitOneFamily({ ffmpegBin, log, clipsDir, family, clips }) {
   );
   if (!streams) {
     log.warn(
-      `hwaccel: ${family} cannot be lifted out of its container — no Annex-B filter is mapped for it, ` +
+      `hwaccel: ${family} cannot be lifted out of its container — no elementary-stream form is mapped for it, ` +
         `so its clips were never measured`
     );
     return null;
@@ -715,7 +741,13 @@ async function fitOneFamily({ ffmpegBin, log, clipsDir, family, clips }) {
       );
       return null;
     }
-    const cost = 1 / measured.speed;
+    // On a quiet-machine basis, like every other startup figure the offer
+    // multiplies by the share free at the time of the question. Measured on the
+    // addon host on 2026-10-07: one clip decoded at 10.74x, 13.29x and 13.24x
+    // with other work taking 35 %, 19 % and 19 % of the machine, and at 16.4x,
+    // 16.3x and 16.3x once that share was divided out (torrent-tv/meta#3).
+    const quietSpeed = Number.isFinite(measured.freeShare) ? measured.speed / measured.freeShare : measured.speed;
+    const cost = 1 / quietSpeed;
     samples.push({
       megapixelsPerSecond: measured.megapixelsPerSecond,
       megabitsPerSecond: measured.megabitsPerSecond,
@@ -723,8 +755,11 @@ async function fitOneFamily({ ffmpegBin, log, clipsDir, family, clips }) {
     });
     log.info(
       `hwaccel: decode "${clip}" ${measured.megapixelsPerSecond.toFixed(1)} Mpx/s ` +
-        `${measured.megabitsPerSecond.toFixed(2)} Mbit/s -> ${measured.speed.toFixed(1)}x ` +
-        `(cost ${cost.toFixed(4)} s/s, over ${measured.windowSec.toFixed(1)}s of decoding)`
+        `${measured.megabitsPerSecond.toFixed(2)} Mbit/s -> ${quietSpeed.toFixed(1)}x ` +
+        (Number.isFinite(measured.freeShare)
+          ? `(read ${measured.speed.toFixed(1)}x with other work taking ${Math.round((1 - measured.freeShare) * 100)}% of the machine; `
+          : "(the machine's load was not readable, so as read; ") +
+        `cost ${cost.toFixed(4)} s/s, over ${measured.windowSec.toFixed(1)}s of decoding)`
     );
   }
   const fitted = fitDecodeCost(samples);
@@ -746,18 +781,27 @@ async function fitOneFamily({ ffmpegBin, log, clipsDir, family, clips }) {
 }
 
 /**
- * The bitstream filter and demuxer that turn a clip's video track into a
+ * The bitstream filter, muxer and demuxer that turn a clip's video track into a
  * continuous elementary stream, by codec family.
  *
- * H.264 and HEVC in MP4 keep their parameter sets in the container's `avcC` /
- * `hvcC` and their access units length-prefixed; Annex-B carries them inline,
- * with start codes, which is what makes plain byte concatenation a valid
- * stream. That is the property this whole measurement rests on.
+ * The property this whole measurement rests on is that plain byte
+ * concatenation of the stream is a valid stream, so every header a decoder
+ * needs has to travel inside it. H.264 and HEVC in MP4 keep their parameter
+ * sets in the container's `avcC` / `hvcC` and their access units
+ * length-prefixed; Annex-B carries them inline, with start codes. MPEG-4 Part 2
+ * and MPEG-2 in MP4 keep their headers in the decoder configuration;
+ * `dump_extra` puts them back in front of every keyframe. AV1 needs no filter:
+ * the low-overhead OBU form carries the sequence header in every keyframe's
+ * temporal unit. MPEG-2's raw stream is written as `mpeg2video` and read as
+ * `mpegvideo`, which is why the two names are kept apart.
  */
-const ANNEX_B_BY_FAMILY = {
-  h264: { filter: "h264_mp4toannexb", demuxer: "h264" },
-  hevc: { filter: "hevc_mp4toannexb", demuxer: "hevc" },
-  hevc10: { filter: "hevc_mp4toannexb", demuxer: "hevc" }
+const ELEMENTARY_BY_FAMILY = {
+  h264: { filter: "h264_mp4toannexb", muxer: "h264", demuxer: "h264" },
+  hevc: { filter: "hevc_mp4toannexb", muxer: "hevc", demuxer: "hevc" },
+  hevc10: { filter: "hevc_mp4toannexb", muxer: "hevc", demuxer: "hevc" },
+  mpeg4: { filter: "dump_extra=freq=keyframe", muxer: "m4v", demuxer: "m4v" },
+  mpeg2: { filter: "dump_extra=freq=keyframe", muxer: "mpeg2video", demuxer: "mpegvideo" },
+  av1: { filter: null, muxer: "obu", demuxer: "obu" }
 };
 
 /**
@@ -784,8 +828,8 @@ function lastErrorLine(stderr) {
 const EXTRACT_TIMEOUT_MS = 20_000;
 
 /**
- * Lift a whole family's clips out of their containers, as Annex-B elementary
- * streams, in ONE ffmpeg run.
+ * Lift a whole family's clips out of their containers, as elementary streams,
+ * in ONE ffmpeg run.
  *
  * No re-encoding — the frames are copied — so the work itself is trivial and
  * the cost is almost entirely the process. Doing one process per clip added
@@ -809,24 +853,22 @@ const EXTRACT_TIMEOUT_MS = 20_000;
  *   One entry per clip, in order; null when the family cannot be lifted at all.
  */
 async function extractFamilyStreams(ffmpegBin, clipPaths, family) {
-  const shape = ANNEX_B_BY_FAMILY[family];
+  const shape = ELEMENTARY_BY_FAMILY[family];
   // A family with no mapping is a hard failure, not a silent fallback to
-  // H.264's filter. AV1 has no Annex-B form at all (its packaging is OBU), and
-  // MPEG-2 and VC-1 have no `*_mp4toannexb` filter — so the three families the
-  // roadmap plans next cannot come through here, and finding that out as
-  // "the clip failed" would send the reader after the clip.
+  // H.264's filter: finding that out as "the clip failed" would send the
+  // reader after the clip.
   if (!shape) {
     return null;
   }
   const workDir = await mkdtemp(path.join(os.tmpdir(), "ttv-calibration-"));
-  const outputs = clipPaths.map((_, index) => path.join(workDir, `stream-${index}.${shape.demuxer}`));
+  const outputs = clipPaths.map((_, index) => path.join(workDir, `stream-${index}.${shape.muxer}`));
   /** @type {string[]} */
   const args = ["-hide_banner", "-loglevel", "info", "-nostats", "-y"];
   for (const clipPath of clipPaths) {
     args.push("-i", clipPath);
   }
   for (const [index, output] of outputs.entries()) {
-    args.push("-map", `${index}:v:0`, "-c:v", "copy", "-bsf:v", shape.filter, "-f", shape.demuxer, output);
+    args.push("-map", `${index}:v:0`, "-c:v", "copy", ...(shape.filter ? ["-bsf:v", shape.filter] : []), "-f", shape.muxer, output);
   }
   const stderr = await runCapturingStderr(ffmpegBin, args, EXTRACT_TIMEOUT_MS);
   try {
@@ -1032,12 +1074,20 @@ function decodePipedStream(ffmpegBin, stream, log = { info: () => {}, warn: () =
     // reads the same in both cases, only the byte count is kept, for the
     // MB/s figure below — a number to read, not a boolean to trust.
     let bytesWritten = 0;
-    const finish = () => {
+    /** The machine at the first kept report, where the window starts. @type {Promise<object | null> | null} */
+    let hostBefore = null;
+    const finish = async () => {
       if (settled) {
         return;
       }
       settled = true;
       clearTimeout(timer);
+      // The machine at the end of the window, read while the decoder still runs
+      // so both readings bound the interval the speed is read over.
+      const hostAfter = hostBefore !== null && child?.pid && child.exitCode === null
+        ? await sampleHost(child.pid).catch(() => null)
+        : null;
+      const freeShare = freeShareDuring(hostBefore === null ? null : await hostBefore, hostAfter);
       try {
         child?.stdin?.destroy();
       } catch {
@@ -1084,13 +1134,18 @@ function decodePipedStream(ffmpegBin, stream, log = { info: () => {}, warn: () =
       );
       resolve({
         speed,
+        // The share of the machine other work left the decoder over the window,
+        // or null where it could not be read. A caller pricing decoding on a
+        // quiet-machine basis divides by it; a caller measuring what company
+        // costs must not, because there the company IS the other work.
+        freeShare,
         windowSec,
         megapixelsPerSecond: stream.megapixelsPerSecond,
         megabitsPerSecond: stream.megabitsPerSecond,
         pipeThroughputMBps: achievedMBps
       });
     };
-    const timer = setTimeout(finish, DECODE_WINDOW_MAX_MS);
+    const timer = setTimeout(() => void finish(), DECODE_WINDOW_MAX_MS);
     try {
       child = spawn(ffmpegBin, args, { stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
     } catch (error) {
@@ -1128,12 +1183,16 @@ function decodePipedStream(ffmpegBin, stream, log = { info: () => {}, warn: () =
           const microseconds = Number(line.slice("out_time_ms=".length));
           if (Number.isFinite(microseconds)) {
             samples.push({ wallSec: (Date.now() - startedAt) / 1000, outSec: microseconds / 1e6, bytesWritten });
+            if (samples.length === 2 && child?.pid) {
+              // The second report, because the window starts there (below).
+              hostBefore = sampleHost(child.pid).catch(() => null);
+            }
           }
         }
         newline = stdout.indexOf("\n");
       }
       if (samples.length >= 2 && samples[samples.length - 1].wallSec - samples[1].wallSec >= DECODE_WINDOW_MIN_SEC) {
-        finish();
+        void finish();
       }
     });
     child.on("error", (error) => {
@@ -1154,7 +1213,7 @@ function decodePipedStream(ffmpegBin, stream, log = { info: () => {}, warn: () =
       }
       resolve({ error: error instanceof Error ? error.message : String(error) });
     });
-    child.on("close", finish);
+    child.on("close", () => void finish());
     feed();
   });
 }
@@ -1342,99 +1401,6 @@ function barFor(cost) {
   return isDecodePriced(cost) ? measured : Math.max(UNPRICED_DECODE_BAR, measured);
 }
 
-/**
- * Benchmark software libx264 presets on this host. Encodes a short synthetic
- * clip at a fixed reference resolution with each preset and measures encoder
- * throughput in pixels/second. The session manager uses this to pick, per
- * stream, the highest-quality preset that still encodes the actual
- * (source-capped) resolution faster than realtime.
- *
- * Runs once at startup; bounded by a per-encode timeout. Presets that fail are
- * omitted from the result.
- *
- * @param {{ ffmpegBin: string, logger?: { info: (m: string) => void, warn: (m: string) => void } }} options
- * @returns {Promise<Array<{ preset: string, pixelsPerSec: number }>>} Ordered slowest→fastest.
- */
-export async function benchmarkSoftwarePresets({ ffmpegBin, logger, encoder = null }) {
-  const log = logger ?? { info: () => {}, warn: () => {} };
-
-  // REAL footage, decoded ONCE into raw frames, and the presets are then timed
-  // on those frames.
-  //
-  // Two reasons, both measured. The pattern this replaced (`testsrc2`) has flat
-  // areas and no grain and encodes 1.23x cheaper than film on the same machine
-  // and preset — an error that always points at offering a rung the host cannot
-  // hold. And feeding a compressed clip to each preset instead would put
-  // decoding and scaling inside the measurement: subtracting them afterwards
-  // compares a wall clock that includes process startup against a decode figure
-  // measured to exclude it, while inside one ffmpeg the two halves overlap. On
-  // the fastest preset — the one every ladder decision reads as the ceiling —
-  // that subtraction is most of the number being measured, so a small error in
-  // it becomes a large error in the answer.
-  //
-  // Raw frames remove all of it: no decoder, no scaler, nothing to subtract,
-  // and no dependence on the decode model. The cost is 25 MB of memory in a
-  // pipe for a few seconds.
-  const rawFramesPath = await decodeToRawFrames(ffmpegBin, log);
-  if (rawFramesPath === null) {
-    // Said once more, in the words that matter to whoever reads the log next:
-    // with no benchmark, `#sustainableHeights` filters nothing and every rung
-    // is offered, which is the failure of 2026-08-14 in full.
-    log.warn("hwaccel: the quality ladder is UNFILTERED on this host — nothing measured the encoder");
-    return [];
-  }
-  /** @type {Array<{ preset: string, pixelsPerSec: number }>} */
-  const results = [];
-  try {
-    // THE CHOSEN ENCODER'S OWN LADDER, whatever kind it is. NVENC walks p1…p7,
-    // QSV veryfast…veryslow, VAAPI its quality levels. A kind with no ladder is
-    // measured once, which is still a reading where there was none at all.
-    const ladder = encoder?.speedLadder;
-    const rungs = Array.isArray(ladder?.values) && ladder.values.length > 0 ? ladder.values : [null];
-    for (const rung of rungs) {
-      const speed = await measureEncodeSlope(ffmpegBin, encoder, rung, rawFramesPath);
-      if (speed === null) {
-        log.warn(`hwaccel: the benchmark of "${rung ?? encoder?.name}" produced no usable reading; skipping`);
-        continue;
-      }
-      const pixelsPerSec = BENCHMARK_REF_W * BENCHMARK_REF_H * TRANSCODE_FPS * speed;
-      results.push({ preset: rung ?? encoder?.name, pixelsPerSec });
-      log.info(
-        `hwaccel: ${encoder?.name} "${rung ?? "as it comes"}" ~= ${(pixelsPerSec / 1e6).toFixed(1)} Mpx/s ` +
-          `(${speed.toFixed(2)}x @ ${BENCHMARK_REF_W}x${BENCHMARK_REF_H}, real footage)`
-      );
-    }
-  } finally {
-    // The encoder was killed a moment ago and on Windows the handle outlives
-    // the signal, so removal is retried and its failure is not worth a session:
-    // this is a temp directory the operating system will clear anyway.
-    try {
-      rmSync(path.dirname(rawFramesPath), { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });
-    } catch (error) {
-      log.warn(`hwaccel: could not remove the benchmark's raw frames: ${error instanceof Error ? error.message : String(error)}`);
-    }
-  }
-  return results;
-}
-
-/**
- * How fast one preset encodes, from ffmpeg's own reports of how much video it
- * has written — not from the clock around the process.
- *
- * Timing whole runs measures the run STARTING. Measured 2026-08-15 on a desktop
- * that spawns ffmpeg in ~0.4 s: three seconds of raw frames encoded that way
- * put `fast` and `ultrafast` within 1.24x of each other, when libx264's own
- * presets differ by several times — the constant had swallowed the difference.
- * The slope between two progress reports contains no part of the startup.
- *
- * The frames are written repeatedly so there is runway to measure over,
- * whatever the preset's speed.
- *
- * @param {string} ffmpegBin
- * @param {string} preset
- * @param {string} rawFramesPath
- * @returns {Promise<number | null>} Video seconds encoded per second of clock.
- */
 /**
  * Video seconds produced per second of clock, from ffmpeg's own reports.
  *
@@ -1465,7 +1431,37 @@ export function slopeOf(samples, minimumWindowSec = ENCODE_BENCHMARK_WINDOW_SEC)
   return slope <= ENCODE_BENCHMARK_MAX_PLAUSIBLE_SPEED ? slope : null;
 }
 
+/**
+ * How fast one mode encodes, from ffmpeg's own reports of how much video it
+ * has written — not from the clock around the process.
+ *
+ * Timing whole runs measures the run STARTING. Measured 2026-08-15 on a desktop
+ * that spawns ffmpeg in ~0.4 s: three seconds of raw frames encoded that way
+ * put `fast` and `ultrafast` within 1.24x of each other, when libx264's own
+ * presets differ by several times — the constant had swallowed the difference.
+ * The slope between two progress reports contains no part of the startup.
+ *
+ * The frames are written repeatedly so there is runway to measure over,
+ * whatever the preset's speed.
+ *
+ * THE MACHINE IS NOT QUIET while this runs, and the reading is returned as the
+ * speed this machine gives a software encoder with nothing else running
+ * (torrent-tv/meta#3).
+ *
+ * The figure is used on a quiet-machine basis: the offer later multiplies it by
+ * the share of the machine free at the time of the question
+ * (`available-share.js`). So the share other work took DURING the reading is
+ * divided back out. Measured on the addon host on 2026-10-07: other work took
+ * 17-53 % of the machine during readings, the same mode read 2.08x-3.10x, and
+ * divided by the share left it read 3.60x-3.79x.
+ *
+ * A hardware encoder is limited by its device and not by the cores, so its
+ * reading is kept as read.
+ *
+ * @returns {Promise<{ speed: number, measuredSpeed: number, freeShare: number | null } | null>}
+ */
 export function measureEncodeSlope(ffmpegBin, encoder, rung, rawFramesPath, frame = { width: BENCHMARK_REF_W, height: BENCHMARK_REF_H }) {
+  const cpuBound = encoder?.kind === "software";
   return new Promise((resolve) => {
     const args = [
       "-hide_banner", "-loglevel", "error", "-nostats",
@@ -1491,18 +1487,32 @@ export function measureEncodeSlope(ffmpegBin, encoder, rung, rawFramesPath, fram
     let buffered = "";
     let child;
     const startedAt = Date.now();
+    /** @type {Promise<object | null> | null} */
+    let hostBefore = null;
     const finish = (value) => {
       if (settled) {
         return;
       }
       settled = true;
       clearTimeout(timer);
-      try {
-        child?.kill("SIGKILL");
-      } catch {
-        // already gone
-      }
-      resolve(value);
+      // The second reading of the machine is taken while the encoder is still
+      // running, so the interval is the one the slope was read over.
+      const hostAfter = value !== null && cpuBound && hostBefore !== null && child?.pid
+        ? sampleHost(child.pid).catch(() => null)
+        : Promise.resolve(null);
+      void Promise.all([hostBefore ?? Promise.resolve(null), hostAfter]).then(([before, after]) => {
+        try {
+          child?.kill("SIGKILL");
+        } catch {
+          // already gone
+        }
+        if (value === null) {
+          resolve(null);
+          return;
+        }
+        const freeShare = freeShareDuring(before, after);
+        resolve({ speed: freeShare === null ? value : value / freeShare, measuredSpeed: value, freeShare });
+      });
     };
     const timer = setTimeout(() => finish(null), ENCODE_BENCHMARK_TIMEOUT_MS);
     try {
@@ -1529,6 +1539,10 @@ export function measureEncodeSlope(ffmpegBin, encoder, rung, rawFramesPath, fram
           // be taken for a position nine trillion seconds before the start.
           if (Number.isFinite(outSec) && outSec >= 0) {
             samples.push({ wallSec: (Date.now() - startedAt) / 1000, outSec });
+            if (samples.length === 1 && cpuBound && child?.pid) {
+              // At the first kept report, which is where the slope starts.
+              hostBefore = sampleHost(child.pid).catch(() => null);
+            }
           }
         }
         newline = buffered.indexOf(NEWLINE);

package/services/encode/quality/ColdStarts.js

@@ -0,0 +1,78 @@
+/**
+ * @file How long each output took from the request that created it to its
+ * first segment being served — measured once per output, said in the log, and
+ * kept nowhere else.
+ *
+ * This is what is left of `HostTimings` (torrent-tv/meta#3). That class also
+ * kept the median of recent first-segment and creation times in
+ * `host-timings.json`, so a restarted proxy would not quote an assumed figure.
+ * It was to go once the time could be computed instead of remembered, and it
+ * can: a fresh output's first piece takes what this host was measured to need
+ * for a first output (`RunCosts`) or one piece at this output's own measured
+ * speed, whichever is longer. The remembered median could never say that —
+ * measured on the addon host on 2026-10-06 it ran from 0.4 to 184 times the
+ * startup figure, because most of it was the swarm.
+ */
+
+export class ColdStarts {
+  /**
+   * Output → when the request that created it arrived, until its first segment
+   * is served. Taken out on that first segment, so each output is measured once
+   * and an output nobody created in this process (adopted at startup) is never
+   * measured at all.
+   *
+   * @type {WeakMap<object, number>}
+   */
+  #createdAt = new WeakMap();
+
+  /**
+   * An output was created by a request that arrived at `at`.
+   *
+   * @param {object} output
+   * @param {number} at
+   * @returns {void}
+   */
+  noteOutputCreated(output, at) {
+    if (Number.isFinite(at) && at > 0) {
+      this.#createdAt.set(output, at);
+    }
+  }
+
+  /**
+   * A segment of this output has just been served. The first one closes the
+   * measurement; every later one is nothing.
+   *
+   * @param {object} output
+   * @param {number} [now]
+   * @returns {number | null} The cold-start latency when this was the first.
+   */
+  noteSegmentServed(output, now = Date.now()) {
+    const at = this.#createdAt.get(output);
+    if (at === undefined) {
+      return null;
+    }
+    this.#createdAt.delete(output);
+    return now - at;
+  }
+}
+
+/**
+ * How long a fresh output of this mode takes to have its first piece on this
+ * host, in seconds: the measured wait for a first output, or one piece at the
+ * output's own speed, whichever is longer.
+ *
+ * The same arithmetic the encode plan prices a fresh encoder with
+ * (`EncodePlan.js`): the measured wait already contains one piece, so the spawn
+ * overhead is the wait less one piece, and overhead plus piece is the larger of
+ * the two. Null where the speed is not known.
+ *
+ * @param {{ firstByteWaitSec: number, segmentDurationSec: number, speed: number }} params
+ * @returns {number | null}
+ */
+export function secondsToFirstPiece({ firstByteWaitSec, segmentDurationSec, speed }) {
+  if (!(speed > 0) || !(segmentDurationSec > 0)) {
+    return null;
+  }
+  const pieceSec = segmentDurationSec / speed;
+  return Math.max(Number.isFinite(firstByteWaitSec) ? firstByteWaitSec : 0, pieceSec);
+}