@torrent-tv/proxy 2.85.1 → 2.87.0

package/services/{learned-median.js → encode/learned-median.js}

@@ -17,6 +17,17 @@
  * but it is answered from the measurements rather than from a constant.
  */
 
+/**
+ * How many of the most recent readings the median is taken over.
+ *
+ * A statement about how much of the past still describes the host, not a
+ * measured quantity, and it is written as one rather than dressed up as one.
+ * It lives here because it is a property of this rule and not of any one cost:
+ * all four learn the same way, and it was declared in the session manager under
+ * a name that claimed it was about decoding while three of the four used it.
+ */
+export const READINGS_KEPT = 7;
+
 /**
  * The middle of a set of readings, or null when there are none.
  *

package/services/encode/output/EncodedOutput.js

@@ -0,0 +1,57 @@
+/**
+ * @file One output that exists on this proxy.
+ *
+ * What it holds are the facts born with the output and gone with it: its
+ * identity and format (`spec`), the file it is made from, where that file is
+ * cut, the container its pieces are in, the shape the encoder is given, and the
+ * playlist the player is told. Two things it deliberately does NOT hold,
+ * decided with the user 2026-09-16: what has been produced — the segment store
+ * owns that — and which encoders are running — the encoding orchestrator owns
+ * that. An output without a live record does not make its pieces invalid;
+ * pieces are valid while they exist.
+ *
+ */
+
+export class EncodedOutput {
+  /**
+   * @param {object} params
+   * @param {string} params.id - The output's name, derived from its key.
+   * @param {import("./OutputSpec.js").OutputSpec} params.spec
+   * @param {object} params.file - The source file, one object per file.
+   * @param {object} params.keyframes - That file's keyframe table, held rather
+   *   than copied so a table read later still reaches it.
+   * @param {object} params.timeline - Where that file is cut, shared by every
+   *   output of it.
+   * @param {object} params.segmentFormat - The container the pieces are in.
+   * @param {import("./Output.js").Output} params.output - The format in the
+   *   terms the encoder is given, and how its pieces land.
+   * @param {boolean} params.useSyntheticPlaylist - The playlist is built from
+   *   the probed duration rather than written by the encoder.
+   * @param {string} params.playlistText
+   * @param {number | undefined} params.variantHeight - The height a step is
+   *   addressed by, when it is produced at exactly that size.
+   */
+  constructor({ id, spec, file, keyframes, timeline, segmentFormat, output, useSyntheticPlaylist, playlistText, variantHeight }) {
+    this.id = id;
+    this.spec = spec;
+    this.file = file;
+    this.keyframes = keyframes;
+    this.timeline = timeline;
+    this.segmentFormat = segmentFormat;
+    this.output = output;
+    this.useSyntheticPlaylist = useSyntheticPlaylist === true;
+    this.playlistText = typeof playlistText === "string" ? playlistText : "";
+    this.variantHeight = variantHeight;
+
+  }
+
+  /**
+   * The address of this output's pieces. Derived, so it cannot say anything
+   * the spec does not.
+   *
+   * @returns {string}
+   */
+  get outputKey() {
+    return this.spec.toKey();
+  }
+}

package/services/encode/output/Output.js

