@torrent-tv/proxy 1.0.0

package/.dockerignore

@@ -0,0 +1,5 @@
+node_modules
+npm-debug.log
+.DS_Store
+.git
+.gitignore

package/Dockerfile

@@ -0,0 +1,30 @@
+# syntax=docker/dockerfile:1.7
+FROM node:22-alpine
+
+ENV NODE_ENV=production
+ENV PORT=9090
+ENV HOST=0.0.0.0
+
+WORKDIR /app
+
+# ffmpeg is needed for optional HLS audio transcode mode.
+RUN apk add --no-cache ffmpeg
+
+# Create an unprivileged runtime user.
+RUN addgroup -S app && adduser -S -G app app
+
+# Install only production dependencies first for better layer caching.
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev && npm cache clean --force
+
+# Copy application sources.
+COPY --chown=app:app . .
+
+USER app
+
+EXPOSE 9090
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+  CMD node -e "fetch(`http://127.0.0.1:${process.env.PORT || 9090}/healthz`).then((r)=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+
+CMD ["sh", "-ec", "if [ -z \"${SERVER_URL:-}\" ]; then echo 'SERVER_URL is required' >&2; exit 1; fi; exec node ./bin/cli.js --server-url \"$SERVER_URL\" --host \"$HOST\" --port \"$PORT\" ${PROXY_EXTRA_ARGS:-}"]

package/LICENSE

@@ -0,0 +1,16 @@
+Copyright (C) 2026 Anton Nemtsev
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+SPDX-License-Identifier: GPL-3.0-or-later

package/README.md

