pywhispercpp

1.4.1 verified Sat May 09 auth: no python

Python bindings for whisper.cpp, providing fast and easy-to-use speech-to-text with support for various backends (CPU, CUDA, Vulkan, OpenVINO, CoreML). Current version 1.4.1, active development with monthly releases.

pip install pywhispercpp

Common errors

error Segmentation fault (core dumped) when creating Model ↓

cause model_path was passed as bytes in older versions, or model file is missing/corrupt.

fix

Use a string path: Model('ggml-base.en.bin'). Ensure the model file exists and is the correct format.

error ImportError: cannot import name 'Model' from 'whispercpp' ↓

cause Trying to import from the wrong module name.

fix

Install pywhispercpp and use: from pywhispercpp import Model

error RuntimeError: whisper.cpp: failed to load model ↓

cause Model file path incorrect or model not found.

fix

Download the model first (e.g., from Hugging Face) and provide the correct path.

Warnings

breaking In v1.1.3, the model path must be a string (not bytes) to avoid segmentation faults. ↓

fix Ensure model_path is a str in newer versions.

gotcha GIL is released during inference; do not call model methods from multiple threads without proper synchronization. ↓

fix Use locks if calling from multiple threads.

deprecated The old import path `import whispercpp` is deprecated and may be removed in future versions. ↓

fix Use `from pywhispercpp import Model` instead.

Imports

Model
```
from pywhispercpp import Model
```
Segment
```
from pywhispercpp import Segment
```

Quickstart

Basic transcription example.

from pywhispercpp import Model

model = Model('ggml-base.en.bin', n_threads=4)
segments = model.transcribe('audio.wav')
for segment in segments:
    print(f"[{segment.t0/100:.2f}s -> {segment.t1/100:.2f}s] {segment.text}")