@torrent-tv/proxy 2.9.29 → 2.9.30

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2.9.30
+
+- **New**: The proxy owns subtitle conversion and detects the language from content (OpenSpec change `subtitle-language`). `GET /api/subtitles` now also serves EXTERNAL subtitle files (no `trackIndex`): it reads the file, decodes its encoding (UTF-8 or Windows-1251 — common for Russian `.srt`), converts `.srt`/`.ass`/`.ssa` → WebVTT on the proxy (the browser no longer converts), and reports the language in `X-Subtitle-Language`/`X-Subtitle-Language-Name`. Language is detected with `franc` (n-gram, MIT) restricted to a curated language set — it distinguishes Russian from Ukrainian (and Latin languages) and avoids short-text false positives, returning no header when undetermined. Embedded tracks detect from the first chunk of extracted VTT. Pairs with the server release that fetches VTT from here and applies the filename → content → audio-language priority.
+
 ## 2.9.29
 
 - **New**: Global disk cap with LRU eviction (OpenSpec change `disk-cap`; Disk hygiene Level 1, final piece). Downloaded torrent data was already removed on a 5-min idle TTL and at shutdown, but under pressure it could still fill a small Home Assistant host's disk (which can take down HA itself). The pool now caps total downloaded data — default min(10 GB, half of free disk), overridable with `--max-disk-bytes` (0 disables) — and, when exceeded, evicts whole torrents with no active reader least-recently-used first (checked every 30 s). A torrent that is currently playing is never evicted. (LRU = least-recently-used.)

package/openspec/changes/subtitle-language/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-07-07

package/openspec/changes/subtitle-language/proposal.md

