@torrent-tv/proxy 2.41.0 → 2.43.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 2.43.0
+
+- **New**: An MP4's text subtitles are read the same way, and more cheaply than Matroska's. Where a Matroska cue costs whatever cluster holds it — the picture around it included — an MP4 states every sample's own byte range in its sample table (ISO/IEC 14496-12 §8.6.1.2, §8.7.3-8.7.5), so a cue costs its own few dozen bytes and nothing else. The tables are read out of the `moov` the keyframe reader already fetches: `stts` for when each cue starts and how long it lasts, `stsz` for its length, `stsc` with `stco`/`co64` for where its bytes are. `tx3g` (3GPP timed text) and `wvtt` (WebVTT in MP4) are decoded; `stpp` (TTML) is XML and is deliberately left out rather than half-shown. An empty sample is the format's way of saying nothing is on screen and is not turned into a blank cue. Same rule as before: only samples whose bytes are already downloaded are read, so a cue never costs a request.
+- **Chore**: The MP4 reader has its own tests over a file built byte by byte — the sample table walked into times and offsets, the gap sample dropped, a `wvtt` payload decoded, and a file with no text track answering with nothing.
+
+## 2.42.0
+
+- **New**: Embedded text subtitles are read out of the clusters the film is already downloading, and no longer extracted with ffmpeg. Measured 2026-08-19 on `Minions.and.Monsters.1080p.mkv`: the browser asked for a track, gave up at its own 60 s limit, and the proxy answered **752 seconds later** with 3040 bytes — because a subtitle stream is sparse and ffmpeg walks the whole container whatever range is asked of it. Measured twice more to be sure: `-ss 1200 -t 4` read to the end of the file and pulled the download from 2.7 % to 81 % of 6.5 GB, and `-copyts -ss 600 -to 604` took 154 s on a copy already 81 % local and still emitted the whole track. A subtitle block sits in the same cluster as the picture around it, so those clusters are in hand anyway: the cue points of the subtitle track name them, the blocks are read where every piece covering them is already downloaded, and nothing is requested from the swarm. **Cost: zero extra bytes**, and the cues for the part being watched are ready before the viewer reaches it — which is the rule this was held to, subtitles arriving like the picture or not at all. On the field file the plan reads in 3.8 s over the swarm and names all four tracks with their languages, and the cues come out with their real times (`118.41s → 125.71s «МАГИЯ ГОЛЛИВУДА»`). A file this cannot be read from falls back to the old extraction, unchanged. `S_TEXT/UTF8` needs no conversion; `S_TEXT/ASS` and `S_TEXT/SSA` have their dialogue fields stripped; image subtitles (PGS, VobSub) are deliberately not offered, since this path cannot show them.
+- **Chore**: The Matroska block reader is its own module with its own tests (`services/container-index/matroska-blocks.js`): cluster time plus the block's own offset, the duration out of the block group, other tracks skipped, negative offsets placed correctly, and lacing stepped over rather than read as text.
+
 ## 2.41.0
 
 - **Fix**: An embedded subtitle track is prepared in the background and kept, instead of being extracted afresh inside a request the browser cannot hold open. Extracting one makes ffmpeg read the WHOLE film, because subtitles are interleaved through it — measured 2026-08-19 on a release with three tracks: track 0 produced **3040 bytes over 752 seconds**, track 1 76 KB over 193 s, track 2 68 KB over 55 s, with the data channel idle throughout (`maxBuffered=0`, the time all in reading the body). The browser gives up at sixty seconds, and every retry started the same twelve-minute scan again, so the first track never arrived at all. The route now starts the work once per `(source, file, track)`, answers `202 { pending: true }` while it runs, and serves the kept result the moment it exists. The scan still takes what it takes; what changes is that it happens once and its result is not thrown away.

package/package.json

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

package/routes/api/subtitles/get.js

