@torrent-tv/proxy 2.87.20 → 2.88.0

package/services/media/container/MatroskaContainer.js

@@ -1,1494 +1,1494 @@
-/**
- * @file Matroska/WebM container — RFC 9559.
- *
- * Reads Tracks in one pass for all media types (video, audio, subtitle).
- * Implements spec-accurate flag handling:
- *  - FlagEnabled 0xB9 default 1, zero-length element = default (not disabled)
- *  - 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
- *  - 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.
- */
-
-import { Container } from "./Container.js";
-import { VideoTrack } from "../tracks/VideoTrack.js";
-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";
-
-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_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_DURATION = 0x4489;
-const ID_CLUSTER = 0x1f43b675;
-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_TRACKS = 0x1654ae6b;
-const ID_TRACK_ENTRY = 0xae;
-const ID_TRACK_NUMBER = 0xd7;
-const ID_TRACK_TYPE = 0x83;
-const ID_FLAG_ENABLED = 0xb9;
-const ID_FLAG_DEFAULT = 0x88;
-const ID_FLAG_FORCED = 0x55aa;
-const ID_FLAG_HEARING = 0x55ab;
-const ID_FLAG_VISUAL = 0x55ac;
-const ID_FLAG_TEXT_DESCR = 0x55ad;
-const ID_FLAG_ORIGINAL = 0x55ae;
-const ID_FLAG_COMMENTARY = 0x55af;
-const ID_CODEC_ID = 0x86;
-const ID_CODEC_PRIVATE = 0x63a2;
-const ID_LANGUAGE = 0x22b59c;
-const ID_LANGUAGE_BCP47 = 0x22b59d;
-const ID_NAME = 0x536e;
-const ID_VIDEO = 0xe0;
-const ID_AUDIO = 0xe1;
-const ID_PIXEL_WIDTH = 0xb0;
-const ID_PIXEL_HEIGHT = 0xba;
-const ID_DISPLAY_WIDTH = 0x54b0;
-const ID_DISPLAY_HEIGHT = 0x54ba;
-const ID_SAMPLING_FREQUENCY = 0xb5;
-const ID_CHANNELS = 0x9f;
-/**
- * ReadOrder, Layer, Style, Name, MarginL, MarginR, MarginV, Effect — the eight
- * fields Matroska writes before the text of an SSA/ASS event. See
- * {@link MatroskaContainer.cueTextOf} for the quotation this comes from.
- */
-const ASS_FIELDS_BEFORE_TEXT = 8;
-
-function readString(buf, el) {
-  return buf.toString("utf8", el.dataOffset, el.dataOffset + el.size).replace(/\0+$/, "");
-}
-
-export class MatroskaContainer extends Container {
-  get formatName() {
-    return "matroska";
-  }
-
-  static detect(head) {
-    return isMatroska(head);
-  }
-
-  /**
-   * 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}.
-   *
-   * @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);
-  }
-
-  /**
-   * 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);
-  }
-
-  /**
-   * 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.
-   *
-   * @param {Buffer} bytes - The cluster, from its own element header onward.
-   * @param {number} trackNumber
-   * @param {number} secondsPerTick
-   * @returns {{ startSeconds: number, endSeconds: number | null, payload: Buffer }[]}
-   */
-  static blocksInCluster(bytes, trackNumber, secondsPerTick) {
-    return harvestCluster(bytes, trackNumber, secondsPerTick);
-  }
-
-  /**
-   * 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
-   * @param {number} secondsPerTick
-   * @returns {{ startSeconds: number, durationSeconds: number | null, payload: Buffer }[]}
-   */
-  static blocksOfTrack(buffer, cluster, trackNumber, secondsPerTick) {
-    return blocksOfTrack(buffer, cluster, trackNumber, secondsPerTick);
-  }
-
-  /**
-   * 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.
-   *
-   * @returns {Promise<import("./Container.js").ContainerMediaInfo>}
-   */
-  async readMediaInfo() {
-    if (this.mediaInfo) {
-      return this.mediaInfo;
-    }
-    /** @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) {
-      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;
-        }
-        break;
-      }
-    }
-    info.startTimeSeconds = await this.#firstClusterSeconds(head, segment.dataOffset, scale);
-    return info;
-  }
-
-  /**
-   * `TimestampScale` from Info, or the specification's default.
-   *
-   * @param {Buffer} head
-   * @param {number} segmentDataOffset
-   * @returns {number} Nanoseconds per tick.
-   */
-  static #timestampScaleOf(head, segmentDataOffset) {
-    const infoElement = findElement(head, ID_INFO, [], segmentDataOffset);
-    if (!infoElement) {
-      return DEFAULT_TIMESTAMP_SCALE;
-    }
-    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;
-      }
-    }
-    return DEFAULT_TIMESTAMP_SCALE;
-  }
-
-  /**
-   * The timestamp of the first Cluster, in seconds.
-   *
-   * 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.
-   */
-  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));
-    }
-
-    const position = MatroskaContainer.#seekPositionOf(head, segmentDataOffset, ID_CLUSTER);
-    if (position === null) {
-      return null;
-    }
-    const at = segmentDataOffset + position;
-    if (at >= this.fileSize) {
-      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;
-      }
-      return timestampIn(chunk, element.dataOffset, Math.min(chunk.length, element.dataOffset + element.size));
-    }
-    return null;
-  }
-
-  /**
-   * Where the SeekHead says an element lives, relative to the Segment's payload.
-   *
-   * @param {Buffer} head
-   * @param {number} segmentDataOffset
-   * @param {number} wantedId
-   * @returns {number | null}
-   */
-  static #seekPositionOf(head, segmentDataOffset, wantedId) {
-    const seekHead = findElement(head, ID_SEEK_HEAD, [], segmentDataOffset);
-    if (!seekHead) {
-      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);
-        }
-      }
-      if (targetId === wantedId && position !== null) {
-        return position;
-      }
-    }
-    return null;
-  }
-
-
-  /**
-   * 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.
-   *
-   * @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.
-   */
-  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[]>} */
-    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) {
-        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
-        }));
-      }
-    }
-    return result;
-  }
-
-  /**
-   * The text field of one cue as Matroska frames it.
-   *
-   * Two rules, both from `matroska.org/technical/subtitles.html`, "Now, how are
-   * they stored in Matroska?":
-   *
-   * 1. "All text is converted to UTF-8", so the block is decoded as UTF-8 and
-   *    no other encoding is guessed at. A subtitle FILE is a different matter —
-   *    there the bytes may be Windows-1251 and `decodeSubtitleBytes` sniffs for
-   *    it — but a muxer had to convert before writing the block.
-   * 2. "Events are stored in the Block in this order: ReadOrder, Layer, Style,
-   *    Name, MarginL, MarginR, MarginV, Effect, Text", and "Start & End field
-   *    are used to set TimeStamp and the BlockDuration element". So eight fields
-   *    stand before the text, the two timing fields of the file's own row are
-   *    NOT among them, and a read order takes their place at the front. The text
-   *    itself may hold commas, so everything from the ninth field on is joined
-   *    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.)
-   *
-   * @param {Buffer} payload - The block's own bytes.
-   * @param {string} codecId - Matroska CodecID of the track the block belongs to.
-   * @returns {string}
-   */
-  static cueTextOf(payload, codecId) {
-    const text = Buffer.isBuffer(payload) ? payload.toString("utf8") : String(payload ?? "");
-    if (codecId !== "S_TEXT/ASS" && codecId !== "S_TEXT/SSA") {
-      return text;
-    }
-    const fields = text.split(",");
-    return fields.length > ASS_FIELDS_BEFORE_TEXT ? fields.slice(ASS_FIELDS_BEFORE_TEXT).join(",") : "";
-  }
-
-  async parseKeyframeIndex() {
-    const times = await readMatroskaKeyframeTimes(this.readRange, this.fileSize);
-    if (!times) return null;
-    if (Array.isArray(times)) return { times, tolerance: 0 };
-    return times;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// 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.
- */
-
-/**
- * Read one block's header.
- *
- * @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}
- */
-function readBlockHeader(buffer, start, end) {
-  const track = readVint(buffer, start, false);
-  if (!track || track.value === null) {
-    return null;
-  }
-  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 {
-    trackNumber: Number(track.value),
-    relativeTicks: buffer.readInt16BE(timestampAt),
-    flags: buffer[timestampAt + 2],
-    dataOffset: timestampAt + 3
-  };
-}
-
-/**
- * Where a laced block's first frame begins.
- *
- * 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.
- *
- * @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.
- */
-function firstFrameOffset(buffer, dataOffset, end, flags) {
-  const lacing = flags & LACING_MASK;
-  if (lacing === LACING_NONE) {
-    return dataOffset;
-  }
-  if (dataOffset >= end) {
-    return null;
-  }
-  const frames = buffer[dataOffset] + 1;
-  let at = dataOffset + 1;
-  if (lacing === LACING_FIXED) {
-    return at;
-  }
-  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;
-      }
-      at += 1;
-    }
-    return at <= end ? at : null;
-  }
-  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;
-      }
-      at += size.length;
-    }
-    return at <= end ? at : null;
-  }
-  return null;
-}
-
-/**
- * Every block of one track inside one cluster.
- *
- * @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[]}
- */
-function blocksOfTrack(buffer, cluster, trackNumber, secondsPerTick) {
-  const end = Math.min(buffer.length, cluster.dataOffset + cluster.size);
-  /** @type {SubtitleBlock[]} */
-  const blocks = [];
-  let clusterTicks = null;
-
-  const take = (blockStart, blockEnd, durationTicks) => {
-    const header = readBlockHeader(buffer, blockStart, blockEnd);
-    if (!header || header.trackNumber !== trackNumber || clusterTicks === null) {
-      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)
-    });
-  };
-
-  for (const element of iterateElements(buffer, cluster.dataOffset, end)) {
-    const elementEnd = Math.min(end, element.dataOffset + element.size);
-    if (element.id === ID_TIMESTAMP) {
-      clusterTicks = readUint(buffer, element.dataOffset, element.size);
-      continue;
-    }
-    if (element.id === ID_SIMPLE_BLOCK) {
-      take(element.dataOffset, elementEnd, null);
-      continue;
-    }
-    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;
-    for (const field of iterateElements(buffer, element.dataOffset, elementEnd)) {
-      const fieldEnd = Math.min(elementEnd, field.dataOffset + field.size);
-      if (field.id === ID_BLOCK) {
-        blockStart = field.dataOffset;
-        blockEnd = fieldEnd;
-      } else if (field.id === ID_BLOCK_DURATION) {
-        durationTicks = readUint(buffer, field.dataOffset, field.size);
-      }
-    }
-    if (blockStart !== null) {
-      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;
-  }
-  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: []
-    });
-  }
-  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 };
-}
-
-/**
- * The cues of one track inside one cluster.
- *
- * @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 }[]}
- */
-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
-  );
-  // 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 });
-}
+/**
+ * @file Matroska/WebM container — RFC 9559.
+ *
+ * Reads Tracks in one pass for all media types (video, audio, subtitle).
+ * Implements spec-accurate flag handling:
+ *  - FlagEnabled 0xB9 default 1, zero-length element = default (not disabled)
+ *  - 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
+ *  - 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.
+ */
+
+import { Container } from "./Container.js";
+import { VideoTrack } from "../tracks/VideoTrack.js";
+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";
+
+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_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_DURATION = 0x4489;
+const ID_CLUSTER = 0x1f43b675;
+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_TRACKS = 0x1654ae6b;
+const ID_TRACK_ENTRY = 0xae;
+const ID_TRACK_NUMBER = 0xd7;
+const ID_TRACK_TYPE = 0x83;
+const ID_FLAG_ENABLED = 0xb9;
+const ID_FLAG_DEFAULT = 0x88;
+const ID_FLAG_FORCED = 0x55aa;
+const ID_FLAG_HEARING = 0x55ab;
+const ID_FLAG_VISUAL = 0x55ac;
+const ID_FLAG_TEXT_DESCR = 0x55ad;
+const ID_FLAG_ORIGINAL = 0x55ae;
+const ID_FLAG_COMMENTARY = 0x55af;
+const ID_CODEC_ID = 0x86;
+const ID_CODEC_PRIVATE = 0x63a2;
+const ID_LANGUAGE = 0x22b59c;
+const ID_LANGUAGE_BCP47 = 0x22b59d;
+const ID_NAME = 0x536e;
+const ID_VIDEO = 0xe0;
+const ID_AUDIO = 0xe1;
+const ID_PIXEL_WIDTH = 0xb0;
+const ID_PIXEL_HEIGHT = 0xba;
+const ID_DISPLAY_WIDTH = 0x54b0;
+const ID_DISPLAY_HEIGHT = 0x54ba;
+const ID_SAMPLING_FREQUENCY = 0xb5;
+const ID_CHANNELS = 0x9f;
+/**
+ * ReadOrder, Layer, Style, Name, MarginL, MarginR, MarginV, Effect — the eight
+ * fields Matroska writes before the text of an SSA/ASS event. See
+ * {@link MatroskaContainer.cueTextOf} for the quotation this comes from.
+ */
+const ASS_FIELDS_BEFORE_TEXT = 8;
+
+function readString(buf, el) {
+  return buf.toString("utf8", el.dataOffset, el.dataOffset + el.size).replace(/\0+$/, "");
+}
+
+export class MatroskaContainer extends Container {
+  get formatName() {
+    return "matroska";
+  }
+
+  static detect(head) {
+    return isMatroska(head);
+  }
+
+  /**
+   * 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}.
+   *
+   * @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);
+  }
+
+  /**
+   * 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);
+  }
+
+  /**
+   * 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.
+   *
+   * @param {Buffer} bytes - The cluster, from its own element header onward.
+   * @param {number} trackNumber
+   * @param {number} secondsPerTick
+   * @returns {{ startSeconds: number, endSeconds: number | null, payload: Buffer }[]}
+   */
+  static blocksInCluster(bytes, trackNumber, secondsPerTick) {
+    return harvestCluster(bytes, trackNumber, secondsPerTick);
+  }
+
+  /**
+   * 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
+   * @param {number} secondsPerTick
+   * @returns {{ startSeconds: number, durationSeconds: number | null, payload: Buffer }[]}
+   */
+  static blocksOfTrack(buffer, cluster, trackNumber, secondsPerTick) {
+    return blocksOfTrack(buffer, cluster, trackNumber, secondsPerTick);
+  }
+
+  /**
+   * 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.
+   *
+   * @returns {Promise<import("./Container.js").ContainerMediaInfo>}
+   */
+  async readMediaInfo() {
+    if (this.mediaInfo) {
+      return this.mediaInfo;
+    }
+    /** @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) {
+      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;
+        }
+        break;
+      }
+    }
+    info.startTimeSeconds = await this.#firstClusterSeconds(head, segment.dataOffset, scale);
+    return info;
+  }
+
+  /**
+   * `TimestampScale` from Info, or the specification's default.
+   *
+   * @param {Buffer} head
+   * @param {number} segmentDataOffset
+   * @returns {number} Nanoseconds per tick.
+   */
+  static #timestampScaleOf(head, segmentDataOffset) {
+    const infoElement = findElement(head, ID_INFO, [], segmentDataOffset);
+    if (!infoElement) {
+      return DEFAULT_TIMESTAMP_SCALE;
+    }
+    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;
+      }
+    }
+    return DEFAULT_TIMESTAMP_SCALE;
+  }
+
+  /**
+   * The timestamp of the first Cluster, in seconds.
+   *
+   * 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.
+   */
+  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));
+    }
+
+    const position = MatroskaContainer.#seekPositionOf(head, segmentDataOffset, ID_CLUSTER);
+    if (position === null) {
+      return null;
+    }
+    const at = segmentDataOffset + position;
+    if (at >= this.fileSize) {
+      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;
+      }
+      return timestampIn(chunk, element.dataOffset, Math.min(chunk.length, element.dataOffset + element.size));
+    }
+    return null;
+  }
+
+  /**
+   * Where the SeekHead says an element lives, relative to the Segment's payload.
+   *
+   * @param {Buffer} head
+   * @param {number} segmentDataOffset
+   * @param {number} wantedId
+   * @returns {number | null}
+   */
+  static #seekPositionOf(head, segmentDataOffset, wantedId) {
+    const seekHead = findElement(head, ID_SEEK_HEAD, [], segmentDataOffset);
+    if (!seekHead) {
+      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);
+        }
+      }
+      if (targetId === wantedId && position !== null) {
+        return position;
+      }
+    }
+    return null;
+  }
+
+
+  /**
+   * 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.
+   *
+   * @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.
+   */
+  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[]>} */
+    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) {
+        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
+        }));
+      }
+    }
+    return result;
+  }
+
+  /**
+   * The text field of one cue as Matroska frames it.
+   *
+   * Two rules, both from `matroska.org/technical/subtitles.html`, "Now, how are
+   * they stored in Matroska?":
+   *
+   * 1. "All text is converted to UTF-8", so the block is decoded as UTF-8 and
+   *    no other encoding is guessed at. A subtitle FILE is a different matter —
+   *    there the bytes may be Windows-1251 and `decodeSubtitleBytes` sniffs for
+   *    it — but a muxer had to convert before writing the block.
+   * 2. "Events are stored in the Block in this order: ReadOrder, Layer, Style,
+   *    Name, MarginL, MarginR, MarginV, Effect, Text", and "Start & End field
+   *    are used to set TimeStamp and the BlockDuration element". So eight fields
+   *    stand before the text, the two timing fields of the file's own row are
+   *    NOT among them, and a read order takes their place at the front. The text
+   *    itself may hold commas, so everything from the ninth field on is joined
+   *    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.)
+   *
+   * @param {Buffer} payload - The block's own bytes.
+   * @param {string} codecId - Matroska CodecID of the track the block belongs to.
+   * @returns {string}
+   */
+  static cueTextOf(payload, codecId) {
+    const text = Buffer.isBuffer(payload) ? payload.toString("utf8") : String(payload ?? "");
+    if (codecId !== "S_TEXT/ASS" && codecId !== "S_TEXT/SSA") {
+      return text;
+    }
+    const fields = text.split(",");
+    return fields.length > ASS_FIELDS_BEFORE_TEXT ? fields.slice(ASS_FIELDS_BEFORE_TEXT).join(",") : "";
+  }
+
+  async parseKeyframeIndex() {
+    const times = await readMatroskaKeyframeTimes(this.readRange, this.fileSize);
+    if (!times) return null;
+    if (Array.isArray(times)) return { times, tolerance: 0 };
+    return times;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 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.
+ */
+
+/**
+ * Read one block's header.
+ *
+ * @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}
+ */
+function readBlockHeader(buffer, start, end) {
+  const track = readVint(buffer, start, false);
+  if (!track || track.value === null) {
+    return null;
+  }
+  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 {
+    trackNumber: Number(track.value),
+    relativeTicks: buffer.readInt16BE(timestampAt),
+    flags: buffer[timestampAt + 2],
+    dataOffset: timestampAt + 3
+  };
+}
+
+/**
+ * Where a laced block's first frame begins.
+ *
+ * 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.
+ *
+ * @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.
+ */
+function firstFrameOffset(buffer, dataOffset, end, flags) {
+  const lacing = flags & LACING_MASK;
+  if (lacing === LACING_NONE) {
+    return dataOffset;
+  }
+  if (dataOffset >= end) {
+    return null;
+  }
+  const frames = buffer[dataOffset] + 1;
+  let at = dataOffset + 1;
+  if (lacing === LACING_FIXED) {
+    return at;
+  }
+  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;
+      }
+      at += 1;
+    }
+    return at <= end ? at : null;
+  }
+  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;
+      }
+      at += size.length;
+    }
+    return at <= end ? at : null;
+  }
+  return null;
+}
+
+/**
+ * Every block of one track inside one cluster.
+ *
+ * @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[]}
+ */
+function blocksOfTrack(buffer, cluster, trackNumber, secondsPerTick) {
+  const end = Math.min(buffer.length, cluster.dataOffset + cluster.size);
+  /** @type {SubtitleBlock[]} */
+  const blocks = [];
+  let clusterTicks = null;
+
+  const take = (blockStart, blockEnd, durationTicks) => {
+    const header = readBlockHeader(buffer, blockStart, blockEnd);
+    if (!header || header.trackNumber !== trackNumber || clusterTicks === null) {
+      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)
+    });
+  };
+
+  for (const element of iterateElements(buffer, cluster.dataOffset, end)) {
+    const elementEnd = Math.min(end, element.dataOffset + element.size);
+    if (element.id === ID_TIMESTAMP) {
+      clusterTicks = readUint(buffer, element.dataOffset, element.size);
+      continue;
+    }
+    if (element.id === ID_SIMPLE_BLOCK) {
+      take(element.dataOffset, elementEnd, null);
+      continue;
+    }
+    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;
+    for (const field of iterateElements(buffer, element.dataOffset, elementEnd)) {
+      const fieldEnd = Math.min(elementEnd, field.dataOffset + field.size);
+      if (field.id === ID_BLOCK) {
+        blockStart = field.dataOffset;
+        blockEnd = fieldEnd;
+      } else if (field.id === ID_BLOCK_DURATION) {
+        durationTicks = readUint(buffer, field.dataOffset, field.size);
+      }
+    }
+    if (blockStart !== null) {
+      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;
+  }
+  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: []
+    });
+  }
+  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 };
+}
+
+/**
+ * The cues of one track inside one cluster.
+ *
+ * @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 }[]}
+ */
+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
+  );
+  // 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 });
+}