@torrent-tv/proxy 2.77.0 → 2.79.0

package/services/orchestrators/EncodeOrchestrator.js

@@ -27,6 +27,8 @@ import { CoverageMap } from "../encode/CoverageMap.js";
 import { firstUnmetWant, planEncoders } from "../encode/EncodePlan.js";
 import { endOfRun } from "../encode/EncodeRun.js";
 import { ENCODE_EXIT } from "../encode/encode-exit.js";
+import { affordableRuns } from "../encode/run-budget.js";
+import { RunCosts } from "../encode/run-costs.js";
 import { SegmentDemand } from "../encode/SegmentDemand.js";
 
 export class EncodeOrchestrator {
@@ -36,9 +38,19 @@ export class EncodeOrchestrator {
   /** Output address to the runs on it. @type {Map<string, import("../encode/EncodeRun.js").EncodeRun[]>} */
   #runs = new Map();
 
+
   /** How runs have ended, by cause. @type {Map<string, number>} */
   #endings = new Map();
 
+  /** The last state said out loud, so an unchanged state is not repeated. */
+  #lastDescribed = "";
+
+  /** What a stop and a start have cost on this host. */
+  #costs = new RunCosts();
+
+  /** The last reason a budget was cut, so the same one is not said twice. */
+  #lastBudgetReason = new Map();
+
   /**
    * @param {object} params
    * @param {(address: string) => number} params.maxRunsFor - How many encoders
@@ -53,17 +65,31 @@ export class EncodeOrchestrator {
    * @param {{ info: (line: string) => void, warn: (line: string) => void }} params.logger
    * @param {() => number} [params.now]
    */
-  constructor({ maxRunsFor, makeRun, segmentSeconds, restartCostSec, lookaheadSegments = 0, logger, now }) {
+  constructor({
+    maxRunsFor,
+    makeRun,
+    segmentSeconds,
+    restartCostSec,
+    refetchSecPerFilmSecond = () => 0,
+    segmentStore = null,
+    logger,
+    now
+  }) {
+    // The store of produced segments — the layer below this one. It is asked to
+    // clean up after a run that ended other than by reaching the end of its
+    // stretch, which is the one thing an ending must not leave behind: a file
+    // under a name that promises a whole segment.
+    this.segmentStore = segmentStore;
     this.demand = new SegmentDemand();
     this.maxRunsFor = maxRunsFor;
+    // Seconds of swarm time per second of film: what re-encoding material that
+    // already exists costs the download, over and above the encoder's own time.
+    // Injected, because the film's byte rate and the swarm's are measured
+    // elsewhere and this class must not reach for them.
+    this.refetchSecPerFilmSecond = refetchSecPerFilmSecond;
     this.makeRun = makeRun;
     this.segmentSeconds = segmentSeconds;
     this.restartCostSec = restartCostSec;
-    // How far in front of its viewer a run is allowed to get. It is what bounds
-    // the claim of a run that was given no end — see #claimFor.
-    this.lookaheadSegments = Number.isFinite(lookaheadSegments) && lookaheadSegments > 0
-      ? Math.ceil(lookaheadSegments)
-      : 0;
     this.logger = logger;
     this.now = typeof now === "function" ? now : Date.now;
   }
@@ -121,9 +147,14 @@ export class EncodeOrchestrator {
    * @param {string} params.address
    * @param {number} params.from
    * @param {number} params.to
+   * @param {number} [params.priority] - Higher is sooner. One viewer states
+   *   several stretches at once — what must be ready before they set off, what
+   *   is reachable while they watch it, the rest of the track — and the filling
+   *   takes them in this order. Absent means one undifferentiated want, which
+   *   is what a caller that knows only a position states.
    */
-  want({ claimant, address, from, to }) {
-    this.demand.state({ claimant, address, from, to, statedAt: this.now() });
+  want({ claimant, address, from, to, priority = 0 }) {
+    this.demand.state({ claimant, address, from, to, priority, statedAt: this.now() });
   }
 
   /**
@@ -173,6 +204,19 @@ export class EncodeOrchestrator {
     for (const address of addresses) {
       this.#reconcileOne(address);
     }
+    // WHAT THIS CLASS BELIEVES, said by this class. `describe()` was written
+    // and called from nowhere, so on 2026-09-05 the question "why did the plan
+    // not see the gap the viewer was stopped at" had to be answered by
+    // inference from start and stop lines, and was not answered at all.
+    //
+    // Printed on CHANGE rather than on a timer: a quiet session says nothing, a
+    // session that is deciding something says what it decided, and there is no
+    // interval to choose.
+    const state = this.describe();
+    if (state !== this.#lastDescribed) {
+      this.#lastDescribed = state;
+      this.logger.info(state);
+    }
   }
 
   /**
@@ -196,9 +240,14 @@ export class EncodeOrchestrator {
         });
       }
     }
+    // Carrying the priority through, because the filling takes the work in that
+    // order: what a viewer must have before they set off comes before what is
+    // merely in front of them, which comes before the rest of the track. Passed
+    // as a plain number so the plan stays arithmetic.
     const windows = this.demand.windowsOn(address).map((window) => ({
       from: window.from,
-      to: window.to
+      to: window.to,
+      priority: Number(window.priority) || 0
     }));
     const live = this.runsOn(address).filter((run) => run.isAlive);
     const actions = planEncoders({
@@ -208,9 +257,17 @@ export class EncodeOrchestrator {
       // each; what it hands back names the run by BEING it, so nothing has to
       // invent a token to refer to one by.
       runs: live,
-      maxRuns: Math.max(0, this.maxRunsFor(address)),
+      maxRuns: this.#affordableOn(address, live),
       segmentSeconds: this.segmentSeconds,
-      restartCostSec: this.restartCostSec
+      restartCostSec: this.restartCostSec,
+      // Measured from this host's own runs, rather than written into the code
+      // from one machine's reading.
+      ...this.#costs.seconds(),
+      // What a second of film costs to fetch again, in seconds of swarm time.
+      // Answered by whoever measures the film's own byte rate and the swarm's;
+      // zero until they have, which makes driving through look cheaper than it
+      // is and is stated here so the bias is known.
+      refetchSecPerFilmSecond: this.refetchSecPerFilmSecond(address)
     });
 
     for (const action of actions) {
@@ -244,24 +301,68 @@ export class EncodeOrchestrator {
    * @param {string} because
    */
   #start(address, from, to, because) {
+    // The encoder is built here and now: whoever builds one waits for nothing,
+    // so it exists by the time this line returns. That is what makes the
+    // stretch held from this instant — this class knows what it is making
+    // because it has just made it, and no second encoder can be started for the
+    // same stretch on the next pass.
+    //
+    // It was not always so. The builder used to answer with nothing and start
+    // the encoder behind the answer, so the stretch stayed FREE for as long as
+    // that took, and every pass in between started another one: 684 starts in
+    // 482 seconds of field 2026-09-05, of which 973 answers said the encoder
+    // was not there yet — every start without exception.
+    //
     // The run names itself: identity is a property of the thing, and two
     // places minting names is how one stops being unique.
     const run = this.makeRun({ address, from, to });
     if (!run) {
-      // Not necessarily a failure: making an encoder can take a probe and a
-      // keyframe read, and this call is arithmetic that must not wait on
-      // either. Whoever builds one answers with nothing while it is on its way,
-      // and the next pass sees it.
-      this.logger.info(`encode: an encoder for #${from}..#${to} of ${address} is not there yet`);
+      // A refusal, not a wait: no session serves this output, or this position
+      // has failed to start too many times running.
+      this.logger.warn(`encode: no encoder could be made for #${from}..#${to} of ${address}`);
       return;
     }
     const onThisOutput = this.#runs.get(address) ?? [];
     onThisOutput.push(run);
     this.#runs.set(address, onThisOutput);
-    this.coverageOf(address).claim(run, from, to);
+    this.coverageOf(address).claim(run, from, endOfRun({ from, to }));
     run.start(because);
   }
 
+  /**
+   * How many encoders may run on this output, from every limit at once.
+   *
+   * The processor is one of them and is answered from outside, where the
+   * machine is measured. The other two are known here: what the swarm delivers,
+   * through the seconds of swarm time a second of film costs, and — once it is
+   * supplied — the memory the piece store may hold against what one encoder's
+   * reader keeps.
+   *
+   * Said out loud when it is not the processor that decided, because "why is
+   * there only one encoder" is otherwise a question no log can answer.
+   *
+   * @param {string} address
+   * @param {{ speedX: number }[]} live
+   * @returns {number}
+   */
+  #affordableOn(address, live) {
+    const byProcessor = Math.max(0, this.maxRunsFor(address));
+    const fastest = live.reduce((best, run) => Math.max(best, run.speedX || 0), 0);
+    const budget = affordableRuns({
+      byProcessor,
+      speedX: fastest,
+      refetchSecPerFilmSecond: this.refetchSecPerFilmSecond(address)
+    });
+    if (budget.runs !== byProcessor && budget.because !== this.#lastBudgetReason.get(address)) {
+      this.#lastBudgetReason.set(address, budget.because);
+      this.logger.info(
+        `encode: ${budget.runs} encoder(s) on ${address.slice(0, 60)} — ${budget.because} ` +
+        `(the processor alone would allow ${byProcessor})`
+      );
+    }
+    return budget.runs;
+  }
+
   /**
    * Take charge of a run this class did not start.
    *
@@ -316,8 +417,18 @@ export class EncodeOrchestrator {
       coverage.claim(run, from, end);
       return;
     }
+    // A RUN WITH NO END HOLDS WHAT IT HAS MADE, NOT WHAT IT MIGHT MAKE.
+    //
+    // "No end" means the film's length is not known, so there is no last number
+    // to claim towards. Claiming the rest of the film would leave a viewer who
+    // opens the same film further in with every number taken and no encoder at
+    // all. Claiming a fixed distance in front of the head — which is what this
+    // did — needs a number nobody measured, and the number it used was the
+    // suspended-encoder threshold that no longer exists.
+    //
+    // What it has made is a fact, and it is the only one available here.
     const head = Number.isFinite(run?.head) ? run.head : from;
-    coverage.claim(run, from, Math.max(from, head + this.lookaheadSegments));
+    coverage.claim(run, from, Math.max(from, head));
   }
 
   /**
@@ -338,6 +449,15 @@ export class EncodeOrchestrator {
    * @param {import("../encode/EncodeRun.js").RunEnded} ended
    */
   noteEnded(ended) {
+    this.#costs.note(ended);
+    // 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 file's name is indistinguishable from a finished one's.
+    if (ended.ending !== ENCODE_EXIT.COMPLETE && this.segmentStore) {
+      void this.segmentStore
+        .discardOpenPieceOf(ended.address, { from: ended.from, to: ended.to })
+        .catch(() => {});
+    }
     this.coverageOf(ended.address).release(ended.run);
     const remaining = this.runsOn(ended.address).filter((run) => run !== ended.run);
     if (remaining.length === 0) {
@@ -378,14 +498,21 @@ export class EncodeOrchestrator {
     const parts = [];
     for (const address of new Set([...this.demand.addresses(), ...this.#runs.keys()])) {
       const coverage = this.coverageOf(address);
-      const windows = this.demand.windowsOn(address).map((w) => ({ from: w.from, to: w.to }));
+      const stated = this.demand.windowsOn(address);
+      const windows = stated.map((w) => ({ from: w.from, to: w.to }));
       const waiting = firstUnmetWant(coverage, windows);
       const runs = this.runsOn(address)
         .map((run) => `#${run.head}..#${run.to}@${run.speedX.toFixed(1)}x`)
         .join(" ");
+      // The zones as they were stated, with their order, so a plan that is
+      // working at the wrong end of the film is visible rather than inferred.
+      const zones = [...stated]
+        .sort((left, right) => (right.priority ?? 0) - (left.priority ?? 0) || left.from - right.from)
+        .map((w) => `p${w.priority ?? 0}:#${w.from}..#${w.to}`)
+        .join(" ");
       parts.push(
         `${address.slice(0, 60)} ready=${coverage.stats().ready} ` +
-        `viewers=${windows.length} runs=[${runs}] ` +
+        `zones=[${zones}] runs=[${runs}] ` +
         `waiting=${waiting === null ? "nobody" : `#${waiting}`}`
       );
     }

package/services/priority/PriorityMap.js

@@ -0,0 +1,252 @@
+/**
+ * @file THE PRIORITY MAP — what one viewer needs, what all of them need
+ * together, and in what order the work should be taken.
+ *
+ * A layer of its own, below both orchestrators and depending on nothing. It
+ * knows ONLY priorities: what is downloaded is the download orchestrator's own
+ * knowledge, what is encoded is the encoding orchestrator's, and neither is
+ * visible from here. Both read this and recompute their own on every change.
+ *
+ * The shape, stated by the user 2026-09-05:
+ *
+ * > Usually you make a map for each viewer, then merge the maps, then decide
+ * > the best way of filling it given the encoders available, where they are now
+ * > and how many there are.
+ *
+ * Three questions, and this file answers the first two. The third — the filling
+ * — belongs to whoever holds the encoders, and it is handed the merged map
+ * instead of a list of windows.
+ *
+ * **ONE PRIORITISATION, TWO CONSUMERS.** Downloading and encoding keep
+ * different STATES — made / being made / free for one; downloaded / arriving,
+ * and which peers hold it at what speed, for the other — but they must agree
+ * about what matters first, or the swarm fetches what the encoder will not
+ * reach for another twenty minutes. That agreement is this map.
+ *
+ * **THE UNIT IS SECONDS OF FILM.** A map is a set of stretches with sizes and a
+ * length of its own, so it needs a unit, and seconds are the only one every
+ * term of the arithmetic is already stated in: encode speed is a ratio of
+ * seconds to seconds, the measured allowance below which an interruption
+ * reaches a viewer is seconds, the viewer's position is seconds, the film's
+ * length is seconds. Bytes cannot serve — how many a second costs is not known
+ * when a file is opened and is not constant across it, and a soundtrack in a
+ * file of its own has bytes of its own. Segment numbers cannot serve either:
+ * they exist only once a cut grid is read, and two outputs of one film number
+ * differently.
+ *
+ * **What this file must NOT know**, and the boundary is the point: nothing about
+ * containers, cut grids, pieces or bytes. Turning a stretch of seconds into the
+ * bytes of one track is the container's and the track's business, by whatever
+ * means suit that file — a Cues table, a sample table, or a walk when the file
+ * carries neither, which is the same answer they already give in order to play
+ * it at all. Getting those bytes is the downloader's business; making segments
+ * out of them is the encoder's.
+ */
+
+/**
+ * How urgently a stretch of film is wanted. Higher is sooner.
+ *
+ * @typedef {object} DemandZone
+ * @property {number} from - First second of film, inclusive.
+ * @property {number} to - Last second of film, inclusive.
+ * @property {number} priority - Higher is more urgent. Only the ORDER between
+ *   zones is meaningful; the numbers themselves are not a scale.
+ */
+
+/** Where the viewer stands. Nothing outranks it. */
+const AT_THE_VIEWER = 33;
+
+/** In front of them, within reach while they watch what is already made. */
+const IN_FRONT = 32;
+
+/** The rest of the track: wanted, because the file is encoded whole. */
+const THE_REST = 1;
+
+/**
+ * How many zones one viewer's map may hold.
+ *
+ * Below realtime the zones grow geometrically, so their number is the logarithm
+ * of the film left over what the viewer holds — five on the addon host's worst
+ * measured case, and it grows by one each time the speed halves. The bound is
+ * not a policy about how many encoders may run (the machine's budget answers
+ * that, and it is far smaller); it stops a speed measured at almost zero from
+ * turning a film into thousands of slivers before anything reads the map.
+ */
+const MOST_ZONES = 32;
+
+/**
+ * One viewer's map, and every boundary in it is measured rather than chosen.
+ *
+ * The shape depends on one measured number — how fast this machine encodes this
+ * track against realtime:
+ *
+ * - **at or above realtime** the encoder gains on the viewer everywhere, so one
+ *   of them holds the whole film. Three zones: the measured allowance in front
+ *   of the viewer, what the encoder reaches while they watch it, and the rest;
+ * - **below realtime** the encoder loses `1 - speed` of a second for every
+ *   second played, so one cannot hold the film and the map says how many can.
+ *   An encoder starting at `q` stays ahead of a viewer at `p` for
+ *   `(q - p) * s / (1 - s)`, which GROWS with its distance from them — so the
+ *   zones grow, each is one encoder's share, and their number is the smallest
+ *   that holds this viewer.
+ *
+ * The last zone is always the rest of the track, wanted because the file is
+ * encoded whole and last because nobody is waiting on it.
+ *
+ * @param {object} params
+ * @param {number} params.atSeconds - Where they are watching from.
+ * @param {number} params.durationSeconds - How long the film is.
+ * @param {number} params.allowanceSeconds - The measured depth below which an
+ *   interruption reaches this viewer (`minimumBufferSeconds`).
+ * @param {number} params.encodeSpeedX - Measured encode speed against realtime
+ *   for this track on this machine. Zero or less means nothing has measured it
+ *   yet, and then zone 2 is left out rather than invented.
+ * @returns {DemandZone[]} Ascending, without gaps or overlaps, covering
+ *   everything from where they are to the end of the film.
+ */
+export function mapForViewer({ atSeconds, durationSeconds, allowanceSeconds, encodeSpeedX }) {
+  const from = Number.isFinite(atSeconds) && atSeconds > 0 ? atSeconds : 0;
+  const end = Number.isFinite(durationSeconds) ? durationSeconds : 0;
+  if (!(end > from)) {
+    return [];
+  }
+  const allowance = Number.isFinite(allowanceSeconds) && allowanceSeconds > 0 ? allowanceSeconds : 0;
+  const speed = Number.isFinite(encodeSpeedX) && encodeSpeedX > 0 ? encodeSpeedX : 0;
+
+  /** @type {DemandZone[]} */
+  const zones = [];
+
+  // AT OR ABOVE REALTIME ONE ENCODER SUFFICES, whatever the film's length.
+  //
+  // From the condition below with `s >= 1`: the encoder gains on the viewer at
+  // every point, so there is no distance at which they catch it. All that has
+  // to exist in front of them is the allowance this file's own interruptions
+  // have shown to be necessary.
+  if (speed === 0 || speed >= 1) {
+    const readyBy = Math.min(end, from + allowance);
+    zones.push({ from, to: readyBy, priority: AT_THE_VIEWER });
+    if (readyBy < end && speed > 0) {
+      // While they watch what the first zone holds, the encoder makes `speed`
+      // times as much again. Beyond that nobody is waiting yet.
+      const reach = Math.min(end, readyBy + (readyBy - from) * speed);
+      if (reach > readyBy) {
+        zones.push({ from: readyBy, to: reach, priority: IN_FRONT });
+      }
+    }
+    const covered = zones[zones.length - 1].to;
+    if (covered < end) {
+      zones.push({ from: covered, to: end, priority: THE_REST });
+    }
+    return zones;
+  }
+
+  // BELOW REALTIME THE ZONES GROW, AND EACH IS ONE ENCODER'S SHARE.
+  //
+  // An encoder starting at `q` produces the point `q + y` after `y / s`, and the
+  // viewer reaches it after `q + y - p`. It stays ahead while
+  //
+  //     y <= (q - p) * s / (1 - s)
+  //
+  // so the length one encoder can hold GROWS with its distance from the viewer:
+  // the further off it starts, the later the viewer arrives. Equal shares are
+  // therefore the wrong division, and by a wide margin — on the addon host with
+  // 2400 s of film left, 120 s held and 0.5x, equal shares need twenty encoders
+  // and growing ones need five (120, 240, 480, 960, 1920).
+  //
+  // Each zone is exactly as long as its bound allows, which makes the count the
+  // smallest that can hold this viewer: any zone longer stalls them, and any
+  // shorter leaves the next one starting nearer, where its own bound is tighter.
+  // With nothing held, no partition holds this viewer: the first encoder can
+  // stay ahead for `b * s / (1 - s)`, and that is zero. Saying so plainly beats
+  // slicing the film into equal slivers that pretend otherwise — the whole of
+  // what is left is urgent, and it will still not be enough.
+  if (allowance <= 0) {
+    return [{ from, to: end, priority: AT_THE_VIEWER }];
+  }
+  const growth = speed / (1 - speed);
+  let at = from;
+  let held = allowance;
+  let priority = AT_THE_VIEWER;
+  while (at < end && zones.length < MOST_ZONES) {
+    const share = held * growth;
+    const to = Math.min(end, at + share);
+    zones.push({ from: at, to, priority });
+    held += to - at;
+    at = to;
+    // The next zone is one step less urgent: the viewer meets the one before it
+    // first. One scale for every viewer, or merging two maps would compare
+    // numbers that mean different things.
+    priority = Math.max(THE_REST + 1, priority - 1);
+  }
+  if (at < end) {
+    zones.push({ from: at, to: end, priority: THE_REST });
+  }
+  return zones;
+}
+
+/**
+ * Every viewer's map as one.
+ *
+ * The highest priority per second wins: film two people want is as urgent as
+ * the more urgent of them, and making it once serves both. What comes back has
+ * no overlaps, so the filling can walk it without asking about any individual
+ * viewer — which is the rule this layer exists to keep, that which viewer asked
+ * never reaches the encoders.
+ *
+ * @param {DemandZone[][]} maps
+ * @returns {DemandZone[]} Ascending by position.
+ */
+export function mergeMaps(maps) {
+  /** @type {DemandZone[]} */
+  const all = [];
+  for (const map of maps ?? []) {
+    for (const zone of map ?? []) {
+      if (Number.isFinite(zone?.from) && Number.isFinite(zone?.to) && zone.to > zone.from) {
+        all.push(zone);
+      }
+    }
+  }
+  if (all.length === 0) {
+    return [];
+  }
+  // Walked by BOUNDARIES rather than by second: a film is thousands of them and
+  // this is asked again on every change.
+  const points = [...new Set(all.flatMap((zone) => [zone.from, zone.to]))].sort(
+    (left, right) => left - right
+  );
+  /** @type {DemandZone[]} */
+  const merged = [];
+  for (let index = 0; index < points.length - 1; index += 1) {
+    const from = points[index];
+    const to = points[index + 1];
+    let priority = 0;
+    for (const zone of all) {
+      if (zone.from <= from && to <= zone.to && zone.priority > priority) {
+        priority = zone.priority;
+      }
+    }
+    if (priority <= 0) {
+      continue;
+    }
+    const previous = merged[merged.length - 1];
+    if (previous && previous.priority === priority && previous.to === from) {
+      previous.to = to;
+      continue;
+    }
+    merged.push({ from, to, priority });
+  }
+  return merged;
+}
+
+/**
+ * The merged map in the order the work is taken: most urgent first, and within
+ * one priority the earliest film first — that is where somebody is stopped.
+ *
+ * @param {DemandZone[]} merged
+ * @returns {DemandZone[]}
+ */
+export function inWorkingOrder(merged) {
+  return [...(merged ?? [])].sort(
+    (left, right) => right.priority - left.priority || left.from - right.from
+  );
+}

package/services/viewer/Viewer.js

@@ -125,6 +125,89 @@ export class Viewer {
      * @type {Set<string>}
      */
     this.outputs = new Set();
+    // Whether the picture is moving. A viewer who has stopped it consumes
+    // nothing, so nothing in front of them ever becomes due — they have no
+    // deadline at all, and the work goes to whoever is watching. The page knows
+    // this exactly and says it outright; inferring it from a position that has
+    // not moved takes two reports and lies whenever a browser holding a full
+    // cushion goes quiet between segments, which it does.
+    this.playing = true;
+    // Seconds of film held ahead of the picture, as the page last said.
+    this.bufferedSeconds = null;
+  }
+
+  /**
+   * Where they are, in SECONDS of film, and nothing else.
+   *
+   * A segment number cannot live here: the picture and the soundtrack of one
+   * film are cut independently and into different numbers of pieces — 454
+   * against 401 on the field file of 2026-09-05 — so piece 48 of one is not the
+   * same moment as piece 48 of the other. Whoever holds a cut grid turns these
+   * seconds into their own numbers.
+   *
+   * @param {number} seconds
+   * @param {number} [now]
+   */
+  moveTo(seconds, now = Date.now()) {
+    if (!Number.isFinite(seconds) || seconds < 0) {
+      return;
+    }
+    this.position = { seconds, at: now, seeked: seconds };
+    this.lastSeenAt = now;
+  }
+
+  /**
+   * Everything a viewer says about itself, in one statement.
+   *
+   * The page sends four things together — how fast its link measured, how much
+   * film it holds, where the picture is, and whether the picture is moving —
+   * and all four are facts about this viewer. Taking them apart and assigning
+   * them one by one somewhere else is how they came to be spread over five
+   * places, two of them on a session shared with other people.
+   *
+   * @param {object} report
+   * @param {number} report.linkMbps
+   * @param {number} report.bufferedAheadSec
+   * @param {number | null} [report.positionSeconds] - Null from a page that
+   *   does not say; then the position stands as it was.
+   * @param {boolean} [report.playing] - Absent from a page that does not say;
+   *   then the viewer counts as playing, which is what every page meant before
+   *   it could say otherwise.
+   * @param {number} [now]
+   */
+  report({ linkMbps, bufferedAheadSec, positionSeconds = null, playing }, now = Date.now()) {
+    this.netReport = {
+      linkMbps,
+      bufferedAheadSec,
+      positionSeconds:
+        Number.isFinite(positionSeconds) && positionSeconds >= 0 ? positionSeconds : null,
+      at: now
+    };
+    this.bufferedSeconds = bufferedAheadSec;
+    this.playing = playing === undefined ? true : Boolean(playing);
+    if (Number.isFinite(positionSeconds) && positionSeconds >= 0) {
+      this.moveTo(/** @type {number} */ (positionSeconds), now);
+    }
+    this.seen(now);
+  }
+
+  /**
+   * When this viewer runs out of what they hold, in milliseconds.
+   *
+   * Film is consumed at one second per second while the picture moves, so the
+   * moment they run dry is now plus what they hold. Stopped, they consume
+   * nothing and there is no such moment — which is why a pause needs no rule of
+   * its own anywhere: it falls out of this as an absent deadline.
+   *
+   * @param {number} [now]
+   * @returns {number | null}
+   */
+  deadlineAt(now = Date.now()) {
+    if (!this.playing) {
+      return null;
+    }
+    const held = Number.isFinite(this.bufferedSeconds) ? Math.max(0, this.bufferedSeconds) : 0;
+    return now + held * 1000;
   }
 
   /**