@torrent-tv/proxy 2.44.0 → 2.46.0

package/services/subtitle-defaults.js

@@ -0,0 +1,131 @@
+/**
+ * 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}
+ */
+export 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 }}
+ */
+export function mergeContainerSubtitleFlags(bannerTracks, declared) {
+  const banner = Array.isArray(bannerTracks) ? bannerTracks : [];
+  const container = Array.isArray(declared) ? declared : [];
+  const undecided = () => ({
+    tracks: banner.map((track) => ({ ...track, declaresDefault: false }))
+  });
+  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
+    })),
+    aligned: true,
+    reason: ""
+  };
+}

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

@@ -157,6 +157,24 @@ export class WorkerTorrentPool {
     return Array.isArray(answer?.tracks) ? answer.tracks : [];
   }
 
+  /**
+   * What the container itself declares about its subtitle tracks, in its own
+   * order and including the picture-based ones — for lining up against
+   * ffmpeg's own numbering.
+   *
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @returns {Promise<object[]>}
+   */
+  async getDeclaredSubtitleTracks(torrent, fileIndex) {
+    const sourceKey = torrent?.sourceKey;
+    if (!sourceKey) {
+      return [];
+    }
+    const answer = await this.#client.getSubtitleTracks({ sourceKey, fileIndex });
+    return Array.isArray(answer?.declared) ? answer.declared : [];
+  }
+
   /**
    * The cues of one subtitle track that the downloaded clusters already carry.
    *

package/services/torrent-worker/subtitle-cues.js

@@ -106,7 +106,12 @@ async function planFor(torrent, fileIndex, key) {
     return state.plan;
   }
   const file = torrent?.files?.[fileIndex];
-  const empty = { tracks: [], secondsPerTick: 0.001, segmentDataOffset: 0 };
+  // `declared` is what the container itself says about its subtitle tracks, in
+  // its own order. Empty means the container said nothing — which is a real
+  // answer and not a missing one: nothing is then shown unasked. An MP4 has no
+  // element that means "show this subtitle track by default", so it declares
+  // nothing however many tracks it carries.
+  const empty = { tracks: [], declared: [], secondsPerTick: 0.001, segmentDataOffset: 0 };
   if (!file) {
     state.plan = empty;
     return state.plan;
@@ -331,6 +336,25 @@ export async function subtitleTracksOf(torrent, fileIndex, sourceKey) {
   }));
 }
 
+/**
+ * What the container itself says about its subtitle tracks, in its own order
+ * and including the picture-based ones.
+ *
+ * Separate from `subtitleTracksOf`, which lists only what can be turned into
+ * WebVTT and is indexed by position in the subtitle API. This one exists to be
+ * lined up against ffmpeg's `0:s:N` numbering, which counts every subtitle
+ * stream, so leaving the picture ones out would shift it.
+ *
+ * @param {object} torrent
+ * @param {number} fileIndex
+ * @param {string} sourceKey
+ * @returns {Promise<object[]>}
+ */
+export async function declaredSubtitleTracksOf(torrent, fileIndex, sourceKey) {
+  const plan = await planFor(torrent, fileIndex, `${sourceKey}:${fileIndex}`);
+  return plan?.declared ?? [];
+}
+
 /**
  * Forget a file's cues — the torrent is gone, and holding them would keep the
  * text of a film nobody is watching.

package/services/torrent-worker/worker.js

@@ -27,7 +27,7 @@ import { parentPort, workerData } from "node:worker_threads";
 import { createSendStream } from "./channel.js";
 import { createFileClaims } from "./file-claims.js";
 import { readFragments, supplyFiguresFor } from "./piece-reader.js";
-import { cuesHeldFor, subtitleTracksOf } from "./subtitle-cues.js";
+import { cuesHeldFor, declaredSubtitleTracksOf, subtitleTracksOf } from "./subtitle-cues.js";
 import { Command, Event } from "./protocol.js";
 
 // Imported dynamically, and that is load-bearing: static imports are RESOLVED
@@ -359,7 +359,10 @@ async function runCommand(command, params, id) {
 
     case Command.SUBTITLE_TRACKS: {
       const torrent = await requireTorrent(params.sourceKey);
-      return { tracks: await subtitleTracksOf(torrent, params.fileIndex, params.sourceKey) };
+      return {
+        tracks: await subtitleTracksOf(torrent, params.fileIndex, params.sourceKey),
+        declared: await declaredSubtitleTracksOf(torrent, params.fileIndex, params.sourceKey)
+      };
     }
 
     case Command.SUBTITLE_CUES: {

package/test/cuts-follow-published-grid.test.js

@@ -0,0 +1,73 @@
+/**
+ * @file A run cuts where the player was told the cuts are.
+ *
+ * There are two boundary tables. The live one is corrected as produced segments
+ * reveal where the file's cuts truly are; the published one is the snapshot the
+ * playlist text was written from, and a player places every fragment by that
+ * text and nothing else. The cut list handed to ffmpeg used to come from the
+ * live table, so every correction moved the run away from the timeline the
+ * player is reading.
+ *
+ * Field 2026-08-20, `Minions.and.Monsters.1080p.mkv`: the picture's segments
+ * arrived a uniform 2.002 s before the times its playlist named — 119 of 125 of
+ * them — against the 0.5 s hls.js bridges. A fragment that does not land is
+ * fetched again, and on 2026-08-17 two of them were fetched 1908 times each.
+ */
+
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { HlsSessionManager, segmentCutTimesFrom } from "../services/hls-session-manager.js";
+
+/** What the playlist in the player's hands says. */
+const PUBLISHED = [0, 4.004, 8.008, 12.012, 16.016, 20.02];
+/** The same grid after produced segments moved two of its cuts. */
+const CORRECTED = [0, 4.004, 6.006, 12.012, 14.014, 20.02];
+
+/**
+ * A session that has published one grid and since corrected another.
+ *
+ * @returns {{ manager: HlsSessionManager, session: object }}
+ */
+function sessionWithDriftedGrid() {
+  const manager = new HlsSessionManager({
+    enabled: true,
+    ffmpegBin: "ffmpeg",
+    localBindHost: "127.0.0.1",
+    localPort: 9090
+  });
+  const session = {
+    id: "picture",
+    segmentBoundaries: [...CORRECTED],
+    publishedBoundaries: [...PUBLISHED]
+  };
+  return { manager, session };
+}
+
+test("the cut list is the one the playlist was written from", () => {
+  const { manager, session } = sessionWithDriftedGrid();
+  const grid = manager.publishedGridFor(session);
+  assert.deepEqual(grid, PUBLISHED);
+  // Interior cuts of a run starting at #1, rebased on the run's own start
+  // (4.004 s), and stopping before the last entry, which is the file's end.
+  assert.deepEqual(
+    segmentCutTimesFrom(grid, 1).map((time) => Number(time.toFixed(3))),
+    [4.004, 8.008, 12.012]
+  );
+});
+
+test("a corrected grid does not move the cuts of a session already being read", () => {
+  const { manager, session } = sessionWithDriftedGrid();
+  const fromCorrected = segmentCutTimesFrom(session.segmentBoundaries, 1);
+  const fromPublished = segmentCutTimesFrom(manager.publishedGridFor(session), 1);
+  assert.notDeepEqual(fromCorrected, fromPublished);
+  // The gap the field measured: the corrected table would have cut #2 two
+  // seconds early, which is four times what a player bridges.
+  assert.equal(Number((fromPublished[0] - fromCorrected[0]).toFixed(3)), 2.002);
+});
+
+test("a session that published no grid falls back to the live one", () => {
+  const { manager } = sessionWithDriftedGrid();
+  const session = { id: "no-playlist", segmentBoundaries: [...CORRECTED], publishedBoundaries: [] };
+  assert.deepEqual(manager.publishedGridFor(session), CORRECTED);
+});

