@torrent-tv/proxy 2.9.63 → 2.9.65

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 2.9.65
+
+- **Fix**: Segment boundaries on the video-COPY path are now the source's **real** keyframe positions, read from the container's own index (`services/container-index/`), instead of an invented 4 s grid. ffmpeg can only cut a copied stream at existing keyframes, so the declared grid was simply false — measured on a field file, the true keyframe spacing is **10.43 s**, meaning roughly two of every three declared boundaries could not exist. Players punish this in two ways, both seen in the field 2026-08-02: on a long file the player stops trusting the playlist and walks it from segment #1 to locate a seek (a 1:30 seek produced requests #1, #2, #45, #86 … #1187 and never arrived), and on a short one it presents **audio with no picture**, because a segment beginning without a keyframe has nothing to decode from.
+- **New**: `services/container-index/` — reads a file's keyframe table directly from the container (Matroska Cues today; MP4/AVI to follow) via two point reads: the head, to learn where the table lives, then the table itself. Measured against a 5.5 GB torrent-backed file: **570 keyframes in 0.8 s from 16 KB**, versus a full packet scan that found 77 in 45 s and never finished. Transport-agnostic by construction — it takes a byte-range function and knows nothing of torrents, HTTP or sessions — and cached per (source, file), so re-opens and seeks reuse the first read. Files with no readable index (live captures, interrupted writes, damaged uploads, MPEG-TS) return nothing and keep the previous fallback.
+
+## 2.9.64
+
+- **Fix**: The 2.9.63 pull-to-lowest-awaited-segment dragged the encoder to the start of the file. A seek to #1354 restarted at **#123** — the position of the *previous* watch — because requests outstanding from before the seek still counted toward `lowestAwaitedIndex`. Two fixes: the awaited floor is cleared the moment a new seek arrives (earlier requests describe where the player used to be, not where it is going), and the pull is bounded by `SEEK_PULL_LIMIT_SEGMENTS` (120) below the target — anything deeper is a leftover, not the preceding keyframe.
+
 ## 2.9.63
 
 - **Fix**: A seek landed the encoder on exactly the requested segment, which is the one position the player never asks for — so it produced files nobody was waiting for and playback hung. Per Apple HLS authoring guidance, a player given a position locates the nearest keyframe **preceding** it, decodes from there, and only then presents from the requested point; it therefore always fetches segments **below** the target. Measured on iOS: a seek to #1082 fetched from #1074 (8 back), one to #1358 fetched from #1301 (57 back) and asked for **nothing at or above** the target. The encoder now starts `SEEK_BACKOFF_SEGMENTS` (12) before the requested segment, and — since the needed depth varies and no fixed number covers it — is pulled down further to the lowest segment the player is actually waiting on, which its own requests report exactly (`lowestAwaitedIndex`). Only ever moves the start earlier, never later. Costs a few seconds of extra encoding per seek.

package/package.json

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

package/services/container-index/ebml-reader.js

