@torrent-tv/proxy 2.90.0 → 2.92.0

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));
     }
   }

package/services/viewer/SourcePreparation.js

@@ -0,0 +1,278 @@
+/** Source preparation is derived from viewers before any output exists. */
+export class SourcePreparation {
+  #viewers;
+  #candidates;
+  #related;
+  #priorityFor;
+  #inspect;
+  #withdraw;
+  #failed;
+  #reprice;
+  #inputReady;
+  #readyChanged;
+  #work = new Map();
+  #revision = 0;
+  #completedRevision = null;
+  #pending = null;
+  #candidateAbort = new AbortController();
+
+  constructor({ viewers, candidatesFor, relatedFilesFor = () => [], priorityFor = (_viewer, priority) => priority,
+    inputReady = async () => false, readyChanged = () => {}, inspect, withdraw, reprice = () => {}, failed }) {
+    this.#viewers = viewers;
+    this.#candidates = candidatesFor;
+    this.#related = relatedFilesFor;
+    this.#priorityFor = priorityFor;
+    this.#inspect = inspect;
+    this.#withdraw = withdraw;
+    this.#failed = failed;
+    this.#reprice = reprice;
+    this.#inputReady = inputReady;
+    this.#readyChanged = readyChanged;
+  }
+
+  refresh() {
+    this.#revision++;
+    this.#candidateAbort.abort();
+    this.#candidateAbort = new AbortController();
+    for (const [key, work] of this.#work) {
+      const demand = this.demandFor(work);
+      if (demand) { this.#reprice(work, demand); continue; }
+      this.#work.delete(key);
+      this.#withdraw(work);
+    }
+    if (!this.#pending) {
+      let succeeded = false;
+      this.#pending = this.#run().then(() => { succeeded = true; }).catch(error => this.#failed?.(error)).finally(() => {
+        this.#pending = null;
+        if (succeeded && this.#completedRevision !== this.#revision) void this.refresh();
+      });
+    }
+    return this.#pending;
+  }
+
+  /** Current owners determine priority; old work never restores a withdrawn read. */
+  demandFor(work) {
+    if (work.selected && work.statement === "packets" &&
+      work.positions !== this.#positionsFor(work.sourceKey, work.fileIndex, work.ownerId)) return null;
+    if (work.role === "subtitle-embedded" && ["packets", "subtitle-cues"].includes(work.statement) &&
+      work.positions !== this.#positionsFor(work.sourceKey, work.fileIndex, work.ownerId, true)) return null;
+    const owners = this.#viewers.forSource(work.sourceKey).filter(viewer => {
+      if (work.ownerId !== undefined && viewer.id !== work.ownerId) return false;
+      if (work.role === "subtitle-embedded" && (viewer.subtitle?.fileIndex !== work.fileIndex ||
+        viewer.subtitle.trackIndex !== work.trackIndex)) return false;
+      const selected = viewer.source.selectedFileIndex;
+      if (work.ownerFileIndex !== undefined) return selected === work.ownerFileIndex &&
+        (work.role !== "source-rest" || viewer.outputs.size === 0);
+      if (work.statement !== "packets") return selected === null || selected === work.fileIndex;
+      if (selected !== null) return selected === work.fileIndex && viewer.outputs.size === 0 && work.selected;
+      return !work.selected && viewer.source.visibleFileIndices.includes(work.fileIndex);
+    });
+    if (!owners.length) return null;
+    const selected = work.ownerFileIndex === undefined && owners.some(viewer => viewer.source.selectedFileIndex !== null);
+    const base = work.role === "source-rest" ? 1 : work.role === "next-episode" ? 5 : work.ownerFileIndex !== undefined ? 10 : 100;
+    const demands = owners.map(viewer => {
+      const chosenSubtitle = ["subtitle", "subtitle-embedded"].includes(work.role) && viewer.subtitle?.fileIndex === work.fileIndex;
+      const ownBase = chosenSubtitle ? 100 : base;
+      const priority = this.#priorityFor(viewer, ownBase, work);
+      return { priority, urgent: (selected || chosenSubtitle) && priority === ownBase };
+    });
+    const priority = Math.max(...demands.map(demand => demand.priority));
+    const urgent = demands.some(demand => demand.urgent);
+    return { priority,
+      urgent, deadlineAt: urgent ? 0 : Infinity, order: work.order ?? 0 };
+  }
+
+  accepts(work) { return this.#work.get(work.key) === work && this.demandFor(work) !== null; }
+
+  /** A retired torrent cannot retain completed preparation or accept late reads. */
+  forget(sourceKey) {
+    this.#revision++;
+    this.#candidateAbort.abort();
+    this.#candidateAbort = new AbortController();
+    for (const [key, work] of this.#work) {
+      if (work.sourceKey !== sourceKey) continue;
+      this.#work.delete(key);
+      this.#withdraw(work);
+    }
+  }
+
+  urgentReadyFor(viewer) {
+    if (!this.subtitleReadyFor(viewer)) return false;
+    return [...this.#work.values()].some(work => work.selected && work.ownerId === viewer.id &&
+      work.urgentReady === true && viewer.source?.sourceKey === work.sourceKey &&
+      viewer.source.selectedFileIndex === work.fileIndex && viewer.outputs.size === 0 &&
+      work.positions === this.#positionsFor(work.sourceKey, work.fileIndex, viewer.id));
+  }
+
+  subtitleReadyFor(viewer) {
+    const selection = viewer.subtitle;
+    if (!selection) return true;
+    return [...this.#work.values()].some(work => work.sourceKey === selection.sourceKey &&
+      work.fileIndex === selection.fileIndex && ["result", "terminal"].includes(work.result) &&
+      (selection.trackIndex === null ? work.statement === "subtitle-file" && work.ownerFileIndex === viewer.source.selectedFileIndex
+        : work.statement === "subtitle-cues" && work.ownerId === viewer.id && work.trackIndex === selection.trackIndex &&
+          work.positions === this.#positionsFor(work.sourceKey, work.fileIndex, viewer.id, true)));
+  }
+
+  async bytesChanged(sourceKey, fileIndex) {
+    let changed = false;
+    for (const work of this.#work.values()) {
+      if (!work.selected || work.sourceKey !== sourceKey || work.fileIndex !== fileIndex || !work.inputRanges) continue;
+      const revision = work.readinessRevision = (work.readinessRevision ?? 0) + 1;
+      const ready = await this.#inputReady(work);
+      if (revision !== work.readinessRevision || !this.accepts(work)) continue;
+      if (work.urgentReady !== ready) {
+        work.urgentReady = ready;
+        changed = true;
+        this.#readyChanged(work, ready);
+      }
+    }
+    if (changed) for (const work of this.#work.values()) {
+      const demand = this.demandFor(work);
+      if (demand) this.#reprice(work, demand);
+    }
+  }
+
+  ownsFile(sourceKey, fileIndex) {
+    return [...this.#work.values()].some(work => work.sourceKey === sourceKey &&
+      work.fileIndex === fileIndex && this.demandFor(work));
+  }
+
+  #positionsFor(sourceKey, fileIndex, ownerId, includeOutputs = false) {
+    return JSON.stringify(this.#viewers.forSource(sourceKey)
+      .filter(viewer => viewer.source.selectedFileIndex === fileIndex && (includeOutputs || viewer.outputs.size === 0) &&
+        (ownerId === undefined || viewer.id === ownerId))
+      .map(viewer => [viewer.id, viewer.position?.seconds ?? 0]).sort((left, right) => left[0].localeCompare(right[0])));
+  }
+
+  result(work, result) {
+    const current = this.#work.get(work.key);
+    if (current !== work || !this.demandFor(work)) return;
+    current.result = result.kind;
+    if (!["needs-ranges", "needs-memory"].includes(result.kind)) void this.refresh();
+  }
+
+  async #run() {
+    let revision;
+    do {
+      revision = this.#revision;
+      for (const sourceKey of this.#viewers.sourceKeys()) {
+        let candidates;
+        try { candidates = await this.#availableCandidates(sourceKey, this.#candidateAbort.signal); }
+        catch (error) {
+          if (error?.name === "AbortError") break;
+          throw error;
+        }
+        if (revision !== this.#revision) break;
+        const people = this.#viewers.forSource(sourceKey);
+        const selected = people.map(viewer => viewer.source.selectedFileIndex).filter(index => index !== null);
+        const files = [...new Set([...candidates, ...selected])];
+        const related = [...new Set(selected)].flatMap(ownerFileIndex =>
+          this.#related(sourceKey, ownerFileIndex).map(file => ({ ...file, ownerFileIndex })));
+        for (const viewer of people) {
+          if (viewer.subtitle?.trackIndex !== null && viewer.subtitle?.trackIndex !== undefined &&
+            viewer.subtitle.fileIndex === viewer.source.selectedFileIndex) {
+            related.push({ fileIndex: viewer.subtitle.fileIndex, ownerFileIndex: viewer.source.selectedFileIndex,
+              ownerId: viewer.id, trackIndex: viewer.subtitle.trackIndex, role: "subtitle-embedded" });
+          }
+        }
+        for (const [key, work] of this.#work) {
+          if (work.sourceKey === sourceKey && !files.includes(work.fileIndex) &&
+            !related.some(file => file.fileIndex === work.fileIndex && file.ownerFileIndex === work.ownerFileIndex)) {
+            this.#work.delete(key);
+            this.#withdraw(work);
+          }
+        }
+        const metadata = [];
+        for (const [order, fileIndex] of files.entries()) {
+          for (const statement of ["tracks", "media-info"]) {
+            if (revision !== this.#revision) break;
+            const work = this.#request({ sourceKey, fileIndex, statement, order });
+            if (!this.demandFor(work)) continue;
+            metadata.push(work);
+            await this.#read(work);
+          }
+        }
+        if (revision !== this.#revision || metadata.some(work => !["result", "terminal"].includes(work.result))) continue;
+        for (const [order, fileIndex] of files.entries()) {
+          if (revision !== this.#revision) break;
+          const selections = [{ selected: false }, ...people
+            .filter(viewer => viewer.source.selectedFileIndex === fileIndex && viewer.outputs.size === 0)
+            .map(viewer => ({ selected: true, ownerId: viewer.id }))];
+          for (const selection of selections) {
+            const work = this.#request({ sourceKey, fileIndex, statement: "packets", ...selection, order });
+            if (this.demandFor(work)) await this.#read(work);
+          }
+        }
+        for (const [order, file] of related.entries()) {
+          if (revision !== this.#revision) break;
+          if (file.role === "subtitle") {
+            await this.#read(this.#request({ sourceKey, ...file, statement: "subtitle-file", order: files.length + order }));
+            continue;
+          }
+          const declarations = [];
+          for (const statement of ["tracks", "media-info"]) {
+            const work = this.#request({ sourceKey, ...file, statement, order: files.length + order });
+            declarations.push(work);
+            await this.#read(work);
+          }
+          if (declarations.some(work => work.result !== "result")) continue;
+          const packets = this.#request({ sourceKey, ...file, statement: "packets", order: files.length + order });
+          await this.#read(packets);
+          if (file.role === "subtitle-embedded" && packets.result === "result") {
+            await this.#read(this.#request({ sourceKey, ...file, statement: "subtitle-cues", order: files.length + order }));
+          }
+        }
+      }
+    } while (revision !== this.#revision);
+    this.#completedRevision = revision;
+  }
+
+  #request(address) {
+    if (address.selected && address.statement === "packets") {
+      address = { ...address, positions: this.#positionsFor(address.sourceKey, address.fileIndex, address.ownerId) };
+    }
+    if (address.role === "subtitle-embedded" && ["packets", "subtitle-cues"].includes(address.statement)) {
+      address = { ...address, positions: this.#positionsFor(address.sourceKey, address.fileIndex, address.ownerId, true) };
+    }
+    const key = JSON.stringify([address.sourceKey, address.fileIndex, address.statement, address.selected ?? null,
+      address.ownerFileIndex ?? null, address.role ?? null, address.positions ?? null, address.ownerId ?? null, address.trackIndex ?? null]);
+    let work = this.#work.get(key);
+    if (work && work.order !== address.order) {
+      work.order = address.order;
+      const demand = this.demandFor(work);
+      if (demand) this.#reprice(work, demand);
+    }
+    if (!work) {
+      work = { ...address, key, requestId: `prepare:${key}`, result: null };
+      if (this.demandFor(work)) this.#work.set(key, work);
+    }
+    return work;
+  }
+
+  #availableCandidates(sourceKey, signal) {
+    return new Promise((resolve, reject) => {
+      let done = false;
+      const finish = (error, value) => {
+        if (done) return;
+        done = true;
+        signal.removeEventListener("abort", aborted);
+        if (error) reject(error); else resolve(value);
+      };
+      const aborted = () => finish(new DOMException("Source preparation was cancelled.", "AbortError"));
+      signal.addEventListener("abort", aborted, { once: true });
+      if (signal.aborted) { aborted(); return; }
+      Promise.resolve().then(() => {
+        if (signal.aborted) throw new DOMException("Source preparation was cancelled.", "AbortError");
+        return this.#candidates(sourceKey);
+      }).then(value => finish(null, value), error => finish(error));
+    });
+  }
+
+  async #read(work) {
+    if (work.result !== null || !this.demandFor(work)) return;
+    const result = await this.#inspect(work);
+    if (this.#work.get(work.key) === work && this.demandFor(work)) work.result = result.kind;
+    if (work.selected && work.inputRanges) await this.bytesChanged(work.sourceKey, work.fileIndex);
+  }
+}

package/services/viewer/Viewer.js

@@ -192,6 +192,8 @@ export class Viewer {
      * @type {Set<string>}
      */
     this.outputs = new Set();
+    /** Source selection exists before any prepared output. */
+    this.source = null;
     /**
      * Which output answers THIS viewer, and for how long that stands.
      *
@@ -225,6 +227,7 @@ export class Viewer {
      * @type {Set<string>}
      */
     this.wantsCuesFor = new Set();
+    this.subtitle = null;
     // WHETHER THE PICTURE IS MOVING, and separately WHETHER THIS VIEWER IS
     // BLOCKED ON US. Two booleans, because there are three states and one
     // boolean cannot hold them:
@@ -254,6 +257,8 @@ export class Viewer {
     // the instant they arrive, without the position ever being invented.
     this.playing = false;
     this.waiting = true;
+    /** When explicit paused state began; waiting for media is not a pause. */
+    this.pausedAt = null;
     // Whether the page carrying this viewer is ON SCREEN, and whether the
     // picture has been pulled out of it.
     //
@@ -312,6 +317,7 @@ export class Viewer {
       return;
     }
     this.#place(seconds, now);
+    if (this.pausedAt !== null) this.pausedAt = now;
     // The buffer's history belongs to the place they left.
     this.bufferReadings = [];
     // WHAT THEY HELD AT THE PLACE THEY LEFT SAYS NOTHING ABOUT THE PLACE THEY
@@ -475,6 +481,11 @@ export class Viewer {
     // material, which is the direction that costs an encoder rather than a
     // viewer.
     this.waiting = waiting === undefined ? this.playing === false && held === 0 : waiting === true;
+    if (!this.playing && !this.waiting) {
+      if (this.pausedAt === null) this.pausedAt = now;
+    } else {
+      this.pausedAt = null;
+    }
     this.inPictureInPicture = inPictureInPicture === undefined ? false : Boolean(inPictureInPicture);
     this.onScreen = onScreen === undefined ? true : Boolean(onScreen);
     this.seen(now);

package/services/viewer/Viewers.js

@@ -50,6 +50,79 @@ export class Viewers {
     this.#onChange = typeof onChange === "function" ? onChange : () => {};
   }
 
+  /** Register presence before source metadata or an output exists. */
+  present(consumerId, now = Date.now()) {
+    if (typeof consumerId !== "string" || !consumerId) throw new TypeError("A viewer needs a name.");
+    const known = this.#byId.get(consumerId);
+    const viewer = known ?? new Viewer(consumerId, now);
+    viewer.seen(now);
+    viewer.gone = false;
+    this.#byId.set(consumerId, viewer);
+    if (!known) this.#onChange();
+    return viewer;
+  }
+
+  /** Bind the same viewer to their source before metadata preparation. */
+  selectsSource(consumerId, sourceKey, now = Date.now()) {
+    if (typeof sourceKey !== "string" || !sourceKey) throw new TypeError("A selected source needs a key.");
+    const viewer = this.present(consumerId, now);
+    if (viewer.source?.sourceKey !== sourceKey) {
+      viewer.source = { sourceKey, visibleFileIndices: [], selectedFileIndex: null };
+      viewer.subtitle = null;
+      this.#onChange();
+    }
+    return viewer;
+  }
+
+  selectsFile(consumerId, sourceKey, fileIndex, now = Date.now(), selection = {}) {
+    if (!Number.isSafeInteger(fileIndex) || fileIndex < 0) throw new TypeError("A selected file needs its source index.");
+    const viewer = this.selectsSource(consumerId, sourceKey, now);
+    const changed = viewer.source.selectedFileIndex !== fileIndex;
+    if (changed) {
+      viewer.source.selectedFileIndex = fileIndex;
+      viewer.source.generation = 0;
+      viewer.subtitle = null;
+    }
+    if (changed || Number.isFinite(selection.positionSeconds)) viewer.moveTo(selection.positionSeconds ?? 0, now);
+    if (typeof selection.wantsToPlay === "boolean") {
+      viewer.playing = false;
+      viewer.waiting = selection.wantsToPlay;
+      viewer.pausedAt = selection.wantsToPlay ? null : viewer.pausedAt ?? now;
+    }
+    if (changed || Object.keys(selection).length) this.#onChange();
+    return viewer;
+  }
+
+  visibleFiles(consumerId, sourceKey, indices, now = Date.now()) {
+    if (!Array.isArray(indices) || indices.some(index => !Number.isSafeInteger(index) || index < 0)) {
+      throw new TypeError("Visible files need source indices.");
+    }
+    const viewer = this.selectsSource(consumerId, sourceKey, now);
+    const visible = [...new Set(indices)];
+    if (JSON.stringify(viewer.source.visibleFileIndices) !== JSON.stringify(visible)) {
+      viewer.source.visibleFileIndices = visible;
+      this.#onChange();
+    }
+    return viewer;
+  }
+
+  /** Accept a source report only while its original selection is still present. */
+  reportSource(consumerId, sourceKey, fileIndex, report, now = Date.now()) {
+    const viewer = this.get(consumerId);
+    if (!viewer || viewer.gone || viewer.outputs.size !== 0 ||
+        viewer.source?.sourceKey !== sourceKey || viewer.source.selectedFileIndex !== fileIndex) return false;
+    if (report.generation !== undefined) {
+      if (!Number.isSafeInteger(report.generation) || report.generation < (viewer.source.generation ?? 0)) return false;
+      viewer.source.generation = report.generation;
+    }
+    if (report.seek === true && Number.isFinite(report.positionSeconds) && report.positionSeconds >= 0) {
+      viewer.moveTo(report.positionSeconds, now);
+    }
+    viewer.report(report, now);
+    this.#onChange();
+    return true;
+  }
+
   /**
    * This viewer, watching this output.
    *
@@ -106,6 +179,15 @@ export class Viewers {
     return this.#byId.get(consumerId) ?? null;
   }
 
+  sourceKeys() {
+    return new Set([...this.#byId.values()].filter(viewer => viewer.isPresent() && viewer.source)
+      .map(viewer => viewer.source.sourceKey));
+  }
+
+  forSource(sourceKey) {
+    return [...this.#byId.values()].filter(viewer => viewer.isPresent() && viewer.source?.sourceKey === sourceKey);
+  }
+
   /**
    * A viewer of one output, without creating one.
    *
@@ -244,7 +326,7 @@ export class Viewers {
       return false;
     }
     viewer.outputs.delete(output.id);
-    if (viewer.outputs.size === 0) {
+    if (viewer.outputs.size === 0 && !viewer.source) {
       // Watching nothing at all: this is a statement that they are gone, and
       // not merely that this one output is no longer theirs.
       viewer.markGone();
@@ -287,7 +369,7 @@ export class Viewers {
     for (const [consumerId, viewer] of this.#byId) {
       if (!viewer.outputs.delete(outputId)) continue;
       if (viewer.activeVariantId === outputId) viewer.activeVariantId = null;
-      if (viewer.outputs.size === 0) {
+      if (viewer.outputs.size === 0 && !viewer.source) {
         viewer.markGone();
         this.#byId.delete(consumerId);
       }
@@ -334,6 +416,31 @@ export class Viewers {
     return true;
   }
 
+  /** Record the chosen subtitle without creating or restoring a viewer. */
+  selectsSubtitle(consumerId, sourceKey, fileIndex, trackIndex = null) {
+    const viewer = this.get(consumerId);
+    if (!viewer || viewer.gone || viewer.source?.sourceKey !== sourceKey ||
+      !Number.isSafeInteger(fileIndex) || fileIndex < 0 ||
+      (trackIndex !== null && (!Number.isSafeInteger(trackIndex) || trackIndex < 0))) return false;
+    if (trackIndex !== null && viewer.source.selectedFileIndex !== fileIndex) return false;
+    const selection = { sourceKey, fileIndex, trackIndex };
+    if (JSON.stringify(viewer.subtitle) !== JSON.stringify(selection)) {
+      viewer.subtitle = selection;
+      this.#onChange();
+    }
+    return true;
+  }
+
+  clearsSubtitle(consumerId, sourceKey) {
+    const viewer = this.get(consumerId);
+    if (!viewer || viewer.gone || viewer.source?.sourceKey !== sourceKey) return false;
+    if (viewer.subtitle !== null) {
+      viewer.subtitle = null;
+      this.#onChange();
+    }
+    return true;
+  }
+
   /**
    * Who has subtitles switched on for this file.
    *