@torrent-tv/proxy 2.37.0 → 2.38.0

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2.38.0
+
+- **Fix**: An MP4's keyframe times are read as composition times, on the track the handler names. Two faults, both measured on real releases over the swarm (`research/mp4-composition-times-2026-08-19.md`). (1) The reader took sample times from `stts`, which is DECODE order, and used neither `ctts` nor `elst`: ISO/IEC 14496-12 says `CT(n) = DT(n) + CTTS(n)` (§8.6.1.3) and the edit list then shifts that (§8.6.6.3). Every LostFilm MP4 measured carries a composition offset AND an edit list cancelling it exactly, which is why decode times had been right on them; `Firefly.S01E03.720p.mp4` carries the same 2002-tick offset with NO edit list, and its times were **62.1 ms early on all 34 keyframes** compared against ffmpeg's own `pts_time` — a constant that closes to four decimals as offset (0.08342 s) minus the container start (0.02133 s). After the fix that file matches ffmpeg to the container start, which `computeSegmentBoundaries` already subtracts, and `Superman.720p` — where the terms cancel — is unchanged and exact to 0.0000 s. Version 1 offsets are read as SIGNED, which is what that version exists for; an empty edit (`media_time = -1`) is skipped rather than treated as a shift. (2) The video track was "the first one carrying sync samples", and the handler was never read. That worked only because all seven measured files put video first; the standard identifies a track by `hdlr`, and a file whose audio track carries sync samples, or one leading with a cover-art video track, would have been read from the wrong place — the same defect fixed in the Matroska reader the day before, arrived at from the other side.
+
+## 2.37.1
+
+- **Fix**: The cost of a seek no longer counts against the quality offer. `requiredSpeed` — the speed a step must sustain to survive a swarm — is built from the reader's interruptions, and the wait on the first piece after a JUMP is not one of them: those pieces have not been asked for yet and the encoder is restarting, so it measures the move, not the supply. Measured 2026-08-18: `proxy now offers 720p` landed 131 ms after a seek, collapsing a five-rung menu to one while the player was already hunting for a fragment, and another session churned `640p` → `640p 540p` → `640p 240p`. The wait is still reported, saying plainly that it belongs to the jump and is not counted, so a gap in the history cannot be mistaken for a swarm that never made the reader wait.
+
 ## 2.37.0
 
 - **Fix**: The segment the viewer seeks TO is no longer refused as stale. A seek bumps the wait epoch so requests made for the position being LEFT stop being held, and the epoch alone cannot tell those apart from the request for the position just arrived at — hls.js asks for it within milliseconds of the seek, and it raced the bump. Measured 2026-08-18: a seek to 1061.0 s, `segment-00101` answered 503 twice within 80 ms, the player never asked for it again, and instead re-fetched `a/0/segment-00103` and `a/0/segment-00104` **737 and 736 times over 149 seconds** — about half a gigabyte of the same two segments — while the picture stood at `t=1061.0s readyState=1` until the session ended. A held request is now released only when its segment lies behind where the viewer now is, or so far ahead that the running encode will not reach it; anything between is what the viewer is waiting for and is held.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.37.0",
