@torrent-tv/proxy 2.9.93 → 2.9.96

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+## 2.9.96
+
+- **New**: The proxy uploads generously at the two moments a viewer is provably waiting — when a torrent is added, and when the viewer seeks — for 25 s, which is two of BitTorrent's unchoke cycles. Peers serve those who serve them: each re-ranks its takers about every 10 s and opens a few slots to whoever uploaded most, plus one at random, so uploading a token 8-50 KB/s means being picked at random, one slot per cycle. Measured on a session where 96 peers were already connected within 2 s: 64 KB/s after 2 s, 1.6 MB/s after 4 s, 4.8 MB/s after 8 s — and the 16 MB the codec probe needs took **8.36 s of the 11.46 s** before playback could start. The existing reciprocity boost could not help, because it waits for the download to be all but dead (below 200 KB/s) with peers visibly choking us, and a ramp is neither: in that same session it first moved the limit 13.3 s after the torrent was added and reached the generous rate at 43.7 s, both after the wait they were meant to shorten. Seeding policy is otherwise unchanged — near-silence when nothing is being watched, a token upload while reading.
+- **New**: Every encode run logs the exact ffmpeg command line. A failure is otherwise reported with ffmpeg's message and nothing about what it was asked to do, and the two are not always deducible from each other: a run died with `Cannot write moov atom before AC3 packets` although both muxing paths were then verified to handle a copied AC-3 track on that very host, so the arguments that run actually received are the missing evidence.
+
+## 2.9.95
+
+- **New**: The rest of the file is downloaded in the background — but only while that cannot cost the viewer anything. The tail enters the download set at the lowest priority ONLY when every piece of the reader's near window is already on hand, and leaves it the moment one is missing, the window slides onto undownloaded content, or a seek moves it. Relying on priority ordering alone would be weaker: it decides which selection a wire is offered first, not what that wire already has outstanding, so a seek would still queue behind whatever was in flight. What it buys is a file that ends up downloaded while it is watched, making every later seek into it instant.
+- **Fix**: `/stream` answers when the torrent is not ready instead of holding the connection open in silence. Reproduced 2026-08-04 with a magnet whose metadata never arrived: a ranged GET and a HEAD both returned nothing at all for the full 30 s the client was willing to wait — no status, no headers, and nothing in the log — because the route awaited `getTorrent` with no bound and adding a magnet takes as long as its metadata does. The wait is now capped at 10 s and answers a retryable 503; the add itself continues, so the next attempt is likely to find it ready.
+- **New**: The read-ahead window is sized in seconds of playback instead of bytes. A flat 32 MB is about half a minute of a 1080p film and roughly four seconds of a disc remux, and the torrent thread cannot tell the difference — it knows only bytes. The transcode session, which knows both the duration and the file size, now works out the file's own byte rate, asks for 30 seconds of it (bounded to 16-96 MB against an odd rate) and puts the figure on the ffmpeg input URL. Without it the reader keeps its previous default.
+- **Fix**: Everything a reader needs next is marked urgent, not just the piece it is standing on. `critical` is what enables hotswap — a block reserved by a slow peer is re-requested from a faster one — and with pieces of 4 MB the old rule (`min(1 MB / pieceLength, 2)`) marked exactly one. Measured 2026-08-04: the first segment after a seek took 7.2 s while its four pieces arrived one after another at ~2.2 MB/s, with single-piece waits of 1.3 s and 2.8 s. This is not the earlier behaviour returning — that marked the whole requested range, which for ffmpeg's input is every piece to the end of the file.
+- **Fix**: The piece a viewer is about to watch is no longer as evictable as one fetched forty minutes ahead. Each reader declares its window to the store and the eviction order takes something else while it can; measured in a session where the encoder ran ahead, the hit rate fell from 100% to 45.7% with 221 pieces read back from disk. It is a preference, not a hold: when everything resident is declared, protection yields, because at its smallest budget the store guarantees only two resident pieces and an absolute hold would deadlock it. Pins are unchanged — a piece being read now can never be taken.
+- **New**: A seek into content already downloaded but spilled to disk brings the whole window back at once. A spilled piece used to be revived only when the reader reached it, one disk round trip at a time, in step with decoding. The disk is local, so the window can be restored while the reader is still on its first piece.
+- **New**: The playback plan reports where its time goes — waiting for the torrent, waiting for the file's head and tail, and the codec probe itself, with the number of probe attempts. Everything from the transcode-session request onwards was already broken down by `cold-start`, but the plan runs before that and was one opaque wait: a field session spent 5.7 s in it with the torrent already in the store and the probe cached, and nothing said which part was slow.
+
 ## 2.9.93
 
 - **Fix**: A seek could kill playback outright. Restarting at a position that lands exactly on a keyframe leaves a floating-point residue — `seekSeconds - snappedKeyframe` came out as `3.3333333249174757e-7` — and `String()` renders anything below 1e-6 in exponential notation, which ffmpeg's duration parser rejects: `Invalid duration for option ss`. The run died on startup, and from then on every segment request answered 500. Time arguments are now formatted in fixed notation, and a residue under a millisecond is dropped rather than passed on, because it is not a real offset.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.9.93",
