How to Use whisper.cpp: A Complete 2026 Guide

## How to use whisper.cpp whisper.cpp is a C/C++ implementation of OpenAI's Whisper speech-recognition model. It lets you run transcription and related audio tasks from the command line or integrate them into applications, often without sending audio to a hosted transcription service. This guide explains how to build it, obtain a model, transcribe files, generate subtitles, tune accuracy and speed, and diagnose common problems. The project is a runtime and implementation, not a single-click transcription website. You will need a compatible model file, a supported build environment, and audio that the program can read. The exact commands and available options can change between releases, so treat the output of `whisper-cli --help` in your installed version as the final reference. ## What whisper.cpp does Whisper is a multilingual speech-recognition model family. whisper.cpp provides a native implementation designed to run on a range of hardware, including ordinary CPUs and, where supported and enabled, accelerator backends. It can transcribe audio, perform speech translation into English, identify timestamps, and create subtitle-oriented output formats. Some builds also expose other modes, such as voice activity detection or server and streaming examples; availability depends on the current version and build configuration. A typical workflow has four parts: 1. Build or install whisper.cpp for your operating system and hardware. 2. Download a compatible Whisper model in the format expected by the project. 3. Provide an audio file and select appropriate transcription options. 4. Inspect and export the result, correcting names, punctuation, and domain-specific terms as needed. The tool does not guarantee a perfect transcript. Recognition quality depends on the model, language, microphone, recording conditions, accents, overlap, and vocabulary. Local processing can help keep audio on your device, but privacy also depends on where you download models, how your own application handles files, and whether you use any network-facing service or wrapper. ### whisper.cpp versus hosted transcription | Consideration | whisper.cpp on your machine | Hosted transcription service | |---|---|---| | Audio handling | Can process files locally after setup | Usually uploads audio to a provider | | Setup | Requires a model and a compatible build | Often starts in a browser or API client | | Control | CLI options and integration are available | Depends on the service's interface and API | | Cost model | No per-minute service fee from the local runtime; hardware and setup still have costs | May have free, usage-based, or subscription tiers; check the provider's current terms | | Maintenance | You manage versions, models, storage, and updates | Provider manages much of the infrastructure | | Best fit | Offline workflows, local experimentation, and custom applications | Fast onboarding, managed workflows, or teams that prefer not to operate local software | These are broad differences, not a claim that one approach is always better. A local command-line tool can be a poor fit for a person who needs a polished collaborative editor, while a hosted service may be unsuitable when audio must remain on a controlled machine. ## Before you start ### Check your operating system and hardware whisper.cpp is intended to be built on common desktop operating systems, but the exact build steps vary. On Linux and macOS, a C/C++ compiler and CMake are common prerequisites. On Windows, use a supported compiler environment and follow the repository's current Windows instructions. Git is useful for obtaining the source. Some acceleration paths require additional system libraries, SDKs, or compatible hardware. A CPU build is a reasonable place to begin. It is easier to verify than a specialized accelerator build and helps establish whether your model and input file work. For longer recordings, a capable GPU or a platform-specific acceleration backend may reduce processing time, but results depend on hardware, build flags, model size, and the audio itself. Do not assume that a GPU is active merely because the computer has one; inspect the build configuration and runtime logs. ### Choose the right model The model files distributed for whisper.cpp use the format expected by the project, commonly referred to as GGML in the project documentation. The repository provides scripts and instructions for obtaining or converting models. Use those documented sources and procedures rather than renaming an unrelated model file. Model families commonly offer tradeoffs between size, speed, and recognition quality. Smaller models generally use less memory and can be faster, while larger models can be more capable on difficult audio but need more resources. This is a practical tendency, not a guarantee for every language or recording. Quantized variants can reduce storage or memory requirements, with possible quality tradeoffs. | Model choice | Practical strengths | Tradeoffs | Consider it when | |---|---|---|---| | Tiny or base | Lightweight; useful for checking a workflow or processing on modest hardware | More likely to miss words in challenging recordings | You need a quick initial test or have tight resource limits | | Small | Middle ground for many general recordings | Still may struggle with noise, overlap, and specialized terms | You want to compare a lighter and larger model | | Medium | More resources than small; often a useful quality-oriented option | Slower and more memory-intensive | The recording matters enough to justify a larger model | | Large | Highest resource demand among the common sizes; can help on difficult material | Not automatically best for every language or noisy recording; requires more compute | You have suitable hardware and need to evaluate maximum available model capacity | | Quantized variant | Smaller storage or memory footprint than its corresponding full-precision form | Recognition behavior may differ; test against your own audio | The standard model does not fit comfortably or runs too slowly | Do not select a model only by its name. Test candidate models on a short, representative section of your own recordings. Include the kinds of speakers, background sound, terminology, and accents that occur in production. Compare corrections needed, not just whether the output looks plausible. ### Prepare audio Start with the original, highest-quality recording available. Clear speech, stable volume, and limited background noise help. If your file is in an unsupported container or codec, convert it with a trusted audio utility to a conventional format such as WAV. Avoid repeated lossy conversions: each conversion can discard information without improving speech. Check that the file has sound, that the expected speaker is audible, and that the channel layout is sensible. Stereo can be useful when speakers are separated by channel, but it is not automatically better. If a recording has one quiet channel, clipping, or long silence, fix or inspect that issue before concluding that the model is inaccurate. The command-line tool may accept a range of formats depending on how it was built; consult its help and examples. ## Install and build whisper.cpp The commands below describe a common source build. Project instructions can change, so verify them against the current repository README before using them. Build options are especially important when you need GPU acceleration or a platform-specific backend. ### Step 1: Get the source Install Git if it is not already available, then clone the official whisper.cpp repository and enter its directory. The repository's README describes the currently supported build process and any platform-specific prerequisites. If you already have a checkout, update it deliberately and note which version you are testing; changing versions can change options and output behavior. ### Step 2: Configure and compile A standard CMake workflow is commonly used: ```sh cmake -B build cmake --build build --config Release ``` On some systems, the executable is placed in a build subdirectory; on others, the exact path differs. Find the generated command-line program and ask it for help: ```sh ./build/bin/whisper-cli --help ``` The executable name or location may vary by release and platform. If the command is not found, inspect the build output and repository documentation rather than assuming compilation failed. A successful build proves that the program compiled, not that every optional backend is enabled. ### Step 3: Add acceleration only after the baseline works First run a short file with the default build. Then consider an accelerator documented by the project for your platform. Depending on the release and hardware, this may involve a backend such as CUDA, Metal, Vulkan, or another supported path. Each has its own dependencies and CMake configuration. Use the current project's instructions; do not copy a flag from an old tutorial without checking that your release recognizes it. Keep a record of the build command and runtime output. When investigating speed, compare the same audio, model, and options. An accelerated build may not help a tiny file because startup overhead can dominate. It can also fail to use the intended device if dependencies or configuration are missing. ## Download and verify a model Use the project's model instructions or scripts to obtain a model compatible with the version you built. Save it to a predictable location, such as a `models` directory, and keep the filename intact. The examples below use `models/ggml-base.bin` as a placeholder; substitute the real path to your downloaded model. For a first test, choose a model that your system can load comfortably. If the program reports that a model cannot be opened, check the path, permissions, file completeness, and expected model format. A file extension alone does not establish compatibility. If the repository offers a conversion script, follow its documented inputs and outputs. Store models responsibly. They can consume substantial disk space, and several variants can accumulate quickly. Keep notes about the model name, source, quantization, and version used for a transcript if reproducibility matters. For sensitive workloads, verify the model's origin and your organization's rules for software and model downloads. ## Transcribe your first audio file With a model and audio file available, run the CLI with explicit paths. A typical command looks like this: ```sh ./build/bin/whisper-cli \ -m models/ggml-base.bin \ -f audio.wav ``` Check `--help` for the exact flags in your build. Most command-line examples use one option to select the model and another to select the input file, but names and supported options should be confirmed locally. The program normally prints recognized text and may print timing or performance information as well. If your first run fails, do not immediately change several settings. Confirm that the executable starts, the model loads, the audio opens, and the selected language is appropriate. Then change one variable at a time. This makes it easier to identify whether the issue comes from the file, model, build, or option selection. ### Select the language Whisper can recognize multiple languages. You can often let the model detect a language, or specify it explicitly with the option supported by your build. Explicit language selection can help when a recording is short, contains little speech, or mixes language cues in a way that confuses automatic detection. Use the language codes and syntax documented by the installed CLI. For multilingual recordings, automatic detection does not necessarily produce a clean, speaker-by-speaker language transcript. Code-switching, names, and short phrases may be handled inconsistently. Review those sections manually and test a representative sample before processing a large batch. ### Transcribe speech as spoken or translate to English Transcription aims to represent the spoken language. Translation mode instead produces English text from supported non-English speech. The exact option name is version-dependent, so confirm it with `--help`. Translation is not the same as a faithful transcript: it may change word order, omit disfluencies, and choose an interpretation rather than preserve every original expression. When you need an auditable record, retain the original-language transcript and create a separate translation. Label each output clearly so readers do not mistake translated text for the words spoken in English. ## Create timestamps and subtitle files Timestamps are useful for editing, reviewing, and aligning text with audio. whisper.cpp can produce output formats suitable for subtitle workflows, depending on the CLI options in your version. Check the help output for formats such as SRT, VTT, or timestamped text. A typical pattern is to specify an output format or output path in addition to the model and input. ```sh ./build/bin/whisper-cli \ -m models/ggml-base.bin \ -f interview.wav \ -osrt ``` Treat that option as an example, not a universal promise: option names and supported formats can change. Verify the generated file and open it in the editor or player used for your project. Inspect subtitle timing, line breaks, punctuation, and speaker changes. Automatic timestamps can drift or split phrases awkwardly, especially with pauses, overlapping speech, music, or rapid dialogue. ### Subtitle review checklist - Confirm that the first and last captions align with audible speech. - Check captions around long pauses, interruptions, and speaker changes. - Break lines at natural phrase boundaries rather than mid-thought. - Correct names, acronyms, numbers, and domain-specific vocabulary. - Check that captions are readable at the playback size and do not obscure important on-screen text. - Replay every corrected segment; a transcript can be grammatically tidy and still be wrong. ## Improve transcription quality ### Use the best source recording Preprocessing is not a substitute for a good microphone or clean recording. If you can control recording, keep the microphone near the speaker, avoid handling noise, and prevent clipping. In post-production, a modest volume adjustment or removal of long silence can make a file easier to review, but aggressive noise reduction may distort consonants and harm recognition. Do not treat resampling as a quality upgrade. It may be necessary to satisfy a tool's input requirements, but it cannot recreate detail that was never captured. Follow the input guidance provided by your build and use a standard conversion tool when needed. ### Set language and context deliberately Explicitly choose the language when you know it and the automatic detector is unreliable. Some versions expose prompt or initial-context options that can help with names and specialized vocabulary. These are hints, not dictionaries or guarantees. Check the exact option syntax in the installed CLI and avoid stuffing a long list of unrelated words into a prompt; excessive or misleading context can bias output. For technical terms, create a correction list after transcription. Decide on preferred spellings for product names, acronyms, and people. Apply corrections consistently, but verify each occurrence against the audio rather than blindly replacing a similar-looking word. ### Compare models with a repeatable test Choose a representative excerpt and run it with two or more candidate models using identical language and decoding settings. Compare the actual errors: omitted phrases, substitutions, punctuation, and timestamps. If you have a trusted reference transcript, use it to assess differences, while remembering that references can also contain mistakes. Keep a record of model and build settings so later changes are comparable. ### Know the limits of automatic cleanup Speech recognition does not reliably identify every speaker or infer the correct meaning from context. A transcript may omit a quiet speaker, normalize a disfluency, misread a proper noun, or produce plausible wording in a noisy gap. Do not use fluent wording as evidence that a segment is accurate. Verify important quotations and any transcript used for legal, medical, financial, safety, or employment decisions with an appropriate human review process. ## Batch processing and repeatable workflows For several files, a shell loop can run the same command against each input. Test the command on one file first, quote paths that contain spaces, and write each result to a distinct output name. A generic shell pattern is: ```sh for file in recordings/*.wav; do ./build/bin/whisper-cli -m models/ggml-base.bin -f "$file" done ``` This example prints output to the terminal; it does not define a reliable naming scheme for saved transcripts. Use the output options supported by your version or add a small wrapper that derives a safe output filename. Test filenames containing spaces and non-English characters on your target system. Avoid overwriting source files or earlier transcripts. For a production batch job, plan for failures rather than assuming every file is valid. Log the input path, model, command options, exit status, and output location. Keep each file's result isolated so one failure does not silently replace another. Consider file size and available memory when running jobs concurrently. Multiple simultaneous model instances can use significantly more memory than one process. ### A practical batch checklist 1. Make a read-only copy or backup of the source audio. 2. Validate that each file is readable and has a supported format. 3. Choose and record a model and language setting. 4. Run a small sample batch and inspect outputs. 5. Add logging and unique output paths before scaling up. 6. Review failures, empty transcripts, and unusually short outputs. 7. Preserve the original audio and document any manual edits. ## Using whisper.cpp in an application The repository includes integration-oriented code and examples, but the precise APIs and example programs can change. Check the current project documentation before building an application around a particular interface. A command-line call is often adequate for a personal script. A service or embedded integration needs additional decisions: concurrency, cancellation, memory limits, file validation, error reporting, and cleanup of temporary audio. If you expose transcription through an HTTP endpoint, treat audio as sensitive input. Apply authentication and authorization, limit request size and processing time, and avoid writing files into publicly served locations. Define retention and deletion behavior. A locally hosted service is not automatically private if logs, backups, or access controls are careless. For applications that need an interface rather than a local CLI, consider what the user actually needs. A screen recorder and a speech transcription engine solve different problems: [Loom](/en/tools/loom) focuses on recording and sharing screen or camera presentations, while whisper.cpp is a software component for running speech recognition. They can be complementary, but one is not a direct replacement for the other. ## whisper.cpp and other AI tools: choose by task The directory below contains AI products that may support adjacent parts of a media workflow. Their presence does not mean they use whisper.cpp, provide equivalent transcription, or guarantee a particular export feature. Verify the product's current capabilities and terms before relying on it. | Tool | Better suited to | How it relates to whisper.cpp | Pricing tier | |---|---|---|---| | [Gemini](/en/tools/gemini) | General AI assistance and work with supported content | Can help organize or summarize text you provide; it is not the same as running whisper.cpp locally | Freemium; check the official site for current pricing | | [Loom](/en/tools/loom) | Recording and sharing screen or camera updates | Captures a presentation workflow; whisper.cpp can be used separately to recognize compatible audio | Freemium; check the official site for current pricing | | [Opus Clip](/en/tools/opus-clip) | Repurposing longer video into shorter clips | Video editing and clip selection are distinct from local speech recognition | Freemium; check the official site for current pricing | | [Canva](/en/tools/canva) | Designing visual content and presentations | Useful after transcription when turning selected material into visual assets; not a substitute for a local model | Freemium; check the official site for current pricing | | [Gamma](/en/tools/gamma) | Creating presentations and structured visual documents | Can be relevant when turning reviewed transcript material into a presentation | Freemium; check the official site for current pricing | | [Wix AI](/en/tools/wix-ai) | Building or managing website content | Can support publishing a reviewed transcript or article, not the local transcription step itself | Freemium; check the official site for current pricing | | [Magical](/en/tools/magical) | Repetitive text and browser-based workflow assistance | May help with downstream text tasks; it is not a replacement for audio recognition | Free; check the official site for current pricing | | [Replicate](/en/tools/replicate) | Accessing hosted machine-learning models and APIs | A hosted model workflow differs from running whisper.cpp on your own hardware; compare privacy, operations, and usage terms | Freemium; check the official site for current pricing | Choose a tool according to the job. For local file transcription and experimentation, whisper.cpp offers direct control over the runtime and model. For editing, publishing, presentation creation, or hosted AI access, an adjacent product may be more convenient. Do not upload confidential audio or transcript text to another service unless its data handling is appropriate for your needs. ## Common errors and troubleshooting ### The model file cannot be opened Check the full path, filename, permissions, and whether the download completed. Confirm that the file is a model format supported by your whisper.cpp version. A model from a different runtime may need conversion. Follow the repository's model instructions; changing the extension is not conversion. ### The audio file cannot be read Try a known-good WAV file to separate an input-format issue from a build issue. Inspect the file with an audio player and confirm it is not empty or corrupt. Convert it with a trusted utility if necessary, using the input format recommended by the project. If the file is multichannel or unusual, make a simple mono test copy and compare results. ### The output is in the wrong language Set the language explicitly using the syntax supported by your build. Check for music, silence, very short speech, or multiple languages that could confuse detection. If the recording switches languages, review each section rather than expecting a single language setting to describe the whole conversation. ### Transcription is slow Confirm which model is loaded and whether the intended acceleration backend is active. Try a smaller model to establish a baseline, then compare a supported accelerated build. Close competing workloads if memory is constrained. Processing speed also varies with audio duration, hardware, build settings, and the model; avoid extrapolating from a very short test clip. ### The output repeats or hallucinates text This can happen when the audio contains silence, noise, music, or speech that is hard to distinguish. Inspect the audio, language setting, and any prompt or context option. Test a different model or a clean excerpt. Do not treat repeated fluent text as evidence that the file contains those words. For critical material, verify against the recording. ### The build succeeds but a backend is unavailable Compilation may complete while an optional accelerator is not enabled. Review the CMake configuration, dependency detection, and runtime startup messages. Compare with the current platform instructions. A CPU fallback can still be useful for validation, but make sure you know which device is actually doing the work. ### Subtitle timing looks wrong Check that the audio itself has not been trimmed or shifted after transcription. Review pauses, overlapping speech, and long sections of music. If you edited the audio, regenerate subtitles from the final audio or align them again in a subtitle editor. Do not assume timestamps remain valid after changing the source timeline. ## Privacy, licensing, and responsible use Local inference can reduce the need to upload audio, but it does not settle every privacy question. Model downloads, package managers, telemetry in surrounding tools, shell history, logs, backups, and application integrations can all affect data exposure. Check your software environment and follow the policies that govern the recordings. Remove temporary files when they are no longer needed and restrict access to stored transcripts. Review the licenses and terms for the whisper.cpp software, model weights, and any dependencies used in your deployment. Software and model terms can differ. For redistribution or commercial use, consult the applicable current licenses rather than assuming that local execution removes obligations. Transcripts can contain personal or confidential information. Limit access, define retention, and obtain appropriate consent where required. Recognition errors can materially change meaning, so do not use a raw automatic transcript as the sole basis for high-impact decisions. ## A recommended end-to-end workflow For a dependable first project, proceed in small stages: 1. Read the current repository build instructions and install the basic compiler tools. 2. Build a CPU version and confirm that its CLI help runs. 3. Download one compatible model through the project's documented process. 4. Test a short, representative recording in a standard format. 5. Set the language explicitly if detection is unreliable. 6. Generate plain text first, then create timestamped or subtitle output if needed. 7. Review names, numbers, punctuation, and difficult passages against the audio. 8. Compare another model or build only when the baseline shows a real limitation. 9. For batch use, add logging, unique outputs, input validation, and failure handling. 10. Document the model and settings, and protect both source recordings and transcripts. This workflow keeps setup problems separate from recognition-quality problems. It also makes it easier to reproduce a result when you update the source, model, or hardware configuration. ## FAQ ### Is whisper.cpp free to use? The whisper.cpp project is open-source software, but you should check the current repository license and the terms for the specific model and dependencies you use. Running locally avoids a hosted transcription charge from that runtime, but hardware, storage, and engineering time still have costs. Check the official project and model sources for current terms. ### Does whisper.cpp work without an internet connection? After you have obtained the software and a compatible model, inference can be run offline. Initial setup requires getting the source or binary and model files. Any wrapper, update checker, or surrounding application may make network requests, so verify the behavior of your complete setup rather than assuming every component is offline. ### Can whisper.cpp transcribe live speech? The repository has offered examples and modes related to streaming or microphone input, but their availability and behavior can vary by version and platform. Check the current examples and build instructions. A workflow that processes recorded files is usually simpler to validate than a real-time application, which also needs to handle buffering, latency, and interruptions. ### Which model should I use? Start with a model that fits your memory and processing constraints, then test a representative sample. Smaller models can be quicker and lighter; larger ones use more resources and may improve some difficult cases. The best choice depends on language, recording quality, vocabulary, and hardware, so compare actual outputs rather than relying on model size alone. ### Can it create subtitles? The CLI can provide timestamped or subtitle-oriented output in supported versions. Check `--help` for the available formats and options. Review the result for timing, line breaks, speaker changes, and terminology before publishing; automatic output is a draft, not a guaranteed finished subtitle file. ### Why does it make mistakes on names and technical vocabulary? A model may not have enough acoustic evidence to distinguish an unfamiliar term, and similar-sounding words can be ambiguous. Improve the source audio, set the language, use documented context options if appropriate, and correct the transcript against the recording. Keep a consistent glossary for recurring terms, but verify every correction in context. ### Is local transcription automatically private? No. Local processing can avoid sending the audio to a transcription provider, but privacy also depends on file storage, logs, backups, access controls, model sources, and any connected application. Review the full workflow and the rules that apply to the recording. ### Is whisper.cpp the same as Whisper in a browser app? No. Whisper refers to a speech-recognition model family, while whisper.cpp is a particular implementation for running compatible models. A browser or hosted service may use different software, model versions, processing settings, and data practices. Compare the implementation and terms rather than assuming they are identical.