Plextrang/story-shorts

Story Shorts：任何點子輸入，完成一部卡通短片輸出

這個技能包含一個電影引擎與一個工作流程。引擎（engine/）在 headless Chrome 中逐幀渲染 three.js 場景： 2D 畫布偶角色位於一個卡通陰影、墨水邊框的 3D 世界中，搭配相機運動與淡入淡出、用於解釋性圖形的 2D 覆蓋層、內嵌字幕，以及一個定時事件音效混音。每部電影只寫入其故事層： 誰在其中、在哪裡發生、有哪些鏡頭、圖形以及聲音計畫。新電影從空白的起點（starter/：兩個預設角色、兩個場景、四個鏡頭）開始。examples/floating-scale/ 是一部已完成的參考影片，僅供參考。切勿重複使用其角色或故事。

視需要閱讀以下文件：

• reference/rules.md：故事與畫面規則。請先閱讀此文件。
• reference/story-templates.md：六種故事模板。每部電影選擇一種。
• reference/engine-api.md：如何在引擎上撰寫電影（角色、姿勢、世界、道具、鏡頭、圖形、提示）。
• reference/transitions.md：規則 11 的實作（相機運動、連續性分鏡、保留的切換）。
• reference/sound.md：配音、音樂與音效，使用 Epidemic Sound 或免費工具。
• reference/lessons.md：已遇到的錯誤與其修復方式。在除錯任何問題前請先查閱。

開始前：問兩個問題

1. 點子。 一句話就夠了：「一個怕黑的燈塔管理員」、「1904 年奧運馬拉松」、「如果重力減半一天」。如果使用者尚未提供，請詢問。如果對使用者很重要，才詢問長度（預設約 60 秒）。
2. 聲音工具。 詢問：「你有 Epidemic Sound（及其 Claude 連接器），還是我該使用免費工具？」
   • Epidemic Sound（建議）： 使用 Epidemic 配音作為旁白與角色、一個根據故事剪輯的 Epidemic 音樂曲目、Epidemic 音效與環境音。這需要在 Claude Code 中安裝 Epidemic Sound MCP 連接器。
   • 免費： 使用 Kokoro TTS 作為配音（scripts/kokoro_voice.py），以及以程式碼合成的配樂與音效。
   • 除非在影片的 README 中說明，否則不要在同一部影片中混用兩者。

然後執行 python scripts/check_setup.py，並在撰寫任何影片程式碼前修復所有標記為 MISSING 的項目。

工作流程（除非使用者要求，否則無需等待審核）

1. 新專案。 python scripts/new_film.py <資料夾> "標題" 會複製引擎與空白起點，寫入一個預設時間軸，並全新安裝 film/node_modules。僅在該資料夾內工作。
2. 故事（docs/STORY.md，script/lines.json）。
   • 選擇符合點子的故事模板（reference/story-templates.md），並說明選擇了哪一個及其原因。
   • 撰寫腳本：每個口白台詞一個條目（id、說話者、開始時間、文字）。旁白加上幾句角色台詞；每分鐘影片約 150 字。
   • 撰寫鏡頭列表，每個鏡頭需有無聲解讀：一個靜音觀眾僅從畫面能理解到的內容。
   • 命名場景。場景改變是淡入淡出的唯一理由；在一個場景內則進行相機運動。
   • 事實必須為真，並使用真實數字。角色、故事與世界均為原創。
3. 角色（film/src/story/cast.js）。
   • 每個角色一個鍵（與其說話者 ID 相同）。從一個預設開始，然後覆寫顏色、比例與特徵，直到成為這部電影專屬的角色（reference/engine-api.md，「角色」）。當故事需要時，在 character.js 中透過新的 feat 標誌加入新的外觀。
   • 執行 node film/tools/charsheet.mjs，並在建立任何鏡頭前檢視每一張角色表。
4. 世界與道具（story/world.js、story/set.js、可選 story/props.js）。
   • 每個場景由 worldkit.js 加上其專屬地標構成。將每個標記放入 SET。為英雄道具提供故事所需的多種狀態。
