whisper.cpp 语音转写与字幕工作流

whisper.cpp 把 Whisper 推理带到本地 C/C++ 环境，适合离线转写、字幕生成和端侧集成。项目命令与模型格式持续演进，下面保留稳定的工作流，不把某个历史二进制名称当作永久接口。

1. 获取并构建

git clone https://github.com/ggml-org/whisper.cpp.git
cd whisper.cpp

cmake -B build
cmake --build build -j --config Release

构建完成后，先查看生成的 CLI 帮助，确认当前参数：

./build/bin/whisper-cli --help

2. 下载模型

仓库提供模型下载脚本：

./models/download-ggml-model.sh base

模型越大，通常识别质量越高，同时需要更多内存和计算。中文转写不要选择带 .en 的纯英文模型。

如果使用自行微调的 Hugging Face 模型，需要通过仓库当前提供的转换脚本生成兼容格式。转换前保留 tokenizer、配置和原始权重。

3. 统一音频格式

排错时先把输入转换为 16 kHz、单声道、16-bit PCM WAV：

ffmpeg -i input.mp4 \
  -ar 16000 \
  -ac 1 \
  -c:a pcm_s16le \
  output.wav

再执行转写：

./build/bin/whisper-cli \
  -m models/ggml-base.bin \
  -f output.wav \
  -l zh

若当前版本的可执行文件或参数不同，以 --help 为准。

4. 生成字幕

使用 CLI 的 SRT 输出选项生成字幕文件，再用 ffmpeg 烧录：

ffmpeg -i input.mp4 \
  -vf "subtitles=input.srt" \
  -c:a copy \
  output-with-subtitles.mp4

字幕生成后应人工检查：

• 专有名词和中英文混排；
• 断句与阅读速度；
• 时间轴是否重叠；
• 长静音后的漂移；
• 背景音乐或多人对话造成的误识别。

如果平台支持外挂字幕，优先保留独立 SRT；硬字幕不可关闭，也不利于后续修改。

5. 量化与加速

量化可以降低模型体积和内存占用，但可能损失少量识别质量。先用原始模型建立准确率基线，再对比量化版本。

Apple 平台可以使用 Metal 或 Core ML 路径，NVIDIA 环境可以使用 CUDA。具体构建开关会随项目版本变化，应该从当前仓库的构建文档确认，而不是复制旧 Makefile 命令。

判断加速是否生效时，记录同一段音频的：

• 总耗时与实时倍率；
• 峰值内存；
• 关键句错误率；
• 首次运行与后续运行差异。

6. 实时转写

实时流式转写还要处理音频窗口、重叠区间和断句。窗口太短会缺少上下文，太长则增加延迟。先确定能接受的延迟，再调整 step、length 和 keep 等参数。

[!TIP] 本地转写的完整质量来自“模型 + 音频预处理 + 语言设置 + 后处理”。只更换更大的模型，不一定能解决音量过低、声道混乱或专有名词的问题。

一条可复现的字幕流程

1. 用 ffmpeg 提取并标准化音轨；
2. 固定模型、语言和推理参数；
3. 输出 SRT；
4. 人工校正术语、断句和时间轴；
5. 保留原始 SRT；
6. 按发布平台需要选择外挂或烧录字幕。

这样既能享受自动转写的效率，也不会把未经检查的模型输出直接变成最终内容。