转录视频
使用捆绑的 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 结果。
输出
transcript.txt— 纯文本。transcript.srt— 字幕文本。transcript.words.json—[{ "word", "start", "end" }],以秒为单位,按时间排序。这是叠加/字幕的同步源。
标准输出结果行(供 /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 形态以及供应商来源信息。