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++ 移植版，它不联网、不吃显卡也能跑，一条命令就能把音频变成文字、字幕甚至带时间戳的数据。读完这篇文章，你将收获：

• 15 分钟内跑通第一条 whisper.cpp 语音转文字命令
• 一套"按需点菜"的模型选择方法，以及给模型"瘦身"的量化技巧
• 10 余个核心参数的实战用法，让转录又快又准
• SRT 字幕、JSON、CSV 等多种格式的一键导出方法
• 实时转录、说话人分离、Karaoke 歌词等进阶玩法
• 两份可直接套用的实战案例，以及常见报错的应对思路

下面我们按"从零到一"的路线，一步步把这位能干的"转写员"请进你的电脑。

第一章 先认识它：一个能离线工作的语音识别引擎

说起语音识别，很多人第一反应是"得连云端 API、按分钟付费、还得担心隐私"。whisper.cpp 恰好把这些顾虑都解决掉了。

它是 OpenAI Whisper 模型的一个极简 C/C++ 实现，核心代码只有两个文件（whisper.h和whisper.cpp），其余部分依赖一个叫 ggml 的机器学习底层库。它的特点可以概括为四点：

• 纯本地运行：音频数据不出设备，录音内容只属于你自己，隐私安全有保障；
• 零依赖、轻量：不需要 Python 环境、不需要庞大的深度学习框架，编译出的程序很小；
• 多平台通吃：macOS、Linux、Windows 都能跑，还支持 iOS、Android，甚至能编译成 WebAssembly 塞进浏览器；
• 硬件适配灵活：纯 CPU 就能工作，x86 有 AVX 加速、苹果芯片有 NEON 与 Metal、NVIDIA 显卡走 CUDA、Intel 设备可借力 OpenVINO。

一句话总结：它把"语音转文字"这件事从云端搬回了本地，像一个随叫随到的私人速记员。接下来，我们就正式把它"雇佣"下来。

第二章 15 分钟快速上手：跑通你的第一句转录

与其纸上谈兵，不如先动手。我们把安装、下载模型、运行转录串成一条流水线，照着敲即可。

第一步：把代码仓库请到本地

在终端里执行：

git clone https://gitcode.com/GitHub_Trending/wh/whisper.cpp cd whisper.cpp

第二步：编译项目

Linux/macOS 下推荐用 CMake：

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

Windows 用户如果用的是 MSVC（Visual Studio），把第一句换成指定生成器：

cmake -B build -G "Visual Studio 17 2022" cmake --build build --config Release

编译完成后，可执行程序在build/bin/目录下，主角叫whisper-cli。

第三步：下载一个模型

模型相当于转写员的"业务能力"，得先准备好。项目提供了一个下载脚本，一行命令即可：

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

这条命令会下载"base 英文模型"（适合入门），默认放进models/目录，文件名形如ggml-base.en.bin。

第四步：转录第一段音频

仓库自带了示例音频samples/jfk.wav，直接用默认模型转录：

./build/bin/whisper-cli -f samples/jfk.wav

稍等几秒，你就能在屏幕上看到带时间戳的英文转写结果。至此，你的第一条 whisper.cpp 语音转文字任务宣告成功。✅

顺带一提，项目还提供了make base.en这种一键命令，它会自动完成"下载模型 + 转录 samples 目录下所有 wav"的整套流程，适合懒得敲命令的同学。

把第一句跑通之后，接下来要操心的问题就变成了：换不同场景时，该用哪个模型？

第三章 像点菜一样选模型：五档配置怎么挑

whisper.cpp 的模型家族按体积从小到大分成 tiny、base、small、medium、large 五档，每档都有纯多语言版和仅英文版（带.en后缀）。选模型就像点菜：胃口（精度要求）和预算（硬件资源）得平衡。

挑选时记住一个朴素原则：内存够就往上选一档，硬件吃紧就往下降一档。英文内容优先考虑.en版，它体积更小、速度更快；多语言内容则要用不带后缀的版本。

下载脚本支持的型号很全，从tiny、small.en-tdrz（带说话人分离能力）到large-v3、large-v3-turbo（高速大模型）都在列表里：

./models/download-ggml-model.sh small.en-tdrz # 支持说话人分离 ./models/download-ggml-model.sh medium # 多语言中档 ./models/download-ggml-model.sh large-v3 # 多语言顶配

