Stickman Story Reels
將一個前提轉變為完成的 60-90 秒垂直 Reel：一個為觀看時間打造的鉤子優先腳本、用程式碼繪製的火柴人分鏡、含逐字字幕的畫外音、音效設計，以及一個讓人留言並期待第二集的二選一投票。此技能源自 PlotVote 互動故事 (@plotvote) 的工作流程。
整個流程是確定性的：你撰寫 episode.json（腳本、時間、動作）和 scenes.js（繪圖），而 scripts/reel.py 完成其餘工作（語音 → 音效 → 建置 → 檢查 → 渲染）。不需要影像模型、圖庫素材，也不需要付費工具（語音除外）。
設定（每台機器一次）
檢查 python3 --version（3.9+）、ffmpeg -version 和 node --version（18+）。第一次渲染時會透過 npx 下載 HyperFrames 和無頭 Chrome；這是正常現象，大約需要一分鐘。對於語音，使用者需在專案資料夾的 .env 檔案中設定 ELEVENLABS_API_KEY=...（或匯出為環境變數）。請勿印出金鑰。若無金鑰，所有功能仍可在 --draft 模式下正常運作（無聲，按實際速度計時）。
在每個終端機工作階段中定義此 shell 函數（是函數，而非字串變數，以便在 zsh 和 bash 中都有效）。以下命令會用到它：
reel() { python3 "<此技能的資料夾>/scripts/reel.py" "$@"; }
工作流程
1. 理解需求
- 「製作這個故事」 給予清晰前提 → 撰寫一個強而有力的腳本並建置。
- 「給我選項」或「腳本點子」 → 提供 3 個完整的選項（請參考手冊 §10），讓他們選擇，然後建置。
- 「下一集」或「X 贏了投票」 → 繼續系列：從上一集的後果開始，揭曉之前的線索，給予真正的答案，逐步升級，新的投票（手冊 §9）。如果有系列聖經，請先閱讀。
- 僅腳本（或沒有 shell 可用）→ 提供腳本表格，以及
episode.json和scenes.js（如果他們要自己渲染）。
2. 撰寫腳本
每次都要先閱讀 references/viral-script-playbook.md。 它包含了決定觀眾是否能在 3 秒內留下的規則。當構思一個前提、系列或季度時，也請閱讀 references/story-engines.md。
將腳本撰寫為表格（# · voice · spoken · on screen），目標約 210-230 字（以一般速度約 85 秒）。執行手冊中的語音前檢查清單。人們最常犯錯的是：第一幀必須有動作；5 秒內必須交代地點、時間和人物；每個決定都必須通過 12 歲兒童測試；角色必須用第一人稱說出自己的揭露；投票選項是兩個具體的單詞行動，且兩邊都有代價；投票後的低語線索必須指向先前埋下的伏筆。
如果使用者要求了選項，或者可能想在花費點數前先批准，請顯示腳本表格並等待。否則，繼續進行。
3. 建立 Reel 骨架
reel new reels/<slug>-part1 --title "<Title> — Part 1"
這會根據一個小型可運作的起始範本建立 episode.json 和 scenes.js。用你的故事取代兩者。
4. 繪製分鏡（scenes.js）
閱讀 references/drawing-kit.md，並開啟 examples/sundown-part1/scenes.js 作為模式庫（一隻生物探出身子、一個拉遠的地圖、逐行揭露的規則牆、定格動畫生物、窗邊的驚險一幕、一台會說話的收音機、樹林裡的手電筒、選擇分歧、一個封面）。
根據你的腳本表格，每個分鏡一個函數。每個函數回傳一個 1080×1920 的 SVG，由工具庫輔助函數（defs()、sky()、forest()、cabin()、room()、water()、stick()、kid()、creature()、phone()、radio()、chip()、ring()、splitChoice()…）建構而成。如果工具庫沒有某個場景（例如水上樂園、火車、沙漠），這很正常：使用矩形、路徑和輔助函數來繪製，並遵循繪圖工具庫的「建立新的場景」一節。為所有應該在特定詞語出現時移動或顯示的元素設定 id。讓臉部保持在字幕帶（y 1180-1380）和右側 140 像素之外。為封面（主題放在標題下方）和投票卡片插圖添加 mode。
5. 設定劇集（episode.json）
閱讀 references/episode-format.md。 為每個場景設定：draw、say 台詞、kenburns 效果，以及對齊特定詞語的 animate 條目（"at": "faster"）。然後：設定語音（為其他角色加上 fx 和字幕 tag）、包含時鐘的 HUD 藥丸、手動放置的 sfx 音效、背景音樂提示、投票場景（兩個選項、插圖、線索台詞）、cover 和 post（包含 {vote_line} 的說明文字、置頂留言、posts_at）。關於語音、音效和字幕，請參考 references/sound-voice-posting.md。
6. 草稿預覽（免費）
reel voice reels/<slug> --draft # 無聲，實際速度計時
reel sound reels/<slug>
reel build reels/<slug>
reel check reels/<slug>
reel snap reels/<slug> --at scenes # 每個分鏡兩張靜態圖（或 --at 0.5,12,30.5 秒）
檢視 reels/<slug>/snaps/ 中的每張靜態圖。修正繪圖工具庫中可讀性規則所警告的問題：太暗而無法閱讀的內容、字幕下方的臉部、太小的主體、時機不對的揭露。check 必須顯示「Check passed」（如果檢查失敗，all 會在渲染前停止）。以下警告是預期且可接受的：「nested structure」、「track too dense」、「composition file too large」以及插圖「overflowing」它們的裁切區域。
7. 語音與渲染
reel all reels/<slug> # 語音 (ElevenLabs) → 音效 → 建置 → 檢查 → 渲染
reel frames reels/<slug> --every 2 # 整個 Reel 的聯絡表，供檢閱
檢查輸出的長度（60-90 秒；如果過長，減少鋪陳）。檢視 renders/review.png：主體是否可讀、字幕是否清晰、命名的物體是否在其對應的詞語出現時移動、投票卡和線索插圖是否顯示。聆聽第一行；如果某個詞可能被誤聽，更改該詞後重新配音（只有更改過的台詞會花費點數）。
8. 交付
提供使用者 renders/<slug>.mp4、renders/cover.png 和 POST.md（說明文字、置頂留言、替代文字、投票截止時間）。如果是系列作品，請在 Reel 資料夾旁撰寫或更新 bible.md：角色設定、世界規則、正史、線索，以及針對每個投票選項的一行描述，說明下一集如何開始（見 story-engines §4）。
命令
| 命令 | 功能 |
|---|---|
reel new <dir> --title "…" | 建立 Reel 資料夾骨架 |
reel voice <dir> [--draft] | 語音 + 逐字時間 → timing.json、assets/audio/narration.wav |
reel sound <dir> | 合成 19 種音效 + 環境背景音 |
reel build <dir> | 編譯 index.html、cover/、POST.md |
reel check <dir> | HyperFrames 語法檢查、版面配置與對比度檢查（失敗時以非零退出碼終止） |
reel snap <dir> --at scenes | 從合成畫面產生 PNG 靜態圖，每個分鏡兩張（或 --at 1,5.5,9 秒） |
reel render <dir> [--draft] | 輸出 -14 LUFS 的 MP4 + cover.png + 聯絡表 |
reel all <dir> [--draft] | 語音 → 音效 → 建置 → 檢查 → 渲染（檢查失敗則停止） |
reel frames <dir> --every 2 | 整個渲染後 MP4 的檢閱表 |
疑難排解
"word" isn't spoken there： 時間參考使用字幕中的拼寫，且僅在該場景中搜尋；錯誤訊息會顯示該場景說了些什麼。對於第二次出現的詞，使用word#1；對於其他場景中的詞，使用sN:word；對於偏移量，使用start+0.2；對於絕對時間，使用12.5s。- 找不到語音： 使用預設名稱（Liam, Brian, George, Daniel, Callum, Bill, Roger, Chris, Eric, Will, Harry, Charlie, River, Adam, Sarah, Matilda, Jessica, Alice, Lily, Laura, Bella）或語音 ID。
- 點數用完： 已經配音的台詞會被快取；加值後重新執行
voice。 - 出現空白或黑色畫面： 該組的 JavaScript 錯誤。
check會顯示錯誤；修正後重新執行build。 - 長度超過 90 秒： 刪減鋪陳台詞和形容詞；保留鉤子、轉折、投票和線索。
npx或node錯誤： 安裝 Node 18+；首次執行時讓npx下載 HyperFrames 和 Chrome。
此技能包含的內容
scripts/reel.py：CLI。scripts/synth.py：19 種音效和背景音（持續低音、風聲、脈動、嗡鳴、水聲），全部為合成。assets/kit.js：繪圖工具庫。assets/runtime.js、assets/base.css：字幕、HUD 和投票卡。references/：viral-script-playbook.md（務必閱讀）、story-engines.md（前提、系列、聖經）、episode-format.md（規格）、drawing-kit.md（繪圖）、sound-voice-posting.md（語音、音效、字幕、發文、安全）。examples/sundown-part1/：一個完整的 89 秒第一集（episode.json+scenes.js）。examples/starter/：由new命令使用的 4 個分鏡起始範本。examples/script-pitches.md：另外五個完整的第一集腳本（THE WHEEL, LAST CAR, LOW TIDE, 3:33, ROW ONE）。