ffmpeg-render-pro

ffmpeg-render-pro

通过代码并行渲染视频。你只需编写一个绘制帧的函数；ffmpeg-render-pro 会将帧范围分配给多个工作线程，每个线程编码一个 MP4 片段，再通过流复制拼接片段（无需重新编码），并在运行期间于浏览器中显示实时仪表板。它还可以检测 GPU 编码器、调整色彩、合并音频，并以 CLI、Node 库、面向 AI Agent 的 MCP 服务和 Claude Code 技能的形式提供。

由 Beeswax Pat 构建。免费且开源。

从这里开始

只需三条命令。你需要 Node.js 18 或更高版本，以及已加入 PATH 的 ffmpeg。

# 1. Prove the setup works: a 5 second test render. The dashboard opens in your browser.
npx ffmpeg-render-pro benchmark

# 2. Write a starter worker script into the current folder.
npx ffmpeg-render-pro init my-worker.js

# 3. Render it. Output lands in output.mp4.
npx ffmpeg-render-pro render my-worker.js --duration=5

打开 my-worker.js。你唯一需要修改的函数是 renderFrame(frameNum, buffer)：将像素填入缓冲区（B、G、R、A，逐行排列），其他一切都已就绪。使用该函数接收的 seed 推导所有随机值，这样并行输出就能与顺序渲染完全一致。

如果不想输入 npx，可以全局安装：

npm install -g ffmpeg-render-pro

使用未加入 PATH 的 ffmpeg

FFMPEG_RENDER_PRO_FFMPEG=/opt/ffmpeg/bin/ffmpeg     # ffmpeg binary
FFMPEG_RENDER_PRO_FFPROBE=/opt/ffmpeg/bin/ffprobe   # optional; the sibling ffprobe is found automatically
FFMPEG_RENDER_PRO_CACHE_DIR=~/.ffmpeg-render-pro    # optional; where GPU probe results are cached

这些变量会在调用时读取，因此 MCP 服务等长期运行的进程无需重启即可获取变更。

CLI

ffmpeg-render-pro init [my-worker.js]   # write the starter worker (--force overwrites)
ffmpeg-render-pro benchmark             # 5 second test render with the bundled worker
ffmpeg-render-pro render <worker.js>    # render with your worker
ffmpeg-render-pro info                  # cores, RAM, recommended workers, ffmpeg version, GPU
ffmpeg-render-pro detect-gpu            # probe hardware encoders (--cpu / --gpu force a mode)
ffmpeg-render-pro version

渲染和基准测试标志：--width=1920 --height=1080（必须为偶数）、--fps=60、--duration=60（允许小数）、--output=out.mp4、--workers=N、--max-workers=8、--seed=42、--title="..."、--crf=20（0-51，数值越低，质量越高）、--encoder-preset=fast（任意 x264 预设）。仪表板标志：--no-dashboard、--no-open、--port=8080、--linger-ms=30000（0 表示渲染完成后立即退出）。不带参数运行 ffmpeg-render-pro 可查看完整列表。

遇到未知标志时会发出警告并继续运行。无法解析的值（例如 --fps=abc）会导致程序以状态码 1 退出，而不会使用默认值进行渲染。

已安装的可执行文件：ffmpeg-render-pro（此 CLI）和 ffmpeg-render-pro-mcp（MCP 服务）。旧名称 ffmpeg-render-mcp 仍然可用，因此现有 MCP 配置不会失效。

渲染流程

1. renderParallel 会检查 ffmpeg、验证分辨率，并根据 CPU 核心数和 RAM 选择工作线程数量（工作线程数不会超过帧数）。
2. 它会在 127.0.0.1 上启动仪表板服务并打开浏览器。
3. 每个工作线程会在 workerData 中获取帧范围并运行你的脚本，将原始 BGRA 帧传入各自的 ffmpeg 进程，并写入一个 MP4 片段。
4. 片段会通过 concat demuxer 和 -c copy 拼接，无论视频多长都只需数秒。
5. 临时文件会被删除。若某个工作线程失败，其负责的范围会重试一次，然后渲染才会失败。

你的 worker

worker 是在 worker_threads 线程中运行的 Node 脚本。init 会提供一个只需编辑 renderFrame 的 worker；已安装包中的 examples/basic-worker.js 是一个更完整的参考示例，包含粒子系统和带种子的随机数生成器。

渲染器通过 workerData 注入的字段：

字段	含义
width、height、fps	帧尺寸和帧率
seed	所有随机值都由此派生
startFrame、endFrame	精确渲染 [startFrame, endFrame)
segmentPath	将此 worker 的 MP4 写入此路径
workerId	在你发送的每条消息中都包含此字段
totalFrames、duration	整个视频的总量，用于进度条等全局效果
renderParallel({ workerData }) 中的任何内容	你自己的额外键（捆绑的 worker 会处理 codecArgs）

