@torrent-tv/proxy 2.9.25 → 2.9.27

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 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.
+
+## 2.9.26
+
+- **New**: Track inventory in the playback plan (OpenSpec change `track-selection`). The codec probe now parses EVERY input stream from the same ffmpeg banner, and the plan returns `audioTracks` and `subtitleTracks` — type-relative index, codec, language tag, `title` metadata, default disposition, and (for subtitles) a `textBased` flag (PGS/VobSub cannot become WebVTT).
+- **New**: Audio track selection for HLS sessions. `POST /api/transcode-sessions` accepts `audioTrackIndex`; the session maps `0:a:N` instead of always the first track, and the index is part of the session key, so switching tracks creates a fresh session (server-side restart) while the old one expires via the idle TTL.
+- **New**: Embedded subtitle extraction — `GET /api/subtitles?sourceKey&fileIndex&trackIndex` streams the chosen text subtitle track converted to WebVTT. Extraction reads the file up to the last cue, so on a cold torrent it drives the sequential download; callers must use a generous timeout. Non-text tracks (or a dead extraction) return 422 before any body.
+- **New**: `GET /api/sources/:sourceKey/files` lists the files of a registered source. Groundwork for magnet-link input (OpenSpec change `magnet-input` in the server repo): the browser parses `.torrent` files locally, but a magnet's file list only exists in swarm metadata — this route resolves the torrent (waiting for metadata on a cold magnet) and returns the inventory.
+- **Chore**: The announce log line strips the query string from the tracker URL — private trackers embed the account passkey there.
+
 ## 2.9.25
 
 - **New**: Observability (OpenSpec change `proxy-observability`). (1) `/healthz` and `/health` now include the proxy `version` — the addon shipped a stale proxy for a whole release and nothing could detect it remotely. (2) Peer-discovery diagnostics in `torrent-pool.js`: each added torrent logs its file count, `private` flag and tracker count; torrent-level `warning` events (tracker rejections/errors) are logged; every tracker announce response is logged with the seeder/leecher counts the tracker returned — so a zero-peer torrent is now explainable from the addon log. (3) Client-level WebTorrent warnings are logged too.

package/openspec/changes/binary-distribution/.openspec.yaml

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

package/openspec/changes/binary-distribution/proposal.md

@@ -0,0 +1,53 @@
+# Proposal: Proxy as a single binary + service registration (research, queued)
+
+## Why
+
+Bare-npm installation assumes Node.js on the host — a real barrier for the
+non-technical proxy owners the pool model targets. Node's Single Executable
+Applications (SEA, stable-ish since Node 20/21) allow shipping the proxy as
+one self-contained binary per platform (win/linux/macOS, x64/arm64): download,
+run, done. A binary can also offer — with the user's explicit consent — to
+register itself as an auto-starting service, closing the "survives reboot"
+gap that the HA addon solves today.
+
+## What Changes (research scope first)
+
+- **SEA build pipeline**: `node --experimental-sea-config` + postject-injected
+  blob, one artifact per platform/arch, published as GitHub release assets
+  alongside the npm package.
+- **Known hard parts to resolve in research**:
+  - Native addons (`node-datachannel`, `utp-native`) cannot live inside the
+    SEA blob — they must ship next to the binary or self-extract on first
+    run to a data dir.
+  - `ffmpeg-static`'s binary likewise ships alongside (or the system ffmpeg
+    is required, as the HA addon already does with `--ffmpeg-bin`).
+- **Service registration (opt-in, explicit user action)**:
+  - Linux: `proxy install-service` writes a systemd unit and runs
+    `systemctl enable --now` (requires sudo — the consent step).
+  - Windows: register via `sc create` / a service wrapper (admin prompt =
+    consent).
+  - macOS: launchd plist in `~/Library/LaunchAgents` (user-level, no admin).
+  - Uninstall counterpart mandatory (`proxy uninstall-service`).
+- Stays deployment-agnostic: the binary is a fourth distribution channel
+  next to HA addon, bare npm and Docker; no code paths may assume it.
+
+## Capabilities
+
+### New Capabilities
+
+- `distribution`: how the proxy is packaged and installed on bare hosts.
+
+### Modified Capabilities
+
+<!-- none -->
+
+## Impact
+
+- Build/release tooling in this repo; a `service` CLI subcommand.
+- No changes to runtime behaviour for existing channels.
+
+## Priority
+
+MINIMAL — explicitly NOT part of the POC (owner decision, 2026-07-07).
+Research for the eventual "pool of non-technical owners" product goal; do
+not pick up while any POC work remains.

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