@@ -0,0 +1,230 @@
+# Torrent Proxy Client
+
+`@torrent-tv/proxy` is a lightweight Node.js service that turns torrent content into HTTP endpoints that are easy to consume from web players and backend services.
+
+It is designed for setups where a central registry/UI needs a simple direct media URL, while the actual torrent fetching happens on a separate edge/client machine.
+
+## Why this exists
+
+- Browsers and many media players cannot consume torrents directly.
+- This service exposes torrent files through regular HTTP (`/stream`) with range support.
+- It can optionally create HLS sessions with AAC audio when direct playback is not suitable.
+- It can also create HLS sessions with video transcoding when browser-side decode still fails.
+- It registers itself in an external registry service and sends heartbeats, so other services can discover and use it.
+
+## What it does
+
+- Runs a Fastify server with health and media endpoints.
+- Accepts torrent sources (`magnet` or base64 `.torrent`) and returns a stable `sourceKey`.
+- Streams a selected file from a torrent by `fileIndex`.
+- Builds a playback plan (`direct` vs `hls`) based on detected audio codec and returns both audio/video codecs.
+- Starts ffmpeg-based HLS transcoding sessions (`audio-only` or `video+audio`) and serves generated playlist/segments.
+- Tracks multi-client consumers per transcode session and stops ffmpeg when the last consumer releases.
+
+## Requirements
+
+- Node.js 18+ (ESM and built-in `fetch` are required).
+- npm.
+- ffmpeg is required only when audio transcoding is enabled.
+  - By default, the package uses `ffmpeg-static`.
+  - You can override binary path with `--ffmpeg-bin`.
+  - You can disable transcoding with `--no-transcode-audio`.
+
+## Install
+
+```bash
+npm install
+```
+
+## Run
+
+```bash
+npm start -- --server-url http://localhost:3000
+```
+
+Minimal required argument:
+
+- `--server-url <url>`: base URL of your registry server.
+
+Useful optional arguments:
+
+- `--host <host>`: bind host (default `127.0.0.1`).
+- `--port <port>`: preferred local port (default `9090`; first free port in range is selected).
+- `--public-base-url <url>`: externally reachable base URL advertised to registry.
+- `--id <id>`: stable proxy client id.
+- `--name <name>`: display name for registry.
+- `--token <token>`: token sent to register/heartbeat endpoints.
+- `--ffmpeg-bin <path>`: custom ffmpeg binary path.
+- `--no-transcode-audio`: disable HLS audio transcoding.
+- `--help`: print all options with descriptions and examples, then exit.
+
+## HTTP API
+
+Base URL examples below use `http://127.0.0.1:9090`.
+
+### Health
+
+```bash
+curl http://127.0.0.1:9090/health
+curl http://127.0.0.1:9090/healthz
+```
+
+### 1) Register a source
+
+```bash
+curl -X POST http://127.0.0.1:9090/api/sources \
+  -H "Content-Type: application/json" \
+  -d '{
+    "sourceType": "magnet",
+    "source": "magnet:?xt=urn:btih:..."
+  }'
+```
+
+Response:
+
+```json
+{ "sourceKey": "..." }
+```
+
+Supported `sourceType` values:
+
+- `magnet`: magnet URI string.
+- `torrent`: base64-encoded raw `.torrent` file bytes.
+
+### 2) Build playback plan
+
+```bash
+curl -X POST http://127.0.0.1:9090/api/playback-plan \
+  -H "Content-Type: application/json" \
+  -d '{
+    "sourceKey": "<sourceKey>",
+    "fileIndex": 0,
+    "userAgent": "Mozilla/5.0"
+  }'
+```
+
+Typical response:
+
+```json
+{
+  "mode": "direct",
+  "directUrl": "http://127.0.0.1:9090/stream?sourceKey=...&fileIndex=0",
+  "reason": "audio-codec-supported",
+  "audioCodec": "aac",
+  "videoCodec": "h264"
+}
+```
+
+`mode` can be:
+
+- `direct`: play `directUrl` directly.
+- `hls`: create an HLS session, then use playlist URL.
+
+### 3) Direct stream endpoint
+
+```bash
+curl -v "http://127.0.0.1:9090/stream?sourceKey=<sourceKey>&fileIndex=0"
+```
+
+Or without pre-registering source:
+
+```bash
+curl -v "http://127.0.0.1:9090/stream?sourceType=magnet&source=magnet:?xt=...&fileIndex=0"
+```
+
+The endpoint supports HTTP Range requests.
+
+### 4) Create HLS transcode session (optional)
+
+```bash
+curl -X POST http://127.0.0.1:9090/api/transcode-sessions \
+  -H "Content-Type: application/json" \
+  -d '{
+    "sourceKey": "<sourceKey>",
+    "fileIndex": 0,
+    "transcodeVideo": false,
+    "consumerId": "browser-session-uuid",
+    "fileName": "Episode01.mkv"
+  }'
+```
+
+Set `"transcodeVideo": true` to force video transcoding (for browser decode fallback cases).
+
+Response:
+
+```json
+{
+  "sessionId": "...",
+  "playlistPath": "/transcode/<sessionId>/index.m3u8"
+}
+```
+
+Open playlist as:
+
+`http://127.0.0.1:9090/transcode/<sessionId>/index.m3u8`
+
+### 5) Poll transcode progress
+
+```bash
+curl "http://127.0.0.1:9090/api/transcode-sessions/<sessionId>/progress"
+```
+
+Response includes transcode and warmup metrics:
+- `percent`, `processedSeconds`, `totalSeconds`, `remainingSeconds`, `speed`
+- `warmupPercent`, `warmupRemainingSeconds`
+
+### 6) Release transcode consumer
+
+```bash
+curl -X POST http://127.0.0.1:9090/api/transcode-sessions/<sessionId>/release \
+  -H "Content-Type: application/json" \
+  -d '{
+    "consumerId": "browser-session-uuid",
+    "reason": "pagehide"
+  }'
+```
+
+When the last consumer is released, proxy disposes the session and stops ffmpeg.
+
+## End-to-end flow
+
+1. Start proxy client with `--server-url`.
+2. Register torrent source via `/api/sources` and get `sourceKey`.
+3. Request `/api/playback-plan`.
+4. If plan is `direct`, use `directUrl`.
+5. If plan is `hls`, create session and play generated playlist.
+6. Poll `/progress` for UI updates, then release session on client stop/close.
+
+## Transcode Session Lifecycle
+
+```mermaid
+sequenceDiagram
+  participant C as Client
+  participant P as Proxy
+  participant F as FFmpeg
+
+  C->>P: POST /api/transcode-sessions (consumerId, mode, fileName)
+  P->>F: start/reuse transcode session
+  C->>P: GET /transcode/:sessionId/index.m3u8
+  C->>P: GET /api/transcode-sessions/:sessionId/progress
+  C->>P: POST /api/transcode-sessions/:sessionId/release (reason)
+  P->>P: remove consumer
+  alt no consumers left
+    P->>F: stop process and cleanup
+  end
+```
+
+## Notes
+
+- HLS session files are stored in OS temp directory and cleaned up automatically.
+- Transcode sessions are cached by `sourceKey:fileIndex:mode`.
+- ffmpeg is bundled via `ffmpeg-static` for out-of-the-box availability.
+- Source registry is in-memory and bounded (old entries are evicted).
+
+## License
+
+This project is distributed under GPL-3.0-or-later (see `LICENSE`).
+
+Third-party dependencies keep their own licenses. In particular, bundled ffmpeg binaries
+provided by `ffmpeg-static` are GPL-compatible.
+

