ffmpeg-render-pro

Parallel video rendering with live dashboard, GPU auto-detection, checkpoint system, and stream-copy concat. Includes an MCP server, a Claude Code skill, and a CLI.

Built by Beeswax Pat · Free and open source forever

Features

• Parallel rendering: Split frames across N worker threads, concat with zero re-encoding
• GPU auto-detection: Probes NVENC, VideoToolbox, AMF, VA-API, QSV with 1-frame validation
• Live dashboard: Auto-opens in your browser with per-worker progress, FPS chart, ETA
• Checkpoint system: 93% reduction in fast-forward overhead for long renders
• Color grading: 5 built-in presets (noir, warm, cool, cinematic, vintage) plus custom filters
• Audio merge: Combine video + audio with loudness normalization, no video re-encode
• Deterministic output: Seeded RNG ensures parallel workers produce identical results to sequential
• MCP server: Model Context Protocol server with 7 tools, works with Claude Code, Claude Desktop, and any MCP client
• Cross-platform: Windows, macOS, Linux. Any GPU or CPU-only. Requires Node.js >= 18 plus ffmpeg.

What's New in v1.5.0

A reliability and agent-integration pass. Fully backward-compatible: every CLI command, API signature, MCP tool name, worker contract, and checkpoint file format from 1.4.x works unchanged.

• Checkpoint resume is exact again. generateCheckpoints saved state one frame ahead of its label, so checkpoint-resumed workers rendered one frame out of sync with a sequential render. Regenerate checkpoint dirs created before 1.5.0 to pick up the fix.
• VA-API actually works on Linux. The probe and codec args now include device init plus hwupload; previously every AMD/Intel GPU on Linux silently fell back to CPU.
• VideoToolbox quality mapping fixed (it was inverted), and every encoder is now validated with its real production args, so Intel Macs fall back to CPU at detection time instead of failing at render time.
• concatSegments validates segment compatibility (codec, resolution, fps, pixel format) with ffprobe before joining; mismatched inputs used to produce silently corrupt output.
• The MCP server is agent-native: structured output and output schemas on every tool, progress notifications, clean cancellation, a new get_worker_template tool, and guaranteed protocol hygiene (stdout carries only JSON-RPC frames).
• New renderParallel options: signal (AbortSignal) and quiet (byte-clean stdout). A failed worker's frame range is retried once automatically, and failures surface on the live dashboard.
• New CLI flags --crf and --encoder-preset; FFMPEG_RENDER_PRO_FFMPEG / FFMPEG_RENDER_PRO_FFPROBE env vars support ffmpeg installs that are not on PATH.
• Fractional fps x duration no longer drops a frame to float error (25fps x 4.6s renders 115 frames, not 114).
• 81 tests grew to 241 across 12 suites, plus a GitHub Actions test matrix (Ubuntu/Windows/macOS x Node 18/20/22) with real ffmpeg installs.

See CHANGELOG.md for the complete list.

Requirements

• Node.js >= 18
• ffmpeg installed and on PATH (or pointed to via env var, below)

Using ffmpeg That Is Not on PATH

ffmpeg and ffprobe binaries are resolved at call time from two env vars (one exception: the best-effort post-render output check, noted below):

# Full path to the ffmpeg executable (used by every render, grade, merge, concat, probe)
FFMPEG_RENDER_PRO_FFMPEG=/opt/ffmpeg/bin/ffmpeg

# Optional: full path to ffprobe. When unset and FFMPEG_RENDER_PRO_FFMPEG is set,
# the sibling ffprobe next to that ffmpeg is used automatically if it exists.
FFMPEG_RENDER_PRO_FFPROBE=/opt/ffmpeg/bin/ffprobe

Because the vars are read at call time (never cached at module load), a long-lived process such as the MCP server picks up changes without a restart. Error messages name these variables when a binary cannot be found. A third variable, FFMPEG_RENDER_PRO_CACHE_DIR, overrides the GPU detection cache directory (default ~/.ffmpeg-render-pro).

Install

# Global install gives you the ffmpeg-render-pro + ffmpeg-render-pro-mcp binaries
npm install -g ffmpeg-render-pro

# Or clone the repo directly
git clone https://github.com/beeswaxpat/ffmpeg-render-pro.git
cd ffmpeg-render-pro

Quick Start

# System info (workers, RAM, CPU, ffmpeg version)
ffmpeg-render-pro info

# Probe hardware encoders
ffmpeg-render-pro detect-gpu

# 5s benchmark render (dashboard auto-opens at http://127.0.0.1:8080)
ffmpeg-render-pro benchmark

# Longer render, custom resolution
ffmpeg-render-pro benchmark --duration=30 --width=1080 --height=1920 --fps=30

# Force CPU / GPU encoding
ffmpeg-render-pro detect-gpu --cpu
ffmpeg-render-pro detect-gpu --gpu

CLI

ffmpeg-render-pro info                # System snapshot
ffmpeg-render-pro detect-gpu          # Probe hardware encoders
ffmpeg-render-pro render <worker.js>  # Render with your worker script
ffmpeg-render-pro benchmark           # Quick 5s test render
ffmpeg-render-pro version             # Print the installed version