worker 通过 parentPort.postMessage 发送的消息：

消息	时机	字段
{ type: 'progress' }	定期	workerId、pct、fps、frame、eta
{ type: 'fast-forward-start' }	可选，在重放状态以到达 startFrame 之前	workerId、frames
{ type: 'done' }	分段完全写入后发送一次	workerId
{ type: 'error' }	发生故障时，之后不会再发送 done	workerId、error

所有 worker 必须使用相同的编解码器、分辨率、帧率和像素格式进行编码，因为这些分段会通过流复制合并。

库

const {
  renderParallel,       // the render engine
  createEncoder,        // pipe raw frames into ffmpeg with backpressure
  detectGPU,            // hardware encoder discovery, cached 7 days
  getConfig,            // worker count and codec choice for a resolution
  computeTotalFrames,   // float-safe fps x duration
  concatSegments,       // stream-copy join (validates inputs by default)
  colorGrade,           // presets or a custom -vf chain
  mergeAudio,           // add a soundtrack without re-encoding video
  startDashboard,       // the local progress server
  ProgressTracker,      // per-worker progress plus dashboard JSON
  saveCheckpoint, loadCheckpoint, restoreCheckpoint, generateCheckpoints,
  getEncoderIO,         // encoder recipe as { inputArgs, filter, outputArgs }
  getCodecArgs,         // the same recipe as one flat array
  ffmpegBin, ffprobeBin // resolved binaries, env-var aware
} = require('ffmpeg-render-pro');

renderParallel(options)

const controller = new AbortController();

const result = await renderParallel({
  workerScript: './my-worker.js',   // required
  outputPath: './output.mp4',       // required
  width: 1920, height: 1080,        // even numbers, up to 7680x4320
  fps: 60, duration: 60,
  seed: 42,
  title: 'My Render',               // shown in the dashboard
  workerCount: undefined,           // exact count; omit to auto-detect
  maxWorkers: 8,                    // cap for auto-detect
  dashboard: true, autoOpen: true, dashboardPort: 8080,
  dashboardLingerMs: 0,             // 0 resolves as soon as the render ends (the CLI keeps it up 30s)
  quiet: false,                     // true keeps stdout byte-clean; status goes to stderr
  signal: controller.signal,        // abort() stops workers and removes temp files
  workerData: {},                   // extra keys for your worker
});
// result: { outputPath, elapsed, totalFrames, avgFps }

中止操作会以 name 为 'AbortError' 的错误拒绝。在库中使用时，将 dashboardLingerMs 设为 0，这样调用返回时进程不会继续保持运行。设置 FFMPEG_RENDER_PRO_DEBUG=1，可在 CLI 中获取完整堆栈跟踪。

后期处理

// Color grade with a preset (noir, warm, cool, cinematic, vintage) or a custom -vf chain
await colorGrade({ inputPath: 'raw.mp4', outputPath: 'graded.mp4', preset: 'cinematic' });
await colorGrade({ inputPath: 'raw.mp4', outputPath: 'graded.mp4', filter: 'eq=contrast=1.08:saturation=0.9', crf: 18 });
await colorGrade({ inputPath: 'final.mp4', outputPath: 'graded.mp4', preset: 'noir', keepAudio: true }); // default strips audio

// Merge audio: video is stream-copied, audio becomes AAC. loop and normalize (loudnorm) are optional.
await mergeAudio({ videoPath: 'graded.mp4', audioPath: 'track.mp3', outputPath: 'final.mp4', bitrate: 320, loop: true, normalize: true });

// Join same-codec, same-size videos with stream copy. Inputs are probed with ffprobe first; pass { validate: false } to skip.
await concatSegments(['part-000.mp4', 'part-001.mp4'], 'joined.mp4');

colorGrade 接受 codec 中的任意编码器名称；需要专属滤镜的编码器（VA-API）会自动将其合并到调色链中。

长时间渲染的检查点

对于持续数小时的渲染，每隔 N 帧将模拟状态快照一次，这样每个 worker 只需从最近的快照开始重放帧，而不必从第 0 帧开始。

generateCheckpoints({ systems, totalFrames: 432000, fps: 60, checkpointDir: './.checkpoints', interval: 60000 });

// inside a worker
const cp = loadCheckpoint('./.checkpoints', startFrame);
if (cp) {
  const resumeFrame = restoreCheckpoint(cp, systems);
  // fast-forward from resumeFrame to startFrame, then render
}

systems 是一个由具名模块组成的对象，这些模块具有 getState()、setState() 和 update(dt)。标记为帧 F 的检查点恰好包含 F 次更新。_frame 和 _timestamp 是保留键。

MCP 服务（适用于 AI Agent）

通过 stdio 提供七个工具，可在 Claude Code、Claude Desktop 或任何 MCP 客户端中使用。

