@torrent-tv/proxy 2.89.6 → 2.89.8

package/services/media/container/unavailable.js

@@ -1,77 +1,77 @@
-/**
- * @file Bytes that are not here yet, said as such.
- *
- * A container reads a file it does not hold: the bytes arrive off a swarm, in
- * whatever order the swarm delivers them. So every read has three outcomes —
- * the bytes, a statement the bytes make ("there is no Cues element"), and "the
- * bytes are not here yet" — and only the first two are facts about the file.
- *
- * Until 2026-10-01 the third came back as `null`, the same value the readers
- * return for "the element is absent". Every container then read a read that
- * had not arrived as an element that does not exist, and everything that
- * remembered a container's answer remembered that as a fact for the life of the
- * process: an embedded subtitle track planned with no clusters while its Cues
- * table was still downloading showed nothing for a whole session
- * (`research/subtitles-never-appear-2026-10-01.md`). The same shape was in the
- * container choice, the track table, the keyframe table, MP4's `moov` and AVI's
- * `idx1`.
- *
- * So a read that cannot be answered now THROWS this, and the rule for anything
- * that keeps an answer is one line: a value or a proven absence may be kept;
- * this may not.
- */
-
-/** Thrown where the bytes a reading needs have not arrived. */
-export class BytesUnavailable extends Error {
-  /**
-   * @param {number} start
-   * @param {number} end - Inclusive.
-   * @param {number} received - How many bytes the read did return.
-   */
-  constructor(start, end, received) {
-    super(`bytes ${start}-${end} of the file are not available yet (${received} of ${end - start + 1} received)`);
-    this.name = "BytesUnavailable";
-    this.start = start;
-    this.end = end;
-    this.received = received;
-  }
-}
-
-/**
- * Whether an error says "not here yet" rather than "something is wrong".
- *
- * @param {unknown} error
- * @returns {boolean}
- */
-export function isUnavailable(error) {
-  return error instanceof BytesUnavailable || /** @type {any} */ (error)?.name === "BytesUnavailable";
-}
-
-/**
- * A reader that answers with every byte asked for, or throws.
- *
- * The range is clamped to the file first, so a reading that asks past the end
- * of a short file — a head window over a file smaller than the window — is
- * answered with what the file has, and that is complete. Anything shorter than
- * the clamped range is a read that did not finish: a stream that ended early,
- * a piece that is not downloaded, a store that could not serve it.
- *
- * @param {(start: number, end: number) => Promise<Buffer | null>} read
- * @param {number} fileSize
- * @returns {(start: number, end: number) => Promise<Buffer>}
- */
-export function strictReader(read, fileSize) {
-  return async (start, end) => {
-    const last = Math.min(end, fileSize - 1);
-    if (!(start >= 0) || last < start) {
-      return Buffer.alloc(0);
-    }
-    const bytes = await read(start, last);
-    const wanted = last - start + 1;
-    const received = bytes ? bytes.length : 0;
-    if (received < wanted) {
-      throw new BytesUnavailable(start, last, received);
-    }
-    return received === wanted ? bytes : bytes.subarray(0, wanted);
-  };
-}
+/**
+ * @file Bytes that are not here yet, said as such.
+ *
+ * A container reads a file it does not hold: the bytes arrive off a swarm, in
+ * whatever order the swarm delivers them. So every read has three outcomes —
+ * the bytes, a statement the bytes make ("there is no Cues element"), and "the
+ * bytes are not here yet" — and only the first two are facts about the file.
+ *
+ * Until 2026-10-01 the third came back as `null`, the same value the readers
+ * return for "the element is absent". Every container then read a read that
+ * had not arrived as an element that does not exist, and everything that
+ * remembered a container's answer remembered that as a fact for the life of the
+ * process: an embedded subtitle track planned with no clusters while its Cues
+ * table was still downloading showed nothing for a whole session
+ * (`research/subtitles-never-appear-2026-10-01.md`). The same shape was in the
+ * container choice, the track table, the keyframe table, MP4's `moov` and AVI's
+ * `idx1`.
+ *
+ * So a read that cannot be answered now THROWS this, and the rule for anything
+ * that keeps an answer is one line: a value or a proven absence may be kept;
+ * this may not.
+ */
+
+/** Thrown where the bytes a reading needs have not arrived. */
+export class BytesUnavailable extends Error {
+  /**
+   * @param {number} start
+   * @param {number} end - Inclusive.
+   * @param {number} received - How many bytes the read did return.
+   */
+  constructor(start, end, received) {
+    super(`bytes ${start}-${end} of the file are not available yet (${received} of ${end - start + 1} received)`);
+    this.name = "BytesUnavailable";
+    this.start = start;
+    this.end = end;
+    this.received = received;
+  }
+}
+
+/**
+ * Whether an error says "not here yet" rather than "something is wrong".
+ *
+ * @param {unknown} error
+ * @returns {boolean}
+ */
+export function isUnavailable(error) {
+  return error instanceof BytesUnavailable || /** @type {any} */ (error)?.name === "BytesUnavailable";
+}
+
+/**
+ * A reader that answers with every byte asked for, or throws.
+ *
+ * The range is clamped to the file first, so a reading that asks past the end
+ * of a short file — a head window over a file smaller than the window — is
+ * answered with what the file has, and that is complete. Anything shorter than
+ * the clamped range is a read that did not finish: a stream that ended early,
+ * a piece that is not downloaded, a store that could not serve it.
+ *
+ * @param {(start: number, end: number) => Promise<Buffer | null>} read
+ * @param {number} fileSize
+ * @returns {(start: number, end: number) => Promise<Buffer>}
+ */
+export function strictReader(read, fileSize) {
+  return async (start, end) => {
+    const last = Math.min(end, fileSize - 1);
+    if (!(start >= 0) || last < start) {
+      return Buffer.alloc(0);
+    }
+    const bytes = await read(start, last);
+    const wanted = last - start + 1;
+    const received = bytes ? bytes.length : 0;
+    if (received < wanted) {
+      throw new BytesUnavailable(start, last, received);
+    }
+    return received === wanted ? bytes : bytes.subarray(0, wanted);
+  };
+}

