@torrent-tv/proxy 2.9.24 → 2.9.26

package/openspec/changes/proxy-observability/proposal.md

@@ -0,0 +1,49 @@
+# Proposal: Proxy observability (queued for the next proxy release, 2.9.25)
+
+## Why
+
+Three diagnosis gaps surfaced while debugging the 2026-07-06 mobile playback
+failures:
+
+1. `/healthz` and `/health` return only `{"ok":true}` — there is no way to
+   see the running proxy version remotely (the addon shipped a stale proxy
+   for a whole release and nothing detected it). The server already returns
+   `version` in its healthz; the proxy should match.
+2. Tracker announces are silent: a torrent with zero peers gives no clue
+   whether the tracker rejected the announce (e.g. a private tracker's
+   client whitelist), returned an empty peer list, or was unreachable.
+   WebTorrent surfaces these as `warning` events that nothing logs.
+3. `MaxListenersExceededWarning` for `[Ssdp]` floods the log — the two
+   port-mapper instances (TCP + UDP) plus WebTorrent's own nat-api attach
+   listeners to a shared SSDP emitter.
+
+## What Changes
+
+- `/healthz` and `/health` include the proxy `version` (from package.json),
+  keeping the current `ok` semantics.
+- Torrent-level `warning` events (tracker errors and rejections) are logged;
+  each tracker announce result is logged with the peer count returned.
+  Where cheaply available, peer origin (tracker / DHT / PEX) is tagged in
+  the existing `[stats]` line.
+- SSDP listener leak fixed (raise the max-listeners on the shared emitter or
+  share one discovery instance between the two port mappers).
+
+## Capabilities
+
+### New Capabilities
+
+- `observability`: health/version reporting and peer-discovery diagnostics.
+
+### Modified Capabilities
+
+<!-- none yet — openspec/specs is empty in this repo -->
+
+## Impact
+
+- `routes/healthz/get.js`, `routes/health/get.js` (or their handlers) —
+  version field.
+- `services/torrent-pool.js` — warning/announce logging, stats origin tags.
+- `services/port-mapper.js` — SSDP listener fix.
+- CHANGELOG entry at current package.json version + 1 patch (2.9.25);
+  requires the usual ha-addon version bump (0.2.47) after `npm run patch`
+  (npm publish needs the user's npm key).

package/openspec/changes/proxy-observability/specs/observability/spec.md

@@ -0,0 +1,33 @@
+# observability — delta spec
+
+## ADDED Requirements
+
+### Requirement: Health endpoints report the version
+`GET /healthz` and `GET /health` SHALL include the running proxy version
+(from package.json) alongside the existing `ok` field.
+
+#### Scenario: Version visible remotely
+- **WHEN** a client requests `/healthz`
+- **THEN** the response contains `ok: true` and the exact npm package version
+  of the running proxy
+
+### Requirement: Peer-discovery diagnostics
+The proxy SHALL log, per torrent: an added line with file count, `private`
+flag and tracker count; every torrent-level warning (tracker rejections and
+errors surface as warnings); and each tracker announce response with the
+seeder/leecher counts returned. Logging failures MUST NOT affect playback
+(best-effort, defensive against WebTorrent internals).
+
+#### Scenario: Zero-peer torrent is explainable
+- **WHEN** a torrent sits at zero peers
+- **THEN** the log shows either the tracker's rejection/warning text or an
+  announce response with zero seeders — distinguishing "tracker refused us"
+  from "the swarm is empty"
+
+### Requirement: No SSDP listener warnings
+Port mapping SHALL NOT flood the log with `MaxListenersExceededWarning`
+regardless of how many ports one mapper maps or renews.
+
+#### Scenario: WebRTC UDP range mapping
+- **WHEN** the UDP mapper maps its 10-port range and later auto-renews it
+- **THEN** no MaxListenersExceededWarning lines appear in the log

package/openspec/changes/proxy-observability/tasks.md

@@ -0,0 +1,21 @@
+# Tasks: Proxy observability
+
+## 1. Implementation
+
+- [x] 1.1 Version in `/healthz` and `/health` (createRequire package.json in
+      server.js, passed as route dep)
+- [x] 1.2 torrent-pool.js: added-torrent line (files/private/trackers),
+      torrent `warning` logging, tracker `update` (announce seeders/leechers)
+      logging with defensive access, client-level warning logging
+- [x] 1.3 port-mapper.js: setMaxListeners(0) on the UPnP SSDP emitter after
+      the first successful map()
+- [x] 1.4 Syntax checks + healthz handler smoke test (version present)
+
+## 2. Release
+
+- [x] 2.1 CHANGELOG.md entry at 2.9.25
+- [x] 2.2 `npm run patch` (needs npm auth), then ha-addon bump 0.2.47 + push
+      (2.9.25 published by the owner — npm 2FA; addon 0.2.47 pushed after)
+- [ ] 2.3 After the addon updates: verify version via `/healthz`, watch the
+      addon log for announce lines on a real torrent, confirm no SSDP
+      warnings

package/openspec/changes/track-selection/.openspec.yaml

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

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

@@ -0,0 +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).

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

