@torrent-tv/proxy 2.26.0 → 2.27.0

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 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.27.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

@@ -4896,6 +4896,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/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);
+});