@torrent-tv/proxy 2.89.7 → 2.89.8

package/services/media/tracks/AudioTrack.js

@@ -1,143 +1,143 @@
-/**
- * @file Audio track — extends ContainerTrack with audio-specific flags.
- *
- * Matroska RFC 9559 §5.1.4.1:
- *  - FlagOriginal 0x55AE (default 0) — track is original language.
- *  - FlagCommentary 0x55AF — commentary track.
- *  - FlagVisualImpaired 0x55AC — audio description for visually impaired.
- *  - FlagTextDescriptions 0x55AD, FlagHearingImpaired etc. may also appear
- *    but the three above drive the audio menu (research/container-spec-conformance).
- * MP4 ISO/IEC 14496-12: tkhd alternate_group groups alternate audio tracks.
- */
-
-import { codecParametersOf, peakKbpsOf } from "./audio-bound.js";
-import { ContainerTrack } from "./ContainerTrack.js";
-
-/**
- * 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"]
-]);
-
-export class AudioTrack extends ContainerTrack {
-  /**
-   * @param {object} params - See ContainerTrack plus:
-   * @param {boolean} params.isOriginal - FlagOriginal
-   * @param {boolean} params.isCommentary - FlagCommentary
-   * @param {boolean} params.isVisualImpaired - FlagVisualImpaired / descriptive audio
-   * @param {number | null} params.channels
-   * @param {number | null} params.samplingFrequency
-   */
-  constructor(params) {
-    super({ ...params, type: "audio" });
-    this.isOriginal = params.isOriginal === true;
-    this.isCommentary = params.isCommentary === true;
-    this.isVisualImpaired = params.isVisualImpaired === true;
-    this.channels = Number.isFinite(params.channels) ? params.channels : null;
-    this.samplingFrequency = Number.isFinite(params.samplingFrequency) ? params.samplingFrequency : null;
-    // What the codec is configured as, and the most that configuration allows
-    // the track to carry — a statement of the file, read with the rest of the
-    // track table (`audio-bound.js`). Own properties rather than getters, so a
-    // copy of the track made field by field keeps them.
-    this.codecParameters = codecParametersOf({
-      codec: AudioTrack.codecNameOf(params),
-      codecPrivateB64: params.codecPrivateB64,
-      channels: this.channels,
-      samplingFrequency: this.samplingFrequency
-    });
-    this.peakKbps = peakKbpsOf(this.codecParameters);
-  }
-
-  /**
-   * 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}
-   */
-  static 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) ?? "";
-  }
-
-  /** Human label helper — commentary and descriptive audio must not look like main track. */
-  audioRoleLabel() {
-    if (this.isCommentary) return "commentary";
-    if (this.isVisualImpaired) return "descriptive";
-    if (this.isOriginal) return "original";
-    return "";
-  }
-}
+/**
+ * @file Audio track — extends ContainerTrack with audio-specific flags.
+ *
+ * Matroska RFC 9559 §5.1.4.1:
+ *  - FlagOriginal 0x55AE (default 0) — track is original language.
+ *  - FlagCommentary 0x55AF — commentary track.
+ *  - FlagVisualImpaired 0x55AC — audio description for visually impaired.
+ *  - FlagTextDescriptions 0x55AD, FlagHearingImpaired etc. may also appear
+ *    but the three above drive the audio menu (research/container-spec-conformance).
+ * MP4 ISO/IEC 14496-12: tkhd alternate_group groups alternate audio tracks.
+ */
+
+import { codecParametersOf, peakKbpsOf } from "./audio-bound.js";
+import { ContainerTrack } from "./ContainerTrack.js";
+
+/**
+ * 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"]
+]);
+
+export class AudioTrack extends ContainerTrack {
+  /**
+   * @param {object} params - See ContainerTrack plus:
+   * @param {boolean} params.isOriginal - FlagOriginal
+   * @param {boolean} params.isCommentary - FlagCommentary
+   * @param {boolean} params.isVisualImpaired - FlagVisualImpaired / descriptive audio
+   * @param {number | null} params.channels
+   * @param {number | null} params.samplingFrequency
+   */
+  constructor(params) {
+    super({ ...params, type: "audio" });
+    this.isOriginal = params.isOriginal === true;
+    this.isCommentary = params.isCommentary === true;
+    this.isVisualImpaired = params.isVisualImpaired === true;
+    this.channels = Number.isFinite(params.channels) ? params.channels : null;
+    this.samplingFrequency = Number.isFinite(params.samplingFrequency) ? params.samplingFrequency : null;
+    // What the codec is configured as, and the most that configuration allows
+    // the track to carry — a statement of the file, read with the rest of the
+    // track table (`audio-bound.js`). Own properties rather than getters, so a
+    // copy of the track made field by field keeps them.
+    this.codecParameters = codecParametersOf({
+      codec: AudioTrack.codecNameOf(params),
+      codecPrivateB64: params.codecPrivateB64,
+      channels: this.channels,
+      samplingFrequency: this.samplingFrequency
+    });
+    this.peakKbps = peakKbpsOf(this.codecParameters);
+  }
+
+  /**
+   * 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}
+   */
+  static 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) ?? "";
+  }
+
+  /** Human label helper — commentary and descriptive audio must not look like main track. */
+  audioRoleLabel() {
+    if (this.isCommentary) return "commentary";
+    if (this.isVisualImpaired) return "descriptive";
+    if (this.isOriginal) return "original";
+    return "";
+  }
+}

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

package/services/media/tracks/ImageSubtitleTrack.js

