@torrent-tv/proxy 2.9.100 → 2.9.102

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2.9.102
+
+- **New**: The playback plan also reports what this host takes to CREATE a session — median of the last eight, 116-843 ms depending on whether the keyframe index is already in hand. It is the second term of the browser's end-to-end estimate, which is being rebuilt as a sum over the stages that have not happened yet rather than a choice between figures that each describe only one of them (`research/playback-eta-2026-08-05.md`).
+
+## 2.9.101
+
+- **New**: The playback plan reports what this host takes to produce a session's first segment — the median of its last eight, measured from session-create to a servable segment (782-1518 ms on the field host). The browser needs it for the gap between "the file is downloaded" and "a segment exists", where until now it assumed the pipeline merely keeps up with realtime and therefore showed 15 s where 3.8 s were left. It is per-host, so a weak box and a fast one each answer for themselves.
+
 ## 2.9.100
 
 - **New**: A long wait for a piece now says who was working on it. The open question about a seek is that a single 8 MiB piece takes 3.0-4.6 s while the swarm as a whole moves 4-6 MB/s, so only about 2 MB/s reaches the piece being waited for — and whether that is because few peers hold it, few are being asked, or each is slow could not be told apart from outside. The line now carries the rate achieved on that piece and, sampled at its peak while waiting, how many connected peers had it, how many were asked, and how many blocks were in flight.

package/package.json

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

package/server.js

@@ -164,7 +164,9 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin,
     localBaseUrl: hlsSessionManager.localBaseUrl,
     sourceRegistry,
     torrentPool,
-    warmKeyframeIndex: (params) => hlsSessionManager.warmKeyframeIndex(params)
+    warmKeyframeIndex: (params) => hlsSessionManager.warmKeyframeIndex(params),
+    expectedFirstSegmentMs: () => hlsSessionManager.expectedFirstSegmentMs(),
+    expectedSessionCreateMs: () => hlsSessionManager.expectedSessionCreateMs()
   });
 
   app.get("/health", async (req, reply) => handleHealthGet(req, reply, { version }));

package/services/hls-session-manager.js

@@ -800,6 +800,24 @@ function normalizeLogFileName(fileName, fileIndex) {
  * expired after {@link HlsSessionManagerOptions.sessionTtlMs} of idle time.
  */
 export class HlsSessionManager {
+  /**
+   * Recent times from session-create to a servable first segment, in ms.
+   * See #rememberFirstSegmentLatency.
+   *
+   * @type {number[]}
+   */
+  #firstSegmentLatencies = [];
+
+  /**
+   * Recent times to create a session, in ms — the second term of the browser's
+   * estimate. Measured for the same reason as the first: it is 116-843 ms
+   * depending on whether the keyframe index is already in hand, and guessing it
+   * was one of the ways the shown figure stopped describing the whole wait.
+   *
+   * @type {number[]}
+   */
+  #sessionCreateLatencies = [];
+
   /**
    * @param {HlsSessionManagerOptions} options
    */
@@ -1113,6 +1131,7 @@ export class HlsSessionManager {
         );
       });
     }
