Skip to main content
`Ctrl`+`K`

# MetadataSourcePlugin

class beets.metadata_plugins.MetadataSourcePlugin(*args, **kwargs)

  Bases: `BeetsPlugin`

  A plugin that provides metadata from a specific source.

  This base class implements a contract for plugins that provide metadata from a specific source. The plugin must implement the methods to search for albums and tracks, and to retrieve album and track information by ID.

  __init__(*args, **kwargs) → None

    Perform one-time plugin setup.

  Public methods summary

  `add_media_field`(name, descriptor) | Add a field that is synchronized between media files and items.
  `album_for_id`(album_id) | Return `AlbumInfo` object or None if no matching release was found.
  `albums_for_ids`(ids) | Batch lookup of album metadata for a list of album IDs.
  `candidates`(items, artist, album, va_likely) | Return `AlbumInfo` candidates that match the given album.
  `commands`() | Should return a list of beets.ui.Subcommand objects for commands that should be added to beets' CLI.
  `get_artist`(artists[, id_key, name_key, join_key]) | Returns an artist string (all artists) and an artist_id (the main artist) for a list of artist object dicts.
  `get_early_import_stages`() | Return a list of functions that should be called as importer pipelines stages early in the pipeline.
  `get_import_stages`() | Return a list of functions that should be called as importer pipelines stages.
  `item_candidates`(item, artist, title) | Return `TrackInfo` candidates that match the given track.
  `queries`() | Return a dict mapping prefixes to Query subclasses.
  `register_listener`(event, func) | Add a function as a listener for the specified event.
  `template_field`(name) | Decorator that registers a path template field computation.
  `template_func`(name) | Decorator that registers a path template function.
  `track_for_id`(track_id) | Return a `TrackInfo` object or None if no matching release was found.
  `tracks_for_ids`(ids) | Batch lookup of track metadata for a list of track IDs.

  Methods definition

  add_media_field(name: str, descriptor: MediaField) → None

    Add a field that is synchronized between media files and items.

    When a media field is added `item.write()` will set the name property of the item’s MediaFile to `item[name]` and save the changes. Similarly `item.read()` will set `item[name]` to the value of the name property of the media file.

  abstractmethod album_for_id(album_id: str) → AlbumInfo | None

    Return `AlbumInfo` object or None if no matching release was found.

  albums_for_ids(ids: Sequence[str]) → Iterable[AlbumInfo | None]

    Batch lookup of album metadata for a list of album IDs.

    Given a list of album identifiers, yields corresponding AlbumInfo objects. Missing albums result in None values in the output iterator. Plugins may implement this for optimized batched lookups instead of single calls to album_for_id.

  abstractmethod candidates(items: Sequence[Item], artist: str, album: str, va_likely: bool) → Iterable[AlbumInfo]

    Return `AlbumInfo` candidates that match the given album.

    Used in the autotag functionality to search for albums.

    Parameters:

      - items – List of items in the album

      - artist – Album artist

      - album – Album name

      - va_likely – Whether the album is likely to be by various artists

  commands() → Sequence[Subcommand]

    Should return a list of beets.ui.Subcommand objects for commands that should be added to beets’ CLI.

  static get_artist(artists: Iterable[dict[str | int, str]], id_key: str | int = 'id', name_key: str | int = 'name', join_key: str | int | None = None) → tuple[str, str | None]

    Returns an artist string (all artists) and an artist_id (the main artist) for a list of artist object dicts.

    For each artist, this function moves articles (such as ‘a’, ‘an’, and ‘the’) to the front. It returns a tuple containing the comma-separated string of all normalized artists and the `id` of the main/first artist. Alternatively a keyword can be used to combine artists together into a single string by passing the join_key argument.

    Parameters:

      - artists – Iterable of artist dicts or lists returned by API.

      - id_key – Key or index corresponding to the value of `id` for the main/first artist. Defaults to ‘id’.

      - name_key – Key or index corresponding to values of names to concatenate for the artist string (containing all artists). Defaults to ‘name’.

      - join_key – Key or index corresponding to a field containing a keyword to use for combining artists into a single string, for example “Feat.”, “Vs.”, “And” or similar. The default is None which keeps the default behaviour (comma-separated).

    Returns:

      Normalized artist string.

  get_early_import_stages() → list[ImportStageFunc]

    Return a list of functions that should be called as importer pipelines stages early in the pipeline.

    The callables are wrapped versions of the functions in self.early_import_stages. Wrapping provides some bookkeeping for the plugin: specifically, the logging level is adjusted to WARNING.

  get_import_stages() → list[ImportStageFunc]

    Return a list of functions that should be called as importer pipelines stages.

    The callables are wrapped versions of the functions in self.import_stages. Wrapping provides some bookkeeping for the plugin: specifically, the logging level is adjusted to WARNING.

  abstractmethod item_candidates(item: Item, artist: str, title: str) → Iterable[TrackInfo]

    Return `TrackInfo` candidates that match the given track.

    Used in the autotag functionality to search for tracks.

    Parameters:

      - item – Track item

      - artist – Track artist

      - title – Track title

  queries() → dict[str, type[Query]]

    Return a dict mapping prefixes to Query subclasses.

  register_listener(event: EventType, func: Listener) → None

    Add a function as a listener for the specified event.

  classmethod template_field(name: str) → Callable[[TFunc[Item]], TFunc[Item]]

    Decorator that registers a path template field computation. The value will be referenced as `$name` from path format strings. The function must accept a single parameter, the Item being formatted.

  classmethod template_func(name: str) → Callable[[TFunc[str]], TFunc[str]]

    Decorator that registers a path template function. The function will be invoked as `%name{}` from path format strings.

  abstractmethod track_for_id(track_id: str) → TrackInfo | None

    Return a `TrackInfo` object or None if no matching release was found.

  tracks_for_ids(ids: Sequence[str]) → Iterable[TrackInfo | None]

    Batch lookup of track metadata for a list of track IDs.

    Given a list of track identifiers, yields corresponding TrackInfo objects. Missing tracks result in None values in the output iterator. Plugins may implement this for optimized batched lookups instead of single calls to track_for_id.