@torrent-tv/proxy 2.66.1 → 2.68.0

package/package.json

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

package/routes/api/sources/warm/post.js

@@ -117,6 +117,19 @@ export async function handleApiSourceWarmPost(req, reply, { sourceRegistry, torr
     };
     for (const file of matched.audio) {
       warmOne(file, { tailBytes: 0 });
+      // And then the whole of it, in the room the viewer's own reading leaves.
+      // The head is enough to NAME the track; it is not enough to play one, and
+      // a viewer who switches otherwise waits for the swarm to deliver its
+      // first pieces — 27.7 s in the field on 2026-08-31, longer than the
+      // switch is willing to wait. A soundtrack is about a twentieth of the
+      // picture, and the fill stands aside for every moment the picture's own
+      // reader is blocked, so it uses capacity the viewer is not using.
+      if (typeof torrentPool.fillFileInBackground === "function") {
+        Promise.resolve(torrentPool.fillFileInBackground(torrent, file.fileIndex)).catch((error) => {
+          const message = error instanceof Error ? error.message : String(error);
+          logger.warn(`warm ${sourceKey.slice(0, 8)}: filling "${file.name}" failed: ${message}`);
+        });
+      }
     }
     for (const file of matched.subtitles) {
       warmOne(

package/server.js

@@ -206,15 +206,13 @@ export async function startProxyServer({
         return;
       }
       const torrent = await torrentPool.getTorrent(record.sourceType, record.source);
-      const file = torrent?.files?.[fileIndex];
-      if (!file || !Number.isFinite(file.length) || file.length <= 0) {
-        return;
-      }
-      await torrentPool.prefetchFileEdges(torrent, fileIndex, {
-        headBytes: file.length,
-        tailBytes: 0,
-        timeoutMs: 600_000
-      });
+      // The same background fill the warm-up starts when a file is chosen, not a
+      // second way of doing it. It is guarded against running twice on one file,
+      // so the two triggers converge instead of putting two readers on the same
+      // soundtrack — and only one of them would have stood aside for the
+      // picture. This trigger remains for the session that never had a warm-up
+      // before it.
+      await torrentPool.fillFileInBackground?.(torrent, fileIndex);
     }
   });
   const playbackPlanner = createPlaybackPlanner({

package/services/supply-margin.js

@@ -9,8 +9,22 @@
  *
  * Both follow from the same two measured quantities, and from nothing else:
  *
- *   W — how long a read waits for a piece it needs (the worst recent one);
- *   T — how long there is between such waits (the median recent interval).
+ *   W — how long the supply is INTERRUPTED (the worst recent stall);
+ *   T — how long the encoder RUNS between two stalls (the median recent gap).
+ *
+ * Both words are load-bearing, and getting either wrong is what produced a
+ * demanded speed of 4422x on 2026-08-31.
+ *
+ * A stall is not a wait. Several readers walk one file — the picture and each
+ * audio rendition — so a piece that has not arrived blocks all of them, and
+ * their waits end within milliseconds of each other. Counted as separate
+ * interruptions they gave an interval of 0.00 s. Waits are therefore merged into
+ * the stretches during which the supply was not delivering, however many readers
+ * noticed.
+ *
+ * And T is the RUNNING time, from the end of one stall to the start of the next
+ * — not the spacing between their ends, which includes a stall's own duration
+ * and so credits the encoder with cushion it was not building.
  *
  * **The margin.** A step producing at speed `v` gains `v - 1` seconds of
  * cushion for every second it runs, and an interruption of `W` seconds costs
@@ -19,10 +33,13 @@
  *
  *     (v - 1) × T > W        i.e.        v > 1 + W / T
  *
- * On the field torrent: waits every 2.22 s, worst 3.16 s, so the honest bar is
- * 2.42 — against the 1.5 that was assumed, and the 1.05 that was measured. The
- * same arithmetic explains why a copied stream never stalls: at 8x it gains
- * 15.5 s between interruptions and loses at most 4.8 s.
+ * On the field torrent: stalls of 1.49 s with 0.73 s of running between them,
+ * the worst 3.16 s, so the honest bar is 5.33 — against the 1.5 that was
+ * assumed, and the 1.05 that was measured. (An earlier reading of the same data
+ * gave 2.42 by using the end-to-end spacing; it was too low in the same
+ * direction as the guess it replaced.) The same arithmetic explains why a copied
+ * stream never stalls: at 8x it gains 10.7 s between stalls and loses at most
+ * 4.8 s.
  *
  * **The buffer.** It must cover the worst interruption that can arrive before
  * it can be refilled, whichever source that interruption comes from, plus the
@@ -62,10 +79,26 @@ export function requiredSpeedFrom(waits) {
   if (ordered.length < 2) {
     return null;
   }
-  const worstWaitSec = Math.max(...ordered.map((wait) => wait.waitedMs)) / 1000;
+  // One INTERRUPTION, not one wait. Several readers walk the same file — the
+  // picture and each audio rendition — and a piece that has not arrived blocks
+  // all of them at once. Counted as separate interruptions, those simultaneous
+  // waits gave a near-zero interval and therefore a required speed of thousands:
+  // measured 2026-08-31, `worst wait 13.26s, one every 0.00s, 2 measured` became
+  // 4422.00x, and every quality step was refused against it.
+  const interruptions = mergeOverlapping(ordered);
+  if (interruptions.length < 2) {
+    // One interruption shows no interval, and an interval invented from one
+    // point is exactly what this file exists to remove.
+    return null;
+  }
+  const worstWaitSec = Math.max(...interruptions.map((one) => one.end - one.start)) / 1000;
   const intervals = [];
-  for (let index = 1; index < ordered.length; index += 1) {
-    const gapMs = ordered[index].at - ordered[index - 1].at;
+  for (let index = 1; index < interruptions.length; index += 1) {
+    // From the END of one interruption to the START of the next: that is the
+    // stretch the encoder actually runs for and builds cushion in. Measuring
+    // end-to-end instead counted each interruption's own duration as part of
+    // the recovery it is supposed to be recovered from.
+    const gapMs = interruptions[index].start - interruptions[index - 1].end;
     if (gapMs > 0) {
       intervals.push(gapMs / 1000);
     }
@@ -81,10 +114,41 @@ export function requiredSpeedFrom(waits) {
     requiredSpeed: 1 + worstWaitSec / medianIntervalSec,
     worstWaitSec,
     medianIntervalSec,
-    samples: ordered.length
+    // Interruptions, not waits: what the figure is derived from. The two differ
+    // whenever more than one reader walks the file, and reporting the raw count
+    // is what made the 4422x line look better evidenced than it was — "24
+    // measured" was 24 waits over far fewer actual stalls.
+    samples: interruptions.length,
+    waits: ordered.length
   };
 }
 
+/**
+ * Waits joined into the interruptions they actually were.
+ *
+ * A wait spans `[at - waitedMs, at]`. Two that overlap or touch are one stretch
+ * during which the supply was not delivering, however many readers noticed it.
+ *
+ * @param {SupplyWait[]} ordered - Usable waits, oldest END first.
+ * @returns {Array<{ start: number, end: number }>} Disjoint, in time order.
+ */
+function mergeOverlapping(ordered) {
+  const spans = ordered
+    .map((wait) => ({ start: wait.at - wait.waitedMs, end: wait.at }))
+    .sort((left, right) => left.start - right.start);
+  /** @type {Array<{ start: number, end: number }>} */
+  const merged = [];
+  for (const span of spans) {
+    const last = merged[merged.length - 1];
+    if (last && span.start <= last.end) {
+      last.end = Math.max(last.end, span.end);
+      continue;
+    }
+    merged.push({ ...span });
+  }
+  return merged;
+}
+
 /**
  * The smallest buffer at which no interruption reaches the viewer.
  *

package/services/torrent-worker/background-fill.js

@@ -0,0 +1,213 @@
+/**
+ * Fetch a whole file that nobody is playing yet, using only the room the viewer
+ * is not using.
+ *
+ * WHAT IT IS FOR. A release ships its dub and its subtitles as separate files,
+ * and a viewer who switches to one waits for the swarm to deliver its first
+ * pieces — 27.7 s in the field on 2026-08-31, which is longer than the switch is
+ * willing to wait. These files are small beside the picture (30 MB against 566
+ * MB, about a twentieth), so having them on disk before anyone asks turns every
+ * later switch into a local read.
+ *
+ * THE ORDERING, WHICH IS THE WHOLE DESIGN. What plays now comes first: the
+ * picture at the playhead, the soundtrack being heard, the subtitles being
+ * shown. The other soundtracks and subtitle files come next. Reading the film
+ * far ahead comes last. This module implements the middle tier, and it stays
+ * below the first by a condition that is measured rather than chosen: it fetches
+ * only while NO reader on the torrent is inside a wait. A reader blocked on a
+ * piece is the viewer's own reading starving, and that is exactly the moment
+ * this must not be asking the swarm for anything.
+ *
+ * WHY IT IS A READ AND NOT A SELECTION. `file.select()` claims every piece of a
+ * file at once. `#syncSelections` in `torrent-pool.js` records what that cost
+ * when it was done alongside the readers' own moving windows: a claim covering
+ * everything always outranked the window, and a seek to 89.1 % of a 4.7 GB film
+ * waited 93 s while the swarm fetched 2.47 GB in file order. So this walks the
+ * file a piece at a time through an ordinary bounded read, which claims what it
+ * is reading and gives it back.
+ */
+
+import { logger } from "../../utils/logger.js";
+import { readersAreBlockedOn, stallsSeenOn } from "./piece-reader.js";
+
+/**
+ * How long to stand aside after finding the viewer's own reading blocked.
+ *
+ * Not a measurement of anything: it is how often the question "is the viewer
+ * still starving?" is asked, and it is answered by the reader count, which is
+ * exact. Short enough that room is used soon after it appears, long enough that
+ * asking costs nothing.
+ */
+const STAND_ASIDE_MS = 1_000;
+
+/** Files being filled, by `sourceKey:fileIndex`, so one runs per file. */
+const running = new Map();
+
+/**
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+function pause(ms) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    timer.unref?.();
+  });
+}
+
+/**
+ * Read one byte range, letting the torrent fetch what is missing.
+ *
+ * @param {object} file
+ * @param {number} start
+ * @param {number} end - Inclusive.
+ * @returns {Promise<number>} Bytes read; 0 on failure.
+ */
+function readRange(file, start, end) {
+  return new Promise((resolve) => {
+    let stream;
+    try {
+      stream = file.createReadStream({ start, end });
+    } catch {
+      resolve(0);
+      return;
+    }
+    let bytes = 0;
+    let settled = false;
+    const settle = (value) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      resolve(value);
+    };
+    stream.on("data", (chunk) => {
+      bytes += chunk.length;
+    });
+    stream.on("end", () => settle(bytes));
+    stream.on("error", () => {
+      stream.destroy?.();
+      settle(0);
+    });
+  });
+}
+
+/**
+ * Fetch a file whole, in the room the viewer leaves.
+ *
+ * Returns as soon as the work is under way; the caller is not waiting for it.
+ * One fill per file — a second request while one is running is ignored rather
+ * than doubling the reads.
+ *
+ * @param {object} torrent
+ * @param {number} fileIndex
+ * @param {string} sourceKey
+ * @param {{ chunkBytes?: number, isBlocked?: (infoHash: string) => boolean, stallsSeen?: (infoHash: string) => number }} [options]
+ *   `isBlocked` answers "is the viewer's own reading starving right now"; it is
+ *   the tier boundary, and it is a parameter so it can be exercised without a
+ *   swarm.
+ * @returns {boolean} Whether a fill was started by this call.
+ */
+export function fillFileInBackground(torrent, fileIndex, sourceKey, options = {}) {
+  const key = `${sourceKey}:${fileIndex}`;
+  if (running.has(key)) {
+    return false;
+  }
+  const file = torrent?.files?.[fileIndex];
+  if (!file || !Number.isFinite(file.length) || file.length <= 0) {
+    return false;
+  }
+  // One piece at a time: the smallest unit the swarm actually delivers, so the
+  // gap between two checks of "is the viewer starving?" is as short as it can
+  // usefully be.
+  const chunkBytes = Number.isFinite(options.chunkBytes) && options.chunkBytes > 0
+    ? options.chunkBytes
+    : (Number(torrent?.pieceLength) || 4 * 1024 * 1024);
+  const isBlocked = typeof options.isBlocked === "function" ? options.isBlocked : readersAreBlockedOn;
+  const stallsSeen = typeof options.stallsSeen === "function" ? options.stallsSeen : stallsSeenOn;
+  const work = fill(torrent, file, fileIndex, chunkBytes, isBlocked, stallsSeen).finally(() => {
+    running.delete(key);
+  });
+  running.set(key, work);
+  return true;
+}
+
+/**
+ * @param {object} torrent
+ * @param {object} file
+ * @param {number} fileIndex
+ * @param {number} chunkBytes
+ * @param {(infoHash: string) => boolean} isBlocked
+ * @param {(infoHash: string) => number} stallsSeen
+ * @returns {Promise<void>}
+ */
+async function fill(torrent, file, fileIndex, chunkBytes, isBlocked, stallsSeen) {
+  const startedAt = Date.now();
+  const infoHash = String(torrent?.infoHash ?? "");
+  let read = 0;
+  let stoodAsideMs = 0;
+  // The stall count this fill last saw. A chunk is fetched only when it has not
+  // moved since the previous one.
+  let quietSince = stallsSeen(infoHash);
+  logger.info(
+    `background-fill: "${String(file.name).slice(0, 40)}" (${(file.length / 1e6).toFixed(1)}MB) will be ` +
+      "fetched whole while the viewer's own reading leaves room"
+  );
+  for (let start = 0; start < file.length; start += chunkBytes) {
+    // Stand aside while anything the viewer is watching is waiting on the
+    // swarm — AND for as long after it as it takes for a quiet stretch to
+    // pass. Pausing only DURING a stall is not enough: on a swarm delivering
+    // exactly what the film needs, this still takes bandwidth between stalls,
+    // and the stalls themselves are the proof there was none to spare. Field
+    // 2026-08-31, the case that forced this: 200-600 KB/s delivered against
+    // the 399 KB/s the film eats, one piece waited 101 s, and the picture
+    // stood still 145.6 s.
+    //
+    // "A quiet stretch" is measured, not chosen: the stall counter must not
+    // have moved while the previous chunk was being fetched. On a starving
+    // swarm it moves constantly and this stops altogether, which is the right
+    // answer — there is no spare room to use.
+    while (isBlocked(infoHash) || stallsSeen(infoHash) !== quietSince) {
+      stoodAsideMs += STAND_ASIDE_MS;
+      await pause(STAND_ASIDE_MS);
+      // Re-baselined after the pause, so a stretch that passes without a new
+      // stall lets the fill go on. Without this it could never resume.
+      quietSince = stallsSeen(infoHash);
+    }
+    // The torrent may have been destroyed under us — a viewer who left, the
+    // disk sweep, a restart. Reading a destroyed file throws, and there is
+    // nothing here worth an error.
+    if (!torrent?.files?.[fileIndex]) {
+      return;
+    }
+    // Taken BEFORE the read, and deliberately not refreshed after it: a stall
+    // that happens while this chunk is in flight must still be visible to the
+    // next iteration. Refreshing afterwards erased exactly that evidence, which
+    // is the defect a test caught here.
+    quietSince = stallsSeen(infoHash);
+    const bytes = await readRange(file, start, Math.min(start + chunkBytes, file.length) - 1);
+    if (bytes === 0) {
+      logger.info(
+        `background-fill: "${String(file.name).slice(0, 40)}" stopped at ` +
+          `${(start / 1e6).toFixed(1)}MB — the read returned nothing`
+      );
+      return;
+    }
+    read += bytes;
+  }
+  logger.info(
+    `background-fill: "${String(file.name).slice(0, 40)}" is on disk — ${(read / 1e6).toFixed(1)}MB in ` +
+      `${((Date.now() - startedAt) / 1000).toFixed(0)}s, of which ${(stoodAsideMs / 1000).toFixed(0)}s ` +
+      "was spent standing aside for the viewer; a switch to it will not wait for the swarm"
+  );
+}
+
+/**
+ * Whether a file is being filled right now. For tests and for the log.
+ *
+ * @param {string} sourceKey
+ * @param {number} fileIndex
+ * @returns {boolean}
+ */
+export function fillIsRunning(sourceKey, fileIndex) {
+  return running.has(`${sourceKey}:${fileIndex}`);
+}

package/services/torrent-worker/client.js

@@ -321,6 +321,16 @@ export class TorrentWorkerClient {
    * @param {{ sourceKey: string, fileIndex: number }} params
    * @returns {Promise<{ tracks: object[] }>}
    */
+  /**
+   * Fetch one whole file in the room the viewer's own reading leaves.
+   *
+   * @param {{ sourceKey: string, fileIndex: number }} params
+   * @returns {Promise<{ started: boolean }>}
+   */
+  async fillFile({ sourceKey, fileIndex }) {
+    return this.#caller.call(Command.FILL_FILE, { sourceKey, fileIndex });
+  }
+
   async getSubtitleTracks({ sourceKey, fileIndex }) {
     return this.#caller.call(Command.SUBTITLE_TRACKS, { sourceKey, fileIndex });
   }

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

@@ -600,6 +600,80 @@ function describeSteering(key) {
   );
 }
 
+/**
+ * How many readers are blocked on a torrent AT THIS MOMENT, by infohash.
+ *
+ * Not a history and not an average: the question it answers is "is anything the
+ * viewer is watching waiting for the swarm right now", and the only honest
+ * answer is a count of readers currently inside a wait.
+ *
+ * It exists so that work which is NOT what the viewer is watching — fetching a
+ * soundtrack or a subtitle file they may switch to later — can proceed while the
+ * swarm has room and stand aside the instant it does not. That ordering is the
+ * whole of the requirement: the picture and the track being played come first,
+ * the other tracks next, and reading the film far ahead last.
+ *
+ * @type {Map<string, number>}
+ */
+const blockedReaders = new Map();
+
+/**
+ * How many stalls a torrent's readers have had, ever. Only differences between
+ * two readings of it mean anything.
+ *
+ * @type {Map<string, number>}
+ */
+const stallsSeen = new Map();
+
+/**
+ * Whether any reader on this torrent is waiting for a piece right now.
+ *
+ * @param {string} infoHash
+ * @returns {boolean}
+ */
+export function readersAreBlockedOn(infoHash) {
+  return (blockedReaders.get(infoHash) ?? 0) > 0;
+}
+
+/**
+ * How many times a reader on this torrent has been blocked since the process
+ * started.
+ *
+ * Exists so that work of lower importance can ask "did the viewer stall while I
+ * was busy?" — which is a different and stricter question than "is the viewer
+ * stalled right now". On a swarm delivering exactly what the film needs, a
+ * background fetch that only pauses DURING a stall still takes bandwidth
+ * between them, and the stalls are the proof it had none to spare. Field
+ * 2026-08-31: the swarm delivered 200-600 KB/s against the 399 KB/s the film
+ * needs, and the picture stood still 145.6 s.
+ *
+ * @param {string} infoHash
+ * @returns {number}
+ */
+export function stallsSeenOn(infoHash) {
+  return stallsSeen.get(infoHash) ?? 0;
+}
+
+/**
+ * @param {string} infoHash
+ * @param {number} delta
+ * @returns {void}
+ */
+function countBlockedReader(infoHash, delta) {
+  if (!infoHash) {
+    return;
+  }
+  if (delta > 0) {
+    stallsSeen.set(infoHash, (stallsSeen.get(infoHash) ?? 0) + 1);
+  }
+  const next = (blockedReaders.get(infoHash) ?? 0) + delta;
+  if (next > 0) {
+    blockedReaders.set(infoHash, next);
+    return;
+  }
+  blockedReaders.delete(infoHash);
+}
+
 function noteSupplyWait(key, label, waitedMs) {
   const history = supplyWaits.get(key) ?? [];
   history.push({ waitedMs, at: Date.now() });
@@ -623,8 +697,14 @@ function noteSupplyWait(key, label, waitedMs) {
   });
   logger.info(
     `supply "${label.slice(0, 40)}": a step must run at ${demand.requiredSpeed.toFixed(2)}x ` +
-    `to survive this swarm (worst wait ${demand.worstWaitSec.toFixed(2)}s, one every ` +
-    `${demand.medianIntervalSec.toFixed(2)}s, ${demand.samples} measured) — ` +
+    // "Interruption", not "wait": several readers walk one file — the picture
+    // and each audio rendition — so one missing piece produces one stall and
+    // several waits. Saying how many of each is what makes the figure readable;
+    // reporting the waits alone made `2 measured` look like two interruptions
+    // 3 ms apart, and the demanded speed came out at 4422x.
+    `to survive this swarm (worst stall ${demand.worstWaitSec.toFixed(2)}s, one every ` +
+    `${demand.medianIntervalSec.toFixed(2)}s of running, ${demand.samples} stall(s) ` +
+    `from ${demand.waits} wait(s)) — ` +
     `and the smallest buffer that hides it is ${buffer ? buffer.seconds.toFixed(1) : "?"}s` +
     // What steering the blocked piece onto another peer bought, as the
     // difference between the waits where it placed something and the waits
@@ -890,6 +970,15 @@ export async function* readFragments({
       }
 
       const waitStartedAt = Date.now();
+      // What the WHOLE torrent received while this one piece was missing. It is
+      // the reading that separates the two causes a wait can have, and neither
+      // could be told from the other before: bytes arriving briskly throughout
+      // mean the swarm had capacity and this piece was stuck behind the wire
+      // that reserved it — the blocked-piece tail; bytes barely moving mean
+      // there was nothing to be had, and no reordering of requests would have
+      // helped. Asked of 2026-08-31, when a session with 4-5 peers of 38 known
+      // waited 41.32 s at worst and the log could not say which it was.
+      const downloadedAtWaitStart = Number(torrent?.downloaded) || 0;
       // 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
@@ -955,9 +1044,16 @@ export async function* readFragments({
         // moment ago may now be the fastest one available.
         pushToFastest();
       }, 500);
+      // Counted for exactly as long as this reader is inside the wait, so that
+      // background work can stand aside while the viewer's own reading is
+      // starving. The `finally` is what makes it safe: a cancelled or failed
+      // read must not leave the torrent looking permanently blocked, which
+      // would stop that background work for the rest of the session.
+      countBlockedReader(torrent?.infoHash, 1);
       try {
         await whenPieceReady(torrent, pieceIndex, cancellation);
       } finally {
+        countBlockedReader(torrent?.infoHash, -1);
         clearInterval(supplyProbe);
       }
       // What a reader spent waiting for data, attributed to the exact piece. A
@@ -999,11 +1095,21 @@ export async function* readFragments({
       }
       if (waitedMs >= PIECE_WAIT_LOG_MS) {
         const rateKbps = Math.round(pieceLength / 1024 / (waitedMs / 1000));
+        // Two rates, side by side, and no verdict word between them: the swarm's
+        // own delivery during the wait against what this piece managed. Both are
+        // measured; which one a reader calls "the cause" follows from the pair
+        // without a threshold having to be chosen here. Far apart means the
+        // bytes were flowing and this piece was not among them; close together,
+        // or both near zero, means there was nothing to deliver.
+        const swarmBytes = Math.max(0, (Number(torrent?.downloaded) || 0) - downloadedAtWaitStart);
+        const swarmKbps = Math.round(swarmBytes / 1024 / (waitedMs / 1000));
         logger.info(
           `piece-reader: waited ${waitedMs}ms for piece ${pieceIndex} ` +
             `(${pieceIndex - firstPiece + 1} of ${lastPiece - firstPiece + 1} in a read from ` +
             `${(start / 1024 / 1024).toFixed(0)}MB of "${file.name}") ` +
-            `— ${rateKbps}KB/s on this piece; ` +
+            `— ${rateKbps}KB/s on this piece while the swarm delivered ` +
+            `${swarmKbps}KB/s (${(swarmBytes / 1024 / 1024).toFixed(1)}MB) across the torrent, ` +
+            `${Number(torrent?.numPeers) || 0} peers connected; ` +
             (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`

package/services/torrent-worker/pool-adapter.js

@@ -134,6 +134,26 @@ export class WorkerTorrentPool {
    * @param {number} fileIndex
    * @returns {Promise<object[]>}
    */
+  /**
+   * Fetch one whole file using only the room the viewer's own reading leaves.
+   *
+   * For a soundtrack or subtitle file shipped beside the picture: small next to
+   * the film, and having it on disk is what turns a later switch into a local
+   * read instead of a wait on the swarm.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @returns {Promise<boolean>} Whether a fill was started by this call.
+   */
+  async fillFileInBackground(torrent, fileIndex) {
+    const sourceKey = torrent?.sourceKey;
+    if (!sourceKey) {
+      return false;
+    }
+    const answer = await this.#client.fillFile({ sourceKey, fileIndex });
+    return answer?.started === true;
+  }
+
   async getSubtitleTracks(torrent, fileIndex) {
     const sourceKey = torrent?.sourceKey;
     if (!sourceKey) {

package/services/torrent-worker/protocol.js

@@ -65,6 +65,12 @@ export const Command = {
   CANCEL_READ: "cancel-read",
   /** Pre-fetch the head and tail a codec probe needs. */
   PREFETCH_EDGES: "prefetch-edges",
+  /**
+   * Fetch one whole file using only the room the viewer's own reading leaves —
+   * a soundtrack or subtitle file they may switch to later. Returns as soon as
+   * the work is under way.
+   */
+  FILL_FILE: "fill-file",
   /** The text subtitle tracks a file carries, for the viewer's menu. */
   SUBTITLE_TRACKS: "subtitle-tracks",
   /**