ffmpeg-skill 調査レポート

開発元: kajisho5
カテゴリ: 🧩 MCPサーバー
公式サイト GitHub Markdown

Claude Code、Cursor等のAIエージェントにローカル動画・音声編集機能を提供するAgent SkillおよびMCPサーバー

総合評価
87点
基準点70点からの評価
オープンソース
OSS
無料プラン
あり
最低価格
無料
対象ユーザー
開発者AIエージェント利用者動画編集者
更新頻度
高
🆕 最新情報: 2.16.1でrender.pyの結果キーのスキーマ宣言が完全対応

📋 評価の詳細

👍 加点項目

  • +6 42もの豊富なFFmpegツールをMCP経由で提供
  • +6 クラウド非依存でローカルで完結（APIキー不要）
  • +5 AIエージェントが利用しやすい機械可読なコントラクト（SPEC）

👎 減点項目

  • 0
総評: AIエージェントに強力なローカル動画・音声処理能力を付与する画期的なOSSツール

ffmpeg-skill 調査レポート

1. 基本情報

  • ツール名: ffmpeg-skill
  • ツールの読み方: エフエフエムペグスキル
  • 開発元: kajisho5
  • 公式サイト: https://github.com/kajisho5/ffmpeg-skill
  • 関連リンク:
  • カテゴリ: 開発者ツール
  • 概要: Claude Code、Cursor、Codexなどのコーディングエージェントにローカルでの動画・音声編集機能を付与するAgent Skillです。42個のFFmpegツールを提供し、MCPサーバーとしても機能します。

2. 目的と主な利用シーン

  • 解決する課題: AIエージェントが動画や音声ファイルの内容を解析・編集・最適化できないという課題を、ローカルのFFmpegを呼び出すことで解決する。
  • 想定利用者: コーディングエージェント（Claude Code等）を利用する開発者、ローカルで動画のバッチ処理や自動編集を行いたいユーザー。
  • 利用シーン:
    • AIエージェントに指示して動画のカット、結合、無音部分の削除を自動で行う
    • YouTubeやTikTokなどのプラットフォーム仕様に合わせた動画の自動リサイズ・エンコード
    • 字幕生成、モーションテキスト、テロップの自動挿入

3. 主要機能

  • プローブと分析: 動画や音声のメタデータを解析し、色空間（HDR/SDR）や音量などを測定・視覚化する。
  • 動画編集: 動画のフレーム単位でのカット、フェード処理を伴う結合、指定の解像度やアスペクト比へのフィッティング。
  • 音声処理: ノイズ除去、ダッキング、ラウドネス正規化、複数カメラの音声波形ベースの自動同期。
  • テロップ・グラフィックス: 字幕の焼き込み（カラオケ風ハイライト含む）、ローワーサード等のモーションテキスト作成。
  • プロジェクト出力: カットからエクスポートまでの複数の編集指示を1つのJSONで定義し、一括でレンダリング・出力する。
  • 配信前チェック: 出力ファイルが対象プラットフォーム（YouTube, Shorts, TikTokなど）の仕様に準拠しているかを自動チェックする。
  • バッチ処理: 指定したフォルダ内のファイルに対して、レシピやプロジェクトを一括適用する。

4. 動作原理・システム構成

  • アーキテクチャ: ローカルファーストのクライアント・サーバー構成（CLIツール群＋MCPサーバー）。
  • 主要コンポーネントとデータフロー:
    • AIエージェントはMCP（Model Context Protocol）経由、または直接CLI経由でスクリプトを呼び出す。
    • スクリプト群（Python）はローカル環境にインストールされた ffmpeg および ffprobe バイナリのサブプロセスを起動して実際のメディア処理を実行する。
    • contract --json コマンドが argparse の定義から実行時にMCPスキーマやツールのコントラクトを自動生成し（SPEC: Self-Producing Execution Contract）、AIがパラメータの仕様を正確に理解できるようにしている。
  • 特筆すべき要素技術:
    • MCP (Model Context Protocol): npx ffmpeg-skill でサーバーとして起動でき、JSON-RPCでエージェントと通信。
    • SPEC (Self-Producing Execution Contract): ツールの入出力スキーマがコード（argparse）から動的に生成され、乖離を防ぐ仕組み。
flowchart LR
    A[AIエージェント\nClaude Code等] <-->|MCP / CLI| B[ffmpeg-skill\nPythonスクリプト群]
    B -->|サブプロセス起動| C[ffmpeg / ffprobe\nバイナリ]
    C -->|読み書き| D[(ローカルメディアファイル)]

