@torrent-tv/proxy 2.74.1 → 2.76.0

package/test/viewer-outputs.test.js

@@ -0,0 +1,273 @@
+/**
+ * @file What a viewer is watching, and what happens to it when they leave.
+ *
+ * The relation "this person watches this output" is indexed both ways — the
+ * output holds its viewers, the viewer holds its outputs — and these checks
+ * hold the three things that go wrong when the two indexes come apart.
+ *
+ * 1. The viewer must never be dropped from the PICTURE. Their chosen
+ *    soundtrack, their position and their step are recorded there, and the
+ *    picture is the only id the browser knows. Dropping them was reachable by
+ *    an ordinary sequence — down a step, back to the picture's own height, down
+ *    again — and cost them the soundtrack they had picked.
+ * 2. A viewer who leaves must be subtracted from EVERY output they were
+ *    watching, and an output with nobody left must be let go. Nothing outside
+ *    the session manager knows the id of a quality step or of a separately
+ *    published soundtrack, so nothing else can ever release one.
+ * 3. Whatever removes a viewer from an output must release what their watching
+ *    claimed of production. The only place a claim is released is the plan's
+ *    pass over the output's viewers, so a viewer deleted by any other route
+ *    leaves a claim that nothing can reach.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { HlsSessionManager, variantConsumerId } from "../services/hls-session-manager.js";
+import { Viewers } from "../services/viewer/Viewers.js";
+import { SourceFile } from "../services/source/SourceFile.js";
+import { Timeline } from "../services/output/Timeline.js";
+import { Output } from "../services/output/Output.js";
+import { fmp4Format } from "../services/segment-formats/fmp4.js";
+import { fakeProcess as fakeEncoder, startRunOn } from "./helpers/encode-run.js";
+
+const BASE_ID = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee";
+const STEP_ID = "11111111-2222-3333-4444-555555555555";
+const AUDIO_ID = "99999999-8888-7777-6666-555555555555";
+const VIEWER = "viewer-one";
+const SEGMENT_SECONDS = 4;
+
+/**
+ * A session shaped like a live one, without the ffmpeg run behind it.
+ *
+ * @param {{ id: string, dirPath: string, file: SourceFile, encodeHeight?: number,
+ *   audioOnly?: boolean, isStep?: boolean }} params
+ * @returns {object}
+ */
+function fakeSession({ id, dirPath, file, encodeHeight = 0, audioOnly = false, isStep = false }) {
+  return {
+    id,
+    dirPath,
+    timeline: new Timeline({
+      boundaries: Array.from({ length: 101 }, (_, index) => index * SEGMENT_SECONDS),
+      cutGrid: "uniform"
+    }),
+    state: "ready",
+    file,
+    get inputFile() { return this.file; },
+    get audioFile() { return this.file; },
+    startedAt: Date.now(),
+    createEntryMs: Date.now(),
+    lastAccessedAt: Date.now(),
+    ffmpeg: null,
+    lastError: "",
+    consumers: new Set(),
+    segmentFormat: fmp4Format,
+    transcodeVideo: !audioOnly,
+    transcodeAudio: true,
+    audioTrackIndex: 0,
+    audioOnly,
+    isStep,
+    variantHeight: isStep ? encodeHeight : undefined,
+    // Left set so that disposal does not remove a directory the other sessions
+    // of this output are still named by.
+    outputKey: `output-${id}`,
+    output: new Output({
+      encodeWidth: 0,
+      encodeHeight,
+      outputFps: 24,
+      softwarePreset: null,
+      applyTonemap: false
+    }),
+    encodeRunGeneration: 0,
+    lastRestartAt: 0,
+    seekFailureTarget: -1,
+    seekFailureCount: 0,
+    seekSettleTimer: null,
+    seekTarget: null,
+    waitEpoch: 0,
+    runs: new Set(),
+    viewers: new Map(),
+    usesExplicitCuts: false,
+    useSyntheticPlaylist: true,
+    playlistText: "#EXTM3U\n",
+    segmentCount: 100,
+    progress: { state: "running", processedSeconds: 0, startPositionSeconds: 0, speed: "1.0x" }
+  };
+}
+
+/**
+ * A picture with one quality step and one separately published soundtrack, all
+ * of one file, and one viewer watching all three — which is what an ordinary
+ * session looks like once the viewer has picked a language and a quality.
+ *
+ * @returns {Promise<{ manager: HlsSessionManager, base: object, step: object,
+ *   audio: object, dirPath: string, released: string[] }>}
+ */
+async function pictureWithStepAndSoundtrack() {
+  const dirPath = await mkdtemp(path.join(os.tmpdir(), "viewer-outputs-"));
+  const manager = new HlsSessionManager({
+    enabled: true,
+    ffmpegBin: "ffmpeg",
+    localBindHost: "127.0.0.1",
+    localPort: 9090
+  });
+  const file = new SourceFile({ sourceKey: "source-1", fileIndex: 0, name: "video.mkv" })
+    .learn({ width: 1920, height: 1080, fps: 24, bitrateKbps: 8000 });
+  const base = fakeSession({ id: BASE_ID, dirPath, file, encodeHeight: 812 });
+  const step = fakeSession({ id: STEP_ID, dirPath, file, encodeHeight: 540, isStep: true });
+  const audio = fakeSession({ id: AUDIO_ID, dirPath, file, audioOnly: true });
+  base.consumers = new Set([VIEWER]);
+  // The family's own claim, which is how a picture holds what it made: the
+  // browser never learns these two ids.
+  step.consumers = new Set([variantConsumerId(BASE_ID)]);
+  audio.consumers = new Set([variantConsumerId(BASE_ID)]);
+  for (const session of [base, step, audio]) {
+    manager.sessionsById.set(session.id, session);
+  }
+  file.stepHeights.set(540, 540);
+  /** @type {string[]} */
+  const released = [];
+  const realRelease = manager.encodeOrchestrator.release.bind(manager.encodeOrchestrator);
+  manager.encodeOrchestrator.release = (claimant) => {
+    released.push(claimant);
+    return realRelease(claimant);
+  };
+  return { manager, base, step, audio, dirPath, released };
+}
+
+test("a viewer who steps down, back to the picture's own height and down again keeps their record", async (t) => {
+  const { manager, base, dirPath } = await pictureWithStepAndSoundtrack();
+  t.after(() => rm(dirPath, { recursive: true, force: true }));
+  startRunOn(base, { process: fakeEncoder() });
+  const viewer = manager.viewers.of(base, VIEWER);
+  viewer.audio = { trackIndex: 1, transcode: true };
+  viewer.head = { segment: 25, seconds: 100, at: Date.now() };
+
+  await manager.resolveVariantFile(BASE_ID, 540, "segment-00025.mp4", VIEWER);
+  await manager.resolveVariantFile(BASE_ID, 812, "segment-00026.mp4", VIEWER);
+  await manager.resolveVariantFile(BASE_ID, 540, "segment-00027.mp4", VIEWER);
+
+  const known = base.viewers.get(VIEWER);
+  assert.ok(known, "the picture is the one id the browser holds — a viewer is never dropped from it");
+  assert.deepEqual(
+    known.audio,
+    { trackIndex: 1, transcode: true },
+    "the soundtrack they chose is recorded on the picture, and a quality switch does not touch it"
+  );
+  assert.equal(known.activeVariantId, STEP_ID, "and the step they moved to is where they are");
+});
+
+test("a viewer leaving is subtracted from every output, and one nobody is left watching is let go", async (t) => {
+  const { manager, base, step, audio, dirPath } = await pictureWithStepAndSoundtrack();
+  t.after(() => rm(dirPath, { recursive: true, force: true }));
+  // Watching all three, which is what a viewer who picked a language and a
+  // quality is doing.
+  manager.viewers.of(base, VIEWER).head = { segment: 25, seconds: 100, at: Date.now() };
+  manager.viewers.of(step, VIEWER);
+  manager.viewers.of(audio, VIEWER);
+  assert.deepEqual(
+    [...manager.viewers.of(base, VIEWER).outputs].sort(),
+    [BASE_ID, STEP_ID, AUDIO_ID].sort(),
+    "one viewer, one object, and it knows all three outputs it is watching"
+  );
+
+  await manager.releaseSessionConsumer(BASE_ID, VIEWER, "the viewer left");
+
+  assert.equal(manager.sessionsById.has(BASE_ID), false, "the picture goes with its last consumer");
+  assert.equal(
+    manager.sessionsById.has(STEP_ID),
+    false,
+    "and so does the quality step: nobody is watching it, and no one outside this class knows its id"
+  );
+  assert.equal(
+    manager.sessionsById.has(AUDIO_ID),
+    false,
+    "and the soundtrack, for the same reason — it used to sit for half an hour holding an encoder, a directory and a claim on the torrent"
+  );
+  assert.equal(manager.viewers.size, 0, "and nobody is left in the registry, which must not be a map that only grows");
+});
+
+test("an output somebody else is still watching is kept when one viewer leaves", async (t) => {
+  const { manager, base, step, audio, dirPath } = await pictureWithStepAndSoundtrack();
+  t.after(() => rm(dirPath, { recursive: true, force: true }));
+  const second = "viewer-two";
+  base.consumers.add(second);
+  manager.viewers.of(base, VIEWER).head = { segment: 25, seconds: 100, at: Date.now() };
+  manager.viewers.of(step, VIEWER);
+  manager.viewers.of(audio, VIEWER);
+  // The second viewer is listening to the same soundtrack and watching the
+  // picture at its own height.
+  manager.viewers.of(base, second).head = { segment: 25, seconds: 100, at: Date.now() };
+  manager.viewers.of(audio, second);
+
+  await manager.releaseSessionConsumer(BASE_ID, VIEWER, "the first viewer left");
+
+  assert.equal(manager.sessionsById.has(BASE_ID), true, "the picture stays: it still has a consumer");
+  assert.equal(
+    manager.sessionsById.has(AUDIO_ID),
+    true,
+    "and the soundtrack stays, because having no listeners is what kills it and it has one"
+  );
+  assert.equal(
+    base.viewers.has(VIEWER),
+    false,
+    "the viewer who left is gone from the picture"
+  );
+  assert.equal(
+    audio.viewers.has(VIEWER),
+    false,
+    "and from the soundtrack, which is the half of the relation the viewer holds"
+  );
+  assert.equal(step.viewers.size, 0, "the step they had is watched by nobody");
+});
+
+test("leaving an output releases what the watching claimed of production", async (t) => {
+  const { manager, base, step, audio, dirPath, released } = await pictureWithStepAndSoundtrack();
+  t.after(() => rm(dirPath, { recursive: true, force: true }));
+  manager.viewers.of(base, VIEWER).head = { segment: 25, seconds: 100, at: Date.now() };
+  manager.viewers.of(step, VIEWER);
+  manager.viewers.of(audio, VIEWER);
+
+  await manager.releaseSessionConsumer(BASE_ID, VIEWER, "the viewer left");
+
+  for (const id of [BASE_ID, STEP_ID, AUDIO_ID]) {
+    assert.ok(
+      released.includes(`${id}:${VIEWER}`),
+      `the claim on ${id.slice(0, 8)} is released — the plan's own pass cannot do it once the viewer is out of the map`
+    );
+  }
+});
+
+test("the two indexes of one relation are written together", () => {
+  const viewers = new Viewers();
+  const picture = { id: "picture" };
+  const soundtrack = { id: "soundtrack" };
+
+  const viewer = viewers.of(picture, VIEWER);
+  viewers.of(soundtrack, VIEWER);
+  assert.equal(viewers.of(soundtrack, VIEWER), viewer, "one person is one object, whatever they are watching");
+  assert.deepEqual([...viewer.outputs].sort(), ["picture", "soundtrack"]);
+  assert.equal(picture.viewers.get(VIEWER), viewer);
+
+  viewers.leaves(soundtrack, VIEWER);
+  assert.deepEqual([...viewer.outputs], ["picture"], "both directions go together");
+  assert.equal(soundtrack.viewers.has(VIEWER), false);
+  assert.equal(viewers.size, 1, "and the person is still known, because they are still watching something");
+
+  viewers.leaves(picture, VIEWER);
+  assert.equal(viewers.size, 0, "watching nothing, they are forgotten");
+});
+
+test("a viewer that cannot name itself belongs to the session that met it", () => {
+  const viewers = new Viewers();
+  const oneFilm = { id: "one" };
+  const another = { id: "another" };
+
+  const first = viewers.of(oneFilm, "");
+  const second = viewers.of(another, "");
+  assert.notEqual(first, second, "two anonymous viewers of two films are not one person");
+  assert.equal(viewers.size, 0, "and neither is in the registry, which is keyed by a name they do not have");
+});