5. 分鏡畫面（story/shots.js、story/overlay.js）。
   • 用影片的鏡頭取代起點的四個鏡頭。從時間軸取得時間節點（K.wordAt、K.lineAt），絕不使用寫死的秒數。在配音產生之前，執行 python tools/build_timeline.py --placeholder。
   • 從一開始就安排連續性（規則 11）：每個角色在每個場景中只有一種表演，道具位於其標記位置。
   • 使用 2D 圖表進行解說（規則 4）。在 CUES 中列出每個可見的動作。
6. 配音。
   • 將每個台詞產生為獨立的音檔，放入 audio/vo/raw/<id>.mp3|wav（Epidemic 或 scripts/kokoro_voice.py）。
   • 執行 python <repo>/scripts/prepare_voice.py（使用 Kokoro 時加上 --atempo-off）以修剪靜音結尾並設定節奏。
   • 執行 python tools/build_timeline.py、python tools/captions.py，然後執行 cd film && node tools/cues.mjs。
   • 切勿在耳語時間點剪輯音檔。重新檢查構圖：因實際配音的出現，節奏已改變。
7. 在完整渲染前審查畫面：
   • 執行 node framecheck.mjs --step 4 必須輸出 "framing OK"。
   • 執行 node tools/poptest.mjs --out ../render/pop 檢查所有邊界是否有爆音；執行 bash tools/movesheet.sh 檢查動作。
   • 執行 bash tools/sheet.sh <名稱> "<時間>" 以產生接觸表。檢視它們，並將每個鏡頭與其無聲解讀進行比對。至少進行兩輪完整的檢查。
8. 音效（audio/sound_plan.json、reference/sound.md）。
   • Epidemic：將曲目與音效下載至 audio/epidemic/，填寫 music、effects 與 ambience，然後執行 cd audio/epidemic_mix && python mix_film.py && python autolevel.py && python qc.py && python sync_check.py。
   • 免費：填寫 synth，然後執行 cd audio/synth && python music.py && python build_fx.py && python mix.py && python cue_presence.py。
   • 目標：−14 LUFS、真實峰值 ≤ −1.3 dBTP、每個台詞的配音至少清晰 6 dB、無靜音間隙、每個音效在一個影格內。
9. 渲染、組合、交付。
   • 執行 cd film && node render.mjs --from 0 --to <幀數-1> --scale 1.5 --workers 2 --jpg --out ../render/frames。
   • 執行 bash tools/assemble.sh 以寫入 out/<標題>.mp4 與 out/contact_sheet.jpg，並測量結果。如果某個工作人員崩潰導致空影格，則拒絕執行。
   • 如果已安裝 earshot：執行 bash audio/tools/es.sh critique out/<標題>.mp4，目標為「發行級」。
   • 撰寫影片的 README.md：標題行、測量結果、每個保留的切換及其原因、使用的音效，以及誠實的弱點。切勿聲稱影片很好： 你無法以全速觀看或聆聽它。列出使用者應透過眼睛與耳朵檢查的項目，然後停止並等待他們的審閱。

不可協商事項（詳情見 reference/rules.md）

• 關閉聲音也能看懂。在解決方案之前先呈現問題。在台詞播放期間，在畫面上顯示每句台詞。
• 不使用字面隱喻；用清晰的 2D 圖表解釋。
• 道具一看就懂。使用包含全身人物的中景與廣角鏡頭，保持字幕區域（高度 62–78%）清晰，沒有人物在畫面邊緣被切斷。
• 同一個場景代表相機運動，新場景代表淡入淡出，只有陳述理由的切換才允許保留。
• 每個可見的動作都有可聽見的音效，且旁白在整個過程中保持清晰。
• 僅使用原創角色、故事與世界。絕不複製現有節目的角色或外觀，也絕不重複使用範例影片的內容。
• 僅在影片自己的資料夾內工作。在那裡全新安裝所有內容；絕不連結到其他專案。