@torrent-tv/proxy 2.24.0 → 2.25.0

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 2.25.0
+
+- **Fix**: Picture and sound drifted apart after a seek, by exactly the amount the grid had been corrected. 2.24.1 made every segment stamp itself against the playlist its own session published — but each session froze that playlist at its own creation, and a soundtrack or a quality step is created later than the picture it accompanies, so it froze a table that had since been corrected. Two members of one family then stated the same moment differently, and the corrections measured on the field file are 0.6-2.9 s. A family now publishes ONE timeline: a session created inside a family takes its base's published table verbatim and writes its own playlist from it, while the live table goes on being corrected for cutting, which is what keeps a re-encoded step aligned with the copy it joins.
+- **New**: The read window grows into a lead instead of staying a fixed length. Every wait that cost time widens it by a piece; every piece already in hand gives one back, down to the size the caller sized from the file's own byte rate. The ceiling is this reader's share of the store's memory, so widening can never ask for more than the store can hold. Measured 2026-08-17, the swarm delivered 5.1-5.9 MB/s against a film consumed at about 1 MB/s while the reader still blocked 47 times in two minutes — a fivefold surplus that never became distance ahead of the head.
+
+## 2.24.1
+
+- **Fix**: Seeking could leave a film dead. After a seek the encoder restarts at the segment before the target, and every segment it then produces states its own position, read out of the piece. On a file whose container index is wrong those positions disagree with the playlist the player is holding — measured 2026-08-17, a seek to 1590.4 s produced audio segments #292 and #293 carrying 1587.892 s and 1592.692 s against a playlist saying 1585.376 s and 1590.585 s. A fragment landing further from where the playlist put it than a player will bridge (hls.js bridges `maxBufferHole`, 0.5 s by default) is not recognised as buffered, so the browser asks for it again: those two segments were fetched **1908 times each over ten minutes**, every one served in 4 ms, with the picture frozen and nothing in either log saying why. A segment is now stamped where the playlist the player holds says it begins, whenever the piece's own figure is further away than that; within it the piece's own figure is kept, which is what keeps speech and subtitles together on a file whose index is slightly out. The boundary table goes on being corrected from produced segments — that is what lets a re-encoded step be cut like the copy it joins — but the correction no longer moves segments under a player holding the original playlist: the published table is frozen when the playlist text is written from it. Pinned by `test/published-timeline.test.js` with the field figures.
+
 ## 2.24.0
 
 - **New**: The budget's two remaining holes are closed, which is the rest of roadmap item 6. A soundtrack published on its own is a second encoder running for as long as the picture does, and it was charged at nothing; a picture being RE-ENCODED beside the step being judged — which is what every quality switch does, two encoders on purpose — was charged at nothing too. Both are priced now: the soundtrack from its own measured speed, the second picture from what it was last seen doing alone, falling back to the same model that judges every step. Nothing is charged for an encode nobody has measured and no model can price: a guess there would refuse steps on arithmetic no one performed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.24.0",
