@torrent-tv/proxy 2.80.1 → 2.80.3

package/services/output/Timeline.js

@@ -1,220 +1,256 @@
-/**
- * @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;
-  }
-}
+/**
+ * @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.
+   * @param {number[] | null} [params.sourceTimes] - The same cuts on the FILE's
+   *   own clock — the keyframe a run must seek to for each boundary.
+   */
+  constructor({ boundaries, published = null, cutGrid, sourceTimes = null }) {
+    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";
+    // Where each cut is on the FILE's clock, which is what a seek asks for.
+    // Frozen beside `published` and never corrected: a run must land where the
+    // player was told the segment begins, and the corrections belong to the
+    // live table. Empty when the grid was restored without it, and then the
+    // seek falls back to searching the file's keyframe list — which is the
+    // lossy path this exists to replace, kept only so a restored table still
+    // plays.
+    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. */
+  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 FILE's own clock: the keyframe a run
+   * starting there must seek to.
+   *
+   * Not `publishedStartOf(index) + startTime`. That round trip is lossy, and a
+   * residue of two parts in a quadrillion costs a whole keyframe interval when
+   * the result is looked up in the container's list by value — which is how a
+   * run came to be numbered from #36 while carrying film 17.4 s earlier
+   * (2026-09-05). The number the container stated is carried, not rebuilt.
+   *
+   * @param {number} index
+   * @returns {number | null} Null when this table was restored without the
+   *   source clock, and the caller must fall back to searching.
+   */
+  sourceStartOf(index) {
+    if (this.sourceTimes.length === 0) {
+      return null;
+    }
+    if (!Number.isInteger(index) || index <= 0) {
+      return this.sourceTimes[0] ?? null;
+    }
+    return this.sourceTimes[Math.min(index, this.sourceTimes.length - 1)] ?? null;
+  }
+
+  /**
+   * 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/cut-grid.js

@@ -0,0 +1,97 @@
+/**
+ * @file Where a file is cut, and which keyframe each cut is.
+ *
+ * Two answers, not one, and that is the whole point of this file existing.
+ *
+ * A cut has a time on the PLAYER's clock — 0-based, because a playlist is —
+ * and it has a time on the FILE's clock, which is the keyframe the muxer will
+ * actually seek to. The two differ by the container's own start time, and a
+ * copied picture cannot be cut anywhere but at a real keyframe, so both are
+ * needed and neither can be derived from the other after the fact.
+ *
+ * **Deriving one from the other after the fact is what broke a viewing on
+ * 2026-09-05.** The 0-based time was stored, rounded to six places, and the
+ * seek then added the start time back and looked the result up in the file's
+ * keyframe list by value. That round trip is lossy: a keyframe at 26.234 s in a
+ * container starting at 0.083 s comes back as 26.233999999999998, the lookup
+ * takes "the keyframe at or before" that, and answers the PREVIOUS one — 8.717 s
+ * earlier. Two parts in a quadrillion became one keyframe interval, that
+ * interval became a trim, the trim moved every cut of the run backwards by
+ * another interval, and the run's files were numbered from #36 while carrying
+ * film 17.4 s before what the playlist says #36 holds. The player's video buffer
+ * covered the playhead, its audio buffer had a 17.4 s hole across it, the
+ * intersection was empty, and the viewer waited two minutes and was told the
+ * proxy had sent no video.
+ *
+ * So the keyframe is carried, by index, from the one place that knows it.
+ */
+
+/**
+ * @typedef {object} CutGrid
+ * @property {number[]} boundaries - Cut times on the player's clock, 0-based,
+ *   ascending, one more than there are segments.
+ * @property {number[]} sourceTimes - The same cuts on the FILE's clock: for a
+ *   keyframe grid, the keyframe itself, exactly as the container stated it.
+ *   Same length as `boundaries`, so an index names both.
+ */
+
+/**
+ * Cut a file into segments.
+ *
+ * On a keyframe grid the cuts are the container's own keyframes, thinned so
+ * that no segment is much shorter than asked for; the first cut is the start of
+ * the file and the last is its end, neither of which need be a keyframe.
+ *
+ * On a uniform grid the cuts are multiples of the segment length, and the two
+ * clocks are the same clock: a re-encode places its own keyframes and owes the
+ * container's start time nothing.
+ *
+ * @param {object} params
+ * @param {boolean} params.useKeyframeGrid
+ * @param {number} params.durationSeconds
+ * @param {number} params.segDur - The segment length asked for.
+ * @param {number[]} [params.keyframeTimes] - On the file's own clock.
+ * @param {number} [params.startTime] - The container's start time.
+ * @returns {CutGrid}
+ */
+export function computeCutGrid({ useKeyframeGrid, durationSeconds, segDur, keyframeTimes, startTime }) {
+  const total = Number.isFinite(durationSeconds) && durationSeconds > 0 ? durationSeconds : 0;
+  const step = Number.isFinite(segDur) && segDur > 0 ? segDur : 4;
+  const base = Number.isFinite(startTime) ? startTime : 0;
+  const uniform = () => {
+    const boundaries = [];
+    for (let t = 0; t < total - 0.001; t += step) {
+      boundaries.push(Number(t.toFixed(6)));
+    }
+    boundaries.push(total);
+    // One clock: nothing here is a keyframe of the source, so nothing is owed
+    // the container's start time either.
+    return { boundaries, sourceTimes: [...boundaries] };
+  };
+  if (!useKeyframeGrid || !Array.isArray(keyframeTimes) || keyframeTimes.length === 0 || total <= 0) {
+    return uniform();
+  }
+  const kept = keyframeTimes
+    .filter((time) => Number.isFinite(time))
+    .map((time) => ({ source: time, published: time - base }))
+    .filter((cut) => cut.published >= -0.001 && cut.published < total - 0.05)
+    .sort((left, right) => left.published - right.published);
+  // The first cut is the start of the file, whatever the container's own clock
+  // says that is; the last is its end. Neither is a keyframe, and a run never
+  // seeks to either — index 0 is served without a seek at all.
+  const boundaries = [0];
+  const sourceTimes = [base];
+  for (const cut of kept) {
+    if (cut.published >= boundaries[boundaries.length - 1] + step - 0.05) {
+      boundaries.push(Number(cut.published.toFixed(6)));
+      // NOT the rounded value with the base added back. This is the number the
+      // container stated, and it is what the seek must ask for.
+      sourceTimes.push(cut.source);
+    }
+  }
+  boundaries.push(total);
+  sourceTimes.push(total + base);
+  // A degenerate index — one keyframe, or none inside the film — is no grid at
+  // all, and an even one serves better than a table with a single entry.
+  return boundaries.length >= 2 ? { boundaries, sourceTimes } : uniform();
+}