Registry / data / pyannote-database

pyannote-database

JSON →
library6.1.1pypypi✓ verified 26d ago

pyannote.database is an open-source Python library that provides a common interface for reproducible experimental protocols across various multimedia databases (audio, video, text). It is part of the broader pyannote ecosystem. Currently at version 6.1.1, the library maintains an active development pace with several releases annually, including significant major version updates that introduce breaking changes.

pip install pyannote-database
INSTALL
IMPORT
SIG · PYANNOTE-DATABASE
P
pyannote-database
datapythonv6.1.1
Install
9.3s avg
Import
1206ms
Disk
198MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v6.1.1 · 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
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 1.216s · 167.8MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 9.3s · import 1.196s · 161MB
198MB installed
● package 198MB
Code
Verified usage

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

registry
from pyannote.database import registry
The primary interface for loading database configurations and accessing protocols since v5.0.0.
FileFinder
from pyannote.database import FileFinder
A common preprocessor used to automatically locate media files associated with a URI within a protocol.
ProtocolFile
from pyannote.database import ProtocolFile
Represents a multimedia resource with metadata, typically encountered when iterating over a protocol subset.
get_protocol
protocol = registry.get_protocol('MyDatabase.MyProtocol')
from pyannote.database import get_protocol; protocol = get_protocol('MyDatabase.MyProtocol')
The `get_protocol` function was removed in v5.0.0 and replaced by the `registry.get_protocol` method.

This quickstart demonstrates how to define a simple database protocol using a YAML configuration file, load it into the `pyannote.database` registry, and then iterate over a protocol subset to access multimedia resources and their associated metadata. It highlights the use of `registry.load_database` and `FileFinder`.

