@torrent-tv/proxy 2.91.0 → 2.92.0

package/services/viewer/DownloadMaps.js

@@ -0,0 +1,168 @@
+/** One published download map per file, including download-only metadata reads. */
+export class DownloadMaps {
+  #files = new Map();
+  #publish;
+  #resolvePlayback;
+  #nextEpoch = 0;
+
+  constructor({ publish, resolvePlayback = async map => map.zones }) {
+    if (typeof publish !== "function") throw new TypeError("Download map publication is required.");
+    this.#publish = publish;
+    this.#resolvePlayback = resolvePlayback;
+  }
+
+  async playback({ sourceKey, fileIndex, durationSeconds, zones }) {
+    const file = this.#file(sourceKey, fileIndex);
+    file.durationSeconds = durationSeconds;
+    const revision = ++file.revision;
+    const now = Date.now();
+    file.sourceZones = zones.map(zone => Number.isFinite(zone.deadlineAt) || !Number.isFinite(zone.withinSeconds)
+      ? zone : { ...zone, deadlineAt: now + Math.max(0, zone.withinSeconds) * 1000 });
+    let changed = false;
+    const retained = file.zones.flatMap(zone => {
+      const interval = zone.downloadInterval ?? zone;
+      const current = file.sourceZones.find(candidate => candidate.from === interval.from && candidate.to === interval.to);
+      const deadlineAt = current && Number.isFinite(current.deadlineAt)
+        ? current.deadlineAt - (zone.leadSeconds ?? 0) * 1000 : current?.deadlineAt;
+      if (!current || Object.keys(current).some(key => key !== "from" && key !== "to" && !Object.is(zone[key], key === "deadlineAt" ? deadlineAt : current[key]))) changed = true;
+      return current ? [{ ...zone, ...current, from: zone.from, to: zone.to, deadlineAt }] : [];
+    });
+    file.zones = retained;
+    for (const [statement, metadata] of file.metadata) {
+      if (metadata.interval && !this.wantsInterval(sourceKey, fileIndex, metadata.interval)) {
+        file.metadata.delete(statement);
+        changed = true;
+      }
+      else if (metadata.interval) {
+        const current = file.sourceZones.find(zone => zone.from === metadata.interval.from && zone.to === metadata.interval.to);
+        const deadlineAt = Number.isFinite(current.deadlineAt) ? current.deadlineAt - metadata.leadSeconds * 1000 : current.deadlineAt;
+        if (metadata.priority !== current.priority || metadata.urgent !== current.urgent || metadata.deadlineAt !== deadlineAt) changed = true;
+        metadata.priority = current.priority;
+        metadata.urgent = current.urgent;
+        metadata.deadlineAt = deadlineAt;
+      }
+    }
+    if (changed) await this.#emit(file);
+    if (revision !== file.revision) return;
+    const resolved = await this.#resolvePlayback({ sourceKey, fileIndex, durationSeconds, zones: file.sourceZones });
+    if (revision !== file.revision) return;
+    file.zones = resolved;
+    return this.#emit(file);
+  }
+
+  refresh(sourceKey, fileIndex) {
+    const file = this.#files.get(`${sourceKey}:${fileIndex}`);
+    if (!file) return Promise.resolve();
+    return this.playback({ sourceKey, fileIndex, durationSeconds: file.durationSeconds, zones: file.sourceZones });
+  }
+
+  epoch(sourceKey, fileIndex) {
+    return this.#files.get(`${sourceKey}:${fileIndex}`)?.epoch ?? 0;
+  }
+
+  native({ sourceKey, fileIndex, zones }) {
+    const file = this.#file(sourceKey, fileIndex);
+    file.nativeZones = zones;
+    return this.#emit(file);
+  }
+
+  wantsInterval(sourceKey, fileIndex, { from, to }) {
+    return this.#files.get(`${sourceKey}:${fileIndex}`)?.sourceZones.some(zone => zone.from === from && zone.to === to) ?? false;
+  }
+
+  /** Exact source ranges already resolved by the download map, without new reads. */
+  inputsForOutput(sourceKey, outputKey, index) {
+    const sources = [];
+    for (const file of this.#files.values()) {
+      if (file.sourceKey !== sourceKey) continue;
+      const zones = file.zones.filter(zone => zone.outputKey === outputKey && zone.index === index);
+      if (!zones.length) continue;
+      sources.push({ sourceId: `${sourceKey}:${file.fileIndex}`,
+        ranges: zones.map(zone => ({ start: zone.byteStart, end: zone.byteEnd + 1 })) });
+    }
+    return sources.length ? sources : null;
+  }
+
+  metadata({ sourceKey, fileIndex, statement, result, priority = 100, urgent = true, deadlineAt = 0, interval, leadSeconds = 0, scope = "playback", order = 0 }) {
+    if (!Number.isFinite(leadSeconds) || leadSeconds < 0) throw new TypeError("Metadata preparation time must be finite and nonnegative.");
+    const file = this.#file(sourceKey, fileIndex);
+    if (result.kind === "needs-ranges") {
+      if (interval && !this.wantsInterval(sourceKey, fileIndex, interval)) return Promise.resolve();
+      const current = interval && file.sourceZones.find(zone => zone.from === interval.from && zone.to === interval.to);
+      if (current) {
+        priority = current.priority;
+        urgent = current.urgent;
+        deadlineAt = Number.isFinite(current.deadlineAt) ? current.deadlineAt - leadSeconds * 1000 : current.deadlineAt;
+      }
+      file.metadata.set(statement, { ranges: result.ranges, requestId: result.requestId, priority, urgent, deadlineAt, interval, leadSeconds, scope, order });
+    } else {
+      file.metadata.delete(statement);
+    }
+    return this.#emit(file);
+  }
+
+  withdrawMetadata(sourceKey, fileIndex, statement) {
+    const file = this.#files.get(`${sourceKey}:${fileIndex}`);
+    return file?.metadata.delete(statement) ? this.#emit(file) : Promise.resolve();
+  }
+
+  repriceMetadata(sourceKey, fileIndex, statement, demand) {
+    const file = this.#files.get(`${sourceKey}:${fileIndex}`);
+    const metadata = file?.metadata.get(statement);
+    if (!metadata || Object.keys(demand).every(key => Object.is(metadata[key], demand[key]))) return Promise.resolve();
+    Object.assign(metadata, demand);
+    return this.#emit(file);
+  }
+
+  forget(sourceKey, fileIndex, { keepPreparation = false } = {}) {
+    const file = this.#file(sourceKey, fileIndex);
+    file.zones = [];
+    file.sourceZones = [];
+    if (!keepPreparation) file.nativeZones = [];
+    file.revision++;
+    file.epoch = ++this.#nextEpoch;
+    for (const [statement, metadata] of file.metadata) {
+      if (!keepPreparation || metadata.scope !== "preparation") file.metadata.delete(statement);
+    }
+    // Keep the publication sequence when the same file is requested again.
+    return this.#emit(file);
+  }
+
+  /** Closing a source discards its maps and cancels queued publications. */
+  retire(sourceKey) {
+    for (const [key, file] of this.#files) {
+      if (file.sourceKey !== sourceKey) continue;
+      file.revision++;
+      this.#files.delete(key);
+    }
+  }
+
+  #file(sourceKey, fileIndex) {
+    if (typeof sourceKey !== "string" || !sourceKey || !Number.isSafeInteger(fileIndex) || fileIndex < 0) {
+      throw new TypeError("A download map requires a source file address.");
+    }
+    const key = `${sourceKey}:${fileIndex}`;
+    let file = this.#files.get(key);
+    if (!file) {
+      file = { sourceKey, fileIndex, durationSeconds: 0, zones: [], nativeZones: [], sourceZones: [], revision: 0, epoch: ++this.#nextEpoch, metadata: new Map(), pending: Promise.resolve() };
+      this.#files.set(key, file);
+    }
+    return file;
+  }
+
+  #emit(file) {
+    const zones = [...file.zones, ...file.nativeZones];
+    for (const { ranges, requestId, priority, urgent, deadlineAt, order } of file.metadata.values()) {
+      for (const [byteStart, byteEnd] of ranges) {
+        zones.push({ byteStart, byteEnd, priority, urgent, downloadOnly: true, requestId, deadlineAt, ...(order ? { order } : {}) });
+      }
+    }
+    const publication = { sourceKey: file.sourceKey, fileIndex: file.fileIndex, durationSeconds: file.durationSeconds, zones };
+    const pending = file.pending.then(() => {
+      if (this.#files.get(`${file.sourceKey}:${file.fileIndex}`) === file) return this.#publish(publication);
+    });
+    // A failed publication must not prevent the next state change from being sent.
+    file.pending = pending.catch(() => undefined);
+    return pending;
+  }
+}

