SpeechRecognition

https://github.com/uberi/speech_recognition
Admin
Python speech recognition library supporting multiple online and offline engines.
Tokens:31,711
Snippets:191
Trust Score:10
License:BSD-3-Clause
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install PyAudio on Windows with Pip

Source: https://github.com/uberi/speech_recognition/blob/master/README.rst

Install PyAudio on Windows using Pip. Execute this command in a terminal.

```bash
pip install SpeechRecognition[audio]
```

--------------------------------

### Install FLAC on Debian-derivatives with APT

Source: https://github.com/uberi/speech_recognition/blob/master/README.rst

Install the flac command line tool on Debian-derivatives. Required on systems where FLAC is not bundled with the library.

```bash
sudo apt-get install flac
```

--------------------------------

### Install PortAudio on OS X with Homebrew

Source: https://github.com/uberi/speech_recognition/blob/master/README.rst

Install PortAudio on OS X using Homebrew.

```bash
brew install portaudio
```

--------------------------------

### Install PyAudio on Debian-derived Linux with APT

Source: https://github.com/uberi/speech_recognition/blob/master/README.rst

Install PyAudio on Debian-derived Linux distributions (like Ubuntu and Mint) using APT.

```bash
sudo apt-get install python-pyaudio python3-pyaudio
```

--------------------------------

### Install Vosk with Pip

Source: https://github.com/uberi/speech_recognition/blob/master/README.rst

Install Vosk API for the Vosk recognizer (recognizer_instance.recognize_vosk). Required only if you want to use Vosk recognizer.

```bash
python3 -m pip install SpeechRecognition[vosk]
```

--------------------------------

### Install Whisper with Pip

Source: https://github.com/uberi/speech_recognition/blob/master/README.rst

Install Whisper for the whisper recognizer (recognizer_instance.recognize_whisper). Required only if you want to use whisper.

```bash
python3 -m pip install SpeechRecognition[whisper-local]
```

--------------------------------

### Install latest PyAudio on Debian-derived Linux with Pip

Source: https://github.com/uberi/speech_recognition/blob/master/README.rst

If the version in the repositories is too old, install the latest release using Pip. Replace 'pip' with 'pip3' if using Python 3.

```bash
sudo apt-get install portaudio19-dev python-all-dev python3-all-dev && sudo pip install SpeechRecognition[audio]
```

--------------------------------

### Build and install IRSTLM

Source: https://github.com/uberi/speech_recognition/blob/master/reference/pocketsphinx.rst

Run the standard build sequence for IRSTLM after downloading and extracting its source code.

```bash
sh regenerate-makefiles.sh --force && ./configure && make && sudo make install
```

--------------------------------

### Install FLAC on OS X with Homebrew

Source: https://github.com/uberi/speech_recognition/blob/master/README.rst

Install the flac command line tool on OS X with Homebrew. Required on systems where FLAC is not bundled with the library.

```bash
brew install flac
```

--------------------------------

### Build and install SphinxBase

Source: https://github.com/uberi/speech_recognition/blob/master/reference/pocketsphinx.rst

Run the standard build sequence for SphinxBase after downloading and extracting its source code.

```bash
sh autogen.sh --force && ./configure && make && sudo make install
```

--------------------------------

### Install Google Cloud Speech Library with Pip

Source: https://github.com/uberi/speech_recognition/blob/master/README.rst

Install google-cloud-speech for the Google Cloud Speech-to-Text API (recognizer_instance.recognize_google_cloud). Required only if you want to use Google Cloud Speech-to-Text API.

```bash
python3 -m pip install SpeechRecognition[google-cloud]
```

--------------------------------

### Install PocketSphinx with Pip

Source: https://github.com/uberi/speech_recognition/blob/master/README.rst

Install PocketSphinx for the Sphinx recognizer (recognizer_instance.recognize_sphinx). Required only if you want to use the Sphinx recognizer. On Linux and other POSIX systems (such as OS X).

```bash
pip install SpeechRecognition[pocketsphinx]
```

--------------------------------

### Install SphinxBase build dependencies

Source: https://github.com/uberi/speech_recognition/blob/master/reference/pocketsphinx.rst

Install the build dependencies required to compile SphinxBase on a Debian-derived Linux distribution.

```bash
sudo apt-get install build-essential automake autotools-dev autoconf libtool
```

--------------------------------

### Using Microphone as a context manager

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Open the microphone and start recording within a with statement. The microphone is automatically released when the block exits.

```python
with Microphone() as source:    # open the microphone and start recording
    pass                        # do things here - ``source`` is the Microphone instance created above
                                # the microphone is automatically released at this point
```

--------------------------------

### Bash script to install PocketSphinx language packs

Source: https://github.com/uberi/speech_recognition/blob/master/reference/pocketsphinx.rst

Downloads and extracts French, Mandarin, and Italian language packs into the SpeechRecognition module directory. Requires the three ZIP files in the current directory and uses sudo for unzip and permission changes.

```bash
#!/usr/bin/env bash
SR_LIB=$(python -c "import speech_recognition as sr, os.path as p; print(p.dirname(sr.__file__))")
sudo apt-get install --yes unzip
sudo unzip -o fr-FR.zip -d "$SR_LIB"
sudo chmod --recursive a+r "$SR_LIB/pocketsphinx-data/fr-FR/"
sudo unzip -o zh-CN.zip -d "$SR_LIB"
sudo chmod --recursive a+r "$SR_LIB/pocketsphinx-data/zh-CN/"
sudo unzip -o it-IT.zip -d "$SR_LIB"
sudo chmod --recursive a+r "$SR_LIB/pocketsphinx-data/it-IT/"
```