package/test/viewer.test.js

@@ -0,0 +1,91 @@
+/**
+ * @file One object per person watching, and one deletion to forget them.
+ *
+ * It was six maps hung on the session, each keyed by consumer id, and the
+ * forgetting was already wrong: releasing a consumer emptied none of them, so a
+ * viewer who had left went on counting as wanting their soundtrack until their
+ * head expired, and their entries stayed for the life of the session.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { SourceFile } from "../services/source/SourceFile.js";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { HlsSessionManager } from "../services/hls-session-manager.js";
+import { Viewer, viewerOf, viewersOf } from "../services/viewer/Viewer.js";
+
+const SESSION_ID = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee";
+
+test("a viewer nobody has heard from is not watching", () => {
+  const viewer = new Viewer("someone");
+  const now = 1_000_000;
+
+  assert.equal(viewer.isLive(now, 60_000), false, "no head at all: they have never asked");
+  viewer.head = { segment: 4, seconds: 16, at: now - 10_000 };
+  assert.equal(viewer.isLive(now, 60_000), true);
+  viewer.head = { segment: 4, seconds: 16, at: now - 120_000 };
+  assert.equal(viewer.isLive(now, 60_000), false, "the tab is gone and nothing released it");
+});
+
+test("a stated position outranks the segment they last asked for", () => {
+  const viewer = new Viewer("someone");
+  assert.equal(viewer.positionSeconds(), null);
+
+  viewer.head = { segment: 10, seconds: 40, at: 1 };
+  assert.equal(viewer.positionSeconds(), 40, "where their player is reading");
+
+  viewer.head = { segment: 10, seconds: 40, at: 1, seeked: 900 };
+  assert.equal(viewer.positionSeconds(), 900, "a seek is the viewer saying where they are");
+});
+
+test("asking for a viewer twice is the same viewer", () => {
+  const session = {};
+  const first = viewerOf(session, "one");
+  first.audio = { trackIndex: 3, transcode: false };
+
+  assert.equal(viewerOf(session, "one"), first);
+  assert.equal(viewerOf(session, "one").audio.trackIndex, 3);
+  assert.notEqual(viewerOf(session, "two"), first);
+  assert.equal(viewersOf(session).size, 2);
+});
+
+test("releasing a consumer forgets everything that was true of them alone", async (t) => {
+  const dirPath = await mkdtemp(path.join(os.tmpdir(), "viewer-"));
+  t.after(async () => {
+    await rm(dirPath, { recursive: true, force: true });
+  });
+  const manager = new HlsSessionManager({
+    enabled: true,
+    ffmpegBin: "ffmpeg",
+    localBindHost: "127.0.0.1",
+    localPort: 9090
+  });
+  const session = {
+    id: SESSION_ID,
+    dirPath,
+    state: "live",
+    file: new SourceFile({ sourceKey: "source-1", fileIndex: 0, name: "video.mkv" }),
+    // An ordinary session reads its own file, and its sound is inside it. The
+    // three differ only for a soundtrack shipped as a file of its own.
+    get inputFile() { return this.file; },
+    get audioFile() { return this.file; },
+    consumers: new Set(["staying", "leaving"]),
+    viewers: new Map(),
+    lastAccessedAt: Date.now()
+  };
+  manager.sessionsById.set(SESSION_ID, session);
+
+  const leaving = viewerOf(session, "leaving");
+  leaving.audio = { trackIndex: 2, transcode: true };
+  leaving.activeVariantId = "some-variant";
+  leaving.head = { segment: 40, seconds: 160, at: Date.now() };
+  viewerOf(session, "staying").audio = { trackIndex: 0, transcode: false };
+
+  await manager.releaseSessionConsumer(SESSION_ID, "leaving", "the tab was closed");
+
+  assert.equal(session.viewers.has("leaving"), false, "one deletion, not six");
+  assert.equal(session.viewers.has("staying"), true, "and it takes nobody else with it");
+  assert.equal(session.consumers.size, 1);
+});

package/utils/perf.js

@@ -21,7 +21,7 @@
  * somewhere specific.
  */
 
