yanghhu/ai-voiceover

AI 語音旁白

使用 voiceover CLI（套件 ai-voiceover-studio，Python 3.9+）來產生旁白。

環境檢查

1. voiceover --version — 若缺少：pip install -e "<repo>[edge]" （[edge] = 免費語音，[yaml] = voices.yaml）。
2. 執行 voiceover doctor --json 並修復其回報的 fail（它永不輸出 key）。
3. 引擎：沒有金鑰時使用免費的 edge 引擎（需網路，免帳號）。 MIRAGEA_API_KEY 會將預設引擎切換為 Miragea（聲音複製、情感模型）； OPENAI_API_KEY 啟用 --provider openai。絕不要要求用戶在聊天中貼入金鑰、 絕不輸出金鑰、絕不將金鑰寫入檔案。
4. MP3 輸出和影片需要 ffmpeg（需含 libass 支援燒錄字幕）。

工作流程：為腳本配音

1. 準備腳本（Markdown 或 TXT）。每行或每個段落一個說話者標籤：

   [旁白]：開場白。
   未標籤行延續當前說話者。
   
   [小傑](tags=興奮, speed=1.1)：一個不同角色。
   [pause 1]
   

   標題、HTML 註解、程式碼區塊和表格會被忽略。
2. 語音（可選）。 若無 voices 檔案，每位說話者會自動獲得一個專屬語音， 從腳本語言中選取。若要指定：voiceover voices --json（加上 --provider edge --filter en-GB 可取得 Edge 語音，如 en-GB-SoniaNeural；Miragea 的 voice_id 為演員 ID）。若有兩個語音同名，則詢問用戶選擇哪一個。Miragea 的 語音也可以是公開的參考音訊 URL 加上其精確逐字稿（reference_text）。 僅複製用戶擁有或獲准使用權限的聲音。
3. 若用戶已選定語音，則撰寫 voices.json（大寫的 key）：

   {"旁白": {"actor_id": "en-US-AndrewNeural"}, "小傑": {"actor_id": "en-US-AvaNeural", "speed": 1.05}}
   

4. 試跑（離線，驗證說話者與時間軸）： voiceover script script.md -o out/ --dry-run --json
5. 生成: voiceover script script.md [--voices voices.json] -o out/ --json 輸出 out/voiceover.mp3、out/voiceover.srt、out/manifest.json、out/segments/。
6. 回報儲存路徑與總時長。若指令未以 exit code 0 結束，不可聲稱成功。

其他指令

• 單行：voiceover say "文字" [--voice <voice id|https://ref.wav>] [--ref-text "..."] [--lang en] -o line.mp3
• 無人影片：voiceover video [--images slides/] --script script.md -o video.mp4 [--style clean|box|bold|minimal] [--size 1080x1920] [--speaker-labels] [--subtitles burn|sidecar|none] 預設字幕為燒錄模式。每個片段一張圖片可精確控制幻燈片時間軸；若無 --images 則使用漸層背景。Short 格式請用 --size 1080x1920 --style bold。
• 使用語音辨識而非時間軸生成字幕（Miragea）：加上 --subtitles recognize（多一次 API 呼叫）。
• 在等待超時後繼續任務：voiceover task <task_id> --wait -o out.mp3

規則

• 重複執行相同指令是安全的：不變的片段會從快取取得，遠端請求會重複使用冪等金鑰。僅在用戶想要重新錄製時才使用 --fresh。
• 若等待超時，保留回報的 task_id 並使用 voiceover task 恢復；不要重新提交。
• Exit codes：0 正常，1 提供者任務失敗，2 使用方式/設定/API 錯誤。使用 --json 時，錯誤為 {"error": {"code", "message", "http_status", "retryable"}, "task_id"?}。
• 401：金鑰被拒 → 用戶檢查金鑰變數。403：帳號無 API 存取權限。 429：配額/速率限制 → 請等待，勿重複嘗試。400：修正文字/語音/速度/標籤。
• proxy_unsupported（edge）：請設定 VOICEOVER_EDGE_PROXY 或對該指令取消設定 HTTPS_PROXY。
• 語言：Edge 支援 75 種語言；Miragea 支援中文、英文、日文、韓文、德文、法文、俄文、葡萄牙文、西班牙文、義大利文（含聲音複製）。