@torrent-tv/proxy 2.8.0 → 2.9.2

package/package.json

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

package/server.js

@@ -27,6 +27,8 @@ import { createSourceRegistry } from "./store/source-registry.js";
 import { TorrentPool } from "./services/torrent-pool.js";
 import { HlsSessionManager } from "./services/hls-session-manager.js";
 import { createPlaybackPlanner } from "./services/playback-planner.js";
+import { detectVideoEncoder } from "./services/hwaccel.js";
+import { logger } from "./utils/logger.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -91,11 +93,18 @@ export async function startProxyServer({ host, port, transcodeAudio, ffmpegBin }
   const selectedPort = await getPort({
     port: buildPortCandidates(port)
   });
+  // Auto-detect the best available H.264 encoder (hardware-accelerated or
+  // software) once at startup, with a real test-encode and graceful fallback.
+  // Only needed when transcoding can occur.
+  const videoEncoder = transcodeAudio
+    ? await detectVideoEncoder({ ffmpegBin, logger })
+    : null;
   const hlsSessionManager = new HlsSessionManager({
     enabled: transcodeAudio,
     ffmpegBin,
     localBindHost: host,
-    localPort: selectedPort
+    localPort: selectedPort,
+    videoEncoder
   });
   const playbackPlanner = createPlaybackPlanner({
     ffmpegBin,

package/services/hls-session-manager.js

@@ -15,6 +15,7 @@ import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { spawn } from "node:child_process";
 import { logger } from "../utils/logger.js";
+import { softwareDescriptor } from "./hwaccel.js";
 
 const PLAYLIST_FILE_NAME = "index.m3u8";
 const SEGMENT_FILE_NAME_PATTERN = /^segment-\d{5}\.ts$/;
@@ -32,9 +33,6 @@ const DEFAULT_SESSION_TTL_MS = 120 * 1000;
 const DEFAULT_STARTUP_WAIT_MS = 5_000;
 const MICROSECONDS_PER_SECOND = 1_000_000;
 const PROGRESS_LOG_INTERVAL_MS = 5_000;
-const VIDEO_TRANSCODE_PRESET = "superfast";
-const VIDEO_TRANSCODE_CRF = "24";
-const VIDEO_TRANSCODE_FPS = 24;
 
 /**
  * Resolve after a given number of milliseconds.
@@ -349,10 +347,15 @@ export class HlsSessionManager {
     localPort,
     segmentDurationSec = DEFAULT_SEGMENT_DURATION_SEC,
     sessionTtlMs = DEFAULT_SESSION_TTL_MS,
-    startupWaitMs = DEFAULT_STARTUP_WAIT_MS
+    startupWaitMs = DEFAULT_STARTUP_WAIT_MS,
+    videoEncoder = null
   }) {
     this.enabled = Boolean(enabled);
     this.ffmpegBin = ffmpegBin;
+    // Detected H.264 encoder descriptor (hardware or software). Defaults to
+    // software libx264 when no detection result is supplied. May be downgraded
+    // to software at runtime if a hardware encode fails.
+    this.videoEncoder = videoEncoder ?? softwareDescriptor();
     this.segmentDurationSec = segmentDurationSec;
     this.sessionTtlMs = sessionTtlMs;
     this.startupWaitMs = startupWaitMs;
@@ -509,7 +512,7 @@ export class HlsSessionManager {
 
     logger.info(
       `transcode ${sessionId} start "${logName}" ` +
-        `video=${transcodeVideo ? "x264" : "copy"} audio=${transcodeAudio ? "aac" : "copy"} ` +
+        `video=${transcodeVideo ? this.videoEncoder.name : "copy"} audio=${transcodeAudio ? "aac" : "copy"} ` +
         `duration=${hasDuration ? formatSeconds(durationSeconds) : "unknown"} segments=${segmentCount}`
     );
 
@@ -588,30 +591,26 @@ export class HlsSessionManager {
       }
     }
 
+    // Video: re-encode only when required, using the detected encoder
+    // (hardware-accelerated or software). The descriptor builds the filter +
+    // codec args (including keyframe alignment on segment boundaries).
     const videoCodecArgs = session.transcodeVideo
-      ? [
-          "-vf",
-          this.#buildVideoFilter(session.targetWidth, session.targetHeight),
-          "-c:v",
-          "libx264",
-          "-preset",
-          VIDEO_TRANSCODE_PRESET,
-          "-crf",
-          VIDEO_TRANSCODE_CRF,
-          "-pix_fmt",
-          "yuv420p",
-          // Force keyframes on segment boundaries so each segment is
-          // independently decodable and exactly segmentDuration long — this
-          // keeps the synthetic playlist's timing accurate.
-          "-force_key_frames",
-          `expr:gte(t,n_forced*${this.segmentDurationSec})`
-        ]
+      ? this.videoEncoder.buildVideoArgs({
+          targetWidth: session.targetWidth,
+          targetHeight: session.targetHeight,
+          segmentDurationSec: this.segmentDurationSec
+        })
       : ["-c:v", "copy"];
     const audioCodecArgs = session.transcodeAudio
       ? ["-c:a", "aac", "-ac", "2", "-b:a", "128k"]
       : ["-c:a", "copy"];
 
     const args = ["-hide_banner", "-nostats", "-loglevel", "error", "-progress", "pipe:1"];
+    // Hardware decode/encode setup (e.g. VAAPI device) must precede -i, and
+    // only applies when we actually re-encode the video track.
+    if (session.transcodeVideo && Array.isArray(this.videoEncoder.inputArgs)) {
+      args.push(...this.videoEncoder.inputArgs);
+    }
     if (startSeconds > 0) {
       // Fast keyframe-level seek before -i (skips decoding earlier frames).
       args.push("-ss", String(startSeconds));
@@ -762,12 +761,25 @@ export class HlsSessionManager {
         logger.info(`transcode ${session.id} encode-run complete "${session.fileName}"`);
         return;
       }
-      session.state = "failed";
-      session.progress.state = "failed";
-      session.progress.updatedAt = Date.now();
       if (!session.lastError) {
         session.lastError = `ffmpeg exited with code ${code ?? -1}${signal ? ` (signal ${signal})` : ""}`;
       }
+      // Runtime safety net: if a hardware encode fails, downgrade this proxy to
+      // software encoding for all sessions and restart this one, so playback is
+      // never permanently broken by a hardware/driver issue.
+      if (session.transcodeVideo && this.videoEncoder.kind !== "software") {
+        const failedEncoder = this.videoEncoder.name;
+        this.videoEncoder = softwareDescriptor();
+        logger.warn(
+          `transcode ${session.id} hardware encoder ${failedEncoder} failed ` +
+            `(${session.lastError}); falling back to software libx264 and restarting`
+        );
+        this.#startEncodeRun(session, session.encodeStartIndex);
+        return;
+      }
+      session.state = "failed";
+      session.progress.state = "failed";
+      session.progress.updatedAt = Date.now();
       logger.error(`transcode ${session.id} encode-run failed: ${session.lastError}`);
     });
   }
@@ -800,12 +812,6 @@ export class HlsSessionManager {
     this.#startEncodeRun(session, index);
   }
 
-  #buildVideoFilter(targetWidth, targetHeight) {
-    const safeWidth = Number.isInteger(targetWidth) && targetWidth > 0 ? targetWidth : 1280;
-    const safeHeight = Number.isInteger(targetHeight) && targetHeight > 0 ? targetHeight : 720;
-    return `scale=${safeWidth}:${safeHeight}:force_original_aspect_ratio=decrease:force_divisible_by=2,fps=${VIDEO_TRANSCODE_FPS}`;
-  }
-
   /**
    * Poll until the HLS playlist file exists and contains a valid `#EXTM3U`
    * header, or until the session fails, or until the startup timeout elapses.

package/services/hwaccel.js

@@ -0,0 +1,418 @@
+/**
+ * @file Hardware-accelerated H.264 encoder auto-detection.
+ *
+ * Probes the ffmpeg build and the host for a usable hardware H.264 encoder
+ * (NVENC / QSV / VAAPI / V4L2 M2M), verifying each candidate with a real
+ * test-encode before selecting it. Falls back to software libx264 when no
+ * hardware encoder is present or working.
+ *
+ * Deployment-agnostic: relies only on ffmpeg, the filesystem and
+ * `process.platform`; makes no assumptions about Home Assistant or any
+ * specific host. A garbled or unsupported hardware path simply fails its
+ * test-encode and is skipped, so the worst case is software encoding.
+ *
+ * A descriptor exposes:
+ *   - `name`        human-readable encoder id (e.g. "h264_vaapi")
+ *   - `kind`        "software" | "vaapi" | "qsv" | "nvenc" | "v4l2m2m"
+ *   - `device`      device node path or null
+ *   - `inputArgs`   ffmpeg args inserted before `-i` (decode/hwaccel setup)
+ *   - `buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec })`
+ *                   ffmpeg video filter + encoder args inserted after `-map`s
+ */
+
+import { spawn } from "node:child_process";
+import { mkdtempSync, readdirSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const SOFTWARE_PRESET = "superfast";
+const SOFTWARE_CRF = "24";
+const TRANSCODE_FPS = 24;
+
+/**
+ * @param {number} targetWidth
+ * @param {number} targetHeight
+ * @returns {{ w: number, h: number }}
+ */
+function safeDimensions(targetWidth, targetHeight) {
+  const w = Number.isInteger(targetWidth) && targetWidth > 0 ? targetWidth : 1280;
+  const h = Number.isInteger(targetHeight) && targetHeight > 0 ? targetHeight : 720;
+  return { w, h };
+}
+
+/**
+ * Force a keyframe on every segment boundary so each HLS segment is
+ * independently decodable and exactly `segmentDurationSec` long.
+ *
+ * @param {number} segmentDurationSec
+ * @returns {string[]}
+ */
+function keyFrameArgs(segmentDurationSec) {
+  return ["-force_key_frames", `expr:gte(t,n_forced*${segmentDurationSec})`];
+}
+
+/** @returns {import("./hwaccel.js").VideoEncoderDescriptor} */
+export function softwareDescriptor() {
+  return {
+    name: "libx264",
+    kind: "software",
+    device: null,
+    inputArgs: [],
+    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec }) {
+      const { w, h } = safeDimensions(targetWidth, targetHeight);
+      return [
+        "-vf",
+        `scale=${w}:${h}:force_original_aspect_ratio=decrease:force_divisible_by=2,fps=${TRANSCODE_FPS}`,
+        "-c:v", "libx264",
+        "-preset", SOFTWARE_PRESET,
+        "-crf", SOFTWARE_CRF,
+        "-pix_fmt", "yuv420p",
+        ...keyFrameArgs(segmentDurationSec)
+      ];
+    }
+  };
+}
+
+/**
+ * @param {string} device
+ * @returns {import("./hwaccel.js").VideoEncoderDescriptor}
+ */
+function vaapiDescriptor(device) {
+  return {
+    name: "h264_vaapi",
+    kind: "vaapi",
+    device,
+    // Decode on the GPU into VAAPI surfaces; scale and encode stay on-GPU.
+    inputArgs: ["-hwaccel", "vaapi", "-hwaccel_output_format", "vaapi", "-vaapi_device", device],
+    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec }) {
+      const { w, h } = safeDimensions(targetWidth, targetHeight);
+      return [
+        "-vf",
+        `scale_vaapi=w=${w}:h=${h}:force_original_aspect_ratio=decrease`,
+        "-c:v", "h264_vaapi",
+        "-qp", "24",
+        ...keyFrameArgs(segmentDurationSec)
+      ];
+    }
+  };
+}
+
+/**
+ * @param {string} device
+ * @returns {import("./hwaccel.js").VideoEncoderDescriptor}
+ */
+function qsvDescriptor(device) {
+  return {
+    name: "h264_qsv",
+    kind: "qsv",
+    device,
+    inputArgs: ["-hwaccel", "qsv", "-qsv_device", device],
+    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec }) {
+      const { w, h } = safeDimensions(targetWidth, targetHeight);
+      return [
+        "-vf", `scale_qsv=w=${w}:h=${h}`,
+        "-c:v", "h264_qsv",
+        "-global_quality", "24",
+        ...keyFrameArgs(segmentDurationSec)
+      ];
+    }
+  };
+}
+
+/** @returns {import("./hwaccel.js").VideoEncoderDescriptor} */
+function nvencDescriptor() {
+  return {
+    name: "h264_nvenc",
+    kind: "nvenc",
+    device: null,
+    inputArgs: [],
+    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec }) {
+      const { w, h } = safeDimensions(targetWidth, targetHeight);
+      return [
+        "-vf",
+        `scale=${w}:${h}:force_original_aspect_ratio=decrease:force_divisible_by=2,fps=${TRANSCODE_FPS}`,
+        "-c:v", "h264_nvenc",
+        "-preset", "p4",
+        "-cq", "24",
+        "-pix_fmt", "yuv420p",
+        ...keyFrameArgs(segmentDurationSec)
+      ];
+    }
+  };
+}
+
+/** @returns {import("./hwaccel.js").VideoEncoderDescriptor} */
+function v4l2m2mDescriptor() {
+  // ARM SoC (e.g. Raspberry Pi / HA Yellow) stateful M2M encoder. No GPU
+  // scaler — scale in software, hand YUV420 frames to the hardware encoder.
+  // `-g` aligns the GOP to the segment length so an IDR lands on every segment
+  // boundary; this is verified by the keyframe-alignment test before use,
+  // because v4l2m2m does not always honour these hints.
+  return {
+    name: "h264_v4l2m2m",
+    kind: "v4l2m2m",
+    device: null,
+    inputArgs: [],
+    buildVideoArgs({ targetWidth, targetHeight, segmentDurationSec }) {
+      const { w, h } = safeDimensions(targetWidth, targetHeight);
+      return [
+        "-vf",
+        `scale=${w}:${h}:force_original_aspect_ratio=decrease:force_divisible_by=2,fps=${TRANSCODE_FPS},format=yuv420p`,
+        "-c:v", "h264_v4l2m2m",
+        "-b:v", "3M",
+        "-g", String(TRANSCODE_FPS * segmentDurationSec),
+        ...keyFrameArgs(segmentDurationSec)
+      ];
+    }
+  };
+}
+
+
+/**
+ * @typedef {Object} VideoEncoderDescriptor
+ * @property {string} name
+ * @property {"software"|"vaapi"|"qsv"|"nvenc"|"v4l2m2m"} kind
+ * @property {string|null} device
+ * @property {string[]} inputArgs
+ * @property {(opts: { targetWidth: number, targetHeight: number, segmentDurationSec: number }) => string[]} buildVideoArgs
+ */
+
+/**
+ * Run ffmpeg and resolve with its exit code and captured output.
+ *
+ * @param {string} ffmpegBin
+ * @param {string[]} args
+ * @param {number} [timeoutMs=12000]
+ * @returns {Promise<{ code: number, stdout: string, stderr: string }>}
+ */
+function runFfmpeg(ffmpegBin, args, timeoutMs = 12000) {
+  return new Promise((resolve) => {
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let child;
+    const finish = (code) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      resolve({ code, stdout, stderr });
+    };
+    try {
+      child = spawn(ffmpegBin, args, { stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+    } catch {
+      finish(-1);
+      return;
+    }
+    const timer = setTimeout(() => {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+        // ignore
+      }
+      finish(-1);
+    }, timeoutMs);
+    child.stdout.on("data", (d) => {
+      stdout += String(d);
+    });
+    child.stderr.on("data", (d) => {
+      stderr += String(d);
+    });
+    child.on("error", () => {
+      clearTimeout(timer);
+      finish(-1);
+    });
+    child.on("exit", (code) => {
+      clearTimeout(timer);
+      finish(code ?? -1);
+    });
+  });
+}
+
+/** @returns {string[]} /dev/dri/renderD* nodes (VAAPI/QSV). */
+function listRenderNodes() {
+  try {
+    return readdirSync("/dev/dri")
+      .filter((n) => n.startsWith("renderD"))
+      .map((n) => `/dev/dri/${n}`)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+/** @returns {boolean} Whether any /dev/nvidia* node exists (NVENC). */
+function hasNvidiaDevice() {
+  try {
+    return readdirSync("/dev").some((n) => /^nvidia(\d+)?$/.test(n));
+  } catch {
+    return false;
+  }
+}
+
+/** @returns {boolean} Whether any /dev/video* node exists (V4L2 M2M). */
+function hasV4l2Device() {
+  try {
+    return readdirSync("/dev").some((n) => /^video\d+$/.test(n));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Build a full ffmpeg command that encodes a short, *moving* synthetic clip
+ * (testsrc2 — far more representative than a static black frame) through the
+ * candidate encoder into real HLS segments in `outDir`, with keyframes forced
+ * on segment boundaries. Verifying the resulting segments (see
+ * {@link verifySegmentsDecodeCleanly}) catches encoders that silently produce
+ * a corrupted or non-IDR-aligned stream (e.g. some V4L2 M2M builds).
+ *
+ * @param {VideoEncoderDescriptor} descriptor
+ * @param {number} segmentDurationSec
+ * @param {string} outDir
+ * @returns {string[]}
+ */
+function buildEncoderTestArgs(descriptor, segmentDurationSec, outDir) {
+  const durationSec = Math.max(8, segmentDurationSec * 3);
+  const source = ["-f", "lavfi", "-i", `testsrc2=s=640x360:r=${TRANSCODE_FPS}:d=${durationSec}`];
+  const kf = keyFrameArgs(segmentDurationSec);
+
+  /** @type {string[]} */
+  let pre = ["-hide_banner", "-loglevel", "error"];
+  /** @type {string[]} */
+  let encode;
+  switch (descriptor.kind) {
+    case "vaapi":
+      pre = [...pre, "-vaapi_device", String(descriptor.device)];
+      encode = ["-vf", "format=nv12,hwupload", "-c:v", "h264_vaapi", "-qp", "24", ...kf];
+      break;
+    case "qsv":
+      pre = [...pre, "-qsv_device", String(descriptor.device)];
+      encode = ["-vf", "hwupload=extra_hw_frames=16,format=qsv", "-c:v", "h264_qsv", "-global_quality", "24", ...kf];
+      break;
+    case "nvenc":
+      encode = ["-c:v", "h264_nvenc", "-preset", "p4", "-cq", "24", "-pix_fmt", "yuv420p", ...kf];
+      break;
+    case "v4l2m2m":
+      encode = ["-pix_fmt", "yuv420p", "-c:v", "h264_v4l2m2m", "-b:v", "3M", "-g", String(TRANSCODE_FPS * segmentDurationSec), ...kf];
+      break;
+    default:
+      encode = ["-c:v", "libx264", "-preset", "ultrafast", "-pix_fmt", "yuv420p", ...kf];
+      break;
+  }
+
+  const hlsOut = [
+    "-f", "hls",
+    "-hls_time", String(segmentDurationSec),
+    "-hls_list_size", "0",
+    "-hls_flags", "independent_segments",
+    "-hls_segment_filename", path.join(outDir, "seg-%03d.ts"),
+    path.join(outDir, "index.m3u8")
+  ];
+  return [...pre, ...source, ...encode, ...hlsOut];
+}
+
+/**
+ * Verify the HLS segments produced by the test encode are valid: at least two
+ * segments exist, and each decodes standalone without errors. A segment that
+ * does not begin with a keyframe (broken/corrupted output) emits decode errors
+ * when read on its own, which fails this check.
+ *
+ * @param {string} ffmpegBin
+ * @param {string} outDir
+ * @returns {Promise<boolean>}
+ */
+async function verifySegmentsDecodeCleanly(ffmpegBin, outDir) {
+  let files;
+  try {
+    files = readdirSync(outDir).filter((n) => /^seg-\d+\.ts$/.test(n)).sort();
+  } catch {
+    return false;
+  }
+  if (files.length < 2) {
+    return false;
+  }
+  for (const file of files) {
+    const result = await runFfmpeg(
+      ffmpegBin,
+      ["-hide_banner", "-loglevel", "error", "-i", path.join(outDir, file), "-f", "null", "-"],
+      8000
+    );
+    if (result.code !== 0 || result.stderr.trim().length > 0) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Detect the best usable H.264 encoder. Always resolves (falls back to
+ * software libx264). Each hardware candidate is verified with a real
+ * test-encode before being selected.
+ *
+ * @param {{ ffmpegBin: string, logger?: { info: (m: string) => void, warn: (m: string) => void }, segmentDurationSec?: number }} options
+ * @returns {Promise<VideoEncoderDescriptor>}
+ */
+export async function detectVideoEncoder({ ffmpegBin, logger, segmentDurationSec = 4 }) {
+  const log = logger ?? { info: () => {}, warn: () => {} };
+  const software = softwareDescriptor();
+
+  const { code, stdout } = await runFfmpeg(ffmpegBin, ["-hide_banner", "-encoders"], 10000);
+  if (code !== 0) {
+    log.warn("hwaccel: could not list ffmpeg encoders; using software libx264");
+    return software;
+  }
+  const has = (name) => stdout.includes(name);
+
+  /** @type {VideoEncoderDescriptor[]} */
+  const candidates = [];
+  const renderNodes = listRenderNodes();
+  if (has("h264_nvenc") && hasNvidiaDevice()) {
+    candidates.push(nvencDescriptor());
+  }
+  if (has("h264_qsv") && renderNodes.length > 0) {
+    candidates.push(qsvDescriptor(renderNodes[0]));
+  }
+  if (has("h264_vaapi") && renderNodes.length > 0) {
+    candidates.push(vaapiDescriptor(renderNodes[0]));
+  }
+  // h264_v4l2m2m (ARM SoC / Raspberry Pi / HA Yellow). It is gated behind the
+  // strict keyframe-alignment test below, because some V4L2 M2M builds silently
+  // emit a corrupted / non-IDR-aligned stream; the test rejects those and the
+  // host falls back to software libx264.
+  if (has("h264_v4l2m2m") && hasV4l2Device()) {
+    candidates.push(v4l2m2mDescriptor());
+  }
+
+  for (const candidate of candidates) {
+    const dir = mkdtempSync(path.join(os.tmpdir(), "tt-hwtest-"));
+    let ok = false;
+    try {
+      const encoded = await runFfmpeg(
+        ffmpegBin,
+        buildEncoderTestArgs(candidate, segmentDurationSec, dir),
+        25000
+      );
+      if (encoded.code === 0) {
+        ok = await verifySegmentsDecodeCleanly(ffmpegBin, dir);
+      }
+    } finally {
+      try {
+        rmSync(dir, { recursive: true, force: true });
+      } catch {
+        // best effort
+      }
+    }
+    if (ok) {
+      log.info(
+        `hwaccel: using hardware encoder ${candidate.name}` +
+          `${candidate.device ? ` (${candidate.device})` : ""}`
+      );
+      return candidate;
+    }
+    log.warn(`hwaccel: ${candidate.name} failed the HLS keyframe-alignment test; skipping`);
+  }
+
+  log.info("hwaccel: no working hardware encoder; using software libx264");
+  return software;
+}