@@ -0,0 +1,131 @@
+/**
+ * @file One output's format in the terms the encoder is given, and how its
+ * pieces land.
+ *
+ * The format is the output's identity (`OutputSpec`) and is decided before the
+ * output is named: the size, the frame rate, the speed setting, whether HDR is
+ * tone mapped. This states the same values the way the command builder reads
+ * them. It used to be decided once per output and cached by the output's key,
+ * because the key named what was asked for while the budget chose the format
+ * afterwards; the cache was dropped sooner than the pieces it described, so one
+ * key could come to name two formats. The key is the format now, and there is
+ * nothing left to cache.
+ *
+ * The bitrate limit is not here: it is part of the output's identity
+ * (`OutputSpec`), so two limits are two outputs and nothing moves a limit under
+ * one that exists.
+ *
+ * **It also holds how well its own pieces land on its own grid.** Where a piece
+ * of THIS output truly began, against where its playlist says it begins, is a
+ * fact of this output: a step that was told to put a keyframe at that instant
+ * and did not will not splice into the stream it accompanies, and a soundtrack
+ * whose grid was corrected under a run already going is that far from the
+ * picture. Neither says anything about the file. Until 2026-09-15 both were
+ * added to a tally held on the CUT TABLE — which is one per (file, grid), so a
+ * picture and the soundtrack inside the same file shared it, the second reading
+ * of one piece number was dropped as a repeat whichever output it came from,
+ * and the summary could not say which of three facts it was summarising.
+ */
+
+export class Output {
+  /** @type {{ checked: number, disagreed: number, maxDeviationSec: number, firstDisagreementIndex: number, deviations: number[], seen: Set<number> }} */
+  #tally;
+
+  /**
+   * @param {object} params
+   * @param {number} params.encodeWidth - 0 means the source's own width.
+   * @param {number} params.encodeHeight - 0 means the source's own height.
+   * @param {number} params.outputFps
+   * @param {string | null} params.softwarePreset - The speed setting, where the
+   *   encoder has a ladder and one was chosen from it.
+   * @param {boolean} params.applyTonemap
+   */
+  constructor({ encodeWidth, encodeHeight, outputFps, softwarePreset, applyTonemap }) {
+    this.encodeWidth = Number.isFinite(encodeWidth) ? encodeWidth : 0;
+    this.encodeHeight = Number.isFinite(encodeHeight) ? encodeHeight : 0;
+    this.outputFps = Number.isFinite(outputFps) && outputFps > 0 ? outputFps : 0;
+    this.softwarePreset = typeof softwarePreset === "string" ? softwarePreset : null;
+    this.applyTonemap = applyTonemap === true;
+    /**
+     * How far this output's produced pieces fell from its own published grid.
+     * Private, because `landing` below is the only honest way to read it: a
+     * caller holding the raw counters would have to know which of them are a
+     * summary and which are working state.
+     *
+     * @type {{ checked: number, disagreed: number, maxDeviationSec: number, firstDisagreementIndex: number, deviations: number[], seen: Set<number> }}
+     */
+    this.#tally = {
+      checked: 0,
+      disagreed: 0,
+      maxDeviationSec: 0,
+      firstDisagreementIndex: -1,
+      deviations: [],
+      // A piece can be produced and served again; a repeat is the same piece,
+      // not new evidence. Per OUTPUT, so one output's reading of piece #7 can
+      // no longer silence another output's reading of its own #7.
+      seen: new Set()
+    };
+  }
+
+  /**
+   * A produced piece of this output states where it truly began.
+   *
+   * @param {object} reading
+   * @param {number} reading.index
+   * @param {number} reading.deviationSec - From where this output's playlist
+   *   says that piece begins.
+   * @param {number} reading.toleranceSec - Above which the two are held to
+   *   disagree rather than to have rounded.
+   * @returns {void}
+   */
+  noteLanding({ index, deviationSec, toleranceSec }) {
+    if (!Number.isInteger(index) || !Number.isFinite(deviationSec) || this.#tally.seen.has(index)) {
+      return;
+    }
+    this.#tally.seen.add(index);
+    this.#tally.checked += 1;
+    this.#tally.deviations.push(deviationSec);
+    if (deviationSec > toleranceSec) {
+      this.#tally.disagreed += 1;
+      if (this.#tally.firstDisagreementIndex < 0) {
+        this.#tally.firstDisagreementIndex = index;
+      }
+    }
+    if (deviationSec > this.#tally.maxDeviationSec) {
+      this.#tally.maxDeviationSec = deviationSec;
+    }
+  }
+
+  /**
+   * How many distinct pieces of this output have stated where they began.
+   *
+   * Separate from `landing` because it is read on every produced piece, to
+   * decide whether the summary is due, while `landing` sorts what it summarises
+   * — which on a two-hour film is a sort per segment on the path that serves
+   * one. A count and a summary are two different costs.
+   *
+   * @returns {number}
+   */
+  get piecesLanded() {
+    return this.#tally.checked;
+  }
+
+  /**
+   * Where this output's pieces have been landing, or null while none has.
+   *
+   * @returns {{ checked: number, disagreed: number, maxDeviationSec: number, medianDeviationSec: number, firstDisagreementIndex: number } | null}
+   */
+  get landing() {
+    if (this.#tally.checked === 0) {
+      return null;
+    }
+    const sorted = [...this.#tally.deviations].sort((left, right) => left - right);
+    return {
+      checked: this.#tally.checked,
+      disagreed: this.#tally.disagreed,
+      maxDeviationSec: this.#tally.maxDeviationSec,
+      medianDeviationSec: sorted[Math.floor(sorted.length / 2)],
+      firstDisagreementIndex: this.#tally.firstDisagreementIndex
+    };
+  }
+}

