SpeechRecognition: one Python API for Whisper, Vosk, Sphinx and cloud speech engines
Speech recognition module for Python, supporting several engines and APIs, online and offline.
At a glance
- What is it?
- SpeechRecognition wraps a dozen recognizers behind a single AudioData and Recognizer interface, so you can swap offline Vosk for the OpenAI API without rewriting your pipeline. The trade-off is that each engine keeps its own install, model and failure modes.
- Who is it for?
- Adopt SpeechRecognition when you need one Python interface across several engines, or when you want to prototype with the free Google Web Speech endpoint before committing to a paid one. Skip it if you need streaming partial results, speaker diarization, or word-level timestamps, since the library's documented recognizers return finished transcriptions.
- Can I use it commercially?
- Yes. BSD-3-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 14 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem: every speech engine has its own Python glue
Cloud speech APIs and local models do not agree on anything. Whisper wants a NumPy array and a sample rate. Vosk wants raw PCM bytes and a loaded model object. Google Cloud wants a client library and a config object. CMU Sphinx wants a decoder and a language model path. If you write a transcription feature and later switch vendors, you rewrite the input handling, the error handling and the result parsing.
SpeechRecognition attacks that by fixing the boundary in one place. Audio in becomes an AudioData object. Audio out becomes a string, or a dict when you ask for extended results. The engine is a parameter, not an architectural decision. The library describes itself as supporting several engines and APIs, online and offline, and that is the whole pitch.
It is for Python developers building prototypes, internal tools, batch transcription jobs, or voice command handlers. It is not a speech platform. There is no server, no queue, no diarization pipeline. It is a client-side abstraction layer with a microphone helper attached.
How the Recognizer and AudioData objects fit together
The architecture has two halves. AudioData holds a recording: raw bytes plus a sample rate, sample width and channel count. Recognizer holds configuration and does the work. You create one Recognizer, then call a method named after the engine, such as recognize_google, recognize_vosk, recognize_whisper, recognize_faster_whisper, recognize_openai or recognize_sphinx. Each returns a string by default; passing show_all=True returns a dict with alternatives and confidence values where the engine provides them.
Microphone input goes through a separate class. The Microphone context manager opens a PyAudio stream, and a listen call records until it detects silence, using an energy threshold. That threshold is exposed as recognizer_instance.energy_threshold, and the repository ships examples/calibrate_energy_threshold.py to measure ambient noise before listening. This is why the README lists PyAudio as required only for microphone input: file transcription never touches it.
Two details are easy to miss. First, audio that is not already in a format the engine accepts is converted to FLAC, which is why a FLAC encoder is listed as a requirement only when the system is not x86-based Windows, Linux or macOS. Second, background listening is a separate example rather than a mode of the main API, so continuous capture is something you assemble from the pieces.
Installing SpeechRecognition and transcribing your first file
The quickstart is a single pip command. The package name on PyPI is SpeechRecognition, with capital letters, while the import name is lowercase speech_recognition. Getting that backwards is the most common first error.
pip install SpeechRecognitionAfter installing, the README suggests running the module directly to try it out:
python -m speech_recognitionThat drops you into an interactive flow rather than printing a version. For a scripted first use, the repository's examples/audio_transcribe.py is the reference. The shape is: create a Recognizer, load a file into AudioFile, open it as a source, record, then call a recognizer method inside a try block. The example uses Google Web Speech through recognize_google, which needs no API key but does need a network connection.
The library also installs a console script named sprc, declared in pyproject.toml as speech_recognition.cli:main. The README does not document its flags, so treat it as a convenience entry point and read the CLI module before scripting against it.
If you want to stay offline, install the extra dependency for your engine. Vosk needs the vosk package, Sphinx needs PocketSphinx, and Whisper needs the whisper package. Each is listed in the README under Requirements as required only if you need that specific recognizer. None of them are pulled in by the base install.
Microphone capture and the energy threshold trap
Microphone use is where the abstraction leaks. The listen method decides when you have stopped talking by comparing incoming audio energy against a threshold. In a quiet room the default may work. In a room with a fan, an air conditioner or a mechanical keyboard, it will either cut you off mid-sentence or wait forever.
The repository acknowledges this by shipping examples/calibrate_energy_threshold.py and pointing at recognizer_instance.energy_threshold in the README. The documented approach is to sample ambient noise for a moment, then set the threshold from that measurement. There is also an ambient noise adjustment duration parameter on the recognizer that the library reference documents.
A second constraint: the microphone path depends on PyAudio 0.2.11 or newer, which compiles against PortAudio. On a clean Linux container that means installing system audio headers before pip will succeed. On a headless server there is no input device at all, so the microphone API is simply unavailable and file transcription is your only option. The README does not document a fallback for that case.
Where SpeechRecognition is the wrong tool
The library returns a finished transcription. It does not stream partial hypotheses while a user is still speaking, and the documented recognizers do not expose word-level timestamps or speaker labels. If you are building live captions, a meeting transcript with speaker attribution, or anything that needs to react before the sentence ends, this interface will fight you. You would be calling a lower-level engine API directly and handling its streaming protocol yourself.
The second limitation is operational. A dozen engines behind one interface means a dozen dependency stories. Whisper pulls in PyTorch. Vosk needs a model directory downloaded separately and a language pack chosen. Sphinx needs acoustic and language models plus the notes in reference/pocketsphinx.rst about installing languages and building language packs. The base pip install gives you none of this, so the cost of the abstraction is paid at setup time, per engine.
The third is version pressure. The project requires Python 3.10 or newer, and pyproject.toml carries a commented-out Python 3.14 classifier with a note that openai-whisper does not support Python 3.14 yet. If your environment is pinned to a newer interpreter, the Whisper path may not be available even though the library itself installs.
How it compares to calling Whisper or Vosk directly
The honest alternative is skipping the wrapper. If you only ever plan to use one engine, the wrapper adds a layer you have to debug without adding capability.
Take Whisper. Calling the whisper package directly gives you the model object, the decode options, segment-level timestamps and the language detection result. SpeechRecognition's recognize_whisper gives you a string, or a dict with show_all=True. That is a real loss if you need timestamps for subtitle generation.
Vosk is similar but the difference runs the other way. Vosk's own API is streaming and returns partial results as audio arrives. Going through SpeechRecognition means feeding it a complete AudioData object and getting one final string, which discards the streaming behaviour that is Vosk's main advantage over batch models.
Where the wrapper earns its place is polyglot code. If your application needs to try a free endpoint in development and a paid one in production, or fall back from a cloud API to an offline model when the network drops, the shared Recognizer surface is worth the indirection. The moment you commit to a single engine and need its advanced output, the wrapper is overhead.
Maintenance, releases and the BSD-3-Clause licence
The repository is not archived, and the last push was on 2026-09-02. Releases are reasonably paced: 3.16.0 on 2026-04-05, 3.16.1 on 2026-04-24, and 3.17.0 on 2026-06-17. The PyPI classifier is Development Status 5, Production/Stable. Nothing in the repository layout suggests an abandoned project.
The upgrade cost sits mostly in the optional dependencies rather than in the library. Because engine packages are extras you install yourself, a SpeechRecognition upgrade does not force a PyTorch or Vosk upgrade. The reverse is also true: a breaking change in Whisper or Vosk will not be caught by upgrading this library. The Makefile runs flake8, rstcheck and mypy over speech_recognition/recognizers and tests, so the project does type-check the recognizer layer, which is some protection against interface drift.
On licensing: the project is BSD-3-Clause, declared in pyproject.toml with license-files set to LICENSE.txt and LICENSE-FLAC.txt. The separate FLAC licence file exists because the repository bundles FLAC-related code. The README does not state what that means for redistribution of your own product, and this is not legal advice. If you ship the library inside a commercial binary, read both files and confirm how the bundled FLAC component is licensed before you rely on the BSD-3-Clause label alone. Note also that each engine you enable carries its own licence, and those are not covered by this repository's files at all.
Editorial conclusion
Adopt SpeechRecognition when you need one Python interface across several engines, or when you want to prototype with the free Google Web Speech endpoint before committing to a paid one. Skip it if you need streaming partial results, speaker diarization, or word-level timestamps, since the library's documented recognizers return finished transcriptions. Before writing production code, verify that your chosen engine's extra dependency installs on your Python version and that the audio you plan to feed it is 16-bit PCM or a format the library's FLAC conversion path can handle.
Frequently asked questions
What is an example of speech recognition with the SpeechRecognition library?
The repository ships examples/audio_transcribe.py, which loads an audio file into AudioFile, records it through a Recognizer, and calls a recognizer method such as recognize_google to get a transcript string. There is also examples/microphone_recognition.py for live capture through PyAudio.
How does speech recognition work in the SpeechRecognition library?
Audio is held in an AudioData object with a sample rate, sample width and channel count, and a Recognizer object dispatches that audio to whichever engine method you call, returning a string or a dict when show_all=True is passed.
How to use speech recognition in Python with the SpeechRecognition module?
Install the package with pip, then create a Recognizer and an AudioFile or Microphone source, record, and call an engine method inside a try block. The repository's examples/ directory covers file transcription, microphone input, background listening and extended results.
How to install SpeechRecognition in Python?
Run pip install SpeechRecognition. Python 3.10 or newer is required, and engine-specific packages such as vosk, PocketSphinx, whisper or openai are separate installs listed in the README's Requirements section. PyAudio is needed only for microphone input.
How to use speech recognition in Python?
Create a Recognizer, capture audio from a Microphone or an AudioFile source, and call one of the recognize_ methods such as recognize_google, recognize_vosk or recognize_whisper. The README points to the examples/ directory for microphone recognition, file transcription, background listening and extended results.
Which AI has speech recognition that SpeechRecognition can call?
The README lists Google Speech Recognition, Google Cloud Speech API, Wit.ai, Microsoft Azure Speech, Houndify, IBM Speech to Text, the OpenAI Transcription API, Groq Whisper API and Cohere Transcribe API, alongside offline engines CMU Sphinx, Snowboy, Vosk and OpenAI Whisper.
Community notes