@muhkoo/theater-transcoder 0.2.3 → 0.3.0

package/README.md

@@ -15,7 +15,19 @@ npm i -g @muhkoo/theater-transcoder
 MUHKOO_USERNAME=you MUHKOO_PASSWORD=… theater-transcoder
 ```
 
-You'll be prompted for your password if it isn't in `$MUHKOO_PASSWORD`. Credentials never leave the machine — it runs the same **zero-knowledge login** the browser uses. `ffmpeg` is bundled (`ffmpeg-static`); nothing else to install. Requires **Node ≥ 20** (≥ 22 recommended).
+You'll be prompted for your password if it isn't in `$MUHKOO_PASSWORD`. Credentials never leave the machine — it runs the same **zero-knowledge login** the browser uses. Requires **Node ≥ 20** (≥ 22 recommended).
+
+### ffmpeg (hardware acceleration)
+
+The transcoder prefers a **system-installed `ffmpeg`** and offloads work to the GPU when one is available — **Apple VideoToolbox**, **NVIDIA NVENC**, **Intel QuickSync**, or **VAAPI**. It runs the whole pipeline on-GPU where it can (**hardware decode → scale → encode**, frames never leaving the GPU), which on NVENC/QuickSync boxes hits many times realtime; on Apple Silicon the encoder is the ceiling but GPU decode still roughly halves CPU use. It automatically steps down — full-GPU → GPU-encode-only → software libx264 — to whatever actually runs on the machine.
+
+- **Best:** install ffmpeg so hardware encoding kicks in automatically:
+  - macOS: `brew install ffmpeg`
+  - Debian/Ubuntu: `sudo apt install ffmpeg`
+  - (or point at a specific build with `FFMPEG_PATH=/path/to/ffmpeg`)
+- **Fallback:** if no system ffmpeg is found, the bundled `ffmpeg-static` binary is used (software libx264 — works everywhere, just slower). You'll see a one-time warning nudging you to install ffmpeg.
+
+On startup the worker logs exactly which binary and encoder it picked, e.g. `✓ hardware encoder: Apple VideoToolbox (h264_videotoolbox)`. If a GPU path is present but fails on a given file, it logs the fallback and keeps going — down to software libx264 if needed.
 
 Leave it running. Upload videos in the app and this box starts chewing through the queue. Ctrl-C to stop.
 
@@ -37,3 +49,5 @@ Offline + P2P are auto-disabled in Node (no IndexedDB / WebRTC), so its shard an
 | `--password` | `MUHKOO_PASSWORD` | prompt |
 | `--base` | `MUHKOO_BASE_URL` | `https://api.muhkoo.dev` |
 | `--app-key` | `MUHKOO_THEATER_KEY` | public prod key |
