@torrent-tv/proxy 2.89.6 → 2.89.7

package/services/encode/run-budget.js

@@ -1,97 +1,97 @@
-/**
- * @file How many encoders this machine can afford on one output.
- *
- * Not how many are wanted — that is the demand map's answer — but how many can
- * run at once without making things worse. It is the SMALLEST of several
- * limits, and every one of them is measured:
- *
- * 1. **the processor.** A second encoder slows the first: measured on the addon
- *    host at 1.70x for two at 854x480 and 1.98x at 1920x1080. The ladder is
- *    walked while the measured penalty still leaves every encoder above
- *    realtime, and it stops where the measurements stop rather than continuing
- *    a curve two points cannot describe;
- * 2. **the swarm.** Every encoder reads the same torrent, so together they
- *    cannot consume faster than it is delivered. On the field file of
- *    2026-09-05 a second of film weighs 842 KB and the swarm gave 2119-3347
- *    KB/s, so the encoders' speeds together may reach 2.5-4x — which is why a
- *    copy the processor would run at 8x runs at four, and why a third encoder
- *    makes all three slower rather than adding anything;
- * 3. **memory for the torrent's pieces.** Encoders placed far apart hold
- *    windows that do not overlap, so the store must hold their SUM. On the
- *    addon host the store was already full on the readers of one viewer — "6
- *    readers want 14 pieces of 14 the store may hold" — so this is the limit
- *    that binds first there, not the processor.
- *
- * Which of them bound the answer is returned beside it, because "why is there
- * only one encoder" is otherwise a question no log can answer.
- *
- * **Only the first is supplied today.** The two readings the others need are
- * both in the torrent thread — what the swarm delivers against the film's own
- * byte rate, and the store's allowance against what one reader keeps — and
- * carrying them across is its own piece of work, deliberately not done here.
- * Until it is, the swarm and the memory terms are inert: this returns what the
- * processor allows, and says so. Stated rather than left to be discovered from
- * a parameter nobody passes.
- */
-
-/**
- * @typedef {object} RunBudget
- * @property {number} runs - How many encoders may run on this output.
- * @property {string} because - Which limit decided it.
- */
-
-/**
- * @param {object} params
- * @param {number} params.byProcessor - What the processor allows, from the
- *   measured speed and the measured penalty for concurrency. At least one.
- * @param {number} [params.speedX] - The measured speed of one encoder here.
- * @param {number} [params.refetchSecPerFilmSecond] - Seconds of swarm time per
- *   second of film: the film's own byte rate over what the swarm delivers. One
- *   encoder at speed `s` therefore consumes `s * refetch` of the swarm, and
- *   what they may consume together is all of it. Absent where neither rate has
- *   been measured, and then the swarm does not bound the answer.
- * @param {number} [params.storeBytes] - What the piece store may hold.
- * @param {number} [params.readerWindowBytes] - What one encoder's reader keeps.
- * @returns {RunBudget}
- */
-export function affordableRuns({
-  byProcessor,
-  speedX,
-  refetchSecPerFilmSecond,
-  storeBytes,
-  readerWindowBytes
-}) {
-  let runs = Number.isFinite(byProcessor) && byProcessor > 0 ? Math.floor(byProcessor) : 1;
-  let because = "the processor";
-
-  // The swarm. One encoder at speed `s` takes `s * refetch` of what is
-  // delivered, and everything running takes the sum, which cannot pass one.
-  if (
-    Number.isFinite(refetchSecPerFilmSecond) &&
-    refetchSecPerFilmSecond > 0 &&
-    Number.isFinite(speedX) &&
-    speedX > 0
-  ) {
-    const bySwarm = Math.max(1, Math.floor(1 / (speedX * refetchSecPerFilmSecond)));
-    if (bySwarm < runs) {
-      runs = bySwarm;
-      because = "what the swarm delivers";
-    }
-  }
-
-  // Memory: encoders far apart hold windows that do not overlap.
-  if (
-    Number.isFinite(storeBytes) &&
-    storeBytes > 0 &&
-    Number.isFinite(readerWindowBytes) &&
-    readerWindowBytes > 0
-  ) {
-    const byMemory = Math.max(1, Math.floor(storeBytes / readerWindowBytes));
-    if (byMemory < runs) {
-      runs = byMemory;
-      because = "memory for the torrent's pieces";
-    }
-  }
-
-  return { runs: Math.max(1, runs), because };
-}
+/**
+ * @file How many encoders this machine can afford on one output.
+ *
+ * Not how many are wanted — that is the demand map's answer — but how many can
+ * run at once without making things worse. It is the SMALLEST of several
+ * limits, and every one of them is measured:
+ *
+ * 1. **the processor.** A second encoder slows the first: measured on the addon
+ *    host at 1.70x for two at 854x480 and 1.98x at 1920x1080. The ladder is
+ *    walked while the measured penalty still leaves every encoder above
+ *    realtime, and it stops where the measurements stop rather than continuing
+ *    a curve two points cannot describe;
+ * 2. **the swarm.** Every encoder reads the same torrent, so together they
+ *    cannot consume faster than it is delivered. On the field file of
+ *    2026-09-05 a second of film weighs 842 KB and the swarm gave 2119-3347
+ *    KB/s, so the encoders' speeds together may reach 2.5-4x — which is why a
+ *    copy the processor would run at 8x runs at four, and why a third encoder
+ *    makes all three slower rather than adding anything;
+ * 3. **memory for the torrent's pieces.** Encoders placed far apart hold
+ *    windows that do not overlap, so the store must hold their SUM. On the
+ *    addon host the store was already full on the readers of one viewer — "6
+ *    readers want 14 pieces of 14 the store may hold" — so this is the limit
+ *    that binds first there, not the processor.
+ *
+ * Which of them bound the answer is returned beside it, because "why is there
+ * only one encoder" is otherwise a question no log can answer.
+ *
+ * **Only the first is supplied today.** The two readings the others need are
+ * both in the torrent thread — what the swarm delivers against the film's own
+ * byte rate, and the store's allowance against what one reader keeps — and
+ * carrying them across is its own piece of work, deliberately not done here.
+ * Until it is, the swarm and the memory terms are inert: this returns what the
+ * processor allows, and says so. Stated rather than left to be discovered from
+ * a parameter nobody passes.
+ */
+
+/**
+ * @typedef {object} RunBudget
+ * @property {number} runs - How many encoders may run on this output.
+ * @property {string} because - Which limit decided it.
+ */
+
+/**
+ * @param {object} params
+ * @param {number} params.byProcessor - What the processor allows, from the
+ *   measured speed and the measured penalty for concurrency. At least one.
+ * @param {number} [params.speedX] - The measured speed of one encoder here.
+ * @param {number} [params.refetchSecPerFilmSecond] - Seconds of swarm time per
+ *   second of film: the film's own byte rate over what the swarm delivers. One
+ *   encoder at speed `s` therefore consumes `s * refetch` of the swarm, and
+ *   what they may consume together is all of it. Absent where neither rate has
+ *   been measured, and then the swarm does not bound the answer.
+ * @param {number} [params.storeBytes] - What the piece store may hold.
+ * @param {number} [params.readerWindowBytes] - What one encoder's reader keeps.
+ * @returns {RunBudget}
+ */
+export function affordableRuns({
+  byProcessor,
+  speedX,
+  refetchSecPerFilmSecond,
+  storeBytes,
+  readerWindowBytes
+}) {
+  let runs = Number.isFinite(byProcessor) && byProcessor > 0 ? Math.floor(byProcessor) : 1;
+  let because = "the processor";
+
+  // The swarm. One encoder at speed `s` takes `s * refetch` of what is
+  // delivered, and everything running takes the sum, which cannot pass one.
+  if (
+    Number.isFinite(refetchSecPerFilmSecond) &&
+    refetchSecPerFilmSecond > 0 &&
+    Number.isFinite(speedX) &&
+    speedX > 0
+  ) {
+    const bySwarm = Math.max(1, Math.floor(1 / (speedX * refetchSecPerFilmSecond)));
+    if (bySwarm < runs) {
+      runs = bySwarm;
+      because = "what the swarm delivers";
+    }
+  }
+
+  // Memory: encoders far apart hold windows that do not overlap.
+  if (
+    Number.isFinite(storeBytes) &&
+    storeBytes > 0 &&
+    Number.isFinite(readerWindowBytes) &&
+    readerWindowBytes > 0
+  ) {
+    const byMemory = Math.max(1, Math.floor(storeBytes / readerWindowBytes));
+    if (byMemory < runs) {
+      runs = byMemory;
+      because = "memory for the torrent's pieces";
+    }
+  }
+
+  return { runs: Math.max(1, runs), because };
+}