package/services/viewer/NativeSourceMap.js

@@ -0,0 +1,33 @@
+import { mapForViewer, mergeMaps, runsOf } from "./PriorityMap.js";
+
+/** Price native source packets with the same viewer map as encoded outputs. */
+export function nativeSourceMap({ index, tracks, viewers, durationSeconds, startTimeSeconds = 0,
+  allowanceSeconds, urgentReadyFor, now = Date.now() }) {
+  if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) return [];
+  const maps = viewers.map(viewer => mapForViewer({
+    atSeconds: viewer.positionSeconds(now) ?? 0, durationSeconds, allowanceSeconds,
+    playing: viewer.playing || viewer.waiting, viewerCount: viewers.length,
+    pauseSeconds: viewer.pausedAt === null ? 0 : (now - viewer.pausedAt) / 1000,
+    urgentReady: urgentReadyFor(viewer)
+  }));
+  const zones = [];
+  for (const zone of runsOf(mergeMaps(maps))) {
+    for (const track of tracks.filter(track => ["video", "audio"].includes(track.type))) {
+      const bounds = index.boundsOf(track.trackNumber);
+      if (!bounds) continue;
+      const from = Math.max(bounds.start, zone.from + startTimeSeconds);
+      const to = Math.min(bounds.end, durationSeconds + startTimeSeconds, zone.to + startTimeSeconds);
+      if (!(to > from)) continue;
+      const input = index.inputFor({ trackId: track.trackNumber, from, to });
+      if (input.kind === "needs-index") continue;
+      if (input.kind !== "result") throw new Error(`Native source input refused: ${input.reason}`);
+      const links = viewers.filter((_viewer, viewerIndex) => maps[viewerIndex].priority[zone.from] === zone.priority)
+        .map(viewer => viewer.linkReading()?.linkMbps).filter(rate => Number.isFinite(rate) && rate > 0);
+      const bytes = input.ranges.reduce((sum, [start, end]) => sum + end - start + 1, 0);
+      const deliverySeconds = links.length ? bytes * 8 / (Math.min(...links) * 1_000_000) : 0;
+      for (const [byteStart, byteEnd] of input.ranges) zones.push({ ...zone, byteStart, byteEnd,
+        deadlineAt: Number.isFinite(zone.withinSeconds) ? now + (zone.withinSeconds - deliverySeconds) * 1000 : Infinity });
+    }
+  }
+  return zones;
+}

