@torrent-tv/proxy 2.64.9 → 2.66.0

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 2.66.0
+
+- **New**: A soundtrack that ships beside the picture is fetched WHOLE once the swarm has capacity to spare, so a later switch to it does not wait. It is a twentieth of the picture — 30 MB against 566 MB on the field torrent — and having it on disk is the difference between an instant switch and one that pays for its own first pieces. The moment it starts is not a guess about the swarm: it is when the encoder is already as far ahead of the viewer as `--lookahead` lets it get, which is the cushion figure the session already measures and prints. Once per file, and only for a soundtrack in a file of its own.
+- **Chore**: That fetch is a bounded READ of the file's length, deliberately not `file.select()`. Selecting a whole file alongside the readers' own moving windows is the mistake `#syncSelections` in `torrent-pool.js` was written against — a claim covering everything always outranked the window, and a seek to 89.1 % of a 4.7 GB film waited 93 s while the swarm fetched 2.47 GB in file order. The comment there records it; this goes through the same path the edge warm-up uses.
+
+## 2.65.0
+
+- **New**: A soundtrack that ships as its own file beside the picture is offered like any other. Releases commonly put a dub in `Rus Sound/<name>.mka` and subtitles in `Sub/[team]/<name>.ass`; until now the video played with its original sound and nothing said the rest of the release existed. The pairing is by name — equal base names, or a shared release hash — and a torrent holding exactly one picture takes every sidecar beside it, since there is nothing else they could belong to. A torrent with several episodes never relaxes that: a wrong pairing would put the sound of one episode over the picture of another, and nothing downstream could notice.
+- **New**: No new container class was needed for it, and that is the point. A `.mka` IS Matroska: `ContainerFactory` sniffs it, `MatroskaContainer` reads its `TrackEntry` list, and out comes an `AudioTrack` with its language, title, channel count and flags — the same reader that serves the picture. "External" is not a kind of track; it is the answer to WHERE a track's bytes are, which is torrent knowledge and now lives in `services/sidecar-files.js` (which file goes with which) and `services/audio-inventory.js` (one numbered list), both pure and both application-layer. `tracks/ExternalSubtitleFile.js` asserted the opposite — it did not extend `ContainerTrack`, duplicated four of its fields and was imported by nothing — and is deleted rather than extended.
+- **New**: The audio menu is built from the container's own track table where one can be read, with ffmpeg's `-i` banner as the fallback. `FlagOriginal` (0x55AE), `FlagCommentary` (0x55AF), `FlagVisualImpaired` (0x55AC), `FlagEnabled` (0xB9) and `LanguageBCP47` appear nowhere in that banner, so a director's commentary and the film itself were indistinguishable in the menu — roadmap item 58, points 1-3. The two readings are lined up by position and the pairing is CHECKED, exactly as `subtitle-defaults.js` checks its own: a differing count, or one pair agreeing on neither language nor title, drops the container reading whole rather than attributing a flag to the wrong track. `0:a:N` is what the encoder is handed, so a wrong flag is worse than a missing one.
+- **New**: One flat number spans the picture's own tracks and the files beside it, and one place resolves it. The browser's menu, the `audioTrackIndex` of a session request and the `a/<n>/` address of a rendition all mean the same number; `#resolveAudioSource` turns it into a file index and a `0:a:N` inside that file. Embedded tracks keep the numbers they have always had, so a session created against a plan cached by an older build still means what it meant.
+- **New**: A sidecar soundtrack chosen by a browser that understands rendition groups costs no second input at all — the rendition reads that file as its only input, and the player joins picture and sound, which is what a rendition group is for. A browser without them gets the two muxed by ffmpeg from two inputs, with the seek applied to each and `-itsoffset` stating the soundtrack's timestamps on the picture's timeline. Both files begin at their own container start time and those need not be equal; the difference is measured from the file rather than assumed to be zero, which is what keeps the sound from sitting at a fixed offset for the whole film.
+- **Fix**: A session now holds a claim on every file it reads. A rendition reading a sidecar claimed only the picture, and the disk sweep deletes what nobody holds — the failure that deleted a film being watched on 2026-08-06, one file over.
+- **Fix**: `declaredTracks` no longer answers from the picture's probe alone. A release that ships its dub separately often ships the picture with no sound at all, so the probe said there was no audio while the output plainly carried some — leaving the header check expecting one track where two arrive, and telling the browser its sound had been lost.
+- **New**: `Command.CONTAINER_TRACKS` reads any file's own track table on the thread that owns the torrent, fetching its head first — a sidecar has usually had nothing downloaded when it is first asked about. The picture's tracks come back the same way, so there is one command rather than two.
+- **New**: The warm-up that runs when a viewer picks a file now warms what lies beside it, for the same reason it warms the picture: none of it depends on the viewer, and every second of it spent now is a second they do not spend waiting later. How much of each follows from what the file IS, not from a size anyone chose — a text subtitle file is smaller than one piece of the torrent, so its edges and the whole of it are the same pieces and all of it is fetched; a soundtrack is tens of megabytes and only its header is needed to name it, so it gets head and tail like the picture. Without this the first thing to ask for a dub's header was the playback plan, on the path to the first frame.
+- **Fix**: The plan waits at most 3 s for a sidecar's header instead of up to two minutes. Reading one goes through the worker, which prefetches the file's edges (60 s) and then reads them (60 s), and neither was bounded from the plan's side — the route's own `maxWaitMs` covers the codec probe loop and nothing after it. A sidecar is a file of the torrent nobody has asked for yet, and on this torrent 256 KB of header means one whole 8 MiB piece. What the timeout costs is small and deliberate: the track is still offered, still numbered and still playable, only without the language and flags its header would have given — and the language the viewer sees comes from the folder the release put it in, which is in the file list and costs no bytes at all.
+- **Fix**: The media-info probe no longer spends its whole 8 s timeout on a file with no picture. It bails early when it has both a duration and a video stream line; a soundtrack file never prints the second, so it waited out the timeout every time — on the path where a viewer is changing track and the browser refuses a switch that is not ready in time. `Duration:` carries the start time being asked for, and it is the last thing such a file has to say about itself.
+- **Fix**: A soundtrack session sizes its read window from the file it READS. Sized from the picture, whose byte rate is twenty times higher over the same duration, the window bought twenty times the seconds it was meant to represent and the piece store held it.
+
 ## 2.64.9
 
 - **New**: The memory line says the SHAPE of the anonymous memory, not only its size — `mappings=[heap 40MB, 47 anon >=2MB = 388MB (largest 64MB), 812 anon <2MB = 231MB, files 31MB]`, read per mapping from `/proc/self/smaps`. The 700 MB that grew in the field on 2026-08-31 is none of the JavaScript heaps, none of the piece store and none of ffmpeg, and the three shapes it could have are three different diagnoses: one growing `[heap]` is the allocator keeping what we free, with no `malloc_trim` on musl to ask for it back; many large anonymous mappings are piece buffers, and whether their count tracks what the store says it holds decides whether anything is retaining them; many medium ones are the allocator's own arenas. Mappings with no resident pages are left out — those are V8's address-space reservations, tens of gigabytes of them, and counting them would drown the reading.

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.9",
+  "version": "2.66.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/server.js