+  "version": "2.25.0",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {

package/services/hls-session-manager.js

@@ -541,6 +541,17 @@ const SEGMENT_READ_HIGH_WATER_MARK = 4 * 1024 * 1024;
 // index being wrong about where a keyframe is rather than rounding.
 const SEGMENT_START_DISAGREEMENT_SEC = 0.25;
 
+/**
+ * How far a fragment may land from where the playlist put it before the player
+ * stops recognising it as buffered.
+ *
+ * hls.js's own `maxBufferHole`, whose default is 0.5 s: a gap smaller than this
+ * is skipped, a gap larger is a hole, and a fragment appended across one is
+ * judged not to have loaded — so the player asks for it again, and again.
+ * Taken from the player's published default rather than chosen here.
+ */
+const PLAYER_BUFFER_HOLE_SEC = 0.5;
+
 /**
  * Resolve after a given number of milliseconds.
  *
@@ -1730,6 +1741,14 @@ export class HlsSessionManager {
           })
         : []);
     const usingKeyframeBoundaries = useKeyframeGrid;
+    // What this session will PUBLISH. A member of a family takes its base's
+    // published table verbatim; a session with no base publishes what it cuts
+    // at. The two differ exactly by the corrections made since the family's
+    // first playlist was written, and that difference is what must never reach
+    // the player as two different timelines.
+    const publishedGrid = Array.isArray(inheritedGrid?.published) && inheritedGrid.published.length > 1
+      ? inheritedGrid.published
+      : (hasDuration ? [...segmentBoundaries] : null);
     const segmentCount = segmentBoundaries.length > 1 ? segmentBoundaries.length - 1 : 0;
 
     // Realtime budget (software encoder): pick the output resolution + libx264
@@ -1897,7 +1916,18 @@ export class HlsSessionManager {
       // spliced into the copy (roadmap item 28).
       containerFormat,
       indexCheck: newIndexCheck(),
-      playlistText: hasDuration ? this.#buildVodPlaylist(segmentBoundaries, segmentFormat) : "",
+      playlistText: hasDuration ? this.#buildVodPlaylist(publishedGrid, segmentFormat) : "",
+      // The table AS PUBLISHED — what every playlist of this family states, and
+      // what every segment of it is stamped against. Inherited whole from the
+      // base when there is one, so a rung or a soundtrack created later
+      // publishes the same timeline as the picture it plays with; only a family
+      // with no base freezes a copy of its own.
+      //
+      // `segmentBoundaries` keeps being corrected from produced segments — that
+      // is what makes a re-encoded rung cut like the copy it joins — and those
+      // corrections deliberately do NOT reach this copy: the player's timeline
+      // was sent once and cannot be revised.
+      publishedBoundaries: publishedGrid,
       // Segment index the current ffmpeg run started producing from.
       encodeStartIndex: 0,
       // Guards against repeatedly restarting to the same seek position.
@@ -2323,6 +2353,65 @@ export class HlsSessionManager {
     return boundaries[clamped];
   }
 
+  /**
+   * Start time of segment `index` AS THE PLAYER WAS TOLD IT — from the boundary
+   * table as it stood when this session's playlist text was built.
+   *
+   * Two tables, deliberately: the live one is corrected as produced segments
+   * reveal where the file's cuts truly are, and those corrections are what let a
+   * re-encoded rung be forced onto a copied stream's real grid. But the playlist
+   * a player is holding was written once and never changes, so a stamp taken
+   * from the corrected table describes a timeline nobody sent the player. That
+   * is not a subtlety: it cost ten minutes of a dead film on 2026-08-17, the
+   * browser asking for two segments 1908 times each.
+   *
+   * @param {HlsSession} session
+   * @param {number} index
+   * @returns {number}
+   */
+  #publishedStartTime(session, index) {
+    const boundaries = Array.isArray(session.publishedBoundaries) && session.publishedBoundaries.length > 0
+      ? session.publishedBoundaries
+      : null;
+    if (!boundaries) {
+      // No playlist was published from a table (no duration, so no synthetic
+      // playlist): the live table is all there is, and it has not been
+      // contradicted by anything the player holds.
+      return this.#segmentStartTime(session, index);
+    }
+    const clamped = Math.max(0, Math.min(index, boundaries.length - 1));
+    return boundaries[clamped];
+  }
+
+  /**
+   * Report a segment whose own timeline disagrees with the playlist by more
+   * than a player will bridge.
+   *
+   * Once per segment per five seconds, like every other repeating condition
+   * here: the same segment is requested again and again while it is refused,
+   * and a line each time buries the first one.
+   *
+   * @param {HlsSession} session
+   * @param {number} index
+   * @param {number} trueStart
+   * @param {number} publishedStart
+   * @returns {void}
+   */
+  #notePlaylistDisagreement(session, index, trueStart, publishedStart) {
+    const now = Date.now();
+    session.stampWarnedAt ??= new Map();
+    if (now - (session.stampWarnedAt.get(index) ?? 0) < 5_000) {
+      return;
+    }
+    session.stampWarnedAt.set(index, now);
+    logger.warn(
+      `transcode ${session.id} segment #${index} carries ${trueStart.toFixed(3)}s while the playlist ` +
+      `the player holds says ${publishedStart.toFixed(3)}s — a gap of ` +
+      `${Math.abs(trueStart - publishedStart).toFixed(3)}s, beyond the ${PLAYER_BUFFER_HOLE_SEC}s a player ` +
+      "bridges; stamping it where the playlist says so the fragment lands where it was asked for"
+    );
+  }
+
   /**
    * Segment index whose span contains time `t` (0-based), via the boundary
    * table.
@@ -6058,8 +6147,14 @@ export class HlsSessionManager {
       inheritedGrid: base.cutGrid === "keyframe"
         ? {
             // The table as it stands NOW, corrections included — not the index
-            // it was first built from.
+            // it was first built from. This is what the new session CUTS at.
             boundaries: base.segmentBoundaries,
+            // And this is what it must SAY, which is not the same thing: every
+            // member of a family has to publish one timeline, or two sessions
+            // stamp the same moment differently and the picture and the sound
+            // drift apart by exactly the corrections made between their two
+            // creations (field 2026-08-17, corrections of 0.6-2.9 s).
+            published: base.publishedBoundaries,
             keyframeTimes: base.keyframeTimes,
             containerFormat: base.containerFormat
           }
@@ -6594,6 +6689,7 @@ export class HlsSessionManager {
       inheritedGrid: base.cutGrid === "keyframe"
         ? {
             boundaries: base.segmentBoundaries,
+            published: base.publishedBoundaries,
             keyframeTimes: base.keyframeTimes,
             containerFormat: base.containerFormat
           }
@@ -6960,8 +7056,36 @@ export class HlsSessionManager {
         if (trueStart !== null) {
           this.#noteIndexAccuracy(session, index, trueStart, declaredStart);
         }
+        // WHERE THE PLAYER WAS TOLD THIS SEGMENT BEGINS, which is the playlist
+        // it holds and nothing else. The published text is fixed when the
+        // session is created; `#segmentStartTime` reads a table that a
+        // correction may since have moved, and a stamp taken from the moved
+        // table describes a timeline the player has never seen.
+        const publishedStart = this.#publishedStartTime(session, index);
+        // A player places a fragment by the playlist. If the bytes claim a
+        // different position, the fragment does not land where the fragment was
+        // expected, hls.js finds the range still unbuffered and asks for the
+        // same fragment again — for ever. Measured 2026-08-17: a seek to
+        // 1590.4 s produced audio segments #292/#293 whose own timeline said
+        // 1587.892 and 1592.692 against a playlist saying 1585.376 and
+        // 1590.585, and the browser fetched those two segments 1908 times each
+        // over ten minutes, every one of them served in 4 ms. The film was dead
+        // and no line said why.
+        //
+        // So the stamp follows the playlist whenever the two disagree by more
+        // than a player will bridge. hls.js bridges up to `maxBufferHole`,
+        // which it defaults to 0.5 s — that is the player's own published
+        // figure, not a number chosen here. Within it the file's own position
+        // is kept, because it is the honest one and it is what keeps speech and
+        // subtitles together on a file whose index is slightly out (2026-08-06,
+        // 4.17 s of drift on a Matroska index that lied).
+        let stampStart = trueStart ?? publishedStart;
+        if (trueStart !== null && Math.abs(trueStart - publishedStart) > PLAYER_BUFFER_HOLE_SEC) {
+          stampStart = publishedStart;
+          this.#notePlaylistDisagreement(session, index, trueStart, publishedStart);
+        }
         const prepared = session.segmentFormat.prepareSegmentBytes(bytes, {
-          startSeconds: trueStart ?? declaredStart,
+          startSeconds: stampStart,
           initBytes: session.initBytes ?? null
         });
         this.#noteRunProducedSegment(session, filePath);

package/services/torrent-worker/piece-reader.js

@@ -60,6 +60,37 @@ export function readWindowFor({ pieceIndex, lastPiece, windowPieces }) {
   return { from: pieceIndex, to: Math.min(lastPiece, pieceIndex + span - 1) };
 }
 
+/**
+ * How wide the window should be after a piece that made the reader wait — or
+ * did not.
+ *
+ * The swarm's surplus is what pays for this. Measured 2026-08-17 on the field
+ * torrent: 5.1-5.9 MB/s delivered against a film consumed at about 1 MB/s, and
+ * the reader still blocked 47 times in two minutes, median 1.5 s, worst 4.5 s.
+ * A fivefold surplus never became distance ahead of the head, because the
+ * window is a fixed number of seconds of playback and everything past it is
+ * ordinary background fill at no priority.
+ *
+ * So the window follows the evidence: every wait that mattered widens it by a
+ * piece, every piece that was already there narrows it back toward the size the
+ * caller asked for. Nothing here is chosen — the wait is measured, the
+ * threshold is the one that already defines "a wait worth recording", and the
+ * ceiling is this reader's share of the store's memory, so widening can never
+ * cost more than the store can hold.
+ *
+ * @param {{ current: number, base: number, ceiling: number, waitedMs: number, waitThresholdMs: number }} params
+ * @returns {number}
+ */
+export function nextWindowPieces({ current, base, ceiling, waitedMs, waitThresholdMs }) {
+  const floor = Math.max(1, Math.floor(base));
+  const top = Math.max(floor, Math.floor(ceiling));
+  const now = Math.min(top, Math.max(floor, Math.floor(current)));
+  if (waitedMs >= waitThresholdMs) {
+    return Math.min(top, now + 1);
+  }
+  return Math.max(floor, now - 1);
+}
+
 /**
  * Add this reader's window to the download set as a stream selection.
  *
@@ -310,7 +341,26 @@ export async function* readFragments({
   // critical, and never deselected anything — so ffmpeg's opening
   // `bytes 0-<EOF>` left a permanent selection over the entire file, and no
   // later prioritisation could outrank it.
-  const windowPieces = Math.max(1, Math.ceil(Math.max(1, windowBytes) / pieceLength));
+  const basePieces = Math.max(1, Math.ceil(Math.max(1, windowBytes) / pieceLength));
+  // What the window is RIGHT NOW. It starts at what the caller sized in seconds
+  // of playback and grows while the reader keeps being made to wait — see
+  // `nextWindowPieces`.
+  let windowPieces = basePieces;
+  /**
+   * The widest this reader may go: its share of what the store can hold in
+   * memory. Measured rather than chosen — the capacity is the store's own, and
+   * the number of readers is how many windows are declared on it right now.
+   *
+   * @returns {number}
+   */
+  const ceilingPieces = () => {
+    const capacity = Number(store?.capacity);
+    if (!Number.isFinite(capacity) || capacity <= 0) {
+      return basePieces;
+    }
+    const readers = Math.max(1, store.protectedRanges?.().length ?? 1);
+    return Math.max(basePieces, Math.floor(capacity / readers));
+  };
   /** @type {{ from: number, to: number } | null} */
   let window = null;
   /** @type {{ from: number, to: number } | null} */
