Registry / ai-ml / speechrecognition

speechrecognition

JSON →
library3.17.0pypypi✓ verified 24d ago

SpeechRecognition is a comprehensive Python library for performing speech recognition. It supports various engines and APIs, both online (e.g., Google Web Speech API, Google Cloud Speech, OpenAI Whisper API, AWS Transcribe, Microsoft Azure Speech, Cohere Transcribe) and offline (e.g., CMU Sphinx, Vosk, Whisper via local models). It is actively maintained with frequent minor and patch releases, currently at version 3.16.0.

pip install SpeechRecognition
INSTALL
IMPORT
SIG · SPEECHRECOGNITION
S
speechrecognition
ai-mlpythonv3.17.0
Install
Import
Disk
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.17.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
2/4 runs
3/4 runs
py 3.11
2/4 runs
3/4 runs
py 3.12
2/4 runs
3/4 runs
py 3.13
2/4 runs
3/4 runs
py 3.9
2/4 runs
3/4 runs
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Recognizer
import speech_recognition as sr r = sr.Recognizer()
Microphone
import speech_recognition as sr mic = sr.Microphone()
AudioFile
import speech_recognition as sr audio_file = sr.AudioFile('path/to/file.wav')
UnknownValueError
from speech_recognition import UnknownValueError
RequestError
from speech_recognition import RequestError

This quickstart demonstrates how to transcribe audio using the SpeechRecognition library. It includes a runnable microphone input example (with graceful degradation if PyAudio is not installed) and an example for transcribing from an audio file. For the audio file example, it attempts to create a dummy WAV file using `pydub` if available, otherwise, it expects a manual WAV file. It uses the free Google Web Speech API for transcription. A third option for using a commercial API (OpenAI Whisper) is also included, requiring an API key and additional installation.

