viral-voice 是做什麼的？
執行一次設定：bash setup.sh。本指南中的腳本與此檔案位於同一目錄，請使用它們的完整路徑。
1. 選擇語音
詢問使用者想要哪種語音，並直接說明權衡：
| 選項 | 成本 | 品質 | 字幕時間對齊 |
|---|---|---|---|
| 免費語音（預設） | 免費 | 清楚，略顯平淡 | 精確，每個單詞隨朗讀亮起 |
| ElevenLabs | 需付費方案或使用免費額度 | 最自然 | 若模型提供時間戳則精確 |
| 使用者自己的語音 | 免費 | 最個人化 | 每行內估算。若按節拍錄製則更緊密 |
通常使用者自己的語音效果最好，因為聽得出來是認真的。無臉短影片不一定要沒聲音。
# 免費語音。馬拉雅拉姆語預設選用 Midhun。使用 --voice ml-IN-SobhanaNeural 可選擇另一種馬拉雅拉姆語語音。
python3 voice.py <project>
# ElevenLabs。需要 ELEVENLABS_API_KEY 和語音 ID。馬拉雅拉姆語需要支援它的模型，例如 eleven_v3。
python3 voice.py <project> --engine elevenlabs --voice <voice id> --model eleven_v3
# 使用者自己的錄音，一次性錄製整個腳本
python3 voice.py <project> --engine file --audio take.m4a
# 使用者自己的錄音，每個節拍一個檔案（voice/b1.m4a，voice/b2.m4a）。這樣時間對齊更精準。
python3 voice.py <project> --engine file --audio voice/
任何其他工具的輸出的音訊也可透過 --engine file 使用，因此如果有連接語音生成工具，請為每個節拍生成一個檔案，然後傳入資料夾。
對於錄音，每一行的時間是根據停頓間的單詞長度來推算的，因此在單次長錄音中，字幕可能會有約一秒的誤差。在我們對一個真實的 48 秒馬拉雅拉姆語短影片測試中，大部分字幕的誤差在半秒內。如果看起來不對，請按節拍錄製。
免費語音是透過開源工具 edge-tts，使用 Microsoft Edge 的朗讀服務。這不是官方 API，因此可能會有變動或停止服務，使用者若用於客戶或商業作品，應先查閱相關條款。如果使用者是為企業製作影片，請告知此點。
2. 需要有人聆聽
這些工具無法聽到音訊，timing.json 只顯示腳本中的單詞，永遠不會知道語音實際說了什麼。因此這裡沒有任何東西可以確認發音。請使用者聆聽 voice.wav，或者如果有連接轉錄工具，則進行轉錄並比對。如果兩者都沒有，請直接說明目前處於「未聽取」狀態。
當語音唸錯某個單詞時，請在 script.json 中對應節拍的 "tts" 屬性加入一個它會正確發音的拼寫，然後重新執行。字幕會持續使用 say。盡量保持 tts 與 say 的單詞數量相同。如果不同，voice.py 會印出提示，並且該節拍的字幕時間會變成估算值。
如果某句台詞聽起來很急促，請調整 --rate（預設 +8%）。--gap 設定節拍之間的停頓。
來自 lint_script.py 和 timing.py 的長度估算只是粗略值，可能短 10% 到 15%。實際長度是 voice.py 印出的結果。若要達到特定長度，請調整 --rate 或刪減文字，然後重新執行。
3. 再次查看畫面
真實語音已移動所有內容，因此請在最終渲染前查看：
node <viral-animate folder>/render.mjs <project> --stills beats
開啟 stills/beats.jpg。綁定到 k、d 或 kit.at 的動畫已跟上語音。任何使用固定秒數的動畫則不會跟隨，請在 scenes.js 中修正這些。
4. 音效
sfx.py 會自動執行：開頭一個低沉的撞擊聲，每個節拍變換時一個安靜的呼嘯聲。對於安靜、情感豐富的作品，請在 script.json 中設定 "sfx_auto": false 來關閉這些效果。若要添加更多音效，請列出它們，並指定在某個單詞上，以保持同步：
"sfx": [{ "beat": "b2", "word": "charger", "kind": "pop", "db": -14 }]
使用 "at": 1.1 代替 word，以指定節拍開始後的秒數。如果指定的單詞在該節拍中不存在，系統會停止並顯示明確的錯誤訊息。音效種類：
| 種類 | 聽起來像 | 適用場景 |
|---|---|---|
whoosh swell | 上升的空氣聲 | 變化、物體飛入 |
swipe | 快速的空氣刷動聲 | 快速移動 |
pop | 小而圓潤的爆裂聲 | 物體出現 |
tick | 極小的乾燥滴答聲 | 計數器、小瞬間 |
click | 清脆的開關點擊聲 | 電燈開關、按鈕 |
knock | 指節敲木頭聲 | 門、桌子 |
thump | 低沉的撞擊聲 | 開場、重大揭露 |
stamp | 帶重量的硬拍打聲 | 裁決、觀點落地 |
這些都是合成音效，因此沒有版權風險。此工具包不添加音樂：這樣能保持語音清晰，並避免版權警告。如果使用者想要音樂，可以在 Instagram 編輯器中添加。
5. 完成
python3 finish.py <project>
這會以真實語音時間渲染全品質的畫面，混合音效，將音量標準化至約 -14 LUFS，並寫出 final.mp4。加上 --no-render 可僅重新混音。
試用版本： 要測試其他鉤子，請複製專案資料夾，將另一個鉤子的 say 放入 b1，將其 label 放入頂層的 label，然後在複製的資料夾上執行 voice.py 和 finish.py。綁定到 k、d 或 kit.at 的動畫會跟隨。請檢查任何 kit.at 的單詞是否仍在新鉤子中。
然後前往 /viral-check。在此之前不要宣告短影片已完成。