kajisho5/ffmpeg-skill

Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.

ffmpeg‑skill とは？

ffmpeg‑skill は、FFmpegをラップしたローカルでエージェントフレンドリーなツールであり、AIコーディングエージェント（Claude Code、Cursor、Codex、または任意のMCPクライアント）が、メディアをクラウドに送信することなくビデオやオーディオファイルを編集できるようにします。それぞれが型定義されたコマンドラインインターフェースと、入力・出力・必要なFFmpeg機能を記述した機械可読なコントラクトを公開する、42種類の小さなPythonツール（例：cut.py、fit.py、loudness.py、caption.py）のコレクションを提供します。

このスキルは厳格なワークフローに従います：

プローブ (Probe)：probe.py を使用してソースの正確なメタデータ（期間、fps、解像度、色空間、オーディオレイアウト、HDRなど）を取得します。
編集 (Edit)：可能な場合はロスレス（ストリームコピー）で編集し、フィルターや精密なカットが必要な場合にのみ再エンコードします。
検証 (Verify)：再度プローブを行い、必要に応じてPNGコンタクトシート（look.py）を生成して結果を検証します。
レポート (Report)：呼び出し元のエージェントが解析可能な構造化されたJSONレポートを返します。

これらすべてがオフラインで実行され、FFmpeg、ffprobe、Python 3（標準ライブラリのみ）が必要です。APIキーや外部サービスは不要で、音声認識（ASR）はローカルのASRエンジンがインストールされている場合のみ機能します。

主な機能

機能	重要性
エージェント対応コントラクト (`contract --json`)	エージェントはJSONスキーマを読み取ることで、渡すフラグが基盤となる `argparse` 定義と一致することを保証でき、ドキュメントとコードの乖離を防ぎます。
42種類の特化ツール	各操作（カット、結合、無音除去、字幕、HDR→SDR、ラウドネス正規化など）は型付き引数を持つ個別のスクリプトであり、LLMが適切なツールを呼び出しやすくなっています。
ロスレス優先ワークフロー	再エンコードが不要な場合、ツールはストリームコピー (`-c copy`) を試み、品質を維持しながら時間を節約します。
ドライランと計画 (`--dry-run`, `--plan FILE`)	エージェントはファイルが書き込まれる前に正確なFFmpegコマンドラインをプレビューしたり、後で実行可能な再現性のある計画を生成したりできます。
検証ステップ (`look.py`, `check.py`)	編集のたびに出力が再度プローブされ、視覚的な内容が変更された場合はPNGシートが生成されるため、エージェントは結果を「見る」ことができます。
機能検出 (`doctor`)	ジョブを実行する前に、ローカルのFFmpegビルドに必要なエンコーダー/フィルター（例：`libass`、`zscale`、`loudnorm`）が含まれているかを確認します。
外部依存関係なし	純粋なPython 3.9+標準ライブラリ。オプションのローカルASRエンジン（Parakeet‑mlx, faster‑whisper, openai‑whisper）は存在する場合のみ使用されます。
テンプレート駆動型配信 (`render.py --template tiktok`)	TikTok、Reels、Shortsなどのプラットフォーム向けに構築済みのJSONテンプレートにより、アスペクト比、字幕スタイル、ラウドネス目標、エクスポートプリセットが自動設定されます。
クロスリポジトリエコシステム	より大規模なAIビデオ制作OSの「手」として設計されており、他のスキル（メディア分析、文字起こし、字幕、カラーグレーディング）がそのコントラクトを呼び出すことができます。

はじめ方

# スキルのインストール（Claudeのスキルディレクトリに追加）
npx ffmpeg-skill

# 必要なFFmpegコンポーネントがマシンにあるか確認
npx ffmpeg-skill doctor

# JSONコントラクトの検査（エージェントやカスタムツールに便利）
npx ffmpeg-skill contract --json | head -40

コマンドラインから直接ツールを実行することも可能です。例：

python3 ~/.claude/skills/ffmpeg-skill/scripts/cut.py input.mp4 \
    --segments 0:45-3:10,5:00-6:30 --dry-run

または、プラットフォーム固有のパッケージをレンダリングする場合：

python3 $HOME/.claude/skills/ffmpeg-skill/scripts/render.py talk.mp4 \
    --template tiktok --cues cues.txt

AIエージェントの典型的なユースケースフロー

ユーザーリクエスト – 「interview.mp4 から最高のハイライトを使って60秒のReelを作って。」
エージェントが SKILL.md を読み、ワークフローを理解します。
プローブ – probe.py が正確なメタデータを返します。
カットの決定 – エージェントは scenes.py を呼び出してハイライト案を取得し、選択したセグメントで cut.py を実行します。
フィットとフォーマット – fit.py で9:16のアスペクト比を強制し、export.py --preset reels で正しいコーデック/ビットレートを設定します。
チェック – check.py --platform reels で期間やラウドネスなどを検証します。
ルック – look.py がコンタクトシートを作成し、エージェントがPNGを検査して視覚的な結果を確認します。
レポート – スキルはステータス、出力パス、プローブの概要、PNGを指す Look: 行を含むJSONオブジェクトを返します。

誰が使うのか？

AI駆動のビデオエディタを構築する開発者：信頼性の高いオフラインのFFmpegバックエンドが必要な場合。
プロンプトエンジニア：生のシェル文字列を書かずにLLMエージェントにメディアを操作させたい場合。
コンテンツクリエイター：プラットフォーム固有のカットを素早く行うために、ローカルでプライバシー重視のワークフローを好む場合。
研究者：ビデオ編集の結果を「見る」必要があるマルチモーダルエージェントを実験している場合。

制限事項

このスキルは、何をカットするか、どの字幕を書くか、どのハイライトが「面白い」かを決定するものではありません。そのロジックは呼び出し元のAIの脳に属します。
ローカルのFFmpegビルドに依存しています。フィルターが欠けていると、対応するツールは使用できません（doctorによって報告されます）。
音声の文字起こしはオプションであり、サポートされているローカルASRエンジンがインストールされている場合のみ機能します。

ライセンス

MIT – 自由に使用、変更、他のプロジェクトへの組み込みが可能です。