@torrent-tv/proxy 2.88.5 → 2.89.0

package/services/media/container/MatroskaContainer.js

@@ -7,15 +7,29 @@
  *  - FlagDefault 0x88 default 1, declaresDefault tracks whether element was written
  *  - FlagForced 0x55AA only for subtitles, FlagHearingImpaired 0x55AB, FlagVisualImpaired 0x55AC,
  *    FlagTextDescriptions 0x55AD, FlagOriginal 0x55AE, FlagCommentary 0x55AF
- *  - Language 0x22B59C default "eng", LanguageBCP47 0x22B59D MUST — when present, Language ignored
+ *  - Language 0x22B59C default "eng" (RFC 8794 §11.1.19: an element equal to its
+ *    default need not be written, and the reader MUST read the default),
+ *    LanguageBCP47 0x22B59D MUST — when present, Language ignored
  *  - CodecID 0x86, CodecPrivate 0x63A2, Name 0x536E, TrackType 0x83 (1 video, 2 audio, 17 subtitle)
  *
- * Byte-level EBML element walking is `ebml-reader.js`, which is the format's
- * grammar and not this container's own statements. Everything Matroska DOES
- * state about itself — the Tracks walk, the Cues, the keyframe times they name,
- * the cluster positions, the blocks inside a cluster —
- * is read in this module: each of those is RFC 9559 speaking about Matroska,
- * and the class is the only way in.
+ * **One reading of each thing the file states, kept on the container.** The
+ * layout of the Segment, the Tracks element and the Cues table are each read
+ * once and kept — and only once they have been read whole: a read whose bytes
+ * have not arrived throws `BytesUnavailable` and leaves nothing behind
+ * (`unavailable.js`). The keyframe times and the subtitle plan are both taken
+ * from the one Cues reading. Until 2026-10-01 the Cues table was read three
+ * times by three functions, the subtitle one kept a read that had not arrived
+ * as "no clusters", and an embedded track showed nothing for a whole session.
+ *
+ * **Read where it lies.** Elements are found by walking the Segment's top-level
+ * headers, not by hoping they fit a head window, and read a portion at a time
+ * through `ebml-stream.js` — so a large Tracks element or Cues table is read by
+ * its own size and never cut short by a bound of ours.
+ *
+ * Byte-level EBML grammar is `ebml-reader.js` and `ebml-stream.js`; the clusters
+ * found from downloaded bytes are `matroska-clusters.js`. Everything Matroska
+ * states about itself is read in this module or that one, and the class is the
+ * only way in.
  */
 
 import { Container } from "./Container.js";
@@ -24,18 +38,14 @@ import { AudioTrack } from "../tracks/AudioTrack.js";
 import { TextSubtitleTrack, TEXT_CODECS_MATROSKA } from "../tracks/TextSubtitleTrack.js";
 import { ImageSubtitleTrack } from "../tracks/ImageSubtitleTrack.js";
 import { ContainerTrack } from "../tracks/ContainerTrack.js";
-import { findElement, iterateElements, readFloat, readUint, readVint } from "./ebml-reader.js";
+import { iterateElements, readFloat, readUint, readVint } from "./ebml-reader.js";
+import { ElementReader, sizeIsUnknown } from "./ebml-stream.js";
+import { firstFrameOffset, readBlockHeader, walkHeldClusters } from "./matroska-clusters.js";
 
+/** Enough to hold the EBML header and the Segment's own header. */
 const HEAD_BYTES = 64 * 1024;
-/** Enough to read any cluster's own element header. */
-const CLUSTER_HEADER_PROBE = 64;
-/**
- * The largest cluster this will read whole. Real muxers write clusters of a few
- * megabytes; anything past this is not a cluster boundary we recognised and
- * reading it would be a large read for nothing.
- */
-const MAX_CLUSTER_BYTES = 32 * 1024 * 1024;
 
+const ID_EBML = 0x1a45dfa3;
 const ID_SEGMENT = 0x18538067;
 const ID_SEEK_HEAD = 0x114d9b74;
 const ID_SEEK = 0x4dbb;
@@ -45,17 +55,17 @@ const ID_INFO = 0x1549a966;
 const ID_TIMESTAMP_SCALE = 0x2ad7b1;
 const ID_DURATION = 0x4489;
 const ID_CLUSTER = 0x1f43b675;
+const ID_CUES = 0x1c53bb6b;
+const ID_CUE_POINT = 0xbb;
+const ID_CUE_TIME = 0xb3;
+const ID_CUE_TRACK_POSITIONS = 0xb7;
+const ID_CUE_TRACK = 0xf7;
+const ID_CUE_CLUSTER_POSITION = 0xf1;
 const ID_TIMESTAMP = 0xe7;
 const ID_SIMPLE_BLOCK = 0xa3;
 const ID_BLOCK_GROUP = 0xa0;
-/** RFC 9559 §5.1.2.1: nanoseconds per tick when Info omits TimestampScale. */
-const DEFAULT_TIMESTAMP_SCALE = 1_000_000;
-/**
- * How much to read at a cluster whose position came from the SeekHead. A
- * cluster's Timestamp is the first child every muxer writes, so this only has
- * to cover the element header and that one field.
- */
-const CLUSTER_PROBE_BYTES = 4 * 1024;
+const ID_BLOCK = 0xa1;
+const ID_BLOCK_DURATION = 0x9b;
 const ID_TRACKS = 0x1654ae6b;
 const ID_TRACK_ENTRY = 0xae;
 const ID_TRACK_NUMBER = 0xd7;
@@ -81,6 +91,16 @@ const ID_DISPLAY_WIDTH = 0x54b0;
 const ID_DISPLAY_HEIGHT = 0x54ba;
 const ID_SAMPLING_FREQUENCY = 0xb5;
 const ID_CHANNELS = 0x9f;
+
+/** RFC 9559 §5.1.2.1: nanoseconds per tick when Info omits TimestampScale. */
+const DEFAULT_TIMESTAMP_SCALE = 1_000_000;
+/** RFC 9559 §5.1.4.1.19: what an absent or empty `Language` element means. */
+const DEFAULT_LANGUAGE = "eng";
+
+const TRACK_TYPE_VIDEO = 1;
+const TRACK_TYPE_AUDIO = 2;
+const TRACK_TYPE_SUBTITLE = 17;
+
 /**
  * ReadOrder, Layer, Style, Name, MarginL, MarginR, MarginV, Effect — the eight
  * fields Matroska writes before the text of an SSA/ASS event. See
@@ -92,7 +112,35 @@ function readString(buf, el) {
   return buf.toString("utf8", el.dataOffset, el.dataOffset + el.size).replace(/\0+$/, "");
 }
 
+/**
+ * @typedef {object} SegmentLayout
+ * @property {number} segmentDataOffset - Where the Segment's data begins.
+ * @property {number} segmentEnd - One past its last byte (the file's end for an
+ *   unknown-sized Segment).
+ * @property {number} secondsPerTick
+ * @property {number | null} infoAt - Positions of the top-level elements, from
+ *   the walk to the first cluster or from the SeekHead.
+ * @property {number | null} tracksAt
+ * @property {number | null} cuesAt
+ * @property {number | null} firstClusterAt
+ */
+
 export class MatroskaContainer extends Container {
+  /** @type {Buffer | null} */
+  #head = null;
+
+  /** @type {SegmentLayout | null} */
+  #layout = null;
+
+  /** @type {Array<import("../tracks/ContainerTrack.js").ContainerTrack> | null} */
+  #tracks = null;
+
+  /**
+   * The Cues reading: undefined until read, null when the file has none.
+   * @type {{ points: Array<{ ticks: number, positions: Array<{ track: number, clusterAt: number }> }> } | null | undefined}
+   */
+  #cues = undefined;
+
   get formatName() {
     return "matroska";
   }
@@ -104,47 +152,29 @@ export class MatroskaContainer extends Container {
   /**
    * The keyframe times this container's own index states, in ascending seconds.
    *
-   * Static so a caller that has bytes and no container can ask; the instance
-   * form is {@link Container#readKeyframeIndex}.
+   * Static so a caller that has bytes and no container can ask; the reading is
+   * the instance's, over a container built for the purpose.
    *
    * @param {(start:number,end:number)=>Promise<Buffer|null>} readRange
    * @param {number} fileSize
    * @returns {Promise<number[]|null>} Null where the container has no index.
    */
-  static readKeyframeTimes(readRange, fileSize) {
-    return readMatroskaKeyframeTimes(readRange, fileSize);
+  static async readKeyframeTimes(readRange, fileSize) {
+    const index = await new MatroskaContainer({ readRange, fileSize }).parseKeyframeIndex();
+    return index ? index.times : null;
   }
 
   /**
-   * This container's subtitle tracks, its Cues table and the cluster positions
-   * they name — RFC 9559 §5.1.4 and §5.1.3.
-   *
    * @param {(start:number,end:number)=>Promise<Buffer|null>} readRange
    * @param {number} fileSize
    * @returns {Promise<object|null>}
    */
   static readSubtitlePlan(readRange, fileSize) {
-    return readSubtitlePlan(readRange, fileSize);
+    return new MatroskaContainer({ readRange, fileSize }).readSubtitlePlan();
   }
 
   /**
-   * The same reading, over the file this container was built on.
-   *
-   * The static form exists for a caller that has bytes and no container; this
-   * is the one to use otherwise, because the reader is already here.
-   *
-   * @returns {Promise<object|null>}
-   */
-  readSubtitlePlan() {
-    return MatroskaContainer.readSubtitlePlan(this.readRange, this.fileSize);
-  }
-
-  /**
-   * The blocks one track has inside a cluster, with their times.
-   *
-   * The payload is handed back as BYTES: what those bytes mean is
-   * {@link MatroskaContainer.cueTextOf}'s answer, and this method's subject is
-   * only where a block sits and how long it lasts.
+   * The blocks one track has inside a cluster held whole in a buffer.
    *
    * @param {Buffer} bytes - The cluster, from its own element header onward.
    * @param {number} trackNumber
@@ -159,9 +189,6 @@ export class MatroskaContainer extends Container {
    * The blocks one track has inside a cluster whose bounds are already known —
    * RFC 9559 §5.1.3.4 (SimpleBlock) and §5.1.3.5 (BlockGroup).
    *
-   * The same reading as {@link MatroskaContainer.blocksInCluster}, entered where
-   * the caller has already parsed the cluster's own header.
-   *
    * @param {Buffer} buffer
    * @param {{ dataOffset: number, size: number }} cluster
    * @param {number} trackNumber
@@ -172,13 +199,132 @@ export class MatroskaContainer extends Container {
     return blocksOfTrack(buffer, cluster, trackNumber, secondsPerTick);
   }
 
+  /**
+   * A reader for the inside of one element: a portion at a time, never past
+   * the element's end — so a Cues table of thousands of CuePoints costs a few
+   * reads rather than one per CuePoint, and nothing after the element is
+   * fetched for it.
+   *
+   * @param {number} end - One past the element's last byte.
+   * @returns {ElementReader}
+   */
+  #readerWithin(end) {
+    return new ElementReader({
+      read: this.readRange,
+      fileSize: this.fileSize,
+      portionBytes: this.portionBytes,
+      prefetch: true,
+      readableUntil: () => end
+    });
+  }
+
+  /** @returns {Promise<Buffer>} */
+  async #headBytes() {
+    if (this.#head === null) {
+      this.#head = await this.readRange(0, Math.min(HEAD_BYTES, this.fileSize) - 1);
+    }
+    return this.#head;
+  }
+
+  /**
+   * Where the Segment's top-level elements are.
+   *
+   * Found by walking their HEADERS from the Segment's start to the first
+   * cluster — each one costs the bytes of its header and nothing of its data —
+   * and, for what lies after the clusters, from the SeekHead. RFC 9559 §6.4: a
+   * Cues element SHOULD be stored before the first cluster or be referenced by
+   * a SeekHead, so the two together find it wherever a conforming file puts it.
+   *
+   * @returns {Promise<SegmentLayout | null>} Null for bytes that are not a
+   *   Matroska Segment.
+   */
+  async #segmentLayout() {
+    if (this.#layout !== null) {
+      return this.#layout;
+    }
+    const head = await this.#headBytes();
+    if (!isMatroska(head)) {
+      return null;
+    }
+    const segment = segmentHeaderIn(head);
+    if (!segment) {
+      return null;
+    }
+    const segmentDataOffset = segment.dataOffset;
+    const segmentEnd = segment.size === null ? this.fileSize : Math.min(this.fileSize, segmentDataOffset + segment.size);
+
+    const reader = new ElementReader({ read: this.readRange, fileSize: this.fileSize, portionBytes: this.portionBytes });
+    /** @type {Map<number, number>} */
+    const found = new Map();
+    /** @type {Map<number, number>} */
+    const seeks = new Map();
+    let firstClusterAt = null;
+    let at = segmentDataOffset;
+    while (at < segmentEnd) {
+      const header = await reader.header(at, segmentEnd);
+      if (!header) {
+        break;
+      }
+      if (header.id === ID_CLUSTER) {
+        firstClusterAt = at;
+        break;
+      }
+      if (!found.has(header.id)) {
+        found.set(header.id, at);
+      }
+      if (header.id === ID_SEEK_HEAD && header.size !== null) {
+        const data = await reader.data(header);
+        if (data) {
+          for (const [id, position] of readSeekEntries(data)) {
+            seeks.set(id, segmentDataOffset + position);
+          }
+        }
+      }
+      if (header.end === null) {
+        break;
+      }
+      at = header.end;
+    }
+    const positionOf = (id) => found.get(id) ?? seeks.get(id) ?? null;
+
+    let secondsPerTick = DEFAULT_TIMESTAMP_SCALE / 1e9;
+    const infoAt = positionOf(ID_INFO);
+    if (infoAt !== null) {
+      const info = await reader.header(infoAt, segmentEnd);
+      const data = info && info.id === ID_INFO ? await reader.data(info) : null;
+      if (data) {
+        for (const field of iterateElements(data)) {
+          if (field.id === ID_TIMESTAMP_SCALE) {
+            const scale = readUint(data, field.dataOffset, field.size);
+            if (scale > 0) {
+              secondsPerTick = scale / 1e9;
+            }
+          }
+        }
+      }
+    }
+    this.#layout = {
+      segmentDataOffset,
+      segmentEnd,
+      secondsPerTick,
+      infoAt,
+      tracksAt: positionOf(ID_TRACKS),
+      cuesAt: positionOf(ID_CUES),
+      firstClusterAt: firstClusterAt ?? seeks.get(ID_CLUSTER) ?? null
+    };
+    return this.#layout;
+  }
+
   /**
    * Duration and the start of this file's own timeline, per RFC 9559 §5.1.2.
    *
-   * Duration is stated in `Info` as a FLOAT in ticks, so it needs the file's
-   * `TimestampScale` to become seconds. The start of the timeline is not stated
-   * anywhere — Matroska has no such element — so it is the timestamp of the
-   * first Cluster, which is what the first frame is placed against.
+   * Duration is stated in `Info` as a FLOAT in ticks. The start of the timeline
+   * is not stated anywhere — Matroska has no such element — so it is the
+   * timestamp of the first Cluster, which is what the first frame is placed
+   * against.
+   *
+   * Kept only once it has been read: a head that had not arrived used to leave
+   * an empty answer here for the life of the container.
    *
    * @returns {Promise<import("./Container.js").ContainerMediaInfo>}
    */
