@torrent-tv/proxy 2.73.1 → 2.74.1

package/services/container/Container.js

@@ -1,135 +1,400 @@
-/**
- * @file Base Container — abstract per RFC 9559 / ISO 14496-12.
- *
- * A Container knows how to read its own format's track table and index.
- * Concrete containers (MatroskaContainer, Mp4Container, AviContainer) implement
- * spec-specific parsing. All byte access goes through `readRange(start,end)` so
- * the class works over torrent piece windows.
- *
- * Spec refs:
- *  - Matroska RFC 9559 §5: EBML, Segment, SeekHead, Tracks, Cues, Clusters
- *  - MP4 ISO/IEC 14496-12 §8: ftyp, moov, trak, tkhd, mdhd, hdlr, elng, stbl
- *  - AVI RIFF §: LIST hdrl, idx1
- */
-
-/**
- * What one file declares about itself. Every field is either a value the
- * container states or `null`, which means the container does not state it —
- * a defined absence, not "nobody has looked yet".
- *
- * @typedef {object} ContainerMediaInfo
- * @property {string} format - "matroska" | "mp4" | "avi" | "unknown".
- * @property {number | null} durationSeconds
- * @property {number | null} startTimeSeconds - Where this file's own timeline
- *   begins. Two files of one release need not agree on it, and the difference
- *   is what keeps a soundtrack shipped separately aligned with its picture.
- */
-
-export class Container {
-  /**
-   * @param {object} params
-   * @param {(start:number,end:number)=>Promise<Buffer|null>} params.readRange
-   * @param {number} params.fileSize
-   * @param {string} [params.label]
-   */
-  constructor({ readRange, fileSize, label = "" }) {
-    this.readRange = readRange;
-    this.fileSize = fileSize;
-    this.label = label;
-  }
-
-  /** @returns {string} Human name: "matroska" | "mp4" | "avi" | "unknown" */
-  get formatName() {
-    return "unknown";
-  }
-
-  /** Whether `head` (first bytes) looks like this container. */
-  static detect(_head) {
-    return false;
-  }
-
-  /**
-   * All tracks declared by the container, in container order.
-   * Includes disabled tracks (isEnabled=false) to preserve declaredIndex alignment with ffmpeg.
-   * @returns {Promise<import("../tracks/index.js").ContainerTrack[]>}
-   */
-  async readTracks() {
-    throw new Error("readTracks not implemented");
-  }
-
-  /**
-   * Keyframe times for the video track, ascending seconds. Null when index absent (MPEG-TS, fragmented MP4, truncated).
-   * @returns {Promise<{times:number[],tolerance:number}|null>}
-   */
-  async readKeyframeIndex() {
-    return null;
-  }
-
-  /**
-   * What this file DECLARES about itself as a whole, as distinct from what its
-   * individual tracks declare.
-   *
-   * The rule this method exists to hold: a fact the container declares is read
-   * from the container; a fact only the media itself has is measured from the
-   * media. Both halves used to be asked of ffmpeg, so the same header was read
-   * twice — measured 2026-09-03, this layer read one `.mka` header in 8 ms while
-   * a second ffmpeg read the same header over HTTP for 8121 ms, in the same
-   * second, on the same file.
-   *
-   * `null` is not "unknown, ask someone else". It means the container does not
-   * declare the field, which is a final answer about the container and the point
-   * at which a caller may go to the media — see `docs/container-architecture.md`.
-   *
-   * @returns {Promise<import("./Container.js").ContainerMediaInfo>}
-   */
-  async readMediaInfo() {
-    if (!this.mediaInfo) {
-      this.mediaInfo = {
-        format: this.formatName,
-        durationSeconds: null,
-        startTimeSeconds: null
-      };
-    }
-    return this.mediaInfo;
-  }
-
-  /**
-   * Subtitle-specific: where cues live (Matroska cluster positions or MP4 sample ranges).
-   * Returned via track objects' clusterPositions/samples, so base has no extra method — tracks carry it.
-   */
-
-  /**
-   * The TEXT FIELD of one subtitle cue, taken out of this container's framing.
-   *
-   * How a cue's bytes are wrapped is stated by the container's own
-   * specification, so each subclass answers for itself: Matroska reorders an ASS
-   * dialogue row, drops its two timing fields and prepends a read order
-   * (`matroska.org/technical/subtitles.html`); an MP4 prefixes a `tx3g` sample
-   * with its length (ISO/IEC 14496-12 §12.6); a subtitle FILE states its own
-   * field order in `[Events]`. None of that is a fact about the subtitle format,
-   * and the format's own markup — `{\pos(…)}`, `\N` — is not a fact about the
-   * container. The second half is `tracks/subtitle-markup.js`; this is the
-   * first, and the two are applied in that order.
-   *
-   * Static because de-framing reads no instance state: a caller that has bytes
-   * and knows the format needs no container built over the whole file. The
-   * instance form below exists so a caller that DOES hold a container gets the
-   * right answer without naming the subclass.
-   *
-   * @param {Buffer} _payload - The cue's bytes as the container stores them.
-   * @param {string} _codecId - CodecID / sample entry type / file extension.
-   * @returns {string} The text field, markup still in place.
-   */
-  static cueTextOf(_payload, _codecId) {
-    throw new Error("cueTextOf not implemented");
-  }
-
-  /**
-   * @param {Buffer} payload
-   * @param {string} codecId
-   * @returns {string}
-   */
-  cueTextOf(payload, codecId) {
-    return /** @type {typeof Container} */ (this.constructor).cueTextOf(payload, codecId);
-  }
-}
+/**
+ * @file Base Container — abstract per RFC 9559 / ISO 14496-12.
+ *
+ * A Container knows how to read its own format's track table and index.
+ * Concrete containers (MatroskaContainer, Mp4Container, AviContainer) implement
+ * spec-specific parsing. All byte access goes through `readRange(start,end)` so
+ * the class works over torrent piece windows.
+ *
+ * Spec refs:
+ *  - Matroska RFC 9559 §5: EBML, Segment, SeekHead, Tracks, Cues, Clusters
+ *  - MP4 ISO/IEC 14496-12 §8: ftyp, moov, trak, tkhd, mdhd, hdlr, elng, stbl
+ *  - AVI RIFF §: LIST hdrl, idx1
+ */
+
+/**
+ * What one file declares about itself. Every field is either a value the
+ * container states or `null`, which means the container does not state it —
+ * a defined absence, not "nobody has looked yet".
+ *
+ * @typedef {object} ContainerMediaInfo
+ * @property {string} format - "matroska" | "mp4" | "avi" | "unknown".
+ * @property {number | null} durationSeconds
+ * @property {number | null} startTimeSeconds - Where this file's own timeline
+ *   begins. Two files of one release need not agree on it, and the difference
+ *   is what keeps a soundtrack shipped separately aligned with its picture.
+ */
+
+export class Container {
+  /**
+   * Two ways of reading, because two readers of one file want different things
+   * and the file is opened once.
+   *
+   * `readRange` fetches what is missing: the head and the track table are
+   * kilobytes, they are needed before anything can be offered, and the codec
+   * probe has already pulled the head of every file that plays. `readHeld`
+   * reads only what is already downloaded and asks the swarm for nothing, which
+   * is what the cue walk needs — turning subtitles on must not pull bytes the
+   * viewer is not waiting for. `isHeld` says whether a range can be read that
+   * way at all, so the walk can leave a cluster for next time instead of
+   * blocking on it.
+   *
+   * They are given per container rather than per call because a container is
+   * cached per file and both readers want the same parsed head. Where the
+   * caller supplies only `readRange`, the held reader is that one and every
+   * range counts as held — which is the right answer for a local file, and for
+   * a torrent it is the caller's job to say otherwise.
+   *
+   * The torrent is NOT passed in and must not be: `readHeld` and `isHeld` are
+   * the only two facts about it this layer needs, and reducing it to two
+   * functions is what keeps the container ignorant of where its bytes live.
+   *
+   * @param {object} params
+   * @param {(start:number,end:number)=>Promise<Buffer|null>} params.readRange
+   * @param {number} params.fileSize
+   * @param {string} [params.label]
+   * @param {(start:number,end:number)=>Promise<Buffer|null>} [params.readHeld]
+   * @param {(start:number,end:number)=>boolean} [params.isHeld]
+   */
+  constructor({ readRange, fileSize, label = "", readHeld, isHeld }) {
+    this.readRange = readRange;
+    this.fileSize = fileSize;
+    this.label = label;
+    this.readHeld = typeof readHeld === "function" ? readHeld : readRange;
+    this.isHeld = typeof isHeld === "function" ? isHeld : () => true;
+  }
+
+
+  /**
+   * Whether one of ffmpeg's banner streams and one of this container's tracks
+   * can be the same track.
+   *
+   * @param {{ language?: string, title?: string }} banner
+   * @param {{ language?: string, name?: string }} container
+   * @returns {boolean}
+   */
+  static pairingHolds(banner, container) {
+    return pairingHolds(banner, container);
+  }
+
+  /**
+   * ffmpeg's description of a file's subtitle streams, corrected by what the
+   * container itself declares.
+   *
+   * The banner cannot express the difference between "no track is marked" and
+   * "every track is marked", because Matroska's `FlagDefault` defaults to 1 and
+   * ffmpeg has already applied that default by the time it prints. The
+   * container can be asked, and this is where the two readings are lined up —
+   * by position, checked pair by pair rather than assumed.
+   *
+   * @param {object[]} bannerTracks
+   * @param {object[]} declared - This container's own subtitle tracks, in its order.
+   * @returns {object[]}
+   */
+  static mergeSubtitleFlags(bannerTracks, declared) {
+    return mergeContainerSubtitleFlags(bannerTracks, declared);
+  }
+
+  /** @returns {string} Human name: "matroska" | "mp4" | "avi" | "unknown" */
+  get formatName() {
+    return "unknown";
+  }
+
+  /** Whether `head` (first bytes) looks like this container. */
+  static detect(_head) {
+    return false;
+  }
+
+  /**
+   * All tracks declared by the container, in container order.
+   * Includes disabled tracks (isEnabled=false) to preserve declaredIndex alignment with ffmpeg.
+   * @returns {Promise<import("../tracks/index.js").ContainerTrack[]>}
+   */
+  async readTracks() {
+    throw new Error("readTracks not implemented");
+  }
+
+
+  /**
+   * This container's subtitle tracks and where their cues are, in ONE shape
+   * whichever container answers.
+   *
+   * `tracks` carries a `clusterPositions` list for a container that stores cues
+   * in clusters and a `samples` list for one that states each cue's own byte
+   * range; a caller reads neither, and asks {@link Container#readHeldCues}
+   * instead. `declared` is what the container says about its subtitle tracks in
+   * its own order, and empty means the container said nothing — a real answer,
+   * not a missing one.
+   *
+   * @returns {Promise<{ tracks: object[], declared: object[], secondsPerTick: number, segmentDataOffset: number } | null>}
+   *   Null where this container declares no subtitles at all.
+   */
+  async readSubtitlePlan() {
+    return null;
+  }
+
+  /**
+   * The cues this container can read RIGHT NOW for one track, without fetching.
+   *
+   * Every container answers this, and each reads what its own specification
+   * says: Matroska walks the clusters its Cues table names, an MP4 reads the
+   * samples its table states. The caller therefore chooses a container once —
+   * from the bytes — and never again. It used to choose twice, once by file
+   * extension for the container and once by whether a track carried a sample
+   * list for the reading, and two choices that must agree and are made from
+   * different evidence are a disagreement waiting to happen.
+   *
+   * `progress` is what has already been read, kept by the caller because it
+   * belongs to the file rather than to one pass: `walked` holds cluster
+   * positions, `harvested` holds sample offsets per track. Each container adds
+   * to the one it uses.
+   *
+   * @param {object} _plan - This file's subtitle plan.
+   * @param {object} _track - The track asked about.
+   * @param {{ walked: Set<number>, harvested: Map<number, Set<number>> }} _progress
+   * @returns {Promise<{ found: Map<number, object[]>, covered: number, indexed: number }>}
+   *   `found` is track number to the cues found in THIS pass — Matroska fills
+   *   every track from one walk, so it is a map and not a list.
+   */
+  async readHeldCues(_plan, _track, _progress) {
+    return { found: new Map(), covered: 0, indexed: 0 };
+  }
+
+  /**
+   * Keyframe times for the video track, ascending seconds. Null when index absent (MPEG-TS, fragmented MP4, truncated).
+   * @returns {Promise<{times:number[],tolerance:number}|null>}
+   */
+  async readKeyframeIndex() {
+    return null;
+  }
+
+  /**
+   * What this file DECLARES about itself as a whole, as distinct from what its
+   * individual tracks declare.
+   *
+   * The rule this method exists to hold: a fact the container declares is read
+   * from the container; a fact only the media itself has is measured from the
+   * media. Both halves used to be asked of ffmpeg, so the same header was read
+   * twice — measured 2026-09-03, this layer read one `.mka` header in 8 ms while
+   * a second ffmpeg read the same header over HTTP for 8121 ms, in the same
+   * second, on the same file.
+   *
+   * `null` is not "unknown, ask someone else". It means the container does not
+   * declare the field, which is a final answer about the container and the point
+   * at which a caller may go to the media — see `docs/container-architecture.md`.
+   *
+   * @returns {Promise<import("./Container.js").ContainerMediaInfo>}
+   */
+  async readMediaInfo() {
+    if (!this.mediaInfo) {
+      this.mediaInfo = {
+        format: this.formatName,
+        durationSeconds: null,
+        startTimeSeconds: null
+      };
+    }
+    return this.mediaInfo;
+  }
+
+  /**
+   * Subtitle-specific: where cues live (Matroska cluster positions or MP4 sample ranges).
+   * Returned via track objects' clusterPositions/samples, so base has no extra method — tracks carry it.
+   */
+
+  /**
+   * The TEXT FIELD of one subtitle cue, taken out of this container's framing.
+   *
+   * How a cue's bytes are wrapped is stated by the container's own
+   * specification, so each subclass answers for itself: Matroska reorders an ASS
+   * dialogue row, drops its two timing fields and prepends a read order
+   * (`matroska.org/technical/subtitles.html`); an MP4 prefixes a `tx3g` sample
+   * with its length (ISO/IEC 14496-12 §12.6); a subtitle FILE states its own
+   * field order in `[Events]`. None of that is a fact about the subtitle format,
+   * and the format's own markup — `{\pos(…)}`, `\N` — is not a fact about the
+   * container. The second half is `TextSubtitleTrack`; this is the
+   * first, and the two are applied in that order.
+   *
+   * Static because de-framing reads no instance state: a caller that has bytes
+   * and knows the format needs no container built over the whole file. The
+   * instance form below exists so a caller that DOES hold a container gets the
+   * right answer without naming the subclass.
+   *
+   * @param {Buffer} _payload - The cue's bytes as the container stores them.
+   * @param {string} _codecId - CodecID / sample entry type / file extension.
+   * @returns {string} The text field, markup still in place.
+   */
+  static cueTextOf(_payload, _codecId) {
+    throw new Error("cueTextOf not implemented");
+  }
+
+  /**
+   * @param {Buffer} payload
+   * @param {string} codecId
+   * @returns {string}
+   */
+  cueTextOf(payload, codecId) {
+    return /** @type {typeof Container} */ (this.constructor).cueTextOf(payload, codecId);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Lining ffmpeg's banner up with what a container declares. Here because the
+// correction is about what a CONTAINER states and the banner cannot.
+// ---------------------------------------------------------------------------
+/**
+ * Which subtitle track the FILE says to show, read from the file rather than
+ * from ffmpeg's description of it.
+ *
+ * Why this exists. The browser decides which subtitle track to turn on from
+ * `isDefault`, and until now that came from ffmpeg's `-i` banner, which prints
+ * `(default)`. In Matroska `FlagDefault` DEFAULTS TO 1 and ffmpeg has already
+ * applied that default by the time it prints — so a file whose muxer wrote the
+ * flag on no track arrives looking exactly like one that wrote it on every
+ * track: everything marked. The banner cannot tell the two apart, and the
+ * difference is the whole question, because one of them means "show this one"
+ * and the other means "the file has no opinion".
+ *
+ * The container itself can be asked, and the EBML reader already walks the
+ * Tracks element for subtitle extraction. What it now also records is whether
+ * the element was WRITTEN, which is the fact the banner destroys.
+ *
+ * The awkward part is lining the two readings up. ffmpeg numbers its subtitle
+ * streams `0:s:0`, `0:s:1`, … over EVERY subtitle stream, picture-based ones
+ * included, in the order the container declares them; the container reading is
+ * a list in that same order. So position is the correspondence — but a position
+ * match that is merely assumed is worth nothing, so it is CHECKED: each pair
+ * has to agree on language or on title. One pair that agrees on neither, or a
+ * length that differs, means the two readings are not describing the same
+ * thing in the same order, and then the container reading is not used at all.
+ */
+
+/**
+ * Language codes that carry no information, and so cannot confirm a pairing.
+ *
+ * ffmpeg prints `und` for a stream with no language; Matroska's own default
+ * for `Language` is `eng`, which is why an absent element cannot be read as a
+ * statement either — but `eng` is also a real answer, so it is not listed here
+ * and is compared like any other.
+ */
+const EMPTY_LANGUAGES = new Set(["", "und", "unknown"]);
+
+/**
+ * @param {unknown} value
+ * @returns {string}
+ */
+function normalise(value) {
+  return typeof value === "string" ? value.trim().toLowerCase() : "";
+}
+
+/**
+ * Whether one banner stream and one container track can be the same track.
+ *
+ * Agreement on either the language or the name is enough; both being empty is
+ * not agreement, because two tracks that say nothing about themselves say
+ * nothing about their pairing either.
+ *
+ * @param {{ language?: string, title?: string }} banner
+ * @param {{ language?: string, name?: string }} container
+ * @returns {boolean}
+ */
+function pairingHolds(banner, container) {
+  const bannerLanguage = normalise(banner?.language);
+  const containerLanguage = normalise(container?.language);
+  if (
+    !EMPTY_LANGUAGES.has(bannerLanguage) &&
+    !EMPTY_LANGUAGES.has(containerLanguage) &&
+    bannerLanguage === containerLanguage
+  ) {
+    return true;
+  }
+  const bannerTitle = normalise(banner?.title);
+  const containerName = normalise(container?.name);
+  if (bannerTitle.length > 0 && bannerTitle === containerName) {
+    return true;
+  }
+  // Nothing to compare on either side. Not a disagreement — a file may name
+  // neither — so it does not break the alignment; it simply adds no support.
+  return (
+    (EMPTY_LANGUAGES.has(bannerLanguage) || EMPTY_LANGUAGES.has(containerLanguage)) &&
+    (bannerTitle.length === 0 || containerName.length === 0)
+  );
+}
+
+/**
+ * The banner's subtitle tracks, with what the container says about each.
+ *
+ * Every returned track gains `declaresDefault`: whether the FILE wrote the flag
+ * for it. When the container reading cannot be trusted — no declarations, a
+ * different number of them, or a pair that agrees on neither language nor name
+ * — every track gets `declaresDefault: false` and its `isDefault` is left as
+ * the banner had it. That is the honest answer for a file we cannot read this
+ * way: the container has not been heard from, so nothing is shown unasked.
+ *
+ * @param {Array<{ index?: number, language?: string, title?: string, isDefault?: boolean }>} bannerTracks
+ * @param {Array<{ language?: string, name?: string, isDefault?: boolean, declaresDefault?: boolean }>} declared
+ * @returns {{ tracks: object[], aligned: boolean, reason: string }}
+ */
+function mergeContainerSubtitleFlags(bannerTracks, declared) {
+  const banner = Array.isArray(bannerTracks) ? bannerTracks : [];
+  const container = Array.isArray(declared) ? declared : [];
+  const undecided = () => ({
+    // The container reading could not be lined up, so nothing of it is used —
+    // including the flags, which would otherwise be attributed to the wrong
+    // track.
+    tracks: banner.map((track) => ({
+      ...track,
+      declaresDefault: false,
+      isForced: false,
+      isHearingImpaired: false,
+      // Not "the container says this track is unusable" — nothing of the
+      // container is being used here. A track is offered unless it was read to
+      // say otherwise.
+      isEnabled: true,
+      languageBcp47: ""
+    }))
+  });
+  if (container.length === 0) {
+    return { ...undecided(), aligned: false, reason: "the container declares no subtitle track" };
+  }
+  if (container.length !== banner.length) {
+    return {
+      ...undecided(),
+      aligned: false,
+      reason: `the container declares ${container.length} subtitle tracks and the probe found ${banner.length}`
+    };
+  }
+  for (const [order, track] of banner.entries()) {
+    if (!pairingHolds(track, container[order])) {
+      return {
+        ...undecided(),
+        aligned: false,
+        reason:
+          `subtitle ${order} is "${normalise(track?.title) || "-"}"/${normalise(track?.language) || "-"} ` +
+          `in the probe and "${normalise(container[order]?.name) || "-"}"/` +
+          `${normalise(container[order]?.language) || "-"} in the container`
+      };
+    }
+  }
+  return {
+    tracks: banner.map((track, order) => ({
+      ...track,
+      isDefault: container[order].isDefault === true,
+      declaresDefault: container[order].declaresDefault === true,
+      // Read from the file rather than guessed from the track's name. Both are
+      // stated by the container itself (RFC 9559 §5.1.4.1) and neither reaches
+      // ffmpeg's `-i` banner, which is where every other field here comes from.
+      isForced: container[order].isForced === true,
+      isHearingImpaired: container[order].isHearingImpaired === true,
+      // FlagEnabled, so the browser can leave an unusable track out of the
+      // menu. It stays in this list and keeps its number: ffmpeg creates a
+      // stream for it either way.
+      isEnabled: container[order].isEnabled !== false,
+      // The RFC 5646 tag, where the file writes one. Kept beside the code
+      // rather than replacing it: what this list is aligned against is ffmpeg's
+      // banner, which prints the three-letter form.
+      languageBcp47: typeof container[order].languageBcp47 === "string" ? container[order].languageBcp47 : ""
+    })),
+    aligned: true,
+    reason: ""
+  };
+}

package/services/container/ContainerFactory.js

@@ -1,31 +1,55 @@
-/**
- * @file Container factory — detects format and returns the precise Container subclass.
- *
- * Sniffs first 16 bytes (same as container-index/index.js) and instantiates
- * MatroskaContainer / Mp4Container / AviContainer. Falls back to null (unknown).
- * Orchestrators depend on this, not on concrete constructors.
- */
-
-import { MatroskaContainer } from "./MatroskaContainer.js";
-import { Mp4Container } from "./Mp4Container.js";
-import { AviContainer } from "./AviContainer.js";
-
-const SNIFF_BYTES = 16;
-
-export class ContainerFactory {
-  /**
-   * @param {(start:number,end:number)=>Promise<Buffer|null>} readRange
-   * @param {number} fileSize
-   * @param {string} label
-   * @returns {Promise<import("./Container.js").Container|null>}
-   */
-  static async create({ readRange, fileSize, label = "" }) {
-    if (typeof readRange !== "function" || !Number.isFinite(fileSize) || fileSize <= 0) return null;
-    const head = await readRange(0, Math.min(SNIFF_BYTES - 1, fileSize - 1));
-    if (!head) return null;
-    if (MatroskaContainer.detect(head)) return new MatroskaContainer({ readRange, fileSize, label });
-    if (Mp4Container.detect(head)) return new Mp4Container({ readRange, fileSize, label });
-    if (AviContainer.detect(head)) return new AviContainer({ readRange, fileSize, label });
-    return null;
-  }
-}
+/**
+ * @file Container factory — detects format and returns the precise Container subclass.
+ *
+ * Sniffs first 16 bytes (same as container-index/index.js) and instantiates
+ * MatroskaContainer / Mp4Container / AviContainer. Falls back to null (unknown).
+ * Orchestrators depend on this, not on concrete constructors.
+ */
+
+import { MatroskaContainer } from "./MatroskaContainer.js";
+import { Mp4Container } from "./Mp4Container.js";
+import { AviContainer } from "./AviContainer.js";
+
+const SNIFF_BYTES = 16;
+
+export class ContainerFactory {
+  /**
+   * The container these bytes are, built over them.
+   *
+   * `params` is passed through whole, so a caller with a torrent's two readers
+   * gets a container that has both — see {@link Container}'s constructor.
+   *
+   * @param {{ readRange: (start:number,end:number)=>Promise<Buffer|null>, fileSize: number, label?: string, readHeld?: Function, isHeld?: Function }} params
+   * @returns {Promise<import("./Container.js").Container|null>}
+   */
+  static async create(params) {
+    const { readRange, fileSize } = params;
+    if (typeof readRange !== "function" || !Number.isFinite(fileSize) || fileSize <= 0) return null;
+    const head = await readRange(0, Math.min(SNIFF_BYTES - 1, fileSize - 1));
+    if (!head) return null;
+    if (MatroskaContainer.detect(head)) return new MatroskaContainer(params);
+    if (Mp4Container.detect(head)) return new Mp4Container(params);
+    if (AviContainer.detect(head)) return new AviContainer(params);
+    return null;
+  }
+
+  /**
+   * The container a file NAME suggests, for the moment the bytes cannot be
+   * sniffed.
+   *
+   * The head of a file nobody has opened is not downloaded, and the cue walk
+   * asks the swarm for nothing — so on that one path the name is all there is.
+   * It is a fallback and never a preference: the bytes decide wherever they can
+   * be read, because a name is what somebody typed and a header is what the
+   * muxer wrote.
+   *
+   * @param {string} name
+   * @returns {typeof MatroskaContainer | typeof Mp4Container | null}
+   */
+  static byName(name) {
+    const text = String(name ?? "");
+    if (/\.(mp4|m4v|m4a)$/i.test(text)) return Mp4Container;
+    if (/\.(mkv|mka|webm)$/i.test(text)) return MatroskaContainer;
+    return null;
+  }
+}