@@ -96,6 +96,27 @@ export async function handleApiSubtitlesGet(req, reply, { sourceRegistry, torren
     return reply.code(400).send({ error: "trackIndex must be a non-negative integer." });
   }
 
+  // From the clusters the viewer has already downloaded, if this file can be
+  // read that way. Costs no network at all and answers with the part of the
+  // film they are watching; the rest arrives as they watch it. Only when the
+  // container cannot be read this way does the old extraction run.
+  const held = await cuesFromDownloadedClusters(torrentPool, torrent, fileIndex, trackIndex);
+  if (held !== null) {
+    setLanguageHeaders(reply, held.language);
+    reply.header("content-type", "text/vtt; charset=utf-8");
+    reply.header("cache-control", "no-store");
+    reply.header("access-control-allow-origin", "*");
+    // How much of the film these cues cover, so the browser knows to ask again
+    // as playback moves into clusters that were not downloaded yet.
+    reply.header("X-Subtitle-Covered-Clusters", String(held.coveredClusters));
+    reply.header("X-Subtitle-Indexed-Clusters", String(held.indexedClusters));
+    reply.raw.setHeader(
+      "Access-Control-Expose-Headers",
+      "X-Subtitle-Language, X-Subtitle-Language-Name, X-Subtitle-Covered-Clusters, X-Subtitle-Indexed-Clusters"
+    );
+    return reply.send(held.vtt);
+  }
+
   const inputUrl = new URL("/stream", `${localBaseUrl}/`);
   inputUrl.searchParams.set("sourceKey", sourceKey);
   inputUrl.searchParams.set("fileIndex", String(fileIndex));
@@ -215,3 +236,115 @@ function readFileFully(file, maxBytes) {
     stream.on("error", reject);
   });
 }
+
+/**
+ * The cues of a track from clusters already downloaded, as WebVTT.
+ *
+ * `trackIndex` is the browser's number for the subtitle stream — its position
+ * among the subtitle streams, as ffprobe lists them — while Matroska blocks
+ * carry the file's own track number. The plan lists the text tracks in file
+ * order, so the browser's Nth subtitle stream is the Nth entry.
+ *
+ * @param {object} torrentPool
+ * @param {object} torrent
+ * @param {number} fileIndex
+ * @param {number} trackIndex
+ * @returns {Promise<{ vtt: string, language: object | null, coveredClusters: number, indexedClusters: number } | null>}
+ *   Null when this file cannot be read this way, and then the caller falls back.
+ */
+async function cuesFromDownloadedClusters(torrentPool, torrent, fileIndex, trackIndex) {
+  if (typeof torrentPool?.getSubtitleTracks !== "function") {
+    return null;
+  }
+  let tracks;
+  try {
+    tracks = await torrentPool.getSubtitleTracks(torrent, fileIndex);
+  } catch {
+    return null;
+  }
+  const track = Array.isArray(tracks) ? tracks[trackIndex] : null;
+  if (!track) {
+    return null;
+  }
+  let held;
+  try {
+    held = await torrentPool.getSubtitleCues(torrent, fileIndex, track.trackNumber);
+  } catch {
+    return null;
+  }
+  if (!held || !Array.isArray(held.cues)) {
+    return null;
+  }
+  const vtt = cuesToVtt(held.cues, held.codecId);
+  const language = held.cues.length > 0
+    ? detectLanguage(held.cues.map((cue) => cue.text).join("\n"))
+    : null;
+  return {
+    vtt,
+    language,
+    coveredClusters: held.coveredClusters ?? 0,
+    indexedClusters: held.indexedClusters ?? 0
+  };
+}
+
+/**
+ * WebVTT from cues read out of the container.
+ *
+ * A cue with no duration — a SimpleBlock, which subtitles rarely use — is given
+ * the time until the next one, and the last such cue a few seconds. That is not
+ * an invention about the film: it is what a player does with an open-ended cue,
+ * made explicit here so the file is valid.
+ *
+ * @param {{ startSeconds: number, endSeconds: number | null, text: string }[]} cues
+ * @param {string} codecId
+ * @returns {string}
+ */
+function cuesToVtt(cues, codecId) {
+  const lines = ["WEBVTT", ""];
+  const isAss = codecId === "S_TEXT/ASS" || codecId === "S_TEXT/SSA";
+  cues.forEach((cue, index) => {
+    const next = cues[index + 1];
+    const end = cue.endSeconds ?? (next ? next.startSeconds : cue.startSeconds + 4);
+    const text = isAss ? assDialogueToText(cue.text) : cue.text.trim();
+    if (!text) {
+      return;
+    }
+    lines.push(`${vttTime(cue.startSeconds)} --> ${vttTime(end)}`);
+    lines.push(text);
+    lines.push("");
+  });
+  return lines.join("\n");
+}
+
+/**
+ * The visible text of an ASS dialogue row.
+ *
+ * A block carries the fields after `Dialogue:` without their header — nine of
+ * them, then the text, which itself holds override groups in braces.
+ *
+ * @param {string} raw
+ * @returns {string}
+ */
+function assDialogueToText(raw) {
+  const fields = raw.split(",");
+  const text = fields.length > 9 ? fields.slice(9).join(",") : raw;
+  return text
+    .replace(/\{[^}]*\}/g, "")
+    .replace(/\\N/gi, "\n")
+    .trim();
+}
+
+/**
+ * A time in the form WebVTT requires.
+ *
+ * @param {number} seconds
+ * @returns {string}
+ */
+function vttTime(seconds) {
+  const safe = Math.max(0, seconds);
+  const hours = Math.floor(safe / 3600);
+  const minutes = Math.floor((safe % 3600) / 60);
+  const rest = safe % 60;
+  return `${String(hours).padStart(2, "0")}:${String(minutes).padStart(2, "0")}:` +
+    `${rest.toFixed(3).padStart(6, "0")}`;
+}