--------------------------------

### get_segment(start_ms, end_ms)

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Returns a new AudioData instance trimmed to a given time interval. The new instance has the same audio data except starting at start_ms milliseconds in and ending at end_ms milliseconds in.

```APIDOC
## get_segment(start_ms, end_ms)

### Description
Returns a new AudioData instance trimmed to a given time interval. The new instance has the same audio data except starting at start_ms milliseconds in and ending at end_ms milliseconds in.

### Method
`audiodata_instance.get_segment(start_ms: Union[float, None] = None, end_ms: Union[float, None] = None) -> AudioData`

### Parameters
- **start_ms** (float, optional) - Optional - Start time in milliseconds. Defaults to the beginning of the audio.
- **end_ms** (float, optional) - Optional - End time in milliseconds. Defaults to the end of the audio.

### Returns
- **AudioData** - A new AudioData instance trimmed to the specified interval.
```

--------------------------------

### Create Microphone instance for first working microphone

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Use list_working_microphones() to find a working microphone and create a Microphone instance. If none are found, prints a message.

```python
for device_index in Microphone.list_working_microphones():
    m = Microphone(device_index=device_index)
    break
else:
    print("No working microphones found!")
```

--------------------------------

### Create Microphone instance by name

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Iterate over microphone names to find a specific one and create a Microphone instance with its device index.

```python
m = None
for i, microphone_name in enumerate(Microphone.list_microphone_names()):
    if microphone_name == "HDA Intel HDMI: 0 (hw:0,3)":
        m = Microphone(device_index=i)
```

--------------------------------

### Use a specific microphone with Microphone(device_index=3)

Source: https://github.com/uberi/speech_recognition/blob/master/README.rst

Replace the default Microphone() with Microphone(device_index=3) to use the Blue Snowball microphone. This is necessary when no default input device is available.

```python
Microphone(device_index=3)
```

--------------------------------

### Download default Vosk model with sprc

Source: https://github.com/uberi/speech_recognition/blob/master/README.rst

Download the default Vosk model. You can also place downloaded models in the 'model' directory of your project.

```bash
sprc download vosk
```

--------------------------------

### List microphone indices for Raspberry Pi

Source: https://github.com/uberi/speech_recognition/blob/master/README.rst

Run this code to find the hardware-specific microphone index for use with Microphone(device_index=MICROPHONE_INDEX). It prints each microphone name and its index.

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

--------------------------------

### Default Microphone() call that raises IOError

Source: https://github.com/uberi/speech_recognition/blob/master/README.rst

Calling Microphone() without arguments raises IOError: No Default Input Device Available when no default microphone is set. Use Microphone(device_index=MICROPHONE_INDEX, ...) or set a default microphone in the OS.

```python
Microphone()
```

--------------------------------

### Upgrade PyInstaller to fix compilation issues

Source: https://github.com/uberi/speech_recognition/blob/master/README.rst

Run this command to upgrade PyInstaller to version 3.0 or later, which supports SpeechRecognition out of the box. This resolves weird issues when compiling the program with PyInstaller.

```bash
pip install --upgrade pyinstaller
```

--------------------------------

### Open audio file with AudioFile

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Opens an audio file for reading using the AudioFile context manager. Inside the with block, the source variable is the AudioFile instance.

```python
import speech_recognition as sr
with sr.AudioFile("SOME_AUDIO_FILE") as source:    # open the audio file for reading
    pass                                           # do things here - ``source`` is the AudioFile instance created above
```

--------------------------------

### recognize_wit(audio_data, key, show_all)

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Performs speech recognition on audio data using the Wit.ai API. Requires a Wit.ai API key.

```APIDOC
## recognize_wit(audio_data, key, show_all)

### Description
Performs speech recognition on `audio_data` (an `AudioData` instance) using the Wit.ai API. Requires a Wit.ai API key.

### Method
recognize_wit

### Endpoint
recognizer_instance.recognize_wit

### Parameters
#### Path Parameters
- **audio_data** (AudioData) - Required - The audio data to recognize.

#### Query Parameters
- **key** (str) - Required - Wit.ai API key (32-character uppercase alphanumeric string).
- **show_all** (bool) - Optional - If false (default), returns most likely transcription. If true, returns raw API response as JSON dictionary.

### Response
#### Success Response (200)
- **result** (Union[str, Dict[str, Any]]) - Most likely transcription or raw API response as JSON dictionary.

### Error Handling
- Raises `speech_recognition.UnknownValueError` if speech is unintelligible.
- Raises `speech_recognition.RequestError` if recognition fails, key is invalid, or no internet connection.
```

--------------------------------

### Convert Italian ARPA language model to Sphinx binary format

Source: https://github.com/uberi/speech_recognition/blob/master/reference/pocketsphinx.rst

Converts the Italian language model from ARPA to Sphinx binary format using sphinx_lm_convert.

```bash
sphinx_lm_convert -i italian.lm -o italian.lm.bin
```

--------------------------------

### recognize_houndify(audio_data, client_id, client_key, show_all)

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Performs speech recognition on audio data using the Houndify API. Requires a Houndify client ID and client key.