-import { monitorEventLoopDelay, performance } from "node:perf_hooks";
+import { monitorEventLoopDelay } from "node:perf_hooks";
 
 const NANOSECONDS_PER_MILLISECOND = 1e6;
 // Sampling interval for the loop-delay histogram. 20 ms is fine enough to catch
@@ -57,65 +57,3 @@ export function eventLoopDelay() {
 export function resetEventLoopDelay() {
   loopDelay.reset();
 }
-
-/**
- * Accumulates how long the parts of one operation took.
- *
- * Usage: `mark()` after each step; `summary()` renders `step=12.3ms` pairs in
- * the order they were marked.
- */
-export class OperationTimer {
-  #startedAt;
-  #lastMarkAt;
-  #marks;
-
-  constructor() {
-    this.#startedAt = performance.now();
-    this.#lastMarkAt = this.#startedAt;
-    this.#marks = [];
-  }
-
-  /**
-   * Record the time since the previous mark under `name`.
-   *
-   * @param {string} name
-   * @returns {number} Milliseconds since the previous mark.
-   */
-  mark(name) {
-    const now = performance.now();
-    const elapsed = now - this.#lastMarkAt;
-    this.#lastMarkAt = now;
-    this.#marks.push([name, elapsed]);
-    return elapsed;
-  }
-
-  /**
-   * Add a figure measured elsewhere (a running total, a count) so it appears in
-   * the same line as the timings.
-   *
-   * @param {string} name
-   * @param {number} value
-   * @returns {void}
-   */
-  add(name, value) {
-    this.#marks.push([name, value]);
-  }
-
-  /**
-   * Total elapsed time since construction, in milliseconds.
-   *
-   * @returns {number}
-   */
-  totalMs() {
-    return performance.now() - this.#startedAt;
-  }
-
-  /**
-   * All marks as `name=12.3ms` pairs, in order.
-   *
-   * @returns {string}
-   */
-  summary() {
-    return this.#marks.map(([name, value]) => `${name}=${value.toFixed(1)}ms`).join(" ");
-  }
-}

package/services/container/index.js

@@ -1,6 +0,0 @@
-export { Container } from "./Container.js";
-export { MatroskaContainer } from "./MatroskaContainer.js";
-export { Mp4Container } from "./Mp4Container.js";
-export { AviContainer } from "./AviContainer.js";
-export { SubtitleFileContainer, SUBTITLE_FILE_EXTENSIONS } from "./SubtitleFileContainer.js";
-export { ContainerFactory } from "./ContainerFactory.js";

package/services/container-index/avi.js

@@ -1,167 +0,0 @@
-/**
- * @file Keyframe index for AVI, read without downloading the file.
- *
- * AVI ends with an `idx1` chunk: one fixed-size entry per stream chunk, each
- * carrying a flags word whose keyframe bit says whether that chunk starts a
- * keyframe. Frame number times the video stream's frame duration gives the
- * time, so the index alone is enough — no media has to be read.
- *
- * `idx1` lives at the end of the file and the top-level chunk headers state
- * their sizes, so it is reached by stepping over headers (typically two hops:
- * `LIST hdrl`, `LIST movi`), not by scanning.
- *
- * Still relevant despite the format's age: older releases are largely XviD in
- * AVI, and those are exactly the files that get copied rather than re-encoded.
- */
-
-const HEADER_BYTES = 8;
-const PROBE_BYTES = 4096;
-// Keyframe flag in an idx1 entry's flags word (AVIIF_KEYFRAME).
-const KEYFRAME_FLAG = 0x10;
-const IDX1_ENTRY_BYTES = 16;
-// Cap on the idx1 read. One entry per chunk, 16 bytes each — a long film runs
-// to a few MB; beyond this is not a normal index.
-const MAX_IDX1_BYTES = 64 * 1024 * 1024;
-
-/**
- * Whether this looks like AVI: a RIFF container whose form type is `AVI `.
- *
- * @param {Buffer} head
- * @returns {boolean}
- */
-export function isAvi(head) {
-  return (
-    head.length >= 12 &&
-    head.toString("latin1", 0, 4) === "RIFF" &&
-    head.toString("latin1", 8, 12) === "AVI "
-  );
-}
-
-/**
- * Microseconds per frame and the video stream's chunk id prefix, from the main
- * header. Both live in the `hdrl` list near the file start.
- *
- * @param {Buffer} head
- * @returns {{ microsecondsPerFrame: number } | null}
- */
-function readMainHeader(head) {
-  // Top-level: "RIFF" size "AVI " then chunks. `avih` sits inside `LIST hdrl`.
-  let offset = 12;
-  while (offset + HEADER_BYTES <= head.length) {
-    const id = head.toString("latin1", offset, offset + 4);
-    const size = head.readUInt32LE(offset + 4);
-    if (size <= 0) {
-      return null;
-    }
-    if (id === "LIST") {
-      // Descend: list type follows the header, then its own chunks.
-      const listType = head.toString("latin1", offset + 8, offset + 12);
-      if (listType === "hdrl") {
-        let inner = offset + 12;
-        while (inner + HEADER_BYTES <= Math.min(head.length, offset + 8 + size)) {
-          const innerId = head.toString("latin1", inner, inner + 4);
-          const innerSize = head.readUInt32LE(inner + 4);
-          if (innerSize <= 0) {
-            return null;
-          }
-          if (innerId === "avih" && inner + 8 + 4 <= head.length) {
-            return { microsecondsPerFrame: head.readUInt32LE(inner + 8) };
-          }
-          inner += HEADER_BYTES + innerSize + (innerSize % 2);
-        }
-      }
-      offset += HEADER_BYTES + 4 + (size - 4) + ((size - 4) % 2);
-      continue;
-    }
-    offset += HEADER_BYTES + size + (size % 2);
-  }
-  return null;
-}
-
-/**
- * Step over top-level chunks to find `idx1`.
- *
- * @param {(start: number, end: number) => Promise<Buffer | null>} readRange
- * @param {number} fileSize
- * @returns {Promise<{ offset: number, size: number } | null>}
- */
-async function findIdx1(readRange, fileSize) {
-  let offset = 12; // Past "RIFF" size "AVI ".
-  while (offset + HEADER_BYTES < fileSize) {
-    const probe = await readRange(offset, Math.min(fileSize - 1, offset + HEADER_BYTES - 1));
-    if (!probe || probe.length < HEADER_BYTES) {
-      return null;
-    }
-    const id = probe.toString("latin1", 0, 4);
-    const size = probe.readUInt32LE(4);
-    if (size <= 0) {
-      return null;
-    }
-    if (id === "idx1") {
-      return { offset: offset + HEADER_BYTES, size };
-    }
-    // Chunks are word-aligned; a LIST carries its type inside the payload, so
-    // the same size arithmetic covers both cases.
-    offset += HEADER_BYTES + size + (size % 2);
-  }
-  return null;
-}
-
-/**
- * Read the keyframe times of an AVI file.
- *
- * @param {(start: number, end: number) => Promise<Buffer | null>} readRange
- * @param {number} fileSize
- * @returns {Promise<number[] | null>} Ascending seconds, or null when the file
- *   has no `idx1` (OpenDML-only index, interrupted write, damaged upload).
- */
-export async function readAviKeyframeTimes(readRange, fileSize) {
-  const head = await readRange(0, Math.min(PROBE_BYTES - 1, fileSize - 1));
-  if (!head || !isAvi(head)) {
-    return null;
-  }
-  const mainHeader = readMainHeader(head);
-  if (!mainHeader || !mainHeader.microsecondsPerFrame) {
-    return null;
-  }
-
-  const idx1 = await findIdx1(readRange, fileSize);
-  if (!idx1 || idx1.size > MAX_IDX1_BYTES) {
-    return null;
-  }
-
-  const table = await readRange(idx1.offset, Math.min(fileSize - 1, idx1.offset + idx1.size - 1));
-  if (!table || table.length < IDX1_ENTRY_BYTES) {
-    return null;
-  }
-
-  const secondsPerFrame = mainHeader.microsecondsPerFrame / 1e6;
-  const times = [];
-  let videoFrame = 0;
-  for (let at = 0; at + IDX1_ENTRY_BYTES <= table.length; at += IDX1_ENTRY_BYTES) {
-    const chunkId = table.toString("latin1", at, at + 4);
-    // Video chunks are "##db" (uncompressed) or "##dc" (compressed); audio is
-    // "##wb" and must not advance the frame counter.
-    const isVideo = chunkId.endsWith("db") || chunkId.endsWith("dc");
-    if (!isVideo) {
-      continue;
-    }
-    const flags = table.readUInt32LE(at + 4);
-    if ((flags & KEYFRAME_FLAG) !== 0) {
-      times.push(videoFrame * secondsPerFrame);
-    }
-    videoFrame += 1;
-  }
-  if (times.length === 0) {
-    return null;
-  }
-  // AVI names a keyframe by its FRAME NUMBER, and the time above is that number
-  // multiplied by the frame duration the header declares. The frames are the
-  // right ones — measured 2026-08-21 against the files themselves, 1196 index
-  // entries against 1196 real keyframes and 901 against 901, exactly — but the
-  // names are 10-44 ms away from the presentation times the demuxer computes,
-  // always under one frame. So the caller is told how far a time here may be
-  // from the instant it refers to, and can ask for a seek late enough that it
-  // still lands on the frame rather than on the one before it.
-  return { times, tolerance: secondsPerFrame };
-}