@torrent-tv/proxy 2.9.29 → 2.9.31

package/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 2.9.31
+
+- **New**: Realtime transcode budget — startup resolution + preset selection (OpenSpec change `transcode-quality`, part 2.1). For the software encoder the proxy now picks the output RESOLUTION as well as the libx264 preset from the startup benchmark: the client-requested box (capped to the source, never upscaled) is the ceiling, and the proxy chooses the highest resolution rung at or below it that the benchmark predicts encodes faster than realtime (with the existing margin), then the best preset at that resolution. On a weak host this downscales (e.g. a 720p60→30 stream that ran at ~0.9× on a Home Assistant box now encodes at ~480p in realtime) instead of dropping into sub-realtime playback with constant stalls. Capable hosts keep full resolution and spend the headroom on a higher-quality preset; hardware encoders and the no-benchmark case are unchanged. Also fixed the realtime-need calculation to use the session's actual output frame rate instead of the fixed 24 fps constant (it under-counted for 25/30 fps content). The chosen encode resolution is logged (`enc=WxH@fps budget=on`). This scales down from the orientation-independent ceiling the browser now sends (server 0.8.43).
+- **New**: Realtime transcode budget — runtime downswitch (OpenSpec change `transcode-quality`, part 2.2). If a software transcode runs below realtime for a sustained window (ffmpeg `speed` < ~0.95× for ~15 s), the proxy steps the resolution one rung down the ladder and restarts the encode at the segment the viewer is on, so a stream that starts fine but bogs down on a heavy passage recovers instead of stalling. It first checks the bottleneck: if the torrent download can't sustain the source's byte rate (and the file isn't fully downloaded), the limit is the download, not the encoder — the proxy logs that and does NOT degrade quality. Conservative guards prevent thrash: a 30 s post-action cooldown, at most 3 downshifts, a resolution floor, the slow window reset on every (re)start, and no automatic upswitch yet. The switch point uses a hard encoder restart (a brief blip is possible there; a seamless discontinuity/parallel tier is a later refinement). Logged as `[budget] … CPU-bound speed=… → downscale to WxH` or `… download-limited; not downscaling`.
+
+## 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/openspec/changes/transcode-quality/specs/transcode-quality/spec.md

@@ -35,3 +35,62 @@ chosen encoder places keyframes:
 - **WHEN** the source frame rate cannot be probed on the software path
 - **THEN** the output falls back to the default rate and playback still
   segments correctly
+
+### Requirement: Software encode fits a realtime budget at startup
+
+For the software encoder, the proxy SHALL choose the output resolution and
+libx264 preset a startup benchmark predicts this host can encode faster than
+realtime (with a margin), rather than always encoding at the client-requested
+resolution. The client-requested box, capped to the source resolution (never
+upscaled), is the ceiling; the proxy SHALL pick the highest resolution rung at
+or below that ceiling that clears the realtime margin, then the highest-quality
+preset that still clears it at that resolution. When even the lowest rung
+cannot clear the margin, the proxy SHALL use the lowest rung (best effort). The
+realtime need SHALL be computed from the session's actual output frame rate.
+Hardware encoders and the no-benchmark case SHALL keep the ceiling resolution
+and the default preset.
+
+#### Scenario: Weak host, source above realtime capacity
+- **WHEN** the software benchmark shows the host cannot encode the source-capped
+  resolution faster than realtime (e.g. 720p60→30 that runs below 1×)
+- **THEN** the proxy downscales to the highest ladder rung that clears the
+  realtime margin (e.g. 480p) instead of encoding sub-realtime at full size
+
+#### Scenario: Capable host
+- **WHEN** the benchmark shows ample headroom at the ceiling resolution
+- **THEN** the proxy keeps the ceiling resolution and spends the headroom on a
+  higher-quality (slower) preset
+
+#### Scenario: Hardware encoder
+- **WHEN** a hardware encoder is selected
+- **THEN** no benchmark-based downscale is applied and the ceiling resolution
+  is used
+
+### Requirement: Software encode downswitches at runtime when CPU-bound
+
+The proxy SHALL, for the software encoder, step the output resolution one rung
+down the ladder and restart the encode at the segment currently being watched
+when a transcode runs below realtime for a sustained window. Before downscaling
+it SHALL determine whether the limit is the encoder or a download-starved
+input — comparing the torrent download rate with the source's average byte rate
+(a fully-downloaded file is never download-bound) — and SHALL NOT downscale when
+the limit is the download (it SHALL log that instead). The downswitch SHALL be
+bounded by a sustained-slow window, a post-action cooldown, a maximum number of
+steps, and a resolution floor, and SHALL reset its slow window on every encode
+(re)start. There SHALL be no automatic upswitch in this version.
+
+#### Scenario: Sustained CPU-bound transcode
+- **WHEN** a software transcode's encoder speed stays below realtime for the
+  sustained window while the input download keeps up
+- **THEN** the proxy downscales one rung and restarts at the current segment,
+  up to the step cap / resolution floor
+
+#### Scenario: Download-limited, not CPU-limited
+- **WHEN** the encoder speed is below realtime but the torrent cannot download
+  the source's byte rate and the file is not fully downloaded
+- **THEN** the proxy does not downscale and logs that the download is the limit
+
+#### Scenario: No thrash after a switch
+- **WHEN** a downswitch (or a viewer seek) has just restarted the encode
+- **THEN** the slow window is reset and no further downswitch occurs until a new
+  sustained-slow window elapses after the cooldown

package/openspec/changes/transcode-quality/tasks.md

@@ -11,11 +11,27 @@
 - [x] 1.3 Unit-verify fps choice and fps↔GOP consistency (25→100, 24→96,
       default→96); syntax checks
 
-## 2. Realtime budget (planned)
-
-- [ ] 2.1 Benchmark picks encoder/preset/resolution/fps within a realtime
-      margin; downscale instead of refuse
-- [ ] 2.2 Runtime `speed<1` watch → restart with a lighter profile
+## 2. Realtime budget
+
+- [x] 2.1 Startup: benchmark picks resolution + preset within a realtime
+      margin; downscale below the client-target ceiling instead of refusing
+      (`chooseSoftwareEncodeSettings`/`buildResolutionLadder` in hwaccel;
+      `#chooseEncodeBudget` + `encodeWidth`/`encodeHeight` in the session
+      manager; fixed the needed-pixels calc to use the session's `outputFps`
+      not the fixed `TRANSCODE_FPS`). Verified on the FIFA host profile
+      (720p60→480p) + strong/weak/no-benchmark profiles.
+- [x] 2.2 Runtime `speed<1` watch → step down the resolution ladder + restart
+      at the current segment (hard-restart tier). Gate on CPU-bound only:
+      compare `getFileStats().downloadSpeed` with the source byte-rate so a
+      download-starved input is NOT misread as an encoder limit (don't degrade
+      quality for a download bottleneck — log it instead). Hysteresis +
+      cooldown + floor + max steps; slow window reset on every (re)start; no
+      upswitch in v1 (oscillation risk). `#enforceRealtimeBudget` +
+      `#classifyTranscodeBound` + `#applyBudgetDownshift` in the session
+      manager; `getSourceStats` injected from server.js.
+      NOTE (follow-up 2.2b): seamless switch via `EXT-X-DISCONTINUITY` /
+      parallel encoder tier keyed by host resources — the hard restart can blip
+      at the switch point.
 - [ ] 2.3 `-maxrate`/`-bufsize`
 
 ## 3. HDR tone mapping (planned)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.9.29",
+  "version": "2.9.31",
   "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/server.js

@@ -117,7 +117,21 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin,
     localBindHost: host,
     localPort: selectedPort,
     videoEncoder,
-    softwarePresetBenchmark
+    softwarePresetBenchmark,
+    // Live download stats accessor for the realtime budget: lets it tell a
+    // CPU-bound transcode from a download-starved input before downscaling.
+    getSourceStats: async (sourceKey, fileIndex) => {
+      const record = sourceRegistry.get(sourceKey);
+      if (!record) {
+        return null;
+      }
+      try {
+        const torrent = await torrentPool.getTorrent(record.sourceType, record.source);
+        return torrentPool.getFileStats(torrent, Number.isInteger(fileIndex) ? fileIndex : null);
+      } catch {
+        return null;
+      }
+    }
   });
   const playbackPlanner = createPlaybackPlanner({
     ffmpegBin,

package/services/hls-session-manager.js

@@ -15,7 +15,13 @@ import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
 import { logger } from "../utils/logger.js";
-import { softwareDescriptor, pickSoftwarePreset, TRANSCODE_FPS, chooseOutputFps } from "./hwaccel.js";
+import {
+  softwareDescriptor,
+  chooseSoftwareEncodeSettings,
+  pickSoftwarePreset,
+  TRANSCODE_FPS,
+  chooseOutputFps
+} from "./hwaccel.js";
 
 const PLAYLIST_FILE_NAME = "index.m3u8";
 const SEGMENT_FILE_NAME_PATTERN = /^segment-\d{5}\.ts$/;
@@ -36,6 +42,30 @@ const RESTART_COOLDOWN_MS = 4_000;
 // segment fetch, so it never expires mid-watch.
 const DEFAULT_SESSION_TTL_MS = 120 * 1000;
 const DEFAULT_STARTUP_WAIT_MS = 5_000;
+// Realtime budget — runtime downswitch (software encoder only). Periodically
+// check each active software-transcode session's ffmpeg `speed`; when it stays
+// below realtime for a sustained window AND the input is not download-starved
+// (so the limit is the encoder, not the torrent), step down one resolution rung
+// and restart at the current segment. Conservative so it never thrashes: a long
+// sustained window, a post-action cooldown, a step cap, and no upswitch (v1).
+const BUDGET_CHECK_INTERVAL_MS = 5_000;
+// Speed below this (cumulative ffmpeg average) counts as "slow"; recovery to
+// realtime resets the slow window (hysteresis).
+const BUDGET_SPEED_SLOW = 0.95;
+const BUDGET_SPEED_OK = 1.0;
+// Slow must persist this long before a downshift (absorbs warm-up + brief
+// complex scenes; the cumulative average won't dip this long unless the host
+// genuinely can't keep up).
+const BUDGET_SUSTAINED_MS = 15_000;
+// After a downshift, wait this long before another (lets the new profile settle
+// and a fresh cumulative average build).
+const BUDGET_ACTION_COOLDOWN_MS = 30_000;
+// Never step down more than this many rungs below the startup choice.
+const BUDGET_MAX_DOWNSHIFTS = 3;
+// The input counts as "keeping up" when the torrent downloads at least this
+// multiple of the source's average byte rate. Below it (and not yet fully
+// downloaded), a low speed is download-bound, not CPU-bound → do NOT downscale.
+const BUDGET_DOWNLOAD_OK_FACTOR = 1.0;
 const MICROSECONDS_PER_SECOND = 1_000_000;
 const PROGRESS_LOG_INTERVAL_MS = 5_000;
 // Read segment files in large blocks so the body is delivered to the data
@@ -625,10 +655,15 @@ export class HlsSessionManager {
     sessionTtlMs = DEFAULT_SESSION_TTL_MS,
     startupWaitMs = DEFAULT_STARTUP_WAIT_MS,
     videoEncoder = null,
-    softwarePresetBenchmark = null
+    softwarePresetBenchmark = null,
+    getSourceStats = null
   }) {
     this.enabled = Boolean(enabled);
     this.ffmpegBin = ffmpegBin;
+    // Optional async accessor for a source's live download stats, used by the
+    // realtime budget to tell a CPU limit from a download-starved input:
+    // (sourceKey, fileIndex) => Promise<{ downloadSpeed, fileLength, fileProgress } | null>.
+    this.getSourceStats = typeof getSourceStats === "function" ? getSourceStats : null;
     // Detected H.264 encoder descriptor (hardware or software). Defaults to
     // software libx264 when no detection result is supplied. May be downgraded
     // to software at runtime if a hardware encode fails.
@@ -647,6 +682,13 @@ export class HlsSessionManager {
       void this.cleanupExpired();
     }, CLEANUP_INTERVAL_MS);
     this.cleanupTimer.unref();
+    // Realtime-budget monitor: only meaningful for the software encoder with a
+    // benchmark (the only path that can pick/step resolution). Cheap no-op scan
+    // otherwise.
+    this.budgetTimer = setInterval(() => {
+      void this.#enforceRealtimeBudget();
+    }, BUDGET_CHECK_INTERVAL_MS);
+    this.budgetTimer.unref();
   }
 
   /**
@@ -787,17 +829,25 @@ export class HlsSessionManager {
     const usingKeyframeBoundaries = hasDuration && !transcodeVideo && Array.isArray(keyframeTimes);
     const segmentCount = segmentBoundaries.length > 1 ? segmentBoundaries.length - 1 : 0;
 
-    // Pick the highest-quality software preset that still encodes the actual
-    // (source-capped) output resolution faster than realtime. Null for hardware
-    // encoders or when the source size / benchmark is unavailable — buildVideoArgs
-    // then uses its static default preset.
-    const softwarePreset = this.#chooseSoftwarePreset({
+    // Realtime budget (software encoder): pick the output resolution + libx264
+    // preset this host can encode faster than realtime. On a weak host this
+    // downscales below the client target (the orientation-independent ceiling)
+    // instead of dropping into sub-realtime playback. Null for hardware
+    // encoders or when the source size / benchmark is unavailable — the encode
+    // then keeps the client target box and buildVideoArgs's default preset.
+    const encodeBudget = this.#chooseEncodeBudget({
       transcodeVideo,
       targetWidth: normalizedTargetWidth,
       targetHeight: normalizedTargetHeight,
       sourceWidth,
-      sourceHeight
+      sourceHeight,
+      outputFps
     });
+    const softwarePreset = encodeBudget?.preset ?? null;
+    // Effective encode box: the budget's downscaled resolution when applied,
+    // otherwise the client target (0 = keep source, handled by buildVideoArgs).
+    const encodeWidth = encodeBudget?.width ?? normalizedTargetWidth;
+    const encodeHeight = encodeBudget?.height ?? normalizedTargetHeight;
 
     const session = {
       id: sessionId,
@@ -818,8 +868,24 @@ export class HlsSessionManager {
       transcodeAudio,
       audioTrackIndex: normalizedAudioTrack,
       outputFps,
+      // Client-requested target box (the orientation-independent ceiling). Kept
+      // for the session key and reference; the actual encode uses encodeWidth/
+      // encodeHeight, which the realtime budget may have downscaled below this.
       targetWidth: normalizedTargetWidth,
       targetHeight: normalizedTargetHeight,
+      // Effective encode resolution handed to ffmpeg (budget-selected on weak
+      // software hosts, else the client target). 0 = keep source.
+      encodeWidth,
+      encodeHeight,
+      // Realtime-budget runtime state (software encoder only). The ladder is the
+      // resolution rungs from the ceiling down; rungIndex is the current rung.
+      // The monitor steps rungIndex down when the encoder is sustainedly
+      // CPU-bound and restarts ffmpeg at the current segment.
+      budgetLadder: encodeBudget?.ladder ?? null,
+      budgetRungIndex: Number.isInteger(encodeBudget?.rungIndex) ? encodeBudget.rungIndex : 0,
+      budgetDownshifts: 0,
+      budgetSlowSince: 0,
+      budgetLastActionAt: 0,
       sourceWidth,
       sourceHeight,
       // Container start time (seconds); subtracted on the copy path so the
@@ -866,6 +932,9 @@ export class HlsSessionManager {
         `branch=${transcodeVideo ? "A(reencode,fixed-gop)" : "B(copy,copyts)"} ` +
         `seg=${usingKeyframeBoundaries ? "keyframe" : "uniform"} ` +
         `${sourceWidth && sourceHeight ? `src=${sourceWidth}x${sourceHeight} ` : ""}` +
+        // Effective encode resolution and whether the realtime budget downscaled
+        // it below the client target (the orientation-independent ceiling).
+        `${transcodeVideo && encodeBudget ? `enc=${encodeWidth}x${encodeHeight}@${outputFps} budget=on ` : ""}` +
         `${sourceStartTime ? `start=${sourceStartTime.toFixed(3)} ` : ""}` +
         `duration=${hasDuration ? formatSeconds(durationSeconds) : "unknown"} segments=${segmentCount}`
     );
@@ -971,25 +1040,190 @@ export class HlsSessionManager {
   }
 
   /**
-   * Choose the libx264 preset for a software video transcode: the highest
-   * quality the startup benchmark says this host can encode at the actual
-   * (source-capped) output resolution faster than realtime. Returns null when
-   * not applicable (no video transcode, hardware encoder, or missing
-   * benchmark/source size) — buildVideoArgs then uses its default preset.
+   * Realtime budget (software encoder only): choose the output resolution AND
+   * libx264 preset this host can encode faster than realtime, from the startup
+   * benchmark. The ceiling is the client-requested box capped to the source
+   * (never upscaled); the budget picks the highest resolution rung at or below
+   * that ceiling that clears realtime × margin, then the best preset at that
+   * resolution. On a weak host this downscales below the client target instead
+   * of dropping into sub-realtime playback. Returns null when not applicable
+   * (no video transcode, hardware encoder, or missing benchmark/source size) —
+   * the encode then keeps the ceiling resolution and the default preset.
    *
-   * @param {{ transcodeVideo: boolean, targetWidth: number, targetHeight: number, sourceWidth: number | null, sourceHeight: number | null }} params
-   * @returns {string | null}
+   * @param {{ transcodeVideo: boolean, targetWidth: number, targetHeight: number, sourceWidth: number | null, sourceHeight: number | null, outputFps: number }} params
+   * @returns {{ width: number, height: number, preset: string } | null}
    */