模型选好了，如果机器仍吃力，还有最后一招——量化。

给模型"瘦身"：量化到底省了多少

量化可以把模型权重从高精度压缩到低精度，体积变小、推理变快，代价是微乎其微的精度损失。quantize工具就是干这个的：

# 把 base.en 模型量化为 Q5_0 格式 ./build/bin/quantize models/ggml-base.en.bin models/ggml-base.en-q5_0.bin q5_0

三种主流量化格式对比如下：

量化后的模型用法不变，只是路径换成新文件：

./build/bin/whisper-cli -m models/ggml-base.en-q5_0.bin samples/jfk.wav

小贴士：下载脚本里也直接提供了预量化的base-q8_0、large-v3-q5_0等型号，不必每次都手动量化。

模型就绪后，下一个现实问题浮出水面：我的音频是 MP3、是视频，不是 WAV，怎么办？

第四章 音频"投喂"前的预处理：格式转换是关键

whisper-cli 目前只认16-bit PCM 单声道 WAV文件。好消息是，任何格式都能用 ffmpeg 这个万能转换器搞定，一句命令即可：

# MP3 转 WAV（16kHz 采样率、单声道，是语音识别的黄金配置） ffmpeg -i input.mp3 -ar 16000 -ac 1 -c:a pcm_s16le output.wav # 从视频中抽音轨并转换 ffmpeg -i video.mp4 -vn -ar 16000 -ac 1 -c:a pcm_s16le audio.wav

参数含义拆解一下：-ar 16000把采样率设为 16kHz，-ac 1强制单声道，-c:a pcm_s16le指定 16-bit PCM 编码。这三件套组合拳打下来，任何音频都能变成 whisper.cpp 的"标准口粮"。

第五章 让转录结果更听话：核心参数逐个击破

格式搞定，接下来是参数调教环节。这就像给转写员交代工作细则，说清楚"今天重点听什么、听多久、用几个人干"。

语言指定与自动检测

默认情况下，模型会尝试自动判断语言。手动指定往往更稳妥、速度也更快：

# 指定中文 ./build/bin/whisper-cli -m models/ggml-medium.bin -l zh -f audio.wav # 自动检测 ./build/bin/whisper-cli -l auto -f multi_lang.wav # 只检测语言，检测完就退出 ./build/bin/whisper-cli -dl -f audio.wav

控制处理范围

长音频只想先试听开头？用-d限制时长（单位毫秒）：

# 只处理前 30 秒 ./build/bin/whisper-cli -d 30000 -f long_audio.wav

用提示词"带节奏"

--prompt可以给模型一个初始提示，相当于告诉它"这段内容的大背景是什么"，对专业术语、人名地名的识别帮助明显：

./build/bin/whisper-cli --prompt "以下是技术会议记录，涉及数据库和微服务架构" -f meeting.wav

分配计算资源

线程数-t是最常用的性能开关，一般设为核心数的 1～2 倍：

./build/bin/whisper-cli -t 8 -f audio.wav

-p则控制并行处理器数量，适合多核机器进一步压榨性能。

参数配齐后，就该聊聊"成果交付"了——毕竟我们真正想要的是字幕文件、结构化数据，而不只是屏幕上一闪而过的文字。

第六章 一键导出：字幕、数据随你挑

whisper-cli 的输出格式相当齐全，一个开关对应一种文件，可以同时叠加使用：

# 生成 SRT 字幕（最通用） ./build/bin/whisper-cli -f audio.wav -osrt # 生成 VTT 字幕（网页播放器常用） ./build/bin/whisper-cli -f audio.wav -ovtt # 生成 JSON（含语言、时长、段落等结构化信息） ./build/bin/whisper-cli -f audio.wav -oj # 生成 CSV（方便导入表格工具做分析） ./build/bin/whisper-cli -f audio.wav -ocsv # 指定输出文件名（不带扩展名），可同时导出多种格式 ./build/bin/whisper-cli -f audio.wav -of result -osrt -oj

最后一条命令会生成result.srt和result.json两个文件，文件名由-of统一管理，非常省心。

JSON 输出的结构大致长这样（简化示例）：

