@torrent-tv/proxy 2.27.0 → 2.28.0

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2.28.0
+
+- **Fix**: The playlist and the media agree again, and the container's keyframe table was never at fault. On a file whose first timestamp is 2.002 s, the copied picture was asked to cut at 808.808 s on the 0-based grid and cut at 806.806 s — exactly the container's start time early, because that branch keeps the source's own timestamps and re-labels the output afterwards, so a cut list stated in 0-based terms is applied 2 s away from where it means. The soundtrack, re-encoded and on the other branch, cut where it was asked. The two then wrote different values into the shared boundary table and corrected each other for the whole session (#202: 808.808 → 806.806 → 808.750 → …), the playlist drifted a whole segment from the media, and the player refetched fragments it could not place. The cut list is now stated in the source's terms on that branch, which is the same shift the seek on it already applies.
+- **Chore**: Which timeline a session works on is answered by one exported predicate instead of two expressions that could disagree — and their disagreement is exactly what desynced picture from sound. Pinned by `test/cut-times-timeline.test.js`, with the field numbers in its header.
+
 ## 2.27.0
 
 - **Fix**: Picture and sound now begin a run at the same instant. They were asked for the same time and landed in different places: a copied picture may begin only at a real keyframe and may not begin before the time asked for — that content belongs to the previous segment — so it moves FORWARD to the next keyframe, by up to the keyframe spacing (0.58-2.96 s measured on the field file); a soundtrack has no keyframes and begins exactly where asked, to within one audio frame. So after every seek the two runs of one film began up to three seconds apart. The picture's true start is measured from the piece it produces, and that measurement now moves every other member of the family whose run begins at the same boundary. Restarted at the boundary rather than seeked to the time, deliberately: a seek decides by segment index, finds the run already begins there and answers "already within the running encode" — true about the index and false about the instant, which is why the first version of this fix moved nothing at all.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.27.0",
+  "version": "2.28.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