```APIDOC
## recognize_houndify(audio_data, client_id, client_key, show_all)

### Description
Performs speech recognition on `audio_data` (an `AudioData` instance) using the Houndify API. Requires a Houndify client ID and client key.

### Method
recognize_houndify

### Endpoint
recognizer_instance.recognize_houndify

### Parameters
#### Path Parameters
- **audio_data** (AudioData) - Required - The audio data to recognize.

#### Query Parameters
- **client_id** (str) - Required - Houndify client ID.
- **client_key** (str) - Required - Houndify client key.
- **show_all** (bool) - Optional - If false (default), returns most likely transcription. If true, returns raw API response as JSON dictionary.

### Response
#### Success Response (200)
- **result** (Union[str, Dict[str, Any]]) - Most likely transcription or raw API response as JSON dictionary.

### Error Handling
- Raises `speech_recognition.UnknownValueError` if speech is unintelligible.
- Raises `speech_recognition.RequestError` if recognition fails, client credentials are invalid, or no internet connection.
```

--------------------------------

### AudioFile(filename_or_fileobject)

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Creates a new AudioFile instance given a WAV/AIFF/FLAC audio file. It is a subclass of AudioSource and is a context manager for use with 'with' statements.

```APIDOC
## AudioFile(filename_or_fileobject)

### Description
Creates a new `AudioFile` instance given a WAV/AIFF/FLAC audio file `filename_or_fileobject`. Subclass of `AudioSource`. If `filename_or_fileobject` is a string, it is interpreted as a path to an audio file. Otherwise, it should be a file-like object such as `io.BytesIO`.

### Constructor Parameters
- **filename_or_fileobject** (Union[str, io.IOBase]) - Required - A path to an audio file or a file-like object.

### Usage
Instances of this class are context managers, and are designed to be used with `with` statements:

```python
with AudioFile("audio.wav") as source:
    # do things here
```
```

--------------------------------

### recognizer_instance.listen

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Listens for a phrase from the audio source and returns the captured audio as an AudioData instance. Use this to capture a single phrase for recognition.

```APIDOC
## [METHOD] recognizer_instance.listen

### Description
Listens for a phrase from the audio source and returns the captured audio as an AudioData instance. Use this to capture a single phrase for recognition.

### Method
CALL

### Endpoint
recognizer_instance.listen(source: AudioSource, timeout: Union[float, None] = None, phrase_time_limit: Union[float, None] = None, snowboy_configuration: Union[Tuple[str, Iterable[str]], None] = None, stream: bool = False) -> AudioData

### Parameters
#### Parameters
- **source** (AudioSource) - Required - The audio source to listen to.
- **timeout** (Union[float, None]) - Optional - Maximum seconds to wait for a phrase to start. If None, waits indefinitely.
- **phrase_time_limit** (Union[float, None]) - Optional - Maximum seconds for the phrase to last. If None, no limit.
- **snowboy_configuration** (Union[Tuple[str, Iterable[str]], None]) - Optional - Configuration for snowboy hotword detection.
- **stream** (bool) - Optional - If True, returns a stream of audio data instead of a single AudioData.

### Response
#### Success Response
- **AudioData** - The captured audio data.

```

--------------------------------

### Convert language model back to binary format

Source: https://github.com/uberi/speech_recognition/blob/master/reference/pocketsphinx.rst

Convert an ARPA language model back to binary format using SphinxBase's sphinx_lm_convert. Replace LANGUAGE_MODEL_FILE_GOES_HERE with the target file path.

```bash
sphinx_lm_convert -i language-model.lm -o LANGUAGE_MODEL_FILE_GOES_HERE
```

--------------------------------

### Recognizer()

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Creates a new Recognizer instance, which represents a collection of speech recognition settings and functionality.

```APIDOC
## Recognizer()

### Description
Creates a new Recognizer instance, which represents a collection of speech recognition settings and functionality.

### Constructor
`Recognizer() -> Recognizer`

### Usage Example
```python
import speech_recognition as sr
r = sr.Recognizer()
```
```

--------------------------------

### Prune language model with IRSTLM

Source: https://github.com/uberi/speech_recognition/blob/master/reference/pocketsphinx.rst

Prune a language model using IRSTLM's prune-lm with a threshold of 1e-8. Higher thresholds produce smaller files.

```bash
prune-lm --threshold=1e-8 t.lm pruned.lm
```

--------------------------------

### recognize_google_cloud(audio_data, credentials_json_path, **kwargs)

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Performs speech recognition on audio data using the Google Cloud Speech API. Requires a credentials JSON file path.

```APIDOC
## recognize_google_cloud(audio_data, credentials_json_path, **kwargs)

### Description
Performs speech recognition on `audio_data` (an `AudioData` instance) using the Google Cloud Speech API. Requires a credentials JSON file path.

### Method
recognize_google_cloud

### Endpoint
recognizer_instance.recognize_google_cloud

### Parameters
#### Path Parameters
- **audio_data** (AudioData) - Required - The audio data to recognize.

#### Query Parameters
- **credentials_json_path** (Union[str, None]) - Optional - Path to Google Cloud credentials JSON file.
- **kwargs** - Optional - Additional keyword arguments for the underlying API call.

### Response
#### Success Response (200)
- **result** (Union[str, Dict[str, Any]]) - Most likely transcription or raw API response as JSON dictionary.

### Error Handling
- Raises `speech_recognition.UnknownValueError` if speech is unintelligible.
- Raises `speech_recognition.RequestError` if recognition fails or credentials are invalid.
```

