whisper.cpp 离线语音识别指南：三步跑通第一次转写
【免费下载链接】whisper.cppPort of OpenAI's Whisper model in C/C++项目地址: https://gitcode.com/GitHub_Trending/wh/whisper.cpp
会议录音、采访音频想转成文字，又不想把音频发到任何云端服务上。whisper.cpp 是 OpenAI Whisper 语音识别模型的 C/C++ 移植版本，完全本地运行：输入 16 kHz 的 WAV，输出带时间戳的文本，全程不需要联网。
先跑通：三步验证最小可用
第 1 步，拿代码：克隆仓库并进入目录。
git clone https://gitcode.com/GitHub_Trending/wh/whisper.cpp第 2 步，拿模型：base.en 文件约 142 MiB，是通用的默认选择。
bash models/download-ggml-model.sh base.en第 3 步，编译并跑样例：样例音频是仓库自带的samples/jfk.wav。
cmake -B build && cmake --build build --config Release && ./build/bin/whisper-cli -f samples/jfk.wav跑完会得到类似[00:00:00.000 --> 00:00:00.850] And so my fellow Americans...的输出，说明离线转写链路已经通了。
能力清单
多平台可运行
官方支持 macOS（Intel 与 Apple Silicon）、Linux、Windows、Android、iOS、树莓派、WebAssembly 和 Docker。Apple Silicon 上编码器可以走 Metal 或 Core ML 在 GPU 执行，NVIDIA 显卡可开 CUDA 加速。
模型档位
从 tiny 到 large-v1、large-v2、large-v3，外加 large-v3-turbo。带.en后缀的版本只识别英语，体积更小、速度略快。
量化压缩
内置 quantize 工具，可以把 ggml 模型压成 q4_0、q5_0、q8_0 等量化版本，磁盘和内存占用都下降，精度损失有限。
多语言转写与翻译
不带.en的多语言模型支持多种语言转写；加--translate参数后，非英语音频可以直接转成英文输出。
模型选型对照表
| 场景 / 设备 | 推荐配置 | 磁盘 / 内存占用（约） |
|---|---|---|
| 树莓派、手机、内存受限的嵌入式 | tiny，或量化版 tiny-q5_1 | 75 MiB / 273 MB |
| 普通 PC、日常转写 | base.en | 142 MiB / 388 MB |
| 多语言、精度要求中等 | small | 466 MiB / 852 MB |
| 服务端专业转写 | large-v3 / large-v3-turbo | 2.9 GiB / 3.9 GB |
内存吃紧时优先上量化模型，并用-t参数降低线程数。
接入示例
核心 API 是 C 风格的，从加载模型到读取结果只需几行：
struct whisper_context * ctx = whisper_init_from_file("models/ggml-base.en.bin"); whisper_full_params p = whisper_full_default_params(WHISPER_SAMPLING_GREEDY); whisper_full(ctx, p, pcmf32.data(), pcmf32.size()); for (int i = 0; i < whisper_full_n_segments(ctx); i++) printf("%s\n", whisper_full_get_segment_text(ctx, i)); whisper_free(ctx);实时麦克风输入、HTTP 识别服务、语法约束输出等完整场景，都放在 examples 目录里，可以直接照着抄。
踩坑清单
模型下载失败怎么办
症状：运行models/download-ggml-model.sh长时间卡住或报错。原因：模型文件托管在 Hugging Face，部分网络环境下连接慢或不稳定。解法：换一台能连通 Hugging Face 的机器，手动下载同名文件（如ggml-base.en.bin），放到本仓库的models/目录，再正常跑命令。
提示音频加载失败怎么办
症状：whisper-cli 报加载失败，没有任何转写输出。原因：whisper-cli 只认 16 位、16 kHz、单声道 WAV。MP3、44.1 kHz 或立体声文件都不能直接喂进去。解法：先用 ffmpeg 转格式：
ffmpeg -i input.mp3 -ar 16000 -ac 1 -c:a pcm_s16le output.wav设备内存不够或跑得太慢怎么办
症状：medium、large 模型直接 OOM，或者十几秒的音频要转好几分钟。原因：内存占用随模型档位上升，large 档需要约 3.9 GB；线程数开得过高也会拖慢速度。解法：换成 tiny 或 base 档，或用 quantize 生成 q4_0 量化模型；运行时用-t把线程数降到 2 再试。
收尾
最省事的起步方式，就是先在自己机器上把上面三步做完，确认jfk.wav的输出符合预期，再去看 examples/cli 目录的源码接入自己的音频。下一步动作：跑一条./build/bin/whisper-cli -f samples/jfk.wav，核对第一行文本和音频内容是否一致。
【免费下载链接】whisper.cppPort of OpenAI's Whisper model in C/C++项目地址: https://gitcode.com/GitHub_Trending/wh/whisper.cpp
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