+| — | `FFMPEG_PATH` | system `ffmpeg` → bundled static |
+| — | `VAAPI_DEVICE` | `/dev/dri/renderD128` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@muhkoo/theater-transcoder",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Drain a Muhkoo Theater transcode queue with NATIVE ffmpeg. Run it on any machine signed in as you to add transcoding power to your library.",
   "type": "module",
   "bin": {

package/src/ffmpeg.js

@@ -0,0 +1,96 @@
+/**
+ * Resolve which ffmpeg binary to run and which H.264 encoder to use.
+ *
+ * Preference order, best → worst:
+ *   1. A **system-installed ffmpeg** (via `FFMPEG_PATH` or on `PATH`) — usually
+ *      built with hardware encoders (Apple VideoToolbox, NVIDIA NVENC, Intel
+ *      QuickSync, VAAPI). These offload encoding to dedicated silicon and are
+ *      dramatically faster than software libx264.
+ *   2. The bundled **`ffmpeg-static`** binary (software libx264 only). Works
+ *      everywhere with zero install, but slow — so we warn and nudge the user to
+ *      `brew/apt install ffmpeg` for hardware acceleration.
+ *
+ * We probe the chosen binary's encoder list AND run a tiny functional test
+ * encode (an encoder can be listed but fail at runtime — e.g. NVENC with no GPU),
+ * then pick the fastest encoder that actually works.
+ */
+import { spawnSync } from "node:child_process";
+import ffmpegStatic from "ffmpeg-static";
+
+const log = (...a) => console.log(new Date().toISOString().slice(11, 19), ...a);
+
+/** Hardware H.264 encoders, in preference order. */
+const HW_ENCODERS = [
+  { codec: "h264_videotoolbox", label: "Apple VideoToolbox" },
+  { codec: "h264_nvenc", label: "NVIDIA NVENC" },
+  { codec: "h264_qsv", label: "Intel QuickSync" },
+  { codec: "h264_vaapi", label: "VAAPI" },
+];
+
+function runnable(bin) {
+  try {
+    const r = spawnSync(bin, ["-hide_banner", "-version"], { encoding: "utf8", timeout: 5000 });
+    return r.status === 0 && /ffmpeg version/i.test(r.stdout || "");
+  } catch { return false; }
+}
+
+/** Find a runnable ffmpeg: FFMPEG_PATH → system PATH → bundled static. */
+function resolveBinary() {
+  const explicit = process.env.FFMPEG_PATH;
+  if (explicit) {
+    if (runnable(explicit)) return { path: explicit, system: true, source: `FFMPEG_PATH (${explicit})` };
+    log(`⚠︎ FFMPEG_PATH="${explicit}" is not a runnable ffmpeg — ignoring it.`);
+  }
+  if (runnable("ffmpeg")) return { path: "ffmpeg", system: true, source: "system install" };
+  return { path: ffmpegStatic, system: false, source: "ffmpeg-static (bundled)" };
+}
+
+function listEncoders(bin) {
+  try {
+    const r = spawnSync(bin, ["-hide_banner", "-encoders"], { encoding: "utf8", timeout: 5000 });
+    return r.status === 0 ? (r.stdout || "") : "";
+  } catch { return ""; }
+}
+
+/** Encode a couple of synthetic frames with `codec` to /dev/null; true if it works. */
+function functionalTest(bin, codec) {
+  const common = ["-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc=size=192x108:rate=5:duration=1"];
+  const args = codec === "h264_vaapi"
+    ? ["-vaapi_device", process.env.VAAPI_DEVICE || "/dev/dri/renderD128", ...common,
+       "-vf", "format=nv12,hwupload", "-c:v", codec, "-frames:v", "3", "-f", "null", "-"]
+    : [...common, "-c:v", codec, "-frames:v", "3", "-f", "null", "-"];
+  try {
+    const r = spawnSync(bin, args, { encoding: "utf8", timeout: 12000 });
+    return r.status === 0;
+  } catch { return false; }
+}
+
+/**
+ * @returns {{ ffmpegPath: string, encoder: { codec: string, label: string, hw: boolean } }}
+ */
+export function resolveEncoder() {
+  const bin = resolveBinary();
+  const encoders = listEncoders(bin.path);
+
+  let chosen = null;
+  for (const cand of HW_ENCODERS) {
+    if (encoders.includes(cand.codec) && functionalTest(bin.path, cand.codec)) { chosen = cand; break; }
+  }
+  const encoder = chosen
+    ? { ...chosen, hw: true }
+    : { codec: "libx264", label: "libx264 (software)", hw: false };
+
+  if (bin.system) {
+    log(`✓ ffmpeg: ${bin.source}`);
+  } else {
+    log("⚠︎ Using the bundled ffmpeg (no system install found). This encodes in software");
+    log("  and is much slower. Install ffmpeg for hardware-accelerated transcoding:");
+    log("    macOS:  brew install ffmpeg");
+    log("    Debian/Ubuntu:  sudo apt install ffmpeg");
+    log("  The transcoder auto-detects it on next start (or set FFMPEG_PATH).");
+  }
+  if (encoder.hw) log(`✓ hardware encoder: ${encoder.label} (${encoder.codec})`);
+  else log(`ℹ no usable hardware H.264 encoder — using software libx264 (${bin.source}).`);
+
+  return { ffmpegPath: bin.path, encoder };
+}

package/src/transcode.js

@@ -2,20 +2,101 @@
  * Native-ffmpeg transcode → HLS, producing the SAME structure the browser writes
  * so playback is identical: each ~6s segment is stored as an encrypted shard via
  * `space.putFile` (→ manifest), and an HLS index `{variants:[{height,bandwidth,
- * segments:[{duration,manifest}]}],duration}` is stored as its own file. Native
- * ffmpeg has no wasm limits, so we use all cores (`-threads 0`) and a nicer
- * preset than the browser's `ultrafast`.
+ * segments:[{duration,manifest}]}],duration}` is stored as its own file.
+ *
+ * The binary + encoder are resolved once (`ffmpeg.js`): a system ffmpeg with a
+ * hardware encoder (VideoToolbox/NVENC/QuickSync/VAAPI) when available, else the
+ * bundled software libx264. Hardware encoding offloads to dedicated silicon and
+ * is far faster than the browser's wasm build; software libx264 uses all cores.
  */
 import { spawn } from "node:child_process";
 import { mkdtemp, readFile, writeFile, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import ffmpegPath from "ffmpeg-static";
+import { resolveEncoder } from "./ffmpeg.js";
+
+const log = (...a) => console.log(new Date().toISOString().slice(11, 19), ...a);
+
+// Resolved once, lazily (probing spawns a few ffmpeg processes). `ensureEncoder`
+// lets the worker trigger + log the choice at startup instead of on first job.
+let _resolved;
+export function ensureEncoder() {
+  return (_resolved ??= resolveEncoder());
+}
 
 // Match the browser's rendition ladder (single 720p for now).
 const RENDITIONS = [{ height: 720, videoBitrate: "2500k", audioBitrate: "128k", bandwidth: 2_800_000 }];
 const SEGMENT_SECONDS = 6;
 
+/**
+ * Ordered encode strategies for a rendition on the resolved encoder — fastest
+ * first, each a full recipe of { input flags before -i, -vf filter, codec args }:
+ *   1. full GPU pipeline: hardware decode + scale + encode, frames never leave the
+ *      GPU (huge win on NVENC/QuickSync/VAAPI);
+ *   2. hardware decode + encode, CPU scale (frames round-trip system memory);
+ *   3. software libx264 (works everywhere).
+ * `encodeRendition` tries them in order and remembers which one runs on this box.
+ */
+function buildStrategies(codec, rend) {
+  const kf = ["-force_key_frames", `expr:gte(t,n_forced*${SEGMENT_SECONDS})`];
+  const scale = `scale=-2:${rend.height}`;
+  const bv = ["-b:v", rend.videoBitrate];
+  const vaapiDev = process.env.VAAPI_DEVICE || "/dev/dri/renderD128";
+
+  const software = {
+    label: "software libx264", input: [], filter: scale,
+    video: ["-threads", "0", "-c:v", "libx264", "-preset", "veryfast", ...bv,
+      "-pix_fmt", "yuv420p", "-profile:v", "main", "-level", "4.0", ...kf, "-sc_threshold", "0"],
+  };
+
+  switch (codec) {
+    case "h264_videotoolbox":
+      // VideoToolbox on Apple Silicon is encoder-bound, so a GPU scale buys little;
+      // GPU *decode* still halves CPU. One hw tier, then software.
+      return [
+        { label: "VideoToolbox (GPU decode+encode)", input: ["-hwaccel", "videotoolbox"], filter: scale,
+          video: ["-c:v", "h264_videotoolbox", ...bv, "-profile:v", "main", "-pix_fmt", "yuv420p", "-realtime", "1", ...kf] },
+        software,
+      ];
+    case "h264_nvenc":
+      return [
+        { label: "NVENC (full GPU pipeline)", input: ["-hwaccel", "cuda", "-hwaccel_output_format", "cuda"],
+          filter: `scale_cuda=-2:${rend.height}:format=yuv420p`,
+          video: ["-c:v", "h264_nvenc", "-preset", "p4", "-tune", "hq", "-rc", "vbr", ...bv, "-profile:v", "main", ...kf] },
+        { label: "NVENC (GPU encode, CPU scale)", input: ["-hwaccel", "cuda"], filter: scale,
+          video: ["-c:v", "h264_nvenc", "-preset", "p4", "-tune", "hq", "-rc", "vbr", ...bv, "-profile:v", "main", "-pix_fmt", "yuv420p", ...kf] },
+        software,
+      ];
+    case "h264_qsv":
+      return [
+        { label: "QuickSync (full GPU pipeline)", input: ["-hwaccel", "qsv", "-hwaccel_output_format", "qsv"],
+          filter: `scale_qsv=-2:${rend.height}`,
+          video: ["-c:v", "h264_qsv", "-preset", "veryfast", ...bv, "-profile:v", "main", ...kf] },
+        { label: "QuickSync (GPU encode, CPU scale)", input: ["-hwaccel", "qsv"], filter: scale,
+          video: ["-c:v", "h264_qsv", "-preset", "veryfast", ...bv, "-profile:v", "main", "-pix_fmt", "nv12", ...kf] },
+        software,
+      ];
+    case "h264_vaapi":
+      return [
+        { label: "VAAPI (full GPU pipeline)", input: ["-hwaccel", "vaapi", "-hwaccel_output_format", "vaapi", "-vaapi_device", vaapiDev],
+          filter: `scale_vaapi=-2:${rend.height}`,
+          video: ["-c:v", "h264_vaapi", ...bv, "-profile:v", "main", ...kf] },
+        { label: "VAAPI (GPU encode, CPU scale)", input: ["-vaapi_device", vaapiDev],
+          filter: `${scale},format=nv12,hwupload`,
+          video: ["-c:v", "h264_vaapi", ...bv, "-profile:v", "main", ...kf] },
+        software,
+      ];
+    default:
+      return [software];
+  }
+}
+
+// Index into the encoder's strategy list to START from — advanced permanently
+// only when a strategy fails *fast* (unavailable on this machine), so a one-off
+// bad file doesn't downgrade every subsequent job. See encodeRendition.
+let _stratStart = 0;
+const FAST_FAIL_MS = 8000;
+
 function parseDurations(m3u8) {
   const out = [];
   for (const line of m3u8.split("\n")) {
@@ -30,16 +111,15 @@ function hhmmssToSec(s) {
   return m ? Number(m[1]) * 3600 + Number(m[2]) * 60 + Number(m[3]) : 0;
 }
 
-/** Run one ffmpeg rendition to HLS; report fraction via stderr `time=` vs total. */
-function runFfmpeg(inPath, dir, rend, playlist, onFrac, signal) {
+/** Run one ffmpeg rendition to HLS with a given strategy; report fraction via
+ *  stderr `time=` vs total. */
+function runFfmpeg(ffmpegPath, strat, inPath, dir, rend, playlist, onFrac, signal) {
   return new Promise((resolve, reject) => {
     const args = [
+      ...strat.input,
       "-i", inPath,
-      "-vf", `scale=-2:${rend.height}`,
-      "-threads", "0", // native: use all cores
-      "-c:v", "libx264", "-preset", "veryfast", "-b:v", rend.videoBitrate,
-      "-pix_fmt", "yuv420p", "-profile:v", "main", "-level", "4.0",
-      "-force_key_frames", `expr:gte(t,n_forced*${SEGMENT_SECONDS})`, "-sc_threshold", "0",
+      "-vf", strat.filter,
+      ...strat.video,
       "-c:a", "aac", "-ac", "2", "-b:a", rend.audioBitrate,
       "-hls_time", String(SEGMENT_SECONDS), "-hls_playlist_type", "vod",
       "-hls_segment_filename", join(dir, `r${rend.height}_%03d.ts`),
@@ -65,11 +145,44 @@ function runFfmpeg(inPath, dir, rend, playlist, onFrac, signal) {
   });
 }
 
+/**
+ * Encode one rendition, trying strategies fastest→slowest and falling back on
+ * failure. If a strategy fails *fast* (before real encoding — i.e. it's not
+ * available on this machine, like a missing GPU filter), we advance the starting
+ * point permanently so future jobs skip it. A *slow* failure (mid-encode, likely
+ * file-specific) falls back for this file only, leaving fast paths for next time.
+ */
+async function encodeRendition(ffmpegPath, encoder, inPath, dir, rend, playlist, onFrac, signal) {
+  const strategies = buildStrategies(encoder.codec, rend);
+  const start = Math.min(_stratStart, strategies.length - 1);
+  let lastErr;
+  for (let i = start; i < strategies.length; i++) {
+    const strat = strategies[i];
+    const t0 = Date.now();
+    try {
+      await runFfmpeg(ffmpegPath, strat, inPath, dir, rend, playlist, onFrac, signal);
+      if (i > start) log(`✓ "${strat.label}" — using it for subsequent jobs.`);
+      return;
+    } catch (e) {
+      if (signal?.aborted) throw e;
+      lastErr = e;
+      // Fast failure ⇒ this strategy isn't available on this box; skip it for good.
+      if (Date.now() - t0 < FAST_FAIL_MS) _stratStart = Math.max(_stratStart, i + 1);
+      const next = strategies[i + 1];
+      if (next) {
+        log(`⚠︎ "${strat.label}" failed (${String(e?.message || e).slice(0, 140)}) — falling back to "${next.label}".`);
+      }
+    }
+  }
+  throw lastErr;
+}
+
 /**
  * Transcode raw bytes into HLS shards stored in `space`.
  * @returns {{ hls_index: unknown, duration: number, size: number }}
  */
 export async function transcodeToHls({ rawBytes, filename, space, onProgress, signal }) {
+  const { ffmpegPath, encoder } = ensureEncoder();
   const dir = await mkdtemp(join(tmpdir(), "tt-"));
   try {
     const ext = filename.match(/\.\w+$/)?.[0] || ".mp4";
@@ -82,8 +195,9 @@ export async function transcodeToHls({ rawBytes, filename, space, onProgress, si
     for (let r = 0; r < nR; r++) {
       const rend = RENDITIONS[r];
       const playlist = join(dir, `r${rend.height}.m3u8`);
+      const onFrac = (f) => onProgress?.({ fraction: (r + f) / nR, label: `Encoding ${rend.height}p…` });
       onProgress?.({ fraction: r / nR, label: `Encoding ${rend.height}p…` });
-      await runFfmpeg(inPath, dir, rend, playlist, (f) => onProgress?.({ fraction: (r + f) / nR, label: `Encoding ${rend.height}p…` }), signal);
+      await encodeRendition(ffmpegPath, encoder, inPath, dir, rend, playlist, onFrac, signal);
 
       const durations = parseDurations(await readFile(playlist, "utf8"));
       const segments = [];

package/src/worker.js

@@ -6,7 +6,7 @@
  * background, and the browser can also process it locally from memory.
  */
 import { hostname, cpus } from "node:os";
-import { transcodeToHls } from "./transcode.js";
+import { transcodeToHls, ensureEncoder } from "./transcode.js";
 
 const WORKER_ID = `node-${Math.random().toString(36).slice(2, 10)}`;
 const WORKER_LABEL = `the transcoder (${hostname()})`;
@@ -108,6 +108,7 @@ export function startWorker({ client, space, appKey, baseUrl }) {
   let stopped = false;
   (async () => {
     log(`worker ${WORKER_ID} draining queue as ${client.auth.zk.user.username} (${WORKER_LABEL}, score ${MY_SCORE})`);
+    ensureEncoder(); // probe + log the ffmpeg binary / hardware encoder up front
     // Announce capability so browsers defer manifest-ready jobs to us.
     const hello = () => void postSignal({ kind: "hello", score: MY_SCORE, worker: WORKER_LABEL, native: true });
     hello(); setInterval(hello, 4_000);