io.github.beeswaxpat/ffmpeg-render-pro

ffmpeg-render-pro

Render video from code, in parallel. You write one function that paints a frame; ffmpeg-render-pro splits the frame range across worker threads, encodes one MP4 segment per worker, joins the segments with stream copy (no re-encode), and shows a live dashboard in your browser while it runs. It also detects GPU encoders, grades color, merges audio, and ships as a CLI, a Node library, an MCP server for AI agents, and a Claude Code skill.

Built by Beeswax Pat. Free and open source.

Start here

Three commands. You need Node.js 18 or newer and ffmpeg on your PATH.

# 1. Prove the setup works: a 5 second test render. The dashboard opens in your browser.
npx ffmpeg-render-pro benchmark

# 2. Write a starter worker script into the current folder.
npx ffmpeg-render-pro init my-worker.js

# 3. Render it. Output lands in output.mp4.
npx ffmpeg-render-pro render my-worker.js --duration=5

Open my-worker.js. The only function you need to change is renderFrame(frameNum, buffer): fill the buffer with your pixels (B, G, R, A, one row after another) and everything else is already done. Derive any randomness from the seed it receives and parallel output stays identical to a sequential render.

Install it globally if you would rather not type npx:

npm install -g ffmpeg-render-pro

Using an ffmpeg that is not on PATH

FFMPEG_RENDER_PRO_FFMPEG=/opt/ffmpeg/bin/ffmpeg     # ffmpeg binary
FFMPEG_RENDER_PRO_FFPROBE=/opt/ffmpeg/bin/ffprobe   # optional; the sibling ffprobe is found automatically
FFMPEG_RENDER_PRO_CACHE_DIR=~/.ffmpeg-render-pro    # optional; where GPU probe results are cached

The variables are read at call time, so a long-running process such as the MCP server picks up changes without a restart.

CLI

ffmpeg-render-pro init [my-worker.js]   # write the starter worker (--force overwrites)
ffmpeg-render-pro benchmark             # 5 second test render with the bundled worker
ffmpeg-render-pro render <worker.js>    # render with your worker
ffmpeg-render-pro info                  # cores, RAM, recommended workers, ffmpeg version, GPU
ffmpeg-render-pro detect-gpu            # probe hardware encoders (--cpu / --gpu force a mode)
ffmpeg-render-pro version

Render and benchmark flags: --width=1920 --height=1080 (must be even), --fps=60, --duration=60 (fractions allowed), --output=out.mp4, --workers=N, --max-workers=8, --seed=42, --title="...", --crf=20 (0-51, lower is higher quality), --encoder-preset=fast (any x264 preset). Dashboard flags: --no-dashboard, --no-open, --port=8080, --linger-ms=30000 (0 exits as soon as the render finishes). Run ffmpeg-render-pro with no arguments for the full list.

An unknown flag warns and continues. A value that does not parse, such as --fps=abc, exits 1 instead of rendering at the default.

Installed binaries: ffmpeg-render-pro (this CLI) and ffmpeg-render-pro-mcp (the MCP server). The older ffmpeg-render-mcp name still works so existing MCP configs never break.

How a render works

1. renderParallel checks ffmpeg, validates the resolution, and picks a worker count from your CPU cores and RAM (never more workers than frames).
2. It starts the dashboard server on 127.0.0.1 and opens your browser.
3. Each worker thread runs your script with a frame range in workerData, pipes raw BGRA frames into its own ffmpeg process, and writes one MP4 segment.
4. Segments are joined with the concat demuxer and -c copy, which takes seconds regardless of length.
5. Temp files are removed. A failed worker's range is retried once before the render fails.

Your worker

A worker is a Node script that runs in a worker_threads thread. init gives you one where only renderFrame needs editing; examples/basic-worker.js in the installed package is a larger reference with a particle system and seeded RNG.

Fields the renderer injects through workerData:

Field	Meaning
width, height, fps	Frame size and rate
seed	Derive every random value from this
startFrame, endFrame	Render exactly [startFrame, endFrame)
segmentPath	Write this worker's MP4 here
workerId	Include it in every message you post
totalFrames, duration	Whole-video totals, for global effects such as a progress bar
anything in renderParallel({ workerData })	Your own extra keys (the bundled workers honor codecArgs)