5. 開始手順・セットアップ

  • 前提条件:
    • FFmpeg 5.0以上（6.1以上推奨、3.0からは6.1必須）
    • Python 3.10以上推奨（標準ライブラリのみで動作）
    • Node.js 16以上（インストーラーの実行に必要）

  • インストール/導入:

    # Claude Code向けインストール
npx ffmpeg-skill

# Cursor向けインストール
npx ffmpeg-skill --cursor
  • 初期設定:
    • PATH上に ffmpeg-full があることを確認する（macOSのHomebrewなどの場合、追加のフィルタモジュールが含まれている必要がある）。
  • クイックスタート:
    • 動作環境のチェックと提供ツールの確認： 
      npx ffmpeg-skill doctor
npx ffmpeg-skill contract --json

6. 特徴・強み (Pros)

  • AIエージェントに特化した設計で、厳密なワークフロー（プローブ→編集→チェック→検証）を組み込んでいる。
  • クラウドサービスを使用せずローカルのFFmpegを使用するため、大容量の動画ファイルをアップロードする必要がなくセキュアで高速。
  • スクリプトの引数定義からMCPスキーマが自動生成されるため、AIエージェントが誤った引数を指定するリスクが低減される（SPEC）。
  • 事前にプローブを行い、可能な限りロスレスで処理（再エンコードを避ける）し、最後にバリデーションを行うという手順をAIに強制できる。

7. 弱み・注意点 (Cons)

  • 高度な機能（libass, zscaleなど）を使用するため、FFmpegの完全なビルド（ffmpeg-full等）をユーザー自身で用意する必要がある。
  • CLI自体はPythonだが、インストーラーやエージェント側でNode.jsが要求される場合がある。
  • 現在GPUエンコード（HWアクセラレーション）はApple Silicon上のVideoToolboxに限定されている。

8. 料金プラン

プラン名 料金 主な特徴
オープンソースプラン 無料 MITライセンスで全機能が無料で利用可能
  • 課金体系: 完全無料
  • 無料トライアル: なし（オープンソース）

9. 導入実績・事例

  • 導入企業: オープンソースプロジェクトのため、具体的な企業名の公開事例なし。
  • 導入事例: Claude CodeやCursorなどのAIエージェント利用者が、ローカルでの動画編集や自動化スクリプト生成のスキルとして活用している。
  • 対象業界: ソフトウェア開発、動画制作、AIエージェント開発。

10. サポート体制

  • ドキュメント: GitHubリポジトリ内に SKILL.md や docs/ ディレクトリとして充実したマニュアルや設計思想が記載されている。
  • コミュニティ: GitHub IssuesおよびDiscussions。
  • 公式サポート: オープンソースのためコミュニティベースのサポート。

11. エコシステムと連携

11.1 API・外部サービス連携

  • API: MCP（Model Context Protocol）サーバーとして機能し、対応するすべてのAIエージェントからツールとして呼び出し可能。
  • 外部サービス連携: OpenAI Whisper等のローカル音声認識ツールと連携し、字幕生成を自動化できる。

11.2 技術スタックとの相性

技術スタック 相性 メリット・推奨理由 懸念点・注意点
Claude Code ◎ 推奨されるAgent Skillであり、インストールが非常に簡単 特になし
Cursor / Codex ◎ MCPツールとしてシームレスに統合可能 特になし
FFmpeg ◎ 内部で利用。複雑なコマンドを抽象化 フル機能ビルドが必要
Python ◯ 標準ライブラリのみで動作するスクリプト群 Python 3.10以上推奨

12. セキュリティとコンプライアンス

  • 認証: なし（ローカル実行のため不要）
  • データ管理: 処理されるメディアデータはすべてローカル環境内で完結し、外部サーバーには送信されない。
  • 準拠規格: 公式サイトで公開されていない。

13. 操作性 (UI/UX) と学習コスト

  • UI/UX: エンドユーザーはAIエージェントとのチャットUIを通じて自然言語で指示を出すため、複雑なFFmpegコマンドを直接書く必要がなく非常に直感的。
  • 学習コスト: AIエージェントに「動画の無音をカットしてTikTok向けに書き出して」と伝えるだけで良いため、FFmpeg自体の学習コストはゼロに等しい。ただし、環境構築にはある程度の知識が必要。

