@torrent-tv/proxy 2.7.0 → 2.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torrent-tv/proxy",
-  "version": "2.7.0",
+  "version": "2.9.0",
   "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$/;
@@ -24,12 +25,6 @@ const DEFAULT_SEGMENT_DURATION_SEC = 4;
 // is allowed to be before we restart ffmpeg at that position (server-side seek).
 // Requests within the window are served by waiting for the running encode.
 const MAX_LOOKAHEAD_SEGMENTS = 8;
-// Just-in-time pacing: pause the encoder once it is this many segments ahead of
-// the player's current position, and resume once the lead shrinks to the resume
-// threshold.  This keeps a comfortable buffer for smooth playback while capping
-// CPU near real-time instead of racing through the whole file at once.
-const PACING_PAUSE_AHEAD_SEGMENTS = 8;
-const PACING_RESUME_AHEAD_SEGMENTS = 4;
 // Idle TTL: a session is disposed this long after the last segment/playlist
 // access. Kept short so an ffmpeg process does not keep burning CPU after the
 // viewer stops or navigates away. Active playback refreshes the timer on every
@@ -38,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.
@@ -355,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;
@@ -498,11 +495,6 @@ export class HlsSessionManager {
       encodeStartIndex: 0,
       // Guards against repeatedly restarting to the same seek position.
       pendingRestartIndex: -1,
-      // Just-in-time pacing: highest segment index the player has requested
-      // (≈ playhead) and whether the encoder is currently paused for running
-      // far enough ahead.
-      playheadIndex: 0,
-      paused: false,
       progress: {
         state: "starting",
         processedSeconds: 0,
@@ -590,44 +582,35 @@ export class HlsSessionManager {
 
     // Terminate any existing encode process before starting a new one.  The
     // old process's exit handler no-ops because session.ffmpeg is reassigned
-    // below (it checks identity).  Resume first in case it was paused, so the
-    // termination signal is actually delivered.
+    // below (it checks identity).
     if (session.ffmpeg && !session.ffmpeg.killed) {
       try {
-        if (session.paused) {
-          session.ffmpeg.kill("SIGCONT");
-        }
         session.ffmpeg.kill("SIGTERM");
       } catch (_error) {
         // Best effort.
       }
     }
-    session.paused = false;
 
+    // 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));
@@ -669,7 +652,6 @@ export class HlsSessionManager {
     session.ffmpeg = ffmpeg;
     session.encodeStartIndex = safeIndex;
     session.pendingRestartIndex = -1;
-    session.playheadIndex = safeIndex;
     session.state = session.state === "disposed" ? "disposed" : "starting";
     session.progress.state = "running";
     session.progress.processedSeconds = startSeconds;
@@ -742,8 +724,6 @@ export class HlsSessionManager {
               ` speed=${session.progress.speed || "n/a"}`
           );
         }
-        // Just-in-time pacing: pause once we are far enough ahead of the player.
-        this.#maybePauseEncoder(session);
       }
     });
 
