| .github/workflows | ||
| img | ||
| .gitignore | ||
| LICENSE | ||
| listenbrainz.el | ||
| musicbrainz.el | ||
| README.org | ||
MusicBrainz
MusicBrainz is a community-maintained open source encyclopedia of music information. The REST-based webservice API can be used for direct access to MusicBrainz data with output in XML and JSON.
This code provides a simple, incomplete yet possibly useful interface
to some of the MusicBrainz and ListenBrainz APIs from emacs for
exploratory use in org-mode or behind the
scenes sending listening metadata.
MusicBrainz API
- Recording documentation: https://musicbrainz.org/doc/Recording
- Release documentation: https://musicbrainz.org/doc/Release
- Artist documentation: https://musicbrainz.org/doc/Artist
searching & browsing
Search supports the full Lucene search syntax.
some examples
The API docs provide an example search for “Autechre albums & eps” using the URL https://musicbrainz.org/ws/2/release-group?artist=410c9baf-5469-44f6-9852-826524b80c61&type=album|ep
The equivalent function (which returns a raw response as an alist) would be…
(musicbrainz-browse "release-group" "artist" "410c9baf-5469-44f6-9852-826524b80c61" "album|ep")For slightly more legible output wrap with musicbrainz-format
(musicbrainz-format
(musicbrainz-browse "release-group"
"artist"
"410c9baf-5469-44f6-9852-826524b80c61"
"album|ep"))A more interactive approach could start with (musicbrainz-search "artist" "Autechre") or
(musicbrainz-search-artist "Autechre")
Which returns an MBID required for the lookup 410c9baf-5469-44f6-9852-826524b80c61
The MBID can be used for specific lookups (and checked if needed
using musicbrainz-mbid-p )
(musicbrainz-lookup "artist" "410c9baf-5469-44f6-9852-826524b80c61" "releases")(musicbrainz-lookup-artist "410c9baf-5469-44f6-9852-826524b80c61")| Autechre | electronic music duo | Group | 410c9baf-5469-44f6-9852-826524b80c61 |
(musicbrainz-lookup-artist-releases "410c9baf-5469-44f6-9852-826524b80c61")(musicbrainz-lookup-artist-recordings "410c9baf-5469-44f6-9852-826524b80c61")(musicbrainz-lookup-release "ec1ecfcc-f529-43d1-8aa6-2c7051ede00c")| 1990 | Autechre / Saw You | Cassette Case | ec1ecfcc-f529-43d1-8aa6-2c7051ede00c |
(musicbrainz-lookup-recording "83730176-89ec-41a5-a4b6-476998f6291c")| [untitled] | 83730176-89ec-41a5-a4b6-476998f6291c |
(musicbrainz-search-label "Warp")| Warp | 46f0f4cd-8aab-4b33-b698-f459faf64190 |
(musicbrainz-search-label "Music" 5)| 100 | Sony Music | global brand, excluding JP, owned by Sony Music Entertainment (1991 ongoing) | 9e6b4d7f-4958-4db7-8504-d89e315836af |
| 96 | [no label] | Special purpose label – white labels, self-published releases and other “no label” releases (ongoing) | 157afde4-4bf5-4039-8ad2-5a15acc85176 |
| 91 | Polydor | worldwide imprint, see annotation (1913-04-02 ongoing) | ce24ab18-1bd6-4293-a486-546d13d6a5e2 |
| 91 | Universal Music | plain logo: “Universal Music” (ongoing) | 13a464dc-b9fd-4d16-a4f4-d4316f6a46c7 |
| 90 | ZYX Music | (1992 ongoing) | 6844efda-a451-431e-8cc1-48ab111b4711 |
cover art
Cover art for a release may be available from the Cover Art Archive and can be accessed via the API
(musicbrainz-coverart "a929130a-535c-4827-8663-f048e1a7ca0d")(musicbrainz-coverart-front "a929130a-535c-4827-8663-f048e1a7ca0d")(musicbrainz-lookup-release "a929130a-535c-4827-8663-f048e1a7ca0d")| Head Cleaning Cassette | Cassette Case | a929130a-535c-4827-8663-f048e1a7ca0d |
MBID
“One of MusicBrainz' aims is to be the universal lingua franca for music by providing a reliable and unambiguous form of music identification; this music identification is performed through the use of MusicBrainz Identifiers (MBIDs). An MBID is a 36 character Universally Unique Identifier that is permanently assigned to each entity in the database, i.e. artists, release groups, releases, recordings, works, labels, areas, places and URLs. MBIDs are also assigned to Tracks, though tracks do not share many other properties of entities.” https://musicbrainz.org/doc/MusicBrainz_Identifier
(musicbrainz-artist-to-mbid "Autechre")returns 410c9baf-5469-44f6-9852-826524b80c61
(musicbrainz-mbid-p "410c9baf-5469-44f6-9852-826524b80c61")ambiguity
From the docs…
John Williams, the soundtrack composer and conductor, has an artist MBID of 53b106e7-0cc6-42cc-ac95-ed8d30a3a98e
John Williams, the classical guitar player, has an artist MBID of 8b8a38a9-a290-4560-84f6-3d4466e8d791
(musicbrainz-disambiguate-artist "John Williams" 3)| Artist: John Williams | MBID | |
| 100 | John Williams, American score composer | 53b106e7-0cc6-42cc-ac95-ed8d30a3a98e |
| 94 | John Williams, classical guitarist | 8b8a38a9-a290-4560-84f6-3d4466e8d791 |
| 92 | John Williams, English A&R executive, producer, songwriter… | eb5d7680-0c00-4b0c-b6eb-9605ff77723d |
There are several “Bad Seeds”
(musicbrainz-artist-to-mbid "Bad Seeds")Which returns the MBID 7feb02f2-51fa-422d-838e-2c14ecb4c7b8 for
“Tomorrows Bad Seeds”, however…
(musicbrainz-disambiguate-artist "Bad Seeds" 7)| Artist: Bad Seeds | MBID | |
| 100 | Tomorrows Bad Seeds, nil | 7feb02f2-51fa-422d-838e-2c14ecb4c7b8 |
| 98 | The Bad Seeds, 60s Texas rock band | 3e593712-9f70-4b7a-b21b-466016998a3d |
| 98 | The Bad Seeds, 60's US garage rock band from Erlanger, KY | 34bc9a97-fa78-424e-8ca8-a904f978f041 |
| 98 | The Bad Seeds, backing band for Nick Cave | eb2a8edc-5670-4896-82be-87db38de9583 |
| 86 | Nick Cave & the Bad Seeds, nil | 172e1f1a-504d-4488-b053-6344ba63e6d0 |
| 50 | The Lightning Seeds, nil | 1ba601a0-3401-4b28-8ddd-9af8203661e8 |
| 49 | Seeds, UK dancehall | a03cf587-a3d3-4847-ac41-e488f779a313 |
(musicbrainz-lookup-artist "172e1f1a-504d-4488-b053-6344ba63e6d0")incompleteness
general, specific and partial API coverage
Searching & browsing
Search supports the full Lucene search syntax in queries.
| (musicbrainz-search type query &optional limit offset) | see musicbrainz-search-types |
| (musicbrainz-browse entity link query &optional type) | and musicbrainz-entities-* |
| (musicbrainz-search-artist artist &optional limit) | |
| (musicbrainz-artist-to-mbid artist) | |
| (musicbrainz-disambiguate-artist artist &optional limit) | |
| (musicbrainz-search-label label &optional limit) | |
| (musicbrainz-search-recording query &optional limit) | |
| (musicbrainz-search-release query &optional limit) | |
| (musicbrainz-search-work query &optional limit) |
Lookup queries & subqueries
| (musicbrainz-lookup entity MBID &optional inc) | valid entities listed in musicbrainz-entities-core |
| Functions & formatted output | example MBID |
| (musicbrainz-lookup-area MBID) | c9ac1239-e832-41bc-9930-e252a1fd1105 |
| (musicbrainz-lookup-artist MBID) | 410c9baf-5469-44f6-9852-826524b80c61 |
| (musicbrainz-lookup-artist-recordings MBID) | … |
| (musicbrainz-lookup-artist-releases MBID) | … |
| (musicbrainz-lookup-artist-release-groups MBID) | … |
| (musicbrainz-lookup-artist-works MBID) | … |
| (musicbrainz-lookup-collection MBID) | … |
| (musicbrainz-lookup-collection-user-collections MBID) | … |
| (musicbrainz-lookup-event MBID) | 7c132556-e902-4481-b9cb-ec76a175628a |
| (musicbrainz-lookup-genre MBID) | 68c81274-5770-4e7b-a4bf-ab0d7d425d99 |
| (musicbrainz-lookup-instrument MBID) | 303d4f1a-f799-4c42-9bac-dbedd9139e91 |
| (musicbrainz-lookup-label MBID) | 8943d408-940c-403b-a01d-9036c227d50f |
| (musicbrainz-lookup-label-releases MBID) | … |
| (musicbrainz-lookup-place MBID) | 73cba8a4-cacb-45b9-8e02-654f716e2e7a |
| (musicbrainz-lookup-recording MBID) | ef8b34c1-8548-472c-872f-03e0d8d3bb37 |
| (musicbrainz-lookup-recording-artists MBID) | … |
| (musicbrainz-lookup-recording-releases MBID) | … |
| (musicbrainz-lookup-recording-isrcs MBID) | … |
| (musicbrainz-lookup-recording-url-rels MBID) | … |
| (musicbrainz-lookup-release MBID) | … |
| (musicbrainz-lookup-release-artists MBID) | … |
| (musicbrainz-lookup-release-collections MBID) | … |
| (musicbrainz-lookup-release-labels MBID) | … |
| (musicbrainz-lookup-release-recordings MBID) | … |
| (musicbrainz-lookup-release-release-groups MBID) | … |
| (musicbrainz-lookup-release-group MBID) | fe4acfe9-6d1e-3565-8857-fb16ddc492ab |
| (musicbrainz-lookup-release-group-artists MBID) | … |
| (musicbrainz-lookup-release-group-releases MBID) | … |
| (musicbrainz-lookup-series MBID) | … |
| (musicbrainz-lookup-work MBID) | 4ee2545d-2be5-3841-b568-0b4554eccc67 |
| (musicbrainz-lookup-url MBID) | … |
ListenBrainz
listening
examples
(setq listenbrainz-api-token "000-000-000")(listenbrainz-validate-token listenbrainz-api-token)(listenbrainz-listens "zzzkt")(listenbrainz-listens "zzzkt" 33)(listenbrainz-submit-single-listen "Matthew Thomas" "Taema" "Architecture")(listenbrainz-submit-single-listen "farmersmanual" "808808008088 (11)")(listenbrainz-submit-playing-now "farmersmanual" "808808008088 (11)")(listenbrainz-playing-now "zzzkt")(listenbrainz-stats-artists "zzzkt")(listenbrainz-stats-releases "zzzkt")(listenbrainz-stats-recordings "zzzkt" 13 "month")incompleteness
Core API endpoints
https://listenbrainz.readthedocs.io/en/production/dev/api/#core-api-endpoints
| POST /1/submit-listens | listenbrainz-submit-listen |
| listenbrainz-submit-single-listen | |
| listenbrainz-submit-playing-now | |
| GET /1/validate-token | listenbrainz-validate-token |
| POST /1/delete-listen | - |
| GET /1/user/(playlistusername)/playlists/collaborator | - |
| GET /1/user/(playlistusername)/playlists/createdfor | - |
| GET /1/users/(userlist)/recent-listens | - |
| GET /1/user/(username)/similar-users | - |
| GET /1/user/(username)/listen-count | - |
| GET /1/user/(username)/playing-now | listenbrainz-playing-now |
| GET /1/user/(username)/similar-to/(otherusername) | - |
| GET /1/user/(playlistusername)/playlists | - |
| GET /1/user/(username)/listens | listenbrainz-listens |
| GET /1/latest-import | - |
| POST /1/latest-import | - |
Feedback API Endpoints
https://listenbrainz.readthedocs.io/en/production/dev/api/#feedback-api-endpoints
| POST /1/feedback/recording-feedback | - |
| GET /1/feedback/recording/(recordingmsid)/get-feedback | - |
| GET /1/feedback/user/(username)/get-feedback-for-recordings | – |
| GET /1/feedback/user/(username)/get-feedback | - |
Recording Recommendation API Endpoints
https://listenbrainz.readthedocs.io/en/production/dev/api/#core-api-endpoints
| GET /1/cf/recommendation/user/(username)/recording | - |
Recording Recommendation Feedback API Endpoints
| POST /1/recommendation/feedback/submit | - |
| POST /1/recommendation/feedback/delete | - |
| GET /1/recommendation/feedback/user/(username)/recordings | - |
| GET /1/recommendation/feedback/user/(username) | - |
Statistics API Endpoints
https://listenbrainz.readthedocs.io/en/production/dev/api/#statistics-api-endpoints
| GET /1/stats/sitewide/artists | - |
| GET /1/stats/user/(username)/listening-activity | - |
| GET /1/stats/user/(username)/daily-activity | - |
| GET /1/stats/user/(username)/recordings | listenbrainz-stats-recordings |
| GET /1/stats/user/(username)/artist-map | - |
| GET /1/stats/user/(username)/releases | listenbrainz-stats-releases |
| GET /1/stats/user/(username)/artists | listenbrainz-stats-artists |
Status API Endpoints
https://listenbrainz.readthedocs.io/en/production/dev/api/#status-api-endpoints
| GET /1/status/get-dump-info | - |
User Timeline API Endpoints
https://listenbrainz.readthedocs.io/en/production/dev/api/#user-timeline-api-endpoints
| POST /1/user/(username)/timeline-event/create/notification | - |
| POST /1/user/(username)/timeline-event/create/recording | - |
| POST /1/user/(username)/feed/events/delete | - |
| GET /1/user/(username)/feed/events | - |
Social API Endpoints
https://listenbrainz.readthedocs.io/en/production/dev/api/#social-api-endpoints
| GET /1/user/(username)/followers | listenbrainz-followers |
| GET /1/user/(username)/following | listenbrainz-following |
| POST /1/user/(username)/unfollow | - |
| POST /1/user/(username)/follow | - |
Pinned Recording API Endpoints
https://listenbrainz.readthedocs.io/en/production/dev/api/#pinned-recording-api-endpoints
| POST /1/pin/unpin | - |
| POST /1/pin | - |
| POST /1/pin/delete/(rowid) | - |
| GET /1/(username)/pins/following | - |
| GET /1/(username)/pins | - |