短影片語音旁白
輸入劇本，產出可直接上傳的短影片。不同於其他工具根據文字長度猜測字幕時間，此技能會先完成語音軌道後再進行轉錄，確保每條字幕精準對應實際說話時間。
使用時機
- 「將這段劇本 / 這些技巧 / 這篇文章轉換為 Short（或 Reel、TikTok）。」
- 「製作一部無臉短影片，附帶語音旁白和字幕。」「使用我的聲音。」
- 「從這些劇本製作 5 部短影片」-> 每個劇本檔案執行一次。
步驟
-
確認已設定
MIRAGEA_API_KEY（切勿輸出顯示）。語音：使用者的 Miragea 語音 ID，或一段公開聲音片段網址及其精確文字。建議執行export MIRAGEA_VOICE_ID=...。僅複製使用者擁有或有權使用的語音。 -
撰寫劇本：每個場景一個短段落，場景間以空白行分隔，總字數 120-170 字約可製成 45-60 秒的 Short。第一場景以吸引人的鉤子開頭。可選擇在某場景開頭使用
@file指定背景：三個讓任何語音旁白聽起來更專業的小技巧。 @broll/desk.mp4 首先，在小房間裡錄音，使用軟質家具。回音比噪音更難處理。 -
渲染：
python3 scripts/short.py tips.txt --voice VOICE_ID # 使用漸層背景 python3 scripts/short.py tips.txt --media ./broll --music bed.mp3 # 使用使用者的圖片/片段 + 音樂 -
從輸出的 JSON 中提供使用者
video和srt路徑。提供編輯選項：修改某場景文字後重新執行；僅該場景會重新語音合成，其餘場景從快取中取得。
自動化處理
| 步驟 | 說明 |
|---|---|
| 語音 | 每個場景使用 Miragea 語音合成；場景間 0.18 秒呼吸停頓 |
| 字幕時間 | 完成的語音軌道由 Miragea 轉錄；1-3 字大寫提示，置於畫面下方 1/3 處 |
| 圖片 | 裁切為 9:16，每個場景交替使用緩慢縮放 |
| 片段 | 裁切為 9:16，循環或修剪至場景長度，移除原始聲音 |
| 無媒體 | 動態漸層背景（4 種色板，循環切換） |
| 音樂 | 循環播放，音量 30%，在語音下方進行側鏈閃避 |
| 響度 | 整合 -14 LUFS，最高 -1 dBTP（符合 Shorts/TikTok/Reels 標準） |
| 重新執行 | 每個場景的語音和轉錄內容皆會快取；未修改的場景不重複計費 |
選項
| 標誌 | 預設值 | 功能說明 |
|---|---|---|
--voice ID / --ref-url URL --ref-text TEXT | 環境變數 | 使用已儲存的 Miragea 語音，或從公開片段複製語音 |
--media DIR | 無 | 在未指定 @file 的場景中使用的圖片/片段，按檔名排序 |
--music FILE | 無 | 背景音樂，自動閃避 |
--lowercase | 關閉 | 使用句子大小寫字母字幕 |
--no-captions | 關閉 | 跳過字幕（不產生轉錄費用） |
--model | expressive | 或 standard |
-o FILE | SCRIPT.short.mp4 | 輸出檔案路徑 |
費用與限制
語音：依字元計費（一篇 150 字的 Short 約 850 個字元）。字幕時間：依已完成語音軌道的長度，每秒 3 點（25 秒約 75 點）；後續從快取讀取免計費。即時費率：GET https://miragea.ai/v1/capabilities。每個場景不得超過 2,000 個字元。若總時長超過 3 分鐘（YouTube Shorts 上限）會顯示警告。
疑難排解
media file not found->@後的路徑是相對於劇本檔案或--media資料夾。No such filter: gradients-> ffmpeg 版本低於 6.1；請升級，或傳入--media參數使用圖片。401密鑰錯誤，402請至 miragea.ai 儲值，429請稍後重新執行（已快取的內容不會重複計費）。
請僅使用您擁有版權的音樂和影像素材。請參閱 examples/ 目錄中的實際劇本與輸出範例。