Install & Compatibility
Where this runs
tested against v0.3.45 · 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
py 3.10
✕ build_error
4/8 runs
py 3.11
✕ build_error
4/8 runs
py 3.12
✕ build_error
4/8 runs
py 3.13
✕ build_error
4/8 runs
py 3.9
✕ build_error
4/8 runs
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Model
✓ from vosk import Model
KaldiRecognizer
✓ from vosk import KaldiRecognizer
Vosk imports as vosk.*
✓ import vosk
✗ from vosk_api import Model
The common import pattern is `from vosk import Model, KaldiRecognizer` or `import vosk`. Direct import from `vosk_api` is incorrect.
This quickstart demonstrates how to set up Vosk for transcribing a WAV audio file. It involves downloading a pre-trained language model, loading it into a `Model` object, initializing a `KaldiRecognizer` with the model and the audio's sample rate, and then feeding audio data in chunks for recognition. Ensure your audio file is 16kHz, 16-bit PCM, mono WAV format.
import os
import wave
from vosk import Model, KaldiRecognizer
# --- IMPORTANT: Download a Vosk model ---
# 1. Visit https://alphacephei.com/vosk/models
# 2. Download a small model (e.g., vosk-model-small-en-us-0.22.zip)
# 3. Unzip it into a directory. For this example, let's assume it's in a 'model' folder
# adjacent to your script, e.g., 'your_project/model/vosk-model-small-en-us-0.22'
MODEL_PATH = "model/vosk-model-small-en-us-0.22" # Adjust this path to your downloaded model
AUDIO_FILE = "test.wav" # Ensure you have a WAV file (16kHz, 16-bit PCM, mono)
if not os.path.exists(MODEL_PATH):
print(f"Error: Vosk model not found at {MODEL_PATH}")
print("Please download a model from https://alphacephei.com/vosk/models and unzip it into the specified path.")
exit(1)
# Load the Vosk model
model = Model(MODEL_PATH)
# Initialize the KaldiRecognizer with the model and the audio sample rate
# The sample rate MUST match the audio file's sample rate (usually 16000 for Vosk models)
rec = KaldiRecognizer(model, 16000)
# Open the audio file
try:
wf = wave.open(AUDIO_FILE, "rb")
if wf.getnchannels() != 1 or wf.getsampwidth() != 2 or wf.getcomptype() != "NONE":
print("Audio file must be MONO, 16-bit PCM, uncompressed WAV.")
print("Consider using ffmpeg to convert: ffmpeg -i input.mp3 -ar 16000 -ac 1 -acodec pcm_s16le output.wav")
exit(1)
except wave.Error as e:
print(f"Error opening audio file {AUDIO_FILE}: {e}")
print("Please ensure the audio file exists and is a valid WAV.")
exit(1)
# Process audio data in chunks
print("Transcribing...")
while True:
data = wf.readframes(4000) # Read 4000 frames (approx. 0.25 seconds for 16kHz audio)
if len(data) == 0:
break
if rec.AcceptWaveform(data):
result = rec.Result()
print(result)
# Get final result for any remaining audio
final_result = rec.FinalResult()
print(final_result)
print("Transcription complete.")
Debug
Known issues
breakingVosk version 0.3.30 introduced an API change regarding word times, making them optional. Code relying on previous implicit behavior might need adjustment.fixReview calls related to word timing extraction and adjust your code to handle `SetWords(True)` explicitly if detailed word timings are required, as default behavior may have changed.
affects: 0.3.30 and later
gotchaIncorrect audio format (e.g., stereo, wrong sample rate, compressed) is a common cause of poor recognition or the `Failed to process waveform` error. Vosk models typically expect mono, 16-bit PCM, uncompressed WAV audio, usually at 16kHz sample rate.fixEnsure your audio input (file or microphone stream) matches the model's expected format (e.g., 16kHz sample rate, 16-bit PCM, mono). Use tools like FFmpeg for conversion if necessary: `ffmpeg -i input.mp3 -ar 16000 -ac 1 -acodec pcm_s16le output.wav`. The sample rate passed to `KaldiRecognizer` MUST match the audio's actual sample rate.
affects: All versions
gotchaModel files must be downloaded separately and their path correctly specified. Using relative paths can lead to errors if the script's execution directory changes, or if `model_name` argument is used incorrectly.fixAlways download and unzip a Vosk model from the official website (alphacephei.com/vosk/models). Provide the absolute path to the unzipped model directory when initializing `vosk.Model()`. If using `model_name`, Vosk might look in a cache directory; for custom paths, pass the full folder path directly to `Model()`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'vosk'
The Vosk library is not installed in the currently active Python environment, or there are multiple Python installations causing conflicts.
fixEnsure `vosk` is installed in your active Python environment: `pip install vosk`. If you have multiple Python versions, verify `pip show vosk` points to the correct installation. Using virtual environments (`venv` or `conda`) is highly recommended to isolate dependencies.
ERROR (VoskAPI:Model():model.cc:122) Folder 'model' does not contain model files. Make sure you specified the model path properly in Model constructor. Exception: Failed to create a model.
The `vosk.Model()` constructor could not find the necessary model files in the specified directory. This often happens due to incorrect path, unzipped folder structure, or an incomplete model download.
fixVerify that the path provided to `vosk.Model()` points directly to the *unzipped* model directory (e.g., `vosk-model-en-us-small-0.22`), not the zip file itself. Ensure all model subdirectories and files are present within this path. Use an absolute path for robustness.
Exception: Failed to process waveform
The audio data being fed to `recognizer.AcceptWaveform()` does not match the expected format or sample rate of the loaded Vosk model. This is commonly due to a mismatch in sample rates between the audio source and the `KaldiRecognizer` initialization.
fixCheck the sample rate of your audio file/stream and ensure it matches the `sample_rate` argument provided to `vosk.KaldiRecognizer()`. Additionally, confirm the audio is mono, 16-bit PCM, and uncompressed WAV. Convert the audio if necessary using `ffmpeg`.
{ "text" : "" } (Vosk returns empty transcription)
This usually indicates that Vosk is not detecting any speech or is unable to process the audio effectively. Common causes include incorrect audio format, extremely low volume, a model not suited for the language or accent, or an incorrect sample rate.
fixDouble-check the audio format (mono, 16-bit PCM, 16kHz WAV is standard) and ensure the `KaldiRecognizer` is initialized with the correct sample rate. Verify the audio actually contains speech and is not too quiet. Try a different Vosk model for the target language. Ensure you are calling `rec.FinalResult()` at the end of processing to retrieve any pending transcription.
Upgrade
Version history
0.3.45latest on PyPI · released Dec 14, 2022
Audit
Dependencies
PythonrequiredVosk requires Python 3.x.
PyAudiooptionalNeeded for real-time audio input from a microphone. May require system-level dependencies (e.g., PortAudio).
FFmpegoptionalUseful for converting audio files to the required format (16kHz, 16-bit PCM, mono WAV) before processing with Vosk.