影片字幕
一個指令就能將影片（或音訊）檔案轉換為易於閱讀的字幕，並可選擇性地產生含字幕的 MP4。原生的語音辨識片段經常在單詞中間斷開（例如「cen」/「ts」）且持續時間過長；此技能會重建完整單詞並重新調整為適當的提示。
使用時機
- 「為這部影片加上字幕」、「為我的演講製作 SRT」、「燒錄字幕進去」。
- 「製作 TikTok/Reels/Shorts 風格的字幕」-> 使用
--style shorts --burn。 - 使用者需要
.vtt檔案用於網站的<track>標籤或上傳至 YouTube。
步驟
-
確認
MIRAGEA_API_KEY已設定（切勿印出）。若缺失，請使用者在 https://miragea.ai 建立金鑰並執行export MIRAGEA_API_KEY=...。 -
對使用者提供的檔案執行腳本：
python3 scripts/captions.py path/to/video.mp4 # -> video.srt + video.vtt python3 scripts/captions.py path/to/video.mp4 --burn # + video.captioned.mp4 python3 scripts/captions.py path/to/short.mp4 --style shorts --burn # 彈出字幕，居中對齊 -
讀取輸出的 JSON（包含
srt、vtt、video、cues），並將檔案路徑提供給使用者。 -
若使用者想修改文字，請編輯
.srt檔案內容（保留時間戳），然後重新執行--burn： 轉錄稿會快取在<file>.transcript.json，因此重新執行不會產生額外費用。
選項
| 旗標 | 預設值 | 功能說明 |
|---|---|---|
--style standard | 是 | 2 行 x 42 字元，每個提示 1-7 秒（廣播慣例） |
--style shorts | 每個提示 1-3 個單詞，大寫，燒錄時居中對齊 | |
--burn | 關閉 | 寫出 <name>.captioned.mp4（H.264，原始音訊保留） |
--upper | 關閉 | 標準字幕全部大寫 |
--out-dir DIR | 輸入檔案所在目錄 | 輸出檔案的存放位置 |
--force | 關閉 | 忽略快取的轉錄稿，重新進行轉錄 |
費用與限制
僅上傳 16 kHz 的單聲道音訊軌（不上傳影片），每個檔案最長 90 分鐘 / 1 GB。Miragea 每 1 秒音訊收取 3 點點數；重新執行快取的轉錄稿則免費。查詢即時費率請使用 GET https://miragea.ai/v1/capabilities。
故障排除
ffmpeg not found-> 安裝 ffmpeg（brew install ffmpeg、sudo apt install ffmpeg、winget install ffmpeg）。401-> 金鑰錯誤；402-> 請至 miragea.ai 充值；429-> 請稍後再執行（可安全重試）。- 在音樂較重的片段中字幕稍微超前/落後：在修剪片頭後，使用
--force重新執行。
請參考 examples/ 目錄中的範例輸出。