--------------------------------

### recognizer_instance.listen_in_background

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Spawns a background thread to continuously listen for phrases and invoke a callback with each captured AudioData. Use this for continuous, non-blocking speech recognition.

```APIDOC
## [METHOD] recognizer_instance.listen_in_background

### Description
Spawns a thread to repeatedly record phrases from `source` (an `AudioSource` instance) into an `AudioData` instance and call `callback` with that `AudioData` instance as soon as each phrase is detected. Returns a function object that, when called, requests that the background listener thread stop.

### Method
CALL

### Endpoint
recognizer_instance.listen_in_background(source: AudioSource, callback: Callable[[Recognizer, AudioData], Any]) -> Callable[bool, None]

### Parameters
#### Parameters
- **source** (AudioSource) - Required - The audio source to listen to.
- **callback** (Callable[[Recognizer, AudioData], Any]) - Required - A function that accepts two parameters: the recognizer instance and an AudioData instance. Called from a non-main thread.

### Response
#### Success Response
- **Callable[bool, None]** - A function that, when called, requests the background listener to stop. If called with a truthy `wait_for_stop`, it waits for the listener to stop before returning.

```

--------------------------------

### recognize_ibm(audio_data, username, password, language='en-US', show_all=False)

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Performs speech recognition on audio data using the IBM Speech to Text API. Requires IBM Speech to Text credentials (username and password). Returns the most likely transcription or the raw API response if show_all is true.

```APIDOC
## recognize_ibm(audio_data: AudioData, username: str, password: str, language: str = "en-US", show_all: bool = False) -> Union[str, Dict[str, Any]]

### Description
Performs speech recognition on `audio_data` (an `AudioData` instance), using the IBM Speech to Text API. The IBM Speech to Text username and password are specified by `username` and `password`, respectively. The recognition language is determined by `language`, an RFC5646 language tag with a dialect like `"en-US"` (US English) or `"zh-CN"` (Mandarin Chinese), defaulting to US English.

### Parameters
- **audio_data** (AudioData) - Required - The audio data to recognize.
- **username** (str) - Required - IBM Speech to Text username (form: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX).
- **password** (str) - Required - IBM Speech to Text password (mixed-case alphanumeric string).
- **language** (str) - Optional - RFC5646 language tag with dialect, default "en-US". Supported values are listed under the `model` parameter of the IBM audio recognition API documentation, in the form `LANGUAGE_BroadbandModel`.
- **show_all** (bool) - Optional - If false (default), returns the most likely transcription. If true, returns the raw API response as a JSON dictionary.

### Returns
- If `show_all` is false: the most likely transcription (str).
- If `show_all` is true: the raw API response as a JSON dictionary (Dict[str, Any]).

### Exceptions
- `speech_recognition.UnknownValueError` - If the speech is unintelligible.
- `speech_recognition.RequestError` - If the speech recognition operation failed, if the key isn't valid, or if there is no internet connection.
```

--------------------------------

### Split AudioData for OpenAI Whisper API

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Splits an AudioData instance into chunks of at most 24 MB using silence-aware splitting, then transcribes each chunk with the OpenAI Whisper API. Requires the 'audio-split' optional extra for silence_aware=True.

```python
import speech_recognition as sr

audio = sr.AudioData.from_file("large.wav")
r = sr.Recognizer()

# 24 MB target leaves a small buffer under Whisper's 25 MB request limit.
chunks = audio.split(max_bytes=24 * 1024 * 1024, silence_aware=True)
text = " ".join(r.recognize_openai(c, model="whisper-1") for c in chunks)
```

--------------------------------

### Microphone(device_index=None, sample_rate=16000, chunk_size=1024)

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Creates a new Microphone instance representing a physical microphone. It is a subclass of AudioSource and is a context manager for use with 'with' statements.

```APIDOC
## Microphone(device_index=None, sample_rate=16000, chunk_size=1024)

### Description
Creates a new `Microphone` instance, which represents a physical microphone on the computer. Subclass of `AudioSource`. This will throw an `AttributeError` if you don't have PyAudio (0.2.11 or later) installed.

### Constructor Parameters
- **device_index** (Union[int, None]) - Optional - The index of the audio device to use. If unspecified or `None`, the default microphone is used.
- **sample_rate** (int) - Optional - The sample rate in samples per second (Hertz). Default is 16000.
- **chunk_size** (int) - Optional - The number of samples per chunk. Default is 1024.

### Usage
Instances of this class are context managers, and are designed to be used with `with` statements:

```python
with Microphone() as source:    # open the microphone and start recording
    pass                        # do things here - `source` is the Microphone instance created above
                                # the microphone is automatically released at this point
```
```

--------------------------------

### recognizer_instance.record

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Records audio from an AudioSource into an AudioData instance. Use this to capture audio for later recognition.