package/services/container-index/matroska-blocks.js

@@ -0,0 +1,202 @@
+/**
+ * @file Subtitle blocks out of Matroska clusters, from bytes already in hand.
+ *
+ * A subtitle track is sparse — a few kilobytes spread across a whole film — and
+ * ffmpeg cannot extract a time range of one without walking the container to
+ * the end. Measured 2026-08-19 on `Minions.and.Monsters.1080p.mkv`: asking for
+ * four seconds at minute twenty read the file through and pulled the download
+ * from 2.7 % to 81 %; asking with `-copyts -ss -to` took 154 s on a copy that
+ * was already 81 % local and still emitted the whole track. So the subtitles
+ * are not asked of ffmpeg.
+ *
+ * They do not have to be. A subtitle block sits in the same cluster as the
+ * picture around it, and those clusters are being downloaded anyway for the
+ * viewer to watch. Reading them as they arrive costs no network at all, and it
+ * puts the cues ahead of the playhead by construction — which is the whole
+ * requirement: subtitles arrive like the picture does, or they are not offered.
+ *
+ * This module is the byte-level half: given a cluster's bytes, it returns the
+ * blocks of one track with their times. It reads element headers and skips
+ * payloads by their declared length; nothing is decoded.
+ *
+ * Structure, from RFC 9559 §5.1.3 and §5.1.4:
+ *
+ *   Cluster (0x1F43B675)
+ *     Timestamp (0xE7)            — the cluster's own time, in ticks
+ *     SimpleBlock (0xA3)          — a block with no duration of its own
+ *     BlockGroup (0xA0)
+ *       Block (0xA1)              — the same header, and where subtitles live
+ *       BlockDuration (0x9B)      — how long the cue stays on screen
+ *
+ * A block's header is: the track number as a variable-length integer, a signed
+ * 16-bit timestamp relative to the cluster, and one byte of flags. Subtitles
+ * are normally in a BlockGroup, because a cue without a duration has no end.
+ */
+
+import { iterateElements, readUint, readVint } from "./ebml-reader.js";
+
+const ID_TIMESTAMP = 0xe7;
+const ID_SIMPLE_BLOCK = 0xa3;
+const ID_BLOCK_GROUP = 0xa0;
+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[]}
+ */
+export 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;
+}