# Claude Code, no install needed
claude mcp add --transport stdio ffmpeg-render-pro -- npx --yes --package=ffmpeg-render-pro ffmpeg-render-pro-mcp

# Claude Code, after npm install -g ffmpeg-render-pro
claude mcp add --transport stdio ffmpeg-render-pro -- ffmpeg-render-pro-mcp

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "ffmpeg-render-pro": {
      "command": "npx",
      "args": ["--yes", "--package=ffmpeg-render-pro", "ffmpeg-render-pro-mcp"]
    }
  }
}

工具	功能
get_worker_template	返回 worker 合约、worker 起始源码，以及两个内置 worker 的路径。从这里开始。
render_video	根据 worker 脚本并行渲染，支持进度通知和取消
detect_gpu	探测硬件编码器（NVENC、VideoToolbox、AMF、VA-API、QSV）
system_info	核心数、RAM、建议的 worker 数量、ffmpeg 版本
color_grade	使用预设或自定义滤镜
merge_audio	添加配乐，视频流直接复制
concat_videos	通过流复制拼接视频，默认验证输入

Agent 的操作步骤：调用 get_worker_template，将 starterSource 复制到文件并替换 renderFrame，然后调用 render_video，将该文件作为 worker_script（无头运行时设置 dashboard: false、auto_open: false）。若不编写代码即可渲染，请将返回的 starterPath 或 templatePath 直接传给 render_video。之后使用 color_grade、merge_audio 和 concat_videos 进行后期处理。

每个工具都声明了 outputSchema 并返回 structuredContent，因此应解析 JSON，而非文本。写入器会覆盖 output_path。render_video 默认使用 30 fps（CLI 默认使用 60），当客户端发送 progressToken 时，每 2 秒发送一次 notifications/progress（长时间渲染时请启用 resetTimeoutOnProgress），并在客户端取消时停止所有 worker。stdout 仅承载 JSON-RPC 帧。若缺少 ffmpeg，将返回错误，并附上安装页面和环境变量的名称。

压缩包还在软件包根目录中附带了 llms.txt 和一个 Claude Code 技能：

# from a global install (macOS / Linux)
cp -r "$(npm root -g)/ffmpeg-render-pro/.claude/skills/ffmpeg-render-pipeline" ~/.claude/skills/
# from a repo clone (Windows)
xcopy .claude\skills\ffmpeg-render-pipeline %USERPROFILE%\.claude\skills\ffmpeg-render-pipeline\ /E /I

NVENC 速查

渲染器会自行检测 NVENC。若要在渲染器之外进行单次编码：

# confirm the encoder exists before relying on it
ffmpeg -y -f lavfi -i testsrc=size=256x256:rate=30:d=1 -c:v h264_nvenc -cq 23 probe.mp4

# encode: presets p1 (fastest) to p7 (best); -cq works like CRF, lower is better
ffmpeg -i in.mp4 -c:v h264_nvenc -preset p5 -cq 21 -pix_fmt yuv420p -c:a aac -b:a 192k -movflags +faststart out.mp4

h264_nvenc 无法处理过窄的画面（Turing 显卡上的最小宽度为 145 px），会生成零字节文件并退出，因此探测时请使用 256x256。两个命令都来自 ffmpeg Render Cookbook（$12）：共 29 个示例，每个都在发布前通过 ffmpeg 8.0.1 运行。

安全说明

• GitHub Actions 通过 npm 可信发布（OIDC）将版本发布到 npm。没有发布令牌；从 1.5.2 版开始，每个版本都带有来源证明，用于将 npm 上的压缩包关联到构建它的确切提交和工作流运行（请参阅 npm 页面上的 Provenance 面板）。
• 仪表盘仅绑定到 127.0.0.1，不会从网络加载任何内容。无遥测。
• render_video 和 renderParallel 会以当前用户的权限执行指定的 worker 脚本。仅运行你编写或信任的 worker。
• MCP 服务可以在当前用户有权限的任何位置读写文件。请与可信的 Agent 一起运行，并考虑在提示词不可信时限制其工作目录。
• 自定义 filter 字符串会涉及文件访问：movie= 和 subtitles= 等 ffmpeg 滤镜会读取本地文件。请像处理文件路径一样谨慎处理滤镜输入。
• Concat 列表文件会写入 os.tmpdir()；输出路径则会按指定位置写入。

测试

npm test 会运行 12 个零依赖测试套件（255 项检查）：单元测试、冒烟测试、通过 stdio 进行的真实 MCP 会话（包含 stdout 字节审计），以及使用 ffprobe 和 framemd5 验证的端到端渲染。在没有 ffmpeg 的计算机上，会正常跳过渲染测试套件。CI 会在 Ubuntu、Windows 和 macOS 上，针对 Node 18、20、22 和 24 运行同样的测试。

更新日志和许可证

参见 CHANGELOG.md。MIT。