```APIDOC
## [METHOD] recognizer_instance.record

### Description
Records up to `duration` seconds of audio from `source` (an `AudioSource` instance) starting at `offset` (or at the beginning if not specified) into an `AudioData` instance, which it returns. If `duration` is not specified, then it will record until there is no more audio input.

### Method
CALL

### Endpoint
recognizer_instance.record(source: AudioSource, duration: Union[float, None] = None, offset: Union[float, None] = None) -> AudioData

### Parameters
#### Parameters
- **source** (AudioSource) - Required - The audio source to record from.
- **duration** (Union[float, None]) - Optional - Maximum number of seconds to record. If not specified, records until no more audio input.
- **offset** (Union[float, None]) - Optional - Start recording at this offset (in seconds) from the beginning of the source. If not specified, starts at the beginning.

### Response
#### Success Response
- **AudioData** - The recorded audio data.

```

--------------------------------

### Convert language model to ARPA format

Source: https://github.com/uberi/speech_recognition/blob/master/reference/pocketsphinx.rst

Convert a language model file to ARPA format using SphinxBase's sphinx_lm_convert. Replace LANGUAGE_MODEL_FILE_GOES_HERE with the actual file path.

```bash
sphinx_lm_convert -i LANGUAGE_MODEL_FILE_GOES_HERE -o language-model.lm -ofmt arpa
```

--------------------------------

### recognize_google(audio_data, key, language, pfilter, show_all)

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Performs speech recognition on audio data using the Google Speech Recognition API. Supports language selection, profanity filtering, and optional API key.

```APIDOC
## recognize_google(audio_data, key, language, pfilter, show_all)

### Description
Performs speech recognition on `audio_data` (an `AudioData` instance) using the Google Speech Recognition API. Supports language selection, profanity filtering, and optional API key.

### Method
recognize_google

### Endpoint
recognizer_instance.recognize_google

### Parameters
#### Path Parameters
- **audio_data** (AudioData) - Required - The audio data to recognize.

#### Query Parameters
- **key** (Union[str, None]) - Optional - Google Speech Recognition API key. If not specified, uses a generic key that may be revoked at any time.
- **language** (str) - Optional - IETF language tag (e.g., "en-US") for recognition language. Defaults to "en-US".
- **pfilter** (Union[0, 1]) - Optional - Profanity filter level: 0 (no filter) or 1 (only first character shown, rest asterisks). Default is 0.
- **show_all** (bool) - Optional - If false (default), returns most likely transcription. If true, returns raw API response as JSON dictionary.

### Response
#### Success Response (200)
- **result** (Union[str, Dict[str, Any]]) - Most likely transcription (if show_all is false) or raw API response as JSON dictionary.

#### Response Example
{
  "transcription": "hello world"
}

### Error Handling
- Raises `speech_recognition.UnknownValueError` if speech is unintelligible.
- Raises `speech_recognition.RequestError` if recognition fails, key is invalid, or no internet connection.
```

--------------------------------

### Microphone.list_microphone_names()

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Returns a list of the names of all available microphones. The index of each name in the list corresponds to the device index for creating a Microphone instance.

```APIDOC
## Microphone.list_microphone_names()

### Description
Returns a list of the names of all available microphones. For microphones where the name can't be retrieved, the list entry contains `None` instead.

### Returns
- **List[str]** - A list of microphone names, where the index corresponds to the device index.

### Example
```python
m = None
for i, microphone_name in enumerate(Microphone.list_microphone_names()):
    if microphone_name == "HDA Intel HDMI: 0 (hw:0,3)":
        m = Microphone(device_index=i)
```
```

--------------------------------

### Microphone.list_working_microphones()

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Returns a dictionary mapping device indices to microphone names for microphones that are currently hearing sounds. Ensure your microphone is unmuted and make some noise to detect it as working.

```APIDOC
## Microphone.list_working_microphones()

### Description
Returns a dictionary mapping device indices to microphone names, for microphones that are currently hearing sounds. When using this function, ensure that your microphone is unmuted and make some noise at it to ensure it will be detected as working.

### Returns
- **Dict[int, str]** - A dictionary mapping device indices to microphone names.

### Example
```python
for device_index in Microphone.list_working_microphones():
    m = Microphone(device_index=device_index)
    break
else:
    print("No working microphones found!")
```
```

--------------------------------

### Convert Mandarin ARPA language model to Sphinx binary format

Source: https://github.com/uberi/speech_recognition/blob/master/reference/pocketsphinx.rst

Converts the pruned Mandarin language model from ARPA to Sphinx binary format using sphinx_lm_convert.

```bash
sphinx_lm_convert -i chinese.lm -o chinese.lm.bin
```

--------------------------------

### recognizer_instance.recognize_sphinx

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Performs speech recognition on audio data using the CMU Sphinx engine. Use this to convert audio to text.

```APIDOC
## [METHOD] recognizer_instance.recognize_sphinx

### Description
Performs speech recognition on audio data using the CMU Sphinx engine. Use this to convert audio to text.

### Method
CALL

### Endpoint
recognizer_instance.recognize_sphinx(audio_data: AudioData, language: str = "en-US", keyword_entries: Union[Iterable[Tuple[str, float]], None] = None, grammar: Union[str, None] = None, show_all: bool = False) -> Union[str, pocketsphinx.pocketsphinx.Decoder]

### Parameters
#### Parameters
- **audio_data** (AudioData) - Required - The audio data to recognize.
- **language** (str) - Optional - The language code (e.g., "en-US"). Default is "en-US".
- **keyword_entries** (Union[Iterable[Tuple[str, float]], None]) - Optional - A list of (keyword, sensitivity) tuples for keyword spotting.
- **grammar** (Union[str, None]) - Optional - Path to a grammar file.
- **show_all** (bool) - Optional - If True, returns the full decoder object instead of the recognized text.

### Response
#### Success Response
- **Union[str, pocketsphinx.pocketsphinx.Decoder]** - The recognized text (if `show_all` is False) or the decoder object (if `show_all` is True).

```

