@torrent-tv/proxy 2.97.6 → 2.97.8

package/package.json

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

package/server.js

@@ -802,6 +802,7 @@ export async function startProxyServer({
     // thread, so the map crosses the worker channel; what it does with it —
     // seconds into bytes, what to ask the swarm for, what to keep in memory —
     // is its own business.
+    setDownloadRate: (bytesPerSecond, because) => torrentPool.setDownloadRate?.(bytesPerSecond, because),
     setPriorityMap: async ({ sourceKey, fileIndex, durationSeconds, zones }) => {
       void sourcePreparation?.refresh();
       const record = sourceRegistry.get(sourceKey);

package/services/encode/EncodeInputs.js

@@ -50,11 +50,12 @@ export class EncodeInputs {
   #failed;
   #capacity;
   #urgent;
+  #rankAt;
   #log;
   #now;
 
   constructor({ resolve, readRanges, heldRanges = null, reviseBudget, changed, failed, capacity = () => null, urgent = () => true,
-    openOf = () => null, log = () => {}, now = Date.now }) {
+    rankAt = () => null, openOf = () => null, log = () => {}, now = Date.now }) {
     this.#openOf = openOf;
     this.#resolve = resolve;
     this.#read = readRanges;
@@ -64,6 +65,7 @@ export class EncodeInputs {
     this.#failed = failed;
     this.#capacity = capacity;
     this.#urgent = urgent;
+    this.#rankAt = rankAt;
     this.#log = log;
     this.#now = now;
   }
@@ -71,12 +73,20 @@ export class EncodeInputs {
   /**
    * One line when a request's state changes, so a wait that never ends names
    * what it waits for. `detail` is said with it and does not count as a change.
+   *
+   * It names the piece the input is prepared FOR and that piece's rank in the
+   * output's map: an input read from the keyframe before starts one piece
+   * early, and its own first piece would understate how urgently it is wanted
+   * (torrent-tv/meta#178).
    */
   #note(request, state, detail = "") {
     if (request.noted === state) return;
     request.noted = state;
+    const serves = request.serves ?? request.from;
+    const rank = this.#rankAt(request.output, serves);
     this.#log(`encode input #${request.from}..#${request.to} of ${request.output.outputKey ?? request.output.id}: ${state}` +
-      ` (held ${this.#held} of ${this.#allowed} allowed)${detail}`);
+      ` (held ${this.#held} of ${this.#allowed} allowed; for #${serves}` +
+      `${rank ? `, rank ${rank.rank} of ${rank.topRank}` : ""})${detail}`);
   }
 
   /** The container's statement of an interval, its time added to the request's account. */
@@ -183,11 +193,14 @@ export class EncodeInputs {
    * `to` is the last number the run may reach. A packet input is prepared for
    * `from` alone; an original input for the longest stretch from `from` that
    * is present, fits memory and copies no longer than an open of that input.
-   * The answer carries the stretch it holds as `from` and `to`.
+   * The answer carries the stretch it holds as `from` and `to`. `serves` is
+   * the piece the run is started for, which is `from` unless the input is read
+   * from the keyframe before.
    */
-  take(output, from, to) {
+  take(output, from, to, serves = from) {
     const key = keyOf(output, from);
     let existing = this.#requests.get(key);
+    if (existing) existing.serves = serves;
     if (existing && existing.to !== to) {
       // The plan's bound for this start moved. A copy already made beyond it
       // holds the shorter stretch whole, so the run is commanded over its
@@ -203,7 +216,7 @@ export class EncodeInputs {
       return existing.result;
     }
     if (existing?.pending || existing?.revision === this.#revision || existing?.result?.kind === "terminal") return null;
-    const request = existing ?? { output, from, to, key };
+    const request = existing ?? { output, from, to, key, serves };
     this.#requests.set(key, request);
     this.#prepare(request);
     return null;

package/services/encode/EncodeRuns.js

@@ -899,7 +899,7 @@ export class EncodeRuns {
     const mayReach = this.#inputFailures.boundFor(session.outputKey, startIndex,
       Number.isInteger(ordered?.to) && ordered.to >= startIndex ? ordered.to
         : segmentCount > startIndex ? segmentCount - 1 : startIndex);
-    const admittedInput = this.#host.encodeInputs?.take(session, inputStart, mayReach) ?? null;
+    const admittedInput = this.#host.encodeInputs?.take(session, inputStart, mayReach, startIndex) ?? null;
     if (!admittedInput) return null;
     const inputEnd = admittedInput.original ? admittedInput.to : startIndex;
     // The stretch is part of an original input's identity: two stretches from

package/services/encode/quality/HostLoad.js

@@ -1,8 +1,8 @@
 /**
  * What the proxy's own work costs this host, read while it runs.
  *
- * The torrent's CPU per megabyte it moves, the share of a core this process
- * draws doing nothing priced, how fast each watched torrent is moving, the speed
+ * The torrent thread's processor per megabyte it downloads, the share of the
+ * machine this process draws doing nothing priced, how fast each watched torrent is moving, the speed
  * each file's supply demands, how long each file is, and how much of the machine
  * a new encoder could have. The encoders' own cost is `EncodeCost`'s.
  */
@@ -30,9 +30,32 @@ export class HostLoad {
   /** The previous reading of the machine, to compare the next one against. */
   #hostLoadSample = null;
 
-  /** The previous reading taken while nothing was encoding, for the torrent's own cost. */
+  /** The previous reading taken while nothing was encoding, for this process's base draw. */
   #idleLoadSample = null;
 
+  /** The previous reading of the torrent thread's processor and the bytes downloaded. */
+  #torrentSample = null;
+
+  /** A reading of the torrent thread is under way; it asks the worker, which may not answer. */
+  #readingTorrent = false;
+
+  /**
+   * The share of the machine the torrent thread draws in intervals that
+   * downloaded nothing: what comes off its spending before the rest is priced
+   * per downloaded byte.
+   */
+  #observedThreadBaseDraw = null;
+
+  /** @type {number[]} Recent readings behind that median. */
+  #threadBaseReadings = [];
+
+  /**
+   * The download limit the processor share last set, bytes per second;
+   * Infinity for none, null before the share ran. Said beside what the
+   * torrents actually moved.
+   */
+  downloadLimit = null;
+
   /** The previous reading of the whole machine taken while nothing was encoding. */
   #idleAvailabilitySample = null;
 
@@ -47,16 +70,21 @@ export class HostLoad {
    */
   fileLengthByKey = new Map();
 
-  /** Seconds of this process's CPU per megabyte the torrent moves, once measured. */
+  /**
+   * The machine's seconds per megabyte downloaded, spent by the torrent thread
+   * (its own processor time divided by the cores, its base draw taken off),
+   * once measured. The torrent's work on other threads — libuv's pool, the main
+   * thread — is not in it. Read by the processor share and the quality offer.
+   */
   observedTorrentCostPerMegabyte = null;
 
   /** @type {number[]} Recent readings behind that median. */
   #torrentCostReadings = [];
 
   /**
-   * The share of one core this process draws with nothing encoding and the
-   * torrents moving nothing — the spending that would have happened anyway, and
-   * which must come off a reading before the rest is called the torrent's.
+   * The share of the machine this process draws with nothing encoding and the
+   * torrents moving nothing — the spending that would have happened anyway.
+   * The processor share takes it off what the proxy has.
    */
   #observedBaseDraw = null;
 
@@ -89,6 +117,11 @@ export class HostLoad {
   /**
    * @param {object} host - `liveRunsOf`, `runStateOf`, the readings of `encode/host-load.js` (`readMachineState`, `readProcessCpuSeconds`, `readProxyCpuSeconds`, `readSystemCpu`, `shareOfMachine`), `getSourceStats`, `getTorrentTotals`, `outputs`
    */
+  /** The share of the machine this process draws doing nothing priced; zero until measured. */
+  get baseDraw() {
+    return this.#observedBaseDraw ?? 0;
+  }
+
   constructor(host) {
     this.#host = host;
   }
@@ -108,60 +141,100 @@ export class HostLoad {
   }
 
   /**
-   * What the torrent itself costs this machine, per megabyte it moves.
+   * What the torrent costs this machine per megabyte it downloads, and what
+   * this process draws when it is doing nothing priced. One reading of the
+   * torrent totals feeds both.
+   *
+   * THE PRICE OF A BYTE is the torrent thread's own processor time against the
+   * bytes every torrent downloaded, both read by that thread in one moment, so
+   * they cover one interval. It is taken whether or not anything encodes: up to
+   * 2.97.7 it was taken only while nothing encoded, and an AVI re-encoded from
+   * the first second of its download never got a price, so the processor share
+   * never limited the download it was built for (field 2026-10-11: 0 limits on
+   * the AVI, 267 on the MKV, torrent-tv/meta#178). The thread's base draw —
+   * what it spends in intervals that downloaded nothing — comes off first, with
+   * the check of `encode/torrent-cost.js` that what is left is more than the
+   * base draw's own scatter; an interval that downloaded nothing is never a
+   * price. The torrent's work on other threads is not counted.
    *
-   * Downloading, verifying every piece and pushing segments down a data channel
-   * are work on the same box as the encoder, they scale with the file's own
-   * bitrate, and the budget counts none of it. Measured on the addon host with
-   * every encoder suspended, the machine was still 20-29 % busy.
+   * THE BASE DRAW OF THIS PROCESS is taken as before: only while nothing
+   * encodes and nothing downloads, and never across metadata parsing.
    *
-   * Taken only while NOTHING is encoding, because that is the only moment the
-   * spending can be attributed without arithmetic: what this process uses then
-   * is the torrent's.
+   * @param {boolean} nothingEncoding
    */
-  async #learnTorrentCost() {
-    const activityBefore = this.#host.readMetadataActivity?.();
-    const bytes = await this.#torrentBytesMoved();
-    const now = {
-      takenAt: Date.now(),
-      cpuSeconds: this.#host.readProxyCpuSeconds(),
-      bytes,
-      metadata: this.#host.readMetadataActivity?.()
-    };
-    const previous = this.#idleLoadSample;
-    this.#idleLoadSample = now;
-    if (previous === null || now.bytes === null || previous.bytes === null) {
-      return;
+  async #learnTorrentCost(nothingEncoding) {
+    if (this.#readingTorrent) return;
+    this.#readingTorrent = true;
+    try {
+      const activityBefore = this.#host.readMetadataActivity?.();
+      const totals = await this.#torrentTotals();
+      const now = {
+        takenAt: Date.now(),
+        cpuSeconds: this.#host.readProxyCpuSeconds(),
+        bytes: totals?.downloaded ?? null,
+        threadCpuSeconds: totals?.threadCpuSeconds ?? null,
+        metadata: this.#host.readMetadataActivity?.()
+      };
+      this.#learnThreadCost(now);
+      if (!nothingEncoding) {
+        this.#idleLoadSample = null;
+        return;
+      }
+      const previous = this.#idleLoadSample;
+      this.#idleLoadSample = now;
+      if (previous === null || now.bytes === null || previous.bytes === null || now.bytes !== previous.bytes) return;
+      // Process CPU includes metadata parsing; an interval holding it is not
+      // what this process draws doing nothing.
+      if (activityBefore?.active || now.metadata?.active || previous.metadata?.active ||
+        activityBefore?.epoch !== now.metadata?.epoch || previous.metadata?.epoch !== now.metadata?.epoch) return;
+      const elapsedSec = (now.takenAt - previous.takenAt) / 1000;
+      // Divided by the cores: `process.cpuUsage()` adds up every thread, while
+      // everything this figure is set against is a share of the whole machine.
+      const cpuSeconds = (now.cpuSeconds - previous.cpuSeconds) / Math.max(1, os.cpus().length);
+      this.#learnBaseDraw(baseDrawFrom({ cpuSeconds, elapsedSeconds: elapsedSec }));
+    } finally {
+      this.#readingTorrent = false;
     }
-    // Process CPU includes metadata parsing. Keep the sample as a baseline,
-    // but never attribute an interval containing that work to torrent bytes.
-    if (activityBefore?.active || now.metadata?.active || previous.metadata?.active ||
-      activityBefore?.epoch !== now.metadata?.epoch || previous.metadata?.epoch !== now.metadata?.epoch) return;
+  }
+
+  /**
+   * One interval of the torrent thread: its base draw where it downloaded
+   * nothing, a price where it downloaded something, and what it moved against
+   * the limit in force, said while anything moves or is limited.
+   *
+   * @param {{ takenAt: number, bytes: number | null, threadCpuSeconds: number | null }} now
+   */
+  #learnThreadCost(now) {
+    const previous = this.#torrentSample;
+    this.#torrentSample = now;
+    if (previous === null || now.bytes === null || previous.bytes === null ||
+      now.threadCpuSeconds === null || previous.threadCpuSeconds === null) return;
     const elapsedSec = (now.takenAt - previous.takenAt) / 1000;
     const megabytes = (now.bytes - previous.bytes) / 1e6;
-    // Divided by the cores, because `process.cpuUsage()` adds up every thread
-    // while everything this figure is later added to is measured in WALL
-    // seconds per second of video. Left undivided on the four-core addon host
-    // it overstated the torrent by four times, which on the field's own rung
-    // was the difference between offering it and refusing it.
-    const cores = Math.max(1, os.cpus().length);
-    const cpuSeconds = (now.cpuSeconds - previous.cpuSeconds) / cores;
+    // A torrent leaving the pool takes its bytes out of the total, and a new
+    // worker starts its clock again: such an interval says nothing.
+    if (!(elapsedSec > 0) || megabytes < 0 || now.threadCpuSeconds < previous.threadCpuSeconds) return;
+    const cpuSeconds = (now.threadCpuSeconds - previous.threadCpuSeconds) / Math.max(1, os.cpus().length);
+    const limit = this.downloadLimit;
+    if (megabytes > 0 || Number.isFinite(limit)) {
+      logger.info(
+        `torrent: downloaded ${(megabytes / elapsedSec).toFixed(2)} MB/s over ${elapsedSec.toFixed(1)}s, ` +
+        `limit ${Number.isFinite(limit) ? `${(limit / 1e6).toFixed(2)} MB/s` : "none"}; ` +
+        `its thread drew ${Math.round(cpuSeconds / elapsedSec * 100)}% of the machine`
+      );
+    }
     if (megabytes === 0) {
-      // Nothing encoding and not one byte moved: whatever this process spent in
-      // that interval, it spends whether or not there is a torrent. Measuring
-      // it is what lets the next interval be attributed instead of divided
-      // whole — see `encode/torrent-cost.js` for the readings that forced this.
-      this.#learnBaseDraw(baseDrawFrom({ cpuSeconds, elapsedSeconds: elapsedSec }));
+      this.#learnThreadBaseDraw(baseDrawFrom({ cpuSeconds, elapsedSeconds: elapsedSec }));
       return;
     }
     const costPerMegabyte = costPerMegabyteFrom({
       cpuSeconds,
       elapsedSeconds: elapsedSec,
       megabytes,
-      baseDraw: this.#observedBaseDraw,
-      // How much the draw's own readings disagree, which is how much of this
-      // interval's remainder means nothing.
-      drawScatter: scatterOf(this.#baseDrawReadings)
+      baseDraw: this.#observedThreadBaseDraw,
+      // How much the base draw's own readings disagree, which is how much of
+      // this interval's remainder means nothing.
+      drawScatter: scatterOf(this.#threadBaseReadings)
     });
     if (costPerMegabyte === null) {
       return;
@@ -174,9 +247,31 @@ export class HostLoad {
     }
     this.observedTorrentCostPerMegabyte = median;
     logger.info(
-      `host-load: the torrent costs ${(median * 1000).toFixed(1)}ms of CPU per MB on this host ` +
+      `host-load: the torrent thread costs ${(median * 1000).toFixed(1)}ms of the machine per downloaded MB ` +
       `(median of ${readings.length}, latest ${(costPerMegabyte * 1000).toFixed(1)}ms over ${megabytes.toFixed(1)}MB, ` +
-      `base draw ${((this.#observedBaseDraw ?? 0) * 100).toFixed(1)}% of a core already taken off)`
+      `its base draw ${((this.#observedThreadBaseDraw ?? 0) * 100).toFixed(1)}% of the machine taken off)`
+    );
+  }
+
+  /**
+   * What the torrent thread draws in an interval that downloaded nothing.
+   *
+   * @param {number | null} share - Of the machine, over the interval just read.
+   */
+  #learnThreadBaseDraw(share) {
+    if (share === null) {
+      return;
+    }
+    const readings = [...this.#threadBaseReadings, share].slice(-READINGS_KEPT);
+    this.#threadBaseReadings = readings;
+    const median = medianOf(readings);
+    if (!movedBeyondScatter(this.#observedThreadBaseDraw, median, readings)) {
+      return;
+    }
+    this.#observedThreadBaseDraw = median;
+    logger.info(
+      `host-load: the torrent thread draws ${(median * 100).toFixed(1)}% of the machine while it downloads nothing ` +
+      `(median of ${readings.length}, latest ${(share * 100).toFixed(1)}%)`
     );
   }
 
@@ -303,7 +398,7 @@ export class HostLoad {
    * Record what this process draws when it is doing none of the work that gets
    * priced.
    *
-   * @param {number | null} share - Of one core, over the interval just read.
+   * @param {number | null} share - Of the machine, over the interval just read.
    * @returns {void}
    */
   #learnBaseDraw(share) {
@@ -318,29 +413,31 @@ export class HostLoad {
     }
     this.#observedBaseDraw = median;
     logger.info(
-      `host-load: this process draws ${(median * 100).toFixed(1)}% of a core with nothing encoding and ` +
+      `host-load: this process draws ${(median * 100).toFixed(1)}% of the machine with nothing encoding and ` +
       `nothing downloading (median of ${readings.length}, latest ${(share * 100).toFixed(1)}%)`
     );
   }
 
   /**
-   * Bytes this proxy's torrents have moved in total, or null when it cannot be
-   * asked.
+   * The bytes every torrent has downloaded and the torrent thread's processor
+   * seconds, read together by that thread, or null when it cannot be asked.
+   * Downloaded bytes only: every one is verified against the piece hash and
+   * written to the store; a byte sent back to the swarm is neither.
    *
-   * @returns {Promise<number | null>}
+   * @returns {Promise<{ downloaded: number | null, threadCpuSeconds: number | null } | null>}
    */
-  async #torrentBytesMoved() {
+  async #torrentTotals() {
     if (typeof this.#host.getTorrentTotals !== "function") {
       return null;
     }
     try {
       const totals = await this.#host.getTorrentTotals();
-      // Downloaded bytes only. Every one of them is verified against the piece
-      // hash and written to the store; a byte sent back to the swarm is neither,
-      // and adding the two would price both at whatever the mixture happened to
-      // be on the day.
       const downloaded = Number(totals?.downloaded);
-      return Number.isFinite(downloaded) ? downloaded : null;
+      const threadCpuSeconds = Number(totals?.threadCpuSeconds);
+      return {
+        downloaded: Number.isFinite(downloaded) ? downloaded : null,
+        threadCpuSeconds: Number.isFinite(threadCpuSeconds) ? threadCpuSeconds : null
+      };
     } catch {
       return null; // the pool is busy or gone; a reading missed is not a fault
     }
@@ -370,9 +467,7 @@ export class HostLoad {
     } finally {
       this.#reporting = false;
     }
-    if (nothingEncoding) {
-      await this.#learnTorrentCost();
-    }
+    await this.#learnTorrentCost(nothingEncoding);
   }
 
   /**
@@ -381,7 +476,7 @@ export class HostLoad {
    * in force for ever: it refused every new encoder, and a refused encoder is
    * the only thing that would have taken the next reading.
    */
-  async #learnIdleAvailability() {
+  async #learnIdleAvailability(watched, suspended) {
     const system = (await this.#host.readSystemCpu?.()) ?? null;
     const sample = { takenAt: Date.now(), system, proxyCpuSeconds: this.#host.readProxyCpuSeconds() };
     const previous = this.#idleAvailabilitySample;
@@ -394,7 +489,36 @@ export class HostLoad {
       { takenAt: previous.takenAt, processCpuSeconds: 0, system: previous.system },
       { takenAt: sample.takenAt, processCpuSeconds: 0, system: sample.system }
     );
-    this.#setAvailability(share, previous, sample);
+    const proxyShare = this.#setAvailability(share, previous, sample);
+    // Said while something is watched, so what is free while every encoder
+    // stands is seen beside what it is free for (torrent-tv/meta#178); a proxy
+    // nobody watches stays quiet.
+    if (share !== null && watched) {
+      await this.#sayMachine(share, proxyShare, 0, suspended);
+    }
+  }
+
+  /**
+   * One line of the machine's reading, the same whether encoders run or stand.
+   * `available` is the share OTHER processes leave the proxy, what the offer
+   * and the processor share divide; `free` is what nothing used over the
+   * interval. Unknown stays `n/a`, never zero.
+   */
+  async #sayMachine(share, proxyShare, running, suspended) {
+    const machine = await this.#host.readMachineState();
+    const asPercent = (value) => (value === null || value === undefined ? "n/a" : `${Math.round(value * 100)}%`);
+    const free = Number.isFinite(share.systemShare) ? Math.max(0, 1 - share.systemShare) : null;
+    logger.info(
+      `host-load: ffmpeg=${asPercent(share.processShare)} proxy=${asPercent(proxyShare)} ` +
+      `system=${asPercent(share.systemShare)} ` +
+      `iowait=${asPercent(share.iowaitShare)} cpu=${machine.megahertz === null ? "n/a" : `${machine.megahertz}MHz`} ` +
+      `temp=${machine.celsius === null ? "n/a" : `${machine.celsius}C`} ` +
+      `encoders=${running} running` + (suspended > 0 ? ` +${suspended} suspended` : "") +
+      ` over=${share.elapsedSec.toFixed(1)}s` +
+      // What the offer will multiply a prediction by, in the same line as the
+      // readings it comes from.
+      ` available=${asPercent(this.hostAvailability.share)} free=${asPercent(free)}`
+    );
   }
 
   /**
@@ -428,7 +552,8 @@ export class HostLoad {
 
   /** @returns {Promise<boolean>} True when no encoder is running, which is when the torrent's cost can be taken. */
   async #reportMachineOnce() {
-    const encoding = [...this.#host.outputs.values()].filter(
+    const outputs = [...this.#host.outputs.values()];
+    const encoding = outputs.filter(
       (session) => processCanBeSignalled(this.#host.runStateOf(session))
     );
     const runningNow = encoding.filter((session) => this.#host.runStateOf(session) !== ENCODE_RUN_STATE.SUSPENDED);
@@ -438,7 +563,8 @@ export class HostLoad {
       // in which every encoder was suspended, the torrent's price could have
       // been taken, and none was. What this process spends now is the download,
       // the verification, the piece store and the delivery. Item 7.
-      await this.#learnIdleAvailability();
+      await this.#learnIdleAvailability(outputs.length > 0,
+        encoding.filter((session) => this.#host.runStateOf(session) === ENCODE_RUN_STATE.SUSPENDED).length);
       this.#hostLoadSample = null;
       return true;
     }
@@ -509,24 +635,12 @@ export class HostLoad {
     // they stopped).
     const suspended = encoding.filter((session) => this.#host.runStateOf(session) === ENCODE_RUN_STATE.SUSPENDED).length;
     const running = encoding.length - suspended;
-    const machine = await this.#host.readMachineState();
-    const asPercent = (value) => (value === null ? "n/a" : `${Math.round(value * 100)}%`);
     // Kept for the quality offer, which predicts from a benchmark taken on a
     // QUIET host: the same reading that is printed here says how much of the
     // machine a new encoder could actually have. Only what nobody has been
     // charged for is subtracted — see `encode/available-share.js`.
     const proxyShare = this.#setAvailability(share, previous, sample);
-    logger.info(
-      `host-load: ffmpeg=${asPercent(share.processShare)} proxy=${asPercent(proxyShare)} ` +
-      `system=${asPercent(share.systemShare)} ` +
-      `iowait=${asPercent(share.iowaitShare)} cpu=${machine.megahertz === null ? "n/a" : `${machine.megahertz}MHz`} ` +
-      `temp=${machine.celsius === null ? "n/a" : `${machine.celsius}C`} ` +
-      `encoders=${running} running` + (suspended > 0 ? ` +${suspended} suspended` : "") +
-      ` over=${share.elapsedSec.toFixed(1)}s` +
-      // What the offer will multiply a prediction by, in the same line as the
-      // readings it comes from.
-      ` available=${asPercent(this.hostAvailability.share)}`
-    );
+    await this.#sayMachine(share, proxyShare, running, suspended);
     return false;
   }
 
@@ -536,8 +650,9 @@ export class HostLoad {
    *
    * A viewer consumes the file at its own byte rate, and every one of those
    * bytes is downloaded, verified and pushed by this process. Priced per
-   * megabyte from readings taken while nothing was encoding, so the two
-   * measurements do not contain each other. Zero while either term is unmeasured
+   * megabyte by the torrent thread's own processor time, which no encoder's
+   * reading contains, so the two do not contain each other; the torrent's
+   * work on other threads is not in it. Zero while either term is unmeasured
    * — a guess here would refuse rungs on arithmetic nobody performed.
    *
    * @param {HlsSession} session

package/services/server/wire-outputs.js

@@ -97,6 +97,8 @@ import path from "node:path";
 import { contentOf, LocalObservations, PROXY_ROOT } from "../encode/LocalObservations.js";
 import { configurationKeyOf } from "../encode/fingerprint.js";
 import { qualityStateOf } from "../encode/quality/OutputQualityState.js";
+import { downloadShare } from "../storage/processor-share.js";
+import { ENCODE_RUN_STATE, processCanBeSignalled } from "../encode/encode-run-state.js";
 
 // Where a variant and an audio rendition live under a session — `v/<height>/…`
 // and `a/<track>/…` — is stated in `encode/output/playlists.js`, beside the lines that
@@ -193,6 +195,7 @@ export function wireOutputs({
     decodeCostModel = null,
     getSourceStats = null,
     setPriorityMap = null,
+    setDownloadRate = null,
     // What a second job costs on this host, measured at startup. Null when it
     // could not be measured, and then nothing is corrected — the alternative
     // is inventing a penalty, which is the same fault as inventing a fill rate.
@@ -342,7 +345,7 @@ export function wireOutputs({
     get encoders() { return parts.encoders; },
     invalidateWaits: (output) => parts.serving.invalidateWaits(output),
     productionFailed: (output) => parts.renditions.noteProductionFailed(output),
-    encodersChanged: () => onEncodersChanged?.(),
+    encodersChanged: () => { parts.applyDownloadShare?.(); onEncodersChanged?.(); },
   });
   // How much film is ready in front of the viewers, said; and the spare soundtracks fetched once it is full.
   parts.cushion = new CushionReport({
@@ -648,6 +651,34 @@ export function wireOutputs({
   // (sourceKey, fileIndex) => Promise<{ downloadSpeed, fileLength, fileProgress } | null>.
   parts.getSourceStats = typeof getSourceStats === "function" ? getSourceStats : null;
   parts.setPriorityMap = typeof setPriorityMap === "function" ? setPriorityMap : null;
+  parts.setDownloadRate = typeof setDownloadRate === "function" ? setDownloadRate : null;
+  // HOW FAST THE TORRENTS MAY DOWNLOAD: the processor the encoders leave
+  // (`storage/processor-share.js`, torrent-tv/meta#178). Worked out again
+  // when the machine is read and when an encoder starts or ends, over every
+  // watched file of every torrent.
+  parts.applyDownloadShare = () => {
+    if (!parts.setDownloadRate || !parts.hostLoad || !parts.encodeCost) return;
+    const files = new Map();
+    for (const output of parts.outputs.values()) {
+      if (!(parts.viewers?.forOutput(output)?.size > 0)) continue;
+      const key = output.file.key;
+      const length = Number(output.file.lengthBytes ?? parts.hostLoad.fileLengthByKey.get(key));
+      const file = files.get(key) ?? { bytesPerFilmSecond: length / Number(output.file.durationSeconds), encodeCostSec: 0 };
+      const state = parts.encodeRuns.runStateOf(output);
+      if (processCanBeSignalled(state) && state !== ENCODE_RUN_STATE.SUSPENDED) {
+        file.encodeCostSec += parts.encodeCost.loadOfOutput(output.outputKey)?.costSec ?? 0;
+      }
+      files.set(key, file);
+    }
+    const watched = [...files.values()].filter((file) => Number.isFinite(file.bytesPerFilmSecond) && file.bytesPerFilmSecond > 0);
+    const share = downloadShare({ availableShare: parts.hostLoad.hostAvailability?.share ?? 1,
+      baseDraw: parts.hostLoad.baseDraw, costPerMegabyte: parts.hostLoad.observedTorrentCostPerMegabyte, files: watched });
+    // Kept beside the readings it is judged against: what the torrents moved
+    // over each interval is said next to the limit in force (meta#178).
+    parts.hostLoad.downloadLimit = share.bytesPerSecond;
+    void Promise.resolve(parts.setDownloadRate(share.bytesPerSecond, `film speed ${share.filmSpeed.toFixed(2)}x ` +
+      `over ${watched.length} file(s), ${Math.round(share.capacity * 100)}% of the machine for the proxy`)).catch(() => {});
+  };
   parts.contentionPenalties = contentionPenalties instanceof Map ? contentionPenalties : null;
   // Seconds of film per second when the picture is COPIED, measured at
   // startup. Nothing else prices that branch: the other benchmarks measure
@@ -980,6 +1011,8 @@ export function wireOutputs({
     openOf: (output) => parts.encodeOrchestrator?.openOf?.(output.outputKey ?? "") ?? null,
     urgent: (output, index) => parts.encodeOrchestrator.wantedSegmentsOn(output.outputKey).some(window =>
       index >= window.from && index <= window.to && window.urgent === true),
+    // The piece's rank in the output's own map, said with an input's state.
+    rankAt: (output, index) => parts.encodeOrchestrator?.rankAt?.(output.outputKey ?? "", index) ?? null,
     log: line => logger.info(line),
     changed: (output, result) => {
       if (result.kind === "terminal") {
@@ -1060,7 +1093,7 @@ export function wireOutputs({
     liveConsumers: (...args) => parts.renditions.liveConsumers(...args),
     liveRunsOf: (...args) => parts.encodeRuns.liveRunsOf(...args),
     producedNumbers: (...args) => parts.serving.producedNumbers(...args),
-    reportHostLoad: (...args) => parts.hostLoad.reportHostLoad(...args),
+    reportHostLoad: async (...args) => { await parts.hostLoad.reportHostLoad(...args); parts.applyDownloadShare?.(); },
     runStateOf: (...args) => parts.encodeRuns.runStateOf(...args),
     sampleDownloadRates: (...args) => parts.hostLoad.sampleDownloadRates(...args),
     get encodeCost() { return parts.encodeCost; },

package/services/storage/processor-share.js

@@ -0,0 +1,57 @@
+/**
+ * @file How fast the torrents may download, so that downloading does not take
+ * the processor the encoders need (torrent-tv/meta#178).
+ *
+ * Field 2026-10-11, Home Assistant: an AVI re-encoded at 720x400 needed 2.3 s
+ * of one core per second of film. While the torrent downloaded 4.5-9.8 MB/s —
+ * mostly far ahead of the viewer — its thread took 56-63 % of a core, ffmpeg
+ * got 176-182 %, below real time, and the viewer saw the spinner; once the
+ * download stopped ffmpeg got 216-261 % and there were no stops.
+ *
+ * THE MODEL, every term a share of the WHOLE MACHINE. The processor the proxy
+ * has, `C`, is the share other processes leave (`encode/available-share.js`)
+ * less what this process draws doing nothing priced. Every watched file `f` of
+ * every torrent advances at a film speed `s`: its running encoders take `s·k_f`
+ * (`k_f` the machine's seconds per second of film, the inverse of the encode
+ * speed) and its download `s·w_f·c` (`w_f` its bytes per second of film, `c`
+ * the machine's seconds per byte the torrent thread spends). One speed for all
+ * is the division under which the slowest file is as fast as it can be:
+ *
+ *     s* = C / Σ_f (k_f + w_f·c),    download rate = max(s*, 1) · Σ_f w_f
+ *
+ * Up to 2.97.7 `C` was counted in cores while `k` and `c` were shares of the
+ * machine, so on the four-core addon host the limit was about four times
+ * looser than this model.
+ *
+ * Downloading faster than `s*·w` only piles bytes ahead while the encoders
+ * starve; what is fetched first within the rate is the priority map's order.
+ * The rate never falls below the films' own byte rate, `Σ w`, because below it
+ * the viewer stops whatever the encoders get. Where `s* < 1` or the swarm
+ * gives less than the rate, stops cannot be avoided, and the start forecast,
+ * reading the speeds measured under this rate, waits for them at the start
+ * and after a seek. With nothing encoding `k` is zero and the download has the
+ * processor. A term nobody has measured contributes nothing: an unmeasured
+ * price of a byte leaves the download unlimited.
+ */
+
+/**
+ * @param {object} params
+ * @param {number} params.availableShare - The share of the machine other processes leave, 0..1.
+ * @param {number} params.baseDraw - The share of the machine this process draws doing nothing priced.
+ * @param {number | null} params.costPerMegabyte - The machine's seconds per megabyte the torrent moves.
+ * @param {{ bytesPerFilmSecond: number, encodeCostSec: number }[]} params.files - Watched files.
+ * @returns {{ filmSpeed: number, bytesPerSecond: number, capacity: number }}
+ *   `capacity` is a share of the machine; `bytesPerSecond` is Infinity where
+ *   the download is not limited.
+ */
+export function downloadShare({ availableShare, baseDraw, costPerMegabyte, files }) {
+  const capacity = Math.max(0, availableShare - baseDraw);
+  // A byte whose price is not measured, or costs nothing, takes nothing from
+  // the encoders: there is then no share to keep the download to.
+  const perByte = Number.isFinite(costPerMegabyte) && costPerMegabyte > 0 ? costPerMegabyte / 1e6 : 0;
+  const bytes = files.reduce((sum, file) => sum + file.bytesPerFilmSecond, 0);
+  const demand = files.reduce((sum, file) => sum + file.encodeCostSec + file.bytesPerFilmSecond * perByte, 0);
+  const filmSpeed = capacity / demand;
+  const bytesPerSecond = perByte > 0 ? Math.max(filmSpeed, 1) * bytes : Infinity;
+  return { filmSpeed, capacity, bytesPerSecond: Number.isFinite(bytesPerSecond) && bytes > 0 ? bytesPerSecond : Infinity };
+}

package/services/torrent/torrent-pool.js

@@ -1261,6 +1261,35 @@ export class TorrentPool {
    *   film against a number, highest first in urgency.
    * @param {number} durationSeconds
    */
+  /**
+   * How fast every torrent may download in all: the share of the processor
+   * the encoders leave (`storage/processor-share.js`, torrent-tv/meta#178).
+   * Within it the swarm is asked for what the priority map puts first.
+   *
+   * @param {number | null} bytesPerSecond - Infinity or null for no limit.
+   * @param {string} [because]
+   */
+  setDownloadRate(bytesPerSecond, because = "") {
+    if (!this.client || this.client.destroyed || typeof this.client.throttleDownload !== "function") return;
+    const rate = Number.isFinite(bytesPerSecond) ? Math.max(1, Math.round(bytesPerSecond)) : -1;
+    if (rate === this.#downloadLimit) return;
+    this.client.throttleDownload(rate);
+    // Said when the limit is set or lifted, and when it moves by a factor of
+    // two either way — the scale on which a limit changes what the swarm gives.
+    const scale = rate < 0 ? null : Math.round(Math.log2(rate));
+    if (scale !== this.#downloadLimitScale) {
+      this.#downloadLimitScale = scale;
+      logger.info(`torrent-pool: download limit -> ${rate < 0 ? "none" : `${Math.round(rate / 1024)} KB/s`}${because ? ` (${because})` : ""}`);
+    }
+    this.#downloadLimit = rate;
+  }
+
+  /** The download limit in force, -1 for none. */
+  #downloadLimit = -1;
+
+  /** The power of two the last limit said was nearest, null for none. */
+  #downloadLimitScale = null;
+
   applyPriorityMap(torrent, fileIndex, zones, durationSeconds) {
     // A MAP WITH NOTHING IN IT IS A STATEMENT, and it is answered before
     // anything else is looked at. It says nobody wants any of this file, and

package/services/torrent/worker/client.js

@@ -475,6 +475,17 @@ export class TorrentWorkerClient {
    * @param {{ sourceKey: string, fileIndex: number, durationSeconds: number, zones: { from: number, to: number, priority: number }[] }} params
    * @returns {Promise<void>}
    */
+  /**
+   * How fast the torrents may download in all (`Command.DOWNLOAD_RATE`).
+   *
+   * @param {number} bytesPerSecond - Infinity for no limit.
+   * @param {string} [because]
+   * @returns {Promise<void>}
+   */
+  async setDownloadRate(bytesPerSecond, because = "") {
+    return this.#caller.call(Command.DOWNLOAD_RATE, { bytesPerSecond: Number.isFinite(bytesPerSecond) ? bytesPerSecond : null, because });
+  }
+
   async setPriorityMap({ sourceKey, fileIndex, zones, durationSeconds, postedAt }) {
     return this.#caller.call(Command.PRIORITY_MAP, {
       sourceKey,

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

@@ -164,6 +164,17 @@ export class WorkerTorrentPool {
    * @param {{ sourceKey: string, fileIndex: number, durationSeconds: number, zones: object[] }} params
    * @returns {Promise<void>}
    */
+  /**
+   * How fast the torrents may download in all, Infinity for no limit.
+   *
+   * @param {number} bytesPerSecond
+   * @param {string} [because]
+   * @returns {Promise<void>}
+   */
+  async setDownloadRate(bytesPerSecond, because = "") {
+    return this.#client.setDownloadRate(bytesPerSecond, because);
+  }
+
   async setPriorityMap({ sourceKey, fileIndex, durationSeconds, zones, postedAt }) {
     if (!sourceKey) {
       return;

package/services/torrent/worker/protocol.js

@@ -66,6 +66,12 @@ export const Command = {
    * sixteen pieces is what tore a film apart on 2026-09-05.
    */
   PRIORITY_MAP: "priority-map",
+  /**
+   * How fast the torrents may download in all, in bytes per second, or
+   * Infinity for no limit: the share of the processor the encoders leave
+   * (`storage/processor-share.js`, torrent-tv/meta#178).
+   */
+  DOWNLOAD_RATE: "download-rate",
   /** Read a byte range; the body arrives as CHUNK messages. */
   READ_RANGE: "read-range",
   /** Abandon an in-flight READ_RANGE (viewer gone, seek superseded). */

package/services/torrent/worker/worker.js

@@ -419,7 +419,11 @@ async function runCommand(command, params, id) {
         downloaded += Number.isFinite(gotBytes) ? gotBytes : 0;
         uploaded += Number.isFinite(sentBytes) ? sentBytes : 0;
       }
-      return { downloaded, uploaded };
+      // This thread's own processor time, read in the same moment as the
+      // bytes, so the price of a downloaded byte is taken over one interval
+      // whether or not anything encodes (torrent-tv/meta#178).
+      const usage = process.threadCpuUsage();
+      return { downloaded, uploaded, threadCpuSeconds: (usage.user + usage.system) / 1e6 };
     }
 
 
@@ -476,6 +480,11 @@ async function runCommand(command, params, id) {
       return { appliedMs: performance.now() - startedAt, receivedAt, repliedAt: performance.timeOrigin + performance.now() };
     }
 
+    case Command.DOWNLOAD_RATE: {
+      pool.setDownloadRate(params.bytesPerSecond, params.because);
+      return true;
+    }
+
     case Command.READ_RANGE: {
       // Streams its own reply; the caller's promise resolves once the body has
       // been fully sent, which is what lets the client await completion.