Messages the worker posts with parentPort.postMessage:

Message	When	Fields
{ type: 'progress' }	periodically	workerId, pct, fps, frame, eta
{ type: 'fast-forward-start' }	optional, before replaying state to reach startFrame	workerId, frames
{ type: 'done' }	once, after the segment is fully written	workerId
{ type: 'error' }	on failure, never followed by done	workerId, error

Every worker must encode with the same codec, resolution, framerate, and pixel format, because the segments are stream-copied together.

Library

const {
  renderParallel,       // the render engine
  createEncoder,        // pipe raw frames into ffmpeg with backpressure
  detectGPU,            // hardware encoder discovery, cached 7 days
  getConfig,            // worker count and codec choice for a resolution
  computeTotalFrames,   // float-safe fps x duration
  concatSegments,       // stream-copy join (validates inputs by default)
  colorGrade,           // presets or a custom -vf chain
  mergeAudio,           // add a soundtrack without re-encoding video
  startDashboard,       // the local progress server
  ProgressTracker,      // per-worker progress plus dashboard JSON
  saveCheckpoint, loadCheckpoint, restoreCheckpoint, generateCheckpoints,
  getEncoderIO,         // encoder recipe as { inputArgs, filter, outputArgs }
  getCodecArgs,         // the same recipe as one flat array
  ffmpegBin, ffprobeBin // resolved binaries, env-var aware
} = require('ffmpeg-render-pro');

renderParallel(options)

const controller = new AbortController();

const result = await renderParallel({
  workerScript: './my-worker.js',   // required
  outputPath: './output.mp4',       // required
  width: 1920, height: 1080,        // even numbers, up to 7680x4320
  fps: 60, duration: 60,
  seed: 42,
  title: 'My Render',               // shown in the dashboard
  workerCount: undefined,           // exact count; omit to auto-detect
  maxWorkers: 8,                    // cap for auto-detect
  dashboard: true, autoOpen: true, dashboardPort: 8080,
  dashboardLingerMs: 0,             // 0 resolves as soon as the render ends (the CLI keeps it up 30s)
  quiet: false,                     // true keeps stdout byte-clean; status goes to stderr
  signal: controller.signal,        // abort() stops workers and removes temp files
  workerData: {},                   // extra keys for your worker
});
// result: { outputPath, elapsed, totalFrames, avgFps }

Abort rejects with an error whose name is 'AbortError'. In library use set dashboardLingerMs: 0 so the call returns without holding the process open. Set FFMPEG_RENDER_PRO_DEBUG=1 for full stack traces from the CLI.

Post-processing

// Color grade with a preset (noir, warm, cool, cinematic, vintage) or a custom -vf chain
await colorGrade({ inputPath: 'raw.mp4', outputPath: 'graded.mp4', preset: 'cinematic' });
await colorGrade({ inputPath: 'raw.mp4', outputPath: 'graded.mp4', filter: 'eq=contrast=1.08:saturation=0.9', crf: 18 });
await colorGrade({ inputPath: 'final.mp4', outputPath: 'graded.mp4', preset: 'noir', keepAudio: true }); // default strips audio

// Merge audio: video is stream-copied, audio becomes AAC. loop and normalize (loudnorm) are optional.
await mergeAudio({ videoPath: 'graded.mp4', audioPath: 'track.mp3', outputPath: 'final.mp4', bitrate: 320, loop: true, normalize: true });

// Join same-codec, same-size videos with stream copy. Inputs are probed with ffprobe first; pass { validate: false } to skip.
await concatSegments(['part-000.mp4', 'part-001.mp4'], 'joined.mp4');

colorGrade accepts any encoder name in codec; encoders that need their own filter (VA-API) get it merged into the grade chain automatically.

Checkpoints for long renders

For multi-hour renders, snapshot your simulation state every N frames once, so each worker replays only the frames since the nearest snapshot instead of starting from frame 0.

generateCheckpoints({ systems, totalFrames: 432000, fps: 60, checkpointDir: './.checkpoints', interval: 60000 });

// inside a worker
const cp = loadCheckpoint('./.checkpoints', startFrame);
if (cp) {
  const resumeFrame = restoreCheckpoint(cp, systems);
  // fast-forward from resumeFrame to startFrame, then render
}

