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’.

musicbrainzngs.set_parser(new_parser_fun=None)¶

Sets the function used to parse the response from the MusicBrainz web service.

If no parser is given, the parser is reset to the default parser mb_parser_xml().

musicbrainzngs.set_format(fmt='xml')¶

Sets the format that should be returned by the Web Service. The server currently supports xml and json.

When you set the format to anything different from the default, you need to provide your own parser with set_parser().

Warning

The json format used by the server is different from the json format returned by the musicbrainzngs internal parser when using the xml format!

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_area_by_id(id, includes=[], release_status=[], release_type=[])¶

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

Available includes: aliases, annotation, area-rels, artist-rels, label-rels, place-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels

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, isrcs, aliases, annotation, area-rels, artist-rels, label-rels, place-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels, tags, user-tags, ratings, user-ratings

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, annotation, area-rels, artist-rels, label-rels, place-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels, tags, user-tags, ratings, user-ratings

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

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

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

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, isrcs, annotation, aliases, tags, user-tags, ratings, user-ratings, area-rels, artist-rels, label-rels, place-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels

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, isrcs, annotation, aliases, tags, user-tags, ratings, user-ratings, area-rels, artist-rels, label-rels, place-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels

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, annotation, aliases, tags, user-tags, ratings, user-ratings, area-rels, artist-rels, label-rels, place-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels

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, isrcs, recording-level-rels, work-level-rels, annotation, aliases, area-rels, artist-rels, label-rels, place-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels

musicbrainzngs.get_releases_by_discid(id, includes=[], toc=None, cdstubs=True)¶

Search for releases with a Disc ID.

When a toc is provided and no release with the disc ID is found, a fuzzy search by the toc is done. The toc should have to same format as discid.Disc.toc_string.

If no toc matches in musicbrainz but a CD Stub does, the CD Stub will be returned. Prevent this from happening by passing cdstubs=False.

The result is a dict with either a ‘disc’ , a ‘cdstub’ key or a ‘release-list’ (fuzzy match with TOC). 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, isrcs, recording-level-rels, work-level-rels, annotation, aliases, area-rels, artist-rels, label-rels, place-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels

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, annotation, tags, user-tags, ratings, user-ratings, area-rels, artist-rels, label-rels, place-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels

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, annotation, tags, user-tags, ratings, user-ratings, area-rels, artist-rels, label-rels, place-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels

musicbrainzngs.get_url_by_id(id, includes=[])¶

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

Available includes: area-rels, artist-rels, label-rels, place-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels

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, limit=None, offset=None)¶

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

See Browsing for how to use limit and offset.

musicbrainzngs.musicbrainz.VALID_RELEASE_TYPES = ['nat', 'album', 'single', 'ep', 'broadcast', 'other', 'compilation', 'soundtrack', 'spokenword', 'interview', 'audiobook', 'live', 'remix', 'dj-mix', 'mixtape/street']¶: 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, area, beginarea, endarea

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, area

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, qdur, recording, recordingaccent, reid, release, rgid, rid, secondarytype, status, tnum, tracks, tracksrelease, tag, type, video

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, quality, 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, user-tags, ratings, user-ratings, area-rels, artist-rels, label-rels, place-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels

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, user-tags, ratings, user-ratings, area-rels, artist-rels, label-rels, place-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels

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, isrcs, tags, user-tags, ratings, user-ratings, area-rels, artist-rels, label-rels, place-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels

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, user-tags, ratings, user-ratings, area-rels, artist-rels, label-rels, place-rels, recording-rels, release-rels, release-group-rels, url-rels, work-rels

musicbrainzngs.browse_releases(artist=None, track_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 also browse by track_artist, which gives all releases where some tracks are attributed to that artist, but not the whole release.

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

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

musicbrainzngs.browse_urls(resource=None, includes=[], limit=None, offset=None)¶

Get urls by actual URL string. You need to give a URL string as ‘resource’

Available includes: area-rels, artist-rels, label-rels, place-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_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.

Logging¶

musicbrainzngs logs debug and informational messages using Python’s logging module. All logging is done in the logger with the name musicbrainzngs.

You can enable this output in your application with:

import logging
logging.basicConfig(level=logging.DEBUG)
# optionally restrict musicbrainzngs output to INFO messages
logging.getLogger("musicbrainzngs").setLevel(logging.INFO)

API¶

General¶

Getting Data¶

Searching¶

Browsing¶

Submitting¶

Exceptions¶

Logging¶

Table Of Contents

Previous topic

Navigation

API¶

General¶

Getting Data¶

Searching¶

Browsing¶

Submitting¶

Exceptions¶

Logging¶

Table Of Contents

Previous topic

Quick search

Navigation