@@ -192,7 +192,30 @@ export async function startProxyServer({
     getCachedMediaInfo: (params) => playbackPlanner.getCachedMediaInfo(params),
     // The file's audio tracks, for the master playlist's rendition group. Already
     // probed for the browser's audio menu; read from there rather than probed again.
-    getCachedAudioTracks: (params) => playbackPlanner.getCachedAudioTracks(params)
+    getCachedAudioTracks: (params) => playbackPlanner.getCachedAudioTracks(params),
+    // 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
+    // spare. A bounded read of the file's whole length, NOT `file.select()`:
+    // selecting a file alongside the readers' own windows is what made a seek
+    // wait 93 s while the swarm fetched 2.47 GB in file order (see
+    // `#syncSelections` in `torrent-pool.js`).
+    fetchWholeFile: async ({ sourceKey, fileIndex }) => {
+      const record = sourceRegistry.get(sourceKey);
+      if (!record) {
+        return;
+      }
+      const torrent = await torrentPool.getTorrent(record.sourceType, record.source);
+      const file = torrent?.files?.[fileIndex];
+      if (!file || !Number.isFinite(file.length) || file.length <= 0) {
+        return;
+      }
+      await torrentPool.prefetchFileEdges(torrent, fileIndex, {
+        headBytes: file.length,
+        tailBytes: 0,
+        timeoutMs: 600_000
+      });
+    }
   });
   const playbackPlanner = createPlaybackPlanner({
     ffmpegBin,

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 ||
+    ""
+  );
+}