ClaudinNarsis/claude-video-skills - FFmpeg動画編集スキル

ffmpeg-skill

スクリプトはこのファイルと同じディレクトリ内の scripts/ にあります。python3 <skill-dir>/scripts/<name>.py で実行し、配信テンプレートは templates/ にあります。このファイルだけでジョブを実行できます。以下の表がリクエストを振り分け、実行直前のスクリプトの --help が最も簡潔な全フラグリストです。リファレンスファイルはこれと同等のコストです。質問がある場合のみ開いてください：references/scripts.md（42全スクリプトの全フラグ）、references/devices.md（iPhone HDR、GoPro、DJI、画面収録、Zoom）、references/gotchas.md（最後にある一行ルールの詳細版）。MCP: tools/list はデフォルトでコア12のみ表示します。他の30（この表の通り）は tools/call で名前指定で呼び出せ、contract --json で説明されます。FFMPEG_SKILL_MCP_FULL=1 を設定すると42すべてが表示されます。

共通フラグ（全スクリプト）： --dry-run、--json（出力パス、そのプローブ、実行したコマンド）、--json-brief（ステータス/出力/検証 + summary；書き込みステップではこちらを優先）、--fast（プレビュー品質）、--progress（パーセント/ETA）、--timeout SECONDS（kind: timeout、デフォルト1800）、--overwrite（ステップ7）、--plan FILE（後で render.py FILE を実行するドライラン；入力が変更された場合は拒否）。再エンコードツールはさらに以下を受け付けます：--hw（Apple Silicon GPU、大きなファイル；FFMPEG_SKILL_HW=1 = デフォルト、エクスポート時は除く）、--codec h264|hevc|av1|prores、--quality N：未設定の場合、SDRはx264（cut.py --keep-hevc：HEVCソースはHEVCのまま）、HDRはx265 Main10；prores には -o NAME.mov が必要、h264 はHDRを拒否（最初に color.py --to-sdr を実行）。

書き込みツールは --dry-run では何も実行しません。測定ツール（probe、check、sync、multicam、scenes、cropdetect、report、silence、loudness、stabilize；overlay はFFmpeg 8.0-8.1.0で複数行の --text に使用）は、ffmpeg/ffprobeを実行することがありますが、アーティファクト/サイドファイル（--edl、--sheet、生成された .ass）はスキップします。verify はこのフラグを無視します。ツールごとに：contract --json dry_run。

ワークフロー（この順序で）