systems is an object of named modules with getState(), setState(), and update(dt). A checkpoint labeled frame F holds exactly F updates. _frame and _timestamp are reserved keys.

MCP server (for AI agents)

Seven tools over stdio, usable from Claude Code, Claude Desktop, or any MCP client.

# Claude Code, no install needed
claude mcp add --transport stdio ffmpeg-render-pro -- npx --yes --package=ffmpeg-render-pro ffmpeg-render-pro-mcp

# Claude Code, after npm install -g ffmpeg-render-pro
claude mcp add --transport stdio ffmpeg-render-pro -- ffmpeg-render-pro-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "ffmpeg-render-pro": {
      "command": "npx",
      "args": ["--yes", "--package=ffmpeg-render-pro", "ffmpeg-render-pro-mcp"]
    }
  }
}

Tool	What it does
get_worker_template	Returns the worker contract, the starter worker source, and paths to both bundled workers. Start here.
render_video	Parallel render from a worker script, with progress notifications and cancellation
detect_gpu	Probe hardware encoders (NVENC, VideoToolbox, AMF, VA-API, QSV)
system_info	Cores, RAM, recommended worker count, ffmpeg version
color_grade	Presets or a custom filter
merge_audio	Add a soundtrack, video stream-copied
concat_videos	Stream-copy join, inputs validated by default

The agent recipe: call get_worker_template, copy starterSource to a file and replace renderFrame, then call render_video with that file as worker_script (dashboard: false, auto_open: false for headless runs). To render without writing code, pass the returned starterPath or templatePath straight to render_video. Post-process with color_grade, merge_audio, and concat_videos.

Every tool declares an outputSchema and returns structuredContent, so parse JSON instead of text. Writers overwrite output_path. render_video defaults to 30 fps (the CLI defaults to 60), emits notifications/progress every 2 seconds when the client sends a progressToken (turn on resetTimeoutOnProgress for long renders), and stops all workers on client cancellation. stdout carries only JSON-RPC frames. Missing ffmpeg returns an error that names the install page and the env var.

The tarball also ships llms.txt at the package root and a Claude Code skill:

# from a global install (macOS / Linux)
cp -r "$(npm root -g)/ffmpeg-render-pro/.claude/skills/ffmpeg-render-pipeline" ~/.claude/skills/
# from a repo clone (Windows)
xcopy .claude\skills\ffmpeg-render-pipeline %USERPROFILE%\.claude\skills\ffmpeg-render-pipeline\ /E /I

NVENC quick reference

The renderer detects NVENC by itself. For one-off encodes outside it:

# confirm the encoder exists before relying on it
ffmpeg -y -f lavfi -i testsrc=size=256x256:rate=30:d=1 -c:v h264_nvenc -cq 23 probe.mp4

# encode: presets p1 (fastest) to p7 (best); -cq works like 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

h264_nvenc rejects very narrow frames (145px minimum on a Turing card) by writing a zero-byte file and exiting, so keep probes at 256x256. Both commands come from the ffmpeg Render Cookbook ($12): 29 recipes, each run on ffmpeg 8.0.1 before publication.

Security notes

• Releases are published to npm by GitHub Actions through npm trusted publishing (OIDC). There is no publish token, and every version from 1.5.2 on carries a provenance attestation that ties the tarball on npm to the exact commit and workflow run that built it (see the Provenance panel on the npm page).
• The dashboard binds to 127.0.0.1 only and loads nothing from the network. No telemetry.
• render_video and renderParallel execute the worker script you name with the privileges of the current user. Only run workers you wrote or trust.
• The MCP server reads and writes files anywhere the current user can. Run it with a trusted agent, and consider restricting its working directory when prompts are untrusted.
• A custom filter string is file access: ffmpeg filters such as movie= and subtitles= read local files. Treat filter input the way you treat a file path.
• Concat list files are written under os.tmpdir(); output paths are written exactly where you point them.

Tests

npm test runs 12 zero-dependency suites (255 checks): unit, smoke, a real MCP session over stdio with a byte audit of stdout, and end-to-end renders verified with ffprobe and framemd5. It skips the render suites cleanly on machines without ffmpeg. CI runs the same on Ubuntu, Windows, and macOS against Node 18, 20, 22, and 24.

Changelog and license

See CHANGELOG.md. MIT.