API

This is a shallow python binding of the MusicBrainz web service so you should read Development/XML Web Service/Version 2 to understand how that web service works in general.

All requests that fetch data return the data in the form of a dict. Attributes and elements both map to keys in the dict. List entities are of type list.

This part will give an overview of available functions. Have a look at Usage for examples on how to use them.

General

musicbrainzngs.auth(u, p)

Set the username and password to be used in subsequent queries to the MusicBrainz XML API that require authentication.

musicbrainzngs.set_rate_limit(limit_or_interval=1.0, new_requests=1)

Sets the rate limiting behavior of the module. Must be invoked before the first Web service call. If the limit_or_interval parameter is set to False then rate limiting will be disabled. If it is a number then only a set number of requests (new_requests) will be made per given interval (limit_or_interval).

musicbrainzngs.set_useragent(app, version, contact=None)

Set the User-Agent to be used for requests to the MusicBrainz webservice. This must be set before requests are made.

musicbrainzngs.set_hostname(new_hostname)

Set the base hostname for MusicBrainz webservice requests. Defaults to ‘musicbrainz.org’.

Getting Data

All of these functions will fetch a MusicBrainz entity or a list of entities as a dict. You can specify a list of includes to get more data and you can filter on release_status and release_type. See musicbrainz.VALID_RELEASE_STATUSES and musicbrainz.VALID_RELEASE_TYPES. The valid includes are listed for each function.

musicbrainzngs.get_artist_by_id(id, includes=[], release_status=[], release_type=[])

Get the artist with the MusicBrainz id as a dict with an ‘artist’ key.

Available includes: recordings, releases, release-groups, works, various-artists, discids, media, aliases, tags, user-tags, ratings, user-ratings, artist-rels, label-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels, annotation

musicbrainzngs.get_label_by_id(id, includes=[], release_status=[], release_type=[])

Get the label with the MusicBrainz id as a dict with a ‘label’ key.

Available includes: releases, discids, media, aliases, tags, user-tags, ratings, user-ratings, artist-rels, label-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels, annotation

musicbrainzngs.get_recording_by_id(id, includes=[], release_status=[], release_type=[])

Get the recording with the MusicBrainz id as a dict with a ‘recording’ key.

Available includes: artists, releases, discids, media, artist-credits, tags, user-tags, ratings, user-ratings, artist-rels, label-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels, annotation, aliases

musicbrainzngs.get_recordings_by_echoprint(echoprint, includes=[], release_status=[], release_type=[])

Search for recordings with an echoprint. The result is a dict with an ‘echoprint’ key, which again includes a ‘recording-list’.

The preferred fingerprint method is AcoustID.

Available includes: artists, releases, discids, media, artist-credits, tags, user-tags, ratings, user-ratings, artist-rels, label-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels, annotation, aliases

musicbrainzngs.get_recordings_by_puid(puid, includes=[], release_status=[], release_type=[])

Search for recordings with a PUID. The result is a dict with a ‘puid’ key, which again includes a ‘recording-list’.

The preferred fingerprint method is AcoustID.

Available includes: artists, releases, discids, media, artist-credits, tags, user-tags, ratings, user-ratings, artist-rels, label-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels, annotation, aliases

musicbrainzngs.get_recordings_by_isrc(isrc, includes=[], release_status=[], release_type=[])

Search for recordings with an ISRC. The result is a dict with an ‘isrc’ key, which again includes a ‘recording-list’.

Available includes: artists, releases, discids, media, artist-credits, tags, user-tags, ratings, user-ratings, artist-rels, label-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels, annotation, aliases

musicbrainzngs.get_release_group_by_id(id, includes=[], release_status=[], release_type=[])

Get the release group with the MusicBrainz id as a dict with a ‘release-group’ key.

Available includes: artists, releases, discids, media, artist-credits, tags, user-tags, ratings, user-ratings, artist-rels, label-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels, annotation, aliases

musicbrainzngs.get_release_by_id(id, includes=[], release_status=[], release_type=[])

Get the release with the MusicBrainz id as a dict with a ‘release’ key.

Available includes: artists, labels, recordings, release-groups, media, artist-credits, discids, puids, echoprints, isrcs, artist-rels, label-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels, recording-level-rels, work-level-rels, annotation, aliases

musicbrainzngs.get_releases_by_discid(id, includes=[], release_status=[], release_type=[])

Search for releases with a Disc ID.

