@torrent-tv/proxy 2.89.1 → 2.89.3

package/openspec/changes/seek-debounce/specs/seek-debounce/spec.md

@@ -1,41 +1,41 @@
-# seek-debounce — delta spec (proxy)
-
-## ADDED Requirements
-
-### Requirement: Scattered post-seek segment requests collapse to one restart
-
-When segment requests land outside the running encode's look-ahead window
-(server-side seeks), the proxy SHALL NOT restart ffmpeg on each one. It SHALL
-wait a short settle period, treating further out-of-window requests as
-re-arming the period and updating the target to the most recently requested
-index, and then restart the encoder exactly once at the settled target. A
-fixed cap SHALL bound the total settle wait so a genuine seek is not delayed
-indefinitely while the scrubber is still moving. During the settle the
-segment route behaves as before (long-poll / client retry).
-
-#### Scenario: Scrub emits a burst of scattered requests
-- **WHEN** a player, after a seek, requests several far-apart segments in
-  quick succession (e.g. 367, 732, 369, 368, 370)
-- **THEN** ffmpeg is restarted only once, at the last requested index, and
-  produces a continuous run from there — no ping-pong between positions
-
-#### Scenario: Settle resolves on the wrong position
-- **WHEN** the settled restart target turns out not to be where the player
-  ultimately needs to play (e.g. it was a lone probe request)
-- **THEN** the player's next out-of-window request arms exactly one more
-  settle and one more restart — never an unbounded restart loop
-
-#### Scenario: Request falls back inside the window
-- **WHEN** a requested segment is within the current run's look-ahead window
-- **THEN** it is served by the running encode with no restart and without
-  affecting any pending settle
-
-### Requirement: A pending settle never outlives its session
-
-When a session is disposed, any pending settle timer SHALL be cleared so it
-cannot fire and restart a disposed session.
-
-#### Scenario: Session disposed mid-settle
-- **WHEN** a session with a pending seek-settle timer is disposed (idle TTL,
-  shutdown, or teardown)
-- **THEN** the timer is cleared and no encode restart occurs afterwards
+# seek-debounce — delta spec (proxy)
+
+## ADDED Requirements
+
+### Requirement: Scattered post-seek segment requests collapse to one restart
+
+When segment requests land outside the running encode's look-ahead window
+(server-side seeks), the proxy SHALL NOT restart ffmpeg on each one. It SHALL
+wait a short settle period, treating further out-of-window requests as
+re-arming the period and updating the target to the most recently requested
+index, and then restart the encoder exactly once at the settled target. A
+fixed cap SHALL bound the total settle wait so a genuine seek is not delayed
+indefinitely while the scrubber is still moving. During the settle the
+segment route behaves as before (long-poll / client retry).
+
+#### Scenario: Scrub emits a burst of scattered requests
+- **WHEN** a player, after a seek, requests several far-apart segments in
+  quick succession (e.g. 367, 732, 369, 368, 370)
+- **THEN** ffmpeg is restarted only once, at the last requested index, and
+  produces a continuous run from there — no ping-pong between positions
+
+#### Scenario: Settle resolves on the wrong position
+- **WHEN** the settled restart target turns out not to be where the player
+  ultimately needs to play (e.g. it was a lone probe request)
+- **THEN** the player's next out-of-window request arms exactly one more
+  settle and one more restart — never an unbounded restart loop
+
+#### Scenario: Request falls back inside the window
+- **WHEN** a requested segment is within the current run's look-ahead window
+- **THEN** it is served by the running encode with no restart and without
+  affecting any pending settle
+
+### Requirement: A pending settle never outlives its session
+
+When a session is disposed, any pending settle timer SHALL be cleared so it
+cannot fire and restart a disposed session.
+
+#### Scenario: Session disposed mid-settle
+- **WHEN** a session with a pending seek-settle timer is disposed (idle TTL,
+  shutdown, or teardown)
+- **THEN** the timer is cleared and no encode restart occurs afterwards

package/openspec/changes/seek-debounce/tasks.md

