@torrent-tv/proxy 2.27.0 → 2.29.0

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 2.29.0
+
+- **New**: A piece a reader is blocked on is handed to the fastest peers that hold it. Measured 2026-08-17: the swarm delivered 5.1-5.9 MB/s against a film consumed at about 1 MB/s — a fivefold surplus — and the reader still blocked 47 times in two minutes, 1.0-4.5 s each, on pieces a median of five peers already had. A block belongs to exactly one wire, so the read ends when the SLOWEST holder delivers, and `critical()` only lets the library take a block from a slow wire when its own picker happens to visit an idle one. This asks for it deliberately: when the wait starts, and again on the sampling tick that already runs while it lasts, the piece is pushed onto the three fastest unchoked holders through the library's own request entry with hotswap enabled. Nothing is duplicated — the library moves a block to a wire at least twice as fast, which bounds how often it can move at all. A refusal is counted rather than ignored (a full pipeline, or nothing reservable even with hotswap, means the piece waits on the wire and not on the picker), and a build that offers no such entry says so instead of failing silently. The wait line now reports `steered onto N of M holders`, so the next session says by number whether the tail shortened.
+
+## 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.

package/package.json

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

package/services/torrent-worker/fastest-wires.js

@@ -0,0 +1,121 @@
+/**
+ * @file Put the piece a reader is blocked on onto the fastest wires that hold
+ * it.
+ *
+ * Measured 2026-08-17: the swarm delivered 5.1-5.9 MB/s against a film consumed
+ * at about 1 MB/s — a fivefold surplus — and the reader still blocked 47 times
+ * in two minutes, 1.0-4.5 s each. So the shortage is not bandwidth. The piece
+ * that blocked had been requested from a median of five peers, and what set the
+ * tail was WHICH wire held the last outstanding block: a block is reserved for
+ * exactly one wire, and the read finishes when the slowest holder delivers.
+ *
+ * What the library already does, and what it does not: `torrent.critical()`
+ * (which the reader already sets over its window) enables HOTSWAP — an idle
+ * wire may take a block away from the SLOWEST holder. It does not duplicate:
+ * `piece.reserve()` returns -1 once every block is spoken for, and the
+ * end-game that would ask a second peer for the same block is commented out in
+ * `webtorrent/lib/torrent.js`. Hotswap therefore fires only when the library's
+ * own picker happens to visit an idle wire while our piece is critical.
+ *
+ * This asks for it on purpose, and chooses who: the wires that are unchoked,
+ * hold the piece and are measurably fastest are handed the piece through the
+ * same entry the library's picker uses, with hotswap enabled. Nothing is
+ * duplicated and no protocol rule is bent — the block moves to a faster holder
+ * instead of staying with whoever got it first.
+ */
+
+/**
+ * The library's own request entry. Internal, so its absence must be noticed
+ * rather than swallowed: without it this lever silently does nothing.
+ *
+ * @param {object} torrent
+ * @returns {boolean}
+ */
+export function canPlaceRequests(torrent) {
+  return typeof torrent?._request === "function";
+}
+
+/**
+ * Wires that could deliver this piece right now, fastest first.
+ *
+ * Excluded, each for its own reason: a wire that is choking us cannot be asked
+ * at all; one that does not hold the piece has nothing to give; a destroyed one
+ * is a corpse. Speed is the library's own measurement over its own window, so
+ * nothing here needs a history of its own.
+ *
+ * @param {object} torrent
+ * @param {number} pieceIndex
+ * @returns {object[]}
+ */
+export function wiresForPiece(torrent, pieceIndex) {
+  const wires = Array.isArray(torrent?.wires) ? torrent.wires : [];
+  const usable = [];
+  for (const wire of wires) {
+    if (!wire || wire.destroyed || wire.peerChoking) {
+      continue;
+    }
+    if (wire.peerPieces?.get?.(pieceIndex) !== true) {
+      continue;
+    }
+    usable.push(wire);
+  }
+  return usable.sort((left, right) => speedOf(right) - speedOf(left));
+}
+
+/**
+ * A wire's measured download speed in bytes per second, or 0 when it has not
+ * been measured. Wrapped because `downloadSpeed` is a method on the wire and a
+ * throw from a destroyed one must not take the caller with it.
+ *
+ * @param {object} wire
+ * @returns {number}
+ */
+function speedOf(wire) {
+  try {
+    const speed = wire?.downloadSpeed?.();
+    return Number.isFinite(speed) ? speed : 0;
+  } catch {
+    // A wire that cannot say how fast it is ranks last, which is the honest
+    // answer — and the caller's own log line reports how many were asked.
+    return 0;
+  }
+}
+
+/**
+ * Ask the fastest holders of `pieceIndex` for it.
+ *
+ * @param {object} torrent
+ * @param {number} pieceIndex
+ * @param {number} [limit] - How many wires to push it onto.
+ * @returns {{ asked: number, considered: number, fastestBytesPerSecond: number }}
+ *   `asked` counts requests the library actually placed: it refuses when a
+ *   wire's pipeline is full or when nothing can be reserved even with hotswap,
+ *   and that refusal is information — a piece nobody can be asked for is
+ *   waiting on the wire, not on the picker.
+ */
+export function askFastestWiresFor(torrent, pieceIndex, limit = 3) {
+  if (!canPlaceRequests(torrent) || !Number.isInteger(pieceIndex) || pieceIndex < 0) {
+    return { asked: 0, considered: 0, fastestBytesPerSecond: 0 };
+  }
+  const candidates = wiresForPiece(torrent, pieceIndex);
+  let asked = 0;
+  for (const wire of candidates.slice(0, Math.max(1, limit))) {
+    try {
+      // `true` is hotswap: if every block is reserved, take one from the
+      // slowest holder. That is the whole point — the reader is blocked
+      // precisely because a slow holder has one.
+      if (torrent._request(wire, pieceIndex, true) === true) {
+        asked += 1;
+      }
+    } catch (error) {
+      // Internal call: report it once per attempt rather than letting the lever
+      // fail in silence.
+      throw new Error(`could not place a request for piece ${pieceIndex}: ${error?.message ?? error}`);
+    }
+  }
+  return {
+    asked,
+    considered: candidates.length,
+    fastestBytesPerSecond: candidates.length > 0 ? speedOf(candidates[0]) : 0
+  };
+}

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