The result is a dict with either a ‘disc’ or a ‘cdstub’ key. A ‘disc’ has a ‘release-list’ and a ‘cdstub’ key has direct ‘artist’ and ‘title’ keys.

Available includes: artists, labels, recordings, release-groups, media, artist-credits, discids, puids, echoprints, isrcs, artist-rels, label-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels, recording-level-rels, work-level-rels, annotation, aliases

musicbrainzngs.get_work_by_id(id, includes=[])

Get the work with the MusicBrainz id as a dict with a ‘work’ key.

Available includes: artists, aliases, tags, user-tags, ratings, user-ratings, artist-rels, label-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels, annotation

musicbrainzngs.get_works_by_iswc(iswc, includes=[])

Search for works with an ISWC. The result is a dict with a`work-list`.

Available includes: artists, aliases, tags, user-tags, ratings, user-ratings, artist-rels, label-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels, annotation

musicbrainzngs.get_collections()

List the collections for the currently authenticated user as a dict with a ‘collection-list’ key.

musicbrainzngs.get_releases_in_collection(collection)

List the releases in a collection. Returns a dict with a ‘collection’ key, which again has a ‘release-list’.

musicbrainzngs.musicbrainz.VALID_RELEASE_TYPES = ['nat', 'album', 'single', 'ep', 'compilation', 'soundtrack', 'spokenword', 'interview', 'audiobook', 'live', 'remix', 'other']

These can be used to filter whenever releases are includes or browsed

musicbrainzngs.musicbrainz.VALID_RELEASE_STATUSES = ['official', 'promotion', 'bootleg', 'pseudo-release']

These can be used to filter whenever releases or release-groups are involved

Searching

For all of these search functions you can use any of the allowed search fields as parameter names. The documentation of what these fields do is on Development/XML Web Service/Version 2/Search.

You can also set the query parameter to any lucene query you like. When you use any of the search fields as parameters, special characters are escaped in the query.

By default the elements are concatenated with spaces in between, so lucene essentially does a fuzzy search. That search might include results that don’t match the complete query, though these will be ranked lower than the ones that do. If you want all query elements to match for all results, you have to set strict=True.

By default the web service returns 25 results per request and you can set a limit of up to 100. You have to use the offset parameter to set how many results you have already seen so the web service doesn’t give you the same results again.

musicbrainzngs.search_annotations(query='', limit=None, offset=None, strict=False, **fields)

Search for annotations and return a dict with an ‘annotation-list’ key.

Available search fields: entity, name, text, type

musicbrainzngs.search_artists(query='', limit=None, offset=None, strict=False, **fields)

Search for artists and return a dict with an ‘artist-list’ key.

Available search fields: arid, artist, artistaccent, alias, begin, comment, country, end, ended, gender, ipi, sortname, tag, type

musicbrainzngs.search_labels(query='', limit=None, offset=None, strict=False, **fields)

Search for labels and return a dict with a ‘label-list’ key.

Available search fields: alias, begin, code, comment, country, end, ended, ipi, label, labelaccent, laid, sortname, type, tag

musicbrainzngs.search_recordings(query='', limit=None, offset=None, strict=False, **fields)

Search for recordings and return a dict with a ‘recording-list’ key.

Available search fields: arid, artist, artistname, creditname, comment, country, date, dur, format, isrc, number, position, primarytype, puid, qdur, recording, recordingaccent, reid, release, rgid, rid, secondarytype, status, tnum, tracks, tracksrelease, tag, type

musicbrainzngs.search_release_groups(query='', limit=None, offset=None, strict=False, **fields)

Search for release groups and return a dict with a ‘release-group-list’ key.

Available search fields: arid, artist, artistname, comment, creditname, primarytype, rgid, releasegroup, releasegroupaccent, releases, release, reid, secondarytype, status, tag, type

musicbrainzngs.search_releases(query='', limit=None, offset=None, strict=False, **fields)

Search for recordings and return a dict with a ‘recording-list’ key.

Available search fields: arid, artist, artistname, asin, barcode, creditname, catno, comment, country, creditname, date, discids, discidsmedium, format, laid, label, lang, mediums, primarytype, puid, reid, release, releaseaccent, rgid, script, secondarytype, status, tag, tracks, tracksmedium, type

Browsing

You can browse entitities of a certain type linked to one specific entity. That is you can browse all recordings by an artist, for example.

