轉錄影片
使用內建的 whisper.cpp 服務,在本地端轉錄任何影片/音訊檔案。無需外部專案或雲端 API。回傳逐字時間戳(用於同步疊加字幕/標註)。
使用時機
- 「轉錄這段剪輯/影片/音訊」、「取得附時間戳的逐字稿」。
- 作為
/produce-video的一個子步驟。
執行方式
一切均由內建的執行器驅動 — 無需要求使用者管理 Docker:
node scripts/transcribe.mjs <影片或音訊路徑> [--out <目錄>] [--port 9111] [--language en] [--no-word-ts] [--task transcribe|translate]
node scripts/transcribe.mjs --stop # 停止暖容器
執行器會:
- 檢查 Docker 守護行程是否可連線(若無法連線則顯示明確的錯誤訊息與指引)。
- 若
transcribe-video-whisper映像檔不存在,則從assets/whisper-service/建置該映像檔(首次建置較慢:會編譯 whisper.cpp 並內嵌ggml-base.en.bin模型)。 - 啟動
transcribe-video-whisper容器(主機連接埠 9111 → 容器 9001);若容器已在執行則重複使用,若已停止則docker start。 - 等待
GET /healthz回報正常。 - 使用本機 ffmpeg 從輸入檔案中提取 16 kHz 單聲道 WAV(whisper.cpp 僅解碼 WAV),然後透過 POST 將其傳送至
/transcribe,並帶有word_ts=true。 - 將
transcript.txt、transcript.srt、transcript.words.json寫入--out(預設為輸入檔案所在目錄),並將 JSON 結果列印至 stdout。
輸出
transcript.txt— 純文字。transcript.srt— 字幕文字。transcript.words.json—[{ "word", "start", "end" }],單位為秒,按時間排序。這是疊加字幕/標註的同步來源。
stdout 結果列(供程式化呼叫者如 /produce-video 使用):
{ "ok": true, "outDir": "...", "wordCount": 38, "segmentCount": 2, "files": { "txt": "transcript.txt", "srt": "transcript.srt", "words": "transcript.words.json" } }
需求
- 必須安裝 Docker — Whisper 服務在容器中執行,因此必須安裝並執行 Docker Desktop。執行器會先檢查此項,若 Docker 遺失或其守護行程未執行,則會顯示明確的錯誤訊息與安裝/啟動指引;沒有非 Docker 的替代方案。
- 必須安裝 ffmpeg(用於為 Whisper 提取 16 kHz 單聲道 WAV)— 執行器會預先檢查,若未在 PATH 中則會顯示明確的錯誤訊息。
- Node ≥ 22。
備註
- 容器會保持執行狀態 (
--restart unless-stopped) 以便暖啟動重複使用;使用--stop停止。 - 若要求逐字時間戳但未回傳任何資料,執行器會顯示明確的錯誤訊息(疊加字幕的同步依賴於此)。
- 請參閱
references/了解 Docker 生命週期、API 格式以及套件來源。