package/services/{output/LiveOutputs.js → encode/output/OutputCatalog.js}

@@ -1,41 +1,135 @@
 /**
- * @file Which outputs of one file exist right now, and what each of them is.
+ * @file The one catalog of the outputs that exist, and every question about
+ * them.
  *
- * Every question here is answered by walking the live sessions and looking at
- * what they ARE — the same file, a step, a soundtrack, this height — and not by
- * following a list of ids anybody keeps. A list of ids is a link between
- * sessions: it ties their lifetimes together, it goes stale when one of them is
- * disposed, and it has to be cleaned from the other side. What an output is is
- * enough to find it, which is the rule `OutputSpec` exists for.
+ * It replaces two classes that held two views of one collection: a registry of
+ * the live outputs and their entry times, and a set of queries walking that
+ * same registry — which outputs belong to one file, which is the picture and
+ * which are its steps and soundtracks, what a step's height is. An output is
+ * found by what it IS, never by a list of ids somebody keeps.
  *
- * Nothing here writes anything except the two answers a session memoizes about
- * itself, and nothing here knows about encoders, viewers, the torrent or the
- * disk. It is the layer the quality budget and the serving path both stand on,
- * and it is separated first for that reason.
+ * Presence is the only statement that an output exists. Creation and access
+ * times describe the catalog entry, not the media, the viewer or the encoder,
+ * so they are kept here and never copied onto the output. What has been
+ * produced is not here either: that is the segment store's, and which runs are
+ * going is the encoding orchestrator's.
  */
 
 import { variantHeightsFor } from "./ladder.js";
 
 import { masterRateArgs } from "./rates.js";
 