package/services/viewer/PriorityMap.js

@@ -87,31 +87,14 @@
  */
 
 /**
- * THE SCALE. Three bands, and the order between them is the whole of what the
- * numbers claim.
- *
- * 1. IN FRONT OF SOMEBODY WHO IS WATCHING — the top value at the second they
- *    are about to see, falling as the film gets further from them;
- * 2. IN FRONT OF SOMEBODY WHO HAS STOPPED — the same shape, and every value of
- *    it below every value of band 1. A stopped viewer will watch this film when
- *    they press play, so it is still in front of them; nobody is waiting for it
- *    now, so it yields to anybody who is;
- * 3. BEHIND EVERYBODY — reachable only by a seek back, and nothing measures how
- *    likely that is, so it is one value rather than a shape.
- *
- * IN FRONT ALWAYS OUTRANKS BEHIND, at any distance and whoever is stopped. The
- * bands make that true by construction rather than by a comparison somebody has
- * to remember to write.
- *
- * The values inside a band are AN ENCODING OF AN ORDER, not a measurement:
- * every consumer asks only which of two seconds comes first, so any strictly
- * decreasing shape does the same work, and none of these numbers claims
- * anything about the world.
+ * Wanted seconds use priorities 1..100. Distance lowers priority relative to
+ * the measured urgent allowance. Pause preserves the same priorities until
+ * urgent outputs are ready. With competing viewers, elapsed pause time then
+ * attenuates the excess above 1 before maps merge. Zero means no demand.
+ * Direction, urgent preparation and attenuation are separate map fields;
+ * priority alone cannot distinguish an attenuated second from a passed one.
  */
 export const AT_A_WATCHING_VIEWER = 100;
