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 # 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:

Messages the worker posts with parentPort.postMessage:

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"] } } }

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:

`