@torrent-tv/proxy 2.63.0 → 2.64.0

package/services/controllers/SubtitleController.js

@@ -0,0 +1,126 @@
+/**
+ * @file Subtitle controller — interface layer over SubtitleOrchestrator.
+ *
+ * Routes (HTTP or data-channel) call this, not the domain module directly.
+ * Handles external files vs embedded tracks branching, header setting, and
+ * cursor/covered-cluster bookkeeping. Domain work (cluster walk, conversion,
+ * language detection) stays in orchestrator/domain.
+ */
+
+import { subtitleOrchestrator } from "../orchestrators/SubtitleOrchestrator.js";
+import { convertSubtitleToVtt, decodeSubtitleBytes } from "../subtitle-convert.js";
+import { detectLanguage } from "../language-detect.js";
+import { finalizeCues } from "../torrent-worker/subtitle-cues.js";
+
+const EXTERNAL_MAX_BYTES = 8 * 1024 * 1024;
+
+function vttTime(s) {
+  const safe = Math.max(0, s);
+  const h = Math.floor(safe / 3600);
+  const m = Math.floor((safe % 3600) / 60);
+  const r = safe % 60;
+  return `${String(h).padStart(2, "0")}:${String(m).padStart(2, "0")}:${r.toFixed(3).padStart(6, "0")}`;
+}
+
+function cuesToVtt(cues, codecId) {
+  const lines = ["WEBVTT", ""];
+  for (const c of finalizeCues(cues, codecId)) {
+    lines.push(`${vttTime(c.startSeconds)} --> ${vttTime(c.endSeconds)}`);
+    lines.push(c.text);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+function readFileFully(file, maxBytes) {
+  return new Promise((resolve, reject) => {
+    const stream = file.createReadStream();
+    const chunks = [];
+    let total = 0;
+    stream.on("data", (chunk) => {
+      total += chunk.length;
+      if (total > maxBytes) { stream.destroy(); reject(new Error("subtitle file exceeds size cap")); return; }
+      chunks.push(chunk);
+    });
+    stream.on("end", () => resolve(Buffer.concat(chunks)));
+    stream.on("error", reject);
+  });
+}
+
+export class SubtitleController {
+  constructor({ sourceRegistry, torrentPool }) {
+    this.sourceRegistry = sourceRegistry;
+    this.torrentPool = torrentPool;
+    this.orchestrator = subtitleOrchestrator;
+  }
+
+  /**
+   * Serve external subtitle file or embedded track.
+   * Returns { vtt, language, headers } or { error, status }.
+   */
+  async getSubtitle({ sourceKey, fileIndex, trackIndex, since, after }) {
+    const rec = this.sourceRegistry.get(sourceKey);
+    if (!rec) return { error: "Source key was not found.", status: 404 };
+    const torrent = await this.torrentPool.getTorrent(rec.sourceType, rec.source);
+    const file = torrent.files[fileIndex];
+    if (!file) return { error: "File index was not found in torrent.", status: 404 };
+
+    const hasTrack = trackIndex !== undefined && trackIndex !== "" && Number.isFinite(Number(trackIndex));
+    if (!hasTrack) {
+      const name = file.name ?? "";
+      const ext = name.slice(name.lastIndexOf(".")).toLowerCase();
+      const release = this.torrentPool.acquireFile(torrent, fileIndex);
+      try {
+        const bytes = await readFileFully(file, EXTERNAL_MAX_BYTES);
+        const text = decodeSubtitleBytes(bytes);
+        const vtt = convertSubtitleToVtt(text, ext);
+        if (!vtt) return { error: `Unsupported subtitle format: ${ext}`, status: 422 };
+        return { vtt, language: detectLanguage(text), headers: {} };
+      } catch (e) {
+        return { error: `Could not read subtitle file: ${e?.message ?? e}`, status: 502 };
+      } finally {
+        release();
+      }
+    }
+
+    const idx = Number(trackIndex);
+    if (!Number.isInteger(idx) || idx < 0) return { error: "trackIndex must be a non-negative integer.", status: 400 };
+
+    // Resolve via orchestrator (domain: cluster walk or MP4 sample ranges)
+    const tracks = await this.orchestrator.getTracks(torrent, fileIndex, sourceKey);
+    const track = Array.isArray(tracks) ? tracks.find((c) => c.declaredIndex === idx) ?? null : null;
+    // Also try domain's declaredIndex-agnostic lookup via getCues path — keep compat with existing subtitle-cues declaredIndex
+    let held = null;
+    try {
+      // Need trackNumber for domain call — find via declared workspace
+      const domainTracks = await this.orchestrator.getDeclaredTracks(torrent, fileIndex, sourceKey);
+      // If not found, fall back to direct cuesHeldFor via trackNumber from tracks list
+      const target = track ?? domainTracks.find((t) => t.declaredIndex === idx) ?? null;
+      const trackNumber = target?.trackNumber ?? track?.trackNumber;
+      if (trackNumber != null) {
+        held = await this.orchestrator.getCues(torrent, fileIndex, sourceKey, trackNumber);
+      }
+    } catch {}
+    if (held && Array.isArray(held.cues)) {
+      const cursor = held.cues.reduce((h, c) => Math.max(h, Number(c.seq) || 0), 0);
+      const fresh = Number.isInteger(since) ? held.cues.filter((c) => (Number(c.seq) || 0) > since)
+        : Number.isFinite(after) ? held.cues.filter((c) => c.startSeconds > after) : held.cues;
+      const vtt = cuesToVtt(fresh, held.track?.codecId ?? track?.codecId ?? "");
+      const language = held.cues.length > 0 ? detectLanguage(held.cues.map((c) => c.text).join("\n")) : null;
+      return {
+        vtt,
+        language,
+        headers: {
+          "X-Subtitle-Covered-Clusters": String(held.coveredClusters ?? 0),
+          "X-Subtitle-Indexed-Clusters": String(held.indexedClusters ?? 0),
+          "X-Subtitle-Cursor": String(cursor)
+        }
+      };
+    }
+    return { pending: true, status: 202 };
+  }
+
+  async warm(torrent, fileIndex, sourceKey) {
+    return this.orchestrator.warm(torrent, fileIndex, sourceKey);
+  }
+}

package/services/controllers/index.js

@@ -0,0 +1,2 @@
+export { PlaybackController } from "./PlaybackController.js";
+export { SubtitleController } from "./SubtitleController.js";

package/services/orchestrators/ContainerOrchestrator.js

@@ -0,0 +1,89 @@
+/**
+ * @file Container orchestrator — application layer over Container domain.
+ *
+ * Holds a per-file cache of Container instances (key sourceKey:fileIndex) so
+ * Tracks and keyframe index are read once per file, not per request.
+ * Delegates format detection to ContainerFactory. Transport-agnostic — takes
+ * readRange, knows nothing about torrents or HTTP.
+ */
+
+import { ContainerFactory } from "../container/ContainerFactory.js";
+import { logger } from "../../utils/logger.js";
+
+export class ContainerOrchestrator {
+  constructor() {
+    /** @type {Map<string, import("../container/Container.js").Container|null>} */
+    this.cache = new Map();
+    /** @type {Map<string, Promise<import("../container/Container.js").Container|null>>} */
+    this.pending = new Map();
+  }
+
+  /**
+   * @param {object} params
+   * @param {string} params.sourceKey
+   * @param {number} params.fileIndex
+   * @param {(start:number,end:number)=>Promise<Buffer|null>} params.readRange
+   * @param {number} params.fileSize
+   * @param {string} [params.label]
+   * @returns {Promise<import("../container/Container.js").Container|null>}
+   */
+  async getContainer({ sourceKey, fileIndex, readRange, fileSize, label = "" }) {
+    const key = `${sourceKey}:${fileIndex}`;
+    if (this.cache.has(key)) return this.cache.get(key);
+    if (this.pending.has(key)) return this.pending.get(key);
+    const p = ContainerFactory.create({ readRange, fileSize, label }).then((c) => {
+      this.cache.set(key, c);
+      this.pending.delete(key);
+      if (c) logger.info(`container: ${c.formatName} for "${label}"`);
+      else logger.info(`container: unknown for "${label}"`);
+      return c;
+    }).catch((e) => {
+      this.pending.delete(key);
+      logger.warn(`container: failed for "${label}": ${e?.message ?? e}`);
+      return null;
+    });
+    this.pending.set(key, p);
+    return p;
+  }
+
+  /**
+   * @param {object} params - same as getContainer
+   * @returns {Promise<import("../tracks/index.js").ContainerTrack[]>}
+   */
+  async getTracks(params) {
+    const container = await this.getContainer(params);
+    if (!container) return [];
+    try {
+      return await container.readTracks();
+    } catch (e) {
+      logger.warn(`container: readTracks failed for "${params.label}": ${e?.message ?? e}`);
+      return [];
+    }
+  }
+
+  /**
+   * @param {object} params - same as getContainer
+   * @returns {Promise<{times:number[],tolerance:number}|null>}
+   */
+  async getKeyframeIndex(params) {
+    const container = await this.getContainer(params);
+    if (!container) return null;
+    try {
+      return await container.readKeyframeIndex();
+    } catch {
+      return null;
+    }
+  }
+
+  forget(sourceKey, fileIndex) {
+    if (fileIndex === undefined) {
+      for (const k of [...this.cache.keys()]) if (k.startsWith(`${sourceKey}:`)) this.cache.delete(k);
+      for (const k of [...this.pending.keys()]) if (k.startsWith(`${sourceKey}:`)) this.pending.delete(k);
+      return;
+    }
+    this.cache.delete(`${sourceKey}:${fileIndex}`);
+    this.pending.delete(`${sourceKey}:${fileIndex}`);
+  }
+}
+
+export const containerOrchestrator = new ContainerOrchestrator();

package/services/orchestrators/SubtitleOrchestrator.js

@@ -0,0 +1,101 @@
+/**
+ * @file Subtitle orchestrator — application layer over subtitle domain.
+ *
+ * Wraps torrent-worker/subtitle-cues.js domain (planFor, cuesHeldFor,
+ * warmSubtitleCues, forgetSubtitles) behind Container/Track abstraction.
+ * Provides per-file track list and cue streaming, with the same "only already
+ * downloaded clusters" rule as before. Controllers (HTTP or data-channel)
+ * depend on this, not on the worker module directly.
+ *
+ * Delegates to ContainerOrchestrator for track enumeration so subtitle tracks
+ * and their flags come from the unified ContainerTrack hierarchy.
+ */
+
+import { containerOrchestrator } from "./ContainerOrchestrator.js";
+import {
+  cuesHeldFor as domainCuesHeldFor,
+  warmSubtitleCues as domainWarm,
+  subtitleTracksOf,
+  declaredSubtitleTracksOf,
+  forgetSubtitles as domainForget
+} from "../torrent-worker/subtitle-cues.js";
+import { logger } from "../../utils/logger.js";
+
+export class SubtitleOrchestrator {
+  /**
+   * @param {import("./ContainerOrchestrator.js").ContainerOrchestrator} containerOrchestrator
+   */
+  constructor(containerOrchestrator) {
+    this.containers = containerOrchestrator;
+  }
+
+  /**
+   * Tracks for menu — text tracks via domain, enriched with ContainerTrack flags.
+   * Falls back to container tracks when domain has no plan yet.
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @param {string} sourceKey
+   * @param {(start:number,end:number)=>Promise<Buffer|null>} [readRange]
+   * @param {number} [fileSize]
+   * @returns {Promise<import("../tracks/index.js").ContainerTrack[]>}
+   */
+  async getTracks(torrent, fileIndex, sourceKey, readRange, fileSize) {
+    try {
+      const domain = await subtitleTracksOf(torrent, fileIndex, sourceKey);
+      if (Array.isArray(domain) && domain.length > 0) return domain;
+    } catch {}
+    if (readRange && Number.isFinite(fileSize)) {
+      try {
+        const tracks = await this.containers.getTracks({ sourceKey, fileIndex, readRange, fileSize, label: torrent?.files?.[fileIndex]?.name ?? "" });
+        return tracks.filter((t) => t.type === "subtitle");
+      } catch {}
+    }
+    return [];
+  }
+
+  /**
+   * Declared subtitle tracks in container order (including image tracks) — for declaredIndex alignment.
+   */
+  async getDeclaredTracks(torrent, fileIndex, sourceKey) {
+    try {
+      return await declaredSubtitleTracksOf(torrent, fileIndex, sourceKey);
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Cues already downloaded for one track.
+   * @param {object} torrent
+   * @param {number} fileIndex
+   * @param {string} sourceKey
+   * @param {number} trackNumber - Container trackNumber
+   */
+  async getCues(torrent, fileIndex, sourceKey, trackNumber) {
+    try {
+      return await domainCuesHeldFor(torrent, fileIndex, sourceKey, trackNumber);
+    } catch (e) {
+      logger.warn(`subtitle-orchestrator: getCues failed: ${e?.message ?? e}`);
+      return { cues: [], coveredClusters: 0, indexedClusters: 0, track: null };
+    }
+  }
+
+  /**
+   * Warm all subtitle tracks of a file — called periodically and on verified pieces.
+   * Returns per-track fresh cues for push.
+   */
+  async warm(torrent, fileIndex, sourceKey) {
+    try {
+      return await domainWarm(torrent, fileIndex, sourceKey);
+    } catch {
+      return [];
+    }
+  }
+
+  forget(sourceKey, fileIndex) {
+    domainForget(sourceKey, fileIndex);
+    this.containers.forget(sourceKey, fileIndex);
+  }
+}
+
+export const subtitleOrchestrator = new SubtitleOrchestrator(containerOrchestrator);

package/services/orchestrators/index.js

@@ -0,0 +1,2 @@
+export { ContainerOrchestrator, containerOrchestrator } from "./ContainerOrchestrator.js";
+export { SubtitleOrchestrator, subtitleOrchestrator } from "./SubtitleOrchestrator.js";

package/services/piece-store/shared-piece-store.js

@@ -411,7 +411,11 @@ export class SharedPieceStore {
 
   /** How many pieces fit in memory at once. */
   get capacity() {
-    return this.#capacity;
+    // What may be held NOW, not the reservation this store was created with.
+    // A reader sizes its window from this (`ceilingPieces` in piece-reader),
+    // and sizing it from an allowance the machine has since withdrawn is how a
+    // reader comes to want more pieces than the store can hold.
+    return this.#growthCeiling;
   }
 
   /** How many pieces are resident right now. */

package/services/tracks/AudioTrack.js

@@ -0,0 +1,40 @@
+/**
+ * @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 { ContainerTrack } from "./ContainerTrack.js";
+
+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;
+  }
+
+  /** 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/tracks/ContainerTrack.js

@@ -0,0 +1,72 @@
+/**
+ * @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 {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,
+    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.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/tracks/ExternalSubtitleFile.js

@@ -0,0 +1,27 @@
+/**
+ * @file External subtitle file — not part of the media container, but shares TextSubtitleTrack API.
+ *
+ * A standalone .srt/.ass/.ssa/.vtt file beside the video in the same torrent.
+ * Has no container flags; language comes from filename suffix or franc detection.
+ */
+
+export class ExternalSubtitleFile {
+  /**
+   * @param {object} params
+   * @param {string} params.fileName
+   * @param {number} params.fileIndex - Torrent file index.
+   * @param {string} params.extension - ".srt" etc. lowercased.
+   * @param {string} params.language - Hint from filename or "".
+   */
+  constructor({ fileName, fileIndex, extension, language = "" }) {
+    this.fileName = fileName;
+    this.fileIndex = fileIndex;
+    this.extension = extension;
+    this.language = language;
+    this.type = "external-subtitle";
+  }
+
+  isTextBased() {
+    return true;
+  }
+}

package/services/tracks/ImageSubtitleTrack.js

@@ -0,0 +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;
+  }
+}

package/services/tracks/SubtitleTrack.js

@@ -0,0 +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;
+  }
+}

package/services/tracks/TextSubtitleTrack.js

@@ -0,0 +1,29 @@
+/**
+ * @file Text subtitle track — convertible to WebVTT.
+ *
+ * Matroska: S_TEXT/UTF8, S_TEXT/ASS, S_TEXT/SSA
+ * MP4: tx3g, text, wvtt (stpp/TTML is NOT text for this pipeline — excluded)
+ * External files: .srt .ass .ssa .vtt — modelled as TextSubtitleTrack with no container backing.
+ */
+
+import { SubtitleTrack } from "./SubtitleTrack.js";
+
+const TEXT_CODECS_MATROSKA = new Set(["S_TEXT/UTF8", "S_TEXT/ASS", "S_TEXT/SSA"]);
+const TEXT_FORMATS_MP4 = new Set(["tx3g", "text", "wvtt"]);
+
+export class TextSubtitleTrack extends SubtitleTrack {
+  constructor(params) {
+    super(params);
+    this.textCodec = params.codecId ?? "";
+  }
+
+  isTextBased() {
+    return true;
+  }
+
+  static isTextCodec(codecId) {
+    return TEXT_CODECS_MATROSKA.has(codecId) || TEXT_FORMATS_MP4.has(codecId);
+  }
+}
+
+export { TEXT_CODECS_MATROSKA, TEXT_FORMATS_MP4 };

package/services/tracks/VideoTrack.js

@@ -0,0 +1,33 @@
+/**
+ * @file Video track — extends ContainerTrack with video-specific container fields.
+ *
+ * Matroska RFC 9559: TrackEntry/Video (PixelWidth/Height, DisplayWidth/Height)
+ * MP4 ISO/IEC 14496-12: tkhd width/height, mdhd timescale, stsd sample entry
+ *   (avc1/hev1/etc.), stss/stts for keyframes, colr for HDR.
+ * No FlagForced / FlagHearingImpaired — those are subtitle-only per spec.
+ */
+
+import { ContainerTrack } from "./ContainerTrack.js";
+
+export class VideoTrack extends ContainerTrack {
+  /**
+   * @param {object} params - See ContainerTrack plus:
+   * @param {number | null} params.width - Coded width (PixelWidth / tkhd width).
+   * @param {number | null} params.height - Coded height.
+   * @param {number | null} params.displayWidth
+   * @param {number | null} params.displayHeight
+   * @param {number | null} params.fps - From container when available (otherwise from ffmpeg banner elsewhere).
+   * @param {boolean} params.isHdr - From container colr / ffmpeg detection later.
+   * @param {number | null} params.bitDepth
+   */
+  constructor(params) {
+    super({ ...params, type: "video" });
+    this.width = Number.isFinite(params.width) ? params.width : null;
+    this.height = Number.isFinite(params.height) ? params.height : null;
+    this.displayWidth = Number.isFinite(params.displayWidth) ? params.displayWidth : null;
+    this.displayHeight = Number.isFinite(params.displayHeight) ? params.displayHeight : null;
+    this.fps = Number.isFinite(params.fps) ? params.fps : null;
+    this.isHdr = params.isHdr === true;
+    this.bitDepth = Number.isFinite(params.bitDepth) ? params.bitDepth : null;
+  }
+}

package/services/tracks/index.js

@@ -0,0 +1,7 @@
+export { ContainerTrack } from "./ContainerTrack.js";
+export { VideoTrack } from "./VideoTrack.js";
+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";