# Ffmpeg Render Pro > Parallel video rendering with live dashboard, GPU auto-detection, and stream-copy concat. MCP server with 7 typed tools for AI agents, a Claude Code skill, and a CLI. - **Type:** MCP server - **Install:** `agentstack add mcp-beeswaxpat-ffmpeg-render-pro` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [beeswaxpat](https://agentstack.voostack.com/s/beeswaxpat) - **Installs:** 0 - **Category:** [Data & Analytics](https://agentstack.voostack.com/c/data-and-analytics) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [beeswaxpat](https://github.com/beeswaxpat) - **Source:** https://github.com/beeswaxpat/ffmpeg-render-pro - **Website:** https://www.npmjs.com/package/ffmpeg-render-pro ## Install ```sh agentstack add mcp-beeswaxpat-ffmpeg-render-pro ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About ``` ╔══════════════════════════════════════════════════════╗ ║ ║ ║ ████████ ████████ ██ ██ ██████ ████████ ████ ║ ║ ██ ██ ███ ███ ██ ██ ██ ██ ║ ║ ██████ ██████ ██ ██ ██ ██████ ██████ ██ ██ ║ ║ ██ ██ ██ ██ ██ ██ ██ ██ ║ ║ ██ ██ ██ ██ ██ ████████ ████ ║ ║ ║ ║ ██████ ████████ ██ ██ ██████ ████████ ██████ ║ ║ ██ ██ ██ ███ ██ ██ ██ ██ ██ ██ ║ ║ ██████ ██████ ██ ██ ██ ██ ██ ██████ ██████ ║ ║ ██ ██ ██ ██ ████ ██ ██ ██ ██ ██ ║ ║ ██ ██ ████████ ██ ██ ██████ ████████ ██ ██ ║ ║ ║ ║ ██████ ██████ ████ ║ ║ ██ ██ ██ ██ ██ ██ ║ ║ ██████ ██████ ██ ██ ║ ║ ██ ██ ██ ██ ██ ║ ║ ██ ██ ██ ████ ║ ║ ║ ║ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░ 8 WRKRS ║ ║ GPU: AUTO DASHBOARD: LIVE CONCAT: INSTANT ║ ╚══════════════════════════════════════════════════════╝ ``` # ffmpeg-render-pro [](https://www.npmjs.com/package/ffmpeg-render-pro) [](LICENSE) [](https://github.com/beeswaxpat/ffmpeg-render-pro) [](https://nodejs.org/) [](https://modelcontextprotocol.io) 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](https://github.com/beeswaxpat) · 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](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): ```bash # 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 ```bash # 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 ```bash # 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 ```bash ffmpeg-render-pro info # System snapshot ffmpeg-render-pro detect-gpu # Probe hardware encoders ffmpeg-render-pro render # 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. ## API ```js 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. ```js 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 never spawns more workers than there are frames, so short renders may use fewer. Auto-detection caps at `maxWorkers` (default 8), free RAM, and CPU cores minus 2. ### Encoder Helpers `getCodecArgs(encoder, { crf, cq, preset })` returns the full production arg array for any of the 11 supported encoders (libx264, NVENC, VideoToolbox, AMF, VA-API, QSV in H.264 and HEVC variants). For VA-API that array includes device init and a `-vf format=nv12,hwupload` pair, because the encoder cannot run without them. `getEncoderIO(encoder, opts)` returns the same recipe split into `{ inputArgs, filter, outputArgs }`. If you build your own `-vf` chain (color grading, scaling), merge `getEncoderIO().filter` into that chain instead of passing two `-vf` flags: ffmpeg only honors the last `-vf` per stream and silently drops the others. This also applies to `colorGrade` with a VA-API codec; keep the default `libx264` for grading, or compose the invocation yourself via `getEncoderIO`. `computeTotalFrames(fps, duration)` is the float-safe frame count the renderer itself uses (25fps x 4.6s correctly yields 115, not 114). `ProgressTracker` accepts a `terminalStream` constructor option (default `process.stdout`; pass `null` to disable the terminal ticker while JSON keeps writing) and has a `fail(message)` method that writes a terminal `error` phase for the dashboard. ### Writing a Worker Workers receive frame ranges via `workerData` and pipe raw BGRA frames to ffmpeg: ```js const { workerData, parentPort } = require('worker_threads'); const { spawn } = require('child_process'); const { width, height, fps, startFrame, endFrame, segmentPath, workerId } = workerData; async function main() { // Spawn ffmpeg encoder (env-var aware, falls back to PATH) const ffmpeg = spawn(process.env.FFMPEG_RENDER_PRO_FFMPEG || 'ffmpeg', [ '-y', '-f', 'rawvideo', '-pixel_format', 'bgra', '-video_size', `${width}x${height}`, '-framerate', String(fps), '-i', 'pipe:0', '-c:v', 'libx264', '-preset', 'fast', '-crf', '20', '-pix_fmt', 'yuv420p', '-movflags', '+faststart', segmentPath, ], { stdio: ['pipe', 'pipe', 'pipe'] }); // Keep the last 8KB of ffmpeg stderr: it carries the error message on // failure, and an uncapped buffer grows unbounded on long renders. let stderrTail = ''; ffmpeg.stderr.on('data', (c) => { stderrTail = (stderrTail + c).slice(-8192); }); // Capture stdin errors (EPIPE when ffmpeg dies mid-pipe) and track the exit // from an EARLY close listener, so the final wait never attaches 'close' // after the event already fired (which would hang forever). let streamError = null; ffmpeg.stdin.on('error', (err) => { if (!streamError) streamError = err; }); let closed = false; let closeCode = null; ffmpeg.on('close', (code) => { closed = true; closeCode = code; }); const frameSize = width * height * 4; // BGRA const buffer = Buffer.alloc(frameSize); // Frames under the pipe's high-water mark can be queued BY REFERENCE even // when write() returns true, so small frames must be copied before writing. // Bigger frames keep zero-copy reuse: write() returns false and the drain // wait guarantees a full flush before the buffer is mutated again. const copyFrames = frameSize ffmpeg.stdin.once('drain', r)); // Report progress const done = f - startFrame + 1; parentPort.postMessage({ type: 'progress', workerId, pct: (done / (endFrame - startFrame)) * 100, fps: 0, frame: done, eta: 0, }); } // Close the encoder; resolve from captured state if it already exited. ffmpeg.stdin.end(); await new Promise((resolve, reject) => { const finish = (code) => (code === 0 ? resolve() : reject(new Error(`ffmpeg exited ${code}: ${stderrTail.slice(-500)}`))); if (closed) return finish(closeCode); ffmpeg.once('close', finish); }); parentPort.postMessage({ type: 'done', workerId }); } main().catch((err) => { parentPort.postMessage({ type: 'error', workerId, error: err.message }); }); ``` See `examples/basic-worker.js` for the complete hardened reference worker (its drain wait also wakes on error/close, it never posts `done` after `error`, and it honors `workerData.codecArgs`). The MCP `get_worker_template` tool returns this contract plus the full reference source. **Worker data** (injected via `worker_threads` `workerData`): `width`, `height`, `fps`, `seed`, `startFrame`, `endFrame`, `segmentPath`, `workerId`, `totalFrames`, `duration`, plus anything you pass in `renderParallel({ workerData })`. **Messages a worker posts** to the parent via `parentPort.postMessage(...)`: | … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [beeswaxpat](https://github.com/beeswaxpat) - **Source:** [beeswaxpat/ffmpeg-render-pro](https://github.com/beeswaxpat/ffmpeg-render-pro) - **License:** MIT - **Homepage:** https://www.npmjs.com/package/ffmpeg-render-pro Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** yes - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-beeswaxpat-ffmpeg-render-pro - Seller: https://agentstack.voostack.com/s/beeswaxpat - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.