@torrent-tv/proxy 2.76.1 → 2.76.3

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 2.76.3
+
+- **Fix**: The proxy stopped answering anything — playback, health, its own log — a few seconds after a viewer opened a film, and burned a whole processor doing it. Measured on the addon host with the stack read out of the live process: the look-ahead timer asked the plan where a new encoder could start, and the walk that answers that walked one segment number at a time towards nine quadrillion, scanning every claim at each step. It did that because the map had no length, and the map had no length because the field naming it moved onto the timeline in 2.76.0 while three readers were left on the old name, where every session answers `undefined`. Those three are the whole defect: with them wrong, no run was ever given an end either, so the feature that lets two encoders share one output was inert as well.
+- **Fix**: That walk can no longer do this whatever the length says. With no length known there is nothing to walk towards, and the answer — where the free stretch ends — is read off what the map already holds: the segments made and the stretches claimed, both finite however long the film is. A run then gets no end, which is what "the length is unknown" honestly means.
+- **Chore**: Three test fixtures stated the moved field on the session, so the checks went on passing over code that could not work. They state the timeline now, which is where the product reads it.
+
+## 2.76.2
+
+- **Fix**: How long a session waits for a film's keyframe table is bounded, and the bound is one the read already had rather than a new number. That table decides which branch a picture takes — with it the picture is passed through untouched, without it the whole picture is re-encoded — and nothing limited the wait, while the file comes off a torrent and the bytes the table lives in may still be arriving. Measured on the addon host over seventeen files from four containers, pieces from 0.25 to 16 MB (`research/keyframe-table-read-2026-09-04.md`): every table that arrived did so within 24.8 s and most within half a second, while two files answered nothing for 120.9 s and 120.5 s — which is exactly TWO of the sixty-second bound the read already has, one for the wait on the file's edges and one for the read, in series. A session now waits for one of them. The read is not cancelled: it goes on, is remembered on the file, and the next session of that file gets the copy.
+- **Fix**: A table that has not arrived is not written onto the file as an absence. It would make a passing shortage of bytes look like a property of the bytes, and every later session of the file would then re-encode a picture that can be copied.
+- **Chore**: The two lines about that read say which quantity each is. They differ by up to sixty seconds — one is the swarm delivering the file's edges plus the parse, the other only the parse — and reading them as one figure produced a wrong conclusion the same day.
+- **Chore**: What a playlist says is written where a playlist belongs (`services/output/playlists.js`), the second part taken out of the session manager: the media playlist, the master with its quality steps and soundtrack group, and the lookup from a time to a segment. All three are statements about a timeline and about nothing else — not about a session, a viewer, an encoder or a disk — and they were private details of an eleven-thousand-line class, along with the HLS attribute quoting, the language tags and the bitrate a variant declares.
+
 ## 2.76.1
 
 - **New**: How long it takes to read a file's keyframe table is recorded, once per file, with the container that answered and how many times it found. That read decides which branch a picture takes — with the table it is copied, without it the whole picture is re-encoded — and nothing measured it. The one figure printed until now, `keyframes=` on the session-create line, is what the SESSION waited for, which is the remainder of a read the playback plan had already started, and reads zero whenever the plan finished first.

package/package.json

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

package/services/encode/CoverageMap.js

