music-video

サブコマンド（最初に確認）

呼び出し	実行内容
`/music-video help`, 曲の指定がない `/music-video`、「使い方は？」	ヘルプブロックをそのまま表示し、前提条件（`node -v`、`ffmpeg -version`、`uv --version`、Chromeが存在すること）を確認し、それぞれ✅/❌とインストールコマンドを報告します。そこで停止。動画は開始しません。
`/music-video lessons`	`LESSONS.md`（最新のエントリは全文、古いエントリは見出しのみ）を表示します。
`/music-video <曲ファイル> [lyrics.srt] [フラグ] [ノート]`	下記のフラグを解析し、どのゲートが有効でどの選択肢が既に設定されているかを1行で述べてから、パイプラインを実行します。

ヘルプ

/music-video: 曲をビートに同期したミュージックビデオに変換。すべてコードで描画。
             手描き風のカートゥーンから、シャープなマーケティングスタイルのモーションデザインまで。

使い方
  /music-video ~/Downloads/song.mp3                     歌詞が埋め込まれたSunoファイルは他に何も必要ありません
  /music-video ~/Downloads/song.mp3 lyrics.srt          他の曲：タイミング付き歌詞（.srt）を指定
  /music-video song.mp3 "ノワールスタイル、猫の探偵"    クリエイティブな方向性を指定（オプション）
  /music-video song.mp3 --auto --style=editorial --human=~/me.jpg --dir=~/musicVideos
                                                        完全自動：すべての選択肢をフラグで設定
  /music-video help | lessons

フラグ（デフォルト：ストーリーボードで停止し、パイロット版で承認を待つ）
  --skip=storyboard        ストーリーボードで待機しない。パイロット版では待機する。
  --skip=pilot             ストーリーボードで待機する。パイロット版では待機しない。
  --skip=all （または --auto）停止なし：曲を入れると完成MP4が出力、完全にエージェントが実行
  --design                 さらに計画：デザイン段階を追加（キャラクターモデルシート、パレットスウォッチ、
                           各チャプターに1つのスタイルフレーム）。アニメーション前にルックを
                           繰り返し調整できるよう停止。組み合わせ例： --design --skip=pilot

選択肢（未設定のものは短いインタビューで質問されます。--auto 下ではデフォルト値が使用されます）
  --style=painted|editorial|keynote|geometric|hybrid
                           painted   = 手描き水彩カートゥーン（オリジナルルック）
                           editorial = 温かみのある紙、正確な細い線、セリフ体、落ち着いた雰囲気
                           keynote   = ほぼ黒、輝くグラデーション、光線、パーティクル
                           geometric = スイスグリッド、カラーブロック、パラメトリック曲線、太いサンセリフ体
                           hybrid    = editorialの詩、keynoteのコーラス
                           ask (デフォルト) = 各スタイルで静止画を1枚レンダリングし、選択させる
                           自動デフォルト: editorial
  --lyrics=kinetic|bar|hooks|off   キネティックタイポグラフィ／字幕バー／フック行のみ／なし
                           （デフォルト：ベクタースタイルではkinetic、paintedではbar）
  --density=bold|every-line|abstract
                           bold (デフォルト) = 2～4行につき1つの強いイメージ。残りは背景のイースターエッグ。
                           every-line = 歌詞の1行ごとに1つのギャグ
  --human=PHOTO|pip        「あなた」を演じる人：写真からの似顔絵、または標準のPip
  --dir=PARENT             曲フォルダの作成先（デフォルト ~/PROJECTS）。PARENT/_shared/ には
                           再利用可能なもの（あなたの写真、キャラクター）を保存し、複数のビデオで共有
  --interview / --no-interview   事前インタビュー（G0）を強制またはスキップ

  スキップされたゲートは作業の省略ではありません。成果物は作成され自己レビューされ、
  その選択はDECISIONS.mdに記録され、後で確認できます。