package/services/media/tracks/ContainerTrack.js

@@ -1,84 +1,84 @@
-/**
- * @file Base container track — what the container declares about one track.
- *
- * Spec sources:
- *  - Matroska RFC 9559 §5.1.4.1 TrackEntry: TrackNumber(0xD7), TrackType(0x83),
- *    FlagEnabled(0xB9, default 1), FlagDefault(0x88, default 1),
- *    Language(0x22B59C, default "eng"), LanguageBCP47(0x22B59D, MUST ignore
- *    Language when present), Name(0x536E), CodecID(0x86), CodecPrivate(0x63A2).
- *  - MP4 ISO/IEC 14496-12 §8.3.2 tkhd (track_ID, flags track_enabled 0x000001,
- *    alternate_group), §8.4.2 mdhd (language, timescale), §8.4.5 hdlr
- *    (handler_type), §8.4.6 elng (extended language).
- *
- * Only fields that exist for EVERY track type live here. Type-specific flags
- * (FlagForced, FlagHearingImpaired, FlagVisualImpaired, FlagOriginal,
- * FlagCommentary) belong to subclasses — RFC 9559 states FlagForced "Applies
- * only to subtitles", so VideoTrack must not carry it.
- */
-
-export class ContainerTrack {
-  /**
-   * @param {object} params
-   * @param {number} params.trackNumber - Matroska TrackNumber or MP4 track_ID.
-   * @param {number} params.declaredIndex - Position among ALL subtitle/audio/video tracks as container orders them; equals ffmpeg 0:s:N / 0:a:N for that type. Stable across image/text filtering.
-   * @param {string} params.type - "video" | "audio" | "subtitle" | "other"
-   * @param {string} params.codecId - Matroska CodecID or MP4 sample entry type (e.g. "S_TEXT/UTF8", "avc1", "mp4a").
-   * @param {string} params.language - Three-letter code or packed mdhd code; empty when absent. For Matroska, when LanguageBCP47 is present this is the BCP47 value ignored per MUST — caller stores both, but `language` here is the resolved one.
-   * @param {string} params.languageBcp47 - RFC 5646 tag from LanguageBCP47 / elng, or "".
-   * @param {boolean} params.declaresLanguage - Whether the file explicitly supplies a language rather than relying on a container default.
-   * @param {string} params.name - Track Name / title, or "".
-   * @param {boolean} params.isEnabled - FlagEnabled / tkhd track_enabled. Default true per both specs. Matroska zero-length element means default, not disabled.
-   * @param {boolean} params.isDefault - FlagDefault / tkhd? For MP4, derived from handler default? For Matroska, after applying default 1.
-   * @param {boolean} params.declaresDefault - Whether FlagDefault was explicitly written (Matroska) or inferred. Needed because ffmpeg banner cannot distinguish "every track marked" from "no track marked".
-   * @param {string} [params.codecPrivateB64] - Base64 of CodecPrivate (ASS header etc.), or "".
-   * @param {number} [params.alternateGroup] - MP4 alternate_group (0 = no group).
-   */
-  constructor({
-    trackNumber,
-    declaredIndex,
-    type,
-    codecId,
-    language,
-    languageBcp47,
-    declaresLanguage,
-    languageSource = "",
-    languageCode = "",
-    name,
-    isEnabled,
-    isDefault,
-    declaresDefault,
-    codecPrivateB64 = "",
-    alternateGroup = 0
-  }) {
-    this.trackNumber = trackNumber;
-    this.declaredIndex = declaredIndex;
-    this.type = type;
-    this.codecId = codecId ?? "";
-    this.language = language ?? "";
-    this.languageBcp47 = languageBcp47 ?? "";
-    this.declaresLanguage = declaresLanguage === true;
-    // Where `language` came from: "bcp47", "language", "default" (the format's
-    // own default, RFC 8794 §11.1.19), or "" where the container has no say.
-    this.languageSource = typeof languageSource === "string" ? languageSource : "";
-    // The three-letter form the file states, or its default — what ffmpeg's
-    // banner prints, and so what a list lined up against it has to carry even
-    // where an RFC 5646 tag is the track's language.
-    this.languageCode = typeof languageCode === "string" ? languageCode : "";
-    this.name = name ?? "";
-    this.isEnabled = isEnabled !== false;
-    this.isDefault = isDefault === true;
-    this.declaresDefault = declaresDefault === true;
-    this.codecPrivateB64 = codecPrivateB64 ?? "";
-    this.alternateGroup = Number.isFinite(alternateGroup) ? alternateGroup : 0;
-  }
-
-  /** Whether this track should be offered in UI menus. Base rule: disabled tracks hidden but still counted for declaredIndex. */
-  isOfferable() {
-    return this.isEnabled;
-  }
-
-  /** RFC 5646 tag wins over three-letter code when present. */
-  resolvedLanguage() {
-    return this.languageBcp47 || this.language;
-  }
-}
+/**
+ * @file Base container track — what the container declares about one track.
+ *
+ * Spec sources:
+ *  - Matroska RFC 9559 §5.1.4.1 TrackEntry: TrackNumber(0xD7), TrackType(0x83),
+ *    FlagEnabled(0xB9, default 1), FlagDefault(0x88, default 1),
+ *    Language(0x22B59C, default "eng"), LanguageBCP47(0x22B59D, MUST ignore
+ *    Language when present), Name(0x536E), CodecID(0x86), CodecPrivate(0x63A2).
+ *  - MP4 ISO/IEC 14496-12 §8.3.2 tkhd (track_ID, flags track_enabled 0x000001,
+ *    alternate_group), §8.4.2 mdhd (language, timescale), §8.4.5 hdlr
+ *    (handler_type), §8.4.6 elng (extended language).
+ *
+ * Only fields that exist for EVERY track type live here. Type-specific flags
+ * (FlagForced, FlagHearingImpaired, FlagVisualImpaired, FlagOriginal,
+ * FlagCommentary) belong to subclasses — RFC 9559 states FlagForced "Applies
+ * only to subtitles", so VideoTrack must not carry it.
+ */
+
+export class ContainerTrack {
+  /**
+   * @param {object} params
+   * @param {number} params.trackNumber - Matroska TrackNumber or MP4 track_ID.
+   * @param {number} params.declaredIndex - Position among ALL subtitle/audio/video tracks as container orders them; equals ffmpeg 0:s:N / 0:a:N for that type. Stable across image/text filtering.
+   * @param {string} params.type - "video" | "audio" | "subtitle" | "other"
+   * @param {string} params.codecId - Matroska CodecID or MP4 sample entry type (e.g. "S_TEXT/UTF8", "avc1", "mp4a").
+   * @param {string} params.language - Three-letter code or packed mdhd code; empty when absent. For Matroska, when LanguageBCP47 is present this is the BCP47 value ignored per MUST — caller stores both, but `language` here is the resolved one.
+   * @param {string} params.languageBcp47 - RFC 5646 tag from LanguageBCP47 / elng, or "".
+   * @param {boolean} params.declaresLanguage - Whether the file explicitly supplies a language rather than relying on a container default.
+   * @param {string} params.name - Track Name / title, or "".
+   * @param {boolean} params.isEnabled - FlagEnabled / tkhd track_enabled. Default true per both specs. Matroska zero-length element means default, not disabled.
+   * @param {boolean} params.isDefault - FlagDefault / tkhd? For MP4, derived from handler default? For Matroska, after applying default 1.
+   * @param {boolean} params.declaresDefault - Whether FlagDefault was explicitly written (Matroska) or inferred. Needed because ffmpeg banner cannot distinguish "every track marked" from "no track marked".
+   * @param {string} [params.codecPrivateB64] - Base64 of CodecPrivate (ASS header etc.), or "".
+   * @param {number} [params.alternateGroup] - MP4 alternate_group (0 = no group).
+   */
+  constructor({
+    trackNumber,
+    declaredIndex,
+    type,
+    codecId,
+    language,
+    languageBcp47,
+    declaresLanguage,
+    languageSource = "",
+    languageCode = "",
+    name,
+    isEnabled,
+    isDefault,
+    declaresDefault,
+    codecPrivateB64 = "",
+    alternateGroup = 0
+  }) {
+    this.trackNumber = trackNumber;
+    this.declaredIndex = declaredIndex;
+    this.type = type;
+    this.codecId = codecId ?? "";
+    this.language = language ?? "";
+    this.languageBcp47 = languageBcp47 ?? "";
+    this.declaresLanguage = declaresLanguage === true;
+    // Where `language` came from: "bcp47", "language", "default" (the format's
+    // own default, RFC 8794 §11.1.19), or "" where the container has no say.
+    this.languageSource = typeof languageSource === "string" ? languageSource : "";
+    // The three-letter form the file states, or its default — what ffmpeg's
+    // banner prints, and so what a list lined up against it has to carry even
+    // where an RFC 5646 tag is the track's language.
+    this.languageCode = typeof languageCode === "string" ? languageCode : "";
+    this.name = name ?? "";
+    this.isEnabled = isEnabled !== false;
+    this.isDefault = isDefault === true;
+    this.declaresDefault = declaresDefault === true;
+    this.codecPrivateB64 = codecPrivateB64 ?? "";
+    this.alternateGroup = Number.isFinite(alternateGroup) ? alternateGroup : 0;
+  }
+
+  /** Whether this track should be offered in UI menus. Base rule: disabled tracks hidden but still counted for declaredIndex. */
+  isOfferable() {
+    return this.isEnabled;
+  }
+
+  /** RFC 5646 tag wins over three-letter code when present. */
+  resolvedLanguage() {
+    return this.languageBcp47 || this.language;
+  }
+}