Registry / ai-ml / pyannote-audio

pyannote-audio

JSON →
library4.0.7pypypiunverified

pyannote.audio is a state-of-the-art open-source toolkit for speaker diarization. It provides pre-trained deep learning models and pipelines for tasks like speaker recognition, voice activity detection, and speaker change detection. Currently at version 4.0.4, it actively integrates with the Hugging Face Hub for model distribution and offers robust audio processing capabilities. Releases are frequent for bug fixes and minor improvements, with major versions aligning with significant API or model architecture updates.

pip install pyannote.audio
INSTALL
IMPORT
SIG · PYANNOTE-AUDIO
P
pyannote-audio
ai-mlpythonv4.0.7
Install
Import
Disk
Pass rate
0/ 10
Env Coverage0 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.915 runs
timeout
glibc
py 3.103.915 runs
timeout
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Pipeline
from pyannote.audio import Pipeline
from pyannote.audio.core.pipeline import Pipeline
The primary Pipeline class is directly available at the top-level `pyannote.audio` package since v2.x. Accessing it from internal modules like `pyannote.audio.core.pipeline` is discouraged and might break in future versions.
Model
from pyannote.audio import Model
For loading individual models directly, e.g., for embedding or Voice Activity Detection.
Annotation
from pyannote.core import Annotation
The core data structure for storing diarization results is part of the `pyannote.core` library.
Segment
from pyannote.core import Segment
Used for representing time segments in annotations and other audio processing tasks, also part of `pyannote.core`.

This quickstart demonstrates how to set up `pyannote.audio`, authenticate with the Hugging Face Hub, and run a speaker diarization pipeline on a dummy audio file. It highlights the critical step of providing an authentication token for model access, a common requirement for `pyannote.audio` models since version 4.0.