処理の流れ（停止ありで約1.5～2時間、--auto で約45～60分）
  1. 曲を分析：テンポ、ドロップ、セクション、歌詞のタイミング
  1b. インタビュー：スタイルの静止画＋未設定の選択肢、停止          （--auto／全て設定済みの場合は除く）
  2. STORYBOARD.md を作成し、承認のために停止                    （--skip の場合を除く）
  2b. --design の場合：モデルシート＋スタイルフレーム、繰り返し調整のために停止
  3. 30秒のパイロットクリップを作成し、視聴のために停止          （--skip の場合を除く）
  4. 残りを並行して作成（サブエージェント）、すべてのシーンチェンジを確認
  5. out/<曲名>_full.mp4 をレンダリング（1080p、H.264 + AAC）、 YouTubeにそのままアップロード可能

必要環境  Node 20+、Google Chrome、ffmpeg、uv （Mac: brew install node ffmpeg uv）
費用      API費用なし。あなたのClaudeプランを使用します（フルソングはかなりの使用量になります）
出力      プロジェクトフォルダ（デフォルト ~/PROJECTS/<曲名>-video/、または --dir）、リポジトリ外
その後    "今日の教訓をmusic-videoスキルに追加" で次回のビデオが改善されます

完成例はzoo2ビデオ（「Please Select Your Ending」、4:30）：約100ショット、壁時計で約1時間40分で作成。 examples/zoo2/ には、そのストーリーボード、各チャプターファイル、メイキング（タイムライン、トークン数、コスト）が含まれています。開始前に LESSONS.md を読んでください：それは改善ログであり、ここに書かれていることと矛盾する場合はそちらが優先されます。

なぜコードなのか、生成ではないのか

画像モデル（Deforum、SDXL-Turbo img2imgなど）はフレームごとに再推論するため、フリッカー、顔の崩れ、手の崩れが発生します。 zoo2の試行1は一晩かけてそれを行いましたが、却下されました。コードで描画されたフレームは曲の時間の純粋な関数です：スムーズで、モデル通り、正確にビートに合っています。クラウドビデオモデル（Kling、Seedance、Veo）はもう一つの方法で、1曲あたり約70～300ドルかかります。

フラグとゲート

引数およびプレーンテキストからフラグを解析します：「停止なし」、「完全自律」、「そのまま作って」は --skip=allを意味します。「ストーリーボード承認をスキップ」は --skip=storyboard。「最初にキャラクターを見せて」、「もっと計画を練って」は --design を意味します。値はカンマで結合します（--skip=storyboard,design）。未知のフラグ：その旨を伝えて停止します。

ゲート	デフォルト	スキップ時
G0 インタビュー	いずれかの選択肢が未設定の場合に停止	`--auto`/`--no-interview` 下では、未設定の選択肢はデフォルト値を取り、`DECISIONS.md` に記録されます。
G1 ストーリーボード	停止	作成し、歌詞シートに対して1回の自己批判パスを実行（1行につき1アイデア？すべてのコーラスで見返り？モチーフは最後に戻る？）してから続行します。
G2 デザイン（`--design` の場合のみ）	承認されるまで停止し繰り返し	`--skip=design` はステージを保持しますが、シートを待たずに自己批判します。
G3 パイロット	停止	それでもパイロット版は作成します（チャプターに必要な共有 `SETS` を作成します）。続行する前に2回のコンタクトシートレビューパスを実行し、通常の初回バグを修正します。

選択肢（--style、--lyrics、--density、--human、--dir；ヘルプの表）。プレーンテキストもカウントされます：「クリーン」、「コーポレート」、「マーケティング」、「子供っぽくない」、「シャープ」はベクタースタイルを意味します（--auto 下ではどちらか尋ねるか、editorial）。「zooのビデオみたいに」、「手描き風」は painted を意味します。最終的な選択肢を STORYBOARD.md の先頭、および src/config.js に PROJECT.style、PROJECT.lyrics として記録し、サブエージェントが継承できるようにします。

ゲートはユーザーがそう言った場合にのみスキップされます。疑わしい場合は停止します。STOPは本物です：ターンを終了して待ちます。スキップされたすべてのゲートについて、DIR/DECISIONS.md に追加します：ゲート、決定内容、検討した代替案、レビューした画像のパス。最終レポートで DECISIONS.md にリンクし、ユーザーが監査できるようにします。ステップ8の最終ffprobeチェックと歌詞/フレームスポットチェックは決してスキップしないでください。これらは検証であり、承認ではありません。

