音樂影片（動態圖形）
您無法聽見歌曲。所有視覺元素都與測量數據同步，因此首要任務永遠是建立歌曲資料夾。如果歌曲資料錯誤，每個影格都會跟著錯。
輔助工具位於此檔案旁。使用技能資料夾中的 run.py 執行它們（預設安裝路徑如下；若安裝在其他位置請自行調整）：
python3 ~/.claude/skills/music-video/run.py song-folder SONG.mp3 OUT_DIR [--fps 30] [--lyrics-lang en|tr] [--lyrics-text known.txt]
python3 ~/.claude/skills/music-video/run.py analyze SONG.mp3 # beats/bars/sections as JSON
python3 ~/.claude/skills/music-video/run.py dance2d SONG.mp3 --out DIR --analysis OUT_DIR/song-map.json --start 23.8 --dur 14.3 [--render]
切勿聲稱已聽過該歌曲。請說「根據分析結果」。
1. 歌曲資料夾（永遠優先）
| 檔案 | 內容 | 工具 |
|---|---|---|
| passage.<副檔名> | 音訊檔案，位元組完全相同的副本（sha256 檢查）；在最終合成時直接使用 | — |
| song-map.json / .md | bpm、節拍、強拍/小節、能量段落（平靜/堆疊/高潮）、每拍能量、下降段落 | Beat This! → aubio CLI → 內建 numpy 追蹤器 |
| stems/ | 人聲 / 鼓組 / 貝斯 / 其他（快取，重新執行很快） | demucs htdemucs（可選） |
| envelopes.json | 混音及每個音軌的逐幀音量（dB 及 0..1） | numpy |
| hits.json | 大鼓 / 小鼓 / 鈸的擊發點，強度 0..1 | 對鼓組音軌進行分頻譜通量分析 |
| notes.json | 旋律與貝斯音符（可選） | basic-pitch |
| lyrics-passage.json / .md | 帶有時間戳的歌詞行 | 對人聲音軌使用 whisper.cpp whisper-cli |
| song-story.md | 您需填寫的範本：主題、風格、情緒曲線、每個段落的關鍵畫面 | 您根據歌詞和地圖填入 |
| README.md | 每個檔案的說明、單位（秒）、fps | 自動產生 |
規則：
- 段落是由能量短語構成（根據歌曲自身能量排序的兩小節短語），而非主歌/副歌。 請在 song-story.md 中自行命名。
--lyrics-text搭配正確歌詞（每行一句）可將歌詞與 whisper 辨識出的單字時間對齊；無法匹配的單字會獲得插值時間（matched: false）。若不提供此參數，則歌詞為 raw whisper 輸出，請務必檢查。當人聲音軌為靜音時，歌詞行會被標記為suspect（whisper 會在純音樂段落產生幻覺）。純音樂歌曲會跳過 whisper。- 每個耗費資源的步驟都會降級執行而非直接失敗：沒有 Beat This! → aubio（外部 CLI）→ numpy 追蹤器（無真實強拍，預設為 4/4 拍）；沒有 demucs → 僅使用混音的 envelopes 和 hits；沒有 basic-pitch → 無 notes.json；沒有 whisper → 無歌詞。執行報告中的
warnings會說明跳過了哪些步驟。請告知使用者。 - hits.json 足夠用於觸發閃爍、震動和縮放效果，但並非專業的鼓組轉錄：鈸的擊發也可能在小鼓上被觸發，貝斯音符可能洩漏到小鼓頻段。
- song-story.md 在重新執行時不會被覆寫。請只寫入歌詞和分析能支持的內容；若不明確，請在標題處留下「未知」，切勿憑空編造含義。
2. 創意規劃（在渲染前展示）
- 一個來自 song-story.md 的概念，一個世界，一個色調，一個開放授權字型（OFL）用於歌詞排版。
- 段落 → 場景表格：段落切換 = 場景或鏡頭切換；副歌 / 最高能量段落使用最大的視覺創意，每次重複時略有變化；下降段落 = 在強拍上進行切換、閃爍或縮放。
- 歌詞排版僅用於關鍵句子（根據其單字時間進行動態字詞排版），而非每句都做卡拉 OK。
- 在平靜音樂時，根據短語和能量節奏進行；不要對每個追蹤到的節拍進行硬切。不同處理方式的數量比剪輯的次數更重要。
- 展示規劃（表格 + 3–4 張描述或渲染的靜止畫面）並獲得同意後再進行完整渲染。
- 值得先閱讀的基礎建設：HyperFrames 自己的
music-to-video技能（github.com/heygen-com/hyperframes，skills/music-to-video/，Apache-2.0）包含一系列節拍剪輯動態原語（閃切、急推、甩鏡、色差、螢幕震動、動態字母……）和歌詞佈局。
3. 內建 2D 舞蹈影片
外觀：扁平角色（圓形黑色頭部、圓角線條四肢、彩色襯衫和鞋子）、拱形鏡門、旋轉的太陽光背景（紫色 / 藍綠色 / 金色 / 粉紅色）、粗體窄版字型（Anton）的歌詞字詞及一個強調詞、一排不同顏色的鏡像舞者複製體、電影膠卷、皇冠和西洋棋道具。靈感來自 Devarf 的 YouTube 實驗中「低投入」2D 影片系列（每個製作投入程度都做一支音樂影片）。
規劃器（musicvideo/dance2d.py，純函數且使用種子亂數）：
- 視窗在強拍上進行切換；每拍一個姿勢關鍵影格，姿勢在該拍上到達；
- 強拍使用大姿勢（堆疊：舉手 / 指 / 拍手，高潮：跳躍 / 舉手）和一個完整的屈膝；
- 動作集（一個 4 拍短語）根據能量等級每小節變換，且不會連續重複兩次；
- 場景在段落開頭和每 4 個小節進行切換（色調切換、太陽光速度根據等級變化、方向交替；平靜/堆疊段落使用門，高潮段落使用西洋棋 + 5 個舞者排，領舞者戴皇冠）；
- 舞者複製數量：平靜 1 個，堆疊 3 個，高潮 5 個；
- 歌詞 JSON
[{start, end, text, accent}]以視窗時間為單位 → 每個字詞落在一個節拍上。
骨架（runtime/char2d.js，window.Char2D）：具有樞紐點的 SVG 群組（臀部 > 大腿 > 小腿 > 腳、軀幹 > 手臂 > 前臂、頭部）。肢體角度為向外延伸的正角度（0 度向下，90 度側向，180 度向上），使一個姿勢適用於兩側；地面鎖定功能讓下方腳掌保持在地板上（蹲下動作自動下沈），air 屬性用於跳躍時抬起。姿勢：idle、stepL/R、armsUp、swayL/R、pointL/R、clap、jump、squat、handsOnHips（mirror(p) 交換左右）。poseAt(keys, t) 保持姿勢，然後在最後 ≤0.26 秒內緩入，並在重大擊打點加入超調。runtime/dance2d.js 從 window.MV_DANCE 繪製規劃；一個 GSAP 時間軸驅動代理 setter → draw(t)，因此每個影格都是 t 的純函數。
dance2d 的輸出：DIR/plan.json 和 DIR/project/（一個 HyperFrames 專案）。使用 --render 參數還會輸出 DIR/dance2d.mp4：1920×1080、30 fps、H.264 yuv420p、歌曲音訊（AAC，無淡入淡出）。使用 CC BY 授權的音樂需在畫面上顯示 --credit。
渲染與否由使用者決定。 --render 會執行 npx hyperframes render，它會下載並驅動一個無頭 Chrome/Chromium。請在使用前詢問。若不使用此參數，僅使用 Python 即可完成專案資料夾前的所有步驟。GSAP 未隨附。請將 gsap.min.js 放入 runtime/（或設定 MV_GSAP），否則專案會在渲染時從 jsDelivr CDN 載入 GSAP 3.14.2。
4. 內建骨架以外的角色（自備）
本技能不附帶任何 3D 模型。如果使用者想要 3D（Three.js）角色：
- 請使用授權允許在完成的影片中重新分發的模型，例如 CC0 模型，或使用者從自己的 Mixamo 帳戶下載的角色和動畫（在完成的影片中可以；原始檔案不得重新分發或提交到公開儲存庫）；
- 切勿在未檢查授權的情況下複製其他專案的範例模型；
- 或者只使用程序生成的幾何體（膠囊體、球體、盒子組成的簡單骨骼鏈），這些完全沒有授權問題。
幀確定性仍然適用：每一幀使用
mixer.setTime(t * rate)，切勿使用mixer.update(dt)；rate = song_bpm / clip_bpm；在小節邊界切換片段。
5. 渲染規則（任何渲染器）
- 一切都是
t = frame / fps的純函數。沒有Date、沒有requestAnimationFrame的 delta 值、沒有未使用種子亂數的Math.random()。 - 小型擊打效果（鏡頭震動、燈光閃爍、縮放彈出）根據 hits.json 中的大鼓/小鼓觸發；亮度或光暈根據 envelopes.json 觸發。
- 輸出：1920×1080（或 Reels/Shorts 用的 1080×1920）、30 fps、H.264 yuv420p、AAC、長度與歌曲相同（或選擇的視窗長度）。
- 光敏感性：每秒鐘全畫格閃爍不超過 3 次。
- 預算：更多的思考時間能產生更好的動作，但請在一次工作階段內進行審查。對單一音樂影片進行多次代理審查循環會快速消耗 Token，且往往在達到限制後重新開始。
6. 交付前檢查
- 影片能播放到最後；時長 == 歌曲（或視窗）時長 ±1 影格。
- 音訊串流為原始歌曲（比較解碼後的 PCM 雜湊值，或檢查延遲為 0 的互相關峰值）。
- 同步點抽查：在副歌強拍處渲染 5 個影格，並確認擊打姿勢 / 閃爍是否準確落在該處。
- 每個段落生成一張接觸表（
ffmpeg -i out.mp4 -vf "fps=1,scale=480:-1,tile=4x4" sheet.jpg）並確實檢視。 report.md：說明您製作了什麼、為什麼、如何製作、檢查了哪些項目，以及您不確定的地方。