Dashboard control flags for render and benchmark: --no-dashboard (disable entirely), --no-open (serve but don't open a browser), --port=8080, and --linger-ms=30000 (how long the dashboard stays up after completion; 0 exits immediately). Run ffmpeg-render-pro with no arguments for the full flag reference.

Quality flags for render and benchmark: --crf=NN (0-51, lower is higher quality) and --encoder-preset=NAME (any x264 preset name: ultrafast through placebo). Both are passed to workers via workerData.codecArgs; the bundled worker honors them, and custom workers can too.

Flag validation: an unknown flag prints a warning on stderr and execution continues (scripts stay forward compatible), but an unparseable value like --fps=abc or an out-of-range --crf=99 exits 1 with a clear error instead of silently rendering at the default.

Installed binaries: ffmpeg-render-pro (this CLI) and ffmpeg-render-pro-mcp (the MCP server). A legacy ffmpeg-render-mcp alias for the MCP server also exists and is kept permanently so older MCP configs never break.

NVENC Quick Reference

The renderer auto-detects NVENC on its own. For one-off encodes outside the renderer, these are the two commands to know.

Confirm NVENC is present before you rely on it. If the encoder is not built into your ffmpeg, it errors with Unknown encoder 'h264_nvenc', and without this probe you find that out an hour into a render:

ffmpeg -encoders | grep nvenc
ffmpeg -y -f lavfi -i testsrc=size=256x256:rate=30:d=1 -c:v h264_nvenc -cq 23 probe.mp4

GPU encode with h264_nvenc. Presets run p1 (fastest) to p7 (best quality); -cq is the quality target, same direction as CRF, lower is better:

ffmpeg -i in.mp4 -c:v h264_nvenc -preset p5 -cq 21 -pix_fmt yuv420p -c:a aac -b:a 192k -movflags +faststart out.mp4

One trap worth knowing: h264_nvenc refuses very narrow frames (measured minimum width 145px on a Turing card; other generations may sit elsewhere) by writing a zero-byte output file and exiting, which a "did the output file get created" check reads as success. Keeping capability probes at 256x256 sidesteps the whole question.

Both commands above are from the ffmpeg Render Cookbook ($12): 29 copy-paste recipes, every one executed on ffmpeg 8.0.1 before publication, covering NVENC, YouTube export, loudness normalization, parallel rendering, and HDR tone mapping, each with the failure it prevents.

API

const {
  renderParallel,       // Core: parallel rendering engine
  createEncoder,        // Pipe raw frames to ffmpeg
  detectGPU,            // Cross-platform GPU detection
  getConfig,            // Auto-tune workers, codec selection
  computeTotalFrames,   // Float-safe frame count for an fps/duration pair
  concatSegments,       // Stream-copy segment joining (validates by default)
  colorGrade,           // Apply color grades (presets or custom)
  mergeAudio,           // Combine video + audio
  startDashboard,       // Live progress dashboard
  ProgressTracker,      // Per-worker progress + dashboard JSON writer
  saveCheckpoint,       // Checkpoint serialization
  loadCheckpoint,       // Checkpoint restoration
  getEncoderIO,         // Encoder recipe split into inputArgs/filter/outputArgs
  getCodecArgs,         // Encoder recipe as one flat arg array
  getEncoderCandidates, // Platform's encoder candidates in priority order
  validateEncoder,      // 1-frame probe of one encoder with production args
  ffmpegBin,            // Resolved ffmpeg binary (env-var aware)
  ffprobeBin,           // Resolved ffprobe binary (env-var aware)
} = require('ffmpeg-render-pro');

renderParallel(options)

The main entry point. Splits a render across workers, shows a live dashboard, and produces a final MP4.

const controller = new AbortController();

await renderParallel({
  workerScript: './my-worker.js',  // Your frame generator
  outputPath: './output.mp4',
  width: 1920,
  height: 1080,
  fps: 60,
  duration: 60,         // seconds
  title: 'My Render',
  autoOpen: true,       // auto-open dashboard in browser
  maxWorkers: 8,        // cap for auto worker count (override with workerCount)
  dashboardLingerMs: 0, // 0 = resolve immediately; CLI default keeps it up 30s
  signal: controller.signal, // optional: abort stops workers + cleans temp files
  quiet: false,         // true keeps stdout byte-clean (status goes to stderr)
});

Width and height must be even (the pipeline encodes yuv420p). For library use, set dashboardLingerMs: 0 so the call resolves without holding the process open. renderParallel resolves with { outputPath, elapsed, totalFrames, avgFps }. Set FFMPEG_RENDER_PRO_DEBUG=1 in the environment for full stack traces from the CLI on error (library rejections carry the stack either way).

Reliability behavior baked into every render:

• Abort: pass an AbortSignal as signal. Calling abort() stops all workers, removes temp files, and rejects the promise with an error whose name is 'AbortError'.
• Quiet mode: quiet: true routes all status lines to stderr and disables the terminal progress ticker, so stdout stays byte-clean for protocol use (this is how the MCP server runs). Dashboard JSON files are still written.
• One-shot retry: a failed worker's frame range is respawned once (to a fresh segment path) before the render is failed; a stderr warning names the worker and attempt.
• Output verification: after concat, one cheap ffprobe metadata read warns on stderr if the output is shorter than requested. It never fails the render and is silent when ffprobe is missing. This best-effort check looks for ffprobe on PATH only; it is the one spawn that does not consult FFMPEG_RENDER_PRO_FFPROBE.
• Failure surfaces live: on error the dashboard shows a red RENDER FAILED banner (and the browser tab title flips to FAILED) instead of freezing at the last good state.

The workerCount option is a request, not a guarantee: the renderer