0. 環境、失敗時のみ。 ジョブを doctor で開始しないでください。壊れたマシンは kind: missing_tool またはフィルタ/エンコーダを指定したffmpegエラーで失敗します。そのような失敗の後、またはマシンの機能について尋ねられた場合にのみ、python3 <skill-dir>/scripts/_contract.py doctor（または npx ffmpeg-skill doctor）を実行してください：ok/usable を読み取り、不足している機能を報告します。contract --json のツールスキーマは 計画 エージェント向けであり、このワークフロー向けではありません。
1. 計画に必要な情報をプローブする。 計画の基となる各入力に対して probe.py を実行します：長さ、fps、解像度、コーデック、チャンネル、variable_frame_rate_suspected。ユーザーがファイルについて質問した場合も同様です。すべての編集の前に個別のプローブは不要です：すべての書き込みツールの --json には、その入力と出力のプローブがすでに含まれています。推測ではなく実際の数値から計画を立ててください。
2. ロスレスを優先する。 リクエストが再エンコードなしで満たせる場合（キーフレーム上の単純なカット、リマックス、音声のみの変更）、再エンコードしないでください。cut.py と loudness.py はデフォルトでビデオをストリームコピーします。フレーム単位の正確なカットが必要な場合のみ、cut.py で --accurate を使用します。
3. --dry-run --json で計画し、その後実行する。 計画内の数値については、ドライランのサマリー行ではなく --json を信頼してください（そこにプレースホルダーが含まれる可能性があります）。長時間のエンコードの前に使用して、事実を報告します。このジョブで作成しなかったファイルを -o で指定しないでください。ユーザーがそのファイルの置き換えを明示的に要求した場合を除き、--overwrite はその場合のみ渡します。
4. 適切な順序でチェーンする。 他の編集のない配信リクエストは、手動でチェーンを構築するのではなく、1つのテンプレート実行（render.py --template NAME INPUT）です。それ以外の場合：カラー（HDR→SDR / LUT）→ カット → 結合 → 無音 → フィット → キャプション/オーバーレイ → 同期 → オーディオ → ラウドネス → エクスポート。キャプションの前にフレームを変更して、テキストが最終フレームに合わせてサイズ設定されるようにします。再エンコードは最小限に抑えます：中間ファイルはCRF 18で、export.py は最後に実行します。3ステップ以上の場合：render.py をproject.jsonとともに使用します。
5. 成果物をチェックする。 報告する前に、指定された宛先に対して check.py OUTPUT --platform X を実行します（テンプレート実行ではすでに実行されています）。フォーマット行（コーデック、ピクセルフォーマット、サイズ、トゥルーピーク、カラータグ、VFR）は安全に修正できます。判断行は内容を変更します：長さ（カットで素材が失われる）、アスペクト（クロップでエッジが失われる）、fps（動きが低下する）、ラウドネス（雰囲気をブーストしてはいけない）— リクエストが答えを暗示している場合のみ修正し、それ以外の場合は選択肢とそのコストを述べてください。WARNについては言及しますが、追求する必要はありません。
6. 出力を検証する。 書き込みツールの --json/--json-brief プローブまたは probe.py から、長さ、解像度、fps、オーディオがリクエストと一致することを確認し、それらの数値を報告します（「final.mp4: 59.98 s, 1080x1920, 30 fps, AAC ステレオ」）。スクリプトが終了コード0で終了し、出力が期待通りにプローブされた場合のみ、ステップは完了とみなされます。ゼロ以外の終了、ファイルの欠落または空、リクエストと矛盾するプローブは、スクリプトのエラーメッセージとともに失敗として報告されます。
7. ユーザーのオリジナルを保持する。 ソースを上書きしないでください。入力の隣、またはユーザーが指定した場所に新しいファイルを書き込みます。既存の出力パスは拒否されます（kind: input）。--overwrite は「はい、置き換えてください」と言う唯一の方法です。
8. 画像を見る。 画像が変更された場合（キャプション、オーバーレイ、グラフィック、クロップ/パッド、リサイズ、カラー、トランジション、join.py がクリップを最初のクリップのフレームにスケーリングする、color.py --to-sdr）は、look.py OUTPUT --tiles 3x2（または1フレームの場合は --at T）を実行し、PNGを表示します（全体クリップレイアウトの場合は4x3）。Look: がそのPNGを指定するまで完了ではありません。プローブは顔の上のキャプションを見ることができません。オーディオのみの場合：Look: not needed。何を見るべきかは、ステップ5の check.py の行と同様に分割されます：
   • 機械的なもの（このスキル自身の検証および報告の仕事）： 指定されたテキスト/ロゴが指定された位置にある、字幕が指定されたタイムスタンプに表示される、寸法が偶数である。fit.py --fit pad からのレターボックスは、そのモードの正しい結果であり、決して欠陥としてフラグを立てるものではありません。
   • 判断（報告するが、黙って合格または不合格にしない）： 被写体や顔が切り取られているかどうか、テキストが顔の上にあるかどうか、色が褪せて見えるかどうか、トランジションが適切に着地するかどうか。これらは被写体が何であるかを決定する必要があり、呼び出し側エージェントの判断です。1行で見た内容を述べてください。彼らが判断します。 視覚機能がない場合、Look: PATH (pixels not inspected; agent has no image view) と書き込んでください。画像が検査されたと主張しないでください。実際には検査されていない場合、存在しない機能を待つために停止しないでください。

何かを実行する前に：何を尋ね、何を想定するか

出力を実質的に変更し、リクエストがそれを暗示していない場合にのみ、短い質問をしてください。複数のことが同時に未確定な場合（漠然とした「ソーシャルメディア用にして」が宛先、アスペクト、長さ、キャプションを未確定のままにする場合）、ターンごとに1つずつ質問しないでください。デフォルト値を含む1つのバンドルを提案し、ユーザーが任意の部分を変更できるようにしてください（「Reels: 9:16 パッド追加、60 秒、-14 LUFS、キャプションなし — よろしいですか？」）。1つの質問、1つの答え、そして実行です。probe.py が教えてくれることを尋ねないでください。

