@torrent-tv/proxy 2.24.0 → 2.24.1

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 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.24.1",
   "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.
  *
@@ -1898,6 +1909,12 @@ export class HlsSessionManager {
       containerFormat,
       indexCheck: newIndexCheck(),
       playlistText: hasDuration ? this.#buildVodPlaylist(segmentBoundaries, segmentFormat) : "",
+      // The table AS PUBLISHED, frozen the moment the playlist text is written
+      // from it. `segmentBoundaries` keeps being corrected from produced
+      // segments — that is what makes a re-encoded rung cut like the copy it
+      // joins — but the player's own copy of the timeline never changes, and a
+      // segment must be stamped against the copy the player has.
+      publishedBoundaries: hasDuration ? [...segmentBoundaries] : null,
       // Segment index the current ffmpeg run started producing from.
       encodeStartIndex: 0,
       // Guards against repeatedly restarting to the same seek position.
@@ -2323,6 +2340,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.
@@ -6960,8 +7036,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/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/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"
   );
 });