@@ -1,19 +1,19 @@
-/**
- * @file Image subtitle track — PGS / VobSub / subp / clcp. Not convertible to WebVTT.
- *
- * Matroska: S_HDMV/PGS, S_VOBSUB, S_IMAGE/BMP etc.
- * MP4: stpp is TTML (XML, excluded from Text), subp (VobSub), clcp (closed captions)
- * Kept in the model only to preserve declaredIndex alignment with ffmpeg 0:s:N.
- */
-
-import { SubtitleTrack } from "./SubtitleTrack.js";
-
-export class ImageSubtitleTrack extends SubtitleTrack {
-  constructor(params) {
-    super(params);
-  }
-
-  isTextBased() {
-    return false;
-  }
-}
+/**
+ * @file Image subtitle track — PGS / VobSub / subp / clcp. Not convertible to WebVTT.
+ *
+ * Matroska: S_HDMV/PGS, S_VOBSUB, S_IMAGE/BMP etc.
+ * MP4: stpp is TTML (XML, excluded from Text), subp (VobSub), clcp (closed captions)
+ * Kept in the model only to preserve declaredIndex alignment with ffmpeg 0:s:N.
+ */
+
+import { SubtitleTrack } from "./SubtitleTrack.js";
+
+export class ImageSubtitleTrack extends SubtitleTrack {
+  constructor(params) {
+    super(params);
+  }
+
+  isTextBased() {
+    return false;
+  }
+}

package/services/media/tracks/SubtitleTrack.js

@@ -1,38 +1,38 @@
-/**
- * @file Subtitle track — extends ContainerTrack with subtitle-only flags.
- *
- * Matroska RFC 9559:
- *  - FlagForced 0x55AA default 0, applies ONLY to subtitles.
- *  - FlagHearingImpaired 0x55AB, FlagVisualImpaired 0x55AC (SDH etc.)
- *  - FlagTextDescriptions 0x55AD also subtitle-related.
- *  - FlagEnabled 0xB9 still handled in base (disabled tracks counted but not offered).
- * MP4 ISO 14496-12 + Apple tx3g extension:
- *  - handler sbtl/subt/text/wvtt vs subp/clcp (image)
- *  - tx3g displayFlags forced bits 0x40000000 / 0x80000000 (unconfirmed primary source, carried as raw flags)
- */
-
-import { ContainerTrack } from "./ContainerTrack.js";
-
-export class SubtitleTrack extends ContainerTrack {
-  /**
-   * @param {object} params - See ContainerTrack plus:
-   * @param {boolean} params.isForced - FlagForced (matroska) or tx3g forced display flag.
-   * @param {boolean} params.isHearingImpaired - FlagHearingImpaired
-   * @param {boolean} params.isVisualImpaired - FlagVisualImpaired
-   * @param {number[]} params.clusterPositions - Matroska: file offsets of clusters whose CuePoints name this track (for push). Empty when indexless.
-   * @param {Array<{offset:number,size:number,startSeconds:number,endSeconds:number}>} params.samples - MP4: per-cue byte ranges from sample tables.
-   */
-  constructor(params) {
-    super({ ...params, type: "subtitle" });
-    this.isForced = params.isForced === true;
-    this.isHearingImpaired = params.isHearingImpaired === true;
-    this.isVisualImpaired = params.isVisualImpaired === true;
-    this.clusterPositions = Array.isArray(params.clusterPositions) ? params.clusterPositions : [];
-    this.samples = Array.isArray(params.samples) ? params.samples : [];
-  }
-
-  /** Whether this track can be converted to WebVTT in current pipeline. Overridden by subclasses. */
-  isTextBased() {
-    return false;
-  }
-}
+/**
+ * @file Subtitle track — extends ContainerTrack with subtitle-only flags.
+ *
+ * Matroska RFC 9559:
+ *  - FlagForced 0x55AA default 0, applies ONLY to subtitles.
+ *  - FlagHearingImpaired 0x55AB, FlagVisualImpaired 0x55AC (SDH etc.)
+ *  - FlagTextDescriptions 0x55AD also subtitle-related.
+ *  - FlagEnabled 0xB9 still handled in base (disabled tracks counted but not offered).
+ * MP4 ISO 14496-12 + Apple tx3g extension:
+ *  - handler sbtl/subt/text/wvtt vs subp/clcp (image)
+ *  - tx3g displayFlags forced bits 0x40000000 / 0x80000000 (unconfirmed primary source, carried as raw flags)
+ */
+
+import { ContainerTrack } from "./ContainerTrack.js";
+
+export class SubtitleTrack extends ContainerTrack {
+  /**
+   * @param {object} params - See ContainerTrack plus:
+   * @param {boolean} params.isForced - FlagForced (matroska) or tx3g forced display flag.
+   * @param {boolean} params.isHearingImpaired - FlagHearingImpaired
+   * @param {boolean} params.isVisualImpaired - FlagVisualImpaired
+   * @param {number[]} params.clusterPositions - Matroska: file offsets of clusters whose CuePoints name this track (for push). Empty when indexless.
+   * @param {Array<{offset:number,size:number,startSeconds:number,endSeconds:number}>} params.samples - MP4: per-cue byte ranges from sample tables.
+   */
+  constructor(params) {
+    super({ ...params, type: "subtitle" });
+    this.isForced = params.isForced === true;
+    this.isHearingImpaired = params.isHearingImpaired === true;
+    this.isVisualImpaired = params.isVisualImpaired === true;
+    this.clusterPositions = Array.isArray(params.clusterPositions) ? params.clusterPositions : [];
+    this.samples = Array.isArray(params.samples) ? params.samples : [];
+  }
+
+  /** Whether this track can be converted to WebVTT in current pipeline. Overridden by subclasses. */
+  isTextBased() {
+    return false;
+  }
+}