@@ -0,0 +1,129 @@
+/**
+ * @file Minimal EBML reader — the encoding Matroska/WebM are built from.
+ *
+ * Only what a keyframe index needs: walk elements, read unsigned integers,
+ * descend into containers. Deliberately not a general EBML implementation.
+ *
+ * Why not the `ebml` npm package (MIT, otherwise fine): its decoder is a
+ * *stream* decoder — it must be fed the file from byte zero. We read two small
+ * ranges out of a multi-gigabyte torrent-backed file and never the whole thing,
+ * so a parser that starts mid-file is exactly what we need and exactly what it
+ * cannot do (verified 2026-08-02: feeding it the Cues range throws
+ * "Unrepresentable length"). The element encoding itself is small enough to
+ * implement directly, so we do — the shape follows the Matroska specification
+ * and the same logic those libraries implement.
+ */
+
+/**
+ * A variable-length integer, as EBML encodes both element ids and sizes.
+ *
+ * The first set bit of the leading byte marks the width: `1xxxxxxx` is one
+ * byte, `01xxxxxx` two, and so on up to eight. For a SIZE the marker bit is
+ * removed and the remainder is the value; for an ID the bytes are kept intact,
+ * because the id *is* those bytes (that is how `0x1C53BB6B` identifies Cues).
+ *
+ * @param {Buffer} buffer
+ * @param {number} offset
+ * @param {boolean} keepMarker - True for ids, false for sizes.
+ * @returns {{ value: number, length: number } | null} Null when truncated or malformed.
+ */
+export function readVint(buffer, offset, keepMarker) {
+  if (offset >= buffer.length) {
+    return null;
+  }
+  const first = buffer[offset];
+  if (first === 0) {
+    return null; // No marker bit in the first byte: not a valid vint start.
+  }
+  let length = 1;
+  let mask = 0x80;
+  while (length <= 8 && (first & mask) === 0) {
+    length += 1;
+    mask >>= 1;
+  }
+  if (length > 8 || offset + length > buffer.length) {
+    return null;
+  }
+  let value = keepMarker ? first : first & (mask - 1);
+  for (let index = 1; index < length; index += 1) {
+    // Values beyond 2^53 cannot be represented exactly; sizes and positions in
+    // real files stay far below that, so plain arithmetic is safe here.
+    value = value * 256 + buffer[offset + index];
+  }
+  return { value, length };
+}
+
+/**
+ * Iterate the elements directly inside `buffer`, without descending.
+ *
+ * Yields each element's id, the offset of its payload and its size. An element
+ * whose payload runs past the end of the buffer is still yielded (its header is
+ * intact and the caller may only need the id), but iteration stops after it.
+ *
+ * @param {Buffer} buffer
+ * @param {number} [start=0]
+ * @param {number} [end=buffer.length]
+ * @yields {{ id: number, dataOffset: number, size: number }}
+ */
+export function* iterateElements(buffer, start = 0, end = buffer.length) {
+  let offset = start;
+  while (offset < end) {
+    const id = readVint(buffer, offset, true);
+    if (!id) {
+      return;
+    }
+    const size = readVint(buffer, offset + id.length, false);
+    if (!size) {
+      return;
+    }
+    const dataOffset = offset + id.length + size.length;
+    yield { id: id.value, dataOffset, size: size.value };
+    if (dataOffset + size.value > end) {
+      return; // Truncated payload — nothing dependable follows it.
+    }
+    offset = dataOffset + size.value;
+  }
+}
+
+/**
+ * Read an EBML unsigned integer payload (big-endian, variable width).
+ *
+ * @param {Buffer} buffer
+ * @param {number} offset
+ * @param {number} size
+ * @returns {number}
+ */
+export function readUint(buffer, offset, size) {
+  let value = 0;
+  for (let index = 0; index < size; index += 1) {
+    value = value * 256 + buffer[offset + index];
+  }
+  return value;
+}
+
+/**
+ * Depth-first search for the first element with `id`, descending only into the
+ * container ids listed in `descendInto`.
+ *
+ * @param {Buffer} buffer
+ * @param {number} id - Element id to find.
+ * @param {number[]} descendInto - Container ids worth entering.
+ * @param {number} [start=0]
+ * @param {number} [end=buffer.length]
+ * @returns {{ dataOffset: number, size: number } | null}
+ */
+export function findElement(buffer, id, descendInto, start = 0, end = buffer.length) {
+  for (const element of iterateElements(buffer, start, end)) {
+    if (element.id === id) {
+      return { dataOffset: element.dataOffset, size: element.size };
+    }
+    if (descendInto.includes(element.id)) {
+      const limit = Math.min(end, element.dataOffset + element.size);
+      const found = findElement(buffer, id, descendInto, element.dataOffset, limit);
+      if (found) {
+        return found;
+      }
+    }
+  }
+  return null;
+}

package/services/container-index/index.js

