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

abstractmethod album_for_id(album_id: str) → AlbumInfo | None

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

abstractmethod track_for_id(track_id: str) → TrackInfo | None

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

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

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

albums_for_ids(ids: Iterable[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.

tracks_for_ids(ids: Iterable[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.

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.

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.

commands() → Sequence[Subcommand]

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

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.

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.