@torrent-tv/proxy 2.101.28 → 2.101.30

package/package.json

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

package/routes/api/client-logs/post.js

@@ -91,14 +91,19 @@ export async function handleApiClientLogsPost(req, reply, { clientLogs, viewerRe
   }
   for (const row of rows) {
     const message = row && typeof row.msg === "string" ? row.msg : "";
-    const match = /^\[first-frame-observation\] consumer=([^ ]+) generation=(\d+) waitId=([^ ]+) wait=(\d+) audioReady=(true|false) elapsedMs=([\d.]+)$/.exec(message);
+    const match = /^\[first-frame-observation\] consumer=([^ ]+) generation=(\d+) waitId=([^ ]+) wait=(\d+) audioReady=(true|false) elapsedMs=([\d.]+)(?: coldStartTotalMs=([\d.]+) transportMs=([\d.]+) planMs=([\d.]+) prepareMs=([\d.]+) prebufferMs=([\d.]+) presentationMs=([\d.]+))?$/.exec(message);
     if (match) {
       const elapsedMs = Number(match[6]);
       if (match[1].length <= 64 && Number.isSafeInteger(Number(match[2])) && match[3].length <= 256 &&
           Number.isSafeInteger(Number(match[4])) && match[5] === "true" &&
           Number.isFinite(elapsedMs) && elapsedMs >= 0) {
+        const stageValues = match.slice(7).map(value => value === undefined ? null : Number(value));
+        const stages = stageValues.every(value => value !== null && Number.isFinite(value) && value >= 0)
+          ? { totalMs: stageValues[0], transportMs: stageValues[1], planMs: stageValues[2],
+            prepareMs: stageValues[3], prebufferMs: stageValues[4], presentationMs: stageValues[5] }
+          : null;
         viewerRequests?.noteFirstFrameObservation?.({ consumerId: match[1], generation: Number(match[2]),
-          waitId: match[3], wait: Number(match[4]), elapsedMs });
+          waitId: match[3], wait: Number(match[4]), elapsedMs, stages });
       }
     }
   }

package/routes/api/sources/files/get.js

@@ -77,13 +77,16 @@ export async function handleApiSourceFilesGet(req, reply, { sourceRegistry, torr
   const generation = generationRaw !== "" && /^\d+$/.test(generationRaw) ? Number(generationRaw) : null;
   const linkMbps = Number(req.query?.linkMbps);
   const linkSampleAgeMs = Number(req.query?.linkSampleAgeMs);
+  const waitElapsedMs = Number(req.query?.waitElapsedMs);
   const earlyLink = Number.isFinite(linkMbps) && linkMbps > 0
     ? { linkMbps, linkSampleAgeMs: Number.isFinite(linkSampleAgeMs) && linkSampleAgeMs >= 0 ? linkSampleAgeMs : null }
     : {};
+  const earlyWaitAge = Number.isFinite(waitElapsedMs) && waitElapsedMs >= 0 ? { waitElapsedMs } : {};
   const files = contents.files().map(file => {
     if (!consumerId || !Number.isSafeInteger(generation) || file.kind !== "video" || file.excludedReason) return file;
     const waitEstimate = viewerRequests?.waitEstimateForFile?.({ consumerId, generation, sourceKey,
-      fileIndex: file.fileIndex, fileName: file.relativePath ?? file.name, fileLength: file.length, ...earlyLink }) ?? null;
+      fileIndex: file.fileIndex, fileName: file.relativePath ?? file.name, fileLength: file.length,
+      ...earlyLink, ...earlyWaitAge }) ?? null;
     return waitEstimate ? { ...file, waitEstimate } : file;
   });
   return reply.send({

package/routes/api/sources/stats/get.js

@@ -39,12 +39,14 @@ export async function handleApiSourceStatsGet(req, reply, { sourceRegistry, torr
     ? Number(req.query.fileLength) : null;
   const linkMbps = Number(req.query.linkMbps);
   const linkSampleAgeMs = Number(req.query.linkSampleAgeMs);
+  const waitElapsedMs = Number(req.query.waitElapsedMs);
   const earlyLink = Number.isFinite(linkMbps) && linkMbps > 0
     ? { linkMbps, linkSampleAgeMs: Number.isFinite(linkSampleAgeMs) && linkSampleAgeMs >= 0 ? linkSampleAgeMs : null }
     : {};
+  const earlyWaitAge = Number.isFinite(waitElapsedMs) && waitElapsedMs >= 0 ? { waitElapsedMs } : {};
   const initialEstimate = () => consumerId && Number.isSafeInteger(generation) && Number.isSafeInteger(fileIndex)
     ? viewerRequests?.waitEstimateForFile?.({ consumerId, generation, sourceKey, fileIndex,
-      fileName: requestedFileName, fileLength: requestedFileLength, ...earlyLink }) ?? null
+      fileName: requestedFileName, fileLength: requestedFileLength, ...earlyLink, ...earlyWaitAge }) ?? null
     : null;
 
   let torrent;
@@ -142,7 +144,8 @@ export async function handleApiSourceStatsGet(req, reply, { sourceRegistry, torr
 
   const waitEstimate = consumerId && Number.isSafeInteger(generation)
     ? viewerRequests?.waitEstimateForSource?.({ consumerId, generation, sourceKey, fileIndex,
-      fileName: torrent.files?.[fileIndex]?.name ?? requestedFileName, fileLength: requestedFileLength, stats, ...earlyLink }) ?? null
+      fileName: torrent.files?.[fileIndex]?.name ?? requestedFileName, fileLength: requestedFileLength,
+      stats, ...earlyLink, ...earlyWaitAge }) ?? null
     : null;
   return reply.send(waitEstimate ? { ...stats, waitEstimate } : stats);
 }

package/services/encode/LocalObservations.js

@@ -6,7 +6,7 @@
  * NOT A TABLE OF QUALITY, and not a condition for anything. The proxy selects,
  * admits and serves with nothing kept here at all: the startup calibration is
  * what qualifies a mode and prices it, and the admission is what decides
- * whether there is room. What is kept here makes three of those figures more
+ * whether there is room. What is kept here makes four of those figures more
  * exact on THIS machine once it has done the work for real:
  *
  * 1. how fast an encode of this mode, at this size, actually ran alone on this
@@ -19,6 +19,9 @@
  * 3. how long an output of this mode took to have the piece a viewer needed
  *    after it was asked for, and what that viewer held when they moved — used
  *    as the time to ready when deciding whether a draining buffer is a threat.
+ * 4. the measured transport, track-plan, output-preparation, prebuffer and
+ *    first-presented-frame stages for an earlier start on this proxy
+ *    configuration, used as separate inputs to an early wait forecast.
  *
  * WHAT IS NEVER KEPT: a picture, a clip, a segment, anything about a viewer
  * beyond the seconds they held, and anything that leaves this machine.
@@ -59,6 +62,7 @@ export const PROXY_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url))
  * figure follows the host as it changes.
  */
 const READINGS_KEPT = 20;
