Install & Compatibility
Where this runs
tested against v? · pip install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
build_error
glibcpy 3.10–3.940 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
VoiceEncoder
✓ from resemblyzer import VoiceEncoder
preprocess_wav
✓ from resemblyzer import preprocess_wav
This quickstart demonstrates how to initialize the VoiceEncoder, preprocess an audio waveform (generating a dummy one for convenience), and extract a speaker embedding. Due to the library's age, strict PyTorch version compatibility (<=1.4.0) is critical for successful execution, especially on CUDA-enabled systems.
import numpy as np
import soundfile as sf
import os
from resemblyzer import VoiceEncoder, preprocess_wav
# Note: Resemblyzer (v0.1.4) was developed with PyTorch <= 1.4.0.
# Installing a compatible PyTorch version (e.g., pip install torch==1.4.0)
# is crucial for avoiding runtime errors, especially on GPU.
# Create a dummy WAV file for demonstration if it doesn't exist
test_wav_path = "resemblyzer_test_audio.wav"
if not os.path.exists(test_wav_path):
# Generate a dummy 5-second 16kHz sine wave
duration = 5 # seconds
sample_rate = 16000 # Hz
frequency = 440 # Hz (A4 note)
t = np.linspace(0, duration, int(sample_rate * duration), endpoint=False)
dummy_audio = 0.5 * np.sin(2 * np.pi * frequency * t)
sf.write(test_wav_path, dummy_audio.astype(np.float32), sample_rate)
print(f"Created dummy audio file: {test_wav_path}")
# Load the pre-trained encoder (downloads if not cached)
print("Loading VoiceEncoder... (first run may download model)")
encoder = VoiceEncoder.from_pretrained()
# Load and preprocess the dummy audio
wav, sr = sf.read(test_wav_path)
# Resemblyzer expects 16kHz audio. If your audio is different,
# you would need to resample it, e.g., using librosa.
# For this dummy, we ensured it's 16kHz.
if sr != 16000:
print(f"Warning: Audio sample rate is {sr}Hz, but Resemblyzer expects 16kHz. Resampling would be needed.")
# Example resampling (requires librosa):
# import librosa
# wav = librosa.resample(wav, orig_sr=sr, target_sr=16000)
clean_wav = preprocess_wav(wav)
# Encode the voice embedding
print("Encoding voice...")
embed = encoder.embed_utterance(clean_wav)
print(f"Generated embedding with shape: {embed.shape}")
print(f"First 5 elements of embedding: {embed[:5]}")
# Clean up dummy file
if os.path.exists(test_wav_path):
os.remove(test_wav_path)
print(f"Removed dummy audio file: {test_wav_path}")
Debug
Known issues
breakingThe library's `requirements.txt` and underlying code were designed for PyTorch versions `<=1.4.0`. Installing with newer PyTorch versions (e.g., 2.x) will almost certainly lead to runtime errors or incorrect behavior due to API changes.fixExplicitly install a compatible PyTorch version, e.g., `pip install torch==1.4.0`. For CUDA, ensure you select the PyTorch version compatible with your CUDA toolkit version.
affects: All versions up to 0.1.4
gotchaThe `soundfile` dependency, used for audio I/O, often requires the `libsndfile` package to be installed at the operating system level (e.g., via `apt-get`, `brew`, or `yum`). Without this system library, `soundfile` may fail to install or function correctly.fixInstall `libsndfile` using your system's package manager. For Debian/Ubuntu: `sudo apt-get install libsndfile1`. For macOS: `brew install libsndfile`.
affects: All versions up to 0.1.4
gotchaThe `VoiceEncoder.from_pretrained()` method downloads a pre-trained model (`encoder.pt`) from a specific URL. If this URL becomes unavailable or the hosting server is down, the model download will fail, preventing the encoder from being initialized.fixEnsure you have a stable internet connection. If the issue persists, you might need to manually download `encoder.pt` from the Resemblyzer GitHub repository (e.g., `github.com/resemble-ai/Resemblyzer/blob/master/resemblyzer/saved_models/encoder.pt`) and load it locally using `VoiceEncoder('path/to/encoder.pt')`. affects: All versions up to 0.1.4
gotchaThe `embed_utterance` method will raise a `NotImplementedError` if the input audio segment is too short, as the model has a minimum receptive field length it requires to produce an embedding.fixEnsure your audio inputs are sufficiently long, typically at least 1.6 seconds, before passing them to `encoder.embed_utterance()`.
affects: All versions up to 0.1.4
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'soundfile'
The `soundfile` Python package is not installed, or its underlying system dependency (`libsndfile`) is missing.
fixRun `pip install soundfile` and ensure `libsndfile` is installed on your operating system (e.g., `sudo apt-get install libsndfile1`).
RuntimeError: CUDA error: device-side assert triggered
This usually indicates a severe incompatibility between the installed PyTorch version and the `resemblyzer` library, or an issue with your GPU setup. `resemblyzer` is tied to older PyTorch versions.
fixVerify that you have PyTorch version `1.4.0` installed (`pip show torch`). If not, uninstall your current PyTorch and install `torch==1.4.0` (or `torch==1.4.0+cuXXX` for CUDA, where XXX matches your CUDA version).
NotImplementedError: The input length must be at least the model's receptive field length (...) but you provided an input of only (...) frames.
The audio segment provided for embedding is too short for the Resemblyzer model to process.
fixEnsure the audio segment you are passing to `encoder.embed_utterance()` is at least the minimum required length (typically around 1.6 seconds or more). You may need to concatenate shorter segments or process longer audio clips.
ConnectionError: HTTPSConnectionPool(host='www.dropbox.com', port=443): Max retries exceeded with url: /s/...', 'name': 'encoder.pt'
The pre-trained model download from the specified URL (often Dropbox) failed due to network issues, server unavailability, or rate limiting.
fixCheck your internet connection and try again. If the problem persists, the download link might be broken. In that case, manually download the `encoder.pt` file from the Resemblyzer GitHub repository and load it locally: `encoder = VoiceEncoder('/path/to/downloaded/encoder.pt')`. Upgrade
Version history
0.1.4latest on PyPI · released Oct 12, 2023
Audit
Dependencies
torchrequiredDeep learning backend; specific version (<=1.4.0) highly recommended.
numpyrequiredNumerical operations and array handling.
soundfilerequiredReading and writing audio files. Requires system-level 'libsndfile'.
librosarequiredAudio analysis functions, particularly for resampling if needed.
scipyrequiredScientific computing, used by other dependencies.