@@ -1019,6 +1019,29 @@ export function ffmpegSeconds(value) {
  * @param {{ useKeyframeGrid: boolean, durationSeconds: number, segDur: number, keyframeTimes: number[] | null, startTime: number }} params
  * @returns {number[]}
  */
+/**
+ * Which timeline a session's own ffmpeg works on.
+ *
+ * True — the COPY branch: the source's timestamps are kept (`-copyts`) and the
+ * output is re-labelled 0-based. Everything handed to the muxer is therefore
+ * stated in the source's terms, and everything read back out of a produced
+ * piece is 0-based.
+ *
+ * False — the re-encode branch: the output is labelled from the run's start on
+ * the 0-based timeline, and the muxer is addressed in those same terms.
+ *
+ * One predicate for both callers, because the two used to answer it separately
+ * and a disagreement between them is exactly what desynced picture from sound.
+ *
+ * @param {{ audioOnly?: boolean, cutGrid?: string, transcodeVideo?: boolean }} session
+ * @returns {boolean}
+ */
+export function onKeyframeGridFor(session) {
+  return session?.audioOnly === true
+    ? session?.cutGrid === "keyframe"
+    : session?.transcodeVideo !== true;
+}
+
 export function computeSegmentBoundaries({ useKeyframeGrid, durationSeconds, segDur, keyframeTimes, startTime }) {
   const total = Number.isFinite(durationSeconds) && durationSeconds > 0 ? durationSeconds : 0;
   const step = Number.isFinite(segDur) && segDur > 0 ? segDur : 4;
@@ -3541,9 +3564,33 @@ export class HlsSessionManager {
     // writes no self-contained pieces, so nothing could read a true start and
     // segments were stamped with times the file does not have — the 4.17 s
     // speech-against-subtitles drift, back again.
-    const cutTimes = explicitTimes && (!session.transcodeVideo || session.cutGrid === "keyframe")
+    const gridCutTimes = explicitTimes && (!session.transcodeVideo || session.cutGrid === "keyframe")
       ? segmentCutTimesFrom(session.segmentBoundaries, safeIndex)
       : null;
+    // On the COPY branch the muxer decides its cuts against the source's own
+    // timestamps, not against the labels we ask it to write. That branch keeps
+    // the source's timestamps (`-copyts`) and re-labels the output 0-based with
+    // `-output_ts_offset -sourceStartTime`; the cut list, being applied before
+    // that relabelling, must therefore be stated in the SOURCE's terms.
+    //
+    // Measured 2026-08-17, and this is the whole of the trouble: asked to cut
+    // at 808.808 s on the 0-based grid, ffmpeg cut at 806.806 s — exactly
+    // `sourceStartTime` (2.002 s) early, and 806.806 s is itself a keyframe the
+    // container's table names, which is why every "disagreement" landed on
+    // another real keyframe. The soundtrack, which is re-encoded and takes the
+    // other branch, cut where it was asked. The two then told the shared
+    // boundary table different things and corrected each other back and forth
+    // for the whole session (#202: 808.808 → 806.806 → 808.750 → …), so the
+    // playlist and the media drifted apart by a whole segment and the player
+    // refetched what it could not place.
+    //
+    // Nothing here is a guess about ffmpeg's semantics: the shift is the same
+    // one the seek already applies on this branch (`seekSeconds = startSeconds
+    // + sourceStartTime`), and the field measurement above is what says the
+    // cuts needed it too.
+    const cutTimes = gridCutTimes && onKeyframeGridFor(session) && sourceStartTime !== 0
+      ? gridCutTimes.map((time) => Number((time + sourceStartTime).toFixed(6)))
+      : gridCutTimes;
 
     // A second chance for a predecessor that survived the escalation above —
     // the first block is the one that does the work. Its exit is ignored
@@ -3641,9 +3688,7 @@ export class HlsSessionManager {
     // the copy branch: `-copyts` and a shift by the container's start time,
     // against a picture labelled from zero. The two would be offset by
     // `sourceStartTime` for the whole file.
-    const onKeyframeGrid = session.audioOnly === true
-      ? session.cutGrid === "keyframe"
-      : !session.transcodeVideo;
+    const onKeyframeGrid = onKeyframeGridFor(session);
     if (!onKeyframeGrid) {
       // Branch A (re-encode): fixed GOP makes keyframes land exactly on the
       // segment grid; relabel output onto the original timeline so segment N

package/test/cut-times-timeline.test.js

@@ -0,0 +1,64 @@
+/**
+ * @file The cut list must be stated on the timeline the muxer decides against.
+ *
+ * Measured 2026-08-17 on a Matroska whose first timestamp is 2.002 s. Asked to
+ * cut at 808.808 s on the 0-based grid, the copied picture cut at 806.806 s —
+ * exactly the container's start time early, and itself a keyframe the file's
+ * own table names, which is why every "disagreement" landed on a real keyframe
+ * and the table looked like it was lying. The soundtrack, re-encoded and on the
+ * other branch, cut where it was asked. The two then wrote different values
+ * into the shared boundary table and corrected each other back and forth
+ * (#202: 808.808 → 806.806 → 808.750), so the playlist and the media drifted
+ * apart by a whole segment.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { onKeyframeGridFor } from "../services/hls-session-manager.js";
+
+test("a copied picture works on the source's timeline", () => {
+  assert.equal(
+    onKeyframeGridFor({ transcodeVideo: false }),
+    true,
+    "video copied means the source's own timestamps are kept"
+  );
+});
+
+test("a re-encoded picture works on the 0-based timeline", () => {
+  assert.equal(onKeyframeGridFor({ transcodeVideo: true }), false);
+});
+
+test("a soundtrack follows the grid it was cut on, not its own encoding", () => {
+  // A rendition is re-encoded by definition, so asking `transcodeVideo` about
+  // it answers nothing. What decides its timeline is the grid it shares with
+  // the picture it plays with.
+  assert.equal(onKeyframeGridFor({ audioOnly: true, cutGrid: "keyframe" }), true);
+  assert.equal(onKeyframeGridFor({ audioOnly: true, cutGrid: "uniform" }), false);
+  assert.equal(
+    onKeyframeGridFor({ audioOnly: true, cutGrid: "keyframe", transcodeVideo: true }),
+    true,
+    "its own encoding must not decide this — that disagreement is the defect"
+  );
+});
+
+test("one predicate answers for every caller", () => {
+  // The two callers used to answer this separately, in two expressions that
+  // could drift apart. A session put through both must get one answer.
+  for (const session of [
+    { transcodeVideo: false },
+    { transcodeVideo: true },
+    { audioOnly: true, cutGrid: "keyframe" },
+    { audioOnly: true, cutGrid: "uniform" },
+    {}
+  ]) {
+    assert.equal(onKeyframeGridFor(session), onKeyframeGridFor({ ...session }));
+  }
+});
+
+test("a session that says nothing is treated as copying", () => {
+  // The default matters: an absent `transcodeVideo` means the picture is
+  // copied, which is the branch that needs the shift.
+  assert.equal(onKeyframeGridFor({}), true);
+  assert.equal(onKeyframeGridFor(null), true);
+});