╔══════════════════════════════════════════════════════╗
║ ║
║ ████████ ████████ ██ ██ ██████ ████████ ████ ║
║ ██ ██ ███ ███ ██ ██ ██ ██ ║
║ ██████ ██████ ██ ██ ██ ██████ ██████ ██ ██ ║
║ ██ ██ ██ ██ ██ ██ ██ ██ ║
║ ██ ██ ██ ██ ██ ████████ ████ ║
║ ║
║ ██████ ████████ ██ ██ ██████ ████████ ██████ ║
║ ██ ██ ██ ███ ██ ██ ██ ██ ██ ██ ║
║ ██████ ██████ ██ ██ ██ ██ ██ ██████ ██████ ║
║ ██ ██ ██ ██ ████ ██ ██ ██ ██ ██ ║
║ ██ ██ ████████ ██ ██ ██████ ████████ ██ ██ ║
║ ║
║ ██████ ██████ ████ ║
║ ██ ██ ██ ██ ██ ██ ║
║ ██████ ██████ ██ ██ ║
║ ██ ██ ██ ██ ██ ║
║ ██ ██ ██ ████ ║
║ ║
║ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░ 8 WRKRS ║
║ GPU: AUTO DASHBOARD: LIVE CONCAT: INSTANT ║
╚══════════════════════════════════════════════════════╝
具备实时仪表盘、GPU 自动检测、检查点系统和流拷贝拼接功能的并行视频渲染工具。这是目前最强大的免费 ffmpeg 渲染工具包。
由 Beeswax Pat 使用 Claude Code 构建 · 永久免费且开源
并行渲染 — 将帧拆分到 N 个工作线程，无需重新编码即可拼接
GPU 自动检测 — 通过 1 帧验证探测 NVENC、VideoToolbox、AMF、VA-API、QSV
实时仪表盘 — 自动在浏览器中打开，显示各工作线程进度、FPS 图表和预计完成时间 (ETA)
检查点系统 — 将长视频渲染的快进开销降低 93%
调色 (Color grading) — 内置 5 种预设（黑色电影、暖色、冷色、电影感、复古）+ 自定义滤镜
音频合并 — 结合视频和音频并进行响度标准化，无需重新编码视频
确定性输出 — 种子化随机数生成器确保并行工作线程产生与顺序渲染一致的结果
MCP 服务器 — 包含 6 个工具的 Model Context Protocol 服务器，可与 Claude Code、Claude Desktop 及任何 MCP 客户端配合使用
跨平台 — 支持 Windows、macOS、Linux。支持任何 GPU 或仅 CPU 渲染。需要 Node.js >= 18 + ffmpeg。
Related MCP server: ffmpeg-mcp
Node.js >= 18
已安装 ffmpeg 并添加到 PATH 环境变量
# 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# 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 --gpuffmpeg-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 renderconst {
renderParallel, // Core: parallel rendering engine
createEncoder, // Pipe raw frames to ffmpeg
detectGPU, // Cross-platform GPU detection
getConfig, // Auto-tune workers, codec selection
concatSegments, // Stream-copy segment joining
colorGrade, // Apply color grades (presets or custom)
mergeAudio, // Combine video + audio
startDashboard, // Live progress dashboard
saveCheckpoint, // Checkpoint serialization
loadCheckpoint, // Checkpoint restoration
} = require('ffmpeg-render-pro');主要入口点。将渲染任务拆分到多个工作线程，显示实时仪表盘，并生成最终的 MP4 文件。
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
});工作线程通过 workerData 接收帧范围，并将原始 BGRA 帧通过管道传输给 ffmpeg：
const { workerData, parentPort } = require('worker_threads');
const { spawn } = require('child_process');
const { width, height, fps, startFrame, endFrame, segmentPath, workerId } = workerData;
// Spawn ffmpeg encoder
const ffmpeg = spawn('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'] });
const buffer = Buffer.alloc(width * height * 4);
for (let f = startFrame; f < endFrame; f++) {
// Fill buffer with your frame data (BGRA format)
renderMyFrame(f, buffer);
// Write with backpressure
const ok = ffmpeg.stdin.write(buffer);
if (!ok) await new Promise(r => ffmpeg.stdin.once('drain', r));
// Report progress
parentPort.postMessage({ type: 'progress', workerId, pct: ..., fps: ..., frame: ..., eta: ... });
}
ffmpeg.stdin.end();
ffmpeg.on('close', () => parentPort.postMessage({ type: 'done', workerId }));查看 examples/basic-worker.js 获取完整的运行示例。
模块 | 用途 |
| 带有进度跟踪的 N 工作线程池 |
| 将原始帧通过管道传输给带有背压控制的 ffmpeg |
| 跨平台硬件编码器发现与验证 |
| 基于分辨率、内存、CPU 自动调整工作线程 |
| 流拷贝分段拼接（即时完成） |
| ffmpeg 视频滤镜预设 + 自定义链 |
| 支持响度标准化的视频与音频合并 |
| 无依赖 HTTP 服务器，自动打开浏览器 |
| 每个工作线程的终端 + JSON 进度跟踪 |
| 长时间渲染的状态序列化 |
运行你自己的测试：
node examples/render-test.js --duration=5
node examples/render-test.js --duration=30
node examples/render-test.js --duration=60 --width=1080 --height=1920npm test一套零依赖的冒烟测试套件，涵盖模块导出、输入验证、仪表盘路径安全（遍历 + 空字节 + 双重编码向量）、检查点往返以及 MCP 服务器 stdio 握手。
ffmpeg-render-pro 包含一个带有 6 个工具的 Model Context Protocol (MCP) 服务器。可与 Claude Code、Claude Desktop 及任何 MCP 客户端配合使用。
# After `npm install -g ffmpeg-render-pro` the MCP binary is on your PATH:
claude mcp add --transport stdio ffmpeg-render-pro -- ffmpeg-render-pro-mcp
# Or without global install (uses npx):
claude mcp add --transport stdio ffmpeg-render-pro -- npx --yes --package=ffmpeg-render-pro ffmpeg-render-pro-mcp添加到你的 claude_desktop_config.json：
{
"mcpServers": {
"ffmpeg-render-pro": {
"command": "ffmpeg-render-pro-mcp"
}
}
}或者，如果你不想全局安装：
{
"mcpServers": {
"ffmpeg-render-pro": {
"command": "npx",
"args": ["--yes", "--package=ffmpeg-render-pro", "ffmpeg-render-pro-mcp"]
}
}
}工具 | 描述 |
| 探测硬件编码器 (NVENC, VideoToolbox, AMF, VA-API, QSV) |
| 显示 CPU 核心数、内存、推荐工作线程数、ffmpeg 版本 |
| 使用实时仪表盘进行并行渲染 |
| 应用预设（黑色电影、暖色、冷色、电影感、复古）或自定义滤镜 |
| 结合视频和音频并进行响度标准化 |
| 流拷贝拼接多个视频（即时完成，无需重新编码） |
此仓库包含一个即用型的 Claude Code 技能。要安装它，请将 skill 文件夹复制到你的 Claude 技能目录中：
# macOS / Linux
cp -r .claude/skills/ffmpeg-render-pipeline ~/.claude/skills/
# Windows
xcopy .claude\skills\ffmpeg-render-pipeline %USERPROFILE%\.claude\skills\ffmpeg-render-pipeline\ /E /I安装后，当你要求 Claude Code 使用 ffmpeg 渲染视频或音频时，它会自动使用该技能。
仪表盘服务器仅绑定到 127.0.0.1。 网络上的其他机器无法访问。
无遥测、无回传、无 CDN 加载。 仪表盘完全使用系统字体从本地文件运行。
MCP 服务器是本地文件系统工具。 当连接到 AI 代理时，它将在当前用户有权访问的任何位置渲染、读取和写入文件。请像对待任何其他启用文件系统的工具一样对待它：仅在受信任的代理下运行，如果你在不受信任的提示词中使用它，请考虑限制进程的工作目录。
流拷贝拼接使用 os.tmpdir() 下的临时文件。 你传递的输出路径将按原样写入——请确保你的输出路径是你想要的位置。
查看 CHANGELOG.md 获取发布说明。最新版本：v1.2.0 — 加固更新（关键仪表盘修复、路径遍历防御、性能改进）。
MIT
Apply a color grade to a video file and write the result to a new file. Provide either a built-in preset (noir, warm, cool, cinematic, vintage) or a custom ffmpeg -vf filter string (filter overrides preset). Re-encodes the video stream with the chosen codec; audio is stripped unless keep_audio is true. Prerequisite: ffmpeg installed. Side effect: overwrites output_path if it already exists.
| Name | Required | Description | Default |
|---|---|---|---|
| crf | No | CRF/CQ quality, 0-51. Lower is higher quality. Default 18. | |
| codec | No | Video encoder for the output. Default libx264. | libx264 |
| filter | No | Custom ffmpeg -vf filter string. Overrides preset when both are given. | |
| preset | No | Built-in color grade preset | |
| input_path | Yes | Input video file path. Must exist. | |
| keep_audio | No | Stream-copy the input audio track instead of stripping it. Default false (audio stripped). | |
| output_path | Yes | Output video file path. Overwritten if it already exists. |
| Name | Required | Description |
|---|---|---|
| crf | Yes | CRF/CQ quality value applied |
| codec | Yes | Encoder used for the output |
| filter | Yes | Custom filter applied, or null when a preset was used |
| preset | Yes | Preset applied, or null when a custom filter was used |
| audioKept | Yes | True when the input audio track was stream-copied into the output |
| inputPath | Yes | Absolute input file path |
| outputPath | Yes | Absolute output file path |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description openly discloses the destructive side effect of overwriting output_path, re-encoding behavior, and the default stripping of audio, all consistent with the destructiveHint annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single well-organized paragraph covering purpose, modes, processing behavior, prerequisite, and side effect without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
It includes the required prerequisite (ffmpeg installed) and the key side effect (overwrite), making the tool's behavior fully understandable even without inspecting the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already documents all seven parameters with descriptions, and the description adds context about re-encoding and the relationship between preset and filter beyond the schema fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool applies a color grade to a video file and writes the result to a new file, which is specific and distinguishes it from rendering, merging, or concatenating videos.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains how to choose between a preset and a custom filter, and clarifies the audio handling behavior. It does not explicitly contrast with sibling tools, but the intent is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Join multiple video files into one with stream copy: no re-encoding, completes in seconds regardless of file size. All inputs must share the same codec, resolution, framerate, and pixel format. By default each input is probed with ffprobe and mismatches are rejected before ffmpeg runs, because ffmpeg itself accepts mismatched inputs and writes a silently corrupt file; set validate false to skip the probes for inputs known to be uniform. Prerequisite: ffmpeg installed. Side effect: overwrites output_path if it already exists.
| Name | Required | Description | Default |
|---|---|---|---|
| validate | No | Probe every input with ffprobe and reject codec/resolution/framerate/pixel-format mismatches before concatenating. Default true. Skipped with a warning when ffprobe is not installed. | |
| input_files | Yes | Video file paths to concatenate, in playback order. All must exist. | |
| output_path | Yes | Output file path. Overwritten if it already exists. |
| Name | Required | Description |
|---|---|---|
| segments | Yes | Absolute paths of the concatenated inputs, in order |
| validated | Yes | True when segment compatibility validation was requested |
| outputPath | Yes | Absolute output file path |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly discloses the destructive side effect of overwriting output_path, aligning with the destructiveHint annotation. It also explains the validation behavior with ffprobe, the rejection of mismatched inputs, and the skip behavior when validate is false, giving a clear picture of execution behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is slightly long but well-structured with clear sections for purpose, constraints, validation, prerequisite, and side effect. The explanatory clause about why validation is needed is verbose but adds important rationale for the default behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides all necessary operational context: the lossless nature of the operation, input constraints, validation defaults, prerequisite software, and destructive side effects. This is sufficient for an agent to correctly invoke the tool without needing external documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers parameter descriptions at 100%, but the tool description adds meaningful context: it explains the impact of the validate flag, restates that input files must be in playback order, and confirms that output_path is overwritten. This goes beyond the schema without being redundant.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: joining multiple video files into one using stream copy with no re-encoding. It immediately distinguishes this from a rendering or transcoding operation, making the tool's role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains when to use the tool (concatenation with matching codecs/parameters) and when to set validate to false for known-uniform inputs. It does not explicitly compare against sibling tools like render_video, but the 'no re-encoding' phrasing strongly implies the appropriate use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detect the best available hardware video encoder on this machine. Probes NVENC, VideoToolbox, AMF, VA-API, and QSV with a 1-frame validation encode and falls back to CPU (libx264) when no GPU encoder works. Use before rendering or grading to confirm hardware acceleration. Results are cached for 7 days in ~/.ffmpeg-render-pro/gpu-cache.json. Requires ffmpeg on PATH or FFMPEG_RENDER_PRO_FFMPEG.
| Name | Required | Description | Default |
|---|---|---|---|
| force_mode | No | auto probes hardware then falls back to CPU (default). cpu skips probing and always returns libx264. gpu fails if no hardware encoder is found. | auto |
| Name | Required | Description |
|---|---|---|
| all | Yes | All validated encoders including the CPU fallback |
| h264 | Yes | Best available H.264 encoder name |
| hevc | Yes | Best available HEVC encoder name, or null |
| isGpu | Yes | True when a hardware encoder validated |
| label | Yes | Human-readable label of the selected encoder |
| ffmpegVersion | Yes | Detected ffmpeg version string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description states that results are 'cached for 7 days in ~/.ffmpeg-render-pro/gpu-cache.json', which involves writing to the filesystem. This contradicts the readOnlyHint annotation that indicates the tool has no side effects. This is a direct conflict between the behavior described and the annotated read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with four focused sentences that lead with the main purpose, then detail the probing behavior, the recommended usage, and the caching/requirements. No unnecessary words or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers key prerequisites (ffmpeg on PATH), the fallback behavior, and caching. The output schema is provided, though the description does not explicitly state what the output structure will be, but that information is available in the schema. Given the tool's simplicity, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, fully documenting the single force_mode parameter with its enum values and default. The description itself adds no extra context about the parameter beyond what is already in the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'Detect the best available hardware video encoder on this machine', identifying both the action (detect) and the resource (best hardware video encoder) while scoping it to the current machine. It distinguishes itself from sibling tools like render_video or system_info by focusing on encoder detection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises when to use the tool: 'Use before rendering or grading to confirm hardware acceleration.' This provides clear timing guidance and implies that it should be used before other rendering/grading operations, making the usage context unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the worker script contract required by render_video, plus the full source of the bundled starter worker (a small file where only renderFrame() needs editing) and the path of the larger reference worker. Use this before authoring a custom worker: copy starterSource to a new file, replace renderFrame(), and pass that file as worker_script. Either templatePath (test scene) or starterPath (gradient) can be passed directly as render_video's worker_script to render without writing code. Read-only: returns documentation and source text, touches nothing.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| messages | Yes | Messages the worker must post to parentPort, their fields, and when to send them |
| workerData | Yes | Fields injected into the worker via worker_threads workerData, mapped to their meaning |
| starterPath | Yes | Absolute path of the bundled starter worker (edit renderFrame only); usable directly as render_video worker_script |
| templatePath | Yes | Absolute path of the bundled reference worker (particle test scene); usable directly as render_video worker_script |
| starterSource | Yes | Full source code of the starter worker; copy it, replace renderFrame(), save as your worker_script |
| templateSource | Yes | Full source code of the bundled reference worker |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
States 'Read-only: returns documentation and source text, touches nothing.' This aligns with readOnlyHint and adds explicit assurance of no side effects. The description also clarifies it returns documentation and source, so no destructive actions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet comprehensive, covering all necessary details in a few sentences without redundancy. Each sentence contributes to understanding the tool's function, usage, and output.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description lists the key returned items (contract, starter source, reference path) and mentions templatePath and starterPath, providing a clear picture of the output. It also places the tool in context with render_video, making it complete for the intended use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema is empty, so no parameter description is needed. The baseline score for zero parameters is 4, and the description adds no parameter-specific info, which is acceptable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets the worker script contract, starter source, and reference path, specifically for render_video. It distinguishes from siblings by focusing on template retrieval rather than rendering or system info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs to use before authoring a custom worker, with steps to copy, replace renderFrame, and pass as worker_script. Also notes that templatePath or starterPath can be passed directly to render_video, providing alternatives. This gives clear when-to-use and how-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Combine a video file and an audio file into one output file. The video stream is copied without re-encoding; audio is encoded to AAC at the given bitrate. Loops audio shorter than the video when loop is true, and can apply loudness normalization (ffmpeg loudnorm) for YouTube-style targets. Prerequisite: ffmpeg installed. Side effect: overwrites output_path if it already exists.
| Name | Required | Description | Default |
|---|---|---|---|
| loop | No | Loop the audio if it is shorter than the video. Default true. | |
| bitrate | No | Audio bitrate in kbps, 8-1024. Default 320. | |
| normalize | No | Apply loudness normalization (loudnorm I=-22 TP=-2 LRA=7). Default false. | |
| audio_path | Yes | Input audio file path. Must exist. | |
| video_path | Yes | Input video file path. Must exist. | |
| output_path | Yes | Output file path. Overwritten if it already exists. |
| Name | Required | Description |
|---|---|---|
| looped | Yes | True when audio looping was enabled |
| audioPath | Yes | Absolute input audio path |
| videoPath | Yes | Absolute input video path |
| normalized | Yes | True when loudness normalization was applied |
| outputPath | Yes | Absolute output file path |
| bitrateKbps | Yes | Audio bitrate applied, in kbps |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the destructiveHint annotation, the description explicitly states the side effect of overwriting the output path, plus details on stream copying, audio encoding, looping, and normalization. It also notes the ffmpeg prerequisite, providing full behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, with the main purpose stated first and all key behaviors summarized in a few sentences. No irrelevant details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential behaviors: input merging, stream handling, side effects, prerequisites, and optional flags. Given that an output schema exists, return value details need not be included. The description is complete for an agent to decide and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers all parameters with clear descriptions (100% coverage). The description adds minor context (e.g., AAC encoding and looping behavior) but largely overlaps with the schema, so no significant additional meaning is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool combines a video and audio file into an output, with specific verbs and resources. This distinguishes it from sibling tools like render_video or concat_videos.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does but does not explicitly give when to use it versus alternatives or when not to use it. It mentions conditions like looping and normalization but no comparative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render a video by running a frame-generating worker script across parallel worker threads. Splits the frame range across N workers, encodes one MP4 segment per worker, then joins segments with stream copy. Prerequisites: ffmpeg installed, plus a worker script implementing the ffmpeg-render-pro worker contract; call get_worker_template first if you need to author a worker, or use its templatePath for a ready-made test scene. Side effects: overwrites output_path if it already exists and writes dashboard files under /preview. Long renders emit MCP progress notifications when the client supplies a progressToken (enable resetTimeoutOnProgress for renders longer than the client request timeout; per-frame progress detail requires dashboard true, the default). Client cancellation stops all workers and removes temp files. Note: this tool defaults to 30 fps; the CLI defaults to 60.
| Name | Required | Description | Default |
|---|---|---|---|
| fps | No | Framerate in frames per second, 1-240. Default 30 for this tool (CLI default is 60). | |
| seed | No | RNG seed passed to workers for deterministic output. Default 42. | |
| title | No | Title shown in the dashboard. Default "Render". | Render |
| width | No | Frame width in pixels. Must be even (yuv420p). Default 1920, max 7680. | |
| height | No | Frame height in pixels. Must be even (yuv420p). Default 1080, max 4320. | |
| workers | No | Exact worker thread count, overriding auto-detection. Omit to auto-detect from CPU/RAM. | |
| duration | Yes | Video duration in seconds. Required. | |
| auto_open | No | Open the dashboard in a browser. Default true; set false for headless or server use. | |
| dashboard | No | Serve the live HTML progress dashboard and write preview JSON files. Default true. | |
| linger_ms | No | How long the dashboard stays up after completion, in milliseconds. Default 30000; 0 stops it immediately. | |
| max_workers | No | Cap for the auto-detected worker count. Ignored when workers is set. Default 8. | |
| output_path | Yes | Output video file path. Overwritten if it already exists. | |
| worker_script | Yes | Absolute path to the worker .js file that generates frames. Must implement the contract returned by get_worker_template. | |
| dashboard_port | No | Dashboard starting port, 1-65535. Default 8080; increments if occupied. |
| Name | Required | Description |
|---|---|---|
| avgFps | Yes | Average frames encoded per second across the whole render |
| outputPath | Yes | Absolute path of the rendered video file |
| totalFrames | Yes | Total frames rendered |
| elapsedSeconds | Yes | Wall-clock render time in seconds |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true, but the description goes far beyond: it spells out that output_path is overwritten, that dashboard files are written, that progress notifications depend on a progressToken and resetTimeoutOnProgress, that cancellation stops workers and removes temp files, and it discloses the fps default discrepancy. This is rich behavioral context with no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but well-organized: it opens with the core action, then prerequisites, side effects, progress behavior, cancellation, and a final note on fps defaults. Every sentence contributes new information and the structure is logical. It is slightly long but not bloated; a 4 reflects its efficiency and front-loaded action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 14 parameters, an output schema, and multiple behavioral nuances (destructive, progress, cancellation, dashboard), the description covers all essential usage aspects: prerequisites, side effects, progress token handling, cancellation semantics, and the CLI difference. The output schema handles return values, so nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents every parameter (including defaults, ranges, and even the CLI fps difference for the fps param). The description itself adds little parameter-specific meaning; it references the worker contract and prerequisites but does not elaborate on individual params. Baseline 3 is appropriate since the schema carries the burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb-resource pair ('Render a video') and the precise mechanism ('running a frame-generating worker script across parallel worker threads'), which clearly distinguishes it from siblings like concat_videos or color_grade. It also mentions the segmentation approach (one MP4 per worker, then stream copy) so an agent understands the exact operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: prerequisites (ffmpeg, worker contract), when to call get_worker_template first, and side effects. It notes a key distinction from the CLI (fps defaults) but doesn't explicitly state 'use this instead of X' for sibling tools. The guidance is sufficient for correct invocation though not exhaustive about alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get render system capabilities: CPU cores, total and free RAM, the recommended parallel worker count for a target resolution, detected GPU encoder, segment and final codecs, and ffmpeg version. Use before render_video to choose a worker count or check whether this machine can handle a resolution. Requires ffmpeg on PATH or FFMPEG_RENDER_PRO_FFMPEG.
| Name | Required | Description | Default |
|---|---|---|---|
| width | No | Target render width in pixels for the worker recommendation. Default 1920, max 7680. | |
| height | No | Target render height in pixels for the worker recommendation. Default 1080, max 4320. |
| Name | Required | Description |
|---|---|---|
| arch | Yes | CPU architecture |
| tier | Yes | Resolution tier used for the recommendation (480p to 4k) |
| isGpu | Yes | True when a hardware encoder is available |
| workers | Yes | Recommended parallel worker count for the target resolution |
| cpuCores | Yes | Logical CPU core count |
| gpuLabel | Yes | Label of the detected GPU encoder or CPU fallback |
| platform | Yes | Node platform string (win32, linux, darwin) |
| freeRamMB | Yes | Free RAM in MB |
| finalCodec | Yes | Codec used for final single-file passes |
| totalRamMB | Yes | Total RAM in MB |
| segmentCodec | Yes | Codec used for parallel segment encoding |
| ffmpegVersion | Yes | Detected ffmpeg version string |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds meaningful context beyond that: it requires ffmpeg on PATH or via FFMPEG_RENDER_PRO_FFMPEG. It also discloses that the tool reports a recommended worker count for a target resolution, which helps agents understand the dependency on input parameters. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences deliver the full purpose and usage context, followed by a necessary prerequisite. The most actionable information is front-loaded, and every sentence earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the read-only annotation, the output schema, and fully described optional parameters, the description covers what the tool returns, when to call it, and the critical ffmpeg prerequisite. An agent has enough information to decide whether and how to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with width and height each documented with defaults and ranges. The description adds only a general reference to 'target resolution,' which is already implied by the schema's 'worker recommendation' phrasing. The schema carries the parameter-meaning burden, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource — 'Get render system capabilities' — and enumerates the exact data returned: CPU cores, RAM, worker count, GPU encoder, codecs, and ffmpeg version. It distinguishes itself from the render_video sibling by framing this as a pre-render query rather than a rendering operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use it: 'Use before render_video to choose a worker count or check whether this machine can handle a resolution.' It does not explicitly discuss when not to use it or name alternatives such as detect_gpu, but the primary use case is clearly communicated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.5.2color_gradeconcat_videosdetect_gpuget_worker_templatemerge_audiorender_videosystem_infoScored across 7 tools
Most tools have clearly distinct roles, but detect_gpu and system_info overlap significantly since system_info already reports the detected GPU encoder; the separate detect_gpu tool may create ambiguity about which to call.
Six of seven tools follow a clear verb_noun pattern (detect_gpu, render_video, get_worker_template, color_grade, merge_audio, concat_videos), but system_info is a noun phrase and breaks the otherwise consistent convention.
Seven tools is a well-scoped set for an ffmpeg rendering server: capability checks, the core render operation, a worker template helper, and three common post-processing operations. No redundant or excessive tools.
The surface covers the main render workflow and common edits like color grading, audio merging, and concatenation. It lacks utilities such as trimming, format conversion, or media probing, but those are arguably outside the render-focused purpose.
MCP server for Google Veo AI video generation
MCP server for Wan AI video generation
MCP server for Clipkit — gives AI agents a video toolbox via the Clipkit schema.
MCP server for Luma Dream Machine AI video generation
