用 whisper.cpp 把录音变成文字我的踩坑笔记与实战命令【免费下载链接】whisper.cppPort of OpenAIs Whisper model in C/C项目地址: https://gitcode.com/GitHub_Trending/wh/whisper.cpp你有没有过这样的时刻一场两个小时的会议录音躺在手机里再也没有人打开过一部没字幕的课程视频你对着进度条反复拖动就为抄一句关键台词。我一度靠外包转写服务一条音频几十块还要等半天隐私还全交出去了。后来我找到 whisper.cpp——OpenAI Whisper 模型的 C/C 移植版本地跑、免费、秒出结果还能输出字幕文件直接扔进播放器。这篇文章就记录我从零部署到玩转它的全过程包括我踩过的坑和最终沉淀下来的命令照着敲就能用。先弄明白为什么我不再想用在线 API在线语音识别其实挺好用但有几个问题绕不开隐私会议录音、客户资料要传到别人服务器我心里一直犯嘀咕。费用时长一长账单就肉疼量大了更是无底洞。依赖网络断网等于停工。whisper.cpp 把这一切搬到了本地。它是 OpenAI Whisper 的 C/C 移植版不需要 Python 环境不需要 GPU 也能跑有 GPU 更快甚至能编译进浏览器。最关键的是它免费而且音频不出你的机器。在动手之前我先看看自己机器够不够格。whisper.cpp 的模型大小从 75MB 到 2.9GB 不等对应内存占用差别很大模型磁盘占用运行内存适合场景tiny75 MiB~273 MB嵌入式设备、追求速度base142 MiB~388 MB通用入门速度和精度平衡small466 MiB~852 MB中等精度需求medium1.5 GiB~2.1 GB高精度转录large2.9 GiB~3.9 GB精度优先不差资源我的笔记本是 16GB 内存跑 medium 绰绰有余如果你只有 8GB建议从 base 开始。部署这一步我卡了整整一下午第一次编译就踩坑了。我照着网上的教程用make直接编译结果因为缺少依赖报了错。其实官方推荐的 CMake 方式简单得多# 获取源码 git clone https://gitcode.com/GitHub_Trending/wh/whisper.cpp cd whisper.cpp # 配置并编译 cmake -B build cmake --build build --config Release编译完成后可执行文件在build/bin/whisper-cli。验证一下./build/bin/whisper-cli -h能看到一大串参数说明就说明环境没问题了。Windows 用户用 MSVC 的话把第二句换成cmake -B build -G Visual Studio 17 2022其余步骤一样。选模型像请翻译不是越大越好我最初无脑下载了 largest 的模型结果第一版大模型转起来慢得让人怀疑人生。后来我把模型比作不同吨位的翻译员——tiny 是反应快但词汇量小的速记员large 是知识渊博但需要慢慢思考的老教授。选谁取决于你的音频和耐心。下载模型用官方脚本一行命令# 英文入门首选我用它跑通了第一个例子 ./models/download-ggml-model.sh base.en # 需要识别中文等多语言就下这个 ./models/download-ggml-model.sh medium # 想要说话人分离功能下带 tdrz 后缀的 ./models/download-ggml-model.sh small.en-tdrz模型文件会落到models/目录命名是ggml-模型名.bin。我的经验是先用 base 跑通流程确认效果后再根据识别质量决定要不要升级。别一上来就上 large转一次几分钟试错成本太高。顺便说一句官方还提供了make -j tiny.en这类快捷目标懒得敲脚本路径时可以直接用。内存不够试试给模型压缩行李有次我在一台 4GB 的旧笔记本上跑 medium直接内存爆掉。解决方案是量化——把模型权重的精度从 16 位降到 4/5/8 位相当于把行李压缩后再带上飞机体积小、跑得快代价是精度稍微损失一点点。whisper.cpp 自带了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不同量化档位怎么选我给你一张对照表量化方法体积缩减精度损失推荐场景q4_0 / q4_1约 50%轻微内存极度紧张的环境q5_0 / q5_1约 40%极小平衡体积与精度我的默认选择q8_0约 25%可忽略对精度敏感又想省点内存量化文件还能直接从下载脚本拿比如small-q8_0这种带后缀的模型名下载脚本本身就支持。第一次转录我踩了 WAV 格式的坑跑通流程后我兴奋地把一段 mp3 扔进去结果 whiper-cli 直接拒绝工作。查文档才知道whisper-cli 只认 16-bit PCM 的 WAV 文件。这是我踩的最大的坑也是新手最常见的问题。解决办法是用 ffmpeg 先转格式顺便统一采样率和声道# MP3 转成 16kHz 单声道 WAV这是 whisper 的标准输入规格 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 -ac 116kHz 采样率、单声道是 Whisper 训练时的标准输入转对了识别率才有保障。格式对了转录就一句话的事# 用默认模型base.en转录 jfk.wav ./build/bin/whisper-cli -f samples/jfk.wav # 指定模型 指定中文语言 ./build/bin/whisper-cli -m models/ggml-medium.bin -l zh -f meeting.wav # 语言不确定让模型自己检测 ./build/bin/whisper-cli -m models/ggml-medium.bin -l auto -f multi_lang.wav这里有个小细节-l auto支持自动检测语言多语言混录的音频尤其好用。想看处理进度就加--print-progress。把转录结果变成字幕、JSON、CSV一条命令搞定转录完只是一半另一半是把结果喂给下游工具。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。JSON 的结构长这样截取关键部分{ model: { type: base.en, multilingual: false }, result: { language: en }, transcription: [ { timestamps: { from: 00:00:00,000, to: 00:00:01,000 }, text: And so my fellow Americans, } ] }用-ojf还能输出 token 级别的完整 JSON包含每个词的置信度做数据分析或者二次处理非常方便。实时转录把麦克风变成打字机普通转录是事后处理但 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每次处理的音频片段长度毫秒。越小延迟越低但 CPU 压力越大500 是个不错的起点。--length上下文窗口毫秒。越大越能理解前文但出字越慢。如果你的目标是尽量接近实时用 base 或 tiny 模型想要高质量medium 也能跑就是延迟高一些。这里没有银弹只能根据你的 CPU 慢慢调。说话人分离谁在说话一目了然有一次转录电话会议满屏文字分不清是谁说的。whisper.cpp 的 tinydiarize 功能正好解决这个需求但前提是模型本身支持——就是前面提到的-tdrz后缀模型# 下载支持说话人分离的模型 ./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] Okay Houston, weve had a problem here. [SPEAKER_TURN] [00:00:03.800 -- 00:00:06.200] This is Houston. Say again please.要注意的是tdrz 模型目前主要是英文中文场景想要分离说话人可以用双声道录音加-di参数基于左右声道能量判断或者等社区的中文 tdrz 模型。让识别结果听话GBNF 语法约束这是我最近才发现的宝藏功能。whisper-cli 支持用 GBNF 语法文件约束识别结果让它只输出你想要的格式。比如做一个语音点色板工具# 用 colors.gbnf 语法约束只会识别颜色词 ./build/bin/whisper-cli -f color_command.wav --grammar grammars/colors.gbnf项目自带grammars/目录里面有colors.gbnf、assistant.gbnf等现成示例。自定义语法也很简单比如只允许开灯/关灯两个命令root :: (开灯 | 关灯)搭配--grammar-rule指定顶层规则就能把识别结果锁死在结构化内容里。做语音助手、语音命令控制这个功能比任何后处理正则都可靠。GPU 加速什么时候值得开我特意把这个放在最后说因为很多人第一步就问怎么开 GPU。但真相是whisper.cpp 默认就启用 GPU如果编译时带上了对应后端CPU 也能跑只是慢一点。NVIDIA 显卡编译时加-DGGML_CUDA1Apple Silicon编译时加-DGGML_METAL1Intel 设备可以试试 OpenVINO-DWHISPER_OPENVINO1一个常见误解是-ng是启用 GPU其实恰恰相反-ng是禁用 GPU 的意思no-gpu。我当初就理解反了白折腾半天。GPU 转写长音频能快好几倍但前提是你的显卡显存装得下模型——large 模型 3.9GB 内存占用显存不够反而会崩。另外两个加速选项也值得一试# Flash Attention新一代注意力实现长音频提速明显 ./build/bin/whisper-cli -fa -f audio.wav # 线程数按 CPU 核心数 1~2 倍调 ./build/bin/whisper-cli -t 8 -f audio.wav转录质量不满意这几个参数先试试跑完发现识别率不理想别急着换大模型先调这几个# 提高 beam search 宽度更稳但更慢 ./build/bin/whisper-cli -f audio.wav -bs 5 # 降低温度让输出更确定适合固定内容 ./build/bin/whisper-cli -f audio.wav -tp 0.0 # 给模型一点上下文提示专业术语识别率暴涨 ./build/bin/whisper-cli --prompt 以下是关于GPU加速的技术分享 -f tech_talk.wav # 只保留高置信度的词 ./build/bin/whisper-cli -f audio.wav -wt 0.05--prompt是我最推荐的一个转写带专业术语的音频时提前告诉模型这是在聊什么效果立竿见影。-ml还能控制每段长度字幕想逐句显示就设小一点比如-ml 20。我的最终工作流一条龙搞定会议记录沉淀了这么多我现在的日常操作长这样# 1. 录音转 WAV ffmpeg -i meeting.mp3 -ar 16000 -ac 1 -c:a pcm_s16le meeting.wav # 2. 高精度转录同时出字幕和 JSON ./build/bin/whisper-cli -m models/ggml-medium.bin -l zh \ -f meeting.wav -osrt -oj -of meeting # 3. 转录文本直接进笔记软件整个流程从录音吃灰变成会议结束 10 分钟内拿到文字版而且全程本地处理敏感内容不出门。遇到内存不足就换-q5_0量化模型遇到 GPU 报错就确认编译选项遇到格式报错就检查是不是 16kHz 单声道 WAV——这三板斧能解决我 90% 的问题。whisper.cpp 的潜力还不止这些-owts能生成卡拉 OK 式逐词高亮视频脚本-di能做立体声说话人分离还有bench工具可以测自己机器的性能上限。别光看了把仓库拉下来、下个 base 模型、扔一段录音进去你会发现音频转文字自由其实离你只有三行命令的距离。跑通了记得回来聊聊你踩过的坑。【免费下载链接】whisper.cppPort of OpenAIs Whisper model in C/C项目地址: https://gitcode.com/GitHub_Trending/wh/whisper.cpp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 用 whisper.cpp 把录音变成文字，我的踩坑笔记与实战命令
用 whisper.cpp 把录音变成文字我的踩坑笔记与实战命令【免费下载链接】whisper.cppPort of OpenAIs Whisper model in C/C项目地址: https://gitcode.com/GitHub_Trending/wh/whisper.cpp你有没有过这样的时刻一场两个小时的会议录音躺在手机里再也没有人打开过一部没字幕的课程视频你对着进度条反复拖动就为抄一句关键台词。我一度靠外包转写服务一条音频几十块还要等半天隐私还全交出去了。后来我找到 whisper.cpp——OpenAI Whisper 模型的 C/C 移植版本地跑、免费、秒出结果还能输出字幕文件直接扔进播放器。这篇文章就记录我从零部署到玩转它的全过程包括我踩过的坑和最终沉淀下来的命令照着敲就能用。先弄明白为什么我不再想用在线 API在线语音识别其实挺好用但有几个问题绕不开隐私会议录音、客户资料要传到别人服务器我心里一直犯嘀咕。费用时长一长账单就肉疼量大了更是无底洞。依赖网络断网等于停工。whisper.cpp 把这一切搬到了本地。它是 OpenAI Whisper 的 C/C 移植版不需要 Python 环境不需要 GPU 也能跑有 GPU 更快甚至能编译进浏览器。最关键的是它免费而且音频不出你的机器。在动手之前我先看看自己机器够不够格。whisper.cpp 的模型大小从 75MB 到 2.9GB 不等对应内存占用差别很大模型磁盘占用运行内存适合场景tiny75 MiB~273 MB嵌入式设备、追求速度base142 MiB~388 MB通用入门速度和精度平衡small466 MiB~852 MB中等精度需求medium1.5 GiB~2.1 GB高精度转录large2.9 GiB~3.9 GB精度优先不差资源我的笔记本是 16GB 内存跑 medium 绰绰有余如果你只有 8GB建议从 base 开始。部署这一步我卡了整整一下午第一次编译就踩坑了。我照着网上的教程用make直接编译结果因为缺少依赖报了错。其实官方推荐的 CMake 方式简单得多# 获取源码 git clone https://gitcode.com/GitHub_Trending/wh/whisper.cpp cd whisper.cpp # 配置并编译 cmake -B build cmake --build build --config Release编译完成后可执行文件在build/bin/whisper-cli。验证一下./build/bin/whisper-cli -h能看到一大串参数说明就说明环境没问题了。Windows 用户用 MSVC 的话把第二句换成cmake -B build -G Visual Studio 17 2022其余步骤一样。选模型像请翻译不是越大越好我最初无脑下载了 largest 的模型结果第一版大模型转起来慢得让人怀疑人生。后来我把模型比作不同吨位的翻译员——tiny 是反应快但词汇量小的速记员large 是知识渊博但需要慢慢思考的老教授。选谁取决于你的音频和耐心。下载模型用官方脚本一行命令# 英文入门首选我用它跑通了第一个例子 ./models/download-ggml-model.sh base.en # 需要识别中文等多语言就下这个 ./models/download-ggml-model.sh medium # 想要说话人分离功能下带 tdrz 后缀的 ./models/download-ggml-model.sh small.en-tdrz模型文件会落到models/目录命名是ggml-模型名.bin。我的经验是先用 base 跑通流程确认效果后再根据识别质量决定要不要升级。别一上来就上 large转一次几分钟试错成本太高。顺便说一句官方还提供了make -j tiny.en这类快捷目标懒得敲脚本路径时可以直接用。内存不够试试给模型压缩行李有次我在一台 4GB 的旧笔记本上跑 medium直接内存爆掉。解决方案是量化——把模型权重的精度从 16 位降到 4/5/8 位相当于把行李压缩后再带上飞机体积小、跑得快代价是精度稍微损失一点点。whisper.cpp 自带了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不同量化档位怎么选我给你一张对照表量化方法体积缩减精度损失推荐场景q4_0 / q4_1约 50%轻微内存极度紧张的环境q5_0 / q5_1约 40%极小平衡体积与精度我的默认选择q8_0约 25%可忽略对精度敏感又想省点内存量化文件还能直接从下载脚本拿比如small-q8_0这种带后缀的模型名下载脚本本身就支持。第一次转录我踩了 WAV 格式的坑跑通流程后我兴奋地把一段 mp3 扔进去结果 whiper-cli 直接拒绝工作。查文档才知道whisper-cli 只认 16-bit PCM 的 WAV 文件。这是我踩的最大的坑也是新手最常见的问题。解决办法是用 ffmpeg 先转格式顺便统一采样率和声道# MP3 转成 16kHz 单声道 WAV这是 whisper 的标准输入规格 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 -ac 116kHz 采样率、单声道是 Whisper 训练时的标准输入转对了识别率才有保障。格式对了转录就一句话的事# 用默认模型base.en转录 jfk.wav ./build/bin/whisper-cli -f samples/jfk.wav # 指定模型 指定中文语言 ./build/bin/whisper-cli -m models/ggml-medium.bin -l zh -f meeting.wav # 语言不确定让模型自己检测 ./build/bin/whisper-cli -m models/ggml-medium.bin -l auto -f multi_lang.wav这里有个小细节-l auto支持自动检测语言多语言混录的音频尤其好用。想看处理进度就加--print-progress。把转录结果变成字幕、JSON、CSV一条命令搞定转录完只是一半另一半是把结果喂给下游工具。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。JSON 的结构长这样截取关键部分{ model: { type: base.en, multilingual: false }, result: { language: en }, transcription: [ { timestamps: { from: 00:00:00,000, to: 00:00:01,000 }, text: And so my fellow Americans, } ] }用-ojf还能输出 token 级别的完整 JSON包含每个词的置信度做数据分析或者二次处理非常方便。实时转录把麦克风变成打字机普通转录是事后处理但 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每次处理的音频片段长度毫秒。越小延迟越低但 CPU 压力越大500 是个不错的起点。--length上下文窗口毫秒。越大越能理解前文但出字越慢。如果你的目标是尽量接近实时用 base 或 tiny 模型想要高质量medium 也能跑就是延迟高一些。这里没有银弹只能根据你的 CPU 慢慢调。说话人分离谁在说话一目了然有一次转录电话会议满屏文字分不清是谁说的。whisper.cpp 的 tinydiarize 功能正好解决这个需求但前提是模型本身支持——就是前面提到的-tdrz后缀模型# 下载支持说话人分离的模型 ./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] Okay Houston, weve had a problem here. [SPEAKER_TURN] [00:00:03.800 -- 00:00:06.200] This is Houston. Say again please.要注意的是tdrz 模型目前主要是英文中文场景想要分离说话人可以用双声道录音加-di参数基于左右声道能量判断或者等社区的中文 tdrz 模型。让识别结果听话GBNF 语法约束这是我最近才发现的宝藏功能。whisper-cli 支持用 GBNF 语法文件约束识别结果让它只输出你想要的格式。比如做一个语音点色板工具# 用 colors.gbnf 语法约束只会识别颜色词 ./build/bin/whisper-cli -f color_command.wav --grammar grammars/colors.gbnf项目自带grammars/目录里面有colors.gbnf、assistant.gbnf等现成示例。自定义语法也很简单比如只允许开灯/关灯两个命令root :: (开灯 | 关灯)搭配--grammar-rule指定顶层规则就能把识别结果锁死在结构化内容里。做语音助手、语音命令控制这个功能比任何后处理正则都可靠。GPU 加速什么时候值得开我特意把这个放在最后说因为很多人第一步就问怎么开 GPU。但真相是whisper.cpp 默认就启用 GPU如果编译时带上了对应后端CPU 也能跑只是慢一点。NVIDIA 显卡编译时加-DGGML_CUDA1Apple Silicon编译时加-DGGML_METAL1Intel 设备可以试试 OpenVINO-DWHISPER_OPENVINO1一个常见误解是-ng是启用 GPU其实恰恰相反-ng是禁用 GPU 的意思no-gpu。我当初就理解反了白折腾半天。GPU 转写长音频能快好几倍但前提是你的显卡显存装得下模型——large 模型 3.9GB 内存占用显存不够反而会崩。另外两个加速选项也值得一试# Flash Attention新一代注意力实现长音频提速明显 ./build/bin/whisper-cli -fa -f audio.wav # 线程数按 CPU 核心数 1~2 倍调 ./build/bin/whisper-cli -t 8 -f audio.wav转录质量不满意这几个参数先试试跑完发现识别率不理想别急着换大模型先调这几个# 提高 beam search 宽度更稳但更慢 ./build/bin/whisper-cli -f audio.wav -bs 5 # 降低温度让输出更确定适合固定内容 ./build/bin/whisper-cli -f audio.wav -tp 0.0 # 给模型一点上下文提示专业术语识别率暴涨 ./build/bin/whisper-cli --prompt 以下是关于GPU加速的技术分享 -f tech_talk.wav # 只保留高置信度的词 ./build/bin/whisper-cli -f audio.wav -wt 0.05--prompt是我最推荐的一个转写带专业术语的音频时提前告诉模型这是在聊什么效果立竿见影。-ml还能控制每段长度字幕想逐句显示就设小一点比如-ml 20。我的最终工作流一条龙搞定会议记录沉淀了这么多我现在的日常操作长这样# 1. 录音转 WAV ffmpeg -i meeting.mp3 -ar 16000 -ac 1 -c:a pcm_s16le meeting.wav # 2. 高精度转录同时出字幕和 JSON ./build/bin/whisper-cli -m models/ggml-medium.bin -l zh \ -f meeting.wav -osrt -oj -of meeting # 3. 转录文本直接进笔记软件整个流程从录音吃灰变成会议结束 10 分钟内拿到文字版而且全程本地处理敏感内容不出门。遇到内存不足就换-q5_0量化模型遇到 GPU 报错就确认编译选项遇到格式报错就检查是不是 16kHz 单声道 WAV——这三板斧能解决我 90% 的问题。whisper.cpp 的潜力还不止这些-owts能生成卡拉 OK 式逐词高亮视频脚本-di能做立体声说话人分离还有bench工具可以测自己机器的性能上限。别光看了把仓库拉下来、下个 base 模型、扔一段录音进去你会发现音频转文字自由其实离你只有三行命令的距离。跑通了记得回来聊聊你踩过的坑。【免费下载链接】whisper.cppPort of OpenAIs Whisper model in C/C项目地址: https://gitcode.com/GitHub_Trending/wh/whisper.cpp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考