@@ -0,0 +1,76 @@
+/**
+ * @file Container keyframe index — where a file's real keyframes are, read
+ * from the container's own tables rather than by scanning the media.
+ *
+ * The problem it solves: on the video-COPY path ffmpeg can only cut segments at
+ * the source's existing keyframes. If our playlist declares an even grid
+ * instead, the declared times do not match the media, and players respond by
+ * either walking the whole file to rebuild the timeline or showing audio with
+ * no picture (both seen in the field 2026-08-02). Getting those positions by
+ * decoding is not an option here — the file is served from a torrent, and a
+ * full packet scan of 5.5 GB found 77 keyframes in 45 s without finishing.
+ *
+ * Containers already store this. The reader takes a byte-range function and
+ * does a couple of point reads, so it works over any transport and knows
+ * nothing about torrents, HTTP or our session model.
+ *
+ * Format support is deliberately partial: a container we cannot index returns
+ * null, and the caller falls back (re-encode with forced keyframes, which is
+ * what Jellyfin, hls-media-server and hls-vod-too all do unconditionally).
+ */
+
+import { logger } from "../../utils/logger.js";
+import { isMatroska, readMatroskaKeyframeTimes } from "./matroska.js";
+
+/**
+ * @callback ReadRange
+ * @param {number} start - First byte, inclusive.
+ * @param {number} end - Last byte, inclusive.
+ * @returns {Promise<Buffer | null>} The bytes, or null when unavailable.
+ */
+
+// Enough to identify any supported container from its magic bytes.
+const SNIFF_BYTES = 16;
+
+/**
+ * Read a file's keyframe times from its container index.
+ *
+ * @param {object} params
+ * @param {ReadRange} params.readRange
+ * @param {number} params.fileSize
+ * @param {string} [params.label] - For logging only.
+ * @returns {Promise<number[] | null>} Ascending seconds, or null when this file
+ *   has no readable index — the caller must then not claim to know the grid.
+ */
+export async function readKeyframeIndex({ readRange, fileSize, label = "" }) {
+  if (typeof readRange !== "function" || !Number.isFinite(fileSize) || fileSize <= 0) {
+    return null;
+  }
+
+  const startedAt = Date.now();
+  let times = null;
+  try {
+    const sniff = await readRange(0, Math.min(SNIFF_BYTES - 1, fileSize - 1));
+    if (!sniff) {
+      return null;
+    }
+    if (isMatroska(sniff)) {
+      times = await readMatroskaKeyframeTimes(readRange, fileSize);
+    }
+    // Other containers fall through as null until their readers land; MP4's
+    // sync-sample table and AVI's index are the next candidates.
+  } catch (error) {
+    // A malformed or partially-downloaded index must never take playback down —
+    // it only means we do not know the grid, which the caller handles.
+    logger.warn(`container-index: failed to read index for "${label}": ${error?.message ?? error}`);
+    return null;
+  }
+
+  const elapsedMs = Date.now() - startedAt;
+  if (times) {
+    logger.info(`container-index: ${times.length} keyframes from the container index in ${elapsedMs}ms for "${label}"`);
+  } else {
+    logger.info(`container-index: no usable index for "${label}" (${elapsedMs}ms)`);
+  }
+  return times;
+}

package/services/container-index/matroska.js