@@ -0,0 +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-pool.js` (log masking).
+- Pairs with the server-side `track-selection-ui` change; requires the usual
+  ha-addon bump.

package/openspec/changes/track-selection/specs/track-selection/spec.md

@@ -0,0 +1,41 @@
+# track-selection — delta spec
+
+## ADDED Requirements
+
+### Requirement: The playback plan lists every track
+The playback plan SHALL include `audioTracks` and `subtitleTracks` arrays
+parsed from the probe: for each track its type-relative index (what
+`-map 0:a:N` / `0:s:N` selects), codec, language tag, `title` metadata,
+default disposition, and — for subtitles — a `textBased` flag. Output-side
+streams of the probe run MUST NOT leak into the inventory.
+
+#### Scenario: MKV with an embedded subtitle
+- **WHEN** the plan is requested for an MKV with one video, one audio and one
+  ASS subtitle stream
+- **THEN** the plan lists exactly one audio track and one subtitle track with
+  `textBased: true`
+
+### Requirement: Audio track selection
+`POST /api/transcode-sessions` SHALL accept `audioTrackIndex` (type-relative,
+default 0) and the session SHALL map that audio track. The index SHALL be
+part of the session identity so different tracks never share a session.
+
+#### Scenario: Second audio track
+- **WHEN** a session is created with `audioTrackIndex: 1`
+- **THEN** ffmpeg maps `0:a:1` and a later request with `audioTrackIndex: 0`
+  gets a different session
+
+### Requirement: Embedded subtitles as WebVTT
+`GET /api/subtitles?sourceKey&fileIndex&trackIndex` SHALL stream the chosen
+embedded TEXT subtitle track converted to WebVTT, starting the response as
+soon as ffmpeg produces output. A track that produces no output (image-based
+or broken) SHALL return 422 before any body. Extraction MUST stop when the
+client disconnects.
+
+#### Scenario: Text track extracted
+- **WHEN** the client requests a text subtitle track
+- **THEN** the response is `text/vtt` starting with `WEBVTT` and real cues
+
+#### Scenario: Image-based track refused
+- **WHEN** the client requests a PGS/VobSub track
+- **THEN** the proxy responds 422 with an explanatory error

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

@@ -0,0 +1,20 @@
+# Tasks: Track inventory, audio selection and embedded-subtitle extraction
+
+## 1. Implementation
+
+- [x] 1.1 playback-planner: input-section stream scanner (index, codec,
+      language, title, default, textBased); `audioTracks`/`subtitleTracks`
+      in the plan (verified against real ffmpeg output from the owner's MKV:
+      hevc + flac + ass(eng) parsed, output streams excluded)
+- [x] 1.2 hls-session-manager: `audioTrackIndex` option → `-map 0:a:N`,
+      part of the session key; transcode-sessions route passthrough
+- [x] 1.3 routes/api/subtitles/get.js: streaming WebVTT extraction, 422 on
+      no-output tracks, kill on client disconnect, 30 min cap (verified:
+      real cues extracted from the embedded ASS track over the LAN proxy)
+- [x] 1.4 torrent-pool: mask the announce query string (passkey)
+
+## 2. Release
+
+- [ ] 2.1 `npm run patch` (2.9.26; needs npm 2FA), then ha-addon 0.2.48
+- [ ] 2.2 After the addon updates: verify plan lists tracks and
+      /api/subtitles serves VTT from the addon proxy

package/openspec/config.yaml

@@ -0,0 +1,38 @@
+schema: spec-driven
+
+context: |
+  @torrent-tv/proxy — WebTorrent + ffmpeg, published to npm. Downloads a torrent
+  and streams the chosen file to the browser over a WebRTC data channel (plain
+  HTTPS transport planned), transcoding to HLS only for the track(s) the browser
+  cannot play natively (supported track = copied).
+  Constraints (see CLAUDE.md for the full set):
+  - Deployment-agnostic: the HA addon is only one way to run it. No
+    Home-Assistant assumptions; runtime detection with graceful fallback only.
+  - Routes: routes/<path>/<method>.js exporting handle<Name><Method>.
+  - All code, comments and docs in English.
+  - Every behavioural change adds a CHANGELOG.md entry at current package.json
+    version + 1 patch. Never edit package.json version (npm run patch bumps it).
+  - Any behavioural proxy change requires bumping ha-addon config.yaml version
+    in the same changeset (the addon must be re-released to pull the new proxy).
+  - HLS is VOD-only with server-side seeking (never -hls_playlist_type event).
+  - Hardware encoders are gated by a strict startup test; software libx264 is
+    the fallback.
+
+# Project context (optional)
+# This is shown to AI when creating artifacts.
+# Add your tech stack, conventions, style guides, domain knowledge, etc.
+# Example:
+#   context: |
+#     Tech stack: TypeScript, React, Node.js
+#     We use conventional commits
+#     Domain: e-commerce platform
+
+# Per-artifact rules (optional)
+# Add custom rules for specific artifacts.
+# Example:
+#   rules:
+#     proposal:
+#       - Keep proposals under 500 words
+#       - Always include a "Non-goals" section
+#     tasks:
+#       - Break tasks into chunks of max 2 hours

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.9.24",
+  "version": "2.9.26",
   "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
   "license": "GPL-3.0-or-later",
   "publishConfig": {

package/routes/api/sources/files/get.js

@@ -0,0 +1,43 @@
+/**
+ * List the files of a registered source (torrent file OR magnet).
+ *
+ * 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.
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{
+ *   sourceRegistry: ReturnType<import("../../../../store/source-registry.js").createSourceRegistry>,
+ *   torrentPool: import("../../../../services/torrent-pool.js").TorrentPool
+ * }} deps
+ * @returns {Promise<void>}
+ */
+export async function handleApiSourceFilesGet(req, reply, { sourceRegistry, torrentPool }) {
+  const sourceKey = typeof req.params?.sourceKey === "string" ? req.params.sourceKey.trim() : "";
+  if (!sourceKey) {
+    return reply.code(400).send({ error: "sourceKey is required." });
+  }
+  const sourceRecord = sourceRegistry.get(sourceKey);
+  if (!sourceRecord) {
+    return reply.code(404).send({ error: "Source key was not found." });
+  }
+
+  const torrent = await torrentPool.getTorrent(sourceRecord.sourceType, sourceRecord.source);
+  const files = (torrent.files ?? []).map((file, index) => ({
+    index,
+    name: file?.name ?? "",
+    // Path relative to the torrent root (matches the browser's own parser).
+    relativePath: file?.path ?? file?.name ?? "",
+    length: Number.isFinite(file?.length) ? file.length : 0
+  }));
+
+  return reply.send({
+    name: torrent.name ?? "",
+    infoHash: torrent.infoHash ?? "",
+    files
+  });
+}

package/routes/api/subtitles/get.js

@@ -0,0 +1,129 @@
+/**
+ * Extract an embedded text subtitle track from a torrent file as WebVTT.
+ *
+ * GET /api/subtitles?sourceKey=...&fileIndex=N&trackIndex=M
+ *
+ * `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.
+ *
+ * @param {import("fastify").FastifyRequest} req
+ * @param {import("fastify").FastifyReply} reply
+ * @param {{
+ *   sourceRegistry: ReturnType<import("../../../store/source-registry.js").createSourceRegistry>,
+ *   torrentPool: import("../../../services/torrent-pool.js").TorrentPool,
+ *   ffmpegBin: string,
+ *   localBaseUrl: string
+ * }} deps
+ * @returns {Promise<void>}
+ */
+
+import { spawn } from "node:child_process";
+
+// Safety cap: no extraction may outlive this (a dead swarm would otherwise
+// hold the ffmpeg process forever).
+const EXTRACTION_TIMEOUT_MS = 30 * 60 * 1000;
+
+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 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." });
+  }
+
+  const sourceRecord = sourceRegistry.get(sourceKey);
+  if (!sourceRecord) {
+    return reply.code(404).send({ error: "Source key was not found." });
+  }
+  const torrent = await torrentPool.getTorrent(sourceRecord.sourceType, sourceRecord.source);
+  if (!torrent.files[fileIndex]) {
+    return reply.code(404).send({ error: "File index was not found in torrent." });
+  }
+
+  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"
+    ],
+    { stdio: ["ignore", "pipe", "pipe"], windowsHide: true }
+  );
+
+  let stderr = "";
+  ffmpeg.stderr.on("data", (chunk) => {
+    if (stderr.length < 4096) {
+      stderr += String(chunk);
+    }
+  });
+
+  const killTimer = setTimeout(() => {
+    if (!ffmpeg.killed) {
+      ffmpeg.kill("SIGKILL");
+    }
+  }, EXTRACTION_TIMEOUT_MS);
+  killTimer.unref?.();
+
+  // Stop extracting when the client goes away.
+  req.raw.on("close", () => {
+    clearTimeout(killTimer);
+    if (!ffmpeg.killed) {
+      ffmpeg.kill("SIGTERM");
+    }
+  });
+
+  // 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) => {
+      if (!settled) {
+        settled = true;
+        resolve(value);
+      }
+    };
+    ffmpeg.stdout.once("data", (chunk) => settle(chunk));
+    ffmpeg.once("exit", () => settle(null));
+    ffmpeg.once("error", () => settle(null));
+  });
+
+  if (firstChunk === null) {
+    clearTimeout(killTimer);
+    return reply
+      .code(422)
+      .send({ error: `Subtitle track could not be extracted: ${stderr.trim() || "no output from ffmpeg"}` });
+  }
+
+  reply.raw.writeHead(200, {
+    "content-type": "text/vtt; charset=utf-8",
+    "cache-control": "no-store",
+    "access-control-allow-origin": "*"
+  });
+  reply.raw.write(firstChunk);
+  ffmpeg.stdout.pipe(reply.raw);
+  await new Promise((resolve) => {
+    ffmpeg.stdout.once("end", resolve);
+    ffmpeg.once("error", resolve);
+  });
+  clearTimeout(killTimer);
+  reply.raw.end();
+  return reply;
+}

