@torrent-tv/proxy 2.64.9 → 2.66.0

package/services/torrent-worker/container-tracks.js

@@ -0,0 +1,243 @@
+/**
+ * The tracks a file declares, read from the file itself on the thread that owns
+ * the torrent.
+ *
+ * This exists because the container layer (`services/container/`) reads bytes,
+ * and the bytes live here: the torrent client runs on this worker thread, so the
+ * main thread cannot open a read stream on one of its files. The main thread
+ * asks over the channel (`Command.CONTAINER_TRACKS`) and gets plain objects
+ * back, because a class instance does not survive the boundary as a class.
+ *
+ * It reads whatever container the file is — the same `ContainerFactory` that
+ * serves the picture serves a `.mka` beside it, since a `.mka` IS Matroska and
+ * differs only in having no video track. That is the whole reason no new class
+ * was needed for a soundtrack shipped as its own file.
+ *
+ * Unlike the subtitle walk, the reads here DO wait on the swarm. A sidecar file
+ * has usually had nothing downloaded at all when this is first asked, and its
+ * header is a few hundred kilobytes; the alternative is offering the viewer a
+ * soundtrack with nothing known about it.
+ */
+
+import { containerOrchestrator } from "../orchestrators/ContainerOrchestrator.js";
+import { logger } from "../../utils/logger.js";
+
+/**
+ * How long one range read may take before it is given up.
+ *
+ * Not a measurement and nothing is derived from it: it is the point past which a
+ * read of a file nobody is playing is presumed lost, so that one stream which
+ * never ends cannot hold the answer — and with it the viewer's audio menu — for
+ * the rest of the session.
+ */
+const READ_ABANDON_MS = 60_000;
+
+/** Bytes of the head a container's track table lives in. */
+const HEAD_BYTES = 256 * 1024;
+
+/**
+ * Tracks already read, by `sourceKey:fileIndex`. Only a non-empty reading is
+ * kept: an empty one usually means the header has not arrived yet, and caching
+ * that would hide the file's tracks for the life of the process.
+ *
+ * @type {Map<string, object[]>}
+ */
+const byFile = new Map();
+
+/** @type {Map<string, Promise<object[]>>} */
+const inFlight = new Map();
+
+/**
+ * Read a byte range of a file, fetching what is missing.
+ *
+ * @param {object} file
+ * @param {number} start
+ * @param {number} end - Inclusive.
+ * @returns {Promise<Buffer | null>}
+ */
+function readFetching(file, start, end) {
+  return new Promise((resolve) => {
+    const chunks = [];
+    let stream;
+    try {
+      stream = file.createReadStream({ start, end });
+    } catch {
+      resolve(null);
+      return;
+    }
+    let settled = false;
+    /** @type {ReturnType<typeof setTimeout> | null} */
+    let abandon = null;
+    const settle = (value) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      if (abandon !== null) {
+        clearTimeout(abandon);
+      }
+      if (value === null) {
+        stream.destroy?.();
+      }
+      resolve(value);
+    };
+    abandon = setTimeout(() => {
+      logger.info(
+        `container-tracks: a read of ${start}-${end} in "${String(file.name).slice(0, 40)}" ` +
+        `did not finish in ${READ_ABANDON_MS / 1000}s and was given up`
+      );
+      settle(null);
+    }, READ_ABANDON_MS);
+    abandon.unref?.();
+    stream.on("data", (chunk) => chunks.push(chunk));
+    stream.on("end", () => settle(Buffer.concat(chunks)));
+    stream.on("error", () => settle(null));
+  });
+}
+
+/**
+ * One track as it crosses the thread boundary: the fields the inventory and the
+ * master playlist read, and nothing that would not survive being cloned.
+ *
+ * @param {import("../tracks/index.js").ContainerTrack} track
+ * @returns {object}
+ */
+function plainTrack(track) {
+  return {
+    type: track.type,
+    trackNumber: track.trackNumber,
+    declaredIndex: track.declaredIndex,
+    codecId: track.codecId,
+    language: track.resolvedLanguage(),
+    languageBcp47: track.languageBcp47,
+    name: track.name,
+    isEnabled: track.isEnabled,
+    isDefault: track.isDefault,
+    declaresDefault: track.declaresDefault,
+    // Audio-only, per RFC 9559 — absent on other types, and read as false there
+    // rather than being placed on the base track where they do not belong.
+    isOriginal: track.isOriginal === true,
+    isCommentary: track.isCommentary === true,
+    isVisualImpaired: track.isVisualImpaired === true,
+    channels: Number.isFinite(track.channels) ? track.channels : null,
+    samplingFrequency: Number.isFinite(track.samplingFrequency) ? track.samplingFrequency : null
+  };
+}
+
+/**
+ * Every track one file declares, in container order.
+ *
+ * @param {object} torrent
+ * @param {number} fileIndex
+ * @param {string} sourceKey
+ * @param {{ prefetchEdges?: () => Promise<unknown> }} [options]
+ * @returns {Promise<object[]>}
+ */
+export async function containerTracksOf(torrent, fileIndex, sourceKey, options = {}) {
+  const key = `${sourceKey}:${fileIndex}`;
+  const held = byFile.get(key);
+  if (Array.isArray(held)) {
+    return held;
+  }
+  const running = inFlight.get(key);
+  if (running) {
+    return running;
+  }
+  const work = readTracks(torrent, fileIndex, sourceKey, options)
+    .then((tracks) => {
+      if (tracks.length > 0) {
+        byFile.set(key, tracks);
+      }
+      return tracks;
+    })
+    .finally(() => {
+      inFlight.delete(key);
+    });
+  inFlight.set(key, work);
+  return work;
+}
+
+/**
+ * @param {object} torrent
+ * @param {number} fileIndex
+ * @param {string} sourceKey
+ * @param {{ prefetchEdges?: () => Promise<unknown> }} options
+ * @returns {Promise<object[]>}
+ */
+async function readTracks(torrent, fileIndex, sourceKey, options) {
+  const file = torrent?.files?.[fileIndex];
+  if (!file || !Number.isFinite(file.length) || file.length <= 0) {
+    return [];
+  }
+  if (typeof options.prefetchEdges === "function") {
+    try {
+      await options.prefetchEdges();
+    } catch {
+      // A prefetch that failed is not a reason to skip the read: the read
+      // fetches what it needs itself, only more slowly.
+    }
+  }
+  const readRange = async (start, end) =>
+    readFetching(file, start, Math.min(end, file.length - 1));
+  try {
+    const tracks = await containerOrchestrator.getTracks({
+      sourceKey,
+      fileIndex,
+      readRange,
+      fileSize: file.length,
+      label: String(file.name ?? "")
+    });
+    const plain = tracks.map(plainTrack);
+    if (plain.length > 0) {
+      logger.info(
+        `container-tracks: "${String(file.name).slice(0, 40)}" declares ` +
+        `${plain.filter((track) => track.type === "video").length} video, ` +
+        `${plain.filter((track) => track.type === "audio").length} audio, ` +
+        `${plain.filter((track) => track.type === "subtitle").length} subtitle track(s)`
+      );
+    }
+    return plain;
+  } catch (error) {
+    logger.warn(
+      `container-tracks: "${String(file.name).slice(0, 40)}" could not be read: ${error?.message ?? error}`
+    );
+    return [];
+  }
+}
+
+/**
+ * The audio tracks of one file, in the order ffmpeg numbers them `0:a:N`.
+ *
+ * @param {object} torrent
+ * @param {number} fileIndex
+ * @param {string} sourceKey
+ * @param {{ prefetchEdges?: () => Promise<unknown> }} [options]
+ * @returns {Promise<object[]>}
+ */
+export async function containerAudioTracksOf(torrent, fileIndex, sourceKey, options = {}) {
+  const tracks = await containerTracksOf(torrent, fileIndex, sourceKey, options);
+  return tracks
+    .filter((track) => track.type === "audio")
+    .sort((left, right) => left.declaredIndex - right.declaredIndex);
+}
+
+/** Bytes of a file's head worth fetching before its track table is read. */
+export const CONTAINER_HEAD_BYTES = HEAD_BYTES;
+
+/**
+ * Forget one file's tracks, or every file of a source.
+ *
+ * @param {string} sourceKey
+ * @param {number} [fileIndex]
+ */
+export function forgetContainerTracks(sourceKey, fileIndex) {
+  if (fileIndex === undefined) {
+    for (const key of [...byFile.keys()]) {
+      if (key.startsWith(`${sourceKey}:`)) {
+        byFile.delete(key);
+      }
+    }
+    return;
+  }
+  byFile.delete(`${sourceKey}:${fileIndex}`);
+}