@@ -0,0 +1,200 @@
+/**
+ * @file Keyframe index for Matroska (MKV/WebM), read without downloading the file.
+ *
+ * Matroska stores a Cues element — a table of "at time T, a keyframe starts at
+ * byte P" — and a SeekHead near the start listing where each top-level element
+ * lives. So two point reads suffice: the head, to learn where Cues is, then
+ * Cues itself. Measured on a 5.5 GB torrent-backed file: 4 KB + 12 KB, both
+ * effectively instant, versus a full packet scan that found 77 keyframes in
+ * 45 s and never finished.
+ *
+ * This matters because on the video-COPY path the encoder can only cut on the
+ * source's own keyframes. A playlist declaring an even grid is then a lie, and
+ * players react badly to it — either walking the whole file to rebuild the
+ * timeline, or presenting audio with no picture because a segment begins with
+ * no keyframe to decode from (both observed in the field 2026-08-02).
+ */
+
+import { findElement, iterateElements, readUint } from "./ebml-reader.js";
+
+// Element ids, from the Matroska specification.
+const ID_SEGMENT = 0x18538067;
+const ID_SEEK_HEAD = 0x114d9b74;
+const ID_SEEK = 0x4dbb;
+const ID_SEEK_ID = 0x53ab;
+const ID_SEEK_POSITION = 0x53ac;
+const ID_INFO = 0x1549a966;
+const ID_TIMESTAMP_SCALE = 0x2ad7b1;
+const ID_CUES = 0x1c53bb6b;
+const ID_CUE_POINT = 0xbb;
+const ID_CUE_TIME = 0xb3;
+
+// How much of the file start to read. Must cover the EBML header, the SeekHead
+// and Info; 64 KB is generous for every real muxer (the file measured needed
+// under 4 KB) while still trivial to fetch.
+const HEAD_BYTES = 64 * 1024;
+// Cap on the Cues read. A two-hour film indexes to tens of KB; anything beyond
+// this is not a normal index and not worth pulling over a torrent.
+const MAX_CUES_BYTES = 8 * 1024 * 1024;
+// Matroska's default timestamp scale (nanoseconds per tick) when Info omits it.
+const DEFAULT_TIMESTAMP_SCALE = 1_000_000;
+
+/**
+ * Whether this looks like a Matroska file (the EBML magic `0x1A45DFA3`).
+ *
+ * @param {Buffer} head
+ * @returns {boolean}
+ */
+export function isMatroska(head) {
+  return head.length >= 4 && head.readUInt32BE(0) === 0x1a45dfa3;
+}
+
+/**
+ * Locate the Segment element and the SeekHead entries inside it.
+ *
+ * Seek positions are relative to the start of Segment's payload, not to the
+ * file, so that base has to come back with them.
+ *
+ * @param {Buffer} head
+ * @returns {{ segmentDataOffset: number, entries: Map<number, number> } | null}
+ */
+function readSeekHead(head) {
+  let segmentDataOffset = -1;
+  for (const element of iterateElements(head)) {
+    if (element.id === ID_SEGMENT) {
+      segmentDataOffset = element.dataOffset;
+      break;
+    }
+  }
+  if (segmentDataOffset < 0) {
+    return null;
+  }
+
+  const seekHead = findElement(head, ID_SEEK_HEAD, [], segmentDataOffset);
+  if (!seekHead) {
+    return null;
+  }
+
+  const entries = new Map();
+  const seekHeadEnd = Math.min(head.length, seekHead.dataOffset + seekHead.size);
+  for (const seek of iterateElements(head, seekHead.dataOffset, seekHeadEnd)) {
+    if (seek.id !== ID_SEEK) {
+      continue;
+    }
+    const seekEnd = Math.min(seekHeadEnd, seek.dataOffset + seek.size);
+    let targetId = null;
+    let position = null;
+    for (const field of iterateElements(head, seek.dataOffset, seekEnd)) {
+      if (field.id === ID_SEEK_ID) {
+        targetId = readUint(head, field.dataOffset, field.size);
+      } else if (field.id === ID_SEEK_POSITION) {
+        position = readUint(head, field.dataOffset, field.size);
+      }
+    }
+    if (targetId !== null && position !== null) {
+      entries.set(targetId, position);
+    }
+  }
+  return { segmentDataOffset, entries };
+}
+
+/**
+ * Timestamp scale (nanoseconds per tick) declared in Info, or the default.
+ *
+ * @param {Buffer} head
+ * @param {number} segmentDataOffset
+ * @returns {number}
+ */
+function readTimestampScale(head, segmentDataOffset) {
+  const info = findElement(head, ID_INFO, [], segmentDataOffset);
+  if (!info) {
+    return DEFAULT_TIMESTAMP_SCALE;
+  }
+  const infoEnd = Math.min(head.length, info.dataOffset + info.size);
+  for (const field of iterateElements(head, info.dataOffset, infoEnd)) {
+    if (field.id === ID_TIMESTAMP_SCALE) {
+      const scale = readUint(head, field.dataOffset, field.size);
+      return scale > 0 ? scale : DEFAULT_TIMESTAMP_SCALE;
+    }
+  }
+  return DEFAULT_TIMESTAMP_SCALE;
+}
+
+/**
+ * Cue times (seconds, ascending) from a Cues payload.
+ *
+ * @param {Buffer} cues
+ * @param {number} timestampScale - Nanoseconds per tick.
+ * @returns {number[]}
+ */
+function readCueTimes(cues, timestampScale) {
+  const times = [];
+  const secondsPerTick = timestampScale / 1e9;
+  for (const point of iterateElements(cues)) {
+    if (point.id !== ID_CUE_POINT) {
+      continue;
+    }
+    const pointEnd = Math.min(cues.length, point.dataOffset + point.size);
+    for (const field of iterateElements(cues, point.dataOffset, pointEnd)) {
+      if (field.id === ID_CUE_TIME) {
+        times.push(readUint(cues, field.dataOffset, field.size) * secondsPerTick);
+        break;
+      }
+    }
+  }
+  times.sort((left, right) => left - right);
+  return times;
+}
+
+/**
+ * Read the keyframe times of a Matroska file using only two point reads.
+ *
+ * @param {(start: number, end: number) => Promise<Buffer | null>} readRange
+ *   Inclusive byte range reader; returns null when the range is unavailable.
+ * @param {number} fileSize
+ * @returns {Promise<number[] | null>} Ascending seconds, or null when the file
+ *   carries no usable index (see the module doc for when that happens).
+ */
+export async function readMatroskaKeyframeTimes(readRange, fileSize) {
+  const head = await readRange(0, Math.min(HEAD_BYTES, Math.max(0, fileSize - 1)));
+  if (!head || !isMatroska(head)) {
+    return null;
+  }
+
+  const seekHead = readSeekHead(head);
+  if (!seekHead) {
+    return null; // No SeekHead — a streamed or truncated mux.
+  }
+
+  const cuesRelative = seekHead.entries.get(ID_CUES);
+  if (cuesRelative === undefined) {
+    return null; // Indexless file: live capture, interrupted write, damaged upload.
+  }
+
+  // SeekHead positions are relative to Segment's payload.
+  const cuesOffset = seekHead.segmentDataOffset + cuesRelative;
+  if (!Number.isFinite(cuesOffset) || cuesOffset <= 0 || cuesOffset >= fileSize) {
+    return null;
+  }
+
+  // The element header states the payload size, but reading it costs a round
+  // trip; fetch a bounded window instead and let the parser stop at the end of
+  // what it got. Cues sits near the file end, so the window is clamped there.
+  const cuesEnd = Math.min(fileSize - 1, cuesOffset + MAX_CUES_BYTES);
+  const cuesChunk = await readRange(cuesOffset, cuesEnd);
+  if (!cuesChunk || cuesChunk.length === 0) {
+    return null;
+  }
+
+  // The window starts exactly at the Cues element, so its own header comes
+  // first; step over it to reach the CuePoints.
+  const cuesElement = [...iterateElements(cuesChunk, 0, cuesChunk.length)][0];
+  if (!cuesElement || cuesElement.id !== ID_CUES) {
+    return null;
+  }
+  const payloadEnd = Math.min(cuesChunk.length, cuesElement.dataOffset + cuesElement.size);
+  const payload = cuesChunk.subarray(cuesElement.dataOffset, payloadEnd);
+
+  const times = readCueTimes(payload, readTimestampScale(head, seekHead.segmentDataOffset));
+  return times.length > 0 ? times : null;
+}