import os from pathlib import Path from pyannote.database import registry, FileFinder # 1. Define your database protocol in a YAML file (e.g., database.yml) # This example creates dummy files for demonstration purposes. (Path("data") / "train.lst").parent.mkdir(parents=True, exist_ok=True) (Path("data") / "train.lst").write_text("dummy_file_1\ndummy_file_2\n") config_content = """ Protocols: MyDatabase: MyProtocol: train: uri: data/train.lst """ Path("database.yml").write_text(config_content) # 2. Load the database configuration into the registry # In a real scenario, you'd provide the actual path to your database.yml # For demonstration, we ensure our dummy config is found. os.environ["PYANNOTE_DATABASE_CONFIG"] = str(Path("database.yml").resolve()) registry.load_database("database.yml") # 3. Access a specific protocol # Use FileFinder as a preprocessor to resolve file paths for 'audio' or similar keys. preprocessors = {'audio': FileFinder()} protocol = registry.get_protocol("MyDatabase.MyProtocol", preprocessors=preprocessors) # 4. Iterate over a subset (e.g., 'train') of the protocol print("Iterating over training files:") for current_file in protocol.train(): print(f" URI: {current_file['uri']}") # In a real application, current_file['audio'] would resolve to the media file path, # and current_file['annotation'] would provide temporal annotations. # For this dummy example, 'audio' will not resolve to a real file path # unless actual dummy audio files are created. # 5. Clean up dummy files (not needed in a real application) Path("database.yml").unlink() (Path("data") / "train.lst").unlink() Path("data").rmdir()
Debug
Known issues
breakingVersion 6.0.0 and above require Python 3.10 or newer. Older Python versions are no longer supported.
fix
Upgrade your Python environment to 3.10 or later.
affects: >=6.0.0
breakingThe global functions `pyannote.database.get_database`, `get_protocol`, and `get_protocols` were removed in favor of methods on the `registry` object.
fix
Replace calls like `get_protocol('MyProtocol')` with `registry.get_protocol('MyProtocol')`. The `registry` object must be imported from `pyannote.database`.
affects: >=5.0.0
breakingAutomatic loading of `database.yml` and `~/.pyannote/database.yml` is primarily for backward compatibility with the 4.x branch. Since v5.0.0, configuration files *must* be explicitly loaded using `registry.load_database()` for robust behavior.
fix
Ensure your configuration files are loaded explicitly using `from pyannote.database import registry; registry.load_database('/path/to/your/database.yml')`.
affects: >=5.0.0
gotchaWhen iterating over protocols (e.g., `protocol.train()`), accessing keys like `current_file['audio']` requires a preprocessor like `FileFinder` to resolve the URI to an actual file path. Without it, the key might not resolve correctly or raise an error.
fix
Pass a `preprocessors` dictionary when calling `registry.get_protocol()`, e.g., `preprocessors={'audio': FileFinder()}`. Make sure to import `FileFinder`.
affects: all
gotchaFor custom data loaders to be automatically discovered and used by `pyannote.database`, they must be registered via the `pyannote.database.loader` entry-point in your Python package's `setup.py` or `pyproject.toml`.
fix
Define the `pyannote.database.loader` entry-point in your `setup.py` or `pyproject.toml` and ensure your package is installed in editable mode (`pip install -e .`) or globally for the entry-point to be active.
affects: all
Errors
Common errors & fixes
FileNotFoundError: "pyannote.database" relies on a YAML configuration file but could not find any.
The `pyannote.database` library requires a YAML configuration file (e.g., `database.yml`) to define the paths to your multimedia databases and experimental protocols, and it could not locate this file in the expected locations (e.g., current working directory or `~/.pyannote/database.yml`).
fix
Create a `database.yml` file in your working directory or in `~/.pyannote/` that specifies your databases and protocols. Alternatively, explicitly load the configuration using `registry.load_database('/path/to/your/database.yml')` after importing `registry` from `pyannote.database`.
ImportError: cannot import name 'registry' from 'pyannote.database'
This error typically occurs when using an older version of `pyannote.database` with code written for a newer API, or vice-versa. In recent versions (since 5.0), the way databases and protocols are accessed changed significantly, moving from direct functions like `get_database` or `get_protocol` to methods of a `registry` object.
fix
Ensure your `pyannote.database` version is compatible with your code. For versions 5.0 and newer, import `registry` and use its methods: `from pyannote.database import registry; registry.load_database('your_config.yml'); database = registry.get_database('MyDatabase')`.
AttributeError: 'ProtocolFile' object has no attribute 'dim'
This `AttributeError` often arises when a `ProtocolFile` object is incorrectly passed to a function or model that expects a different input type, such as an `Audio` object or a specific feature representation, especially in the context of `pyannote.audio` models that have specific input requirements.
fix
Review the documentation or examples for the specific model or function you are using to understand the expected input type. You might need to preprocess the `ProtocolFile` (e.g., load the audio, extract features) before passing it to the model. For instance, ensure you are passing the correct part of the file or converting it to the expected format before feeding it to a `Model` or `Pipeline`.
ModuleNotFoundError: No module named 'pyannote.core'
This error indicates that the `pyannote.core` library, a fundamental dependency for `pyannote.database` and other `pyannote` ecosystem components, is not installed or not accessible in your Python environment.
fix
Install `pyannote.core` using pip: `pip install pyannote.core`. Ensure your Python environment is correctly activated if you are using virtual environments. If using `pyannote.audio`, it is often recommended to install `pyannote.audio` which should pull `pyannote.core` as a dependency.
ValueError: No loader for files with '.rttm' suffix
This error occurs when `pyannote.database` attempts to load a file with a specific suffix (e.g., `.rttm`) but does not have a registered data loader for that file type. This can happen if the necessary loader is not imported, not properly configured, or if there were breaking changes in how loaders are registered across library versions.
fix
Ensure that the appropriate data loader is imported and registered. For `.rttm` files, you might need to explicitly import `load_rttm` from `pyannote.database.util`. If using custom loaders, make sure they are correctly defined and registered as entry points. Verify your `pyannote.database` version as loader mechanisms might evolve across major releases.
Upgrade
Version history
6.1.1latest on PyPI · released Dec 7, 2025
Audit
Dependencies
pandasrequiredData manipulation for loaders
pyannote-corerequiredProvides core data structures for temporal segments and annotations
pyyamlrequiredFor parsing YAML configuration files
Agent activity
28 hits · last 30 days
node
19
OpenAI (training)
1
Resources
pyannote-database — pip install pyannote-database · libregistry