import os import torchaudio import torch import numpy as np import tempfile import shutil # 1. Create a dummy audio file for demonstration duration_seconds = 5 sample_rate = 16000 t = np.linspace(0, duration_seconds, int(sample_rate * duration_seconds), endpoint=False) audio_data = 0.5 * np.sin(2 * np.pi * 440 * t).astype(np.float32) temp_dir = tempfile.mkdtemp() dummy_audio_path = os.path.join(temp_dir, "dummy_audio.wav") torchaudio.save(dummy_audio_path, torch.from_numpy(audio_data).unsqueeze(0), sample_rate) # 2. Authenticate with Hugging Face Hub # Get your Hugging Face token from https://huggingface.co/settings/tokens # and set it as an environment variable `HF_TOKEN` or replace the placeholder. hf_token = os.environ.get("HF_TOKEN", "hf_YOUR_HUGGING_FACE_TOKEN_HERE") if hf_token == "hf_YOUR_HUGGING_FACE_TOKEN_HERE": print("WARNING: Please obtain a Hugging Face token from https://huggingface.co/settings/tokens ") print("and set the HF_TOKEN environment variable or replace the placeholder in the code.") print("Continuing with placeholder token; pipeline initialization might fail without proper authentication.") # 3. Import and initialize the Pyannote.audio Pipeline from pyannote.audio import Pipeline pipeline = Pipeline("pyannote/speaker-diarization-3.1", use_auth_token=hf_token) # 4. Prepare the audio input demo_file = {"uri": "dummy_conversation", "audio": dummy_audio_path} # 5. Run the speaker diarization di_result = pipeline(demo_file) # 6. Print the diarization result print("\nDiarization Result:") for turn, _, speaker in di_result.itertracks(yield_label=True): print(f"start={turn.start:.1f}s stop={turn.end:.1f}s speaker={speaker}") # 7. Clean up the dummy audio file shutil.rmtree(temp_dir) print(f"\nCleaned up temporary audio directory: {temp_dir}")
Debug
Known issues
breakingAs of `pyannote.audio` v4.x, all pre-trained models hosted on the Hugging Face Hub require an authentication token to be downloaded. This is a significant change from v3.x, where models could be downloaded without explicit authentication.
fix
Obtain a Hugging Face user access token (read role is sufficient) from `https://huggingface.co/settings/tokens`. Pass it via the `use_auth_token` argument to `Pipeline` or `Model` constructors, or log in using `huggingface-cli login`.
affects: >=4.0.0
gotchaGPU acceleration with PyTorch requires a specific `torch` installation matching your CUDA version. `pyannote.audio` itself does not install GPU-enabled `torch` by default, leading to CPU-only inference if not correctly set up.
fix
Manually install the correct `torch` version for your CUDA toolkit (e.g., `pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121` for CUDA 12.1) *before* installing `pyannote.audio`.
affects: All
gotchaInput audio files should ideally be mono, 16kHz sample rate, and in a commonly supported format (e.g., WAV). Issues may arise with uncommon codecs, multichannel audio, or significantly different sample rates, potentially leading to errors or suboptimal performance.
fix
Pre-process audio to mono, 16kHz before passing to the pipeline. `pyannote.audio` uses `torchaudio` for loading, which handles resampling and channel reduction internally but explicit pre-processing ensures consistency.
affects: All
gotchaModel versions (e.g., `pyannote/speaker-diarization-3.1` vs `pyannote/speaker-diarization@main`) can have different performance characteristics, bug fixes, or even breaking changes. Relying on `@main` can lead to unexpected behavior.
fix
Always pin to a specific model version (e.g., `"pyannote/speaker-diarization-3.1"`) when instantiating pipelines in production or for reproducible research. Check the Hugging Face model page for available versions.
affects: All
gotchaFor CPU-only inference, the default PyTorch backend can be significantly slower than optimized runtimes like ONNX. This impacts processing time for long audio files or batch processing.
fix
Install `pyannote.audio` with the ONNX extra: `pip install pyannote.audio[onnx]`. The pipeline will automatically try to use ONNX runtime if available and compatible.
affects: All
Errors
Common errors & fixes
TypeError: Pipeline.from_pretrained() got an unexpected keyword argument 'use_auth_token'
The `use_auth_token` parameter for authenticating with Hugging Face Hub models has been deprecated in recent versions of `pyannote.audio` (and `huggingface_hub`) and replaced with `token`.
fix
Replace `use_auth_token` with `token` and ensure you are passing a valid Hugging Face access token. Also, make sure you have accepted the user conditions for the specific `pyannote.audio` model on the Hugging Face Hub.
AttributeError: module 'torchaudio' has no attribute 'set_audio_backend'
This error occurs when an older version of `pyannote.audio` (e.g., 3.1.0) tries to call `torchaudio.set_audio_backend('soundfile')`, but this function has been removed in `torchaudio` versions 2.2 and above.
fix
Upgrade `pyannote.audio` to version 4.x or higher, which no longer uses `torchaudio.set_audio_backend` and instead relies on FFmpeg via `torchcodec`. Also, ensure your NumPy version is compatible (>=2.3).
'Could not load audio' Error
This error typically indicates that `pyannote.audio` is unable to access or process the provided audio file. Common reasons include an invalid, indirect, or inaccessible audio file URL, incorrect file permissions, an expired temporary URL, or the file exceeding size limits.
ModuleNotFoundError: No module named 'pyannote.core'
This error usually means that core components of the `pyannote` library, such as `pyannote.core` or `pyannote.audio.pipelines`, are not properly installed or accessible within your Python environment, often due to an incomplete or incorrect installation, or an outdated `pyannote.audio` version incompatible with other installed dependencies.
Segmentation Fault
Segmentation faults with `pyannote.audio` are often complex, stemming from underlying issues with `torch`, `torchaudio`, FFmpeg, or other low-level dependencies, especially in specific environments like Docker containers or on certain hardware (e.g., Raspberry Pi), indicating memory access violations.
Upgrade
Version history
4.0.7latest on PyPI · released Jun 30, 2026
Audit
Dependencies
torchrequiredDeep learning framework for model inference.
huggingface_hubrequiredRequired for downloading and authenticating pre-trained models from Hugging Face Hub.
onnxruntimeoptionalOptional backend for faster CPU inference.
Agent activity
97 hits · last 30 days
node
88
OpenAI (training)
1
Resources
pyannote-audio — pip install pyannote-audio · libregistry