@torrent-tv/proxy 2.64.8 → 2.65.0

package/services/piece-store/shared-piece-store.js

@@ -107,6 +107,38 @@ function availableMemorySync() {
   return os.freemem();
 }
 
+/**
+ * How many piece buffers this thread has let go of, and how many the collector
+ * has actually taken back.
+ *
+ * The one reading that separates the two explanations of the 700 MB nobody can
+ * account for (roadmap item 2, field 2026-08-31): if the two numbers track each
+ * other, this code is holding nothing and whatever grows is below us, in the
+ * allocator — on musl there is no `malloc_trim` and no way to ask. If the gap
+ * widens, a reference of ours outlives the piece, and then a heap snapshot can
+ * name the holder.
+ *
+ * What it does NOT prove: a `SharedArrayBuffer`'s memory is shared between the
+ * isolates, so this thread's handle going means only that THIS thread let go.
+ * The main thread counts its own (`torrent-worker/client.js`), and the pair is
+ * what answers the question.
+ */
+const released = { count: 0, collected: 0 };
+const collector = typeof FinalizationRegistry === "function"
+  ? new FinalizationRegistry(() => {
+    released.collected += 1;
+  })
+  : null;
+
+/**
+ * What the collector has taken back against what was let go.
+ *
+ * @returns {{ released: number, collected: number }}
+ */
+export function pieceBufferCollection() {
+  return { released: released.count, collected: released.collected };
+}
+
 const MIN_BUDGET_BYTES = 64 * 1024 * 1024;
 const MIN_RESIDENT_PIECES = 2;
 /**
@@ -501,7 +533,7 @@ export class SharedPieceStore {
         this.#counters.fromMemory += 1;
         return already;
       }
-      const target = new SharedArrayBuffer(this.#lengthOf(index));
+      const target = this.#watchForCollection(new SharedArrayBuffer(this.#lengthOf(index)));
       await this.#disk.read(index, Buffer.from(target));
       this.#registerPiece(index, target);
       this.#counters.fromDisk += 1;
@@ -512,6 +544,19 @@ export class SharedPieceStore {
     }
   }
 
+  /**
+   * Count this buffer as one this thread will have to let go of, and notice
+   * when the collector takes it. See {@link pieceBufferCollection}.
+   *
+   * @param {SharedArrayBuffer} buffer
+   * @returns {SharedArrayBuffer} The same buffer.
+   */
+  #watchForCollection(buffer) {
+    released.count += 1;
+    collector?.register(buffer, null);
+    return buffer;
+  }
+
   /**
    * A fresh buffer holding this piece's bytes.
    *
@@ -521,7 +566,7 @@ export class SharedPieceStore {
    */
   #copyIntoNewBuffer(index, bytes) {
     const length = this.#lengthOf(index);
