@torrent-tv/proxy 2.9.27 → 2.9.30

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 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.)
+- **New**: Output frame rate follows the source instead of a fixed 24 fps (OpenSpec change `transcode-quality`, part 1). 25/30 fps content no longer plays resampled to 24 (which caused judder). Frame-count-GOP encoders (software libx264, v4l2m2m) use an integer rate — source rounded, capped at 30 as a speed guard — with the fps filter and the GOP length kept in lockstep so a keyframe still lands on every segment boundary; the time-based-keyframe encoders (nvenc, vaapi, qsv) inherit the exact source rate untouched (nvenc previously forced 24 — its fps filter is removed). Source rate is parsed from the existing startup probe. (GOP = group of pictures, the span between keyframes; the segment grid needs a keyframe at each boundary.)
+- **Fix**: `GET /api/sources/:key/files` no longer blocks until metadata arrives (or fails prematurely on a cold magnet). It now waits only a short per-request budget (`maxWaitMs`, default 8 s, cap 20 s) and returns `{ pending: true }` while the swarm fetch continues in the background, so the browser can poll — mirroring the cold-torrent playback-plan poll. Field-found: a magnet whose metadata had not arrived yet failed with "no peers" on the first paste, then succeeded on a second paste because the fetch had kept running in the background. A real fetch error now returns 502 (distinct from pending). Pairs with server 0.8.39 (which references this as "proxy 2.9.28" — that release was folded into 2.9.29 before publishing).
+
 ## 2.9.27
 
 - **Fix**: A magnet whose infoHash matches a torrent already loaded in the pool no longer fails with 500 "Cannot add duplicate torrent" (scenario: one viewer opened the .torrent file, another pasted the magnet of the same content — different source keys, one swarm). The duplicate-add error now resolves to the already-loaded torrent (waiting for its metadata when it is itself still cold), so both source keys share the swarm. Found by a field test of the magnet flow.

package/bin/cli.js

@@ -56,6 +56,7 @@ program
   .option("--name <name>", "Display name")
   .option("--no-transcode-audio", "Disable optional HLS AAC audio transcoding")
   .option("--no-port-mapping", "Disable automatic UPnP/NAT-PMP port mapping")
+  .option("--max-disk-bytes <bytes>", "Cap total downloaded torrent data (0 = disabled; default min(10GB, half free disk))")
   .option("--ffmpeg-bin <path>", "Path to ffmpeg binary")
   .option("--token <token>", "Registration token", "")
   .addHelpText("after", HELP_EXAMPLES);
