╔══════════════════════════════════════════════════════╗
║ ║
║ ████████ ████████ ██ ██ ██████ ████████ ████ ║
║ ██ ██ ███ ███ ██ ██ ██ ██ ║
║ ██████ ██████ ██ ██ ██ ██████ ██████ ██ ██ ║
║ ██ ██ ██ ██ ██ ██ ██ ██ ║
║ ██ ██ ██ ██ ██ ████████ ████ ║
║ ║
║ ██████ ████████ ██ ██ ██████ ████████ ██████ ║
║ ██ ██ ██ ███ ██ ██ ██ ██ ██ ██ ║
║ ██████ ██████ ██ ██ ██ ██ ██ ██████ ██████ ║
║ ██ ██ ██ ██ ████ ██ ██ ██ ██ ██ ║
║ ██ ██ ████████ ██ ██ ██████ ████████ ██ ██ ║
║ ║
║ ██████ ██████ ████ ║
║ ██ ██ ██ ██ ██ ██ ║
║ ██████ ██████ ██ ██ ║
║ ██ ██ ██ ██ ██ ║
║ ██ ██ ██ ████ ║
║ ║
║ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░ 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가지 내장 프리셋(noir, warm, cool, cinematic, vintage) 및 사용자 정의 필터 지원
오디오 병합 — 비디오 재인코딩 없이 음량 정규화와 함께 비디오와 오디오 결합
결정론적 출력 — 시드 기반 난수 생성(RNG)을 통해 병렬 워커가 순차 처리와 동일한 결과를 생성하도록 보장
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로의 원시 프레임 파이프 |
| 크로스 플랫폼 하드웨어 인코더 탐색 및 검증 |
| 해상도, RAM, CPU에 따른 워커 자동 최적화 |
| 스트림 복사 방식의 세그먼트 결합 (즉시 처리) |
| ffmpeg 비디오 필터 프리셋 및 사용자 정의 체인 |
| loudnorm을 지원하는 비디오 및 오디오 병합 |
| 의존성 없는 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-mcpclaude_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 코어, RAM, 권장 워커 수, ffmpeg 버전 표시 |
| 실시간 대시보드를 통한 병렬 렌더링 |
| 프리셋(noir, warm, cool, cinematic, vintage) 또는 사용자 정의 필터 적용 |
| 음량 정규화를 포함한 비디오 및 오디오 결합 |
| 여러 비디오의 스트림 복사 방식 결합 (즉시 처리, 재인코딩 없음) |
이 저장소에는 즉시 사용 가능한 Claude Code 스킬이 포함되어 있습니다. 설치하려면 스킬 폴더를 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