• 宛先 はアスペクト、長さ制限、ラウドネス、コーデックを決定します。「Reels用」はこれら4つすべてに答え、テンプレートを指定します。宛先がなく、単純なカット/キャプションの場合は、ソース形式を維持し、そのように伝えてください。ユーザーが「エクスポート」、「投稿」、「配信」と言った場合は、どこかを尋ねてください。
• 長さ（「60秒にして」）で方法が指定されていない場合：変更が1.5倍以下の場合は速度変更、それ以外の場合はトリミングを使用し、その旨を伝えてください。内容がトーク（トリミングで言葉が失われる）で変更が大きい場合は質問してください。
• キャプション でテキストソースが指定されていない場合：ローカルエンジンが存在する場合は --transcribe、そうでない場合はテキストまたはタイムドファイルを要求してください。決して会話を捏造しないでください。
• フォントとブランド：ユーザーがブランド、色、「私たちのフォント」について言及した場合、brand.json を要求するか作成し、1回再利用します。
• CJK / 非ラテン文字：ツールにスクリプトでフォントを選択させます（--font でオフになります）。漢字のみのテキストには --lang ja|ko を使用します。doctor --json の .fonts.scripts は、ここでレンダリングできるものを示します。トーフ（文字化け）は失敗したジョブです。
• クロップ位置 --fit crop の場合：デフォルトは中央ですが、リクエストまたはソースが中央にない被写体を指定している場合（「製品を右側に残す」、シート内で誰かが明らかに中央にいない場合）、中央を推測する代わりに --crop-x/--crop-y（0=左/上、1=右/下）を使用するか、どちらの端を残すか尋ねてください。
• その他すべて（トランジションタイプ、キャプションスタイル）：従来のデフォルトを選択し、何を選択したかを伝え、1行で代替案を提供してください。

このスキルが行うことと行わないこと

このスキルは、ファイルのカット、結合、測定、同期、エクスポート、チェックを行います。編集を実行しますが、編集を決定するわけではありません。人間、呼び出し側エージェント、または別のスキルに属するもの：

• どのカットが正しいか、成果物が承認可能か — このスキルは測定して報告します（check.py のPASS/WARN/FAIL、cut.py の長さエラー）。出荷するかどうかはユーザーまたはプロダクションエージェントが決定します。
• ハイライトを何が面白くするか — scenes.py --highlights は測定されたプロキシ（オーディオエネルギー、長さ）でランク付けします。候補であり、判定ではありません。
• サムネイルやカバーの構成 — デザインの決定であり、測定ではありません。
• ビデオが何についてであるかを理解すること — ここには look.py のコンタクトシート以上の視覚機能はありません。これらは呼び出し側エージェントの目が使うものであり、このスキルが解釈するものではありません。
• 何が見た目に良いかを判断すること — 「このLUTを適用する」、「露出を+0.3ストップ補正する」（color.py）は機械的です。「このシーンを映画のようにグレーディングする」は、パラメータを決定してから color.py を呼び出すカラーグレーディングスキール（color-grading-skill）に属します。
• キャプションの単語 — キューテキストは書かれたまま焼き付けられます。フレームに対して長すぎる場合は、サイズを小さくするか、--max-lines を使用するか、ユーザー自身の編集が必要です。「収まるようにする」と頼まれても、決して書き換えたり、短縮したり、言い換えたりしないでください。その旨を伝え、より小さいサイズで --max-lines 1 を提案してください。
• 与えられていない被写体や領域を選択すること — 「x=200,y=0 にクロップ」は、ボックスがわかれば機械的です。「話者をフレーム内に収めるためにクロップ」するには、話者が何であるかを決定する必要があり、それは呼び出し側エージェント（look.py シートから）の判断です。

線引き：同じ入力＋同じ明示的なパラメータが常に同じ検証可能な出力を生成するものはここに属します。味覚、理解、見た目や音の良さに依存するものは、その判断を行う人に属します。

