@torrent-tv/proxy 2.75.0 → 2.76.0

package/services/output/OutputSpec.js

@@ -0,0 +1,195 @@
+/**
+ * @file What a session PRODUCES, stated once and used as its identity.
+ *
+ * Three domain axes already have a home in this package: what a file states
+ * about itself (`container/`), what a track states about itself (`tracks/`),
+ * and what anybody wants off the swarm (`demand/`). This is the fourth — what
+ * we make out of them — and it had no home at all: the identity of a session
+ * was a `[...].join(":")` inside a 300-line function, with no name, no test and
+ * nothing printing it.
+ *
+ * The rule it exists to express, stated by the user 2026-09-03:
+ *
+ * > A session belongs to the tracks its output actually carries. Its key holds
+ * > those tracks' parameters and nothing else. Two sessions whose parameters
+ * > agree ARE the same session, and the encoded result is reused by definition.
+ *
+ * So reuse between viewers is not a feature built on top of this — it is what a
+ * correctly built key already means. A field of the REQUEST that does not
+ * change one byte of the output must not appear here; measured 2026-09-03, two
+ * viewers of one copied picture got two sessions whose output was identical
+ * byte for byte (`research/two-viewers-one-file-2026-09-03.md`).
+ *
+ * What deliberately does NOT appear:
+ *
+ * 1. the viewer, in any form. Not the consumer id, not where they started, not
+ *    their viewport. A viewer is not a property of the material;
+ * 2. the bitrate ceiling the viewer's measured link puts on a re-encode. It is
+ *    a runtime parameter of a SHARED session — the worst link among the live
+ *    consumers decides — so two viewers on one encode is the design, not a
+ *    collision. Rate control appears in neither the SPS nor the PPS, which is
+ *    why it can move under a player that has already cached the init;
+ * 3. the video track number. Only `0:v:0` is ever mapped, so the file names the
+ *    picture. Add it here the day a second video track can be chosen.
+ *
+ * A limit worth stating: two specs that agree name interchangeable output
+ * within ONE proxy. A copied picture's bytes depend only on the source, but a
+ * re-encoded one's depend on this host's encoder, its preset and its rate cap —
+ * so this is not enough to reuse segments BETWEEN proxies (roadmap item 41).
+ */
+
+/**
+ * The picture an output carries.
+ */
+export class VideoOutput {
+  /**
+   * @param {object} params
+   * @param {number} params.fileIndex - The file the picture is read from.
+   * @param {{ width: number, height: number, manual: boolean } | null} params.encode
+   *   Null when the picture is copied — then the output is the source's own
+   *   size and nothing about a target box can change it. The box when it is
+   *   re-encoded, with `manual` saying the viewer forced it and the realtime
+   *   budget must not move it.
+   */
+  constructor({ fileIndex, encode = null }) {
+    this.fileIndex = Number.isInteger(fileIndex) && fileIndex >= 0 ? fileIndex : 0;
+    this.encode = encode
+      ? {
+          width: Number.isInteger(encode.width) && encode.width > 0 ? encode.width : 0,
+          height: Number.isInteger(encode.height) && encode.height > 0 ? encode.height : 0,
+          manual: encode.manual === true
+        }
+      : null;
+  }
+
+  /**
+   * @returns {string}
+   */
+  toKey() {
+    if (!this.encode) {
+      return `v=${this.fileIndex}/copy`;
+    }
+    const box = `${this.encode.width}x${this.encode.height}`;
+    return `v=${this.fileIndex}/enc:${box}:${this.encode.manual ? "manual" : "auto"}`;
+  }
+}
+
+/**
+ * The soundtrack an output carries.
+ */
+export class AudioOutput {
+  /**
+   * @param {object} params
+   * @param {number} params.fileIndex - The file the TRACK lives in, which for a
+   *   dub shipped beside the picture is not the picture's file.
+   * @param {number} params.trackIndex - `0:a:N` inside that file. The flat
+   *   number the browser sends spans the picture's own tracks and the files
+   *   beside it, and two flat numbers of two different pictures can name one
+   *   track; this is the number that cannot.
+   * @param {boolean} params.transcode - Re-encoded to AAC, or copied.
+   */
+  constructor({ fileIndex, trackIndex, transcode }) {
+    this.fileIndex = Number.isInteger(fileIndex) && fileIndex >= 0 ? fileIndex : 0;
+    this.trackIndex = Number.isInteger(trackIndex) && trackIndex >= 0 ? trackIndex : 0;
+    this.transcode = transcode === true;
+  }
+
+  /**
+   * @returns {string}
+   */
+  toKey() {
+    return `a=${this.fileIndex}/${this.trackIndex}/${this.transcode ? "aac" : "copy"}`;
+  }
+}
+
+/**
+ * Where an output is cut.
+ *
+ * Both forms belong to a FILE and not to the session: the keyframe grid is that
+ * file's own keyframe times, and the uniform grid is derived from that file's
+ * duration. A soundtrack takes the grid of the picture it accompanies, so its
+ * grid names the picture's file — which is what makes two soundtrack sessions
+ * cut for two different pictures tell themselves apart.
+ */
+export class CutGrid {
+  /**
+   * @param {object} params
+   * @param {"keyframe" | "uniform"} params.kind
+   * @param {number} params.fileIndex - Whose keyframes, or whose duration.
+   */
+  constructor({ kind, fileIndex }) {
+    this.kind = kind === "keyframe" ? "keyframe" : "uniform";
+    this.fileIndex = Number.isInteger(fileIndex) && fileIndex >= 0 ? fileIndex : 0;
+  }
+
+  /**
+   * @returns {string}
+   */
+  toKey() {
+    return `grid=${this.kind === "keyframe" ? "kf" : "even"}@${this.fileIndex}`;
+  }
+}
+
+/**
+ * One encode of one torrent's material: which tracks, in what form, cut how,
+ * packaged how.
+ */
+export class OutputSpec {
+  /**
+   * @param {object} params
+   * @param {string} params.sourceKey - `torrent:<infohash>`, the canonical
+   *   identity of the torrent itself: a magnet and a `.torrent` file for the
+   *   same content produce the same one (`torrent-source-key.js`). Nothing
+   *   further is needed to say WHICH film this is.
+   * @param {string} params.segmentFormatId - fMP4 or MPEG-TS. Two viewers
+   *   asking for different containers cannot share one ffmpeg.
+   * @param {CutGrid} params.grid
+   * @param {VideoOutput | null} params.video
+   * @param {AudioOutput | null} params.audio
+   */
+  constructor({ sourceKey, segmentFormatId, grid, video = null, audio = null }) {
+    this.sourceKey = String(sourceKey ?? "");
+    this.segmentFormatId = String(segmentFormatId ?? "");
+    this.grid = grid;
+    this.video = video;
+    this.audio = audio;
+  }
+
+  /**
+   * What this output carries, in the vocabulary the rest of the class uses.
+   *
+   * `muxed` is the one case where a session legitimately holds the parameters
+   * of two tracks: a browser that does not understand rendition groups must be
+   * sent its sound inside the picture's own stream.
+   *
+   * @returns {"video-only" | "audio-only" | "muxed" | "empty"}
+   */
+  get carries() {
+    if (this.video && this.audio) {
+      return "muxed";
+    }
+    if (this.video) {
+      return "video-only";
+    }
+    if (this.audio) {
+      return "audio-only";
+    }
+    return "empty";
+  }
+
+  /**
+   * The identity. Two outputs with the same one are the same output.
+   *
+   * @returns {string}
+   */
+  toKey() {
+    const parts = [this.sourceKey, `fmt=${this.segmentFormatId}`, this.grid.toKey(), this.carries];
+    if (this.video) {
+      parts.push(this.video.toKey());
+    }
+    if (this.audio) {
+      parts.push(this.audio.toKey());
+    }
+    return parts.join(":");
+  }
+}