--------------------------------

### get_wav_data(convert_rate, convert_width)

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Returns a byte string representing the contents of a WAV file containing the audio represented by the AudioData instance. Optionally converts the sample width.

```APIDOC
## get_wav_data(convert_rate, convert_width)

### Description
Returns a byte string representing the contents of a WAV file containing the audio represented by the AudioData instance. If convert_width is specified and the audio samples are not convert_width bytes each, the resulting audio is converted to match.

### Method
`audiodata_instance.get_wav_data(convert_rate: Union[int, None] = None, convert_width: Union[int, None] = None) -> bytes`

### Parameters
- **convert_rate** (int, optional) - Optional - Target sample rate in Hz. If specified and different from the original, the audio is resampled.
- **convert_width** (int, optional) - Optional - Target sample width in bytes. If specified and different from the original, the audio is converted.

### Returns
- **bytes** - A byte string representing the contents of a WAV file.
```

--------------------------------

### split(max_bytes, silence_aware)

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Returns a list of AudioData chunks whose WAV-serialized size is at most max_bytes bytes each. This is intended for feeding oversized recordings to APIs that enforce strict upload limits.

```APIDOC
## split(max_bytes, silence_aware)

### Description
Returns a list of AudioData chunks whose WAV-serialized size (the output of `get_wav_data()`) is at most max_bytes bytes each. This is intended for feeding oversized recordings to APIs that enforce strict upload limits, such as OpenAI's Whisper transcription endpoint (25 MB per request).

### Method
`audiodata_instance.split(max_bytes: int, *, silence_aware: bool = False) -> list[AudioData]`

### Parameters
- **max_bytes** (int) - Required - Maximum size in bytes for each chunk.
- **silence_aware** (bool, optional) - Optional - If True, chunk boundaries are snapped to nearby silences via `librosa.effects.split`. Requires the `audio-split` optional extra. Defaults to False.

### Returns
- **list[AudioData]** - A list of AudioData chunks.

### Raises
- **ValueError** - If max_bytes is smaller than the WAV header overhead (44 bytes) plus one sample, or if `len(frame_data)` is not a multiple of `sample_width`.
- **SetupError** - If silence_aware is True and `librosa` and `numpy` are not importable or fail to initialize at runtime.

### Example
```python
import speech_recognition as sr

audio = sr.AudioData.from_file("large.wav")
r = sr.Recognizer()

# 24 MB target leaves a small buffer under Whisper's 25 MB request limit.
chunks = audio.split(max_bytes=24 * 1024 * 1024, silence_aware=True)
text = " ".join(r.recognize_openai(c, model="whisper-1") for c in chunks)
```
```

--------------------------------

### get_raw_data(convert_rate, convert_width)

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Returns a byte string representing the raw frame data for the audio represented by the AudioData instance. Optionally resamples or converts the sample width.

```APIDOC
## get_raw_data(convert_rate, convert_width)

### Description
Returns a byte string representing the raw frame data for the audio represented by the AudioData instance. If convert_rate is specified and the audio sample rate is not convert_rate Hz, the resulting audio is resampled to match. If convert_width is specified and the audio samples are not convert_width bytes each, the resulting audio is converted to match.

### Method
`audiodata_instance.get_raw_data(convert_rate: Union[int, None] = None, convert_width: Union[int, None] = None) -> bytes`

### Parameters
- **convert_rate** (int, optional) - Optional - Target sample rate in Hz. If specified and different from the original, the audio is resampled.
- **convert_width** (int, optional) - Optional - Target sample width in bytes. If specified and different from the original, the audio is converted.

### Returns
- **bytes** - A byte string representing the raw frame data. Writing these bytes directly to a file results in a valid RAW/PCM audio file.
```

--------------------------------

### AudioData(frame_data, sample_rate, sample_width)

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Creates a new AudioData instance representing mono audio data. The raw audio data is specified by frame_data, a sequence of bytes representing audio samples in PCM WAV format.

```APIDOC
## AudioData(frame_data, sample_rate, sample_width)

### Description
Creates a new AudioData instance representing mono audio data. The raw audio data is specified by frame_data, a sequence of bytes representing audio samples in PCM WAV format.

### Constructor
`AudioData(frame_data: bytes, sample_rate: int, sample_width: int) -> AudioData`

### Parameters
- **frame_data** (bytes) - Required - A sequence of bytes representing audio samples.
- **sample_rate** (int) - Required - The sample rate of the audio data in samples per second (Hertz).
- **sample_width** (int) - Required - The width of each sample in bytes.

### Returns
- **AudioData** - A new AudioData instance.

### Notes
Usually instances are obtained from `recognizer_instance.record` or `recognizer_instance.listen`, or in the callback for `recognizer_instance.listen_in_background`, rather than instantiating them directly.
```

--------------------------------

### Convert Mandarin DMP language model to ARPA format

Source: https://github.com/uberi/speech_recognition/blob/master/reference/pocketsphinx.rst

Converts the Mandarin language model from DMP to ARPA format using sphinx_lm_convert.