@@ -1,33 +1,33 @@
-# Tasks: Debounce server-side seek restarts
-
-## 1. Implementation (proxy)
-
-- [x] 1.1 Add `SEEK_SETTLE_MS = 1200` and `SEEK_SETTLE_MAX_MS = 2500` to the
-      constants block in `hls-session-manager.js`.
-- [x] 1.2 Add session state `seekSettleTimer: null`, `seekTarget: null`,
-      `seekFirstFarAt: 0` where `lastRestartAt` is initialised.
-- [x] 1.3 Rewrite the out-of-window branch of `#ensureEncodingFor` as the
-      settle/debounce (design.md): record target, arm/re-arm the timer with
-      the capped delay, restart once on fire (`#fireSettledSeek`), re-arm for
-      the cooldown remainder if still cooling down. `timer.unref?.()`.
-- [x] 1.4 `disposeSession`: clear `seekSettleTimer` and null it.
-- [x] 1.5 Restart log line: `transcode <id> seek settle → restart at segment #<target>`.
-
-## 2. Verification
-
-- [x] 2.1 Timing/target logic verified with a fake-clock replica: burst
-      `367,732,369,368,370` → one restart at 370; lone later far request →
-      exactly one more restart (900); disposal mid-settle → no restart; the
-      2.5 s cap forces a fire while the scrubber keeps moving. (Replica, not
-      the wired private method — the methods are private and `#startEncodeRun`
-      spawns ffmpeg; the wired code mirrors the replica.)
-- [x] 2.2 `node --check services/hls-session-manager.js`.
-
-## 3. Release
-
-- [ ] 3.1 CHANGELOG (proxy, next patch) + `npm run patch` (user OTP).
-- [ ] 3.2 Bump `ha-addon/torrent_tv_proxy/config.yaml` + CHANGELOG; push;
-      update the addon in HA.
-- [ ] 3.3 Field: scrub Poirot on iOS → a single `seek settle → restart` per
-      scrub (not a train of `seek → restart`), playback resumes after the
-      settle + the unavoidable cold-segment wait.
+# Tasks: Debounce server-side seek restarts
+
+## 1. Implementation (proxy)
+
+- [x] 1.1 Add `SEEK_SETTLE_MS = 1200` and `SEEK_SETTLE_MAX_MS = 2500` to the
+      constants block in `hls-session-manager.js`.
+- [x] 1.2 Add session state `seekSettleTimer: null`, `seekTarget: null`,
+      `seekFirstFarAt: 0` where `lastRestartAt` is initialised.
+- [x] 1.3 Rewrite the out-of-window branch of `#ensureEncodingFor` as the
+      settle/debounce (design.md): record target, arm/re-arm the timer with
+      the capped delay, restart once on fire (`#fireSettledSeek`), re-arm for
+      the cooldown remainder if still cooling down. `timer.unref?.()`.
+- [x] 1.4 `disposeSession`: clear `seekSettleTimer` and null it.
+- [x] 1.5 Restart log line: `transcode <id> seek settle → restart at segment #<target>`.
+
+## 2. Verification
+
+- [x] 2.1 Timing/target logic verified with a fake-clock replica: burst
+      `367,732,369,368,370` → one restart at 370; lone later far request →
+      exactly one more restart (900); disposal mid-settle → no restart; the
+      2.5 s cap forces a fire while the scrubber keeps moving. (Replica, not
+      the wired private method — the methods are private and `#startEncodeRun`
+      spawns ffmpeg; the wired code mirrors the replica.)
+- [x] 2.2 `node --check services/hls-session-manager.js`.
+
+## 3. Release
+
+- [ ] 3.1 CHANGELOG (proxy, next patch) + `npm run patch` (user OTP).
+- [ ] 3.2 Bump `ha-addon/torrent_tv_proxy/config.yaml` + CHANGELOG; push;
+      update the addon in HA.
+- [ ] 3.3 Field: scrub Poirot on iOS → a single `seek settle → restart` per
+      scrub (not a train of `seek → restart`), playback resumes after the
+      settle + the unavoidable cold-segment wait.

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

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

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

@@ -1,50 +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.
+# 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

@@ -1,34 +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)
+# 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

@@ -1,26 +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
+# 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/track-selection/.openspec.yaml

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

package/openspec/changes/track-selection/design.md

