@torrent-tv/proxy 2.86.0 → 2.87.1

package/services/encode/quality/link-budget.js

@@ -0,0 +1,254 @@
+/**
+ * @file What a viewer's link can carry, and what an output asks of it.
+ *
+ * PURE FUNCTIONS: the viewer's connection enters as a NUMBER — how many megabits
+ * the last report showed — and never as a reference to a viewer. Nothing here
+ * holds anybody, reads anything or can be asked at the wrong moment.
+ *
+ * WHAT A LINK CARRIES IS A LOAD, NOT A PICTURE (roadmap item 97, step 11). The
+ * viewer receives the picture AND the soundtrack they chose — inside the
+ * picture's own stream, or as a separate one — so both are added before the
+ * link is asked. And each part says how much its figure can be trusted:
+ *
+ * 1. `known` — a bound the encoder is held to: a re-encode's `maxrate`, or the
+ *    constant rate a re-encoded soundtrack is produced at;
+ * 2. `estimated` — a figure the FILE states: a copied picture's average rate,
+ *    a copied soundtrack's stated rate. An average is not a bound, so a load
+ *    built on it is admitted only by estimate and is never confirmed;
+ * 3. `unknown` — no figure at all: a hardware encoder given no limit, a copied
+ *    soundtrack whose rate nothing states.
+ *
+ * A load is as trustworthy as its least trustworthy part.
+ */
+
+import { maxrateKbpsFor, nominalKbpsFor } from "../args.js";
+
+/**
+ * How much of a measured link may be spent on the stream.
+ *
+ * The rest is what the link does when it is not being perfect: transport
+ * framing, retransmission, the other tabs, the moment somebody else in the
+ * house starts something. A load sized to the whole reading stalls on the
+ * first of those.
+ *
+ * Chosen, not measured, and written as a constant rather than dressed up as a
+ * measurement. What would replace it is a reading of the transport's own
+ * overhead and of how far a link's throughput varies over a session, which
+ * nothing takes.
+ */
+export const LINK_SAFETY = 0.8;
+
+/** How far a figure in a load can be trusted. */
+export const PEAK_CLASS = Object.freeze({
+  KNOWN: "known",
+  ESTIMATED: "estimated",
+  UNKNOWN: "unknown"
+});
+
+/** What a link was found to do with a load. */
+export const LINK_VERDICT = Object.freeze({
+  FITS: "fits",
+  ESTIMATED_TO_FIT: "estimated to fit",
+  DOES_NOT_FIT: "does not fit",
+  NO_SAFE_BOUND: "no safe bound",
+  NO_MEASUREMENT: "no measurement"
+});
+
+const CLASS_ORDER = [PEAK_CLASS.KNOWN, PEAK_CLASS.ESTIMATED, PEAK_CLASS.UNKNOWN];
+
+/**
+ * @typedef {{ mbps: number | null, peakClass: string }} LoadPart
+ * @typedef {{ video: LoadPart | null, audio: LoadPart | null, totalMbps: number | null, peakClass: string }} Load
+ */
+
+/**
+ * @param {number | null} mbps
+ * @param {string} peakClass
+ * @returns {LoadPart}
+ */
+function part(mbps, peakClass) {
+  const figure = Number.isFinite(mbps) && mbps > 0 ? mbps : null;
+  // A figure that is missing is no figure, whatever the part claimed to be.
+  return { mbps: figure, peakClass: figure === null ? PEAK_CLASS.UNKNOWN : peakClass };
+}
+
+/**
+ * The picture part of a load, read from an output's identity.
+ *
+ * An encoder given no limit states no bound, and its part is `unknown` — unless
+ * this host has seen outputs of exactly this mode carry a peak (roadmap item
+ * 97, step 14), and then that peak is its figure, as an ESTIMATE: it is what
+ * was seen, not a bound anything holds the encoder to.
+ *
+ * @param {import("../output/OutputSpec.js").OutputSpec} spec
+ * @param {number | null} sourceMbps - The average rate the source file states.
+ * @param {number | null} [observedPeakMbps] - The largest peak outputs of this
+ *   mode were seen carrying on this configuration, or null.
+ * @returns {LoadPart | null} Null for an output that carries no picture.
+ */
+export function videoLoadOfSpec(spec, sourceMbps, observedPeakMbps = null) {
+  if (!spec?.video) {
+    return null;
+  }
+  const encode = spec.video.encode;
+  if (!encode) {
+    return part(sourceMbps, PEAK_CLASS.ESTIMATED);
+  }
+  const rateControl = encode.rateControl;
+  if (rateControl) {
+    return part(rateControl.maxrateKbps / 1000, PEAK_CLASS.KNOWN);
+  }
+  return Number.isFinite(observedPeakMbps) && observedPeakMbps > 0
+    ? part(observedPeakMbps, PEAK_CLASS.ESTIMATED)
+    : part(null, PEAK_CLASS.UNKNOWN);
+}
+
+/**
+ * The picture part of a load for a height nothing has produced yet, the way
+ * it WOULD be produced here: at the nominal limit on the software encoder,
+ * with no limit on a hardware one, and as the source's own stream when the
+ * picture is copied at the source's height.
+ *
+ * The nominal limit is the one of the FRAME the height would be encoded at,
+ * chosen by its area (`nominalKbpsFor`) — the same row the output is then
+ * opened in, so the offer and the output cannot price one step differently.
+ *
+ * @param {{ sourceHeight: number, copiesAtSource: boolean, sourceMbps: number | null, encoderKind: string }} picture
+ * @param {{ width: number, height: number }} frame - The frame this height is
+ *   encoded at for this source.
+ * @returns {LoadPart}
+ */
+export function videoLoadForFrame(picture, frame) {
+  const sourceHeight = Math.round(Number(picture?.sourceHeight) || 0);
+  if (picture?.copiesAtSource === true && frame.height === sourceHeight) {
+    return part(picture?.sourceMbps ?? null, PEAK_CLASS.ESTIMATED);
+  }
+  if (picture?.encoderKind !== "software") {
+    return part(null, PEAK_CLASS.UNKNOWN);
+  }
+  return part(maxrateKbpsFor(nominalKbpsFor(frame)) / 1000, PEAK_CLASS.KNOWN);
+}
+
+/**
+ * The picture part of a load for a software encode at a nominal limit nothing
+ * has produced yet. The bound is the one `softwareRateControlFor` would give
+ * it, so an output opened at that limit carries exactly this load.
+ *
+ * @param {number} nominalKbps
+ * @returns {LoadPart}
+ */
+export function videoLoadOfLimit(nominalKbps) {
+  return part(maxrateKbpsFor(nominalKbps) / 1000, PEAK_CLASS.KNOWN);
+}
+
+/**
+ * The soundtrack part of a load: the track THIS viewer chose.
+ *
+ * @param {{ transcode: boolean, bitrateKbps: number | null } | null} track -
+ *   Null when the viewer receives no sound from this output or beside it.
+ * @param {number} transcodeKbps - What a re-encoded track is produced at.
+ * @returns {LoadPart | null}
+ */
+export function audioLoadOf(track, transcodeKbps) {
+  if (!track) {
+    return null;
+  }
+  if (track.transcode === true) {
+    return part(transcodeKbps / 1000, PEAK_CLASS.KNOWN);
+  }
+  return part((Number(track.bitrateKbps) || 0) / 1000, PEAK_CLASS.ESTIMATED);
+}
+
+/**
+ * The whole load: the parts added, and the class of the least trustworthy.
+ *
+ * @param {LoadPart | null} video
+ * @param {LoadPart | null} audio
+ * @returns {Load}
+ */
+export function loadOf(video, audio) {
+  const parts = [video, audio].filter(Boolean);
+  const peakClass = parts.reduce(
+    (worst, one) => (CLASS_ORDER.indexOf(one.peakClass) > CLASS_ORDER.indexOf(worst) ? one.peakClass : worst),
+    PEAK_CLASS.KNOWN
+  );
+  const totalMbps = peakClass === PEAK_CLASS.UNKNOWN
+    ? null
+    : parts.reduce((sum, one) => sum + one.mbps, 0);
+  return { video, audio, totalMbps, peakClass };
+}
+
+/**
+ * What a link that measured `linkMbps` does with a load.
+ *
+ * 1. nothing measured the link — every class is admitted, since the link gave
+ *    no ground to refuse, and nothing is confirmed;
+ * 2. an `unknown` load against a measured link — `no safe bound`, refused:
+ *    there is no number to compare;
+ * 3. otherwise the load is compared with the usable share of the link: a
+ *    `known` load that passes FITS and is confirmed, an `estimated` one that
+ *    passes is admitted by estimate and is NOT confirmed.
+ *
+ * @param {number | null} linkMbps
+ * @param {Load} load
+ * @returns {{ verdict: string, admitted: boolean, confirmed: boolean, linkMbps: number | null, load: Load }}
+ */
+export function linkCouldCarry(linkMbps, load) {
+  const measured = Number.isFinite(linkMbps) && linkMbps > 0;
+  const answer = (verdict, admitted, confirmed) => ({
+    verdict,
+    admitted,
+    confirmed,
+    linkMbps: measured ? linkMbps : null,
+    load
+  });
+  if (!measured) {
+    return answer(LINK_VERDICT.NO_MEASUREMENT, true, false);
+  }
+  if (load.peakClass === PEAK_CLASS.UNKNOWN) {
+    return answer(LINK_VERDICT.NO_SAFE_BOUND, false, false);
+  }
+  if (linkMbps * LINK_SAFETY < load.totalMbps) {
+    return answer(LINK_VERDICT.DOES_NOT_FIT, false, false);
+  }
+  return load.peakClass === PEAK_CLASS.KNOWN
+    ? answer(LINK_VERDICT.FITS, true, true)
+    : answer(LINK_VERDICT.ESTIMATED_TO_FIT, true, false);
+}
+
+/**
+ * How strongly an answer is admitted, for ordering: a load whose figure is a
+ * bound before one whose figure is an average, and both before one with no
+ * figure (which is only ever admitted with nothing measured). Zero for a
+ * refusal.
+ *
+ * @param {{ admitted: boolean, load: Load }} answer
+ * @returns {number}
+ */
+export function admissionRank(answer) {
+  if (!answer.admitted) {
+    return 0;
+  }
+  return 3 - CLASS_ORDER.indexOf(answer.load.peakClass);
+}
+
+/**
+ * The figures behind an answer, as plain values a log line or a report can
+ * carry.
+ *
+ * @param {{ verdict: string, linkMbps: number | null, load: Load }} answer
+ * @returns {object}
+ */
+export function linkAnswerFigures(answer) {
+  return {
+    verdict: answer.verdict,
+    linkMbps: answer.linkMbps,
+    linkSafety: LINK_SAFETY,
+    videoMbps: answer.load.video?.mbps ?? null,
+    videoClass: answer.load.video?.peakClass ?? null,
+    audioMbps: answer.load.audio?.mbps ?? null,
+    audioClass: answer.load.audio?.peakClass ?? null,
+    totalMbps: answer.load.totalMbps,
+    peakClass: answer.load.peakClass
+  };
+}