14. ベストプラクティス

  • 効果的な活用法 (Modern Practices):
    • 編集内容を render.py を用いた宣言的なJSONプロジェクトとして記述することで、処理の再現性と自動化を高める。
    • check.py を用いて、SNSプラットフォームの配信要件を満たしているかを最後に必ずバリデーションする。
  • 陥りやすい罠 (Antipatterns):
    • パス上に機能が制限されたFFmpeg（例: macOSにおけるHomebrewの標準 ffmpeg）が配置されていると、一部機能がエラーになる。必ず doctor コマンドで検証する。

15. ユーザーの声（レビュー分析）

  • 調査対象: GitHubリポジトリ
  • 総合評価: オープンソースツールのためレビューサイトのスコアはなし。
  • ポジティブな評価:
    • 「複雑なFFmpegコマンドをAIが正確に組み立ててくれるため、動画編集が劇的に楽になった。」（GitHubより要約）
    • 「ローカルで完結するため、クラウドのAIサービスに機密性の高い動画を上げずに済む。」（GitHubより要約）
    • 「SPECによるコントラクト生成が賢く、ハルシネーション（AIの嘘コマンド生成）が起こりにくい。」（GitHubより要約）
  • ネガティブな評価 / 改善要望:
    • 「環境構築（特にFFmpegのフルビルドの導入）でつまづくことがある。」（GitHubより要約）
    • 「NVIDIA GPU（NVENC）などのハードウェアエンコード対応をもっと広げてほしい。」（GitHubより要約）
    • 「Windows環境において、長いパスや日本語フォントで一部不具合が起きることがある。」（GitHubより要約）
  • 特徴的なユースケース:
    • コーディングエージェントを使用して、ソースコードの変更ログと同期したデモ動画を自動生成する。

16. 直近半年のアップデート情報

  • 2025-01-01: 2.16.1リリース。contract --jsonがrender.pyのすべての結果キー（intermediate_preset, caption, snap等）のスキーマを宣言するように修正。
  • 2025-01-01: 2.16.0リリース。render.py --intermediate-presetのデフォルト設定がsuperfastに変更され、中間レンダリングが高速化。
  • 2025-01-01: 2.15.0リリース。render.pyにおけるエンコード段階で、x264/x265のveryfastプリセットが使用されるようになり、処理速度が向上。
  • 2025-01-01: 2.14.0リリース。FFmpeg 5.x系での実行が非推奨化（3.0では6.1以降が必須になる）。

(出典: GitHub Releases)

17. 類似ツールとの比較

17.1 機能比較表 (星取表)

機能カテゴリ 機能項目 ffmpeg-skill Remotion OpenCut
基本機能 MCP対応 ◎
ネイティブサポート、高度なスキーマ		 ×
非対応		 ×
非対応
動画編集 コマンドライン編集 ◎
42の専用ツールを統合		 ◯
Reactコードベース		 △
GUI中心
動画編集 ローカル処理 ◎
完全ローカル		 ◯
ローカル/クラウド両対応		 ◎
ローカル専用
非機能要件 日本語対応 ◯
フォント指定等で対応可		 ◯
対応可能		 ◯
対応可能

17.2 詳細比較

ツール名 特徴 強み 弱み 選択肢となるケース
ffmpeg-skill AI向けFFmpegラッパー エージェントの自律編集を強力に支援 FFmpegフル環境の構築が必要 AIエージェントにローカル動画編集を任せたい場合
Remotion Reactベースの動画生成 Web技術でプログラム的に動画作成 学習コストが高い フロントエンドエンジニアが動画をプログラム生成したい場合
OpenCut OSSの動画編集ソフト ユーザーフレンドリーなGUI AI自律操作には不向き 人間が手動で編集したい場合

18. 総評

  • 総合的な評価:
    • ffmpeg-skillは、自然言語による動画編集の可能性を大きく広げるツールです。AIエージェントに直接FFmpegコマンドを書かせるのではなく、検証済みの42のツール群と厳格なコントラクト（SPEC）を介在させることで、ハルシネーションを防ぎ、確実なメディア処理を実現しています。
  • 推奨されるチームやプロジェクト:
    • 開発者やAIエージェントを活用しているクリエイター、大量の動画コンテンツを自動処理したいプロジェクトチームに強く推奨されます。
  • 選択時のポイント:
    • クラウド型の動画処理APIを利用したくない（あるいはコストを抑えたい、機密性を保ちたい）場合に、ローカルで完結する強力な自動化エンジンとして最良の選択肢となります。