@@ -22,6 +22,7 @@
 
 import { findSharedStore } from "../piece-store/shared-piece-store.js";
 import { logger } from "../../utils/logger.js";
+import { askFastestWiresFor, canPlaceRequests } from "./fastest-wires.js";
 
 /** Only waits at least this long are reported; sequential reading stays silent. */
 const PIECE_WAIT_LOG_MS = 1_000;
@@ -438,6 +439,35 @@ export async function* readFragments({
       }
 
       const waitStartedAt = Date.now();
+      // The reader is blocked, so this piece is now the only thing that matters
+      // on this torrent: hand it to the fastest wires that hold it. A block is
+      // reserved for exactly one wire, and the read ends when the slowest
+      // holder delivers — measured 2026-08-17, the swarm had a fivefold surplus
+      // of bandwidth and the reader still waited 1.0-4.5 s, 47 times in two
+      // minutes, on pieces five peers already had.
+      let pushed = { asked: 0, considered: 0, fastestBytesPerSecond: 0 };
+      const pushToFastest = () => {
+        try {
+          const result = askFastestWiresFor(torrent, pieceIndex);
+          pushed = {
+            asked: pushed.asked + result.asked,
+            considered: result.considered,
+            fastestBytesPerSecond: result.fastestBytesPerSecond
+          };
+        } catch (error) {
+          // The entry is internal to the library; if a version changes it, this
+          // lever stops working and that must be visible rather than silent.
+          logger.warn(`piece-reader: could not steer piece ${pieceIndex} — ${error?.message ?? error}`);
+        }
+      };
+      if (canPlaceRequests(torrent)) {
+        pushToFastest();
+      } else {
+        logger.warn(
+          "piece-reader: this webtorrent build offers no way to place a request; " +
+            "the blocked piece cannot be steered onto a faster peer"
+        );
+      }
       // Sampled while waiting rather than after: once the piece lands, nothing
       // is outstanding on it any more and every count reads zero.
       let supply = null;
@@ -446,6 +476,9 @@ export async function* readFragments({
         if (!supply || sample.blocks > supply.blocks) {
           supply = sample;
         }
+        // Wires come and go, and their speeds change: a holder that was slow a
+        // moment ago may now be the fastest one available.
+        pushToFastest();
       }, 500);
       try {
         await whenPieceReady(torrent, pieceIndex, cancellation);
@@ -482,7 +515,14 @@ export async function* readFragments({
             (supply
               ? `${supply.holders}/${supply.peers} peers had it, ${supply.askedOf} were asked, ` +
                 `${supply.blocks} blocks (${Math.round((supply.blocks * 16384) / 1024)}KB) in flight at peak`
-              : "no sample taken")
+              : "no sample taken") +
+            // What WE did about it, so the next session says whether steering
+            // the piece onto faster holders shortens the tail — by number
+            // rather than by impression.
+            `; steered onto ${pushed.asked} of ${pushed.considered} holders` +
+            (pushed.fastestBytesPerSecond > 0
+              ? `, fastest ${Math.round(pushed.fastestBytesPerSecond / 1024)}KB/s`
+              : "")
         );
       }
 

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/fastest-wires.test.js

@@ -0,0 +1,121 @@
+/**
+ * @file Choosing who is asked for the piece a reader is blocked on.
+ *
+ * The measurement behind it (2026-08-17): a fivefold bandwidth surplus and 47
+ * blocking waits in two minutes, on pieces a median of five peers already had.
+ * A block belongs to one wire, so the read ends when the SLOWEST holder
+ * delivers — which makes "who holds it" the thing worth deciding.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { askFastestWiresFor, canPlaceRequests, wiresForPiece } from "../services/torrent-worker/fastest-wires.js";
+
+/**
+ * @param {{ speed: number, has?: boolean, choking?: boolean, destroyed?: boolean }} options
+ * @returns {object}
+ */
+function wire({ speed, has = true, choking = false, destroyed = false }) {
+  return {
+    destroyed,
+    peerChoking: choking,
+    peerPieces: { get: () => has },
+    downloadSpeed: () => speed
+  };
+}
+
+/**
+ * @param {object[]} wires
+ * @returns {{ torrent: object, asked: Array<{ speed: number, hotswap: boolean }> }}
+ */
+function torrentWith(wires, { refuse = false } = {}) {
+  /** @type {Array<{ speed: number, hotswap: boolean }>} */
+  const asked = [];
+  const torrent = {
+    wires,
+    _request(target, _index, hotswap) {
+      asked.push({ speed: target.downloadSpeed(), hotswap });
+      return !refuse;
+    }
+  };
+  return { torrent, asked };
+}
+
+test("the fastest holders are asked first", () => {
+  const { torrent, asked } = torrentWith([
+    wire({ speed: 100_000 }),
+    wire({ speed: 900_000 }),
+    wire({ speed: 400_000 })
+  ]);
+
+  const result = askFastestWiresFor(torrent, 42);
+
+  assert.deepEqual(
+    asked.map((entry) => entry.speed),
+    [900_000, 400_000, 100_000],
+    "fastest first — the read ends when the slowest holder delivers"
+  );
+  assert.equal(result.asked, 3);
+  assert.equal(result.fastestBytesPerSecond, 900_000);
+});
+
+test("hotswap is always on, because that is the whole point", () => {
+  // The reader is blocked precisely because every block is reserved and one of
+  // them sits with a slow wire. Without hotswap the library answers "nothing to
+  // reserve" and the lever does nothing at all.
+  const { torrent, asked } = torrentWith([wire({ speed: 10 })]);
+  askFastestWiresFor(torrent, 7);
+  assert.deepEqual(asked.map((entry) => entry.hotswap), [true]);
+});
+
+test("a wire that cannot deliver is not asked", () => {
+  const { torrent, asked } = torrentWith([
+    wire({ speed: 900_000, choking: true }),
+    wire({ speed: 800_000, has: false }),
+    wire({ speed: 700_000, destroyed: true }),
+    wire({ speed: 1_000 })
+  ]);
+
+  const result = askFastestWiresFor(torrent, 3);
+
+  assert.equal(asked.length, 1, "a choking, an absent and a dead wire are all unusable");
+  assert.equal(result.considered, 1);
+});
+
+test("a refusal is counted as a refusal", () => {
+  // The library refuses when a wire's pipeline is full or nothing can be
+  // reserved even with hotswap. That is information: the piece is waiting on
+  // the wire, not on the picker.
+  const { torrent } = torrentWith([wire({ speed: 500 }), wire({ speed: 400 })], { refuse: true });
+  const result = askFastestWiresFor(torrent, 11);
+  assert.equal(result.asked, 0);
+  assert.equal(result.considered, 2);
+});
+
+test("a build without the request entry is reported, not silently skipped", () => {
+  assert.equal(canPlaceRequests({ wires: [] }), false);
+  assert.equal(canPlaceRequests({ wires: [], _request: () => true }), true);
+  const result = askFastestWiresFor({ wires: [wire({ speed: 1 })] }, 1);
+  assert.deepEqual(result, { asked: 0, considered: 0, fastestBytesPerSecond: 0 });
+});
+
+test("a wire that cannot say how fast it is ranks last rather than throwing", () => {
+  const mute = wire({ speed: 0 });
+  mute.downloadSpeed = () => {
+    throw new Error("destroyed");
+  };
+  const ranked = wiresForPiece({ wires: [mute, wire({ speed: 5 })] }, 0);
+  assert.equal(ranked.length, 2);
+  assert.equal(ranked[0].downloadSpeed(), 5);
+});
+
+test("a throw from the library is raised, never swallowed", () => {
+  const torrent = {
+    wires: [wire({ speed: 1 })],
+    _request() {
+      throw new Error("internal");
+    }
+  };
+  assert.throws(() => askFastestWiresFor(torrent, 5), /could not place a request for piece 5/);
+});