import speech_recognition as sr import os r = sr.Recognizer() # --- Option 1: Listen from Microphone (requires PyAudio and PortAudio) --- try: import pyaudio with sr.Microphone() as source: print("Say something into the microphone!") r.adjust_for_ambient_noise(source, duration=1) # Adjust for ambient noise audio = r.listen(source, timeout=5, phrase_time_limit=10) print("Processing microphone input...") text = r.recognize_google(audio) print(f"You said (Google Web Speech): {text}") except sr.WaitTimeoutError: print("No speech detected within the timeout period for microphone.") except sr.UnknownValueError: print("Google Web Speech Recognition could not understand microphone audio.") except sr.RequestError as e: print(f"Could not request results from Google Web Speech service for microphone; {e}") except ImportError: print("PyAudio not installed. Cannot use microphone. To enable, install with: pip install pyaudio") except Exception as e: print(f"An unexpected error occurred with microphone input: {e}") # --- Option 2: Transcribe an Audio File (e.g., using Google Web Speech API) --- file_path = "dummy_audio.wav" # Create a dummy WAV file for demonstration if it doesn't exist if not os.path.exists(file_path): try: from pydub import AudioSegment AudioSegment.silent(duration=1000, frame_rate=16000).export(file_path, format="wav") print(f"\nCreated a dummy WAV file: {file_path}") except ImportError: print("\npydub not installed, cannot create dummy audio. Please provide a WAV file manually.") print("Skipping audio file transcription example.") file_path = None if file_path: try: with sr.AudioFile(file_path) as source: audio = r.record(source) # Read the entire audio file print(f"Transcribing '{file_path}'...") text = r.recognize_google(audio) print(f"Transcription (Google Web Speech): {text}") except sr.UnknownValueError: print(f"Google Web Speech Recognition could not understand audio from '{file_path}'.") except sr.RequestError as e: print(f"Could not request results from Google Web Speech service for '{file_path}'; {e}") except Exception as e: print(f"An error occurred with audio file transcription: {e}") # --- Option 3: Using a Commercial API (e.g., OpenAI Whisper API) --- # Requires 'pip install openai' and setting OPENAI_API_KEY environment variable OPENAI_API_KEY = os.environ.get("OPENAI_API_KEY", "") if OPENAI_API_KEY and file_path: print("\nAttempting transcription with OpenAI Whisper API...") try: with sr.AudioFile(file_path) as source: audio = r.record(source) text = r.recognize_whisper_api(audio, api_key=OPENAI_API_KEY) print(f"Transcription (OpenAI Whisper API): {text}") except sr.UnknownValueError: print(f"OpenAI Whisper API could not understand audio from '{file_path}'.") except sr.RequestError as e: print(f"Could not request results from OpenAI Whisper API service; {e}") except Exception as e: print(f"An error occurred with OpenAI Whisper API: {e}") else: print("\nSkipping OpenAI Whisper API example (OPENAI_API_KEY not set or no audio file for transcription).")
Debug
Known issues
breakingSpeechRecognition version 3.x and later requires Python 3.9 or newer. Older Python 3.x versions (e.g., 3.6-3.8) and Python 2 are no longer supported.
fix
Upgrade your Python environment to 3.9 or higher.
affects: <3.9
gotchaMany speech recognition features (e.g., microphone input, specific offline recognizers like PocketSphinx/Vosk) require additional system-level libraries (e.g., PortAudio for PyAudio, FLAC binaries) or Python packages that are not installed by default with `pip install SpeechRecognition`.
fix
Consult the official documentation for specific installation instructions for your chosen recognizer and input method (e.g., `pip install pyaudio`, system-level `portaudio` development headers, `pip install vosk`, etc.).
affects: All
gotchaCommercial APIs (e.g., Google Cloud Speech, OpenAI Whisper API, AWS Transcribe, Microsoft Azure Speech, Cohere Transcribe) require API keys, which are typically passed as an argument or loaded from environment variables. These services are not free and incur costs.
fix
Obtain an API key from the respective service provider and provide it when calling the recognition method (e.g., `recognize_google_cloud(audio, credentials_json=YOUR_KEY)` or `recognize_whisper_api(audio, api_key=os.environ.get('OPENAI_API_KEY'))`). The `recognize_google` method is free for limited use without an explicit key.
affects: All
gotchaOffline recognition engines like Vosk and PocketSphinx require separate language model downloads, which can be large (hundreds of MBs to several GBs). These models are not included with the Python package installation.
fix
Follow the documentation for your chosen offline engine to download and specify the correct model path (e.g., `model = vosk.Model('path/to/model')` for Vosk, or using the `sprc download vosk` CLI command introduced in 3.14.4).
affects: All
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pyaudio'
The PyAudio library, a dependency for microphone input, is not installed or incorrectly installed.
fix
Install PyAudio using `pip install PyAudio`. On some systems (especially Linux), you might need to install system-level PortAudio development headers first (e.g., `sudo apt-get install portaudio19-dev`).
speech_recognition.UnknownValueError
The speech recognition service could not understand or interpret the audio input.
fix
Implement robust error handling using a `try...except sr.UnknownValueError` block and ensure the audio input is clear, free of background noise, and in a language supported by the chosen recognizer.
speech_recognition.RequestError
There was an issue communicating with the speech recognition API service (e.g., network problem, invalid API key, service down, rate limit exceeded).
fix
Verify your internet connection, ensure any required API keys are correctly set and valid, check the API service status, and ensure you are not exceeding usage limits.
ValueError: Audio file could not be read as PCM WAV, AIFF/AIFC, or FLAC; check if file is corrupted or in an unsupported format
The `AudioFile` source expects audio files in specific uncompressed formats (WAV, AIFF/AIFC, FLAC), but an unsupported format (e.g., MP3, M4A) or a corrupted file was provided.
fix
Convert the audio file to a supported format like WAV before processing. Libraries like `pydub` can be used for conversion (e.g., `AudioSegment.from_mp3('audio.mp3').export('audio.wav', format='wav')`).
Upgrade
Version history
3.17.0latest on PyPI · released Jun 17, 2026
Audit
Dependencies
PyAudiooptionalRequired for real-time microphone input (sr.Microphone). Also needs system-level PortAudio library.
FLACoptionalRequired for some offline processing or specific recognizers (e.g., Google Web Speech API for local files on some systems). Needs system-level FLAC binaries.
pocketsphinxoptionalRequired for offline CMU Sphinx recognition (sr.recognize_sphinx). Needs system-level PocketSphinx library.
voskoptionalRequired for offline Vosk recognition (sr.recognize_vosk). Also needs specific language model downloads.
openaioptionalRequired for OpenAI Whisper API recognition (sr.recognize_whisper_api).
whisperoptionalRequired for local Whisper model recognition (sr.recognize_whisper).
pyduboptionalUsed in the quickstart example to create a dummy audio file. Not strictly required by SpeechRecognition itself.
Agent activity
47 hits · last 30 days
node
40
OpenAI (training)
1
Resources
speechrecognition — pip install speechrecognition · libregistry