@torrent-tv/proxy 2.101.2 → 2.101.4

package/bin/cli.js

@@ -90,7 +90,6 @@ program
   .option("--no-port-mapping", "Disable automatic UPnP/NAT-PMP port mapping")
   .option("--delivery-sink", "Serve /api/delivery-sink, a torrent-free byte stream for delivery testing")
   .option("--pin-preset <name>", "Encode every software picture at this libx264 preset only, for runs that must be compared at one quality (off by default)")
-  .option("--input-stretch-bytes <bytes>", "Size every original-input stretch to this many bytes instead of copy rate times open, for runs that compare input sizes; memory, downloaded bytes and the plan still bound it (off by default)")
   .option("--heap-snapshots", "Write a heap snapshot of a thread whose memory reaches a new high-water; each one stops that thread while it is written (off by default)")
   .option("--profile-start <seconds>", "Profile the CPU of the main thread and the torrent thread for this many seconds from the first source opened, written beside the state (off by default)")
   .option(
@@ -400,7 +399,6 @@ try {
     profileStartSeconds: Number(options.profileStart) || 0,
     heapSnapshots: options.heapSnapshots === true,
     pinnedPreset: typeof options.pinPreset === "string" && options.pinPreset.trim() ? options.pinPreset.trim() : null,
-    inputStretchBytes: Number(options.inputStretchBytes) > 0 ? Math.floor(Number(options.inputStretchBytes)) : null,
     // Late-bound the same way `webRtcManager` is below: the torrent pool is
     // built inside `startProxyServer`, before `dataChannelHandler` — the
     // thing that actually owns a channel to push down — exists.

package/package.json

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

package/server.js

@@ -88,6 +88,7 @@ import { takeTurns } from "./utils/take-turns.js";
 import { completedFilesRoot } from "./services/storage/files/CompletedFiles.js";
 import { startupCpuProfile } from "./services/storage/cpu-profile.js";
 import { startProcessorReport } from "./services/storage/processor-report.js";
+import { processorBound } from "./services/storage/machine-processor.js";
 
 const require = createRequire(import.meta.url);
 const { version } = require("./package.json");
@@ -134,9 +135,6 @@ export async function startProxyServer({
   // The one software preset every picture is encoded at, for runs compared at
   // one quality; null leaves the choice to the machine.
   pinnedPreset = null,
-  // The size every original-input stretch is given in place of copy rate
-  // times open, for runs that compare input sizes; null keeps the rule.
-  inputStretchBytes = null,
   // What viewers' connections carry beyond the film, per byte of film; the
   // transport counts it and is built after this server, so it is late-bound.
   serviceShare = () => null,
@@ -234,6 +232,10 @@ export async function startProxyServer({
   let videoEncoder = transcodeAudio
     ? await detectVideoEncoder({ ffmpegBin, logger })
     : null;
+  // The cores this process may use (a container's quota or CPU set): the
+  // readings below divide out a share of those, the unit every later share of
+  // the machine is in (torrent-tv/meta#180, phase 3).
+  const processorCores = processorBound().cores;
   // WHAT THIS HOST DOES, measured before any viewer exists. Every one of these
   // was gated on the chosen encoder being SOFTWARE, and two of the three are
   // not about the encoder at all: a host with a GPU decodes in software just
@@ -246,7 +248,7 @@ export async function startProxyServer({
   // (the rungs are timed on raw frames), but the order keeps the two figures
   // side by side in the log.
   const decodeCostModel = transcodeAudio
-    ? await benchmarkDecodeCost({ ffmpegBin, logger })
+    ? await benchmarkDecodeCost({ ffmpegBin, logger, processorCores })
     : null;
   // What a second job costs on this host. Measured because the budget adds
   // independent prices and this host says two jobs that each fit alone do not
@@ -267,16 +269,16 @@ export async function startProxyServer({
   // the processor and the threads, the device and its driver — which is what
   // decides whether anything kept from an earlier run still applies.
   const fingerprint = videoEncoder
-    ? await readHostFingerprint({ ffmpegBin, encoder: videoEncoder })
+    ? await readHostFingerprint({ ffmpegBin, encoder: videoEncoder, processorCores })
     : null;
   /** @type {Record<string, object[]>} */
   const calibratedModes = {};
   if (videoEncoder) {
     calibratedModes[videoEncoder.kind] =
-      (await calibrateEncoder({ ffmpegBin, encoder: videoEncoder, logger })).modes;
+      (await calibrateEncoder({ ffmpegBin, encoder: videoEncoder, logger, processorCores })).modes;
     if (videoEncoder.kind !== "software") {
       calibratedModes.software =
-        (await calibrateEncoder({ ffmpegBin, encoder: softwareDescriptor(), logger })).modes;
+        (await calibrateEncoder({ ffmpegBin, encoder: softwareDescriptor(), logger, processorCores })).modes;
       // A device that passed detection's own test and then none of whose modes
       // passed the product's is not used: detection encodes a synthetic pattern
       // with arguments of its own, and it is the product's arguments a viewer
@@ -857,7 +859,6 @@ export async function startProxyServer({
   let sourcePreparation;
   const outputParts = wireOutputs({
     pinnedPreset,
-    inputStretchBytes,
     indexMemory,
     serviceShare,
     readMetadataActivity: () => containerOrchestrator.activity(),
@@ -1158,7 +1159,9 @@ export async function startProxyServer({
         film: Number(run.progress?.processedSeconds) - Number(run.progress?.startPositionSeconds ?? 0)
       })))
       .filter((run) => Number.isInteger(run.pid)),
-    detailed: () => startupProfile.active()
+    detailed: () => startupProfile.active(),
+    // What the pause rule judges from (torrent-tv/meta#180, phase 4).
+    onRunSeconds: (seconds) => outputParts.encodeOrchestrator?.noteRunSeconds(seconds)
   });
   // What the last life of this process left on the disk. The kernel kills this
   // one often enough for that to be an ordinary state rather than an odd one —

package/services/encode/EncodeInputs.js

@@ -62,20 +62,10 @@ export class EncodeInputs {
    * @type {(output: object, from: number, to: number, input: object) => void}
    */
   #stretchCopied;
-  /**
-   * A stretch size the operator named for comparison runs
-   * (`--input-stretch-bytes`), in place of copy rate times open; null keeps
-   * the measured rule. Only the target changes: memory, downloaded bytes and
-   * the plan's bound still end a stretch (torrent-tv/meta#182).
-   *
-   * @type {number | null}
-   */
-  #fixedStretchBytes;
 
   constructor({ resolve, readRanges, heldRanges = null, reviseBudget, changed, failed, capacity = () => null, urgent = () => true,
-    rankAt = () => null, openOf = () => null, log = () => {}, now = Date.now, stretchCopied = () => {}, stretchBytes = null }) {
+    rankAt = () => null, openOf = () => null, log = () => {}, now = Date.now, stretchCopied = () => {} }) {
     this.#stretchCopied = stretchCopied;
-    this.#fixedStretchBytes = Number.isSafeInteger(stretchBytes) && stretchBytes > 0 ? stretchBytes : null;
     this.#openOf = openOf;
     this.#resolve = resolve;
     this.#read = readRanges;
@@ -354,10 +344,6 @@ export class EncodeInputs {
   #sizingFor(output) {
     const rate = middleOf(this.#copyRates);
     const open = this.#openOf(output);
-    if (this.#fixedStretchBytes !== null) {
-      return { bytes: this.#fixedStretchBytes, openMeasured: true, openSeconds: open?.seconds ?? null,
-        copyBytesPerMs: rate, fixed: true };
-    }
     return rate === null || !open ? null : { bytes: Math.floor(rate * open.seconds * 1000),
       openMeasured: open.measured, openSeconds: open.seconds, copyBytesPerMs: rate };
   }
@@ -621,7 +607,7 @@ export class EncodeInputs {
     if (result.kind === "result") {
       this.#log(`encode input selection of ${addressOf(output)}: ${JSON.stringify({
         from, requestedTo: request.to, serves, floor, targetEnd, chosenEnd: end,
-        targetBytes: target, targetFixed: sizing?.fixed === true, minimumBytes: minimum, inputBytes: result.bytes,
+        targetBytes: target, minimumBytes: minimum, inputBytes: result.bytes,
         copyBytesPerMs: sizing?.copyBytesPerMs ?? null, openSeconds: sizing?.openSeconds ?? null,
         openMeasured: sizing?.openMeasured ?? null, reservations, probes
       })}`);

package/services/encode/EncodeOrchestrator.js

@@ -24,7 +24,8 @@
  */
 
 import { CoverageMap } from "./CoverageMap.js";
-import { firstUnmetWant, planEncoders } from "./EncodePlan.js";
+import { deadlineReaderFor, firstUnmetWant, planEncoders } from "./EncodePlan.js";
+import { PauseRule } from "./PauseRule.js";
 import { endOfRun } from "./EncodeRun.js";
 import { ENCODE_EXIT } from "./encode-exit.js";
 import { affordableRuns } from "./run-budget.js";
@@ -138,13 +139,19 @@ export class EncodeOrchestrator {
    * viewer was stopped for waited 59 s behind a picture that had long left
    * the urgent band (Home Assistant 2026-10-12, torrent-tv/meta#178).
    *
-   * @type {Map<string, { urgent: boolean, priority: number }>}
+   * @type {Map<string, { urgent: boolean, priority: number, from: number }>}
    */
   #heldBack = new Map();
 
   /** What a stop and a start have cost on this host. */
   #costs = new RunCosts();
 
+  /**
+   * Whether a less urgent encoder runs beside the leading one, from what
+   * running it was measured to do (torrent-tv/meta#180, phase 4).
+   */
+  #pauseRule = new PauseRule();
+
   /**
    * What starting and stopping an encoder was measured to cost on this host,
    * before any viewer existed. Told once; real runs replace it as they end.
@@ -228,6 +235,9 @@ export class EncodeOrchestrator {
    *   this one may be asked about encoders with no ledger, no clock and no
    *   viewer anywhere. Absent, the line simply does not carry it.
    * @param {SegmentCoverage | null} [params.segmentCoverage]
+   * @param {{ freeCores: () => number | null, otherCores: () => number | null } | null} [params.processor] -
+   *   The processor left free and the processor other work takes, in cores
+   *   (`ProcessorBudget`); absent, both are unknown.
    */
   constructor({
     maxRunsFor,
@@ -242,6 +252,7 @@ export class EncodeOrchestrator {
     inputsUnplaced = null,
     describeWaits = null,
     admission = null,
+    processor = null,
     logger,
     now
   }) {
@@ -250,6 +261,7 @@ export class EncodeOrchestrator {
     // encoder that would slow everybody below realtime. Absent in a check that
     // is about one output, and then only the per-output limit binds.
     this.admission = admission && typeof admission.placesFor === "function" ? admission : null;
+    this.processor = processor && typeof processor.freeCores === "function" ? processor : null;
     this.#describeWaits = typeof describeWaits === "function" ? describeWaits : () => "";
     // Only the segment facts and operations this planner needs cross the
     // storage boundary; the concrete storage remains in the server assembly.
@@ -665,7 +677,7 @@ export class EncodeOrchestrator {
   /**
    * The most urgent band a live encoder stands in, over every output.
    *
-   * @returns {{ urgent: boolean, priority: number, address: string, index: number } | null}
+   * @returns {{ urgent: boolean, priority: number, address: string, index: number, run: object } | null}
    */
   #leadingBand() {
     let leading = null;
@@ -673,7 +685,7 @@ export class EncodeOrchestrator {
       for (const run of runs) {
         if (!run.isAlive || run.isStopping) continue;
         const band = this.#bandAt(address, run.head);
-        if (!leading || compareUrgency(band, leading) < 0) leading = { ...band, address, index: run.head };
+        if (!leading || compareUrgency(band, leading) < 0) leading = { ...band, address, index: run.head, run };
       }
     }
     return leading;
@@ -696,6 +708,13 @@ export class EncodeOrchestrator {
    * Paused rather than lowered in priority: a lowered priority cannot be raised
    * again without `CAP_SYS_NICE`, which the add-on's container does not have
    * (Home Assistant 2026-10-10: `renice 0` after `renice 19` left 19).
+   *
+   * AND PAUSED ONLY WHERE RUNNING IT WAS MEASURED TO COST THE LEADER
+   * (torrent-tv/meta#180, phase 4). Behind the leader is the condition, not
+   * the verdict: `PauseRule` lets a less urgent encoder run while the leader
+   * still makes what its deadlines need, and pauses it once the leader's own
+   * readings say it does not. Without readings to judge from, behind is paused
+   * as before.
    */
   shareTheMachine() {
     const leading = this.#leadingBand();
@@ -704,21 +723,125 @@ export class EncodeOrchestrator {
       this.#placeHeldBack(null);
       return;
     }
+    const now = this.now();
+    const running = this.#runningNow();
+    const need = this.#needOf(leading);
+    const free = this.#processorReading("freeCores");
+    const others = this.#processorReading("otherCores");
     for (const [address, runs] of this.#runs) {
       for (const run of runs) {
         if (!run.isAlive || run.isStopping || typeof run.pause !== "function") continue;
         const behind = compareUrgency(this.#bandAt(address, run.head), leading) > 0;
-        if (behind && run.isSuspended !== true) {
-          run.pause(`#${run.head} of ${address} is wanted less urgently than #${leading.index} of ${leading.address}, ` +
-            `which is being made`);
-        } else if (!behind && run.isSuspended === true) {
-          run.resume(`nothing more urgent than #${run.head} of ${address} is being made`);
+        if (!behind) {
+          if (run.isSuspended === true) run.resume(`nothing more urgent than #${run.head} of ${address} is being made`);
+          continue;
+        }
+        const urgency = `#${run.head} of ${address} is wanted less urgently than #${leading.index} of ${leading.address}`;
+        const verdict = this.#pauseRule.judge({
+          leader: leading.run, band: leading, run, address, need, remainingFilm: this.#remainingFilm(run), free, others, running, now
+        });
+        if (verdict === null) {
+          if (run.isSuspended !== true) run.pause(`${urgency}, which is being made`);
+        } else if (verdict.runs && run.isSuspended === true) {
+          run.resume(`${urgency}, and runs beside it: ${verdict.because}`);
+        } else if (!verdict.runs && run.isSuspended !== true) {
+          run.pause(`${urgency}, which is being made: ${verdict.because}`);
         }
       }
     }
     this.#placeHeldBack(leading);
   }
 
+  /**
+   * One second of each encoder's processor and speed, by process
+   * (`storage/processor-report.js`): what `PauseRule` judges from. Who has the
+   * processor is decided again after it.
+   *
+   * @param {Map<number, { cores: number, speed: number | null }>} seconds
+   * @param {number} [at]
+   */
+  noteRunSeconds(seconds, at = this.now()) {
+    if (!(seconds instanceof Map) || seconds.size === 0) return;
+    const running = this.#runningNow();
+    let noted = false;
+    for (const runs of this.#runs.values()) {
+      for (const run of runs) {
+        const reading = seconds.get(run.process?.pid);
+        // A paused process draws nothing and makes nothing: its second says
+        // nothing about what it costs when it runs.
+        if (!reading || !run.isAlive || run.isSuspended === true) continue;
+        this.#pauseRule.noteSecond(run, { at, cores: reading.cores, speed: reading.speed }, running, run.isWaitingForInput === true);
+        noted = true;
+      }
+    }
+    if (noted) this.shareTheMachine();
+  }
+
+  /** @returns {Set<object>} Every encoder running now, not paused. */
+  #runningNow() {
+    const running = new Set();
+    for (const runs of this.#runs.values()) {
+      for (const run of runs) if (run.isAlive && !run.isStopping && run.isSuspended !== true) running.add(run);
+    }
+    return running;
+  }
+
+  /**
+   * The speed the leading run's deadlines ask for: over every number it has
+   * left, the film up to it over the time until it is needed. Infinite where a
+   * viewer already waits for one of them; 0 where none is due.
+   *
+   * @param {{ address: string, run: object }} leading
+   * @returns {number}
+   */
+  #needOf({ address, run }) {
+    const seconds = this.segmentSeconds;
+    if (!(seconds > 0)) return Number.POSITIVE_INFINITY;
+    const dueIn = deadlineReaderFor(this.#demand.mapOn(address), seconds);
+    let need = 0;
+    for (let index = run.head; index <= run.to; index += 1) {
+      const due = dueIn(index);
+      if (!Number.isFinite(due)) break;
+      if (due <= 0) return Number.POSITIVE_INFINITY;
+      need = Math.max(need, ((index - run.head + 1) * seconds) / due);
+    }
+    return need;
+  }
+
+  /**
+   * @param {object} run
+   * @returns {number} Film seconds it has left to make; infinite with no end.
+   */
+  #remainingFilm(run) {
+    return Number.isFinite(run.to) ? Math.max(0, run.to - run.head + 1) * this.segmentSeconds : Number.POSITIVE_INFINITY;
+  }
+
+  /**
+   * @param {"freeCores" | "otherCores"} name
+   * @returns {number | null}
+   */
+  #processorReading(name) {
+    const value = this.processor?.[name]?.();
+    return Number.isFinite(value) ? value : null;
+  }
+
+  /**
+   * Why a start at `from` on `address` would be paused the moment it exists,
+   * or null: behind the leader, and not let go by `PauseRule`.
+   *
+   * @param {string} address
+   * @param {number} from
+   * @returns {string | null}
+   */
+  #holdReason(address, from) {
+    const leading = this.#leading;
+    if (!leading?.run || compareUrgency(this.#bandAt(address, from), leading) <= 0) return null;
+    const verdict = this.#pauseRule.wouldStart({
+      leader: leading.run, address, need: this.#needOf(leading), free: this.#processorReading("freeCores")
+    });
+    return verdict.runs ? null : verdict.because;
+  }
+
   /**
    * Plan again every output whose start was held back behind what is no
    * longer more urgent than it: the start is placed now, by the same plan,
@@ -728,7 +851,7 @@ export class EncodeOrchestrator {
    */
   #placeHeldBack(leading) {
     for (const [address, band] of [...this.#heldBack]) {
-      if (leading && compareUrgency(band, leading) > 0) continue;
+      if (leading && compareUrgency(band, leading) > 0 && this.#holdReason(address, band.from) !== null) continue;
       this.#heldBack.delete(address);
       this.#reconcileOne(address);
     }
@@ -824,7 +947,11 @@ export class EncodeOrchestrator {
       // was measured it holds the largest reading rather than continuing a curve
       // nothing observed.
       contentionPenaltyFor: (others) => contentionPenalty(others, this.contentionPenalties).penalty,
-      speedX
+      speedX,
+      // A START THE PAUSE RULE WOULD PAUSE AT ONCE IS NOT MADE: the encoder
+      // would hold a process and its input for nothing. The plan returns it as
+      // `hold`, and it is placed when the rule lets it go (`#placeHeldBack`).
+      holdStart: (from) => this.#holdReason(address, from)
     });
 
     // A move is the plan taking a running encoder away from where it already
@@ -869,13 +996,10 @@ export class EncodeOrchestrator {
         `live=${JSON.stringify(live.map((run) => ({ from: run.from, to: run.to, head: run.head, speedX: run.speedX })))}`
       );
     }
-    // A START BEHIND WHAT IS BEING MADE ELSEWHERE IS NOT MADE: the encoder would
-    // be paused the moment it exists (`shareTheMachine`), holding a process and
-    // its input for nothing. It is placed when nothing more urgent is in hand.
+    // A start held by the plan is placed when the pause rule lets it go.
     let heldBack = null;
     for (const action of actions) {
-      if (action.type === "start" && this.#leading &&
-          compareUrgency(this.#bandAt(address, action.from), this.#leading) > 0) {
+      if (action.type === "hold") {
         heldBack = action;
         continue;
       }
@@ -946,7 +1070,7 @@ export class EncodeOrchestrator {
     // a 159 090-line file, 31 % of the log, all of one wedge.
     const wanting = firstUnmetWant(coverage, windows);
     const stillRunning = this.runsOn(address).filter((run) => run.isAlive);
-    if (heldBack) this.#heldBack.set(address, this.#bandAt(address, heldBack.from));
+    if (heldBack) this.#heldBack.set(address, { ...this.#bandAt(address, heldBack.from), from: heldBack.from });
     else this.#heldBack.delete(address);
     if (wanting === null || stillRunning.length > 0) {
       this.#lastUnmet.delete(address);
@@ -956,7 +1080,7 @@ export class EncodeOrchestrator {
         this.#lastUnmet.set(address, said);
         this.logger.info(
           `encode: #${heldBack.from} of ${address} waits — #${this.#leading?.index} of ` +
-          `${this.#leading?.address} is wanted more urgently and is being made`
+          `${this.#leading?.address} is wanted more urgently and is being made (${heldBack.because})`
         );
       }
     } else if (this.#lastUnmet.get(address) !== wanting) {
@@ -1184,6 +1308,7 @@ export class EncodeOrchestrator {
       this.#lastProgress.set(ended.address, progress);
     }
     this.#costs.note(ended);
+    if (ended.run) this.#pauseRule.forget(ended.run, ended.address);
     // Exactly one ending is normal — the run reached the end of the stretch it
     // was given and closed its last file. Every other leaves a piece open, and
     // that piece is under this run's OWN working name, so clearing up after it

package/services/encode/EncodePlan.js

@@ -84,7 +84,8 @@
  * @typedef {{ type: "start", from: number, to: number, because: string }
  *   | { type: "move", run: object, from: number, to: number, because: string }
  *   | { type: "stop", run: object, because: string }
- *   | { type: "keep", run: object, from: number, to: number }} PlanAction
+ *   | { type: "keep", run: object, from: number, to: number }
+ *   | { type: "hold", from: number, to: number, because: string }} PlanAction
  */
 
 /**
@@ -116,6 +117,11 @@
  *   encoder per piece: at exactly realtime each next piece is marginally late
  *   however many are running, so another one always seemed to help a little.
  *   Unmeasured is 1, and then the budget is the only thing bounding the count.
+ * @param {(from: number) => string | null} [params.holdStart] - Why a start at
+ *   `from` would be paused the moment it exists (`PauseRule`), or null. Such a
+ *   start comes back as `hold` with that reason: the encoder would hold a
+ *   process and its input for nothing, and one place decides a start
+ *   (torrent-tv/meta#180).
  * @returns {PlanAction[]} Stops first, then moves, then starts, so that a plan
  *   carried out in order never holds two encoders where it means to hold one.
  */
@@ -130,7 +136,8 @@ export function planEncoders({
   now = Date.now(),
   refetchSecPerFilmSecond = 0,
   contentionPenaltyFor = () => 1,
-  speedX = 0
+  speedX = 0,
+  holdStart = () => null
 }) {
   /** @type {PlanAction[]} */
   const stops = [];
@@ -686,7 +693,11 @@ export function planEncoders({
     });
   }
 
-  return [...stops, ...moves, ...starts, ...keeps];
+  const startsOrHeld = starts.map((start) => {
+    const because = holdStart(start.from);
+    return because ? { type: "hold", from: start.from, to: start.to, because } : start;
+  });
+  return [...stops, ...moves, ...startsOrHeld, ...keeps];
 }
 
 
@@ -1010,7 +1021,7 @@ function lastOf(windows) {
   return Math.max(...windows.map((span) => span.to));
 }
 
-function deadlineReaderFor(windows, segmentSeconds) {
+export function deadlineReaderFor(windows, segmentSeconds) {
   const perSegment = segmentSeconds > 0 ? segmentSeconds : 0;
   // A TABLE BY SEGMENT, filled once per plan. Read for every segment of every
   // arrangement the plan weighs, a search of every window for each index was

package/services/encode/EncodeRun.js

@@ -454,6 +454,11 @@ export class EncodeRun {
     this.clock.inputWaitEnds();
   }
 
+  /** @returns {boolean} Whether an input read of this run is waiting for bytes now. */
+  get isWaitingForInput() {
+    return this.clock.waitingForInput;
+  }
+
   /** @returns {boolean} Whether it is stopped where it stands, producing nothing. */
   get isSuspended() {
     return this.#state === ENCODE_RUN_STATE.SUSPENDED;

package/services/encode/PauseRule.js

@@ -0,0 +1,334 @@
+/**
+ * @file Whether an encoder making something less urgent runs beside the most
+ * urgent one, from what running it was measured to do (torrent-tv/meta#180,
+ * phase 4).
+ *
+ * Until this, everything less urgent than the leading band was stopped,
+ * whatever the leader did with the processor and whatever it needed by its
+ * deadline (`EncodeOrchestrator.shareTheMachine`). On a machine where the
+ * leader does not take all the processor — libx264 thread scaling, a hardware
+ * encoder whose work is on the device, a leader ahead of its deadline — the
+ * paused work waited for nothing; and a one-piece soundtrack copy at 150x was
+ * paused behind a picture it could not have slowed (Home Assistant r73).
+ *
+ * THE RULE. `L` is the leading run, `r` a less urgent one.
+ *
+ * 1. `L`'s need `s*` is the speed its deadlines ask for (film seconds per
+ *    second); infinite where a viewer already waits for what `L` is making.
+ * 2. `r` keeps running when, over the seconds it ran beside `L`, `L` still made
+ *    at least `s*` (finite need), or neither `L`'s speed nor its cores fell
+ *    below what they were without `r` by more than their own scatter (infinite
+ *    need). Otherwise `r` is paused. Both are read: memory-bandwidth contention
+ *    lowers the speed and not the cores, and on Home Assistant (r78, r79) a
+ *    short run's speed scattered by as much as its median from second to second
+ *    while its cores scattered by 0.02-0.2, so a slowdown is often visible in
+ *    the cores first. No number of cores enters: a fraction of a core can be
+ *    enough, and a free core does not cap what a new ffmpeg takes.
+ * 3. A paused `r` is tried when the processor left free (`F`, cores) is
+ *    unknown or exceeds what `r` drew when it last ran, or when `L` makes more
+ *    than `s*` by more than its scatter. With an infinite need it is tried only
+ *    once `L` has seconds without it to be compared against.
+ * 4. A run whose whole remaining stretch costs less processor than `L`'s
+ *    scatter over one second cannot be measured against `L` and is never
+ *    paused.
+ *
+ * NO ALTERNATION UNDER UNCHANGED LOAD. A pause for a measured slowdown is
+ * remembered for the pair with what it was measured under: `L`'s output and
+ * band, the other runs running, and the processor other work took. `r` is not
+ * tried beside `L` again until one of these changes — the others' draw by more
+ * than `r`'s own — so under constant load there is at most one try and one
+ * pause.
+ *
+ * WITHOUT READINGS NOTHING CHANGES. Where `L` has no per-second readings (no
+ * `/proc` to read an ffmpeg's processor from), or `r` has run beside `L` since
+ * before anything could be compared, the answer is null and the caller keeps
+ * the urgency rule it had.
+ *
+ * Readings are the per-second ones of `storage/processor-report.js`: each
+ * run's cores and the film it made per second of wall clock. Seconds in which
+ * `L` waited for its input say nothing about `r` and are left out.
+ */
+
+/**
+ * How many seconds of readings a run keeps. Enough for a baseline before a try
+ * and the seconds beside after it; `L`'s cost changes from piece to piece, so
+ * older seconds describe other pieces.
+ */
+const KEPT_SECONDS = 30;
+
+/**
+ * The fewest seconds a median and its scatter are taken from: with fewer,
+ * the scatter of one or two values says nothing.
+ */
+const LEAST_SECONDS = 3;
+
+/**
+ * @typedef {object} RunSecond
+ * @property {number} at - When the second ended, in milliseconds.
+ * @property {number} cores - What the run's ffmpeg used over it.
+ * @property {number | null} speed - Film made per second of wall clock.
+ * @property {Set<object>} running - The runs running (not paused) beside it.
+ * @property {boolean} waiting - Whether its input waited at the end of it.
+ */
+
+/**
+ * @typedef {object} PairConditions
+ * @property {string} address - `L`'s output.
+ * @property {boolean} urgent - `L`'s band.
+ * @property {number} priority
+ * @property {Set<object>} running - The other runs running, `L` and `r` aside.
+ * @property {number | null} others - Cores other work took.
+ */
+
+export class PauseRule {
+  /** @type {Map<object, RunSecond[]>} */
+  #seconds = new Map();
+
+  /** When the rule last let each run go. @type {Map<object, number>} */
+  #triedAt = new Map();
+
+  /** What the last run on each output drew, for the next run there. @type {Map<string, number>} */
+  #lastDrawOn = new Map();
+
+  /** Pauses for a measured slowdown, by leader, then by run. @type {Map<object, Map<object, PairConditions>>} */
+  #pairs = new Map();
+
+  /**
+   * One second of one run.
+   *
+   * @param {object} run
+   * @param {{ at: number, cores: number, speed: number | null }} reading
+   * @param {Iterable<object>} running - Every run running at the time.
+   * @param {boolean} [waiting]
+   */
+  noteSecond(run, { at, cores, speed }, running, waiting = false) {
+    if (!Number.isFinite(cores)) return;
+    const kept = this.#seconds.get(run) ?? [];
+    kept.push({ at, cores, speed: Number.isFinite(speed) ? speed : null, running: new Set(running), waiting: waiting === true });
+    while (kept.length > 0 && kept[0].at <= at - KEPT_SECONDS * 1000) kept.shift();
+    this.#seconds.set(run, kept);
+  }
+
+  /**
+   * A run that has ended: what it drew is kept for the next run on its output.
+   *
+   * @param {object} run
+   * @param {string} address
+   */
+  forget(run, address) {
+    const draw = this.#drawOf(run);
+    if (draw !== null && typeof address === "string") this.#lastDrawOn.set(address, draw);
+    this.#seconds.delete(run);
+    this.#triedAt.delete(run);
+    this.#pairs.delete(run);
+    for (const pairs of this.#pairs.values()) pairs.delete(run);
+  }
+
+  /**
+   * Whether `run` runs beside `leader` now.
+   *
+   * @param {object} params
+   * @param {object} params.leader - The leading run.
+   * @param {{ address: string, urgent: boolean, priority: number }} params.band - Where it leads.
+   * @param {object} params.run - A run less urgent than it.
+   * @param {string} params.address - `run`'s output.
+   * @param {number} params.need - `L`'s `s*`: film seconds per second, `Infinity`
+   *   where a viewer waits for what it is making, 0 where nothing is due.
+   * @param {number} params.remainingFilm - Film seconds `run` has left to make.
+   * @param {number | null} params.free - `F`: cores left free, or null.
+   * @param {number | null} params.others - Cores other work took, or null.
+   * @param {Iterable<object>} params.running - Every run running now.
+   * @param {number} params.now
+   * @returns {{ runs: boolean, because: string } | null} Null where nothing
+   *   was measured to decide from.
+   */
+  judge({ leader, band, run, address, need, remainingFilm, free, others, running, now }) {
+    const lead = (this.#seconds.get(leader) ?? []).filter((second) => !second.waiting && second.speed !== null);
+    if (lead.length === 0) return null;
+    const leadCores = middleAndScatter(lead.map((second) => second.cores));
+    const draw = this.#drawOf(run) ?? this.#lastDrawOn.get(address) ?? null;
+    const perFilm = this.#costPerFilm(run);
+    if (perFilm !== null && Number.isFinite(remainingFilm) && remainingFilm * perFilm < leadCores.scatter) {
+      return { runs: true, because: `its remaining ${remainingFilm.toFixed(1)}s of film cost ${(remainingFilm * perFilm).toFixed(3)} ` +
+        `CPU-s, less than the leader's scatter of ${leadCores.scatter.toFixed(3)} cores over one second` };
+    }
+    const without = lead.filter((second) => !second.running.has(run));
+    const otherRunning = new Set([...running].filter((other) => other !== leader && other !== run));
+    if (run.isSuspended === true) {
+      return this.#whetherToTry({ leader, band, run, need, lead, without, draw, free, others, otherRunning, now });
+    }
+    const since = this.#triedAt.get(run) ?? Number.NEGATIVE_INFINITY;
+    const beside = lead.filter((second) => second.running.has(run) && second.at > since);
+    if (beside.length < LEAST_SECONDS) {
+      // Let go by this rule and not measured yet: it runs until it is.
+      // Running since before anything could be compared: the urgency rule.
+      return this.#triedAt.has(run) ? { runs: true, because: `being measured beside the leader (${beside.length}s so far)` } : null;
+    }
+    const besideSpeed = middleAndScatter(beside.map((second) => second.speed));
+    if (Number.isFinite(need)) {
+      if (besideSpeed.middle >= need) {
+        return { runs: true, because: `the leader made ${besideSpeed.middle.toFixed(2)}x beside it over ${beside.length}s, ` +
+          `needing ${need.toFixed(2)}x` };
+      }
+      this.#remember(leader, run, { band, otherRunning, others });
+      return { runs: false, because: `the leader made ${besideSpeed.middle.toFixed(2)}x beside it over ${beside.length}s, ` +
+        `below the ${need.toFixed(2)}x its deadlines need` };
+    }
+    if (without.length < LEAST_SECONDS) {
+      return this.#triedAt.has(run) ? { runs: true, because: "nothing to compare the leader's speed with" } : null;
+    }
+    const alone = middleAndScatter(without.map((second) => second.speed));
+    const besideCores = middleAndScatter(beside.map((second) => second.cores));
+    const aloneCores = middleAndScatter(without.map((second) => second.cores));
+    const measured = `the leader made ${besideSpeed.middle.toFixed(2)}x on ${besideCores.middle.toFixed(2)} cores beside it ` +
+      `over ${beside.length}s, ${alone.middle.toFixed(2)}x (scatter ${alone.scatter.toFixed(2)}) on ` +
+      `${aloneCores.middle.toFixed(2)} cores (scatter ${aloneCores.scatter.toFixed(2)}) without it over ${without.length}s, ` +
+      "and a viewer waits for it";
+    if (alone.middle - besideSpeed.middle > alone.scatter || aloneCores.middle - besideCores.middle > aloneCores.scatter) {
+      this.#remember(leader, run, { band, otherRunning, others });
+      return { runs: false, because: measured };
+    }
+    return { runs: true, because: measured };
+  }
+
+  /**
+   * Whether a run not started yet, on `address` and less urgent than
+   * `leader`, would be let go at once: a start the rule would pause is not
+   * made (`EncodePlan` holds it). Without readings of the leader, it would.
+   *
+   * @param {object} params
+   * @param {object} params.leader
+   * @param {string} params.address
+   * @param {number} params.need
+   * @param {number | null} params.free
+   * @returns {{ runs: boolean, because: string }}
+   */
+  wouldStart({ leader, address, need, free }) {
+    const lead = (this.#seconds.get(leader) ?? []).filter((second) => !second.waiting && second.speed !== null);
+    if (lead.length === 0) {
+      return { runs: false, because: "nothing has measured what the leader does" };
+    }
+    const draw = this.#lastDrawOn.get(address) ?? null;
+    return this.#tryCondition({ need, lead, without: lead, draw, free });
+  }
+
+  /**
+   * Whether a paused run is let go to be measured beside the leader.
+   *
+   * @param {object} params
+   * @returns {{ runs: boolean, because: string }}
+   */
+  #whetherToTry({ leader, band, run, need, lead, without, draw, free, others, otherRunning, now }) {
+    const remembered = this.#pairs.get(leader)?.get(run);
+    const changed = remembered ? changeOf(remembered, { band, otherRunning, others, draw }) : null;
+    if (remembered) {
+      if (changed === null) {
+        return { runs: false, because: "it slowed the leader when last tried, and nothing it was tried under has changed" };
+      }
+      this.#pairs.get(leader)?.delete(run);
+    }
+    const verdict = this.#tryCondition({ need, lead, without, draw, free });
+    if (!verdict.runs) return verdict;
+    this.#triedAt.set(run, now);
+    return { runs: true, because: `tried beside the leader: ${verdict.because}` +
+      (remembered ? ` (${changed} changed since it was paused)` : "") };
+  }
+
+  /**
+   * Rule 3: the conditions under which a run not running is let go.
+   *
+   * @param {{ need: number, lead: RunSecond[], without: RunSecond[], draw: number | null, free: number | null }} params
+   * @returns {{ runs: boolean, because: string }}
+   */
+  #tryCondition({ need, lead, without, draw, free }) {
+    if (!Number.isFinite(need) && without.length < LEAST_SECONDS) {
+      return { runs: false, because: `a viewer waits for the leader, and it has run ${without.length}s without this one ` +
+        "to be compared with" };
+    }
+    const leadSpeed = middleAndScatter(lead.map((second) => second.speed));
+    if (free === null || !Number.isFinite(free)) {
+      return { runs: true, because: "the processor left free is unknown" };
+    }
+    if (free > (draw ?? 0)) {
+      return { runs: true, because: `${free.toFixed(2)} cores are free, more than the ` +
+        `${draw === null ? "unmeasured draw" : `${draw.toFixed(2)} cores`} it draws` };
+    }
+    if (Number.isFinite(need) && leadSpeed.middle - need > leadSpeed.scatter) {
+      return { runs: true, because: `the leader makes ${leadSpeed.middle.toFixed(2)}x, needing ${need.toFixed(2)}x` };
+    }
+    return { runs: false, because: `${free.toFixed(2)} cores are free, not more than the ` +
+      `${draw === null ? "?" : draw.toFixed(2)} cores it draws, and the leader makes ${leadSpeed.middle.toFixed(2)}x` +
+      (Number.isFinite(need) ? `, needing ${need.toFixed(2)}x` : " with a viewer waiting") };
+  }
+
+  /**
+   * @param {object} leader
+   * @param {object} run
+   * @param {{ band: { address: string, urgent: boolean, priority: number }, otherRunning: Set<object>, others: number | null }} under
+   */
+  #remember(leader, run, { band, otherRunning, others }) {
+    const pairs = this.#pairs.get(leader) ?? new Map();
+    pairs.set(run, { address: band.address, urgent: band.urgent === true, priority: band.priority, running: otherRunning,
+      others: Number.isFinite(others) ? others : null });
+    this.#pairs.set(leader, pairs);
+    this.#triedAt.delete(run);
+  }
+
+  /**
+   * The cores a run drew while it ran: the median of its seconds.
+   *
+   * @param {object} run
+   * @returns {number | null}
+   */
+  #drawOf(run) {
+    const seconds = this.#seconds.get(run) ?? [];
+    return seconds.length === 0 ? null : middleAndScatter(seconds.map((second) => second.cores)).middle;
+  }
+
+  /**
+   * CPU seconds per second of film, over the seconds in which it made film.
+   *
+   * @param {object} run
+   * @returns {number | null}
+   */
+  #costPerFilm(run) {
+    const costs = (this.#seconds.get(run) ?? []).filter((second) => second.speed > 0).map((second) => second.cores / second.speed);
+    return costs.length === 0 ? null : middleAndScatter(costs).middle;
+  }
+}
+
+/**
+ * What has changed since a pause for a slowdown, or null.
+ *
+ * @param {PairConditions} remembered
+ * @param {{ band: { address: string, urgent: boolean, priority: number }, otherRunning: Set<object>, others: number | null, draw: number | null }} now
+ * @returns {string | null}
+ */
+function changeOf(remembered, { band, otherRunning, others, draw }) {
+  if (remembered.address !== band.address || remembered.urgent !== (band.urgent === true) || remembered.priority !== band.priority) {
+    return "the leader's band";
+  }
+  if (remembered.running.size !== otherRunning.size || [...otherRunning].some((other) => !remembered.running.has(other))) {
+    return "the runs running";
+  }
+  if (remembered.others !== null && Number.isFinite(others) && draw !== null && remembered.others - others > draw) {
+    return "the processor other work takes";
+  }
+  return null;
+}
+
+/**
+ * The median and the median distance to it.
+ *
+ * @param {number[]} values
+ * @returns {{ middle: number, scatter: number }}
+ */
+function middleAndScatter(values) {
+  const median = (list) => {
+    const sorted = [...list].sort((left, right) => left - right);
+    const half = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0 ? (sorted[half - 1] + sorted[half]) / 2 : sorted[half];
+  };
+  const middle = median(values);
+  return { middle, scatter: median(values.map((value) => Math.abs(value - middle))) };
+}

package/services/encode/ProcessorBudget.js

@@ -23,7 +23,7 @@ import { correctForAvailability, leftForEncoders } from "./available-share.js";
 import { contentionPenalty } from "./contention.js";
 
 export class ProcessorBudget {
-  /** @type {() => ({ share: number, forEncoders?: number, known: boolean } | null | undefined)} */
+  /** @type {() => ({ share: number, forEncoders?: number, known: boolean, freeCores?: number | null, otherCores?: number | null } | null | undefined)} */
   #reading;
 
   /** @type {import("./contention.js").ContentionPenalties | null} */
@@ -74,6 +74,27 @@ export class ProcessorBudget {
     return correctForAvailability(aloneSpeed, this.availability());
   }
 
+  /**
+   * The processor left free over the latest reading, in cores, or null where
+   * it was not read (torrent-tv/meta#180, phase 4).
+   *
+   * @returns {number | null}
+   */
+  freeCores() {
+    const free = this.availability()?.freeCores;
+    return Number.isFinite(free) ? free : null;
+  }
+
+  /**
+   * The processor other work took over the latest reading, in cores, or null.
+   *
+   * @returns {number | null}
+   */
+  otherCores() {
+    const others = this.availability()?.otherCores;
+    return Number.isFinite(others) ? others : null;
+  }
+
   /**
    * The measured penalties, as the plan and the runs read them.
    *

package/services/encode/RunClock.js

@@ -91,6 +91,16 @@ export class RunClock {
     }
   }
 
+  /**
+   * Whether an input read of this run is waiting for bytes now, whether or
+   * not the process is also stopped.
+   *
+   * @returns {boolean}
+   */
+  get waitingForInput() {
+    return this.#idleCauses - (this.#isStopped ? 1 : 0) > 0;
+  }
+
   /**
    * Milliseconds the process has been stopped so far.
    *

package/services/encode/available-share.js

@@ -41,6 +41,19 @@
  * `share`, what other processes leave, stays for the download's share of the
  * proxy's processor (`processor-share.js`), which divides the proxy's room
  * between its own download and its encoders and must not lose that room twice.
+ *
+ * THE WHOLE MACHINE IS WHAT THIS PROCESS MAY USE (torrent-tv/meta#180, phase
+ * 3). `/proc/stat` and `os.cpus()` describe the host; a container's CPU quota
+ * (`cpu.max`, Docker `--cpus`) or a CPU set (`--cpuset-cpus`) gives the proxy
+ * fewer cores than that. Where such a bound is smaller than the host, both
+ * shares are fractions of the bound instead: the encoders get what the host's
+ * other work leaves, but never more than the bound less the proxy's own draw.
+ * Measured as fractions of the host, a 1.5-core quota on an 8-core host read
+ * a busy neighbour as lost room the quota never had, and the proxy's own draw
+ * as an eighth of what it takes from the quota. The startup measurements are
+ * divided by the same fraction (`host-load.js` `freeShareDuring`), so a cost
+ * filed from either stays in one unit. Without a bound smaller than the host,
+ * nothing changes.
  */
 
 /**
@@ -52,10 +65,17 @@
  * @param {number | null} reading.encoderShare - Our own ffmpeg processes.
  * @param {number | null} reading.proxyShare - The proxy process itself, every
  *   thread of it.
- * @returns {{ share: number, forEncoders: number, unattributed: number, known: boolean }}
+ * @param {number | null} [reading.hostCores] - The cores the three shares
+ *   above are fractions of.
+ * @param {number | null} [reading.boundCores] - The cores this process may use
+ *   (`storage/machine-processor.js` `processorBound`); counts only when
+ *   smaller than `hostCores`.
+ * @returns {{ share: number, forEncoders: number, unattributed: number, known: boolean, boundCores?: number }}
  *   `share` is what other processes leave; `forEncoders` what they and the
- *   proxy leave. `known` is false when the host does not report its own load —
- *   then both are 1 and the caller must say it is uncorrected rather than pretend.
+ *   proxy leave; both of `boundCores` where it is given, else of the whole
+ *   host. `unattributed` stays a fraction of the host. `known` is false when
+ *   the host does not report its own load — then both are 1 and the caller
+ *   must say it is uncorrected rather than pretend.
  */
 export function availableShareFrom(reading = {}) {
   const systemBusy = finite(reading.systemBusy);
@@ -65,11 +85,26 @@ export function availableShareFrom(reading = {}) {
     return { share: 1, forEncoders: 1, unattributed: 0, known: false };
   }
   const encoders = finite(reading.encoderShare) ?? 0;
-  const ours = encoders + (finite(reading.proxyShare) ?? 0);
+  const proxy = finite(reading.proxyShare) ?? 0;
+  const ours = encoders + proxy;
   // Rounding, and the two readings being taken microseconds apart, can put our
   // own share fractionally above the system total. Below zero is not a
   // measurement of anything.
   const unattributed = clamp(systemBusy - ours, 0, 1);
+  const hostCores = finite(reading.hostCores);
+  const boundCores = finite(reading.boundCores);
+  if (hostCores !== null && boundCores !== null && boundCores > 0 && boundCores < hostCores) {
+    // In cores: the host's other work takes from the host, the proxy's own
+    // draw from the bound as well.
+    const leftOnHost = hostCores - clamp(systemBusy - encoders, 0, 1) * hostCores;
+    return {
+      share: clamp(Math.min(boundCores, hostCores - unattributed * hostCores) / boundCores, 0, 1),
+      forEncoders: clamp(Math.min(boundCores - proxy * hostCores, leftOnHost) / boundCores, 0, 1),
+      unattributed,
+      known: true,
+      boundCores
+    };
+  }
   return { share: clamp(1 - unattributed, 0, 1), forEncoders: clamp(1 - (systemBusy - encoders), 0, 1),
     unattributed, known: true };
 }

package/services/encode/calibration.js

@@ -185,6 +185,8 @@ async function checkModeProducesCorrectSegments({ ffmpegBin, encoder, rung, segm
  * @param {{ info: (m: string) => void, warn: (m: string) => void }} [params.logger]
  * @param {number} [params.segmentDurationSec]
  * @param {Array<{ width: number, height: number }>} [params.frames]
+ * @param {number | null} [params.processorCores] - The cores this process may
+ *   use, which the readings' share of the machine is of (`measureEncodeSlope`).
  * @param {object} [params.measure] - Replaces the three readings, for a check
  *   that must not run ffmpeg: `check`, `rawFrames`, `speed`. `speed` answers a
  *   number, or `{ speed, freeShare }` as `measureEncodeSlope` does.
@@ -196,12 +198,13 @@ export async function calibrateEncoder({
   logger,
   segmentDurationSec = 4,
   frames = CALIBRATION_FRAMES,
+  processorCores = null,
   measure = null
 }) {
   const log = logger ?? { info: () => {}, warn: () => {} };
   const check = measure?.check ?? checkModeProducesCorrectSegments;
   const rawFrames = measure?.rawFrames ?? ((frame) => decodeToRawFrames(ffmpegBin, log, frame));
-  const speed = measure?.speed ?? ((rung, rawPath, frame) => measureEncodeSlope(ffmpegBin, encoder, rung, rawPath, frame));
+  const speed = measure?.speed ?? ((rung, rawPath, frame) => measureEncodeSlope(ffmpegBin, encoder, rung, rawPath, frame, processorCores));
   const release = measure?.release ?? ((rawPath) => {
     try {
       rmSync(path.dirname(rawPath), { recursive: true, force: true, maxRetries: 5, retryDelay: 200 });

package/services/encode/fingerprint.js

@@ -22,7 +22,10 @@
  * 2. the libx264 build — the version string x264 writes into every stream it
  *    produces (`x264 - core N rNNNN hash`), read from one encoded frame;
  * 3. the processor model and the thread count the encoder is given
- *    (`CPU_THREADS`, which is the core count);
+ *    (`CPU_THREADS`, which is the core count), and the cores this process may
+ *    use where a container's CPU quota or CPU set makes them fewer: a speed
+ *    filed as a share of those cores (`available-share.js`) does not hold
+ *    under another quota (torrent-tv/meta#180);
  * 4. for a device-backed encoder, the device model and its driver: NVIDIA's
  *    own tool where it exists, and otherwise what the kernel publishes under
  *    `/sys` for the render node or the video device.
@@ -116,7 +119,9 @@ export function configurationKeyOf(fingerprint, encoder) {
       ...common,
       `x264=${fingerprint?.x264 ?? UNKNOWN}`,
       `cpu=${fingerprint?.cpu ?? UNKNOWN}`,
-      `threads=${fingerprint?.threads ?? UNKNOWN}`
+      `threads=${fingerprint?.threads ?? UNKNOWN}`,
+      // Only where it binds, so a host without a quota keeps its key.
+      ...(Number.isFinite(fingerprint?.boundCores) ? [`bound=${fingerprint.boundCores}`] : [])
     ].join(";");
   }
   const device = fingerprint?.devices?.[encoder?.kind] ?? null;
@@ -137,6 +142,8 @@ export function configurationKeyOf(fingerprint, encoder) {
  * @property {string} x264
  * @property {string} cpu
  * @property {number} threads
+ * @property {number | null} [boundCores] - The cores this process may use,
+ *   where fewer than the host's; absent or null otherwise.
  * @property {Record<string, DeviceFingerprint>} devices - By encoder kind.
  */
 
@@ -288,10 +295,10 @@ async function nvidiaDevice() {
  * Read this host's fingerprint. Always resolves: an unreadable part is
  * `unknown`, never a refusal to start.
  *
- * @param {{ ffmpegBin: string, encoder?: { kind: string, device: string | null } | null }} params
+ * @param {{ ffmpegBin: string, encoder?: { kind: string, device: string | null } | null, processorCores?: number | null }} params
  * @returns {Promise<HostFingerprint>}
  */
-export async function readHostFingerprint({ ffmpegBin, encoder = null }) {
+export async function readHostFingerprint({ ffmpegBin, encoder = null, processorCores = null }) {
   const versionText = await capture(ffmpegBin, ["-hide_banner", "-version"], 5000);
   // `-hide_banner` does not hide the version line itself: it is the answer.
   const ffmpeg = parseFfmpegVersion(versionText ? versionText.toString("utf8") : "");
@@ -317,6 +324,7 @@ export async function readHostFingerprint({ ffmpegBin, encoder = null }) {
     x264,
     cpu: os.cpus()[0]?.model?.trim() || UNKNOWN,
     threads: CPU_THREADS,
+    boundCores: Number.isFinite(processorCores) && processorCores < os.cpus().length ? processorCores : null,
     devices
   };
 }

package/services/encode/host-load.js

@@ -189,14 +189,14 @@ export function shareOfMachine(before, after, cores = os.cpus().length) {
  * One reading of everything above, to be compared against the next.
  *
  * @param {number | null} pid - The encoder's process, when one is running.
- * @returns {Promise<{ takenAt: number, processCpuSeconds: number | null, system: CpuTotals | null }>}
+ * @returns {Promise<{ takenAt: number, processCpuSeconds: number | null, system: CpuTotals | null, proxyCpuSeconds: number }>}
  */
 export async function sampleHost(pid) {
   const [processCpuSeconds, system] = await Promise.all([
     pid === null ? Promise.resolve(null) : readProcessCpuSeconds(pid),
     readSystemCpu()
   ]);
-  return { takenAt: Date.now(), processCpuSeconds, system };
+  return { takenAt: Date.now(), processCpuSeconds, system, proxyCpuSeconds: readProxyCpuSeconds() };
 }
 
 /**
@@ -215,12 +215,22 @@ export async function sampleHost(pid) {
  * Null when the host does not report its load (no `/proc`), or a reading was
  * refused; the measurement is then used as it was read, and says so.
  *
- * @param {{ takenAt: number, processCpuSeconds: number | null, system: object | null } | null} before
- * @param {{ takenAt: number, processCpuSeconds: number | null, system: object | null } | null} after
+ * Where this process may use fewer cores than the host has (a container's CPU
+ * quota or CPU set, `boundCores`), the share is of those cores, as the share a
+ * running encoder is filed with (`available-share.js`): what the host's other
+ * work leaves, but never more than the bound less this process's own draw.
+ * Otherwise the measurement, which ran inside the bound, was divided by a
+ * share of the whole host, and a busy neighbour made it read faster than the
+ * bound allows (torrent-tv/meta#180, phase 3).
+ *
+ * @param {{ takenAt: number, processCpuSeconds: number | null, system: object | null, proxyCpuSeconds?: number | null } | null} before
+ * @param {{ takenAt: number, processCpuSeconds: number | null, system: object | null, proxyCpuSeconds?: number | null } | null} after
  * @param {number} [cores]
+ * @param {number | null} [boundCores] - The cores this process may use; counts
+ *   only when fewer than `cores`.
  * @returns {number | null} Between 0 and 1.
  */
-export function freeShareDuring(before, after, cores = os.cpus().length) {
+export function freeShareDuring(before, after, cores = os.cpus().length, boundCores = null) {
   if (!before || !after) {
     return null;
   }
@@ -229,10 +239,28 @@ export function freeShareDuring(before, after, cores = os.cpus().length) {
     return null;
   }
   const others = Math.min(1, Math.max(0, shares.systemShare - shares.processShare));
-  const free = 1 - others;
+  const free = Number.isFinite(boundCores) && boundCores > 0 && boundCores < cores
+    ? Math.min(1, (cores - others * cores) / boundCores, (boundCores - proxyCoresBetween(before, after)) / boundCores)
+    : 1 - others;
   return free > 0 ? free : null;
 }
 
+/**
+ * The cores this process drew between two readings; 0 where either has no
+ * reading of it.
+ *
+ * @param {{ takenAt: number, proxyCpuSeconds?: number | null }} before
+ * @param {{ takenAt: number, proxyCpuSeconds?: number | null }} after
+ * @returns {number}
+ */
+function proxyCoresBetween(before, after) {
+  const elapsedSec = (after.takenAt - before.takenAt) / 1000;
+  if (!(elapsedSec > 0) || !Number.isFinite(before.proxyCpuSeconds) || !Number.isFinite(after.proxyCpuSeconds)) {
+    return 0;
+  }
+  return Math.max(0, (after.proxyCpuSeconds - before.proxyCpuSeconds) / elapsedSec);
+}
+
 /**
  * How much CPU THIS process has used, across every thread it owns.
  *

package/services/encode/hwaccel.js

@@ -679,13 +679,13 @@ export async function benchmarkContention({ ffmpegBin, logger, clipsDir = CALIBR
   return penalties;
 }
 
-export async function benchmarkDecodeCost({ ffmpegBin, logger, clipsDir = CALIBRATION_DIR }) {
+export async function benchmarkDecodeCost({ ffmpegBin, logger, clipsDir = CALIBRATION_DIR, processorCores = null }) {
   const log = logger ?? { info: () => {}, warn: () => {} };
   const startedAllAt = Date.now();
   /** @type {Record<string, { pixelTerm: number, bitrateTerm: number, constantTerm: number }>} */
   const families = {};
   for (const [family, clips] of Object.entries(CALIBRATION_SETS)) {
-    const fitted = await fitOneFamily({ ffmpegBin, log, clipsDir, family, clips });
+    const fitted = await fitOneFamily({ ffmpegBin, log, clipsDir, family, clips, processorCores });
     if (fitted) {
       families[family] = fitted;
     }
@@ -721,10 +721,10 @@ export async function benchmarkDecodeCost({ ffmpegBin, logger, clipsDir = CALIBR
 /**
  * Fit one codec family's decode cost from its own clips.
  *
- * @param {{ ffmpegBin: string, log: { info: Function, warn: Function }, clipsDir: string, family: string, clips: string[] }} params
+ * @param {{ ffmpegBin: string, log: { info: Function, warn: Function }, clipsDir: string, family: string, clips: string[], processorCores?: number | null }} params
  * @returns {Promise<{ pixelTerm: number, bitrateTerm: number, constantTerm: number } | null>}
  */
-async function fitOneFamily({ ffmpegBin, log, clipsDir, family, clips }) {
+async function fitOneFamily({ ffmpegBin, log, clipsDir, family, clips, processorCores = null }) {
   const startedAllAt = Date.now();
   /** @type {Array<{ megapixelsPerSecond: number, megabitsPerSecond: number, costSecondsPerSecond: number }>} */
   const samples = [];
@@ -745,7 +745,7 @@ async function fitOneFamily({ ffmpegBin, log, clipsDir, family, clips }) {
   }
   for (const [index, clip] of clips.entries()) {
     const stream = streams[index];
-    const measured = stream ? await decodePipedStream(ffmpegBin, stream, log) : null;
+    const measured = stream ? await decodePipedStream(ffmpegBin, stream, log, processorCores) : null;
     if (!measured?.speed) {
       log.warn(
         `hwaccel: decode benchmark "${clip}" said nothing; ${family} not measured` +
@@ -998,9 +998,11 @@ function runCapturingStderr(ffmpegBin, args, timeoutMs) {
  *
  * @param {string} ffmpegBin
  * @param {{ bytes: Buffer, demuxer: string, megapixelsPerSecond: number, megabitsPerSecond: number, fps: number }} stream
+ * @param {{ info: Function, warn: Function }} [log]
+ * @param {number | null} [processorCores] - The cores this process may use, for `freeShareDuring`.
  * @returns {Promise<{ speed: number, windowSec: number, megapixelsPerSecond: number, megabitsPerSecond: number } | null>}
  */
-function decodePipedStream(ffmpegBin, stream, log = { info: () => {}, warn: () => {} }) {
+function decodePipedStream(ffmpegBin, stream, log = { info: () => {}, warn: () => {} }, processorCores = null) {
   return new Promise((resolve) => {
     const args = [
       "-hide_banner", "-loglevel", "error", "-nostats",
@@ -1047,7 +1049,7 @@ function decodePipedStream(ffmpegBin, stream, log = { info: () => {}, warn: () =
       const hostAfter = hostBefore !== null && child?.pid && child.exitCode === null
         ? await sampleHost(child.pid).catch(() => null)
         : null;
-      const freeShare = freeShareDuring(hostBefore === null ? null : await hostBefore, hostAfter);
+      const freeShare = freeShareDuring(hostBefore === null ? null : await hostBefore, hostAfter, undefined, processorCores);
       try {
         child?.stdin?.destroy();
       } catch {
@@ -1418,9 +1420,13 @@ export function slopeOf(samples, minimumWindowSec = ENCODE_BENCHMARK_WINDOW_SEC)
  * A hardware encoder is limited by its device and not by the cores, so its
  * reading is kept as read.
  *
+ * `processorCores` is the cores this process may use (a container's quota or
+ * CPU set); the share divided out is of those where they are fewer than the
+ * host's (`freeShareDuring`, torrent-tv/meta#180).
+ *
  * @returns {Promise<{ speed: number, measuredSpeed: number, freeShare: number | null } | null>}
  */
-export function measureEncodeSlope(ffmpegBin, encoder, rung, rawFramesPath, frame = { width: BENCHMARK_REF_W, height: BENCHMARK_REF_H }) {
+export function measureEncodeSlope(ffmpegBin, encoder, rung, rawFramesPath, frame = { width: BENCHMARK_REF_W, height: BENCHMARK_REF_H }, processorCores = null) {
   const cpuBound = encoder?.kind === "software";
   return new Promise((resolve) => {
     const args = [
@@ -1470,7 +1476,7 @@ export function measureEncodeSlope(ffmpegBin, encoder, rung, rawFramesPath, fram
           resolve(null);
           return;
         }
-        const freeShare = freeShareDuring(before, after);
+        const freeShare = freeShareDuring(before, after, undefined, processorCores);
         resolve({ speed: freeShare === null ? value : value / freeShare, measuredSpeed: value, freeShare });
       });
     };

package/services/encode/quality/HostLoad.js

@@ -593,6 +593,7 @@ export class HostLoad {
       // What the offer will multiply a prediction by, in the same line as the
       // readings it comes from.
       ` available=${asPercent(this.hostAvailability.share)} for-encoders=${asPercent(this.hostAvailability.forEncoders)}` +
+      (Number.isFinite(this.hostAvailability.boundCores) ? ` of ${this.hostAvailability.boundCores.toFixed(2)} cores` : "") +
       ` free=${asPercent(free)}` + processor + late
     );
   }
@@ -664,7 +665,7 @@ export class HostLoad {
   /**
    * @param {{ elapsedSec: number, processShare: number | null, systemShare: number | null, rejected?: string[] } | null} share
    * @param {{ proxyCpuSeconds: number | null }} previous
-   * @param {{ proxyCpuSeconds: number | null }} sample
+   * @param {{ proxyCpuSeconds: number | null, processor?: { bound?: { cores: number } | null } | null }} sample
    * @returns {number | null} The proxy's own share of the machine, for the log.
    */
   #setAvailability(share, previous, sample) {
@@ -682,11 +683,27 @@ export class HostLoad {
     const proxyShare = Number.isFinite(previous.proxyCpuSeconds)
       ? (sample.proxyCpuSeconds - previous.proxyCpuSeconds) / (share.elapsedSec * cores)
       : null;
-    this.hostAvailability = availableShareFrom({
+    // Of the cores this process may use where that is fewer than the host's
+    // (torrent-tv/meta#180, phase 3).
+    const availability = availableShareFrom({
       systemBusy: share.systemShare,
       encoderShare: share.processShare,
-      proxyShare
+      proxyShare,
+      hostCores: cores,
+      boundCores: sample.processor?.bound?.cores ?? null
     });
+    // The processor left free and what other work takes, in cores, for the
+    // pause rule (torrent-tv/meta#180, phase 4). Unknown stays null.
+    const ourShare = Number.isFinite(proxyShare) && Number.isFinite(share.processShare) ? proxyShare + share.processShare : null;
+    const reading = typeof this.#host.processorBetween === "function"
+      ? this.#host.processorBetween(previous.processor ?? null, sample.processor ?? null,
+        { systemShare: share.systemShare, ourShare, hostCores: cores })
+      : null;
+    this.hostAvailability = {
+      ...availability,
+      freeCores: Number.isFinite(reading?.freeCores) ? reading.freeCores : null,
+      otherCores: availability.known ? availability.unattributed * cores : null
+    };
     return proxyShare;
   }
 

package/services/server/wire-outputs.js

@@ -197,9 +197,6 @@ export function wireOutputs({
     // A software preset every picture is encoded at, for runs compared at one
     // quality (`--pin-preset`); null leaves the choice to the machine.
     pinnedPreset = null,
-    // A size every original-input stretch is given in place of copy rate
-    // times open (`--input-stretch-bytes`); null keeps the rule.
-    inputStretchBytes = null,
     // What every encoder this host may use was qualified and measured to do at
     // startup, by kind (`encode/calibration.js`). Takes the place of the one
     // array above, which a test may still hand in on its own.
@@ -1079,6 +1076,9 @@ export function wireOutputs({
     makeRun: ({ address, from, to, because }) => parts.encodeRuns.makeRunAt(address, from, to, because),
     segmentSeconds: parts.segmentDurationSec,
     contentionPenalties: parts.processor.penalties,
+    // The processor left free and what other work takes, for the pause rule
+    // (torrent-tv/meta#180, phase 4).
+    processor: parts.processor,
     startingSpeedFor: (address) => parts.encodeCost.speedForOutput(address),
     segmentCoverage,
     // HOW IT ASKS TO DECIDE AGAIN. A plan that refuses to place anything
@@ -1117,7 +1117,6 @@ export function wireOutputs({
     readRanges: readEncodeRanges,
     heldRanges: readEncodeHeldRanges,
     stretchCopied,
-    stretchBytes: inputStretchBytes,
     reviseBudget: () => parts.machineBudget.revise("memory", "admitted encode inputs"),
     capacity: () => parts.machineBudget.capacityOf("memory"),
     // How long this output's input takes to open, from the one owner of start
@@ -1141,9 +1140,6 @@ export function wireOutputs({
       parts.serving.invalidateWaits(output);
     }
   }) : null);
-  if (parts.encodeInputs && inputStretchBytes) {
-    logger.info(`encode input: every original-input stretch sized to ${inputStretchBytes} bytes (--input-stretch-bytes)`);
-  }
   // One owner of the disk, and the list of what takes it lives with the owner.
   parts.machineBudget = wireMachineBudget({
     segmentStore: parts.segmentStore,

package/services/storage/processor-report.js

@@ -286,11 +286,14 @@ function middleAndScatter(values) {
  * @param {(line: string) => void} params.log
  * @param {() => Array<{ pid: number, label: string, film: number | null }>} params.ffmpegRuns - The encoders running now, with the film each has made.
  * @param {() => boolean} [params.detailed]
+ * @param {(seconds: Map<number, { label: string, cores: number, speed: number | null }>) => void} [params.onRunSeconds] -
+ *   Each second's readings of every run, by process, for whoever decides
+ *   from them (`EncodeOrchestrator.noteRunSeconds`, torrent-tv/meta#180).
  * @param {number} [params.everyMs]
  * @param {number} [params.sayEveryMs]
  * @returns {{ stop: () => void }}
  */
-export function startProcessorReport({ log, ffmpegRuns, detailed = () => false, everyMs = 1000, sayEveryMs = 60_000 }) {
+export function startProcessorReport({ log, ffmpegRuns, detailed = () => false, onRunSeconds = () => {}, everyMs = 1000, sayEveryMs = 60_000 }) {
   let previous = null;
   let series = [];
   /** @type {Map<number, { label: string, cores: number[], speed: number[] }>} */
@@ -305,6 +308,15 @@ export function startProcessorReport({ log, ffmpegRuns, detailed = () => false,
     const shares = previous ? sharesBetween(previous, now) : null;
     const perRun = previous ? runSecondsBetween(previous, now) : new Map();
     previous = now;
+    if (perRun.size > 0) {
+      // A fault in whoever decides from the readings must not end the
+      // readings, nor reach the timer as an uncaught exception.
+      try {
+        onRunSeconds(perRun);
+      } catch (error) {
+        log(`processor: run seconds not handled: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
     if (!shares) return;
     series.push(shares);
     for (const [pid, second] of perRun) {