@@ -79,6 +80,12 @@ const clientName = options.name ? String(options.name) : `proxy-${clientId.slice
 const token = String(options.token ?? "");
 const transcodeAudio = options.transcodeAudio !== false;
 const portMappingEnabled = options.portMapping !== false;
+// Optional disk cap. undefined → the pool computes its own default; a valid
+// non-negative number (0 disables) → passed through.
+const maxDiskBytes =
+  options.maxDiskBytes !== undefined && Number.isFinite(Number(options.maxDiskBytes)) && Number(options.maxDiskBytes) >= 0
+    ? Number(options.maxDiskBytes)
+    : undefined;
 const bundledFfmpegBin = typeof ffmpegStatic === "string" ? ffmpegStatic : "";
 const ffmpegBin = options.ffmpegBin ? String(options.ffmpegBin) : bundledFfmpegBin || "ffmpeg";
 
@@ -234,7 +241,8 @@ try {
     host: bindHost,
     port: localPort,
     transcodeAudio,
-    ffmpegBin
+    ffmpegBin,
+    maxDiskBytes
   });
   app = started.app;
   actualPort = started.port;

package/openspec/changes/disk-cap/.openspec.yaml

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

package/openspec/changes/disk-cap/proposal.md

@@ -0,0 +1,37 @@
+# Proposal: Global disk cap with LRU eviction (Disk hygiene Level 1, final)
+
+## Why
+
+Downloaded torrent data is already removed on a 300 s idle TTL and at
+shutdown, and orphans are swept at startup — but under pressure (several
+large files opened within the TTL window, or a fast fill) the total can
+still grow unbounded and fill a small Home Assistant host's disk
+(SD/eMMC on a Yellow/Pi is often 16–32 GB). A full disk can take down Home
+Assistant itself. This adds the last missing Level 1 piece: a global cap.
+
+## What Changes
+
+- The pool tracks total downloaded bytes and, when it exceeds a cap, evicts
+  whole torrents with NO active reader, least-recently-used first, until
+  back under the cap (checked every 30 s and reused via the existing
+  remove-with-store path). A torrent that is currently playing is never
+  evicted — we cannot delete what is in use.
+- The cap defaults to `min(10 GB, half of free disk)` (measured via
+  `statfs` on the store filesystem), and is overridable with
+  `--max-disk-bytes` (0 disables).
+
+## Capabilities
+
+### New Capabilities
+
+- `disk-cap`: bounded total on-disk footprint via LRU eviction.
+
+### Modified Capabilities
+
+<!-- none -->
+
+## Impact
+
+- `services/torrent-pool.js` (access tracking, cap enforcement),
+  `bin/cli.js` (`--max-disk-bytes`), `server.js` (option pass-through);
+  ha-addon bump. Part of the proxy transcode/hygiene batch (2.9.29).

package/openspec/changes/disk-cap/specs/disk-cap/spec.md

@@ -0,0 +1,25 @@
+# disk-cap — delta spec
+
+## ADDED Requirements
+
+### Requirement: Total torrent data is bounded by a disk cap
+The pool SHALL keep the total downloaded torrent footprint under a cap. When
+the total exceeds the cap it SHALL evict whole torrents that have no active
+file reader, least-recently-used first, removing each with its on-disk store,
+until back under the cap or no evictable torrent remains. A torrent with an
+active reader SHALL NEVER be evicted. The cap SHALL default to the smaller of
+10 GB and half the free disk, and be overridable (0 disables).
+
+#### Scenario: Idle torrents evicted under pressure
+- **WHEN** the total downloaded data exceeds the cap and some torrents have no
+  active reader
+- **THEN** the least-recently-used idle torrents are removed with their stores
+  until the total is back under the cap
+
+#### Scenario: Active torrent protected
+- **WHEN** the cap is exceeded but the only large torrent is currently playing
+- **THEN** it is not evicted (the cap cannot delete in-use data)
+
+#### Scenario: Cap disabled
+- **WHEN** the cap is set to 0
+- **THEN** no eviction occurs

package/openspec/changes/disk-cap/tasks.md

@@ -0,0 +1,19 @@
+# Tasks: Global disk cap with LRU eviction
+
+## 1. Implementation
+
+- [x] 1.1 Access tracking (`#lastAccess`) updated on getTorrent (incl. the
+      duplicate-infoHash path) and acquireFile
+- [x] 1.2 Cap computed at construction (`min(10GB, half free)` via statfs) or
+      taken from the `maxDiskBytes` option; 0 disables
+- [x] 1.3 Periodic (30 s) `#enforceDiskCap`: evict zero-reader torrents
+      LRU-first via the existing remove-with-store path; clear timer on
+      destroyAll; drop `#lastAccess` on removal
+- [x] 1.4 `--max-disk-bytes` CLI flag → server.js → pool
+- [x] 1.5 Syntax checks + unit-test the eviction ordering/active-skip
+
+## 2. Release
+
+- [ ] 2.1 Ship in the proxy batch (2.9.29) + ha-addon bump
+- [ ] 2.2 Field-check on the host: open several large files, confirm idle
+      ones are evicted and playback is never interrupted

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/.openspec.yaml

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

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