@@ -251,7 +251,22 @@ export class CoverageMap {
    */
   freeRunFrom(index, exceptRun = null) {
     const start = Number.isInteger(index) && index > 0 ? index : 0;
-    const last = this.#segmentCount > 0 ? this.#segmentCount - 1 : Number.MAX_SAFE_INTEGER;
+    if (this.#segmentCount <= 0) {
+      // The length is not known, so how far the free stretch reaches is not
+      // known either, and the honest answer is "as far as there is film" — the
+      // caller turns that into a run with no end.
+      //
+      // Never walked one number at a time to find that out. It used to be, up to
+      // MAX_SAFE_INTEGER, with a scan of every claim at each step: on the addon
+      // host, 2026-09-05, the main thread spun at 100% from the look-ahead timer
+      // and the proxy stopped answering anything at all, its own log included.
+      // The length was missing because the field naming it had moved and three
+      // readers were left on the old name — but a walk whose end depends on a
+      // field being present must not be able to do this even then.
+      const covered = this.#firstCoveredFrom(start, exceptRun);
+      return covered === null ? Number.POSITIVE_INFINITY : covered - start;
+    }
+    const last = this.#segmentCount - 1;
     let at = start;
     while (at <= last) {
       if (this.#ready.has(at)) {
@@ -266,6 +281,38 @@ export class CoverageMap {
     return at - start;
   }
 
+  /**
+   * The first number at or after `index` that somebody has made or is making,
+   * or null when nobody has touched anything from there on.
+   *
+   * Asked of what the map HOLDS rather than by walking the numbers, so it can be
+   * answered without a length: the map knows every ready number and every claim,
+   * and both are finite however long the film is.
+   *
+   * @param {number} index
+   * @param {object | null} exceptRun
+   * @returns {number | null}
+   */
+  #firstCoveredFrom(index, exceptRun) {
+    let lowest = null;
+    for (const ready of this.#ready) {
+      if (ready >= index && (lowest === null || ready < lowest)) {
+        lowest = ready;
+      }
+    }
+    for (const [run, span] of this.#claims) {
+      if (run === exceptRun) {
+        continue;
+      }
+      // A claim that has already begun covers `index` itself.
+      const covers = span.from <= index && index <= span.to ? index : span.from;
+      if (covers >= index && (lowest === null || covers < lowest)) {
+        lowest = covers;
+      }
+    }
+    return lowest;
+  }
+
   /**
    * What this map holds, for a log line.
    *

package/services/encode/EncodePlan.js

@@ -184,7 +184,7 @@ export function planEncoders({
       type: "move",
       run,
       from: gap,
-      to: gap + Math.max(1, free) - 1,
+      to: endOfStretch(gap, free),
       because: driveSec === null
         ? `${coveredAhead} segment(s) ahead are already covered and its speed is not measured`
         : `driving through ${coveredAhead} covered segment(s) costs ${driveSec.toFixed(2)}s ` +
@@ -219,7 +219,7 @@ export function planEncoders({
     starts.push({
       type: "start",
       from: gap,
-      to: gap + free - 1,
+      to: endOfStretch(gap, free),
       because: `#${gap} is wanted and nobody is making it`
     });
   }
@@ -227,6 +227,21 @@ export function planEncoders({
   return [...stops, ...moves, ...starts, ...keeps];
 }
 
+/**
+ * The last number of a stretch that begins at `from` and is `length` long.
+ *
+ * `-1` when the length is not finite, which is this layer's word for a run with
+ * no end: the film's length is not known, so there is nothing to stop it at, and
+ * a number invented here would be an end nobody measured.
+ *
+ * @param {number} from
+ * @param {number} length
+ * @returns {number}
+ */
+function endOfStretch(from, length) {
+  return Number.isFinite(length) ? from + Math.max(1, length) - 1 : -1;
+}
+
 /**
  * The lowest number a viewer is waiting for that is not ready — what the plan
  * is judged by.

package/services/hls-session-manager.js

@@ -64,6 +64,7 @@ import { AudioOutput, CutGrid, OutputSpec, VideoOutput } from "./output/index.js
 import { newIndexCheck, Timeline, Timelines } from "./output/Timeline.js";
 export { newIndexCheck };
 import { Output, Outputs } from "./output/Output.js";
+import { masterPlaylistText, mediaPlaylistText, segmentIndexForTime } from "./output/playlists.js";
 import { SourceFiles, sourceDecodeCharacteristics } from "./source/SourceFile.js";
 import { ProducedIndex } from "./produced-index.js";
 import { SegmentStore } from "./encode/SegmentStore.js";
@@ -118,51 +119,10 @@ export function isInputUnavailable(message) {
 // The index of variants. Served from the same route as the media playlist, so
 // it needs no path of its own.
 const MASTER_PLAYLIST_FILE_NAME = "master.m3u8";
-// Path prefix under a session for one of its variants: `v/<height>/<file>`. A
-// directory level, so every relative name inside a variant's own playlist — its
-// segments and its init — resolves to that variant without any of them changing.
-const VARIANT_PATH_PREFIX = "v";
-// Where an audio rendition lives, and the name the variants refer to it by. One
-// directory level under the base session, exactly as a quality variant is, so
-// every relative name inside its playlist resolves to it unchanged.
-const AUDIO_PATH_PREFIX = "a";
-const AUDIO_GROUP_ID = "aud";
-
-/**
- * Quote a value for an HLS attribute list. Only the quote itself can end the
- * attribute early, and a track title comes from the file, so it is not ours to
- * trust.
- *
- * @param {string} value
- * @returns {string}
- */
-function escapeAttribute(value) {
-  // The quote would end the attribute early; a line break would end the LINE,
-  // splitting one `#EXT-X-MEDIA` into two and corrupting the master. Both come
-  // from the file's own metadata, which is not ours to trust.
-  return String(value ?? "").replace(/"/g, "'").replace(/[\u0000-\u001f\u007f]/g, " ").trim();
-}
-
-// ISO 639-2 codes as ffmpeg reports them, against the RFC 5646 tags HLS asks
-// for. Only the languages this serves in practice; anything else is passed
-// through, which is what players other than iOS accept anyway.
-const LANGUAGE_TAGS = new Map([
-  ["rus", "ru"], ["eng", "en"], ["ukr", "uk"], ["deu", "de"], ["ger", "de"],
-  ["fra", "fr"], ["fre", "fr"], ["spa", "es"], ["ita", "it"], ["jpn", "ja"],
-  ["kor", "ko"], ["zho", "zh"], ["chi", "zh"], ["pol", "pl"], ["por", "pt"],
-  ["tur", "tr"], ["ces", "cs"], ["cze", "cs"], ["nld", "nl"], ["dut", "nl"]
-]);
-
-/**
- * The RFC 5646 tag for a language ffmpeg named, or the name unchanged.
- *
- * @param {string} language
- * @returns {string}
- */
-function languageTag(language) {
-  const code = String(language ?? "").toLowerCase();
-  return LANGUAGE_TAGS.get(code) ?? code;
-}
+// Where a variant and an audio rendition live under a session — `v/<height>/…`
+// and `a/<track>/…` — is stated in `output/playlists.js`, beside the lines that
+// write those addresses into a master playlist. The routes that parse them back
+// are in `server.js`.
 
 /**
  * The last index of the unbroken run of segments starting at `from`.
@@ -448,21 +408,27 @@ export function variantConsumerId(baseSessionId) {
   return `variant-of:${baseSessionId}`;
 }
 
-/**
- * A rough bitrate for a height, in bits per second.
- *
- * `BANDWIDTH` is required on every variant by the HLS specification, and the
- * player uses it to order them. It does not have to be exact — nothing here
- * adapts on it, because the viewer chooses — so it is the usual H.264 rule of
- * thumb rather than a measurement we do not have before encoding starts.
- *
- * @param {number} height
- * @returns {number}
- */
-export function estimatedBitrateFor(height) {
-  return Math.max(400_000, Math.round(height * height * 3.2));
-}
 const CLEANUP_INTERVAL_MS = 30_000;
+
+// How long a session waits for the file's keyframe table before giving up on
+// copying the picture and re-encoding it instead.
+//
+// Measured on the addon host, 2026-09-04, over seventeen files from
+// `Dropbox/trn` — four containers, pieces from 0.25 to 16 MB, files from 0.36 to
+// 20 GB, each torrent registered fresh so nothing of it was downloaded
+// (`research/keyframe-table-read-2026-09-04.md`). Every table that arrived did
+// so within 24.8 s, most within half a second; the two files that answered
+// nothing took 120.9 s and 120.5 s.
+//
+// Those two figures are not a coincidence and they are what fixes this one:
+// they are TWO of the bound the read already has — `READ_ABANDON_MS` in
+// `torrent-worker/container-tracks.js`, one for the wait on the file's edges and
+// one for the read itself, in series. A session waiting for two of them is the
+// defect; waiting for one is the bound, and it leaves 2.4x over the slowest
+// table that did arrive. The line printed when it fires names which case
+// happened, so the field can move it rather than an argument.
+const KEYFRAME_TABLE_BUDGET_MS = 60_000;
+
 const DEFAULT_SEGMENT_DURATION_SEC = 4;
 // How many segments ahead of the current encode head a missing-segment request
 // is allowed to be before we restart ffmpeg at that position (server-side seek).
@@ -1702,6 +1668,11 @@ export class HlsSessionManager {
     segmentDurationSec = DEFAULT_SEGMENT_DURATION_SEC,
     sessionTtlMs = DEFAULT_SESSION_TTL_MS,
     startupWaitMs = DEFAULT_STARTUP_WAIT_MS,
+    // How long a session waits for the file's keyframe table before it
+    // re-encodes the picture instead of copying it. Measured, not chosen —
+    // see KEYFRAME_TABLE_BUDGET_MS. A parameter so a check can name a
+    // shorter one rather than sitting out the real wait.
+    keyframeTableBudgetMs = KEYFRAME_TABLE_BUDGET_MS,
     videoEncoder = null,
     softwarePresetBenchmark = null,
     decodeCostModel = null,
@@ -1722,6 +1693,9 @@ export class HlsSessionManager {
     getTorrentTotals}) {
     this.enabled = Boolean(enabled);
     this.ffmpegBin = ffmpegBin;
+    this.keyframeTableBudgetMs = Number.isFinite(keyframeTableBudgetMs) && keyframeTableBudgetMs > 0
+      ? keyframeTableBudgetMs
+      : KEYFRAME_TABLE_BUDGET_MS;
     // Where measurements about this host are kept between runs. Empty means
     // beside the installed proxy; a deployment with somewhere persistent to
     // write names it (--state-dir).
@@ -2283,15 +2257,12 @@ export class HlsSessionManager {
       // boundaries (the playlist itself), so this MUST block session creation —
       // an incorrect playlist is worse than a slower start.
       //
-      // There is NO bound on this wait. A comment here used to promise a short
-      // timeout and "never more than ~6 s to session start"; nothing in this
-      // path has ever had a timeout, and the fallback below fires when the
-      // index is ABSENT, which is a statement about the file and not about how
-      // long a read ran. The file comes off a torrent, so the bytes the table
-      // lives in may still be arriving and the read waits for them. What the
-      // bound should be has to come from what this read costs on real hosts —
-      // roadmap item 74, and the reading it needs is the line printed by
-      // #readContainerKeyframes.
+      // The wait is bounded (KEYFRAME_TABLE_BUDGET_MS), and the bound is what
+      // the read costs on a real host rather than a figure picked here. A
+      // comment in this place used to promise a short timeout and "never more
+      // than ~6 s to session start" when no timeout existed at all; the file
+      // comes off a torrent, so the bytes the table lives in may still be
+      // arriving, and a session used to wait for them without limit.
       const keyframeStartMs = Date.now();
       // Read the container's OWN keyframe table (Cues/stss) rather than
       // scanning the media. On the copy path ffmpeg can only cut at the
@@ -2303,15 +2274,27 @@ export class HlsSessionManager {
       // the file comes off a torrent, and a full packet scan of 5.5 GB found 77
       // keyframes in 45 s without finishing, while the container index yields
       // all 570 in 0.8 s from two point reads (16 KB).
-      const index = await this.#readContainerKeyframes({ sourceKey, fileIndex, inputUrl, logName });
+      const index = await this.readKeyframeTableWithin({ sourceKey, fileIndex, inputUrl, logName });
       keyframeTimes = index.times;
       containerFormat = index.format;
       keyframeTolerance = Number.isFinite(index.tolerance) ? index.tolerance : 0;
       keyframeMs = Date.now() - keyframeStartMs;
-      // Onto the file: the table is a property of its immutable bytes, like the
-      // duration and the track list, and every session of the file reads the
-      // one answer.
-      file.learn({ keyframeTimes, keyframeTolerance, containerFormat });
+      // Onto the file only when the file has ANSWERED. A read that ran out of
+      // its budget is still running, and writing its absence onto the file would
+      // make a passing shortage of bytes look like a property of the bytes —
+      // every later session of the file would then re-encode a picture that can
+      // be copied.
+      if (index.arrived) {
+        // The table is a property of immutable bytes, like the duration and the
+        // track list, and every session of the file reads the one answer.
+        file.learn({ keyframeTimes, keyframeTolerance, containerFormat });
+      } else {
+        logger.warn(
+          `transcode ${sessionId}: the keyframe table for "${logName}" has not arrived in ` +
+            `${Math.round(this.keyframeTableBudgetMs / 1000)}s, so this session re-encodes the picture ` +
+            "instead of copying it; the read goes on and the next session of this file gets the copy"
+        );
+      }
       if (!keyframeTimes) {
         // No index, so there is no honest grid for a COPY: a copied picture can
         // only be cut at the source's own keyframes, and we do not know where
@@ -2328,11 +2311,13 @@ export class HlsSessionManager {
         // could not be read in the budget lands here too, which is right for
         // the same reason.
         transcodeVideo = true;
-        logger.warn(
-          `transcode ${sessionId}: no keyframe index in the ${containerFormat} container for ` +
-            `"${logName}" — a copied picture has no honest grid without one, so the video is ` +
-            "re-encoded instead and its keyframes are placed on our own cuts"
-        );
+        if (index.arrived) {
+          logger.warn(
+            `transcode ${sessionId}: no keyframe index in the ${containerFormat} container for ` +
+              `"${logName}" — a copied picture has no honest grid without one, so the video is ` +
+              "re-encoded instead and its keyframes are placed on our own cuts"
+          );
+        }
       }
     } else if (hasDuration && transcodeVideo) {
       // Re-encode path: keyframeTimes are ONLY used to snap a LATER seek (see
@@ -2695,7 +2680,7 @@ export class HlsSessionManager {
       // read; this counts them so a session can report what it found. It is
       // what decides whether a re-encoded rung can be cut on this same grid and
       // spliced into the copy (roadmap item 28).
-      playlistText: hasDuration ? this.#buildVodPlaylist(publishedGrid, segmentFormat) : "",
+      playlistText: hasDuration ? mediaPlaylistText({ boundaries: publishedGrid, segmentFormat }) : "",
       // The table AS PUBLISHED — what every playlist of this family states, and
       // what every segment of it is stamped against. Inherited whole from the
       // base when there is one, so a rung or a soundtrack created later
@@ -3137,12 +3122,12 @@ export class HlsSessionManager {
     if (running) {
       return running;
     }
-    // What this read costs is what decides whether a picture can be copied, and
-    // until now nothing recorded it: the one figure printed — `keyframes=` on
-    // the session-create line — is what the SESSION waited for, which is the
-    // remainder of a read the plan had already started, and is zero whenever
-    // the plan finished first. The read itself is a fact of the file and is
-    // timed here, where it is made exactly once per file.
+    // The WHOLE wait, as whoever asked for the table experiences it: the swarm
+    // delivering the head and tail of the file, the parse over those bytes, and
+    // the crossing to the torrent thread and back. The worker's own line
+    // (`container-keyframes:`) reports the last two apart from the first, and
+    // reading the two lines as one figure is what led to a wrong conclusion on
+    // 2026-09-04 — they differ by up to sixty seconds on a thin swarm.
     const startedMs = Date.now();
     const work = this.#readContainerKeyframesOnce({ sourceKey, fileIndex, inputUrl, logName })
       .then((result) => {
@@ -3151,7 +3136,7 @@ export class HlsSessionManager {
         const found = Array.isArray(result?.times) ? result.times.length : 0;
         logger.info(
           `keyframe index "${logName}": ${found > 0 ? `${found} times` : "none"} from the ` +
-            `${result?.format ?? "unrecognised"} container in ${tookMs}ms`
+            `${result?.format ?? "unrecognised"} container, waited ${tookMs}ms`
         );
         return result;
       })
@@ -3169,6 +3154,40 @@ export class HlsSessionManager {
     return work;
   }
 
+  /**
+   * The same read, with a bound on how long a session will wait for it.
+   *
+   * The read itself is NOT cancelled when the bound is reached — it goes on in
+   * the background, is memoized on the file, and is there for the next session
+   * of it. What the bound decides is only whether THIS session waits: a copied
+   * picture cannot be cut without the table, so the answer to "not yet" is to
+   * re-encode, which needs no table because it places the keyframes itself.
+   *
+   * Public because it is what decides which branch a picture takes, and a
+   * private method cannot be pinned by a check.
+   *
+   * @param {{ sourceKey: string, fileIndex: number, inputUrl?: URL, logName: string }} params
+   * @returns {Promise<{ times: number[] | null, format: string, tolerance?: number, arrived: boolean }>}
+   */
+  async readKeyframeTableWithin(params) {
+    const read = this.#readContainerKeyframes(params);
+    let timer = null;
+    const budget = new Promise((resolve) => {
+      timer = setTimeout(() => resolve(null), this.keyframeTableBudgetMs);
+      // A session must not be held open by this timer alone.
+      timer?.unref?.();
+    });
+    const answer = await Promise.race([read.then((result) => ({ ...result, arrived: true })), budget]);
+    clearTimeout(timer);
+    if (answer) {
+      return answer;
+    }
+    // Nothing is added here to swallow a late rejection: the race is holding a
+    // handler on that promise already, and a second one would only look like it
+    // was doing something.
+    return { times: null, format: "not yet read", tolerance: 0, arrived: false };
+  }
+
   /**
    * The read itself, made exactly once per file by the caller above.
    *
@@ -3222,36 +3241,6 @@ export class HlsSessionManager {
     return ContainerFactory.readKeyframeIndex({ readRange, fileSize, label: logName });
   }
 
-  #buildVodPlaylist(boundaries, segmentFormat) {
-    const count = Math.max(0, boundaries.length - 1);
-    let maxDuration = 0;
-    for (let index = 0; index < count; index += 1) {
-      const duration = Math.max(0.1, boundaries[index + 1] - boundaries[index]);
-      if (duration > maxDuration) {
-        maxDuration = duration;
-      }
-    }
-    const lines = [
-      "#EXTM3U",
-      // The container decides the minimum version (fMP4 + `#EXT-X-MAP` needs 7,
-      // MPEG-TS is fine at 3).
-      `#EXT-X-VERSION:${segmentFormat.playlistVersion}`,
-      `#EXT-X-TARGETDURATION:${Math.ceil(maxDuration)}`,
-      "#EXT-X-MEDIA-SEQUENCE:0",
-      "#EXT-X-PLAYLIST-TYPE:VOD",
-      "#EXT-X-INDEPENDENT-SEGMENTS",
-      // Container-specific header lines (e.g. fMP4's `#EXT-X-MAP`).
-      ...segmentFormat.playlistHeaderLines()
-    ];
-    for (let index = 0; index < count; index += 1) {
-      const duration = Math.max(0.1, boundaries[index + 1] - boundaries[index]);
-      lines.push(`#EXTINF:${duration.toFixed(6)},`);
-      lines.push(segmentFormat.segmentFileName(index));
-    }
-    lines.push("#EXT-X-ENDLIST");
-    return `${lines.join("\n")}\n`;
-  }
-
   /**
    * Start time (seconds, 0-based) of segment `index`, from the session's
    * boundary table. Clamped to valid range.
@@ -3357,24 +3346,7 @@ export class HlsSessionManager {
     // The player's grid, for the same reason the cut list uses it: the time
     // being resolved came from the playlist the player holds, so the index it
     // means is the index that playlist gives it.
-    const boundaries = this.publishedGridFor(session);
-    if (boundaries.length < 2) {
-      return Math.max(0, Math.floor(t / this.segmentDurationSec));
-    }
-    // boundaries is sorted ascending; find the last boundary <= t.
-    let lo = 0;
-    let hi = boundaries.length - 1;
-    let result = 0;
-    while (lo <= hi) {
-      const mid = (lo + hi) >> 1;
-      if (boundaries[mid] <= t) {
-        result = mid;
-        lo = mid + 1;
-      } else {
-        hi = mid - 1;
-      }
-    }
-    return Math.min(result, boundaries.length - 2);
+    return segmentIndexForTime(this.publishedGridFor(session), t, this.segmentDurationSec);
   }
 
   /**
@@ -3884,7 +3856,13 @@ export class HlsSessionManager {
     const now = Date.now();
     for (const [address, sessions] of byOutput) {
       const coverage = this.encodeOrchestrator.coverageOf(address);
-      const segmentCount = Number(sessions[0].segmentCount) || 0;
+      // From the TIMELINE, which is where how a file is cut has lived since
+      // 2.76.0. Read off the session it left, this was `undefined` on every
+      // session ever made: the map then held no length, and the walk that
+      // gives a run its end ran to MAX_SAFE_INTEGER — the main thread spun at
+      // 100% and the proxy answered nothing, measured on the addon host
+      // 2026-09-05 with the stack read out of the live process.
+      const segmentCount = Number(sessions[0].timeline?.segmentCount) || 0;
       if (segmentCount > 0) {
         coverage.setSegmentCount(segmentCount);
       }
@@ -5489,7 +5467,7 @@ export class HlsSessionManager {
 
   planRunInterval(session, startIndex, exceptRun = null) {
     const key = session.outputKey ?? "";
-    const lastIndex = (Number(session.segmentCount) || 0) - 1;
+    const lastIndex = (Number(session.timeline?.segmentCount) || 0) - 1;
     if (!key || lastIndex < 0) {
       // Nothing to plan against: no address, or no playlist yet. The run keeps
       // the shape it has always had — start here, no end.
@@ -5720,7 +5698,8 @@ export class HlsSessionManager {
       // The film's last segment number, which is what tells "it reached the
       // end" from "its input dried up": ffmpeg exits zero for both and over a
       // torrent cannot tell them apart.
-      lastSegmentIndex: () => (session.segmentCount > 0 ? session.segmentCount - 1 : null),
+      lastSegmentIndex: () =>
+        session.timeline?.segmentCount > 0 ? session.timeline.segmentCount - 1 : null,
       inputUnavailable: (message) => isInputUnavailable(message),
       onProgress: (report) => this.#noteRunProgress(session, run, report),
       onEnded: (ended) => this.#onRunEnded(session, run, ended)
@@ -9216,7 +9195,6 @@ export class HlsSessionManager {
     // existence made a live session answer 404 to its own published address.
     const rungs = this.liveOutputs.splicableHeights(session);
     const sourceWidth = Number(session.file.width) || 0;
-    const lines = ["#EXTM3U", `#EXT-X-VERSION:${session.segmentFormat.playlistVersion}`];
     // The audio tracks, published once for the whole file rather than muxed
     // into every rung. Two things follow from that: the same track is not
     // encoded once per rung on a host that struggles to encode it once, and
@@ -9233,27 +9211,14 @@ export class HlsSessionManager {
       // field would start the second viewer in the first viewer's language.
       ? this.#audioRenditionsOf(session, this.#audioChoiceOf(session, consumerId).trackIndex)
       : [];
-    const audioGroup = renditions.length > 0 ? AUDIO_GROUP_ID : "";
-    for (const rendition of renditions) {
-      lines.push(
-        `#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="${audioGroup}",NAME="${escapeAttribute(rendition.name)}"` +
-        (rendition.language ? `,LANGUAGE="${escapeAttribute(languageTag(rendition.language))}"` : "") +
-        `,AUTOSELECT=YES,DEFAULT=${rendition.isDefault ? "YES" : "NO"}` +
-        `,URI="${AUDIO_PATH_PREFIX}/${rendition.trackIndex}/${PLAYLIST_FILE_NAME}"`
-      );
-    }
-    for (const height of rungs) {
-      const width = sourceHeight > 0 && sourceWidth > 0
-        ? Math.round((sourceWidth / sourceHeight) * height / 2) * 2
-        : 0;
-      lines.push(
-        `#EXT-X-STREAM-INF:BANDWIDTH=${estimatedBitrateFor(height)}` +
-        (width > 0 ? `,RESOLUTION=${width}x${height}` : "") +
-        (audioGroup ? `,AUDIO="${audioGroup}"` : "")
-      );
-      lines.push(`${VARIANT_PATH_PREFIX}/${height}/${PLAYLIST_FILE_NAME}`);
-    }
-    return `${lines.join("\n")}\n`;
+    return masterPlaylistText({
+      playlistVersion: session.segmentFormat.playlistVersion,
+      heights: rungs,
+      sourceWidth,
+      sourceHeight,
+      renditions,
+      playlistFileName: PLAYLIST_FILE_NAME
+    });
   }
 
   /**

package/services/output/playlists.js

@@ -0,0 +1,206 @@
+/**
+ * @file What an output tells a player it consists of.
+ *
+ * Two texts and one lookup, and all three are statements about a TIMELINE — how
+ * the file is cut, and which of the file's heights and soundtracks are being
+ * published beside it. None of them is about a session, a viewer, an encoder or
+ * a disk, which is why they live here: the manager resolved a session, walked
+ * the live outputs and then also wrote HLS by hand, so the format of a playlist
+ * was a private detail of an eleven-thousand-line class.
+ *
+ * Every input is passed in. This layer reads no file, holds no state, and knows
+ * nothing of the classes above it.
+ */
+
+// Where a rung and a soundtrack live under a session's own address. The player
+// only ever sees them joined to it, so they are written once, here, beside the
+// lines that use them.
+const VARIANT_PATH_PREFIX = "v";
+const AUDIO_PATH_PREFIX = "a";
+
+// One group for every soundtrack of one picture: a rendition group is what
+// makes changing language the player's own switch instead of this proxy
+// rebuilding the session with another track number.
+const AUDIO_GROUP_ID = "aud";
+
+// ISO 639-2 codes as ffmpeg reports them, against the RFC 5646 tags HLS asks
+// for. Only the languages this serves in practice; anything else is passed
+// through, which is what players other than iOS accept anyway.
+const LANGUAGE_TAGS = new Map([
+  ["rus", "ru"], ["eng", "en"], ["ukr", "uk"], ["deu", "de"], ["ger", "de"],
+  ["fra", "fr"], ["fre", "fr"], ["spa", "es"], ["ita", "it"], ["jpn", "ja"],
+  ["kor", "ko"], ["zho", "zh"], ["chi", "zh"], ["pol", "pl"], ["por", "pt"],
+  ["tur", "tr"], ["ces", "cs"], ["cze", "cs"], ["nld", "nl"], ["dut", "nl"]
+]);
+
+/**
+ * The RFC 5646 tag for a language ffmpeg named, or the name unchanged.
+ *
+ * @param {string} language
+ * @returns {string}
+ */
+export function languageTag(language) {
+  const code = String(language ?? "").toLowerCase();
+  return LANGUAGE_TAGS.get(code) ?? code;
+}
+
+/**
+ * Quote a value for an HLS attribute list.
+ *
+ * The quote would end the attribute early; a line break would end the LINE,
+ * splitting one `#EXT-X-MEDIA` into two and corrupting the master. Both come
+ * from the file's own metadata, which is not ours to trust.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+export function escapeAttribute(value) {
+  return String(value ?? "").replace(/"/g, "'").replace(/[\u0000-\u001f\u007f]/g, " ").trim();
+}
+
+/**
+ * A rough bitrate for a height, in bits per second.
+ *
+ * `BANDWIDTH` is required on every variant by the HLS specification, and the
+ * player uses it to order them. It does not have to be exact — nothing here
+ * adapts on it, because the viewer chooses — so it is the usual H.264 rule of
+ * thumb rather than a measurement we do not have before encoding starts.
+ *
+ * @param {number} height
+ * @returns {number}
+ */
+export function estimatedBitrateFor(height) {
+  return Math.max(400_000, Math.round(height * height * 3.2));
+}
+
+/**
+ * The media playlist: the whole film, as a VOD list of segments that mostly do
+ * not exist yet.
+ *
+ * Synthetic and complete by design — every segment listed and `#EXT-X-ENDLIST`
+ * at the end — so the player knows the length and can seek at once. An `event`
+ * playlist gives neither, which is the bug this replaced.
+ *
+ * @param {{ boundaries: number[], segmentFormat: { playlistVersion: number, playlistHeaderLines: () => string[], segmentFileName: (index: number) => string } }} params
+ * @returns {string}
+ */
+export function mediaPlaylistText({ boundaries, segmentFormat }) {
+  const count = Math.max(0, boundaries.length - 1);
+  let maxDuration = 0;
+  for (let index = 0; index < count; index += 1) {
+    const duration = Math.max(0.1, boundaries[index + 1] - boundaries[index]);
+    if (duration > maxDuration) {
+      maxDuration = duration;
+    }
+  }
+  const lines = [
+    "#EXTM3U",
+    // The container decides the minimum version (fMP4 + `#EXT-X-MAP` needs 7,
+    // MPEG-TS is fine at 3).
+    `#EXT-X-VERSION:${segmentFormat.playlistVersion}`,
+    `#EXT-X-TARGETDURATION:${Math.ceil(maxDuration)}`,
+    "#EXT-X-MEDIA-SEQUENCE:0",
+    "#EXT-X-PLAYLIST-TYPE:VOD",
+    "#EXT-X-INDEPENDENT-SEGMENTS",
+    // Container-specific header lines (e.g. fMP4's `#EXT-X-MAP`).
+    ...segmentFormat.playlistHeaderLines()
+  ];
+  for (let index = 0; index < count; index += 1) {
+    const duration = Math.max(0.1, boundaries[index + 1] - boundaries[index]);
+    lines.push(`#EXTINF:${duration.toFixed(6)},`);
+    lines.push(segmentFormat.segmentFileName(index));
+  }
+  lines.push("#EXT-X-ENDLIST");
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * The master playlist: the heights a player may switch between, and the
+ * soundtracks published beside them.
+ *
+ * The soundtracks are published once for the whole file rather than muxed into
+ * every rung. Two things follow: the same track is not encoded once per rung on
+ * a host that struggles to encode it once, and changing track becomes the
+ * player switching rendition instead of this proxy rebuilding the session.
+ *
+ * Which rendition is marked DEFAULT is decided by the caller, per VIEWER: one
+ * picture is shared by everyone watching it and each of them may have chosen a
+ * different language, so a default taken from the session's own field would
+ * start the second viewer in the first viewer's language.
+ *
+ * @param {{
+ *   playlistVersion: number,
+ *   heights: number[],
+ *   sourceWidth: number,
+ *   sourceHeight: number,
+ *   renditions?: Array<{ trackIndex: number, name: string, language: string, isDefault: boolean }>,
+ *   playlistFileName: string
+ * }} params
+ * @returns {string}
+ */
+export function masterPlaylistText({
+  playlistVersion,
+  heights,
+  sourceWidth,
+  sourceHeight,
+  renditions = [],
+  playlistFileName
+}) {
+  const lines = ["#EXTM3U", `#EXT-X-VERSION:${playlistVersion}`];
+  const audioGroup = renditions.length > 0 ? AUDIO_GROUP_ID : "";
+  for (const rendition of renditions) {
+    lines.push(
+      `#EXT-X-MEDIA:TYPE=AUDIO,GROUP-ID="${audioGroup}",NAME="${escapeAttribute(rendition.name)}"` +
+      (rendition.language ? `,LANGUAGE="${escapeAttribute(languageTag(rendition.language))}"` : "") +
+      `,AUTOSELECT=YES,DEFAULT=${rendition.isDefault ? "YES" : "NO"}` +
+      `,URI="${AUDIO_PATH_PREFIX}/${rendition.trackIndex}/${playlistFileName}"`
+    );
+  }
+  for (const height of heights) {
+    const width = sourceHeight > 0 && sourceWidth > 0
+      ? Math.round((sourceWidth / sourceHeight) * height / 2) * 2
+      : 0;
+    lines.push(
+      `#EXT-X-STREAM-INF:BANDWIDTH=${estimatedBitrateFor(height)}` +
+      (width > 0 ? `,RESOLUTION=${width}x${height}` : "") +
+      (audioGroup ? `,AUDIO="${audioGroup}"` : "")
+    );
+    lines.push(`${VARIANT_PATH_PREFIX}/${height}/${playlistFileName}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * The segment whose span contains `seconds`, by a boundary table.
+ *
+ * The table to pass is the one the PLAYER holds: the time being resolved came
+ * from the playlist the player was given, so the index it means is the index
+ * that playlist gives it. Falls back to an even grid of `segmentDurationSec`
+ * when there is no table, which is a session with no known duration.
+ *
+ * @param {number[]} boundaries
+ * @param {number} seconds
+ * @param {number} segmentDurationSec
+ * @returns {number}
+ */
+export function segmentIndexForTime(boundaries, seconds, segmentDurationSec) {
+  if (!Array.isArray(boundaries) || boundaries.length < 2) {
+    return Math.max(0, Math.floor(seconds / segmentDurationSec));
+  }
+  // boundaries is sorted ascending; find the last boundary <= t.
+  let lo = 0;
+  let hi = boundaries.length - 1;
+  let result = 0;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    if (boundaries[mid] <= seconds) {
+      result = mid;
+      lo = mid + 1;
+    } else {
+      hi = mid - 1;
+    }
+  }
+  return Math.min(result, boundaries.length - 2);
+}
+
+export { AUDIO_GROUP_ID, AUDIO_PATH_PREFIX, VARIANT_PATH_PREFIX };

package/services/torrent-worker/container-tracks.js

@@ -309,6 +309,13 @@ export async function containerKeyframesOf(torrent, fileIndex, sourceKey, option
   if (!file || !Number.isFinite(file.length) || file.length <= 0) {
     return null;
   }
+  // Timed apart from the read below, and reported apart from it, because the
+  // two are different quantities and reading them as one led to a wrong
+  // conclusion on 2026-09-04: this wait is the SWARM delivering the head and
+  // tail of the file, and it reached 60 s on a torrent with one peer, while the
+  // read that follows it is parsing bytes already in hand and never passed
+  // 8.4 s across four containers. A bound belongs on the first, not the second.
+  const edgesStartedAt = Date.now();
   if (typeof options.prefetchEdges === "function") {
     try {
       await options.prefetchEdges();
@@ -317,6 +324,7 @@ export async function containerKeyframesOf(torrent, fileIndex, sourceKey, option
       // fetches what it needs itself, only more slowly.
     }
   }
+  const edgesMs = Date.now() - edgesStartedAt;
   const readRange = async (start, end) =>
     readFetching(file, start, Math.min(end, file.length - 1));
   const startedAt = Date.now();
@@ -339,7 +347,8 @@ export async function containerKeyframesOf(torrent, fileIndex, sourceKey, option
       `container-keyframes: "${String(file.name).slice(0, 40)}" ` +
       (times
         ? `${times.length} keyframes from the ${format} index in ${Date.now() - startedAt}ms`
-        : `has no readable index (${format}, ${Date.now() - startedAt}ms)`)
+        : `has no readable index (${format}, ${Date.now() - startedAt}ms)`) +
+      `, after ${edgesMs}ms waiting for the file's edges`
     );
     return {
       times,

package/test/auto-quality-step.test.js

@@ -99,7 +99,6 @@ function fakeSession({ dirPath, transcodeVideo = true, cutGrid = transcodeVideo
     usesExplicitCuts: false,
     useSyntheticPlaylist: true,
     playlistText: "#EXTM3U\n",
-    segmentCount: 100,
     progress: { state: "running", processedSeconds: 40, startPositionSeconds: 0, speed: "1.0x" }
   };
 }

package/test/behind-head-repair.test.js

@@ -65,7 +65,6 @@ async function managerWithRunAhead() {
     transcodeVideo: true,
     useSyntheticPlaylist: true,
     playlistText: "#EXTM3U\n",
-    segmentCount: 1936,
     lastRestartAt: 0,
     seekFailureTarget: -1,
     seekFailureCount: 0,

package/test/coverage-map.test.js

@@ -151,3 +151,28 @@ test("with the length unknown, a gap search needs its own bound", () => {
   assert.equal(map.firstGapFrom(0), null, "no length and no bound answers nothing");
   assert.equal(map.firstGapFrom(0, 3), 0);
 });
+
+test("with the length unknown, the free stretch is answered without walking to it", () => {
+  // What this pins: on the addon host, 2026-09-05, a map with no length walked
+  // one number at a time to MAX_SAFE_INTEGER, scanning every claim at each step.
+  // The main thread spun at 100% from the look-ahead timer and the proxy stopped
+  // answering anything, its own log included. The length was missing because the
+  // field naming it had moved to the timeline and three readers were left on the
+  // old name — but this walk must not be able to do that even when it is.
+  //
+  // This check cannot FAIL against the old code — a synchronous walk cannot be
+  // interrupted by the runner, so it would hang the whole run instead, which is
+  // worse than no check. What it pins is the contract that replaced the walk:
+  // the answer comes from what the map holds.
+  const map = new CoverageMap();
+
+  assert.equal(map.freeRunFrom(0), Number.POSITIVE_INFINITY, "nothing is covered, so nothing bounds it");
+
+  const run = aRun();
+  map.claim(run, 500, 900);
+  assert.equal(map.freeRunFrom(0), 500, "and a claim ahead is where the free stretch ends");
+  assert.equal(map.freeRunFrom(0, run), Number.POSITIVE_INFINITY, "its own claim does not bound it");
+
+  map.markReady(200);
+  assert.equal(map.freeRunFrom(0), 200, "so is a segment somebody has already made");
+});

package/test/keyframe-table-budget.test.js

@@ -0,0 +1,101 @@
+/**
+ * @file How long a session waits for the file's keyframe table.
+ *
+ * With the table a picture is copied; without it the whole picture is
+ * re-encoded, which on a weak host is the difference between almost free and
+ * more than the machine has. Until 2.76.1 there was no bound on that wait at
+ * all, and the file comes off a torrent — so the bytes the table lives in may
+ * still be arriving, and a session could sit there for as long as they took.
+ *
+ * Measured on the addon host 2026-09-04 over fifteen torrents
+ * (`research/keyframe-table-read-2026-09-04.md`): every read whose bytes were
+ * there finished within 8.8 s, while reads on swarms of one to four peers were
+ * still waiting at 60-121 s. The bound sits between those two, and what it must
+ * do is pinned here.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { HlsSessionManager } from "../services/hls-session-manager.js";
+
+/**
+ * @param {number} budgetMs
+ * @returns {HlsSessionManager}
+ */
+function manager(budgetMs) {
+  return new HlsSessionManager({
+    enabled: true,
+    ffmpegBin: "ffmpeg",
+    localBindHost: "127.0.0.1",
+    localPort: 9090,
+    keyframeTableBudgetMs: budgetMs
+  });
+}
+
+const FILE = { sourceKey: "torrent:abc", fileIndex: 0, logName: "a.mkv" };
+
+test("a table that arrives inside the budget is the answer", async () => {
+  const sessions = manager(1_000);
+  sessions.getContainerKeyframes = async () => ({ times: [0, 4, 8], tolerance: 0, format: "matroska" });
+
+  const answer = await sessions.readKeyframeTableWithin(FILE);
+
+  assert.deepEqual(answer.times, [0, 4, 8]);
+  assert.equal(answer.arrived, true, "the file has answered, so what it said may be written onto it");
+});
+
+test("a table that has not arrived gives up on copying rather than on the session", async () => {
+  const sessions = manager(60);
+  // The bytes it needs are still coming off the swarm. On the field host this
+  // is a torrent with one peer: the read was still waiting after two minutes.
+  sessions.getContainerKeyframes = () => new Promise(() => {});
+
+  const startedAt = Date.now();
+  const answer = await sessions.readKeyframeTableWithin(FILE);
+  const waited = Date.now() - startedAt;
+
+  assert.equal(answer.times, null, "no table, so this session cannot copy the picture");
+  assert.equal(
+    answer.arrived,
+    false,
+    "and it says the file has NOT answered — an absence written onto the file would make " +
+      "a passing shortage of bytes look like a property of the bytes"
+  );
+  assert.ok(waited < 2_000, `the wait ended at the bound, not at the read (${waited}ms)`);
+});
+
+test("the read goes on after the budget, so the next session of the file gets the copy", async () => {
+  const sessions = manager(40);
+  let reads = 0;
+  let answerLate = null;
+  sessions.getContainerKeyframes = () => {
+    reads += 1;
+    return new Promise((resolve) => {
+      answerLate = resolve;
+    });
+  };
+
+  const first = await sessions.readKeyframeTableWithin(FILE);
+  assert.equal(first.arrived, false);
+
+  answerLate({ times: [0, 5, 10], tolerance: 0, format: "matroska" });
+  await new Promise((resolve) => setTimeout(resolve, 10));
+
+  const second = await sessions.readKeyframeTableWithin(FILE);
+  assert.deepEqual(second.times, [0, 5, 10], "the late answer was kept, not thrown away");
+  assert.equal(second.arrived, true);
+  assert.equal(reads, 1, "and it was not read a second time");
+});
+
+test("a read that fails is not turned into a bounded wait's silence", async () => {
+  const sessions = manager(1_000);
+  sessions.getContainerKeyframes = async () => {
+    throw new Error("the head is not downloaded");
+  };
+
+  await assert.rejects(
+    () => sessions.readKeyframeTableWithin(FILE),
+    /the head is not downloaded/,
+    "a read that threw is a different thing from a read that is still running"
+  );
+});

package/test/run-intervals.test.js

@@ -61,7 +61,14 @@ function sessionOn({ id, dirPath, segmentCount = 100, runState = null, encodeSta
     get inputFile() { return this.file; },
     get audioFile() { return this.file; },
     segmentFormat: fmp4Format,
-    segmentCount,
+    // How the file is cut, held by the TIMELINE. A fixture that stated it on the
+    // session was describing a shape the product had left, and it kept a defect
+    // alive for a release: `session.segmentCount` is undefined on every real
+    // session, so runs were given no end and the coverage map had no length.
+    timeline: new Timeline({
+      boundaries: Array.from({ length: segmentCount + 1 }, (_, index) => index * 4),
+      cutGrid: "uniform"
+    }),
     runs: new Set(),
     consumers: new Set(),
     lastAccessedAt: Date.now()