Skip to main content
`Ctrl`+`K`

# MusicBrainz Plugin

The `musicbrainz` plugin extends the autotagger’s search capabilities to include matches from the MusicBrainz database.

## Installation

To use the `musicbrainz` plugin, enable it in your configuration (see Using Plugins)

## Configuration

This plugin can be configured like other metadata source plugins as described in Using Metadata Source Plugins.

### Default

    musicbrainz:
        host: musicbrainz.org
        https: no
        ratelimit: 1
        ratelimit_interval: 1.0
        extra_tags: []
        genres: no
        genres_tag: genre
        external_ids:
            discogs: no
            bandcamp: no
            spotify: no
            deezer: no
            beatport: no
            tidal: no
        data_source_mismatch_penalty: 0.5
        search_limit: 5
        aliases_as_credits: no

host (default: `musicbrainz.org`)

  The Web server hostname (and port, optionally) that will be contacted by beets. You can use this to configure beets to use your own MusicBrainz database instead of the main server.

  The server must have search indices enabled (see Building search indexes).

  Example:

      musicbrainz:
          host: localhost:5000

https (default: `no`)

  Makes the client use HTTPS instead of HTTP. This setting applies only to custom servers. The official MusicBrainz server always uses HTTPS.

ratelimit (default: `1`)

  Controls the number of Web service requests per second. This setting applies only to custom servers. The official MusicBrainz server enforces a rate limit of 1 request per second.

ratelimit_interval (default: `1.0`)

  The time interval (in seconds) for the rate limit. Only applies to custom servers.

enabled (default: `yes`)

  Deprecated since version 2.4: Add `musicbrainz` to the `plugins` list instead.

extra_tags (default: `[]`)

  By default, beets will use only the album and either artist or the MusicBrainz Various Artists ID to query MusicBrainz. Additional tags, including track count, can be queried by using the `extra_tags` setting.

  This setting should improve the autotagger results if the metadata with the given tags match the metadata returned by MusicBrainz.

  Tags supported by this setting:

  - `alias` (also search for release aliases matching the query)

  - `barcode`

  - `catalognum`

  - `country`

  - `label`

  - `media`

  - `tracks` (number of tracks on the release)

  - `year`

  Example:

      musicbrainz:
          extra_tags: [alias, barcode, catalognum, country, label, media, tracks, year]

genres (default: `no`)

  Use MusicBrainz genre tags to populate (and replace if it’s already set) the `genre` tag. This will make it a list of all the genres tagged for the release and the release-group on MusicBrainz, separated by “; “ and sorted by the total number of votes.

external_ids

  Default

      musicbrainz:
          external_ids:
              discogs: no
              spotify: no
              bandcamp: no
              beatport: no
              deezer: no
              tidal: no

  Set any of the `external_ids` options to `yes` to enable the MusicBrainz importer to look for links to related metadata sources. If such a link is available the release ID will be extracted from the URL provided and imported to the beets library.

  The library fields of the corresponding Autotagger Extensions are used to save the data as flexible attributes (`discogs_album_id`, `bandcamp_album_id`, `spotify_album_id`, `beatport_album_id`, `deezer_album_id`, `tidal_album_id`). On re-imports existing data will be overwritten.

genres_tag (default: `genre`)

  Either `genre` or `tag`. Specify `genre` to use just musicbrainz genre and `tag` to use all user-supplied musicbrainz tags.

aliases_as_credits (default: `no`)

  Use the “aliases” data from MusicBrainz as the value for `*_credit` fields.

data_source_mismatch_penalty (default: `0.5`)

  Penalty applied when the data source of a match candidate differs from the original source of your existing tracks. Any decimal number between 0.0 and 1.0

  This setting controls how much to penalize matches from different metadata sources during import. The penalty is applied when beets detects that a match candidate comes from a different data source than what appears to be the original source of your music collection.

  Example configurations:

      # Prefer MusicBrainz over Discogs when sources don't match
      plugins: musicbrainz discogs

      musicbrainz:
          data_source_mismatch_penalty: 0.3  # Lower penalty = preferred
      discogs:
          data_source_mismatch_penalty: 0.8  # Higher penalty = less preferred

      # Do not penalise candidates from Discogs at all
      plugins: musicbrainz discogs

      musicbrainz:
          data_source_mismatch_penalty: 0.5
      discogs:
          data_source_mismatch_penalty: 0.0

      # Disable cross-source penalties entirely
      plugins: musicbrainz discogs

      musicbrainz:
          data_source_mismatch_penalty: 0.0
      discogs:
          data_source_mismatch_penalty: 0.0

  Tip

  The last configuration is equivalent to setting:

      match:
          distance_weights:
              data_source: 0.0  # Disable data source matching

source_weight (default: `0.5`)

  Deprecated since version 2.5: Use data_source_mismatch_penalty instead.

search_limit (default: `5`)

  Maximum number of search results to return.