@@ -0,0 +1,51 @@
+# Proposal: Transcode quality — source fps, realtime budget, HDR, manual quality
+
+## Why
+
+The transcode pipeline was tuned for "make it play at all" and left several
+quality/robustness gaps flagged in the project analysis: output was hard-
+locked to 24 fps (25/30 fps content played with resampling judder); the
+encoder profile could be slower than realtime on weak hosts (stalls instead
+of graceful degradation); 10-bit/HDR sources transcoded to 8-bit H.264
+without tone mapping (washed-out colours); and the viewer had no way to force
+a resolution. This change is the transcode-stage batch (proxy side; the
+manual-quality menu also needs the server UI).
+
+## What Changes
+
+- **Source fps** (DONE): the output frame rate is inherited from the source
+  (rounded to an integer, capped at 30), replacing the fixed 24. The
+  fixed-GOP encoders keep the fps↔GOP relationship exact so keyframes stay on
+  the segment grid; time-based-keyframe encoders (nvenc) just use it as the
+  rate; VAAPI/QSV already inherited.
+- **Realtime budget** (planned): the startup benchmark picks the
+  encoder/preset/resolution/fps combination whose predicted throughput stays
+  above realtime; a source that would not encode in time is downscaled
+  (720/540p) rather than refused, and a sustained runtime `speed<1` triggers
+  a restart with a lighter profile. `-maxrate`/`-bufsize` cap bitrate spikes.
+- **HDR tone mapping** (planned): detect 10-bit/HDR (pix_fmt,
+  color_transfer smpte2084/HLG) and insert a tone-map chain when re-encoding
+  to 8-bit H.264, so colours are not washed out. Depends on the ffmpeg build
+  having the tonemap filters.
+- **Manual quality** (planned): a player Quality menu — Auto (current
+  viewport/DPR behaviour) plus forced resolutions — the proxy already
+  honours a requested target height.
+
+## Capabilities
+
+### New Capabilities
+
+- `transcode-quality`: output frame rate, realtime encode budget, HDR tone
+  mapping, and explicit quality selection.
+
+### Modified Capabilities
+
+<!-- none -->
+
+## Impact
+
+- `services/hwaccel.js` (fps, benchmark, tonemap args),
+  `services/hls-session-manager.js` (fps probe, runtime speed watch),
+  `services/playback-planner.js` (HDR/fps in the plan);
+  server player UI for the Quality menu; ha-addon bump.
+- Released as a batch (proxy 2.9.29 + addon) after the pieces land.

package/openspec/changes/transcode-quality/specs/transcode-quality/spec.md

@@ -0,0 +1,37 @@
+# transcode-quality — delta spec
+
+## ADDED Requirements
+
+### Requirement: Output frame rate follows the source
+When re-encoding video, the proxy SHALL NOT force a fixed 24 fps. The output
+rate SHALL follow the source, and the fps handling SHALL depend on how the
+chosen encoder places keyframes:
+
+- Frame-count-GOP encoders (software libx264, v4l2m2m) SHALL use an INTEGER
+  output rate — source rate rounded and capped — with the `fps` filter and
+  the GOP length (`segmentDuration × fps`) using that same integer, so a
+  keyframe lands on every segment boundary and segments do not drift off the
+  synthetic playlist's uniform grid. When the source rate is unknown they
+  SHALL fall back to the default rate.
+- Time-based-keyframe encoders (nvenc, vaapi, qsv) SHALL inherit the exact
+  source rate with no fps filter (their keyframes are forced by output time,
+  so any rate segments correctly); no rounding, no cap.
+
+#### Scenario: 25 fps source on the software encoder
+- **WHEN** a 25 fps video is re-encoded with libx264 and 4-second segments
+- **THEN** the output is 25 fps and the GOP is 100 frames (keyframe every
+  segment)
+
+#### Scenario: High-fps source on the software encoder
+- **WHEN** a 60 fps video is re-encoded with libx264/v4l2m2m
+- **THEN** the output rate is capped at 30 fps (speed guard)
+
+#### Scenario: Fractional source on a hardware time-based encoder
+- **WHEN** a 23.976 fps video is re-encoded with nvenc/vaapi/qsv
+- **THEN** the exact source rate is kept (no fps filter) and segments are
+  still cut on time
+
+#### Scenario: Unknown source rate
+- **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

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