リクエストに、42のスクリプトのどれも公開していないFFmpeg機能が必要な場合は、その旨を伝え、最も近い組み込みオプションを指定してください。scripts/*.py の外部で生の ffmpeg/ffprobe 呼び出しを推測しないでください。それはこのスキルが行うすべての保証を無効にするため、決してフォールバックとしてはなりません。

リクエスト → スクリプト

この表と doctor --json の tools リストが、何が存在するかについての真実の情報源です。それらのいずれかで見たスクリプトのみを名前指定してください（doctor.py、trim.py、subtitle.py はありません）。

タイムスタンプフラグ（--start、--end、--at、--from、--duration、--offset、およびキューとチャプターファイル内の時間）は、秒、mm:ss(.fff)、hh:mm:ss(.fff)、または @fps 付きのSMPTE hh:mm:ss:ff（00:01:02:[email protected]）を受け付けます。NLEキューシートをそのまま貼り付けてください。長さフラグ（--min-silence、--margin、--fade）はプレーンな秒です。

ユーザーの発言	実行内容
「1:20から2:05までカット」、「最初の10秒をトリム」	cut.py input.mp4 --start 1:20 --end 2:05
「これらの部分だけ残す」、「真ん中を削除」	cut.py input.mp4 --segments 0-1:00,1:30-2:00
「正確に60秒にして」	fit.py input.mp4 --duration 60（速度変更）または --method trim
「これをカットしてHEVC / AV1 / ProResにして」（出力コーデック指定）	cut.py input.mp4 --start 0:10 --end 0:40 --codec hevc（ProResの場合は -o NAME.mov が必要）
「間をカット」、「ジャンプカット」	silence.py input.mp4 [--threshold -40 --min-silence 0.8]
「えーと、あーをカット」、「フィラーワードを削除」	silence.py input.mp4 --filler --words words.json（測定された単語タイミング；--transcribe で作成）
「文の途中でカットしないで、本当の間だけ」	silence.py input.mp4 --speech-aware — 文内の --min-silence 未満の息継ぎは保持され、文境界の間のみカット。--filler と組み合わせて1つのリストに。
「この1時間から60秒のハイライト」	scenes.py long.mp4 --highlights 6 --target 60 --edl picks.txt → cut.py --segments
「ビートでカット」、「音楽に合わせて編集」	scenes.py track.mp4 --beats --json > beats.json、次に cut.py input.mp4 --segments ... --snap beats --snap-source beats.json（--snap-source で測定されたグリッドを引き継ぐ）
「ここを速く、そこをスローモに」（既知のセグメント）	speedramp.py action.mp4 --segment 0-3:1.0 --segment 3-4:0.25 --segment 4-8:2.0
「このフレームで停止」、「最後のフレームをフリーズ」	freeze.py clip.mp4 --hold 2
「滑らかなスローモーション」、「半分の速度だが流動的に」	fit.py input.mp4 --duration 2x --smooth interpolate（遅い）または --smooth blend
「このクリップを反転」	reverse.py input.mp4
「このクリップをループして30秒にする」	loop.py bg_loop.mp4 --duration 30
「縦型 / 9:16 / 正方形にして」	fit.py input.mp4 --aspect 9:16 --fit pad（または --fit crop；ぼかしバーの場合は --pad-fill blur）
「高さ/幅にリサイズ」	fit.py input.mp4 --height 1080（または --width、または両方で正確なフレーム）
「この正確なボックスにクロップ」（既知のx/y/w/h）	crop.py input.mp4 --x 100 --y 0 --width 1080 --height 1920
「黒いバーの代わりにぼかし背景」	fit.py input.mp4 --aspect 9:16 --fit blur（画像全体を保持、境界はぼかされた暗いコピー）
「90度回転」、「ミラー」	fit.py input.mp4 --rotate 90 / fit.py input.mp4 --flip h
「地平線が傾いている」（既知の角度）	straighten.py tilted.mp4 --degrees -2.5
「この360度ビデオから平面ビュー」（既知のyaw/pitch/fov）	sphere.py insta360.mp4 --yaw 90 --pitch 0 --h-fov 100 --v-fov 70
「この古い映像はインターレースしている」	deinterlace.py input.mp4
「粒子/ノイズが多いので、きれいにして」	denoise.py input.mp4 --strength medium
「この顔/ナンバープレートをぼかす/ピクセル化」（既知のボックス）	redact.py input.mp4 --x 820 --y 140 --width 240 --height 240 --mode pixelate
「この固定ロゴを削除」（既知のボックス）	redact.py input.mp4 --x 40 --y 20 --width 180 --height 60 --mode delogo
「この手振れを安定化」	stabilize.py input.mp4
「これに黒いバーがあるか？」	cropdetect.py input.mp4
「iPhone Dolby Visionクリップがおかしい」	color.py input.mp4 --to-sdr（トーンマッピング）
「色を修正して、寒色系に」、「暖かくして」	color.py input.mp4 --temp -1500 --tint 10（ケルビン単位）
「明るく/暗く」、「露出を+1ストップ」	color.py input.mp4 --exposure 1.0
「彩度を上げる/下げる」、「白黒にする」	color.py input.mp4 --saturation 0.5 / color.py input.mp4 --saturation 0
「このLUTを適用」、「この外観をグレード」	color.py input.mp4 --lut FILTER.cube
「映画のような24fpsに見えるように」、「テレシネ」	telecine.py cinematic.mp4 --from 30 --to 24（ソース/ターゲットfpsを指定）
「このクリップにテキストを追加」（テキストと位置を知っている）	`overlay.py input.mp4 --text