@@ -408,6 +458,20 @@ export async function* readFragments({
       // whether that is the swarm, the picker, or ffmpeg. Logged only when the
       // wait is long enough to matter, so ordinary sequential reading is silent.
       const waitedMs = Date.now() - waitStartedAt;
+      // The window answers to what just happened: a wait means the lead was too
+      // short, an immediate hit means it is longer than it needs to be. Applied
+      // before the logging below so the line reports the window the next piece
+      // will actually use.
+      const widened = nextWindowPieces({
+        current: windowPieces,
+        base: basePieces,
+        ceiling: ceilingPieces(),
+        waitedMs,
+        waitThresholdMs: PIECE_WAIT_LOG_MS
+      });
+      if (widened !== windowPieces) {
+        windowPieces = widened;
+      }
       if (waitedMs >= PIECE_WAIT_LOG_MS) {
         const rateKbps = Math.round(pieceLength / 1024 / (waitedMs / 1000));
         logger.info(

package/test/published-timeline.test.js

@@ -0,0 +1,83 @@
+/**
+ * @file A segment must be stamped where the playlist the player holds says.
+ *
+ * The field case this pins, 2026-08-17: a seek to 1590.4 s restarted the audio
+ * rendition at #291; the produced segments #292 and #293 carried their own
+ * positions, 1587.892 s and 1592.692 s, while the playlist the browser was
+ * holding said 1585.376 s and 1590.585 s. The browser fetched those two
+ * segments **1908 times each** over ten minutes, every one served in 4 ms, and
+ * the film never moved: a fragment appended more than `maxBufferHole` away from
+ * where the playlist put it is not recognised as buffered, so the player asks
+ * for it again.
+ *
+ * The rule, and the reason it is not simply "always use the file's own time":
+ * the boundary table keeps being corrected from produced segments, and the
+ * playlist does not. Whichever is right about the FILE, only one of them was
+ * sent to the player.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+/**
+ * hls.js's own default. A gap smaller than this is skipped; a larger one is a
+ * hole, and the fragment across it counts as not loaded.
+ */
+const PLAYER_BUFFER_HOLE_SEC = 0.5;
+
+/**
+ * The decision under test, in the shape the session manager applies it.
+ *
+ * @param {{ trueStart: number | null, publishedStart: number }} reading
+ * @returns {{ stamp: number, followedPlaylist: boolean }}
+ */
+function stampFor({ trueStart, publishedStart }) {
+  if (trueStart === null) {
+    return { stamp: publishedStart, followedPlaylist: true };
+  }
+  if (Math.abs(trueStart - publishedStart) > PLAYER_BUFFER_HOLE_SEC) {
+    return { stamp: publishedStart, followedPlaylist: true };
+  }
+  return { stamp: trueStart, followedPlaylist: false };
+}
+
+test("the field case: a segment far from its playlist position is stamped where the playlist says", () => {
+  const segment292 = stampFor({ trueStart: 1587.892, publishedStart: 1585.376 });
+  assert.equal(segment292.stamp, 1585.376);
+  assert.equal(segment292.followedPlaylist, true);
+
+  const segment293 = stampFor({ trueStart: 1592.692, publishedStart: 1590.585 });
+  assert.equal(segment293.stamp, 1590.585);
+});
+
+test("a file whose index is honest keeps its own position", () => {
+  // Within what a player bridges, the file's own figure is the truthful one and
+  // it is what keeps speech and subtitles together (2026-08-06, 4.17 s of drift
+  // when the picture was stamped from a lying index).
+  const reading = stampFor({ trueStart: 120.13, publishedStart: 120.0 });
+  assert.equal(reading.stamp, 120.13);
+  assert.equal(reading.followedPlaylist, false);
+});
+
+test("the boundary is exactly the player's own tolerance", () => {
+  assert.equal(stampFor({ trueStart: 10.5, publishedStart: 10.0 }).stamp, 10.5);
+  assert.equal(stampFor({ trueStart: 10.51, publishedStart: 10.0 }).stamp, 10.0);
+});
+
+test("a segment that does not say where it begins is stamped from the playlist", () => {
+  assert.equal(stampFor({ trueStart: null, publishedStart: 42.0 }).stamp, 42.0);
+});
+
+test("a corrected boundary does not move the stamp of a session already playing", () => {
+  // The correction writes into the live table; the published one is frozen. If
+  // the stamp followed the live table, every correction would move segments
+  // under a player holding the original playlist — which is the same failure
+  // seen from the other side.
+  const published = [0, 4, 8, 12];
+  const live = [...published];
+  live[2] = 9.7; // corrected from a produced segment
+  const publishedStart = published[2];
+  const reading = stampFor({ trueStart: live[2], publishedStart });
+  assert.equal(publishedStart, 8);
+  assert.equal(reading.stamp, 8, "the player was told 8 s and must be given 8 s");
+});

package/test/read-window.test.js

@@ -19,7 +19,11 @@ import { EventEmitter } from "node:events";
 import os from "node:os";
 import path from "node:path";
 import fs from "node:fs/promises";
-import { readFragments, readWindowFor } from "../services/torrent-worker/piece-reader.js";
+import {
+  nextWindowPieces,
+  readFragments,
+  readWindowFor
+} from "../services/torrent-worker/piece-reader.js";
 import { SharedPieceStore } from "../services/piece-store/shared-piece-store.js";
 
 const PIECE = 1024;
@@ -276,3 +280,50 @@ test("a reader that is abandoned mid-fragment does not keep the piece pinned", a
     await fs.rm(directory, { recursive: true, force: true });
   }
 });
+
+// ------------------------------------------ the window that grows into a lead
+
+test("a wait that mattered widens the window by a piece", () => {
+  // Field 2026-08-17: 5.1-5.9 MB/s delivered against ~1 MB/s consumed, and the
+  // reader still blocked 47 times in two minutes. The surplus never became
+  // distance ahead of the head.
+  assert.equal(
+    nextWindowPieces({ current: 4, base: 4, ceiling: 12, waitedMs: 1457, waitThresholdMs: 1000 }),
+    5
+  );
+});
+
+test("a piece that was already there gives a piece back", () => {
+  assert.equal(
+    nextWindowPieces({ current: 7, base: 4, ceiling: 12, waitedMs: 0, waitThresholdMs: 1000 }),
+    6
+  );
+});
+
+test("it never shrinks below what the caller asked for", () => {
+  assert.equal(
+    nextWindowPieces({ current: 4, base: 4, ceiling: 12, waitedMs: 0, waitThresholdMs: 1000 }),
+    4
+  );
+});
+
+test("it never grows past this reader's share of the store", () => {
+  assert.equal(
+    nextWindowPieces({ current: 12, base: 4, ceiling: 12, waitedMs: 4453, waitThresholdMs: 1000 }),
+    12
+  );
+  // A ceiling below the base cannot pull the window under it: the caller sized
+  // the base from the file's own byte rate, and a store too small to hold it is
+  // an argument about memory, not about what the reader needs next.
+  assert.equal(
+    nextWindowPieces({ current: 4, base: 4, ceiling: 1, waitedMs: 2000, waitThresholdMs: 1000 }),
+    4
+  );
+});
+
+test("a wait exactly at the threshold counts as a wait", () => {
+  assert.equal(
+    nextWindowPieces({ current: 4, base: 4, ceiling: 9, waitedMs: 1000, waitThresholdMs: 1000 }),
+    5
+  );
+});

package/test/segment-serve-wiring.test.js

@@ -171,7 +171,7 @@ test("serving a segment records what its real start says about the container's i
 });
 
 test("a segment that exists is served, not reported as still being produced", async (t) => {
-  const { manager, dirPath } = await managerWithReadySegment();
+  const { manager, dirPath, session } = await managerWithReadySegment();
   t.after(async () => {
     await manager.disposeAll();
     await rm(dirPath, { recursive: true, force: true });
@@ -189,12 +189,26 @@ test("a segment that exists is served, not reported as still being produced", as
   const served = Buffer.concat(chunks);
   assert.equal(served.toString("latin1", 4, 8), "moof", "the init header must be stripped off a media segment");
 
-  // The position the PIECE states, carried into the fragment it belongs to.
-  // Reading it is the step that threw in 2.9.124.
+  // Where the PLAYLIST the player holds puts this segment — which is what the
+  // fragment must be stamped with whenever the piece's own position is further
+  // away than a player will bridge. This fixture's piece says 12.5 s while the
+  // playlist says 0, and stamping the piece's figure is what killed a film on
+  // 2026-08-17: the browser asked for two segments 1908 times each over ten
+  // minutes, each served in 4 ms, because a fragment landing 2.5 s from where
+  // it was expected is not recognised as buffered. Reading the piece's own
+  // position still happens — it is the step that threw in 2.9.124, it feeds the
+  // index tally and it corrects the grid for rungs made later — it just no
+  // longer contradicts the timeline the player was sent. See
+  // test/published-timeline.test.js for the rule itself.
   assert.equal(
     Number(served.readBigUInt64BE(served.indexOf("tfdt") + 8)),
-    Math.round(SEGMENT_START_SECONDS * VIDEO_TIMESCALE),
-    "the segment must be stamped with where it really begins"
+    0,
+    "the segment must be stamped where the playlist the player holds says it begins"
+  );
+  assert.equal(
+    session.indexCheck.checked,
+    1,
+    "and the piece's own position must still have been read, or nothing measures the index"
   );
 });