```bash
sphinx_lm_convert -i zh_broadcastnews_64000_utf8.DMP -o chinese.lm -ofmt arpa
```

--------------------------------

### Set energy threshold to 4000

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Sets the energy threshold to 4000 to avoid false positives from ambient noise. Useful when the microphone is sensitive or in louder rooms.

```python
import speech_recognition as sr
r = sr.Recognizer()
r.energy_threshold = 4000
# rest of your code goes here
```

--------------------------------

### get_flac_data

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Returns a byte string representing the contents of a FLAC file containing the audio represented by the AudioData instance. Note that 32-bit FLAC is not supported. If the audio data is 32-bit and convert_width is not specified, then the resulting FLAC will be a 24-bit FLAC. If convert_rate is specified and the audio sample rate is not convert_rate Hz, the resulting audio is resampled to match. If convert_width is specified and the audio samples are not convert_width bytes each, the resulting audio is converted to match.

```APIDOC
## get_flac_data

### Description
Returns a byte string representing the contents of a FLAC file containing the audio represented by the AudioData instance. Note that 32-bit FLAC is not supported. If the audio data is 32-bit and convert_width is not specified, then the resulting FLAC will be a 24-bit FLAC. If convert_rate is specified and the audio sample rate is not convert_rate Hz, the resulting audio is resampled to match. If convert_width is specified and the audio samples are not convert_width bytes each, the resulting audio is converted to match.

### Method
N/A (SDK method)

### Endpoint
N/A (SDK method)

### Parameters
#### Optional Parameters
- **convert_rate** (Union[int, None]) - Optional - If specified and the audio sample rate is not convert_rate Hz, the resulting audio is resampled to match.
- **convert_width** (Union[int, None]) - Optional - If specified and the audio samples are not convert_width bytes each, the resulting audio is converted to match.

### Request Example
N/A (SDK method)

### Response
#### Success Response
- **bytes** - Byte string representing the contents of a FLAC file containing the audio.

#### Response Example
N/A (SDK method)
```

--------------------------------

### Prune Mandarin language model with threshold

Source: https://github.com/uberi/speech_recognition/blob/master/reference/pocketsphinx.rst

Prunes the Mandarin language model with a threshold of 0.00000004 using prune-lm.

```bash
prune-lm --threshold=4e-8 chinese.lm chinese.lm
```

--------------------------------

### Convert French DMP language model to ARPA format

Source: https://github.com/uberi/speech_recognition/blob/master/reference/pocketsphinx.rst

Converts the French language model from the obsolete DMP format to ARPA format using sphinx_lm_convert.

```bash
sphinx_lm_convert -i fr.lm.gmp -o french.lm.bin
```

--------------------------------

### get_wav_data

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Returns a byte string representing the contents of a WAV file containing the audio represented by the AudioData instance. If convert_rate is specified and the audio sample rate is not convert_rate Hz, the resulting audio is resampled to match.

```APIDOC
## get_wav_data

### Description
Returns a byte string representing the contents of a WAV file containing the audio represented by the AudioData instance. If convert_rate is specified and the audio sample rate is not convert_rate Hz, the resulting audio is resampled to match.

### Method
N/A (SDK method)

### Endpoint
N/A (SDK method)

### Parameters
#### Optional Parameters
- **convert_rate** (Union[int, None]) - Optional - If specified and the audio sample rate is not convert_rate Hz, the resulting audio is resampled to match.
- **convert_width** (Union[int, None]) - Optional - If specified and the audio samples are not convert_width bytes each, the resulting audio is converted to match.

### Request Example
N/A (SDK method)

### Response
#### Success Response
- **bytes** - Byte string representing the contents of a WAV file containing the audio.

#### Response Example
N/A (SDK method)
```

--------------------------------

### Recognizer.dynamic_energy_adjustment_ratio

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

If the dynamic energy threshold setting is enabled, represents the ratio of the current energy threshold that is used to adjust the threshold. Can be changed.

```APIDOC
## Recognizer.dynamic_energy_adjustment_ratio

### Description
If the dynamic energy threshold setting is enabled, represents the ratio of the current energy threshold that is used to adjust the threshold. Can be changed.

### Property
`dynamic_energy_adjustment_ratio` (float) - The adjustment ratio. Default is 1.5.

### Usage Example
```python
import speech_recognition as sr
r = sr.Recognizer()
r.dynamic_energy_adjustment_ratio = 2.0
```
```

--------------------------------

### recognize_groq(audio_data, model='whisper-large-v3-turbo', **kwargs)

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Performs speech recognition using the Groq Whisper API. This is an autofunction reference to the Groq recognize function.

```APIDOC
## recognize_groq(audio_data: AudioData, model = "whisper-large-v3-turbo", **kwargs)

### Description
Performs speech recognition on `audio_data` using the Groq Whisper API. The `model` parameter specifies the model to use (default "whisper-large-v3-turbo"). Additional keyword arguments can be passed to the API.

### Parameters
- **audio_data** (AudioData) - Required - The audio data to recognize.
- **model** (str) - Optional - Groq Whisper model name, default "whisper-large-v3-turbo".
- **kwargs** - Optional - Additional keyword arguments for the API request.

### Returns
- The most likely transcription (str) or a dictionary if `show_all` is true (not specified here).
```

--------------------------------

