SearchApiMetadataSourcePlugin

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

Bases: Generic[R], MetadataSourcePlugin

Helper class to implement a metadata source plugin with an API.

Plugins using this ABC must implement an API search method to retrieve album and track information by ID, i.e. album_for_id and track_for_id, and a search method to perform a search on the API. The search method should return a list of identifiers for the requested type (album or track).

__init__(*args, **kwargs) → None

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.
get_search_query_with_filters(query_type, ...)	Build query text and API filters for a provider search.
get_search_response(params)	Fetch raw search results for a provider request.
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 get_search_query_with_filters(query_type: QueryType, items: Sequence[Item], artist: str, name: str, va_likely: bool) → tuple[str, dict[str, str]]

Build query text and API filters for a provider search.

Subclasses can override this hook when their API requires a query format or filter set that differs from the default text-based construction.

Parameters:

• query_type – The type of query to perform. Either album or track

• items – List of items the search is being performed for

• artist – Artist name

• name – Album or track name, depending on query_type

• va_likely – Whether the search is likely to be for various artists

Returns:

Tuple of (query text, filters dict) to use for the search API call

abstractmethod get_search_response(params: SearchParams) → Sequence[R]

Fetch raw search results for a provider request.

Implementations should return records containing source IDs so shared candidate resolution can perform ID-based album and track lookups.

Parameters:

params – SearchParams named tuple

Returns:

Sequence of IDResponse dicts containing at least an “id” key for each

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

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

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: 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.

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.

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: 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.