@@ -0,0 +1,34 @@
+# Tasks: Transcode quality
+
+## 1. Source fps
+
+- [x] 1.1 hwaccel: `chooseOutputFps` (integer, capped); `buildVideoArgs`
+      takes `fps`, threaded into the filter + frame-count GOP (software,
+      v4l2m2m) and the filter only (nvenc); VAAPI/QSV unchanged (already
+      inherit); startup test-encode/benchmark keep the fixed rate
+- [x] 1.2 hls-session-manager: parse source fps from the probe, compute
+      `session.outputFps`, pass it into `buildVideoArgs`
+- [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.3 `-maxrate`/`-bufsize`
+
+## 3. HDR tone mapping (planned)
+
+- [ ] 3.1 Detect 10-bit/HDR; insert tonemap chain when re-encoding to 8-bit
+- [ ] 3.2 Guard on tonemap-filter availability in the ffmpeg build
+
+## 4. Manual quality (planned)
+
+- [ ] 4.1 Proxy honours requested target height (already partly there)
+- [ ] 4.2 Server Quality menu (Auto + forced resolutions)
+
+## 5. Release
+
+- [ ] 5.1 Batch release: proxy 2.9.29 + ha-addon bump; field-test on the
+      owner's hardware (25/30 fps content plays without judder; seek intact)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.9.27",
+  "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/sources/files/get.js

@@ -4,9 +4,14 @@
  * GET /api/sources/:sourceKey/files
  *
  * The browser parses `.torrent` files locally, but a magnet URI carries no
- * file list — the metadata comes from the swarm. This route resolves the
- * torrent (waiting for metadata on a cold magnet; callers should use a
- * generous timeout) and returns the file inventory.
+ * file list — the metadata comes from the swarm and can take a while to
+ * arrive on a cold magnet. Rather than block the request until it does (a
+ * single long request racing the transport timeout, which surfaced as a
+ * premature "no peers" error while the metadata was in fact still arriving),
+ * this waits only a short per-request budget: if the metadata is not ready it
+ * returns `{ pending: true }` while the fetch continues in the background. The
+ * caller polls again until the file list comes back — mirroring the cold-
+ * torrent playback-plan poll.
  *
  * @param {import("fastify").FastifyRequest} req
  * @param {import("fastify").FastifyReply} reply
@@ -16,6 +21,10 @@
  * }} deps
  * @returns {Promise<void>}
  */
+
+/** Sentinel resolved when the per-request wait elapses before metadata. */
+const PENDING = Symbol("pending");
+
 export async function handleApiSourceFilesGet(req, reply, { sourceRegistry, torrentPool }) {
   const sourceKey = typeof req.params?.sourceKey === "string" ? req.params.sourceKey.trim() : "";
   if (!sourceKey) {
@@ -26,7 +35,41 @@ export async function handleApiSourceFilesGet(req, reply, { sourceRegistry, torr
     return reply.code(404).send({ error: "Source key was not found." });
   }
 
-  const torrent = await torrentPool.getTorrent(sourceRecord.sourceType, sourceRecord.source);
+  // How long to wait within THIS request before returning `pending`. Well
+  // under the transport's request timeout so a single poll never races it.
+  const rawWait = Number(req.query?.maxWaitMs);
+  const maxWaitMs = Number.isFinite(rawWait) && rawWait > 0 ? Math.min(rawWait, 20_000) : 8_000;
+
+  // getTorrent dedupes concurrent/repeated calls via the pool's in-flight map,
+  // so polling keeps joining the same background fetch (metadata keeps
+  // downloading between polls). Race it against the wait budget; if the wait
+  // wins, the fetch is left running for the next poll to observe.
+  let timer;
+  const waitPromise = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(PENDING), maxWaitMs);
+    timer.unref?.();
+  });
+  const torrentPromise = torrentPool
+    .getTorrent(sourceRecord.sourceType, sourceRecord.source)
+    // Swallow so a rejection that loses the race is not an unhandled rejection;
+    // the next poll re-issues getTorrent and re-observes any real error.
+    .catch((error) => (error instanceof Error ? error : new Error(String(error))));
+
+  let result;
+  try {
+    result = await Promise.race([torrentPromise, waitPromise]);
+  } finally {
+    clearTimeout(timer);
+  }
+
+  if (result === PENDING) {
+    return reply.send({ pending: true });
+  }
+  if (result instanceof Error) {
+    return reply.code(502).send({ error: `Could not load torrent metadata: ${result.message}` });
+  }
+
+  const torrent = result;
   const files = (torrent.files ?? []).map((file, index) => ({
     index,
     name: file?.name ?? "",

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