### recognize_openai(audio_data, model='whisper-1', **kwargs)

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Performs speech recognition using the OpenAI Whisper API. This is an autofunction reference to the OpenAI recognize function.

```APIDOC
## recognize_openai(audio_data: AudioData, model = "whisper-1", **kwargs)

### Description
Performs speech recognition on `audio_data` using the OpenAI Whisper API. The `model` parameter specifies the model to use (default "whisper-1"). Additional keyword arguments can be passed to the API.

### Parameters
- **audio_data** (AudioData) - Required - The audio data to recognize.
- **model** (str) - Optional - OpenAI Whisper model name, default "whisper-1".
- **kwargs** - Optional - Additional keyword arguments for the API request.

### Returns
- The most likely transcription (str) or a dictionary if `show_all` is true (not specified here).
```

--------------------------------

### recognizer_instance.adjust_for_ambient_noise

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Adjusts the recognizer's energy threshold based on ambient noise from the source. Use this to calibrate the recognizer for the current environment.

```APIDOC
## [METHOD] recognizer_instance.adjust_for_ambient_noise

### Description
Adjusts the recognizer's energy threshold based on ambient noise from the source. Use this to calibrate the recognizer for the current environment.

### Method
CALL

### Endpoint
recognizer_instance.adjust_for_ambient_noise(source: AudioSource, duration: float = 1) -> None

### Parameters
#### Parameters
- **source** (AudioSource) - Required - The audio source to use for ambient noise measurement.
- **duration** (float) - Optional - The duration (in seconds) to listen for ambient noise. Default is 1.

### Response
#### Success Response
- None

```

--------------------------------

### recognize_cohere_api(audio_data, *, language, model='cohere-transcribe-03-2026')

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Performs speech recognition using the Cohere API. This is an autofunction reference to the Cohere recognize function.

```APIDOC
## recognize_cohere_api(audio_data: AudioData, *, language: str, model = "cohere-transcribe-03-2026")

### Description
Performs speech recognition on `audio_data` using the Cohere API. The `language` parameter is required and specifies the recognition language. The `model` parameter specifies the model to use (default "cohere-transcribe-03-2026").

### Parameters
- **audio_data** (AudioData) - Required - The audio data to recognize.
- **language** (str) - Required - The recognition language.
- **model** (str) - Optional - Cohere model name, default "cohere-transcribe-03-2026".

### Returns
- The most likely transcription (str) or a dictionary if `show_all` is true (not specified here).
```

--------------------------------

### get_aiff_data

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Returns a byte string representing the contents of an AIFF-C file containing the audio represented by the AudioData instance. If convert_width is specified and the audio samples are not convert_width bytes each, the resulting audio is converted to match. If convert_rate is specified and the audio sample rate is not convert_rate Hz, the resulting audio is resampled to match.

```APIDOC
## get_aiff_data

### Description
Returns a byte string representing the contents of an AIFF-C file containing the audio represented by the AudioData instance. If convert_width is specified and the audio samples are not convert_width bytes each, the resulting audio is converted to match. If convert_rate is specified and the audio sample rate is not convert_rate Hz, the resulting audio is resampled to match.

### Method
N/A (SDK method)

### Endpoint
N/A (SDK method)

### Parameters
#### Optional Parameters
- **convert_rate** (Union[int, None]) - Optional - If specified and the audio sample rate is not convert_rate Hz, the resulting audio is resampled to match.
- **convert_width** (Union[int, None]) - Optional - If specified and the audio samples are not convert_width bytes each, the resulting audio is converted to match.

### Request Example
N/A (SDK method)

### Response
#### Success Response
- **bytes** - Byte string representing the contents of an AIFF-C file containing the audio.

#### Response Example
N/A (SDK method)
```

--------------------------------

### recognize_vosk(audio_data, *, verbose=False)

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

Performs speech recognition using the Vosk recognizer. This is an autofunction reference to the Vosk recognize function.

```APIDOC
## recognize_vosk(audio_data: AudioData, *, verbose: bool = False) -> Union[str, Dict[str, str]]

### Description
Performs speech recognition on `audio_data` using the Vosk recognizer. The `verbose` parameter controls verbosity. Returns the most likely transcription or a dictionary if verbose is true.

### Parameters
- **audio_data** (AudioData) - Required - The audio data to recognize.
- **verbose** (bool) - Optional - If true, returns a dictionary with additional information.

### Returns
- If `verbose` is false: the most likely transcription (str).
- If `verbose` is true: a dictionary (Dict[str, str]).
```

--------------------------------

### Recognizer.dynamic_energy_adjustment_damping

Source: https://github.com/uberi/speech_recognition/blob/master/reference/library-reference.rst

If the dynamic energy threshold setting is enabled, represents approximately the fraction of the current energy threshold that is retained after one second of dynamic threshold adjustment. Can be changed (not recommended).

```APIDOC
## Recognizer.dynamic_energy_adjustment_damping

### Description
If the dynamic energy threshold setting is enabled, represents approximately the fraction of the current energy threshold that is retained after one second of dynamic threshold adjustment. Can be changed (not recommended).

### Property
`dynamic_energy_adjustment_damping` (float) - The damping factor. Default is 0.15. Should be between 0 and 1.

### Usage Example
```python
import speech_recognition as sr
r = sr.Recognizer()
r.dynamic_energy_adjustment_damping = 0.2
```
```
Tokens:
Raw