ffmpeg

FFmpeg

ffmpeg と ffprobe を使って、ローカルの音声／動画を調査・変換する CLI スキルです。/ffmpeg として呼び出します。

対象範囲： ディスク上のファイルのメタデータ調査、クリップのトリミング、コンテナ／コーデックのトランスコード、セグメントの連結、音声の抽出、サムネイルのキャプチャ、GIF プレビューの作成。AI による画像や動画の生成（draw-thing）、UI やレイアウトのデザイン（design）、ネットワーク経由のダウンロード（yt-dlp）、放送／ストリーミングのパイプラインには対応しません。

---

標準用語

用語	意味	そうではないもの
probe	読み取り専用の ffprobe 調査	トランスコード
trim	時間範囲を指定して短縮すること	UI モックアップのクロップ
transcode	新しいコンテナ／コーデックに再多重化または再エンコードすること	新しい画像の生成
concat	複数の入力を順番に連結すること	Git ブランチのマージ
extract-audio	動画を取り除き、音声トラックを保持すること	音声からテキストへの変換
thumbnail	動画から切り出す単一の静止フレーム	ポスターのレイアウトデザイン
gif	動画クリップから作成するアニメーション GIF プレビュー	CSS アニメーション
stream copy	再エンコードなしの -c copy	すべてのトリミングで常に安全な方法
recipe	references/ の承認済みコマンドテンプレート	場当たり的なフィルターグラフ

---

ディスパッチ

$ARGUMENTS	モード	アクション
doctor / check / preflight	Doctor	PATH の診断を実行し、ffmpeg／ffprobe が見つからない場合は停止します
probe <path> / info <path> / metadata <path>	Probe	プローブヘルパーを実行し、ストリームと再生時間を要約します
trim <path> <start> <end> / clip <path> ...	Trim	プローブし、コピーと再エンコードのレシピを選び、新しい出力パスを指定します
transcode <path> / convert <path> to mp4	Transcode	コーデックをプローブし、H.264／AAC またはコピーのレシピを適用します
concat <file1> <file2> [...] / join ...	Concat	プローブを検証し、concat デマルチプレクサーのレシピと新しい出力パスを使用します
extract-audio <path> / audio <path>	Extract audio	音声ストリームをプローブし、MP3／M4A／コピーのレシピを使用します
thumbnail <path> / thumb <path> [timestamp]	Thumbnail	フレームをシークし、新しいパスに JPG／PNG を書き込みます
gif <path> / animate <path> [start] [duration]	GIF	再生時間の上限を設けたパレット GIF のレシピを使用します
メディアのパス + 自然言語による編集意図	Auto	意図からトリミング／トランスコード／サムネイル／GIF を分類します
(空)	Help	モード、重要なルール、スクリプトコマンド、リファレンスを表示します

自動検出のヒューリスティック

1. インストール／ツールについて不明な点がある → Doctor。
2. 「metadata」「codec」「duration」「how long」「what format」→ Probe。
3. 「cut」「clip」「from ... to ...」、時間範囲 → Trim。
4. 「mp4」「webm」「h264」「aac」「smaller」「compress」→ Transcode。
5. 「join」「merge clips」「append videos」→ Concat。
6. 「mp3」「wav」「m4a」「strip video」「audio only」→ Extract audio。
7. 「poster frame」「screenshot」「still」「thumbnail」→ Thumbnail。
8. 「gif」「animated preview」→ GIF。
9. 画像／動画の生成に関する依頼 → 断り、draw-thing を案内します。
10. UI／ページ／レイアウトのデザインに関する依頼 → 断り、design を案内します。
11. 曖昧な場合 → どのモードかを尋ね、コピーと再エンコードのトレードオフを伝えます。

---

重要なルール

1. 変更前にプローブする — トリミング、トランスコード、連結、音声抽出、サムネイル作成、GIF 作成の前に、すべてのソースファイルに対して probe_media.py を実行します。プローブのフィールドを使って、マップ、コーデック、再生時間の範囲を選択します。references/probe-fields.md を参照してください。
2. デフォルトでは上書きしない — 常に新しい出力パスに書き込みます。明示的なユーザーの承認とバックアップ／一時ファイルを使った置き換えがある場合に限り、同じ場所での置き換えが可能です。references/safety.md を参照してください。
3. 変更にはレシピのみを使用する — ffmpeg コマンドは references/recipes-trim-transcode.md と references/recipes-thumbnail-gif.md のみから作成します。承認なしに、独自のフィルターチェーンや破壊的な一括処理を行ってはいけません。

---

前提条件のプロトコル

変更を行う前に実行します。

uv run python scripts/doctor.py --format json

JSON の ok が false の場合は停止します。インストール方法：

brew install ffmpeg

入力ファイルごとに実行します。

uv run python scripts/probe_media.py /absolute/path/to/input.mp4

レシピを選択する前に、summary.duration_seconds、summary.stream_counts、およびコーデックのフィールドを解析します。

---

モードのプロトコル

Doctor

1. uv run python scripts/doctor.py --format json を実行します。
2. checks のステータスと、fail がある場合はその対処方法を報告します。
3. ffmpeg-binary または ffprobe-binary が失敗した場合は、ffmpeg による変更処理を実行しません。

Probe

