@torrent-tv/proxy 2.9.123 → 2.9.124

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2.9.124
+
+- **Fix**: Subtitles no longer drift away from the picture. A segment was stamped with the time the PLAYLIST assigned it, and the playlist is built from the container keyframe index — which can be wrong. Measured 2026-08-06 on a Matroska file whose index claimed a keyframe at 157.99 s where the real ones were 153.820 and 164.247: ffmpeg cut at 153.820, the stamp said 157.99, and the player was told that picture belonged 4.17 s later than it did. Subtitles, extracted straight from the source with no offset of any kind, kept the true times, so speech and text sat 4.17 s apart for the whole stretch. The stamp now comes from the piece itself — the muxer records its position as an empty edit at the head of the track edit list, read before the header is stripped — and falls back to the playlist only when the piece does not say. Identical to the old figure whenever the index is honest, so a well-formed file is unaffected. When the two disagree by more than a quarter of a second the log names both, so an index that lies is visible rather than merely felt. Verified against ffmpeg on pieces cut the same way (12/30/36 s read back exactly), and covered by tests including a 64-bit edit list and a non-default movie timescale.
+
 ## 2.9.123
 
 - **Fix**: The check added in 2.9.121 was deleting the file an encoder was writing into. A segment short of a track means one of two very different things — left behind by a run that was killed, or simply not finished yet — and treating them alike removed the file mid-write, after which ffmpeg went on writing to something nobody could open and the segment never appeared. Measured 2026-08-06: segment #225 was deleted 14 s into the run producing it and answered 404 thirty-three seconds later. The readiness rule could not prevent it, because it waves a segment through once the NEXT one exists and that next one had been left by an older run. Ownership decides it now: the current run writes from its start index upwards, so a file at or above that index while the run is alive is unfinished and is waited for, and only a file below it, or any file once no run is producing, is a leftover worth removing.

package/package.json

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

package/services/hls-session-manager.js

@@ -3453,8 +3453,34 @@ export class HlsSessionManager {
           }
           return { kind: "warming-up" };
         }
