螢幕錄影配上旁白 是做什麼的？
為螢幕錄影配上旁白時，最耗時的並非語音本身，而是同步：將每一句話對齊到它所描述的點擊動作，並修補句子比動作還長的片段。本技能能自動完成這兩件事，絕不讓旁白偏移或重疊。
使用時機
- 「為這個示範 / 教學 / 螢幕錄影加上旁白。」
- 「我錄了螢幕但沒有聲音，幫我配上旁白」或「我不想用自己的聲音 / 口音。」
- 「讓旁白與螢幕上的動作同步。」
步驟
-
確認
MIRAGEA_API_KEY已設定（切勿印出）。語音：向使用者詢問一次他們的 Miragea 語音 ID，或是其聲音的公開 URL 及其確切文字。建議使用export MIRAGEA_VOICE_ID=...這樣就不必再次詢問。只克隆使用者擁有或獲得許可的聲音。 -
找出步驟並建立腳本模板：
python3 scripts/scenes.py demo.mp4 # -> demo.frames/*.jpg, demo.frames/steps.json, demo.script.txt -
檢視
demo.frames/中的幀（你可以讀取圖片），並在demo.script.txt中為每個時間戳後方撰寫一句清晰的旁白，取代# step註解。遵守~N words的提示，讓句子在下一步驟開始前能說完。可以自由合併、移動或刪除步驟。如果使用者提供了自己的旁白腳本，則將句子對應到相符的時間戳。 -
不需花費即可檢查時間：
python3 scripts/voiceover.py demo.mp4 demo.script.txt --dry-run如果使用者希望完全沒有凍結幀，請縮短標記為
will freeze的句子。 -
渲染：
python3 scripts/voiceover.py demo.mp4 demo.script.txt --voice VOICE_ID # 字幕輸出為檔案 python3 scripts/voiceover.py demo.mp4 demo.script.txt --burn --music bed.mp3 # 燒錄字幕 + 降低背景音量 -
告知使用者從輸出的 JSON 中取得的路徑：
video（有旁白的 MP4）、voice_track（供編輯器使用的 WAV）、srt/vtt。如果frozen_seconds大於零，請告知。 -
若要修改某行，編輯腳本後再次執行步驟 5：未修改的行會從快取中直接取用，不另計費。
腳本格式
[00:00] 歡迎使用 Acme。這是您登入後看到的儀表板。
[00:04] 點擊「新增專案」，輸入名稱，然後選擇擁有該專案的團隊。
[01:02.5] 就是這樣。您的專案已準備就緒。
接受的時間戳格式：[mm:ss]、[h:mm:ss]、mm:ss.s、12.5s。以 # 開頭的行是註解。
同步原理
- 每句旁白會在其時間戳準時開始；在下一個步驟前保留 0.25 秒的緩衝。
- 比其時間區間更長的旁白會加速播放，最高至
--max-speed（預設 1.15 倍，仍聽起來自然）。 - 若仍無法容納，影片會停留在該步驟的最後一幀，直到旁白結束，然後繼續播放。後續的旁白會相應延後，因此同步永遠不會錯亂。
- 字幕是根據每句旁白的實際朗讀長度來定時（最多 2 行 x 42 個字元）。
- 音量會標準化至約 -16 LUFS（YouTube/網路標準）。若有提供背景音樂，其音量會在說話時自動降低。
選項
| 標記 | 預設值 | 說明 |
|---|---|---|
--voice ID / --ref-url URL --ref-text TEXT | 環境變數 | 已儲存的 Miragea 語音，或從公開片段克隆（確切文字 = 較便宜的 1 倍費率） |
--model | expressive | 或 standard |
--max-speed | 1.15 | 凍結幀前的最大加速倍數 |
--burn | 關閉 | 將字幕燒錄進影片中 |
--music FILE | 無 | 背景音樂，循環播放並自動降低音量 |
--keep-audio | 關閉 | 保留錄影的原始聲音，以較低音量與旁白共存 |
--dry-run | 顯示時間區間規劃並附上估計的說話速率；不呼叫 API | |
-o FILE | VIDEO.voiceover.mp4 | 輸出路徑；原始檔案絕不會被修改 |
費用與限制
Miragea 按字元收費（使用已儲存的語音或確切的參考文字為 1 倍費率；即時費率查詢 GET https://miragea.ai/v1/capabilities）。一個 3 分鐘的示範通常需要 2,000-3,000 個字元。每句旁白不得超過 2,000 個字元。在 Miragea 的上傳端點推出之前，參考片段必須使用公開 URL。
疑難排解
no timestamp/not after the previous line-> 修正錯誤中指出的腳本行。no voice chosen-> 加上--voice或設定MIRAGEA_VOICE_ID。401金鑰錯誤，402請到 miragea.ai 充值，429請等待並重新執行（快取的行不會再次計費）。scenes.py產生的步驟太多或太少 ->--threshold 0.02（更多）/0.08（更少），--min-gap。
請參閱 examples/ 目錄，裡面有真實的腳本、規劃 JSON 以及它所產生的字幕。