music-video
將一首完成的作品轉換成 24fps 的音樂影片。歌曲為主音軌，場景區間必須恰好覆蓋整首歌曲一次。
觸發詞
- music video / MV / lyric video / visualizer / storyboard
- 音乐视频 / MV合成 / 歌词动画 / 歌曲动画
能力
code：初始化一個固定版本的 p5.js 與 p5.brush 專案，然後用 JavaScript 製作動畫。hybrid：檢查本地的角色圖片、場景靜態畫面與影片剪輯，然後組合它們。不呼叫任何圖片或影片生成 API。- 本地分析節拍、起始點、低頻與音量，作為剪接點與動畫提示。
- 以原始歌曲為唯一配樂，進行畫格級的精準組合。
輸入
必要項目：
song：本機音檔（.mp3、.wav、.m4a、.flac、.ogg、.aac）brief：視覺概念、目標觀眾與所需的參考資料mode：code或hybrid
選擇性項目：
lyrics：純文字檔或.srt。當人聲節奏很重要時，在分鏡前必須提供。assets：hybrid模式用的靜態畫面與剪輯目錄。aspect：16:9（預設）、9:16、1:1或4:3
如果使用者想先製作一首歌，請使用 text-to-music，然後再回到此處並帶入所選檔案。
輸出
<project>/output/final.mp4docs/CREATIVE_BRIEF.md、docs/STORYBOARD.md、docs/TASKS.md與docs/PROGRESS.mdaudio/analysis.json，以及當有資產時會產生的docs/inspect.json
工作流程
從版本庫根目錄執行 python3 skills/music-video/scripts/mv.py。如果此技能安裝在其他位置，請使用此檔案旁邊的 scripts/mv.py。請在技能目錄之外建立專案。
- 當影片是用 JavaScript 繪製時，選擇
code。當使用者提供靜態畫面或剪輯時，選擇hybrid。若兩者皆不明確，則詢問一次。 - 初始化一個隔離的專案：
python3 skills/music-video/scripts/mv.py init \
--project ./mv-project --song ./song.mp3 --lyrics ./lyrics.txt --mode code
python3 skills/music-video/scripts/mv.py init \
--project ./mv-project --song ./song.mp3 --lyrics ./lyrics.srt \
--assets ./clips --mode hybrid --aspect 16:9
- 分析歌曲。將節奏變化視為近似值，並從音訊中確認段落邊界：
python3 skills/music-video/scripts/mv.py analyze --project ./mv-project
- 取得歌詞時間。如果使用者未提供，僅在
NOIZ_API_KEY或~/.config/noiz/api_key已存在時使用 speech-to-text。切勿印出金鑰。如果兩者皆不存在，請向使用者索取歌詞或時間戳記，並且不要上傳歌曲。 - 閱讀 references/opus-5.5-prompt.md 並遵循其指示。在編寫場景程式碼或組合之前，先撰寫創意簡報與分鏡腳本。在構建其他章節之前，先檢視開場與主要高潮。
- 在
code模式下，在繪製之前先閱讀<project>/animation/ANIMATION_GUIDE.md。從audio/analysis.json設定PROJECT.bpm與PROJECT.offset。固定模板畫布為 1920×1080；若使用其他長寬比，請先修改studio.html與渲染器視窗。使用模板渲染器檢查動態：
node render.mjs --sheet=1,2,3 --out=../output/sheets/pilot.jpg
node render.mjs --strip=START:END --out=../output/sheets/pilot-motion.jpg
node render.mjs --clip --range=START:END --out=../output/pilots/opening.mp4
在 <project>/animation 內部執行這些指令。當 Chrome 不在標準位置時，傳遞 --chrome 或設定 CHROME_PATH。聯絡表僅用於檢查佈局。--strip 或播放開場、高潮與結尾則是動態審查。
7. 在 hybrid 模式下，檢查本地媒體，如果缺少必要剪輯則停止。不要產生替代片段。
python3 skills/music-video/scripts/mv.py inspect --project ./mv-project
- 使用 references/timeline.schema.json 撰寫
timeline.json。區間在start_frame包含，在end_frame不包含。 - 組合並檢查結果：
python3 skills/music-video/scripts/mv.py assemble --project ./mv-project
時間線
{
"fps": 24,
"width": 1920,
"height": 1080,
"audio": "audio/source.mp3",
"scenes": [
{
"id": "opening",
"start_frame": 0,
"end_frame": 240,
"source": "output/pilots/opening.mp4",
"source_start": 0,
"fit": "cover",
"transition": "fade",
"fade_frames": 6
}
],
"overlays": []
}
fade 僅在其所屬場景內部生效。不要重疊場景來建立交叉淡出。
完成
僅在所有項目皆為真時才算完成：
[0, ceil(duration × 24))被恰好覆蓋一次，無間隙或重疊。final.mp4包含一個視訊串流與完整的原始歌曲。- 開場、主要高潮與結尾已透過動態方式審查。
- 最後閱讀的故事有時間結束。
docs/PROGRESS.md中沒有未解決的阻礙。
安全
init --mode code 會將 JohnHeibel/ClaudeAnimationBase 在提交 0ac8bf2b31942376cb6b8c4074715595d512acd2 的版本複製到專案中。該模板採用 MIT 授權。分析、檢查、渲染與組合均在本地進行。Hybrid 模式不會上傳媒體，也不會呼叫圖片、影片或音樂生成服務。
需求
ffmpeg與ffprobe- Python 3.9+
analyze：uv pip install 'numpy>=2,<3'code模式：git、Node.js 與 Google Chromehybrid模式：僅限本地資產
限制
- 此技能不作曲、不產生音效，也不透過 API 建立圖片或影片。
- 節拍網格假設節奏大致穩定。
- 在 code 模式下，若沒有獨立 GPU，水彩填色可能耗費數秒。請在整合式顯示卡上要求渲染器避免此類填色。
- 組合時會拒絕比場景時長還短的剪輯，而不是凍結或重新調整其時間。