╔══════════════════════════════════════════════════════╗
║ ║
║ ████████ ████████ ██ ██ ██████ ████████ ████ ║
║ ██ ██ ███ ███ ██ ██ ██ ██ ║
║ ██████ ██████ ██ ██ ██ ██████ ██████ ██ ██ ║
║ ██ ██ ██ ██ ██ ██ ██ ██ ║
║ ██ ██ ██ ██ ██ ████████ ████ ║
║ ║
║ ██████ ████████ ██ ██ ██████ ████████ ██████ ║
║ ██ ██ ██ ███ ██ ██ ██ ██ ██ ██ ║
║ ██████ ██████ ██ ██ ██ ██ ██ ██████ ██████ ║
║ ██ ██ ██ ██ ████ ██ ██ ██ ██ ██ ║
║ ██ ██ ████████ ██ ██ ██████ ████████ ██ ██ ║
║ ║
║ ██████ ██████ ████ ║
║ ██ ██ ██ ██ ██ ██ ║
║ ██████ ██████ ██ ██ ║
║ ██ ██ ██ ██ ██ ║
║ ██ ██ ██ ████ ║
║ ║
║ ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓░░░░░░░░░░ 8 WRKRS ║
║ GPU: AUTO DASHBOARD: LIVE CONCAT: INSTANT ║
╚══════════════════════════════════════════════════════╝
Renderizado de vídeo en paralelo con panel de control en vivo, autodetección de GPU, sistema de puntos de control y concatenación mediante copia de flujo. El kit de herramientas de renderizado ffmpeg gratuito más potente.
Creado por Beeswax Pat con Claude Code · Libre y de código abierto para siempre
Renderizado en paralelo — Divide los fotogramas entre N hilos de trabajo, concatena sin necesidad de volver a codificar
Autodetección de GPU — Analiza NVENC, VideoToolbox, AMF, VA-API, QSV con validación de 1 fotograma
Panel de control en vivo — Se abre automáticamente en tu navegador con progreso por trabajador, gráfico de FPS y tiempo estimado (ETA)
Sistema de puntos de control — Reducción del 93% en la sobrecarga de avance rápido para renderizados largos
Corrección de color — 5 ajustes preestablecidos integrados (noir, cálido, frío, cinematográfico, vintage) + filtros personalizados
Fusión de audio — Combina vídeo + audio con normalización de sonoridad, sin volver a codificar el vídeo
Salida determinista — El generador de números aleatorios con semilla garantiza que los trabajadores paralelos produzcan resultados idénticos a los secuenciales
Servidor MCP — Servidor del Protocolo de Contexto de Modelo con 6 herramientas, funciona con Claude Code, Claude Desktop y cualquier cliente MCP
Multiplataforma — Windows, macOS, Linux. Cualquier GPU o solo CPU. Requiere Node.js >= 18 + ffmpeg.
Related MCP server: ffmpeg-mcp
Node.js >= 18
ffmpeg instalado y en el 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');El punto de entrada principal. Divide un renderizado entre trabajadores, muestra un panel de control en vivo y produce un MP4 final.
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
});Los trabajadores reciben rangos de fotogramas a través de workerData y envían fotogramas BGRA sin procesar a 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 }));Consulta examples/basic-worker.js para ver un ejemplo de trabajo completo.
Módulo | Propósito |
| Grupo de hilos de N trabajadores con seguimiento de progreso |
| Canalización de fotogramas sin procesar a ffmpeg con contrapresión |
| Descubrimiento + validación de codificador de hardware multiplataforma |
| Ajuste automático de trabajadores basado en resolución, RAM, CPU |
| Unión de segmentos mediante copia de flujo (instantánea) |
| Ajustes preestablecidos de filtros de vídeo de ffmpeg + cadenas personalizadas |
| Fusión de vídeo + audio con soporte para loudnorm |
| Servidor HTTP sin dependencias con apertura automática del navegador |
| Seguimiento de progreso por trabajador en terminal + JSON |
| Serialización de estado para renderizados largos |
Ejecuta los tuyos:
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 testUn conjunto de pruebas de humo sin dependencias que cubre exportaciones de módulos, validación de entrada, seguridad de ruta del panel de control (vectores de recorrido + byte nulo + doble codificación), ida y vuelta de puntos de control y protocolo de enlace stdio del servidor MCP.
ffmpeg-render-pro incluye un servidor del Protocolo de Contexto de Modelo (MCP) con 6 herramientas. Funciona con Claude Code, Claude Desktop y cualquier cliente 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-mcpAñádelo a tu claude_desktop_config.json:
{
"mcpServers": {
"ffmpeg-render-pro": {
"command": "ffmpeg-render-pro-mcp"
}
}
}O, si prefieres no instalarlo globalmente:
{
"mcpServers": {
"ffmpeg-render-pro": {
"command": "npx",
"args": ["--yes", "--package=ffmpeg-render-pro", "ffmpeg-render-pro-mcp"]
}
}
}Herramienta | Descripción |
| Analizar codificadores de hardware (NVENC, VideoToolbox, AMF, VA-API, QSV) |
| Mostrar núcleos de CPU, RAM, trabajadores recomendados, versión de ffmpeg |
| Renderizado en paralelo con panel de control en vivo |
| Aplicar ajustes preestablecidos (noir, cálido, frío, cinematográfico, vintage) o filtros personalizados |
| Combinar vídeo + audio con normalización de sonoridad |
| Unir varios vídeos mediante copia de flujo (instantáneo, sin volver a codificar) |
Este repositorio incluye una habilidad lista para usar de Claude Code. Para instalarla, copia la carpeta de la habilidad en tu directorio de habilidades de 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 /IUna vez instalada, Claude Code utilizará automáticamente la habilidad cuando le pidas renderizar vídeo o audio con ffmpeg.
El servidor del panel de control se vincula solo a 127.0.0.1. Nunca es accesible desde otras máquinas en tu red.
Sin telemetría, sin llamadas a servidores externos, sin cargas de CDN. El panel de control se ejecuta completamente desde archivos locales utilizando fuentes del sistema.
El servidor MCP es una herramienta de sistema de archivos local. Cuando se conecta a un agente de IA, renderizará, leerá y escribirá archivos en cualquier lugar donde el usuario actual tenga acceso. Trátalo como cualquier otra herramienta habilitada para el sistema de archivos: ejecútalo solo con un agente de confianza y considera restringir el directorio de trabajo del proceso si lo usas con prompts no confiables.
La concatenación mediante copia de flujo utiliza archivos temporales en os.tmpdir(). Las rutas de salida que proporciones se escribirán tal cual; asegúrate de que tu ruta de salida sea donde deseas que esté.
Consulta CHANGELOG.md para ver las notas de la versión. Última: v1.2.0 — fase de endurecimiento (corrección crítica del panel de control, defensa contra recorrido de rutas, mejoras de rendimiento).
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
