@torrent-tv/proxy 2.75.0 → 2.76.0

package/routes/transcode/audio-file/get.js

@@ -25,7 +25,17 @@ export async function handleTranscodeAudioFileGet(req, reply, { hlsSessionManage
   const trackIndex = Number(req.params.trackIndex);
   const fileName = typeof req.params.fileName === "string" ? req.params.fileName : "";
 
-  const resolved = await hlsSessionManager.resolveAudioRenditionFile(baseSessionId, trackIndex, fileName);
+  // Which viewer is asking. One picture serves everyone watching it, and the
+  // soundtrack each of them chose is their own: without this, a segment request
+  // from one viewer would be read as everybody moving to that track, and the
+  // other viewer's encoder would be stopped once per segment.
+  const consumerId = typeof req.query?.consumer === "string" ? req.query.consumer : "";
+  const resolved = await hlsSessionManager.resolveAudioRenditionFile(
+    baseSessionId,
+    trackIndex,
+    fileName,
+    consumerId
+  );
   if (resolved.error) {
     // Retryable, like every other not-ready answer on this path: a 500 for a
     // rendition playlist would end the stream over something the next attempt

package/routes/transcode/audio-warm/get.js

@@ -36,9 +36,19 @@ export async function handleTranscodeAudioWarmGet(req, reply, { hlsSessionManage
     return reply.code(400).send({ error: "A track index and a non-negative position are required." });
   }
 
+  // Whose track change this is. Another viewer of the same picture may be
+  // listening to something else, and preparing a track must not be read as
+  // everybody moving to it.
+  const consumerId = typeof req.query?.consumer === "string" ? req.query.consumer : "";
+
   let prepared;
   try {
-    prepared = await hlsSessionManager.prepareAudioTrack(baseSessionId, trackIndex, positionSeconds);
+    prepared = await hlsSessionManager.prepareAudioTrack(
+      baseSessionId,
+      trackIndex,
+      positionSeconds,
+      consumerId
+    );
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     reply.header("Retry-After", "1");

package/routes/transcode/session-file/get.js

@@ -117,7 +117,7 @@ export async function serveSessionFile(req, reply, { hlsSessionManager, sessionI
     // where the viewer was.
     logger.info(
       `[hold] ${fileName} refused: the viewer is at ` +
-      `${hlsSessionManager.viewerPositionOf(sessionId).toFixed(1)}s and this is not the segment there`
+      `${hlsSessionManager.viewerPositionOf(sessionId, consumerId).toFixed(1)}s and this is not the segment there`
     );
     reply.header("Retry-After", "0");
     return reply.code(503).send({ error: "Superseded by a seek." });

package/routes/transcode/variant-file/get.js

@@ -26,7 +26,16 @@ export async function handleTranscodeVariantFileGet(req, reply, { hlsSessionMana
   const height = Number(req.params.height);
   const fileName = typeof req.params.fileName === "string" ? req.params.fileName : "";
 
-  const resolved = await hlsSessionManager.resolveVariantFile(baseSessionId, height, fileName);
+  // Which viewer is asking. Two viewers of one picture can be on two rungs, and
+  // a segment request is what says which rung a viewer is watching — read as
+  // the session's own, one of them would take the other off their step.
+  const consumerId = typeof req.query?.consumer === "string" ? req.query.consumer : "";
+  const resolved = await hlsSessionManager.resolveVariantFile(
+    baseSessionId,
+    height,
+    fileName,
+    consumerId
+  );
   if (resolved.error) {
     // Preparing the variant failed — a probe, a keyframe index, an input that
     // is not there yet. Retryable, like every other not-ready answer on this

package/scripts/render-run-graph.js

@@ -28,7 +28,7 @@ import {
   mayRestart,
   processCanBeSignalled,
   wireState
-} from "../services/encode-run-state.js";
+} from "../services/encode/encode-run-state.js";
 
 /** Where the rendered document lives. */
 export const GRAPH_DOC_PATH = path.join(
@@ -97,7 +97,7 @@ export function renderRunGraphMarkdown() {
   const lines = [];
 
   lines.push(
-    "<!-- GENERATED from services/encode-run-state.js by scripts/render-run-graph.js.",
+    "<!-- GENERATED from services/encode/encode-run-state.js by scripts/render-run-graph.js.",
     "     Do not edit by hand: change the table and run `npm run graph`. -->",
     "",
     "# The encoder run — states and transitions",

package/server.js

@@ -210,6 +210,23 @@ export async function startProxyServer({
         return null;
       }
     },
+    // Where the file's keyframes are, read by the same container that answered
+    // the two above. It used to be read by the session itself over this proxy's
+    // own HTTP, once per session — so two viewers opening one film read the
+    // same table twice, and each of them could get a different answer about
+    // whether the picture can be copied at all.
+    getContainerKeyframes: async ({ sourceKey, fileIndex }) => {
+      const record = sourceRegistry.get(sourceKey);
+      if (!record || typeof torrentPool.getContainerKeyframes !== "function") {
+        return null;
+      }
+      try {
+        const torrent = await torrentPool.getTorrent(record.sourceType, record.source);
+        return await torrentPool.getContainerKeyframes(torrent, fileIndex);
+      } catch {
+        return null;
+      }
+    },
     // Pull one whole file onto the disk. Used for a soundtrack that ships beside
     // the picture, once the encoder is as far ahead of the viewer as it is
     // allowed to get — the one moment the swarm's capacity is demonstrably
@@ -232,6 +249,14 @@ export async function startProxyServer({
       await torrentPool.fillFileInBackground?.(torrent, fileIndex);
     }
   });
+  // What the last life of this process left on the disk. The kernel kills this
+  // one often enough for that to be an ordinary state rather than an odd one —
+  // twice in a single viewing on 2026-09-02 — and when it does, no exit handler
+  // runs and nothing is cleared up. So this is both the cleanup and the only
+  // record that those encoders ended at all: it says what it found before it
+  // decides anything, keeps the segments whose closure is proven, and removes
+  // the one piece per output that was being written when the process died.
+  hlsSessionManager.adoptSegmentsLeftBehind();
   const playbackPlanner = createPlaybackPlanner({
     ffmpegBin,
     transcodeAudioEnabled: transcodeAudio,

package/services/audio-inventory.js

@@ -1,201 +1,206 @@
-/**
- * The soundtracks a viewer may choose between, as ONE numbered list — the ones
- * muxed into the picture and the ones shipped as separate files beside it.
- *
- * Why one list. Everything downstream addresses a soundtrack by a single number:
- * the browser's menu, the `audioTrackIndex` on the session-create request, the
- * `a/<n>/` path a rendition is published at, and hls.js's own rendition order.
- * Giving a sidecar file its own numbering would mean a second vocabulary and a
- * translation at every boundary. Instead the number stays flat and this module
- * owns the only place that knows what it resolves to: which FILE the track lives
- * in, and which track it is inside that file.
- *
- * The list is built from two readings of the same file, and that is deliberate:
- *
- * - ffmpeg's `-i` banner, which is what `0:a:N` will select and therefore the
- *   authority on NUMBERING;
- * - the container's own track table (`services/container/`), which is the only
- *   authority on the FLAGS — `FlagOriginal`, `FlagCommentary`,
- *   `FlagVisualImpaired`, `FlagEnabled` and `LanguageBCP47` do not appear in the
- *   banner at all, so the audio menu could not tell a director's commentary from
- *   the film itself.
- *
- * The two are lined up by position and the pairing is CHECKED, exactly as
- * `subtitle-defaults.js` checks its own: a length that differs, or one pair that
- * agrees on neither language nor title, means the two readings are not
- * describing the same thing in the same order — and then the container reading
- * is dropped whole rather than attributed to the wrong track. A wrong flag is
- * worse than a missing one, because `0:a:N` is what the encoder is given.
- */
-
-
-import { AudioTrack } from "./tracks/AudioTrack.js";
-
-
-
-
-
-/**
- * @typedef {object} AudioInventoryEntry
- * @property {number} index - The flat number everything downstream uses.
- * @property {number} fileIndex - The torrent file this track lives in.
- * @property {number} sourceTrackIndex - `0:a:N` WITHIN that file.
- * @property {"embedded" | "sidecar"} kind - Whether it is muxed into the picture
- *   or ships as a file beside it. Not a type of track — a statement about where
- *   the bytes are.
- * @property {string} codec
- * @property {string} language - As the container states it, or "" when it does
- *   not. Never guessed here: what a folder name suggests is derived in the
- *   browser, where the language table and the viewer's locale already live.
- * @property {string} languageBcp47
- * @property {string} title
- * @property {boolean} isDefault
- * @property {boolean} declaresDefault
- * @property {boolean} isOriginal
- * @property {boolean} isCommentary
- * @property {boolean} isVisualImpaired
- * @property {boolean} isEnabled
- * @property {number | null} channels
- * @property {string} fileName - For a sidecar: its own file name. "" otherwise.
- * @property {string[]} folders - For a sidecar: the folders above it, relative
- *   to the torrent root. What the browser reads a language and a releaser from.
- */
-
-/**
- * One numbered list from the picture's own tracks and its sidecar files.
- *
- * Order is load-bearing: embedded tracks keep the numbers they have always had,
- * so a session created before this existed and one created after agree about
- * what `audioTrackIndex: 1` means, and sidecars are appended after them in
- * torrent-file order. Sidecar files are stable in that order for a given
- * torrent, so the numbering is stable for a given file.
- *
- * @param {object} params
- * @param {object[]} params.embedded - Merged banner+container tracks of the video.
- * @param {number} params.videoFileIndex
- * @param {Array<{ file: import("./sidecar-files.js").SidecarFile, tracks: object[] }>} params.sidecars
- *   Each sidecar file with the audio tracks IT holds. A file whose container
- *   could not be read contributes one track, which is what a bare elementary
- *   stream is.
- * @returns {AudioInventoryEntry[]}
- */
-export function buildAudioInventory({ embedded, videoFileIndex, sidecars }) {
-  /** @type {AudioInventoryEntry[]} */
-  const inventory = [];
-  const add = (track, fileIndex, sourceTrackIndex, kind, file) => {
-    inventory.push({
-      index: inventory.length,
-      fileIndex,
-      sourceTrackIndex,
-      kind,
-      // The name the browser judges "can I play this?" by. For an embedded
-      // track it is ffmpeg's own; for a sidecar it is translated from what the
-      // container wrote, or from the extension when there was no table to read.
-      codec: AudioTrack.codecNameOf(track, file?.extension ?? ""),
-      language: typeof track?.language === "string" ? track.language : "",
-      languageBcp47: typeof track?.languageBcp47 === "string" ? track.languageBcp47 : "",
-      title:
-        typeof track?.title === "string" && track.title.length > 0
-          ? track.title
-          : (typeof track?.name === "string" ? track.name : ""),
-      isDefault: track?.isDefault === true,
-      declaresDefault: track?.declaresDefault === true,
-      isOriginal: track?.isOriginal === true,
-      isCommentary: track?.isCommentary === true,
-      isVisualImpaired: track?.isVisualImpaired === true,
-      isEnabled: track?.isEnabled !== false,
-      channels: Number.isFinite(track?.channels) ? track.channels : null,
-      fileName: kind === "sidecar" ? (file?.name ?? "") : "",
-      folders: kind === "sidecar" && Array.isArray(file?.folders) ? file.folders : []
-    });
-  };
-
-  for (const [order, track] of (Array.isArray(embedded) ? embedded : []).entries()) {
-    add(track, videoFileIndex, order, "embedded", null);
-  }
-  for (const sidecar of Array.isArray(sidecars) ? sidecars : []) {
-    const tracks = Array.isArray(sidecar?.tracks) && sidecar.tracks.length > 0
-      ? sidecar.tracks
-      // A file whose track table could not be read is one track: `.ac3`, `.dts`
-      // and `.mp3` have no table to read, and a `.mka` whose head has not
-      // arrived yet is better offered than hidden — ffmpeg will find its first
-      // audio stream either way.
-      : [{}];
-    for (const [order, track] of tracks.entries()) {
-      add(track, sidecar.file.fileIndex, order, "sidecar", sidecar.file);
-    }
-  }
-  return inventory;
-}
-
-/**
- * Resolve the flat number back to the file and the track inside it.
- *
- * @param {AudioInventoryEntry[]} inventory
- * @param {number} index
- * @returns {AudioInventoryEntry | null}
- */
-export function resolveAudioIndex(inventory, index) {
-  if (!Array.isArray(inventory) || !Number.isInteger(index) || index < 0) {
-    return null;
-  }
-  return inventory.find((entry) => entry.index === index) ?? null;
-}
-
-/**
- * The name an `#EXT-X-MEDIA` line carries for one soundtrack.
- *
- * Deliberately plain, and deliberately NOT localised: this is the name inside a
- * playlist, and what the viewer reads in the menu is composed in the browser
- * from the same facts, where the language table and the viewer's own locale are.
- * The only requirements here are that it says something and that no two
- * renditions of one file share it — hls.js groups renditions by name.
- *
- * @param {AudioInventoryEntry} entry
- * @param {AudioInventoryEntry[]} inventory
- * @returns {string}
- */
-export function audioRenditionName(entry, inventory) {
-  const parts = [];
-  if (entry.title) {
-    parts.push(entry.title);
-  } else if (entry.languageBcp47 || entry.language) {
-    parts.push(entry.languageBcp47 || entry.language);
-  } else if (entry.folders.length > 0) {
-    // The folder a dub sits in is usually the only thing naming it, and a
-    // release names it for a reason: "Rus Sound", "Ukr Dub".
-    parts.push(entry.folders[entry.folders.length - 1]);
-  } else if (entry.fileName) {
-    parts.push(entry.fileName);
-  } else {
-    parts.push(`Track ${entry.index + 1}`);
-  }
-  if (entry.isCommentary) {
-    parts.push("commentary");
-  } else if (entry.isVisualImpaired) {
-    parts.push("described");
-  }
-  const name = parts.join(" · ");
-  const clash = (Array.isArray(inventory) ? inventory : []).some(
-    (other) => other.index !== entry.index && audioRenditionNameCore(other) === audioRenditionNameCore(entry)
-  );
-  return clash ? `${name} (${entry.index + 1})` : name;
-}
-
-/**
- * The part of a rendition name that a clash is judged on — the name without the
- * disambiguating number, so that adding the number cannot itself cause a clash.
- *
- * @param {AudioInventoryEntry} entry
- * @returns {string}
- */
-function audioRenditionNameCore(entry) {
-  return (
-    entry.title ||
-    entry.languageBcp47 ||
-    entry.language ||
-    (entry.folders.length > 0 ? entry.folders[entry.folders.length - 1] : "") ||
-    entry.fileName ||
-    ""
-  );
-}
+/**
+ * The soundtracks a viewer may choose between, as ONE numbered list — the ones
+ * muxed into the picture and the ones shipped as separate files beside it.
+ *
+ * Why one list. Everything downstream addresses a soundtrack by a single number:
+ * the browser's menu, the `audioTrackIndex` on the session-create request, the
+ * `a/<n>/` path a rendition is published at, and hls.js's own rendition order.
+ * Giving a sidecar file its own numbering would mean a second vocabulary and a
+ * translation at every boundary. Instead the number stays flat and this module
+ * owns the only place that knows what it resolves to: which FILE the track lives
+ * in, and which track it is inside that file.
+ *
+ * The list is built from two readings of the same file, and that is deliberate:
+ *
+ * - ffmpeg's `-i` banner, which is what `0:a:N` will select and therefore the
+ *   authority on NUMBERING;
+ * - the container's own track table (`services/container/`), which is the only
+ *   authority on the FLAGS — `FlagOriginal`, `FlagCommentary`,
+ *   `FlagVisualImpaired`, `FlagEnabled` and `LanguageBCP47` do not appear in the
+ *   banner at all, so the audio menu could not tell a director's commentary from
+ *   the film itself.
+ *
+ * The two are lined up by position and the pairing is CHECKED, exactly as
+ * `subtitle-defaults.js` checks its own: a length that differs, or one pair that
+ * agrees on neither language nor title, means the two readings are not
+ * describing the same thing in the same order — and then the container reading
+ * is dropped whole rather than attributed to the wrong track. A wrong flag is
+ * worse than a missing one, because `0:a:N` is what the encoder is given.
+ */
+
+
+import { AudioTrack } from "./tracks/AudioTrack.js";
+
+
+
+
+
+/**
+ * @typedef {object} AudioInventoryEntry
+ * @property {number} index - The flat number everything downstream uses.
+ * @property {number} fileIndex - The torrent file this track lives in.
+ * @property {number} sourceTrackIndex - `0:a:N` WITHIN that file.
+ * @property {"embedded" | "sidecar"} kind - Whether it is muxed into the picture
+ *   or ships as a file beside it. Not a type of track — a statement about where
+ *   the bytes are.
+ * @property {string} codec
+ * @property {string} language - As the container states it, or "" when it does
+ *   not. Never guessed here: what a folder name suggests is derived in the
+ *   browser, where the language table and the viewer's locale already live.
+ * @property {string} languageBcp47
+ * @property {string} title
+ * @property {boolean} isDefault
+ * @property {boolean} declaresDefault
+ * @property {boolean} isOriginal
+ * @property {boolean} isCommentary
+ * @property {boolean} isVisualImpaired
+ * @property {boolean} isEnabled
+ * @property {number | null} channels
+ * @property {string} fileName - For a sidecar: its own file name. "" otherwise.
+ * @property {string[]} folders - For a sidecar: the folders above it, relative
+ *   to the torrent root. What the browser reads a language and a releaser from.
+ */
+
+/**
+ * One numbered list from the picture's own tracks and its sidecar files.
+ *
+ * Order is load-bearing: embedded tracks keep the numbers they have always had,
+ * so a session created before this existed and one created after agree about
+ * what `audioTrackIndex: 1` means, and sidecars are appended after them in
+ * torrent-file order. Sidecar files are stable in that order for a given
+ * torrent, so the numbering is stable for a given file.
+ *
+ * @param {object} params
+ * @param {object[]} params.embedded - Merged banner+container tracks of the video.
+ * @param {number} params.videoFileIndex
+ * @param {Array<{ file: import("./torrent/files.js").SidecarFile, tracks: object[] }>} params.sidecars
+ *   Each sidecar file with the audio tracks IT holds. A file whose container
+ *   could not be read contributes one track, which is what a bare elementary
+ *   stream is.
+ * @returns {AudioInventoryEntry[]}
+ */
+export function buildAudioInventory({ embedded, videoFileIndex, sidecars }) {
+  /** @type {AudioInventoryEntry[]} */
+  const inventory = [];
+  const add = (track, fileIndex, sourceTrackIndex, kind, file) => {
+    inventory.push({
+      index: inventory.length,
+      fileIndex,
+      sourceTrackIndex,
+      kind,
+      // The name the browser judges "can I play this?" by. For an embedded
+      // track it is ffmpeg's own; for a sidecar it is translated from what the
+      // container wrote, or from the extension when there was no table to read.
+      codec: AudioTrack.codecNameOf(track, file?.extension ?? ""),
+      language: typeof track?.language === "string" ? track.language : "",
+      languageBcp47: typeof track?.languageBcp47 === "string" ? track.languageBcp47 : "",
+      title:
+        typeof track?.title === "string" && track.title.length > 0
+          ? track.title
+          : (typeof track?.name === "string" ? track.name : ""),
+      isDefault: track?.isDefault === true,
+      declaresDefault: track?.declaresDefault === true,
+      isOriginal: track?.isOriginal === true,
+      isCommentary: track?.isCommentary === true,
+      isVisualImpaired: track?.isVisualImpaired === true,
+      isEnabled: track?.isEnabled !== false,
+      channels: Number.isFinite(track?.channels) ? track.channels : null,
+      fileName: kind === "sidecar" ? (file?.name ?? "") : "",
+      folders: kind === "sidecar" && Array.isArray(file?.folders) ? file.folders : [],
+      // What the file's own path says, for a track that ships as its own file:
+      // read here, by the grammar that also decided this file belongs to this
+      // picture. The browser used to read the same path again to build the
+      // label, which is one name read twice by two rules.
+      naming: kind === "sidecar" ? (file?.naming ?? null) : null
+    });
+  };
+
+  for (const [order, track] of (Array.isArray(embedded) ? embedded : []).entries()) {
+    add(track, videoFileIndex, order, "embedded", null);
+  }
+  for (const sidecar of Array.isArray(sidecars) ? sidecars : []) {
+    const tracks = Array.isArray(sidecar?.tracks) && sidecar.tracks.length > 0
+      ? sidecar.tracks
+      // A file whose track table could not be read is one track: `.ac3`, `.dts`
+      // and `.mp3` have no table to read, and a `.mka` whose head has not
+      // arrived yet is better offered than hidden — ffmpeg will find its first
+      // audio stream either way.
+      : [{}];
+    for (const [order, track] of tracks.entries()) {
+      add(track, sidecar.file.fileIndex, order, "sidecar", sidecar.file);
+    }
+  }
+  return inventory;
+}
+
+/**
+ * Resolve the flat number back to the file and the track inside it.
+ *
+ * @param {AudioInventoryEntry[]} inventory
+ * @param {number} index
+ * @returns {AudioInventoryEntry | null}
+ */
+export function resolveAudioIndex(inventory, index) {
+  if (!Array.isArray(inventory) || !Number.isInteger(index) || index < 0) {
+    return null;
+  }
+  return inventory.find((entry) => entry.index === index) ?? null;
+}
+
+/**
+ * The name an `#EXT-X-MEDIA` line carries for one soundtrack.
+ *
+ * Deliberately plain, and deliberately NOT localised: this is the name inside a
+ * playlist, and what the viewer reads in the menu is composed in the browser
+ * from the same facts, where the language table and the viewer's own locale are.
+ * The only requirements here are that it says something and that no two
+ * renditions of one file share it — hls.js groups renditions by name.
+ *
+ * @param {AudioInventoryEntry} entry
+ * @param {AudioInventoryEntry[]} inventory
+ * @returns {string}
+ */
+export function audioRenditionName(entry, inventory) {
+  const parts = [];
+  if (entry.title) {
+    parts.push(entry.title);
+  } else if (entry.languageBcp47 || entry.language) {
+    parts.push(entry.languageBcp47 || entry.language);
+  } else if (entry.folders.length > 0) {
+    // The folder a dub sits in is usually the only thing naming it, and a
+    // release names it for a reason: "Rus Sound", "Ukr Dub".
+    parts.push(entry.folders[entry.folders.length - 1]);
+  } else if (entry.fileName) {
+    parts.push(entry.fileName);
+  } else {
+    parts.push(`Track ${entry.index + 1}`);
+  }
+  if (entry.isCommentary) {
+    parts.push("commentary");
+  } else if (entry.isVisualImpaired) {
+    parts.push("described");
+  }
+  const name = parts.join(" · ");
+  const clash = (Array.isArray(inventory) ? inventory : []).some(
+    (other) => other.index !== entry.index && audioRenditionNameCore(other) === audioRenditionNameCore(entry)
+  );
+  return clash ? `${name} (${entry.index + 1})` : name;
+}
+
+/**
+ * The part of a rendition name that a clash is judged on — the name without the
+ * disambiguating number, so that adding the number cannot itself cause a clash.
+ *
+ * @param {AudioInventoryEntry} entry
+ * @returns {string}
+ */
+function audioRenditionNameCore(entry) {
+  return (
+    entry.title ||
+    entry.languageBcp47 ||
+    entry.language ||
+    (entry.folders.length > 0 ? entry.folders[entry.folders.length - 1] : "") ||
+    entry.fileName ||
+    ""
+  );
+}

package/services/container/AviContainer.js

@@ -85,7 +85,7 @@ export class AviContainer extends Container {
     return info;
   }
 
-  async readKeyframeIndex() {
+  async parseKeyframeIndex() {
     const r = await readAviKeyframeTimes(this.readRange, this.fileSize);
     if (!r) return null;
     if (Array.isArray(r)) return { times: r, tolerance: 0 };

package/services/container/Container.js

@@ -408,10 +408,42 @@ export class Container {
   }
 
   /**
-   * Keyframe times for the video track, ascending seconds. Null when index absent (MPEG-TS, fragmented MP4, truncated).
+   * Keyframe times for the video track, ascending seconds. Null when index
+   * absent (MPEG-TS, fragmented MP4, truncated).
+   *
+   * Read ONCE per file, like the track table and the media info beside it: this
+   * is a property of immutable bytes, so a second reading could only agree —
+   * and the reading is not cheap, since the table lives at the end of the file
+   * and comes off a torrent. The wait belongs here too: two sessions created in
+   * the same moment join one read instead of making two, which is exactly what
+   * two viewers opening one film do.
+   *
+   * The subclass says how its format states it; this says how often it is
+   * asked.
+   *
    * @returns {Promise<{times:number[],tolerance:number}|null>}
    */
   async readKeyframeIndex() {
+    if (this.keyframeIndexRead) {
+      return this.keyframeIndexRead;
+    }
+    this.keyframeIndexRead = Promise.resolve(this.parseKeyframeIndex()).catch((error) => {
+      // A failed read is not remembered as an answer: the bytes it needed may
+      // simply not have arrived yet.
+      this.keyframeIndexRead = null;
+      throw error;
+    });
+    return this.keyframeIndexRead;
+  }
+
+  /**
+   * How THIS format states where its keyframes are. Overridden by every
+   * container that has such a table; the default is the honest answer for one
+   * that does not.
+   *
+   * @returns {Promise<{times:number[],tolerance:number}|null>}
+   */
+  async parseKeyframeIndex() {
     return null;
   }
 

package/services/container/MatroskaContainer.js

@@ -681,7 +681,7 @@ export class MatroskaContainer extends Container {
     return fields.length > ASS_FIELDS_BEFORE_TEXT ? fields.slice(ASS_FIELDS_BEFORE_TEXT).join(",") : "";
   }
 
-  async readKeyframeIndex() {
+  async parseKeyframeIndex() {
     const times = await readMatroskaKeyframeTimes(this.readRange, this.fileSize);
     if (!times) return null;
     if (Array.isArray(times)) return { times, tolerance: 0 };

package/services/container/Mp4Container.js

@@ -519,7 +519,7 @@ export class Mp4Container extends Container {
     return decodeSubtitleSample(payload, codecId);
   }
 
-  async readKeyframeIndex() {
+  async parseKeyframeIndex() {
     const r = await readMp4KeyframeTimes(this.readRange, this.fileSize);
     if (!r) return null;
     if (Array.isArray(r)) return { times: r, tolerance: 0 };

package/services/container/SubtitleFileContainer.js

@@ -320,4 +320,3 @@ ${clean}`;
   }
 }
 
-export { EXTENSIONS as SUBTITLE_FILE_EXTENSIONS };