Musicbrainz

This is a plugin for Moe utilizing the musicbrainz metadata source and provides the following features:

  • Musicbrainz as an import souce.

  • Update musicbrainz collections automatically on import or manually.

  • Various API functions.

Installation

  1. Install via pipx

    $ pipx inject moe moe_musicbrainz

Configuration

Add musicbrainz to the enabled_plugins configuration option.

This plugin has the following configuration options:

username

Musicbrainz username.

password

Musicbrainz password.

search_limit = 5

Maximum number of search results to return when searching for candidate albums from MusicBrainz. Must be at least 1. Defaults to 5.

Collections

The following options involve auto updating a specific collection on musicbrainz, and should be specified under a musicbrainz.collection block as shown:

[musicbrainz.collection]
collection_id = "123"

Important

Utilizing any of the collections functionality requires setting your musicbrainz username and password as described above.

collection_id

Musicbrainz collection to automatically update.

auto_add = false

Whether to automatically add new releases in the library to the collection defined in collection_id.

auto_remove = false

Whether to automatically remove releases from collection_id when removed from the library.

Custom Fields

This plugin adds the following custom fields:

Track Fields

  • mb_track_id - musicbrainz track id

Album Fields

  • mb_album_id - musicbrainz album aka release id

Command-line Interface

This plugin adds the following commands:

mbcol

Used to sync a musicbrainz collection with musicbrainz releases in the library. The collection synced is the one specified under collection_id in the user config.

moe mbcol [-h] [-a | -e] [--add | --remove] query

By default, the musicbrainz collection will be set to the releases found in the queried items. If tracks or extras are queried, their associated album releases will be synced with the collection.

Positional Arguments

query

Query your library for items to sync your collection with. See the Moe query docs for more info.

Optional Arguments

-h, --help

Display the help message.

-a, --album

Query for matching albums instead of tracks.

-e, --extra

Query for matching extras instead of tracks.

--add

Add releases to the collection.

--remove

Remove releases from the collection.

API

moe_musicbrainz

Core musicbrainz API.

See also

exception MBAuthError

Bases: Exception

Musicbrainz user authentication error.

add_releases_to_collection(releases: set[str], collection: str | None = None) → None

Adds releases to a musicbrainz collection.

Parameters:

  • releases – Musicbrainz release IDs to add to the collection.

  • collection – Musicbrainz collection ID to add the releases to. If not given, defaults to the musicbrainz.collection.collection_id config option.

Raises:

MBAuthError – Invalid musicbrainz user credentials in the configuration.

get_album_by_id(release_id: str) → MetaAlbum

Returns an album from musicbrainz with the given release ID.

get_candidate_by_id(album: Album, release_id: str) → CandidateAlbum

Returns a candidate for album from the given release_id.

get_track_by_id(track_id: str, album_id: str) → MetaTrack

Gets a musicbrainz track from a given track and release id.

Parameters:

  • track_id – Musicbrainz track ID to match.

  • album_id – Release album ID the track belongs to.

Returns:

A track containing all metadata associated with the given IDs.

Raises:

ValueError – Couldn’t find track based on given track_id and album_id.

rm_releases_from_collection(releases: set[str], collection: str | None = None) → None

Removes releases from a musicbrainz collection.

Parameters:

  • releases – Musicbrainz release IDs to remove from the collection.

  • collection – Musicbrainz collection ID to remove the releases from. If not given, defaults to the musicbrainz.collection.collection_id config option.

Raises:

MBAuthError – Invalid musicbrainz user credentials in the configuration.

set_collection(releases: set[str], collection: str | None = None) → None

Sets a musicbrainz collection with the given releases.

The releases in the collection will be set to releases, adding any releases not present in the collection, as well as removing any extraneous releases.

Parameters:

  • releases – Musicbrainz releases to set the collection to.

  • collection – Musicbrainz collection ID for the collection to set. If not given, defaults to the musicbrainz.collection.collection_id config option.

Raises:

MBAuthError – Invalid user credentials in the configuration.