package/test/decode-cost.test.js

@@ -17,6 +17,7 @@ import assert from "node:assert/strict";
 import { createRequire } from "node:module";
 import { spawn } from "node:child_process";
 import { mkdtemp, rm } from "node:fs/promises";
+import { decodeCostOf, decodeFamilyOf } from "../services/decode-cost-fit.js";
 import os from "node:os";
 import path from "node:path";
 import {
@@ -282,8 +283,22 @@ test("a banner with no bitrate reads as no bitrate, not as zero", () => {
 test("the source's decode figures come off the probe, or not at all", () => {
   assert.deepEqual(sourceDecodeCharacteristics({ width: 1920, height: 1080, fps: 24, bitrateKbps: 8000 }), {
     megapixelsPerSecond: (1920 * 1080 * 24) / 1e6,
-    megabitsPerSecond: 8
+    megabitsPerSecond: 8,
+    // Which measurement of this host applies. Absent on the probe means absent
+    // here — the caller then prices the source as H.264 8-bit, which is what
+    // every source was priced as before the model was fitted per family.
+    codec: "",
+    bitDepth: null
   });
+  assert.deepEqual(
+    sourceDecodeCharacteristics({ width: 1920, height: 1080, fps: 24, bitrateKbps: 8000, codec: "hevc", bitDepth: 10 }),
+    {
+      megapixelsPerSecond: (1920 * 1080 * 24) / 1e6,
+      megabitsPerSecond: 8,
+      codec: "hevc",
+      bitDepth: 10
+    }
+  );
   assert.equal(sourceDecodeCharacteristics({ width: 1920, height: 1080, fps: 24, bitrateKbps: null }), null);
   assert.equal(sourceDecodeCharacteristics(null), null);
 });
@@ -391,3 +406,52 @@ test("the OFFER drops the rungs the host cannot hold, and the master keeps addre
     "the copied height costs no encoder and stays; nothing re-encoded survives that supply"
   );
 });
+
+test("a source is priced by its own codec family when that family was measured", () => {
+  // A model as the startup benchmark now returns it: H.264 terms at the top
+  // level, for a caller that knows nothing about codecs, and the measured
+  // families beside them.
+  const model = {
+    pixelTerm: 0.006, bitrateTerm: 0.012, constantTerm: 0,
+    families: {
+      h264: { pixelTerm: 0.006, bitrateTerm: 0.012, constantTerm: 0 },
+      hevc: { pixelTerm: 0.011, bitrateTerm: 0.020, constantTerm: 0 },
+      hevc10: { pixelTerm: 0.017, bitrateTerm: 0.026, constantTerm: 0 }
+    }
+  };
+  const rates = { megapixelsPerSecond: 50, megabitsPerSecond: 9 };
+  const asH264 = decodeCostOf(model, { ...rates, codec: "h264", bitDepth: 8 });
+  const asHevc = decodeCostOf(model, { ...rates, codec: "hevc", bitDepth: 8 });
+  const asHevc10 = decodeCostOf(model, { ...rates, codec: "hevc", bitDepth: 10 });
+  assert.equal(Number(asH264.toFixed(4)), 0.408);
+  assert.equal(Number(asHevc.toFixed(4)), 0.73);
+  assert.equal(Number(asHevc10.toFixed(4)), 1.084);
+  // The whole point: the same file costs more as HEVC than as H.264, and more
+  // again at ten bits. A single fit could not say that.
+  assert.ok(asHevc > asH264 && asHevc10 > asHevc);
+});
+
+test("a family with no clips is priced as H.264, and a model with no families still works", () => {
+  const withFamilies = {
+    pixelTerm: 0.006, bitrateTerm: 0.012, constantTerm: 0,
+    families: { h264: { pixelTerm: 0.006, bitrateTerm: 0.012, constantTerm: 0 } }
+  };
+  const rates = { megapixelsPerSecond: 50, megabitsPerSecond: 9 };
+  // AV1 has no set of its own yet.
+  assert.equal(
+    decodeCostOf(withFamilies, { ...rates, codec: "av1", bitDepth: 8 }),
+    decodeCostOf(withFamilies, { ...rates, codec: "h264", bitDepth: 8 })
+  );
+  // And a flat model — every model before this release — is unchanged.
+  const flat = { pixelTerm: 0.006, bitrateTerm: 0.012, constantTerm: 0 };
+  assert.equal(decodeCostOf(flat, { ...rates, codec: "hevc", bitDepth: 10 }), 0.408);
+});
+
+test("the family is chosen by codec and depth, and unknown names fall to H.264", () => {
+  assert.equal(decodeFamilyOf({ codec: "hevc", bitDepth: 8 }), "hevc");
+  assert.equal(decodeFamilyOf({ codec: "HEVC", bitDepth: 10 }), "hevc10");
+  assert.equal(decodeFamilyOf({ codec: "h265", bitDepth: 12 }), "hevc10");
+  assert.equal(decodeFamilyOf({ codec: "h264", bitDepth: 10 }), "h264");
+  assert.equal(decodeFamilyOf({ codec: "vc1", bitDepth: null }), "h264");
+  assert.equal(decodeFamilyOf({}), "h264");
+});

package/test/subtitle-defaults.test.js

@@ -0,0 +1,97 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mergeContainerSubtitleFlags, pairingHolds } from "../services/subtitle-defaults.js";
+
+test("a flag the container wrote is carried through, and one it did not is not", () => {
+  const banner = [
+    { index: 0, language: "rus", title: "Forced", isDefault: true },
+    { index: 1, language: "eng", title: "SDH", isDefault: true }
+  ];
+  const declared = [
+    { language: "rus", name: "Forced", isDefault: true, declaresDefault: true },
+    { language: "eng", name: "SDH", isDefault: true, declaresDefault: false }
+  ];
+  const merged = mergeContainerSubtitleFlags(banner, declared);
+  assert.equal(merged.aligned, true);
+  assert.deepEqual(
+    merged.tracks.map((track) => [track.isDefault, track.declaresDefault]),
+    [[true, true], [true, false]]
+  );
+});
+
+test("a file that wrote nothing is reported as having written nothing, though ffmpeg marked everything", () => {
+  // This is the case the banner cannot express: `FlagDefault` defaults to 1, so
+  // ffmpeg prints `(default)` against every track of a file that chose none.
+  const banner = [
+    { index: 0, language: "rus", title: "", isDefault: true },
+    { index: 1, language: "eng", title: "", isDefault: true }
+  ];
+  const declared = [
+    { language: "rus", name: "", isDefault: true, declaresDefault: false },
+    { language: "eng", name: "", isDefault: true, declaresDefault: false }
+  ];
+  const merged = mergeContainerSubtitleFlags(banner, declared);
+  assert.equal(merged.aligned, true);
+  assert.deepEqual(merged.tracks.map((track) => track.declaresDefault), [false, false]);
+});
+
+test("the container's own answer overrides the banner's, in both directions", () => {
+  const banner = [
+    { index: 0, language: "rus", title: "a", isDefault: true },
+    { index: 1, language: "eng", title: "b", isDefault: false }
+  ];
+  const declared = [
+    { language: "rus", name: "a", isDefault: false, declaresDefault: true },
+    { language: "eng", name: "b", isDefault: true, declaresDefault: true }
+  ];
+  const merged = mergeContainerSubtitleFlags(banner, declared);
+  assert.deepEqual(merged.tracks.map((track) => track.isDefault), [false, true]);
+});
+
+test("a count that differs means the two readings are not the same list", () => {
+  // The container declares a picture track the probe did not report; position
+  // is then not the correspondence and nothing may be read across.
+  const banner = [{ index: 0, language: "rus", title: "", isDefault: true }];
+  const declared = [
+    { language: "rus", name: "", isDefault: false, declaresDefault: true },
+    { language: "eng", name: "", isDefault: true, declaresDefault: true }
+  ];
+  const merged = mergeContainerSubtitleFlags(banner, declared);
+  assert.equal(merged.aligned, false);
+  assert.match(merged.reason, /declares 2 subtitle tracks and the probe found 1/);
+  assert.deepEqual(merged.tracks.map((track) => [track.isDefault, track.declaresDefault]), [[true, false]]);
+});
+
+test("a pair agreeing on neither language nor name refuses the whole alignment", () => {
+  const banner = [
+    { index: 0, language: "rus", title: "", isDefault: true },
+    { index: 1, language: "eng", title: "", isDefault: true }
+  ];
+  const declared = [
+    { language: "eng", name: "", isDefault: true, declaresDefault: true },
+    { language: "rus", name: "", isDefault: false, declaresDefault: true }
+  ];
+  const merged = mergeContainerSubtitleFlags(banner, declared);
+  assert.equal(merged.aligned, false);
+  assert.deepEqual(merged.tracks.map((track) => track.declaresDefault), [false, false]);
+});
+
+test("a container that declares nothing leaves the banner alone", () => {
+  const banner = [{ index: 0, language: "rus", title: "", isDefault: true }];
+  const merged = mergeContainerSubtitleFlags(banner, []);
+  assert.equal(merged.aligned, false);
+  assert.equal(merged.tracks[0].isDefault, true);
+  assert.equal(merged.tracks[0].declaresDefault, false);
+});
+
+test("a name confirms a pairing when the languages are unstated", () => {
+  assert.equal(pairingHolds({ language: "und", title: "Forced" }, { language: "", name: "Forced" }), true);
+});
+
+test("two tracks that say nothing about themselves do not break the alignment", () => {
+  assert.equal(pairingHolds({ language: "und", title: "" }, { language: "", name: "" }), true);
+});
+
+test("a stated language that differs is a disagreement", () => {
+  assert.equal(pairingHolds({ language: "rus", title: "" }, { language: "eng", name: "" }), false);
+});