1 # -*- mode: org; coding: utf-8; -*-
2 #+OPTIONS: toc:2 num:nil html-style:nil
4 #+title: MusicBrainz & ListenBrainz & others
6 - [[#musicbrainz][MusicBrainz]]
7 - [[#musicbrainz-api][MusicBrainz API]]
8 - [[#searching--browsing][searching & browsing]]
9 - [[#some-examples][some examples]]
10 - [[#cover-art][cover art]]
12 - [[#ambiguity][ambiguity]]
13 - [[#incompleteness][incompleteness]]
14 - [[#listenbrainz][ListenBrainz]]
15 - [[#listening][listening]]
16 - [[#examples][examples]]
17 - [[#incompleteness-1][incompleteness]]
18 - [[#otherbrainz][otherBrainz]]
19 - [[#further][further]]
23 [[file:img/musicbrainz-logo.svg]]
25 MusicBrainz is a community-maintained open source encyclopedia of [[https://musicbrainz.org/doc/About][music information]]. The REST-based [[https://musicbrainz.org/doc/MusicBrainz_API][webservice API]] can be used for direct access to MusicBrainz data with output in XML and JSON.
27 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.
31 - Recording documentation: https://musicbrainz.org/doc/Recording
32 - Release documentation: https://musicbrainz.org/doc/Release
33 - Artist documentation: https://musicbrainz.org/doc/Artist
35 ** searching & browsing
37 Search supports the full [[https://lucene.apache.org/core/7_7_2/queryparser/org/apache/lucene/queryparser/classic/package-summary.html#package.description][Lucene search syntax]].
41 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
43 The equivalent function (which returns a raw response as an alist) would be…
44 #+BEGIN_SRC emacs-lisp
45 (musicbrainz-browse "release-group" "artist" "410c9baf-5469-44f6-9852-826524b80c61" "album|ep")
48 For slightly more legible output wrap with =musicbrainz-format=
49 #+BEGIN_SRC emacs-lisp
51 (musicbrainz-browse "release-group"
53 "410c9baf-5469-44f6-9852-826524b80c61"
57 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=
59 The MBID can be used for specific lookups (and checked if needed using =musicbrainz-mbid-p= )
61 #+BEGIN_SRC emacs-lisp
62 (musicbrainz-lookup "artist" "410c9baf-5469-44f6-9852-826524b80c61" "releases")
65 #+BEGIN_SRC emacs-lisp
66 (musicbrainz-lookup-artist "410c9baf-5469-44f6-9852-826524b80c61")
69 | Autechre | electronic music duo | Group | [[https://musicbrainz.org/artist/410c9baf-5469-44f6-9852-826524b80c61][410c9baf-5469-44f6-9852-826524b80c61]] |
71 #+BEGIN_SRC emacs-lisp
72 (musicbrainz-lookup-artist-releases "410c9baf-5469-44f6-9852-826524b80c61")
75 #+BEGIN_SRC emacs-lisp
76 (musicbrainz-lookup-artist-recordings "410c9baf-5469-44f6-9852-826524b80c61")
79 #+BEGIN_SRC emacs-lisp
80 (musicbrainz-lookup-release "ec1ecfcc-f529-43d1-8aa6-2c7051ede00c")
83 | 1990 | Autechre / Saw You | Cassette Case | [[https://musicbrainz.org/release/ec1ecfcc-f529-43d1-8aa6-2c7051ede00c][ec1ecfcc-f529-43d1-8aa6-2c7051ede00c]] |
85 #+BEGIN_SRC emacs-lisp
86 (musicbrainz-lookup-recording "83730176-89ec-41a5-a4b6-476998f6291c")
89 | [untitled] | [[https://musicbrainz.org/recording/83730176-89ec-41a5-a4b6-476998f6291c][83730176-89ec-41a5-a4b6-476998f6291c]] |
91 #+BEGIN_SRC emacs-lisp
92 (musicbrainz-search-label "Warp")
95 | Warp | [[https://musicbrainz.org/label/46f0f4cd-8aab-4b33-b698-f459faf64190][46f0f4cd-8aab-4b33-b698-f459faf64190]] |
97 #+BEGIN_SRC emacs-lisp
98 (musicbrainz-search-label "Music" 5)
101 | 100 | Sony Music | global brand, excluding JP, owned by Sony Music Entertainment (1991 ongoing) | [[https://musicbrainz.org/label/9e6b4d7f-4958-4db7-8504-d89e315836af][9e6b4d7f-4958-4db7-8504-d89e315836af]] |
102 | 96 | [no label] | Special purpose label – white labels, self-published releases and other “no label” releases (ongoing) | [[https://musicbrainz.org/label/157afde4-4bf5-4039-8ad2-5a15acc85176][157afde4-4bf5-4039-8ad2-5a15acc85176]] |
103 | 91 | Polydor | worldwide imprint, see annotation (1913-04-02 ongoing) | [[https://musicbrainz.org/label/ce24ab18-1bd6-4293-a486-546d13d6a5e2][ce24ab18-1bd6-4293-a486-546d13d6a5e2]] |
104 | 91 | Universal Music | plain logo: “Universal Music” (ongoing) | [[https://musicbrainz.org/label/13a464dc-b9fd-4d16-a4f4-d4316f6a46c7][13a464dc-b9fd-4d16-a4f4-d4316f6a46c7]] |
105 | 90 | ZYX Music | (1992 ongoing) | [[https://musicbrainz.org/label/6844efda-a451-431e-8cc1-48ab111b4711][6844efda-a451-431e-8cc1-48ab111b4711]] |
109 Cover art for a release may be available from the [[http://coverartarchive.org/][Cover Art Archive]] and can be accessed via the [[https://musicbrainz.org/doc/Cover_Art_Archive/API][API]]
111 #+BEGIN_SRC emacs-lisp
112 (musicbrainz-coverart "a929130a-535c-4827-8663-f048e1a7ca0d")
116 #+BEGIN_SRC emacs-lisp
117 (musicbrainz-coverart-front "a929130a-535c-4827-8663-f048e1a7ca0d")
121 #+BEGIN_SRC emacs-lisp
122 (musicbrainz-lookup-release "a929130a-535c-4827-8663-f048e1a7ca0d")
125 | Head Cleaning Cassette | Cassette Case | [[https://musicbrainz.org/release/a929130a-535c-4827-8663-f048e1a7ca0d][a929130a-535c-4827-8663-f048e1a7ca0d]] |
129 “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
131 #+BEGIN_SRC emacs-lisp
132 (musicbrainz-artist-to-mbid "Autechre")
135 returns =410c9baf-5469-44f6-9852-826524b80c61=
137 #+BEGIN_SRC emacs-lisp
138 (musicbrainz-mbid-p "410c9baf-5469-44f6-9852-826524b80c61")
147 John Williams, the soundtrack composer and conductor, has an artist MBID of 53b106e7-0cc6-42cc-ac95-ed8d30a3a98e
148 John Williams, the classical guitar player, has an artist MBID of 8b8a38a9-a290-4560-84f6-3d4466e8d791
151 #+BEGIN_SRC emacs-lisp
152 (musicbrainz-disambiguate-artist "John Williams" 3)
155 | | Artist: John Williams | MBID |
156 | 100 | John Williams, American score composer | [[https://musicbrainz.org/artist/53b106e7-0cc6-42cc-ac95-ed8d30a3a98e][53b106e7-0cc6-42cc-ac95-ed8d30a3a98e]] |
157 | 94 | John Williams, classical guitarist | [[https://musicbrainz.org/artist/8b8a38a9-a290-4560-84f6-3d4466e8d791][8b8a38a9-a290-4560-84f6-3d4466e8d791]] |
158 | 92 | John Williams, English A&R executive, producer, songwriter... | [[https://musicbrainz.org/artist/eb5d7680-0c00-4b0c-b6eb-9605ff77723d][eb5d7680-0c00-4b0c-b6eb-9605ff77723d]] |
160 There are several “Bad Seeds”
162 #+BEGIN_SRC emacs-lisp
163 (musicbrainz-artist-to-mbid "Bad Seeds")
166 Which returns the MBID =7feb02f2-51fa-422d-838e-2c14ecb4c7b8= for “Tomorrows Bad Seeds”, however…
168 #+BEGIN_SRC emacs-lisp
169 (musicbrainz-disambiguate-artist "Bad Seeds" 7)
172 | | Artist: Bad Seeds | MBID |
173 | 100 | Tomorrows Bad Seeds, nil | [[https://musicbrainz.org/artist/7feb02f2-51fa-422d-838e-2c14ecb4c7b8][7feb02f2-51fa-422d-838e-2c14ecb4c7b8]] |
174 | 98 | The Bad Seeds, 60s Texas rock band | [[https://musicbrainz.org/artist/3e593712-9f70-4b7a-b21b-466016998a3d][3e593712-9f70-4b7a-b21b-466016998a3d]] |
175 | 98 | The Bad Seeds, 60's US garage rock band from Erlanger, KY | [[https://musicbrainz.org/artist/34bc9a97-fa78-424e-8ca8-a904f978f041][34bc9a97-fa78-424e-8ca8-a904f978f041]] |
176 | 98 | The Bad Seeds, backing band for Nick Cave | [[https://musicbrainz.org/artist/eb2a8edc-5670-4896-82be-87db38de9583][eb2a8edc-5670-4896-82be-87db38de9583]] |
177 | 86 | Nick Cave & the Bad Seeds, nil | [[https://musicbrainz.org/artist/172e1f1a-504d-4488-b053-6344ba63e6d0][172e1f1a-504d-4488-b053-6344ba63e6d0]] |
178 | 50 | The Lightning Seeds, nil | [[https://musicbrainz.org/artist/1ba601a0-3401-4b28-8ddd-9af8203661e8][1ba601a0-3401-4b28-8ddd-9af8203661e8]] |
179 | 49 | Seeds, UK dancehall | [[https://musicbrainz.org/artist/a03cf587-a3d3-4847-ac41-e488f779a313][a03cf587-a3d3-4847-ac41-e488f779a313]] |
181 #+BEGIN_SRC emacs-lisp
182 (musicbrainz-lookup-artist "172e1f1a-504d-4488-b053-6344ba63e6d0")
187 general, specific and partial API coverage
189 *** Searching & browsing
191 Search supports the full [[https://lucene.apache.org/core/7_7_2/queryparser/org/apache/lucene/queryparser/classic/package-summary.html#package.description][Lucene search syntax]] in queries.
193 | (musicbrainz-search /type/ /query/ &optional /limit/ /offset/) | see =musicbrainz-search-types= |
194 | (musicbrainz-browse /entity/ /link/ /query/ &optional /type/) | and =musicbrainz-entities-*= |
196 | (musicbrainz-search-artist /artist/ &optional /limit/) | |
197 | (musicbrainz-artist-to-mbid /artist/) | |
198 | (musicbrainz-disambiguate-artist /artist/ &optional /limit/) | |
199 | (musicbrainz-search-label /label/ &optional /limit/) | |
200 | (musicbrainz-search-recording /query/ &optional /limit/) | |
201 | (musicbrainz-search-release /query/ &optional /limit/) | |
202 | (musicbrainz-search-work /query/ &optional /limit/) | |
204 *** Lookup queries & subqueries
206 | (musicbrainz-lookup /entity/ /MBID/ &optional /inc/) | valid entities listed in =musicbrainz-entities-core= |
208 | *Functions & formatted output* | example MBID |
209 | (musicbrainz-lookup-area /MBID/) | [[https://musicbrainz.org/area/c9ac1239-e832-41bc-9930-e252a1fd1105][c9ac1239-e832-41bc-9930-e252a1fd1105]] |
210 | (musicbrainz-lookup-artist /MBID/) | [[https://musicbrainz.org/artist/410c9baf-5469-44f6-9852-826524b80c61][410c9baf-5469-44f6-9852-826524b80c61]] |
211 | (musicbrainz-lookup-artist-recordings /MBID/) | … |
212 | (musicbrainz-lookup-artist-releases /MBID/) | … |
213 | (musicbrainz-lookup-artist-release-groups /MBID/) | … |
214 | (musicbrainz-lookup-artist-works /MBID/) | … |
215 | (musicbrainz-lookup-collection /MBID/) | … |
216 | (musicbrainz-lookup-collection-user-collections /MBID/) | … |
217 | (musicbrainz-lookup-event /MBID/) | [[https://musicbrainz.org/event/7c132556-e902-4481-b9cb-ec76a175628a][7c132556-e902-4481-b9cb-ec76a175628a]] |
218 | (musicbrainz-lookup-genre /MBID/) | [[https://musicbrainz.org/genre/68c81274-5770-4e7b-a4bf-ab0d7d425d99][68c81274-5770-4e7b-a4bf-ab0d7d425d99]] |
219 | (musicbrainz-lookup-instrument /MBID/) | [[https://musicbrainz.org/instrument/303d4f1a-f799-4c42-9bac-dbedd9139e91][303d4f1a-f799-4c42-9bac-dbedd9139e91]] |
220 | (musicbrainz-lookup-label /MBID/) | [[https://musicbrainz.org/label/8943d408-940c-403b-a01d-9036c227d50f][8943d408-940c-403b-a01d-9036c227d50f]] |
221 | (musicbrainz-lookup-label-releases /MBID/) | … |
222 | (musicbrainz-lookup-place /MBID/) | [[https://musicbrainz.org/place/73cba8a4-cacb-45b9-8e02-654f716e2e7a][73cba8a4-cacb-45b9-8e02-654f716e2e7a]] |
223 | (musicbrainz-lookup-recording /MBID/) | [[https://musicbrainz.org/recording/ef8b34c1-8548-472c-872f-03e0d8d3bb37][ef8b34c1-8548-472c-872f-03e0d8d3bb37]] |
224 | (musicbrainz-lookup-recording-artists /MBID/) | … |
225 | (musicbrainz-lookup-recording-releases /MBID/) | … |
226 | (musicbrainz-lookup-recording-isrcs /MBID/) | … |
227 | (musicbrainz-lookup-recording-url-rels /MBID/) | … |
228 | (musicbrainz-lookup-release /MBID/) | … |
229 | (musicbrainz-lookup-release-artists /MBID/) | … |
230 | (musicbrainz-lookup-release-collections /MBID/) | … |
231 | (musicbrainz-lookup-release-labels /MBID/) | … |
232 | (musicbrainz-lookup-release-recordings /MBID/) | … |
233 | (musicbrainz-lookup-release-release-groups /MBID/) | … |
234 | (musicbrainz-lookup-release-group /MBID/) | [[https://musicbrainz.org/release-group/fe4acfe9-6d1e-3565-8857-fb16ddc492ab][fe4acfe9-6d1e-3565-8857-fb16ddc492ab]] |
235 | (musicbrainz-lookup-release-group-artists /MBID/) | … |
236 | (musicbrainz-lookup-release-group-releases /MBID/) | … |
237 | (musicbrainz-lookup-series /MBID/) | … |
238 | (musicbrainz-lookup-work /MBID/) | [[https://musicbrainz.org/work/4ee2545d-2be5-3841-b568-0b4554eccc67][4ee2545d-2be5-3841-b568-0b4554eccc67]] |
239 | (musicbrainz-lookup-url /MBID/) | … |
244 [[file:img/listenbrainz-logo.svg]]
248 - https://listenbrainz.org
249 - https://listenbrainz.readthedocs.io/
253 #+BEGIN_SRC emacs-lisp
254 (setq listenbrainz-api-token "000-000-000")
257 #+BEGIN_SRC emacs-lisp
258 (listenbrainz-validate-token listenbrainz-api-token)
261 #+BEGIN_SRC emacs-lisp
262 (listenbrainz-listens "zzzkt")
265 #+BEGIN_SRC emacs-lisp
266 (listenbrainz-listens "zzzkt" 33)
269 #+BEGIN_SRC emacs-lisp
270 (listenbrainz-submit-single-listen "Matthew Thomas" "Taema" "Architecture")
273 #+BEGIN_SRC emacs-lisp
274 (listenbrainz-submit-single-listen "farmersmanual" "808808008088 (11)")
277 #+BEGIN_SRC emacs-lisp
278 (listenbrainz-submit-playing-now "farmersmanual" "808808008088 (11)")
281 #+BEGIN_SRC emacs-lisp
282 (listenbrainz-playing-now "zzzkt")
285 #+BEGIN_SRC emacs-lisp
286 (listenbrainz-stats-artists "zzzkt")
289 #+BEGIN_SRC emacs-lisp
290 (listenbrainz-stats-releases "zzzkt")
293 #+BEGIN_SRC emacs-lisp
294 (listenbrainz-stats-recordings "zzzkt" 13 "month")
298 *** Core API endpoints
300 https://listenbrainz.readthedocs.io/en/production/dev/api/#core-api-endpoints
302 | POST /1/submit-listens | listenbrainz-submit-listen |
303 | | listenbrainz-submit-single-listen |
304 | | listenbrainz-submit-playing-now |
305 | GET /1/validate-token | listenbrainz-validate-token |
306 | POST /1/delete-listen | - |
307 | GET /1/user/(playlist_user_name)/playlists/collaborator | - |
308 | GET /1/user/(playlist_user_name)/playlists/createdfor | - |
309 | GET /1/users/(user_list)/recent-listens | - |
310 | GET /1/user/(user_name)/similar-users | - |
311 | GET /1/user/(user_name)/listen-count | - |
312 | GET /1/user/(user_name)/playing-now | listenbrainz-playing-now |
313 | GET /1/user/(user_name)/similar-to/(other_user_name) | - |
314 | GET /1/user/(playlist_user_name)/playlists | - |
315 | GET /1/user/(user_name)/listens | listenbrainz-listens |
316 | GET /1/latest-import | - |
317 | POST /1/latest-import | - |
319 *** Feedback API Endpoints
321 https://listenbrainz.readthedocs.io/en/production/dev/api/#feedback-api-endpoints
323 | POST /1/feedback/recording-feedback | - |
324 | GET /1/feedback/recording/(recording_msid)/get-feedback | - |
325 | GET /1/feedback/user/(user_name)/get-feedback-for-recordings | – |
326 | GET /1/feedback/user/(user_name)/get-feedback | - |
328 *** Recording Recommendation API Endpoints
330 https://listenbrainz.readthedocs.io/en/production/dev/api/#core-api-endpoints
332 | GET /1/cf/recommendation/user/(user_name)/recording | - |
334 *** Recording Recommendation Feedback API Endpoints
336 https://listenbrainz.readthedocs.io/en/production/dev/api/#recording-recommendation-feedback-api-endpoints
338 | POST /1/recommendation/feedback/submit | - |
339 | POST /1/recommendation/feedback/delete | - |
340 | GET /1/recommendation/feedback/user/(user_name)/recordings | - |
341 | GET /1/recommendation/feedback/user/(user_name) | - |
343 *** Statistics API Endpoints
345 https://listenbrainz.readthedocs.io/en/production/dev/api/#statistics-api-endpoints
347 | GET /1/stats/sitewide/artists | - |
348 | GET /1/stats/user/(user_name)/listening-activity | - |
349 | GET /1/stats/user/(user_name)/daily-activity | - |
350 | GET /1/stats/user/(user_name)/recordings | listenbrainz-stats-recordings |
351 | GET /1/stats/user/(user_name)/artist-map | - |
352 | GET /1/stats/user/(user_name)/releases | listenbrainz-stats-releases |
353 | GET /1/stats/user/(user_name)/artists | listenbrainz-stats-artists |
355 *** Status API Endpoints
357 https://listenbrainz.readthedocs.io/en/production/dev/api/#status-api-endpoints
359 | GET /1/status/get-dump-info | - |
361 *** User Timeline API Endpoints
363 https://listenbrainz.readthedocs.io/en/production/dev/api/#user-timeline-api-endpoints
365 | POST /1/user/(user_name)/timeline-event/create/notification | - |
366 | POST /1/user/(user_name)/timeline-event/create/recording | - |
367 | POST /1/user/(user_name)/feed/events/delete | - |
368 | GET /1/user/(user_name)/feed/events | - |
370 *** Social API Endpoints
372 https://listenbrainz.readthedocs.io/en/production/dev/api/#social-api-endpoints
374 | GET /1/user/(user_name)/followers | listenbrainz-followers |
375 | GET /1/user/(user_name)/following | listenbrainz-following |
376 | POST /1/user/(user_name)/unfollow | - |
377 | POST /1/user/(user_name)/follow | - |
379 *** Pinned Recording API Endpoints
381 https://listenbrainz.readthedocs.io/en/production/dev/api/#pinned-recording-api-endpoints
383 | POST /1/pin/unpin | - |
385 | POST /1/pin/delete/(row_id) | - |
386 | GET /1/(user_name)/pins/following | - |
387 | GET /1/(user_name)/pins | - |
390 - [[https://critiquebrainz.org/][CritiqueBrainz]]
391 - [[https://bookbrainz.org/][BookBrainz]] → https://api.test.bookbrainz.org/1/docs/
392 - [[https://listenbrainz.org/messybrainz/][MessyBrainz]]
393 - [[https://coverartarchive.org/][Cover art archive]]
396 - https://labs.api.listenbrainz.org/
397 - https://troi.readthedocs.io/en/latest/
398 - https://listenbrainz.org/user/troi-bot/playlists/
399 - https://github.com/metabrainz/bono-data-sets/blob/main/top_discoveries.py