@torrent-tv/proxy 2.80.12 → 2.80.14

package/services/output/LiveOutputs.js

@@ -16,6 +16,8 @@
 
 import { variantHeightsFor } from "./ladder.js";
 
+import { masterRateArgs } from "./rates.js";
+
 export class LiveOutputs {
   /**
    * @param {object} params
@@ -264,4 +266,38 @@ export class LiveOutputs {
     }
     return this.splicableHeights(owner).length >= 2;
   }
+  /**
+   * Everything the master playlist needs of a session except its soundtracks.
+   *
+   * The shape of the film — which heights can be spliced, how big the source
+   * is, how the pieces are packaged — and the rates it carries. All of it is a
+   * fact about the OUTPUT, and it was assembled at the call site in the session
+   * manager, which is the file that is being taken apart.
+   *
+   * The soundtracks are not here on purpose: which of them is marked default is
+   * the asking VIEWER'S business, and that belongs to whoever holds viewers.
+   *
+   * @param {object} session
+   * @param {(address: string) => { index: number, size: number }} largestPiece -
+   *   The biggest piece an output has made, asked of whoever owns the disk. A
+   *   plain function, so this layer holds no store.
+   * @returns {object}
+   */
+  masterFactsOf(session, largestPiece) {
+    return {
+      playlistVersion: session.segmentFormat.playlistVersion,
+      heights: this.splicableHeights(session),
+      sourceWidth: Number(session.file?.width) || 0,
+      sourceHeight: Number(session.file?.height) || 0,
+      ...masterRateArgs({
+        fileLength: Number(session.file?.length) || 0,
+        durationSeconds: Number(session.file?.durationSeconds) || 0,
+        largest: largestPiece(session.outputKey ?? ""),
+        boundaries: session.timeline?.published ?? session.timeline?.boundaries ?? null,
+        producedHeight: this.producedHeightOf(session),
+        capKbps: Number(session.rateCapKbps) || 0
+      })
+    };
+  }
+
 }

package/services/output/playlists.js

