Guide · Open source

How to use pyannote-audio: install, run and read the output

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

pyannote.audio is an open-source Python toolkit that splits a recording into segments and labels which speaker is talking at each point, a task called speaker diarization. It is built on PyTorch and ships with pretrained pipelines you can run on your own audio. This guide shows you the setup steps, a working code sample, how to read the output and where the toolkit fits best.

pyannotepyannote/pyannote-audio · ★ 10.8k · MIT Install options & downloads

Quick start

1Install ffmpeg. Make sure ffmpeg is installed, since the torchcodec audio decoding library needs it.
2Install the package. Run uv add pyannote.audio, or pip install pyannote.audio if you use pip.
3Accept model conditions. Open the pyannote/speaker-diarization-community-1 page on Hugging Face and accept its user conditions.
4Create an access token. Create a Hugging Face access token at hf.co/settings/tokens.
5Run the pipeline. Load the pipeline with your token and call it on an audio file such as audio.wav.
6Read the speaker turns. Print each turn's start and stop times and its speaker label.

What pyannote.audio does

pyannote.audio answers the question 'who spoke when' for a recording. It is a speaker diarization toolkit, so its output is a list of time segments, each tagged with a speaker label such as SPEAKER_00 or speaker_0.

The toolkit is built on PyTorch and comes with pretrained models and pipelines. You can also fine-tune them on your own data for better results on your audio.

Speaker diarization: splitting audio into segments and labeling the speaker of each segment
Pretrained models and pipelines hosted on the Hugging Face model hub
Python-first API
Multi-GPU training with pytorch-lightning, according to the README

What you need before you install

Check these prerequisites first. The README lists Python, ffmpeg, a Hugging Face account with an access token, and either uv or pip. ffmpeg is needed by the torchcodec audio decoding library.

Python installed on your machine
ffmpeg installed (the README links to ffmpeg.org)
A Hugging Face account
A Hugging Face access token created at hf.co/settings/tokens
uv or pip available to install the package

Install pyannote.audio with uv or pip

The README recommends uv. If you use pip, the command is different. Run one of the two install commands from your project environment.

With uv (recommended): uv add pyannote.audio
With pip: pip install pyannote.audio

uv add pyannote.audio
# or
pip install pyannote.audio

Get access to the pretrained pipeline

The pretrained community-1 pipeline needs two things before it will load. First, open the pyannote/speaker-diarization-community-1 page on Hugging Face and accept its user conditions. Second, create a Hugging Face access token at hf.co/settings/tokens. You will pass this token into the code.

Keep the token private. The README's example uses a placeholder string, HUGGINGFACE_ACCESS_TOKEN, which you replace with your own token.

Accept the user conditions for pyannote/speaker-diarization-community-1
Create a token at hf.co/settings/tokens
Replace HUGGINGFACE_ACCESS_TOKEN in the code with your token

Run speaker diarization on an audio file

The README's example loads the pretrained pipeline, optionally moves it to a GPU, and runs it on audio.wav. The progress hook is optional. According to the README, processing runs locally in this mode. The code uses torch.device("cuda"), so the GPU step only applies when a CUDA GPU is available.

Load the pipeline with Pipeline.from_pretrained and your token
Call pipeline.to(torch.device("cuda")) to use a GPU when available
Run the pipeline on your file and loop over the speaker turns

import torch
from pyannote.audio import Pipeline
from pyannote.audio.pipelines.utils.hook import ProgressHook

# Community-1 open-source speaker diarization pipeline
pipeline = Pipeline.from_pretrained(
    "pyannote/speaker-diarization-community-1", token="HUGGINGFACE_ACCESS_TOKEN"
)

# send pipeline to GPU (when available)
pipeline.to(torch.device("cuda"))

# apply pretrained pipeline (with optional progress hook)
with ProgressHook() as hook:
    output = pipeline("audio.wav", hook=hook)  # runs locally

# print the result
for turn, speaker in output.speaker_diarization:
    print(f"start={turn.start:.1f}s stop={turn.end:.1f}s speaker_{speaker}")