@@ -0,0 +1,50 @@
+# Proposal: Proxy owns subtitle conversion + content-based language detection
+
+## Why
+
+Subtitle language was guessed only from the filename, so a file without a
+language code (e.g. the Enola release's `.srt`) showed "Unknown", and the
+owner specifically does not want Ukrainian and Russian confused. Reliable
+detection needs an n-gram model on the actual text — which belongs on the
+proxy (Node, node_modules, no per-browser payload, and the subtitle bytes are
+right there) rather than in the browser.
+
+## What Changes
+
+- The proxy becomes the single owner of subtitle content: `GET /api/subtitles`
+  now also serves EXTERNAL subtitle files (no `trackIndex`) — it reads the
+  file, decodes its encoding (UTF-8 or Windows-1251, common for Russian
+  `.srt`), and converts `.srt`/`.ass`/`.ssa` → WebVTT here. The browser no
+  longer converts.
+- The proxy detects the language from the full text with `franc` (n-gram /
+  trigram, MIT), restricted to a curated set of plausible subtitle languages
+  (distinguishes ru/uk/bg/sr and Latin languages; avoids short-text false
+  positives like English→Scots), and reports it in `X-Subtitle-Language`
+  (+ `X-Subtitle-Language-Name`). Embedded tracks detect from the first chunk
+  of extracted VTT.
+- The browser sets each track's language by priority: explicit code in the
+  filename / container metadata (author intent) → proxy content detection →
+  the film's audio-track language (forced-signs subs usually match the dub)
+  → Unknown.
+
+## Capabilities
+
+### New Capabilities
+
+- `subtitle-language`: proxy-side subtitle conversion, encoding handling and
+  content-based language detection.
+
+### Modified Capabilities
+
+<!-- track-selection covered embedded extraction; this extends /api/subtitles
+     to external files and adds detection. Its change is unarchived, so this
+     lands as a new capability rather than a delta. -->
+
+## Impact
+
+- proxy: new `services/subtitle-convert.js`, `services/language-detect.js`
+  (franc dep), extended `routes/api/subtitles/get.js`.
+- server: `components/loading/loading.js` fetches VTT from the proxy for
+  external subs (drops client-side conversion) and applies the language
+  priority; browser franc/alphabet detection removed.
+- Pairs with a server release; requires the ha-addon bump.

package/openspec/changes/subtitle-language/specs/subtitle-language/spec.md

@@ -0,0 +1,34 @@
+# subtitle-language — delta spec
+
+## ADDED Requirements
+
+### Requirement: Proxy converts subtitles and reports the language
+`GET /api/subtitles` SHALL serve every subtitle as WebVTT and report the
+detected language in `X-Subtitle-Language` (ISO 639-1) and
+`X-Subtitle-Language-Name`. It SHALL handle two modes: an embedded track
+(`trackIndex` given — extracted via ffmpeg) and an external subtitle file (no
+`trackIndex` — the file is read, its encoding decoded, and `.srt`/`.ass`/
+`.ssa` converted to WebVTT on the proxy). A leading BOM SHALL be stripped and
+Windows-1251 bytes decoded when the file is not valid UTF-8.
+
+#### Scenario: External Russian .srt without a filename code
+- **WHEN** an external `.srt` whose name has no language code is requested
+- **THEN** the response is WebVTT and `X-Subtitle-Language` is `ru`
+
+#### Scenario: Ukrainian is not reported as Russian
+- **WHEN** the subtitle text is Ukrainian
+- **THEN** the detected language is `uk`, not `ru`
+
+#### Scenario: Unsupported format
+- **WHEN** an image-based or unconvertible subtitle is requested
+- **THEN** the proxy responds 422
+
+### Requirement: Detection is confidence-gated
+Language detection SHALL be restricted to a curated set of plausible subtitle
+languages and SHALL return no language (omit the header) when the text is too
+short or undetermined, rather than emitting a wrong guess.
+
+#### Scenario: Too little text
+- **WHEN** the subtitle has only a few characters
+- **THEN** no language header is set (the browser falls back to filename or
+  audio language)

package/openspec/changes/subtitle-language/tasks.md

@@ -0,0 +1,26 @@
+# Tasks: Proxy subtitle conversion + language detection
+
+## 1. Proxy
+
+- [x] 1.1 `services/subtitle-convert.js`: encoding-aware decode (UTF-8/BOM/
+      Windows-1251) + srt/ass/ssa → WebVTT (ported, BOM-stripped)
+- [x] 1.2 `services/language-detect.js`: franc restricted to a curated
+      ISO 639-3→639-1 allowlist; null when undetermined/too short
+- [x] 1.3 `routes/api/subtitles/get.js`: external-file mode (read, decode,
+      convert, detect) + `X-Subtitle-Language(-Name)` on both modes
+- [x] 1.4 franc dependency added to proxy
+- [x] 1.5 Verified: unit-tested convert+detect (ru/uk/en/de, short→null) and
+      the route end-to-end on the real Enola .srt (→ ru, 19 cues)
+
+## 2. Server (browser)
+
+- [x] 2.1 External subs fetch VTT from `/api/subtitles` (no client convert)
+- [x] 2.2 Language priority: filename code → X-Subtitle-Language → audio-track
+      language → und; embedded track uses metadata → header → audio
+- [x] 2.3 Removed the client-side convertSubtitleToVtt call + dead import
+
+## 3. Release
+
+- [ ] 3.1 Proxy publish (OTP) + ha-addon bump + server patch
+- [ ] 3.2 Field-check: Enola external .srt labels "Russian"; a Ukrainian sub
+      labels "Ukrainian"; embedded tracks keep their metadata language

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.9.29",
+  "version": "2.9.30",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {
@@ -26,6 +26,7 @@
     "commander": "^12.1.0",
     "fastify": "^5.8.5",
     "ffmpeg-static": "^5.3.0",
+    "franc": "^6.2.0",
     "get-port": "^7.1.0",
     "node-datachannel": "^0.32.0",
     "webtorrent": "^2.8.4",

package/routes/api/subtitles/get.js

@@ -1,15 +1,17 @@
 /**
- * Extract an embedded text subtitle track from a torrent file as WebVTT.
+ * Serve a subtitle as WebVTT, with the detected language reported in the
+ * `X-Subtitle-Language` / `X-Subtitle-Language-Name` response headers. Two
+ * modes:
  *
- * GET /api/subtitles?sourceKey=...&fileIndex=N&trackIndex=M
+ *   - Embedded track:  ?sourceKey&fileIndex=<video>&trackIndex=<sub stream N>
+ *     ffmpeg extracts the text subtitle stream (`-map 0:s:N -f webvtt`),
+ *     streamed as it is produced.
+ *   - External file:   ?sourceKey&fileIndex=<subtitle file>   (no trackIndex)
+ *     the subtitle FILE is read, decoded (UTF-8/Windows-1251), and converted
+ *     (.srt/.ass/.ssa → WebVTT) here on the proxy.
  *
- * `trackIndex` is the TYPE-RELATIVE subtitle stream index (what ffmpeg's
- * `-map 0:s:M` selects), as reported by the playback plan's
- * `subtitleTracks[].index`.
- *
- * The response streams while ffmpeg produces it. Extraction has to read the
- * file up to the last cue, so on a cold torrent this drives (and waits for)
- * the sequential download — callers must use a generous timeout.
+ * The proxy owns subtitle conversion + language detection so no model or
+ * converter ships to the browser and detection sees the full text.
  *
  * @param {import("fastify").FastifyRequest} req
  * @param {import("fastify").FastifyReply} reply
@@ -23,19 +25,35 @@
  */
 
 import { spawn } from "node:child_process";
+import { convertSubtitleToVtt, decodeSubtitleBytes } from "../../../services/subtitle-convert.js";
+import { detectLanguage } from "../../../services/language-detect.js";
 
-// Safety cap: no extraction may outlive this (a dead swarm would otherwise
-// hold the ffmpeg process forever).
+// Safety cap: no embedded extraction may outlive this.
 const EXTRACTION_TIMEOUT_MS = 30 * 60 * 1000;
+// External subtitle files are small; cap the read to guard against a bad index.
+const EXTERNAL_MAX_BYTES = 8 * 1024 * 1024;
+
+/** Set the detected-language response headers (no-op when detection failed). */
+function setLanguageHeaders(reply, lang) {
+  if (lang && typeof lang.code === "string") {
+    reply.raw.setHeader("X-Subtitle-Language", lang.code);
+    if (typeof lang.name === "string") {
+      reply.raw.setHeader("X-Subtitle-Language-Name", encodeURIComponent(lang.name));
+    }
+    // These are custom headers on a cross-origin fetch — expose them.
+    reply.raw.setHeader("Access-Control-Expose-Headers", "X-Subtitle-Language, X-Subtitle-Language-Name");
+  }
+}
 
 export async function handleApiSubtitlesGet(req, reply, { sourceRegistry, torrentPool, ffmpegBin, localBaseUrl }) {
   const query = req.query ?? {};
   const sourceKey = typeof query.sourceKey === "string" ? query.sourceKey.trim() : "";
   const fileIndex = Number(query.fileIndex);
+  const hasTrackIndex = query.trackIndex !== undefined && query.trackIndex !== "";
   const trackIndex = Number(query.trackIndex);
 
-  if (!sourceKey || !Number.isInteger(fileIndex) || fileIndex < 0 || !Number.isInteger(trackIndex) || trackIndex < 0) {
-    return reply.code(400).send({ error: "sourceKey, fileIndex and trackIndex are required." });
+  if (!sourceKey || !Number.isInteger(fileIndex) || fileIndex < 0) {
+    return reply.code(400).send({ error: "sourceKey and fileIndex are required." });
   }
 
   const sourceRecord = sourceRegistry.get(sourceKey);
@@ -43,28 +61,47 @@ export async function handleApiSubtitlesGet(req, reply, { sourceRegistry, torren
     return reply.code(404).send({ error: "Source key was not found." });
   }
   const torrent = await torrentPool.getTorrent(sourceRecord.sourceType, sourceRecord.source);
-  if (!torrent.files[fileIndex]) {
+  const file = torrent.files[fileIndex];
+  if (!file) {
     return reply.code(404).send({ error: "File index was not found in torrent." });
   }
 
+  // ---- External subtitle FILE (no trackIndex) -----------------------------
+  if (!hasTrackIndex) {
+    const name = typeof file.name === "string" ? file.name : "";
+    const ext = name.slice(name.lastIndexOf(".")).toLowerCase();
+    const release = 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 reply.code(422).send({ error: `Unsupported subtitle format: ${ext}` });
+      }
+      setLanguageHeaders(reply, detectLanguage(text));
+      reply.header("content-type", "text/vtt; charset=utf-8");
+      reply.header("cache-control", "no-store");
+      return reply.send(vtt);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return reply.code(502).send({ error: `Could not read subtitle file: ${message}` });
+    } finally {
+      release();
+    }
+  }
+
+  // ---- Embedded track (ffmpeg extraction, streamed) -----------------------
+  if (!Number.isInteger(trackIndex) || trackIndex < 0) {
+    return reply.code(400).send({ error: "trackIndex must be a non-negative integer." });
+  }
+
   const inputUrl = new URL("/stream", `${localBaseUrl}/`);
   inputUrl.searchParams.set("sourceKey", sourceKey);
   inputUrl.searchParams.set("fileIndex", String(fileIndex));
 
   const ffmpeg = spawn(
     ffmpegBin,
-    [
-      "-hide_banner",
-      "-loglevel",
-      "error",
-      "-i",
-      inputUrl.toString(),
-      "-map",
-      `0:s:${trackIndex}`,
-      "-f",
-      "webvtt",
-      "pipe:1"
-    ],
+    ["-hide_banner", "-loglevel", "error", "-i", inputUrl.toString(), "-map", `0:s:${trackIndex}`, "-f", "webvtt", "pipe:1"],
     { stdio: ["ignore", "pipe", "pipe"], windowsHide: true }
   );
 
@@ -81,8 +118,6 @@ export async function handleApiSubtitlesGet(req, reply, { sourceRegistry, torren
     }
   }, EXTRACTION_TIMEOUT_MS);
   killTimer.unref?.();
-
-  // Stop extracting when the client goes away.
   req.raw.on("close", () => {
     clearTimeout(killTimer);
     if (!ffmpeg.killed) {
@@ -90,8 +125,6 @@ export async function handleApiSubtitlesGet(req, reply, { sourceRegistry, torren
     }
   });
 
-  // Distinguish "bad track / not text-based" (ffmpeg dies before any output)
-  // from a mid-stream failure (headers already sent; the stream just ends).
   const firstChunk = await new Promise((resolve) => {
     let settled = false;
     const settle = (value) => {
@@ -112,6 +145,9 @@ export async function handleApiSubtitlesGet(req, reply, { sourceRegistry, torren
       .send({ error: `Subtitle track could not be extracted: ${stderr.trim() || "no output from ffmpeg"}` });
   }
 
+  // Detect language from the first chunk of the produced VTT (embedded tracks
+  // frequently lack a language tag in their container metadata).
+  setLanguageHeaders(reply, detectLanguage(String(firstChunk)));
   reply.raw.writeHead(200, {
     "content-type": "text/vtt; charset=utf-8",
     "cache-control": "no-store",
@@ -127,3 +163,29 @@ export async function handleApiSubtitlesGet(req, reply, { sourceRegistry, torren
   reply.raw.end();
   return reply;
 }
+
+/**
+ * Read a torrent file fully into a Buffer, bounded by `maxBytes`.
+ *
+ * @param {{ createReadStream: () => import("node:stream").Readable, length?: number }} file
+ * @param {number} maxBytes
+ * @returns {Promise<Buffer>}
+ */
+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 the size cap"));
+        return;
+      }
+      chunks.push(chunk);
+    });
+    stream.on("end", () => resolve(Buffer.concat(chunks)));
+    stream.on("error", reject);
+  });
+}

package/services/language-detect.js

@@ -0,0 +1,73 @@
+/**
+ * @file Content-based subtitle language detection (proxy side).
+ *
+ * Uses `franc` (n-gram / trigram frequency against per-language reference
+ * profiles — MIT). Runs on the proxy where the full subtitle text and
+ * node_modules live, so no detection model ships to the browser. Detection is
+ * restricted to a curated set of plausible subtitle languages via franc's
+ * `only` option: this both maps ISO 639-3 → ISO 639-1 + English name and
+ * avoids exotic false positives on short text (e.g. English mis-detected as
+ * Scots). Returns null when franc is not confident (too little text, or
+ * undetermined).
+ */
+
+import { franc } from "franc";
+
+/** ISO 639-3 (franc output) → { code: ISO 639-1 / BCP-47, name }. Curated allowlist. */
+const LANG_3_TO_1 = {
+  eng: { code: "en", name: "English" },
+  rus: { code: "ru", name: "Russian" },
+  ukr: { code: "uk", name: "Ukrainian" },
+  bel: { code: "be", name: "Belarusian" },
+  jpn: { code: "ja", name: "Japanese" },
+  kor: { code: "ko", name: "Korean" },
+  cmn: { code: "zh", name: "Chinese" },
+  spa: { code: "es", name: "Spanish" },
+  fra: { code: "fr", name: "French" },
+  deu: { code: "de", name: "German" },
+  ita: { code: "it", name: "Italian" },
+  por: { code: "pt", name: "Portuguese" },
+  pol: { code: "pl", name: "Polish" },
+  nld: { code: "nl", name: "Dutch" },
+  arb: { code: "ar", name: "Arabic" },
+  tur: { code: "tr", name: "Turkish" },
+  vie: { code: "vi", name: "Vietnamese" },
+  tha: { code: "th", name: "Thai" },
+  hin: { code: "hi", name: "Hindi" },
+  ind: { code: "id", name: "Indonesian" },
+  zlm: { code: "ms", name: "Malay" },
+  ces: { code: "cs", name: "Czech" },
+  slk: { code: "sk", name: "Slovak" },
+  ron: { code: "ro", name: "Romanian" },
+  hun: { code: "hu", name: "Hungarian" },
+  srp: { code: "sr", name: "Serbian" },
+  hrv: { code: "hr", name: "Croatian" },
+  bul: { code: "bg", name: "Bulgarian" },
+  ell: { code: "el", name: "Greek" },
+  heb: { code: "he", name: "Hebrew" },
+  dan: { code: "da", name: "Danish" },
+  fin: { code: "fi", name: "Finnish" },
+  nob: { code: "no", name: "Norwegian" },
+  swe: { code: "sv", name: "Swedish" },
+  fas: { code: "fa", name: "Persian" }
+};
+
+const ONLY = Object.keys(LANG_3_TO_1);
+
+/**
+ * Best-effort detect the language of subtitle text.
+ *
+ * @param {string} text - Decoded subtitle text (VTT/SRT/ASS — franc ignores markup well enough).
+ * @returns {{ code: string, name: string } | null} Detected language, or null when uncertain.
+ */
+export function detectLanguage(text) {
+  if (typeof text !== "string" || text.trim().length < 15) {
+    return null;
+  }
+  // Restrict to plausible subtitle languages; require a little text.
+  const iso3 = franc(text, { only: ONLY, minLength: 15 });
+  if (iso3 === "und") {
+    return null;
+  }
+  return LANG_3_TO_1[iso3] ?? null;
+}

package/services/subtitle-convert.js

@@ -0,0 +1,150 @@
+/**
+ * @file Subtitle conversion (proxy side).
+ *
+ * Decodes subtitle file bytes (encoding-aware) and converts SubRip (.srt) and
+ * ASS/SSA (.ass/.ssa) to WebVTT so the browser can attach them to a `<track>`
+ * without any client-side conversion. The proxy owns subtitle conversion so it
+ * can also run language detection where the full text is available.
+ */
+
+/**
+ * Decode subtitle bytes to text. Prefers UTF-8 (honouring a BOM); if the UTF-8
+ * decode yields many replacement characters the bytes are re-decoded as
+ * Windows-1251 (very common for Russian .srt files) — otherwise both display
+ * and language detection would see mojibake.
+ *
+ * @param {Buffer | Uint8Array} bytes
+ * @returns {string}
+ */
+export function decodeSubtitleBytes(bytes) {
+  const buf = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  // UTF-8 BOM → definitely UTF-8.
+  if (buf.length >= 3 && buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf) {
+    return new TextDecoder("utf-8").decode(buf);
+  }
+  const utf8 = new TextDecoder("utf-8").decode(buf);
+  const replacements = (utf8.match(/�/g) || []).length;
+  // >0.5% replacement chars ⇒ not valid UTF-8; try the common legacy Cyrillic
+  // codepage. TextDecoder supports windows-1251 with a full-ICU Node build.
+  if (replacements > Math.max(2, utf8.length * 0.005)) {
+    try {
+      return new TextDecoder("windows-1251").decode(buf);
+    } catch {
+      // Decoder unavailable — fall back to the UTF-8 attempt.
+    }
+  }
+  return utf8;
+}
+
+/** Strip a leading UTF-8 BOM so it never leaks into the WEBVTT signature or first cue. */
+function stripBom(text) {
+  return typeof text === "string" && text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
+function srtTsToVtt(ts) {
+  return ts.replace(",", ".");
+}
+
+/**
+ * Convert SubRip (.srt) text to WebVTT.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function srtToVtt(text) {
+  const lines = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+  const out = ["WEBVTT", ""];
+  for (const line of lines) {
+    const m = line.match(/^(\d{2}:\d{2}:\d{2},\d{3})\s*-->\s*(\d{2}:\d{2}:\d{2},\d{3})(.*)?$/);
+    out.push(m ? `${srtTsToVtt(m[1])} --> ${srtTsToVtt(m[2])}${m[3] ?? ""}` : line);
+  }
+  return out.join("\n");
+}
+
+function assTsToVtt(ts) {
+  const m = ts.match(/^(\d+):(\d{2}):(\d{2})\.(\d{2})$/);
+  if (!m) {
+    return "00:00:00.000";
+  }
+  const ms = (parseInt(m[4], 10) * 10).toString().padStart(3, "0");
+  return `${m[1].padStart(2, "0")}:${m[2]}:${m[3]}.${ms}`;
+}
+
+function stripAssTags(text) {
+  return text
+    .replace(/\{[^}]*\}/g, "")
+    .replace(/\\N/g, "\n")
+    .replace(/\\n/g, "\n")
+    .replace(/\\h/g, " ")
+    .trim();
+}
+
+/**
+ * Convert ASS/SSA text to WebVTT (only the [Events] section; styling dropped).
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function assToVtt(text) {
+  const lines = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+  let inEvents = false;
+  let formatCols = null;
+  const cues = [];
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === "[Events]") {
+      inEvents = true;
+      continue;
+    }
+    if (trimmed.startsWith("[") && trimmed.endsWith("]") && inEvents) {
+      inEvents = false;
+      continue;
+    }
+    if (!inEvents) {
+      continue;
+    }
+    if (trimmed.startsWith("Format:")) {
+      formatCols = trimmed.slice("Format:".length).split(",").map((c) => c.trim().toLowerCase());
+      continue;
+    }
+    if (trimmed.startsWith("Dialogue:") && formatCols) {
+      const parts = trimmed.slice("Dialogue:".length).split(",");
+      const startIdx = formatCols.indexOf("start");
+      const endIdx = formatCols.indexOf("end");
+      const textIdx = formatCols.indexOf("text");
+      if (startIdx < 0 || endIdx < 0 || textIdx < 0) {
+        continue;
+      }
+      const cueText = stripAssTags(parts.slice(textIdx).join(","));
+      if (!cueText) {
+        continue;
+      }
+      cues.push(`${assTsToVtt((parts[startIdx] ?? "").trim())} --> ${assTsToVtt((parts[endIdx] ?? "").trim())}\n${cueText}`);
+    }
+  }
+  return cues.length === 0 ? "WEBVTT\n" : `WEBVTT\n\n${cues.join("\n\n")}`;
+}
+
+/**
+ * Convert subtitle text to WebVTT by file extension. Returns null for formats
+ * that cannot be converted in-place (image-based .sup, ambiguous .sub, .ttml).
+ *
+ * @param {string} text
+ * @param {string} ext - Lowercase extension including the dot, e.g. ".srt".
+ * @returns {string | null}
+ */
+export function convertSubtitleToVtt(text, ext) {
+  const clean = stripBom(text);
+  switch (ext) {
+    case ".vtt":
+    case ".webvtt":
+      return clean.trimStart().startsWith("WEBVTT") ? clean : `WEBVTT\n\n${clean}`;
+    case ".srt":
+      return srtToVtt(clean);
+    case ".ass":
+    case ".ssa":
+      return assToVtt(clean);
+    default:
+      return null;
+  }
+}