@@ -1,47 +1,47 @@
-# Design: Track inventory, audio selection and embedded-subtitle extraction
-
-## Context
-
-The probe already captures the full ffmpeg `-i` banner; the HLS session
-manager already restarts ffmpeg per (source, file, settings) key; the
-`/stream` route already drives prioritised sequential download. All three
-features ride those mechanisms.
-
-## Goals / Non-Goals
-
-**Goals:** expose every track; select audio server-side; deliver embedded
-text subtitles as WebVTT.
-
-**Non-Goals:** seamless (no-restart) audio switching via HLS alternate
-renditions; image-based subtitles (PGS/VobSub — needs OCR or burn-in);
-subtitle extraction that avoids downloading the file (impossible: cues are
-interleaved across the whole container).
-
-## Decisions
-
-1. **Parse tracks from the existing probe output** (zero extra probe cost).
-   The scanner reads only the Input section — ffmpeg prints Stream lines for
-   the null output too, which would duplicate every track (caught against
-   real output). Titles come from each stream's `title` metadata line.
-2. **Audio switch = new session.** `audioTrackIndex` joins the session key;
-   the old session dies via the existing idle TTL. Reuses the proven
-   seek-restart machinery instead of building HLS alternate renditions;
-   the cost is a few seconds' gap on switch — acceptable v1.
-3. **Extraction as a streaming route.** ffmpeg writes WebVTT to stdout piped
-   into the HTTP response; the first stdout chunk decides 200-vs-422 (a
-   non-text track dies before producing output). Client disconnect kills
-   ffmpeg; a 30-minute hard cap guards dead swarms. The transport layer's
-   60 s request timeout must be raised per-request by the browser (done in
-   the paired server change).
-4. **Accepted v1 cost:** extraction reads to the last cue → cold torrents
-   download while extracting. For the transcode path the file downloads
-   anyway; for direct play this is extra traffic the viewer opted into by
-   picking a subtitle.
-
-## Risks / Trade-offs
-
-- [Extraction competes with playback for piece priority] → both readers move
-  the 8 MB critical window; sequential download serves both. Field-watch; if
-  playback stalls appear, throttle extraction reads later.
-- [Stream-line format drift across ffmpeg versions] → regex kept permissive;
-  a parse miss degrades to an empty inventory (menus simply do not appear).
+# Design: Track inventory, audio selection and embedded-subtitle extraction
+
+## Context
+
+The probe already captures the full ffmpeg `-i` banner; the HLS session
+manager already restarts ffmpeg per (source, file, settings) key; the
+`/stream` route already drives prioritised sequential download. All three
+features ride those mechanisms.
+
+## Goals / Non-Goals
+
+**Goals:** expose every track; select audio server-side; deliver embedded
+text subtitles as WebVTT.
+
+**Non-Goals:** seamless (no-restart) audio switching via HLS alternate
+renditions; image-based subtitles (PGS/VobSub — needs OCR or burn-in);
+subtitle extraction that avoids downloading the file (impossible: cues are
+interleaved across the whole container).
+
+## Decisions
+
+1. **Parse tracks from the existing probe output** (zero extra probe cost).
+   The scanner reads only the Input section — ffmpeg prints Stream lines for
+   the null output too, which would duplicate every track (caught against
+   real output). Titles come from each stream's `title` metadata line.
+2. **Audio switch = new session.** `audioTrackIndex` joins the session key;
+   the old session dies via the existing idle TTL. Reuses the proven
+   seek-restart machinery instead of building HLS alternate renditions;
+   the cost is a few seconds' gap on switch — acceptable v1.
+3. **Extraction as a streaming route.** ffmpeg writes WebVTT to stdout piped
+   into the HTTP response; the first stdout chunk decides 200-vs-422 (a
+   non-text track dies before producing output). Client disconnect kills
+   ffmpeg; a 30-minute hard cap guards dead swarms. The transport layer's
+   60 s request timeout must be raised per-request by the browser (done in
+   the paired server change).
+4. **Accepted v1 cost:** extraction reads to the last cue → cold torrents
+   download while extracting. For the transcode path the file downloads
+   anyway; for direct play this is extra traffic the viewer opted into by
+   picking a subtitle.
+
+## Risks / Trade-offs
+
+- [Extraction competes with playback for piece priority] → both readers move
+  the 8 MB critical window; sequential download serves both. Field-watch; if
+  playback stalls appear, throttle extraction reads later.
+- [Stream-line format drift across ffmpeg versions] → regex kept permissive;
+  a parse miss degrades to an empty inventory (menus simply do not appear).

