ffmpeg-skill — コーディングエージェント向けローカル動画編集MCPツール
kajisho5/ffmpeg-skill
★ 6,993 ・ Python ・ MIT
概要
ffmpeg-skill は、Claude Code、Cursor、Codex などのコーディングエージェント向けに作られたローカル動画編集ツールキットです。Anthropic が提唱する Agent Skill 仕様に準拠しているほか、Model Context Protocol(MCP)サーバーとしても動作します。
LLM やコーディングエージェントに直接シェルコマンドで FFmpeg を実行させると、存在しない引数を推測したり、動画のプロパティを誤認して無駄な再エンコードを行ったり、生成物の確認を怠ったりする問題が発生しがちです。ffmpeg-skill は、カット、結合、無音削除、字幕生成、ラウドネス調整、アスペクト比変換などの 42 種類の処理を型付けされた個別スクリプトとして提供します。事前調査(probe)から実行、検証(verify)までの一連のワークフローをエージェントに教え込むことで、確実で安全なローカル動画編集を実現します。クラウドサービスや外部 API キーに依存せず、手元の端末で動画を処理したい開発者やエージェント運用者に適しています。
主な特徴
- 42種類の特化型ツール群: カット(cut)、結合(join)、無音区間カット(silence)、字幕焼き込み(caption)、ラウドネス正規化(loudness)、マルチカム同期、カラーグレーディングなど、動画編集に必要な処理が個別ツールとして実装されています。
- 機械可読な実行契約(SPEC: Self-Producing Execution Contract): 各ツールの入力スキーマは CLI の
argparse定義から実行時に自動生成されるため、CLI フラグと MCP 定義の乖離が発生しません。エージェントはcontract --json経由で各ツールの仕様を正確に把握できます。 - MCP(Model Context Protocol)サーバー機能: クライアントのコンテキスト消費を抑えるため、デフォルトでは主要な 12 ツールのみを公開しつつ、環境変数切り替えですべてのツールを公開できます。名前指定の呼び出しであれば全 42 ツールに対応しています。
- 完全ローカル動作・外部依存なし: コア部分は Python 標準ライブラリのみで書かれており、クラウド送信や追加の Python ライブラリ導入なしで動作します。機密性の高い動画ファイルも安全に処理可能です。
- 「推測させない」検証主導のワークフロー: 処理前に必ず動画情報を実測し、可能な場合は可逆(ストリームコピー)で編集し、処理後には出力仕様の適合確認やコンタクトシートによる目視確認を行うワークフローが設計されています。
使い方
動作環境の準備
システム上に ffmpeg、ffprobe、および python3 がインストールされている必要があります。以下は Ubuntu / Debian での例です。
sudo apt install ffmpeg
スキルのインストール
npx コマンドを使用して、対象のエージェント環境にスキルをインストールします。デフォルトは Claude Code 向けですが、オプションで Cursor や Codex も指定できます。
# Claude Code 向けにインストール
npx ffmpeg-skill
# Cursor 向けにインストールする場合は --cursor、全対応は --all
npx ffmpeg-skill --all
動作診断と仕様確認
インストール後、必要なバイナリや依存コンポーネントが揃っているかを doctor サブコマンドで検証できます。
# 実行環境の依存関係を診断
npx ffmpeg-skill doctor
# エージェント向けの機械可読な契約(JSON)を確認
npx ffmpeg-skill contract --json | head -40
音声からの自動文字起こし・字幕生成(caption.py --transcribe)を利用したい場合は、ローカルの音声認識エンジン(faster-whisper など)を別途インストールします。未導入の場合でも、他の全機能はそのまま動作します。
技術的なポイント
単一の情報源から導出される契約(SPEC)
エージェント連携ツールでは、エージェントへ提示する JSON スキーマと実際の CLI 実装との間で不一致が起きる問題(スキーマドリフト)が課題になります。ffmpeg-skill では「Self-Producing Execution Contract (SPEC)」というアプローチを採用しており、argparse で記述された引数定義から MCP の input_schema を直接生成しています。CI パイプライン上でもこの同期が検証されており、実装とインターフェース定義の齟齬を防いでいます。
シェルを介さない堅牢なコマンド構築
LLM が自由記述のシェルスクリプトや複雑な FFmpeg フィルターグラフを直接組み立てると、構文エラーや意図しない挙動が生じやすくなります。ffmpeg-skill では、すべての操作を個別の Python スクリプトとして分離し、引数を厳密に型付けしています。シェルを介さず引数リストとして FFmpeg を呼び出すため、エスケープ漏れやインジェクションのリスクを排除しています。
エコシステムにおける役割分担
作者のリポジトリ群において、本ツールは「手(Hands)」としての役割に徹しています。カット位置の決定や演出の判断といった「頭脳(Brain)」の役割は上位のエージェント(video-production-agent など)が担当し、本ツールは指示された通りの正確な測定、切断、出力、および構造化 JSON での報告のみを担う設計になっています。
注意点
- ローカルバイナリへの依存: クラウドに依存しない反面、実行ホスト上に
ffmpegおよびffprobeが正しく導入され、PATH が通っている必要があります。利用可能なコーデックやフィルターは導入されている FFmpeg のビルド内容に依存します。 - スキルの更新手順:
npx ffmpeg-skillでエージェントの設定ディレクトリ(例:~/.claude/skills/ffmpeg-skill)にファイルをコピーする方式をとっているため、ツール本体をアップデートする際は再度コマンドを実行して手動で上書きする必要があります。 - 文字起こし機能の追加設定: 音声認識を用いた字幕付けや無音検出の高度なオプションには、
faster-whisperやopenai-whisperなどのローカル ASR エンジンの別途導入が必要です。初回実行時にはモデルのダウンロードが発生します。 - ライセンス: 本プロジェクトは MIT ライセンスで公開されています。
まとめ
ffmpeg-skill は、コーディングエージェントに FFmpeg の正確な実行能力を与える実用的なツールキットです。推測に頼らない計測・検証の仕組みと厳密なスキーマ設計により、エージェントによる動画編集の失敗を最小限に抑えます。CLI や MCP 経由で手軽に導入できるため、AI を活用したメディア処理の自動化を検討している方におすすめです。