-export class LiveOutputs {
+export class OutputCatalog {
+  #steps = new WeakSet();
+  /** The heights each picture can be spliced to, derived once from its file. @type {WeakMap<object, number[]>} */
+  #splicable = new WeakMap();
+
+  #byId = new Map();
+  #lifetime = new Map();
+  #now;
+
   /**
-   * @param {object} params
-   * @param {Map<string, object>} params.sessionsById - The live sessions. Read,
-   *   never written.
+   * @param {object} [params]
+   * @param {() => number} [params.now]
+   * @param {(output: object) => number} [params.fileLengthOf] - How many bytes a
+   *   source file is, which the torrent reports.
+   * @param {(address: string) => { index: number, size: number }} [params.largestPieceOf]
+   *   The biggest piece an output has made, which the disk knows.
    */
-  constructor({ sessionsById, fileLengthOf = () => 0, largestPieceOf = () => ({ index: -1, size: 0 }) }) {
-    this.sessionsById = sessionsById;
-    // Two facts this layer needs and does not own: how many bytes a source file
-    // is, which the torrent reports, and the biggest piece an output has made,
-    // which the disk knows. Taken as plain functions, so nothing of either layer
-    // is held here.
+  constructor({
+    now = Date.now,
+    fileLengthOf = () => 0,
+    largestPieceOf = () => ({ index: -1, size: 0 })
+  } = {}) {
+    this.#now = now;
+    // Two facts this catalog needs and does not own, taken as plain functions
+    // so nothing of their layers is held here: the torrent's byte length and
+    // the store's largest piece. The bitrate limit is not among them any more:
+    // it is part of the output itself (`OutputSpec`).
     this.fileLengthOf = fileLengthOf;
     this.largestPieceOf = largestPieceOf;
   }
 
+  set(id, output) {
+    const known = this.#byId.get(id);
+    this.#byId.set(id, output);
+    if (known !== output) {
+      const at = this.#now();
+      this.#lifetime.set(id, { startedAt: at, lastAccessedAt: at });
+    }
+    return this;
+  }
+
+  get(id) {
+    return this.#byId.get(id);
+  }
+
+  has(id) {
+    return this.#byId.has(id);
+  }
+
+  delete(id) {
+    this.#lifetime.delete(id);
+    return this.#byId.delete(id);
+  }
+
+  clear() {
+    this.#lifetime.clear();
+    this.#byId.clear();
+  }
+
+  touch(outputOrId, at = this.#now()) {
+    const id = typeof outputOrId === "string" ? outputOrId : outputOrId?.id;
+    const lifetime = this.#lifetime.get(id);
+    if (!lifetime || !Number.isFinite(at)) {
+      return false;
+    }
+    lifetime.lastAccessedAt = at;
+    return true;
+  }
+
+  startedAt(outputOrId) {
+    const id = typeof outputOrId === "string" ? outputOrId : outputOrId?.id;
+    return this.#lifetime.get(id)?.startedAt ?? null;
+  }
+
+  lastAccessedAt(outputOrId) {
+    const id = typeof outputOrId === "string" ? outputOrId : outputOrId?.id;
+    return this.#lifetime.get(id)?.lastAccessedAt ?? null;
+  }
+
+  expiredBefore(cutoff) {
+    const ids = [];
+    for (const [id, lifetime] of this.#lifetime) {
+      if (lifetime.lastAccessedAt < cutoff) {
+        ids.push(id);
+      }
+    }
+    return ids;
+  }
+
+  keys() {
+    return this.#byId.keys();
+  }
+
+  values() {
+    return this.#byId.values();
+  }
+
+  entries() {
+    return this.#byId.entries();
+  }
+
+  get size() {
+    return this.#byId.size;
+  }
+
+  [Symbol.iterator]() {
+    return this.#byId[Symbol.iterator]();
+  }
+
   /**
-   * Every live session producing ONE output.
+   * Every live record producing ONE output.
    *
    * The output is the address the encoding layer works in: two sessions whose
    * output parameters agree ARE the same output, so what one of them measured
@@ -44,10 +138,10 @@ export class LiveOutputs {
    * @param {string} address
    * @returns {object[]}
    */
-  sessionsOn(address) {
+  outputsOn(address) {
     const found = [];
-    for (const session of this.sessionsById.values()) {
-      if (session.outputKey === address && session.state !== "disposed") {
+    for (const session of this.values()) {
+      if (session.outputKey === address) {
         found.push(session);
       }
     }
@@ -69,8 +163,8 @@ export class LiveOutputs {
   familyOf(session) {
     const family = [session];
     const key = session?.file?.key;
-    for (const other of this.sessionsById.values()) {
-      if (other === session || other.state === "disposed" || other.file?.key !== key) {
+    for (const other of this.values()) {
+      if (other === session || other.file?.key !== key) {
         continue;
       }
       family.push(other);
@@ -85,7 +179,7 @@ export class LiveOutputs {
    * @returns {object[]}
    */
   renditionsOf(base) {
-    return this.familyOf(base).filter((session) => session !== base && session.audioOnly === true);
+    return this.familyOf(base).filter((session) => session !== base && session.spec.carries === "audio-only");
   }
 
   /**
@@ -102,7 +196,11 @@ export class LiveOutputs {
    * @returns {object[]}
    */
   stepsOf(base) {
-    return this.familyOf(base).filter((session) => session !== base && session.isStep === true);
+    return this.familyOf(base).filter((session) => session !== base && this.#steps.has(session));
+  }
+
+  markStep(output) {
+    this.#steps.add(output);
   }
 
   /**
@@ -122,11 +220,11 @@ export class LiveOutputs {
    * @returns {object}
    */
   pictureOf(session) {
-    if (!session || session.isStep !== true) {
+    if (!session || !this.#steps.has(session)) {
       return session;
     }
     for (const other of this.familyOf(session)) {
-      if (other.isStep !== true && other.audioOnly !== true) {
+      if (!this.#steps.has(other) && other.spec.carries !== "audio-only") {
         return other;
       }
     }
@@ -158,7 +256,7 @@ export class LiveOutputs {
    * @returns {boolean}
    */
   supersededBy(session, stepOnScreen = null) {
-    if (!session || session.isStep === true || session.audioOnly === true) {
+    if (!session || this.#steps.has(session) || session.spec.carries === "audio-only") {
       return false;
     }
     // The picture. A step of it on screen says outright that this is not what
@@ -207,7 +305,7 @@ export class LiveOutputs {
    * @returns {number}
    */
   producedHeightOf(session) {
-    if (!session || session.transcodeVideo !== true || session.audioOnly === true) {
+    if (!session || !session.spec.transcodesVideo || session.spec.carries === "audio-only") {
       return 0;
     }
     return Math.round(Number(session.output.encodeHeight) || 0);
@@ -236,16 +334,18 @@ export class LiveOutputs {
    */
   splicableHeights(session) {
     const owner = this.pictureOf(session);
-    if (Array.isArray(owner.splicableHeights)) {
-      return owner.splicableHeights;
+    const known = this.#splicable.get(owner);
+    if (known) {
+      return known;
     }
     const heights = new Set(variantHeightsFor(Number(owner.file.height) || 0));
     const own = this.variantHeightOf(owner);
     if (own > 0) {
       heights.add(own);
     }
-    owner.splicableHeights = [...heights].sort((left, right) => right - left);
-    return owner.splicableHeights;
+    const sorted = [...heights].sort((left, right) => right - left);
+    this.#splicable.set(owner, sorted);
+    return sorted;
   }
 
   /**
@@ -267,7 +367,7 @@ export class LiveOutputs {
     // A copy can only be cut where the source already has a keyframe, so a rung
     // meant to splice into it has to be cut at exactly those times. A copy that
     // fell back to an even grid ffmpeg does not cut on has nothing to align to.
-    if (!owner.transcodeVideo && owner.timeline.cutGrid !== "keyframe") {
+    if (!owner.spec.transcodesVideo && owner.timeline.cutGrid !== "keyframe") {
       return false;
     }
     return this.splicableHeights(owner).length >= 2;
@@ -305,9 +405,10 @@ export class LiveOutputs {
         largest: this.largestPieceOf(session.outputKey ?? ""),
         boundaries: session.timeline?.published ?? session.timeline?.boundaries ?? null,
         producedHeight: this.producedHeightOf(session),
-        capKbps: Number(session.rateCapKbps) || 0
+        // The peak the encoder is held to, which is what BANDWIDTH declares.
+        // Zero where nothing bounds it — a copy, or a hardware encoder.
+        capKbps: Number(session.spec?.video?.encode?.rateControl?.maxrateKbps) || 0
       })
     };
   }
-
 }