package/services/encode/quality/output-format.js

@@ -0,0 +1,266 @@
+/**
+ * @file The format an output produces, decided before it is named — because
+ * the name IS the format (decided with the user 2026-09-16).
+ *
+ * A copy is the source's own picture. A re-encode is which encoder, the size,
+ * the frame rate, the speed setting, whether HDR is tone mapped, and the rate
+ * control:
+ *
+ * 1. a size produced exactly — every rung of a master — is the box asked for,
+ *    fitted to the source, and only its speed setting is chosen;
+ * 2. a size left to the budget is the highest rung of the viewer's own ladder
+ *    this machine holds, with the speed setting for that rung;
+ * 3. on a hardware encoder, or with no startup measurement, there is no ladder
+ *    to choose from and the box asked for is produced.
+ *
+ * The rate control is part of the format: a software encode is bounded at a
+ * limit from `limitsFor(frame)` — the nominal one until a set of lower limits
+ * is decided — or at the limit asked for (`capKbps`), and declared at the
+ * level of that size's nominal output. A hardware encoder is given no bound.
+ *
+ * AND THE VIEWER'S LINK DECIDES WHETHER IT MAY BE GIVEN AT ALL (roadmap item
+ * 97, step 11). Every format considered is judged by what this viewer's link
+ * does with its whole load — the picture and the soundtrack THEY chose
+ * (`link-budget.js`). In order:
+ *
+ * 1. an output already here that suits them (`serving-output.js`);
+ * 2. the size wanted, at the highest limit their link admits;
+ * 3. in AUTO only, a smaller rung of their ladder at the highest limit their
+ *    link admits — a smaller size proves nothing by itself;
+ * 4. otherwise NOTHING: the answer is `unavailable`, with the figures, and no
+ *    output is named. A format known not to fit is never handed over.
+ *
+ * Nothing here reads the machine or the disk: what it needs arrives as values
+ * and as functions over them.
+ */
+
+import { computeOutputDimensions, nominalKbpsFor, softwareRateControlFor } from "../args.js";
+import { buildResolutionLadder, canSustainOutput, pickSoftwarePreset } from "../hwaccel.js";
+import { OutputSpec } from "../output/OutputSpec.js";
+import { chooseServingOutput, nextRungAreaBelow, servingCandidates } from "./serving-output.js";
+import { linkAnswerFigures, linkCouldCarry, loadOf, videoLoadOfSpec } from "./link-budget.js";
+
+/**
+ * @param {object} params
+ * @param {boolean} params.encodesPicture - The output carries a picture and re-encodes it.
+ * @param {boolean} params.exact - The size is produced exactly as asked.
+ * @param {{ width: number, height: number }} params.target - The box asked for; zeroes mean the source's.
+ * @param {{ width: number, height: number, megabitsPerSecond: number | null, decode: object | null }} params.source
+ * @param {number} params.fps
+ * @param {{ kind: string, name: string }} params.encoder
+ * @param {unknown} params.benchmark - The startup measurement of the software encoder, or null.
+ * @param {{ decodeModel: object | null, observedDecodeCostSec: number | null, requiredSpeed: number | null }} params.cost
+ * @param {(params: object) => object | null} params.chooseBudget - The realtime budget's ladder choice.
+ * @param {boolean} params.tonemap
+ * @param {number | null} [params.capKbps] - A nominal limit asked for outright;
+ *   above the size's own it is refused (`softwareRateControlFor`).
+ * @param {(frame: { width: number, height: number }) => number[]} [params.limitsFor] -
+ *   The nominal limits a frame may be produced at, highest first; the row is
+ *   chosen by the frame's area (`limitRowFor`).
+ * @param {import("./link-budget.js").LoadPart | null} [params.audioLoad] - The
+ *   soundtrack this viewer receives with the picture, from it or beside it.
+ * @param {(encode: object | null) => OutputSpec} params.specWith - The output
+ *   with this picture format and every other part as the request made it.
+ * @param {{ mode: "auto" | "manual", linkMbps: number | null, keys: Iterable<string>, readyAt: (key: string) => boolean, observedPeakMbps?: (spec: OutputSpec) => number | null }} params.serving
+ * @returns {{
+ *   spec: OutputSpec | null,
+ *   budget: object | null,
+ *   wantedKey: string,
+ *   reusedKey: string | null,
+ *   answer: object | null,
+ *   unavailable: { reason: string, figures: object | null } | null
+ * }}
+ */
+export function decideOutputFormat({
+  encodesPicture,
+  exact,
+  target,
+  source,
+  fps,
+  encoder,
+  benchmark,
+  cost,
+  chooseBudget,
+  tonemap,
+  capKbps = null,
+  limitsFor = (frame) => [nominalKbpsFor(frame)],
+  audioLoad = null,
+  specWith,
+  serving
+}) {
+  const judge = (spec) => linkCouldCarry(
+    serving.linkMbps,
+    loadOf(videoLoadOfSpec(spec, source.megabitsPerSecond, serving.observedPeakMbps?.(spec) ?? null), audioLoad)
+  );
+  const given = (spec, answer, extra = {}) => ({
+    spec,
+    budget: null,
+    wantedKey: spec.toKey(),
+    reusedKey: null,
+    answer,
+    unavailable: null,
+    ...extra
+  });
+  const refused = (spec, answer, reason, extra = {}) => ({
+    spec: null,
+    budget: null,
+    wantedKey: spec.toKey(),
+    reusedKey: null,
+    answer,
+    unavailable: { reason, figures: answer ? linkAnswerFigures(answer) : null, bound: "link" },
+    ...extra
+  });
+
+  if (!encodesPicture) {
+    const spec = specWith(null);
+    if (!spec.video) {
+      // A soundtrack on its own: the viewer's load was judged with the picture
+      // it plays beside, which counted this track.
+      return given(spec, null);
+    }
+    const answer = judge(spec);
+    return answer.admitted
+      ? given(spec, answer)
+      : refused(spec, answer, "the source's own picture is more than this viewer's link carries");
+  }
+
+  const ceiling = computeOutputDimensions(target.width, target.height, source.width, source.height);
+  const budget = exact
+    ? null
+    : chooseBudget({
+        transcodeVideo: true,
+        targetWidth: target.width,
+        targetHeight: target.height,
+        sourceWidth: source.width,
+        sourceHeight: source.height,
+        outputFps: fps,
+        source: source.decode,
+        requiredSpeed: cost.requiredSpeed
+      });
+  const width = budget?.width ?? ceiling?.w ?? 0;
+  const height = budget?.height ?? ceiling?.h ?? 0;
+  const priced = {
+    decodeModel: cost.decodeModel,
+    source: source.decode,
+    observedDecodeCostSec: cost.observedDecodeCostSec,
+    requiredSpeed: cost.requiredSpeed
+  };
+  const software = encoder.kind === "software";
+  const measured = software && Boolean(benchmark);
+  // WHETHER THIS MACHINE HAS SHOWN IT CAN ENCODE THIS SIZE (roadmap item 97,
+  // step 14): a mode of this encoder qualified at startup, measured at this
+  // frame, and fast enough on its own for this source. A size that fails is not
+  // a format anybody is given here — not the one asked for, and not a lower
+  // one in its place. Whether the machine has room for it BESIDE what already
+  // runs is the admission's, asked when the output is opened.
+  const machineCan = (w, h) => {
+    if (!(w > 0 && h > 0)) {
+      return true; // no size to judge: the source's own, which the probe could not read
+    }
+    if (!Array.isArray(benchmark)) {
+      return true; // not calibrated: a wiring made without the startup calibration
+    }
+    if (benchmark.length === 0) {
+      return false; // calibrated, and no mode qualified
+    }
+    return canSustainOutput({ benchmark, ...priced, outputPixelsPerSec: w * h * fps, frame: { width: w, height: h } }).sustainable;
+  };
+  const presetFor = (w, h) => (budget && w === width && h === height
+    ? budget.preset
+    : measured && w > 0
+      ? pickSoftwarePreset(benchmark, w * h * fps, priced, { width: w, height: h })
+      : null);
+  // Every format at one size this viewer could be given, highest limit first.
+  // A hardware encoder is given no limit, so it has exactly one.
+  const formatsAt = (w, h) => {
+    const limits = !software || !(w > 0 && h > 0)
+      ? [null]
+      : capKbps !== null && capKbps !== undefined && w === width && h === height
+        ? [capKbps]
+        : limitsFor({ width: w, height: h });
+    return limits.map((limit) => specWith({
+      encoder: encoder.name,
+      width: w,
+      height: h,
+      fps,
+      preset: presetFor(w, h),
+      tonemap,
+      rateControl: limit === null ? null : softwareRateControlFor({ width: w, height: h, fps, capKbps: limit })
+    }));
+  };
+  const wantedFormats = formatsAt(width, height);
+  const wantedSpec = wantedFormats[0];
+  const wantedKey = wantedSpec.toKey();
+
+  // A LIMIT NAMED IN THE REQUEST IS WHAT WAS ASKED FOR, and no other output
+  // stands in for it. It is named when a viewer is being moved to another
+  // limit of the height they watch (roadmap item 97, step 12), and the output
+  // they are being moved OFF always suits them by the rule below — so letting
+  // the rule answer would hand them back the very output the move is for
+  // leaving. An output with exactly this limit is still reused: it has the same
+  // key, and the key is what `OutputOpening` looks up.
+  const limitNamed = capKbps !== null && capKbps !== undefined;
+  if (ceiling && !limitNamed) {
+    const served = chooseServingOutput({
+      mode: serving.mode,
+      wanted: { width, height },
+      nextLowerArea: nextRungAreaBelow(buildResolutionLadder(ceiling.w, ceiling.h), height),
+      atRisk: measured && !canSustainOutput({ benchmark, ...priced, outputPixelsPerSec: width * height * fps, frame: { width, height } }).sustainable,
+      judge: (candidate) => judge(candidate.spec),
+      candidates: servingCandidates({
+        wanted: wantedSpec,
+        keys: serving.keys,
+        source,
+        encoderName: encoder.name,
+        readyAt: serving.readyAt
+      })
+    });
+    if (served && served.key !== wantedKey) {
+      return given(OutputSpec.fromKey(served.key), served.answer, { budget, wantedKey, reusedKey: served.key });
+    }
+  }
+
+  let anySizeHeld = machineCan(width, height);
+  if (anySizeHeld) {
+    for (const spec of wantedFormats) {
+      const answer = judge(spec);
+      if (answer.admitted) {
+        return given(spec, answer, { budget, wantedKey });
+      }
+    }
+  }
+  if (serving.mode !== "manual" && ceiling) {
+    for (const rung of buildResolutionLadder(ceiling.w, ceiling.h).filter((one) => one.height < height)) {
+      if (!machineCan(rung.width, rung.height)) {
+        continue;
+      }
+      anySizeHeld = true;
+      for (const spec of formatsAt(rung.width, rung.height)) {
+        const answer = judge(spec);
+        if (answer.admitted) {
+          return given(spec, answer, { wantedKey });
+        }
+      }
+    }
+  }
+  if (!anySizeHeld) {
+    // Not the viewer's link: this machine. Said apart, because the answer to
+    // it is another proxy, found before anything plays.
+    return {
+      ...refused(wantedSpec, null, `this machine has not shown it can re-encode this picture at ${width}x${height}@${fps} or any size below it`, { budget, wantedKey }),
+      unavailable: {
+        reason: `this machine has not shown it can re-encode this picture at ${width}x${height}@${fps} or any size below it`,
+        figures: { width, height, fps, encoder: encoder.name },
+        bound: "machine"
+      }
+    };
+  }
+  return refused(
+    wantedSpec,
+    judge(wantedSpec),
+    serving.mode === "manual"
+      ? "no limit of the size picked is admitted by this viewer's link"
+      : "no size and limit this viewer's ladder offers is admitted by their link",
+    { budget, wantedKey }
+  );
+}