啟用合約
當使用者想要一個卡通 / cel-shaded 3D 解說短片（扁平色彩、黑色輪廓、物體彈入、移動鏡頭、大字幕），想要重現「Stupy Doo」風格的影片，或要求從文字在 Blender 中為圖表製作動畫時，載入此技能。
硬性規則
- 絕不使用圖片/影片 AI 模型生成視覺效果。其外觀是由 Blender 渲染的 3D 幾何圖形 + Freestyle 輪廓。
- Blender 執行檔：
~/.local/bin/blender（5.1.x 版，使用者安裝）。始終以-b -P參數在無頭模式下執行。 - Storyboard 是唯一真實來源：
storyboard.json（結構定義在references/storyboard-schema.md）。編輯 JSON，重新渲染。絕不手動編輯.blend檔案。 - 在渲染完整影片之前，務必先檢查：使用
--stills參數渲染 3–5 個時間點，建立對照表，閱讀它，修復重疊或超出鏡頭的物體。 - 字幕和音訊是後期處理（
mix.py、captions.py），絕不使用 Blender 的文字物件。 - 音效透過
audio區段中的action:引用對齊動作時間點，當動作存在時，絕不手動輸入秒數。 - 旁白保持西班牙語的中性風格；UI / 字幕內容跟隨使用者的語言。
- 保持短片簡潔：每個 storyboard 8–30 秒。使用 ffmpeg concat 將多個片段串聯成較長的影片。
決策關卡
| 需求 | 做法 |
|---|---|
| 有旁白的影片 | 先錄製旁白，根據旁白時間加上字幕，然後進行動畫。透過 voice-video（tts.py）將語音放入 audio.narration。 |
| 音效 / 音樂 | audio 區段：narration、music、sfx，其中 sfx 使用 action: 引用。預留檔案在 assets/sfx/，CC0 來源請見其 README。 |
| 提供音樂 | 在靜態畫面之前執行 beats.py snap storyboard.json --music track.mp3 --write。 |
| 快速外觀檢查 | 使用 --preview --stills t1,t2,t3（半解析度，8 個樣本）。 |
| 最終渲染 | 不使用 --preview；預設為 1080x1920，30 fps。 |
| 物件不在預設集裡 | 預設集：box、plane、cylinder、sphere、panel、panel_row、cable、device、car、charger、transformer、cloud、tree、pole。否則使用基本幾何體或 model（glb/obj）。 |
| 畫面看起來廉價 | 每個鏡頭一個主體，相機距離 8–13 公尺，使用 tree / pole / cloud 裝飾，cable 使用 draw 然後 flow。請參閱 references/style-notes.md。 |
| 想要手動調整 | 加上 --blend 參數，在 Blender UI 中開啟 out/scene.blend。 |
執行步驟
- 閱讀
references/storyboard-schema.md和references/style-notes.md。 - 編寫一個小型的
gen.py，用於生成<workdir>/storyboard.json：物體位於 z=0 的地平面上，包含多個鏡頭（每個鏡頭一個主體）、動作、字幕、post、audio。 - 靜態畫面：
~/.local/bin/blender -b -P ~/.claude/skills/toon-explainer/assets/build.py -- storyboard.json out --preview --stills 1,3,5。使用 Pillow 建立對照表並閱讀它。 - 修正 JSON 中的構圖和時間點。重複步驟 3，直到每個鏡頭都清晰可讀。
- 預覽影片：使用相同的指令，僅加上
--preview參數。使用 ffprobe 檢查out/raw.mp4（持續時間、fps）。 - 音訊（如果
audio存在）：python3 ~/.claude/skills/toon-explainer/assets/mix.py storyboard.json out/mix.wav。閱讀提示時間表。 - 字幕 + 混合：
python3 ~/.claude/skills/toon-explainer/assets/captions.py storyboard.json out/raw.mp4 out/final.mp4 --audio out/mix.wav（如果沒有audio則使用--audio narration.wav）。 - 最終輸出：移除
--preview，重新執行步驟 5–7。使用xdg-open開啟out/final.mp4。
輸出合約
回傳：storyboard.json 的路徑、out/final.mp4 的路徑、持續時間、解析度，以及每個鏡頭的一行描述，說明畫面上顯示的內容。回報渲染時間。列出任何尚未實作的功能（唇形同步、多片段串聯）。
參考資料
references/storyboard-schema.md— JSON 結構定義、預設集、動作、相機慣例。references/style-notes.md— 參考外觀、Blender 5 注意事項、解決廉價剪輯的方法、聲音設計。references/external/— MIT 授權副本：EL4CTEO 的blender-stylized-npr、arjun988 的camera-cinematography。assets/toonlib.py— bpy 函式庫（材質、預設集、相機、動畫）。assets/build.py— 從 storyboard 到 Blender 渲染。assets/mix.py— 將audio區段混合為一個 WAV 檔案（降低音樂音量、音效提示）。assets/beats.py— 節拍偵測 + 對齊動作時間點。assets/sfx/— 預留音效，CC0 來源。assets/captions.py— ffmpeg 字幕 + 音訊混合。assets/storyboard.example.json— 太陽能屋頂範例，9 秒。