@torrent-tv/proxy 2.43.1 → 2.44.0

package/services/torrent-worker/subtitle-cues.js

@@ -99,7 +99,7 @@ function readHeld(file, start, end) {
 async function planFor(torrent, fileIndex, key) {
   let state = byFile.get(key);
   if (!state) {
-    state = { plan: null, harvested: new Map(), cues: new Map() };
+    state = { plan: null, harvested: new Map(), cues: new Map(), seq: new Map(), walked: new Set() };
     byFile.set(key, state);
   }
   if (state.plan !== null) {
@@ -154,6 +154,31 @@ async function planFor(torrent, fileIndex, key) {
   return state.plan;
 }
 
+/**
+ * The order a cue was FOUND in, which is the only cursor a browser can follow.
+ *
+ * A cue's TIME cannot serve as one. Cues are harvested out of whichever
+ * clusters happen to be downloaded, and those are not contiguous, so the set
+ * grows in the middle as well as at the end. A browser that remembered "the
+ * latest time I hold" and asked for everything past it would never be sent the
+ * cues that turn up BEHIND that mark afterwards — which is exactly the stretch
+ * it is about to play. Measured 2026-08-20 on a viewer at 272 s: one answer
+ * carried cues out to 1176 s, and from then on every cue between the two was
+ * filtered away for the rest of the session, with 59 of 276 clusters read.
+ *
+ * Found-order is monotonic by construction, so `?since=<n>` is exact however
+ * the file arrives.
+ *
+ * @param {{ seq: Map<number, number> }} state
+ * @param {number} trackNumber
+ * @returns {number}
+ */
+function nextSeq(state, trackNumber) {
+  const next = (state.seq.get(trackNumber) ?? 0) + 1;
+  state.seq.set(trackNumber, next);
+  return next;
+}
+
 /**
  * Every cue of one track that can be read from what is already downloaded.
  *
@@ -201,7 +226,12 @@ export async function cuesHeldFor(torrent, fileIndex, sourceKey, trackNumber) {
       harvested.add(sample.offset);
       const text = decodeSubtitleSample(bytes, track.codecId);
       if (text) {
-        cues.push({ startSeconds: sample.startSeconds, endSeconds: sample.endSeconds, text });
+        cues.push({
+          startSeconds: sample.startSeconds,
+          endSeconds: sample.endSeconds,
+          text,
+          seq: nextSeq(state, trackNumber)
+        });
       }
     }
     cues.sort((left, right) => left.startSeconds - right.startSeconds);
@@ -213,8 +243,24 @@ export async function cuesHeldFor(torrent, fileIndex, sourceKey, trackNumber) {
     };
   }
 
-  for (const position of track.clusterPositions) {
-    if (harvested.has(position)) {
+  // ONE walk for the whole file, not one per track. A Matroska cluster carries
+  // the blocks of every track that has anything to say over its span, so the
+  // bytes that answer one track answer them all — and reading them once per
+  // track meant the same cluster was fetched and parsed as many times as the
+  // film has subtitle tracks. Measured 2026-08-20 on a film with five: five
+  // requests every fifteen seconds, each costing 0.2-5.2 s of container
+  // reading, for cues that together weigh a few kilobytes.
+  //
+  // The union of the tracks' cluster lists is what gets walked: each track's
+  // list comes from its own Cues entries, so they overlap but do not coincide.
+  const positions = new Set();
+  for (const candidate of plan.tracks) {
+    for (const position of candidate.clusterPositions ?? []) {
+      positions.add(position);
+    }
+  }
+  for (const position of [...positions].sort((left, right) => left - right)) {
+    if (state.walked.has(position)) {
       continue;
     }
     // The header first: it says how long the cluster is, and a cluster whose
@@ -225,7 +271,7 @@ export async function cuesHeldFor(torrent, fileIndex, sourceKey, trackNumber) {
     const probe = await readHeld(file, position, Math.min(file.length - 1, position + CLUSTER_HEADER_PROBE - 1));
     const header = probe && [...iterateElements(probe, 0, probe.length)][0];
     if (!header || header.size <= 0 || header.size > MAX_CLUSTER_BYTES) {
-      harvested.add(position); // not a cluster we can read; do not look again
+      state.walked.add(position); // not a cluster we can read; do not look again
       continue;
     }
     const last = Math.min(file.length - 1, position + header.dataOffset + header.size - 1);
@@ -236,18 +282,33 @@ export async function cuesHeldFor(torrent, fileIndex, sourceKey, trackNumber) {
     if (!bytes) {
       continue;
     }
-    harvested.add(position);
-    for (const cue of harvestCluster(bytes, trackNumber, plan.secondsPerTick)) {
-      cues.push(cue);
+    state.walked.add(position);
+    for (const candidate of plan.tracks) {
+      let into = state.cues.get(candidate.trackNumber);
+      if (!into) {
+        into = [];
+        state.cues.set(candidate.trackNumber, into);
+      }
+      let found = false;
+      for (const cue of harvestCluster(bytes, candidate.trackNumber, plan.secondsPerTick)) {
+        cue.seq = nextSeq(state, candidate.trackNumber);
+        into.push(cue);
+        found = true;
+      }
+      if (found) {
+        into.sort((left, right) => left.startSeconds - right.startSeconds);
+      }
     }
   }
-  cues.sort((left, right) => left.startSeconds - right.startSeconds);
   return {
-    cues,
-    coveredClusters: harvested.size,
+    cues: state.cues.get(trackNumber) ?? [],
+    // Every track is filled by the same walk, so this is a fact about the FILE
+    // and reads the same whichever track asked.
+    coveredClusters: state.walked.size,
     indexedClusters: track.clusterPositions.length,
     track
   };
+
 }
 
 /**

package/test/subtitle-cursor.test.js

@@ -0,0 +1,63 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+/**
+ * The rule this pins: a subtitle cursor counts the order cues were FOUND, not
+ * where they sit in the film.
+ *
+ * Cues are read out of whichever clusters happen to be downloaded, and a
+ * torrent does not arrive in film order — a seek pulls a later stretch first,
+ * and the earlier one fills in afterwards. So the set of known cues grows in
+ * the MIDDLE as well as at the end.
+ *
+ * A cursor in film time cannot survive that: measured 2026-08-20 on a viewer at
+ * 272 s, one answer carried cues out to 1176 s, and from that moment every cue
+ * between the two was filtered away for the rest of the session — the stretch
+ * they were about to watch. 59 of 276 clusters had been read.
+ *
+ * The filter below is the route's, written out so the property can be checked
+ * without a torrent: `?since=<n>` selects by found-order, `?after=<seconds>` is
+ * the old behaviour kept for an older browser.
+ */
+const bySince = (cues, since) => cues.filter((cue) => (Number(cue.seq) || 0) > since);
+const byAfter = (cues, after) => cues.filter((cue) => cue.startSeconds > after);
+
+/** A late-arriving cluster from EARLIER in the film than what is already held. */
+const held = [
+  { startSeconds: 40, text: "found first, early in the film", seq: 1 },
+  { startSeconds: 1176, text: "found second, far ahead", seq: 2 },
+  { startSeconds: 300, text: "found third, behind the furthest held", seq: 3 }
+];
+
+test("a cue found after a further-ahead one is still delivered", () => {
+  // The browser holds seq 1 and 2 and asks for what came after.
+  const fresh = bySince(held, 2);
+  assert.deepEqual(fresh.map((cue) => cue.startSeconds), [300]);
+});
+
+test("the same case in film time loses that cue for ever", () => {
+  // This is what shipped in 2.43.1 and what the field session showed: the
+  // browser's furthest cue is 1176 s, so the 300 s cue can never reach it.
+  const fresh = byAfter(held, 1176);
+  assert.deepEqual(fresh.map((cue) => cue.startSeconds), []);
+});
+
+test("a browser asking for the first time is sent everything", () => {
+  assert.equal(bySince(held, 0).length, 3);
+});
+
+test("nothing new is answered with nothing", () => {
+  assert.deepEqual(bySince(held, 3), []);
+});
+
+test("the cursor to send back is the highest found-order held", () => {
+  const cursor = held.reduce((highest, cue) => Math.max(highest, Number(cue.seq) || 0), 0);
+  assert.equal(cursor, 3);
+});
+
+test("a cursor is unaffected by the order cues are sorted into", () => {
+  // The list is kept in film order for the WebVTT it becomes; the cursor must
+  // not depend on that.
+  const sorted = [...held].sort((left, right) => left.startSeconds - right.startSeconds);
+  assert.deepEqual(bySince(sorted, 2).map((cue) => cue.startSeconds), [300]);
+});

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

@@ -39,6 +39,7 @@ function familyAtBoundaryTwo() {
     runState: ENCODE_RUN_STATE.PRODUCING,
     segmentBoundaries: [...BOUNDARIES],
     encodeStartIndex: 2,
+    runSerial: 0,
     audioRenditionSessions: new Map([[1, "sound"]]),
     indexCheck: null
   };
@@ -112,3 +113,29 @@ test("a member that is not running is left alone", () => {
   assert.equal(sound.runState, ENCODE_RUN_STATE.STOPPED);
   assert.notEqual(INITIAL_RUN_STATE, ENCODE_RUN_STATE.STOPPED);
 });
+
+test("a soundtrack does not move the grid the picture is cut on", () => {
+  const { manager, picture, sound } = familyAtBoundaryTwo();
+  const pictureBefore = [...picture.segmentBoundaries];
+  const soundBefore = [...sound.segmentBoundaries];
+
+  // The sound reports where IT began, which is where it was asked to begin, to
+  // within one audio frame. The picture's own boundary is a keyframe of the
+  // file and can be seconds away from that — both readings correct, about
+  // different things.
+  //
+  // Field 2026-08-20: boundary #521 of one film was corrected 2086.084 →
+  // 2084.082 by the picture and 2084.082 → 2086.033 by the sound 1.6 s later,
+  // 1.951 s apart, each overwriting the other for as long as the film ran. The
+  // table never converged, so the guard that stops a correction the table
+  // already holds never fired.
+  manager.correctBoundaryFromSegment(sound, 2, 10.5);
+
+  assert.deepEqual(
+    picture.segmentBoundaries,
+    pictureBefore,
+    "the grid is the picture's cut list and a soundtrack may not move it"
+  );
+  assert.deepEqual(sound.segmentBoundaries, soundBefore);
+  assert.equal(picture.runSerial, 0, "and nothing is restarted on a soundtrack's say-so");
+});