vvai-pixel-mv · 像素小人卡拍 MV
順序固定：故事線 → 分鏡表（用戶看、改，可以來回多次）→ 用戶確認 → 出片。沒有經過用戶確認的分鏡，不渲染。
完整範例在 assets/examples/：一首歌的故事線和 story.json，7 段、3 個角色、帶桌面視窗。
準備
PY：安裝了 librosa、faster-whisper、numpy、Pillow 的 Python 3.10 以上，安裝見 INSTALL.md。用戶的 CLAUDE.md 或記憶裡寫了 Python 路徑時用那個；沒寫就先確認python能導入這幾個套件，不行再問用戶。MV：PY -X utf8 <本 skill>/scripts/pixel_mv.py。- 需要 ffmpeg、Node。渲染預設走
npx --yes [email protected]；要換 CLI 時設定環境變數HF_CLI，多個參數用|隔開。
流程
- 收素材。必須有音頻、帶時間的歌詞（srt 或 lrc）和歌名。
- 可選：截取起止秒、調色檔（base / neon / classic / retro）、強度（dj / standard / soft）、角色圖。
- 還要問故事：用戶心裡有沒有劇情？沒有就在第 3 步提方案。
- 沒有歌詞檔案就向用戶要，不要用轉寫去猜。轉寫不出人聲的段落要先問用戶，不能當成前奏。第 1 集就把主歌誤判成了前奏。
- 建工程：
MV new <工程目錄> --audio <音頻> --lyrics <srt/lrc> --title <歌名> [--start 秒 --end 秒] [--look base] [--character 圖片]。- 這一步會剪音頻、測節拍和能量高點、逐字對齊歌詞。
- 同時生成一份只按關鍵字換場的初稿
story.json，以及故事線.md模板。 - 工程放在用戶指定的目錄；用戶有固定的系列目錄時（寫在 CLAUDE.md 或記憶裡）放那裡。
- 寫故事線。按 講故事的方法 填
故事線.md：一句話故事、角色、母題、分幕、逐句。給用戶確認。 - 寫 story.json。把故事線翻成 story.json。
- 出分鏡表給用戶看。
- 執行
MV board <工程> --frames：每段截 1–3 張畫面，生成分鏡表.md，內容有總覽、逐段的角色、劇情動作、歌詞句號和出現方式、轉場、鏡頭、卡點。 - 用 SendUserFile 把
分鏡表.md和分鏡/畫面/裡的 contact sheet 發送給用戶。 - 告訴用戶哪些地方可以改。
- 執行
- 改到滿意。用戶提修改，就改 story.json，再執行
board。- 版本號自動加 1，舊版存在
分鏡/歷史/。 - 可以來回多次，每次都把新版分鏡表發送給用戶。
- 版本號自動加 1，舊版存在
- 確認後出片。
- 用戶明確說「可以出片」，才執行
MV approve <工程>，再執行MV render <工程> --sample 12。 - 含糊的回覆（「好的」「看著辦」）不算確認。
render會核對 story.json 指紋，確認後又改過就拒絕渲染。- 超過 30 MB 的另壓一份
_預覽.mp4給手機。
- 用戶明確說「可以出片」，才執行
- 交付。按 1 幀/秒拼圖自己看一遍：故事看得懂，場景、歌詞、轉場、標題都在，時長和原音頻一致、有音軌。
- 出片後用戶還要改，回到第 6 步：改 story.json → 出新版分鏡表 → 再確認 → 再渲染。
關鍵規則
- 故事先於特效。每句至少一個劇情動作或一種歌詞互動；劇情動作落在關鍵字的時間上；轉場要有劇情理由。詳見 講故事的方法。
- 換場：沒有故事要求時，預設「桌面為主 + 意象插入」，見 分鏡規則。有故事時按分幕來，覺悟、回看類的段落用電腦桌面視窗視角。
- 角色：
- 預設 Claude 小人當「我」。
- 其他角色用
cast宣告（girl、rival、friend、ghost）。 - 用戶給圖時執行
MV character <工程> <圖片>，轉成 16×16 像素角色。
- 卡拍：
- 小人每拍正好落地，落地壓扁，腳下擴散水波。
- 每拍有鏡頭衝擊和色閃，強拍加 RGB 分離。
- 全螢幕閃白只放在轉場和 drop 上，每秒不超過 3 次。
- 受驚反應包全片最多 2 次，只放在真正的反轉上。
- 歌詞正文：
- 只出現在畫面裡和工程檔案裡；聊天回覆和分鏡表只寫句號。
- 歌曲版權由用戶負責，發布前提醒一句。
命令一覽
| 命令 | 作用 |
|---|---|
new | 建工程：analyze + align + draft + story |
story | 生成 故事線.md 模板（--force 重建） |
check | 檢查 story.json 裡的名字、時間、視窗是否都是引擎認識的 |
board [--frames] | 出分鏡表（第 N 版），存歷史 |
approve | 記下用戶確認的版本；之後 render 才放行 |
render [--sample 12] [--name 檔名] | 渲染；--force 跳過確認，只在用戶明說時用 |
sync | 只同步 story.json → assets/story.js（除錯用；board 和 render 會自動同步） |
upgrade | 把舊工程換成目前模板引擎，舊檔案留 .before-upgrade 備份 |
character | 角色圖 → 像素角色 |
analyze / align / draft | new 的分步，單獨重跑用 |
超出模板的客製化
模板引擎 v2 已經覆蓋下面這些，見 互動目錄：
- 27 個場景、16 種基礎動作；
- 23 種劇情動作；
- 7 種歌詞方式、6 種進場、9 種退場；
- 7 種轉場；
- 桌面視窗。
還不夠時，在該工程的 assets/engine.js 裡加，不要改本 skill 裡的模板。可以參考 第 1 集手法。想把新橋段沉澱進模板，先和使用者確認。沉澱時要同時改這幾處：
- 模板
engine.js； pixel_mv.py的BEAT_NAMES等名單，以及分鏡表用的中文名ZH_*；interactions.md。
場景庫
- 資料在
assets/scene-library/scenes.json。 - 增加場景要同時改兩處：在
scenes.json裡登記關鍵字和互動，在模板engine.js的SCENES裡寫繪製方法。