卡通 3D 故事短片 (three.js + Remotion)
所有指令從專案根目錄以 Bash（非 PowerShell）執行。 references/ 和 templates/ 是相對於此技能的路徑；SK = .claude/skills/cartoon-3d-short。
已完成並存放在 src/videos/ 的短片一律不可編輯。請勿閱讀它們來學習程式碼：references/API.md 才是你的地圖。
references/STYLE_BIBLE.md 和 references/reports/ 是來自其他管道的學習素材。絕不可複製該管道的腳本、角色或鏡頭，也不可在旁白或描述中提及該管道名稱。
規則
- 無字幕或標籤。僅限英文。單一穩定的語調。笑話須基於經研究證實的真實事實。
- 每個鏡頭都必須用地平線後的建築物、樹木（樹幹間隙有 2-3 公尺的灌木叢）或遠山來遮擋地平線。只填滿相機看得到的範圍。場景要豐富：擁擠的人群、裝飾品、紋理、旗幟。
- 最終輸出為 1080x1920 解析度，30 fps，絕不使用
--scale。 - 混音：語音、低約 6 dB 的免費 CC0 音效、根據場景切換（非單一連續曲目）並壓低在語音下的音樂提示，整個混音目標為 -15 LUFS。
- 對於免費、無版權的音效和 3D 模型有例行批准權：在檔案頁面檢查授權條款，跳過要求署名 / 非商業用途 / 相同方式分享的項目，在
_sfx/LICENSES.md中記錄，說明你抓取了什麼以及檔案大小。在需要登入、付費、其他下載或執行未安裝的套件之前，請先詢問。 - 靜態幀檢查清單 (
references/QA.md)：在第一次完整生成靜態幀時以及在最終渲染前各執行一次 Opus-medium 代理檢查，其間你自己也要反覆複查，然後由用戶批准靜態幀。沒有任何絕對分數是必須通過的關卡。 - 修正錯誤時僅重新渲染變更的區塊 (
--redo)，絕不重新渲染整個影片。 - 每一步完成後都要儲存。有兩個用戶中斷點：腳本批准，以及最終渲染前的靜態幀批准。除此之外，需獨立完成到交付為止，無需詢問。
管線
- 主題與事實。 一個令人驚訝的真實故事，具有視覺化的因果關係，以及一個日常生活的類比。事實及其來源需放在
src/videos/<名稱>/SCRIPT.md的頂部。 - 腳本。 長度由故事決定。字數 = 秒數 x 每秒字數，透過一段選定語音的單句樣本測量（無樣本：假設為 3，並在錄製後確認）。節奏：鉤子（荒誕事實，一行）、背景設定（年份、地點、榮耀）、動作（3-4 個逐步升級的節拍）、轉折、冷面笑匠式結語（「幸運的是... / 不幸的是...」）、解釋（一個概念，日常生活類比）、後果、回馬槍轉折。切勿描述觀眾已經看到的畫面。僅作為佈局參考：
templates/SCRIPT_example.md。在此停下，等待使用者批准腳本。 - 語音。 使用者將錄音生成至
_voiceover/<名稱>/voice_raw.wav。接著執行python scripts/voice_trim.py _voiceover/<名稱>/voice_raw.wav _voiceover/<名稱>/voice.wav和python scripts/words_whisper.py _voiceover/<名稱>/voice.wav _voiceover/<名稱>/words.json。所有時間點都對齊words.json：切勿直接讀取它，應將其列印為word@frame格式，發現錯誤單字時用一個簡短腳本修正。依據kept pauses那一行的指示操作（references/GOTCHAS.md「語音」部分）。 - 影片資料夾。 將
templates/starter/中的四個檔案複製到src/videos/<名稱>/，將Short.tsx重新命名為<名稱>.tsx，並一併修改其內部的StarterShort/STARTER_FRAMES，然後在src/Root.tsx中註冊該合成。這些檔案僅存放故事資料及一個標記為EXAMPLE的 2 鏡頭示範；引擎則位於src/shared/。請在編輯前閱讀references/API.md。如果src/shared/或scripts/遺失或缺少檔案，請從templates/shared/或templates/scripts/複製過來。 - 道具搜尋。 針對每個節拍，使用
grep搜尋public/kenney/INDEX.txt，並將選取的道具記錄在src/videos/<名稱>/PROPS.md表格中。缺少道具時：下載一個免費的 CC0 資源包（references/GOTCHAS.md）到public/kenney/<包名>/，將其附加到INDEX.txt，並在world.ts中將<包名>/<模型>加入KENNEY。 - 鏡頭計畫 在
story.ts中：TOTAL= ceil(語音秒數 x 30)，接著設定SHOTS、XFADE、FLASH_AT、CAMS、KICKS、DOF_V2。視覺反應的出現時間點要比其對應單字提早 0-3 幀。每個靜止畫面都要有微量的晃動或移動。每個循環動作都必須設定明確的切換時間。 - 建構鏡頭 透過取代
EXAMPLE部分。房屋的外觀風格已內建於引擎中（references/LOOK.md）；絕不要為了單一影片而編輯src/shared/。- 世界 (
world.ts)：場景、道具、材質、以及在pose()中的動態道具。天空、燈光、城鎮、港口、太陽以及視線剔除由引擎提供。對重要道具使用prop()並傳入keep = true。 - 角色 (
cast.ts)：服裝以及每個排練區的一個stage()案例。卡片、輪廓、眨眼和陰影由引擎提供。 - 合成 (
<名稱>.tsx)：僅包含名稱和poolShots。後處理鏈（墨線、鏡頭模糊、輝光、色調映射、調色）在引擎中。
- 世界 (
- 靜態幀檢查，在任何長時間渲染之前（
references/QA.md）：每個鏡頭的中間幀靜態圖、腳本化檢查、代理檢查、修正並自我檢查、第二次代理檢查、修正並自我檢查。在此停下，等待使用者批准靜態幀。 - 音效準備（
references/SOUND.md）：音效事件放在_sfx/<名稱>_events.json，音樂提示放在_sfx/<名稱>_music_cues.json。 - 最終渲染（
references/RENDER.md）：REMOTION_TMP=C:/remotion-tmp node scripts/render_chunks.mjs <合成名稱> out/<名稱>/video.mp4 <TOTAL>。 - 混音與品質保證。 組裝音樂（
music_cues.py，詳見references/SOUND.md），然後執行python SK/templates/audio/build_mix.py _voiceover/<名稱>/voice.wav out/<名稱>/video.mp4 out/<名稱> _sfx/<名稱>_events.json [_sfx/<名稱>_music.wav]，這會寫出video_final.mp4。接著執行python scripts/bridge_shots.py src/videos/<名稱>/story.ts out/<名稱>/shots.json以及python scripts/short_qa.py out/<名稱>/video_final.mp4 out/<名稱>/qa out/<名稱>/shots.json --voice _voiceover/<名稱>/voice.wav，後者必須以 exit code 0 結束。如果有問題，使用render_chunks.mjs ... --redo A-B,C-D修正，然後再次執行混音和 QA。用戶對最終影片的意見處理：references/QA.md「用戶審查」。 - 交付。 傳送
video_final.mp4（若超過 30 MB：提供一個較小的預覽版本以及檔案路徑），刪除C:/remotion-tmp中此短片的暫存資料夾，並更新記憶體記錄。
參考檔案
| 檔案 | 何時閱讀 |
|---|---|
references/QA.md | 靜態幀檢查、檢查清單提示、short_qa |
references/SOUND.md | 音效庫、音樂提示、混音 |
references/RENDER.md | 渲染設定、區塊循環、恢復渲染 |
references/API.md | 在編輯起手檔案之前：了解每個東西該放哪裡、函式簽章 |
references/GOTCHAS.md | 語音、道具與場景、構圖陷阱、此 PC 的注意事項 |
references/LOOK.md | 房屋外觀數值、相機與角色規則 |
references/LOOK_MATCH.md | 僅在需要比對原始參考外觀或進行外觀匹配通過時閱讀 |
references/house/GRADER_PROMPT.md | 兩兩比對 A/B 時使用，僅在變更外觀時閱讀 |
若要變更此技能本身（文件、起手檔案、引擎、腳本）：請先閱讀 MAINTAINING.md。