中文視頻轉英文配音
把中文口播視頻轉成英文配音成片：克隆原說話人的音色，面向海外買家重寫文案，輸出單個 MP4。
一條命令
cd "<項目根>"
$env:MINIMAX_API_KEY = "<MiniMax 國內站 Key>"
$env:VOLC_API_KEY = "<火山 API Key>"
.\\.venv\Scripts\python.exe scripts\dub.py --src "<視頻路徑>" --slug "<短名>"
產物：
| 位置 | 內容 |
|---|---|
out/<短名>_EN_dubbed.mp4 | 成片（唯一交付） |
out/<短名>_EN.srt / _ZH.srt | 中英字幕 |
work/batch/<短名>/REPORT.md | 耗時、合成輪次、成本 |
常用參數：--until translate（只出文案，不合成）、--from fit（從某階段開始）、--force（忽略已存狀態）。
六個階段
1 prep 提取音訊 + demucs 人聲分離 + 記錄視頻時長
2 asr 火山詞級識別 → 中文分句時間軸
3 translate DeepSeek → 英文文稿（受眾切換 + 詞數預算 + 數字寫單詞）
4 fit 跑 N 輪合成 → 各自實測 → 按"最多能填到多少"評分取最優
5 place 按時間軸鋪設 + 句界插停頓 + 寫字幕（真實詞級時間戳）
6 mux 配背景音樂 + 響度歸一 → MP4
失敗後重跑同一條命令即可，已完成階段自動跳過（含"產物必須比輸入新"校驗）。
前置條件
| 項 | 說明 |
|---|---|
| 音色 | work/voice.json，跑一次 clone_voice.py 生成即可，所有視頻共用，不需重複克隆 |
| 火山 Key | 錄音檔案識別（volc.seedasr.auc） |
| MiniMax Key | 國內站 api.minimaxi.com，需實名 + 餘額（否則 2038 / 1008） |
| DeepSeek Key | 官方 api.deepseek.com |
| 依賴 | demucs torch numpy requests openai soundfile |
| 音樂 | 一個放 .wav 的目錄，見 config.py 的 BGM_DIR |
所有服務直連，dub.py 會強制清掉代理變數。
必讀：18 條實測經驗
完整清單在 docs/LESSONS.md。最容易踩且代價最高的幾條：
- 受眾要切換，不只是翻譯 —— 很多素材原本是對國內出口商說的（"做外貿的朋友們"），英文必須直接對海外買家說話。規則在
translate.py的SYSTEM_FILL裡。 - 數字在翻譯階段就寫成英文單詞 ——
20,000算 1 個詞卻讀成 2 個詞，會讓所有長度計算偏掉；留著阿拉伯數字還可能被逐位讀。 - atempo 已禁用 —— 不要為了鋪滿而讓人說得更快，要把文案壓短。
- 句界拼接必須加淡入淡出 —— 切點在非零波形處會產生咔哒聲。
- 驗收音訊瑕疵不能只看全檔案最大跳變 —— 會被源檔案的更大跳變掩蓋，要看跳變分佈。
- 斷點續跑必須校驗產物比輸入新 —— 否則會靜默交付舊稿配音。
詳細機制與踩坑過程見 docs/USAGE.md（原《使用說明》）與 docs/REPORT.md（實施報告）。
已知限制
- 中文資訊密度高於英文，極少數素材需要在保留賣點的前提下刪句（工具會自動做，報告裡會記錄）。
- 鋪滿度一般 93–100%，末尾由背景音樂補足。
Eva之外唸不對的專有名詞，加進synth_single.py的TTS_RESPELL字典（只影響 TTS 輸入，字幕不變）。
建議工作流
新素材先用一條跑完整流程給客戶確認（音色／語速／音樂／停頓），確認後再批量。批量時逐條會寫明成本。