電影級音樂影片導演
一個用於製作以歌曲為脊柱的、值得觀看的短片的生產技能——不是歌詞模板、不是幻燈片、也不是一堆不相關的生成片段。每一幀都由程式繪製，並且可以從整數幀號重現。
此技能刻意以音樂優先和證據優先：
- 在想像畫面之前先測量歌曲；
- 在撰寫任何一個鏡頭之前先撰寫論文和導演分數；
- 在渲染之前鎖定一個幀精確的剪輯；
- 透過 10-20 秒的試播片證明樣式和動態；
- 以可續接的鏡頭單位渲染；
- 驗證你實際輸出的檔案。
鐵則： 絕不發明時間戳、BPM、歌詞行、渲染結果或 QC 通過項。 如果缺少證據，將該項目標記為
unverified並在交付說明中說明。
何時使用
當使用者要求製作音樂影片、依音樂剪輯的動畫短片、片頭序列，或「將我的歌曲變成電影」這類任務，且接受在本機端渲染時使用。預設輸出為 9:16，1080×1920，24 fps，H.264 + AAC，並可選配外掛字幕檔。
不要使用此技能下載受版權保護的音訊、複製在世藝術家的肖像，或逐鏡頭重現既有的 MV。請詢問使用者他們擁有使用權的音訊。
先決條件（檢查，不要假設）
- Node 20+、ffmpeg/ffprobe、Google Chrome 或 Chromium。
- Python 3.10–3.13，安裝
numpy scipy soundfile librosa（matplotlib 為選用，Pillow 用於工作表）。 - 專案
node_modules中的puppeteer-core、p5、p5.brush。 - 足夠的磁碟空間存放幀：1080×1920 JPEG q94 ≈ 0.2–0.5 MB/幀；一部 4 分鐘的影片約需 1–3 GB。
- 對於中文歌詞，需要使用者提供的 LRC/SRT 檔案，或本機端的 Whisper 模型；絕不要爬取並將隨機歌詞網站的時間標記呈現為已驗證。
執行 scripts/doctor.sh（或 references/render-recovery.md 中的等效指令）並記錄結果。如果缺少某個先決條件，請修復它或報告阻礙。
生產循環
0. 接收與權利
收集：音訊路徑、歌詞文字與任何時間標記檔案、畫面比例/解析度/fps、截止日期、語言以及使用情境。將音訊以唯讀方式複製到 assets/；絕不覆蓋原始檔。在 README.md 中陳述權利假設（例如「使用者提供的音訊，僅供私人使用」）。
1. 音樂主檔（閘道 M）
python scripts/analyze_music.py assets/song.m4a \
--out analysis --lrc assets/song.lrc --sections analysis/sections.json \
--asr analysis/asr/whisper.json --fps 24
產生 analysis/audiomap.json、lyrics.json、lyrics.srt、analysis.md、analysis.png。
該映射包含時長、相位擬合的速度網格、節拍/強拍、能量/頻譜曲線、候選高潮視窗、段落範圍，以及帶有來源證明的逐行歌詞時間標記。
驗收標準：
- 時長和取樣率與提供的檔案相符；
- 報告速度一致性；如果 < 0.6，透過聆聽/頻譜圖檢查，並考慮製作速度映射；
- 每一行歌詞都有一個時間來源（
lrc_line、srt_line、cross_checked、untimed）； - 不得在未經結構性交叉檢查的情況下，將響度視為情緒高潮。
如果使用者未提供歌詞時間標記，則使用本機 ASR 轉寫稿執行 scripts/align_lyrics.py 並審查結果。將短語時間（小節/短語標記，用於剪輯）與聲音起始點（用於字幕）分開處理。切勿為了讓剪輯看起來整齊而靜默地移動整首歌。
2. 三個概念，然後選一個（閘道 D1）
撰寫 storyboard/concepts.md，包含三個真正不同的電影。根據歌詞/音樂契合度、故事完整性、情感衝擊、視覺原創性、程式碼可行性以及長時間觀看性為每個概念評分。選擇一個並寫下理由。在完成此步驟之前，不要開始鏡頭程式碼。
然後撰寫 storyboard/director_score.json：
論點、反論點、情感曲線、視覺章節（世界/調色盤/空間/攝影機/語法）、對比圖、母題與回報、角色想要/需要/弧線、鏡頭角色與交接、聲音-視覺對應圖。
一個不能說明其角色、進入交接和離開交接的鏡頭就是尚未準備就緒。
3. 視覺語言與測試（閘道 D2）
在開始動畫之前，先撰寫 style-guide.md 和角色/美術聖經。定義：
包含十六進位色值和顏色指令碼的調色盤；9:16 的鏡頭語言/構圖語法；線條與紋理規則；角色比例、剪影、服裝連續性與表情範圍；燈光；轉場詞彙；電影不會做的確切事情（例如「沒有無敘事原因的浮動粒子」）。
渲染 1–3 個風格幀和一張角色表。以全解析度判斷它們，而不是縮圖。如果外觀不佳，現在就改變語言——而不是在 40 個鏡頭之後。
4. 幀精確剪輯（閘道 E）
撰寫 storyboard/timeline.json，包含 fps、total_frames、shots[]，以及每個鏡頭的：
id, start_frame, end_frame, section, lyric_refs, size, composition, environment, action, expression, camera, transition_in/out, emotion, function, implementation, complexity。
鏡頭必須是連續的並覆蓋整個音訊。
python scripts/validate_timeline.py \
--timeline storyboard/timeline.json --audiomap analysis/audiomap.json \
--out analysis/timeline_validation.md
驗證器是一個硬性閘道：無間隙、無重疊、最後一幀 ≥ ceil(時長×fps)、每一行歌詞都已計入、沒有剪輯點不合理地遠離節拍/歌詞/段落而無書面理由。
5. 試播片（閘道 P）
渲染 10–20 秒，至少包含：一個廣角定場鏡頭、一個角色中景、一個特寫、一個快速動作或撞擊，以及一個轉場。建立一份聯絡表與一個包含真實音訊的可觀看片段。檢查：
- 風格在 100% 顯示下是否成立？
- 角色比例、服裝和燈光是否連續？
- 攝影機運鏡是否有動機，還是無緣無故地漂移？
- 剪輯點是否落在音樂事件上？
- 渲染器在沒有例外的情況下能否存活超過 300 幀？
- 測量到的毫秒/幀和磁碟成本是多少？
在進行完整傳遞之前修正試播片。將測量到的效能記錄在 LESSONS.md 中。
6. 完整渲染（閘道 R）
使用確定性頁面合約：window.renderAt(t) -> dataURL，無 Math.random、使用種子雜訊、整數幀索引。逐鏡頭或逐幀進行原子寫入渲染；維護已完成單元的清單與雜湊值，以便變更的鏡頭只會使其自身失效。
node scripts/render.mjs --project . --start 0 --end 232.6 --out renders/frames
偏好使用逐鏡頭單位以及 --force/--shot 路徑，而不是「刪除所有內容然後重來」。不要重新渲染同一個已批准的鏡頭兩次。絕不讓失敗的幀通過被視為完成：一個幀必須存在、非零且可解碼。
7. 組裝（閘道 A）
ffmpeg -y -framerate 24 -i renders/frames/f_%06d.jpg -i assets/song.m4a \
-c:v libx264 -preset slow -crf 16 -pix_fmt yuv420p -profile:v high -level 4.2 \
-c:a aac -b:a 256k -ar 44100 -shortest -movflags +faststart output/final.mp4
主音訊是不可變的。不要為了配合畫面而對歌曲進行淡入淡出、重新計時或重新編碼。最後一個鏡頭必須覆蓋音訊尾聲；不可有黑色尾聲，也不可有被截斷的最後和弦。
8. QC（閘道 Q）
兩者都執行，並附上證據：
python scripts/qc_video.py output/final.mp4 --audio assets/song.m4a \
--expected-frames 5583 --timeline storyboard/timeline.json --out analysis/qc
技術方面：解碼、時長與音訊比對（容差 ≤ 0.12 秒）、串流數量、解析度、fps、pix_fmt、幀數、blackdetect、freezedetect、覆蓋率、遺失/佔位幀。 視覺方面：全解析度聯絡表、每場景關鍵幀、剪輯點處的連續幀條、AV 同步抽查、角色連續性檢查、標題/字幕安全區。
視覺 QC 無法自動化。 明確陳述你觀看了哪些鏡頭、在什麼解析度下觀看，以及你的發現。一個乾淨的 ffprobe 輸出不等於視覺檢查通過。
9. 交付
提供：主 MP4、低解析度預覽、storyboard.md、timeline.json、style-guide.md、qc-report.md、README.md、可選的 SRT 檔案，以及可重現的原始碼。除非使用者擁有發布權利，否則將音訊和歌詞保留在本機端。新增一個帶有日期的 LESSONS.md 條目。
檔案合約
project/
assets/ # song.m4a, lyrics.lrc/srt, 使用者提供的參考資料（勿覆蓋）
analysis/ # audiomap.json, lyrics.json, sections.json, 驗證, QC
storyboard/ # concepts.md, director_score.json, timeline.json, storyboard.md
characters/ # 美術聖經, 角色模型表
src/ # 確定性繪圖程式碼: lib/, custom_shots.js, shots.js
studio.html # window.renderAt(t) 合約
renders/ # frames/ (全域序列), pilot/, manifests
previews/ # pilot.mp4, 聯絡表, 審查板
output/ # 最終 MP4, 預覽, SRT, storyboard.md, timeline.json, style-guide.md, QC
不可協商的工藝規則
- 歌曲是主時間軸。畫面是為音樂剪輯的；音樂絕不為畫面剪輯。
- 一部電影，不是一個外觀的播放清單。母題會重現並改變。
- 重複的副歌在視覺上可以押韻；但不能一成不變地使用相同的構圖。
- 角色需要慾望、障礙、選擇、後果。臉部和手部必須有表演。
- 攝影機運鏡需要動機（揭示、壓力、釋放），而不是預設的 Ken Burns 效果。
- 每個鏡頭必須包含至少一個屬於故事世界的移動元素。
- 不要用粒子、速度曲線或無謂的輝光來掩蓋缺失的故事。
- 如果誠實的結果是風格化且有限的，請在 QC 報告中說明；不要稱之為寫實。
故障與恢復
渲染器被設計為大聲失敗並廉價恢復：
- 原子幀寫入（
*.tmp→ 重新命名），絕不將一半的 JPEG 計為已完成； - 每個鏡頭一個清單，包含原始碼雜湊值、開始/結束幀與狀態；
--shot/--start/--end僅重新渲染受影響的範圍；- 保留最後一次已知良好的編碼；在 QC 通過之前，絕不覆蓋主檔案。
如果瀏覽器或 GPU 當機，使用新的頁面/設定檔重試該單元兩次。如果一個幀失敗三次，停止，隔離該鏡頭，並回報幀號與錯誤。不要用重複的幀或靜止畫來填補。
參考資料索引
references/directing.md— 概念選擇、導演分數、時長、節奏、結局。references/visual-language.md— 9:16 構圖、攝影機、色彩、角色、紋理。references/audio-lyrics.md— 測量、相位擬合速度、段落、誠實對齊。references/render-recovery.md— 確定性合約、清單、編碼、續接。references/qc.md— 硬/軟閘道、聯絡表、自動化無法看到的東西。templates/— 導演分數、時間軸、鏡頭卡、樣式指南、專案設定。tests/— 解析器、覆蓋率和驗證器測試；執行bash tests/run_tests.sh。LESSONS.md— 在實際生產中什麼出了問題以及什麼修復了它。
鳴謝與授權
引擎模式參考了使用 MIT 授權的 ClaudeAnimationBase (John Heibel) 和 claude-music-video-skill (Sage Arbor)。工作流程概念研究自 musical-mv-storyboard，該項目無授權；未從中複製任何程式碼或文字。請參閱 THIRD_PARTY_LICENSES.md。p5 使用 LGPL-2.1、p5.brush 使用 MIT、puppeteer-core 使用 Apache-2.0、librosa 使用 ISC、ffmpeg 使用 GPL。專案中使用的歌曲和歌詞不屬於此技能的一部分。