Access data from Musicbrainz.

See also: cpe musicbrainz command.

This module wraps the musicbrainzngs library.


Musicbrainz access requires that you set a User Agent string. A default is set by the MusicbrainzContext object which can be overridden using its config.


Caching of data is handled using the calliope.cache module.


Package Contents



Configuration for Musicbrainz APIs.


annotate(context, playlist, include_patterns, select_fun=None, update=False)

Annotate each item in a playlist with metadata from Musicbrainz.

resolve_image(context, playlist, max_size = 250)

Resolve a cover image using the Cover Art API.

class calliope.musicbrainz.MusicbrainzContext(config)

Configuration for Musicbrainz APIs.

Keys used from config dict:

  • App name

  • musicbrainz.version: API version

  • Contact URL

If unset, the defaults reference Calliope and API version 1.


config (dict) –

calliope.musicbrainz.annotate(context, playlist, include_patterns, select_fun=None, update=False)

Annotate each item in a playlist with metadata from Musicbrainz.

The include_patterns parameter controls what subqueries are run, via the MusicBrainz include query parameter.

This parameter takes keys like areas or url-rels which cause more data to be fetched. MusicBrainz has different resource types, while in Calliope everything is a playlist item, so within Calliope we specify keys as typename.key. These are examples of different include key fullnames:

  • artist.areas

  • artist.url-rels

  • recording.url-rels

In include_patterns you can pass literal key names, and you can use * as a wildcard. For example, you can get all url-rels information with *.url-rels, and all info about an artist with artist.*.

For reference documentation of the include parameter, see: <>.

Use calliope.includes.all_include_key_fullnames() to retrieve the full list of include keys.

calliope.musicbrainz.resolve_image(context, playlist, max_size=250)

Resolve a cover image using the Cover Art API.

See for more info.