pyannote.database

Warnings

• breaking Version 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.
• breaking The 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`.
• breaking Automatic 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')`.
• gotcha When 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`.
• gotcha For 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.

Install

• pip install pyannote-database Install stable version

Imports

• 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')

  The `get_protocol` function was removed in v5.0.0 and replaced by the `registry.get_protocol` method.

Quickstart

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()