package/services/torrent-worker/pool-adapter.js

@@ -161,6 +161,44 @@ export class WorkerTorrentPool {
     return Array.isArray(answer?.declared) ? answer.declared : [];
   }
 
+  /**
+   * Every track one file declares, read from its own header by the container
+   * layer.
+   *
+   * The audio menu is built from ffmpeg's `-i` banner, which carries neither
+   * `FlagOriginal`, `FlagCommentary`, `FlagVisualImpaired`, `FlagEnabled` nor
+   * `LanguageBCP47` — so without this a director's commentary and the film
+   * itself are indistinguishable in it. Also how a soundtrack shipped as its own
+   * file is read: a `.mka` is Matroska and the same reader serves it.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @returns {Promise<object[]>}
+   */
+  async getContainerTracks(torrent, fileIndex) {
+    const sourceKey = torrent?.sourceKey;
+    if (!sourceKey) {
+      return [];
+    }
+    const answer = await this.#client.getContainerTracks({ sourceKey, fileIndex });
+    return Array.isArray(answer?.tracks) ? answer.tracks : [];
+  }
+
+  /**
+   * The audio tracks one file declares, in the order ffmpeg numbers them
+   * `0:a:N`.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @returns {Promise<object[]>}
+   */
+  async getDeclaredAudioTracks(torrent, fileIndex) {
+    const tracks = await this.getContainerTracks(torrent, fileIndex);
+    return tracks
+      .filter((track) => track?.type === "audio")
+      .sort((left, right) => (left.declaredIndex ?? 0) - (right.declaredIndex ?? 0));
+  }
+
   /**
    * The cues of one subtitle track that the downloaded clusters already carry.
    *

package/services/torrent-worker/protocol.js

@@ -67,6 +67,14 @@ export const Command = {
   PREFETCH_EDGES: "prefetch-edges",
   /** The text subtitle tracks a file carries, for the viewer's menu. */
   SUBTITLE_TRACKS: "subtitle-tracks",