package/services/output/Timeline.js

@@ -0,0 +1,220 @@
+/**
+ * @file Where a file is cut, and what the player was told about it.
+ *
+ * This belongs to the FILE and its grid, not to a session and not to a viewer.
+ * Every quality step of one film has to be cut at exactly the same times — that
+ * is what lets a segment made by one encoder be appended where another's would
+ * have gone — and every session serving that film has to publish the same
+ * playlist, or two of them stamp the same moment differently and the picture
+ * and the sound drift apart.
+ *
+ * Until now each session computed and kept its own copy, and agreement between
+ * them was achieved by COPYING: a variant was handed `inheritedGrid` at
+ * creation, and a soundtrack the same. That works while somebody remembers to
+ * pass it, and it failed when the two tables drifted — measured 2026-08-17,
+ * corrections of 0.6-2.9 s between two sessions of one file, and again
+ * 2026-08-20, segments arriving a uniform 2.002 s before the times the playlist
+ * named for them, four times what a player will bridge. One table, held once,
+ * cannot drift from itself.
+ *
+ * **What it does NOT hold, and why.** The container's own keyframe table, how
+ * exact that table is, which container answered, and how long the file runs:
+ * every one of those is a fact of the FILE, and this object is held per file AND
+ * grid — so a file cut two ways kept two copies of one immutable list. They live
+ * on the source file now, which is one object per file whatever grids are cut
+ * from it. What is left here is the two things that really are per grid: where
+ * the cuts are, and what the player was told they are.
+ *
+ * **Two tables, and they are not the same thing.** `boundaries` is where the
+ * file is cut NOW, corrections included, and it is what a run is told to cut
+ * at. `published` is what the player was given, written once and never changed,
+ * and it is what a segment must be stamped to. A player places a fragment by
+ * the playlist it holds; the live table keeps moving as produced segments
+ * reveal where the file's cuts really are.
+ */
+
+/**
+ * A fresh tally of how well a container's keyframe index matches its file.
+ *
+ * @returns {{ checked: number, disagreed: number, maxDeviationSec: number, firstDisagreementIndex: number, deviations: number[], landedOnAnotherKeyframe: number, seen: Set<number> }}
+ */
+export function newIndexCheck() {
+  return {
+    checked: 0,
+    disagreed: 0,
+    maxDeviationSec: 0,
+    firstDisagreementIndex: -1,
+    // Every deviation, so the summary can report a distribution instead of one
+    // extreme. Bounded by the number of distinct boundaries a file produces.
+    deviations: [],
+    // Of the segments that started away from the playlist, how many began at
+    // ANOTHER time in the very list the grid was built from. This is the
+    // measurement that separates the two explanations: a table that describes
+    // times the file does not have, against a table that lists only SOME
+    // keyframes and a grid built over its gaps. Asked 2026-08-17 by the user,
+    // who was right that the second is far more likely — every deviation
+    // measured that day was positive, 0.58-2.96 s, which is what a cut pushed
+    // forward to the next real keyframe looks like.
+    landedOnAnotherKeyframe: 0,
+    // Which boundaries have been counted. A segment can be requested again, and
+    // a repeat is the same boundary, not new evidence.
+    seen: new Set()
+  };
+}
+
+export class Timeline {
+  /**
+   * @param {object} params
+   * @param {number[]} params.boundaries - Cut times in seconds, ascending, one
+   *   more than there are segments.
+   * @param {number[] | null} [params.published] - What the player was told, when
+   *   that differs from the boundaries because corrections have been made since.
+   * @param {"keyframe" | "uniform"} params.cutGrid - Whether those times are
+   *   the source's own keyframes, which a copied picture has no choice about,
+   *   or an even grid the encoder is told to place keyframes on.
+   */
+  constructor({ boundaries, published = null, cutGrid }) {
+    this.boundaries = Array.isArray(boundaries) ? boundaries : [];
+    // What the player holds. Taken from the boundaries as they stood when the
+    // playlist was written, and never touched again. Given outright only when a
+    // table is being restored with corrections already in it — a live one is
+    // always published from its own boundaries.
+    this.published = Array.isArray(published) ? published : [...this.boundaries];
+    this.cutGrid = cutGrid === "keyframe" ? "keyframe" : "uniform";
+    // How well this container's keyframe index matches its own file. A fact
+    // about the FILE and its index: asked per session it would be answered a
+    // different number of times for one film depending on how many people
+    // happened to watch it.
+    this.indexCheck = newIndexCheck();
+  }
+
+  /** @returns {number} How many segments this file is cut into. */
+  get segmentCount() {
+    return Math.max(0, this.boundaries.length - 1);
+  }
+
+  /**
+   * Where segment `index` begins, on the timeline the player was given.
+   *
+   * @param {number} index
+   * @returns {number}
+   */
+  publishedStartOf(index) {
+    if (!Number.isInteger(index) || index <= 0) {
+      return this.published[0] ?? 0;
+    }
+    const at = Math.min(index, this.published.length - 1);
+    return this.published[at] ?? 0;
+  }
+
+  /**
+   * Where segment `index` begins on the live table — where a run cutting now
+   * will really put it.
+   *
+   * @param {number} index
+   * @returns {number}
+   */
+  liveStartOf(index) {
+    if (!Number.isInteger(index) || index <= 0) {
+      return this.boundaries[0] ?? 0;
+    }
+    const at = Math.min(index, this.boundaries.length - 1);
+    return this.boundaries[at] ?? 0;
+  }
+
+  /**
+   * Which segment holds this moment.
+   *
+   * @param {number} seconds
+   * @returns {number}
+   */
+  indexForTime(seconds) {
+    const wanted = Number.isFinite(seconds) && seconds > 0 ? seconds : 0;
+    for (let index = 0; index < this.segmentCount; index += 1) {
+      if (wanted < this.boundaries[index + 1]) {
+        return index;
+      }
+    }
+    return Math.max(0, this.segmentCount - 1);
+  }
+
+}
+
+/**
+ * The timelines this proxy holds, one per file and grid.
+ *
+ * Keyed by the two things that decide where the cuts are: which file, and
+ * whether the cuts are its own keyframes or an even grid. A quality step of the
+ * same film is a different OUTPUT and the same timeline, which is exactly the
+ * agreement `inheritedGrid` used to arrange by copying.
+ */
+export class Timelines {
+  /** @type {Map<string, Timeline>} */
+  #byKey = new Map();
+
+  /**
+   * @param {string} sourceKey
+   * @param {number} fileIndex
+   * @param {"keyframe" | "uniform"} cutGrid
+   * @returns {string}
+   */
+  static keyFor(sourceKey, fileIndex, cutGrid) {
+    return `${sourceKey}:${fileIndex}:${cutGrid === "keyframe" ? "kf" : "even"}`;
+  }
+
+  /**
+   * The one for this file and grid, made by `build` if it is not there yet.
+   *
+   * @param {string} key
+   * @param {() => Timeline} build
+   * @returns {Timeline}
+   */
+  get(key, build) {
+    let timeline = this.#byKey.get(key);
+    if (!timeline) {
+      timeline = build();
+      this.#byKey.set(key, timeline);
+    }
+    return timeline;
+  }
+
+  /**
+   * @param {string} key
+   * @returns {Timeline | null}
+   */
+  peek(key) {
+    return this.#byKey.get(key) ?? null;
+  }
+
+  /** @param {string} key */
+  forget(key) {
+    this.#byKey.delete(key);
+  }
+
+  /**
+   * Drop every timeline nobody is holding.
+   *
+   * A timeline is small — two arrays of a few thousand numbers — and it is kept
+   * for as long as somebody is reading the file it describes. Nothing else
+   * removes one, and a map that only ever grows is the shape of half the memory
+   * faults recorded in this project.
+   *
+   * @param {Set<Timeline>} inUse
+   * @returns {number} How many were dropped.
+   */
+  forgetUnused(inUse) {
+    let dropped = 0;
+    for (const [key, timeline] of [...this.#byKey]) {
+      if (!inUse.has(timeline)) {
+        this.#byKey.delete(key);
+        dropped += 1;
+      }
+    }
+    return dropped;
+  }
+
+  /** @returns {number} */
+  get size() {
+    return this.#byKey.size;
+  }
+}

package/services/output/index.js

@@ -0,0 +1 @@
+export { OutputSpec, VideoOutput, AudioOutput, CutGrid } from "./OutputSpec.js";

package/services/output/ladder.js

@@ -0,0 +1,26 @@
+/**
+ * @file The heights a picture may be offered at.
+ *
+ * A fact about an output and about nothing else: it takes a source height and
+ * answers with heights. What the machine can afford of them is the quality
+ * budget's question, and what a player may splice between is `LiveOutputs`.
+ */
+
+// The resolutions a viewer may choose between. Only rungs at or below the
+// source are offered: upscaling invents detail and costs the encoder more than
+// the source itself.
+const VARIANT_LADDER = [2160, 1440, 1080, 720, 540, 480, 360, 240];
+
+/**
+ * The heights offered for a source of this height, largest first.
+ *
+ * @param {number} sourceHeight
+ * @returns {number[]}
+ */
+export function variantHeightsFor(sourceHeight) {
+  if (!Number.isFinite(sourceHeight) || sourceHeight <= 0) {
+    return [];
+  }
+  const rungs = VARIANT_LADDER.filter((height) => height < sourceHeight);
+  return [Math.round(sourceHeight), ...rungs];
+}