+    this.#rememberSessionCreateLatency(Date.now() - createEntryMs);
     logger.info(
       `cold-start ${sessionId.slice(0, 8)}: media-info=${mediaInfoMs}ms (${mediaInfoSource}) ` +
         `keyframes=${keyframeMs === -1 ? "skipped" : keyframeMs === -2 ? "background" : `${keyframeMs}ms`} ` +
@@ -2727,6 +2746,69 @@ export class HlsSessionManager {
     return session.requestSeqCounter;
   }
 
+  /**
+   * Remember how long this host took to make a session's first segment.
+   *
+   * The browser has to answer "how long until playback" during the gap between
+   * the file being downloaded and the first segment existing, and until now it
+   * assumed the pipeline merely keeps up with realtime — which on the measured
+   * session meant showing 15 s where 3.8 s were left, and showing it as a jump
+   * UP from 5.5 s. This host knows the real figure because it has just done it
+   * several times: 782 ms, 1052 ms, 1387 ms, 1518 ms on the sessions measured
+   * 2026-08-04/05. A median of recent runs is a measurement, not an assumption,
+   * and it is per-host, so a weak box and a fast one each get their own.
+   *
+   * @param {number} latencyMs
+   * @returns {void}
+   */
+  #rememberSessionCreateLatency(latencyMs) {
+    if (!Number.isFinite(latencyMs) || latencyMs <= 0) {
+      return;
+    }
+    this.#sessionCreateLatencies.push(latencyMs);
+    if (this.#sessionCreateLatencies.length > FIRST_SEGMENT_SAMPLES) {
+      this.#sessionCreateLatencies.shift();
+    }
+  }
+
+  /**
+   * What this host typically takes to create a session, in ms — the median of
+   * recent ones, or null before any has finished.
+   *
+   * @returns {number | null}
+   */
+  expectedSessionCreateMs() {
+    if (this.#sessionCreateLatencies.length === 0) {
+      return null;
+    }
+    const sorted = [...this.#sessionCreateLatencies].sort((left, right) => left - right);
+    return sorted[Math.floor(sorted.length / 2)];
+  }
+
+  #rememberFirstSegmentLatency(latencyMs) {
+    if (!Number.isFinite(latencyMs) || latencyMs <= 0) {
+      return;
+    }
+    this.#firstSegmentLatencies.push(latencyMs);
+    if (this.#firstSegmentLatencies.length > FIRST_SEGMENT_SAMPLES) {
+      this.#firstSegmentLatencies.shift();
+    }
+  }
+
+  /**
+   * What this host typically takes to produce a session's first segment, in
+   * milliseconds — the median of recent runs, or null before any has finished.
+   *
+   * @returns {number | null}
+   */
+  expectedFirstSegmentMs() {
+    if (this.#firstSegmentLatencies.length === 0) {
+      return null;
+    }
+    const sorted = [...this.#firstSegmentLatencies].sort((left, right) => left - right);
+    return sorted[Math.floor(sorted.length / 2)];
+  }
+
   /**
    * How many times the viewer has moved since this session started.
    *
@@ -2881,6 +2963,7 @@ export class HlsSessionManager {
       // — the time from session-create entry to a playable first segment.
       if (!isPlaylist && !session.firstSegmentLogged) {
         session.firstSegmentLogged = true;
+        this.#rememberFirstSegmentLatency(Date.now() - session.createEntryMs);
         logger.info(
           `cold-start ${sessionId.slice(0, 8)}: first-segment ready +${Date.now() - session.createEntryMs}ms`
         );

package/services/playback-planner.js

@@ -264,6 +264,12 @@ export function createPlaybackPlanner({
   localBaseUrl,
   sourceRegistry,
   torrentPool,
+  // Optional. Reports what this host typically takes to produce a session's
+  // first segment. The browser needs it for the gap between "the file is
+  // downloaded" and "a segment exists": until now it assumed the pipeline
+  // merely keeps up with realtime, and showed 15 s where 3.8 s were left.
+  expectedFirstSegmentMs,
+  expectedSessionCreateMs,
   // Optional. Called once the file's edges are downloaded, so the keyframe
   // index — which reads the same tail of the file — is fetched alongside the
   // codec probe instead of after it. Late-bound to the HLS session manager,
@@ -396,6 +402,8 @@ export function createPlaybackPlanner({
       }
       const { audioCodec, videoCodec, container, durationSeconds, videoWidth, videoHeight, audioTracks, subtitleTracks } = probe;
       const codecsDetected = audioCodec.length > 0 || videoCodec.length > 0;
+      const firstSegmentMs = expectedFirstSegmentMs?.() ?? null;
+      const sessionCreateMs = expectedSessionCreateMs?.() ?? null;
       logger.info(
         `plan ${sourceKey.slice(0, 8)}:${fileIndex} torrent-ready=${torrentReadyMs}ms ` +
           `file-edges=${edgesReadyMs - torrentReadyMs}ms probe=${Date.now() - planEntryMs - edgesReadyMs}ms ` +
@@ -421,7 +429,12 @@ export function createPlaybackPlanner({
         videoHeight,
         // Full track inventory for the browser's audio/subtitle menus.
         audioTracks: audioTracks ?? [],
-        subtitleTracks: subtitleTracks ?? []
+        subtitleTracks: subtitleTracks ?? [],
+        // What this host has recently taken to make a session's first segment.
+        // Null until one has finished since startup.
+        expectedFirstSegmentMs: firstSegmentMs,
+        // Second term of the browser's estimate; see research/playback-eta-2026-08-05.md.
+        expectedSessionCreateMs: sessionCreateMs
       };
       // Only cache a plan whose codecs were actually detected. An empty probe is
       // a "header not downloaded yet" signal, not a valid result — caching it