@torrent-tv/proxy 2.25.1 → 2.27.0

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 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.
+
 ## 2.25.1
 
 - **Fix**: Picture and sound are back in step. Two releases in a row moved a segment's stamp toward the playlist — 2.24.1 per session, 2.25.0 by one offset for the whole family — and both desynced playback in the field the same day. The reason is what the first segment of a run is: it is not CUT at all, it begins where ffmpeg's seek landed, and the picture must land on a keyframe while the sound needs none, so after every restart the two runs genuinely begin at different real times and the whole run carries that difference (measured: the sound's #292 began at 1587.892 s and #293 at 1592.692 s, one segment apart, the run shifted 2.5 s from the grid). Labelling each track with its own true time is what keeps them together in real time; a segment is stamped with its own start again, as it was for weeks before 2.24.1. What stays from those releases is the part that was right: one published timeline per family, and a warning when a piece lands further from the playlist than a player will bridge.

package/package.json

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

@@ -202,6 +202,18 @@ export function newIndexCheck() {
     disagreed: 0,
     maxDeviationSec: 0,
     firstDisagreementIndex: -1,
+    // Every deviation, so the summary can report a distribution instead of one
+    // extreme. Bounded by the number of distinct boundaries a session produces.
+    deviations: [],
+    // Of the segments that started away from the playlist, how many began at
+    // ANOTHER time in the very list the grid was built from. This is the
+    // measurement that separates the two explanations: a table that describes
+    // times the file does not have, against a table that lists only SOME
+    // keyframes and a grid built over its gaps. Asked 2026-08-17 by the user,
+    // who was right that the second is far more likely — every deviation
+    // measured that day was positive, 0.58-2.96 s, which is what a cut pushed
+    // forward to the next real keyframe looks like.
+    landedOnAnotherKeyframe: 0,
     // Which boundaries have been counted. A segment can be requested again, and
     // a repeat is the same boundary, not new evidence.
     seen: new Set()
@@ -217,12 +229,17 @@ export function newIndexCheck() {
  *   start the playlist declared for it.
  * @returns {void}
  */
-export function noteIndexDeviation(check, index, deviationSec) {
+export function noteIndexDeviation(check, index, deviationSec, landedOnKeyframe = null) {
   if (check.seen.has(index)) {
     return;
   }
   check.seen.add(index);
   check.checked += 1;
+  check.deviations ??= [];
+  check.deviations.push(deviationSec);
+  if (landedOnKeyframe === true) {
+    check.landedOnAnotherKeyframe = (check.landedOnAnotherKeyframe ?? 0) + 1;
+  }
   if (deviationSec > SEGMENT_START_DISAGREEMENT_SEC) {
     check.disagreed += 1;
     if (check.firstDisagreementIndex < 0) {
@@ -4786,7 +4803,14 @@ export class HlsSessionManager {
   #noteIndexAccuracy(session, index, trueStart, declaredStart) {
     const deviation = Math.abs(trueStart - declaredStart);
     session.indexCheck ??= newIndexCheck();
-    noteIndexDeviation(session.indexCheck, index, deviation);
+    // Did this segment begin at ANOTHER keyframe from the same list? Half an
+    // audio frame is the tolerance — anything the list names is exact, so a
+    // match is a match. `keyframeTimes` is the list the grid was built from, so
+    // this compares the file against the table on the table's own terms.
+    const knownKeyframe = Array.isArray(session.keyframeTimes)
+      ? session.keyframeTimes.some((time) => Math.abs(time - trueStart) <= 0.05)
+      : null;
+    noteIndexDeviation(session.indexCheck, index, deviation, knownKeyframe);
     if (deviation > SEGMENT_START_DISAGREEMENT_SEC) {
       // Which boundary the true start DOES match, if any. This is what tells
       // the two possible faults apart, and they need opposite fixes: matching
@@ -4808,6 +4832,14 @@ export class HlsSessionManager {
           : "the container's keyframe index disagrees with the file; using the file")
       );
     }
+    // Said as the evidence accumulates, not only when the session is disposed.
+    // A proxy restart takes its sessions with it — every addon update does —
+    // and a summary that only ever appears at the end is a summary that is
+    // routinely never written. Twenty-five distinct boundaries is enough for
+    // the proportion to mean something and rare enough not to repeat itself.
+    if (session.indexCheck.checked > 0 && session.indexCheck.checked % 25 === 0) {
+      this.#logIndexAccuracy(session);
+    }
     this.correctBoundaryFromSegment(session, index, trueStart);
   }
 
@@ -4864,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(() => {});
+    }
   }
 
   /**
@@ -4974,12 +5044,19 @@ export class HlsSessionManager {
     if (!check || check.checked === 0) {
       return;
     }
+    const deviations = [...(check.deviations ?? [])].sort((left, right) => left - right);
+    const median = deviations.length > 0 ? deviations[Math.floor(deviations.length / 2)] : 0;
+    const landed = check.landedOnAnotherKeyframe ?? 0;
     logger.info(
       `keyframe-index ${session.containerFormat || "unknown"} "${session.fileName}": ` +
       `${check.disagreed} of ${check.checked} produced segments started away from the playlist, ` +
-      `worst ${check.maxDeviationSec.toFixed(3)}s` +
+      `median ${median.toFixed(3)}s worst ${check.maxDeviationSec.toFixed(3)}s` +
       (check.firstDisagreementIndex >= 0 ? ` (first at #${check.firstDisagreementIndex})` : "") +
-      ` [tolerance ${SEGMENT_START_DISAGREEMENT_SEC}s]`
+      // The discriminator, stated in the same line as the count it explains: a
+      // segment that began at another time the SAME table names was not
+      // mis-described by the table — the grid was built over a gap in it.
+      `; ${landed} of them began at another keyframe the table names` +
+      ` [tolerance ${SEGMENT_START_DISAGREEMENT_SEC}s, ${(session.keyframeTimes?.length ?? 0)} keyframes read]`
     );
   }
 

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