@@ -58,19 +58,75 @@ export function escapeAttribute(value) {
   return String(value ?? "").replace(/"/g, "'").replace(/[\u0000-\u001f\u007f]/g, " ").trim();
 }
 
+// The smallest rate the HLS specification tolerates in a `BANDWIDTH` attribute.
+// It is a floor on what may be DECLARED, not a belief about any content: a file
+// whose rate is not yet known is described by it, and so is a variant so small
+// that the arithmetic below would go under it.
+const MINIMUM_DECLARED_BITS_PER_SECOND = 400_000;
+
 /**
- * A rough bitrate for a height, in bits per second.
+ * How many bits of film there are per second of playback, for one height.
+ *
+ * MEASURED, and the measurement is available before anything is encoded. The
+ * comment here used to say the opposite — "a measurement we do not have before
+ * encoding starts" — and gave `height * height * 3.2` instead, which for 1080
+ * is 3 732 480. Field 2026-09-08: that was declared for a file carrying
+ * 18.4 Mbit/s, five times more, and the arithmetic that reads it is not
+ * cosmetic.
+ *
+ * **What reads it.** The browser sizes its cushion in BYTES from this figure
+ * times the seconds it is asked to hold, so a figure five times low makes the
+ * cushion five times shallow: 120 s asked bought 56 MB, which is 26 s of that
+ * film, and the deepest the browser ever held was 17.1 s. And hls.js compares
+ * it against its own estimate of the link to decide a level is unplayable —
+ * which is why an inflated figure is not the answer either: its own recovery
+ * then moves level, and that path does not honour our pinning (measured, 2.59.3).
+ *
+ * **Where the figure comes from.** Two cases, both exact:
+ *
+ * - a height that is COPIED carries the source's own bits, so it is the file's
+ *   length over its duration;
+ * - a height that is RE-ENCODED carries what the encoder is capped at, which we
+ *   impose ourselves.
  *
- * `BANDWIDTH` is required on every variant by the HLS specification, and the
- * player uses it to order them. It does not have to be exact — nothing here
- * adapts on it, because the viewer chooses — so it is the usual H.264 rule of
- * thumb rather than a measurement we do not have before encoding starts.
+ * The specification wants the PEAK per segment in `BANDWIDTH` and the average
+ * in `AVERAGE-BANDWIDTH`; both are emitted, and the peak is scaled from the
+ * average by the ratio the largest produced segment has actually shown — never
+ * a chosen multiplier, and equal to the average until a segment exists.
  *
- * @param {number} height
+ * @param {object} params
+ * @param {number} params.averageBitsPerSecond - The film's own rate, measured.
+ * @param {number} params.height
+ * @param {number} params.sourceHeight
+ * @param {number} [params.capKbps] - What a re-encoded height is capped at.
  * @returns {number}
  */
-export function estimatedBitrateFor(height) {
-  return Math.max(400_000, Math.round(height * height * 3.2));
+export function bitrateFor({ averageBitsPerSecond, height, sourceHeight, capKbps = 0 }) {
+  // ONE EXPRESSION, and each term is a measured quantity or the absence of one
+  // written as the identity of its operation. There is no case analysis here
+  // because there are no cases: the rate a variant carries is what the source
+  // carries, shrunk by how much less picture there is, and never more than what
+  // we cap the encoder at.
+  //
+  //  - what the source carries: `length * 8 / duration`, exact. Unknown is 0,
+  //    and 0 falls to the floor below, which is what "not measured" means;
+  //  - how much less picture: the ratio of pixel counts, and never above 1 —
+  //    a variant at or above the source's height carries the source's bits.
+  //    The pixel count is the one term of the relation that is a fact rather
+  //    than an opinion about the encoder, and it errs HIGH for a small height,
+  //    which is the safe direction: the cushion is sized generously and the
+  //    player does not conclude the level is beyond its link;
+  //  - what we cap it at: exact where we impose one, and `Infinity` where we
+  //    do not, which is the identity of `min` and so states "no cap" without a
+  //    branch;
+  //  - the floor: the smallest figure the specification tolerates, and the
+  //    identity of `max`.
+  const measured = Number(averageBitsPerSecond) > 0 ? Number(averageBitsPerSecond) : 0;
+  const shrink = height > 0 && sourceHeight > 0
+    ? Math.min(1, (height * height) / (sourceHeight * sourceHeight))
+    : 1;
+  const cap = capKbps > 0 ? capKbps * 1000 : Number.POSITIVE_INFINITY;
+  return Math.round(Math.max(MINIMUM_DECLARED_BITS_PER_SECOND, Math.min(measured * shrink, cap)));
 }
 
 /**
@@ -134,7 +190,10 @@ export function mediaPlaylistText({ boundaries, segmentFormat }) {
  *   sourceWidth: number,
  *   sourceHeight: number,
  *   renditions?: Array<{ trackIndex: number, name: string, language: string, isDefault: boolean }>,
- *   playlistFileName: string
+ *   playlistFileName: string,
+ *   averageBitsPerSecond?: number,
+ *   peakOverAverage?: number,
+ *   capKbpsFor?: (height: number) => number
  * }} params
  * @returns {string}
  */
@@ -144,7 +203,10 @@ export function masterPlaylistText({
   sourceWidth,
   sourceHeight,
   renditions = [],
-  playlistFileName
+  playlistFileName,
+  averageBitsPerSecond = 0,
+  peakOverAverage = 1,
+  capKbpsFor = () => 0
 }) {
   const lines = ["#EXTM3U", `#EXT-X-VERSION:${playlistVersion}`];
   const audioGroup = renditions.length > 0 ? AUDIO_GROUP_ID : "";
@@ -160,8 +222,21 @@ export function masterPlaylistText({
     const width = sourceHeight > 0 && sourceWidth > 0
       ? Math.round((sourceWidth / sourceHeight) * height / 2) * 2
       : 0;
+    const average = bitrateFor({
+      averageBitsPerSecond,
+      height,
+      sourceHeight,
+      capKbps: capKbpsFor(height)
+    });
+    // BOTH, because they answer different questions and the specification has a
+    // name for each: the peak is what a link must carry at the worst moment,
+    // the average is what the whole variant costs. hls.js sizes its byte budget
+    // from BANDWIDTH, so the peak is what stops the cushion being sized for a
+    // quiet stretch and running dry on a loud one — measured on the field file,
+    // 17.1 Mbit/s median against 73 Mbit/s at its peak.
+    const peak = Math.round(average * Math.max(1, peakOverAverage));
     lines.push(
-      `#EXT-X-STREAM-INF:BANDWIDTH=${estimatedBitrateFor(height)}` +
+      `#EXT-X-STREAM-INF:BANDWIDTH=${peak},AVERAGE-BANDWIDTH=${average}` +
       (width > 0 ? `,RESOLUTION=${width}x${height}` : "") +
       (audioGroup ? `,AUDIO="${audioGroup}"` : "")
     );

package/services/output/rates.js

@@ -0,0 +1,95 @@
+/**
+ * @file How many bits of film there are per second of playback.
+ *
+ * A fact about the OUTPUT, and the two figures the HLS specification asks for:
+ * the average over the whole variant, and the peak one segment reaches. Both
+ * are measured — the average from the file's own length and duration, the peak
+ * from the biggest piece actually produced and the span it covers.
+ *
+ * It used to be `height * height * 3.2`, a rule of thumb, justified by a comment
+ * saying the measurement was not available before encoding starts. It is: the
+ * length and the duration are known when the session is created, and the peak
+ * refines itself as pieces appear. Field 2026-09-08: 3.73 Mbit/s declared for a
+ * file carrying 18.4, and the browser's cushion is sized in BYTES from that
+ * figure — 120 s asked bought 26 s of film.
+ *
+ * Pure: plain numbers in, plain numbers out. Nothing here knows what a session,
+ * a store or a torrent is.
+ */
+
+/**
+ * The two rates to declare, from what has been measured of this file.
+ *
+ * @param {object} params
+ * @param {number} params.fileLength - Bytes of the source file.
+ * @param {number} params.durationSeconds
+ * @param {{ index: number, size: number }} [params.largest] - The biggest piece
+ *   produced so far, with its number. An index of `-1` means none yet.
+ * @param {number[]} [params.boundaries] - Where the file is cut, so the biggest
+ *   piece's own span is known. Bytes alone cannot give a rate.
+ * @returns {{ averageBitsPerSecond: number, peakOverAverage: number }}
+ */
+export function declaredRates({ fileLength, durationSeconds, largest = null, boundaries = null }) {
+  const length = Number(fileLength);
+  const duration = Number(durationSeconds);
+  if (!(length > 0) || !(duration > 0)) {
+    return { averageBitsPerSecond: 0, peakOverAverage: 1 };
+  }
+  const averageBitsPerSecond = (length * 8) / duration;
+  const index = Number(largest?.index);
+  const size = Number(largest?.size);
+  if (!Number.isInteger(index) || index < 0 || !(size > 0) || !Array.isArray(boundaries)) {
+    // Nothing has been produced, so the peak is not yet a measured quantity and
+    // is declared equal to the average. It rises as soon as one piece exists,
+    // and a ratio invented meanwhile would be exactly the fabrication this file
+    // replaced.
+    return { averageBitsPerSecond, peakOverAverage: 1 };
+  }
+  const span = Number(boundaries[index + 1]) - Number(boundaries[index]);
+  if (!(span > 0)) {
+    return { averageBitsPerSecond, peakOverAverage: 1 };
+  }
+  // Never below one: the peak cannot be under the average, and a piece that
+  // happens to be the smallest in a short session must not lower the figure the
+  // player sizes its cushion from.
+  return {
+    averageBitsPerSecond,
+    peakOverAverage: Math.max(1, ((size * 8) / span) / averageBitsPerSecond)
+  };
+}
+
+/**
+ * The three arguments the master playlist needs to declare its rates.
+ *
+ * Assembled here rather than at the call site, because all three are facts
+ * about the OUTPUT and none of them is a fact about a session: the file's own
+ * length and duration, the biggest piece made of it, and the cap imposed on the
+ * one height being produced. The caller holds them and passes them as numbers.
+ *
+ * Only the height being produced has a cap — the other heights do not exist
+ * yet, and stating one for them would be a guess about a session nobody has
+ * made.
+ *
+ * @param {object} params
+ * @param {number} params.fileLength
+ * @param {number} params.durationSeconds
+ * @param {{ index: number, size: number } | null} [params.largest]
+ * @param {number[] | null} [params.boundaries]
+ * @param {number} [params.producedHeight] - The height this output encodes at.
+ * @param {number} [params.capKbps] - What that height is capped at, if it is.
+ * @returns {{ averageBitsPerSecond: number, peakOverAverage: number,
+ *   capKbpsFor: (height: number) => number }}
+ */
+export function masterRateArgs({
+  fileLength,
+  durationSeconds,
+  largest = null,
+  boundaries = null,
+  producedHeight = 0,
+  capKbps = 0
+}) {
+  return {
+    ...declaredRates({ fileLength, durationSeconds, largest, boundaries }),
+    capKbpsFor: (height) => (height === producedHeight ? capKbps : 0)
+  };
+}

package/services/piece-store/piece-lru.js

@@ -268,9 +268,16 @@ export class PieceLru {
    * a union wider than the capacity cannot be held however the eviction is
    * ordered.
    *
-   * @returns {{ readers: number, unionPieces: number, widestPieces: number, capacity: number }}
+   * @returns {{ readers: number, names: string[], unionPieces: number, widestPieces: number, capacity: number }}
    */
   demand() {
+    // WHO THEY ARE, not only how many. A "reader" here is whoever declared a
+    // range, and on 2026-09-08 the field said `5 reader(s) want 24 piece(s) of
+    // 25` on a session with two encoders — because the priority map declares one
+    // range per zone and four of its zones were arriving as four readers. The
+    // count alone could not say that, and choosing between "narrow the windows"
+    // and "raise the allowance" was guesswork until the names were printed.
+    const names = [...this.#protected.keys()].map(String).sort();
     const ranges = [...this.#protected.values()]
       .map((range) => ({ from: range.from, to: range.to }))
       .sort((left, right) => left.from - right.from);
@@ -288,6 +295,7 @@ export class PieceLru {
     }
     return {
       readers: ranges.length,
+      names,
       unionPieces,
       widestPieces,
       capacity: this.#capacity