Usage ~~~~~ In general you need to set a useragent for your application, start searches to get to know corresponding MusicBrainz IDs and then retrieve information about these entities. The data is returned in form of a :class:`dict`. If you also want to submit data, then you must authenticate as a MusicBrainz user. This part of the documentation will give you usage examples. For an overview of available functions you can have a look at the :doc:`api`. Identification -------------- To access the MusicBrainz webservice through this library, you `need to identify your application <http://musicbrainz.org/doc/XML_Web_Service/Version_2#Identifying_your_application_to_the_MusicBrainz_Web_Service>`_ by setting the useragent header made in HTTP requests to one that is unique to your application. To ease this, the convenience function :meth:`musicbrainzngs.set_useragent` is provided which automatically sets the useragent based on information about the application name, version and contact information to the format `recommended by MusicBrainz <http://musicbrainz.org/doc/XML_Web_Service/Rate_Limiting#Provide_meaningful_User-Agent_strings>`_. If a request is made without setting the useragent beforehand, a :exc:`musicbrainzngs.UsageError` will be raised. Authentication -------------- Certain calls to the webservice require user authentication prior to the call itself. The affected functions state this requirement in their documentation. The user and password used for authentication are the same as for the MusicBrainz website itself and can be set with the :meth:`musicbrainzngs.auth` method. After calling this function, the credentials will be saved and automaticall used by all functions requiring them. If a method requiring authentication is called without authenticating, a :exc:`musicbrainzngs.UsageError` will be raised. If the credentials provided are wrong and the server returns a status code of 401, a :exc:`musicbrainzngs.AuthenticationError` will be raised. Getting Data ------------ Regular MusicBrainz Data ^^^^^^^^^^^^^^^^^^^^^^^^ You can get MusicBrainz entities as a :class:`dict` when retrieving them with some form of identifier. An example using :func:`musicbrainzngs.get_artist_by_id`:: artist_id = "c5c2ea1c-4bde-4f4d-bd0b-47b200bf99d6" try: result = musicbrainzngs.get_artist_by_id(artist_id) except WebServiceError as exc: print("Something went wrong with the request: %s" % exc) else: artist = result["artist"] print("name:\t\t%s" % artist["name"]) print("sort name:\t%s" % artist["sort-name"]) You can get more information about entities connected to the artist with adding `includes` and you filter releases and release_groups:: result = musicbrainzngs.get_artist_by_id(artist_id, includes=["release-groups"], release_type=["album", "ep"]) for release_group in result["artist"]["release-group-list"]: print("{title} ({type})".format(title=release_group["title"], type=release_group["type"])) .. tip:: Compilations are also of primary type "album". You have to filter these out manually if you don't want them. .. note:: You can only get at most 25 release groups using this method. If you want to fetch all release groups you will have to `browse <browsing>`_. Cover Art Data ^^^^^^^^^^^^^^ This library includes a few methods to access data from the `Cover Art Archive <https://coverartarchive.org/>`_ which has a `documented API documentation <https://musicbrainz.org/doc/Cover_Art_Archive/API>`_ Both :func:`musicbrainzngs.get_image_list` and :func:`musicbrainzngs.get_release_group_image_list` return the deserialized cover art listing for a `release <https://musicbrainz.org/doc/Cover_Art_Archive/API#.2Frelease.2F.7Bmbid.7D.2F>`_ or `release group <https://musicbrainz.org/doc/Cover_Art_Archive/API#.2Frelease-group.2F.7Bmbid.7D.2F>`_. To find out whether a release has an approved front image, you could use the following example code:: release_id = "46a48e90-819b-4bed-81fa-5ca8aa33fbf3" data = musicbrainzngs.get_cover_art_list("46a48e90-819b-4bed-81fa-5ca8aa33fbf3") for image in data["images"]: if "Front" in image["types"] and image["approved"]: print "%s is an approved front image!" % image["thumbnails"]["large"] break To retrieve an image itself, use :func:`musicbrainzngs.get_image`. A few convenience functions like :func:`musicbrainzngs.get_image_front` are provided to allow easy access to often requested images. .. warning:: There is no upper bound for the size of images uploaded to the Cover Art Archive and downloading an image will return the binary data in memory. Consider using the :py:mod:`tempfile` module or similar techniques to save images to disk as soon as possible. Searching --------- When you don't know the MusicBrainz IDs yet, you have to start a search. Using :func:`musicbrainzngs.search_artists`:: result = musicbrainzngs.search_artists(artist="xx", type="group", country="GB") for artist in result['artist-list']: print(u"{id}: {name}".format(id=artist['id'], name=artist["name"])) .. tip:: Musicbrainzngs returns unicode strings. It's up to you to make sure Python (2) doesn't try to convert these to ascii again. In the example we force a unicode literal for print. Python 3 works without fixes like these. You can also use the query without specifying the search fields:: musicbrainzngs.search_release_groups("the clash london calling") The query and the search fields can also be used at the same time. Browsing -------- When you want to fetch a list of entities greater than 25, you have to use one of the browse functions. Not only can you specify a `limit` as high as 100, but you can also specify an `offset` to get the complete list in multiple requests. An example would be using :func:`musicbrainzngs.browse_release_groups` to get all releases for a label:: label = "71247f6b-fd24-4a56-89a2-23512f006f0c" limit = 100 offset = 0 releases = [] page = 1 print("fetching page number %d.." % page) result = musicbrainzngs.browse_releases(label=label, includes=["labels"], release_type=["album"], limit=limit) page_releases = result['release-list'] releases += page_releases # release-count is only available starting with musicbrainzngs 0.5 if "release-count" in result: count = result['release-count'] print("") while len(page_releases) >= limit: offset += limit page += 1 print("fetching page number %d.." % page) result = musicbrainzngs.browse_releases(label=label, includes=["labels"], release_type=["album"], limit=limit, offset=offset) page_releases = result['release-list'] releases += page_releases print("") for release in releases: for label_info in release['label-info-list']: catnum = label_info.get('catalog-number') if label_info['label']['id'] == label and catnum: print("{catnum:>17}: {date:10} {title}".format(catnum=catnum, date=release['date'], title=release['title'])) print("\n%d releases on %d pages" % (len(releases), page)) .. tip:: You should always try to filter in the query, when possible, rather than fetching everything and filtering afterwards. This will make your application faster since web service requests are throttled. In the example we filter by `release_type`. Submitting ---------- You can also submit data using musicbrainzngs. Please use :func:`musicbrainzngs.set_hostname` to set the host to test.musicbrainz.org when testing the submission part of your application. `Authentication`_ is necessary to submit any data to MusicBrainz. An example using :func:`musicbrainzngs.submit_barcodes` looks like this:: musicbrainzngs.set_hostname("test.musicbrainz.org") musicbrainzngs.auth("test", "mb") barcodes = { "174a5513-73d1-3c9d-a316-3c1c179e35f8": "5099749534728", "838952af-600d-3f51-84d5-941d15880400": "602517737280" } musicbrainzngs.submit_barcodes(barcodes) See :ref:`api_submitting` in the API for other possibilites. More Examples ------------- You can find some examples for using `musicbrainzngs` in the `examples directory <https://github.com/alastair/python-musicbrainzngs/tree/master/examples>`_.