talking-clip 是做什麼的？
一個片段包含四個步驟：撰寫台詞、生成語音、規劃表演、建構與渲染。 輸出：一個 HyperFrames 專案和一個 mp4 檔案（預設為直立 1080x1920）。
1. line 由你撰寫，使用角色的語氣
2. voice scripts/tts.py （ElevenLabs 需耗費點數；say 與 none 免費）
3. plan 你編寫 plan.json （手勢與表情對應到詞語）
4. video scripts/build_clip.py -> scripts/verify.py -> scripts/render.py
所有路徑相對於此套件的根目錄：即包含 .claude-plugin/ 的資料夾，位於此檔案上兩層（請先解析符號連結）。需要公開的 HyperFrames 技能（hyperframes、hyperframes-cli）：在動手編輯任何合成之前，請先閱讀 hyperframes 一次。
0. 預檢（永遠優先執行）
執行 python3 scripts/setup.py doctor（加上 --json 可解析輸出）。它會列出所有相依套件、用途以及適用於此機器的確切安裝指令；當缺少必要項目時，會以 exit code 1 結束。
- 必要缺少（ffmpeg、Node.js 18+、HyperFrames 技能，以及配置語音為 ElevenLabs 時所需的金鑰或
say）：用一句話告知使用者每個項目的用途，並建議執行印出的指令。僅在使用者同意後才執行。切勿自行輸入或要求 API 金鑰：請告知使用者在 shell 中設定ELEVENLABS_API_KEY環境變數。 - 可選缺少：向使用者提議一次，並說明每個項目能解鎖哪些功能。Playwright 可提供網頁擷取（含元素縮放框與全頁截圖），tesseract（OCR）可掃描螢幕截圖中的機密資訊，ASR（mlx-whisper / openai-whisper）可進行音訊檢查與取得精確詞語時間。若使用者拒絕，則跳過這些檢查；對應的驗證步驟將改為手動的
review步驟。 - HyperFrames 技能（
hyperframes、hyperframes-cli、hyperframes-registry、media-use）：若缺少，建議執行npx hyperframes skills。在建立或編輯任何合成之前，請先閱讀hyperframes（以及hyperframes-cli用於渲染問題的說明）。
設定（首次執行，或使用者想要變更項目時）
尋找設定檔：python3 scripts/setup.py show。如果不存在，或使用者要求變更角色、語音、渲染或樣式，請進行訪談（一次一個簡短問題，提供預設值），然後使用旗標寫入設定：
| 問題 | 旗標 | 選項 |
|---|---|---|
| 包含哪些部分？ | --features | character、explainer 或兩者 |
| 哪個角色？ | --character | 內建範例（pkg:characters/host/character.json）或使用者自己的路徑（儲存為絕對路徑） |
| 旁白語言 | --language | ISO 代碼；搭配 say 時會自動挑選清晰的語音（setup.py voices --lang <code> 列出可用的語音，--say-voice 可覆寫） |
| 哪種語音？ | --voice | elevenlabs（使用者的 ELEVENLABS_API_KEY 金鑰與 --voice-id）、say（macOS，免費）、none |
| 點數保護（ElevenLabs） | --max-chars、--max-seconds、--daily-credit-cap | 使用者選擇的數字；留空表示不設限制 |
| 如何渲染？ | --render | local（免費，使用此機器）、cloud（HyperFrames 雲端，需要 npx hyperframes auth login）、preview（僅限 Studio） |
| 尺寸 | --size | 1080x1920、1920x1080、1080x1080 |
python3 scripts/setup.py init --features character --voice say --render local --yes
init 會先執行 doctor 並提供相同的安裝選項。如果設定檔已存在，會先詢問是否覆寫；若非互動模式則需加上 --force。
使用者的自訂角色：python3 scripts/setup.py new-character --name "<name>" --out ./characters/<name> --activate
會複製範例並設為啟用（無需第二次 init）。然後協助使用者填入其列印的欄位：description、personality、speaking_style.rules、rig.colors（或 sprites）、expressions / poses / gestures、set、voice_moods。
切勿要求、列印或寫入 API 金鑰。如果缺少 ELEVENLABS_API_KEY，請告知使用者在 shell 中設定。設定檔的 schema 位於 config/config.schema.json；角色檔案的格式請參考 README（「Your own character」）。
為此片段選擇風格
沒有統一的預設外觀。每次片段應根據主題、觀眾以及使用者的品牌或品味來挑選風格：場景（{"type": "color"|"gradient"|"image", ...}）、構圖（close、medium、wide）以及動作強度（calm、normal、lively）。當風格選擇很重要時（例如片段是為品牌、公開頻道或系列影片製作），請詢問使用者。每次片段應變換風格，避免重複上一次的選擇。如果設定檔中有 brand 套件，其 background 會優先於你的選擇。將風格寫入一個檔案，並傳遞 --style 參數：
{"set": {"type": "gradient", "colors": ["#FFF4E6", "#FFD9B3"]}, "framing": "medium", "motion": "lively"}
台詞也一樣：根據觀眾調整語氣，同時符合角色個性，且不要重複使用與前一個片段相同的開場白或結尾句。
1. 撰寫台詞
讀取設定檔中指定的角色檔案（character 鍵）：personality 和 speaking_style.rules 就是角色的語氣。請遵循這些規則；若與使用者要求衝突，則以使用者要求為準。
- 長度：最多
styles.talking_clip.max_seconds。以speaking_style.chars_per_second（約 14 字元）計算，20 秒的片段大約不超過 260 個字元。一個想法，一個結尾句。 - 語言：使用使用者的語言，除非使用者另有要求。
- ElevenLabs 支援音訊標籤的模型（v3 及更新版本）可接受英文的情緒標籤，放在方括號內，置於其所修飾的詞語之前：
[excited]、[calm]、[whispers]、[laughs]、[pause]。say和none模式會忽略這些標籤（它們會被移除）；請改用對應的手勢來表現情緒。
2. 生成語音
python3 scripts/tts.py estimate --text "<line>" --max-seconds 20
python3 scripts/tts.py speak --text "<line>" --out out/voice.wav [--mood excited] [--confirm]
- ElevenLabs：務必先執行
estimate並告知使用者費用；speak在沒有--confirm時會拒絕執行，並且會在使用者設定的保護限制（最大字元數、最大秒數、每日點數上限）被突破時拒絕執行。--takes 2可產生替代方案。詞語時間會寫入out/voice.wav.words.json。 --mood會從角色的voice_moods中選取一個情緒（ElevenLabs 設定 + 可選的 ffmpeg 濾鏡）。say/none：免費。使用none時沒有音訊；請改為向建構器傳遞--text參數。
3. 規劃表演
python3 scripts/timings.py out/voice.wav --text "<line>" 會給出每個詞語的起始時間。請編寫 plan.json：
{"expression": "neutral",
"events": [{"t": 0.0, "gesture": "hello"},
{"t": 2.1, "gesture": "explain", "dur": 2.5},
{"t": 5.0, "expression": "happy"},
{"t": 6.2, "gesture": "wink"}]}
gesture和expression的 id 來自角色檔案（gestures、expressions）；每個手勢都有其描述和典型的dur。在規劃前請先閱讀這些內容。- 嘴巴、眨眼、呼吸與閒置搖晃都是自動處理的。你只需要安排表演的節拍。
- 將一個強烈的手勢安排在它所配合的詞語之前 0.2-0.3 秒。每個節拍一個反應；同一秒內切勿安排兩個手勢。以一個平靜、持續的手勢結束（它會自動保持到片段結束）。
4. 建構、驗證、渲染
python3 scripts/build_clip.py --audio out/voice.wav --plan out/plan.json --style out/style.json --project out/clip
python3 scripts/render.py out/clip --out out/clip.mp4 --quality draft
python3 scripts/verify.py all --project out/clip --text "<line>" --video out/clip.mp4
驗證是必須的（詳細說明請參考 explainer 技能的「驗證」章節，相同流程）：build 必須乾淨無誤，render 會產生一個聯絡表，你必須檢查（嘴巴在動、手勢在預期位置、沒有東西被裁切），audio 會使用 ASR 檢查詞語並確認時長限制。修正問題後從失敗的階段重新執行。每次 verify.py all 執行即為一次迭代；若達到 verify.max_iterations 次數限制，則以 exit code 2 結束，並告知使用者仍然失敗的項目，而非交付成品。render 階段會保持為 review 狀態，直到你查看聯絡表並使用 verify.py mark render pass|fail --project out/clip --note "..." 記錄結果，然後再次執行 verify.py all（重建會使標記失效）。
接著使用已設定的後端渲染最終版本：python3 scripts/render.py out/clip --out out/clip.mp4（render.max_mb 會重新編碼以符合上傳限制）。切勿提交 mp4 或 wav 檔案。