-    const sab = new SharedArrayBuffer(length);
+    const sab = this.#watchForCollection(new SharedArrayBuffer(length));
     const view = Buffer.from(sab);
     if (bytes.copy) {
       bytes.copy(view, 0, 0, length);

package/services/playback-planner.js

@@ -9,6 +9,8 @@
 import { spawn } from "node:child_process";
 import { logger } from "../utils/logger.js";
 import { mergeContainerSubtitleFlags } from "./subtitle-defaults.js";
+import { buildAudioInventory, mergeContainerAudioFlags } from "./audio-inventory.js";
+import { countVideoFiles, matchSidecarFiles } from "./sidecar-files.js";
 import {
   parseFfmpegDurationSeconds,
   parseFfmpegStartTimeSeconds,
@@ -28,6 +30,17 @@ const DIRECT_AUDIO_CODECS = new Set(["aac", "mp3", "opus", "vorbis", "flac"]);
 // the codec probe). ~16 MB ≈ the first segments of typical media.
 const BODY_PREFETCH_BYTES = 16 * 1024 * 1024;
 
+/**
+ * How long the plan waits for a file's own header before offering its
+ * soundtrack without what that header would have said.
+ *
+ * Not a measurement, and nothing is derived from it: it is the point past which
+ * holding the viewer costs more than the language and flags being waited for —
+ * which the folder name supplies anyway, from the torrent's file list, at no
+ * cost. The reading itself carries on in the worker and is kept there.
+ */
+const SIDECAR_HEADER_WAIT_MS = 3_000;
+
 /** Subtitle codecs that can be converted to WebVTT (text-based). */
 const TEXT_SUBTITLE_CODECS = new Set(["subrip", "srt", "ass", "ssa", "webvtt", "vtt", "mov_text", "text"]);
 
@@ -345,6 +358,122 @@ export function createPlaybackPlanner({
     return merged.tracks;
   }
 
+  /**
+   * Every soundtrack this file can be watched with, as one numbered list: its
+   * own tracks and the ones shipped as separate files beside it.
+   *
+   * Built here, in the plan, because the plan is what the viewer's menu is drawn
+   * from — so the offer is complete the moment a file is opened, with nothing
+   * arriving late and nothing measured while the viewer waits. It is also what
+   * the master playlist's rendition group is built from, so the number in the
+   * menu and the number in the `a/<n>/` address are the same number by
+   * construction rather than by agreement.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @param {object[]} bannerAudioTracks - The probe's own audio streams.
+   * @returns {Promise<import("./audio-inventory.js").AudioInventoryEntry[]>}
+   */
+  async function buildInventory(torrent, fileIndex, bannerAudioTracks) {
+    const banner = Array.isArray(bannerAudioTracks) ? bannerAudioTracks : [];
+    /**
+     * Read a file's declared audio tracks, or give up quickly.
+     *
+     * The plan is on the path to the first frame, and reading a sidecar's header
+     * waits on the swarm: that file has usually had nothing downloaded when this
+     * runs, and a header that never arrives would hold the plan — and the
+     * viewer — for the whole of the read's own patience. What a timeout costs is
+     * small and deliberate: the track is still offered, still numbered and still
+     * playable, only without the language and flags its own header would have
+     * given. The language the viewer actually sees is read from the FOLDER the
+     * release put it in, which is in the torrent's file list and needs no bytes
+     * at all.
+     *
+     * @param {number} wantedFileIndex
+     * @param {string} label
+     * @returns {Promise<object[]>}
+     */
+    const declaredAudioOf = async (wantedFileIndex, label) => {
+      if (typeof torrentPool?.getDeclaredAudioTracks !== "function") {
+        return [];
+      }
+      let timer = null;
+      try {
+        return await Promise.race([
+          torrentPool.getDeclaredAudioTracks(torrent, wantedFileIndex),
+          new Promise((resolve) => {
+            timer = setTimeout(() => resolve(null), SIDECAR_HEADER_WAIT_MS);
+            timer.unref?.();
+          })
+        ]).then((tracks) => {
+          if (tracks === null) {
+            logger.info(
+              `audio tracks: "${label}" did not answer within ` +
+              `${SIDECAR_HEADER_WAIT_MS / 1000}s — offered without what its header would say`
+            );
+            return [];
+          }
+          return Array.isArray(tracks) ? tracks : [];
+        });
+      } catch (error) {
+        logger.info(`audio tracks: "${label}" could not be read (${error?.message ?? error})`);
+        return [];
+      } finally {
+        if (timer !== null) {
+          clearTimeout(timer);
+        }
+      }
+    };
+    // The picture's own tracks: ffmpeg numbers them, the container declares what
+    // they are. Both readings, lined up and checked — see `audio-inventory.js`.
+    let embedded = banner.map((track) => ({ ...track, declaresDefault: false }));
+    if (banner.length > 0) {
+      // The picture's head is already downloaded — the codec probe just read it
+      // — so this is a parse and not a wait, but it is bounded like the rest.
+      const declared = await declaredAudioOf(fileIndex, "the picture");
+      const merged = mergeContainerAudioFlags(banner, declared);
+      embedded = merged.tracks;
+      logger.info(
+        merged.aligned
+          ? `audio tracks: the container describes all ${merged.tracks.length}` +
+            `${merged.tracks.some((track) => track.isCommentary) ? ", one of them commentary" : ""}` +
+            `${merged.tracks.some((track) => track.isVisualImpaired) ? ", one of them described" : ""}`
+          : `audio tracks: using the probe's own fields — ${merged.reason}`
+      );
+    }
+
+    const sidecarFiles = matchSidecarFiles({
+      files: torrent?.files ?? [],
+      videoIndex: fileIndex,
+      torrentName: typeof torrent?.name === "string" ? torrent.name : "",
+      videoCount: countVideoFiles(torrent?.files ?? [])
+    });
+    // All of them at once. They are separate files with separate headers, and
+    // read one after another the waits add up on the path to the first frame.
+    const sidecars = await Promise.all(
+      sidecarFiles.audio.map(async (file) => ({
+        file,
+        // A bare elementary stream — `.ac3`, `.dts`, `.mp3` — has no table to
+        // read, so nothing is asked of the swarm for it at all.
+        tracks: file.declaresTracks ? await declaredAudioOf(file.fileIndex, file.name) : []
+      }))
+    );
+    const inventory = buildAudioInventory({ embedded, videoFileIndex: fileIndex, sidecars });
+    if (sidecars.length > 0) {
+      logger.info(
+        `audio tracks: ${sidecars.length} file(s) beside the picture carry sound — ` +
+        inventory
+          .filter((entry) => entry.kind === "sidecar")
+          .map((entry) =>
+            `a:${entry.index}=${entry.folders.join("/") || "."}/${entry.fileName}` +
+            `#${entry.sourceTrackIndex}${entry.codec ? `(${entry.codec})` : ""}`
+          )
+          .join(" ")
+      );
+    }
+    return inventory;
+  }
+
   function withHostTimings(plan) {
     return {
       ...plan,
@@ -516,8 +645,10 @@ export function createPlaybackPlanner({
         // (list of forced resolutions <= source). 0 when unknown.
         videoWidth,
         videoHeight,
-        // Full track inventory for the browser's audio/subtitle menus.
-        audioTracks: audioTracks ?? [],
+        // Full track inventory for the browser's audio/subtitle menus. The audio
+        // half spans the picture's own tracks AND the soundtracks shipped as
+        // files beside it, under one numbering — see `buildInventory`.
+        audioTracks: await buildInventory(torrent, fileIndex, audioTracks ?? []),
         subtitleTracks: await withContainerDefaults(torrent, fileIndex, subtitleTracks ?? []),
         // Both host timings are filled in by `withHostTimings` on the way out,
         // never here: read at build time they would be frozen into the cached

package/services/sidecar-files.js

@@ -0,0 +1,352 @@
+/**
+ * Which files of a torrent belong to one video file as its sound or its
+ * subtitles.
+ *
+ * Releases often ship a dub or a subtitle set as SEPARATE FILES beside the
+ * picture — `Rus Sound/<name>.mka`, `Sub/[group]/<name>.ass` — and a viewer who
+ * cannot reach them is watching the release without half of what it carries.
+ * This module answers only which file goes with which; what is inside a file is
+ * the container layer's business (`services/container/`), and what a viewer is
+ * shown is composed in the browser, where the locale is known.
+ *
+ * Nothing here reads bytes, waits on the swarm or knows about ffmpeg. It is a
+ * function of the torrent's own list of names, which is why it can be tested
+ * outright.
+ *
+ * A note on the axes this fits into. A file beside the video is NOT a third kind
+ * of track: `<name>.mka` is a Matroska container holding an audio track, and
+ * `MatroskaContainer` reads it exactly as it reads the picture's own tracks. So
+ * "external" is not a type — it is only the answer to WHERE a track lives, and
+ * that answer belongs here rather than in `tracks/`, which describes what a
+ * container declares and must stay free of torrent knowledge.
+ */
+
+/**
+ * Containers and elementary streams that can carry a soundtrack on their own.
+ *
+ * Two groups, and the difference matters to the caller: `.mka` and `.m4a` have a
+ * track table that `ContainerFactory` can read, so their language, title and
+ * flags are available; the rest are raw elementary streams that carry exactly
+ * one track and declare nothing about it.
+ */
+export const AUDIO_SIDECAR_EXTENSIONS = new Set([
+  ".mka",
+  ".m4a",
+  ".aac",
+  ".ac3",
+  ".eac3",
+  ".dts",
+  ".dtshd",
+  ".flac",
+  ".mp3",
+  ".mp2",
+  ".ogg",
+  ".oga",
+  ".opus",
+  ".wav",
+  ".thd",
+  ".mlp",
+  ".wma"
+]);
+
+/**
+ * Subtitle files. Image-based ones (`.sup`, `.sub`, `.idx`) are listed because
+ * they exist and must be RECOGNISED — a file we cannot show is still not a
+ * soundtrack — but this module does not decide what is offerable; that is the
+ * subtitle track's own `isTextBased()`.
+ */
+export const SUBTITLE_SIDECAR_EXTENSIONS = new Set([
+  ".srt",
+  ".ass",
+  ".ssa",
+  ".vtt",
+  ".webvtt",
+  ".sub",
+  ".sup",
+  ".idx",
+  ".ttml",
+  ".smi",
+  ".txt"
+]);
+
+/**
+ * Containers that carry a picture.
+ *
+ * Here to COUNT them, not to decide what plays: whether a file is playable is
+ * the browser's answer, made from what its own media stack accepts, and this
+ * proxy must not acquire a second opinion about it. The count is needed for one
+ * decision — whether a torrent holds exactly one picture, in which case a
+ * soundtrack beside it has nothing else it could belong to.
+ */
+export const VIDEO_FILE_EXTENSIONS = new Set([
+  ".mp4",
+  ".mkv",
+  ".webm",
+  ".mov",
+  ".m4v",
+  ".avi",
+  ".mpg",
+  ".mpeg",
+  ".ts",
+  ".m2ts",
+  ".mts",
+  ".wmv",
+  ".asf",
+  ".flv",
+  ".f4v",
+  ".ogv",
+  ".ogm",
+  ".3gp",
+  ".3g2",
+  ".divx",
+  ".vob",
+  ".m2v",
+  ".m2p",
+  ".mxf",
+  ".rm",
+  ".rmvb"
+]);
+
+/**
+ * How many files of a torrent carry a picture.
+ *
+ * @param {Array<{ path?: string, name?: string }>} files
+ * @returns {number}
+ */
+export function countVideoFiles(files) {
+  let count = 0;
+  for (const file of Array.isArray(files) ? files : []) {
+    const name = typeof file?.name === "string" && file.name.length > 0
+      ? file.name
+      : String(file?.path ?? "");
+    if (VIDEO_FILE_EXTENSIONS.has(extensionOf(name))) {
+      count += 1;
+    }
+  }
+  return count;
+}
+
+/**
+ * Subtitle formats that are text, and therefore small by construction — a whole
+ * episode of dialogue is tens of kilobytes.
+ *
+ * The distinction is used to decide how much of such a file to fetch ahead of
+ * the viewer: a text file is fetched WHOLE, because it is smaller than the
+ * torrent's own piece and reading its edges would cost the same pieces as
+ * reading all of it. An image-based one (`.sup`, `.sub`+`.idx`) is a picture per
+ * cue and runs to tens of megabytes, so it gets the same edges treatment as
+ * anything else.
+ */
+export const TEXT_SUBTITLE_SIDECAR_EXTENSIONS = new Set([
+  ".srt",
+  ".ass",
+  ".ssa",
+  ".vtt",
+  ".webvtt",
+  ".ttml",
+  ".smi",
+  ".txt"
+]);
+
+/**
+ * Extensions whose track table a `Container` subclass can read. Everything else
+ * in {@link AUDIO_SIDECAR_EXTENSIONS} is a bare stream: one track, no metadata.
+ */
+const CONTAINER_BACKED_AUDIO = new Set([".mka", ".m4a", ".mp4", ".mkv", ".webm"]);
+
+/**
+ * The extension of a name, lowercased, including the dot. Empty when there is
+ * none.
+ *
+ * @param {string} name
+ * @returns {string}
+ */
+export function extensionOf(name) {
+  const text = typeof name === "string" ? name : "";
+  const dot = text.lastIndexOf(".");
+  // A leading dot is a hidden file, not an extension.
+  return dot > 0 ? text.slice(dot).toLowerCase() : "";
+}
+
+/**
+ * A name without its extension.
+ *
+ * @param {string} name
+ * @returns {string}
+ */
+export function baseNameOf(name) {
+  const text = typeof name === "string" ? name : "";
+  const dot = text.lastIndexOf(".");
+  return dot > 0 ? text.slice(0, dot) : text;
+}
+
+/**
+ * Whether a sidecar file of this extension has a readable track table.
+ *
+ * @param {string} extension - Lowercased, with the dot.
+ * @returns {boolean}
+ */
+export function declaresItsOwnTracks(extension) {
+  return CONTAINER_BACKED_AUDIO.has(extension);
+}
+
+/**
+ * Split a torrent file's path into the folders above it and its own name, with
+ * the torrent's own name removed from the front.
+ *
+ * WebTorrent prefixes every path in a multi-file torrent with the torrent name;
+ * the browser strips it again to show a playlist. Doing it once, here, means the
+ * folders travel to the browser already relative to the torrent root, so there
+ * is one stripping rule in the system rather than two that can disagree.
+ *
+ * @param {string} path - `file.path` as WebTorrent reports it.
+ * @param {string} torrentName
+ * @returns {{ folders: string[], name: string }}
+ */
+export function splitTorrentPath(path, torrentName) {
+  const text = typeof path === "string" ? path.replace(/\\/g, "/") : "";
+  const prefix = typeof torrentName === "string" && torrentName.length > 0 ? `${torrentName}/` : "";
+  const relative = prefix && text.startsWith(prefix) ? text.slice(prefix.length) : text;
+  const segments = relative.split("/").filter((segment) => segment.length > 0);
+  const name = segments.length > 0 ? segments[segments.length - 1] : "";
+  return { folders: segments.slice(0, -1), name };
+}
+
+/**
+ * Bracketed groups of a name, in order: `[HorribleSubs] X [1080p]` → both.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function bracketTokensOf(text) {
+  const source = typeof text === "string" ? text : "";
+  const tokens = [];
+  for (const match of source.matchAll(/\[([^\]]+)\]/g)) {
+    const token = match[1].trim();
+    if (token.length > 0) {
+      tokens.push(token);
+    }
+  }
+  return tokens;
+}
+
+/**
+ * Bracketed groups that look like a release hash — `[78EFD746]`. Anime releases
+ * carry the CRC of the file, and two files sharing one are certainly a pair.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+function hashTokensOf(text) {
+  return bracketTokensOf(text)
+    .filter((token) => /^[0-9a-f]{4,10}$/i.test(token))
+    .map((token) => token.toLowerCase());
+}
+
+/**
+ * Whether a sidecar and a video are the same release of the same episode.
+ *
+ * Two rules, both taken from what releases actually do, and neither of them
+ * involving the folder — a dub lives in a folder of its own by construction, so
+ * requiring the folders to match would reject every case this exists for:
+ *
+ * 1. the base names are equal, which is the common shape (`X.mkv` / `X.mka`);
+ * 2. they share a release hash, which anime releases carry.
+ *
+ * @param {string} sidecarName
+ * @param {string} videoName
+ * @returns {boolean}
+ */
+export function namesPair(sidecarName, videoName) {
+  const sidecarBase = baseNameOf(sidecarName).toLowerCase();
+  const videoBase = baseNameOf(videoName).toLowerCase();
+  if (sidecarBase.length === 0 || videoBase.length === 0) {
+    return false;
+  }
+  if (sidecarBase === videoBase) {
+    return true;
+  }
+  const videoHashes = new Set(hashTokensOf(videoBase));
+  if (videoHashes.size > 0) {
+    for (const token of hashTokensOf(sidecarBase)) {
+      if (videoHashes.has(token)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * @typedef {object} SidecarFile
+ * @property {number} fileIndex - Index in the torrent.
+ * @property {string} name - File name, extension included.
+ * @property {string[]} folders - Folders above it, relative to the torrent root.
+ * @property {string} extension - Lowercased, with the dot.
+ * @property {number} length - Bytes.
+ * @property {boolean} declaresTracks - Whether its own track table can be read.
+ */
+
+/**
+ * The audio and subtitle files of a torrent that belong to one video file.
+ *
+ * The pairing is by name (see {@link namesPair}), with ONE relaxation: a torrent
+ * holding a single video file has nothing else its sidecars could belong to, so
+ * there every sidecar is taken. That covers the very common
+ * `Film.mkv` + `Rus.mka` shape, where the two names have nothing in common. It
+ * is deliberately not extended to a torrent with several videos, where a wrong
+ * pairing would put the sound of one episode over the picture of another.
+ *
+ * @param {object} params
+ * @param {Array<{ path?: string, name?: string, length?: number }>} params.files
+ * @param {number} params.videoIndex
+ * @param {string} [params.torrentName]
+ * @param {number} [params.videoCount] - How many playable video files the
+ *   torrent holds. When 1, the relaxation above applies. Counted by the caller,
+ *   which is the side that knows what counts as playable.
+ * @returns {{ audio: SidecarFile[], subtitles: SidecarFile[] }}
+ */
+export function matchSidecarFiles({ files, videoIndex, torrentName = "", videoCount = 0 }) {
+  const list = Array.isArray(files) ? files : [];
+  const video = list[videoIndex];
+  if (!video) {
+    return { audio: [], subtitles: [] };
+  }
+  const videoPath = splitTorrentPath(video.path ?? video.name ?? "", torrentName);
+  const onlyVideo = videoCount === 1;
+  /** @type {SidecarFile[]} */
+  const audio = [];
+  /** @type {SidecarFile[]} */
+  const subtitles = [];
+
+  for (const [fileIndex, file] of list.entries()) {
+    if (fileIndex === videoIndex) {
+      continue;
+    }
+    const { folders, name } = splitTorrentPath(file?.path ?? file?.name ?? "", torrentName);
+    const extension = extensionOf(name);
+    const isAudio = AUDIO_SIDECAR_EXTENSIONS.has(extension);
+    const isSubtitle = !isAudio && SUBTITLE_SIDECAR_EXTENSIONS.has(extension);
+    if (!isAudio && !isSubtitle) {
+      continue;
+    }
+    if (!onlyVideo && !namesPair(name, videoPath.name)) {
+      continue;
+    }
+    const entry = {
+      fileIndex,
+      name,
+      folders,
+      extension,
+      length: Number.isFinite(file?.length) ? file.length : 0,
+      declaresTracks: declaresItsOwnTracks(extension)
+    };
+    if (isAudio) {
+      audio.push(entry);
+    } else {
+      subtitles.push(entry);
+    }
+  }
+
+  return { audio, subtitles };
+}

package/services/torrent-worker/client.js

@@ -41,6 +41,37 @@ const WORKER_EXIT_GRACE_MS = 5_000;
  * queued behind that work, so reading a finished 10 MB file took 12-23 s where
  * handing it to the channel took 125 ms.
  */
+/**
+ * Piece buffers this thread has been handed, and how many the collector has
+ * taken back.
+ *
+ * A `SharedArrayBuffer`'s memory belongs to neither isolate: it lives until
+ * BOTH have let go. So the worker's own count answers only half the question,
+ * and this is the other half — 700 MB grew in the field on 2026-08-31 with the
+ * store's own memory falling, and the two candidates are "a reference of ours
+ * outlives the piece" and "the allocator keeps what we free". These two
+ * counters separate them (roadmap item 2).
+ *
+ * A fragment arrives as a fresh handle onto the same shared memory every time,
+ * so what is counted is handles, not pieces. That is the right quantity anyway:
+ * one handle retained keeps the whole piece alive.
+ */
+const fragmentBuffers = { seen: 0, collected: 0 };
+const fragmentCollector = typeof FinalizationRegistry === "function"
+  ? new FinalizationRegistry(() => {
+    fragmentBuffers.collected += 1;
+  })
+  : null;
+
+/**
+ * What the collector has taken back against what this thread was handed.
+ *
+ * @returns {{ seen: number, collected: number }}
+ */
+export function fragmentBufferCollection() {
+  return { seen: fragmentBuffers.seen, collected: fragmentBuffers.collected };
+}
+
 export class TorrentWorkerClient {
   #worker;
   /**
@@ -138,6 +169,8 @@ export class TorrentWorkerClient {
             );
           }
           this.#lastPieceByRead.set(message.id, message.pieceIndex);
+          fragmentBuffers.seen += 1;
+          fragmentCollector?.register(buffer, null);
           const view = new Uint8Array(buffer, message.offset, message.length);
 
           const reader = this.#fragmentReaders.get(message.id);
@@ -292,6 +325,20 @@ export class TorrentWorkerClient {
     return this.#caller.call(Command.SUBTITLE_TRACKS, { sourceKey, fileIndex });
   }
 
+  /**
+   * Every track one file declares, read from its own header.
+   *
+   * Asked of the picture for the flags ffmpeg's banner does not carry, and of a
+   * soundtrack shipped as its own file beside it — the same question about a
+   * different file, which is why there is one command rather than two.
+   *
+   * @param {{ sourceKey: string, fileIndex: number }} params
+   * @returns {Promise<{ tracks: object[] }>}
+   */
+  async getContainerTracks({ sourceKey, fileIndex }) {
+    return this.#caller.call(Command.CONTAINER_TRACKS, { sourceKey, fileIndex });
+  }
+
   /**
    * The cues of one subtitle track that can be read from what is downloaded.
    *