1. 読み取り可能なローカルファイルのパスが必要です。
2. uv run python scripts/probe_media.py <path> を実行します。
3. コンテナー、再生時間、映像／音声コーデック、解像度、ストリーム数を要約します。
4. 回転、複数音声トラック、字幕ストリームを解釈する際は、references/probe-fields.md を読み込みます。

Trim

1. ソースを調べ、start／end が duration_seconds の範囲内か検証します。
2. キーフレームとの位置合わせに問題がなければストリームコピーを優先し、問題がある場合は再エンコードによるトリミングのレシピを使用します。
3. basename.trim.ext またはユーザー指定の新しいパスに出力します。
4. references/recipes-trim-transcode.md を読み込みます。

Transcode

1. ソースを調べ、コピーするか、H.264／AAC に再エンコードするかを判断します。
2. 複数のトラックがある場合は、明示的にストリームをマッピングします。
3. ユーザーから禁止されていない限り、MP4 をウェブ配信用にする際は -movflags +faststart を含めます。
4. references/recipes-trim-transcode.md を読み込みます。

Concat

1. すべてのセグメントを調べ、ストリームコピーによる結合に対応するコーデック／解像度か確認します。
2. 絶対パスを含む concat リストファイルを作成します。警告なしに、コーデックが異なる無関係な素材をコピーで結合してはいけません。
3. 新しい *.concat.mp4 パスに出力します。
4. references/recipes-trim-transcode.md を読み込みます。

Extract audio

1. ソースを調べます。stream_counts.audio が 0 の場合は、適切にエラーを処理します。
2. 出力形式に応じて、MP3、M4A、またはコピーのレシピを選びます。
3. 新しいファイルとして basename.audio.ext に書き出します。
4. references/recipes-trim-transcode.md を読み込みます。

Thumbnail

1. ソースを調べ、映像ストリームが少なくとも 1 つあることを確認します。
2. タイムスタンプを決めます（ユーザー指定の値、または再生時間の 10％を 1～10 秒の範囲に収めた値）。
3. JPG／PNG を OUTPUT/ または同じフォルダー内のパスに書き出します。ソースを上書きしてはいけません。
4. references/recipes-thumbnail-gif.md を読み込みます。

GIF

1. ソースを調べ、再生時間を制限します（ユーザーが延長しない限り、デフォルトの最大値は 5 秒です）。
2. 品質を優先する場合は 2 パスのパレットレシピを使用します。クイックプレビューの場合に限り、1 パスを使用します。
3. 新しいファイルとして clip.gif と、必要に応じて palette.png を書き出します。
4. references/recipes-thumbnail-gif.md を読み込みます。

Help (empty)

ディスパッチテーブル、重要なルール、doctor／probe コマンド、リファレンスの一覧、および以下のギャラリーを表示します。

Gallery (Empty Arguments)

$ARGUMENTS が空の場合は、一般的なローカルメディアのタスクを提示します。

#	タスク	例
1	ツールの事前チェック	/ffmpeg doctor
2	メタデータを調べる	/ffmpeg probe ~/Movies/clip.mp4
3	クリップをトリミングする	/ffmpeg trim ~/Movies/clip.mp4 00:00:05 00:00:15
4	コンテナーをトランスコードする	/ffmpeg transcode ~/Movies/clip.mov
5	セグメントを結合する	/ffmpeg concat part1.mp4 part2.mp4
6	音声を抽出する	/ffmpeg extract-audio ~/Movies/clip.mp4
7	ポスターフレーム	/ffmpeg thumbnail ~/Movies/clip.mp4 00:00:03
8	GIF プレビュー	/ffmpeg gif ~/Movies/clip.mp4 00:00:02 4

番号、ディスパッチテーブルのモード、またはファイルパスを貼り付けて編集内容を説明してください。

---

スキルの判別

シグナル	リダイレクト先
「画像を生成」「txt2img」「AI 動画」、ローカルの Draw Things	draw-thing
「ランディングページをデザイン」「Figma」「React のレイアウト」	design
「YouTube／URL からダウンロード」	yt-dlp
ライブストリーミング、RTMP、OBS の接続設定	対象範囲外 — ストリーミングのドキュメントを案内します

---

リファレンスファイル

ファイル	読み込むタイミング
references/safety.md	変更処理、または上書きに関する質問がある場合
references/probe-fields.md	probe JSON を解釈する場合
references/recipes-trim-transcode.md	trim、transcode、concat、extract-audio の場合
references/recipes-thumbnail-gif.md	thumbnail、gif の場合

---

スクリプト

スクリプト	用途
scripts/doctor.py	PATH 上の ffmpeg／ffprobe を検証します（--format json）
scripts/probe_media.py	要約付きの ffprobe ラッパーです（ペイロード全体には --raw を指定）
scripts/check.py	SKILL.md、evals、パッケージのドライラン、監査を検証します

検証：

uv run python scripts/check.py

---

報告テンプレート

変更を加えた後は、以下を報告してください。

1. Doctor のステータス（このセッションで実行した場合）
2. プローブの概要（再生時間、コーデック、ストリーム）
3. レシピ名（コピーまたは再エンコード）
4. 実行した ffmpeg コマンドの正確な内容
5. 出力先のパスとサイズの変化
6. 注意点（キーフレームによるトリミング、音声の欠落、GIF の再生時間の上限）