+  /**
+   * Every track a file declares, read from its own header by the container
+   * layer. Answers what ffmpeg's `-i` banner cannot: FlagOriginal,
+   * FlagCommentary, FlagVisualImpaired, FlagEnabled and LanguageBCP47 appear
+   * nowhere in it. Asked of the picture AND of a soundtrack shipped as its own
+   * file beside it, which is the same question about a different file.
+   */
+  CONTAINER_TRACKS: "container-tracks",
   /** Cues of one subtitle track, from the clusters already downloaded. */
   SUBTITLE_CUES: "subtitle-cues",
   /** Shut the client down, optionally deleting downloaded data. */

package/services/torrent-worker/worker.js

@@ -28,6 +28,7 @@ import { createSendStream } from "./channel.js";
 import { createFileClaims } from "./file-claims.js";
 import { readFragments, supplyFiguresFor } from "./piece-reader.js";
 import { cuesHeldFor, declaredSubtitleTracksOf, subtitleTracksOf, warmSubtitleCues } from "./subtitle-cues.js";
+import { CONTAINER_HEAD_BYTES, containerTracksOf } from "./container-tracks.js";
 import { Command, Event } from "./protocol.js";
 import { startMemoryReport, WORKER_MEMORY_SAMPLE_MS } from "../memory-report.js";
 
@@ -370,6 +371,24 @@ async function runCommand(command, params, id) {
       };
     }
 