+const FIRST_FRAME_CATEGORICAL = new Set(["fileAvailable", "videoOperation", "audioOperation"]);
 
 /** The version of the file's shape; a file of another shape is not read. */
 const FILE_VERSION = 1;
@@ -264,27 +268,21 @@ export class LocalObservations {
   }
 
   /**
-   * Keep a browser-measured wait outcome with the source and link readings
-   * visible before the container was inspected. These readings are useful
-   * only on the encoder configurations present on this host.
+   * The viewer presented its first audio-ready frame: keep the separately
+   * measured stage timings and the input snapshots from the start of that run.
    *
-   * @param {{ seconds: number, features: object }} params
+   * @param {{ seconds: number, features: object, featureSnapshots?: object[], stages?: object | null }} params
    * @returns {void}
    */
-  noteFirstFrame({ seconds, features }) {
+  noteFirstFrame({ seconds, features, featureSnapshots = null, stages = null }) {
     if (!Number.isFinite(seconds) || seconds < 0 || !features || typeof features !== "object") return;
     const key = this.#firstFrameKey();
+    const snapshots = [features, ...(Array.isArray(featureSnapshots) ? featureSnapshots : [])]
+      .filter(value => value && typeof value === "object").slice(0, 2).map(firstFrameFeatures);
     const readings = [...(this.#entries.firstFrame[key] ?? []), {
-      seconds,
-      extension: typeof features.extension === "string" ? features.extension : "",
-      fileLength: positive(features.fileLength),
-      downloadSpeed: nonNegative(features.downloadSpeed),
-      linkMbps: nonNegative(features.linkMbps),
-      linkSampleAgeMs: nonNegative(features.linkSampleAgeMs),
-      preparedOutputBytes: nonNegative(features.preparedOutputBytes),
-      fileAvailable: typeof features.fileAvailable === "boolean" ? features.fileAvailable : null,
-      headerRemaining: nonNegative(features.headerRemaining),
-      peers: nonNegative(features.peers),
+      ...snapshots[0],
+      featureSnapshots: snapshots,
+      stages: stagesOf(stages),
       at: this.#now()
     }].slice(-READINGS_KEPT);
     this.#entries.firstFrame[key] = readings;
@@ -292,60 +290,86 @@ export class LocalObservations {
   }
 
   /**
-   * Predict this host's first-frame wait from the closest measured start with
-   * the same media suffix. Distance uses squared log-ratios for numeric
-   * inputs and exact-state distance for categorical inputs; it does not mix
-   * bytes, bit rates and peers in their raw units. Missing data contributes
-   * distance only when the other observation measured that input.
+   * Predict the first-frame wait as the sum of separately predicted cold-start
+   * stages. Each stage uses all compatible measurements, weighted by the
+   * normalized distance between the measured inputs; no complete past wait is
+   * returned as the forecast. A known cache/source state must also be known in
+   * the training observation, otherwise that observation is not comparable.
    *
    * @param {object} features
    * @returns {number | null}
    */
   firstFrameSeconds(features) {
     if (!features || typeof features !== "object") return null;
-    const readings = this.#entries.firstFrame[this.#firstFrameKey()] ?? [];
-    const candidates = readings.filter(reading => reading.extension === (features.extension ?? ""));
+    const candidates = (this.#entries.firstFrame[this.#firstFrameKey()] ?? [])
+      .filter(reading => reading.extension === (features.extension ?? "") && reading.stages);
     if (candidates.length === 0) return null;
     const dimensions = ["fileLength", "downloadSpeed", "linkMbps", "linkSampleAgeMs", "preparedOutputBytes",
-      "fileAvailable", "headerRemaining", "peers"];
-    const scales = new Map(dimensions.map(key => [key, median(candidates
-      .map(reading => key === "fileAvailable" ? null : nonNegative(reading[key]))
+      "fileAvailable", "headerRemaining", "peers", "videoOperation", "audioOperation", "videoSpeedX", "audioSpeedX"];
+    const pointsOf = reading => Array.isArray(reading.featureSnapshots) && reading.featureSnapshots.length > 0
+      ? reading.featureSnapshots : [reading];
+    const scales = new Map(dimensions.map(key => [key, median(candidates.flatMap(reading => pointsOf(reading)
+      .map(point => FIRST_FRAME_CATEGORICAL.has(key) ? null : nonNegative(point[key])))
       .filter(value => value !== null && value > 0))]));
-    let best = null;
+    const distances = [];
     for (const reading of candidates) {
-      let distance = 0;
-      let used = 0;
-      let shared = 0;
-      for (const key of dimensions) {
-        const current = key === "fileAvailable"
-          ? (typeof features[key] === "boolean" ? features[key] : null)
-          : nonNegative(features[key]);
-        const previous = key === "fileAvailable"
-          ? (typeof reading[key] === "boolean" ? reading[key] : null)
-          : nonNegative(reading[key]);
-        if (current === null && previous === null) continue;
-        if (current === null || previous === null) {
-          distance += 1;
+      let bestDistance = null;
+      for (const point of pointsOf(reading)) {
+        if ((features.preparedOutputBytes !== null && features.preparedOutputBytes !== undefined &&
+            point.preparedOutputBytes === null) ||
+            [...FIRST_FRAME_CATEGORICAL].some(key => {
+              const current = key === "fileAvailable" ? features[key] : operationOf(features[key]);
+              return current !== null && current !== undefined && point[key] !== current;
+            })) continue;
+        let distance = 0;
+        let used = 0;
+        let shared = 0;
+        for (const key of dimensions) {
+          const current = FIRST_FRAME_CATEGORICAL.has(key)
+            ? key === "fileAvailable" ? (typeof features[key] === "boolean" ? features[key] : null)
+              : operationOf(features[key])
+            : nonNegative(features[key]);
+          const previous = FIRST_FRAME_CATEGORICAL.has(key)
+            ? key === "fileAvailable" ? (typeof point[key] === "boolean" ? point[key] : null)
+              : operationOf(point[key])
+            : nonNegative(point[key]);
+          if (current === null && previous === null) continue;
+          if (current === null || previous === null) {
+            distance += 1;
+            used += 1;
+            continue;
+          }
+          shared += 1;
+          const scale = scales.get(key);
+          const difference = typeof current !== "number" && typeof previous !== "number"
+            ? Number(current !== previous)
+            : scale === null
+              ? Number(current !== previous)
+              : Math.log1p(current / scale) - Math.log1p(previous / scale);
+          distance += difference * difference;
           used += 1;
-          continue;
         }
-        shared += 1;
-        const scale = scales.get(key);
-        const difference = typeof current === "boolean" && typeof previous === "boolean"
-          ? Number(current !== previous)
-          : scale === null
-            ? Number(current !== previous)
-            : Math.log1p(current / scale) - Math.log1p(previous / scale);
-        distance += difference * difference;
-        used += 1;
-      }
-      if (used === 0 || shared === 0) continue;
-      distance /= used;
-      if (!best || distance < best.distance || (distance === best.distance && reading.at > best.reading.at)) {
-        best = { distance, reading };
+        if (used === 0 || shared === 0) continue;
+        distance /= used;
+        if (bestDistance === null || distance < bestDistance) bestDistance = distance;
       }
+      if (bestDistance !== null) distances.push({ distance: bestDistance, reading });
     }
-    return best?.reading.seconds ?? null;
+    if (distances.length === 0) return null;
+    const exact = distances.filter(candidate => candidate.distance === 0);
+    const weighted = exact.length > 0
+      ? exact.map(candidate => ({ ...candidate, weight: 1 }))
+      : distances.map(candidate => ({ ...candidate, weight: 1 / candidate.distance }));
+    const stages = ["transportMs", "planMs", "prepareMs", "prebufferMs", "presentationMs"];
+    const predicted = stages.map(stage => {
+      const applicable = weighted.filter(candidate => Number.isFinite(candidate.reading.stages[stage]));
+      const totalWeight = applicable.reduce((sum, candidate) => sum + candidate.weight, 0);
+      return totalWeight > 0
+        ? applicable.reduce((sum, candidate) => sum + candidate.reading.stages[stage] * candidate.weight, 0) / totalWeight
+        : null;
+    });
+    if (predicted.some(value => value === null)) return null;
+    return predicted.reduce((sum, value) => sum + value, 0) / 1000;
   }
 
   #firstFrameKey() {
@@ -458,6 +482,38 @@ function nonNegative(value) {
   return Number.isFinite(number) && number >= 0 ? number : null;
 }
 
+/** @param {unknown} value @returns {"copy" | "encode" | null} */
+function operationOf(value) {
+  return value === "copy" || value === "encode" ? value : null;
+}
+
+/** @param {unknown} value @returns {{ totalMs: number, transportMs: number, planMs: number, prepareMs: number, prebufferMs: number, presentationMs: number } | null} */
+function stagesOf(value) {
+  if (!value || typeof value !== "object") return null;
+  const keys = ["totalMs", "transportMs", "planMs", "prepareMs", "prebufferMs", "presentationMs"];
+  const stages = Object.fromEntries(keys.map(key => [key, nonNegative(value[key])]));
+  return keys.every(key => stages[key] !== null) ? stages : null;
+}
+
+/** @param {object} features @returns {object} */
+function firstFrameFeatures(features) {
+  return {
+    extension: typeof features.extension === "string" ? features.extension : "",
+    fileLength: positive(features.fileLength),
+    downloadSpeed: nonNegative(features.downloadSpeed),
+    linkMbps: nonNegative(features.linkMbps),
+    linkSampleAgeMs: nonNegative(features.linkSampleAgeMs),
+    preparedOutputBytes: nonNegative(features.preparedOutputBytes),
+    fileAvailable: typeof features.fileAvailable === "boolean" ? features.fileAvailable : null,
+    headerRemaining: nonNegative(features.headerRemaining),
+    peers: nonNegative(features.peers),
+    videoOperation: operationOf(features.videoOperation),
+    audioOperation: operationOf(features.audioOperation),
+    videoSpeedX: nonNegative(features.videoSpeedX),
+    audioSpeedX: nonNegative(features.audioSpeedX)
+  };
+}
+
 /** @param {number[]} values @returns {number | null} */
 function median(values) {
   if (values.length === 0) return null;

package/services/server/ViewerRequests.js

@@ -8,7 +8,7 @@
  */
 
 import { logger } from "../../utils/logger.js";
-import { isOutputName } from "../encode/output/index.js";
+import { isOutputName, OutputSpec } from "../encode/output/index.js";
 import { withSubtitleReadiness } from "./subtitle-readiness.js";
 
 function isWarmupTimeoutError(error) {
@@ -106,19 +106,20 @@ export class ViewerRequests {
    * @param {{ consumerId: string, generation: number, sourceKey: string, fileIndex: number, fileName: string, fileLength: number }} params
    * @returns {object | null}
    */
-  waitEstimateForFile({ consumerId, generation, sourceKey, fileIndex, fileName, fileLength, linkMbps, linkSampleAgeMs }) {
+  waitEstimateForFile({ consumerId, generation, sourceKey, fileIndex, fileName, fileLength, linkMbps, linkSampleAgeMs,
+    waitElapsedMs }) {
     if (!consumerId || !Number.isSafeInteger(generation) || typeof sourceKey !== "string" ||
         !Number.isSafeInteger(fileIndex) || fileIndex < 0) return null;
     const waitId = `${sourceKey}:${fileIndex}:${generation}`;
     const key = `${consumerId}:${waitId}`;
     const extension = typeof fileName === "string" ? fileName.split(".").at(-1)?.toLowerCase() ?? "" : "";
+    const link = linkMeasurementOf(this.#host.viewers.get(consumerId), linkMbps, linkSampleAgeMs);
     const features = {
       extension,
       fileLength,
       downloadSpeed: null,
-      linkMbps: Number.isFinite(linkMbps) && linkMbps > 0
-        ? linkMbps : this.#host.viewers.get(consumerId)?.linkReading()?.linkMbps,
-      linkSampleAgeMs: Number.isFinite(linkSampleAgeMs) && linkSampleAgeMs >= 0 ? linkSampleAgeMs : null,
+      linkMbps: link.mbps,
+      linkSampleAgeMs: link.ageMs,
       preparedOutputBytes: this.#preparedOutputBytes(sourceKey, fileIndex),
       fileAvailable: null,
       headerRemaining: null,
@@ -126,19 +127,27 @@ export class ViewerRequests {
     };
     const current = this.#earlyWaits.get(key);
     if (current?.waitId === waitId && current.hasSourceObservation) {
-      const seconds = this.#host.firstFrameSecondsOf?.(current.features) ?? null;
+      const context = this.#setEarlyWait({ consumerId, generation, fileIndex, waitId, features,
+        revision: current.revision, current, waitElapsedMs });
+      const changed = this.#recordEarlyWaitSnapshot(context, context.features);
+      if (changed) context.revision += 1;
+      this.#pruneEarlyWaits();
+      const totalSeconds = this.#host.firstFrameSecondsOf?.(context.features) ?? null;
+      const seconds = earlyWaitRemainingSeconds(totalSeconds, waitElapsedSince(context, waitElapsedMs));
       if (!Number.isFinite(seconds) || seconds < 0) return null;
-      return { version: 1, waitId, revision: current.revision, remainingSeconds: seconds, ageMs: 0 };
+      return { version: 1, waitId, revision: context.revision, remainingSeconds: seconds, ageMs: 0 };
     }
     const sameWait = current?.waitId === waitId;
     const revision = sameWait ? current.revision : 0;
-    const context = this.#setEarlyWait({ consumerId, generation, fileIndex, waitId, features, revision, current });
-    const changed = this.#recordEarlyWaitSnapshot(context, features);
+    const context = this.#setEarlyWait({ consumerId, generation, fileIndex, waitId, features, revision, current,
+      waitElapsedMs });
+    const changed = this.#recordEarlyWaitSnapshot(context, context.features);
     if (sameWait && changed) context.revision += 1;
     this.#pruneEarlyWaits();
-    const seconds = this.#host.firstFrameSecondsOf?.(features) ?? null;
+    const totalSeconds = this.#host.firstFrameSecondsOf?.(context.features) ?? null;
+    const seconds = earlyWaitRemainingSeconds(totalSeconds, waitElapsedSince(context, waitElapsedMs));
     if (!Number.isFinite(seconds) || seconds < 0) return null;
-    return { version: 1, waitId, revision, remainingSeconds: seconds, ageMs: 0 };
+    return { version: 1, waitId, revision: context.revision, remainingSeconds: seconds, ageMs: 0 };
   }
 
   /**
@@ -149,35 +158,45 @@ export class ViewerRequests {
    * @returns {object | null}
    */
   waitEstimateForSource({ consumerId, generation, sourceKey, fileIndex, fileName = "", fileLength = null,
-    stats = {}, linkMbps, linkSampleAgeMs }) {
+    stats = {}, linkMbps, linkSampleAgeMs, waitElapsedMs, processing = {} }) {
     if (!consumerId || !Number.isSafeInteger(generation) || typeof sourceKey !== "string") return null;
     const waitId = `${sourceKey}:${fileIndex ?? "all"}:${generation}`;
     const key = `${consumerId}:${waitId}`;
     const extension = typeof fileName === "string" ? fileName.split(".").at(-1)?.toLowerCase() ?? "" : "";
+    const link = linkMeasurementOf(this.#host.viewers.get(consumerId), linkMbps, linkSampleAgeMs);
     const features = {
       extension,
       fileLength: Number.isFinite(stats?.fileLength) && stats.fileLength > 0
         ? stats.fileLength : fileLength,
       downloadSpeed: stats?.downloadSpeed,
-      linkMbps: Number.isFinite(linkMbps) && linkMbps > 0
-        ? linkMbps : this.#host.viewers.get(consumerId)?.linkReading()?.linkMbps,
-      linkSampleAgeMs: Number.isFinite(linkSampleAgeMs) && linkSampleAgeMs >= 0 ? linkSampleAgeMs : null,
+      linkMbps: link.mbps,
+      linkSampleAgeMs: link.ageMs,
       preparedOutputBytes: Number.isSafeInteger(fileIndex) && fileIndex >= 0
         ? this.#preparedOutputBytes(sourceKey, fileIndex) : null,
       fileAvailable: typeof stats?.fileAvailable === "boolean" ? stats.fileAvailable : null,
       headerRemaining: Number.isFinite(stats?.headerBytes) && Number.isFinite(stats?.headerDownloadedBytes)
         ? Math.max(0, stats.headerBytes - stats.headerDownloadedBytes) : null,
-      peers: stats?.connectedPeers ?? stats?.numPeers
+      peers: stats?.connectedPeers ?? stats?.numPeers,
+      videoOperation: processing.videoOperation ?? null,
+      audioOperation: processing.audioOperation ?? null,
+      videoSpeedX: processing.videoSpeedX ?? null,
+      audioSpeedX: processing.audioSpeedX ?? null
     };
     const current = this.#earlyWaits.get(key);
-    const revision = current?.waitId === waitId ? current.revision + 1 : 0;
+    const sameWait = current?.waitId === waitId;
+    const revision = sameWait ? current.revision : 0;
     const context = this.#setEarlyWait({ consumerId, generation, fileIndex, waitId, features, revision, current,
-      sourceObserved: true });
-    this.#recordEarlyWaitSnapshot(context, features);
+      sourceObserved: true, waitElapsedMs });
+    const changed = this.#recordEarlyWaitSnapshot(context, context.features);
+    if (sameWait && changed) context.revision += 1;
     this.#pruneEarlyWaits();
-    const seconds = this.#host.firstFrameSecondsOf?.(features) ?? null;
+    const measuredWorkSeconds = processing.firstRequiredSegmentsSeconds;
+    const totalSeconds = Number.isFinite(measuredWorkSeconds) && measuredWorkSeconds >= 0
+      ? waitElapsedSince(context, waitElapsedMs) / 1000 + measuredWorkSeconds
+      : this.#host.firstFrameSecondsOf?.(context.features) ?? null;
+    const seconds = earlyWaitRemainingSeconds(totalSeconds, waitElapsedSince(context, waitElapsedMs));
     if (!Number.isFinite(seconds) || seconds < 0) return null;
-    return { version: 1, waitId, revision, remainingSeconds: seconds, ageMs: 0 };
+    return { version: 1, waitId, revision: context.revision, remainingSeconds: seconds, ageMs: 0 };
   }
 
   /**
@@ -185,22 +204,27 @@ export class ViewerRequests {
    * viewing. The saved source and link readings are the ones available at
    * selection time, before the full track plan existed.
    *
-   * @param {{ consumerId: string, generation: number, waitId: string, wait: number, elapsedMs: number }} params
+   * @param {{ consumerId: string, generation: number, waitId: string, wait: number, elapsedMs: number,
+   *   stages?: { totalMs: number, transportMs: number, planMs: number, prepareMs: number,
+   *     prebufferMs: number, presentationMs: number } | null }} params
    * @returns {void}
    */
-  noteFirstFrameObservation({ consumerId, generation, waitId, wait, elapsedMs }) {
+  noteFirstFrameObservation({ consumerId, generation, waitId, wait, elapsedMs, stages = null }) {
     const key = `${consumerId}:${waitId}`;
     const early = this.#earlyWaits.get(key);
     if (!early || early.generation !== generation || !Number.isSafeInteger(wait) || wait < 0 || early.observedWaits.has(wait) ||
         !Number.isFinite(elapsedMs) || elapsedMs < 0) return;
-    for (const snapshot of early.snapshots) {
-      this.#host.noteFirstFrame?.({ seconds: elapsedMs / 1000, features: snapshot });
+    const initialFeatures = early.snapshots[0];
+    if (initialFeatures) {
+      this.#host.noteFirstFrame?.({ seconds: elapsedMs / 1000, features: initialFeatures,
+        featureSnapshots: early.snapshots.slice(1), stages });
     }
     early.observedWaits.add(wait);
     early.updatedAt = Date.now();
   }
 
-  #setEarlyWait({ consumerId, generation, fileIndex, waitId, features, revision, current, sourceObserved = false }) {
+  #setEarlyWait({ consumerId, generation, fileIndex, waitId, features, revision, current,
+    sourceObserved = false, waitElapsedMs }) {
     const sameWait = current?.waitId === waitId;
     const context = sameWait ? current : {
       consumerId,
@@ -211,7 +235,17 @@ export class ViewerRequests {
       hasSourceObservation: false,
       observedWaits: new Set()
     };
-    Object.assign(context, { consumerId, generation, fileIndex, waitId, features, updatedAt: Date.now(), revision,
+    const measuredAt = performance.now();
+    const actionElapsedMs = Number.isFinite(waitElapsedMs) && waitElapsedMs >= 0 ? waitElapsedMs : null;
+    const startedAt = actionElapsedMs === null
+      ? Number.isFinite(context.startedAt) ? context.startedAt : measuredAt
+      : measuredAt - actionElapsedMs;
+    const ageElapsedMs = Number.isFinite(context.featuresMeasuredAt)
+      ? Math.max(0, measuredAt - context.featuresMeasuredAt)
+      : 0;
+    const mergedFeatures = mergeWaitFeatures(context.features, features, ageElapsedMs);
+    Object.assign(context, { consumerId, generation, fileIndex, waitId, features: mergedFeatures,
+      featuresMeasuredAt: measuredAt, startedAt, updatedAt: Date.now(), revision,
       hasSourceObservation: context.hasSourceObservation || sourceObserved });
     this.#earlyWaits.set(`${consumerId}:${waitId}`, context);
     return context;
@@ -232,11 +266,21 @@ export class ViewerRequests {
     if (!outputs?.values || !segmentStore?.sizesOf) return null;
     let bytes = 0;
     const seen = new Set();
-    for (const output of outputs.values()) {
-      if (output.file?.sourceKey !== sourceKey || output.file?.fileIndex !== fileIndex || !output.outputKey) continue;
-      if (seen.has(output.outputKey)) continue;
-      seen.add(output.outputKey);
-      for (const size of segmentStore.sizesOf(output.outputKey).values()) {
+    const liveOutputs = [...outputs.values()];
+    const keys = new Set([
+      ...liveOutputs.map(output => output.outputKey),
+      ...(segmentStore.addresses?.() ?? [])
+    ].filter(key => typeof key === "string" && key.length > 0));
+    for (const outputKey of keys) {
+      const output = liveOutputs.find(candidate => candidate.outputKey === outputKey);
+      const spec = output ? null : OutputSpec.fromKey(outputKey);
+      const matchesFile = output
+        ? output.file?.sourceKey === sourceKey && output.file?.fileIndex === fileIndex
+        : spec?.sourceKey === sourceKey &&
+          (spec.video?.fileIndex === fileIndex || spec.audio?.fileIndex === fileIndex);
+      if (!matchesFile || seen.has(outputKey)) continue;
+      seen.add(outputKey);
+      for (const size of segmentStore.sizesOf(outputKey).values()) {
         if (Number.isFinite(size) && size > 0) bytes += size;
       }
     }
@@ -768,6 +812,7 @@ export class ViewerRequests {
 
     const sourceMeasurements = new Map();
     const sourceForecasts = new Map();
+    let primarySourceStats = null;
     const tracks = [];
     for (const output of outputs) {
       const trackProgress = output === session ? progress : this.#host.encodeRuns.progressOf(output);
@@ -803,6 +848,7 @@ export class ViewerRequests {
         } catch {
           stats = null;
         }
+        if (output === session && fileIndex === session.file.fileIndex) primarySourceStats = stats;
         parts.statsMs += performance.now() - statsAt;
         parts.workerForecastMs += Number(stats?.forecastMs) || 0;
         if (!sourceForecasts.has(output.file.sourceKey)) sourceForecasts.set(output.file.sourceKey, stats?.downloadForecast ?? { ranges: [] });
@@ -929,6 +975,29 @@ export class ViewerRequests {
           outputCodec: output.spec.audio.transcode ? "aac" : null }] : [])
       ];
     });
+    const generation = consumerId && viewer?.assignments
+      ? this.#host.generationOfRequest(consumerId) : null;
+    const earlyWaitId = Number.isSafeInteger(generation)
+      ? `${session.file.sourceKey}:${session.file.fileIndex}:${generation}` : null;
+    if (earlyWaitId && this.#earlyWaits.has(`${consumerId}:${earlyWaitId}`) && primarySourceStats) {
+      const linkMeasuredAt = Number(viewerReading?.linkMeasuredAt);
+      const videoOperation = forecast.operations.find(operation => operation.track === "video");
+      const audioOperation = forecast.operations.find(operation => operation.track === "audio");
+      const waitEstimate = this.waitEstimateForSource({ consumerId, generation,
+        sourceKey: session.file.sourceKey, fileIndex: session.file.fileIndex,
+        fileName: session.file.relativePath ?? session.file.name ?? "",
+        fileLength: primarySourceStats.fileLength, stats: primarySourceStats,
+        linkMbps: viewerReading?.linkMbps,
+        linkSampleAgeMs: Number.isFinite(linkMeasuredAt) ? Math.max(0, Date.now() - linkMeasuredAt) : undefined,
+        processing: {
+          videoOperation: videoOperation?.operation,
+          audioOperation: audioOperation?.operation,
+          videoSpeedX: videoOperation?.speed,
+          audioSpeedX: audioOperation?.speed,
+          firstRequiredSegmentsSeconds: forecast.firstRequiredSegmentsSeconds
+        } });
+      if (waitEstimate) forecast.waitEstimate = waitEstimate;
+    }
     if (measurement.forecastReason !== forecast.reason) {
       measurement.forecastReason = forecast.reason;
       logger.info(`playback readiness ${session.id} consumer=${consumerId} ${JSON.stringify({
@@ -1134,6 +1203,91 @@ export class ViewerRequests {
   }
 }
 
+/**
+ * Keep a wait's measurements when a later response omits a field. Zero is a
+ * measurement for rates, peers and byte counts; only null or an invalid value
+ * means that this response did not measure the field.
+ *
+ * @param {object | null | undefined} previous
+ * @param {object} incoming
+ * @param {number} ageElapsedMs
+ * @returns {object}
+ */
+function mergeWaitFeatures(previous, incoming, ageElapsedMs) {
+  const merged = { ...(previous ?? {}) };
+  for (const [key, value] of Object.entries(incoming ?? {})) {
+    if (value === null || value === undefined) {
+      if (!Object.hasOwn(merged, key)) merged[key] = null;
+      continue;
+    }
+    if (key === "extension") {
+      if (typeof value === "string" && value.length > 0) merged[key] = value;
+      continue;
+    }
+    if (key === "fileAvailable") {
+      if (typeof value === "boolean") merged[key] = value;
+      continue;
+    }
+    if (key === "videoOperation" || key === "audioOperation") {
+      if (value === "copy" || value === "encode") merged[key] = value;
+      continue;
+    }
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0 ||
+        ((key === "fileLength" || key === "linkMbps") && value === 0)) continue;
+    merged[key] = value;
+  }
+  const hasIncomingAge = Number.isFinite(incoming?.linkSampleAgeMs) && incoming.linkSampleAgeMs >= 0;
+  if (Number.isFinite(merged.linkSampleAgeMs) && !hasIncomingAge) {
+    merged.linkSampleAgeMs += Number.isFinite(ageElapsedMs) ? Math.max(0, ageElapsedMs) : 0;
+  }
+  return merged;
+}
+
+/**
+ * Read the separately measured viewer-to-proxy link and retain the age of the
+ * sample when an older page does not send it with its source request.
+ *
+ * @param {object | null | undefined} viewer
+ * @param {number | null | undefined} reportedMbps
+ * @param {number | null | undefined} reportedAgeMs
+ * @returns {{ mbps: number | null, ageMs: number | null }}
+ */
+function linkMeasurementOf(viewer, reportedMbps, reportedAgeMs) {
+  const reading = viewer?.linkReading?.() ?? null;
+  const mbps = Number.isFinite(reportedMbps) && reportedMbps > 0
+    ? reportedMbps
+    : Number.isFinite(reading?.linkMbps) && reading.linkMbps > 0 ? reading.linkMbps : null;
+  const ageMs = Number.isFinite(reportedAgeMs) && reportedAgeMs >= 0
+    ? reportedAgeMs
+    : Number.isFinite(reading?.linkMeasuredAt) ? Math.max(0, Date.now() - reading.linkMeasuredAt) : null;
+  return { mbps, ageMs };
+}
+
+/**
+ * Convert a learned full wait into the time still expected after this action.
+ *
+ * @param {number | null} totalSeconds
+ * @param {number} elapsedMs
+ * @returns {number | null}
+ */
+function earlyWaitRemainingSeconds(totalSeconds, elapsedMs) {
+  if (!Number.isFinite(totalSeconds) || totalSeconds < 0 || !Number.isFinite(elapsedMs) || elapsedMs < 0) return null;
+  return Math.max(0, totalSeconds - elapsedMs / 1000);
+}
+
+/**
+ * Prefer the browser's monotonic age of the original action; retain a proxy
+ * monotonic clock fallback for older pages that do not send it.
+ *
+ * @param {object} context
+ * @param {number | undefined} reportedElapsedMs
+ * @returns {number}
+ */
+function waitElapsedSince(context, reportedElapsedMs) {
+  if (Number.isFinite(reportedElapsedMs) && reportedElapsedMs >= 0) return reportedElapsedMs;
+  return Number.isFinite(context.startedAt) ? Math.max(0, performance.now() - context.startedAt) : 0;
+}
+
 /**
  * The download service a source's forecast runs on: what the swarm carried
  * while our selection held none of its connections back, but never less than

package/services/viewer/playback-readiness.js

@@ -542,6 +542,15 @@ export function predictPlaybackReadiness(input = {}) {
         ...(stop.unavailableSource ? { unavailableSource: stop.unavailableSource } : {}) };
     }
   }
+  const firstRequiredTrackSeconds = trackState.slice(0, requiredTracks).map((state, trackIndex) => {
+    const first = state.segments.find(segment => segment.endSeconds > position);
+    if (!first) return 0;
+    if (first.ranges.every(range => contains(state.clientRanges, range.start, range.end))) return 0;
+    const completion = completions.find(item => item.trackIndex === trackIndex && item.segment.index === first.index);
+    return completion?.at ?? null;
+  });
+  const firstRequiredSegmentsSeconds = firstRequiredTrackSeconds.every(Number.isFinite)
+    ? Math.max(0, ...firstRequiredTrackSeconds) : null;
   const delay = Math.max(0, ...constraints);
   const originReady = trackState.every(({ clientRanges }) => compare(contiguousEnd(clientRanges, at), at) > 0);
   const ready = delay === 0 && originReady;
@@ -549,6 +558,7 @@ export function predictPlaybackReadiness(input = {}) {
     Math.max(0, reserve - buffered), ready ? 'trajectory-safe-now' :
       Number.isFinite(delay) ? 'minimum-safe-delay' : 'service-not-advancing', preparedSegments);
   return { ...forecast, measuredAt: now, predictedStartAt: Number.isFinite(delay) ? now + delay * 1000 : null,
+    firstRequiredSegmentsSeconds,
     // The piece whose `kind` — its production, or its delivery to the page —
     // comes `atSeconds` from now while the media before it lasts
     // `aheadSeconds`: the difference is the delay.