-  #chooseSoftwarePreset({ transcodeVideo, targetWidth, targetHeight, sourceWidth, sourceHeight }) {
+  #chooseEncodeBudget({ transcodeVideo, targetWidth, targetHeight, sourceWidth, sourceHeight, outputFps }) {
     if (!transcodeVideo || this.videoEncoder?.kind !== "software" || !this.softwarePresetBenchmark) {
       return null;
     }
-    const out = computeOutputDimensions(targetWidth, targetHeight, sourceWidth, sourceHeight);
-    if (!out) {
+    const ceiling = computeOutputDimensions(targetWidth, targetHeight, sourceWidth, sourceHeight);
+    if (!ceiling) {
+      return null;
+    }
+    return chooseSoftwareEncodeSettings(this.softwarePresetBenchmark, { width: ceiling.w, height: ceiling.h }, outputFps);
+  }
+
+  /**
+   * Parse ffmpeg's `speed` progress value (e.g. "0.903x", "1.6x", "N/A") into a
+   * number. Returns null when it cannot be parsed (no data yet).
+   *
+   * @param {string} value
+   * @returns {number | null}
+   */
+  #parseSpeed(value) {
+    if (typeof value !== "string" || value.length === 0) {
       return null;
     }
-    const pixelsPerSecNeeded = out.w * out.h * TRANSCODE_FPS;
-    return pickSoftwarePreset(this.softwarePresetBenchmark, pixelsPerSecNeeded);
+    const numeric = Number.parseFloat(value);
+    return Number.isFinite(numeric) && numeric > 0 ? numeric : null;
+  }
+
+  /**
+   * Realtime budget monitor (software encoder only). For each active
+   * software-transcode session, watch the encoder's cumulative `speed`: when it
+   * stays below realtime for a sustained window AND the input is not
+   * download-starved (so the limit is the encoder, not the torrent), step the
+   * resolution one rung down the ladder and restart the encode at the current
+   * segment. Conservative: sustained window, post-action cooldown, a step cap,
+   * and a resolution floor (the last ladder rung). No upswitch in v1.
+   *
+   * @returns {Promise<void>}
+   */
+  async #enforceRealtimeBudget() {
+    if (this.videoEncoder?.kind !== "software") {
+      return;
+    }
+    const now = Date.now();
+    for (const session of this.sessionsById.values()) {
+      if (
+        !session ||
+        session.state === "disposed" ||
+        session.state === "failed" ||
+        !session.transcodeVideo ||
+        !Array.isArray(session.budgetLadder) ||
+        session.budgetLadder.length < 2
+      ) {
+        continue;
+      }
+      // Already at the floor or out of steps — nothing more to give.
+      if (
+        session.budgetRungIndex >= session.budgetLadder.length - 1 ||
+        session.budgetDownshifts >= BUDGET_MAX_DOWNSHIFTS
+      ) {
+        continue;
+      }
+      const speed = this.#parseSpeed(session.progress?.speed);
+      if (speed === null) {
+        continue; // no measurement yet
+      }
+      if (speed >= BUDGET_SPEED_OK) {
+        session.budgetSlowSince = 0; // recovered — reset the slow window
+        continue;
+      }
+      if (speed >= BUDGET_SPEED_SLOW) {
+        continue; // in the hysteresis band; neither slow nor ok
+      }
+      // speed < BUDGET_SPEED_SLOW — track how long it has been slow.
+      if (session.budgetSlowSince === 0) {
+        session.budgetSlowSince = now;
+        continue;
+      }
+      if (now - session.budgetSlowSince < BUDGET_SUSTAINED_MS) {
+        continue; // not sustained yet
+      }
+      if (now - session.budgetLastActionAt < BUDGET_ACTION_COOLDOWN_MS) {
+        continue; // let the previous action settle
+      }
+      // Sustained sub-realtime. Only downscale if the encoder — not a
+      // download-starved input — is the limit.
+      const bound = await this.#classifyTranscodeBound(session);
+      if (bound === "download") {
+        logger.info(
+          `[budget] transcode ${session.id} speed=${speed.toFixed(2)}x but download-limited ` +
+            `"${session.fileName}"; not downscaling (torrent is the bottleneck)`
+        );
+        session.budgetSlowSince = 0; // re-evaluate fresh; don't thrash on this
+        continue;
+      }
+      this.#applyBudgetDownshift(session, speed, bound);
+    }
+  }
+
+  /**
+   * Decide whether a sustained sub-realtime transcode is limited by the encoder
+   * (CPU) or by a download-starved input. Compares the torrent's download rate
+   * with the source's average byte rate; a fully-downloaded file can never be
+   * download-bound. Returns "cpu" | "download" | "unknown" ("unknown" is treated
+   * as CPU by the caller — the common case, logged as such).
+   *
+   * @param {HlsSession} session
+   * @returns {Promise<"cpu" | "download" | "unknown">}
+   */
+  async #classifyTranscodeBound(session) {
+    if (!this.getSourceStats) {
+      return "unknown";
+    }
+    let stats;
+    try {
+      stats = await this.getSourceStats(session.sourceKey, session.fileIndex);
+    } catch {
+      return "unknown";
+    }
+    if (!stats) {
+      return "unknown";
+    }
+    // A fully (or almost fully) downloaded file cannot be download-bound.
+    if (typeof stats.fileProgress === "number" && stats.fileProgress >= 0.999) {
+      return "cpu";
+    }
+    const duration = Number.isFinite(session.totalDurationSeconds) ? session.totalDurationSeconds : 0;
+    const length = Number.isFinite(stats.fileLength) && stats.fileLength > 0 ? stats.fileLength : 0;
+    const downloadSpeed = Number.isFinite(stats.downloadSpeed) ? stats.downloadSpeed : 0;
+    if (duration <= 0 || length <= 0) {
+      return "unknown"; // cannot compute the source byte rate
+    }
+    const sourceByteRate = length / duration;
+    return downloadSpeed >= sourceByteRate * BUDGET_DOWNLOAD_OK_FACTOR ? "cpu" : "download";
+  }
+
+  /**
+   * Step a session one resolution rung down the budget ladder and restart the
+   * encode at the current segment with the lighter profile.
+   *
+   * @param {HlsSession} session
+   * @param {number} speed - The measured (sub-realtime) speed, for logging.
+   * @param {"cpu" | "unknown"} bound
+   * @returns {void}
+   */
+  #applyBudgetDownshift(session, speed, bound) {
+    const nextIndex = session.budgetRungIndex + 1;
+    const rung = session.budgetLadder[nextIndex];
+    if (!rung) {
+      return;
+    }
+    const fps = Number.isInteger(session.outputFps) && session.outputFps > 0 ? session.outputFps : TRANSCODE_FPS;
+    session.budgetRungIndex = nextIndex;
+    session.budgetDownshifts += 1;
+    session.budgetLastActionAt = Date.now();
+    session.budgetSlowSince = 0;
+    session.encodeWidth = rung.width;
+    session.encodeHeight = rung.height;
+    session.softwarePreset = pickSoftwarePreset(this.softwarePresetBenchmark, rung.width * rung.height * fps);
+    // Restart at the current live-edge segment so the lighter profile takes over
+    // from where the viewer is watching (hard-restart tier).
+    const head = session.encodeStartIndex;
+    const processed = Number.isFinite(session.progress?.processedSeconds)
+      ? session.progress.processedSeconds
+      : this.#segmentStartTime(session, head);
+    const currentSeg = Math.max(head, this.#segmentIndexForTime(session, processed));
+    logger.info(
+      `[budget] transcode ${session.id} ${bound === "unknown" ? "assuming CPU-bound" : "CPU-bound"} ` +
+        `speed=${speed.toFixed(2)}x → downscale to ${rung.width}x${rung.height}/${session.softwarePreset} ` +
+        `(rung ${nextIndex + 1}/${session.budgetLadder.length}, downshift ${session.budgetDownshifts}/${BUDGET_MAX_DOWNSHIFTS}), ` +
+        `restart at segment #${currentSeg} "${session.fileName}"`
+    );
+    this.#startEncodeRun(session, currentSeg);
   }
 
   /**
@@ -1027,8 +1261,10 @@ export class HlsSessionManager {
     // codec args (including keyframe alignment on segment boundaries).
     const videoCodecArgs = session.transcodeVideo
       ? this.videoEncoder.buildVideoArgs({
-          targetWidth: session.targetWidth,
-          targetHeight: session.targetHeight,
+          // Budget-selected encode box (may be below the client target on weak
+          // software hosts); falls back to the client target for hardware.
+          targetWidth: session.encodeWidth,
+          targetHeight: session.encodeHeight,
           segmentDurationSec: this.segmentDurationSec,
           // Source-inherited output rate (integer, capped); descriptors that
           // use time-based keyframes just apply it as the frame rate.
@@ -1115,6 +1351,11 @@ export class HlsSessionManager {
     session.progress.processedSeconds = startSeconds;
     session.progress.startPositionSeconds = startSeconds;
     session.progress.updatedAt = Date.now();
+    // Any (re)start resets the cumulative `speed` ffmpeg reports, so reset the
+    // realtime-budget slow window too — otherwise warm-up right after a user
+    // seek could be mis-counted as sustained sub-realtime and trigger a
+    // premature downscale.
+    session.budgetSlowSince = 0;
 
     logger.info(
       `transcode ${session.id} encode-run from segment #${safeIndex} ` +
@@ -1533,6 +1774,7 @@ export class HlsSessionManager {
    */
   async disposeAll() {
     clearInterval(this.cleanupTimer);
+    clearInterval(this.budgetTimer);
     const activeIds = Array.from(this.sessionsById.keys());
     for (const sessionId of activeIds) {
       await this.disposeSession(sessionId);

package/services/hwaccel.js

@@ -558,3 +558,87 @@ export function pickSoftwarePreset(benchmark, pixelsPerSecNeeded) {
   }
   return benchmark[benchmark.length - 1].preset;
 }
+
+// Resolution-ladder heights (output height rungs), high→low. The ladder is
+// derived per-stream from the ceiling (the client-requested, source-capped
+// output box): only rungs at or below the ceiling height are used, so the
+// budget never upscales past what the client asked for. Standard heights keep
+// the downscaled output at familiar resolutions.
+const RESOLUTION_LADDER_HEIGHTS = [2160, 1440, 1080, 720, 540, 480, 360, 240];
+
+/**
+ * Build the resolution ladder for a ceiling box. Returns candidate output
+ * dimensions from the ceiling downward, preserving the ceiling's aspect ratio,
+ * each even-sized. The ceiling itself is always the top rung; ladder heights
+ * at or above it are skipped (never upscale). Deduped by height.
+ *
+ * @param {number} ceilingWidth
+ * @param {number} ceilingHeight
+ * @returns {Array<{ width: number, height: number }>} high→low
+ */
+export function buildResolutionLadder(ceilingWidth, ceilingHeight) {
+  const cw = Number.isInteger(ceilingWidth) && ceilingWidth > 0 ? ceilingWidth : 0;
+  const ch = Number.isInteger(ceilingHeight) && ceilingHeight > 0 ? ceilingHeight : 0;
+  if (!cw || !ch) {
+    return [];
+  }
+  const even = (v) => {
+    const r = Math.round(v);
+    return Math.max(2, r - (r % 2));
+  };
+  /** @type {Array<{ width: number, height: number }>} */
+  const rungs = [{ width: cw, height: ch }];
+  for (const h of RESOLUTION_LADDER_HEIGHTS) {
+    if (h >= ch) {
+      continue; // at/above the ceiling — the ceiling rung already covers it
+    }
+    rungs.push({ width: even(cw * (h / ch)), height: h });
+  }
+  const seen = new Set();
+  return rungs.filter((rung) => {
+    if (seen.has(rung.height)) {
+      return false;
+    }
+    seen.add(rung.height);
+    return true;
+  });
+}
+
+/**
+ * Choose the software encode settings (resolution + preset) that fit the
+ * realtime budget on this host. From the resolution ladder (ceiling downward),
+ * pick the HIGHEST rung whose encode throughput — predicted from the startup
+ * benchmark's fastest preset — clears realtime × PRESET_SPEED_MARGIN. Then, at
+ * that resolution, pick the highest-quality preset that still clears the
+ * margin. When even the lowest rung cannot clear it, use the lowest rung with
+ * the fastest preset (best effort — a smaller picture beats sub-realtime
+ * playback at full size). Returns null when no benchmark or ceiling is
+ * available (the caller keeps the ceiling resolution and the default preset).
+ *
+ * @param {Array<{ preset: string, pixelsPerSec: number }>} benchmark - slowest→fastest
+ * @param {{ width: number, height: number }} ceiling
+ * @param {number} outputFps
+ * @returns {{ width: number, height: number, preset: string, ladder: Array<{ width: number, height: number }>, rungIndex: number } | null}
+ */
+export function chooseSoftwareEncodeSettings(benchmark, ceiling, outputFps) {
+  if (!Array.isArray(benchmark) || benchmark.length === 0) {
+    return null;
+  }
+  const fps = Number.isFinite(outputFps) && outputFps > 0 ? outputFps : TRANSCODE_FPS;
+  const ladder = buildResolutionLadder(ceiling?.width, ceiling?.height);
+  if (ladder.length === 0) {
+    return null;
+  }
+  const fastest = benchmark[benchmark.length - 1].pixelsPerSec; // ultrafast throughput
+  let chosenIndex = ladder.length - 1; // default: lowest rung (best effort)
+  for (let i = 0; i < ladder.length; i += 1) {
+    const needed = ladder[i].width * ladder[i].height * fps;
+    if (fastest >= needed * PRESET_SPEED_MARGIN) {
+      chosenIndex = i;
+      break;
+    }
+  }
+  const chosen = ladder[chosenIndex];
+  const preset = pickSoftwarePreset(benchmark, chosen.width * chosen.height * fps);
+  return { width: chosen.width, height: chosen.height, preset, ladder, rungIndex: chosenIndex };
+}

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