Music Video：純程式碼繪製的卡點完整 MV

音樂影片製作

子命令（請先檢查這些）

調用方式	執行動作
/music-video help, /music-video 未指定歌曲，或「我該如何使用？」	逐字輸出下方的 說明 區塊，然後檢查先決條件（node -v、ffmpeg -version、uv --version、Chrome 是否存在），並以 ✅/❌ 回報每個項目的狀態，同時附上安裝指令。停止；不要開始製作影片。
/music-video lessons	輸出 LESSONS.md（最新的條目全文輸出，較舊的條目僅輸出標題）。
/music-video <歌曲檔案> [lyrics.srt] [標記] [備註]	解析下方的標記，一行說明哪些閘門已開啟以及哪些選擇已設定，然後執行工作流程。

說明

/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                 更多規劃：新增設計階段（角色模型
                           表、色板樣本、每章一幅風格影格）
                           並停止，以便您在動畫開始前反覆調整外觀。可與
                           --design --skip=pilot 組合使用

選擇（未設定的選擇會在簡短的面談中詢問；在 --auto 模式下使用預設值）
  --style=painted|editorial|keynote|geometric|hybrid
                          painted   = 手繪水彩卡通（原始外觀）
                          editorial = 溫暖紙張、精準細線、襯線字體、平靜
                          keynote   = 近黑色、發光漸層、光束、粒子
                          geometric = 瑞士網格、色塊、參數曲線、粗體無襯線字體
                          hybrid    = editorial 主歌 + keynote 副歌
                          ask (預設) = 每種風格渲染一張靜態圖，讓您挑選
                          自動預設值：editorial
  --lyrics=kinetic|bar|hooks|off   動態文字 / 字幕條 / 僅副歌 / 無
                            (預設：向量風格為 kinetic，繪畫風格為 bar)
  --density=bold|every-line|abstract
                          bold (預設) = 每 2–4 行一個強烈畫面，
                          額外的笑點作為背景彩蛋；every-line = 每行歌詞一個笑點
  --human=PHOTO|pip        誰扮演「你」：從照片繪製的漫畫肖像，或預設的 Pip 角色
  --dir=PARENT             歌曲資料夾的存放位置（預設 ~/PROJECTS）；PARENT/_shared/
                           存放可重複使用的東西（您的照片、您的角色）跨影片使用
  --interview / --no-interview   強制或跳過預先的面談（G0）

  跳過的閘門不代表跳過工作：仍然會製作成品並進行自我審查，
  並且其做出的選擇會記錄在 DECISIONS.md 中，供您之後閱讀。

發生什麼事（約 1.5–2 小時含停止；約 45–60 分鐘使用 --auto）
  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），在任何儲存庫之外
之後   「將今天的經驗教訓新增到音樂影片技能」將使下一部影片更好

已完成的範例是 zoo2 影片（「請選擇您的結局」，4:30）：約 100 個鏡頭，大約 1 小時 40 分鐘的實際時間建構完成。 examples/zoo2/ 包含其分鏡腳本、每個章節檔案，以及製作過程、時間線、代幣和成本的記錄。在開始之前，請先閱讀 LESSONS.md：它是改進日誌，且若與此處任何內容衝突，以其為準。

為什麼用程式碼，而不是生成式

影像模型（Deforum、SDXL-Turbo img2img 等）會重新猜測每個影格，導致閃爍、變形的臉孔和不好的手部。 Zoo2 的第一次嘗試整晚這樣做，並被否決了。程式碼繪製的影格是歌曲時間的純函數：流暢、符合模型且精準地打在節拍上。雲端影片模型（Kling、Seedance、Veo）是另一條路，每首歌約需 70–300 美元。

標記和閘門

從引數和普通文字中解析標記：「無停止點」、「完全自主」、「直接做」代表 --skip=all；「跳過分鏡腳本批准」代表 --skip=storyboard；「讓我先看角色」、「多做點規劃」代表 --design。值可以用逗號組合（--skip=storyboard,design）。未知的標記：告知並停止。