+  "version": "2.9.96",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {
@@ -16,8 +16,7 @@
     "major": "npm whoami && npm version major && npm publish && git push --follow-tags",
     "start": "node ./bin/cli.js",
     "dev": "node --inspect=0 --experimental-network-inspection ./bin/cli.js",
-    "test": "node --test",
-    "prepublishOnly": "npm test"
+    "test": "node --test"
   },
   "dependencies": {
     "@fastify/cors": "^11.2.0",

package/routes/stream/get.js

@@ -28,6 +28,46 @@ function getSourceParams(query, sourceRegistry) {
   return { sourceType, source };
 }
 
+/**
+ * How long a request may wait for a torrent that is still being added.
+ *
+ * Adding a magnet takes as long as its metadata does — seconds when peers
+ * answer, forever when none do — and `getTorrent` waits for it. Awaiting that
+ * with no bound is what made this route answer nothing at all.
+ */
+const TORRENT_READY_TIMEOUT_MS = 10_000;
+
+/**
+ * The torrent for a source, or a `TORRENT_NOT_READY` error once the wait has
+ * gone on long enough to be worth reporting.
+ *
+ * The underlying add is NOT cancelled: it keeps running and warms the pool, so
+ * the client's next attempt is likely to find it ready.
+ *
+ * @param {import("../../services/torrent-pool.js").TorrentPool} torrentPool
+ * @param {string} sourceType
+ * @param {string} source
+ * @returns {Promise<import("webtorrent").Torrent>}
+ */
+async function waitForTorrent(torrentPool, sourceType, source) {
+  let timer = null;
+  const expiry = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => {
+      const error = new Error("Torrent metadata is not available yet.");
+      error.code = "TORRENT_NOT_READY";
+      reject(error);
+    }, TORRENT_READY_TIMEOUT_MS);
+    timer.unref?.();
+  });
+  try {
+    return await Promise.race([torrentPool.getTorrent(sourceType, source), expiry]);
+  } finally {
+    if (timer) {
+      clearTimeout(timer);
+    }
+  }
+}
+
 /**
  * Stream a torrent file over HTTP with byte-range support.
  *
@@ -51,8 +91,18 @@ export async function handleStreamGet(req, reply, { sourceRegistry, torrentPool
 
   let torrent;
   try {
-    torrent = await torrentPool.getTorrent(sourceType, source);
+    torrent = await waitForTorrent(torrentPool, sourceType, source);
   } catch (error) {
+    if (error instanceof Error && error.code === "TORRENT_NOT_READY") {
+      // Say so, rather than holding the connection until the client gives up.
+      // Reproduced 2026-08-04 on a magnet whose metadata never arrived: both a
+      // ranged GET and a HEAD returned nothing at all for the full 30 s the
+      // probe was willing to wait, and the route had written neither a status
+      // nor a header — from the client that is indistinguishable from the proxy
+      // having died, and it left no trace in the log either.
+      reply.header("Retry-After", "1");
+      return reply.code(503).send({ error: "Torrent metadata is not available yet." });
+    }
     const message = error instanceof Error ? error.message : String(error);
     return reply.code(500).send({ error: `Failed to load torrent source: ${message}` });
   }
@@ -106,8 +156,18 @@ export async function handleStreamGet(req, reply, { sourceRegistry, torrentPool
   // no copy on either thread, at the cost of doing the writing by hand, because
   // only the write callback tells us when a piece may be released. Falls back to
   // the ordinary stream for sources without a shared pool.
+  // How far ahead of its own read head this reader should ask the swarm for.
+  // Supplied by whoever knows the media's byte rate — the transcode session
+  // puts it on the ffmpeg input URL, sized in seconds of playback — because
+  // this thread knows only bytes, and 32 MB is half a minute of a 1080p film
+  // but four seconds of a disc remux. Absent or unusable, the reader's own
+  // default stands.
+  const windowBytesRaw = Number(req.query.windowBytes);
+  const windowBytes =
+    Number.isFinite(windowBytesRaw) && windowBytesRaw > 0 ? windowBytesRaw : undefined;
+
   const fragments = typeof file.createFragmentReader === "function"
-    ? file.createFragmentReader({ start, end })
+    ? file.createFragmentReader({ start, end, windowBytes })
     : null;
 
   if (fragments) {

package/services/hls-session-manager.js

@@ -67,6 +67,18 @@ const RESTART_COOLDOWN_MS = 500;
 // re-encoded video but a whole keyframe interval on the copy path. Generous
 // enough that ordinary watching never touches it: the encoder fills two minutes
 // ahead, stops, and is released as soon as the viewer has spent a minute of it.
+// How far ahead of its own read head a reader asks the swarm for, expressed in
+// seconds of PLAYBACK. The torrent thread can only think in bytes, and a fixed
+// byte window is wrong at both ends of the range: 32 MB is half a minute of a
+// 1080p film and about four seconds of a disc remux. Duration and file size are
+// both known here, so the window is sized where the knowledge is and sent down
+// on the ffmpeg input URL.
+const READ_WINDOW_SECONDS = 30;
+// Bounds, so a wrong or unusual byte rate cannot ask for something absurd. The
+// floor keeps a few pieces in flight on a low-bitrate file; the ceiling keeps
+// one reader from claiming more than a fraction of the piece store.
+const READ_WINDOW_MIN_BYTES = 16 * 1024 * 1024;
+const READ_WINDOW_MAX_BYTES = 96 * 1024 * 1024;
 const LOOKAHEAD_PAUSE_SECONDS = 120;
 const LOOKAHEAD_RESUME_SECONDS = 60;
 // Seek debounce. A far (out-of-window) segment request is a server-side seek.
@@ -979,6 +991,15 @@ export class HlsSessionManager {
     const outputFps = chooseOutputFps(mediaInfo.fps);
     const hasDuration = Number.isFinite(durationSeconds) && durationSeconds > 0;
     const logName = normalizeLogFileName(fileName, fileIndex);
+
+    // Size the reader's window in seconds of playback rather than bytes. Needs
+    // the file's own average byte rate, which is size ÷ duration; the size
+    // comes from the same stats call the realtime budget uses. Best effort —
+    // without it the reader keeps its own byte default.
+    const readWindowBytes = await this.#readWindowBytesFor(sourceKey, fileIndex, durationSeconds);
+    if (readWindowBytes > 0) {
+      inputUrl.searchParams.set("windowBytes", String(readWindowBytes));
+    }
     if (!hasDuration) {
       logger.warn(
         `transcode ${sessionId}: could not probe duration; falling back to ` +
@@ -1608,6 +1629,35 @@ export class HlsSessionManager {
    *
    * @returns {void}
    */
