@torrent-tv/proxy 2.26.0 → 2.28.0

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 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.
+
 ## 2.26.0
 
 - **New**: The keyframe-index measurement now answers the question it was raising. Each file's summary reports the distribution of how far produced segments fell from the playlist (median and worst, not one extreme), how many keyframes were read from the container, and — the discriminator — **how many of the disagreeing segments began at ANOTHER time the same table names**. That separates the two explanations that have been argued rather than measured: a table describing times the file does not have, against a table listing only some keyframes with our grid built over its gaps. Every deviation measured on 2026-08-17 was positive, 0.58-2.96 s, which is what a cut pushed forward to the next real keyframe looks like. The summary is also written every 25 distinct boundaries instead of only when a session is disposed, because a proxy restart — every addon update is one — takes its sessions with it and the summary was routinely never written.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.26.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
@@ -4896,6 +4941,44 @@ export class HlsSessionManager {
       `transcode ${session.id} boundary #${index} corrected ${wasAt.toFixed(3)}s → ` +
       `${trueStart.toFixed(3)}s from the file itself`
     );
+    // And every OTHER member whose run begins at this very boundary is moved
+    // to the same instant.
+    //
+    // Why they were not there already: the two branches are asked for the same
+    // time and land in different places. The picture cannot begin anywhere but
+    // a real keyframe, and it may not begin before the time asked for — that
+    // content belongs to the previous segment — so it moves FORWARD to the next
+    // one, by up to the keyframe spacing (0.58-2.96 s measured 2026-08-17).
+    // A soundtrack has no keyframes: it begins exactly where asked, to within
+    // one audio frame. So after every restart the two runs of one film began up
+    // to three seconds apart, each correctly labelled with where it really was,
+    // and the viewer got sound with no new picture for the difference.
+    //
+    // The picture's true start is a MEASURED quantity — read from the piece it
+    // just produced, which is what the correction above is — so the soundtrack
+    // can be put exactly there instead of at the time the container's table
+    // claimed. It converges: once the boundary holds the true time, the next
+    // reading agrees with it and the guard above returns before doing anything.
+    for (const member of this.#familyOf(session)) {
+      if (member === session || member.encodeStartIndex !== index) {
+        continue;
+      }
+      if (!processCanBeSignalled(member.runState)) {
+        continue;
+      }
+      logger.info(
+        `transcode ${member.id} begins at #${index}, which really starts ` +
+        `${(trueStart - wasAt).toFixed(3)}s later than the table said — restarting it there ` +
+        `so picture and sound begin together`
+      );
+      // Restarted at the same INDEX, deliberately, rather than seeked to the
+      // time: a seek decides by index, finds this run already begins at #index,
+      // and answers "already within the running encode" — which is true about
+      // the index and false about the instant, and it is why the first version
+      // of this fix moved nothing at all. The boundary now holds the corrected
+      // time, so starting the run at this index starts it at that time.
+      void this.#startEncodeRun(member, index).catch(() => {});
+    }
   }
 
   /**

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);
+});

package/test/tracks-begin-together.test.js

@@ -0,0 +1,114 @@
+/**
+ * @file Picture and sound must begin their runs at the same real instant.
+ *
+ * The two branches are asked for the same time and land in different places: a
+ * copied picture may only begin at a real keyframe and may not begin before the
+ * time asked for, so it moves FORWARD to the next one; a soundtrack has no
+ * keyframes and begins exactly where asked. Measured 2026-08-17, the difference
+ * was 0.58-2.96 s on one file, and the viewer got sound with no new picture for
+ * as long as it lasted.
+ *
+ * The picture's true start is measured from the piece it produced. This pins
+ * that the measurement is carried to the other members of the family.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { HlsSessionManager } from "../services/hls-session-manager.js";
+import { ENCODE_RUN_STATE, INITIAL_RUN_STATE } from "../services/encode-run-state.js";
+
+const BOUNDARIES = [0, 4, 8, 12, 16, 20];
+
+/**
+ * A film's family: the picture, and a soundtrack rendition of it. Both runs
+ * begin at boundary #2, which the container's table puts at 8 s.
+ *
+ * @returns {{ manager: HlsSessionManager, picture: object, sound: object }}
+ */
+function familyAtBoundaryTwo() {
+  const manager = new HlsSessionManager({
+    enabled: true,
+    ffmpegBin: "ffmpeg",
+    localBindHost: "127.0.0.1",
+    localPort: 9090
+  });
+  const picture = {
+    id: "picture",
+    state: "ready",
+    runState: ENCODE_RUN_STATE.PRODUCING,
+    segmentBoundaries: [...BOUNDARIES],
+    encodeStartIndex: 2,
+    audioRenditionSessions: new Map([[1, "sound"]]),
+    indexCheck: null
+  };
+  const sound = {
+    id: "sound",
+    state: "ready",
+    runState: ENCODE_RUN_STATE.PRODUCING,
+    audioOnly: true,
+    baseSessionId: "picture",
+    segmentBoundaries: [...BOUNDARIES],
+    encodeStartIndex: 2,
+    runSerial: 0,
+    indexCheck: null
+  };
+  manager.sessionsById.set("picture", picture);
+  manager.sessionsById.set("sound", sound);
+
+  return { manager, picture, sound };
+}
+
+test("a soundtrack follows the picture to the instant the picture really began", () => {
+  const { manager, picture, sound } = familyAtBoundaryTwo();
+  const runsBefore = sound.runSerial;
+
+  manager.correctBoundaryFromSegment(picture, 2, 10.5);
+
+  assert.deepEqual(
+    picture.segmentBoundaries,
+    [0, 4, 10.5, 12, 16, 20],
+    "the family's table must hold what the file itself said"
+  );
+  assert.equal(
+    sound.segmentBoundaries[2],
+    10.5,
+    "and every member's table with it — one film, one timeline"
+  );
+  // A NEW run, not a seek. A seek decides by index, finds the soundtrack
+  // already begins at #2 and answers "already within the running encode" —
+  // true about the index, false about the instant. The first version of this
+  // fix did exactly that and moved nothing.
+  //
+  // `runSerial` is the evidence because it is the first thing a run start
+  // writes, before it awaits anything: the assertion then holds without the
+  // test needing a filesystem, a process, or a guess about how many ticks to
+  // wait for one.
+  assert.equal(
+    sound.runSerial,
+    runsBefore + 1,
+    "the soundtrack's run must be started again, at the corrected time"
+  );
+});
+
+test("a correction the table already holds moves nobody", () => {
+  const { manager, picture, sound } = familyAtBoundaryTwo();
+  const before = [...sound.segmentBoundaries];
+  // Within the tolerance: the reading agrees with the table, so there is
+  // nothing to correct and nothing to move. This is what makes the repositioning
+  // converge instead of repeating on every produced segment.
+  manager.correctBoundaryFromSegment(picture, 2, 8.1);
+  assert.deepEqual(sound.segmentBoundaries, before);
+});
+
+test("a member that is not running is left alone", () => {
+  const { manager, picture, sound } = familyAtBoundaryTwo();
+  // A rung the viewer switched away from has no process. Moving it would start
+  // an encoder for nobody — the failure that put three ffmpeg runs on one file.
+  sound.runState = ENCODE_RUN_STATE.STOPPED;
+  manager.correctBoundaryFromSegment(picture, 2, 10.5);
+  assert.equal(sound.runSerial, 0, "a stopped member is not started again for nobody");
+  assert.equal(sound.encodeStartIndex, 2, "a stopped member keeps its place and its silence");
+  assert.equal(sound.runState, ENCODE_RUN_STATE.STOPPED);
+  assert.notEqual(INITIAL_RUN_STATE, ENCODE_RUN_STATE.STOPPED);
+});