]> git.vanrenterghem.biz Git - musicbrainz.git/blob - README.org
Support individual historic listens submittion.
[musicbrainz.git] / README.org
1 # -*- mode: org; coding: utf-8; -*-
2 #+OPTIONS: toc:2 num:nil html-style:nil
3 #+author:
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]]
11     - [[#mbid][MBID]]
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]]
21 * MusicBrainz
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.
29 ** MusicBrainz API
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]].
39 ** some examples
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")
46 #+END_SRC
48 For slightly more legible output wrap with =musicbrainz-format=
49 #+BEGIN_SRC emacs-lisp
50 (musicbrainz-format
51  (musicbrainz-browse "release-group"
52                      "artist"
53                      "410c9baf-5469-44f6-9852-826524b80c61"
54                      "album|ep"))
55 #+END_SRC
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")
63 #+END_SRC
65 #+BEGIN_SRC emacs-lisp
66 (musicbrainz-lookup-artist "410c9baf-5469-44f6-9852-826524b80c61")
67 #+END_SRC
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")
73 #+END_SRC
75 #+BEGIN_SRC emacs-lisp
76 (musicbrainz-lookup-artist-recordings "410c9baf-5469-44f6-9852-826524b80c61")
77 #+END_SRC
79 #+BEGIN_SRC emacs-lisp
80 (musicbrainz-lookup-release "ec1ecfcc-f529-43d1-8aa6-2c7051ede00c")
81 #+END_SRC
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")
87 #+END_SRC
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")
93 #+END_SRC
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)
99 #+END_SRC
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]] |
107 ** cover art
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")
113 #+END_SRC
116 #+BEGIN_SRC emacs-lisp
117 (musicbrainz-coverart-front "a929130a-535c-4827-8663-f048e1a7ca0d")
118 #+END_SRC
121 #+BEGIN_SRC emacs-lisp
122 (musicbrainz-lookup-release "a929130a-535c-4827-8663-f048e1a7ca0d")
123 #+END_SRC
125  | Head Cleaning Cassette | Cassette Case | [[https://musicbrainz.org/release/a929130a-535c-4827-8663-f048e1a7ca0d][a929130a-535c-4827-8663-f048e1a7ca0d]] |
127 ** MBID
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")
133 #+END_SRC
135 returns =410c9baf-5469-44f6-9852-826524b80c61=
137 #+BEGIN_SRC emacs-lisp
138 (musicbrainz-mbid-p "410c9baf-5469-44f6-9852-826524b80c61")
139 #+END_SRC
142 ** ambiguity
144 From the docs…
146 #+BEGIN_SRC text
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
149 #+END_SRC
151 #+BEGIN_SRC emacs-lisp
152 (musicbrainz-disambiguate-artist "John Williams" 3)
153 #+END_SRC
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")
164 #+END_SRC
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)
170 #+END_SRC
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")
183 #+END_SRC
185 ** incompleteness
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/)                         | …                                    |
241 * ListenBrainz
244 [[file:img/listenbrainz-logo.svg]]
246 ** listening
248 - https://listenbrainz.org
249 - https://listenbrainz.readthedocs.io/
251 ** examples
253 #+BEGIN_SRC emacs-lisp
254 (setq listenbrainz-api-token "000-000-000")
255 #+END_SRC
257 #+BEGIN_SRC emacs-lisp
258 (listenbrainz-validate-token listenbrainz-api-token)
259 #+END_SRC
261 #+BEGIN_SRC emacs-lisp
262 (listenbrainz-listens "zzzkt")
263 #+END_SRC
265 #+BEGIN_SRC emacs-lisp
266 (listenbrainz-listens "zzzkt" 33)
267 #+END_SRC
269 #+BEGIN_SRC emacs-lisp
270 (listenbrainz-submit-single-listen "Matthew Thomas" "Taema" "Architecture")
271 #+END_SRC
273 #+BEGIN_SRC emacs-lisp
274 (listenbrainz-submit-single-listen "farmersmanual" "808808008088 (11)")
275 #+END_SRC
277 #+BEGIN_SRC emacs-lisp
278 (listenbrainz-submit-playing-now "farmersmanual" "808808008088 (11)")
279 #+END_SRC
281 #+BEGIN_SRC emacs-lisp
282 (listenbrainz-playing-now "zzzkt")
283 #+END_SRC
285 #+BEGIN_SRC emacs-lisp
286 (listenbrainz-stats-artists "zzzkt")
287 #+END_SRC
289 #+BEGIN_SRC emacs-lisp
290 (listenbrainz-stats-releases "zzzkt")
291 #+END_SRC
293 #+BEGIN_SRC emacs-lisp
294 (listenbrainz-stats-recordings "zzzkt" 13 "month")
295 #+END_SRC
297 ** incompleteness
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                 | - |
384 | POST /1/pin                       | - |
385 | POST /1/pin/delete/(row_id)       | - |
386 | GET /1/(user_name)/pins/following | - |
387 | GET /1/(user_name)/pins           | - |
389 * otherBrainz
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]]
395 * further
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