-const WATCHING_FLOOR = 70;
-const AT_A_STOPPED_VIEWER = 69;
-const STOPPED_FLOOR = 39;
 
 /** Behind everybody. */
 export const NOBODY_IS_COMING = 1;
@@ -159,7 +142,7 @@ export function isAtAWatchingViewer(priority) {
  * @returns {boolean}
  */
 export function isNobodyComingNow(priority) {
-  return priority > NOBODY_IS_COMING && priority <= AT_A_STOPPED_VIEWER;
+  return priority === NOBODY_IS_COMING;
 }
 
 /**
@@ -197,7 +180,9 @@ export function emptyMap(durationSeconds) {
     durationSeconds: seconds,
     priority: new Uint8Array(seconds),
     secondsUntilPlayed: new Float64Array(seconds).fill(Number.POSITIVE_INFINITY),
-    behind: new Uint8Array(seconds).fill(1)
+    behind: new Uint8Array(seconds).fill(1),
+    urgent: new Uint8Array(seconds),
+    deferred: new Uint8Array(seconds)
   };
 }
 
@@ -209,11 +194,9 @@ export function emptyMap(durationSeconds) {
  * a clock time — is what the value is derived from, and it is why two viewers
  * can be compared at all: the nearer one wins the second they both want.
  *
- * **A pause removes the time, not the direction.** A stopped viewer is still
- * standing somewhere, and the film in front of them is still the film they will
- * watch, so their map keeps its shape and moves into the band below. Collapsed
- * to one flat value over the whole film, as it was, their position disappeared
- * entirely — and with it the rule that what is in front is made first.
+ * Pause retains urgent preparation first. Once that work is ready, the
+ * allowance / (allowance + pauseSeconds) coefficient gradually reduces this
+ * viewer's priorities if others consume the file. Resume restores them.
  *
  * **What must NOT be here**, and the boundary is the point: how fast this
  * machine encodes, how many encoders that takes, what a second weighs in bytes,
@@ -229,7 +212,15 @@ export function emptyMap(durationSeconds) {
  * @param {boolean} [params.playing] - Whether the picture is moving.
  * @returns {PriorityMap}
  */
-export function mapForViewer({ atSeconds, durationSeconds, allowanceSeconds, playing = true }) {
+export function pauseCoefficient({ playing, urgentReady, viewerCount, pauseSeconds, allowanceSeconds }) {
+  if (playing !== false || !urgentReady || viewerCount <= 1) return 1;
+  const allowance = Number.isFinite(allowanceSeconds) && allowanceSeconds > 0 ? allowanceSeconds : 1;
+  const elapsed = Number.isFinite(pauseSeconds) ? Math.max(0, pauseSeconds) : 0;
+  return allowance / (allowance + elapsed);
+}
+
+export function mapForViewer({ atSeconds, durationSeconds, allowanceSeconds, playing = true,
+  pauseSeconds = 0, urgentReady = false, viewerCount = 1 }) {
   const map = emptyMap(durationSeconds);
   if (map.durationSeconds === 0) {
     return map;
@@ -237,10 +228,13 @@ export function mapForViewer({ atSeconds, durationSeconds, allowanceSeconds, pla
   const at = Number.isFinite(atSeconds) && atSeconds > 0 ? Math.floor(atSeconds) : 0;
   const allowance = Number.isFinite(allowanceSeconds) && allowanceSeconds > 0
     ? allowanceSeconds
-    : 1;
+    : map.durationSeconds;
   const watching = playing !== false;
-  const top = watching ? AT_A_WATCHING_VIEWER : AT_A_STOPPED_VIEWER;
-  const floor = watching ? WATCHING_FLOOR : STOPPED_FLOOR;
+  // The measured urgent span is the time scale. There is no chosen decay
+  // period: one span on pause halves the excess above minimum priority.
+  const attenuate = !watching && urgentReady && viewerCount > 1;
+  const elapsed = Number.isFinite(pauseSeconds) ? Math.max(0, pauseSeconds) : 0;
+  const coefficient = pauseCoefficient({ playing, urgentReady, viewerCount, pauseSeconds: elapsed, allowanceSeconds: allowance });
   for (let second = 0; second < map.durationSeconds; second += 1) {
     if (second < at) {
       map.priority[second] = NOBODY_IS_COMING;
@@ -248,11 +242,13 @@ export function mapForViewer({ atSeconds, durationSeconds, allowanceSeconds, pla
     }
     map.behind[second] = 0;
     const distance = second - at;
-    map.priority[second] = Math.max(floor, top - stepsAway(distance, allowance));
-    // A viewer who has stopped is on their way nowhere, so there is no second by
-    // which any of this must exist. The direction survives the pause, in the
-    // priority above; the time does not, because there is none to state.
-    map.secondsUntilPlayed[second] = watching ? distance : Number.POSITIVE_INFINITY;
+    const priority = Math.max(NOBODY_IS_COMING, AT_A_WATCHING_VIEWER - stepsAway(distance, allowance));
+    map.priority[second] = Math.max(NOBODY_IS_COMING, 1 + Math.floor((priority - 1) * coefficient));
+    map.urgent[second] = distance < allowance && !attenuate ? 1 : 0;
+    map.deferred[second] = attenuate ? 1 : 0;
+    // Urgent preparation keeps its deadline during pause. After completion,
+    // pause duration defers this viewer's work without altering other viewers.
+    map.secondsUntilPlayed[second] = distance + (attenuate ? elapsed : 0);
   }
   return map;
 }
@@ -308,6 +304,7 @@ export function mergeMaps(maps) {
     return emptyMap(0);
   }
   const merged = emptyMap(Math.max(...all.map((map) => map.durationSeconds)));
+  merged.deferred.fill(1);
   for (const map of all) {
     for (let second = 0; second < map.durationSeconds; second += 1) {
       if (map.priority[second] > merged.priority[second]) {
@@ -321,8 +318,14 @@ export function mergeMaps(maps) {
       if (map.behind[second] === 0) {
         merged.behind[second] = 0;
       }
+      if (map.urgent?.[second]) merged.urgent[second] = 1;
+      // Deferred only if every viewer needing this second has yielded it.
+      if (map.behind[second] === 0 && !map.deferred?.[second]) merged.deferred[second] = 0;
     }
   }
+  for (let second = 0; second < merged.durationSeconds; second += 1) {
+    if (merged.behind[second]) merged.deferred[second] = 0;
+  }
   return merged;
 }
 
@@ -349,12 +352,16 @@ export function runsOf(map) {
       continue;
     }
     const behind = map.behind[second] === 1;
+    const urgent = map.urgent?.[second] === 1;
+    const deferred = map.deferred?.[second] === 1;
     const previous = runs[runs.length - 1];
     if (
       previous
       && previous.to === second
       && previous.priority === priority
       && previous.behind === behind
+      && previous.urgent === urgent
+      && previous.deferred === deferred
     ) {
       previous.to = second + 1;
       continue;
@@ -373,7 +380,9 @@ export function runsOf(map) {
       to: second + 1,
       priority,
       withinSeconds,
-      behind
+      behind,
+      urgent,
+      deferred
     });
   }
   return runs;

package/services/viewer/PriorityOrchestrator.js

@@ -16,7 +16,7 @@
  * append, and an empty picture for six minutes (field 2026-09-05).
  */
 
-import { emptyMap, mapForViewer, mergeMaps, runsOf } from "./PriorityMap.js";
+import { emptyMap, mapForViewer, mergeMaps, runsOf, pauseCoefficient } from "./PriorityMap.js";
 
 export class PriorityOrchestrator {
   /** Where the map goes once it is built. @type {(published: object) => void} */
@@ -66,6 +66,7 @@ export class PriorityOrchestrator {
   /** Whether this output is what that person is consuming, as opposed to one
    * they merely hold a record on. @type {(session: object, viewer: object) => boolean} */
   #watchedBy;
+  #urgentReadyFor;
 
   /**
    * Who watches an output is this component's own registry, handed in as the
@@ -85,7 +86,7 @@ export class PriorityOrchestrator {
    *   this layer does not know; absent, every registered viewer counts, and then
    *   the per-output map says the same as the per-file one.
    */
-  constructor({ publish, viewers, allowanceFor, watchedBy }) {
+  constructor({ publish, viewers, allowanceFor, watchedBy, urgentReadyFor }) {
     if (typeof viewers?.forOutput !== "function") {
       throw new TypeError("PriorityOrchestrator needs the viewer registry");
     }
@@ -93,6 +94,16 @@ export class PriorityOrchestrator {
     this.#viewers = viewers;
     this.#allowanceFor = typeof allowanceFor === "function" ? allowanceFor : () => 0;
     this.#watchedBy = typeof watchedBy === "function" ? watchedBy : () => true;
+    this.#urgentReadyFor = typeof urgentReadyFor === "function" ? urgentReadyFor : () => false;
+  }
+
+  /** Apply the viewer's same pause attenuation to related source preparation. */
+  priorityFor(session, viewer, priority, viewerCount, now = Date.now()) {
+    const allowanceSeconds = this.#allowanceFor(session);
+    const coefficient = pauseCoefficient({ playing: viewer.playing || viewer.waiting, viewerCount,
+      pauseSeconds: viewer.pausedAt === null ? 0 : (now - viewer.pausedAt) / 1000, allowanceSeconds,
+      urgentReady: viewer.pausedAt !== null && this.#urgentReadyFor(session, viewer, allowanceSeconds, now) });
+    return Math.max(1, 1 + Math.floor((priority - 1) * coefficient));
   }
 
   /**
@@ -110,17 +121,21 @@ export class PriorityOrchestrator {
    *   nobody is watching or the film's length is unknown, which says the same as
    *   a map with nothing in it.
    */
-  #mapFrom({ durationSeconds, allowanceSeconds, viewers }) {
+  #mapFrom({ durationSeconds, allowanceSeconds, viewers, viewerCount }) {
     if (!(durationSeconds > 0) || !(viewers?.length > 0)) {
       return emptyMap(0);
     }
+    const count = viewerCount ?? new Set(viewers.map((one, index) => one.id ?? index)).size;
     return mergeMaps(
       viewers.map((viewer) =>
         mapForViewer({
           atSeconds: viewer.atSeconds,
           durationSeconds,
           allowanceSeconds,
-          playing: viewer.playing !== false
+          playing: viewer.playing !== false,
+          pauseSeconds: viewer.pauseSeconds ?? 0,
+          urgentReady: viewer.urgentReady === true,
+          viewerCount: count
         })
       )
     );
@@ -139,7 +154,7 @@ export class PriorityOrchestrator {
    * @returns {import("./PriorityMap.js").PriorityMap} One number per second of
    *   film, merged over everyone watching it.
    */
-  build({ sourceKey, fileIndex, durationSeconds, allowanceSeconds, viewers }) {
+  build({ sourceKey, fileIndex, durationSeconds, allowanceSeconds, viewers, demandKey = null }) {
     const map = this.#mapFrom({ durationSeconds, allowanceSeconds, viewers });
     const key = `${sourceKey}:${fileIndex}`;
     this.#maps.set(key, map);
@@ -148,7 +163,7 @@ export class PriorityOrchestrator {
     // make it do that several times a second. Compared as stretches rather than
     // second by second, which is the same comparison over far fewer values.
     const zones = runsOf(map);
-    const shape = JSON.stringify(zones);
+    const shape = JSON.stringify({ zones, demandKey });
     if (this.#last.get(key)?.shape !== shape) {
       // The length is remembered with the shape, so that a file whose viewers
       // have all gone can still be spoken for: what is published then is the
@@ -196,7 +211,12 @@ export class PriorityOrchestrator {
     const byOutput = new Map();
     for (const sessions of sessionGroups) {
       for (const session of sessions) {
-        const key = `${session.sourceKey}:${session.fileIndex}`;
+        const sourceKey = session.file?.sourceKey;
+        const fileIndex = session.file?.fileIndex;
+        if (typeof sourceKey !== "string" || !sourceKey || !Number.isSafeInteger(fileIndex) || fileIndex < 0) {
+          throw new TypeError("A priority map requires its output file's source and file index.");
+        }
+        const key = `${sourceKey}:${fileIndex}`;
         const durationSeconds = Number(session.file?.durationSeconds) || 0;
         // The first band is as wide as an interruption this file has actually
         // shown on this swarm, never a chosen number.
@@ -204,11 +224,12 @@ export class PriorityOrchestrator {
         let held = byFile.get(key);
         if (!held) {
           held = {
-            sourceKey: session.sourceKey,
-            fileIndex: session.fileIndex,
+            sourceKey,
+            fileIndex,
             durationSeconds,
             allowanceSeconds,
-            viewers: []
+            viewers: [],
+            demandKey: []
           };
           byFile.set(key, held);
         }
@@ -219,15 +240,21 @@ export class PriorityOrchestrator {
         const address = session.outputKey ?? "";
         let mine = byOutput.get(address);
         if (!mine) {
-          mine = { durationSeconds, allowanceSeconds, viewers: [] };
+          mine = { durationSeconds, allowanceSeconds, viewers: [], fileKey: key };
           byOutput.set(address, mine);
         }
         for (const viewer of this.#viewers.forOutput(session).values()) {
           if (!viewer.isPresent()) {
             continue;
           }
+          held.demandKey.push([session.outputKey, viewer.id, viewer.audio?.trackIndex,
+            viewer.audio?.transcode, viewer.activeVariantId, viewer.warmingVariantId,
+            viewer.warmingAudioId, this.#watchedBy(session, viewer)]);
           const stated = {
+            id: viewer.id,
             atSeconds: viewer.positionSeconds(now) ?? 0,
+            pauseSeconds: viewer.pausedAt == null ? 0 : Math.max(0, (now - viewer.pausedAt) / 1000),
+            urgentReady: viewer.pausedAt != null && this.#urgentReadyFor(session, viewer, allowanceSeconds, now),
             // WATCHING OR WAITING, not merely playing. Three states reach this
             // one question: a viewer whose picture is advancing, a viewer
             // blocked on material we owe them, and a viewer who stopped it
@@ -236,9 +263,9 @@ export class PriorityOrchestrator {
             // on screen has its timers throttled and asks for nothing, which is
             // indistinguishable from a full cushion, so it is not consuming
             // either — told apart on the page, folded into one question here.
-            playing: typeof viewer.wantsFilmNow === "function"
+            playing: viewer.pausedAt == null && (typeof viewer.wantsFilmNow === "function"
               ? viewer.wantsFilmNow()
-              : viewer.playing === true || viewer.waiting === true
+              : viewer.playing === true || viewer.waiting === true)
           };
           held.viewers.push(stated);
           if (this.#watchedBy(session, viewer)) {
@@ -280,6 +307,8 @@ export class PriorityOrchestrator {
       }
     }
     for (const [address, one] of byOutput) {
+      // Competition is per file, even when two viewers use different outputs.
+      one.viewerCount = new Set((byFile.get(one.fileKey)?.viewers ?? []).map((viewer, index) => viewer.id ?? index)).size;
       this.#byOutput.set(address, this.#mapFrom(one));
     }
   }