package/openspec/changes/track-selection/proposal.md

@@ -1,45 +1,45 @@
-# Proposal: Track inventory, audio selection and embedded-subtitle extraction
-
-## Why
-
-Torrents routinely carry several audio languages and embedded subtitles
-(the owner's own test MKVs embed ASS subtitles), but the proxy exposed only
-"the first audio track" and no subtitles at all: the probe reported a single
-audio/video codec pair, the HLS session hard-mapped `0:a:0`, and embedded
-subtitle streams were unreachable by the browser.
-
-## What Changes
-
-- **Probe returns the full track inventory**: `audioTracks` and
-  `subtitleTracks` in the playback plan (type-relative index, codec,
-  language, `title` metadata, default flag, `textBased` for subtitles) —
-  parsed from the same single ffmpeg banner, no extra probe cost.
-- **Audio selection**: `POST /api/transcode-sessions` accepts
-  `audioTrackIndex`; the ffmpeg map becomes `0:a:N` and the index joins the
-  session key (switch = fresh session via the existing restart machinery).
-- **Embedded subtitle extraction**: `GET /api/subtitles` streams a chosen
-  text subtitle track as WebVTT (ffmpeg `-map 0:s:N -f webvtt`). Image-based
-  tracks (PGS/VobSub) are refused with 422. Known cost, accepted for v1:
-  extraction reads the file to the last cue, so a cold torrent downloads
-  sequentially while extracting.
-- Announce log masks the tracker query string (passkey).
-
-## Capabilities
-
-### New Capabilities
-
-- `track-selection`: track inventory in the plan, audio mapping, subtitle
-  extraction.
-
-### Modified Capabilities
-
-- `observability`: announce log masks the passkey (delta note; the change is
-  still unarchived so the edit lands there).
-
-## Impact
-
-- `services/playback-planner.js`, `services/hls-session-manager.js`,
-  `routes/api/transcode-sessions/post.js`, new `routes/api/subtitles/get.js`,
-  `server.js` wiring, `services/torrent/torrent-pool.js` (log masking).
-- Pairs with the server-side `track-selection-ui` change; requires the usual
-  ha-addon bump.
+# Proposal: Track inventory, audio selection and embedded-subtitle extraction
+
+## Why
+
+Torrents routinely carry several audio languages and embedded subtitles
+(the owner's own test MKVs embed ASS subtitles), but the proxy exposed only
+"the first audio track" and no subtitles at all: the probe reported a single
+audio/video codec pair, the HLS session hard-mapped `0:a:0`, and embedded
+subtitle streams were unreachable by the browser.
+
+## What Changes
+
+- **Probe returns the full track inventory**: `audioTracks` and
+  `subtitleTracks` in the playback plan (type-relative index, codec,
+  language, `title` metadata, default flag, `textBased` for subtitles) —
+  parsed from the same single ffmpeg banner, no extra probe cost.
+- **Audio selection**: `POST /api/transcode-sessions` accepts
+  `audioTrackIndex`; the ffmpeg map becomes `0:a:N` and the index joins the
+  session key (switch = fresh session via the existing restart machinery).
+- **Embedded subtitle extraction**: `GET /api/subtitles` streams a chosen
+  text subtitle track as WebVTT (ffmpeg `-map 0:s:N -f webvtt`). Image-based
+  tracks (PGS/VobSub) are refused with 422. Known cost, accepted for v1:
+  extraction reads the file to the last cue, so a cold torrent downloads
+  sequentially while extracting.
+- Announce log masks the tracker query string (passkey).
+
+## Capabilities
+
+### New Capabilities
+
+- `track-selection`: track inventory in the plan, audio mapping, subtitle
+  extraction.
+
+### Modified Capabilities
+
+- `observability`: announce log masks the passkey (delta note; the change is
+  still unarchived so the edit lands there).
+
+## Impact
+
+- `services/playback-planner.js`, `services/hls-session-manager.js`,
+  `routes/api/transcode-sessions/post.js`, new `routes/api/subtitles/get.js`,
+  `server.js` wiring, `services/torrent/torrent-pool.js` (log masking).
+- Pairs with the server-side `track-selection-ui` change; requires the usual
+  ha-addon bump.