ggml-org / whisper.cpp

#14

50,3435,606+33 todayC++

View on GitHub

Port of OpenAI's Whisper model in C/C++

💡 Use Cases

最适合需要在各种设备上离线、高效运行语音识别的场景，特别是移动端和边缘计算环境。

离线语音转文字

Problem: 开发者需要在没有网络连接或需要保护隐私的设备上，将音频文件转换为文字。

Solution: 使用whisper.cpp在本地设备上运行Whisper模型，无需依赖云端API，实现完全离线的语音识别。

Example: 在树莓派或旧笔记本电脑上，将会议录音、采访音频或播客节目转换为文字稿，无需上传到互联网。

移动端语音助手

Problem: 开发者想在iOS或Android应用中集成语音识别功能，但希望避免网络延迟和隐私问题。

Solution: 将whisper.cpp集成到移动应用中，利用其优化的ARM NEON和Metal支持，在设备上高效运行语音识别。

Example: 开发一个离线语音笔记应用，用户说话后立即在手机上生成文字记录，或者创建一个语音控制的智能家居控制应用。

边缘设备语音处理

Problem: 开发者需要在资源受限的边缘设备（如嵌入式系统、工控机）上处理实时音频流。

Solution: 利用whisper.cpp的零运行时内存分配、整数量化和小模型支持，在低功耗设备上实现实时语音识别。

Example: 在工厂的质检设备中实时识别操作员语音指令，或在智能摄像头中识别环境声音事件（如玻璃破碎、警报声）。

跨平台语音应用

Problem: 开发者需要为Windows、Linux、macOS等多个平台开发统一的语音识别功能，避免为每个平台重写代码。

Solution: 使用whisper.cpp的纯C/C++实现和C-style API，轻松集成到各种平台的应用程序中，支持x86、ARM等多种架构。

Example: 开发一个跨平台的视频编辑软件，自动为视频生成字幕；或为一个桌面应用添加语音命令控制功能。

📊 Project Info

Language: C++
Stars: ⭐ 50,343
Forks: 5,606
Today: +33
Ranking: #14
Collection: Language
Trending Date: June 1, 2026
Last Push: 6/1/2026

🏷️ Topics

C/C++实现语音识别高性能轻量级嵌入式开发移动端开发

📸 Screenshots

5分钟快速开始：whisper.cpp

OpenAI Whisper模型的C/C++移植版本，用于高性能语音识别推理。

🖥️ OS

macOSWindowsLinux

⚙️ Runtime

Git最新

CMake3.10+

make最新

🔧 Tools

ffmpeg— 音频文件转换（可选，用于非WAV文件）

📝 Steps

克隆仓库

下载whisper.cpp源代码到本地。

克隆仓库

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

✓Expected: 创建whisper.cpp目录并下载文件。

💡确保网络连接正常。

进入目录

切换到项目目录。

进入项目根目录

$ cd whisper.cpp

✓Expected: 当前目录变为whisper.cpp。

💡在终端中执行。

下载模型

下载一个预转换的ggml格式Whisper模型。

下载base.en模型

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

✓Expected: 下载models/ggml-base.en.bin文件。

💡模型大小约142MB，确保有足够磁盘空间。

构建项目

编译whisper-cli示例程序。

使用默认配置构建

$ make

✓Expected: 成功编译，生成build/bin/whisper-cli可执行文件。

💡如果失败，检查CMake和make是否安装。

运行推理

使用示例音频文件测试语音识别。

转录JFK音频样本

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

✓Expected: 输出转录文本，如'And so my fellow Americans ask not what your country can do for you ask what you can do for your country.'

💡确保音频文件为16位WAV格式；如需其他文件，用ffmpeg转换。

✅ 验证成功

成功运行whisper-cli并看到转录输出。

✓命令执行无错误
✓输出包含英文文本
✓程序正常退出

⚡ Quick Tips

快捷方式快速演示：运行'make base.en'自动下载模型并测试所有样本。

文档查看帮助：运行'./build/bin/whisper-cli -h'获取详细用法。

性能支持GPU：如需CUDA或Metal加速，参考README构建选项。

🔍 Troubleshooting

❓ 构建失败，提示CMake错误。

→ 确保已安装CMake 3.10+和make工具。

❓ 运行whisper-cli时音频文件无法识别。

→ 使用ffmpeg转换音频为16位WAV：'ffmpeg -i input.mp3 -ar 16000 -ac 1 -c:a pcm_s16le output.wav'。

❓ 模型下载慢或失败。

→ 检查网络，或手动从GitHub releases下载模型文件到models/目录。

🎯 Next Steps

尝试其他模型

下载tiny、small等模型测试不同精度和速度。

集成到应用

使用C-style API将whisper.cpp嵌入到自定义项目中。

探索高级功能

参考README了解量化、Core ML、OpenVINO等优化选项。

Difficulty

初级

Est. Time

2-3小时

Target Audience

对语音识别感兴趣、有基本C/C++编程经验或希望了解如何在本地运行AI模型的开发者。适合想快速体验离线语音转文本功能的初学者。

🎯 What You'll Learn

学会在本地计算机上编译和运行Whisper.cpp，将音频文件转换为文字，并了解如何根据硬件选择不同的加速方案。

📋 Prerequisites

C/C++基础了解

项目核心是C/C++实现，需要能理解基本的编译命令（如make, cmake）和命令行操作。

Git基础了解

需要从GitHub克隆项目仓库。

命令行/终端使用熟悉

所有步骤（克隆、编译、运行）均在命令行中完成。

Python基础（可选）了解(optional)