@@ -781,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}`);
     });
   }
@@ -819,85 +812,6 @@ export class HlsSessionManager {
     this.#startEncodeRun(session, index);
   }
 
-  /**
-   * Segment index ffmpeg has encoded up to so far, derived from the output
-   * timestamp reported via -progress.
-   *
-   * @param {HlsSession} session
-   * @returns {number}
-   */
-  #producedSegmentIndex(session) {
-    const processed = Number(session.progress?.processedSeconds);
-    if (!Number.isFinite(processed) || processed <= 0) {
-      return session.encodeStartIndex;
-    }
-    return Math.floor(processed / this.segmentDurationSec);
-  }
-
-  /**
-   * Pause the encoder once it has produced enough segments ahead of the
-   * player's current position (just-in-time pacing).  No-op on platforms
-   * without POSIX job-control signals (fail-open: the encoder keeps running).
-   *
-   * @param {HlsSession} session
-   * @returns {void}
-   */
-  #maybePauseEncoder(session) {
-    if (session.paused || !session.ffmpeg || session.ffmpeg.killed) {
-      return;
-    }
-    if (process.platform === "win32") {
-      return;
-    }
-    const ahead = this.#producedSegmentIndex(session) - session.playheadIndex;
-    if (ahead < PACING_PAUSE_AHEAD_SEGMENTS) {
-      return;
-    }
-    try {
-      session.ffmpeg.kill("SIGSTOP");
-      session.paused = true;
-      logger.info(
-        `transcode ${session.id} paused (buffered ${ahead} segments ahead) "${session.fileName}"`
-      );
-    } catch (_error) {
-      // Fail-open: if we cannot pause, let the encoder keep running.
-    }
-  }
-
-  /**
-   * Resume a paused encoder when the player has caught up enough that the
-   * buffered lead has shrunk to the resume threshold.
-   *
-   * @param {HlsSession} session
-   * @returns {void}
-   */
-  #maybeResumeEncoder(session) {
-    if (!session.paused || !session.ffmpeg || session.ffmpeg.killed) {
-      return;
-    }
-    const ahead = this.#producedSegmentIndex(session) - session.playheadIndex;
-    if (ahead > PACING_RESUME_AHEAD_SEGMENTS) {
-      return;
-    }
-    try {
-      session.ffmpeg.kill("SIGCONT");
-      session.paused = false;
-      session.progress.updatedAt = Date.now();
-      logger.info(`transcode ${session.id} resumed (lead ${ahead} segments) "${session.fileName}"`);
-    } catch (_error) {
-      // If resume fails, force a restart from the player's position so it does
-      // not stall (fail-safe toward smooth playback).
-      session.paused = false;
-      this.#startEncodeRun(session, session.playheadIndex);
-    }
-  }
-
-  #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.
@@ -970,16 +884,6 @@ export class HlsSessionManager {
     }
     session.lastAccessedAt = Date.now();
 
-    // Track the player position (≈ playhead) from segment requests and resume
-    // a paused encoder as the player approaches the buffered edge.
-    if (fileName !== PLAYLIST_FILE_NAME) {
-      const requestedIndex = segmentIndexFromName(fileName);
-      if (requestedIndex >= 0) {
-        session.playheadIndex = Math.max(session.playheadIndex, requestedIndex);
-        this.#maybeResumeEncoder(session);
-      }
-    }
-
     // Serve the synthetic VOD playlist (full duration, terminated with
     // #EXT-X-ENDLIST) so the player gets the correct total length and a fully
     // seekable timeline up-front, independent of how far ffmpeg has encoded.
@@ -1127,16 +1031,6 @@ export class HlsSessionManager {
     this.sessionIdBySource.delete(session.sourceMapKey);
 
     if (session.ffmpeg && !session.ffmpeg.killed) {
-      // Resume first if paused, otherwise SIGTERM is not delivered to a
-      // stopped process.
-      if (session.paused) {
-        try {
-          session.ffmpeg.kill("SIGCONT");
-        } catch (_error) {
-          // Best effort.
-        }
-        session.paused = false;
-      }
       session.ffmpeg.kill("SIGTERM");
       await waitForChildExit(session.ffmpeg);
     }

package/services/hwaccel.js

@@ -0,0 +1,345 @@
+/**
+ * @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 { readdirSync } from "node:fs";
+
+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) stateful M2M encoder. No GPU scaler — scale in
+  // software, then hand YUV420 frames to the hardware encoder.
+  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",
+        ...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;
+  }
+}
+
+/**
+ * Kind-specific test-encode args that verify the encoder initialises and
+ * encodes a few frames from a synthetic source.
+ *
+ * @param {VideoEncoderDescriptor} descriptor
+ * @returns {string[]}
+ */
+function testEncodeArgs(descriptor) {
+  const src = ["-f", "lavfi", "-i", "color=c=black:s=320x240:r=15:d=0.4"];
+  switch (descriptor.kind) {
+    case "vaapi":
+      return [
+        "-hide_banner", "-loglevel", "error",
+        "-vaapi_device", String(descriptor.device),
+        ...src,
+        "-vf", "format=nv12,hwupload", "-c:v", "h264_vaapi",
+        "-f", "null", "-"
+      ];
+    case "qsv":
+      return [
+        "-hide_banner", "-loglevel", "error",
+        "-qsv_device", String(descriptor.device),
+        ...src,
+        "-vf", "hwupload=extra_hw_frames=16,format=qsv", "-c:v", "h264_qsv",
+        "-f", "null", "-"
+      ];
+    case "nvenc":
+      return ["-hide_banner", "-loglevel", "error", ...src, "-c:v", "h264_nvenc", "-f", "null", "-"];
+    case "v4l2m2m":
+      return [
+        "-hide_banner", "-loglevel", "error",
+        ...src, "-pix_fmt", "yuv420p", "-c:v", "h264_v4l2m2m", "-f", "null", "-"
+      ];
+    default:
+      return [
+        "-hide_banner", "-loglevel", "error",
+        ...src, "-c:v", "libx264", "-preset", "ultrafast", "-f", "null", "-"
+      ];
+  }
+}
+
+/**
+ * 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 } }} options
+ * @returns {Promise<VideoEncoderDescriptor>}
+ */
+export async function detectVideoEncoder({ ffmpegBin, logger }) {
+  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]));
+  }
+  if (has("h264_v4l2m2m") && hasV4l2Device()) {
+    candidates.push(v4l2m2mDescriptor());
+  }
+
+  for (const candidate of candidates) {
+    const result = await runFfmpeg(ffmpegBin, testEncodeArgs(candidate), 12000);
+    if (result.code === 0) {
+      log.info(
+        `hwaccel: using hardware encoder ${candidate.name}` +
+          `${candidate.device ? ` (${candidate.device})` : ""}`
+      );
+      return candidate;
+    }
+    log.warn(`hwaccel: ${candidate.name} present but test-encode failed; skipping`);
+  }
+
+  log.info("hwaccel: no working hardware encoder; using software libx264");
+  return software;
+}