@torrent-tv/proxy 2.64.8 → 2.65.0

package/docs/container-architecture.md

@@ -2,6 +2,32 @@
 
 Domain → Application → Interface, per RFC 9559 (Matroska) and ISO/IEC 14496-12 (MP4).
 
+## Two axes, and what is NOT a third
+
+Everything here is placed on exactly two axes: **which container** a track lives
+in, and **what kind of track** it is (video / audio / subtitle). A file lying
+beside the video — a dub as `<name>.mka`, subtitles as `<name>.ass` — is not a
+third kind of anything:
+
+- a `.mka` **is** Matroska. `ContainerFactory` sniffs it, `MatroskaContainer`
+  reads its `TrackEntry` list, and out comes an `AudioTrack` with its language,
+  title and flags. It differs from the picture's own file only in having no
+  video track. The same holds for `.m4a` and `Mp4Container`;
+- "external" is therefore not a TYPE. It is the answer to WHERE a track's bytes
+  are, and that is torrent knowledge — which this layer must not have
+  (`ContainerFactory`: no torrent knowledge; `ContainerOrchestrator`:
+  transport-agnostic). The pairing of a sidecar file with a picture lives in
+  `services/sidecar-files.js`, and the numbered list a viewer chooses from lives
+  in `services/audio-inventory.js`. Both are pure and both are application-layer.
+
+A class called `ExternalSubtitleFile` used to sit in `tracks/` asserting the
+opposite. It did not extend `ContainerTrack`, duplicated four of its fields, and
+was imported by nothing; it was deleted rather than extended. Nothing replaced
+it — a subtitle file beside the video is a `TextSubtitleTrack` whose bytes are
+read from another file, and a raw `.srt` needs no `Container` subclass because
+it has no track table and no index to read: the whole file is the payload, and
+`SubtitleController` already reads it as such.
+
 ## Layers
 
 ```mermaid
@@ -26,8 +52,12 @@ flowchart TB
     CF[ContainerFactory<br/>detect 16 bytes]
     CO[ContainerOrchestrator<br/>cache + getTracks/getKeyframeIndex]
     SO[SubtitleOrchestrator<br/>wrap subtitle-cues.js]
+    SF[sidecar-files.js<br/>which file goes with which]
+    AI[audio-inventory.js<br/>one flat numbering]
     CF --> CO
     CO --> SO
+    SF --> AI
+    CO --> AI
   end
   subgraph Interface
     PC[PlaybackController]
@@ -50,6 +80,8 @@ flowchart TB
 | `AudioTrack` | RFC9559 FlagOriginal 0x55AE, FlagCommentary 0x55AF, FlagVisualImpaired 0x55AC | `isOriginal/isCommentary/isVisualImpaired`, `channels/samplingFrequency` | FlagForced |
 | `SubtitleTrack` | RFC9559 FlagForced 0x55AA (subtitle-only), FlagHearingImpaired 0x55AB | `isForced/isHearingImpaired`, `clusterPositions`/`samples` | Video dims |
 | `TextSubtitleTrack` | `S_TEXT/UTF8, S_TEXT/ASS, tx3g, wvtt` | `toVtt()` convertible | Image tracks |
+| `sidecar-files.js` | — (torrent naming) | which files of a torrent are one picture's sound and subtitles | what is inside them |
+| `audio-inventory.js` | RFC9559 audio flags, merged against ffmpeg's numbering | one flat number per soundtrack → `(fileIndex, 0:a:N)` | display labels |
 | `ImageSubtitleTrack` | `S_HDMV/PGS, S_VOBSUB, subp, clcp` | kept for `declaredIndex` alignment | Conversion |
 | `MatroskaContainer` | RFC9559 SeekHead, Tracks, Cues, Clusters | single Tracks walk for all types, EBML via `ebml-reader.js` | HTTP |
 | `Mp4Container` | ISO 14496-12 moov/trak/tkhd/mdhd/hdlr/elng/stbl | `alternate_group` grouping, packed language, `tx3g` forced bits | Torrent |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.64.8",
+  "version": "2.65.0",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {

package/routes/api/sources/warm/post.js

@@ -1,4 +1,9 @@
 import { logger } from "../../../../utils/logger.js";
+import {
+  countVideoFiles,
+  matchSidecarFiles,
+  TEXT_SUBTITLE_SIDECAR_EXTENSIONS
+} from "../../../../services/sidecar-files.js";
 
 /**
  * Start fetching a source before anyone asks to play it.
@@ -74,10 +79,60 @@ export async function handleApiSourceWarmPost(req, reply, { sourceRegistry, torr
     });
   }
 
+  // The files that carry this episode's OTHER soundtracks and its subtitles.
+  //
+  // Warmed here for the same reason the picture is: none of it depends on the
+  // viewer, and every second of it that happens now is a second they do not
+  // spend waiting later. Without this the first thing to ask for a dub's header
+  // is the playback plan, on the path to the first frame, and the first thing to
+  // ask for a subtitle file is the browser once the film is already running —
+  // which is why a track the container marks default appears after the opening
+  // rather than during it.
+  //
+  // How much of each is fetched follows from what the file IS, not from a size
+  // anyone chose. A text subtitle file is smaller than one piece of this
+  // torrent, so its edges and the whole of it are the same pieces — fetch all of
+  // it. A soundtrack is tens of megabytes and only its header is needed to name
+  // and describe it, so it gets the head and the tail, exactly as the picture
+  // does. The rest of it is fetched when it is played, and nothing here spends
+  // the pool owner's bandwidth on a track nobody chose.
+  let sidecars = 0;
+  if (fileIndex !== null && Array.isArray(torrent.files)) {
+    const matched = matchSidecarFiles({
+      files: torrent.files,
+      videoIndex: fileIndex,
+      torrentName: typeof torrent.name === "string" ? torrent.name : "",
+      videoCount: countVideoFiles(torrent.files)
+    });
+    const warmOne = (file, options) => {
+      sidecars += 1;
+      // Not awaited, like the picture's own edges above: the point of this route
+      // is that the viewer goes on choosing while it happens.
+      Promise.resolve(torrentPool.prefetchFileEdges(torrent, file.fileIndex, options)).catch(
+        (error) => {
+          const message = error instanceof Error ? error.message : String(error);
+          logger.warn(`warm ${sourceKey.slice(0, 8)}: "${file.name}" failed: ${message}`);
+        }
+      );
+    };
+    for (const file of matched.audio) {
+      warmOne(file, { tailBytes: 0 });
+    }
+    for (const file of matched.subtitles) {
+      warmOne(
+        file,
+        TEXT_SUBTITLE_SIDECAR_EXTENSIONS.has(file.extension)
+          ? { headBytes: Math.max(1, file.length), tailBytes: 0 }
+          : { tailBytes: 0 }
+      );
+    }
+  }
+
   logger.info(
     `warm ${sourceKey.slice(0, 8)}: swarm started for "${torrent.name}"` +
-      (edges ? `, fetching the edges of file ${fileIndex}` : ", file not chosen yet")
+      (edges ? `, fetching the edges of file ${fileIndex}` : ", file not chosen yet") +
+      (sidecars > 0 ? ` and of ${sidecars} file(s) beside it` : "")
   );
 
-  return reply.send({ started: true, swarm: true, edges });
+  return reply.send({ started: true, swarm: true, edges, sidecars });
 }

package/routes/api/transcode-sessions/post.js

@@ -113,7 +113,17 @@ export async function handleApiTranscodeSessionsPost(req, reply, { hlsSessionMan
       // only while they run, and a seek leaves a gap with no read at all — the
       // disk sweep caught that gap on 2026-08-06 and deleted the film being
       // watched.
-      acquireSource: () => holdSource({ sourceRegistry, torrentPool, sourceKey, fileIndex })
+      // Takes the file to hold, because a session does not always read the file
+      // it was created for: a release whose dub ships as its own file gives that
+      // soundtrack a session of its own, reading a different index of the same
+      // torrent. Defaults to the picture, which is every other case.
+      acquireSource: (heldFileIndex = fileIndex) =>
+        holdSource({
+          sourceRegistry,
+          torrentPool,
+          sourceKey,
+          fileIndex: Number.isInteger(heldFileIndex) ? heldFileIndex : fileIndex
+        })
     });
     // The index of quality variants, when this session has more than one to
     // offer. Its presence is what tells the browser it can change quality

package/services/audio-inventory.js

@@ -0,0 +1,411 @@
+/**
+ * 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.
+ */
+
+/**
+ * Language codes that carry no information, so cannot confirm a pairing. Same
+ * rule and same reasoning as `subtitle-defaults.js`: ffmpeg prints `und` for a
+ * stream with no language, while Matroska's own default for `Language` is `eng`
+ * — which is also a real answer, so it 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 title is enough; both sides saying
+ * nothing is not agreement, but it is not disagreement either — a file may name
+ * neither, and then this pair simply adds no support to the alignment.
+ *
+ * @param {{ language?: string, title?: string }} banner
+ * @param {{ language?: string, name?: string }} container
+ * @returns {boolean}
+ */
+export function audioPairingHolds(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;
+  }
+  return (
+    (EMPTY_LANGUAGES.has(bannerLanguage) || EMPTY_LANGUAGES.has(containerLanguage)) &&
+    (bannerTitle.length === 0 || containerName.length === 0)
+  );
+}
+
+/**
+ * The banner's audio streams, with what the container declares about each.
+ *
+ * @param {Array<{ index?: number, language?: string, title?: string, isDefault?: boolean, codec?: string }>} bannerTracks
+ * @param {Array<object>} declared - `AudioTrack`s in container order.
+ * @returns {{ tracks: object[], aligned: boolean, reason: string }}
+ */
+export function mergeContainerAudioFlags(bannerTracks, declared) {
+  const banner = Array.isArray(bannerTracks) ? bannerTracks : [];
+  const container = Array.isArray(declared) ? declared : [];
+  const undecided = () => ({
+    // Nothing of the container reading is used, flags included — attributing
+    // them to the wrong track is the failure this guard exists to prevent.
+    tracks: banner.map((track) => ({
+      ...track,
+      declaresDefault: false,
+      isOriginal: false,
+      isCommentary: false,
+      isVisualImpaired: false,
+      // Not "the container says this track is unusable": the container has not
+      // been heard from. A track is offered unless it was read to say otherwise.
+      isEnabled: true,
+      languageBcp47: "",
+      channels: null
+    }))
+  });
+  if (banner.length === 0) {
+    return { tracks: [], aligned: false, reason: "the probe found no audio stream" };
+  }
+  if (container.length === 0) {
+    return { ...undecided(), aligned: false, reason: "the container declares no audio track" };
+  }
+  if (container.length !== banner.length) {
+    return {
+      ...undecided(),
+      aligned: false,
+      reason: `the container declares ${container.length} audio tracks and the probe found ${banner.length}`
+    };
+  }
+  for (const [order, track] of banner.entries()) {
+    if (!audioPairingHolds(track, container[order])) {
+      return {
+        ...undecided(),
+        aligned: false,
+        reason:
+          `audio ${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,
+      // Read from the file itself (RFC 9559 §5.1.4.1). None of these four
+      // reaches ffmpeg's banner, which is where every other field here is from.
+      isOriginal: container[order].isOriginal === true,
+      isCommentary: container[order].isCommentary === true,
+      isVisualImpaired: container[order].isVisualImpaired === true,
+      isEnabled: container[order].isEnabled !== false,
+      // FlagDefault, and whether the file actually WROTE it. Matroska defaults
+      // the flag to 1 and ffmpeg prints the applied default, so the banner
+      // cannot tell "every track marked" from "the file has no opinion".
+      isDefault: container[order].isDefault === true,
+      declaresDefault: container[order].declaresDefault === true,
+      languageBcp47:
+        typeof container[order].languageBcp47 === "string" ? container[order].languageBcp47 : "",
+      channels: Number.isFinite(container[order].channels) ? container[order].channels : null,
+      title:
+        typeof track?.title === "string" && track.title.length > 0
+          ? track.title
+          : (typeof container[order].name === "string" ? container[order].name : "")
+    })),
+    aligned: true,
+    reason: ""
+  };
+}
+
+/**
+ * Codec identifiers as containers write them, against the name ffmpeg prints.
+ *
+ * Needed because the browser decides whether it can play a soundtrack from that
+ * name, and for a sidecar file there is no ffmpeg banner to read it from — the
+ * track came from the container's own table, where Matroska writes `A_AC3` and
+ * MP4 writes `ac-3` for the thing ffmpeg calls `ac3`. Only what a soundtrack can
+ * actually be is listed; an identifier not here is reported as it was written,
+ * which the browser treats as one it does not know and therefore transcodes.
+ */
+const CODEC_NAMES = new Map([
+  ["A_AAC", "aac"],
+  ["A_AC3", "ac3"],
+  ["A_EAC3", "eac3"],
+  ["A_DTS", "dts"],
+  ["A_FLAC", "flac"],
+  ["A_OPUS", "opus"],
+  ["A_VORBIS", "vorbis"],
+  ["A_TRUEHD", "truehd"],
+  ["A_MPEG/L3", "mp3"],
+  ["A_MPEG/L2", "mp2"],
+  ["A_ALAC", "alac"],
+  ["mp4a", "aac"],
+  ["ac-3", "ac3"],
+  ["ec-3", "eac3"],
+  ["alac", "alac"],
+  ["opus", "opus"],
+  ["Opus", "opus"],
+  ["fLaC", "flac"],
+  ["flac", "flac"]
+]);
+
+/**
+ * Extensions of raw elementary streams, against the codec they carry.
+ *
+ * A bare `.ac3` has no track table to read, and its extension is the only thing
+ * that states its codec — which for an elementary stream is exactly what the
+ * extension means.
+ */
+const CODEC_BY_EXTENSION = new Map([
+  [".aac", "aac"],
+  [".ac3", "ac3"],
+  [".eac3", "eac3"],
+  [".dts", "dts"],
+  [".dtshd", "dts"],
+  [".flac", "flac"],
+  [".mp3", "mp3"],
+  [".mp2", "mp2"],
+  [".opus", "opus"],
+  [".ogg", "vorbis"],
+  [".oga", "vorbis"],
+  [".wav", "pcm"],
+  [".thd", "truehd"],
+  [".mlp", "truehd"],
+  [".m4a", "aac"]
+]);
+
+/**
+ * The ffmpeg-side codec name for one track, from whatever the reading gave.
+ *
+ * @param {{ codec?: string, codecId?: string }} track
+ * @param {string} [extension] - The sidecar file's extension, when the track
+ *   came from a file with no readable table.
+ * @returns {string}
+ */
+export function codecNameOf(track, extension = "") {
+  const fromBanner = typeof track?.codec === "string" ? track.codec.trim() : "";
+  if (fromBanner.length > 0) {
+    return fromBanner.toLowerCase();
+  }
+  const codecId = typeof track?.codecId === "string" ? track.codecId.trim() : "";
+  if (codecId.length > 0) {
+    const known = CODEC_NAMES.get(codecId);
+    if (known) {
+      return known;
+    }
+    // Matroska allows a suffix — `A_AAC/MPEG4/LC`, `A_PCM/INT/LIT` — so the
+    // family is what the first two segments say.
+    const family = codecId.split("/").slice(0, 2).join("/");
+    const byFamily = CODEC_NAMES.get(family) ?? CODEC_NAMES.get(codecId.split("/")[0]);
+    if (byFamily) {
+      return byFamily;
+    }
+    if (codecId.startsWith("A_PCM")) {
+      return "pcm";
+    }
+    return codecId.toLowerCase();
+  }
+  return CODEC_BY_EXTENSION.get(extension) ?? "";
+}
+
+/**
+ * @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: 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 ||
+    ""
+  );
+}