卡字 是做什麼的？
卡點視頻卡鼓點，講解視頻卡字。寫動畫程式碼的 AI 聽不到聲音，只能猜這一秒觀眾該看哪裡。 卡字把順序反過來：先有聲音，再有畫面，畫面始終追隨聲音。每個字是第幾秒唸的，先算出來；動作落在哪一幀，從表裡查。
這份說明給你（AI）看。每一步的細節在 docs/ 裡，用到哪步讀哪步，不用一次讀完。
下文的 tools/、starter/、docs/ 都在這個 skill 自己的目錄裡（和本檔案同一層），用的時候換成完整路徑。
六步，四個停頓
| 步 | 做什麼 | 產出 | 細節 |
|---|---|---|---|
| 1 寫稿 | 照說話寫，每句一個關鍵詞，配音版和字幕版分開 | script.txt | docs/01_寫稿.md |
| ⏸ 停一 | 把稿子給使用者看，等他點頭 | ||
| 2 配音 | 每句生成幾遍，另一個 AI 回聽打分，留最好的 | vo/lines/ | docs/02_配音.md |
| ⏸ 停二 | 讓使用者試聽整條配音 | ||
| 3 對時間 | 對齊模型給每個字標起止時間 | timeline.json | docs/03_對時間.md |
| 4 畫面 | 畫動詞；動作落在關鍵詞首字前 3 幀 | 程式碼 + 渲染 | docs/04_畫面.md |
| ⏸ 停三 | 先做 20 到 30 秒樣片給使用者看 | out/sample.mp4 | |
| 5 聲音 | 配樂讓位旁白；音效從動畫打點裡讀出來 | 混好的音軌 | docs/05_聲音.md |
| 6 檢查和發布 | 逐幀量卡字率、黑幀、閃幀、響度；準備標題封面簡介 | out/final.mp4 和檢查報告 | docs/06_檢查和發布.md |
| ⏸ 停四 | 成片和檢查報告一起交給使用者 |
使用者明確說「不用停、直接做完」時可以跳過停頓，但第 6 步的檢查一定要跑，結果要寫進最後的回覆。
使用者已經有錄好的旁白，就跳過第 2 步，直接從第 3 步開始（timeline.py --whole）。
開工前
- 跑
python tools/doctor.py，看缺什麼。配音和對齊目前只在蘋果晶片的 Mac 上實測過；別的平台按它給的替代辦法走，並告訴使用者。 - 問清楚（使用者沒說的才問）：講什麼、給誰看、多長、橫屏還是豎屏、有沒有自己的聲音樣本（十秒左右的乾淨錄音加逐字稿）。
- 建專案目錄，結構見下面。所有中間檔案都留著，每一版樣片單獨存，別覆蓋。
專案/
script.txt 稿子（格式見 docs/01）
vo/ 配音：lines/ 每句一個 wav，takes/ 所有遍
timeline.json 每句、每個字的起止時間
film/ 畫面工程（預設用 starter/ 裡的 Remotion 模板）
audio/ 配樂、音效、混音
out/ 樣片、成片、檢查報告
每一步最要緊的規矩
寫稿（為什麼都在 docs/01）
- 照說話寫。兩個標點之間不超過 22 個字，長短句穿插。耳朵只能聽一遍。
- 每句只標一個關鍵詞：
*關鍵詞*。後面的畫面就落在這個詞上。一條字幕裡最多一個關鍵詞。 - 唸法和字幕不一樣時寫成
{唸法=>字幕}，比如{F F M peg=>FFmpeg}。 - 句子說完整：主詞、受詞、量詞別省；動詞以兩個字以上為主，單字和多字交替；關鍵詞不用單字。停頓按意思定，見 docs/01 的停頓表。
- 容易讀錯的多音字寫稿時就換掉（docs/02 有替代表）。
- 寫完跑
python tools/lint_script.py script.txt，它會查一口氣太長、字幕超長、一句多個關鍵詞，還會估算時長。
配音
python tools/voice.py script.txt vo --ref 聲音樣本.wav：每句生成 4 遍，語音辨識轉回文字和原稿比對，唸錯的扔掉，留最好的一遍。- 多音字、聽起來像別的意思，辨識結果裡會露出來；對不上的句子改寫或者改唸法，別硬留。
- 想整體快一點用
tools/tempo.py（變速不變調），別重新生成。 python tools/pace.py vo_fast vo_paced：規整停頓。句首句尾的靜音、句內標點處的靜音都量出來，補短剪長，只動靜音不動聲音。tools/polyphone.py挑出可能讀錯的多音字拼成試聽音訊；它會誤報也會漏，最後靠人聽。
對時間
python tools/timeline.py script.txt vo_paced timeline.json --wav vo_paced/narration.wav --speech-gap，得到每句和每個字的起止時間，還有關鍵詞列表。--speech-gap讓稿子裡的停頓等於聽到的空白。- 畫面裡所有和旁白有關的時刻都從這張表裡查，不許按字數估。按字數估，十句以後就能差出三秒多。
畫面
- 先定畫風。拿不準就去翻程式碼畫風圖鑑 https://github.com/syydaniel/awesome-code-animation ，先挑畫風，再挑工具。沒有特別理由就用
starter/（Remotion）。 - 畫動詞，別畫名詞。「體積變大」要畫的是變大這個動作，不是一塊冰的插圖。常用動詞怎麼畫，見 docs/04 的表。
- 時間常數（60 幀下）：動作到位的那一幀，放在關鍵詞首字開始前 3 幀（
hit()）；允許提前 6 幀到推後 1 幀。新出現的東西，第一幀至少比關鍵詞早 12 幀。 - 關鍵詞那一下，畫面要明顯多動一下：比前一秒動得多。整段一直在動、或者一句話只在開頭動一次，都卡不上。
- 一屏新增資訊不超過 4 塊；旁白已經說了整句不要再上屏，只放關鍵詞。
- 找一個貫穿全片的東西（一個小人、一種顏色、一個形狀）；鏡頭會推拉、跟著重點走；兩個畫面之間盡量用畫面裡的東西接過去。
- 字幕：每條不超過 16 個字，去掉逗號句號；字按真實唸到的時間由淺變深，關鍵詞變色。
- 每做完一段，渲染一小段，用
tools/kazi_check.py量一下再往下做。
聲音
- 配樂在旁白下面 12 到 18 LU；按逐字時間做讓位：句子開始前 0.2 秒壓下去，句間空檔超過 1.2 秒才浮上來。
- 全片停樂 2 到 4 次，留給最重要的幾句。
- 音效從畫面的打點（cue）裡匯出，分四層：落點、過渡、氛圍、擬音。聲音的質感跟畫面走。
- 成片響度 -14 LUFS，真峰值不超過 -1 dBTP，48 kHz。
檢查
python tools/kazi_check.py out/final.mp4 --timeline timeline.json：卡字率、隨機基線、黑幀、一閃而過的幀、長時間不動、響度、音軌、片長。- 不通過就回去改，改完再量。全部通過才叫使用者，並把報告裡的數字原樣告訴使用者，沒量過的不要說「已完成」。
- 使用者要 4K 或 HDR 時，檢查通過以後再出：
tools/master.sh渲染 4K 母版，tools/hdr/hdr_encode.sh出杜比視界 8.4 和 HLG。換了配色要把新的底色、發光色告訴hdr_mask.py，見 docs/06_檢查和發布.md。
工具一覽
| 工具 | 用途 |
|---|---|
tools/doctor.py | 查環境，缺什麼、怎麼裝 |
tools/lint_script.py | 查稿子 |
tools/voice.py | 複製聲音逐句配音，多遍挑一 |
tools/tempo.py | 整體變速不變調 |
tools/pace.py | 規整停頓：句首句尾和句內標點處的靜音 |
tools/polyphone.py | 挑出可能讀錯的多音字，拼成試聽音訊 |
tools/timeline.py | 逐字對齊，生成 timeline.json；--whole 用於一整條現成錄音 |
tools/kazi_check.py | 量卡字率和各種硬傷 |
tools/caption_check.py | 量字幕出現、消失、逐字變亮和配音對不對得上 |
tools/mix.py | 旁白、配樂、音效混音，按逐字時間讓位，統一響度 |
tools/thin_cues.py | 音效打點太多時按優先級篩一遍 |
tools/master.sh | 分段渲染 4K 母版，中斷可續 |
tools/hdr/ | SDR 母版轉 HDR：杜比視界 8.4（HLG 基礎層）和 HLG |
starter/ | Remotion 模板：time.ts 查時間，anim.ts 曲線和彈簧，字幕元件 |
交付時告訴使用者
- 成片路徑、時長、解析度。
- 卡字率、隨機基線、高出隨機多少；沒卡上的關鍵詞是哪幾個、為什麼。
- 檢查出的問題和處理結果；還沒解決的直接說。