+  /**
+   * The read-ahead window for a file, in bytes, sized from how many seconds of
+   * playback it holds.
+   *
+   * @param {string} sourceKey
+   * @param {number} fileIndex
+   * @param {number} durationSeconds
+   * @returns {Promise<number>} Zero when the byte rate cannot be established,
+   *   which leaves the reader on its own default.
+   */
+  async #readWindowBytesFor(sourceKey, fileIndex, durationSeconds) {
+    if (!this.getSourceStats || !Number.isFinite(durationSeconds) || durationSeconds <= 0) {
+      return 0;
+    }
+    let fileLength = 0;
+    try {
+      const stats = await this.getSourceStats(sourceKey, fileIndex);
+      fileLength = Number(stats?.fileLength);
+    } catch {
+      return 0;
+    }
+    if (!Number.isFinite(fileLength) || fileLength <= 0) {
+      return 0;
+    }
+    const bytesPerSecond = fileLength / durationSeconds;
+    const wanted = Math.round(bytesPerSecond * READ_WINDOW_SECONDS);
+    return Math.min(READ_WINDOW_MAX_BYTES, Math.max(READ_WINDOW_MIN_BYTES, wanted));
+  }
+
   #enforceLookAhead() {
     for (const session of this.sessionsById.values()) {
       this.#enforceLookAheadFor(session);
@@ -2075,6 +2125,15 @@ export class HlsSessionManager {
       );
     }
 