Read the output

Each line of output gives a start time, a stop time and a speaker label. Times are in seconds. The README's sample output shows lines such as start=0.2s stop=1.5s speaker_0, followed by a turn for speaker_1, and so on. The same speaker label appears again when that speaker returns to talk.

The labels are generic. The toolkit tells you which turns belong to the same speaker, not who that speaker is by name. Matching names to labels is a step you do yourself.

start and stop give the segment boundaries in seconds
speaker_0, speaker_1 and so on are anonymous labels
Turns from the same label belong to the same speaker

Use the hosted pyannoteAI option instead

The README also describes precision-2, a premium speaker diarization service run on pyannoteAI servers. To use it, create an API key at dashboard.pyannote.ai. The README says new users get free credits. The example loads the pipeline with a PYANNOTEAI_API_KEY token and runs it without the local GPU step. Its output uses labels such as SPEAKER_00.

The README says this is an optional premium option, so the open-source community-1 pipeline does not depend on it.

Create an API key at dashboard.pyannote.ai
Load pyannote/speaker-diarization-precision-2 with your key
Audio is processed on pyannoteAI servers, not locally

from pyannote.audio import Pipeline

# Precision-2 premium speaker diarization service
pipeline = Pipeline.from_pretrained(
    "pyannote/speaker-diarization-precision-2", token="PYANNOTEAI_API_KEY"
)

output = pipeline("audio.wav")  # runs on pyannoteAI servers

Control telemetry if you prefer not to send usage data

The README describes an optional telemetry feature that sends anonymous usage metrics to the pyannote team. It says it does not track information that could identify the user. You can turn it off with an environment variable. Setting PYANNOTE_METRICS_ENABLED to 0 disables metrics, and 1 enables them.

Environment variable: PYANNOTE_METRICS_ENABLED
Per-session control: set_telemetry_metrics(False) from pyannote.audio.telemetry
Global settings are also described in the README

# disable metrics
export PYANNOTE_METRICS_ENABLED=0

What people use it for

Labeling who spoke when in a recorded meeting, as a starting point for transcripts
Splitting an interview recording into speaker turns for review
Comparing or fine-tuning speaker diarization models as a researcher
Adding speaker separation to an existing Python audio workflow

Frequently asked questions

Is pyannote-audio free to use?

pyannote.audio is released under the MIT licence, according to the project listing. The pretrained community-1 pipeline still requires you to accept its user conditions on Hugging Face and use an access token. The README also describes a paid premium service, pyannoteAI, as optional.

What do I need to install pyannote-audio?

You need Python, ffmpeg, a Hugging Face account and access token, and either uv or pip. Install the package with uv add pyannote.audio or pip install pyannote.audio. The README says ffmpeg is needed by the torchcodec audio decoding library.

Why do I need a Hugging Face token?

The pretrained pipelines are loaded from the Hugging Face model hub, and the community-1 pipeline requires you to accept its user conditions and pass an access token. You create the token at hf.co/settings/tokens. The README's code sample includes the token as a parameter.

Does pyannote-audio need a GPU?

The README's example moves the pipeline to a CUDA GPU when one is available, and the sample sends the pipeline to torch.device("cuda"). The README does not state a minimum hardware requirement, so check the project page for details before you commit to a setup.

Can I use pyannote-audio without writing code?

No. The README only shows Python code samples, so it is not a no-code app. If you need a graphical tool, pick a different product.

What are alternatives to pyannote-audio?

The listing names NVIDIA NeMo, WhisperX and SpeechBrain as comparable projects. The README itself does not compare them in detail, so test each one on your own recordings before choosing.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

pyannote.audio suits Python developers, researchers and teams who can run PyTorch code and want speaker diarization they control. It is a poor fit for anyone who needs a no-code app or has no Python experience, because setup involves ffmpeg, a package install and a Hugging Face token. Pick a different tool if you need a graphical interface.

Install options & downloads