@torrent-tv/proxy 2.80.13 → 2.80.15

package/services/encode/run-costs.js

@@ -53,9 +53,22 @@ export class RunCosts {
    * that was never told to stop did not die on command, and one that produced
    * nothing has no first output — and an absent reading is not a zero.
    *
-   * @param {{ dyingMs?: number | null, firstOutputMs?: number | null }} ended
+   * @param {{ dyingMs?: number | null, firstOutputMs?: number | null,
+   *   livedMs?: number | null }} ended - `livedMs` is how long a run that
+   *   produced NOTHING was alive, which is a lower bound on the first output.
    */
   note(ended) {
+    // A RUN THAT PRODUCED NOTHING IS A MEASUREMENT TOO — of a lower bound. It
+    // says the first output takes at least as long as this run lived, which is
+    // a fact and not an estimate, and it is the only reading a thrash can
+    // supply: every run in one is killed before it finishes anything.
+    //
+    // Without it the figure that prices a move could only ever be learned from
+    // runs that survived, so the state in which moves are ruinous was exactly
+    // the state in which their cost stayed unknown.
+    if (!Number.isFinite(ended?.firstOutputMs) && Number.isFinite(ended?.livedMs) && ended.livedMs > 0) {
+      RunCosts.#keep(this.#firstOutput, /** @type {number} */ (ended.livedMs));
+    }
     if (Number.isFinite(ended?.dyingMs)) {
       RunCosts.#keep(this.#dying, /** @type {number} */ (ended.dyingMs));
     }
@@ -85,9 +98,47 @@ export class RunCosts {
    * @returns {{ killCostSec: number, firstByteWaitSec: number, samples: number }}
    */
   seconds() {
+    const dying = middleOf(this.#dying);
+    const first = middleOf(this.#firstOutput);
     return {
-      killCostSec: (middleOf(this.#dying) ?? 0) / 1000,
-      firstByteWaitSec: (middleOf(this.#firstOutput) ?? 0) / 1000,
+      // UNKNOWN IS NOT ZERO, and for a cost it is not a small number either: it
+      // is the figure that makes the act it prices never worth doing. Reported
+      // as 0, an unmeasured move was FREE in the plan's arithmetic, so any gain
+      // however small justified it — and moving an encoder is irreversible,
+      // because the process it kills cannot be un-killed.
+      //
+      // The blindness was self-sustaining: `#firstOutput` only takes a reading
+      // from a run that produced something, and a run killed 0.8 s after
+      // starting produces nothing. So a thrash prevented the measurement that
+      // would have stopped it. Field 2026-09-08: 39 moves in one session, 24 of
+      // them between three adjacent numbers — #58 to #59, #59 to #58, #58 to
+      // #60, #60 to #58, six times each — while the picture stood still for
+      // 116.7 s.
+      //
+      // TWO QUESTIONS, NOT ONE, and they take the unknown differently.
+      //
+      // PLACING an encoder where there is none has no alternative: the film gets
+      // made or it does not. So an unmeasured cost must not stand in the way,
+      // and the honest figure is what has been measured or nothing.
+      //
+      // MOVING one has an alternative — leave it alone — and it is
+      // irreversible, because the process it kills cannot be un-killed. There
+      // an unmeasured cost must not license the act, and `Infinity` is the
+      // identity of the comparison that consumes it: "nobody has measured what
+      // this costs" and "never worth doing" are the same statement about an
+      // action whose price is unknown.
+      //
+      // Reported as 0 for both, an unmeasured move was FREE in the plan's
+      // arithmetic, so a gain of a fraction of a second justified it. And the
+      // blindness was self-sustaining: `#firstOutput` takes a reading only from
+      // a run that produced something, and every run in a thrash is killed
+      // before it finishes anything.
+      killCostSec: (dying ?? 0) / 1000,
+      firstByteWaitSec: (first ?? 0) / 1000,
+      moveCostSec:
+        first === null
+          ? Number.POSITIVE_INFINITY
+          : ((dying ?? 0) + first) / 1000,
       samples: Math.min(this.#dying.length, this.#firstOutput.length)
     };
   }

package/services/hls-session-manager.js

@@ -1510,7 +1510,11 @@ export class HlsSessionManager {
     // picture a step belongs to, the steps, the soundtracks, the height a
     // session is named by. Read-only over the register above, and the layer the
     // quality budget and the serving path both stand on.
-    this.liveOutputs = new LiveOutputs({ sessionsById: this.sessionsById });
+    this.liveOutputs = new LiveOutputs({
+      sessionsById: this.sessionsById,
+      fileLengthOf: (session) => this.#fileLengthByKey.get(session.file.key) ?? 0,
+      largestPieceOf: (address) => this.segmentStore.largestPiece(address)
+    });
     // What this host learned last time it ran. Without it every restart shows
     // the first viewer a figure with no measurement behind it.
     this.#loadHostTimings();
@@ -3178,7 +3182,7 @@ export class HlsSessionManager {
    * @param {{ linkMbps: number, bufferedAheadSec: number, consumerId?: string, positionSeconds?: number }} report
    * @returns {boolean}
    */
-  recordNetReport(sessionId, { linkMbps, bufferedAheadSec, consumerId, positionSeconds, playing }) {
+  recordNetReport(sessionId, { linkMbps, bufferedAheadSec, consumerId, positionSeconds, playing, onScreen, inPictureInPicture }) {
     const named = this.sessionsById.get(sessionId);
     if (!named || named.state === "disposed") {
       return false;
@@ -3196,7 +3200,7 @@ export class HlsSessionManager {
     const now = Date.now();
     this.viewers
       .of(session, typeof consumerId === "string" && consumerId.length > 0 ? consumerId : "")
-      .report({ linkMbps, bufferedAheadSec, positionSeconds, playing }, now);
+      .report({ linkMbps, bufferedAheadSec, positionSeconds, playing, onScreen, inPictureInPicture }, now);
     // A stale reading must not go on deciding for the viewers still here: a
     // report describes a link at a moment, and a viewer who seeked since then
     // is somewhere else entirely.
@@ -8295,13 +8299,6 @@ export class HlsSessionManager {
     if (!this.liveOutputs.publishesVariants(session)) {
       return null;
     }
-    const sourceHeight = Number(session.file.height) || 0;
-    // What CAN be spliced, not what is worth offering this second. The live
-    // judgement travels in `offeredHeights` and in every progress report, which
-    // is what the viewer's menu follows; letting it decide the master's
-    // existence made a live session answer 404 to its own published address.
-    const rungs = this.liveOutputs.splicableHeights(session);
-    const sourceWidth = Number(session.file.width) || 0;
     // The audio tracks, published once for the whole file rather than muxed
     // into every rung. Two things follow from that: the same track is not
     // encoded once per rung on a host that struggles to encode it once, and
@@ -8319,10 +8316,12 @@ export class HlsSessionManager {
       ? this.#audioRenditionsOf(session, this.#audioChoiceOf(session, consumerId).trackIndex)
       : [];
     return masterPlaylistText({
-      playlistVersion: session.segmentFormat.playlistVersion,
-      heights: rungs,
-      sourceWidth,
-      sourceHeight,
+      // The shape of the film and the rates it carries, asked of the layer that
+      // holds both. What CAN be spliced, not what is worth offering this second:
+      // the live judgement travels in `offeredHeights` and in every progress
+      // report, and letting it decide the master's existence made a live session
+      // answer 404 to its own published address.
+      ...this.liveOutputs.masterFactsOf(session),
       renditions,
       playlistFileName: PLAYLIST_FILE_NAME
     });

package/services/output/LiveOutputs.js

@@ -16,14 +16,22 @@
 
 import { variantHeightsFor } from "./ladder.js";
 
+import { masterRateArgs } from "./rates.js";
+
 export class LiveOutputs {
   /**
    * @param {object} params
    * @param {Map<string, object>} params.sessionsById - The live sessions. Read,
    *   never written.
    */
-  constructor({ sessionsById }) {
+  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.
+    this.fileLengthOf = fileLengthOf;
+    this.largestPieceOf = largestPieceOf;
   }
 
   /**
@@ -264,4 +272,42 @@ 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
+   * @returns {object}
+   */
+  masterFactsOf(session) {
+    return {
+      playlistVersion: session.segmentFormat.playlistVersion,
+      heights: this.splicableHeights(session),
+      sourceWidth: Number(session.file?.width) || 0,
+      sourceHeight: Number(session.file?.height) || 0,
+      ...masterRateArgs({
+        // FROM WHOEVER KNOWS IT. A source file does not carry its own byte
+        // length — the torrent reports it — and reading a field that does not
+        // exist is what declared every variant at the floor in 2.80.14.
+        fileLength: Number(this.fileLengthOf(session)) || 0,
+        durationSeconds: Number(session.file?.durationSeconds) || 0,
+        // The probe's own reading of the video stream, which is known from the
+        // moment the session exists and covers the gap before the torrent has
+        // reported a length.
+        streamBitsPerSecond: (Number(session.file?.decode?.megabitsPerSecond) || 0) * 1_000_000,
+        largest: this.largestPieceOf(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,125 @@
+/**
+ * @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, 0 until the
+ *   torrent has said. Counts every track and every byte of container, so it is
+ *   the better figure of the two.
+ * @param {number} params.durationSeconds
+ * @param {number} [params.streamBitsPerSecond] - What a probe read off the
+ *   video stream, known from session creation. Lower than the whole file's rate
+ *   because it is one track of it, and used while the length is not known.
+ * @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,
+  streamBitsPerSecond = 0,
+  largest = null,
+  boundaries = null
+}) {
+  const length = Number(fileLength);
+  const duration = Number(durationSeconds);
+  // TWO SOURCES, AND THE LARGER OF THEM, because each is measured and each can
+  // be absent — and absent is 0, so the larger is whichever was measured.
+  //
+  //  - the whole file's length over its duration: the best figure, since it
+  //    counts every track and every byte of container. Known only once the
+  //    torrent has reported the file's size;
+  //  - what the probe read off the video stream: known when the session is
+  //    created, and lower, because it is one track of several.
+  //
+  // The first alone was what shipped in 2.80.14, read from a field that does
+  // not exist on a source file. It came back 0 on every session, so every
+  // variant was declared at the 400 kbit/s floor — nine times WORSE than the
+  // rule of thumb it replaced — and the browser, which sizes its cushion in
+  // bytes from this figure, held 0.1 s of film against 120 s asked. The picture
+  // stood still for 116.7 s of one viewing. Assuming a field instead of
+  // checking it is the whole of that fault.
+  const fromLength = length > 0 && duration > 0 ? (length * 8) / duration : 0;
+  const averageBitsPerSecond = Math.max(fromLength, Number(streamBitsPerSecond) || 0);
+  if (!(averageBitsPerSecond > 0)) {
+    return { averageBitsPerSecond: 0, peakOverAverage: 1 };
+  }
+  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 {number} [params.streamBitsPerSecond]
+ * @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,
+  streamBitsPerSecond = 0,
+  largest = null,
+  boundaries = null,
+  producedHeight = 0,
+  capKbps = 0
+}) {
+  return {
+    ...declaredRates({ fileLength, durationSeconds, streamBitsPerSecond, 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