@@ -14,7 +14,8 @@
 ## 2. Release
 
 - [x] 2.1 CHANGELOG.md entry at 2.9.25
-- [ ] 2.2 `npm run patch` (needs npm auth), then ha-addon bump 0.2.47 + push
+- [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/package.json

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

@@ -18,7 +18,9 @@ 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";
@@ -132,9 +134,20 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin }
   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",

package/services/playback-planner.js

@@ -11,6 +11,54 @@ import { spawn } from "node:child_process";
 /** Audio codecs that browsers can decode natively without transcoding. */
 const DIRECT_AUDIO_CODECS = new Set(["aac", "mp3", "opus", "vorbis", "flac"]);
 
+/** Subtitle codecs that can be converted to WebVTT (text-based). */
+const TEXT_SUBTITLE_CODECS = new Set(["subrip", "srt", "ass", "ssa", "webvtt", "vtt", "mov_text", "text"]);
+
+/**
+ * Parse every stream from the ffmpeg `-i` banner: type, codec, language tag,
+ * default disposition and (when present) the stream's `title` metadata line.
+ *
+ * @param {string} ffmpegOutput
+ * @returns {Array<{ streamIndex: number, type: string, codec: string, language: string, title: string, isDefault: boolean }>}
+ */
+function parseStreams(ffmpegOutput) {
+  // Only the Input section: ffmpeg prints Stream lines for the null OUTPUT
+  // too (wrapped_avframe / pcm_s16le), which would duplicate every track.
+  const inputSection = ffmpegOutput.split(/^(?:Output #|Stream mapping:)/m)[0] ?? ffmpegOutput;
+  const lines = inputSection.split(/\r?\n/);
+  const streams = [];
+  let current = null;
+  for (const line of lines) {
+    const streamMatch = line.match(
+      /^\s*Stream #0:(\d+)(?:\[[^\]]*\])?(?:\(([A-Za-z0-9]{2,3})\))?: (Audio|Video|Subtitle): ([A-Za-z0-9_]+)/
+    );
+    if (streamMatch) {
+      current = {
+        streamIndex: Number(streamMatch[1]),
+        type: streamMatch[3].toLowerCase(),
+        codec: String(streamMatch[4]).toLowerCase(),
+        language: (streamMatch[2] ?? "").toLowerCase(),
+        title: "",
+        isDefault: /\(default\)/.test(line)
+      };
+      streams.push(current);
+      continue;
+    }
+    if (current) {
+      const titleMatch = line.match(/^\s+title\s*:\s*(.+)$/);
+      if (titleMatch && current.title.length === 0) {
+        current.title = titleMatch[1].trim();
+        continue;
+      }
+      // A new top-level section (non-indented line) ends the stream's block.
+      if (!/^\s/.test(line)) {
+        current = null;
+      }
+    }
+  }
+  return streams;
+}
+
 /**
  * Parse audio and video codec names from ffmpeg stderr output.
  *
@@ -28,11 +76,38 @@ function parseStreamCodecs(ffmpegOutput) {
       Number(durationMatch[1]) * 3600 + Number(durationMatch[2]) * 60 + Number(durationMatch[3]);
     durationSeconds = Number.isFinite(value) ? value : 0;
   }
+  const streams = parseStreams(ffmpegOutput);
+  const audioTracks = streams
+    .filter((s) => s.type === "audio")
+    .map((s, i) => ({
+      // Type-relative index — what ffmpeg's `-map 0:a:N` selects.
+      index: i,
+      streamIndex: s.streamIndex,
+      codec: s.codec,
+      language: s.language,
+      title: s.title,
+      isDefault: s.isDefault
+    }));
+  const subtitleTracks = streams
+    .filter((s) => s.type === "subtitle")
+    .map((s, i) => ({
+      // Type-relative index — what ffmpeg's `-map 0:s:N` selects.
+      index: i,
+      streamIndex: s.streamIndex,
+      codec: s.codec,
+      language: s.language,
+      title: s.title,
+      isDefault: s.isDefault,
+      // Image-based subtitles (PGS/VobSub) cannot become WebVTT.
+      textBased: TEXT_SUBTITLE_CODECS.has(s.codec)
+    }));
   return {
     audioCodec: audioMatch ? String(audioMatch[1]).toLowerCase() : "",
     videoCodec: videoMatch ? String(videoMatch[1]).toLowerCase() : "",
     container: containerMatch ? String(containerMatch[1]).trim().toLowerCase() : "",
-    durationSeconds
+    durationSeconds,
+    audioTracks,
+    subtitleTracks
   };
 }
 
@@ -213,7 +288,9 @@ export function createPlaybackPlanner({
           audioCodec: "",
           videoCodec: "",
           container: "",
-          durationSeconds: 0
+          durationSeconds: 0,
+          audioTracks: [],
+          subtitleTracks: []
         };
         cache.set(cacheKey, plan);
         return plan;
@@ -239,7 +316,7 @@ export function createPlaybackPlanner({
         await torrentPool.prefetchFileEdges(torrent, fileIndex);
         probe = await probeStreamCodecs({ ffmpegBin, inputUrl: directUrl, userAgent });
       }
-      const { audioCodec, videoCodec, container, durationSeconds } = probe;
+      const { audioCodec, videoCodec, container, durationSeconds, audioTracks, subtitleTracks } = probe;
       const codecsDetected = audioCodec.length > 0 || videoCodec.length > 0;
 
       // `mode` is advisory only (audio-codec based). The browser makes the
@@ -253,7 +330,10 @@ export function createPlaybackPlanner({
         audioCodec,
         videoCodec,
         container,
-        durationSeconds
+        durationSeconds,
+        // Full track inventory for the browser's audio/subtitle menus.
+        audioTracks: audioTracks ?? [],
+        subtitleTracks: subtitleTracks ?? []
       };
       // Only cache a plan whose codecs were actually detected. An empty probe is
       // a "header not downloaded yet" signal, not a valid result — caching it

package/services/torrent-pool.js

@@ -145,7 +145,10 @@ export class TorrentPool {
     const tracker = torrent.discovery?.tracker;
     if (tracker && typeof tracker.on === "function") {
       tracker.on("update", (data) => {
-        const announceUrl = typeof data?.announce === "string" ? data.announce : "?";
+        // Private trackers embed the account passkey in the announce URL —
+        // strip the query string before logging.
+        const announceUrl =
+          typeof data?.announce === "string" ? data.announce.replace(/\?.*$/, "") : "?";
         logger.info(
           `torrent-pool: [${label}] announce ${announceUrl}: ` +
             `seeders=${data?.complete ?? "?"} leechers=${data?.incomplete ?? "?"}`
@@ -184,6 +187,27 @@ export class TorrentPool {
     const promise = new Promise((resolve, reject) => {
       const onError = (error) => {
         this.client.off("error", onError);
+        // The same content can arrive as a .torrent AND as a magnet —
+        // different pool keys, one swarm. WebTorrent rejects the duplicate
+        // add; resolve with the already-loaded torrent instead of failing.
+        const message = error instanceof Error ? error.message : String(error);
+        const dupMatch = /duplicate torrent ([0-9a-f]{40})/i.exec(message);
+        if (dupMatch) {
+          const existing = this.client.torrents.find((t) => t?.infoHash === dupMatch[1]);
+          if (existing) {
+            const settle = () => {
+              this.torrents.set(key, existing);
+              this.#pending.delete(key);
+              resolve(existing);
+            };
+            if (existing.ready) {
+              settle();
+            } else {
+              existing.once("ready", settle);
+            }
+            return;
+          }
+        }
         this.#pending.delete(key);
         reject(error);
       };