閘門	預設	跳過時
G0 面談	當任何選擇未設定時停止	在 --auto/--no-interview 模式下，未設定的選擇使用預設值，並記錄到 DECISIONS.md。
G1 分鏡腳本	停止	撰寫它，對照歌詞表執行一次自我批評（每行一個點子？每個副歌都有回報？主題在結尾重現？），然後繼續。
G2 設計（僅限 --design）	停止，反覆調整直到批准	--skip=design保留此階段，但會自我批評模型表而不是等待。
G3 試播	停止	仍然建構試播（它會建立章節所需的共享 SETS）。在繼續之前，執行兩次連環畫審查，並修正常見的首次建構錯誤。

選擇（--style、--lyrics、--density、--human、--dir；詳見說明的表格）。普通文字也有效：「乾淨」、「企業」、「行銷」、「不要幼稚」、「清晰」代表向量風格（詢問是哪種，或在 --auto 下使用 editorial）；「像動物園影片」、「手繪」代表 painted。在 STORYBOARD.md 的頂部和 src/config.js 中以 PROJECT.style、PROJECT.lyrics 記錄最終選擇，以便子代理繼承它們。

閘門只有在使用者要求時才會被跳過；當有疑慮時，就停止。一個 STOP 是真實的：結束該回合並等待。 對於每個被跳過的閘門，附加到 DIR/DECISIONS.md：閘門、決定了什麼、你權衡過的替代方案，以及你審查過的圖片路徑。在最終報告中連結 DECISIONS.md，以便使用者可以審計。 永遠不要跳過步驟 8 中的最終 ffprobe 檢查和歌詞/影格抽檢：那些是驗證，而不是批准。

工作流程（按順序執行；除非標記跳過，否則 STOP 是真實的）

1. 專案。 在任何儲存庫之外建立專案資料夾：PARENT/<歌曲-slug>/，其中 PARENT 是 --dir（預設 ~/PROJECTS），並將歌曲移動到其 assets/ 中。將參考照片（--human）放在 PARENT/_shared/ 中。 bash ~/.claude/skills/music-video/scripts/setup_project.sh PARENT/<歌曲-slug> 這會複製 UPSTREAM_PIN 處的 ClaudeAnimationBase，新增 src/cast.js（Pip、道具、卡拉 OK）並整合卡拉 OK。 它需要 Node 20+、Chrome、ffmpeg、uv 和 git。
2. 分析。 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 可能會是感覺節奏的兩倍（低相干性，一行歌詞等於兩個「小節」）：在分鏡腳本中註明感覺節奏，並對感覺節拍使用 bt(2k)。 2b. 面談（G0）。 僅在每個選擇都已設定或給出了 --auto/--no-interview 時跳過。否則：
   • 先展示風格，用圖片。 如果 --style 未設定，渲染比較靜態圖：node design/style_tests.mjs（由 setup 複製）會以 editorial、keynote、geometric 和 hybrid 風格繪製同一個歌詞時刻（--line1/--line2/--stamp 設定文字），輸出到 out/design/style_test_*.jpg 和 style_tests_all.jpg。發送它們，如果使用者尚未看過，再加上 zoo2 範例中的一個 painted 風格影格。人們無法從文字中選擇風格。
   • 然後在一個 AskUserQuestion 輪次中詢問其餘未設定的選擇（lyrics、density、human），以及分鏡腳本無法單獨決定的歌曲特定問題：如何忠實地呈現真實品牌或產品，以及如何呈現敏感的歌詞行（暴力、醜聞、真實事件）。
   • 重用而非重繪： 如果 PARENT/_shared/cast/ 已經有這個人的角色（例如 <name>.js + <name>_body.js，在先前的影片中獲得批准），將這些檔案複製到 src/vec/，在 vec.js 之後新增它們的 <script> 標籤，並按原樣使用（包含表情和姿勢控制）。僅在使用者要求更改時才重繪。在新角色獲得批准後，將他們的檔案複製到 PARENT/_shared/cast/（並在 _shared/README.md 中新增一行），以便下一部影片重用。
   • 對於新的 --human 照片，查看它並將漫畫特徵寫入 STORYBOARD.md（頭型、頭髮或無、鬍鬚、眉毛、眼睛、通常的穿著）。根據特徵繪製；永遠不要將照片描圖或貼到影片中。 G0 — 停止 在發送靜態圖和問題之後。將答案組合成選擇，然後繼續。