+  "version": "2.38.0",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {

package/services/container-index/mp4.js

@@ -149,7 +149,7 @@ function findAllBoxes(buffer, start, end, type) {
  * @param {Set<number>} wanted - Sample numbers (1-based).
  * @returns {number[]} Seconds, ascending.
  */
-function resolveSampleTimes(buffer, stts, timescale, wanted) {
+function resolveSampleTimes(buffer, stts, timescale, wanted, offsets = null) {
   const entryCount = buffer.readUInt32BE(stts.dataOffset + 4);
   const times = [];
   let sampleNumber = 1;
@@ -160,7 +160,10 @@ function resolveSampleTimes(buffer, stts, timescale, wanted) {
     const delta = buffer.readUInt32BE(cursor + 4);
     for (let index = 0; index < count; index += 1) {
       if (wanted.has(sampleNumber)) {
-        times.push(ticks / timescale);
+        // `CT(n) = DT(n) + CTTS(n)` — ISO/IEC 14496-12 §8.6.1.3. The offset is
+        // what turns decode order into the order frames are shown in, and it is
+        // the timeline ffmpeg cuts on.
+        times.push((ticks + (offsets?.get(sampleNumber) ?? 0)) / timescale);
       }
       ticks += delta;
       sampleNumber += 1;
@@ -170,6 +173,100 @@ function resolveSampleTimes(buffer, stts, timescale, wanted) {
   return times;
 }
 
+/**
+ * Composition offsets for the sample numbers asked for.
+ *
+ * `ctts` is run-length encoded like `stts`, and version 1 carries SIGNED
+ * offsets — which is what the version exists for: a frame may be shown before
+ * it is decoded. Reading them as unsigned turns a small negative offset into
+ * roughly four billion ticks.
+ *
+ * @param {Buffer} buffer
+ * @param {{ dataOffset: number, end: number }} ctts
+ * @param {Set<number>} wanted - Sample numbers (1-based).
+ * @returns {Map<number, number>} Sample number to offset in media ticks.
+ */
+function readCompositionOffsets(buffer, ctts, wanted) {
+  const version = buffer[ctts.dataOffset];
+  const entryCount = buffer.readUInt32BE(ctts.dataOffset + 4);
+  const offsets = new Map();
+  let sampleNumber = 1;
+  let cursor = ctts.dataOffset + 8;
+  for (let entry = 0; entry < entryCount && cursor + 8 <= ctts.end; entry += 1) {
+    const count = buffer.readUInt32BE(cursor);
+    const offset = version === 1 ? buffer.readInt32BE(cursor + 4) : buffer.readUInt32BE(cursor + 4);
+    for (let index = 0; index < count; index += 1) {
+      if (wanted.has(sampleNumber)) {
+        offsets.set(sampleNumber, offset);
+      }
+      sampleNumber += 1;
+    }
+    cursor += 8;
+  }
+  return offsets;
+}
+
+/**
+ * How far the edit list shifts this track's composition timeline, in media
+ * ticks.
+ *
+ * ISO/IEC 14496-12 §8.6.6.3: `media_time` is the start of the edit within the
+ * media, in the MEDIA timescale and in composition time, while
+ * `segment_duration` is in the MOVIE timescale — two different units in one
+ * structure, which is why only the first is read here. `media_time = -1` is an
+ * empty edit: it inserts blank presentation time and starts no media, so the
+ * first real edit is the one that matters.
+ *
+ * Measured 2026-08-19: every LostFilm MP4 that carries a composition offset
+ * also carries an edit list cancelling it exactly, which is why decode times
+ * have been right on those files. `Firefly.S01E03` has the offset and NO edit
+ * list, and its times were 62.1 ms early on all 34 keyframes checked.
+ *
+ * @param {Buffer} buffer
+ * @param {{ dataOffset: number, end: number }} elst
+ * @returns {number} Ticks to subtract; zero when nothing is shifted.
+ */
+function readEditShift(buffer, elst) {
+  const version = buffer[elst.dataOffset];
+  const entryCount = buffer.readUInt32BE(elst.dataOffset + 4);
+  const wide = version === 1;
+  const entryBytes = wide ? 20 : 12;
+  let cursor = elst.dataOffset + 8;
+  for (let entry = 0; entry < entryCount && cursor + entryBytes <= elst.end; entry += 1) {
+    const mediaTime = wide
+      ? Number(buffer.readBigInt64BE(cursor + 8))
+      : buffer.readInt32BE(cursor + 4);
+    if (mediaTime >= 0) {
+      return mediaTime;
+    }
+    cursor += entryBytes;
+  }
+  return 0;
+}
+
+/**
+ * Whether this track's handler says it carries video.
+ *
+ * The standard identifies a track by its `hdlr`, and nothing else does. Picking
+ * "the first track that happens to carry sync samples" worked only because the
+ * seven releases measured all put video first; a file whose audio track carries
+ * them, or one that leads with a cover-art video track, would be read from the
+ * wrong place. That is the same defect that was fixed in the Matroska reader on
+ * 2026-08-18, arrived at from the other side.
+ *
+ * @param {Buffer} buffer
+ * @param {{ dataOffset: number, end: number }} mdia
+ * @returns {boolean}
+ */
+function isVideoTrack(buffer, mdia) {
+  const hdlr = findBox(buffer, mdia.dataOffset, mdia.end, "hdlr");
+  if (!hdlr || hdlr.dataOffset + 12 > hdlr.end) {
+    return false;
+  }
+  // FullBox header (4) then a reserved pre_defined (4), then the handler type.
+  return buffer.toString("latin1", hdlr.dataOffset + 8, hdlr.dataOffset + 12) === "vide";
+}
+
 /**
  * Read the keyframe times of an MP4/MOV file.
  *
@@ -189,12 +286,12 @@ export async function readMp4KeyframeTimes(readRange, fileSize) {
     return null;
   }
 
-  // Examine every track; the video one is whichever carries sync samples. A
+  // Examine every track, and take the one whose HANDLER says it is video. A
   // track with no `stss` has every sample a keyframe, so it constrains nothing
-  // and is skipped.
+  // and is skipped even when it is the video one.
   for (const trak of findAllBoxes(moov, moovBox.headerBytes, moov.length, "trak")) {
     const mdia = findBox(moov, trak.dataOffset, trak.end, "mdia");
-    if (!mdia) {
+    if (!mdia || !isVideoTrack(moov, mdia)) {
       continue;
     }
     const mdhd = findBox(moov, mdia.dataOffset, mdia.end, "mdhd");
@@ -237,9 +334,24 @@ export async function readMp4KeyframeTimes(readRange, fileSize) {
       continue;
     }
 
-    const times = resolveSampleTimes(moov, stts, timescale, wanted);
+    // The two terms that turn decode times into the timeline ffmpeg cuts on.
+    // Both are optional: a file without them is one whose decode and
+    // composition orders already agree, and then nothing is added or taken.
+    const ctts = findBox(moov, stbl.dataOffset, stbl.end, "ctts");
+    const offsets = ctts ? readCompositionOffsets(moov, ctts, wanted) : null;
+    const edts = findBox(moov, trak.dataOffset, trak.end, "edts");
+    const elst = edts && findBox(moov, edts.dataOffset, edts.end, "elst");
+    const editShift = elst ? readEditShift(moov, elst) : 0;
+
+    const times = resolveSampleTimes(moov, stts, timescale, wanted, offsets);
     if (times.length > 0) {
-      return times;
+      // A shift applied after the division would be in the wrong units: the
+      // edit's `media_time` is in MEDIA ticks, like everything else here.
+      const shifted = editShift === 0 ? times : times.map((time) => time - editShift / timescale);
+      // A negative time is not a position in the file. It happens when an edit
+      // starts later than a keyframe the table lists, and those frames are not
+      // presented at all.
+      return shifted.filter((time) => time >= 0);
     }
   }
   return null;

package/services/torrent-worker/piece-reader.js

@@ -484,6 +484,20 @@ export async function* readFragments({
   // process.
   const readerId = `read-${(readerSequence += 1)}`;
 
+  /**
+   * Set when the window JUMPS, cleared by the first wait after it.
+   *
+   * The wait that follows a jump is the cost of the jump: the pieces at the new
+   * position have not been asked for yet, and the encoder is restarting. It is
+   * not evidence about how well this swarm SUSTAINS a read, which is the only
+   * thing `requiredSpeed` is about — and letting it in is what collapsed the
+   * quality offer 131 ms after the seek measured on 2026-08-18, refusing every
+   * re-encoded rung on the strength of one jump.
+   *
+   * @type {boolean}
+   */
+  let waitBelongsToJump = false;
+
   const moveWindowTo = (pieceIndex) => {
     const next = readWindowFor({ pieceIndex, lastPiece, windowPieces });
     if (window && window.from === next.from && window.to === next.to) {
@@ -501,6 +515,7 @@ export async function* readFragments({
     // fills the store while the encoder runs ahead of the viewer.
     store.protectRange?.(readerId, next.from, next.to);
     if (isJump) {
+      waitBelongsToJump = true;
       // A jump — a seek, not the window sliding along — can land on pieces that
       // are already downloaded but have been spilled to disk. Bring the whole
       // window back at once instead of one disk round trip per piece as the
@@ -603,7 +618,18 @@ export async function* readFragments({
       // short, an immediate hit means it is longer than it needs to be. Applied
       // before the logging below so the line reports the window the next piece
       // will actually use.
-      noteSupplyWait(`${torrent?.infoHash ?? "?"}/${file?.name ?? "?"}`, file?.name ?? "", waitedMs);
+      if (waitBelongsToJump) {
+        // Recorded nowhere: see `waitBelongsToJump`. Said out loud, because a
+        // gap in the supply history is otherwise indistinguishable from a swarm
+        // that never made the reader wait.
+        logger.info(
+          `piece-reader: ${waitedMs}ms on the first piece after a jump — the cost of moving, ` +
+            `not of this swarm's supply, so it is not counted against the quality offer`
+        );
+        waitBelongsToJump = false;
+      } else {
+        noteSupplyWait(`${torrent?.infoHash ?? "?"}/${file?.name ?? "?"}`, file?.name ?? "", waitedMs);
+      }
       const widened = nextWindowPieces({
         current: windowPieces,
         base: basePieces,