package/services/hls-session-manager.js

@@ -16,6 +16,7 @@ import { randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
 import { logger } from "../utils/logger.js";
+import { readKeyframeIndex } from "./container-index/index.js";
 
 /** Own package version, stamped onto session-start log lines. */
 const PROXY_VERSION = createRequire(import.meta.url)("../package.json").version;
@@ -85,6 +86,13 @@ const ENCODER_STALL_MS = 12_000;
 // player is actually waiting on when that is lower still. Costs a few seconds
 // of extra encoding per seek.
 const SEEK_BACKOFF_SEGMENTS = 12;
+// Hard limit on how far below the requested segment the start may be pulled by
+// `lowestAwaitedIndex`. Without it a stale request from earlier playback drags
+// the encoder across the whole file: field 2026-08-02, a seek to #1354 was
+// pulled to #123 — the start of the previous watch — because requests from
+// before the seek were still counted. Anything deeper than this is not the
+// preceding keyframe, it is a leftover.
+const SEEK_PULL_LIMIT_SEGMENTS = 120;
 const SEEK_SETTLE_MS = 1_200;
 // Hard cap on the total settle wait, measured from the first far request of a
 // burst, so a still-moving scrubber cannot delay a genuine seek forever.
@@ -485,6 +493,17 @@ async function probeVideoKeyframeTimes(ffmpegBin, inputUrl, timeoutMs = 25_000)
         ffprobeBinFor(ffmpegBin),
         [
           "-v", "error",
+          // `-skip_frame nokey` makes the decoder discard non-keyframes, so the
+          // probe reads only what it needs. Without it a full packet scan of a
+          // ~5 GB MKV cannot finish inside any sane budget over a torrent-backed
+          // input, the probe returns nothing, and the playlist falls back to a
+          // uniform grid — which on the COPY path is a lie: cuts land on the
+          // source's real keyframes, not on a 4 s ruler. The player then finds
+          // the declared times do not match the media, stops trusting the
+          // playlist and walks the file from segment #1 to locate the seek
+          // position by hand (field 2026-08-02: a seek to 1:30 produced requests
+          // #1, #2, #45, #86, #123 … #1187, taking minutes and never arriving).
+          "-skip_frame", "nokey",
           "-select_streams", "v:0",
           "-show_entries", "packet=pts_time,flags",
           "-of", "csv=p=0",
@@ -728,6 +747,11 @@ export class HlsSessionManager {
     this.startupWaitMs = startupWaitMs;
     this.localBaseUrl = buildHttpBaseUrl(localBindHost, localPort);
     this.sessionsById = new Map();
+    // Container keyframe index per (source, file). Immutable per file, so one
+    // read serves every session, re-open and seek. Null means "this file has no
+    // readable index" and is cached too — no point retrying a scan that cannot
+    // succeed.
+    this.keyframeIndexCache = new Map();
     this.sessionIdBySource = new Map();
     this.cleanupTimer = setInterval(() => {
       void this.cleanupExpired();
@@ -906,12 +930,22 @@ export class HlsSessionManager {
       // packet scan time out and fall back to a uniform grid, so this never adds
       // more than ~6 s to session start.
       const keyframeStartMs = Date.now();
-      keyframeTimes = await probeVideoKeyframeTimes(this.ffmpegBin, inputUrl.toString(), 6_000);
+      // Read the container's OWN keyframe table (Cues/stss) rather than
+      // scanning the media. On the copy path ffmpeg can only cut at the
+      // source's existing keyframes, so these times ARE the segment
+      // boundaries — declaring an even grid instead is a falsehood the player
+      // punishes: it walks the whole file to rebuild the timeline, or presents
+      // audio with no picture because a segment starts with nothing decodable
+      // (both field-observed 2026-08-02). Scanning cannot supply them here —
+      // 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).
+      keyframeTimes = await this.#readContainerKeyframes({ sourceKey, fileIndex, inputUrl, logName });
       keyframeMs = Date.now() - keyframeStartMs;
       if (!keyframeTimes) {
         logger.warn(
-          `transcode ${sessionId}: keyframe probe unavailable; using uniform grid ` +
-            `for "${logName}" (seek precision may be reduced)`
+          `transcode ${sessionId}: no container keyframe index for "${logName}"; ` +
+            `falling back to a uniform grid — segment boundaries will not match the media`
         );
       }
     } else if (hasDuration && transcodeVideo) {
@@ -1150,6 +1184,56 @@ export class HlsSessionManager {
    *   spans `[boundaries[i], boundaries[i+1])`.
    * @returns {string}
    */
+  /**
+   * Keyframe times for a source file, from the container's own index.
+   *
+   * Cached per (source, file) because the answer never changes for a given
+   * file: a second session, a re-open or a seek all reuse the first read
+   * instead of repeating it.
+   *
+   * Reads byte ranges through the proxy's own /stream route, so it goes through
+   * the same torrent piece prioritisation as everything else and needs no
+   * separate access path.
+   *
+   * @param {{ sourceKey: string, fileIndex: number, inputUrl: URL, logName: string }} params
+   * @returns {Promise<number[] | null>} Ascending seconds, or null when this
+   *   file carries no readable index.
+   */
+  async #readContainerKeyframes({ sourceKey, fileIndex, inputUrl, logName }) {
+    const cacheKey = `${sourceKey}:${fileIndex}`;
+    if (this.keyframeIndexCache.has(cacheKey)) {
+      return this.keyframeIndexCache.get(cacheKey);
+    }
+
+    const url = inputUrl.toString();
+    let fileSize = 0;
+    try {
+      const head = await fetch(url, { method: "HEAD" });
+      fileSize = Number(head.headers.get("content-length")) || 0;
+    } catch {
+      return null;
+    }
+    if (fileSize <= 0) {
+      return null;
+    }
+
+    const readRange = async (start, end) => {
+      try {
+        const response = await fetch(url, { headers: { Range: `bytes=${start}-${end}` } });
+        if (!response.ok && response.status !== 206) {
+          return null;
+        }
+        return Buffer.from(await response.arrayBuffer());
+      } catch {
+        return null;
+      }
+    };
+
+    const times = await readKeyframeIndex({ readRange, fileSize, label: logName });
+    this.keyframeIndexCache.set(cacheKey, times);
+    return times;
+  }
+
   #buildVodPlaylist(boundaries) {
     const count = Math.max(0, boundaries.length - 1);
     let maxDuration = 0;
@@ -2063,6 +2147,10 @@ export class HlsSessionManager {
     // player needs a segment containing the preceding keyframe, so one that
     // begins exactly at the target is useless to it.
     const startIndex = Math.max(0, index - SEEK_BACKOFF_SEGMENTS);
+    // A new seek invalidates everything the player was waiting for before it:
+    // those requests describe where it USED to be. Clearing here is what keeps
+    // the pull below anchored to this seek.
+    session.lowestAwaitedIndex = -1;
     logger.info(
       `transcode ${session.id} viewer seek to ${positionSeconds.toFixed(1)}s → segment #${index}, ` +
         `starting at #${startIndex} (${SEEK_BACKOFF_SEGMENTS} back for the preceding keyframe)`
@@ -2168,7 +2256,8 @@ export class HlsSessionManager {
     // requests say exactly how far back it needs the keyframe, so honour that
     // rather than a guess. Only ever pulls the start EARLIER, never later.
     const awaited = session.lowestAwaitedIndex;
-    const effectiveTarget = awaited >= 0 && awaited < target ? awaited : target;
+    const pullFloor = Math.max(0, target - SEEK_PULL_LIMIT_SEGMENTS);
+    const effectiveTarget = awaited >= pullFloor && awaited < target ? awaited : target;
     if (effectiveTarget !== target) {
       logger.info(
         `transcode ${session.id} pulling encode start #${target} → #${effectiveTarget} ` +