パイプライン（順番に実行。STOPはフラグでスキップされない限り本物です）

プロジェクト. リポジトリ外にプロジェクトフォルダを作成：PARENT/<曲スラッグ>/。PARENTは --dir（デフォルト ~/PROJECTS）。曲を assets/ に移動します。参照写真（--human）を PARENT/_shared/ に置きます。 bash ~/.claude/skills/music-video/scripts/setup_project.sh PARENT/<曲スラッグ> これは UPSTREAM_PIN でClaudeAnimationBaseをクローンし、src/cast.js（Pip、小道具、カラオケ）を追加し、カラオケを配線します。 Node 20+、Chrome、ffmpeg、uv、gitが必要です。
分析. uv run ~/.claude/skills/music-video/scripts/analyze_song.py SONG --project DIR [--srt LYRICS.srt] これにより src/config.js（フェーズ適合BPMとオフセット）、src/lyrics.js、analysis.json が書き込まれます。librosaのBPMを決して信頼しないでください。 適合した値を使用してください。energy_drops を [Chorus] セクションの開始と照合してください。Sunoのエクスポートには [Section] タグ付きのSRTトラックが埋め込まれています。他の曲の場合は、最初にタイミングを取得します（ユーザーに尋ねるか、whisperでアライメント）。適合BPMは感じられるテンポの2倍になることがあります（低コヒーレンス、歌詞1行＝2「小節」）：ストーリーボードに感じられるテンポを記録し、感じられるビートには bt(2k) を使用します。 2b. インタビュー (G0). すべての選択肢が設定されているか、--auto/--no-interview が指定された場合のみスキップします。そうでなければ：
- 最初にスタイル、絵で。 --style が未設定の場合、比較用静止画をレンダリングします：node design/style_tests.mjs（セットアップ時にコピーされます）は、同じ歌詞の瞬間を editorial、keynote、geometric、hybrid で描画します（--line1/--line2/--stamp で単語を設定）、out/design/style_test_*.jpg と style_tests_all.jpg に出力します。それらを送信し、ユーザーがまだ見ていない場合はzoo2の例からpaintedフレームも1枚送信します。人は言葉からスタイルを選べません。
- その後、残りの未設定の選択肢について1回の AskUserQuestion ラウンドで質問します（lyrics、density、human）、およびストーリーボードだけでは判断できない曲固有の呼び出し：実際のブランドや製品をどの程度文字通りに表示するか、センシティブな歌詞の行（暴力、スキャンダル、実際の出来事）をどのように表示するか。
- 再描画する前に再利用： PARENT/_shared/cast/ にこの人物のキャラクターが既にある場合（例：<名前>.js + <名前>_body.js、以前のビデオで承認済み）、それらのファイルを src/vec/ にコピーし、vec.js の後に <script> タグを追加して、そのまま使用します（表情とポーズのコントロールを含む）。ユーザーが変更を求めた場合のみ再描画します。新しい人物が承認された後、そのファイルを PARENT/_shared/cast/ にコピーします（_shared/README.md に行を追加）これにより、次のビデオで再利用されます。
- 新しい --human 写真の場合、それを見て、似顔絵の特徴を STORYBOARD.md に書き込みます（頭の形、髪の有無、顔の毛、眉毛、目、普段の服装）。特徴から描画します。写真をトレースしたり、ビデオに貼り付けたりしないでください。 G0 — 停止： 静止画と質問を送信後。回答を選択肢にまとめてから続行します。
DIR/ANIMATION_GUIDE.md（キットのルール）、LESSONS.md、および1つのチャプター例（examples/zoo2/scenes/c01_pilot.js）を何かを書く前に読んでください。ベクタースタイル（painted 以外）の場合、ガイドのエンジンセクションは引き続き適用されます（タイムライン、shots()、カメラ、イージング、ビート、レビューループ）が、そのルックルールは逆になります：ベクタースタイル を参照。
ストーリーボード. DIR/STORYBOARD.md（形式：examples/zoo2/STORYBOARD.md）を、ログライン、キャスト、パレットアーク、モチーフ、曲全体のチャプターテーブル、およびパイロットのショットバイショット（タイミング付き「読み」付き）で書き込みます。画像密度は --density に従います（bold：2〜4行につき1つの強いイメージ、残りは背景のイースターエッグ。every-line：行ごとに1つ、キャラクターが演技）。G1 — 停止： ユーザーに表示し、承認を待ちます（--skip=storyboard/all の場合：自己批判し、DECISIONS.md に記録し、続行）。 4b. デザイン（--design の場合のみ）。 アニメーションの前に、out/design/ に静止画でルックを確定します：
- cast_<名前>.jpg キャラクターごとのモデルシート：正面、3/4、横顔、4つの表情（無表情、喜び、恐れ、決意）、ストーリーボードからの3つのアクションポーズ、全キャストの身長比較。
- palette.jpg：チャプターごとのスウォッチストリップ、曲全体のパレットアークを示す。
- style_<チャプター>.jpg：ストーリーボードのヒーローモーメントにおけるチャプターごとの完成キーフレーム1枚、歌詞付き。これらは、使い捨ての scenes/design.js（曲の時間範囲外のシート専用チャプター）と node render.mjs --sheet=... で描画します。キャラクターコードは src/cast.js の追加部分に入り、チャプターで再利用されます。承認されたデザインはそのままビデオに引き継がれます。G2 — 停止： シートを表示。メモを取り（「目を大きく」、「コーラスのパレットを暖かく」）、再レンダリングし、ユーザーが承認するまで繰り返します。その後、STORYBOARD.md をそれに合わせて更新します。
パイロット. セクション境界をまたいでコーラスに入る約30秒を選択します。1つのチャプターファイルとして、window.SETS にエクスポートされた共有セット（c01_pilot.js の最後を参照）を使用して構築します。 node render.mjs --sheet=... --out=out/check/x.jpg および --strip=a:b でチェックし、画像を見てください。通常の初回バグ：キャラクターが小さすぎる（カメラを1.3〜1.5倍に押し込む）、ワイプパンに背景形状の幅が足りない、小道具がカラオケバーの下に隠れている。ベクタースタイルの場合は、src/scenes/sets.js 上に構築します（セットアップで動作するものをコピー：部屋、窓、廊下、スクロール、感情ブレンド。適応）。レンダリング：node render.mjs --clip --range=a:b --out=out/pilot.mp4。 G3 — 停止： ユーザーが視聴し、承認するか変更を要求します（--skip=pilot/all の場合：2回のレビューパスを行い、DECISIONS.md に記録し、続行）。
チャプターを並列に。 まず、すべてのチャプターのスタブファイルとその <script> タグを studio.html に追加します（エージェントは共有ファイルを編集してはいけません）。その後、チャプターごとに1つのサブエージェントを起動します（フォークタイプなので、このコンテキストを継承します）。各サブエージェントに、その時間範囲、歌詞の行、ストーリーボードからのチャプター概要、「自分のファイルのみ」、共有 SETS とグローバル、およびシーム契約を与えます：
- チャプター間：両側で同じ色のトランジション（painted：brushWipe、最後の0.3秒で out p<.5、in .5+lt/.6；ベクター：V.wipe、CHAPTER_BRIEF.md を参照）
- コーラスドロップへの入り：ハードカットアウトとフラッシュイン（flash(1-lt/.18) / V.flash(1-lt/.2)）。ベクターチャプターエージェントには CHAPTER_BRIEF.md も渡します。
- コンタクトシートは out/check/<チャプター>_*.jpg のみに出力し、out/frames やMP4には決して出力しない。
- 最低2回のレビューパス、その後ショットリストと既知の弱点を報告。イントロとアウトロは1つのエージェントでペアにし、エンディングがオープニングと韻を踏むようにします。 --design の場合、各エージェントに承認済みの out/design/style_<チャプター>.jpg を、一致させるルックとして渡します。
シーム. 各境界±0.04秒および±0.2秒でシートをレンダリングし、ワイプ（もしあれば）が正しく機能しているか確認します。

Music Video：コードで描くビート同期のフルMV