+    case Command.CONTAINER_TRACKS: {
+      const torrent = await requireTorrent(params.sourceKey);
+      return {
+        tracks: await containerTracksOf(torrent, params.fileIndex, params.sourceKey, {
+          // The header of a file nobody is playing has usually not arrived at
+          // all — a sidecar soundtrack is asked about before anyone has chosen
+          // it. Its head is a few hundred kilobytes, and without them there is
+          // nothing to read.
+          prefetchEdges: () =>
+            pool.prefetchFileEdges(torrent, params.fileIndex, {
+              headBytes: CONTAINER_HEAD_BYTES,
+              tailBytes: 0,
+              timeoutMs: 60_000
+            })
+        })
+      };
+    }
+
     case Command.SUBTITLE_CUES: {
       const torrent = await requireTorrent(params.sourceKey);
       const held = await cuesHeldFor(torrent, params.fileIndex, params.sourceKey, params.trackNumber);

package/services/tracks/index.js

@@ -4,4 +4,10 @@ export { AudioTrack } from "./AudioTrack.js";
 export { SubtitleTrack } from "./SubtitleTrack.js";
 export { TextSubtitleTrack, TEXT_CODECS_MATROSKA, TEXT_FORMATS_MP4 } from "./TextSubtitleTrack.js";
 export { ImageSubtitleTrack } from "./ImageSubtitleTrack.js";
-export { ExternalSubtitleFile } from "./ExternalSubtitleFile.js";
+// There is deliberately no class for a track that lives in a file of its own.
+// `<name>.mka` is a Matroska container holding an `AudioTrack`, and
+// `MatroskaContainer` reads it exactly as it reads the picture's — so "external"
+// is not a KIND of track, only the answer to where a track's bytes are. That
+// answer belongs to the application layer, which knows about torrents; this one
+// describes what a container declares and must not. `ExternalSubtitleFile`,
+// which asserted the opposite, was never used by anything and is gone.

package/test/audio-inventory.test.js

@@ -0,0 +1,177 @@
+/**
+ * @file One numbered list of soundtracks, from two readings of the same file.
+ *
+ * Two things are being pinned here, and each has cost a real failure elsewhere
+ * in this project:
+ *
+ * 1. **The alignment guard.** The container reading is used ONLY when it can be
+ *    lined up with ffmpeg's own numbering, because `0:a:N` is what the encoder
+ *    is handed — a flag attributed to the wrong track is worse than a missing
+ *    one. Same discipline as `subtitle-defaults.js`, for the same reason.
+ * 2. **The flat numbering.** The browser's menu, the `audioTrackIndex` on a
+ *    session request and the `a/<n>/` address of a rendition are one number.
+ *    Embedded tracks must keep the numbers they have always had, so that a
+ *    session created against an older cached plan means the same thing.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  audioPairingHolds,
+  audioRenditionName,
+  buildAudioInventory,
+  codecNameOf,
+  mergeContainerAudioFlags,
+  resolveAudioIndex
+} from "../services/audio-inventory.js";
+
+test("a pair agreeing on language is accepted", () => {
+  assert.equal(audioPairingHolds({ language: "jpn" }, { language: "jpn" }), true);
+});
+
+test("a pair disagreeing on language is refused", () => {
+  assert.equal(audioPairingHolds({ language: "jpn" }, { language: "rus" }), false);
+});
+
+test("two tracks that say nothing about themselves do not break the alignment", () => {
+  assert.equal(audioPairingHolds({ language: "und", title: "" }, { language: "", name: "" }), true);
+});
+
+test("the container's own flags reach the merged track", () => {
+  const merged = mergeContainerAudioFlags(
+    [
+      { index: 0, language: "eng", title: "", isDefault: true, codec: "aac" },
+      { index: 1, language: "eng", title: "Director", isDefault: true, codec: "ac3" }
+    ],
+    [
+      { language: "eng", name: "", isOriginal: true, isDefault: true, declaresDefault: true, channels: 6 },
+      { language: "eng", name: "Director", isCommentary: true, isDefault: false, declaresDefault: true, channels: 2 }
+    ]
+  );
+  assert.equal(merged.aligned, true);
+  assert.equal(merged.tracks[0].isOriginal, true);
+  assert.equal(merged.tracks[0].channels, 6);
+  assert.equal(merged.tracks[1].isCommentary, true);
+  // Matroska defaults FlagDefault to 1 and ffmpeg prints the applied default, so
+  // the banner said both tracks were default. The container says otherwise.
+  assert.equal(merged.tracks[1].isDefault, false);
+});
+
+test("a count that differs drops the container reading whole", () => {
+  const merged = mergeContainerAudioFlags(
+    [{ index: 0, language: "eng", isDefault: true }],
+    [{ language: "eng" }, { language: "rus" }]
+  );
+  assert.equal(merged.aligned, false);
+  assert.match(merged.reason, /declares 2 audio tracks and the probe found 1/);
+  // Nothing of it is used — not even the flags that happened to line up.
+  assert.equal(merged.tracks[0].isCommentary, false);
+  assert.equal(merged.tracks[0].declaresDefault, false);
+});
+
+test("one pair that agrees on neither language nor title drops it too", () => {
+  const merged = mergeContainerAudioFlags(
+    [{ index: 0, language: "jpn", title: "" }, { index: 1, language: "rus", title: "" }],
+    [{ language: "jpn", name: "" }, { language: "eng", name: "" }]
+  );
+  assert.equal(merged.aligned, false);
+  assert.match(merged.reason, /audio 1 is/);
+});
+
+test("embedded tracks keep the numbers they have always had, sidecars follow", () => {
+  const inventory = buildAudioInventory({
+    embedded: [
+      { language: "jpn", codec: "aac", isDefault: true },
+      { language: "eng", codec: "ac3", title: "Commentary", isCommentary: true }
+    ],
+    videoFileIndex: 24,
+    sidecars: [
+      {
+        file: { fileIndex: 12, name: "ep.mka", folders: ["Rus Sound"], extension: ".mka" },
+        tracks: [{ language: "rus", codecId: "A_AC3", channels: 6 }]
+      }
+    ]
+  });
+
+  assert.deepEqual(inventory.map((entry) => entry.index), [0, 1, 2]);
+  assert.deepEqual(inventory.map((entry) => entry.fileIndex), [24, 24, 12]);
+  assert.deepEqual(inventory.map((entry) => entry.sourceTrackIndex), [0, 1, 0]);
+  assert.deepEqual(inventory.map((entry) => entry.kind), ["embedded", "embedded", "sidecar"]);
+  assert.equal(inventory[2].codec, "ac3");
+  assert.deepEqual(inventory[2].folders, ["Rus Sound"]);
+  assert.equal(inventory[2].fileName, "ep.mka");
+});
+
+test("a sidecar whose table could not be read is still offered, as one track", () => {
+  const inventory = buildAudioInventory({
+    embedded: [{ language: "eng", codec: "aac" }],
+    videoFileIndex: 0,
+    sidecars: [{ file: { fileIndex: 1, name: "dub.ac3", folders: [], extension: ".ac3" }, tracks: [] }]
+  });
+  assert.equal(inventory.length, 2);
+  assert.equal(inventory[1].sourceTrackIndex, 0);
+  // The extension of a bare elementary stream IS its codec.
+  assert.equal(inventory[1].codec, "ac3");
+});
+
+test("a sidecar carrying two tracks contributes both", () => {
+  const inventory = buildAudioInventory({
+    embedded: [],
+    videoFileIndex: 0,
+    sidecars: [
+      {
+        file: { fileIndex: 3, name: "dubs.mka", folders: [], extension: ".mka" },
+        tracks: [{ language: "rus" }, { language: "ukr" }]
+      }
+    ]
+  });
+  assert.deepEqual(inventory.map((entry) => [entry.index, entry.sourceTrackIndex]), [[0, 0], [1, 1]]);
+});
+
+test("the flat number resolves back to a file and a track inside it", () => {
+  const inventory = buildAudioInventory({
+    embedded: [{ language: "jpn" }],
+    videoFileIndex: 24,
+    sidecars: [{ file: { fileIndex: 12, name: "ep.mka", folders: [], extension: ".mka" }, tracks: [{}] }]
+  });
+  assert.equal(resolveAudioIndex(inventory, 1).fileIndex, 12);
+  assert.equal(resolveAudioIndex(inventory, 1).sourceTrackIndex, 0);
+  assert.equal(resolveAudioIndex(inventory, 9), null);
+});
+
+test("codec identifiers are translated to the names the browser judges by", () => {
+  assert.equal(codecNameOf({ codec: "AAC" }), "aac");
+  assert.equal(codecNameOf({ codecId: "A_AC3" }), "ac3");
+  assert.equal(codecNameOf({ codecId: "A_AAC/MPEG4/LC" }), "aac");
+  assert.equal(codecNameOf({ codecId: "A_PCM/INT/LIT" }), "pcm");
+  assert.equal(codecNameOf({ codecId: "ec-3" }), "eac3");
+  assert.equal(codecNameOf({}, ".dts"), "dts");
+  assert.equal(codecNameOf({}, ".unknown"), "");
+});
+
+test("a rendition is named by what the file says, and two never share a name", () => {
+  const inventory = buildAudioInventory({
+    embedded: [{ language: "jpn" }],
+    videoFileIndex: 0,
+    sidecars: [
+      { file: { fileIndex: 1, name: "a.mka", folders: ["Rus Sound"], extension: ".mka" }, tracks: [{}] },
+      { file: { fileIndex: 2, name: "b.mka", folders: ["Rus Sound"], extension: ".mka" }, tracks: [{}] }
+    ]
+  });
+  assert.equal(audioRenditionName(inventory[0], inventory), "jpn");
+  // Both sidecars sit in the same folder and neither names itself, so the names
+  // would collide — and hls.js groups renditions by name.
+  assert.notEqual(
+    audioRenditionName(inventory[1], inventory),
+    audioRenditionName(inventory[2], inventory)
+  );
+});
+
+test("a commentary says so in its rendition name", () => {
+  const inventory = buildAudioInventory({
+    embedded: [{ language: "eng" }, { language: "eng", title: "Director", isCommentary: true }],
+    videoFileIndex: 0,
+    sidecars: []
+  });
+  assert.match(audioRenditionName(inventory[1], inventory), /commentary/);
+});