package/services/encode/run-command.js

@@ -711,6 +711,8 @@ export function buildRunCommand({
       // one — which never comes for the last piece of every run.
       "-segment_list",
       "pipe:3",
+      "-segment_list_type",
+      "csv",
       "-segment_list_flags",
       "+live",
       ...explicitTimes,
@@ -750,6 +752,6 @@ export function buildRunCommand({
       PLAYLIST_FILE_NAME
     );
   }
-  return { args, safeIndex, startSeconds, cutTimes };
+  return { args, safeIndex, inputIndex, startSeconds, cutTimes };
 
 }

package/services/encode/run-costs.js

@@ -1,155 +1,155 @@
-/**
- * @file What starting and stopping an encoder costs on THIS host.
- *
- * Two figures, and both are terms in the one decision anybody makes about a
- * running encoder: let it drive on through material that already exists, or
- * stop it and start another where the material is missing.
- *
- * Before this file neither was measured here. The start was a single reading
- * taken once on one machine and written into the code as a constant; the stop
- * and the wait for the first output were not counted at all, so the comparison
- * priced only one side of itself and always answered the same way.
- *
- * Readings are kept and read as their median: one starved start must not decide
- * the rule, and a host that has since become busy must be able to change the
- * answer.
- */
-
-/**
- * How many recent readings a figure is taken from. The same reasoning as the
- * other learned figures in this proxy: long enough that one reading does not
- * move the answer, short enough that the answer still follows the host.
- */
-const RECENT_READINGS = 20;
-
-/**
- * The middle of a set of readings, or null when there are none.
- *
- * Written here rather than borrowed from the general helper one level up: this
- * layer states facts and imports nothing above itself, and four lines of
- * arithmetic are not worth breaking that for.
- *
- * @param {number[]} values
- * @returns {number | null}
- */
-function middleOf(values) {
-  if (values.length === 0) {
-    return null;
-  }
-  const sorted = [...values].sort((left, right) => left - right);
-  const middle = Math.floor(sorted.length / 2);
-  return sorted.length % 2 === 0 ? (sorted[middle - 1] + sorted[middle]) / 2 : sorted[middle];
-}
-
-export class RunCosts {
-  /** How long dying took, in milliseconds. @type {number[]} */
-  #dying = [];
-
-  /** How long the first output took to appear, in milliseconds. @type {number[]} */
-  #firstOutput = [];
-
-  /**
-   * What this host was measured to do at startup, before any viewer existed.
-   *
-   * WITHOUT IT BOTH FIGURES ARE ZERO AT A COLD OPEN, and zero does not read as
-   * "not measured" — it reads as "free". The whole comparison the plan makes is
-   * between leaving an encoder where it stands, which costs the remainder of its
-   * warm-up, and moving it, which costs the killing plus a warm-up from the
-   * beginning. Subtract one from the other and what is left is the killing plus
-   * the time the run has already lived — the warm-up a move throws away. Set the
-   * warm-up to zero and that difference collapses to zero as well: keeping and
-   * moving cost exactly the same, the tie falls to position, and any advantage
-   * however small wins. Field 2026-09-08: an encoder moved between two adjacent
-   * numbers every half second, produced nothing, and was killed each time.
-   *
-   * Readings from real runs replace it as they arrive; this is where the plan
-   * starts from, not where it stays.
-   *
-   * @type {{ firstByteWaitSec: number, killCostSec: number } | null}
-   */
-  #atStartup = null;
-
-  /**
-   * Take what the startup measurement found on this host.
-   *
-   * @param {{ firstByteWaitSec: number, killCostSec: number } | null} measured
-   * @returns {void}
-   */
-  noteStartup(measured) {
-    this.#atStartup =
-      Number.isFinite(measured?.firstByteWaitSec) && measured.firstByteWaitSec > 0
-        ? { firstByteWaitSec: measured.firstByteWaitSec, killCostSec: Math.max(0, measured.killCostSec ?? 0) }
-        : null;
-  }
-
-  /**
-   * Take the two readings a finished run carries. Either may be absent — a run
-   * that was never told to stop did not die on command, and one that produced
-   * nothing has no first output — and an absent reading is not a zero.
-   *
-   * @param {{ dyingMs?: number | null, firstOutputMs?: number | null,
-   *   livedMs?: number | null }} ended - `livedMs` is how long a run that
-   *   produced NOTHING was alive, which is a lower bound on the first output.
-   */
-  note(ended) {
-    // A RUN THAT PRODUCED NOTHING IS A MEASUREMENT TOO — of a lower bound. It
-    // says the first output takes at least as long as this run lived, which is
-    // a fact and not an estimate, and it is the only reading a thrash can
-    // supply: every run in one is killed before it finishes anything.
-    //
-    // Without it the figure that prices a move could only ever be learned from
-    // runs that survived, so the state in which moves are ruinous was exactly
-    // the state in which their cost stayed unknown.
-    if (!Number.isFinite(ended?.firstOutputMs) && Number.isFinite(ended?.livedMs) && ended.livedMs > 0) {
-      RunCosts.#keep(this.#firstOutput, /** @type {number} */ (ended.livedMs));
-    }
-    if (Number.isFinite(ended?.dyingMs)) {
-      RunCosts.#keep(this.#dying, /** @type {number} */ (ended.dyingMs));
-    }
-    if (Number.isFinite(ended?.firstOutputMs)) {
-      RunCosts.#keep(this.#firstOutput, /** @type {number} */ (ended.firstOutputMs));
-    }
-  }
-
-  /**
-   * @param {number[]} readings
-   * @param {number} value
-   */
-  static #keep(readings, value) {
-    readings.push(value);
-    while (readings.length > RECENT_READINGS) {
-      readings.shift();
-    }
-  }
-
-  /**
-   * The two costs in seconds, from this host's own readings.
-   *
-   * Zero where nothing has been measured yet. Zero understates both, so a plan
-   * that has no readings prices moving an encoder as cheaper than it is — which
-   * is why the plan keeps a run it cannot compare rather than moving it.
-   *
-   * @returns {{ killCostSec: number, firstByteWaitSec: number, samples: number }}
-   */
-  seconds() {
-    // MEASURED OR ABSENT, and absent is said as zero rather than as a guess.
-    //
-    // There was an `Infinity` here for a while, for the cost of a move, on the
-    // reasoning that an unmeasured price must not license an irreversible act.
-    // It was an exception in a model that needs none, and it is not required: a
-    // first piece cannot appear faster than it takes to ENCODE one, and how fast
-    // this host encodes is measured before any viewer exists. The floor is
-    // derived from that where the arithmetic is, and every figure here stays a
-    // plain reading or a plain zero.
-    //
-    // `firstByteWaitSec` is spawn to first piece, so it already contains one
-    // piece's encoding. Whoever uses it separates the two, because the piece
-    // costs more when encoders share the machine and the spawn does not.
-    return {
-      killCostSec: (middleOf(this.#dying) ?? 0) / 1000 || (this.#atStartup?.killCostSec ?? 0),
-      firstByteWaitSec:
-        (middleOf(this.#firstOutput) ?? 0) / 1000 || (this.#atStartup?.firstByteWaitSec ?? 0),
-      samples: Math.min(this.#dying.length, this.#firstOutput.length)
-    };
-  }
-}
+/**
+ * @file What starting and stopping an encoder costs on THIS host.
+ *
+ * Two figures, and both are terms in the one decision anybody makes about a
+ * running encoder: let it drive on through material that already exists, or
+ * stop it and start another where the material is missing.
+ *
+ * Before this file neither was measured here. The start was a single reading
+ * taken once on one machine and written into the code as a constant; the stop
+ * and the wait for the first output were not counted at all, so the comparison
+ * priced only one side of itself and always answered the same way.
+ *
+ * Readings are kept and read as their median: one starved start must not decide
+ * the rule, and a host that has since become busy must be able to change the
+ * answer.
+ */
+
+/**
+ * How many recent readings a figure is taken from. The same reasoning as the
+ * other learned figures in this proxy: long enough that one reading does not
+ * move the answer, short enough that the answer still follows the host.
+ */
+const RECENT_READINGS = 20;
+
+/**
+ * The middle of a set of readings, or null when there are none.
+ *
+ * Written here rather than borrowed from the general helper one level up: this
+ * layer states facts and imports nothing above itself, and four lines of
+ * arithmetic are not worth breaking that for.
+ *
+ * @param {number[]} values
+ * @returns {number | null}
+ */
+function middleOf(values) {
+  if (values.length === 0) {
+    return null;
+  }
+  const sorted = [...values].sort((left, right) => left - right);
+  const middle = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0 ? (sorted[middle - 1] + sorted[middle]) / 2 : sorted[middle];
+}
+
+export class RunCosts {
+  /** How long dying took, in milliseconds. @type {number[]} */
+  #dying = [];
+
+  /** How long the first output took to appear, in milliseconds. @type {number[]} */
+  #firstOutput = [];
+
+  /**
+   * What this host was measured to do at startup, before any viewer existed.
+   *
+   * WITHOUT IT BOTH FIGURES ARE ZERO AT A COLD OPEN, and zero does not read as
+   * "not measured" — it reads as "free". The whole comparison the plan makes is
+   * between leaving an encoder where it stands, which costs the remainder of its
+   * warm-up, and moving it, which costs the killing plus a warm-up from the
+   * beginning. Subtract one from the other and what is left is the killing plus
+   * the time the run has already lived — the warm-up a move throws away. Set the
+   * warm-up to zero and that difference collapses to zero as well: keeping and
+   * moving cost exactly the same, the tie falls to position, and any advantage
+   * however small wins. Field 2026-09-08: an encoder moved between two adjacent
+   * numbers every half second, produced nothing, and was killed each time.
+   *
+   * Readings from real runs replace it as they arrive; this is where the plan
+   * starts from, not where it stays.
+   *
+   * @type {{ firstByteWaitSec: number, killCostSec: number } | null}
+   */
+  #atStartup = null;
+
+  /**
+   * Take what the startup measurement found on this host.
+   *
+   * @param {{ firstByteWaitSec: number, killCostSec: number } | null} measured
+   * @returns {void}
+   */
+  noteStartup(measured) {
+    this.#atStartup =
+      Number.isFinite(measured?.firstByteWaitSec) && measured.firstByteWaitSec > 0
+        ? { firstByteWaitSec: measured.firstByteWaitSec, killCostSec: Math.max(0, measured.killCostSec ?? 0) }
+        : null;
+  }
+
+  /**
+   * Take the two readings a finished run carries. Either may be absent — a run
+   * that was never told to stop did not die on command, and one that produced
+   * nothing has no first output — and an absent reading is not a zero.
+   *
+   * @param {{ dyingMs?: number | null, firstOutputMs?: number | null,
+   *   livedMs?: number | null }} ended - `livedMs` is how long a run that
+   *   produced NOTHING was alive, which is a lower bound on the first output.
+   */
+  note(ended) {
+    // A RUN THAT PRODUCED NOTHING IS A MEASUREMENT TOO — of a lower bound. It
+    // says the first output takes at least as long as this run lived, which is
+    // a fact and not an estimate, and it is the only reading a thrash can
+    // supply: every run in one is killed before it finishes anything.
+    //
+    // Without it the figure that prices a move could only ever be learned from
+    // runs that survived, so the state in which moves are ruinous was exactly
+    // the state in which their cost stayed unknown.
+    if (!Number.isFinite(ended?.firstOutputMs) && Number.isFinite(ended?.livedMs) && ended.livedMs > 0) {
+      RunCosts.#keep(this.#firstOutput, /** @type {number} */ (ended.livedMs));
+    }
+    if (Number.isFinite(ended?.dyingMs)) {
+      RunCosts.#keep(this.#dying, /** @type {number} */ (ended.dyingMs));
+    }
+    if (Number.isFinite(ended?.firstOutputMs)) {
+      RunCosts.#keep(this.#firstOutput, /** @type {number} */ (ended.firstOutputMs));
+    }
+  }
+
+  /**
+   * @param {number[]} readings
+   * @param {number} value
+   */
+  static #keep(readings, value) {
+    readings.push(value);
+    while (readings.length > RECENT_READINGS) {
+      readings.shift();
+    }
+  }
+
+  /**
+   * The two costs in seconds, from this host's own readings.
+   *
+   * Zero where nothing has been measured yet. Zero understates both, so a plan
+   * that has no readings prices moving an encoder as cheaper than it is — which
+   * is why the plan keeps a run it cannot compare rather than moving it.
+   *
+   * @returns {{ killCostSec: number, firstByteWaitSec: number, samples: number }}
+   */
+  seconds() {
+    // MEASURED OR ABSENT, and absent is said as zero rather than as a guess.
+    //
+    // There was an `Infinity` here for a while, for the cost of a move, on the
+    // reasoning that an unmeasured price must not license an irreversible act.
+    // It was an exception in a model that needs none, and it is not required: a
+    // first piece cannot appear faster than it takes to ENCODE one, and how fast
+    // this host encodes is measured before any viewer exists. The floor is
+    // derived from that where the arithmetic is, and every figure here stays a
+    // plain reading or a plain zero.
+    //
+    // `firstByteWaitSec` is spawn to first piece, so it already contains one
+    // piece's encoding. Whoever uses it separates the two, because the piece
+    // costs more when encoders share the machine and the spawn does not.
+    return {
+      killCostSec: (middleOf(this.#dying) ?? 0) / 1000 || (this.#atStartup?.killCostSec ?? 0),
+      firstByteWaitSec:
+        (middleOf(this.#firstOutput) ?? 0) / 1000 || (this.#atStartup?.firstByteWaitSec ?? 0),
+      samples: Math.min(this.#dying.length, this.#firstOutput.length)
+    };
+  }
+}

package/services/encode/run-inputs.js

@@ -1,53 +1,53 @@
-/**
- * @file The addresses an encoder reads its source from.
- *
- * Built per run from facts that belong elsewhere — which files the output
- * reads (`OutputSpec`), where the stream route listens, which output the read
- * feeds, and how wide its read window is — and kept nowhere.
- *
- * Two query parameters are what make the encoder's read what it is to the
- * stream route: `reader=playback`, the one read that says where the viewer is,
- * and `windowBytes`, how far ahead of itself that read asks the swarm for,
- * sized in seconds of playback by whoever knows the file's byte rate.
- */
-
-/** The query parameter naming which run of an output a read feeds. */
-const RUN_PARAMETER = "run";
-
-/**
- * @param {object} params
- * @param {{ fileIndex: number, streamUrl: (baseUrl: string, options?: { sessionId?: string }) => URL }} params.picture
- * @param {{ fileIndex: number, streamUrl: (baseUrl: string, options?: { sessionId?: string }) => URL }} params.soundtrack
- *   The file the carried soundtrack lives in; the picture's own file for an
- *   embedded track.
- * @param {"video-only" | "audio-only" | "muxed" | "empty"} params.carries
- * @param {boolean} params.audioSeparate - The picture's sound travels as its own output.
- * @param {string} params.sessionId - Which output this read feeds.
- * @param {number} [params.runToken] - Which run of that output the read feeds,
- *   so the time its input waits is charged to that run and not to another one
- *   working on the same output.
- * @param {number} params.readWindowBytes - Zero when no window was measured.
- * @param {string} params.baseUrl
- * @returns {{ inputFile: object, audioFile: object, inputUrl: string, audioInputUrl: string }}
- */
-export function encoderInputs({ picture, soundtrack, carries, audioSeparate, sessionId, runToken, readWindowBytes, baseUrl }) {
-  // A soundtrack shipped as its own file is encoded FROM that file, so a
-  // rendition of it reads nothing else.
-  const inputFile = carries === "audio-only" && soundtrack !== picture ? soundtrack : picture;
-  const input = inputFile.streamUrl(baseUrl, { sessionId });
-  const forRun = (url) => {
-    if (Number.isInteger(runToken)) url.searchParams.set(RUN_PARAMETER, String(runToken));
-    return url;
-  };
-  forRun(input);
-  if (Number.isFinite(readWindowBytes) && readWindowBytes > 0) {
-    input.searchParams.set("windowBytes", String(readWindowBytes));
-    input.searchParams.set("reader", "playback");
-  }
-  // The second input exists only for a picture that carries its sound inside
-  // itself when that sound is in another file.
-  const audioInputUrl = carries !== "audio-only" && !audioSeparate && soundtrack !== inputFile
-    ? forRun(soundtrack.streamUrl(baseUrl, { sessionId })).toString()
-    : "";
-  return { inputFile, audioFile: soundtrack, inputUrl: input.toString(), audioInputUrl };
-}
+/**
+ * @file The addresses an encoder reads its source from.
+ *
+ * Built per run from facts that belong elsewhere — which files the output
+ * reads (`OutputSpec`), where the stream route listens, which output the read
+ * feeds, and how wide its read window is — and kept nowhere.
+ *
+ * Two query parameters are what make the encoder's read what it is to the
+ * stream route: `reader=playback`, the one read that says where the viewer is,
+ * and `windowBytes`, how far ahead of itself that read asks the swarm for,
+ * sized in seconds of playback by whoever knows the file's byte rate.
+ */
+
+/** The query parameter naming which run of an output a read feeds. */
+const RUN_PARAMETER = "run";
+
+/**
+ * @param {object} params
+ * @param {{ fileIndex: number, streamUrl: (baseUrl: string, options?: { sessionId?: string }) => URL }} params.picture
+ * @param {{ fileIndex: number, streamUrl: (baseUrl: string, options?: { sessionId?: string }) => URL }} params.soundtrack
+ *   The file the carried soundtrack lives in; the picture's own file for an
+ *   embedded track.
+ * @param {"video-only" | "audio-only" | "muxed" | "empty"} params.carries
+ * @param {boolean} params.audioSeparate - The picture's sound travels as its own output.
+ * @param {string} params.sessionId - Which output this read feeds.
+ * @param {number} [params.runToken] - Which run of that output the read feeds,
+ *   so the time its input waits is charged to that run and not to another one
+ *   working on the same output.
+ * @param {number} params.readWindowBytes - Zero when no window was measured.
+ * @param {string} params.baseUrl
+ * @returns {{ inputFile: object, audioFile: object, inputUrl: string, audioInputUrl: string }}
+ */
+export function encoderInputs({ picture, soundtrack, carries, audioSeparate, sessionId, runToken, readWindowBytes, baseUrl }) {
+  // A soundtrack shipped as its own file is encoded FROM that file, so a
+  // rendition of it reads nothing else.
+  const inputFile = carries === "audio-only" && soundtrack !== picture ? soundtrack : picture;
+  const input = inputFile.streamUrl(baseUrl, { sessionId });
+  const forRun = (url) => {
+    if (Number.isInteger(runToken)) url.searchParams.set(RUN_PARAMETER, String(runToken));
+    return url;
+  };
+  forRun(input);
+  if (Number.isFinite(readWindowBytes) && readWindowBytes > 0) {
+    input.searchParams.set("windowBytes", String(readWindowBytes));
+    input.searchParams.set("reader", "playback");
+  }
+  // The second input exists only for a picture that carries its sound inside
+  // itself when that sound is in another file.
+  const audioInputUrl = carries !== "audio-only" && !audioSeparate && soundtrack !== inputFile
+    ? forRun(soundtrack.streamUrl(baseUrl, { sessionId })).toString()
+    : "";
+  return { inputFile, audioFile: soundtrack, inputUrl: input.toString(), audioInputUrl };
+}