kajisho5/remotion-ffmpeg-skill

remotion-ffmpeg-skill は何をしますか？

ffmpeg-skillが測定 → Remotionが描画 → ffmpeg-skillがチェックして納品。 スクリプトはこのファイルの隣の scripts/ ディレクトリにあり、python3 <skill-dir>/scripts/<name>.py で実行します。スクリプトの --help で完全なフラグ一覧を表示します。references/timeline.md はタイムラインフォーマットと、すべてのコンポジションが受け付けるオプションです。

このスキルは ffmpeg-skill に依存します（このスキルの隣、~/.claude/skills/ffmpeg-skill、または FFMPEG_SKILL_DIR 環境変数で指定）。生の ffmpeg/ffprobe コマンドは直接実行しません。測定、チェック、納品はすべて ffmpeg-skill のスクリプトを通じて行われるため、その保証も引き継がれます。

共通フラグ（すべてのスクリプト）: --json（標準出力にJSONオブジェクト1つを出力。推奨）、--dry-run（計画のみで何も書き込まない）、--overwrite（既存の出力を置き換える唯一の方法）、--timeout SECONDS。

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

1. プロジェクト作成（一度だけ）。 まだRemotionプロジェクトがない場合: init.py ./motion --install（テンプレートをコピーし、npm install を実行。Remotionのヘッドレスブラウザは最初のレンダリング時にダウンロードされます）。このスキルで既存のプロジェクトがある場合は、それを再利用します。
2. 測定。 analyze.py SOURCE [--captions FILE.srt] [--beats] -o SOURCE.timeline.json。サマリーと warnings を読んでください。VFR（可変フレームレート）またはHDRソースは、描画の 前に ffmpeg-skill で修正する必要があります（color.py --to-sdr でSDRに変換、固定フレームレートで書き出し）。Remotionは固定フレームグリッドでSDRレンダリングを行います。タイムラインの数値は手動で書き換えたり編集したりせず、代わりに再測定してください（--threshold、--min-silence は静かな部屋向け）。
3. スチルプレビュー。 still.py --project ./motion --comp NAME --timeline TL --at 1.5 --at 6 を実行し、PNGを確認します。キャプションの配置、パンチイン、色をチェック。コストが低いので、本レンダリングの前に行ってください。
4. レンダリング。 render.py --project ./motion --comp NAME --timeline TL [--options look.json] -o OUT.mp4（--fast = 半分サイズのプレビュー、--frames 0-89 = 範囲指定、--codec prores -o master.mov = マスター用）。出力をタイムラインと照合（フレーム数、FPS、サイズ、オーディオ）し、不一致があれば非ゼロで終了します。
   • 形（アスペクト比）： 最終的に配信される形で描画します。--aspect 9:16 はReels / TikTok / Shorts用（1:1、4:5、16:9 も可）。--fit blur（デフォルト。形が変わる場合：ぼかしたコピーの上にコンテンツを収める）、contain（黒帯）、cover（クロップ—事前にスチルで被写体を確認）。16:9でレンダリングして9:16テンプレートでクロップしてはいけません。キャプションの端が欠けます。pipeline.py --platform はffmpeg-skillのテンプレートから自動でアスペクト比を選択します。
   • フォント： 日本語/中国語/韓国語のキャプションは、ffmpeg-skillがマシン上で見つけたCJKフォントを自動で使用します（プロジェクトにステージングされるため、豆腐になりません）。--font-file F.ttf で特定のフォントを指定可能。レポート行 font: に使用されたフォント、または見つからなかったことが表示されます。
   • 編集アプリ向けレイヤー： --overlay --keep-graphics（Captioned / PeakPulseコンポジション、ソースと同じアスペクト比）を指定すると、グラフィックスのみを透明ProRes 4444 .graphics.mov として描画し、ffmpeg-skillの overlay.py で未加工のソースと合成します。この .mov をPremiere / Resolve / Final Cutで仕上げる人に渡します。通常のレンダリングより速くはありません。
5. 納品。 deliver.py OUT.mp4 --platform youtube|reels|tiktok|shorts|x|... はffmpeg-skillの配信テンプレートとその check.py テーブルを実行します。フォーマット行は修正しても安全です。判断行（duration、aspect）は内容を変更するため、確認してください。WARNsに言及し、追及しすぎないでください。出力先が指定されていない場合は、このステップをスキップし、その旨を伝えます。
6. 確認。 返信で、render.py が書き出したコンタクトシートのパス（Look: PATH）を明示し、その内容を説明するまで完了ではありません。機械的な確認（チェックして報告）：テキストは指定された場所にあるか、キューは指定された時間に表示されるか、フレームの端で切れていないか。判断を要する確認（見えたものを述べ、ユーザーが決定）：顔の上にテキストがある、ジャンプカットの着地が悪いなど。画像が表示できない場合：Look: PATH (pixels not inspected) — 見たと主張しないでください。コンタクトシートがない場合（結果の look_error に理由、例：drawtextがないFFmpegなど）：代わりに still.py のフレームを確認し、エラーが示す修正方法を伝えてください。

オプションファイルはレンダリング前にチェックされます。未知のキーや間違った型は、静かに無視される代わりに拒否されます（kind: input）。

MCP: mcp/server.py は同じツールを公開します（スキーマは scripts/_contract.py から、contract --json で出力）。