@@ -188,467 +334,243 @@ export class MatroskaContainer extends Container {
     }
     /** @type {import("./Container.js").ContainerMediaInfo} */
     const info = { format: this.formatName, durationSeconds: null, startTimeSeconds: null };
-    this.mediaInfo = info;
-    const head = await this.readRange(0, Math.min(HEAD_BYTES - 1, this.fileSize - 1));
-    if (!head || !isMatroska(head)) {
-      return info;
-    }
-    const segment = findElement(head, ID_SEGMENT, []);
-    if (!segment) {
+    const layout = await this.#segmentLayout();
+    if (!layout) {
+      this.mediaInfo = info;
       return info;
     }
-    const scale = MatroskaContainer.#timestampScaleOf(head, segment.dataOffset);
-    const infoElement = findElement(head, ID_INFO, [], segment.dataOffset);
-    if (infoElement) {
-      const infoEnd = Math.min(head.length, infoElement.dataOffset + infoElement.size);
-      for (const field of iterateElements(head, infoElement.dataOffset, infoEnd)) {
-        if (field.id !== ID_DURATION) {
-          continue;
-        }
-        const ticks = readFloat(head, field.dataOffset, field.size);
-        if (ticks !== null && ticks > 0) {
-          info.durationSeconds = (ticks * scale) / 1e9;
+    const reader = new ElementReader({ read: this.readRange, fileSize: this.fileSize, portionBytes: this.portionBytes });
+    if (layout.infoAt !== null) {
+      const header = await reader.header(layout.infoAt, layout.segmentEnd);
+      const data = header && header.id === ID_INFO ? await reader.data(header) : null;
+      if (data) {
+        for (const field of iterateElements(data)) {
+          if (field.id === ID_DURATION) {
+            const ticks = readFloat(data, field.dataOffset, field.size);
+            if (ticks !== null && ticks > 0) {
+              info.durationSeconds = ticks * layout.secondsPerTick;
+            }
+          }
         }
-        break;
       }
     }
-    info.startTimeSeconds = await this.#firstClusterSeconds(head, segment.dataOffset, scale);
+    if (layout.firstClusterAt !== null) {
+      info.startTimeSeconds = await clusterTimestampSeconds(reader, layout.firstClusterAt, layout);
+    }
+    this.mediaInfo = info;
     return info;
   }
 
   /**
-   * `TimestampScale` from Info, or the specification's default.
+   * Every track the file declares, in its order, read once.
    *
-   * @param {Buffer} head
-   * @param {number} segmentDataOffset
-   * @returns {number} Nanoseconds per tick.
+   * @returns {Promise<import("../tracks/index.js").ContainerTrack[]>}
    */
-  static #timestampScaleOf(head, segmentDataOffset) {
-    const infoElement = findElement(head, ID_INFO, [], segmentDataOffset);
-    if (!infoElement) {
-      return DEFAULT_TIMESTAMP_SCALE;
+  async readTracks() {
+    if (this.#tracks !== null) {
+      return this.#tracks;
+    }
+    const layout = await this.#segmentLayout();
+    if (!layout || layout.tracksAt === null) {
+      this.#tracks = [];
+      return this.#tracks;
     }
-    const infoEnd = Math.min(head.length, infoElement.dataOffset + infoElement.size);
-    for (const field of iterateElements(head, infoElement.dataOffset, infoEnd)) {
-      if (field.id === ID_TIMESTAMP_SCALE) {
-        const scale = readUint(head, field.dataOffset, field.size);
-        return scale > 0 ? scale : DEFAULT_TIMESTAMP_SCALE;
+    const reader = new ElementReader({ read: this.readRange, fileSize: this.fileSize, portionBytes: this.portionBytes });
+    const tracksHeader = await reader.header(layout.tracksAt, layout.segmentEnd);
+    if (!tracksHeader || tracksHeader.id !== ID_TRACKS || tracksHeader.end === null) {
+      this.#tracks = [];
+      return this.#tracks;
+    }
+    /** @type {import("../tracks/index.js").ContainerTrack[]} */
+    const result = [];
+    const counters = { video: -1, audio: -1, subtitle: -1 };
+    const within = this.#readerWithin(tracksHeader.end);
+    let at = tracksHeader.dataOffset;
+    while (at < tracksHeader.end) {
+      const entry = await within.header(at, tracksHeader.end);
+      if (!entry || entry.end === null) {
+        break;
       }
+      if (entry.id === ID_TRACK_ENTRY) {
+        const data = await within.data(entry);
+        // An entry larger than one portion is refused rather than assembled.
+        // Its type cannot be known without its data, so it is kept as a track
+        // of no kind — which makes the count of its kind short by one, and
+        // `alignWithBanner` then refuses to line the two readings up rather
+        // than pairing them wrongly.
+        const fields = data ? parseTrackEntry(data) : { refused: true, trackNumber: null };
+        const track = trackFrom(fields, counters);
+        if (track) {
+          result.push(track);
+        }
+      }
+      at = entry.end;
     }
-    return DEFAULT_TIMESTAMP_SCALE;
+    this.#tracks = result;
+    return result;
   }
 
   /**
-   * The timestamp of the first Cluster, in seconds.
+   * The Cues table, read once, every CuePoint with every track it names.
    *
-   * Tried in the head window first, because a muxer writes the first cluster
-   * straight after Tracks and both usually fit; a file whose Tracks element is
-   * large enough to push it out is answered from the SeekHead instead, with one
-   * short read at the position it names.
-   *
-   * @param {Buffer} head
-   * @param {number} segmentDataOffset
-   * @param {number} scale - Nanoseconds per tick.
-   * @returns {Promise<number | null>} Null when no cluster could be read.
+   * @returns {Promise<{ points: Array<{ ticks: number, positions: Array<{ track: number, clusterAt: number }> }> } | null>}
+   *   Null where the file has no Cues element — a statement about the file,
+   *   kept. A Cues element that has not downloaded throws and is not kept.
    */
-  async #firstClusterSeconds(head, segmentDataOffset, scale) {
-    /**
-     * @param {Buffer} buffer
-     * @param {number} dataOffset
-     * @param {number} end
-     * @returns {number | null}
-     */
-    const timestampIn = (buffer, dataOffset, end) => {
-      for (const field of iterateElements(buffer, dataOffset, end)) {
-        if (field.id === ID_TIMESTAMP) {
-          const ticks = readUint(buffer, field.dataOffset, field.size);
-          return Number.isFinite(ticks) ? (ticks * scale) / 1e9 : null;
-        }
-        // Timestamp is written before any frame. Stopping at the first one keeps
-        // this from walking a cluster's whole payload, which is megabytes and
-        // usually not in the buffer at all.
-        if (field.id === ID_SIMPLE_BLOCK || field.id === ID_BLOCK_GROUP) {
-          return null;
-        }
-      }
-      return null;
-    };
-
-    for (const element of iterateElements(head, segmentDataOffset, head.length)) {
-      if (element.id !== ID_CLUSTER) {
-        continue;
-      }
-      return timestampIn(head, element.dataOffset, Math.min(head.length, element.dataOffset + element.size));
+  async readCues() {
+    if (this.#cues !== undefined) {
+      return this.#cues;
     }
-
-    const position = MatroskaContainer.#seekPositionOf(head, segmentDataOffset, ID_CLUSTER);
-    if (position === null) {
+    const layout = await this.#segmentLayout();
+    if (!layout || layout.cuesAt === null) {
+      this.#cues = null;
       return null;
     }
-    const at = segmentDataOffset + position;
-    if (at >= this.fileSize) {
+    const reader = new ElementReader({ read: this.readRange, fileSize: this.fileSize, portionBytes: this.portionBytes });
+    const cues = await reader.header(layout.cuesAt, layout.segmentEnd);
+    if (!cues || cues.id !== ID_CUES || cues.end === null) {
+      // The SeekHead names a position with no Cues element at it. The file is
+      // wrong there, and the same bytes will say the same thing next time.
+      this.#cues = null;
       return null;
     }
-    const chunk = await this.readRange(at, Math.min(this.fileSize - 1, at + CLUSTER_PROBE_BYTES - 1));
-    if (!chunk) {
-      return null;
-    }
-    for (const element of iterateElements(chunk, 0, chunk.length)) {
-      if (element.id !== ID_CLUSTER) {
-        continue;
+    const points = [];
+    const within = this.#readerWithin(cues.end);
+    let at = cues.dataOffset;
+    while (at < cues.end) {
+      const point = await within.header(at, cues.end);
+      if (!point || point.end === null) {
+        break;
       }
-      return timestampIn(chunk, element.dataOffset, Math.min(chunk.length, element.dataOffset + element.size));
+      if (point.id === ID_CUE_POINT) {
+        const data = await within.data(point);
+        if (data) {
+          const parsed = parseCuePoint(data, layout.segmentDataOffset);
+          if (parsed) {
+            points.push(parsed);
+          }
+        }
+      }
+      at = point.end;
     }
-    return null;
+    this.#cues = { points };
+    return this.#cues;
   }
 
   /**
-   * Where the SeekHead says an element lives, relative to the Segment's payload.
+   * This container's subtitle tracks, the Cues table and the clusters it
+   * names — everything the cue walk starts from.
    *
-   * @param {Buffer} head
-   * @param {number} segmentDataOffset
-   * @param {number} wantedId
-   * @returns {number | null}
+   * `cuesState` says whether the file has a Cues table at all; where it has
+   * none, the walk finds clusters from the downloaded bytes themselves.
+   *
+   * @returns {Promise<object | null>} Null for bytes that are not Matroska.
    */
-  static #seekPositionOf(head, segmentDataOffset, wantedId) {
-    const seekHead = findElement(head, ID_SEEK_HEAD, [], segmentDataOffset);
-    if (!seekHead) {
+  async readSubtitlePlan() {
+    const layout = await this.#segmentLayout();
+    if (!layout) {
       return null;
     }
-    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);
+    const allTracks = await this.readTracks();
+    const cues = await this.readCues();
+    const subtitles = allTracks.filter((track) => track.type === "subtitle");
+    const declared = subtitles.map((track) => ({
+      trackNumber: track.trackNumber,
+      codecId: track.codecId,
+      // The three-letter code: this list is lined up against ffmpeg's banner,
+      // which prints that form. The RFC 5646 tag rides beside it.
+      language: track.languageCode || track.language,
+      languageBcp47: track.languageBcp47,
+      declaresLanguage: track.declaresLanguage,
+      languageSource: track.languageSource,
+      name: track.name,
+      isDefault: track.isDefault,
+      declaresDefault: track.declaresDefault,
+      isEnabled: track.isEnabled,
+      isForced: track.isForced === true,
+      isHearingImpaired: track.isHearingImpaired === true
+    }));
+    /** @type {Map<number, Set<number>>} */
+    const byTrack = new Map();
+    /** @type {Map<number, number>} */
+    const entrySeconds = new Map();
+    for (const point of cues?.points ?? []) {
+      const seconds = point.ticks * layout.secondsPerTick;
+      for (const { track, clusterAt } of point.positions) {
+        if (!byTrack.has(track)) {
+          byTrack.set(track, new Set());
+        }
+        byTrack.get(track).add(clusterAt);
+        // The cluster begins at or before the earliest frame that names it.
+        const known = entrySeconds.get(clusterAt);
+        if (known === undefined || seconds < known) {
+          entrySeconds.set(clusterAt, seconds);
         }
-      }
-      if (targetId === wantedId && position !== null) {
-        return position;
       }
     }
-    return null;
+    const tracks = subtitles
+      .filter((track) => TEXT_CODECS_MATROSKA.has(track.codecId) && track.isEnabled)
+      .map((track) => ({
+        trackNumber: track.trackNumber,
+        declaredIndex: track.declaredIndex,
+        codecId: track.codecId,
+        language: track.language,
+        languageBcp47: track.languageBcp47,
+        declaresLanguage: track.declaresLanguage,
+        languageSource: track.languageSource,
+        name: track.name,
+        isDefault: track.isDefault,
+        isForced: track.isForced === true,
+        isHearingImpaired: track.isHearingImpaired === true,
+        codecPrivate: track.codecPrivateB64,
+        clusterPositions: [...(byTrack.get(track.trackNumber) ?? [])].sort((left, right) => left - right)
+      }));
+    return {
+      tracks,
+      declared,
+      secondsPerTick: layout.secondsPerTick,
+      segmentDataOffset: layout.segmentDataOffset,
+      fileSize: this.fileSize,
+      segmentEnd: layout.segmentEnd,
+      firstClusterAt: layout.firstClusterAt,
+      cuesState: cues ? "complete" : "absent",
+      entryPoints: [...entrySeconds].map(([at, seconds]) => ({ at, seconds })).sort((left, right) => left.at - right.at),
+      subtitleTrackNumbers: tracks.map((track) => track.trackNumber),
+      allTrackNumbers: allTracks.map((track) => track.trackNumber).filter((number) => Number.isFinite(number))
+    };
   }
 
-
   /**
-   * Walk the clusters this file's Cues table names and give up the blocks in
-   * every one that is READABLE now, for every track at once.
-   *
-   * One walk for the whole file, not one per track: a Matroska cluster carries
-   * the blocks of every track that has anything to say over its span, so the
-   * bytes that answer one track answer them all. Reading them once per track
-   * meant the same cluster was fetched and parsed as many times as the film has
-   * subtitle tracks — measured 2026-08-20 on a film with five: five requests
-   * every fifteen seconds, each costing 0.2-5.2 s, for a few kilobytes of cues.
-   *
-   * Nothing is fetched. `isHeld` decides whether a cluster can be read at all,
-   * and one that is not here yet is left for the next call — turning subtitles
-   * on must not pull bytes the viewer is not waiting for.
+   * The cues this file holds now, for every text track at once — see
+   * `matroska-clusters.js` for how clusters are found and in what order read.
    *
-   * @param {object} plan - From {@link MatroskaContainer.readSubtitlePlan}.
-   * @param {Set<number>} walked - Cluster positions already read; added to.
-   * @returns {Promise<Map<number, {startSeconds: number, endSeconds: number|null, text: string}[]>>}
-   *   Track number to the cues found in THIS pass.
+   * @param {object} plan
+   * @param {object} track
+   * @param {object} progress
+   * @param {import("./Container.js").HeldReader} held
+   * @returns {Promise<{ found: Map<number, object[]>, covered: number, indexed: number, withdrawn: number[], stats: object }>}
    */
-  async readHeldCues(plan, track, progress) {
-    const found = await this.walkHeldClusters(plan, progress.walked);
-    return {
-      found,
-      // Every track is filled by the same walk, so this is a fact about the
-      // FILE and reads the same whichever track asked.
-      covered: progress.walked.size,
-      indexed: track?.clusterPositions?.length ?? 0
-    };
-  }
-
-  async walkHeldClusters(plan, walked) {
-    /** @type {Map<number, object[]>} */
+  async readHeldCues(plan, track, progress, held) {
+    const walked = await walkHeldClusters({ plan, progress, held });
     const found = new Map();
-    // The union of the tracks' cluster lists: each track's list comes from its
-    // own Cues entries, so they overlap but do not coincide.
-    const positions = new Set();
-    for (const candidate of plan?.tracks ?? []) {
-      for (const position of candidate.clusterPositions ?? []) {
-        positions.add(position);
-      }
-    }
-    for (const position of [...positions].sort((left, right) => left - right)) {
-      if (walked.has(position)) {
-        continue;
-      }
-      // The header first: it says how long the cluster is, and a cluster whose
-      // bytes are not all here is left for the next time round.
-      const probeEnd = Math.min(this.fileSize - 1, position + CLUSTER_HEADER_PROBE - 1);
-      if (!this.isHeld(position, probeEnd)) {
-        continue;
-      }
-      const probe = await this.readHeld(position, probeEnd);
-      const header = probe && [...iterateElements(probe, 0, probe.length)][0];
-      if (!header || header.size <= 0 || header.size > MAX_CLUSTER_BYTES) {
-        walked.add(position); // not a cluster this can read; do not look again
-        continue;
-      }
-      const last = Math.min(this.fileSize - 1, position + header.dataOffset + header.size - 1);
-      if (!this.isHeld(position, last)) {
-        continue;
-      }
-      const bytes = await this.readHeld(position, last);
-      if (!bytes) {
+    for (const candidate of plan.tracks) {
+      const blocks = walked.found.get(candidate.trackNumber);
+      if (!blocks) {
         continue;
       }
-      walked.add(position);
-      for (const candidate of plan.tracks) {
-        const blocks = MatroskaContainer.blocksInCluster(bytes, candidate.trackNumber, plan.secondsPerTick);
-        if (blocks.length === 0) {
-          continue;
-        }
-        const into = found.get(candidate.trackNumber) ?? [];
-        for (const block of blocks) {
-          // The block's bytes become text HERE, where the container that framed
-          // them is known. A cue kept framed and unframed later cannot be
-          // unframed at all: nothing downstream knows which container it came
-          // out of, and guessing from the field count is what showed the
-          // dialogue row's own fields to the viewer.
-          into.push({
-            startSeconds: block.startSeconds,
-            endSeconds: block.endSeconds,
-            text: MatroskaContainer.cueTextOf(block.payload, candidate.codecId)
-          });
-        }
-        found.set(candidate.trackNumber, into);
-      }
-    }
-    return found;
-  }
-
-  async readTracks() {
-    const head = await this.readRange(0, Math.min(HEAD_BYTES - 1, this.fileSize - 1));
-    if (!head || !isMatroska(head)) return [];
-
-    // Delegate to subtitle plan reader for subtitle tracks (already handles Flags spec-correct),
-    // but we need video/audio tracks too. Do a dedicated Tracks walk here for all types,
-    // then merge subtitle detail (clusterPositions, declaresDefault etc.) from the plan.
-    const seg = findElement(head, 0x18538067, []);
-    if (!seg) return [];
-    const tracksEl = findElement(head, ID_TRACKS, [], seg.dataOffset);
-    if (!tracksEl) return [];
-
-    const tracksEnd = Math.min(head.length, tracksEl.dataOffset + tracksEl.size);
-    /** @type {import("../tracks/index.js").ContainerTrack[]} */
-    const result = [];
-    // Subtitle declaredIndex is position among subtitle tracks, not global — track per-type counters.
-    let subtitleDeclaredIndex = -1;
-    let audioDeclaredIndex = -1;
-    let videoDeclaredIndex = -1;
-
-    // For subtitle flag enrichment, read the existing plan (it already does Cues walk)
-    let subtitlePlan = null;
-    try {
-      const shim = async (s, e) => this.readRange(s, Math.min(e, this.fileSize - 1));
-      subtitlePlan = await readSubtitlePlan(shim, this.fileSize);
-    } catch {
-      subtitlePlan = null;
-    }
-    const declaredByNumber = new Map();
-    const planTracksByNumber = new Map();
-    if (subtitlePlan?.declared) {
-      for (const d of subtitlePlan.declared) declaredByNumber.set(d.trackNumber, d);
-    }
-    if (subtitlePlan?.tracks) {
-      for (const t of subtitlePlan.tracks) planTracksByNumber.set(t.trackNumber, t);
-    }
-
-    for (const entry of iterateElements(head, tracksEl.dataOffset, tracksEnd)) {
-      if (entry.id !== ID_TRACK_ENTRY) continue;
-      const entryEnd = Math.min(tracksEnd, entry.dataOffset + entry.size);
-      let trackNumber = null;
-      let typeNum = null;
-      let codecId = "";
-      let language = "";
-      let languageBcp47 = "";
-      let name = "";
-      let codecPrivateB64 = "";
-      let isEnabled = true;
-      let isDefault = true;
-      let declaresDefault = false;
-      let isForced = false;
-      let isHearing = false;
-      let isVisual = false;
-      let isOriginal = false;
-      let isCommentary = false;
-      let pixelWidth = null;
-      let pixelHeight = null;
-      let displayWidth = null;
-      let displayHeight = null;
-      let samplingFreq = null;
-      let channels = null;
-
-      for (const f of iterateElements(head, entry.dataOffset, entryEnd)) {
-        switch (f.id) {
-          case ID_TRACK_NUMBER: trackNumber = readUint(head, f.dataOffset, f.size); break;
-          case ID_TRACK_TYPE: typeNum = readUint(head, f.dataOffset, f.size); break;
-          case ID_CODEC_ID: codecId = readString(head, f); break;
-          case ID_CODEC_PRIVATE: codecPrivateB64 = head.toString("base64", f.dataOffset, f.dataOffset + f.size); break;
-          case ID_LANGUAGE: language = readString(head, f); break;
-          case ID_LANGUAGE_BCP47: languageBcp47 = readString(head, f); break;
-          case ID_NAME: name = readString(head, f); break;
-          case ID_FLAG_ENABLED: isEnabled = f.size === 0 || readUint(head, f.dataOffset, f.size) !== 0; break;
-          case ID_FLAG_DEFAULT: isDefault = f.size === 0 || readUint(head, f.dataOffset, f.size) === 1; declaresDefault = true; break;
-          case ID_FLAG_FORCED: isForced = f.size > 0 && readUint(head, f.dataOffset, f.size) !== 0; break;
-          case ID_FLAG_HEARING: isHearing = f.size > 0 && readUint(head, f.dataOffset, f.size) !== 0; break;
-          case ID_FLAG_VISUAL: isVisual = f.size > 0 && readUint(head, f.dataOffset, f.size) !== 0; break;
-          case ID_FLAG_TEXT_DESCR: break;
-          case ID_FLAG_ORIGINAL: isOriginal = f.size > 0 && readUint(head, f.dataOffset, f.size) !== 0; break;
-          case ID_FLAG_COMMENTARY: isCommentary = f.size > 0 && readUint(head, f.dataOffset, f.size) !== 0; break;
-          default: break;
-        }
-        // Video/Audio sub-elements are nested, not at entry level — read separately below.
-      }
-      if (trackNumber === null) continue;
-
-      // Parse Video/Audio sub-elements if present
-      const videoEl = findElement(head, ID_VIDEO, [], entry.dataOffset, entryEnd);
-      if (videoEl) {
-        for (const vf of iterateElements(head, videoEl.dataOffset, Math.min(entryEnd, videoEl.dataOffset + videoEl.size))) {
-          if (vf.id === ID_PIXEL_WIDTH) pixelWidth = readUint(head, vf.dataOffset, vf.size);
-          else if (vf.id === ID_PIXEL_HEIGHT) pixelHeight = readUint(head, vf.dataOffset, vf.size);
-          else if (vf.id === ID_DISPLAY_WIDTH) displayWidth = readUint(head, vf.dataOffset, vf.size);
-          else if (vf.id === ID_DISPLAY_HEIGHT) displayHeight = readUint(head, vf.dataOffset, vf.size);
-        }
-      }
-      const audioEl = findElement(head, ID_AUDIO, [], entry.dataOffset, entryEnd);
-      if (audioEl) {
-        for (const af of iterateElements(head, audioEl.dataOffset, Math.min(entryEnd, audioEl.dataOffset + audioEl.size))) {
-          if (af.id === ID_SAMPLING_FREQUENCY) {
-            // SamplingFrequency is float64
-            if (af.size === 8) samplingFreq = head.readDoubleBE(af.dataOffset);
-            else samplingFreq = readUint(head, af.dataOffset, af.size);
-          } else if (af.id === ID_CHANNELS) channels = readUint(head, af.dataOffset, af.size);
-        }
-      }
-
-      // RFC 9559 LanguageBCP47 MUST — when present, Language ignored
-      const resolvedLang = languageBcp47 || language;
-      const bcpTag = languageBcp47;
-      const declaresLanguage = resolvedLang.length > 0;
-
-      if (typeNum === 1) {
-        videoDeclaredIndex += 1;
-        result.push(new VideoTrack({
-          trackNumber,
-          declaredIndex: videoDeclaredIndex,
-          codecId,
-          language: resolvedLang,
-          languageBcp47: bcpTag,
-          declaresLanguage,
-          name,
-          isEnabled,
-          isDefault,
-          declaresDefault,
-          codecPrivateB64,
-          width: pixelWidth,
-          height: pixelHeight,
-          displayWidth,
-          displayHeight
-        }));
-      } else if (typeNum === 2) {
-        audioDeclaredIndex += 1;
-        result.push(new AudioTrack({
-          trackNumber,
-          declaredIndex: audioDeclaredIndex,
-          codecId,
-          language: resolvedLang,
-          languageBcp47: bcpTag,
-          declaresLanguage,
-          name,
-          isEnabled,
-          isDefault,
-          declaresDefault,
-          codecPrivateB64,
-          isOriginal,
-          isCommentary,
-          isVisualImpaired: isVisual,
-          channels,
-          samplingFrequency: samplingFreq
-        }));
-      } else if (typeNum === 17) {
-        subtitleDeclaredIndex += 1;
-        // Only Forced/Hearing belong to subtitles; Original/Commentary must not leak.
-        const declared = declaredByNumber.get(trackNumber);
-        const planTrack = planTracksByNumber.get(trackNumber);
-        // Prefer plan's flags when available (already spec-correct), else use parsed.
-        const finalForced = planTrack ? !!planTrack.isForced : isForced;
-        const finalHearing = planTrack ? !!planTrack.isHearingImpaired : isHearing;
-        const finalEnabled = declared ? declared.isEnabled !== false : isEnabled;
-        const finalDefault = declared ? !!declared.isDefault : isDefault;
-        const finalDeclares = declared ? !!declared.declaresDefault : declaresDefault;
-        const clusterPositions = planTrack ? planTrack.clusterPositions ?? [] : [];
-        const isText = TEXT_CODECS_MATROSKA.has(codecId);
-        // disabled image/text tracks still counted (declaredIndex above) — offerable flag controls visibility
-        if (isText && finalEnabled) {
-          result.push(new TextSubtitleTrack({
-            trackNumber,
-            declaredIndex: subtitleDeclaredIndex,
-            codecId,
-            language: resolvedLang,
-            languageBcp47: bcpTag,
-            declaresLanguage,
-            name,
-            isEnabled: finalEnabled,
-            isDefault: finalDefault,
-            declaresDefault: finalDeclares,
-            codecPrivateB64,
-            isForced: finalForced,
-            isHearingImpaired: finalHearing,
-            clusterPositions
-          }));
-        } else {
-          // Image or disabled — keep declaredIndex, not offerable if disabled
-          const Target = isText ? TextSubtitleTrack : ImageSubtitleTrack;
-          result.push(new Target({
-            trackNumber,
-            declaredIndex: subtitleDeclaredIndex,
-            codecId,
-            language: resolvedLang,
-            languageBcp47: bcpTag,
-            declaresLanguage,
-            name,
-            isEnabled: finalEnabled,
-            isDefault: finalDefault,
-            declaresDefault: finalDeclares,
-            codecPrivateB64,
-            isForced: finalForced,
-            isHearingImpaired: finalHearing,
-            clusterPositions: isText ? clusterPositions : []
-          }));
-        }
-      } else {
-        // Other TrackType (complex, logo, buttons, control) — keep as generic, not video
-        result.push(new ContainerTrack({
-          trackNumber,
-          declaredIndex: -1,
-          type: "other",
-          codecId,
-          language: resolvedLang,
-          languageBcp47: bcpTag,
-          declaresLanguage,
-          name,
-          isEnabled,
-          isDefault,
-          declaresDefault,
-          codecPrivateB64
-        }));
-      }
+      found.set(
+        candidate.trackNumber,
+        blocks.map((block) => ({
+          startSeconds: block.startSeconds,
+          endSeconds: block.endSeconds,
+          // The block's bytes become text HERE, where the container that
+          // framed them is known.
+          text: MatroskaContainer.cueTextOf(block.payload, candidate.codecId),
+          source: block.source
+        }))
+      );
     }
-    return result;
+    return { ...walked, found };
   }
 
   /**
@@ -670,9 +592,7 @@ export class MatroskaContainer extends Container {
    *    back together.
    *
    * `S_TEXT/UTF8` and `S_TEXT/WEBVTT` have no such framing: the block holds the
-   * cue text and nothing else. (A WebVTT cue's settings, identifier and
-   * preceding comments live in a BlockAddition, which this proxy does not read;
-   * losing them costs positioning, not words.)
+   * cue text and nothing else.
    *
    * @param {Buffer} payload - The block's own bytes.
    * @param {string} codecId - Matroska CodecID of the track the block belongs to.
@@ -687,146 +607,361 @@ export class MatroskaContainer extends Container {
     return fields.length > ASS_FIELDS_BEFORE_TEXT ? fields.slice(ASS_FIELDS_BEFORE_TEXT).join(",") : "";
   }
 
+  /**
+   * The keyframe times of the first video track, from the one Cues reading.
+   *
+   * A CuePoint belongs to the track named inside its CueTrackPositions, and a
+   * muxer indexes whatever tracks it likes — field files index their subtitle
+   * tracks too, and read without the track those times entered the cut list as
+   * though they were keyframes (2026-08-18). Where the filter leaves nothing
+   * although a table exists, the unfiltered table is used: less exact than the
+   * picture's own keyframes, better than an even grid that has nothing to do
+   * with the file.
+   *
+   * @returns {Promise<{ times: number[], tolerance: number } | null>}
+   */
   async parseKeyframeIndex() {
-    const times = await readMatroskaKeyframeTimes(this.readRange, this.fileSize);
-    if (!times) return null;
-    if (Array.isArray(times)) return { times, tolerance: 0 };
-    return times;
+    const layout = await this.#segmentLayout();
+    if (!layout) {
+      return null;
+    }
+    const cues = await this.readCues();
+    if (!cues) {
+      return null;
+    }
+    const tracks = await this.readTracks();
+    const video = tracks.find((track) => track.type === "video")?.trackNumber ?? null;
+    const timesFor = (wanted) =>
+      cues.points
+        .filter((point) => wanted === null || point.positions.some((position) => position.track === wanted))
+        .map((point) => point.ticks * layout.secondsPerTick)
+        .sort((left, right) => left - right);
+    const times = timesFor(video);
+    if (times.length > 0) {
+      return { times, tolerance: 0 };
+    }
+    if (video === null) {
+      return null;
+    }
+    const unfiltered = timesFor(null);
+    return unfiltered.length > 0 ? { times: unfiltered, tolerance: 0 } : null;
   }
 }
 
-// ---------------------------------------------------------------------------
-// Matroska's own reading of its subtitle tracks and its clusters. It lives in
-// this module because every line of it is a statement of RFC 9559 about how
-// this container stores a subtitle, and the class is the only way in.
-// ---------------------------------------------------------------------------
-
-const ID_BLOCK = 0xa1;
-const ID_BLOCK_DURATION = 0x9b;
-
-/** Bits 1-2 of the flags byte say how a block is laced, or that it is not. */
-const LACING_MASK = 0x06;
-const LACING_NONE = 0x00;
-const LACING_XIPH = 0x02;
-const LACING_FIXED = 0x04;
-const LACING_EBML = 0x06;
-
 /**
- * @typedef {object} SubtitleBlock
- * @property {number} startSeconds - When the cue appears.
- * @property {number | null} durationSeconds - How long it stays, or null when
- *   the block carried no duration (a SimpleBlock; the caller decides).
- * @property {Buffer} payload - The block's own bytes, still in the codec's form.
+ * Whether this looks like a Matroska file (the EBML magic `0x1A45DFA3`).
+ *
+ * @param {Buffer} head
+ * @returns {boolean}
  */
+function isMatroska(head) {
+  return head.length >= 4 && head.readUInt32BE(0) === ID_EBML;
+}
 
 /**
- * Read one block's header.
+ * The Segment element's header, from the top-level elements of the head.
  *
- * @param {Buffer} buffer
- * @param {number} start - First byte of the block's payload.
- * @param {number} end - One past its last byte.
- * @returns {{ trackNumber: number, relativeTicks: number, flags: number, dataOffset: number } | null}
+ * @param {Buffer} head
+ * @returns {{ dataOffset: number, size: number | null } | null} `size` is null
+ *   for an unknown-sized Segment (RFC 8794 §6.2), which runs to the file's end.
  */
-function readBlockHeader(buffer, start, end) {
-  const track = readVint(buffer, start, false);
-  if (!track || track.value === null) {
-    return null;
+function segmentHeaderIn(head) {
+  let offset = 0;
+  while (offset < head.length) {
+    const id = readVint(head, offset, true);
+    const size = id && readVint(head, offset + id.length, false);
+    if (!id || !size) {
+      return null;
+    }
+    const dataOffset = offset + id.length + size.length;
+    if (id.value === ID_SEGMENT) {
+      return { dataOffset, size: sizeIsUnknown(size) ? null : size.value };
+    }
+    offset = dataOffset + size.value;
   }
-  const timestampAt = start + track.length;
-  // Signed, and it can be negative: a block may belong slightly before the
-  // cluster it is stored in.
-  if (timestampAt + 3 > end) {
-    return null;
+  return null;
+}
+
+/**
+ * The SeekHead's entries, id to position relative to the Segment's data.
+ *
+ * @param {Buffer} data - The SeekHead's data.
+ * @returns {Map<number, number>}
+ */
+function readSeekEntries(data) {
+  const entries = new Map();
+  for (const seek of iterateElements(data)) {
+    if (seek.id !== ID_SEEK) {
+      continue;
+    }
+    const end = Math.min(data.length, seek.dataOffset + seek.size);
+    let targetId = null;
+    let position = null;
+    for (const field of iterateElements(data, seek.dataOffset, end)) {
+      if (field.id === ID_SEEK_ID) {
+        targetId = readUint(data, field.dataOffset, field.size);
+      } else if (field.id === ID_SEEK_POSITION) {
+        position = readUint(data, field.dataOffset, field.size);
+      }
+    }
+    if (targetId !== null && position !== null && !entries.has(targetId)) {
+      entries.set(targetId, position);
+    }
   }
-  return {
-    trackNumber: Number(track.value),
-    relativeTicks: buffer.readInt16BE(timestampAt),
-    flags: buffer[timestampAt + 2],
-    dataOffset: timestampAt + 3
-  };
+  return entries;
 }
 
 /**
- * Where a laced block's first frame begins.
+ * The timestamp of a cluster, from its leading children.
  *
- * Subtitles are rarely laced, but a block that IS laced starts with a frame
- * count and a table of sizes, and reading the payload without stepping over
- * them yields the table as though it were text.
+ * §5.1.3.1: the Timestamp SHOULD be the first child, or the second after a
+ * CRC-32. Children before it are stepped over by their headers; reading stops
+ * at the first block, so a cluster's megabytes are never pulled for this.
  *
- * @param {Buffer} buffer
- * @param {number} dataOffset - First byte after the block header.
- * @param {number} end
- * @param {number} flags
- * @returns {number | null} The offset of the first frame, or null when the
- *   lacing cannot be read.
+ * @param {ElementReader} reader
+ * @param {number} at
+ * @param {SegmentLayout} layout
+ * @returns {Promise<number | null>}
  */
-function firstFrameOffset(buffer, dataOffset, end, flags) {
-  const lacing = flags & LACING_MASK;
-  if (lacing === LACING_NONE) {
-    return dataOffset;
-  }
-  if (dataOffset >= end) {
+async function clusterTimestampSeconds(reader, at, layout) {
+  const cluster = await reader.header(at, layout.segmentEnd);
+  if (!cluster || cluster.id !== ID_CLUSTER) {
     return null;
   }
-  const frames = buffer[dataOffset] + 1;
-  let at = dataOffset + 1;
-  if (lacing === LACING_FIXED) {
-    return at;
+  const limit = cluster.end ?? layout.segmentEnd;
+  let cursor = cluster.dataOffset;
+  while (cursor < limit) {
+    const child = await reader.header(cursor, limit);
+    if (!child || child.size === null) {
+      return null;
+    }
+    if (child.id === ID_TIMESTAMP) {
+      const bytes = await reader.bytes(child.dataOffset, child.size);
+      return readUint(bytes, 0, child.size) * layout.secondsPerTick;
+    }
+    if (child.id === ID_SIMPLE_BLOCK || child.id === ID_BLOCK_GROUP) {
+      return null;
+    }
+    cursor = child.end;
   }
-  if (lacing === LACING_XIPH) {
-    // Each size but the last is a run of 0xFF bytes ending in a smaller one.
-    for (let frame = 0; frame < frames - 1; frame += 1) {
-      while (at < end && buffer[at] === 0xff) {
-        at += 1;
+  return null;
+}
+
+/**
+ * One CuePoint: its time and every track position it names.
+ *
+ * @param {Buffer} data
+ * @param {number} segmentDataOffset - CueClusterPosition is relative to it.
+ * @returns {{ ticks: number, positions: Array<{ track: number, clusterAt: number }> } | null}
+ */
+function parseCuePoint(data, segmentDataOffset) {
+  let ticks = null;
+  const positions = [];
+  for (const field of iterateElements(data)) {
+    if (field.id === ID_CUE_TIME) {
+      ticks = readUint(data, field.dataOffset, field.size);
+      continue;
+    }
+    if (field.id !== ID_CUE_TRACK_POSITIONS) {
+      continue;
+    }
+    const end = Math.min(data.length, field.dataOffset + field.size);
+    let track = null;
+    let cluster = null;
+    for (const inner of iterateElements(data, field.dataOffset, end)) {
+      if (inner.id === ID_CUE_TRACK) {
+        track = readUint(data, inner.dataOffset, inner.size);
+      } else if (inner.id === ID_CUE_CLUSTER_POSITION) {
+        cluster = readUint(data, inner.dataOffset, inner.size);
       }
-      at += 1;
     }
-    return at <= end ? at : null;
+    if (track !== null && cluster !== null) {
+      positions.push({ track, clusterAt: segmentDataOffset + cluster });
+    }
   }
-  if (lacing === LACING_EBML) {
-    // The first size is a plain variable-length integer, the rest are signed
-    // differences from it; either way each is one such integer to step over.
-    for (let frame = 0; frame < frames - 1; frame += 1) {
-      const size = readVint(buffer, at, false);
-      if (!size) {
-        return null;
+  return ticks === null ? null : { ticks, positions };
+}
+
+/**
+ * Every field of one TrackEntry this proxy reads, with RFC 9559's defaults.
+ *
+ * @param {Buffer} data - The TrackEntry's data.
+ * @returns {object}
+ */
+function parseTrackEntry(data) {
+  const fields = {
+    refused: false,
+    trackNumber: null,
+    type: null,
+    codecId: "",
+    language: null,
+    languageBcp47: "",
+    name: "",
+    codecPrivateB64: "",
+    isEnabled: true,
+    // FlagDefault DEFAULTS TO 1; whether the file wrote it is kept apart,
+    // because once the default is applied "no track marked" and "every track
+    // marked" look the same.
+    isDefault: true,
+    declaresDefault: false,
+    isForced: false,
+    isHearing: false,
+    isVisual: false,
+    isOriginal: false,
+    isCommentary: false,
+    pixelWidth: null,
+    pixelHeight: null,
+    displayWidth: null,
+    displayHeight: null,
+    samplingFreq: null,
+    channels: null
+  };
+  for (const f of iterateElements(data)) {
+    switch (f.id) {
+      case ID_TRACK_NUMBER: fields.trackNumber = readUint(data, f.dataOffset, f.size); break;
+      case ID_TRACK_TYPE: fields.type = readUint(data, f.dataOffset, f.size); break;
+      case ID_CODEC_ID: fields.codecId = readString(data, f); break;
+      case ID_CODEC_PRIVATE: fields.codecPrivateB64 = data.toString("base64", f.dataOffset, f.dataOffset + f.size); break;
+      // An empty element carries its default (RFC 8794 §6.3 and §11.1.19).
+      case ID_LANGUAGE: fields.language = f.size === 0 ? DEFAULT_LANGUAGE : readString(data, f); break;
+      case ID_LANGUAGE_BCP47: fields.languageBcp47 = readString(data, f); break;
+      case ID_NAME: fields.name = readString(data, f); break;
+      // Zero length carries the default, which is 1; only an explicit zero
+      // takes a track away.
+      case ID_FLAG_ENABLED: fields.isEnabled = f.size === 0 || readUint(data, f.dataOffset, f.size) !== 0; break;
+      case ID_FLAG_DEFAULT: fields.isDefault = f.size === 0 || readUint(data, f.dataOffset, f.size) === 1; fields.declaresDefault = true; break;
+      case ID_FLAG_FORCED: fields.isForced = f.size > 0 && readUint(data, f.dataOffset, f.size) !== 0; break;
+      case ID_FLAG_HEARING: fields.isHearing = f.size > 0 && readUint(data, f.dataOffset, f.size) !== 0; break;
+      case ID_FLAG_VISUAL: fields.isVisual = f.size > 0 && readUint(data, f.dataOffset, f.size) !== 0; break;
+      case ID_FLAG_TEXT_DESCR: break;
+      case ID_FLAG_ORIGINAL: fields.isOriginal = f.size > 0 && readUint(data, f.dataOffset, f.size) !== 0; break;
+      case ID_FLAG_COMMENTARY: fields.isCommentary = f.size > 0 && readUint(data, f.dataOffset, f.size) !== 0; break;
+      case ID_VIDEO: {
+        const end = Math.min(data.length, f.dataOffset + f.size);
+        for (const vf of iterateElements(data, f.dataOffset, end)) {
+          if (vf.id === ID_PIXEL_WIDTH) fields.pixelWidth = readUint(data, vf.dataOffset, vf.size);
+          else if (vf.id === ID_PIXEL_HEIGHT) fields.pixelHeight = readUint(data, vf.dataOffset, vf.size);
+          else if (vf.id === ID_DISPLAY_WIDTH) fields.displayWidth = readUint(data, vf.dataOffset, vf.size);
+          else if (vf.id === ID_DISPLAY_HEIGHT) fields.displayHeight = readUint(data, vf.dataOffset, vf.size);
+        }
+        break;
       }
-      at += size.length;
+      case ID_AUDIO: {
+        const end = Math.min(data.length, f.dataOffset + f.size);
+        for (const af of iterateElements(data, f.dataOffset, end)) {
+          if (af.id === ID_SAMPLING_FREQUENCY) {
+            fields.samplingFreq = af.size === 8 ? data.readDoubleBE(af.dataOffset) : readFloat(data, af.dataOffset, af.size);
+          } else if (af.id === ID_CHANNELS) {
+            fields.channels = readUint(data, af.dataOffset, af.size);
+          }
+        }
+        break;
+      }
+      default: break;
     }
-    return at <= end ? at : null;
   }
-  return null;
+  return fields;
+}
+
+/**
+ * The track object one TrackEntry describes.
+ *
+ * The language follows RFC 9559's order: a `LanguageBCP47` element wins and
+ * `Language` is then ignored; otherwise `Language`; otherwise its default,
+ * `eng` — which a reader MUST apply (RFC 8794 §11.1.19). Where it came from is
+ * kept as `languageSource`.
+ *
+ * @param {object} fields - From {@link parseTrackEntry}.
+ * @param {{ video: number, audio: number, subtitle: number }} counters
+ * @returns {import("../tracks/ContainerTrack.js").ContainerTrack | null}
+ */
+function trackFrom(fields, counters) {
+  if (fields.trackNumber === null && !fields.refused) {
+    return null;
+  }
+  const declaresLanguage = fields.languageBcp47.length > 0 || fields.language !== null;
+  const languageSource = fields.languageBcp47 ? "bcp47" : fields.language !== null ? "language" : "default";
+  const language = fields.languageBcp47 || (fields.language !== null ? fields.language : DEFAULT_LANGUAGE);
+  const common = {
+    trackNumber: fields.trackNumber,
+    codecId: fields.codecId,
+    language,
+    languageBcp47: fields.languageBcp47,
+    declaresLanguage,
+    languageSource,
+    languageCode: fields.language !== null ? fields.language : DEFAULT_LANGUAGE,
+    name: fields.name,
+    isEnabled: fields.isEnabled,
+    isDefault: fields.isDefault,
+    declaresDefault: fields.declaresDefault,
+    codecPrivateB64: fields.codecPrivateB64
+  };
+  if (fields.type === TRACK_TYPE_VIDEO) {
+    counters.video += 1;
+    return new VideoTrack({
+      ...common,
+      declaredIndex: counters.video,
+      width: fields.pixelWidth,
+      height: fields.pixelHeight,
+      displayWidth: fields.displayWidth,
+      displayHeight: fields.displayHeight
+    });
+  }
+  if (fields.type === TRACK_TYPE_AUDIO) {
+    counters.audio += 1;
+    return new AudioTrack({
+      ...common,
+      declaredIndex: counters.audio,
+      isOriginal: fields.isOriginal,
+      isCommentary: fields.isCommentary,
+      isVisualImpaired: fields.isVisual,
+      channels: fields.channels,
+      samplingFrequency: fields.samplingFreq
+    });
+  }
+  if (fields.type === TRACK_TYPE_SUBTITLE) {
+    counters.subtitle += 1;
+    // A track the file marks unusable is still COUNTED: ffmpeg creates and
+    // numbers a stream for it, so leaving it out would shift `declaredIndex`
+    // off `0:s:N` for every track after it. It is refused where it is offered.
+    const isText = TEXT_CODECS_MATROSKA.has(fields.codecId);
+    const Target = isText ? TextSubtitleTrack : ImageSubtitleTrack;
+    return new Target({
+      ...common,
+      declaredIndex: counters.subtitle,
+      isForced: fields.isForced,
+      isHearingImpaired: fields.isHearing,
+      clusterPositions: []
+    });
+  }
+  return new ContainerTrack({ ...common, declaredIndex: -1, type: "other" });
 }
 
 /**
- * Every block of one track inside one cluster.
+ * Every block of one track inside one cluster held whole in a buffer.
  *
  * @param {Buffer} buffer - Bytes holding the cluster's payload.
  * @param {{ dataOffset: number, size: number }} cluster - Where that payload is.
  * @param {number} trackNumber - The track to keep.
  * @param {number} secondsPerTick - From the segment's timestamp scale.
- * @returns {SubtitleBlock[]}
+ * @returns {{ startSeconds: number, durationSeconds: number | null, payload: Buffer }[]}
  */
 function blocksOfTrack(buffer, cluster, trackNumber, secondsPerTick) {
   const end = Math.min(buffer.length, cluster.dataOffset + cluster.size);
-  /** @type {SubtitleBlock[]} */
   const blocks = [];
   let clusterTicks = null;
+  const pending = [];
 
   const take = (blockStart, blockEnd, durationTicks) => {
     const header = readBlockHeader(buffer, blockStart, blockEnd);
-    if (!header || header.trackNumber !== trackNumber || clusterTicks === null) {
+    if (!header || header.trackNumber !== trackNumber) {
       return;
     }
     const payloadAt = firstFrameOffset(buffer, header.dataOffset, blockEnd, header.flags);
     if (payloadAt === null || payloadAt >= blockEnd) {
       return;
     }
-    blocks.push({
-      startSeconds: (clusterTicks + header.relativeTicks) * secondsPerTick,
-      durationSeconds: durationTicks === null ? null : durationTicks * secondsPerTick,
-      payload: buffer.subarray(payloadAt, blockEnd)
-    });
+    pending.push({ relativeTicks: header.relativeTicks, durationTicks, payload: buffer.subarray(payloadAt, blockEnd) });
   };
 
   for (const element of iterateElements(buffer, cluster.dataOffset, end)) {
@@ -842,9 +977,6 @@ function blocksOfTrack(buffer, cluster, trackNumber, secondsPerTick) {
     if (element.id !== ID_BLOCK_GROUP) {
       continue;
     }
-    // A group holds the block and, for a subtitle, the duration that says when
-    // the cue leaves the screen. Both are read before either is used, because
-    // the duration may be written after the block.
     let blockStart = null;
     let blockEnd = null;
     let durationTicks = null;
@@ -861,634 +993,39 @@ function blocksOfTrack(buffer, cluster, trackNumber, secondsPerTick) {
       take(blockStart, blockEnd, durationTicks);
     }
   }
-  return blocks;
-}
-
-
-/**
- * The rest of what a TrackEntry says about itself, RFC 9559 §5.1.4.1. Read
- * because the file states them and a releaser's own wording in `Name` is the
- * only thing we had before: "fors" and "SDH" in a menu were whatever text
- * someone happened to type.
- *
- * `FlagEnabled` defaults to 1 and means "the track is usable"; a track that
- * says 0 is counted but not offered. `FlagForced` applies only to subtitles and
- * defaults to 0. `FlagHearingImpaired` is set "if and only if the track is
- * suitable for users with hearing impairments". `FlagVisualImpaired`,
- * `FlagOriginal` and `FlagCommentary` bear on the AUDIO choice and are read
- * with that work, not here — see roadmap item 55.
- */
-const ID_FLAG_HEARING_IMPAIRED = 0x55ab;
-/**
- * The language as RFC 5646 writes it. The specification is a MUST: "If this
- * element is used, then any Language elements used in the same TrackEntry MUST
- * be ignored" — so where both are present, this one is the answer and the
- * three-letter code is not.
- */
-const ID_CUES = 0x1c53bb6b;
-const ID_CUE_POINT = 0xbb;
-const ID_CUE_TRACK_POSITIONS = 0xb7;
-const ID_CUE_TRACK = 0xf7;
-const ID_CUE_CLUSTER_POSITION = 0xf1;
-
-/** TrackType 17 is subtitles; 1 is video and 2 audio. */
-const TRACK_TYPE_SUBTITLE = 17;
-/** How much of the file start to read: the same window the keyframe reader uses. */
-/** Cap on the Cues read; a long film indexes to tens of KB. */
-const MAX_CUES_BYTES = 8 * 1024 * 1024;
-
-/**
- * The codecs whose blocks are text this proxy can turn into WebVTT.
- *
- * `S_TEXT/UTF8` is a plain line of text and needs nothing. `S_TEXT/ASS` and
- * `S_TEXT/SSA` carry a dialogue row whose fields have to be stripped, and their
- * header lives in CodecPrivate — supported, with the stripping done where the
- * cue is turned into WebVTT. `S_HDMV/PGS` and `S_VOBSUB` are pictures, not
- * text, and are deliberately absent: offering them would promise something this
- * path cannot deliver.
- */
-const TEXT_CODECS = new Set(["S_TEXT/UTF8", "S_TEXT/ASS", "S_TEXT/SSA"]);
-
-/**
- * @typedef {object} SubtitleTrackPlan
- * @property {number} trackNumber - As the blocks name it.
- * @property {number} declaredIndex - Its position among ALL of the file's
- *   subtitle tracks, picture-based ones included — which is the number ffmpeg
- *   gives the same stream in `0:s:N`, and therefore the only number the browser
- *   ever names. Text tracks alone are not a numbering: a file whose PGS track
- *   comes first would have every text track one lower here than in the browser.
- * @property {string} codecId
- * @property {string} language - The language the file declares: its RFC 5646
- *   tag where it writes one, and the three-letter code otherwise. The
- *   specification requires that order — where `LanguageBCP47` is present, the
- *   `Language` element MUST be ignored.
- * @property {string} languageBcp47 - The RFC 5646 tag alone, or "".
- * @property {string} name - What the file calls the track, if anything.
- * @property {boolean} isDefault
- * @property {boolean} isForced - `FlagForced`: the track carries what a viewer
- *   needs even when they asked for no subtitles — signs, and dialogue in
- *   another language. It does NOT carry the film's own dialogue.
- * @property {boolean} isHearingImpaired - `FlagHearingImpaired`: suitable for
- *   viewers who cannot hear, so it carries non-speech sound as well as speech.
- * @property {string} codecPrivate - The ASS/SSA header, base64, or "".
- * @property {number[]} clusterPositions - File offsets of clusters whose cue
- *   points name this track, ascending. Empty when the file indexes only its
- *   picture, and then the caller has to walk clusters as they arrive instead.
- */
-
-
-/**
- * Everything about a file's text subtitle tracks that can be learned without
- * reading the film.
- *
- * @param {(start: number, end: number) => Promise<Buffer | null>} readRange
- * @param {number} fileSize
- * @returns {Promise<{ tracks: SubtitleTrackPlan[], declared: object[], secondsPerTick: number, segmentDataOffset: number } | null>}
- */
-async function readSubtitlePlan(readRange, fileSize) {
-  const head = await readRange(0, Math.min(HEAD_BYTES, Math.max(0, fileSize - 1)));
-  if (!head || head.length < 4 || head.readUInt32BE(0) !== 0x1a45dfa3) {
-    return null;
-  }
-  const segment = findElement(head, ID_SEGMENT, []);
-  if (!segment) {
-    return null;
-  }
-  const base = segment.dataOffset;
-
-  const info = findElement(head, ID_INFO, [], base);
-  let scale = DEFAULT_TIMESTAMP_SCALE;
-  if (info) {
-    const declared = findElement(head, ID_TIMESTAMP_SCALE, [], info.dataOffset, info.dataOffset + info.size);
-    if (declared) {
-      const value = readUint(head, declared.dataOffset, declared.size);
-      if (value > 0) {
-        scale = value;
-      }
-    }
-  }
-
-  const tracksElement = findElement(head, ID_TRACKS, [], base);
-  if (!tracksElement) {
-    return null;
+  // The Timestamp SHOULD come first (§5.1.3.1), not MUST: blocks before it are
+  // placed once the cluster's time is known.
+  if (clusterTicks === null) {
+    return blocks;
   }
-  const tracksEnd = Math.min(head.length, tracksElement.dataOffset + tracksElement.size);
-  /** @type {SubtitleTrackPlan[]} */
-  const tracks = [];
-  /**
-   * Every subtitle track the file declares, in the order the Tracks element
-   * names them, text or picture. This is not for extraction — `tracks` is —
-   * but for lining ffmpeg's `0:s:N` numbering up against the container, which
-   * only holds while nothing is missing from the middle of the list.
-   *
-   * @type {Array<{ trackNumber: number, codecId: string, language: string, name: string, isDefault: boolean, declaresDefault: boolean }>}
-   */
-  const declared = [];
-  for (const entry of iterateElements(head, tracksElement.dataOffset, tracksEnd)) {
-    if (entry.id !== ID_TRACK_ENTRY) {
-      continue;
-    }
-    const entryEnd = Math.min(tracksEnd, entry.dataOffset + entry.size);
-    let trackNumber = null;
-    let type = null;
-    let codecId = "";
-    let language = "";
-    let name = "";
-    let codecPrivate = "";
-    // Matroska's `FlagDefault` DEFAULTS TO 1, so a file whose muxer wrote it on
-    // no track is indistinguishable, once the default has been applied, from
-    // one that wrote it on every track — which is how ffmpeg's banner prints it
-    // and why the banner cannot answer this. Both are kept: what the flag
-    // amounts to, and whether the file said anything at all.
-    let isDefault = true;
-    let declaresDefault = false;
-    // Defaults straight from RFC 9559: a track is usable and not forced unless
-    // the file says otherwise, and the impaired flags are absent until claimed.
-    let isEnabled = true;
-    let isForced = false;
-    let isHearingImpaired = false;
-    let languageBcp47 = "";
-    for (const field of iterateElements(head, entry.dataOffset, entryEnd)) {
-      if (field.id === ID_TRACK_NUMBER) {
-        trackNumber = readUint(head, field.dataOffset, field.size);
-      } else if (field.id === ID_TRACK_TYPE) {
-        type = readUint(head, field.dataOffset, field.size);
-      } else if (field.id === ID_CODEC_ID) {
-        codecId = readString(head, field);
-      } else if (field.id === ID_LANGUAGE) {
-        language = readString(head, field);
-      } else if (field.id === ID_LANGUAGE_BCP47) {
-        languageBcp47 = readString(head, field);
-      } else if (field.id === ID_NAME) {
-        name = readString(head, field);
-      } else if (field.id === ID_FLAG_DEFAULT) {
-        isDefault = readUint(head, field.dataOffset, field.size) === 1;
-        declaresDefault = true;
-      } else if (field.id === ID_FLAG_ENABLED) {
-        // An element written with zero length carries its default, which for
-        // this one is 1 — so an empty element must not read as "unusable", and
-        // neither must a value outside the declared 0-1 range. Only an explicit
-        // zero takes a track away.
-        isEnabled = field.size === 0 || readUint(head, field.dataOffset, field.size) !== 0;
-      } else if (field.id === ID_FLAG_FORCED) {
-        isForced = field.size > 0 && readUint(head, field.dataOffset, field.size) !== 0;
-      } else if (field.id === ID_FLAG_HEARING_IMPAIRED) {
-        isHearingImpaired = field.size > 0 && readUint(head, field.dataOffset, field.size) !== 0;
-      } else if (field.id === ID_CODEC_PRIVATE) {
-        codecPrivate = head.toString("base64", field.dataOffset, field.dataOffset + field.size);
-      }
-    }
-    if (type !== TRACK_TYPE_SUBTITLE || trackNumber === null) {
-      continue;
-    }
-    // A track the file marks unusable is still COUNTED. FlagEnabled says "the
-    // track is usable", and a player should not offer it — but ffmpeg does not
-    // drop it: `matroskadec.c` parses `MATROSKA_ID_TRACKFLAGENABLED` as
-    // `EBML_NONE`, reading the element and keeping nothing, so the stream is
-    // created and numbered like any other. Leaving it out of this list would
-    // therefore shift `declaredIndex` off ffmpeg's `0:s:N` for every track
-    // after it, which is the numbering defect this file was fixed for a day
-    // earlier. It is counted here and refused where it is offered instead.
-    //
-    // `language` here stays the three-letter code, because this list exists to
-    // be lined up against ffmpeg's banner, which prints that code. The RFC 5646
-    // tag rides beside it for whoever displays the track.
-    const declaresLanguage = languageBcp47.length > 0 || language.length > 0;
-    declared.push({
-      trackNumber,
-      codecId,
-      language,
-      languageBcp47,
-      declaresLanguage,
-      name,
-      isDefault,
-      declaresDefault,
-      isEnabled,
-      isForced,
-      isHearingImpaired
-    });
-    if (!TEXT_CODECS.has(codecId) || !isEnabled) {
-      continue;
-    }
-    tracks.push({
-      trackNumber,
-      declaredIndex: declared.length - 1,
-      codecId,
-      // This list is ours and is not compared with ffmpeg's, so it carries the
-      // language the file states most precisely: where RFC 5646 is written, the
-      // three-letter code MUST be ignored.
-      language: languageBcp47 || language,
-      languageBcp47,
-      declaresLanguage,
-      name,
-      isDefault,
-      isForced,
-      isHearingImpaired,
-      codecPrivate,
-      clusterPositions: []
+  for (const block of pending) {
+    blocks.push({
+      startSeconds: (clusterTicks + block.relativeTicks) * secondsPerTick,
+      durationSeconds: block.durationTicks === null ? null : block.durationTicks * secondsPerTick,
+      payload: block.payload
     });
   }
-  if (tracks.length === 0) {
-    return { tracks, declared, secondsPerTick: scale / 1e9, segmentDataOffset: base };
-  }
-
-  // Where the clusters holding those tracks are. A file that indexes only its
-  // picture leaves these empty, which is not a failure: the caller then reads
-  // the clusters the viewer's own playback brings in.
-  const seekHead = findElement(head, ID_SEEK_HEAD, [], base);
-  let cuesRelative;
-  if (seekHead) {
-    const seekEnd = Math.min(head.length, seekHead.dataOffset + seekHead.size);
-    for (const seek of iterateElements(head, seekHead.dataOffset, seekEnd)) {
-      if (seek.id !== ID_SEEK) {
-        continue;
-      }
-      let target = null;
-      let position = null;
-      for (const field of iterateElements(head, seek.dataOffset, Math.min(seekEnd, seek.dataOffset + seek.size))) {
-        if (field.id === ID_SEEK_ID) {
-          target = readUint(head, field.dataOffset, field.size);
-        } else if (field.id === ID_SEEK_POSITION) {
-          position = readUint(head, field.dataOffset, field.size);
-        }
-      }
-      if (target === ID_CUES && position !== null) {
-        cuesRelative = position;
-      }
-    }
-  }
-  if (cuesRelative !== undefined) {
-    const cuesAt = base + cuesRelative;
-    if (cuesAt > 0 && cuesAt < fileSize) {
-      const chunk = await readRange(cuesAt, Math.min(fileSize - 1, cuesAt + MAX_CUES_BYTES));
-      const element = chunk && [...iterateElements(chunk, 0, chunk.length)][0];
-      if (element && element.id === ID_CUES) {
-        const body = chunk.subarray(element.dataOffset, Math.min(chunk.length, element.dataOffset + element.size));
-        const byTrack = new Map(tracks.map((track) => [track.trackNumber, new Set()]));
-        for (const point of iterateElements(body, 0, body.length)) {
-          if (point.id !== ID_CUE_POINT) {
-            continue;
-          }
-          const pointEnd = Math.min(body.length, point.dataOffset + point.size);
-          for (const field of iterateElements(body, point.dataOffset, pointEnd)) {
-            if (field.id !== ID_CUE_TRACK_POSITIONS) {
-              continue;
-            }
-            let cueTrack = null;
-            let position = null;
-            for (const inner of iterateElements(body, field.dataOffset, Math.min(pointEnd, field.dataOffset + field.size))) {
-              if (inner.id === ID_CUE_TRACK) {
-                cueTrack = readUint(body, inner.dataOffset, inner.size);
-              } else if (inner.id === ID_CUE_CLUSTER_POSITION) {
-                position = readUint(body, inner.dataOffset, inner.size);
-              }
-            }
-            if (position !== null && byTrack.has(cueTrack)) {
-              byTrack.get(cueTrack).add(base + position);
-            }
-          }
-        }
-        for (const track of tracks) {
-          track.clusterPositions = [...byTrack.get(track.trackNumber)].sort((left, right) => left - right);
-        }
-      }
-    }
-  }
-  return { tracks, declared, secondsPerTick: scale / 1e9, segmentDataOffset: base };
+  return blocks;
 }
 
 /**
- * The cues of one track inside one cluster.
+ * The cues of one track inside one cluster held whole in a buffer.
  *
  * @param {Buffer} bytes - The cluster, from its own element header onward.
  * @param {number} trackNumber
  * @param {number} secondsPerTick
- * @returns {{ startSeconds: number, endSeconds: number | null, text: string }[]}
+ * @returns {{ startSeconds: number, endSeconds: number | null, payload: Buffer }[]}
  */
 function harvestCluster(bytes, trackNumber, secondsPerTick) {
   const header = [...iterateElements(bytes, 0, bytes.length)][0];
   if (!header) {
     return [];
   }
-  const blocks = blocksOfTrack(
-    bytes,
-    { dataOffset: header.dataOffset, size: header.size },
-    trackNumber,
-    secondsPerTick
+  return blocksOfTrack(bytes, { dataOffset: header.dataOffset, size: header.size }, trackNumber, secondsPerTick).map(
+    (block) => ({
+      startSeconds: block.startSeconds,
+      endSeconds: block.durationSeconds === null ? null : block.startSeconds + block.durationSeconds,
+      payload: block.payload
+    })
   );
-  // The payload is handed on as BYTES. What those bytes mean — which of them
-  // are the text and which are the eight fields Matroska puts before it — is
-  // stated by the container's specification and answered by
-  // `MatroskaContainer.cueTextOf`, not here: this function's subject is where a
-  // block sits and how long it lasts.
-  return blocks.map((block) => ({
-    startSeconds: block.startSeconds,
-    endSeconds: block.durationSeconds === null ? null : block.startSeconds + block.durationSeconds,
-    payload: block.payload
-  }));
-}
-
-// ---------------------------------------------------------------------------
-// RFC 9559 speaking about Matroska: the Cues table that says where a keyframe is.
-// Here because the class is the only way in.
-// ---------------------------------------------------------------------------
-
-// Element ids, from the Matroska specification.
-const ID_CUE_TIME = 0xb3;
-// TrackType 1 is video; 2 is audio, 17 subtitles, and the rest are rarer still.
-const TRACK_TYPE_VIDEO = 1;
-
-// 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.
-// 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.
-// Cap on a Tracks read, for the rare file whose Tracks element sits outside the
-// head window. Track entries are small, so a file with dozens of them still
-// fits well inside this.
-const MAX_TRACKS_BYTES = 1024 * 1024;
-// Matroska's default timestamp scale (nanoseconds per tick) when Info omits it.
-
-/**
- * Whether this looks like a Matroska file (the EBML magic `0x1A45DFA3`).
- *
- * @param {Buffer} head
- * @returns {boolean}
- */
-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;
-}
-
-/**
- * The number of the first video track, from a Tracks payload.
- *
- * The FIRST one, because that is the track ffmpeg is told to copy (`0:v:0`).
- *
- * @param {Buffer} buffer
- * @param {{ dataOffset: number, size: number }} tracks
- * @returns {number | null}
- */
-function readVideoTrackNumber(buffer, tracks) {
-  const tracksEnd = Math.min(buffer.length, tracks.dataOffset + tracks.size);
-  for (const entry of iterateElements(buffer, tracks.dataOffset, tracksEnd)) {
-    if (entry.id !== ID_TRACK_ENTRY) {
-      continue;
-    }
-    const entryEnd = Math.min(tracksEnd, entry.dataOffset + entry.size);
-    let number = null;
-    let type = null;
-    for (const field of iterateElements(buffer, entry.dataOffset, entryEnd)) {
-      if (field.id === ID_TRACK_NUMBER) {
-        number = readUint(buffer, field.dataOffset, field.size);
-      } else if (field.id === ID_TRACK_TYPE) {
-        type = readUint(buffer, field.dataOffset, field.size);
-      }
-    }
-    if (number !== null && type === TRACK_TYPE_VIDEO) {
-      return number;
-    }
-  }
-  return null;
-}
-
-/**
- * Cue times (seconds, ascending) of ONE track, from a Cues payload.
- *
- * The track is the whole point, and leaving it out is what this reader got
- * wrong until 2026-08-18. A CuePoint belongs to the track named inside its
- * CueTrackPositions, and a muxer indexes whatever tracks it likes: RFC 9559
- * says each keyframe of a video track SHOULD be referenced, and that the Cues
- * Element "can be used to index every single timestamp of every Block or they
- * can be indexed selectively". Both field files index their SUBTITLE tracks as
- * well — `Minions.and.Monsters.1080p.mkv` has 2778 video entries every 2.002 s
- * plus 4669 across four subtitle tracks; `Moana.2 … MegaPeer.mkv` has 1055
- * video entries plus 5007 across five.
- *
- * Read without the track, those extra times enter the cut list as though they
- * were keyframes. ffmpeg can only cut a COPIED picture at a real keyframe at or
- * after the time it is given, so every cut asked for at one of them lands late
- * — which is exactly what the field measured: on the first file every deviation
- * was 2.002 s, that file's own keyframe spacing, and on the second the median
- * was 6.3 s with a worst case of 21 s. Never once negative.
- *
- * @param {Buffer} cues
- * @param {number} timestampScale - Nanoseconds per tick.
- * @param {number | null} trackNumber - Null keeps every entry, which is right
- *   only for a file that indexes one track.
- * @returns {number[]}
- */
-function readCueTimes(cues, timestampScale, trackNumber) {
-  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);
-    let time = null;
-    let belongsToTrack = trackNumber === null;
-    for (const field of iterateElements(cues, point.dataOffset, pointEnd)) {
-      if (field.id === ID_CUE_TIME) {
-        time = readUint(cues, field.dataOffset, field.size) * secondsPerTick;
-        continue;
-      }
-      if (field.id !== ID_CUE_TRACK_POSITIONS || belongsToTrack) {
-        continue;
-      }
-      const positionsEnd = Math.min(pointEnd, field.dataOffset + field.size);
-      for (const inner of iterateElements(cues, field.dataOffset, positionsEnd)) {
-        if (inner.id === ID_CUE_TRACK && readUint(cues, inner.dataOffset, inner.size) === trackNumber) {
-          belongsToTrack = true;
-          break;
-        }
-      }
-    }
-    if (time !== null && belongsToTrack) {
-      times.push(time);
-    }
-  }
-  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).
- */
-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);
-
-  // Whose entries to keep. Tracks sits near the head and is normally inside the
-  // bytes already fetched; when it is not, SeekHead says where it is and one
-  // more short read gets it. Nothing is fetched twice and nothing is scanned.
-  const videoTrack = await readVideoTrack(readRange, head, seekHead, fileSize);
-  const timestampScale = readTimestampScale(head, seekHead.segmentDataOffset);
-  const times = readCueTimes(payload, timestampScale, videoTrack);
-  if (times.length > 0) {
-    return times;
-  }
-  if (videoTrack === null) {
-    return null;
-  }
-  // The filter left nothing, and that is not an answer about the file: a table
-  // exists, and this reader simply failed to recognise which of its entries
-  // belong to the picture — a track numbered one way in Tracks and another in
-  // the cue points, or an entry with no CueTrack at all. Returning null here
-  // would put an EVEN grid on a copied picture, which is the failure this
-  // module exists to prevent, so the unfiltered table is used instead: less
-  // exact than the picture's own keyframes, better than a grid that has nothing
-  // to do with the file.
-  const unfiltered = readCueTimes(payload, timestampScale, null);
-  return unfiltered.length > 0 ? unfiltered : null;
-}
-
-/**
- * The video track's number — from the head when it is there, and from one extra
- * short read when it is not.
- *
- * @param {(start: number, end: number) => Promise<Buffer | null>} readRange
- * @param {Buffer} head
- * @param {{ segmentDataOffset: number, entries: Map<number, number> }} seekHead
- * @param {number} fileSize
- * @returns {Promise<number | null>} Null when Tracks cannot be read at all, and
- *   then every cue entry is kept — right for a file that indexes only its
- *   picture, wrong for one that does not, and nothing here can tell them apart.
- *   Refusing the index instead would put an even grid on a copied picture,
- *   which is the failure this reader exists to prevent.
- */
-async function readVideoTrack(readRange, head, seekHead, fileSize) {
-  const inHead = findElement(head, ID_TRACKS, [], seekHead.segmentDataOffset);
-  if (inHead && inHead.dataOffset + inHead.size <= head.length) {
-    return readVideoTrackNumber(head, inHead);
-  }
-  const relative = seekHead.entries.get(ID_TRACKS);
-  if (relative === undefined) {
-    return null;
-  }
-  const offset = seekHead.segmentDataOffset + relative;
-  if (!Number.isFinite(offset) || offset <= 0 || offset >= fileSize) {
-    return null;
-  }
-  const chunk = await readRange(offset, Math.min(fileSize - 1, offset + MAX_TRACKS_BYTES));
-  if (!chunk || chunk.length === 0) {
-    return null;
-  }
-  const element = [...iterateElements(chunk, 0, chunk.length)][0];
-  if (!element || element.id !== ID_TRACKS) {
-    return null;
-  }
-  return readVideoTrackNumber(chunk, { dataOffset: element.dataOffset, size: element.size });
 }