API

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

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

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

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

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

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

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

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

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

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

musicbrainzngs.get_work_by_id(id, includes=[])

musicbrainzngs.get_works_by_iswc(iswc, includes=[])

musicbrainzngs.get_collections()

musicbrainzngs.get_releases_in_collection(collection)

Searching

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

Search for annotations by a free-form query string or any of the following keyword arguments specifying field queries: entity, name, text, type When fields are set, special lucene characters are escaped in the query.

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

Search for artists by a free-form query string or any of the following keyword arguments specifying field queries: arid, artist, sortname, type, begin, end, comment, alias, country, gender, tag When fields are set, special lucene characters are escaped in the query.

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

Search for labels by a free-form query string or any of the following keyword arguments specifying field queries: laid, label, sortname, type, code, country, begin, end, comment, alias, tag When fields are set, special lucene characters are escaped in the query.

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

Search for recordings by a free-form query string or any of the following keyword arguments specifying field queries: rid, recording, isrc, arid, artist, artistname, creditname, reid, release, type, status, tracks, tracksrelease, dur, qdur, tnum, position, tag When fields are set, special lucene characters are escaped in the query.

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

Search for release groups by a free-form query string or any of the following keyword arguments specifying field queries: rgid, releasegroup, reid, release, arid, artist, artistname, creditname, type, tag When fields are set, special lucene characters are escaped in the query.

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

Search for releases by a free-form query string or any of the following keyword arguments specifying field queries: reid, release, arid, artist, artistname, creditname, type, status, tracks, tracksmedium, discids, discidsmedium, mediums, date, asin, lang, script, country, date, label, catno, barcode, puid When fields are set, special lucene characters are escaped in the query.

musicbrainz.VALID_INCLUDES = {'echoprint': ['artists', 'releases'], 'collection': ['releases'], 'isrc': ['artists', 'releases', 'puids', 'echoprints', 'isrcs'], 'annotation': [], 'discid': ['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'], 'artist': ['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'], 'iswc': ['artists'], 'work': ['artists', 'aliases', 'tags', 'user-tags', 'ratings', 'user-ratings', 'artist-rels', 'label-rels', 'recording-rels', 'release-rels', 'release-group-rels', 'url-rels', 'work-rels', 'annotation'], 'label': ['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'], 'recording': ['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'], 'puid': ['artists', 'releases', 'puids', 'echoprints', 'isrcs'], 'release': ['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'], 'release-group': ['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']}

musicbrainz.VALID_SEARCH_FIELDS = {'artist': ['arid', 'artist', 'sortname', 'type', 'begin', 'end', 'comment', 'alias', 'country', 'gender', 'tag', 'ipi', 'artistaccent'], 'work': ['wid', 'work', 'iswc', 'type', 'arid', 'artist', 'alias', 'tag', 'comment', 'workaccent'], 'label': ['laid', 'label', 'sortname', 'type', 'code', 'country', 'begin', 'end', 'comment', 'alias', 'tag', 'ipi', 'labelaccent'], 'recording': ['rid', 'recording', 'isrc', 'arid', 'artist', 'artistname', 'creditname', 'reid', 'release', 'type', 'status', 'tracks', 'tracksrelease', 'dur', 'qdur', 'tnum', 'position', 'tag', 'comment', 'country', 'dateformat', 'recordingaccent'], 'release': ['reid', 'release', 'arid', 'artist', 'artistname', 'creditname', 'type', 'status', 'tracks', 'tracksmedium', 'discids', 'discidsmedium', 'mediums', 'date', 'asin', 'lang', 'script', 'country', 'date', 'label', 'catno', 'barcode', 'puid', 'comment', 'format', 'releaseaccent', 'rgid'], 'release-group': ['rgid', 'releasegroup', 'reid', 'release', 'arid', 'artist', 'artistname', 'creditname', 'type', 'tag', 'releasegroupaccent', 'releases', 'comment'], 'annotation': ['entity', 'name', 'text', 'type']}

Browsing

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

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

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

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

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

Submitting

musicbrainzngs.submit_barcodes(barcodes)

Submits a set of {release1: barcode1, release2:barcode2}

Must call auth(user, pass) first

musicbrainzngs.submit_puids(puids)

Submit PUIDs.

Must call auth(user, pass) first

musicbrainzngs.submit_echoprints(echoprints)

Submit echoprints.

Must call auth(user, pass) first

musicbrainzngs.submit_isrcs(recordings_isrcs)

Submit ISRCs. Submits a set of {recording-id: [isrc1, isrc2, ...]}

Must call auth(user, pass) first

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

Submit user tags. Artist or recording parameters are of the form: {‘entityid’: [taglist]}

Must call auth(user, pass) first

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

Submit user ratings. Artist or recording parameters are of the form: {‘entityid’: rating}

Must call auth(user, pass) first

musicbrainzngs.add_releases_to_collection(collection, releases=[])

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

Must call auth(user, pass) first

musicbrainzngs.remove_releases_from_collection(collection, releases=[])

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

Must call auth(user, pass) first

Exceptions

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

Received a HTTP 401 response while accessing a protected resource.

class musicbrainzngs.UsageError

Error related to misuse of the module API.