Skip to content
Get packs

Guide · Open source

How to use whisper.cpp: build, transcribe audio and tips

Updated · written with AI from the project's own documentation and checked against our catalogue data

whisper.cpp is a C/C++ implementation of OpenAI's Whisper automatic speech recognition model, which turns spoken audio into text. It has no external dependencies and can run offline on your own device, so audio does not need to be sent to a cloud service. This guide walks through cloning the repository, building the whisper-cli example, transcribing a WAV file and converting other audio formats first.

whisper.cppggml-org/whisper.cpp · ★ 54.9k · MIT

Quick start

  1. 1Clone the repository. Run git clone on the ggml-org/whisper.cpp repository and change into the whisper.cpp folder.
  2. 2Download a model. Run the download-ggml-model.sh script with base.en to fetch a ggml-format Whisper model.
  3. 3Configure the build. Run cmake -B build to set up the build folder.
  4. 4Build the project. Run cmake --build build -j --config Release to compile whisper-cli.
  5. 5Prepare your audio. Convert your file to 16-bit WAV with ffmpeg if it is in another format.
  6. 6Transcribe. Run ./build/bin/whisper-cli -f followed by your WAV file path.

What you need before you start

The project is installed by cloning the repository and building it yourself. The README lists these prerequisites: git, CMake, a C/C++ compiler, and ffmpeg. ffmpeg is optional and is only needed if you want to convert audio to WAV.

  • git, to clone the repository
  • CMake, to configure the build
  • A C/C++ compiler
  • ffmpeg (optional), for converting audio to 16-bit WAV

Clone the repository and download a model

First, clone the repository and move into its folder. Then download one of the Whisper models that the project has converted to its ggml format. The README uses base.en as the example. The models are listed in the models/README.md file in the repository.

git clone https://github.com/ggml-org/whisper.cpp.git cd whisper.cpp sh ./models/download-ggml-model.sh base.en

Build whisper-cli with CMake

Configure the build with CMake, then build the project. The README uses a Release configuration. When the build finishes, the whisper-cli example is available in the build/bin folder.

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

Transcribe an audio file

Run whisper-cli with the -f flag and a path to your audio file. The README uses the sample file samples/jfk.wav. For detailed usage instructions, the README says to run the help command.

  • Run ./build/bin/whisper-cli -h to see all options
  • The CLI example currently accepts only 16-bit WAV files
./build/bin/whisper-cli -f samples/jfk.wav

Convert other audio formats to WAV

If your audio is not 16-bit WAV, convert it before running the tool. The README gives an ffmpeg command that sets a 16 kHz sample rate, a single channel and 16-bit PCM encoding. Replace input.mp3 and output.wav with your own file names.

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

Choose a model and speed up inference

The README lists models from tiny to large, with disk and memory figures for each. Quantization is an option: the README says quantized models need less memory and disk space, and can be processed more efficiently depending on hardware. On Apple Silicon, the README describes Core ML support that can run the encoder on the Apple Neural Engine. It notes the first run on a device can be slow and later runs are faster.

  • tiny: 75 MiB disk, about 273 MB memory
  • base: 142 MiB disk, about 388 MB memory
  • small: 466 MiB disk, about 852 MB memory
  • medium: 1.5 GiB disk, about 2.1 GB memory
  • large: 2.9 GiB disk, about 3.9 GB memory
./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/gb0.wav

What people use it for

  • Adding offline speech-to-text to a native C or C++ application
  • Transcribing recordings on your own computer without sending them to a cloud service
  • Running transcription on Apple Silicon with GPU or Neural Engine acceleration
  • Building an offline voice assistant, using the command example the README links to
  • Running speech-to-text on constrained hardware such as a Raspberry Pi

Frequently asked questions

Is whisper.cpp free to use?

whisper.cpp is released under the MIT licence, as stated on the repository page. The MIT licence generally allows use, modification and redistribution, including in commercial projects. Check the LICENSE file in the repository for the full terms.

What do I need to install whisper.cpp?

The README lists git, CMake, a C/C++ compiler and ffmpeg as optional. You clone the repository, download a model and build it with CMake. No external dependencies are required by the core project.

Why does whisper-cli reject my MP3 file?

The CLI example currently runs only with 16-bit WAV files. Convert your audio first with ffmpeg, using the command shown in the README, and then run whisper-cli on the output file.

Can whisper.cpp work offline?

Yes. The project describes itself as able to work offline on the device, and the README gives an example of running the model fully offline on an iPhone 13.

Which model should I pick?

The README lists tiny, base, small, medium and large models with their disk size and memory use. Smaller models need less memory, so choose based on the hardware you have. The README uses base.en as its example.

How does whisper.cpp compare with faster-whisper or openai-whisper?

This guide does not compare benchmarks, since the source does not include them. Comparable projects include faster-whisper, openai-whisper, whisperx and insanely-fast-whisper. Pick based on whether you need a C/C++ library, a Python tool or a hosted service.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

whisper.cpp suits developers who want to embed offline speech-to-text in a native app, or people who want private transcription on their own machine and are comfortable with the command line. If you want a ready-made app with a graphical interface or a hosted transcription API, pick a different tool.

Install options & downloads