@torrent-tv/proxy 2.42.0 → 2.43.0

package/CHANGELOG.md

@@ -1,4 +1,9 @@
-## 2.41.0
+## 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.

package/package.json

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

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

@@ -0,0 +1,380 @@
+/**
+ * @file The text subtitle tracks of an MP4, and where each cue's bytes are.
+ *
+ * The same rule as the Matroska side: nothing is extracted with ffmpeg and
+ * nothing is fetched for its own sake. Here it is cheaper still. Matroska hides
+ * its subtitle blocks inside clusters shared with the picture, so a cue costs
+ * whatever cluster holds it; an MP4 states every sample's offset and length in
+ * the sample table, so a cue costs its own bytes and nothing more — usually a
+ * few dozen of them.
+ *
+ * The tables, from ISO/IEC 14496-12:
+ *
+ *   stsd — what the samples are (`tx3g` timed text, `wvtt` WebVTT, `stpp` TTML)
+ *   stts — how long each sample lasts, run-length encoded (§8.6.1.2)
+ *   stsz — how long each sample is, in bytes (§8.7.3)
+ *   stsc — how samples are grouped into chunks (§8.7.4)
+ *   stco / co64 — where each chunk begins in the file (§8.7.5)
+ *
+ * Together they give, for sample N: when it starts, how long it stays, and the
+ * exact byte range holding it. That is everything needed to show a cue without
+ * reading anything else.
+ */
+
+const HEADER_BYTES = 8;
+const LARGE_SIZE_MARKER = 1;
+const LARGE_HEADER_BYTES = 16;
+const PROBE_BYTES = 64;
+const MAX_MOOV_BYTES = 32 * 1024 * 1024;
+
+/** Handlers that mean "this track is text on screen". */
+const TEXT_HANDLERS = new Set(["text", "sbtl", "subt"]);
+/** Sample formats this can turn into cues. `stpp` (TTML) is XML and is not one. */
+const TEXT_FORMATS = new Set(["tx3g", "text", "wvtt"]);
+
+/**
+ * One box header at `offset`, or null when the bytes do not hold one.
+ *
+ * @param {Buffer} buffer
+ * @param {number} offset
+ * @returns {{ type: string, size: number, dataOffset: number, end: number } | null}
+ */
+function readBox(buffer, offset) {
+  if (offset + HEADER_BYTES > buffer.length) {
+    return null;
+  }
+  let size = buffer.readUInt32BE(offset);
+  const type = buffer.toString("latin1", offset + 4, offset + 8);
+  let headerBytes = HEADER_BYTES;
+  if (size === LARGE_SIZE_MARKER) {
+    if (offset + LARGE_HEADER_BYTES > buffer.length) {
+      return null;
+    }
+    size = Number(buffer.readBigUInt64BE(offset + 8));
+    headerBytes = LARGE_HEADER_BYTES;
+  }
+  if (size < headerBytes) {
+    return null;
+  }
+  return { type, size, dataOffset: offset + headerBytes, end: offset + size };
+}
+
+/**
+ * Every direct child of a range with the given type.
+ *
+ * @param {Buffer} buffer
+ * @param {number} start
+ * @param {number} end
+ * @param {string} type
+ * @returns {{ type: string, size: number, dataOffset: number, end: number }[]}
+ */
+function childrenOf(buffer, start, end, type) {
+  const found = [];
+  let at = start;
+  while (at < end) {
+    const box = readBox(buffer, at);
+    if (!box) {
+      break;
+    }
+    if (box.type === type) {
+      found.push(box);
+    }
+    at = box.end;
+  }
+  return found;
+}
+
+/**
+ * The first child of a range with the given type, or null.
+ *
+ * @param {Buffer} buffer
+ * @param {number} start
+ * @param {number} end
+ * @param {string} type
+ * @returns {{ type: string, size: number, dataOffset: number, end: number } | null}
+ */
+function childOf(buffer, start, end, type) {
+  return childrenOf(buffer, start, end, type)[0] ?? null;
+}
+
+/**
+ * Walk the top level of the file to find `moov`, reading only box headers.
+ *
+ * @param {(start: number, end: number) => Promise<Buffer | null>} readRange
+ * @param {number} fileSize
+ * @returns {Promise<{ offset: number, size: number } | null>}
+ */
+async function findMoov(readRange, fileSize) {
+  let at = 0;
+  while (at < fileSize) {
+    const probe = await readRange(at, Math.min(fileSize - 1, at + PROBE_BYTES - 1));
+    if (!probe || probe.length < HEADER_BYTES) {
+      return null;
+    }
+    const box = readBox(probe, 0);
+    if (!box) {
+      return null;
+    }
+    if (box.type === "moov") {
+      return { offset: at, size: box.size };
+    }
+    at += box.size;
+  }
+  return null;
+}
+
+/**
+ * Sample durations, expanded from the run-length table.
+ *
+ * @param {Buffer} moov
+ * @param {{ dataOffset: number, end: number }} stts
+ * @param {number} total - How many samples the size table declares.
+ * @returns {number[]} Ticks each sample lasts.
+ */
+function sampleDurations(moov, stts, total) {
+  const durations = new Array(total).fill(0);
+  const entries = moov.readUInt32BE(stts.dataOffset + 4);
+  let at = stts.dataOffset + 8;
+  let sample = 0;
+  for (let entry = 0; entry < entries && at + 8 <= stts.end && sample < total; entry += 1, at += 8) {
+    const count = moov.readUInt32BE(at);
+    const delta = moov.readUInt32BE(at + 4);
+    for (let index = 0; index < count && sample < total; index += 1, sample += 1) {
+      durations[sample] = delta;
+    }
+  }
+  return durations;
+}
+
+/**
+ * Sample sizes, whether the table states one for all or one for each.
+ *
+ * @param {Buffer} moov
+ * @param {{ dataOffset: number, end: number }} stsz
+ * @returns {number[]}
+ */
+function sampleSizes(moov, stsz) {
+  const uniform = moov.readUInt32BE(stsz.dataOffset + 4);
+  const count = moov.readUInt32BE(stsz.dataOffset + 8);
+  if (uniform > 0) {
+    return new Array(count).fill(uniform);
+  }
+  const sizes = new Array(count).fill(0);
+  let at = stsz.dataOffset + 12;
+  for (let index = 0; index < count && at + 4 <= stsz.end; index += 1, at += 4) {
+    sizes[index] = moov.readUInt32BE(at);
+  }
+  return sizes;
+}
+
+/**
+ * Where every sample of a track begins in the file.
+ *
+ * The sample-to-chunk table says how many samples each run of chunks holds, and
+ * the chunk-offset table says where each chunk starts; a sample's own offset is
+ * its chunk's start plus the sizes of the samples before it in that chunk.
+ *
+ * @param {Buffer} moov
+ * @param {{ dataOffset: number, end: number }} stsc
+ * @param {number[]} chunkOffsets
+ * @param {number[]} sizes
+ * @returns {number[]}
+ */
+function sampleOffsets(moov, stsc, chunkOffsets, sizes) {
+  const offsets = new Array(sizes.length).fill(0);
+  const entries = moov.readUInt32BE(stsc.dataOffset + 4);
+  /** @type {{ firstChunk: number, perChunk: number }[]} */
+  const runs = [];
+  let at = stsc.dataOffset + 8;
+  for (let entry = 0; entry < entries && at + 12 <= stsc.end; entry += 1, at += 12) {
+    runs.push({ firstChunk: moov.readUInt32BE(at), perChunk: moov.readUInt32BE(at + 4) });
+  }
+  let sample = 0;
+  for (let run = 0; run < runs.length && sample < sizes.length; run += 1) {
+    const from = runs[run].firstChunk;
+    const to = run + 1 < runs.length ? runs[run + 1].firstChunk - 1 : chunkOffsets.length;
+    for (let chunk = from; chunk <= to && sample < sizes.length; chunk += 1) {
+      let inChunk = chunkOffsets[chunk - 1];
+      if (inChunk === undefined) {
+        break;
+      }
+      for (let index = 0; index < runs[run].perChunk && sample < sizes.length; index += 1, sample += 1) {
+        offsets[sample] = inChunk;
+        inChunk += sizes[sample];
+      }
+    }
+  }
+  return offsets;
+}
+
+/**
+ * @typedef {object} Mp4SubtitleSample
+ * @property {number} startSeconds
+ * @property {number} endSeconds
+ * @property {number} offset - Where the sample's bytes are in the file.
+ * @property {number} size
+ */
+
+/**
+ * @typedef {object} Mp4SubtitleTrack
+ * @property {number} trackId
+ * @property {string} format - `tx3g`, `text` or `wvtt`.
+ * @property {string} language - Three letters, as the file declares them.
+ * @property {Mp4SubtitleSample[]} samples - In time order.
+ */
+
+/**
+ * The text subtitle tracks of an MP4, with every cue's time and byte range.
+ *
+ * @param {(start: number, end: number) => Promise<Buffer | null>} readRange
+ * @param {number} fileSize
+ * @returns {Promise<{ tracks: Mp4SubtitleTrack[] } | null>}
+ */
+export async function readMp4SubtitlePlan(readRange, fileSize) {
+  const found = await findMoov(readRange, fileSize);
+  if (!found || found.size > MAX_MOOV_BYTES) {
+    return null;
+  }
+  const moov = await readRange(found.offset, Math.min(fileSize - 1, found.offset + found.size - 1));
+  if (!moov || moov.length < HEADER_BYTES) {
+    return null;
+  }
+  const moovBox = readBox(moov, 0);
+  if (!moovBox) {
+    return null;
+  }
+
+  /** @type {Mp4SubtitleTrack[]} */
+  const tracks = [];
+  for (const trak of childrenOf(moov, moovBox.dataOffset, moov.length, "trak")) {
+    const mdia = childOf(moov, trak.dataOffset, trak.end, "mdia");
+    if (!mdia) {
+      continue;
+    }
+    const hdlr = childOf(moov, mdia.dataOffset, mdia.end, "hdlr");
+    const handler = hdlr ? moov.toString("latin1", hdlr.dataOffset + 8, hdlr.dataOffset + 12) : "";
+    if (!TEXT_HANDLERS.has(handler)) {
+      continue;
+    }
+    const mdhd = childOf(moov, mdia.dataOffset, mdia.end, "mdhd");
+    if (!mdhd) {
+      continue;
+    }
+    const version = moov[mdhd.dataOffset];
+    const timescale = moov.readUInt32BE(version === 1 ? mdhd.dataOffset + 20 : mdhd.dataOffset + 12);
+    if (!timescale) {
+      continue;
+    }
+    // The language is five bits per letter, offset from 0x60, packed into two
+    // bytes after the times (ISO/IEC 14496-12 §8.4.2.3).
+    const languageAt = version === 1 ? mdhd.dataOffset + 32 : mdhd.dataOffset + 20;
+    let language = "";
+    if (languageAt + 2 <= mdhd.end) {
+      const packed = moov.readUInt16BE(languageAt);
+      language = [10, 5, 0]
+        .map((shift) => String.fromCharCode(((packed >> shift) & 0x1f) + 0x60))
+        .join("")
+        .replace(/[^a-z]/g, "");
+    }
+
+    const tkhd = childOf(moov, trak.dataOffset, trak.end, "tkhd");
+    const trackId = tkhd
+      ? moov.readUInt32BE(moov[tkhd.dataOffset] === 1 ? tkhd.dataOffset + 20 : tkhd.dataOffset + 12)
+      : tracks.length + 1;
+
+    const minf = childOf(moov, mdia.dataOffset, mdia.end, "minf");
+    const stbl = minf && childOf(moov, minf.dataOffset, minf.end, "stbl");
+    if (!stbl) {
+      continue;
+    }
+    const stsd = childOf(moov, stbl.dataOffset, stbl.end, "stsd");
+    const first = stsd && readBox(moov, stsd.dataOffset + 8);
+    const format = first ? first.type : "";
+    if (!TEXT_FORMATS.has(format)) {
+      continue;
+    }
+    const stts = childOf(moov, stbl.dataOffset, stbl.end, "stts");
+    const stsz = childOf(moov, stbl.dataOffset, stbl.end, "stsz");
+    const stsc = childOf(moov, stbl.dataOffset, stbl.end, "stsc");
+    const stco = childOf(moov, stbl.dataOffset, stbl.end, "stco");
+    const co64 = childOf(moov, stbl.dataOffset, stbl.end, "co64");
+    if (!stts || !stsz || !stsc || (!stco && !co64)) {
+      continue;
+    }
+
+    const sizes = sampleSizes(moov, stsz);
+    const durations = sampleDurations(moov, stts, sizes.length);
+    const chunkOffsets = [];
+    if (stco) {
+      const count = moov.readUInt32BE(stco.dataOffset + 4);
+      let at = stco.dataOffset + 8;
+      for (let index = 0; index < count && at + 4 <= stco.end; index += 1, at += 4) {
+        chunkOffsets.push(moov.readUInt32BE(at));
+      }
+    } else {
+      const count = moov.readUInt32BE(co64.dataOffset + 4);
+      let at = co64.dataOffset + 8;
+      for (let index = 0; index < count && at + 8 <= co64.end; index += 1, at += 8) {
+        chunkOffsets.push(Number(moov.readBigUInt64BE(at)));
+      }
+    }
+    const offsets = sampleOffsets(moov, stsc, chunkOffsets, sizes);
+
+    /** @type {Mp4SubtitleSample[]} */
+    const samples = [];
+    let ticks = 0;
+    for (let index = 0; index < sizes.length; index += 1) {
+      const start = ticks / timescale;
+      ticks += durations[index];
+      // An empty sample is a gap between cues, which the format uses to say
+      // "nothing on screen"; it is not a cue and would show as a blank line.
+      if (sizes[index] > 2) {
+        samples.push({
+          startSeconds: start,
+          endSeconds: ticks / timescale,
+          offset: offsets[index],
+          size: sizes[index]
+        });
+      }
+    }
+    tracks.push({ trackId, format, language, samples });
+  }
+  return { tracks };
+}
+
+/**
+ * The text of one sample.
+ *
+ * `tx3g` is a two-byte length followed by UTF-8; anything after that is styling
+ * boxes, which this deliberately drops. `wvtt` is a sequence of boxes, and the
+ * text lives in the `payl` inside a `vttc`.
+ *
+ * @param {Buffer} bytes
+ * @param {string} format
+ * @returns {string}
+ */
+export function decodeSubtitleSample(bytes, format) {
+  if (format === "wvtt") {
+    let at = 0;
+    const parts = [];
+    while (at + HEADER_BYTES <= bytes.length) {
+      const box = readBox(bytes, at);
+      if (!box) {
+        break;
+      }
+      if (box.type === "vttc") {
+        const payl = childOf(bytes, box.dataOffset, Math.min(bytes.length, box.end), "payl");
+        if (payl) {
+          parts.push(bytes.toString("utf8", payl.dataOffset, Math.min(bytes.length, payl.end)));
+        }
+      }
+      at = box.end;
+    }
+    return parts.join("\n").trim();
+  }
+  if (bytes.length < 2) {
+    return "";
+  }
+  const length = bytes.readUInt16BE(0);
+  return bytes.toString("utf8", 2, Math.min(bytes.length, 2 + length)).trim();
+}