すべてを一度に実行: pipeline.py SOURCE --project ./motion --comp NAME [--captions F] [--platform P] は手順2→4→5を同じチェックで実行し、失敗した最初のステップで停止します。

リクエスト → スクリプト / コンポジション

リクエスト	実行内容
"この動画にアニメーションキャプション/字幕を付けたい"	analyze.py --captions → render.py --comp Captioned
"無音部分をカット/ジャンプカット/このトークを詰めたい"（モーション付き）	analyze.py → render.py --comp Jumpcut（キャプションがあれば再調整）
"オーディオに反応する/ビートに合わせる/カットに合わせるグラフィックス"	analyze.py [--beats] → render.py --comp PeakPulse（ビートグリッドが測定された場合、ビートに合わせてパルス）
"カラオケキャプション/話されている単語がハイライトされる"	analyze.py --words WORDS.json [--captions F.srt] → render.py --comp Karaoke（ローカルの音声エンジンからの単語タイミング、whisper JSON。SRTがない場合、キューは単語からグループ化）
"ローワーサード/名前タイトル/チャプタータイトル"	render.py --comp Titled --options に lowerThirds / sceneTitles を指定—テキストはユーザーから取得します。必ず尋ね、名前を勝手に作らないこと
"ハイライトリール/ベストモーメント"	analyze.py --highlights N [--target S] → render.py --comp Highlights（オーディオエネルギー順位付け：候補であることを伝える）
"ビートに合わせてカット/ミュージックモンタージュ"	analyze.py --beats [--highlights N] → render.py --comp BeatMontage（オーディオは連続、ピクチャーは測定されたビートごとにカット。信頼できるグリッドがない場合はシーンカット）
"YouTube/Reels/TikTok...用に"	pipeline.py --platform（テンプレートのアスペクト比でレンダリングし、納品とチェックを行う）、または render.py --aspect + deliver.py --platform
"縦長/9:16/正方形"	render.py --aspect 9:16（または 1:1、4:5）
"日本語キャプション" / 特定のフォント	CJKの場合は特別な操作不要（自動フォント）。--font-file でフォントを指定
"グラフィックスを別レイヤーで出力"	render.py --overlay --keep-graphics
"色/フォント/キャプションサイズ/ズームを変更"	--options JSON（references/timeline.md）を指定して再レンダリング
複数クリップ（"イントロ＋トーク＋アウトロ"）	analyze.py A.mp4 B.mov C.mp4（または pipeline.py に複数入力）：ffmpeg-skillの join.py で正規化・結合し、結合されたファイルで測定
"プレビュー" / "フレームを見せて"	still.py
新しい種類のグラフィックス	プロジェクトの src/ に src/timeline.ts から Props を読み取るコンポジションを追加。render.py --comp YourId でレンダリング（組み込みの期待値なしに測定された数値を報告）
グラフィックスなしの単純カット/トリム/リサイズ/ラウドネス	このスキルではありません。ffmpeg-skillを直接使用
何かが壊れた	doctor.py [--project DIR]

このスキルが決定することとしないこと

• 決定する（機械的）： コンポジションの長さ、FPS、サイズ（プローブから）。カットの位置（測定された無音から）。キューの表示タイミング（キャプションファイルから）。パルスのタイミング（測定されたピークから）。レンダリング結果がタイムラインと一致するかどうか。
• 決定しない： 名前、タイトル、チャプター名（ローワーサードやシーンのタイトルはユーザーのテキスト—必ず尋ねること）。キャプションが言う単語—キューテキストは書かれた通りに正確に描画され、決して短縮や言い換えをしない（「収めるため」であっても。代わりにより小さい captionSize を提案）。何がハイライトか。見た目が良いかどうか。これらはユーザーまたは呼び出し元のエージェントに属します。
• データを決して捏造しない。 ユーザーまたはローカルの音声認識エンジンからのタイミング付きキャプションファイルなしでキャプションは付けない。--beats で測定しなかったビートグリッドは使わない。

ジョブの失敗を防ぐルール

• Remotionライセンス：個人および3人以下の営利組織は無料。大企業はRemotionの会社ライセンスが必要です（https://www.remotion.dev/license）。ユーザーが明らかに大企業である場合、その旨を一度伝えてください。
• ユーザーのオリジナルを保持：ソースはプロジェクトの public/media/ にリンクされ、決して変更されません。出力は --overwrite なしで既存ファイルを上書きしません。
• CJKキャプション：自動フォントはffmpeg-skillのフォント検出から取得されます。レポートでフォントが見つからなかったと表示された場合、フォント（Noto Sans CJK）をインストールするか、--font-file を指定します—コンタクトシートで豆腐が表示されたらジョブ失敗です。日本語の行はフレーズ間で改行され、単語の中では改行されません。
• 速度（2コアLinuxマシン、全コア使用で測定—render.pyのデフォルト）：1080p30でクリップ長の約2.6倍（30秒で80秒）。長い映像の本レンダリングの前に still.py と --fast でプレビューし、長時間のレンダリングを開始する前にユーザーに予想時間を伝えてください。--concurrency をコア数より大きく設定するとRemotionに拒否されます。
• プロジェクト内のRemotionパッケージはすべて同じバージョンである必要があります。テンプレートで固定されています。異なる remotion バージョンを混在させないでください。
• 検証に失敗したレンダリングは失敗です。--json から失敗した行を報告し、納品しないでください。