package/services/container-index/matroska-subtitles.js

@@ -0,0 +1,262 @@
+/**
+ * @file The subtitle tracks of a Matroska file, and where their cues live.
+ *
+ * Two halves, both reading only what is asked for by byte range:
+ *
+ *   - {@link readSubtitlePlan} — once per file: which tracks are text
+ *     subtitles, in what codec, and the cluster positions their cue points
+ *     name. Two short reads, the head and the Cues element, exactly as the
+ *     keyframe reader already does.
+ *   - {@link harvestCluster} — per cluster, over bytes already downloaded:
+ *     the cues inside it, ready to be shown.
+ *
+ * Kept apart from `matroska.js` because that file answers one question (where
+ * are the keyframes) and is read on the path that starts playback; this one is
+ * only ever consulted for a viewer who asked for subtitles.
+ */
+
+import { findElement, iterateElements, readUint } from "./ebml-reader.js";
+import { blocksOfTrack } from "./matroska-blocks.js";
+
+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_TRACKS = 0x1654ae6b;
+const ID_TRACK_ENTRY = 0xae;
+const ID_TRACK_NUMBER = 0xd7;
+const ID_TRACK_TYPE = 0x83;
+const ID_CODEC_ID = 0x86;
+const ID_CODEC_PRIVATE = 0x63a2;
+const ID_LANGUAGE = 0x22b59c;
+const ID_NAME = 0x536e;
+const ID_FLAG_DEFAULT = 0x88;
+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. */
+const HEAD_BYTES = 64 * 1024;
+/** Cap on the Cues read; a long film indexes to tens of KB. */
+const MAX_CUES_BYTES = 8 * 1024 * 1024;
+const DEFAULT_TIMESTAMP_SCALE = 1_000_000;
+
+/**
+ * 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 {string} codecId
+ * @property {string} language - The three-letter code the file declares.
+ * @property {string} name - What the file calls the track, if anything.
+ * @property {boolean} isDefault
+ * @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.
+ */
+
+/**
+ * Read a string element, trimming the padding some muxers leave.
+ *
+ * @param {Buffer} buffer
+ * @param {{ dataOffset: number, size: number }} element
+ * @returns {string}
+ */
+function readString(buffer, element) {
+  return buffer
+    .toString("utf8", element.dataOffset, element.dataOffset + element.size)
+    .replace(/\0+$/, "");
+}
+
+/**
+ * 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[], secondsPerTick: number, segmentDataOffset: number } | null>}
+ */
+export 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 = [];
+  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 = "";
+    let isDefault = true;
+    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_NAME) {
+        name = readString(head, field);
+      } else if (field.id === ID_FLAG_DEFAULT) {
+        isDefault = readUint(head, field.dataOffset, field.size) === 1;
+      } else if (field.id === ID_CODEC_PRIVATE) {
+        codecPrivate = head.toString("base64", field.dataOffset, field.dataOffset + field.size);
+      }
+    }
+    if (type !== TRACK_TYPE_SUBTITLE || trackNumber === null || !TEXT_CODECS.has(codecId)) {
+      continue;
+    }
+    tracks.push({
+      trackNumber,
+      codecId,
+      language,
+      name,
+      isDefault,
+      codecPrivate,
+      clusterPositions: []
+    });
+  }
+  if (tracks.length === 0) {
+    return { tracks, 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, 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 }[]}
+ */
+export function harvestCluster(bytes, trackNumber, secondsPerTick) {
+  const header = [...iterateElements(bytes, 0, bytes.length)][0];
+  if (!header) {
+    return [];
+  }
+  const blocks = blocksOfTrack(
+    bytes,
+    { dataOffset: header.dataOffset, size: header.size },
+    trackNumber,
+    secondsPerTick
+  );
+  return blocks.map((block) => ({
+    startSeconds: block.startSeconds,
+    endSeconds: block.durationSeconds === null ? null : block.startSeconds + block.durationSeconds,
+    text: block.payload.toString("utf8")
+  }));
+}