@torrent-tv/proxy 2.74.0 → 2.75.0

package/services/container/Container.js

@@ -91,10 +91,257 @@ export class Container {
    * @param {object[]} declared - This container's own subtitle tracks, in its order.
    * @returns {object[]}
    */
+    /**
+   * The picture's facts, from the two readings that state them.
+   *
+   * Audio and subtitles have had this since the flags were first read from the
+   * file; video never did. Every figure the encode is planned from — the size,
+   * the frame rate, whether it is HDR, how many bits a sample carries — was
+   * taken from ffmpeg's `-i` banner alone, and the `VideoTrack` the container
+   * declares was read and then used for nothing but a line in the log.
+   *
+   * Which reading wins is decided per field by what each one IS, and the rule
+   * is the one `readMediaInfo` already states: a fact the container DECLARES is
+   * read from the container; a fact only the media has is measured from the
+   * media.
+   *
+   * - the coded size and the frame rate are the BANNER's. Both are declared by
+   *   the container as well, but what the encoder receives is what the decoder
+   *   produced, and the ladder and the scale filter have to be sized to that. A
+   *   container that declares something else is mis-declaring, and using its
+   *   numbers would size the encode to a picture that never arrives;
+   * - the bit depth and the HDR signalling are the CONTAINER's where it states
+   *   them. They are not properties of the decoded frames at all — they are the
+   *   file saying how its samples are to be read — and ffmpeg prints them only
+   *   as a side effect of naming a pixel format. HDR is not compared for
+   *   disagreement: both sides give a boolean, and a boolean cannot say "I did
+   *   not look";
+   * - the display size is the container's alone; the banner has no such field.
+   *
+   * Where only one side states a field, that side answers whatever the rule
+   * would have preferred. Where both state it and they DISAGREE, the
+   * disagreement is reported: it is a fact about the file, and until now
+   * nothing could see it.
+   *
+   * @param {{ width?: number|null, height?: number|null, fps?: number|null, isHdr?: boolean, bitDepth?: number|null }} banner
+   * @param {object | null} declared - The container's own `VideoTrack`.
+   * @returns {{ width: number|null, height: number|null, fps: number|null, isHdr: boolean, bitDepth: number|null, displayWidth: number|null, displayHeight: number|null, disagreements: string[] }}
+   */
+  static mergeVideoFacts(banner, declared) {
+    const number = (value) => (Number.isFinite(value) && value > 0 ? Number(value) : null);
+    const fromBanner = {
+      width: number(banner?.width),
+      height: number(banner?.height),
+      fps: number(banner?.fps),
+      isHdr: banner?.isHdr === true,
+      bitDepth: number(banner?.bitDepth)
+    };
+    if (!declared) {
+      return { ...fromBanner, displayWidth: null, displayHeight: null, disagreements: [] };
+    }
+    const fromContainer = {
+      width: number(declared.width),
+      height: number(declared.height),
+      fps: number(declared.fps),
+      isHdr: declared.isHdr === true,
+      bitDepth: number(declared.bitDepth)
+    };
+    const disagreements = [];
+    const note = (field, mine, theirs) => {
+      if (mine !== null && theirs !== null && mine !== theirs) {
+        disagreements.push(`${field} ${theirs} in the container against ${mine} in the probe`);
+      }
+    };
+    note("width", fromBanner.width, fromContainer.width);
+    note("height", fromBanner.height, fromContainer.height);
+    if (fromBanner.bitDepth !== null && fromContainer.bitDepth !== null && fromBanner.bitDepth !== fromContainer.bitDepth) {
+      disagreements.push(
+        `bit depth ${fromContainer.bitDepth} in the container against ${fromBanner.bitDepth} in the probe`
+      );
+    }
+    // HDR is deliberately NOT compared. Both sides give it as a boolean, and a
+    // boolean cannot say "I did not look": a container with no Colour element
+    // and one that states SDR are the same `false`, as are a probe that printed
+    // no colour metadata and one that printed BT.709. Reporting that as a
+    // disagreement would report it on almost every file. Either side saying yes
+    // is taken as yes, which is the safe direction — the cost of tone mapping a
+    // picture that did not need it is smaller than showing a washed-out one.
+    return {
+      width: fromBanner.width ?? fromContainer.width,
+      height: fromBanner.height ?? fromContainer.height,
+      fps: fromBanner.fps ?? fromContainer.fps,
+      // The container declares these; the probe only reflects them.
+      bitDepth: fromContainer.bitDepth ?? fromBanner.bitDepth,
+      isHdr: fromContainer.isHdr || fromBanner.isHdr,
+      displayWidth: number(declared.displayWidth),
+      displayHeight: number(declared.displayHeight),
+      disagreements
+    };
+  }
+
+  /**
+   * Line ffmpeg's banner up with what the container declares, and say whether the
+   * two are describing the same thing in the same order.
+   *
+   * ffmpeg numbers a file's streams `0:a:N` / `0:s:N` over every stream of that
+   * kind, 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, and 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 about the same thing, and
+   * then the container reading is not used AT ALL. A wrong flag is worse than a
+   * missing one, because `0:a:N` is what the encoder is given.
+   *
+   * One alignment for every media kind, because it is one rule. It was written
+   * twice — once for subtitles, once for audio — down to a `pairingHolds` that
+   * was byte-for-byte the same function under two names.
+   *
+   * @param {object[]} bannerTracks
+   * @param {object[]} declared
+   * @param {string} noun - "subtitle" or "audio"; only for the reason text.
+   * @returns {{ aligned: boolean, reason: string, banner: object[], container: object[] }}
+   */
+  static alignWithBanner(bannerTracks, declared, noun) {
+    const banner = Array.isArray(bannerTracks) ? bannerTracks : [];
+    const container = Array.isArray(declared) ? declared : [];
+    if (banner.length === 0) {
+      return { aligned: false, reason: `the probe found no ${noun} stream`, banner, container };
+    }
+    if (container.length === 0) {
+      return { aligned: false, reason: `the container declares no ${noun} track`, banner, container };
+    }
+    if (container.length !== banner.length) {
+      return {
+        aligned: false,
+        reason: `the container declares ${container.length} ${noun} tracks and the probe found ${banner.length}`,
+        banner,
+        container
+      };
+    }
+    for (const [order, track] of banner.entries()) {
+      if (!Container.pairingHolds(track, container[order])) {
+        return {
+          aligned: false,
+          reason:
+            `${noun} ${order} is "${normalise(track?.title) || "-"}"/${normalise(track?.language) || "-"} ` +
+            `in the probe and "${normalise(container[order]?.name) || "-"}"/` +
+            `${normalise(container[order]?.language) || "-"} in the container`,
+          banner,
+          container
+        };
+      }
+    }
+    return { aligned: true, reason: "", banner, container };
+  }
+
+  /**
+   * What the banner says, with the flags only the container knows added — or the
+   * banner alone where the two could not be lined up.
+   *
+   * `take` says which of the container's fields this kind of track wants, and is
+   * the only part that differs between them.
+   *
+   * @param {object[]} bannerTracks
+   * @param {object[]} declared
+   * @param {string} noun
+   * @param {(containerTrack: object, bannerTrack: object) => object} take
+   * @param {object} absent - The same fields as `take` returns, for a track whose
+   *   container reading could not be used. Not "the container says no" — the
+   *   container has not been heard from.
+   * @returns {{ tracks: object[], aligned: boolean, reason: string }}
+   */
+  static mergeDeclaredFlags(bannerTracks, declared, noun, take, absent) {
+    const { aligned, reason, banner, container } = Container.alignWithBanner(bannerTracks, declared, noun);
+    if (!aligned) {
+      return {
+        tracks: banner.map((track) => ({ ...track, ...absent })),
+        aligned,
+        reason
+      };
+    }
+    return {
+      tracks: banner.map((track, order) => ({ ...track, ...take(container[order], track) })),
+      aligned: true,
+      reason: ""
+    };
+  }
+
   static mergeSubtitleFlags(bannerTracks, declared) {
-    return mergeContainerSubtitleFlags(bannerTracks, declared);
+    return Container.mergeDeclaredFlags(
+      bannerTracks,
+      declared,
+      "subtitle",
+      (track) => ({
+        isDefault: track.isDefault === true,
+        declaresDefault: track.declaresDefault === true,
+        // Read from the file rather than guessed from the track's name. Both
+        // are stated by the container itself (RFC 9559 §5.1.4.1) and neither
+        // reaches ffmpeg's `-i` banner, which is where every other field here
+        // comes from.
+        isForced: track.isForced === true,
+        isHearingImpaired: track.isHearingImpaired === true,
+        // FlagEnabled, so the browser can leave an unusable track out of the
+        // menu. It stays in the list and keeps its number: ffmpeg creates a
+        // stream for it either way.
+        isEnabled: track.isEnabled !== false,
+        // The RFC 5646 tag where the file writes one, kept BESIDE the code
+        // rather than replacing it: this list is aligned against ffmpeg's
+        // banner, which prints the three-letter form.
+        languageBcp47: typeof track.languageBcp47 === "string" ? track.languageBcp47 : ""
+      }),
+      {
+        declaresDefault: false,
+        isForced: false,
+        isHearingImpaired: false,
+        isEnabled: true,
+        languageBcp47: ""
+      }
+    );
+  }
+
+  /**
+   * The same for audio, with the flags RFC 9559 §5.1.4.1 defines for it.
+   *
+   * `FlagOriginal`, `FlagCommentary` and `FlagVisualImpaired` do not appear in
+   * the banner at all, so without this the audio menu cannot tell a director's
+   * commentary from the film.
+   *
+   * @param {object[]} bannerTracks
+   * @param {object[]} declared
+   * @returns {{ tracks: object[], aligned: boolean, reason: string }}
+   */
+  static mergeAudioFlags(bannerTracks, declared) {
+    return Container.mergeDeclaredFlags(
+      bannerTracks,
+      declared,
+      "audio",
+      (track, banner) => ({
+        isOriginal: track.isOriginal === true,
+        isCommentary: track.isCommentary === true,
+        isVisualImpaired: track.isVisualImpaired === true,
+        isEnabled: track.isEnabled !== false,
+        isDefault: track.isDefault === true,
+        declaresDefault: track.declaresDefault === true,
+        languageBcp47: typeof track.languageBcp47 === "string" ? track.languageBcp47 : "",
+        channels: Number.isFinite(track.channels) ? track.channels : null,
+        title:
+          typeof banner?.title === "string" && banner.title.length > 0
+            ? banner.title
+            : (typeof track.name === "string" ? track.name : "")
+      }),
+      {
+        declaresDefault: false,
+        isOriginal: false,
+        isCommentary: false,
+        isVisualImpaired: false,
+        isEnabled: true,
+        languageBcp47: "",
+        channels: null
+      }
+    );
   }
 
+
   /** @returns {string} Human name: "matroska" | "mp4" | "avi" | "unknown" */
   get formatName() {
     return "unknown";
@@ -114,6 +361,52 @@ export class Container {
     throw new Error("readTracks not implemented");
   }
 
+
+  /**
+   * This container's subtitle tracks and where their cues are, in ONE shape
+   * whichever container answers.
+   *
+   * `tracks` carries a `clusterPositions` list for a container that stores cues
+   * in clusters and a `samples` list for one that states each cue's own byte
+   * range; a caller reads neither, and asks {@link Container#readHeldCues}
+   * instead. `declared` is what the container says about its subtitle tracks in
+   * its own order, and empty means the container said nothing — a real answer,
+   * not a missing one.
+   *
+   * @returns {Promise<{ tracks: object[], declared: object[], secondsPerTick: number, segmentDataOffset: number } | null>}
+   *   Null where this container declares no subtitles at all.
+   */
+  async readSubtitlePlan() {
+    return null;
+  }
+
+  /**
+   * The cues this container can read RIGHT NOW for one track, without fetching.
+   *
+   * Every container answers this, and each reads what its own specification
+   * says: Matroska walks the clusters its Cues table names, an MP4 reads the
+   * samples its table states. The caller therefore chooses a container once —
+   * from the bytes — and never again. It used to choose twice, once by file
+   * extension for the container and once by whether a track carried a sample
+   * list for the reading, and two choices that must agree and are made from
+   * different evidence are a disagreement waiting to happen.
+   *
+   * `progress` is what has already been read, kept by the caller because it
+   * belongs to the file rather than to one pass: `walked` holds cluster
+   * positions, `harvested` holds sample offsets per track. Each container adds
+   * to the one it uses.
+   *
+   * @param {object} _plan - This file's subtitle plan.
+   * @param {object} _track - The track asked about.
+   * @param {{ walked: Set<number>, harvested: Map<number, Set<number>> }} _progress
+   * @returns {Promise<{ found: Map<number, object[]>, covered: number, indexed: number }>}
+   *   `found` is track number to the cues found in THIS pass — Matroska fills
+   *   every track from one walk, so it is a map and not a list.
+   */
+  async readHeldCues(_plan, _track, _progress) {
+    return { found: new Map(), covered: 0, indexed: 0 };
+  }
+
   /**
    * Keyframe times for the video track, ascending seconds. Null when index absent (MPEG-TS, fragmented MP4, truncated).
    * @returns {Promise<{times:number[],tolerance:number}|null>}
@@ -274,81 +567,3 @@ function pairingHolds(banner, container) {
   );
 }
 
-/**
- * The banner's subtitle tracks, with what the container says about each.
- *
- * Every returned track gains `declaresDefault`: whether the FILE wrote the flag
- * for it. When the container reading cannot be trusted — no declarations, a
- * different number of them, or a pair that agrees on neither language nor name
- * — every track gets `declaresDefault: false` and its `isDefault` is left as
- * the banner had it. That is the honest answer for a file we cannot read this
- * way: the container has not been heard from, so nothing is shown unasked.
- *
- * @param {Array<{ index?: number, language?: string, title?: string, isDefault?: boolean }>} bannerTracks
- * @param {Array<{ language?: string, name?: string, isDefault?: boolean, declaresDefault?: boolean }>} declared
- * @returns {{ tracks: object[], aligned: boolean, reason: string }}
- */
-function mergeContainerSubtitleFlags(bannerTracks, declared) {
-  const banner = Array.isArray(bannerTracks) ? bannerTracks : [];
-  const container = Array.isArray(declared) ? declared : [];
-  const undecided = () => ({
-    // The container reading could not be lined up, so nothing of it is used —
-    // including the flags, which would otherwise be attributed to the wrong
-    // track.
-    tracks: banner.map((track) => ({
-      ...track,
-      declaresDefault: false,
-      isForced: false,
-      isHearingImpaired: false,
-      // Not "the container says this track is unusable" — nothing of the
-      // container is being used here. A track is offered unless it was read to
-      // say otherwise.
-      isEnabled: true,
-      languageBcp47: ""
-    }))
-  });
-  if (container.length === 0) {
-    return { ...undecided(), aligned: false, reason: "the container declares no subtitle track" };
-  }
-  if (container.length !== banner.length) {
-    return {
-      ...undecided(),
-      aligned: false,
-      reason: `the container declares ${container.length} subtitle tracks and the probe found ${banner.length}`
-    };
-  }
-  for (const [order, track] of banner.entries()) {
-    if (!pairingHolds(track, container[order])) {
-      return {
-        ...undecided(),
-        aligned: false,
-        reason:
-          `subtitle ${order} is "${normalise(track?.title) || "-"}"/${normalise(track?.language) || "-"} ` +
-          `in the probe and "${normalise(container[order]?.name) || "-"}"/` +
-          `${normalise(container[order]?.language) || "-"} in the container`
-      };
-    }
-  }
-  return {
-    tracks: banner.map((track, order) => ({
-      ...track,
-      isDefault: container[order].isDefault === true,
-      declaresDefault: container[order].declaresDefault === true,
-      // Read from the file rather than guessed from the track's name. Both are
-      // stated by the container itself (RFC 9559 §5.1.4.1) and neither reaches
-      // ffmpeg's `-i` banner, which is where every other field here comes from.
-      isForced: container[order].isForced === true,
-      isHearingImpaired: container[order].isHearingImpaired === true,
-      // FlagEnabled, so the browser can leave an unusable track out of the
-      // menu. It stays in this list and keeps its number: ffmpeg creates a
-      // stream for it either way.
-      isEnabled: container[order].isEnabled !== false,
-      // The RFC 5646 tag, where the file writes one. Kept beside the code
-      // rather than replacing it: what this list is aligned against is ffmpeg's
-      // banner, which prints the three-letter form.
-      languageBcp47: typeof container[order].languageBcp47 === "string" ? container[order].languageBcp47 : ""
-    })),
-    aligned: true,
-    reason: ""
-  };
-}

package/services/container/ContainerFactory.js

@@ -1,31 +1,122 @@
-/**
- * @file Container factory — detects format and returns the precise Container subclass.
- *
- * Sniffs first 16 bytes (same as container-index/index.js) and instantiates
- * MatroskaContainer / Mp4Container / AviContainer. Falls back to null (unknown).
- * Orchestrators depend on this, not on concrete constructors.
- */
-
-import { MatroskaContainer } from "./MatroskaContainer.js";
-import { Mp4Container } from "./Mp4Container.js";
-import { AviContainer } from "./AviContainer.js";
-
-const SNIFF_BYTES = 16;
-
-export class ContainerFactory {
-  /**
-   * @param {(start:number,end:number)=>Promise<Buffer|null>} readRange
-   * @param {number} fileSize
-   * @param {string} label
-   * @returns {Promise<import("./Container.js").Container|null>}
-   */
-  static async create({ readRange, fileSize, label = "" }) {
-    if (typeof readRange !== "function" || !Number.isFinite(fileSize) || fileSize <= 0) return null;
-    const head = await readRange(0, Math.min(SNIFF_BYTES - 1, fileSize - 1));
-    if (!head) return null;
-    if (MatroskaContainer.detect(head)) return new MatroskaContainer({ readRange, fileSize, label });
-    if (Mp4Container.detect(head)) return new Mp4Container({ readRange, fileSize, label });
-    if (AviContainer.detect(head)) return new AviContainer({ readRange, fileSize, label });
-    return null;
-  }
-}
+/**
+ * @file Container factory — detects format and returns the precise Container subclass.
+ *
+ * Sniffs first 16 bytes (same as container-index/index.js) and instantiates
+ * MatroskaContainer / Mp4Container / AviContainer. Falls back to null (unknown).
+ * Orchestrators depend on this, not on concrete constructors.
+ */
+
+import { MatroskaContainer } from "./MatroskaContainer.js";
+import { Mp4Container } from "./Mp4Container.js";
+import { AviContainer } from "./AviContainer.js";
+import { logger } from "../../utils/logger.js";
+
+const SNIFF_BYTES = 16;
+
+export class ContainerFactory {
+  /**
+   * The container these bytes are, built over them.
+   *
+   * `params` is passed through whole, so a caller with a torrent's two readers
+   * gets a container that has both — see {@link Container}'s constructor.
+   *
+   * @param {{ readRange: (start:number,end:number)=>Promise<Buffer|null>, fileSize: number, label?: string, readHeld?: Function, isHeld?: Function }} params
+   * @returns {Promise<import("./Container.js").Container|null>}
+   */
+  static async create(params) {
+    const { readRange, fileSize } = params;
+    if (typeof readRange !== "function" || !Number.isFinite(fileSize) || fileSize <= 0) return null;
+    const head = await readRange(0, Math.min(SNIFF_BYTES - 1, fileSize - 1));
+    if (!head) return null;
+    if (MatroskaContainer.detect(head)) return new MatroskaContainer(params);
+    if (Mp4Container.detect(head)) return new Mp4Container(params);
+    if (AviContainer.detect(head)) return new AviContainer(params);
+    return null;
+  }
+
+  /**
+   * The container a file NAME suggests, for the moment the bytes cannot be
+   * sniffed.
+   *
+   * The head of a file nobody has opened is not downloaded, and the cue walk
+   * asks the swarm for nothing — so on that one path the name is all there is.
+   * It is a fallback and never a preference: the bytes decide wherever they can
+   * be read, because a name is what somebody typed and a header is what the
+   * muxer wrote.
+   *
+   * @param {string} name
+   * @returns {typeof MatroskaContainer | typeof Mp4Container | null}
+   */
+
+  /**
+   * Where a file's real keyframes are, read from the container's own tables
+   * rather than by scanning the media.
+   *
+   * The problem it solves: on the video-COPY path ffmpeg can only cut segments
+   * at the source's existing keyframes. A playlist declaring an even grid
+   * instead is false, and players punish it — either walking the whole file to
+   * rebuild the timeline, or presenting audio with no picture because a segment
+   * begins with nothing decodable (both seen in the field 2026-08-02; the file
+   * measured had 10.43 s keyframe spacing against our declared 4 s).
+   *
+   * Scanning is not an option: the file is served from a torrent, and a full
+   * packet scan of 5.5 GB found 77 keyframes in 45 s without finishing.
+   * Containers already store the table, and a couple of point reads get it —
+   * 16 KB and 0.8 s for 570 keyframes on that same file.
+   *
+   * This is the sniff plus the container's own reading, which is why it lives
+   * on the factory: doing it anywhere else meant a third place that decided
+   * what a file is.
+   *
+   * @param {{ readRange: (start:number,end:number)=>Promise<Buffer|null>, fileSize: number, label?: string }} params
+   * @returns {Promise<{ times: number[] | null, format: string, tolerance: number }>}
+   *   Ascending seconds, or null times where this file has no readable index —
+   *   the caller must then not claim to know the grid. The format is which
+   *   container answered, reported whether or not it produced anything: how
+   *   often an index disagrees with its own file is a question about the
+   *   CONTAINER, and a measurement that does not say which one cannot answer it.
+   */
+  static async readKeyframeIndex({ readRange, fileSize, label = "" }) {
+    if (typeof readRange !== "function" || !Number.isFinite(fileSize) || fileSize <= 0) {
+      return { times: null, format: "unknown", tolerance: 0 };
+    }
+    const startedAt = Date.now();
+    let container = null;
+    try {
+      container = await ContainerFactory.create({ readRange, fileSize, label });
+    } catch (error) {
+      logger.warn(`container-index: failed to read "${label}": ${error?.message ?? error}`);
+      return { times: null, format: "unrecognised", tolerance: 0 };
+    }
+    if (!container) {
+      return { times: null, format: "unrecognised", tolerance: 0 };
+    }
+    const format = container.formatName;
+    let index = null;
+    try {
+      index = await container.readKeyframeIndex();
+    } catch (error) {
+      // A malformed or partly-downloaded index must never take playback down —
+      // it only means the grid is unknown, which the caller already handles.
+      logger.warn(`container-index: failed to read index for "${label}": ${error?.message ?? error}`);
+      return { times: null, format, tolerance: 0 };
+    }
+    const elapsedMs = Date.now() - startedAt;
+    const times = index && Array.isArray(index.times) ? index.times : null;
+    if (times) {
+      logger.info(
+        `container-index: ${times.length} keyframes from the ${format} index in ${elapsedMs}ms for "${label}"`
+      );
+    } else {
+      logger.info(`container-index: no usable index for "${label}" (${format}, ${elapsedMs}ms)`);
+    }
+    return { times, format, tolerance: Number.isFinite(index?.tolerance) ? index.tolerance : 0 };
+  }
+
+  static byName(name) {
+    const text = String(name ?? "");
+    if (/\.(mp4|m4v|m4a)$/i.test(text)) return Mp4Container;
+    if (/\.(mkv|mka|webm)$/i.test(text)) return MatroskaContainer;
+    return null;
+  }
+}