Skip to main content
`Ctrl`+`K`

# MusicBrainzAPI

class beetsplug._utils.musicbrainz.MusicBrainzAPI

  Bases: `RequestHandler`

  High-level interface to the MusicBrainz WS/2 API.

  Responsibilities:

  - Configure the API host and request rate from application configuration.

  - Offer helpers to fetch common entity types and to run searches.

  - Normalize MusicBrainz responses so relation lists are grouped by target type for easier downstream consumption.

  Documentation: https://musicbrainz.org/doc/MusicBrainz_API

  __init__() → None

  Public methods summary

  `browse_recordings`(**kwargs) | Browse recordings related to the given entities.
  `browse_release_groups`(**kwargs) | Browse release groups related to the given entities.
  `create_session`() | Create a new HTTP session instance.
  `delete`(*args, **kwargs) | Perform HTTP DELETE request with automatic error handling.
  `format_search_term`(field, term) | Format a search term for the MusicBrainz API.
  `get`(*args, **kwargs) | Perform HTTP GET request with automatic error handling.
  `get_json`(*args, **kwargs) | Fetch JSON data from MusicBrainz and normalize its field names.
  `get_recording`(id_, **kwargs) | Retrieve a recording by its MusicBrainz ID.
  `get_release`(id_, **kwargs) | Retrieve a release by its MusicBrainz ID.
  `get_work`(id_, **kwargs) | Retrieve a work by its MusicBrainz ID.
  `handle_http_error`() | Convert standard HTTP errors to beets-specific exceptions.
  `put`(*args, **kwargs) | Perform HTTP PUT request with automatic error handling.
  `request`(*args, **kwargs) | Ensure all requests specify JSON response format by default.
  `search`(entity, filters, **kwargs) | Search for MusicBrainz entities matching the given filters.
  `status_to_error`(code) | Map HTTP status codes to beets-specific exception types.

  Methods definition

  explicit_http_errors: ClassVar[list[type[BeetsHTTPError]]] = [<class 'beetsplug._utils.requests.HTTPNotFoundError'>, <class 'beetsplug._utils.musicbrainz.UnauthorizedMBError'>]

    List of custom exceptions to be raised for specific status codes.

  create_session() → LimiterTimeoutSession

    Create a new HTTP session instance.

    Can be overridden by subclasses to provide custom session types.

  request(*args, **kwargs) → Response

    Ensure all requests specify JSON response format by default.

  get_json(*args, **kwargs)

    Fetch JSON data from MusicBrainz and normalize its field names.

  static format_search_term(field: str, term: str) → str

    Format a search term for the MusicBrainz API.

    See https://lucene.apache.org/core/4_3_0/queryparser/org/apache/lucene/queryparser/classic/package-summary.html

  search(entity: Entity, filters: dict[str, str], **kwargs: Unpack[SearchKwargs]) → list[IDResponse]

    Search for MusicBrainz entities matching the given filters.

    - Query is constructed by combining the provided filters using AND logic

    - Each filter key-value pair is formatted as ‘key:”value”’ unless - ‘key’ is empty, in which case only the value is used, ‘“value”’ - ‘value’ is empty, in which case the filter is ignored

    - Values are lowercased and stripped of whitespace.

  get_release(id_: str, **kwargs: Unpack[LookupKwargs]) → Release

    Retrieve a release by its MusicBrainz ID.

  get_recording(id_: str, **kwargs: Unpack[LookupKwargs]) → Recording

    Retrieve a recording by its MusicBrainz ID.

  get_work(id_: str, **kwargs: Unpack[LookupKwargs]) → Work

    Retrieve a work by its MusicBrainz ID.

  browse_recordings(**kwargs: Unpack[BrowseRecordingsKwargs]) → list[Recording]

    Browse recordings related to the given entities.

    At least one of artist, collection, release, or work must be provided.

  browse_release_groups(**kwargs: Unpack[BrowseReleaseGroupsKwargs]) → list[ReleaseGroup]

    Browse release groups related to the given entities.

    At least one of artist, collection, or release must be provided. Optionally filter by type (e.g., “album|ep”).

  delete(*args, **kwargs) → Response

    Perform HTTP DELETE request with automatic error handling.

  get(*args, **kwargs) → Response

    Perform HTTP GET request with automatic error handling.

  handle_http_error() → Iterator[None]

    Convert standard HTTP errors to beets-specific exceptions.

    Wraps operations that may raise HTTPError, automatically translating recognized status codes into their corresponding beets exception types. Unrecognized errors are re-raised unchanged.

  put(*args, **kwargs) → Response

    Perform HTTP PUT request with automatic error handling.

  status_to_error(code: int) → type[HTTPError] | None

    Map HTTP status codes to beets-specific exception types.

    Searches the configured explicit HTTP errors for a matching status code. Returns None if no specific error type is registered for the given code.

## Related TypedDicts

typeddict beetsplug._utils.musicbrainz.LookupKwargs

  Bases: `TypedDict`

  `typing.TypedDict`.

typeddict beetsplug._utils.musicbrainz.SearchKwargs

  Bases: `PagingKwargs`

  `typing.TypedDict`.

typeddict beetsplug._utils.musicbrainz.BrowseKwargs

  Bases: `LookupKwargs`, `PagingKwargs`

  `typing.TypedDict`.

typeddict beetsplug._utils.musicbrainz.BrowseRecordingsKwargs

  Bases: `BrowseReleaseGroupsKwargs`

  `typing.TypedDict`.

typeddict beetsplug._utils.musicbrainz.BrowseReleaseGroupsKwargs

  Bases: `BrowseKwargs`

  `typing.TypedDict`.