@torrent-tv/proxy 2.86.0 → 2.87.0

package/services/encode/output/OutputSpec.js

@@ -0,0 +1,390 @@
+import { createHash } from "node:crypto";
+
+/**
+ * @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 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 control —
+ * so this is not enough to reuse segments BETWEEN proxies (roadmap item 41).
+ */
+
+/**
+ * A rate control as an output states it, or null where there is none.
+ *
+ * @param {unknown} given
+ * @returns {{ maxrateKbps: number, bufsizeKbps: number, level: string | null } | null}
+ */
+function rateControlOf(given) {
+  if (!given || typeof given !== "object") {
+    return null;
+  }
+  const maxrateKbps = Number(given.maxrateKbps);
+  const bufsizeKbps = Number(given.bufsizeKbps);
+  if (!(Number.isInteger(maxrateKbps) && maxrateKbps > 0 && Number.isInteger(bufsizeKbps) && bufsizeKbps > 0)) {
+    return null;
+  }
+  return {
+    maxrateKbps,
+    bufsizeKbps,
+    level: typeof given.level === "string" && /^[0-9.]+$/.test(given.level) ? given.level : null
+  };
+}
+
+/**
+ * The picture an output carries.
+ *
+ * ITS RATE CONTROL IS PART OF IT (roadmap item 97, step 10, decided with the
+ * user 2026-09-18 and 2026-09-23). A bitrate limit changes the bytes of every
+ * piece, so two limits are two outputs; it was once a runtime field of a
+ * shared output that the worst link among its viewers moved, which took a
+ * slow viewer's limit onto every viewer of that picture. The level the stream
+ * is declared at is part of it too: it is written into the header. It is the
+ * level of the NOMINAL output of this size, so every limit at one size writes
+ * the same header (`softwareRateControlFor`).
+ */
+export class VideoOutput {
+  /**
+   * @param {object} params
+   * @param {number} params.fileIndex - The file the picture is read from.
+   * @param {{ encoder: string, width: number, height: number, fps: number, preset: string | null, tonemap: boolean, rateControl?: { maxrateKbps: number, bufsizeKbps: number, level: string | null } | null } | null} params.encode
+   *   Null when the picture is copied — then the output is the source's own
+   *   picture and nothing asked for can change a byte of it. When it is
+   *   re-encoded, the FORMAT that is actually produced: which encoder, the
+   *   size, the frame rate, the speed setting and whether HDR is tone mapped
+   *   down. Each of those changes what a decoder must be told in the header,
+   *   so pieces that differ in any of them cannot share one init segment.
+   *
+   *   What was ASKED for is not here. The key used to carry the viewer's box
+   *   and whether it was to be produced exactly, while the budget chose the
+   *   real size afterwards — so one address could name two formats, and pieces
+   *   of both would be served under the header of one (decided with the user
+   *   2026-09-16).
+   */
+  constructor({ fileIndex, encode = null }) {
+    this.fileIndex = Number.isInteger(fileIndex) && fileIndex >= 0 ? fileIndex : 0;
+    this.encode = encode
+      ? {
+          encoder: typeof encode.encoder === "string" && encode.encoder.length > 0 ? encode.encoder : "unknown",
+          width: Number.isInteger(encode.width) && encode.width > 0 ? encode.width : 0,
+          height: Number.isInteger(encode.height) && encode.height > 0 ? encode.height : 0,
+          fps: Number.isFinite(encode.fps) && encode.fps > 0 ? encode.fps : 0,
+          preset: typeof encode.preset === "string" && encode.preset.length > 0 ? encode.preset : null,
+          tonemap: encode.tonemap === true,
+          // Null where nothing bounds the rate — a hardware encoder, which is
+          // given a quality figure and no `-maxrate` at all.
+          rateControl: rateControlOf(encode.rateControl)
+        }
+      : null;
+  }
+
+  /**
+   * How many points of picture this output carries, or zero for a copy, which
+   * is the source's own size and is compared by the caller that knows it.
+   *
+   * @returns {number}
+   */
+  get area() {
+    return this.encode ? this.encode.width * this.encode.height : 0;
+  }
+
+  /**
+   * @returns {string}
+   */
+  toKey() {
+    if (!this.encode) {
+      return `v=${this.fileIndex}/copy`;
+    }
+    const { encoder, width, height, fps, preset, tonemap, rateControl } = this.encode;
+    const rate = rateControl
+      ? `vbv=${rateControl.maxrateKbps}k-${rateControl.bufsizeKbps}k@${rateControl.level ?? "-"}`
+      : "vbv=-";
+    return `v=${this.fileIndex}/enc/${encoder}/${width}x${height}@${fps}/${preset ?? "-"}/${tonemap ? "tonemap" : "none"}/${rate}`;
+  }
+}
+
+/**
+ * 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}`;
+  }
+}
+
+/**
+ * The shape `OutputSpec.toKey` writes, read back part by part.
+ */
+const KEY_PATTERN =
+  /^(?<source>.+):fmt=(?<format>[a-z0-9]+):grid=(?<grid>kf|even)@(?<gridFile>\d+):(?<carries>video-only|audio-only|muxed)(?::v=(?<videoFile>\d+)\/(?<video>copy|enc\/(?<encoder>[^/:]+)\/(?<width>\d+)x(?<height>\d+)@(?<fps>[0-9.]+)\/(?<preset>[^/:]+)\/(?<tonemap>tonemap|none)\/vbv=(?<vbv>-|(?<maxrate>\d+)k-(?<bufsize>\d+)k@(?<level>-|[0-9.]+))))?(?::a=(?<audioFile>\d+)\/(?<audioTrack>\d+)\/(?<audioCodec>aac|copy))?$/;
+
+/**
+ * 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/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";
+  }
+
+  /** @returns {boolean} */
+  get transcodesVideo() {
+    return this.video?.encode !== null && this.video?.encode !== undefined;
+  }
+
+  /** @returns {boolean} */
+  get transcodesAudio() {
+    return this.audio?.transcode === true;
+  }
+
+  /** @returns {boolean} */
+  get carriesAudioSeparately() {
+    return this.carries === "video-only";
+  }
+
+  /** @returns {number} */
+  get audioFileIndex() {
+    return this.audio?.fileIndex ?? -1;
+  }
+
+  /** @returns {number} */
+  get audioSourceTrackIndex() {
+    return this.audio?.trackIndex ?? 0;
+  }
+
+  /**
+   * 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(":");
+  }
+
+  /**
+   * The identity read back from its own key, or null for a key this version
+   * does not write.
+   *
+   * A directory of produced pieces names its output by the key it was made
+   * under, and that is the only record of what format lies inside it. A key in
+   * an older shape — one that named the box a viewer ASKED for rather than the
+   * format produced — cannot say that, so it answers null and the directory is
+   * not served.
+   *
+   * @param {string} key
+   * @returns {OutputSpec | null}
+   */
+  static fromKey(key) {
+    const match = KEY_PATTERN.exec(String(key ?? ""));
+    if (!match) {
+      return null;
+    }
+    const groups = match.groups;
+    const video = groups.video === undefined
+      ? null
+      : new VideoOutput({
+          fileIndex: Number(groups.videoFile),
+          encode: groups.video === "copy"
+            ? null
+            : {
+                encoder: groups.encoder,
+                width: Number(groups.width),
+                height: Number(groups.height),
+                fps: Number(groups.fps),
+                preset: groups.preset === "-" ? null : groups.preset,
+                tonemap: groups.tonemap === "tonemap",
+                rateControl: groups.vbv === "-"
+                  ? null
+                  : {
+                      maxrateKbps: Number(groups.maxrate),
+                      bufsizeKbps: Number(groups.bufsize),
+                      level: groups.level === "-" ? null : groups.level
+                    }
+              }
+        });
+    const audio = groups.audioFile === undefined
+      ? null
+      : new AudioOutput({
+          fileIndex: Number(groups.audioFile),
+          trackIndex: Number(groups.audioTrack),
+          transcode: groups.audioCodec === "aac"
+        });
+    const spec = new OutputSpec({
+      sourceKey: groups.source,
+      segmentFormatId: groups.format,
+      grid: new CutGrid({ kind: groups.grid === "kf" ? "keyframe" : "uniform", fileIndex: Number(groups.gridFile) }),
+      video,
+      audio
+    });
+    // Read back exactly or not at all: a key that parses into something that
+    // writes a different key is not a key this version made.
+    return spec.toKey() === key ? spec : null;
+  }
+
+  /**
+   * The name anybody outside this layer addresses the output by.
+   *
+   * A function of the identity above and of nothing else, so two requests that
+   * would produce the same bytes get the same name however far apart they
+   * arrive, and MANY VIEWERS OF ONE OUTPUT address one name by construction
+   * rather than because somebody arranged it.
+   *
+   * It used to be a fresh `randomUUID()` minted per session. That was a second
+   * name for a thing that already had one — a session is found by `toKey()`, so
+   * there is exactly one per output — and it said nothing the key did not. What
+   * it did do was hide the output's identity from everything outside: two lives
+   * of one output looked like two unrelated things, and no log could be
+   * followed across a restart.
+   *
+   * SHORT AND OPAQUE, so that whoever carries it can carry it whole: the key
+   * itself is a sentence with punctuation in it, and every carrier would have
+   * to agree on how to escape that. Sixteen characters of SHA-256 is about one
+   * chance in ten thousand of two outputs colliding after four billion of them,
+   * which is far beyond what one proxy produces.
+   *
+   * Nothing outside takes it apart, so its shape is ours: it is compared whole,
+   * and shortened only for a log line.
+   *
+   * @returns {string}
+   */
+  toName() {
+    return createHash("sha256").update(this.toKey()).digest("hex").slice(0, 16);
+  }
+}
+
+/**
+ * Whether a string is a name this proxy minted.
+ *
+ * Here, beside the minting, because it is the same fact read backwards, and a
+ * fact stated in two places is one that can disagree with itself. It did, the
+ * day the name stopped being a uuid: the shape changed here while the guard
+ * elsewhere still demanded 36 characters of hex and dashes, and every route
+ * behind that guard would have refused every request.
+ *
+ * It is a guard and not only a test of form: a name reaching the filesystem
+ * must not be able to carry a `/` or a `.`.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isOutputName(value) {
+  return typeof value === "string" && /^[a-f0-9]{16}$/.test(value);
+}

package/services/{output → encode/output}/Timeline.js

@@ -25,6 +25,15 @@
  * 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.
  *
+ * **Nor how well produced pieces land**, which it did hold until 2026-09-15 and
+ * had no business holding. One reading is taken off a produced piece and three
+ * different facts are drawn from it — a copy shows where this FILE's keyframes
+ * really are, a step shows whether IT obeyed its grid, a soundtrack shows how
+ * far the picture's grid has moved under its run — and a tally per (file, grid)
+ * mixed all three, because a picture and the soundtrack inside the same file
+ * share one grid by construction. The file's half is on `KeyframeTable`, the
+ * output's half on `Output`.
+ *
  * **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,
@@ -33,35 +42,6 @@
  * 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
@@ -93,11 +73,6 @@ export class Timeline {
     this.sourceTimes = Array.isArray(sourceTimes) && sourceTimes.length === this.published.length
       ? sourceTimes
       : [];
-    // 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. */
@@ -170,17 +145,17 @@ export class Timeline {
    * It lived in the session manager, which is a place, not a layer. Here it is
    * beside the table it converts against.
    *
-   * @param {import("../priority/PriorityMap.js").PriorityMap} map - One number
+   * @param {import("../../viewer/PriorityMap.js").PriorityMap} map - One number
    *   per second of film.
    * @param {number} segmentCount - How many pieces this output has.
-   * @returns {import("../priority/PriorityMap.js").DemandZone[]} Runs of pieces
+   * @returns {import("../../viewer/PriorityMap.js").DemandZone[]} Runs of pieces
    *   that agree. Empty where nothing is stated, which says nobody is coming.
    */
   inSegments(map, segmentCount) {
     if (!(segmentCount > 0) || !map || !(map.durationSeconds > 0)) {
       return [];
     }
-    /** @type {import("../priority/PriorityMap.js").DemandZone[]} */
+    /** @type {import("../../viewer/PriorityMap.js").DemandZone[]} */
     const runs = [];
     for (let index = 0; index < segmentCount; index += 1) {
       // A PIECE TAKES THE STRONGEST SECOND IT HOLDS. It is made or not made

package/services/encode/output/index.js

@@ -0,0 +1,20 @@
+export { OutputSpec, VideoOutput, AudioOutput, CutGrid, isOutputName } from "./OutputSpec.js";
+export { PLAYLIST_FILE_NAME } from "./playlists.js";
+
+/**
+ * The code an error carries when no output suits the viewer: nothing this proxy
+ * could produce or already holds is admitted by their link. Its `details` say
+ * why and with which figures. A definition shared by both sides of the
+ * interface — the encoding that decides it and the routes that answer it.
+ */
+export const OUTPUT_UNAVAILABLE = "OUTPUT_UNAVAILABLE";
+
+/**
+ * The code an error carries when THIS MACHINE cannot take the output: no mode
+ * of its encoder was shown at startup to hold the picture at any size this
+ * viewer could be given, or the machine has no place for one more encoder
+ * beside what already runs (roadmap item 97, step 14). Not the viewer's link —
+ * another proxy may well serve it, and the page asks the pool before anything
+ * plays. Its `details` say why, with the figures.
+ */
+export const OUTPUT_NO_CAPACITY = "OUTPUT_NO_CAPACITY";

package/services/encode/output/ladder.js

@@ -0,0 +1,32 @@
+/**
+ * @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 `OutputCatalog`.
+ */
+
+/**
+ * The standard heights, high to low. One list for both uses: the heights the
+ * menu offers, and the rungs the realtime budget steps down through below a
+ * viewer's own screen size. They were two lists with the same values, and two
+ * owners of one fact drift apart.
+ *
+ * Only rungs below the source are used: upscaling invents detail and costs the
+ * encoder more than the source itself.
+ */
+export const LADDER_HEIGHTS = Object.freeze([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 = LADDER_HEIGHTS.filter((height) => height < sourceHeight);
+  return [Math.round(sourceHeight), ...rungs];
+}

package/services/{output → encode/output}/playlists.js

@@ -33,6 +33,9 @@ const LANGUAGE_TAGS = new Map([
   ["tur", "tr"], ["ces", "cs"], ["cze", "cs"], ["nld", "nl"], ["dut", "nl"]
 ]);
 
+/** The name ffmpeg writes its own playlist to, and the name that is served. */
+export const PLAYLIST_FILE_NAME = "index.m3u8";
+
 /**
  * The RFC 5646 tag for a language ffmpeg named, or the name unchanged.
  *

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

@@ -0,0 +1,21 @@
+/**
+ * @file Which container an output's segments are in, read from its key.
+ *
+ * The key names the format produced, so a directory of segments can be read
+ * back without any record kept elsewhere — which is what adopting segments an
+ * earlier process left behind needs. A key in a shape this version does not
+ * write (one naming the box a viewer asked for rather than the format
+ * produced) cannot say what is inside, and the answer is null.
+ */
+
+import { OutputSpec } from "./output/index.js";
+import { resolveSegmentFormat, SEGMENT_FORMAT_IDS } from "./segment-formats/index.js";
+
+/**
+ * @param {string} key
+ * @returns {object | null} The segment format, or null when the key cannot say.
+ */
+export function segmentFormatOfKey(key) {
+  const stated = OutputSpec.fromKey(key)?.segmentFormatId ?? "";
+  return SEGMENT_FORMAT_IDS.includes(stated) ? resolveSegmentFormat(stated) : null;
+}