package/bin/cli.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+import chalk from "chalk";
+import { Command } from "commander";
+import crypto from "node:crypto";
+import { spawnSync } from "node:child_process";
+import ffmpegStatic from "ffmpeg-static";
+import { startProxyServer } from "../server.js";
+import { registerClient, sendHeartbeat } from "../services/registry-api.js";
+
+const program = new Command();
+
+const HELP_EXAMPLES = `
+Examples:
+  torrent-tv-proxy --server-url http://localhost:8080
+  torrent-tv-proxy --server-url http://localhost:8080 --host 0.0.0.0 --port 9090
+  torrent-tv-proxy --server-url http://localhost:8080 --public-base-url https://proxy.example.com
+  torrent-tv-proxy --server-url http://localhost:8080 --ffmpeg-bin /usr/local/bin/ffmpeg
+  torrent-tv-proxy --server-url http://localhost:8080 --no-transcode-audio
+
+Notes:
+  - --help prints this message and exits with code 0.
+  - Video transcode is available automatically for per-session fallback when requested by client API.
+`;
+
+if (process.argv.includes("help")) {
+  process.argv = [process.argv[0], process.argv[1], "--help"];
+}
+
+program
+  .name("torrent-proxy-client")
+  .description("Expose torrent files over HTTP stream endpoints for browser playback.")
+  .requiredOption("--server-url <url>", "Registry server base URL")
+  .option("--public-base-url <url>", "Direct URL advertised to browser clients")
+  .option("--host <host>", "Local bind host", "127.0.0.1")
+  .option("--port <port>", "Local HTTP port", "9090")
+  .option("--id <id>", "Stable client id")
+  .option("--name <name>", "Display name")
+  .option("--no-transcode-audio", "Disable optional HLS AAC audio transcoding")
+  .option("--ffmpeg-bin <path>", "Path to ffmpeg binary")
+  .option("--token <token>", "Registration token", "")
+  .addHelpText("after", HELP_EXAMPLES);
+
+program.parse(process.argv);
+const options = program.opts();
+
+const localPort = Number(options.port);
+if (!Number.isInteger(localPort) || localPort <= 0 || localPort > 65535) {
+  console.error(chalk.red("[proxy-client] Invalid --port value."));
+  process.exit(1);
+}
+
+const serverUrl = String(options.serverUrl).replace(/\/+$/, "");
+const bindHost = String(options.host);
+const explicitBaseUrl = options.publicBaseUrl
+  ? String(options.publicBaseUrl).replace(/\/+$/, "")
+  : "";
+const clientId = options.id ? String(options.id) : crypto.randomUUID();
+const clientName = options.name ? String(options.name) : `proxy-${clientId.slice(0, 8)}`;
+const token = String(options.token ?? "");
+const transcodeAudio = options.transcodeAudio !== false;
+const bundledFfmpegBin = typeof ffmpegStatic === "string" ? ffmpegStatic : "";
+const ffmpegBin = options.ffmpegBin ? String(options.ffmpegBin) : bundledFfmpegBin || "ffmpeg";
+
+function assertFfmpegAvailability() {
+  const probe = spawnSync(ffmpegBin, ["-version"], {
+    stdio: "ignore",
+    windowsHide: true,
+    timeout: 5000
+  });
+  if (probe.error) {
+    const message = probe.error instanceof Error ? probe.error.message : String(probe.error);
+    throw new Error(`Audio transcode is enabled, but ffmpeg is unavailable (${ffmpegBin}): ${message}`);
+  }
+  if (typeof probe.status === "number" && probe.status !== 0) {
+    throw new Error(
+      `Audio transcode is enabled, but ffmpeg check failed (${ffmpegBin}, exit code ${probe.status}).`
+    );
+  }
+}
+
+let registrationInProgress = false;
+let heartbeatTimer = null;
+let app = null;
+let actualPort = localPort;
+let shutdownInProgress = false;
+
+async function registerClientSafe() {
+  if (registrationInProgress) {
+    return;
+  }
+  registrationInProgress = true;
+  try {
+    const result = await registerClient({
+      serverUrl,
+      id: clientId,
+      name: clientName,
+      baseUrl: explicitBaseUrl || `http://${bindHost}:${actualPort}`,
+      token
+    });
+    console.log(chalk.green(`[proxy-client] Registered: ${JSON.stringify(result.client)}`));
+  } finally {
+    registrationInProgress = false;
+  }
+}
+
+async function shutdown(signal) {
+  if (shutdownInProgress) {
+    return;
+  }
+  shutdownInProgress = true;
+  if (heartbeatTimer) {
+    clearInterval(heartbeatTimer);
+    heartbeatTimer = null;
+  }
+  console.log(chalk.yellow(`[proxy-client] Received ${signal}, shutting down...`));
+  try {
+    if (app) {
+      await app.close();
+    }
+    process.exit(0);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(chalk.red(`[proxy-client] Shutdown failed: ${message}`));
+    process.exit(1);
+  }
+}
+
+try {
+  if (transcodeAudio) {
+    assertFfmpegAvailability();
+  }
+  const started = await startProxyServer({
+    host: bindHost,
+    port: localPort,
+    transcodeAudio,
+    ffmpegBin
+  });
+  app = started.app;
+  actualPort = started.port;
+  const directBaseUrl = explicitBaseUrl || `http://${bindHost}:${actualPort}`;
+
+  console.log(chalk.cyan(`[proxy-client] Local stream endpoint: http://${bindHost}:${actualPort}/stream`));
+  console.log(chalk.cyan(`[proxy-client] Advertised direct URL: ${directBaseUrl}`));
+  if (transcodeAudio) {
+    console.log(
+      chalk.cyan(`[proxy-client] Optional HLS audio transcode is enabled (ffmpeg: ${ffmpegBin}).`)
+    );
+  }
+
+  await registerClientSafe();
+
+  heartbeatTimer = setInterval(async () => {
+    const status = await sendHeartbeat({
+      serverUrl,
+      id: clientId,
+      token
+    });
+    if (status === 404) {
+      console.log(chalk.yellow("[proxy-client] Heartbeat returned 404, re-registering..."));
+      try {
+        await registerClientSafe();
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(chalk.red(`[proxy-client] Re-register failed: ${message}`));
+      }
+    }
+  }, 20_000);
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(chalk.red(`[proxy-client] ${message}`));
+  process.exit(1);
+}
+
+process.on("SIGINT", () => {
+  void shutdown("SIGINT");
+});
+
+process.on("SIGTERM", () => {
+  void shutdown("SIGTERM");
+});

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@torrent-tv/proxy",
+  "version": "1.0.0",
+  "description": "Torrent proxy client that exposes webseed-like HTTP stream endpoint.",
+  "license": "GPL-3.0-or-later",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "torrent-tv-proxy": "./bin/cli.js"
+  },
+  "scripts": {
+    "patch": "npm version patch && npm publish && git push --follow-tags",
+    "minor": "npm version minor && npm publish && git push --follow-tags",
+    "major": "npm version major && npm publish && git push --follow-tags",
+    "start": "node ./bin/cli.js",
+    "dev": "node --inspect=0 --experimental-network-inspection ./bin/cli.js"
+  },
+  "dependencies": {
+    "@fastify/cors": "^11.2.0",
+    "@fastify/helmet": "^13.0.2",
+    "@fastify/static": "^9.1.3",
+    "chalk": "^5.4.1",
+    "commander": "^12.1.0",
+    "fastify": "^5.8.5",
+    "ffmpeg-static": "^5.3.0",
+    "get-port": "^7.1.0",
+    "webtorrent": "^2.8.4"
+  }
+}