3. 閱讀 DIR/ANIMATION_GUIDE.md（工具箱的規則）、LESSONS.md 和一個範例章節 （examples/zoo2/scenes/c01_pilot.js）在編寫任何內容之前。對於 向量風格（painted 以外的任何風格），指南的引擎部分仍然適用（時間線、shots()、攝影機、緩動、節拍、審查迴圈），但其外觀規則則相反：請參閱向量風格。
4. 分鏡腳本。 撰寫 DIR/STORYBOARD.md（格式：examples/zoo2/STORYBOARD.md），包含劇情摘要、角色、色板弧線、主題、整首歌的章節表格，以及試播的逐個鏡頭和計時「讀取」。 影像密度遵循 --density（bold：每 2–4 行一個強烈畫面，其餘作為背景彩蛋；every-line：每行一個，由角色演出）。G1 — 停止：向使用者展示並等待批准 （使用 --skip=storyboard/all：自我批評，記錄到 DECISIONS.md，繼續）。 4b. 設計（僅限 --design）。 在任何動畫之前，先在 out/design/ 中以靜態圖確定外觀：
   • cast_<name>.jpg 每個角色的模型表：正面、四分之三側面和側面，4 種表情（中性、喜悅、恐懼、決心），來自分鏡腳本的 3 種動作姿勢，以及一個所有角色身高比較圖；
   • palette.jpg：每個章節的色板條，顯示歌曲中的色板弧線；
   • style_<chapter>.jpg：每個章節在分鏡腳本英雄時刻的一個完成關鍵影格，附有歌詞。 使用一次性 scenes/design.js（一個僅限模型表的章節，在歌曲時間範圍之外）以及 node render.mjs --sheet=... 來繪製它們；角色程式碼放在 src/cast.js 的新增部分中，章節將重複使用這些程式碼，因此批准的設計會直接帶入影片中。G2 — 停止： 展示模型表；記錄意見（「眼睛大一點」、「副歌色板溫暖一點」），重新渲染，重複直到使用者批准。然後更新 STORYBOARD.md 以符合。
5. 試播。 選取約 30 秒，跨越一個段落邊界進入副歌。將其建構為一個章節檔案，並在 window.SETS 上匯出共享集合（參見 c01_pilot.js 的結尾）。使用 node render.mjs --sheet=... --out=out/check/x.jpg 和 --strip=a:b 檢查它，並觀看圖片。常見的首次建構錯誤：角色太小（將攝影機推近至 1.3–1.5 倍）、背景形狀不夠寬以容納橫搖拍攝、道具被卡拉 OK 列隱藏。對於向量風格，建立在 src/scenes/sets.js 上（setup 會複製一個可用的：房間、窗戶、走廊、捲軸、情緒混合；使其適應）。使用 node render.mjs --clip --range=a:b --out=out/pilot.mp4 渲染。 G3 — 停止：使用者觀看它並批准或提出修改（使用 --skip=pilot/all：兩次審查，記錄到 DECISIONS.md，繼續）。
6. 並行章節。 首先為每個章節新增存根檔案及其在 studio.html 中的 <script> 標籤（代理不得編輯共享檔案）。然後為每個章節啟動一個子代理（fork 類型，以便繼承此上下文）。給予每個子代理其時間範圍、其歌詞行、來自分鏡腳本的章節簡報、「僅限您的檔案」、共享的 SETS 和全域變數，以及接縫約定：
   • 在章節之間，一個在兩側使用相同顏色的過渡（painted：brushWipe，在最後 0.3 秒輸出 p<.5，輸入 .5+lt/.6；向量：V.wipe，請參閱 CHAPTER_BRIEF.md）

...