@torrent-tv/proxy 2.9.64 → 2.9.66

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 2.9.66
+
+- **New**: The container keyframe index now covers **MP4/MOV and AVI** as well as Matroska. MP4 reads the sync-sample and time-to-sample tables from `moov` — found by stepping over top-level box headers, so it works whether `moov` sits at the file start or the end, without scanning the gigabytes of `mdat` between them (verified on a 2 GB field file: **1145 keyframes in 625 ms**). AVI reads the trailing `idx1` table, still worth having because older releases are largely XviD-in-AVI and are exactly the files served by copying rather than re-encoding. Formats left out are documented in the module with the reason: MPEG-TS/M2TS carry no index anywhere by design, fragmented MP4 spreads timing across fragments instead of one table, and FLV/ASF have tables but effectively never appear in these releases.
+
+## 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.

package/package.json

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

package/services/container-index/avi.js

@@ -0,0 +1,156 @@
+/**
+ * @file Keyframe index for AVI, read without downloading the file.
+ *
+ * AVI ends with an `idx1` chunk: one fixed-size entry per stream chunk, each
+ * carrying a flags word whose keyframe bit says whether that chunk starts a
+ * keyframe. Frame number times the video stream's frame duration gives the
+ * time, so the index alone is enough — no media has to be read.
+ *
+ * `idx1` lives at the end of the file and the top-level chunk headers state
+ * their sizes, so it is reached by stepping over headers (typically two hops:
+ * `LIST hdrl`, `LIST movi`), not by scanning.
+ *
+ * Still relevant despite the format's age: older releases are largely XviD in
+ * AVI, and those are exactly the files that get copied rather than re-encoded.
+ */
+
+const HEADER_BYTES = 8;
+const PROBE_BYTES = 4096;
+// Keyframe flag in an idx1 entry's flags word (AVIIF_KEYFRAME).
+const KEYFRAME_FLAG = 0x10;
+const IDX1_ENTRY_BYTES = 16;
+// Cap on the idx1 read. One entry per chunk, 16 bytes each — a long film runs
+// to a few MB; beyond this is not a normal index.
+const MAX_IDX1_BYTES = 64 * 1024 * 1024;
+
+/**
+ * Whether this looks like AVI: a RIFF container whose form type is `AVI `.
+ *
+ * @param {Buffer} head
+ * @returns {boolean}
+ */
+export function isAvi(head) {
+  return (
+    head.length >= 12 &&
+    head.toString("latin1", 0, 4) === "RIFF" &&
+    head.toString("latin1", 8, 12) === "AVI "
+  );
+}
+
+/**
+ * Microseconds per frame and the video stream's chunk id prefix, from the main
+ * header. Both live in the `hdrl` list near the file start.
+ *
+ * @param {Buffer} head
+ * @returns {{ microsecondsPerFrame: number } | null}
+ */
+function readMainHeader(head) {
+  // Top-level: "RIFF" size "AVI " then chunks. `avih` sits inside `LIST hdrl`.
+  let offset = 12;
+  while (offset + HEADER_BYTES <= head.length) {
+    const id = head.toString("latin1", offset, offset + 4);
+    const size = head.readUInt32LE(offset + 4);
+    if (size <= 0) {
+      return null;
+    }
+    if (id === "LIST") {
+      // Descend: list type follows the header, then its own chunks.
+      const listType = head.toString("latin1", offset + 8, offset + 12);
+      if (listType === "hdrl") {
+        let inner = offset + 12;
+        while (inner + HEADER_BYTES <= Math.min(head.length, offset + 8 + size)) {
+          const innerId = head.toString("latin1", inner, inner + 4);
+          const innerSize = head.readUInt32LE(inner + 4);
+          if (innerSize <= 0) {
+            return null;
+          }
+          if (innerId === "avih" && inner + 8 + 4 <= head.length) {
+            return { microsecondsPerFrame: head.readUInt32LE(inner + 8) };
+          }
+          inner += HEADER_BYTES + innerSize + (innerSize % 2);
+        }
+      }
+      offset += HEADER_BYTES + 4 + (size - 4) + ((size - 4) % 2);
+      continue;
+    }
+    offset += HEADER_BYTES + size + (size % 2);
+  }
+  return null;
+}
+
+/**
+ * Step over top-level chunks to find `idx1`.
+ *
+ * @param {(start: number, end: number) => Promise<Buffer | null>} readRange
+ * @param {number} fileSize
+ * @returns {Promise<{ offset: number, size: number } | null>}
+ */
+async function findIdx1(readRange, fileSize) {
+  let offset = 12; // Past "RIFF" size "AVI ".
+  while (offset + HEADER_BYTES < fileSize) {
+    const probe = await readRange(offset, Math.min(fileSize - 1, offset + HEADER_BYTES - 1));
+    if (!probe || probe.length < HEADER_BYTES) {
+      return null;
+    }
+    const id = probe.toString("latin1", 0, 4);
+    const size = probe.readUInt32LE(4);
+    if (size <= 0) {
+      return null;
+    }
+    if (id === "idx1") {
+      return { offset: offset + HEADER_BYTES, size };
+    }
+    // Chunks are word-aligned; a LIST carries its type inside the payload, so
+    // the same size arithmetic covers both cases.
+    offset += HEADER_BYTES + size + (size % 2);
+  }
+  return null;
+}
+
+/**
+ * Read the keyframe times of an AVI file.
+ *
+ * @param {(start: number, end: number) => Promise<Buffer | null>} readRange
+ * @param {number} fileSize
+ * @returns {Promise<number[] | null>} Ascending seconds, or null when the file
+ *   has no `idx1` (OpenDML-only index, interrupted write, damaged upload).
+ */
+export async function readAviKeyframeTimes(readRange, fileSize) {
+  const head = await readRange(0, Math.min(PROBE_BYTES - 1, fileSize - 1));
+  if (!head || !isAvi(head)) {
+    return null;
+  }
+  const mainHeader = readMainHeader(head);
+  if (!mainHeader || !mainHeader.microsecondsPerFrame) {
+    return null;
+  }
+
+  const idx1 = await findIdx1(readRange, fileSize);
+  if (!idx1 || idx1.size > MAX_IDX1_BYTES) {
+    return null;
+  }
+
+  const table = await readRange(idx1.offset, Math.min(fileSize - 1, idx1.offset + idx1.size - 1));
+  if (!table || table.length < IDX1_ENTRY_BYTES) {
+    return null;
+  }
+
+  const secondsPerFrame = mainHeader.microsecondsPerFrame / 1e6;
+  const times = [];
+  let videoFrame = 0;
+  for (let at = 0; at + IDX1_ENTRY_BYTES <= table.length; at += IDX1_ENTRY_BYTES) {
+    const chunkId = table.toString("latin1", at, at + 4);
+    // Video chunks are "##db" (uncompressed) or "##dc" (compressed); audio is
+    // "##wb" and must not advance the frame counter.
+    const isVideo = chunkId.endsWith("db") || chunkId.endsWith("dc");
+    if (!isVideo) {
+      continue;
+    }
+    const flags = table.readUInt32LE(at + 4);
+    if ((flags & KEYFRAME_FLAG) !== 0) {
+      times.push(videoFrame * secondsPerFrame);
+    }
+    videoFrame += 1;
+  }
+  return times.length > 0 ? times : null;
+}

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,102 @@
+/**
+ * @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. A playlist declaring an even grid instead is
+ * then false, and players punish it — either walking the whole file to rebuild
+ * the timeline, or presenting audio with no picture because a segment begins
+ * with nothing decodable (both seen in the field 2026-08-02; the file measured
+ * had 10.43 s keyframe spacing against our declared 4 s).
+ *
+ * Scanning for the answer 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 the table — this reads it with a couple
+ * of point reads (16 KB, 0.8 s for 570 keyframes on that same file).
+ *
+ * Transport-agnostic by construction: it takes a byte-range function and knows
+ * nothing about torrents, HTTP or our session model, which is what let it be
+ * verified standalone before being wired in.
+ */
+
+import { logger } from "../../utils/logger.js";
+import { isMatroska, readMatroskaKeyframeTimes } from "./matroska.js";
+import { isMp4, readMp4KeyframeTimes } from "./mp4.js";
+import { isAvi, readAviKeyframeTimes } from "./avi.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 every supported container from its opening bytes.
+const SNIFF_BYTES = 16;
+
+/**
+ * Container readers, in detection order. Each pairs a cheap magic-byte test
+ * with the reader for that format.
+ *
+ * Formats deliberately absent, and why:
+ *  - **MPEG-TS / M2TS** carry no index at all — the format is a continuous
+ *    broadcast stream with no table of contents anywhere. Nothing to read.
+ *  - **FLV / ASF-WMV** do have keyframe tables, but effectively never appear in
+ *    the releases this serves; adding them is mechanical if that changes.
+ *  - **Fragmented MP4** spreads its timing across fragments instead of a single
+ *    `moov` table; `readMp4KeyframeTimes` returns null for it rather than
+ *    guessing.
+ *
+ * @type {{ name: string, matches: (head: Buffer) => boolean, read: ReadRange extends never ? never : (readRange: ReadRange, fileSize: number) => Promise<number[] | null> }[]}
+ */
+const READERS = [
+  { name: "matroska", matches: isMatroska, read: readMatroskaKeyframeTimes },
+  { name: "mp4", matches: isMp4, read: readMp4KeyframeTimes },
+  { name: "avi", matches: isAvi, read: readAviKeyframeTimes }
+];
+
+/**
+ * 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;
+  let format = "unrecognised";
+  try {
+    const sniff = await readRange(0, Math.min(SNIFF_BYTES - 1, fileSize - 1));
+    if (!sniff) {
+      return null;
+    }
+    const reader = READERS.find((candidate) => candidate.matches(sniff));
+    if (reader) {
+      format = reader.name;
+      times = await reader.read(readRange, fileSize);
+    }
+  } catch (error) {
+    // A malformed or partially-downloaded index must never take playback down —
+    // it only means the grid is unknown, which the caller already 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 ${format} index in ${elapsedMs}ms for "${label}"`
+    );
+  } else {
+    logger.info(`container-index: no usable index for "${label}" (${format}, ${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/container-index/mp4.js

@@ -0,0 +1,246 @@
+/**
+ * @file Keyframe index for MP4/MOV, read without downloading the file.
+ *
+ * MP4 keeps its tables in a `moov` box: `stss` lists which samples are sync
+ * samples (keyframes) by number, and `stts` gives each sample's duration, so
+ * the two together turn "sample #N" into "second T". `moov` sits either at the
+ * start (files written for streaming) or at the end (the common case for a
+ * plain mux); box headers state their own size, so it is found by stepping over
+ * top-level boxes rather than scanning bytes — a couple of 64-byte reads even
+ * when `mdat` is gigabytes.
+ *
+ * Same purpose as the Matroska reader: on the video-COPY path the segment
+ * boundaries ARE the source's keyframes, and inventing an even grid instead
+ * makes players walk the whole file or present audio with no picture.
+ */
+
+// A 64-bit box size is signalled by a 32-bit size of 1, the real size following
+// in the next 8 bytes.
+const LARGE_SIZE_MARKER = 1;
+const HEADER_BYTES = 8;
+const LARGE_HEADER_BYTES = 16;
+// Enough to read any box header while walking the top level.
+const PROBE_BYTES = 64;
+// Cap on the moov read. A feature-length file indexes to a few hundred KB;
+// beyond this is not a normal index and not worth pulling over a torrent.
+const MAX_MOOV_BYTES = 32 * 1024 * 1024;
+
+/**
+ * Whether this looks like MP4/MOV — every real file opens with an `ftyp` box.
+ *
+ * @param {Buffer} head
+ * @returns {boolean}
+ */
+export function isMp4(head) {
+  return head.length >= 12 && head.toString("latin1", 4, 8) === "ftyp";
+}
+
+/**
+ * Read a box header at `offset`.
+ *
+ * @param {Buffer} buffer
+ * @param {number} offset
+ * @returns {{ type: string, size: number, headerBytes: number } | null}
+ */
+function readBoxHeader(buffer, offset) {
+  if (offset + HEADER_BYTES > buffer.length) {
+    return null;
+  }
+  const size32 = buffer.readUInt32BE(offset);
+  const type = buffer.toString("latin1", offset + 4, offset + 8);
+  if (size32 === LARGE_SIZE_MARKER) {
+    if (offset + LARGE_HEADER_BYTES > buffer.length) {
+      return null;
+    }
+    // High word is zero for any file we can practically handle.
+    const high = buffer.readUInt32BE(offset + 8);
+    const low = buffer.readUInt32BE(offset + 12);
+    return { type, size: high * 4294967296 + low, headerBytes: LARGE_HEADER_BYTES };
+  }
+  return { type, size: size32, headerBytes: HEADER_BYTES };
+}
+
+/**
+ * Walk the top-level boxes to find `moov`, reading only each box header.
+ *
+ * @param {(start: number, end: number) => Promise<Buffer | null>} readRange
+ * @param {number} fileSize
+ * @returns {Promise<{ offset: number, size: number, headerBytes: number } | null>}
+ */
+async function findMoov(readRange, fileSize) {
+  let offset = 0;
+  while (offset < fileSize) {
+    const probe = await readRange(offset, Math.min(fileSize - 1, offset + PROBE_BYTES - 1));
+    if (!probe || probe.length < HEADER_BYTES) {
+      return null;
+    }
+    const header = readBoxHeader(probe, 0);
+    // Size 0 means "extends to end of file" — legal only for the last box, and
+    // never for one we would step over.
+    if (!header || header.size <= 0) {
+      return null;
+    }
+    if (header.type === "moov") {
+      return { offset, size: header.size, headerBytes: header.headerBytes };
+    }
+    offset += header.size;
+  }
+  return null;
+}
+
+/**
+ * Find the first box of `type` directly inside a range of an already-read buffer.
+ *
+ * @param {Buffer} buffer
+ * @param {number} start
+ * @param {number} end
+ * @param {string} type
+ * @returns {{ dataOffset: number, end: number } | null}
+ */
+function findBox(buffer, start, end, type) {
+  let offset = start;
+  while (offset + HEADER_BYTES <= end) {
+    const header = readBoxHeader(buffer, offset);
+    if (!header || header.size <= 0) {
+      return null;
+    }
+    if (header.type === type) {
+      return { dataOffset: offset + header.headerBytes, end: Math.min(end, offset + header.size) };
+    }
+    offset += header.size;
+  }
+  return null;
+}
+
+/**
+ * All boxes of `type` directly inside a range.
+ *
+ * @param {Buffer} buffer
+ * @param {number} start
+ * @param {number} end
+ * @param {string} type
+ * @returns {{ dataOffset: number, end: number }[]}
+ */
+function findAllBoxes(buffer, start, end, type) {
+  const found = [];
+  let offset = start;
+  while (offset + HEADER_BYTES <= end) {
+    const header = readBoxHeader(buffer, offset);
+    if (!header || header.size <= 0) {
+      break;
+    }
+    if (header.type === type) {
+      found.push({ dataOffset: offset + header.headerBytes, end: Math.min(end, offset + header.size) });
+    }
+    offset += header.size;
+  }
+  return found;
+}
+
+/**
+ * Turn sample numbers into seconds using the time-to-sample table.
+ *
+ * `stts` is run-length encoded — pairs of (sample count, per-sample duration) —
+ * so one walk yields every sample's start time without expanding the table.
+ *
+ * @param {Buffer} buffer
+ * @param {{ dataOffset: number, end: number }} stts
+ * @param {number} timescale - Ticks per second.
+ * @param {Set<number>} wanted - Sample numbers (1-based).
+ * @returns {number[]} Seconds, ascending.
+ */
+function resolveSampleTimes(buffer, stts, timescale, wanted) {
+  const entryCount = buffer.readUInt32BE(stts.dataOffset + 4);
+  const times = [];
+  let sampleNumber = 1;
+  let ticks = 0;
+  let cursor = stts.dataOffset + 8;
+  for (let entry = 0; entry < entryCount && cursor + 8 <= stts.end; entry += 1) {
+    const count = buffer.readUInt32BE(cursor);
+    const delta = buffer.readUInt32BE(cursor + 4);
+    for (let index = 0; index < count; index += 1) {
+      if (wanted.has(sampleNumber)) {
+        times.push(ticks / timescale);
+      }
+      ticks += delta;
+      sampleNumber += 1;
+    }
+    cursor += 8;
+  }
+  return times;
+}
+
+/**
+ * Read the keyframe times of an MP4/MOV file.
+ *
+ * @param {(start: number, end: number) => Promise<Buffer | null>} readRange
+ * @param {number} fileSize
+ * @returns {Promise<number[] | null>} Ascending seconds, or null when the file
+ *   carries no usable index (fragmented MP4, truncated or damaged `moov`).
+ */
+export async function readMp4KeyframeTimes(readRange, fileSize) {
+  const moovBox = await findMoov(readRange, fileSize);
+  if (!moovBox || moovBox.size > MAX_MOOV_BYTES) {
+    return null;
+  }
+
+  const moov = await readRange(moovBox.offset, Math.min(fileSize - 1, moovBox.offset + moovBox.size - 1));
+  if (!moov || moov.length < moovBox.headerBytes) {
+    return null;
+  }
+
+  // Examine every track; the video one is whichever carries sync samples. A
+  // track with no `stss` has every sample a keyframe, so it constrains nothing
+  // and is skipped.
+  for (const trak of findAllBoxes(moov, moovBox.headerBytes, moov.length, "trak")) {
+    const mdia = findBox(moov, trak.dataOffset, trak.end, "mdia");
+    if (!mdia) {
+      continue;
+    }
+    const mdhd = findBox(moov, mdia.dataOffset, mdia.end, "mdhd");
+    if (!mdhd) {
+      continue;
+    }
+    // mdhd layout: version(1) + flags(3), then creation/modification times —
+    // 32-bit each in version 0, 64-bit in version 1 — then the timescale.
+    const version = moov[mdhd.dataOffset];
+    const timescaleOffset = version === 1 ? mdhd.dataOffset + 20 : mdhd.dataOffset + 12;
+    if (timescaleOffset + 4 > mdhd.end) {
+      continue;
+    }
+    const timescale = moov.readUInt32BE(timescaleOffset);
+    if (!timescale) {
+      continue;
+    }
+
+    const minf = findBox(moov, mdia.dataOffset, mdia.end, "minf");
+    const stbl = minf && findBox(moov, minf.dataOffset, minf.end, "stbl");
+    if (!stbl) {
+      continue;
+    }
+    const stss = findBox(moov, stbl.dataOffset, stbl.end, "stss");
+    const stts = findBox(moov, stbl.dataOffset, stbl.end, "stts");
+    if (!stss || !stts) {
+      continue;
+    }
+
+    const syncCount = moov.readUInt32BE(stss.dataOffset + 4);
+    const wanted = new Set();
+    for (let index = 0; index < syncCount; index += 1) {
+      const at = stss.dataOffset + 8 + index * 4;
+      if (at + 4 > stss.end) {
+        break;
+      }
+      wanted.add(moov.readUInt32BE(at));
+    }
+    if (wanted.size === 0) {
+      continue;
+    }
+
+    const times = resolveSampleTimes(moov, stts, timescale, wanted);
+    if (times.length > 0) {
+      return times;
+    }
+  }
+  return 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;
@@ -492,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",
@@ -735,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();
@@ -913,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) {
@@ -1157,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;