@torrent-tv/proxy 2.35.0 → 2.36.1

package/services/hwaccel.js

@@ -157,21 +157,18 @@ const ENCODE_BENCHMARK_MAX_PLAUSIBLE_SPEED = 1000;
 const ENCODE_BENCHMARK_TIMEOUT_MS = 10_000;
 /** Progress reports arrive line by line. */
 const NEWLINE = String.fromCharCode(10);
-// Require the predicted speed to clear realtime by this much. The benchmarks
-// run at startup with an idle CPU; during playback ffmpeg competes with
-// in-process WebTorrent (download + hashing) and delivery, so real throughput
-// is lower, and the margin covers that plus complex scenes.
-//
-// It was 1.8 while the prediction counted ENCODING only and was therefore
-// several times too optimistic on a re-encode; with the decode term the
-// prediction is within ~13 % of measured, so the margin no longer has to stand
-// in for a missing term as well as for load.
-const PRESET_SPEED_MARGIN = 1.5;
-// The bar for a prediction that has NO decode term — a host whose calibration
-// clips are missing, or whose fit was rejected. That figure is the one the
-// margin was 1.8 for, and lowering it there would make an uncalibrated host
-// more permissive than it was before any of this existed.
-const ENCODE_ONLY_SPEED_MARGIN = 1.8;
+// Producing one second of video per second of clock. Not a margin and not a
+// choice — the definition of keeping up, and the bar when nothing better is
+// known about the supply this step will meet.
+const REALTIME = 1;
+// The bar where decoding CANNOT be priced — no calibration fit, or a source the
+// probe said too little about. This one is not measured and cannot be: the
+// prediction it guards counts encoding only, which on the field host was
+// several times optimistic, and there is no reading on such a host to correct
+// it with. It is left at the figure it has had since before decoding was
+// priced, because lowering it to realtime would make the least-measured hosts
+// the most permissive. Where decoding IS priced, nothing chosen remains.
+const UNPRICED_DECODE_BAR = 1.8;
 
 /**
  * @param {number} targetWidth
@@ -1064,7 +1061,7 @@ export function predictedRealtimeSpeed({
  * The encoder figure is the FASTEST benchmarked preset: it is the best this
  * host can do, so a rung it cannot hold cannot be held at any quality setting.
  *
- * @param {{ benchmark: Array<{ preset: string, pixelsPerSec: number }>, decodeModel?: object | null, source?: { megapixelsPerSecond: number, megabitsPerSecond: number } | null, outputPixelsPerSec: number }} params
+ * @param {{ benchmark: Array<{ preset: string, pixelsPerSec: number }>, decodeModel?: object | null, source?: { megapixelsPerSecond: number, megabitsPerSecond: number } | null, outputPixelsPerSec: number, requiredSpeed?: number | null }} params
  * @returns {{ speed: number | null, sustainable: boolean }}
  */
 export function canSustainOutput({
@@ -1073,7 +1070,8 @@ export function canSustainOutput({
   source = null,
   outputPixelsPerSec,
   observedDecodeCostSec = null,
-  concurrentCostSec = 0
+  concurrentCostSec = 0,
+  requiredSpeed = null
 }) {
   if (!Array.isArray(benchmark) || benchmark.length === 0) {
     // Nothing measured on this host: the budget cannot refuse what it cannot
@@ -1114,11 +1112,45 @@ export function canSustainOutput({
   if (speed === null) {
     return { speed: null, sustainable: true };
   }
-  return { speed, sustainable: speed >= PRESET_SPEED_MARGIN };
+  return { speed, sustainable: speed >= speedBar(requiredSpeed) };
+}
+
+/**
+ * The speed a step has to reach to be worth offering.
+ *
+ * Realtime is not enough on its own: a step that produces exactly one second
+ * per second never recovers the seconds lost while its reader waits for the
+ * swarm, so it survives its own supply only if what it gains between
+ * interruptions covers what one interruption costs. That is measured per file
+ * and per swarm by the reader — `1 + worst wait / median interval`, in
+ * `supply-margin.js` — and on the field torrent of 2026-08-17 it came to 1.67
+ * against the 1.5 that used to stand here, and to 4.04-8.14 on a torrent whose
+ * swarm no encoder could have kept up with.
+ *
+ * Where that figure does not exist yet — fewer than two interruptions measured
+ * — the bar is realtime. It is the one thing that can be said without
+ * measuring the swarm, and the offer is restated as soon as the reader has
+ * something to say.
+ *
+ * @param {number | null | undefined} requiredSpeed - What this file's own
+ *   interruptions demand, when they have been measured.
+ * @returns {number}
+ */
+export function speedBar(requiredSpeed) {
+  return Number.isFinite(requiredSpeed) && requiredSpeed > REALTIME ? requiredSpeed : REALTIME;
 }
 
-/** The margin a predicted speed must clear to be offered. */
-export const REALTIME_SPEED_MARGIN = PRESET_SPEED_MARGIN;
+/**
+ * The bar for a cost description — the supply's demand where decoding is
+ * priced, and never below the unpriced-decode bar where it is not.
+ *
+ * @param {{ decodeModel?: object | null, source?: object | null, observedDecodeCostSec?: number | null, requiredSpeed?: number | null }} cost
+ * @returns {number}
+ */
+function barFor(cost) {
+  const measured = speedBar(cost?.requiredSpeed);
+  return isDecodePriced(cost) ? measured : Math.max(UNPRICED_DECODE_BAR, measured);
+}
 
 /**
  * Benchmark software libx264 presets on this host. Encodes a short synthetic
@@ -1377,7 +1409,7 @@ async function decodeToRawFrames(ffmpegBin, log) {
  *
  * @param {Array<{ preset: string, pixelsPerSec: number }>} benchmark - slowest→fastest
  * @param {number} pixelsPerSecNeeded
- * @param {{ decodeModel?: object | null, source?: { megapixelsPerSecond: number, megabitsPerSecond: number } | null }} [cost]
+ * @param {{ decodeModel?: object | null, source?: { megapixelsPerSecond: number, megabitsPerSecond: number } | null, requiredSpeed?: number | null }} [cost]
  * @returns {string}
  */
 /**
@@ -1405,8 +1437,7 @@ export function pickSoftwarePreset(benchmark, pixelsPerSecNeeded, cost = {}) {
   const observed = Number.isFinite(cost?.observedDecodeCostSec) && cost.observedDecodeCostSec > 0
     ? cost.observedDecodeCostSec
     : null;
-  const priced = isDecodePriced(cost);
-  const bar = priced ? PRESET_SPEED_MARGIN : ENCODE_ONLY_SPEED_MARGIN;
+  const bar = barFor(cost);
   // The FIRST entry that clears the bar wins — the list is in quality order, so
   // that is the best picture this host can hold. Every entry is examined rather
   // than the walk stopping at the first miss, because the measurements do not
@@ -1493,9 +1524,9 @@ export function buildResolutionLadder(ceilingWidth, ceilingHeight) {
  * Choose the software encode settings (resolution + preset) that fit the
  * realtime budget on this host. From the resolution ladder (ceiling downward),
  * pick the HIGHEST rung whose encode throughput — predicted from the startup
- * benchmark's fastest preset — clears realtime × PRESET_SPEED_MARGIN. Then, at
- * that resolution, pick the highest-quality preset that still clears the
- * margin. When even the lowest rung cannot clear it, use the lowest rung with
+ * benchmark's fastest preset — clears the speed this file's own supply
+ * demands (`speedBar`). Then, at that resolution, pick the highest-quality
+ * preset that still clears it. When even the lowest rung cannot clear it, use the lowest rung with
  * the fastest preset (best effort — a smaller picture beats sub-realtime
  * playback at full size). Returns null when no benchmark or ceiling is
  * available (the caller keeps the ceiling resolution and the default preset).
@@ -1503,7 +1534,7 @@ export function buildResolutionLadder(ceilingWidth, ceilingHeight) {
  * @param {Array<{ preset: string, pixelsPerSec: number }>} benchmark - slowest→fastest
  * @param {{ width: number, height: number }} ceiling
  * @param {number} outputFps
- * @param {{ decodeModel?: object | null, source?: { megapixelsPerSecond: number, megabitsPerSecond: number } | null }} [cost]
+ * @param {{ decodeModel?: object | null, source?: { megapixelsPerSecond: number, megabitsPerSecond: number } | null, requiredSpeed?: number | null }} [cost]
  * @returns {{ width: number, height: number, preset: string, ladder: Array<{ width: number, height: number }>, rungIndex: number } | null}
  */
 export function chooseSoftwareEncodeSettings(benchmark, ceiling, outputFps, cost = {}) {
@@ -1516,7 +1547,7 @@ export function chooseSoftwareEncodeSettings(benchmark, ceiling, outputFps, cost
     return null;
   }
   const fastest = cheapestPresetPixelsPerSec(benchmark); // the cheapest preset's throughput
-  const bar = isDecodePriced(cost) ? PRESET_SPEED_MARGIN : ENCODE_ONLY_SPEED_MARGIN;
+  const bar = barFor(cost);
   let chosenIndex = ladder.length - 1; // default: lowest rung (best effort)
   for (let i = 0; i < ladder.length; i += 1) {
     const speed = predictedRealtimeSpeed({

package/services/learned-median.js

@@ -0,0 +1,79 @@
+/**
+ * @file Publishing a value that is learned from repeated readings.
+ *
+ * Four costs are learned this way — what a file costs to decode, what copying
+ * it costs, what a soundtrack costs, what the torrent costs per megabyte — and
+ * each has the same two decisions to make: which figure the readings amount to,
+ * and when a new figure replaces the published one.
+ *
+ * The first is the median, because one starved moment must not drag the answer.
+ *
+ * The second used to be "more than five per cent", a figure nobody measured.
+ * It is now the scatter of the readings themselves: a median that has moved
+ * further than its own readings disagree with each other has moved for a
+ * reason, and one that has not is the same answer read again. Republishing
+ * costs something real — every session recomputes its offer, on the path that
+ * serves every playlist, init and segment — so the question is worth asking,
+ * but it is answered from the measurements rather than from a constant.
+ */
+
+/**
+ * The middle of a set of readings, or null when there are none.
+ *
+ * @param {number[]} values
+ * @returns {number | null}
+ */
+export function medianOf(values) {
+  const usable = (Array.isArray(values) ? values : []).filter((value) => Number.isFinite(value));
+  if (usable.length === 0) {
+    return null;
+  }
+  const sorted = [...usable].sort((left, right) => left - right);
+  const middle = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0 ? (sorted[middle - 1] + sorted[middle]) / 2 : sorted[middle];
+}
+
+/**
+ * How far the readings sit from their own middle — the median of their
+ * distances to it.
+ *
+ * The median distance rather than the mean one, for the same reason the value
+ * itself is a median: a single disturbed reading describes the disturbance, not
+ * the host.
+ *
+ * @param {number[]} values
+ * @returns {number | null} Null when there is nothing to measure. Zero is a
+ *   real answer: readings that all agree disagree by nothing.
+ */
+export function scatterOf(values) {
+  const middle = medianOf(values);
+  if (middle === null) {
+    return null;
+  }
+  const distances = (Array.isArray(values) ? values : [])
+    .filter((value) => Number.isFinite(value))
+    .map((value) => Math.abs(value - middle));
+  return medianOf(distances);
+}
+
+/**
+ * Whether a newly computed median should replace the published one.
+ *
+ * @param {number | null} published - What every session is answering with now.
+ * @param {number} median - What the readings say today.
+ * @param {number[]} readings - The readings that median came from.
+ * @returns {boolean}
+ */
+export function movedBeyondScatter(published, median, readings) {
+  if (!Number.isFinite(median)) {
+    return false;
+  }
+  if (!Number.isFinite(published)) {
+    return true; // nothing published yet; the first answer is always news
+  }
+  const scatter = scatterOf(readings);
+  if (scatter === null) {
+    return true;
+  }
+  return Math.abs(median - published) > scatter;
+}

package/services/torrent-cost.js

@@ -0,0 +1,88 @@
+/**
+ * @file What the torrent itself costs this machine, per megabyte it moves.
+ *
+ * Downloading, verifying every piece and pushing segments down a data channel
+ * are work on the same box as the encoder, and they scale with what is moved.
+ * The reading is taken only while nothing is encoding, because that is the one
+ * moment the spending needs no arithmetic to attribute: what the process uses
+ * then is the torrent's.
+ *
+ * Except that it is not all the torrent's, and that is what this file exists
+ * for. Measured on the addon host 2026-08-18, one session reported **145.4 ms
+ * per megabyte over 8.7 MB** and **23.1 ms per megabyte over 54 MB** — the same
+ * host, the same minute, a sixfold disagreement that follows the size of the
+ * interval rather than anything about the torrent. A process with nothing to do
+ * still runs its timers, its tunnel and its session sweeps, and that draw does
+ * not shrink when fewer megabytes move: divided by a small number it swamps the
+ * answer. A minimum-megabytes threshold stood against exactly this and did not
+ * hold, because a chosen number was standing in for a measured one.
+ *
+ * The draw is measurable. An interval in which nothing encodes and the torrents
+ * move no bytes at all costs whatever this process spends anyway; subtract that
+ * from an interval which did move bytes, and what remains is the torrent's.
+ */
+
+/**
+ * The share of one core this process draws while it has nothing to do.
+ *
+ * @param {{ cpuSeconds: number, elapsedSeconds: number }} interval - CPU seconds
+ *   already divided by the number of cores, so the figure is comparable with
+ *   the wall seconds every other cost in the budget is stated in.
+ * @returns {number | null} Null when the interval cannot be divided.
+ */
+export function baseDrawFrom({ cpuSeconds, elapsedSeconds }) {
+  if (!Number.isFinite(cpuSeconds) || !Number.isFinite(elapsedSeconds) || !(elapsedSeconds > 0)) {
+    return null;
+  }
+  if (!(cpuSeconds >= 0)) {
+    return null;
+  }
+  return cpuSeconds / elapsedSeconds;
+}
+
+/**
+ * What one megabyte cost, once the draw that would have been spent anyway is
+ * taken off.
+ *
+ * The draw is subtracted, so what is left is only as certain as the draw is.
+ * The draw's own readings disagree with each other by a measured amount, and
+ * over an interval that disagreement is worth `scatter × elapsed` seconds of
+ * CPU: a reading whose remainder is smaller than that measures the wobble in
+ * the subtraction rather than the torrent. This is what the removed
+ * minimum-megabytes threshold was reaching for, arrived at from the readings
+ * instead of from a chosen size — a small interval fails it because little was
+ * moved in it, and a large one passes on the same arithmetic.
+ *
+ * @param {{ cpuSeconds: number, elapsedSeconds: number, megabytes: number, baseDraw: number | null, drawScatter?: number | null }} interval
+ * @returns {number | null} Seconds of work per megabyte, or null when this
+ *   interval cannot say — no base draw measured yet, nothing moved, or the
+ *   interval spent no more than the draw and its own uncertainty account for.
+ */
+export function costPerMegabyteFrom({ cpuSeconds, elapsedSeconds, megabytes, baseDraw, drawScatter = null }) {
+  if (!Number.isFinite(cpuSeconds) || !Number.isFinite(elapsedSeconds) || !(elapsedSeconds > 0)) {
+    return null;
+  }
+  if (!Number.isFinite(megabytes) || !(megabytes > 0)) {
+    return null;
+  }
+  if (!Number.isFinite(baseDraw) || !(baseDraw >= 0)) {
+    // Nothing measured to subtract. Publishing the whole spending as the
+    // torrent's is what produced the 145 ms/MB reading, so this interval says
+    // nothing instead.
+    return null;
+  }
+  const attributable = cpuSeconds - baseDraw * elapsedSeconds;
+  if (!(attributable > 0)) {
+    // The draw accounts for everything this interval spent. Not a discovery
+    // that the torrent is free — a reading with nothing left in it.
+    return null;
+  }
+  const uncertainty = Number.isFinite(drawScatter) && drawScatter > 0 ? drawScatter * elapsedSeconds : 0;
+  if (!(attributable > uncertainty)) {
+    // What is left is inside the disagreement between the draw's own readings.
+    // Dividing it by a small number of megabytes is how 145 ms/MB was reported
+    // on a host that costs 23.
+    return null;
+  }
+  return attributable / megabytes;
+}

package/test/decode-cost.test.js

@@ -24,7 +24,7 @@ import {
   canSustainOutput,
   decodeSpeedFor,
   predictedRealtimeSpeed,
-  REALTIME_SPEED_MARGIN
+  speedBar
 } from "../services/hwaccel.js";
 import { HlsSessionManager, sourceDecodeCharacteristics } from "../services/hls-session-manager.js";
 import { parseFfmpegBitrateKbps, parseFfmpegVideoDimensions, parseFfmpegVideoFps } from "../services/ffmpeg-banner.js";
@@ -111,7 +111,7 @@ test("with no decode fit the prediction is the encoder alone — what it was bef
   assert.equal(speed, 5.99, "the old figure, four times the truth on that rung");
 });
 
-test("a rung is refused when the combined speed is under the margin", () => {
+test("a rung is refused when the combined speed is under the bar", () => {
   // The addon host's fastest preset, read from its own log: 11.2 Mpx/s.
   const benchmark = [{ preset: "ultrafast", pixelsPerSec: 11.2e6 }];
   const source = MEASURED_FILM;
@@ -123,14 +123,10 @@ test("a rung is refused when the combined speed is under the margin", () => {
     outputPixelsPerSec: 1280 * 720 * 24
   });
   assert.equal(heavy.sustainable, false, "720p needs 22 Mpx/s from an 11.2 Mpx/s host");
-  assert.ok(heavy.speed < REALTIME_SPEED_MARGIN);
-
-  // And this is the gap the model does NOT close: the 240p rung predicts 1.58x
-  // and clears a margin of 1.5, while the field measured that same rung at
-  // 0.388-0.947x under real load — a host simultaneously copying 1080p,
-  // downloading the torrent and pushing segments. The prediction is honest for
-  // an idle machine; the margin is what has to carry the load, and 1.5 does not
-  // carry it. Pinned here so the arithmetic is not rediscovered from a log.
+  assert.ok(heavy.speed < 1, `predicted ${heavy.speed.toFixed(2)}x`);
+
+  // The 240p rung of that film predicts 1.58x on an idle machine, and with
+  // nothing known about the swarm the bar is realtime, so it is offered.
   const light = canSustainOutput({
     benchmark,
     decodeModel: ADDON_HOST_MODEL,
@@ -141,6 +137,26 @@ test("a rung is refused when the combined speed is under the margin", () => {
   assert.equal(light.sustainable, true);
 });
 
+test("the bar is what this file's own supply demands, when it has been measured", () => {
+  // The field torrent of 2026-08-17: waits of 1.49 s median arriving every
+  // 2.22 s demand 1.67x of any step that is to survive them. The same 240p rung
+  // predicted at 1.58x clears realtime and does not clear that.
+  const benchmark = [{ preset: "ultrafast", pixelsPerSec: 11.2e6 }];
+  const rung = {
+    benchmark,
+    decodeModel: ADDON_HOST_MODEL,
+    source: MEASURED_FILM,
+    outputPixelsPerSec: 426 * 240 * 24
+  };
+  assert.equal(canSustainOutput({ ...rung, requiredSpeed: 1.67 }).sustainable, false);
+  assert.equal(canSustainOutput({ ...rung, requiredSpeed: 1.2 }).sustainable, true);
+  // A swarm that has not been measured cannot raise the bar, and cannot lower
+  // it below realtime either.
+  assert.equal(speedBar(null), 1);
+  assert.equal(speedBar(0.4), 1);
+  assert.equal(speedBar(1.67), 1.67);
+});
+
 test("a reading from the running encoder outranks the model of the clips", () => {
   // The field case, 2026-08-14: the 240p rung of that film ran at 0.95x at its
   // best on a host whose fastest preset benchmarked at 11.2 Mpx/s. Subtracting
@@ -340,8 +356,24 @@ test("the master playlist drops the rungs the host cannot hold", async (t) => {
   const stronger = { ...session, id: "dddddddd-eeee-ffff-0000-111111111111", offeredHeightsCache: undefined };
   manager.sessionsById.set(stronger.id, stronger);
   const master = manager.buildMasterPlaylist(stronger.id);
-  assert.ok(master, "1080p copied plus the one rung this host can produce");
+  assert.ok(master, "1080p copied plus the rungs this host can produce");
   const heights = [...master.matchAll(/^v\/(\d+)\/index\.m3u8$/gm)].map((match) => Number(match[1]));
-  assert.deepEqual(heights, [1080, 240]);
+  assert.deepEqual(heights, [1080, 360, 240], "nothing is known about this swarm, so the bar is realtime");
   assert.deepEqual(manager.offeredHeights(stronger), heights);
+
+  // The same host, once the reader has measured what this file's supply
+  // demands: waits arriving as they did on the field torrent of 2026-08-17 ask
+  // 1.67x of any step, and the rungs that only just cleared realtime go.
+  const onAThinSwarm = {
+    ...stronger,
+    id: "eeeeeeee-ffff-0000-1111-222222222222",
+    offeredHeightsCache: undefined,
+    supplyFigures: { requiredSpeed: 1.67, worstWaitSec: 1.49, medianIntervalSec: 2.22, samples: 12 }
+  };
+  manager.sessionsById.set(onAThinSwarm.id, onAThinSwarm);
+  assert.deepEqual(
+    manager.offeredHeights(onAThinSwarm),
+    [1080],
+    "the copied height costs no encoder and stays; nothing re-encoded survives that supply"
+  );
 });

package/test/learned-median.test.js

@@ -0,0 +1,37 @@
+/**
+ * @file Adopting a new median only when it has moved further than the readings
+ * behind it disagree with each other.
+ */
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { medianOf, movedBeyondScatter, scatterOf } from "../services/learned-median.js";
+
+test("the median is the middle reading, and the mean of the two middle ones", () => {
+  assert.equal(medianOf([3, 1, 2]), 2);
+  assert.equal(medianOf([1, 2, 3, 4]), 2.5);
+  assert.equal(medianOf([]), null);
+  assert.equal(medianOf([Number.NaN]), null);
+});
+
+test("the scatter is the median distance from the middle", () => {
+  assert.equal(scatterOf([10, 10, 10]), 0);
+  assert.equal(scatterOf([8, 10, 12]), 2);
+  assert.equal(scatterOf([]), null);
+});
+
+test("the first answer is always adopted", () => {
+  assert.equal(movedBeyondScatter(null, 5, [5]), true);
+});
+
+test("a move smaller than the readings' own disagreement is the same answer", () => {
+  assert.equal(movedBeyondScatter(10, 11, [8, 10, 12]), false);
+});
+
+test("a move larger than that disagreement is adopted", () => {
+  assert.equal(movedBeyondScatter(10, 13, [8, 10, 12]), true);
+});
+
+test("readings that all agree let any change through", () => {
+  assert.equal(movedBeyondScatter(10, 10.4, [10, 10, 10]), true);
+  assert.equal(movedBeyondScatter(10, 10, [10, 10, 10]), false);
+});

package/test/matroska-cues-track.test.js

@@ -0,0 +1,192 @@
+/**
+ * @file The container's table names a track, and only the picture's entries are
+ * cut points.
+ *
+ * Measured 2026-08-18 on the two files the field sessions were recorded from:
+ * `Minions.and.Monsters.1080p.mkv` carries 2778 cue entries for its video track
+ * — one every 2.002 s — and 4669 more across four subtitle tracks;
+ * `Moana.2 … MegaPeer.mkv` carries 1055 for video and 5007 across five subtitle
+ * tracks. Read without the track, both sets went into the cut list together,
+ * and ffmpeg — which can only cut a copied picture at a real keyframe at or
+ * after the time it is asked for — moved every such cut forward to the next
+ * keyframe. That is the whole of the disagreement the field reported: 2.002 s
+ * on the first file, a median of 6.3 s and a worst case of 21 s on the second,
+ * and never once negative.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readMatroskaKeyframeTimes } from "../services/container-index/matroska.js";
+
+const ID_EBML = 0x1a45dfa3;
+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_CUES = 0x1c53bb6b;
+const ID_CUE_POINT = 0xbb;
+const ID_CUE_TIME = 0xb3;
+const ID_CUE_TRACK_POSITIONS = 0xb7;
+const ID_CUE_TRACK = 0xf7;
+const ID_CUE_CLUSTER_POSITION = 0xf1;
+
+/** An element id, as the bytes the specification gives it. */
+function idBytes(id) {
+  const bytes = [];
+  let rest = id;
+  while (rest > 0) {
+    bytes.unshift(rest & 0xff);
+    rest = Math.floor(rest / 256);
+  }
+  return Buffer.from(bytes);
+}
+
+/** A size, as a four-byte EBML variable-length integer. */
+function sizeBytes(size) {
+  const buffer = Buffer.alloc(4);
+  buffer.writeUInt32BE(size, 0);
+  buffer[0] |= 0x10;
+  return buffer;
+}
+
+function element(id, payload) {
+  return Buffer.concat([idBytes(id), sizeBytes(payload.length), payload]);
+}
+
+/** An unsigned value, in as few bytes as it needs. */
+function uintElement(id, value) {
+  const bytes = [];
+  let rest = value;
+  do {
+    bytes.unshift(rest & 0xff);
+    rest = Math.floor(rest / 256);
+  } while (rest > 0);
+  return element(id, Buffer.from(bytes));
+}
+
+function cuePoint(timeMs, tracks) {
+  return element(ID_CUE_POINT, Buffer.concat([
+    uintElement(ID_CUE_TIME, timeMs),
+    ...tracks.map((track) => element(ID_CUE_TRACK_POSITIONS, Buffer.concat([
+      uintElement(ID_CUE_TRACK, track),
+      uintElement(ID_CUE_CLUSTER_POSITION, 4096)
+    ])))
+  ]));
+}
+
+/**
+ * A file with the shape the field files have: one picture, one set of subtitles,
+ * and a table that indexes both.
+ *
+ * @param {{ withTracks?: boolean }} [options]
+ * @returns {Buffer}
+ */
+function buildFile({ withTracks = true, cueTrack = null } = {}) {
+  const info = element(ID_INFO, uintElement(ID_TIMESTAMP_SCALE, 1_000_000));
+  const tracks = element(ID_TRACKS, Buffer.concat([
+    element(ID_TRACK_ENTRY, Buffer.concat([
+      uintElement(ID_TRACK_NUMBER, 1),
+      uintElement(ID_TRACK_TYPE, 1) // video
+    ])),
+    element(ID_TRACK_ENTRY, Buffer.concat([
+      uintElement(ID_TRACK_NUMBER, 2),
+      uintElement(ID_TRACK_TYPE, 17) // subtitles
+    ]))
+  ]));
+  const forPicture = cueTrack ?? 1;
+  const forSubtitles = cueTrack ?? 2;
+  const cues = element(ID_CUES, Buffer.concat([
+    cuePoint(0, [forPicture]),
+    cuePoint(1070, [forSubtitles]),
+    cuePoint(2002, [forPicture]),
+    cuePoint(3141, [forSubtitles]),
+    cuePoint(4004, [forPicture])
+  ]));
+
+  const seekEntry = (targetId, position) => element(ID_SEEK, Buffer.concat([
+    element(ID_SEEK_ID, idBytes(targetId)),
+    element(ID_SEEK_POSITION, (() => {
+      const buffer = Buffer.alloc(4);
+      buffer.writeUInt32BE(position, 0);
+      return buffer;
+    })())
+  ]));
+  // Positions are relative to the Segment's payload, so the SeekHead has to be
+  // measured before they can be stated. Its own length does not change when the
+  // placeholders become real values: every size and position here is written at
+  // a fixed width.
+  const draft = element(ID_SEEK_HEAD, Buffer.concat([
+    seekEntry(ID_INFO, 0),
+    ...(withTracks ? [seekEntry(ID_TRACKS, 0)] : []),
+    seekEntry(ID_CUES, 0)
+  ]));
+  const infoAt = draft.length;
+  const tracksAt = infoAt + info.length;
+  const cuesAt = withTracks ? tracksAt + tracks.length : infoAt + info.length;
+  const seekHead = element(ID_SEEK_HEAD, Buffer.concat([
+    seekEntry(ID_INFO, infoAt),
+    ...(withTracks ? [seekEntry(ID_TRACKS, tracksAt)] : []),
+    seekEntry(ID_CUES, cuesAt)
+  ]));
+
+  const segmentPayload = Buffer.concat(
+    withTracks ? [seekHead, info, tracks, cues] : [seekHead, info, cues]
+  );
+  return Buffer.concat([
+    element(ID_EBML, Buffer.from([0x42, 0x86, 0x81, 0x01])),
+    element(ID_SEGMENT, segmentPayload)
+  ]);
+}
+
+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("only the picture's entries become cut times", async () => {
+  const file = buildFile();
+
+  const times = await readMatroskaKeyframeTimes(readerOver(file), file.length);
+
+  assert.deepEqual(
+    times.map((time) => Number(time.toFixed(3))),
+    [0, 2.002, 4.004],
+    "the subtitle entries at 1.070 and 3.141 are not keyframes, and a cut asked for there lands late"
+  );
+});
+
+test("a table whose entries name no known track is still used", async () => {
+  // The cue points reference track 9, which Tracks never declares. Filtering
+  // leaves nothing — and returning nothing would put an even grid on a copied
+  // picture, the failure this reader exists to prevent.
+  const file = buildFile({ cueTrack: 9 });
+
+  const times = await readMatroskaKeyframeTimes(readerOver(file), file.length);
+
+  assert.deepEqual(
+    times.map((time) => Number(time.toFixed(3))),
+    [0, 1.07, 2.002, 3.141, 4.004],
+    "an unrecognised table beats no table at all"
+  );
+});
+
+test("a file whose tracks cannot be read keeps every entry", async () => {
+  const file = buildFile({ withTracks: false });
+
+  const times = await readMatroskaKeyframeTimes(readerOver(file), file.length);
+
+  assert.deepEqual(
+    times.map((time) => Number(time.toFixed(3))),
+    [0, 1.07, 2.002, 3.141, 4.004],
+    "with nothing to tell the tracks apart, the old behaviour is the only one available"
+  );
+});