SpeechRecognition: A Comprehensive Python Library for Speech-to-Text

Introduction

Speech recognition is a critical component in many modern applications, from virtual assistants and transcription services to accessibility tools and automated workflows. The SpeechRecognition library for Python provides a unified interface to a wide range of speech recognition engines and APIs, making it easy to integrate speech-to-text capabilities into your projects. Whether you need offline recognition with CMU Sphinx or cloud-based accuracy with Google, Azure, or OpenAI Whisper, this library has you covered.

Supported Engines and APIs

SpeechRecognition supports a diverse set of backends, allowing you to choose the best fit for your use case:

• Offline Engines:

  • CMU Sphinx (PocketSphinx): Works entirely offline, ideal for privacy-sensitive or low-latency applications.
  • Vosk API: Another offline option with support for multiple languages.
  • Whisper (local): OpenAI's Whisper model can run locally for high-quality transcription without internet.
  • Faster Whisper: A more optimized version of Whisper for faster inference.
  • Snowboy Hotword Detection: For wake word detection (offline).

• Cloud APIs:

  • Google Speech Recognition: Free tier available, easy to use.
  • Google Cloud Speech API: More accurate and customizable, requires authentication.
  • Microsoft Azure Speech: Enterprise-grade recognition.
  • Wit.ai: Facebook's speech API.
  • Houndify: SoundHound's API.
  • IBM Speech to Text: IBM Watson's offering.
  • OpenAI Whisper API: Cloud-based Whisper with high accuracy.
  • Groq Whisper API: Fast inference via Groq hardware.
  • Cohere Transcribe API: Cohere's transcription service.

• Self-Hosted Endpoints:

  • Supports OpenAI-compatible endpoints like vLLM and Ollama, giving you flexibility to run your own inference server.

Getting Started

Installation is straightforward with pip:

pip install SpeechRecognition

To quickly test it out, run:

python -m speech_recognition

This will use your default microphone and attempt to recognize speech using Google's free API.

Basic Usage Examples

Recognize Speech from a Microphone

import speech_recognition as sr

# Initialize recognizer
r = sr.Recognizer()

# Use the default microphone as source
with sr.Microphone() as source:
    print("Say something!")
    audio = r.listen(source)

# Recognize speech using Google Speech Recognition
try:
    text = r.recognize_google(audio)
    print(f"You said: {text}")
except sr.UnknownValueError:
    print("Could not understand audio")
except sr.RequestError as e:
    print(f"Error: {e}")

Transcribe an Audio File

import speech_recognition as sr

r = sr.Recognizer()

with sr.AudioFile("path/to/audio.wav") as source:
    audio = r.record(source)

text = r.recognize_google(audio)
print(text)

Save Audio Data to a File

with sr.Microphone() as source:
    audio = r.listen(source)

# Save to a WAV file
with open("recording.wav", "wb") as f:
    f.write(audio.get_wav_data())

Calibrate for Ambient Noise

with sr.Microphone() as source:
    r.adjust_for_ambient_noise(source)
    print("Adjusted for ambient noise. Say something!")
    audio = r.listen(source)

Listen in the Background

def callback(recognizer, audio):
    try:
        text = recognizer.recognize_google(audio)
        print(f"You said: {text}")
    except sr.UnknownValueError:
        print("Could not understand")

r.listen_in_background(sr.Microphone(), callback)

# Keep the program running
import time
while True:
    time.sleep(1)

Installation Details

PyAudio (for Microphone Input)

PyAudio is required to use the Microphone class. Install it with:

pip install SpeechRecognition[audio]

On Linux, you may need system packages:

sudo apt-get install portaudio19-dev python3-all-dev

PocketSphinx (Offline Sphinx)

pip install SpeechRecognition[pocketsphinx]

Vosk (Offline Vosk)

pip install SpeechRecognition[vosk]

Then download a Vosk model from here and place it in a model directory.

Whisper (Local)

pip install SpeechRecognition[whisper-local]

Faster Whisper

pip install SpeechRecognition[faster-whisper]

OpenAI Whisper API

pip install SpeechRecognition[openai]

Set the environment variable OPENAI_API_KEY before use.

Groq Whisper API

pip install SpeechRecognition[groq]

Set GROQ_API_KEY.

Cohere Transcribe API

pip install SpeechRecognition[cohere-api]

Set CO_API_KEY.

Troubleshooting Common Issues

Recognizer Too Sensitive or Not Sensitive Enough

Adjust the energy_threshold property. Values typically range from 50 to 4000. Higher values mean less sensitivity, useful in noisy environments.

r.energy_threshold = 3000

Recognizer Hangs on First Listen

Call adjust_for_ambient_noise before listening to set a proper threshold.

No Default Input Device

List available microphones:

import speech_recognition as sr
for index, name in enumerate(sr.Microphone.list_microphone_names()):
    print(f"Microphone with name \"{name}\" found for `Microphone(device_index={index})`")

Then use Microphone(device_index=INDEX).

Language/Dialect Issues

Set the language parameter for better accuracy. For example, use "en-GB" for British English:

text = r.recognize_google(audio, language="en-GB")

Conclusion

SpeechRecognition is a powerful and flexible library that abstracts away the complexities of different speech recognition backends. Whether you need offline capabilities for privacy or cloud-based accuracy for production, it provides a consistent API that makes development fast and maintainable. With support for the latest models like Whisper and Groq, it remains a top choice for Python developers building voice-enabled applications.

For more examples and detailed documentation, visit the GitHub repository.

Source

Uberi/speech_recognition: Speech recognition module for Python, supporting several engines and APIs, online and offline.