仅在需要使用Core ML或OpenVINO等高级功能生成模型时才会用到。对于快速入门不是必须的。

📚 Resources

必看

GitHub README

项目最核心的文档，包含了所有安装、编译、使用和高级功能的说明。

🗺️ Learning Phases

环境准备与项目获取

⏱ 15-30分钟

安装必要的编译工具

根据你的操作系统（如macOS, Linux, Windows），确保已安装Git和C/C++编译器（如gcc/clang，或Windows上的MSVC/MinGW）。对于macOS，通常已自带。对于Linux，可能需要运行 `sudo apt install build-essential` 或类似命令。

💡Windows用户建议使用MSYS2或WSL2来获得类似Linux的体验，或者直接使用Visual Studio的开发者命令提示符。

克隆项目仓库

打开终端，运行 `git clone https://github.com/ggml-org/whisper.cpp` 将项目下载到本地。

进入项目目录

运行 `cd whisper.cpp` 进入项目根目录。

快速入门与初体验

⏱ 30-45分钟

下载预转换的模型

运行 `./models/download-ggml-model.sh base.en` 下载一个较小的英文专用模型。这是最快上手的模型。

💡模型会下载到 `models/` 目录下。如果脚本执行失败，可以手动从项目Releases页面或Hugging Face寻找ggml格式的模型文件。

编译基础命令行程序

运行 `make` 命令编译项目。这会在 `build/bin/` 目录下生成可执行文件，主要是 `whisper-cli`。

💡如果编译出错，请检查前置的编译工具是否安装正确。这是最常见的问题。

运行快速演示

运行 `make base.en`。这个命令会自动下载 `base.en` 模型并对项目自带的 `samples/` 目录下的.wav样例文件进行转录。

💡这是验证一切是否正常工作的最快方法。观察终端输出，应该能看到识别出的英文文本。

核心功能实践

⏱ 45-60分钟

转录自己的音频文件

1. 确保你的音频文件是16-bit单声道WAV格式。如果不是，使用ffmpeg转换：`ffmpeg -i input.mp3 -ar 16000 -ac 1 -c:a pcm_s16le output.wav`。 2. 运行转录命令：`./build/bin/whisper-cli -m models/ggml-base.en.bin -f path/to/your/output.wav`。

💡`-m` 指定模型路径，`-f` 指定音频文件路径。可以尝试 `-h` 查看所有参数，例如 `-l zh` 指定中文语言（如果使用多语言模型）。

尝试不同模型

下载其他模型进行对比，例如更小的 `tiny` 或更强大的 `small`。运行 `./models/download-ggml-model.sh tiny`，然后用 `-m models/ggml-tiny.bin` 参数运行转录。观察速度、内存占用和准确率的差异。

💡参考README中的‘Memory usage’表格，根据你的硬件选择合适模型。内存小的电脑不要轻易尝试‘large’模型。

探索更多样例

运行 `./samples/download-samples.sh` 下载更多音频样例进行测试。

高级功能探索（可选）

⏱ 30-60分钟

根据硬件启用加速

根据你的硬件，在编译时启用相应支持以获得更快速度。例如： - Apple Silicon (Mac)：`make clean && WHISPER_METAL=1 make` 启用Metal GPU加速。 - NVIDIA GPU：`make clean && WHISPER_CUDA=1 make`。 - 其他：参考README中的OpenBLAS、Vulkan、Core ML等部分。

💡每次切换编译选项前，最好先运行 `make clean`。加速功能可能需要额外安装库（如CUDA Toolkit）。

了解量化模型

运行 `./models/quantize.sh` 脚本，将下载的模型进行量化，生成更小、可能更快的 `.q4_0.bin` 等文件。然后用量化后的模型进行转录。

💡量化模型会损失少量精度，但能显著减少内存和磁盘占用，在资源受限的设备（如树莓派）上很有用。

⚠️ Common Mistakes

❌ 音频格式不正确

✅ Whisper.cpp 的 `whisper-cli` 目前只支持16-bit PCM WAV格式。务必使用ffmpeg等工具将MP3等格式正确转换（采样率16000Hz，单声道）。

❌ 编译失败，提示找不到命令或头文件

✅ 确认已安装完整的编译工具链（如build-essential）。在macOS上，可能需要安装Xcode Command Line Tools (`xcode-select --install`)。

❌ 运行程序时提示找不到模型文件

✅ 检查 `-m` 参数后的模型路径是否正确。模型文件应放在 `models/` 目录下，并使用正确的文件名。确保已成功运行下载脚本。

❌ 内存不足，程序崩溃

✅ 尤其是使用‘medium’或‘large’模型时。请先使用‘tiny’或‘base’模型。确保你的系统有足够可用内存（参考README内存表）。

❌ 启用GPU加速后编译或运行出错

✅ 确保已正确安装对应的驱动和开发库（如CUDA、Metal SDK）。仔细阅读README中对应加速板块的详细 prerequisites。初次尝试建议先使用CPU-only版本确保基础功能正常。

🚀 Next Steps

1. 阅读 `whisper.h` 和 `whisper.cpp` 源码，理解模型推理的核心流程。 2. 研究如何将 `whisper.cpp` 作为库集成到你自己的C/C++项目中。 3. 探索项目 `examples` 目录下的其他示例，如实时麦克风输入转录 (`stream`)。 4. 尝试为其他语言（非英语）音频进行转录，使用 `tiny` 或 `base` 等多语言模型。 5. 了解 `ggml` 库，这是本项目依赖的底层机器学习张量库。 6. 关注项目更新，尝试最新的功能和模型优化。