package/public/.well-known/appspecific/com.chrome.devtools.json

@@ -0,0 +1 @@
+{}

package/routes/api/playback-plan/post.js

@@ -0,0 +1,31 @@
+function getPayload(body) {
+  if (body && typeof body === "object" && !Array.isArray(body)) {
+    return body;
+  }
+  return {};
+}
+
+export async function handleApiPlaybackPlanPost(req, reply, { playbackPlanner }) {
+  const payload = getPayload(req.body);
+  const sourceKey = typeof payload.sourceKey === "string" ? payload.sourceKey.trim() : "";
+  const fileIndex = Number(payload.fileIndex);
+  const userAgent = typeof payload.userAgent === "string" ? payload.userAgent : "";
+
+  if (!sourceKey || !Number.isInteger(fileIndex) || fileIndex < 0) {
+    return reply.code(400).send({ error: "sourceKey and valid fileIndex are required." });
+  }
+
+  try {
+    const plan = await playbackPlanner.getPlan({ sourceKey, fileIndex, userAgent });
+    return reply.send(plan);
+  } catch (error) {
+    if (error instanceof Error && error.code === "SOURCE_NOT_FOUND") {
+      return reply.code(404).send({ error: error.message });
+    }
+    if (error instanceof Error && error.code === "FILE_NOT_FOUND") {
+      return reply.code(404).send({ error: error.message });
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return reply.code(500).send({ error: `Failed to prepare playback plan: ${message}` });
+  }
+}

package/routes/api/sources/post.js

@@ -0,0 +1,18 @@
+function getPayload(body) {
+  if (body && typeof body === "object" && !Array.isArray(body)) {
+    return body;
+  }
+  return {};
+}
+
+export async function handleApiSourcesPost(req, reply, { sourceRegistry }) {
+  const payload = getPayload(req.body);
+  const sourceType = typeof payload.sourceType === "string" ? payload.sourceType : "";
+  const source = typeof payload.source === "string" ? payload.source : "";
+  if (!sourceType || !source) {
+    return reply.code(400).send({ error: "sourceType and source are required." });
+  }
+
+  const sourceKey = sourceRegistry.upsert(sourceType, source);
+  return reply.send({ sourceKey });
+}

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

@@ -0,0 +1,39 @@
+function getPayload(body) {
+  if (body && typeof body === "object" && !Array.isArray(body)) {
+    return body;
+  }
+  return {};
+}
+
+export async function handleApiTranscodeSessionsPost(req, reply, { hlsSessionManager }) {
+  const payload = getPayload(req.body);
+  const sourceKey = typeof payload.sourceKey === "string" ? payload.sourceKey.trim() : "";
+  const fileIndex = Number(payload.fileIndex);
+  const transcodeVideo = payload.transcodeVideo === true;
+  const consumerId = typeof payload.consumerId === "string" ? payload.consumerId.trim() : "";
+  const fileName = typeof payload.fileName === "string" ? payload.fileName.trim() : "";
+
+  if (!sourceKey || !Number.isInteger(fileIndex) || fileIndex < 0) {
+    return reply.code(400).send({ error: "sourceKey and valid fileIndex are required." });
+  }
+
+  try {
+    const session = await hlsSessionManager.createOrGetSession({
+      sourceKey,
+      fileIndex,
+      transcodeVideo,
+      consumerId,
+      fileName
+    });
+    return reply.send({
+      sessionId: session.id,
+      playlistPath: `/transcode/${session.id}/index.m3u8`
+    });
+  } catch (error) {
+    if (error instanceof Error && error.code === "TRANSCODE_DISABLED") {
+      return reply.code(409).send({ error: error.message });
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return reply.code(500).send({ error: `Failed to prepare transcode session: ${message}` });
+  }
+}

package/routes/api/transcode-sessions/progress/get.js

@@ -0,0 +1,13 @@
+export async function handleApiTranscodeSessionsProgressGet(req, reply, { hlsSessionManager }) {
+  const sessionId = typeof req.params.sessionId === "string" ? req.params.sessionId : "";
+  if (!sessionId) {
+    return reply.code(400).send({ error: "sessionId is required." });
+  }
+
+  const progress = hlsSessionManager.getSessionProgress(sessionId);
+  if (!progress) {
+    return reply.code(404).send({ error: "Transcode session was not found." });
+  }
+
+  return reply.send(progress);
+}

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

@@ -0,0 +1,22 @@
+function getPayload(body) {
+  if (body && typeof body === "object" && !Array.isArray(body)) {
+    return body;
+  }
+  return {};
+}
+
+export async function handleApiTranscodeSessionReleasePost(req, reply, { hlsSessionManager }) {
+  const sessionId = typeof req.params.sessionId === "string" ? req.params.sessionId : "";
+  const payload = getPayload(req.body);
+  const consumerId = typeof payload.consumerId === "string" ? payload.consumerId.trim() : "";
+  const reason = typeof payload.reason === "string" ? payload.reason.trim() : "";
+  if (!sessionId || !consumerId) {
+    return reply.code(400).send({ error: "sessionId and consumerId are required." });
+  }
+
+  const released = await hlsSessionManager.releaseSessionConsumer(sessionId, consumerId, reason);
+  if (!released) {
+    return reply.code(404).send({ error: "Transcode session was not found." });
+  }
+  return reply.send({ ok: true });
+}

package/routes/health/get.js

@@ -0,0 +1,3 @@
+export async function handleHealthGet(_req, reply) {
+  return reply.send({ ok: true });
+}

package/routes/healthz/get.js

@@ -0,0 +1,3 @@
+export async function handleHealthzGet(_req, reply) {
+  return reply.send({ ok: true });
+}