ffmpeg-render-pro

ffmpeg-render-pro

コードから動画を並列レンダリングできます。フレームを描画する関数を1つ記述すると、ffmpeg-render-proがフレーム範囲をワーカースレッドに分割し、各ワーカーでMP4セグメントを1つずつエンコードして、再エンコードせずにストリームコピーで結合します。実行中はブラウザーにライブダッシュボードが表示されます。また、GPUエンコーダーの検出、カラーグレーディング、音声の結合にも対応し、CLI、Nodeライブラリ、AIエージェント向けMCPサーバー、Claude Codeスキルとして提供されます。

Beeswax Patが開発しました。無料のオープンソースです。

まずはこちら

コマンドは3つです。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セグメントを1つ書き出します。
4. セグメントはconcatデマルチプレクサーと-c copyで結合されます。動画の長さにかかわらず、数秒で完了します。
5. 一時ファイルは削除されます。ワーカーが失敗した場合は、その範囲を1回再試行してからレンダリングを失敗として終了します。

ワーカー

ワーカーは、worker_threads スレッドで実行される Node スクリプトです。init では、renderFrame だけを編集すればよいワーカーが提供されます。インストール済みパッケージの examples/basic-worker.js には、パーティクルシステムとシード付き RNG を備えた、より大規模な参考例があります。

レンダラーが workerData 経由で注入するフィールド：

フィールド	意味
width、height、fps	フレームサイズとフレームレート
seed	すべての乱数値をここから導出します
startFrame、endFrame	[startFrame, endFrame) を正確にレンダリングします
segmentPath	このワーカーの MP4 をここに書き込みます
workerId	送信するすべてのメッセージに含めます
totalFrames、duration	動画全体の合計値です。プログレスバーなどの全体にわたるエフェクトに使います
renderParallel({ workerData }) 内の任意の値	独自の追加キーです（同梱ワーカーは codecArgs を使用します）

ワーカーが parentPort.postMessage で送信するメッセージ：

メッセージ	タイミング	フィールド
{ type: 'progress' }	定期的	workerId、pct、fps、frame、eta
{ type: 'fast-forward-start' }	任意。startFrame に到達するために状態を再生する前	workerId、frames
{ type: 'done' }	セグメントの書き込み完了後に1回	workerId
{ type: 'error' }	失敗時。以降に done が送信されることはありません	workerId、error

すべてのワーカーは、同じコーデック、解像度、フレームレート、ピクセル形式でエンコードする必要があります。セグメントはストリームコピーで結合されるためです。

ライブラリ

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' のエラーで reject されます。ライブラリで使用する場合は、プロセスを開いたままにせず呼び出しが戻るように、dashboardLingerMs: 0 を設定してください。CLI の完全なスタックトレースを表示するには、FFMPEG_RENDER_PRO_DEBUG=1 を設定します。

後処理

// 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 フレームごとにシミュレーションの状態を一度スナップショットに保存し、各ワーカーがフレーム 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 エージェント向け）

stdio 経由で使用できる 7 つのツールです。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	ワーカーの仕様、スターター用ワーカーソース、同梱されている 2 つのワーカーへのパスを返します。まずはこちらから始めてください。
render_video	ワーカースクリプトから並列レンダリングを行い、進行状況の通知とキャンセルに対応します
detect_gpu	ハードウェアエンコーダー（NVENC、VideoToolbox、AMF、VA-API、QSV）を検出します
system_info	コア数、RAM、推奨ワーカー数、ffmpeg のバージョンを返します
color_grade	プリセットまたはカスタムフィルターを適用します
merge_audio	サウンドトラックを追加し、動画ストリームはコピーします
concat_videos	ストリームコピーで動画を連結します。入力はデフォルトで検証されます

エージェントでの手順：get_worker_template を呼び出し、starterSource をファイルにコピーして renderFrame を置き換えた後、そのファイルを worker_script として render_video を呼び出します（ヘッドレス実行の場合は 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 を有効にしてください）。クライアントによるキャンセル時には、すべてのワーカーを停止します。stdout には JSON-RPC フレームのみが出力されます。ffmpeg が見つからない場合は、インストールページと環境変数の名前を含むエラーが返されます。

tarball には、パッケージのルートにある 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 カードでは最小 145px）を拒否し、0 バイトのファイルを書き込んで終了するため、プローブは 256x256 のままにしてください。どちらのコマンドも ffmpeg Render Cookbook（$12）に掲載されています。29 個のレシピがあり、公開前にそれぞれ ffmpeg 8.0.1 で実行されています。

セキュリティに関する注意

• リリースは npm trusted publishing（OIDC）を通じて GitHub Actions から npm に公開されます。公開トークンは使用せず、1.5.2 以降の各バージョンには、npm 上の tarball と、それをビルドした正確なコミットおよびワークフロー実行を結び付ける来歴証明が付属します（npm ページの Provenance パネルを参照してください）。
• ダッシュボードは 127.0.0.1 のみにバインドされ、ネットワークから何も読み込みません。テレメトリはありません。
• render_video と renderParallel は、指定されたワーカースクリプトを現在のユーザーの権限で実行します。自分で作成した、または信頼できるワーカーのみを実行してください。
• MCP サーバーは、現在のユーザーがアクセスできるすべての場所でファイルを読み書きします。信頼できるエージェントとともに実行し、プロンプトが信頼できない場合は、作業ディレクトリの制限を検討してください。
• カスタムの filter 文字列はファイルアクセスを伴います。movie= や subtitles= などの ffmpeg フィルターはローカルファイルを読み込みます。フィルター入力はファイルパスと同様に扱ってください。
• 連結リストファイルは os.tmpdir() の下に書き込まれ、出力パスは指定した場所にそのまま書き込まれます。

テスト

npm test は、依存関係不要の 12 個のテストスイート（255 件のチェック）を実行します。ユニットテスト、スモークテスト、stdout のバイト監査を含む stdio 経由の実際の MCP セッション、ffprobe と framemd5 で検証するエンドツーエンドのレンダリングが含まれます。ffmpeg がないマシンでは、レンダリングテストスイートを適切にスキップします。CI では Ubuntu、Windows、macOS 上で、Node 18、20、22、24 を対象に同じテストを実行します。

変更履歴とライセンス

CHANGELOG.md を参照してください。MIT。