{ "language": "en", "duration": 11.0, "segments": [ { "id": 0, "start": 0.0, "end": 1.0, "text": " And so my fellow Americans," } ] }

如果需要更完整的逐词信息，可以用-ojf（full JSON）；想要逐词时间戳，则用-ml 1配合-sow（按词切分），这对做逐字字幕特别有用。

输出不是终点，质量才是。接下来我们把目光投向"如何让转写结果更接近完美"。

第七章 质量调优：从"听得清"到"听得准"

用束搜索换精度

beam search（束搜索）会让模型在多个候选结果中挑选最优组合，精度更高但更慢：

# 提高识别精度（牺牲速度） ./build/bin/whisper-cli -f audio.wav -bs 10 -bo 20

-bs是束宽，-bo是保留的最佳候选数量，数值越大越费时，量力而行。

压低随机性

温度参数-tp控制模型输出的随机程度，数值越低越"死板"、越稳定：

# 降低随机性，适合字幕等固定内容 ./build/bin/whisper-cli -f audio.wav -tp 0.0

过滤杂音词与低置信度内容

口语里常见的"嗯、啊、那个"可以用正则过滤掉：

./build/bin/whisper-cli -f audio.wav --suppress-regex "(um|uh|like)"

而-wt可以设置单词置信度阈值，只保留足够"有把握"的词（默认 0.01）：

./build/bin/whisper-cli -f audio.wav -wt 0.05

控制输出长度与上下文

-ml限制每个段落的字符数上限，-mc限制上下文窗口大小，对长音频的内存控制很有帮助：

./build/bin/whisper-cli -f audio.wav -ml 100 # 每段最多 100 字符 ./build/bin/whisper-cli -f audio.wav -mc 1024 # 限制上下文大小

调优做完，很多用户会问：能不能再快点？这就轮到硬件加速登场了。

第八章 提速利器：从多线程到 GPU 全家桶

CPU 多线程

不换硬件的前提下，-t 8这类线程参数是见效最快的。配合-pp还可以实时查看转录进度：

./build/bin/whisper-cli -t 8 -pp -f audio.wav

NVIDIA GPU（CUDA）

编译时打开 CUDA 开关即可：

cmake -B build -DGGML_CUDA=1 cmake --build build --config Release

需要说明的是，whisper-cli 在编译支持 GPU 的情况下默认启用 GPU，只有想强制回退到 CPU 时才需要加-ng（即--no-gpu）。另外-fa可以开启 Flash Attention 加速，适合支持的硬件进一步提速：

./build/bin/whisper-cli -fa -f samples/jfk.wav

Apple Silicon（Metal）

macOS 上启用 Metal 后，推理会完整跑在 GPU 上，体验极佳：

cmake -B build -DGGML_METAL=1 cmake --build build --config Release

Intel 设备（OpenVINO）

OpenVINO 适合 Intel CPU/GPU 环境。先转换模型，再编译、运行：

# 转换模型 python models/convert-whisper-to-openvino.py --model base.en # 编译支持 OpenVINO cmake -B build -DWHISPER_OPENVINO=1 cmake --build build --config Release # 指定 OpenVINO 编码设备运行 ./build/bin/whisper-cli -f samples/jfk.wav -oved GPU

到这里，静态音频的转录能力已经拉满。但 whisper.cpp 的看家本领还不止这些——它还能"边听边写"。

第九章 进阶玩法：实时转录、说话人分离、歌词与语法约束

玩法一：麦克风实时转录（stream）

用 stream 工具可以实现边说话边出字的效果：

# 编译 stream cmake --build build --target stream # 实时转录：500ms 处理步长、5 秒上下文窗口 ./build/bin/stream -m models/ggml-base.en.bin -t 4 --step 500 --length 5000

两个核心参数值得琢磨：--step是每次处理的音频片段长度，越小延迟越低但开销越大；--length是上下文窗口长度，越大对语境的把握越好但响应越慢。想进一步过滤静音，还可以调-vth（VAD 阈值）。

玩法二：说话人分离（tinydiarize）

会议录音里"谁说了什么"也能区分出来。先下载专用模型：

./models/download-ggml-model.sh small.en-tdrz

再在转录时加上-tdrz开关：

./build/bin/whisper-cli -m models/ggml-small.en-tdrz.bin -tdrz -f meeting.wav