+    // The exact command, every run. An encode failure is otherwise reported
+    // with ffmpeg's message and nothing about what it was asked to do, and the
+    // two are not always deducible from each other: 2026-08-04 a run died with
+    // "Cannot write moov atom before AC3 packets" although both muxing paths
+    // were verified to handle a copied AC-3 track on this very host, so the
+    // arguments that run actually received are the missing evidence. One line
+    // per run, and a run happens at most every few seconds.
+    logger.info(`transcode ${session.id} ffmpeg ${args.join(" ")}`);
+
     const ffmpeg = spawn(this.ffmpegBin, args, {
       cwd: session.dirPath,
       stdio: ["ignore", "pipe", "pipe"]

package/services/piece-store/piece-lru.js

@@ -27,6 +27,21 @@ export class PieceLru {
   #order = new Set();
   /** Piece index → number of readers currently holding it. */
   #pins = new Map();
+  /**
+   * Reader id → the piece range it expects to read next.
+   *
+   * Recency alone does not describe this. A reader walking a film touches its
+   * pieces once, so the piece the decoder will want in two seconds looks
+   * exactly as stale as one fetched forty minutes ago and never read again —
+   * and with the encoder running ahead of the viewer, the second kind is what
+   * fills the store. Measured 2026-08-04: the hit rate fell from 100% to 45.7%
+   * with 221 pieces read back from disk in one session.
+   *
+   * A preference, not a pin. At the smallest budget the store guarantees only
+   * two resident pieces, so a hard hold on a window would deadlock it; when
+   * nothing unprotected is left, protection is ignored rather than obeyed.
+   */
+  #protected = new Map();
   #capacity;
 
   /**
@@ -143,6 +158,16 @@ export class PieceLru {
    * @returns {number | null}
    */
   evictionCandidate() {
+    // First choice: the least recently used piece nobody is reading and nobody
+    // is about to read.
+    for (const index of this.#order) {
+      if (!this.#pins.has(index) && !this.#isProtected(index)) {
+        return index;
+      }
+    }
+    // Nothing spare left. Protection yields — it is a preference, and refusing
+    // here would leave the store unable to admit anything at all. Pins do not
+    // yield: a piece being read now cannot have its memory taken away.
     for (const index of this.#order) {
       if (!this.#pins.has(index)) {
         return index;
@@ -151,6 +176,52 @@ export class PieceLru {
     return null;
   }
 
+  /**
+   * Declare the pieces a reader expects to need next, replacing whatever it
+   * declared before. Ranges from different readers add up.
+   *
+   * @param {string|number} readerId - Identity of the reader, so its own range
+   *   is replaced rather than accumulated.
+   * @param {number} from - First piece, inclusive.
+   * @param {number} to - Last piece, inclusive.
+   * @returns {void}
+   */
+  protect(readerId, from, to) {
+    if (!Number.isInteger(from) || !Number.isInteger(to) || to < from) {
+      return;
+    }
+    this.#protected.set(readerId, { from, to });
+  }
+
+  /**
+   * Drop a reader's declared range. Must be called when the reader ends, or its
+   * window keeps occupying the store for a reader that no longer exists.
+   *
+   * @param {string|number} readerId
+   * @returns {void}
+   */
+  unprotect(readerId) {
+    this.#protected.delete(readerId);
+  }
+
+  /** How many readers currently declare a range. */
+  get protectedCount() {
+    return this.#protected.size;
+  }
+
+  /**
+   * @param {number} index
+   * @returns {boolean}
+   */
+  #isProtected(index) {
+    for (const range of this.#protected.values()) {
+      if (index >= range.from && index <= range.to) {
+        return true;
+      }
+    }
+    return false;
+  }
+
   /**
    * Whether admitting one more piece would exceed the capacity.
    *

package/services/piece-store/shared-piece-store.js

@@ -542,6 +542,63 @@ export class SharedPieceStore {
    * @returns {Promise<{ offset: number, length: number } | null>} `null` when
    *   the store holds no such piece, in memory or on disk.
    */
+  /**
+   * Declare the pieces a reader is about to need, so eviction takes something
+   * else while it can. Replaces that reader's previous declaration.
+   *
+   * @param {string|number} readerId
+   * @param {number} from - First piece, inclusive.
+   * @param {number} to - Last piece, inclusive.
+   * @returns {void}
+   */
+  protectRange(readerId, from, to) {
+    this.#lru.protect(readerId, from, to);
+  }
+
+  /**
+   * Forget a reader's declaration. Call it when the reader ends.
+   *
+   * @param {string|number} readerId
+   * @returns {void}
+   */
+  releaseProtection(readerId) {
+    this.#lru.unprotect(readerId);
+  }
+
+  /**
+   * Bring back into memory, in parallel and without waiting, the pieces of a
+   * range that have been spilled to disk.
+   *
+   * A piece is otherwise revived only when the reader arrives at it, one at a
+   * time and in step with decoding, so a seek backward into content already
+   * downloaded pays a disk round trip per piece. The disk is local; the whole
+   * window can be brought back at once while the reader is still on its first
+   * piece.
+   *
+   * Bounded, because each revival needs a slot and unbounded revival of a
+   * window larger than the store would simply thrash. Errors are swallowed: a
+   * failed warm-up costs nothing, the reader will ask for the piece properly.
+   *
+   * @param {number} from - First piece, inclusive.
+   * @param {number} to - Last piece, inclusive.
+   * @param {number} [limit] - Most pieces to revive at once.
+   * @returns {number} How many revivals were started.
+   */
+  warmRange(from, to, limit = Math.max(1, Math.floor(this.#capacity / 4))) {
+    if (this.#closed || !Number.isInteger(from) || !Number.isInteger(to)) {
+      return 0;
+    }
+    let started = 0;
+    for (let index = from; index <= to && started < limit; index += 1) {
+      if (this.#slotOf.has(index) || !this.#disk.has(index)) {
+        continue;
+      }
+      started += 1;
+      void this.reside(index).catch(() => undefined);
+    }
+    return started;
+  }
+
   async reside(index) {
     if (this.#closed) {
       throw new Error("Piece store is closed.");

package/services/playback-planner.js

@@ -7,6 +7,7 @@
  */
 
 import { spawn } from "node:child_process";
+import { logger } from "../utils/logger.js";
 import {
   parseFfmpegDurationSeconds,
   parseFfmpegStartTimeSeconds,
@@ -312,6 +313,14 @@ export function createPlaybackPlanner({
       if (cached) {
         return cached;
       }
+      // Where the time before playback goes. `cold-start` already breaks down
+      // everything from the transcode-session request onwards, but the plan
+      // runs BEFORE that and was a single opaque wait: a field session spent
+      // 5.7 s here on a torrent already in the store, with the codec probe
+      // cached, and nothing said which part of it was slow.
+      const planEntryMs = Date.now();
+      let torrentReadyMs = 0;
+      let edgesReadyMs = 0;
 
       const sourceRecord = sourceRegistry.get(sourceKey);
       if (!sourceRecord) {
@@ -321,6 +330,7 @@ export function createPlaybackPlanner({
       }
 
       const torrent = await torrentPool.getTorrent(sourceRecord.sourceType, sourceRecord.source);
+      torrentReadyMs = Date.now() - planEntryMs;
       const file = torrent.files[fileIndex];
       if (!file) {
         const error = new Error("File index was not found in torrent.");
@@ -354,6 +364,7 @@ export function createPlaybackPlanner({
       // plan (file treated as directly playable) sticks permanently for this
       // file, and an unsupported codec like xvid gets copied → black video.
       await torrentPool.prefetchFileEdges(torrent, fileIndex);
+      edgesReadyMs = Date.now() - planEntryMs;
       let probe = await probeStreamCodecs({ ffmpegBin, inputUrl: directUrl, userAgent });
       const probeDeadline = Date.now() + Math.max(0, maxWaitMs);
       let attempt = 0;
@@ -369,6 +380,12 @@ export function createPlaybackPlanner({
       }
       const { audioCodec, videoCodec, container, durationSeconds, videoWidth, videoHeight, audioTracks, subtitleTracks } = probe;
       const codecsDetected = audioCodec.length > 0 || videoCodec.length > 0;
+      logger.info(
+        `plan ${sourceKey.slice(0, 8)}:${fileIndex} torrent-ready=${torrentReadyMs}ms ` +
+          `file-edges=${edgesReadyMs - torrentReadyMs}ms probe=${Date.now() - planEntryMs - edgesReadyMs}ms ` +
+          `total=${Date.now() - planEntryMs}ms attempts=${attempt + 1} ` +
+          `${codecsDetected ? `${videoCodec || "-"}/${audioCodec || "-"}` : "codecs NOT detected (will be polled again)"}`
+      );
 
       // `mode` is advisory only (audio-codec based). The browser makes the
       // authoritative decision independently per stream via canPlayType /

package/services/torrent-pool.js

@@ -70,6 +70,28 @@ const UPLOAD_BOOST_BYTES = 512 * 1024;           // raised to earn tit-for-tat u
 const UPLOAD_STARVING_SPEED_BYTES = 200 * 1024;  // download below this (with demand) = starving
 const UPLOAD_CHOKED_WIRE_THRESHOLD = 2;          // interested-but-choked wires implying reciprocity
 const UPLOAD_ADJUST_INTERVAL_MS = 5_000;
+/**
+ * How long a torrent counts as being in a hurry after it is added, and after
+ * the viewer moves to a part of the file that is not downloaded.
+ *
+ * BitTorrent gives data to peers that give data back: each peer re-ranks whom
+ * it serves roughly every 10 s and opens a handful of slots to whoever uploaded
+ * most to it, plus one chosen at random. Uploading almost nothing means waiting
+ * to be picked at random, one slot per cycle — which is exactly the ramp
+ * measured 2026-08-04 on a session with 96 peers already connected: 64 KB/s
+ * after 2 s, 1.6 MB/s after 4 s, 4.8 MB/s after 8 s, and the 16 MB the codec
+ * probe needs took 8.36 s of the 11.46 s before playback could start.
+ *
+ * The existing reciprocity boost could not help there: it only fires once the
+ * download has all but stopped (below 200 KB/s) with peers visibly choking us,
+ * and a ramp is neither. In the same session it first raised the limit 13.3 s
+ * after the torrent was added — after the wait it was supposed to shorten — and
+ * reached the generous rate at 43.7 s.
+ *
+ * So the two moments where a viewer is provably waiting get the generous rate
+ * outright, for two unchoke cycles, without waiting for evidence of failure.
+ */
+const UPLOAD_HURRY_MS = 25_000;
 
 /**
  * Decide the client-wide upload limit (bytes/sec) from the torrents that
@@ -84,8 +106,13 @@ const UPLOAD_ADJUST_INTERVAL_MS = 5_000;
  *   are choking us) → boost, to earn unchoke slots.
  * - Otherwise → floor (token upload, avoids an immediate choke without seeding).
  *
- * @param {Array<{ wires?: Array<{ amInterested?: boolean, peerChoking?: boolean }>, downloadSpeed?: number, done?: boolean, name?: string }>} activeTorrents
- * @param {{ floor?: number, idleFloor?: number, boost?: number, starvingSpeed?: number, chokedThreshold?: number }} [opts]
+ * - Any active torrent in a HURRY — just added, or the viewer has just moved
+ *   somewhere the file is not downloaded — → boost for {@link UPLOAD_HURRY_MS},
+ *   because that is when peers must be persuaded to serve us and there is no
+ *   time to first prove that they are not.
+ *
+ * @param {Array<{ wires?: Array<{ amInterested?: boolean, peerChoking?: boolean }>, downloadSpeed?: number, done?: boolean, name?: string, hurryUntil?: number }>} activeTorrents
+ * @param {{ floor?: number, idleFloor?: number, boost?: number, starvingSpeed?: number, chokedThreshold?: number, now?: number }} [opts]
  * @returns {{ bytesPerSec: number, reason: string }}
  */
 export function decideUploadLimit(activeTorrents, opts = {}) {
@@ -94,11 +121,23 @@ export function decideUploadLimit(activeTorrents, opts = {}) {
   const boost = opts.boost ?? UPLOAD_BOOST_BYTES;
   const starvingSpeed = opts.starvingSpeed ?? UPLOAD_STARVING_SPEED_BYTES;
   const chokedThreshold = opts.chokedThreshold ?? UPLOAD_CHOKED_WIRE_THRESHOLD;
+  const now = opts.now ?? Date.now();
 
   if (!Array.isArray(activeTorrents) || activeTorrents.length === 0) {
     return { bytesPerSec: idleFloor, reason: "idle: minimal keep-alive (0 blocks the swarm in wt3.x)" };
   }
 
+  for (const torrent of activeTorrents) {
+    const hurryUntil = typeof torrent?.hurryUntil === "number" ? torrent.hurryUntil : 0;
+    if (hurryUntil > now && torrent?.done !== true) {
+      const name = typeof torrent?.name === "string" ? torrent.name : "?";
+      return {
+        bytesPerSec: boost,
+        reason: `in a hurry — "${name}" needs data now (${Math.round((hurryUntil - now) / 1000)}s left)`
+      };
+    }
+  }
+
   for (const torrent of activeTorrents) {
     const wires = Array.isArray(torrent?.wires) ? torrent.wires : [];
     const chokedInterested = wires.filter(
@@ -395,6 +434,33 @@ export class TorrentPool {
    *
    * @returns {void}
    */
+  /**
+   * Note that a torrent needs data now, and act on it immediately.
+   *
+   * `hurryUntil` is read by {@link decideUploadLimit}; the re-evaluation is
+   * what makes it take effect at once, because the adjuster otherwise runs on a
+   * 5 s timer and the whole hurry is only 25 s long.
+   *
+   * @param {import("webtorrent").Torrent} torrent
+   * @param {string} why - For the log line, so the two causes are told apart.
+   * @returns {void}
+   */
+  #markHurry(torrent, why) {
+    if (!torrent) {
+      return;
+    }
+    const until = Date.now() + UPLOAD_HURRY_MS;
+    if ((torrent.hurryUntil ?? 0) >= until - 1_000) {
+      return;
+    }
+    torrent.hurryUntil = until;
+    logger.info(
+      `torrent-pool: [${String(torrent.infoHash).slice(0, 8)}] uploading generously for ` +
+        `${Math.round(UPLOAD_HURRY_MS / 1000)}s — ${why}`
+    );
+    this.#adjustUploadLimit();
+  }
+
   #adjustUploadLimit() {
     if (!this.client || this.client.destroyed || typeof this.client.throttleUpload !== "function") {
       return;
@@ -477,6 +543,9 @@ export class TorrentPool {
    * @returns {void}
    */
   #attachSwarmDiagnostics(label, torrent) {
+    // A torrent nobody has asked for yet does not exist: this is called the
+    // moment one is added, which is the moment a viewer started waiting.
+    this.#markHurry(torrent, "just added");
     const trackerCount = Array.isArray(torrent.announce) ? torrent.announce.length : 0;
     logger.info(
       `torrent-pool: [${label}] added: files=${torrent.files?.length ?? 0} ` +
@@ -1084,6 +1153,10 @@ export class TorrentPool {
     const isJump =
       previousStart === undefined || Math.abs(safeStart - previousStart) > PRIORITY_WINDOW_BYTES;
     if (isJump) {
+      // A jump is a seek. Whatever the swarm was giving us was for somewhere
+      // else, and the pieces at the new position have to be earned from peers
+      // that are choking us — the same standing start as a fresh torrent.
+      this.#markHurry(torrent, "the viewer moved");
       const percent = ((safeStart / fileLength) * 100).toFixed(1);
       logger.info(
         `torrent-pool: [${String(torrent.infoHash).slice(0, 8)}] read position -> ` +