These functions can be used to to include more than the maximum of 25 linked entities returned by the functions in Getting Data. You can set a limit as high as 100. The default is still 25. Similar to the functions in Searching, you have to specify an offset to see the results you haven’t seen yet.

You have to provide exactly one MusicBrainz ID to these functions.

musicbrainzngs.browse_artists(recording=None, release=None, release_group=None, includes=[], limit=None, offset=None)

Get all artists linked to a recording, a release or a release group. You need to give one MusicBrainz ID.

Available includes: aliases, tags, ratings, user-tags, user-ratings

musicbrainzngs.browse_labels(release=None, includes=[], limit=None, offset=None)

Get all labels linked to a relase. You need to give a MusicBrainz ID.

Available includes: aliases, tags, ratings, user-tags, user-ratings

musicbrainzngs.browse_recordings(artist=None, release=None, includes=[], limit=None, offset=None)

Get all recordings linked to an artist or a release. You need to give one MusicBrainz ID.

Available includes: artist-credits, tags, ratings, user-tags, user-ratings

musicbrainzngs.browse_release_groups(artist=None, release=None, release_type=[], includes=[], limit=None, offset=None)

Get all release groups linked to an artist or a release. You need to give one MusicBrainz ID.

You can filter by musicbrainz.VALID_RELEASE_TYPES.

Available includes: artist-credits, tags, ratings, user-tags, user-ratings

musicbrainzngs.browse_releases(artist=None, label=None, recording=None, release_group=None, release_status=[], release_type=[], includes=[], limit=None, offset=None)

Get all releases linked to an artist, a label, a recording or a release group. You need to give one MusicBrainz ID.

You can filter by musicbrainz.VALID_RELEASE_TYPES or musicbrainz.VALID_RELEASE_STATUSES.

Available includes: artist-credits, labels, recordings, release-groups, media, discids, artist-rels, label-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels

Submitting

These are the only functions that write to the MusicBrainz database. They take one or more dicts with multiple entities as keys, which take certain values or a list of values.

You have to use auth() before using any of these functions.

musicbrainzngs.submit_barcodes(release_barcode)

Submits a set of {release_id1: barcode, ...}

musicbrainzngs.submit_puids(recording_puids)

Submit PUIDs. Submits a set of {recording_id1: [puid1, ...], ...} or {recording_id1: puid, ...}.

musicbrainzngs.submit_echoprints(recording_echoprints)

Submit echoprints. Submits a set of {recording_id1: [echoprint1, ...], ...} or {recording_id1: echoprint, ...}.

musicbrainzngs.submit_isrcs(recording_isrcs)

Submit ISRCs. Submits a set of {recording-id1: [isrc1, ...], ...} or {recording_id1: isrc, ...}.

musicbrainzngs.submit_tags(artist_tags={}, recording_tags={})

Submit user tags. Artist or recording parameters are of the form: {entity_id1: [tag1, ...], ...}

musicbrainzngs.submit_ratings(artist_ratings={}, recording_ratings={})

Submit user ratings. Artist or recording parameters are of the form: {entity_id1: rating, ...}

musicbrainzngs.add_releases_to_collection(collection, releases=[])

Add releases to a collection. Collection and releases should be identified by their MBIDs

musicbrainzngs.remove_releases_from_collection(collection, releases=[])

Remove releases from a collection. Collection and releases should be identified by their MBIDs

Exceptions

These are the main exceptions that are raised by functions in musicbrainzngs. You might want to catch some of these at an appropriate point in your code.

Some of these might have subclasses that are not listed here.

class musicbrainzngs.MusicBrainzError

Base class for all exceptions related to MusicBrainz.

class musicbrainzngs.UsageError

Bases: musicbrainzngs.musicbrainz.MusicBrainzError

Error related to misuse of the module API.

class musicbrainzngs.WebServiceError(message=None, cause=None)

Bases: musicbrainzngs.musicbrainz.MusicBrainzError

Error related to MusicBrainz API requests.

class musicbrainzngs.AuthenticationError(message=None, cause=None)

Bases: musicbrainzngs.musicbrainz.WebServiceError

Received a HTTP 401 response while accessing a protected resource.

class musicbrainzngs.NetworkError(message=None, cause=None)

Bases: musicbrainzngs.musicbrainz.WebServiceError

Problem communicating with the MB server.

class musicbrainzngs.ResponseError(message=None, cause=None)

Bases: musicbrainzngs.musicbrainz.WebServiceError

Bad response sent by the MB server.