输出中会自动标注说话人：

[00:00:00.000 --> 00:00:03.800] [SPEAKER_00] Okay Houston, we've had a problem here. [00:00:03.800 --> 00:00:06.200] [SPEAKER_01] This is Houston. Say again please.

玩法三：Karaoke 歌词视频

-owts会生成一个可执行的 ffmpeg 脚本，用于制作逐词高亮的卡拉 OK 视频：

./build/bin/whisper-cli -f song.wav -owts source ./song.wav.wts # 执行生成的脚本

玩法四：语法约束识别（GBNF）

通过 GBNF 语法文件可以"规定"识别结果只能落在某些词上，非常适合命令控制类场景。项目自带了grammars/colors.gbnf：

./build/bin/whisper-cli -f color_command.wav --grammar grammars/colors.gbnf

也可以指定语法里的顶层规则：

./build/bin/whisper-cli -f voice_command.wav --grammar my_commands.gbnf --grammar-rule command

一份 GBNF 语法文件长这样，规则清晰得像画流程图：

root ::= (red | green | blue | yellow | black | white) (space (red | green | blue | yellow | black | white))* space ::= " "

基于这套语法约束，再配合 command 工具，你甚至可以快速搭一个本地的离线语音助手原型：

cmake --build build --target command ./build/bin/command -m models/ggml-base.en.bin --grammar grammars/assistant.gbnf

学了这么多招数，是时候组合起来打两场"实战"了。

第十章 实战演练：两个拿来即用的完整流程

案例一：会议录音自动转纪要

把一段会议录音变成带说话人标注的纪要，全程三步：

# 1. 格式转换（MP3 → 16kHz WAV） ffmpeg -i meeting.mp3 -ar 16000 -ac 1 -c:a pcm_s16le meeting.wav # 2. 带说话人分离的高精度转录，同时导出 JSON 和 SRT ./build/bin/whisper-cli -m models/ggml-small.en-tdrz.bin -tdrz -f meeting.wav -oj -osrt # 3. 用 jq 提取纯文本，交给摘要工具生成纪要 jq -r '.segments[].text' meeting.json | summarize-tool > summary.txt

整个流程从录音到纪要全自动，中间不需要人工干预。

案例二：为视频批量生成多语言字幕

给一部视频配上字幕，同样三步走：

# 1. 从视频抽取音轨 ffmpeg -i video.mp4 -vn -ar 16000 -ac 1 -c:a pcm_s16le audio.wav # 2. 用大模型自动检测语言并生成 SRT ./build/bin/whisper-cli -m models/ggml-large-v3.bin -l auto -f audio.wav -osrt -of subtitles # 3. 把字幕烧进视频 ffmpeg -i video.mp4 -vf "subtitles=subtitles.srt" output_with_subs.mp4

到这里，你的 whisper.cpp 技能树已经点得七七八八了。不过实操中难免踩坑，最后奉上一份避坑速查表。

第十一章 避坑指南：常见报错与解决思路

另外，想量化评估自己机器的性能，可以编译并运行 bench 基准测试工具：

cmake --build build --target bench ./build/bin/bench -m models/ggml-base.en.bin

它会给出清晰的耗时数据，帮你判断硬件瓶颈在哪。

写在最后：你的语音转文字工具箱已经就位

回顾全程，我们从零开始认识了 whisper.cpp 这个离线语音识别引擎，完成了安装、选型、量化、转码、调参、输出、加速、进阶玩法直到实战落地的一整套闭环。现在你手里的工具，足以应对会议纪要、字幕生成、实时转录、语音助手原型等绝大多数日常场景。

想更进一步？还有三条路值得探索：

1. 自定义模型：用models/convert-h5-to-ggml.py把微调好的模型转换成 ggml 格式再投入生产；
2. 多语言集成：项目提供了 Go、Java、Ruby、Python 等多种语言绑定，可以把它嵌入自己的应用；
3. Web 部署：whisper.wasm 能让浏览器直接跑语音识别，无需任何后端。

工具已经备好，剩下的就交给你的想象力了。动手试试吧，第一条转录成功的提示符，正在等你点亮。

【免费下载链接】whisper.cppPort of OpenAI's Whisper model in C/C++项目地址: https://gitcode.com/GitHub_Trending/wh/whisper.cpp