package/services/torrent-worker/subtitle-cues.js

@@ -18,6 +18,7 @@
  */
 
 import { readSubtitlePlan, harvestCluster } from "../container-index/matroska-subtitles.js";
+import { decodeSubtitleSample, readMp4SubtitlePlan } from "../container-index/mp4-subtitles.js";
 import { iterateElements } from "../container-index/ebml-reader.js";
 import { logger } from "../../utils/logger.js";
 
@@ -105,15 +106,42 @@ async function planFor(torrent, fileIndex, key) {
     return state.plan;
   }
   const file = torrent?.files?.[fileIndex];
-  if (!file || !/\.mkv$/i.test(String(file.name))) {
-    // Only Matroska is read this way. An MP4's text track is cheaper still —
-    // its sample table gives exact byte offsets — and is not written yet.
-    state.plan = { tracks: [], secondsPerTick: 0.001, segmentDataOffset: 0 };
+  const empty = { tracks: [], secondsPerTick: 0.001, segmentDataOffset: 0 };
+  if (!file) {
+    state.plan = empty;
     return state.plan;
   }
   const readRange = async (start, end) => readHeld(file, start, Math.min(end, file.length - 1));
+  const name = String(file.name);
+  if (/\.mp4$/i.test(name) || /\.m4v$/i.test(name)) {
+    // An MP4 states every sample's byte range in its own table, so a cue costs
+    // its own few dozen bytes rather than the cluster around it. The samples
+    // are carried as `clusterPositions` of one byte range each, so the harvest
+    // treats both containers the same way.
+    const mp4 = await readMp4SubtitlePlan(readRange, file.length);
+    state.plan = mp4
+      ? {
+        ...empty,
+        tracks: mp4.tracks.map((track, order) => ({
+          trackNumber: track.trackId,
+          codecId: track.format,
+          language: track.language,
+          name: "",
+          isDefault: order === 0,
+          codecPrivate: "",
+          clusterPositions: [],
+          samples: track.samples
+        }))
+      }
+      : empty;
+    return state.plan;
+  }
+  if (!/\.mkv$/i.test(name) && !/\.webm$/i.test(name)) {
+    state.plan = empty;
+    return state.plan;
+  }
   const plan = await readSubtitlePlan(readRange, file.length);
-  state.plan = plan ?? { tracks: [], secondsPerTick: 0.001, segmentDataOffset: 0 };
+  state.plan = plan ?? empty;
   if (state.plan.tracks.length > 0) {
     logger.info(
       `subtitles: "${String(file.name).slice(0, 40)}" has ${state.plan.tracks.length} text track(s) — ` +
@@ -155,6 +183,36 @@ export async function cuesHeldFor(torrent, fileIndex, sourceKey, trackNumber) {
     state.cues.set(trackNumber, cues);
   }
 
+  if (Array.isArray(track.samples)) {
+    // An MP4: every cue's bytes are stated, so only those bytes are read, and
+    // only where they are already downloaded.
+    for (const sample of track.samples) {
+      if (harvested.has(sample.offset)) {
+        continue;
+      }
+      const last = Math.min(file.length - 1, sample.offset + sample.size - 1);
+      if (!rangeIsHeld(torrent, file, sample.offset, last)) {
+        continue;
+      }
+      const bytes = await readHeld(file, sample.offset, last);
+      if (!bytes) {
+        continue;
+      }
+      harvested.add(sample.offset);
+      const text = decodeSubtitleSample(bytes, track.codecId);
+      if (text) {
+        cues.push({ startSeconds: sample.startSeconds, endSeconds: sample.endSeconds, text });
+      }
+    }
+    cues.sort((left, right) => left.startSeconds - right.startSeconds);
+    return {
+      cues,
+      coveredClusters: harvested.size,
+      indexedClusters: track.samples.length,
+      track
+    };
+  }
+
   for (const position of track.clusterPositions) {
     if (harvested.has(position)) {
       continue;

package/test/mp4-subtitles.test.js

@@ -0,0 +1,127 @@
+/**
+ * @file Reading an MP4's text subtitle track out of its sample table.
+ *
+ * The file is built here, so every answer is known in advance: two cues at
+ * stated times, in stated places, with an empty sample between them — the way
+ * the format says "nothing on screen just now".
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { decodeSubtitleSample, readMp4SubtitlePlan } from "../services/container-index/mp4-subtitles.js";
+
+function box(type, payload) {
+  const header = Buffer.alloc(8);
+  header.writeUInt32BE(payload.length + 8, 0);
+  header.write(type, 4, "latin1");
+  return Buffer.concat([header, payload]);
+}
+
+function fullBox(type, payload) {
+  return box(type, Buffer.concat([Buffer.from([0, 0, 0, 0]), payload]));
+}
+
+function u32(...values) {
+  const buffer = Buffer.alloc(values.length * 4);
+  values.forEach((value, index) => buffer.writeUInt32BE(value, index * 4));
+  return buffer;
+}
+
+/** A `tx3g` sample: a two-byte length, then the text. */
+function textSample(text) {
+  const bytes = Buffer.from(text, "utf8");
+  const length = Buffer.alloc(2);
+  length.writeUInt16BE(bytes.length, 0);
+  return Buffer.concat([length, bytes]);
+}
+
+/**
+ * A file with one text track: three samples, the middle one empty.
+ *
+ * @returns {{ file: Buffer, samples: Buffer[] }}
+ */
+function buildFile() {
+  const samples = [textSample("First line"), Buffer.alloc(2), textSample("Second line")];
+  const timescale = 1000;
+
+  const mdhd = fullBox("mdhd", Buffer.concat([
+    u32(0, 0, timescale, 60_000),
+    // Language "eng", five bits a letter offset from 0x60, then a spare word.
+    Buffer.from([0x15, 0xc7, 0, 0])
+  ]));
+  const hdlr = fullBox("hdlr", Buffer.concat([u32(0), Buffer.from("sbtl", "latin1"), u32(0, 0, 0)]));
+  const tkhd = fullBox("tkhd", u32(0, 0, 7, 0, 60_000));
+
+  const stsd = fullBox("stsd", Buffer.concat([u32(1), box("tx3g", Buffer.alloc(24))]));
+  // Two seconds a sample, so the cues sit at 0-2, 2-4 and 4-6 seconds.
+  const stts = fullBox("stts", Buffer.concat([u32(1), u32(3, 2000)]));
+  const stsz = fullBox("stsz", Buffer.concat([u32(0, 3), u32(...samples.map((s) => s.length))]));
+  const stsc = fullBox("stsc", Buffer.concat([u32(1), u32(1, 3, 1)]));
+
+  const stbl = box("stbl", Buffer.concat([stsd, stts, stsz, stsc, fullBox("stco", Buffer.concat([u32(1), u32(0)]))]));
+  const minf = box("minf", stbl);
+  const mdia = box("mdia", Buffer.concat([mdhd, hdlr, minf]));
+  const trak = box("trak", Buffer.concat([tkhd, mdia]));
+  const moovDraft = box("moov", trak);
+
+  // The samples sit after moov, so the chunk offset is known only now. Its
+  // length does not change when the placeholder becomes the real value.
+  const mdatStart = moovDraft.length + 8;
+  const stcoReal = fullBox("stco", Buffer.concat([u32(1), u32(mdatStart)]));
+  const stblReal = box("stbl", Buffer.concat([stsd, stts, stsz, stsc, stcoReal]));
+  const moov = box("moov", box("trak", Buffer.concat([
+    tkhd,
+    box("mdia", Buffer.concat([mdhd, hdlr, box("minf", stblReal)]))
+  ])));
+  const mdat = box("mdat", Buffer.concat(samples));
+  return { file: Buffer.concat([moov, mdat]), samples };
+}
+
+function readerOver(file) {
+  return async (start, end) => {
+    const last = Math.min(end, file.length - 1);
+    return start > last ? null : file.subarray(start, last + 1);
+  };
+}
+
+test("a text track's cues are found with their times and their byte ranges", async () => {
+  const { file, samples } = buildFile();
+
+  const plan = await readMp4SubtitlePlan(readerOver(file), file.length);
+
+  assert.equal(plan.tracks.length, 1);
+  const track = plan.tracks[0];
+  assert.equal(track.format, "tx3g");
+  assert.equal(track.language, "eng");
+  assert.equal(track.samples.length, 2, "the empty sample is a gap, not a cue");
+  assert.deepEqual(
+    track.samples.map((sample) => [sample.startSeconds, sample.endSeconds]),
+    [[0, 2], [4, 6]],
+    "times come from the duration table, and the gap keeps its place in it"
+  );
+  // The bytes the plan points at are the ones that hold the text.
+  const first = file.subarray(track.samples[0].offset, track.samples[0].offset + track.samples[0].size);
+  assert.equal(decodeSubtitleSample(first, "tx3g"), "First line");
+  const second = file.subarray(track.samples[1].offset, track.samples[1].offset + track.samples[1].size);
+  assert.equal(decodeSubtitleSample(second, "tx3g"), "Second line");
+  assert.equal(second.length, samples[2].length);
+});
+
+test("a file with no text track offers nothing", async () => {
+  const moov = box("moov", box("trak", box("mdia", Buffer.concat([
+    fullBox("mdhd", Buffer.concat([u32(0, 0, 1000, 100), Buffer.from([0, 0, 0, 0])])),
+    fullBox("hdlr", Buffer.concat([u32(0), Buffer.from("vide", "latin1"), u32(0, 0, 0)]))
+  ]))));
+  const file = Buffer.concat([moov, box("mdat", Buffer.alloc(4))]);
+
+  const plan = await readMp4SubtitlePlan(readerOver(file), file.length);
+
+  assert.deepEqual(plan.tracks, []);
+});
+
+test("a WebVTT sample gives up the text inside its payload box", () => {
+  const payl = box("payl", Buffer.from("Hello there", "utf8"));
+  const sample = box("vttc", payl);
+
+  assert.equal(decodeSubtitleSample(sample, "wvtt"), "Hello there");
+});