package/routes/api/transcode-sessions/post.js

@@ -34,6 +34,7 @@ export async function handleApiTranscodeSessionsPost(req, reply, { hlsSessionMan
   const targetWidth = Number(payload.targetWidth);
   const targetHeight = Number(payload.targetHeight);
   const startPositionSeconds = Number(payload.startPositionSeconds);
+  const audioTrackIndex = Number(payload.audioTrackIndex);
 
   if (!sourceKey || !Number.isInteger(fileIndex) || fileIndex < 0) {
     return reply.code(400).send({ error: "sourceKey and valid fileIndex are required." });
@@ -52,7 +53,9 @@ export async function handleApiTranscodeSessionsPost(req, reply, { hlsSessionMan
       startPositionSeconds:
         Number.isFinite(startPositionSeconds) && startPositionSeconds > 0
           ? startPositionSeconds
-          : 0
+          : 0,
+      audioTrackIndex:
+        Number.isInteger(audioTrackIndex) && audioTrackIndex > 0 ? audioTrackIndex : 0
     });
     return reply.send({
       sessionId: session.id,

package/routes/health/get.js

@@ -5,8 +5,9 @@
  *
  * @param {import("fastify").FastifyRequest} _req
  * @param {import("fastify").FastifyReply} reply
+ * @param {{ version: string }} deps
  * @returns {Promise<void>}
  */
-export async function handleHealthGet(_req, reply) {
-  return reply.send({ ok: true });
+export async function handleHealthGet(_req, reply, { version } = {}) {
+  return reply.send({ ok: true, version });
 }

package/routes/healthz/get.js

@@ -5,8 +5,9 @@
  *
  * @param {import("fastify").FastifyRequest} _req
  * @param {import("fastify").FastifyReply} reply
+ * @param {{ version: string }} deps
  * @returns {Promise<void>}
  */
-export async function handleHealthzGet(_req, reply) {
-  return reply.send({ ok: true });
+export async function handleHealthzGet(_req, reply, { version } = {}) {
+  return reply.send({ ok: true, version });
 }

package/server.js

@@ -12,12 +12,15 @@ import fastifyHelmet from "@fastify/helmet";
 import fastifyStatic from "@fastify/static";
 import getPort from "get-port";
 import path from "node:path";
+import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { handleHealthGet } from "./routes/health/get.js";
 import { handleHealthzGet } from "./routes/healthz/get.js";
 import { handleApiSourcesPost } from "./routes/api/sources/post.js";
 import { handleApiSourceStatsGet } from "./routes/api/sources/stats/get.js";
+import { handleApiSourceFilesGet } from "./routes/api/sources/files/get.js";
 import { handleApiPlaybackPlanPost } from "./routes/api/playback-plan/post.js";
+import { handleApiSubtitlesGet } from "./routes/api/subtitles/get.js";
 import { handleApiTranscodeSessionsPost } from "./routes/api/transcode-sessions/post.js";
 import { handleApiTranscodeSessionsProgressGet } from "./routes/api/transcode-sessions/progress/get.js";
 import { handleApiTranscodeSessionReleasePost } from "./routes/api/transcode-sessions/release/post.js";
@@ -32,6 +35,8 @@ import { logger } from "./utils/logger.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+const require = createRequire(import.meta.url);
+const { version } = require("./package.json");
 const publicRoot = path.resolve(__dirname, "./public");
 
 /**
@@ -121,17 +126,28 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin }
     torrentPool
   });
 
-  app.get("/health", async (req, reply) => handleHealthGet(req, reply));
-  app.get("/healthz", async (req, reply) => handleHealthzGet(req, reply));
+  app.get("/health", async (req, reply) => handleHealthGet(req, reply, { version }));
+  app.get("/healthz", async (req, reply) => handleHealthzGet(req, reply, { version }));
   app.post("/api/sources", async (req, reply) =>
     handleApiSourcesPost(req, reply, { sourceRegistry })
   );
   app.get("/api/sources/:sourceKey/stats", async (req, reply) =>
     handleApiSourceStatsGet(req, reply, { sourceRegistry, torrentPool })
   );
+  app.get("/api/sources/:sourceKey/files", async (req, reply) =>
+    handleApiSourceFilesGet(req, reply, { sourceRegistry, torrentPool })
+  );
   app.post("/api/playback-plan", async (req, reply) =>
     handleApiPlaybackPlanPost(req, reply, { playbackPlanner })
   );
+  app.get("/api/subtitles", async (req, reply) =>
+    handleApiSubtitlesGet(req, reply, {
+      sourceRegistry,
+      torrentPool,
+      ffmpegBin,
+      localBaseUrl: hlsSessionManager.localBaseUrl
+    })
+  );
   app.get("/stream", async (req, reply) =>
     handleStreamGet(req, reply, { sourceRegistry, torrentPool })
   );

package/services/hls-session-manager.js

@@ -642,6 +642,7 @@ export class HlsSessionManager {
    * @param {number}  [options.targetWidth=0]            - Target video width (0 = keep source).
    * @param {number}  [options.targetHeight=0]           - Target video height (0 = keep source).
    * @param {number}  [options.startPositionSeconds=0]   - Seek start position in seconds.
+   * @param {number}  [options.audioTrackIndex=0]        - Type-relative audio track to map (0:a:N).
    * @returns {Promise<HlsSession>}
    */
   async createOrGetSession({
@@ -653,7 +654,8 @@ export class HlsSessionManager {
     fileName = "",
     targetWidth = 0,
     targetHeight = 0,
-    startPositionSeconds = 0
+    startPositionSeconds = 0,
+    audioTrackIndex = 0
   }) {
     if (!this.enabled) {
       const error = new Error("Audio transcoding is disabled on this proxy.");
@@ -669,11 +671,14 @@ export class HlsSessionManager {
       Number.isFinite(startPositionSeconds) && startPositionSeconds > 0
         ? Math.round(startPositionSeconds / 10) * 10
         : 0;
+    const normalizedAudioTrack =
+      Number.isInteger(audioTrackIndex) && audioTrackIndex > 0 ? audioTrackIndex : 0;
     const sourceMapKey = [
       sourceKey,
       String(fileIndex),
       transcodeVideo ? "video" : "audio",
       transcodeAudio ? "a1" : "a0",
+      `t${normalizedAudioTrack}`,
       String(normalizedTargetWidth),
       String(normalizedTargetHeight),
       String(normalizedStartPosition)
@@ -783,6 +788,7 @@ export class HlsSessionManager {
       fileIndex,
       transcodeVideo,
       transcodeAudio,
+      audioTrackIndex: normalizedAudioTrack,
       targetWidth: normalizedTargetWidth,
       targetHeight: normalizedTargetHeight,
       sourceWidth,
@@ -1043,7 +1049,8 @@ export class HlsSessionManager {
       "-map",
       "0:v:0?",
       "-map",
-      "0:a:0?",
+      // Type-relative audio track chosen by the viewer (default 0).
+      `0:a:${session.audioTrackIndex ?? 0}?`,
       ...videoCodecArgs,
       ...audioCodecArgs,
       "-f",