+        // Where this segment REALLY begins, taken from the piece itself, and
+        // only from the playlist when the piece does not say.
+        //
+        // The playlist's own answer is built from the container's keyframe
+        // index, and an index can be wrong: measured 2026-08-06 on a Matroska
+        // file whose index claimed a keyframe at 157.99 s where the real ones
+        // were 153.82 and 164.247. ffmpeg cut at 153.82, and stamping that
+        // picture with 157.99 told the player it belonged four seconds later
+        // than it did — while subtitles, extracted straight from the source,
+        // kept the true times. Speech and text drifted apart by 4.17 s.
+        //
+        // Read from `raw`, before the header is stripped: the position lives
+        // in an empty edit in the piece's own `moov`, which `stripInit`
+        // removes. Identical to the playlist's figure whenever the index is
+        // honest, so nothing changes for a well-formed file.
+        const trueStart = session.usesExplicitCuts
+          ? session.segmentFormat.readSegmentStartSeconds?.(raw) ?? null
+          : null;
+        const declaredStart = this.#segmentStartTime(session, index);
+        if (trueStart !== null && Math.abs(trueStart - declaredStart) > SEGMENT_START_DISAGREEMENT_SEC) {
+          logger.warn(
+            `transcode ${session.id} segment #${index} really starts at ` +
+            `${trueStart.toFixed(3)}s, the playlist says ${declaredStart.toFixed(3)}s — ` +
+            "the container's keyframe index disagrees with the file; using the file"
+          );
+        }
         const prepared = session.segmentFormat.prepareSegmentBytes(bytes, {
-          startSeconds: this.#segmentStartTime(session, index),
+          startSeconds: trueStart ?? declaredStart,
           initBytes: session.initBytes ?? null
         });
         return {

package/services/segment-formats/fmp4.js

@@ -189,6 +189,21 @@ export const fmp4Format = {
     return match ? Number(match[1]) : -1;
   },
 
+  /**
+   * Where a self-contained piece says it begins, in seconds, or null.
+   *
+   * Only the pieces the `segment` muxer writes carry this — they have their
+   * own `moov` — which is exactly the path where the playlist's own answer
+   * can be wrong. Must be given the piece BEFORE {@link stripInit}, since that
+   * removes the header the position lives in.
+   *
+   * @param {Buffer} piece
+   * @returns {number | null}
+   */
+  readSegmentStartSeconds(piece) {
+    return readSelfContainedStartSeconds(piece);
+  },
+
   /**
    * fMP4 segments must be read into memory and corrected before being served —
    * see {@link stampSegmentStartTime} for the full reasoning. Without this a

package/services/segment-formats/mp4-boxes.js

@@ -183,3 +183,65 @@ export function stampSegmentStartTime(segment, startSeconds, trackTimescales) {
   });
   return stamped;
 }
+
+/**
+ * Where a self-contained piece really begins, in seconds, or null.
+ *
+ * The `segment` muxer writes each piece with its own `moov`, and puts the
+ * piece's position on the source timeline into an EMPTY EDIT at the head of the
+ * track's edit list: an entry whose `media_time` is -1 and whose duration, in
+ * the movie timescale, is the offset. That is the piece's own account of where
+ * it sits, and it is the only honest one available.
+ *
+ * It matters because the alternative — the time the playlist ASSIGNED to that
+ * segment — can be wrong. The playlist is built from the container's keyframe
+ * index, and an index can list times that are not keyframes: measured
+ * 2026-08-06 on a Matroska file whose index claimed one at 157.99 s while the
+ * real keyframes were at 153.82 and 164.247. The cut therefore produced a piece
+ * starting at 153.82, and stamping it with the playlist's 157.99 told the
+ * player that picture belonged four seconds later than it did — while the
+ * subtitles, extracted straight from the source, kept the true times. The
+ * result was a steady 4.17 s desync between speech and text.
+ *
+ * @param {Buffer} piece
+ * @returns {number | null} Seconds, or null when the piece carries no edit list.
+ */
+export function readSelfContainedStartSeconds(piece) {
+  let movieTimescale = 0;
+  let startSeconds = null;
+  walkBoxes(piece, (type, bodyStart, bodyEnd) => {
+    if (type === "mvhd" && movieTimescale === 0) {
+      const version = piece[bodyStart];
+      const offset = version === 1 ? bodyStart + 20 : bodyStart + 12;
+      if (offset + 4 <= piece.length) {
+        movieTimescale = piece.readUInt32BE(offset);
+      }
+      return;
+    }
+    if (type !== "elst" || startSeconds !== null || movieTimescale === 0) {
+      return;
+    }
+    const version = piece[bodyStart];
+    const entryStart = bodyStart + 8;
+    if (version === 1) {
+      if (entryStart + 16 > bodyEnd) {
+        return;
+      }
+      const duration = Number(piece.readBigUInt64BE(entryStart));
+      const mediaTime = piece.readBigInt64BE(entryStart + 8);
+      if (mediaTime === -1n) {
+        startSeconds = duration / movieTimescale;
+      }
+      return;
+    }
+    if (entryStart + 8 > bodyEnd) {
+      return;
+    }
+    const duration = piece.readUInt32BE(entryStart);
+    const mediaTime = piece.readInt32BE(entryStart + 4);
+    if (mediaTime === -1) {
+      startSeconds = duration / movieTimescale;
+    }
+  });
+  return startSeconds;
+}

package/test/segment-true-start.test.js

@@ -0,0 +1,86 @@
+/**
+ * @file A segment must be stamped with where it really begins.
+ *
+ * The playlist's answer comes from the container's keyframe index, and an index
+ * can be wrong. Measured 2026-08-06 on a Matroska file whose index claimed a
+ * keyframe at 157.99 s: the real ones around there were 153.820 and 164.247, so
+ * ffmpeg cut at 153.820 and the segment was stamped 157.99 — telling the player
+ * that picture belonged 4.17 s later than it did, while the subtitles, taken
+ * straight from the source, kept the true times. Speech and text drifted apart
+ * by exactly that much.
+ *
+ * The piece itself knows better: the `segment` muxer records its position as an
+ * empty edit at the head of the track's edit list.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readSelfContainedStartSeconds } from "../services/segment-formats/mp4-boxes.js";
+
+/**
+ * A minimal MP4 carrying `moov > mvhd` and `moov > trak > edts > elst`, with a
+ * leading empty edit of `offsetSeconds`.
+ *
+ * @param {{ offsetSeconds: number, timescale?: number, version?: 0 | 1 }} shape
+ * @returns {Buffer}
+ */
+function pieceWithEmptyEdit({ offsetSeconds, timescale = 1000, version = 0 }) {
+  const box = (type, body) => {
+    const head = Buffer.alloc(8);
+    head.writeUInt32BE(8 + body.length, 0);
+    head.write(type, 4, "latin1");
+    return Buffer.concat([head, body]);
+  };
+
+  const mvhd = Buffer.alloc(100);
+  mvhd.writeUInt8(0, 0);                       // version 0
+  mvhd.writeUInt32BE(timescale, 12);           // timescale
+
+  const duration = Math.round(offsetSeconds * timescale);
+  let elstBody;
+  if (version === 1) {
+    elstBody = Buffer.alloc(8 + 20);
+    elstBody.writeUInt8(1, 0);
+    elstBody.writeUInt32BE(1, 4);              // one entry
+    elstBody.writeBigUInt64BE(BigInt(duration), 8);
+    elstBody.writeBigInt64BE(-1n, 16);         // empty edit
+  } else {
+    elstBody = Buffer.alloc(8 + 12);
+    elstBody.writeUInt8(0, 0);
+    elstBody.writeUInt32BE(1, 4);              // one entry
+    elstBody.writeUInt32BE(duration, 8);
+    elstBody.writeInt32BE(-1, 12);             // empty edit
+  }
+
+  return Buffer.concat([
+    box("ftyp", Buffer.alloc(16)),
+    box("moov", Buffer.concat([
+      box("mvhd", mvhd),
+      box("trak", box("edts", box("elst", elstBody)))
+    ]))
+  ]);
+}
+
+test("the position is read from the empty edit, in seconds", () => {
+  assert.equal(readSelfContainedStartSeconds(pieceWithEmptyEdit({ offsetSeconds: 153.82 })), 153.82);
+  assert.equal(readSelfContainedStartSeconds(pieceWithEmptyEdit({ offsetSeconds: 0 })), 0);
+});
+
+test("a 64-bit edit list is read the same way", () => {
+  const piece = pieceWithEmptyEdit({ offsetSeconds: 4321.5, version: 1 });
+  assert.equal(readSelfContainedStartSeconds(piece), 4321.5);
+});
+
+test("the movie timescale is honoured, not assumed", () => {
+  const piece = pieceWithEmptyEdit({ offsetSeconds: 12.5, timescale: 90_000 });
+  assert.equal(
+    readSelfContainedStartSeconds(piece),
+    12.5,
+    "reading the duration without dividing by the file's own timescale would give 1 125 000"
+  );
+});
+
+test("a piece with no edit list says nothing rather than guessing", () => {
+  const bare = Buffer.concat([Buffer.alloc(8), Buffer.from("ftyp", "latin1")]);
+  assert.equal(readSelfContainedStartSeconds(bare), null);
+});