README.org

   1 # -*- mode: org; coding: utf-8; -*-
   2 #+OPTIONS: toc:2 num:nil html-style:nil
   3 #+author:
   4 #+title:  MusicBrainz & ListenBrainz & others
   5
   6 * MusicBrainz
   7
   8 [[file:img/musicbrainz-logo.svg]]
   9
  10 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.
  11
  12 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.
  13
  14 ** MusicBrainz API
  15
  16 - Recording documentation: https://musicbrainz.org/doc/Recording
  17 - Release documentation: https://musicbrainz.org/doc/Release
  18 - Artist documentation: https://musicbrainz.org/doc/Artist
  19
  20 ** searching & browsing
  21
  22 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]].
  23
  24 ** some examples
  25
  26 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
  27
  28 The equivalent function (which returns a raw response as an alist) would be…
  29 #+BEGIN_SRC emacs-lisp
  30 (musicbrainz-browse "release-group" "artist" "410c9baf-5469-44f6-9852-826524b80c61" "album|ep")
  31 #+END_SRC
  32
  33 For slightly more legible output wrap with =musicbrainz-format=
  34 #+BEGIN_SRC emacs-lisp
  35 (musicbrainz-format
  36  (musicbrainz-browse "release-group"
  37                      "artist"
  38                      "410c9baf-5469-44f6-9852-826524b80c61"
  39                      "album|ep"))
  40 #+END_SRC
  41
  42 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=
  43
  44 The MBID can be used for specific lookups (and checked if needed using =musicbrainz-mbid-p= )
  45
  46 #+BEGIN_SRC emacs-lisp
  47 (musicbrainz-lookup "artist" "410c9baf-5469-44f6-9852-826524b80c61" "releases")
  48 #+END_SRC
  49
  50 #+BEGIN_SRC emacs-lisp
  51 (musicbrainz-lookup-artist "410c9baf-5469-44f6-9852-826524b80c61")
  52 #+END_SRC
  53
  54 | Autechre | electronic music duo | Group | [[https://musicbrainz.org/artist/410c9baf-5469-44f6-9852-826524b80c61][410c9baf-5469-44f6-9852-826524b80c61]] |
  55
  56 #+BEGIN_SRC emacs-lisp
  57 (musicbrainz-lookup-artist-releases "410c9baf-5469-44f6-9852-826524b80c61")
  58 #+END_SRC
  59
  60 #+BEGIN_SRC emacs-lisp
  61 (musicbrainz-lookup-artist-recordings "410c9baf-5469-44f6-9852-826524b80c61")
  62 #+END_SRC
  63
  64 #+BEGIN_SRC emacs-lisp
  65 (musicbrainz-lookup-release "ec1ecfcc-f529-43d1-8aa6-2c7051ede00c")
  66 #+END_SRC
  67
  68 | 1990 | Autechre / Saw You | Cassette Case | [[https://musicbrainz.org/release/ec1ecfcc-f529-43d1-8aa6-2c7051ede00c][ec1ecfcc-f529-43d1-8aa6-2c7051ede00c]] |
  69
  70 #+BEGIN_SRC emacs-lisp
  71 (musicbrainz-lookup-recording "83730176-89ec-41a5-a4b6-476998f6291c")
  72 #+END_SRC
  73
  74 | [untitled] | [[https://musicbrainz.org/recording/83730176-89ec-41a5-a4b6-476998f6291c][83730176-89ec-41a5-a4b6-476998f6291c]] |
  75
  76 #+BEGIN_SRC emacs-lisp
  77 (musicbrainz-search-label "Warp")
  78 #+END_SRC
  79
  80 | Warp | [[https://musicbrainz.org/label/46f0f4cd-8aab-4b33-b698-f459faf64190][46f0f4cd-8aab-4b33-b698-f459faf64190]] |
  81
  82 #+BEGIN_SRC emacs-lisp
  83 (musicbrainz-search-label "Music" 5)
  84 #+END_SRC
  85
  86 | 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]] |
  87 |  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]] |
  88 |  91 | Polydor         | worldwide imprint, see annotation (1913-04-02 ongoing)                                                | [[https://musicbrainz.org/label/ce24ab18-1bd6-4293-a486-546d13d6a5e2][ce24ab18-1bd6-4293-a486-546d13d6a5e2]] |
  89 |  91 | Universal Music | plain logo: “Universal Music” (ongoing)                                                               | [[https://musicbrainz.org/label/13a464dc-b9fd-4d16-a4f4-d4316f6a46c7][13a464dc-b9fd-4d16-a4f4-d4316f6a46c7]] |
  90 |  90 | ZYX Music       | (1992 ongoing)                                                                                        | [[https://musicbrainz.org/label/6844efda-a451-431e-8cc1-48ab111b4711][6844efda-a451-431e-8cc1-48ab111b4711]] |
  91
  92
  93 ** MBID
  94
  95 “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
  96
  97 #+BEGIN_SRC emacs-lisp
  98 (musicbrainz-artist-to-mbid "Autechre")
  99 #+END_SRC
 100
 101 returns =410c9baf-5469-44f6-9852-826524b80c61=
 102
 103 #+BEGIN_SRC emacs-lisp
 104 (musicbrainz-mbid-p "410c9baf-5469-44f6-9852-826524b80c61")
 105 #+END_SRC
 106
 107 ** ambiguity
 108
 109 From the docs…
 110
 111 #+BEGIN_SRC text
 112 John Williams, the soundtrack composer and conductor, has an artist MBID of 53b106e7-0cc6-42cc-ac95-ed8d30a3a98e
 113 John Williams, the classical guitar player, has an artist MBID of 8b8a38a9-a290-4560-84f6-3d4466e8d791
 114 #+END_SRC
 115
 116 #+BEGIN_SRC emacs-lisp
 117 (musicbrainz-disambiguate-artist "John Williams" 3)
 118 #+END_SRC
 119
 120 |     | Artist: John Williams                                         | MBID                                 |
 121 | 100 | John Williams, American score composer                        | [[https://musicbrainz.org/artist/53b106e7-0cc6-42cc-ac95-ed8d30a3a98e][53b106e7-0cc6-42cc-ac95-ed8d30a3a98e]] |
 122 |  94 | John Williams, classical guitarist                            | [[https://musicbrainz.org/artist/8b8a38a9-a290-4560-84f6-3d4466e8d791][8b8a38a9-a290-4560-84f6-3d4466e8d791]] |
 123 |  92 | John Williams, English A&R executive, producer, songwriter... | [[https://musicbrainz.org/artist/eb5d7680-0c00-4b0c-b6eb-9605ff77723d][eb5d7680-0c00-4b0c-b6eb-9605ff77723d]] |
 124
 125 There are several “Bad Seeds”
 126
 127 #+BEGIN_SRC emacs-lisp
 128 (musicbrainz-artist-to-mbid "Bad Seeds")
 129 #+END_SRC
 130
 131 Which returns the MBID =7feb02f2-51fa-422d-838e-2c14ecb4c7b8= for “Tomorrows Bad Seeds”, however…
 132
 133 #+BEGIN_SRC emacs-lisp
 134 (musicbrainz-disambiguate-artist "Bad Seeds" 7)
 135 #+END_SRC
 136
 137 |     | Artist: Bad Seeds                                         | MBID                                 |
 138 | 100 | Tomorrows Bad Seeds, nil                                  | [[https://musicbrainz.org/artist/7feb02f2-51fa-422d-838e-2c14ecb4c7b8][7feb02f2-51fa-422d-838e-2c14ecb4c7b8]] |
 139 |  98 | The Bad Seeds, 60s Texas rock band                        | [[https://musicbrainz.org/artist/3e593712-9f70-4b7a-b21b-466016998a3d][3e593712-9f70-4b7a-b21b-466016998a3d]] |
 140 |  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]] |
 141 |  98 | The Bad Seeds, backing band for Nick Cave                 | [[https://musicbrainz.org/artist/eb2a8edc-5670-4896-82be-87db38de9583][eb2a8edc-5670-4896-82be-87db38de9583]] |
 142 |  86 | Nick Cave & the Bad Seeds, nil                            | [[https://musicbrainz.org/artist/172e1f1a-504d-4488-b053-6344ba63e6d0][172e1f1a-504d-4488-b053-6344ba63e6d0]] |
 143 |  50 | The Lightning Seeds, nil                                  | [[https://musicbrainz.org/artist/1ba601a0-3401-4b28-8ddd-9af8203661e8][1ba601a0-3401-4b28-8ddd-9af8203661e8]] |
 144 |  49 | Seeds, UK dancehall                                       | [[https://musicbrainz.org/artist/a03cf587-a3d3-4847-ac41-e488f779a313][a03cf587-a3d3-4847-ac41-e488f779a313]] |
 145
 146 #+BEGIN_SRC emacs-lisp
 147 (musicbrainz-lookup-artist "172e1f1a-504d-4488-b053-6344ba63e6d0")
 148 #+END_SRC
 149
 150 ** incompleteness
 151
 152 general, specific and partial API coverage
 153
 154 *** Searching & browsing
 155
 156 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.
 157
 158 | (musicbrainz-search /type/ /query/ &optional /limit/ /offset/) | see =musicbrainz-search-types= |
 159 | (musicbrainz-browse /entity/ /link/ /query/ &optional /type/)  | and =musicbrainz-entities-*=   |
 160
 161 | (musicbrainz-search-artist /artist/ &optional /limit/)       |   |
 162 | (musicbrainz-artist-to-mbid /artist/)                      |   |
 163 | (musicbrainz-disambiguate-artist /artist/ &optional /limit/) |   |
 164 | (musicbrainz-search-label /label/ &optional /limit/)         |   |
 165 | (musicbrainz-search-recording /query/ &optional /limit/)     |   |
 166 | (musicbrainz-search-release /query/ &optional /limit/)       |   |
 167 | (musicbrainz-search-work /query/ &optional /limit/)   |   |
 168
 169 *** Lookup queries & subqueries
 170
 171 | (musicbrainz-lookup /entity/ /MBID/ &optional /inc/) | valid entities listed in =musicbrainz-entities-core= |
 172
 173 | *Functions & formatted output*                          | example MBID                         |
 174 | (musicbrainz-lookup-area /MBID/)                        | [[https://musicbrainz.org/area/c9ac1239-e832-41bc-9930-e252a1fd1105][c9ac1239-e832-41bc-9930-e252a1fd1105]] |
 175 | (musicbrainz-lookup-artist /MBID/)                      | [[https://musicbrainz.org/artist/410c9baf-5469-44f6-9852-826524b80c61][410c9baf-5469-44f6-9852-826524b80c61]] |
 176 | (musicbrainz-lookup-artist-recordings /MBID/)           | …                                    |
 177 | (musicbrainz-lookup-artist-releases /MBID/)             | …                                    |
 178 | (musicbrainz-lookup-artist-release-groups /MBID/)       | …                                    |
 179 | (musicbrainz-lookup-artist-works /MBID/)                | …                                    |
 180 | (musicbrainz-lookup-collection /MBID/)                  | …                                    |
 181 | (musicbrainz-lookup-collection-user-collections /MBID/) | …                                    |
 182 | (musicbrainz-lookup-event /MBID/)                       | [[https://musicbrainz.org/event/7c132556-e902-4481-b9cb-ec76a175628a][7c132556-e902-4481-b9cb-ec76a175628a]] |
 183 | (musicbrainz-lookup-genre /MBID/)                       | [[https://musicbrainz.org/genre/68c81274-5770-4e7b-a4bf-ab0d7d425d99][68c81274-5770-4e7b-a4bf-ab0d7d425d99]] |
 184 | (musicbrainz-lookup-instrument /MBID/)                  | [[https://musicbrainz.org/instrument/303d4f1a-f799-4c42-9bac-dbedd9139e91][303d4f1a-f799-4c42-9bac-dbedd9139e91]] |
 185 | (musicbrainz-lookup-label /MBID/)                       | [[https://musicbrainz.org/label/8943d408-940c-403b-a01d-9036c227d50f][8943d408-940c-403b-a01d-9036c227d50f]] |
 186 | (musicbrainz-lookup-label-releases /MBID/)              | …                                    |
 187 | (musicbrainz-lookup-place /MBID/)                       | [[https://musicbrainz.org/place/73cba8a4-cacb-45b9-8e02-654f716e2e7a][73cba8a4-cacb-45b9-8e02-654f716e2e7a]] |
 188 | (musicbrainz-lookup-recording /MBID/)                   | [[https://musicbrainz.org/recording/ef8b34c1-8548-472c-872f-03e0d8d3bb37][ef8b34c1-8548-472c-872f-03e0d8d3bb37]] |
 189 | (musicbrainz-lookup-recording-artists /MBID/)           | …                                    |
 190 | (musicbrainz-lookup-recording-releases /MBID/)          | …                                    |
 191 | (musicbrainz-lookup-recording-isrcs /MBID/)             | …                                    |
 192 | (musicbrainz-lookup-recording-url-rels /MBID/)          | …                                    |
 193 | (musicbrainz-lookup-release /MBID/)                     | …                                    |
 194 | (musicbrainz-lookup-release-artists /MBID/)             | …                                    |
 195 | (musicbrainz-lookup-release-collections /MBID/)         | …                                    |
 196 | (musicbrainz-lookup-release-labels /MBID/)              | …                                    |
 197 | (musicbrainz-lookup-release-recordings /MBID/)          | …                                    |
 198 | (musicbrainz-lookup-release-release-groups /MBID/)      | …                                    |
 199 | (musicbrainz-lookup-release-group /MBID/)               | [[https://musicbrainz.org/release-group/fe4acfe9-6d1e-3565-8857-fb16ddc492ab][fe4acfe9-6d1e-3565-8857-fb16ddc492ab]] |
 200 | (musicbrainz-lookup-release-group-artists /MBID/)       | …                                    |
 201 | (musicbrainz-lookup-release-group-releases /MBID/)      | …                                    |
 202 | (musicbrainz-lookup-series /MBID/)                      | …                                    |
 203 | (musicbrainz-lookup-work /MBID/)                        | [[https://musicbrainz.org/work/4ee2545d-2be5-3841-b568-0b4554eccc67][4ee2545d-2be5-3841-b568-0b4554eccc67]] |
 204 | (musicbrainz-lookup-url /MBID/)                         | …                                    |
 205
 206
 207 * ListenBrainz
 208
 209
 210 [[file:img/listenbrainz-logo.svg]]
 211
 212 ** listening
 213
 214 - https://listenbrainz.org
 215 - https://listenbrainz.readthedocs.io/
 216
 217 ** examples
 218
 219 #+BEGIN_SRC emacs-lisp
 220 (setq listenbrainz-api-token "000-000-000")
 221 #+END_SRC
 222
 223 #+BEGIN_SRC emacs-lisp
 224 (listenbrainz-validate-token listenbrainz-api-token)
 225 #+END_SRC
 226
 227 #+BEGIN_SRC emacs-lisp
 228 (listenbrainz-listens "zzzkt")
 229 #+END_SRC
 230
 231 #+BEGIN_SRC emacs-lisp
 232 (listenbrainz-listens "zzzkt" 33)
 233 #+END_SRC
 234
 235 #+BEGIN_SRC emacs-lisp
 236 (listenbrainz-submit-single-listen "Matthew Thomas" "Taema" "Architecture")
 237 #+END_SRC
 238
 239 #+BEGIN_SRC emacs-lisp
 240 (listenbrainz-submit-single-listen "farmersmanual" "808808008088 (11)")
 241 #+END_SRC
 242
 243 #+BEGIN_SRC emacs-lisp
 244 (listenbrainz-submit-playing-now "farmersmanual" "808808008088 (11)")
 245 #+END_SRC
 246
 247 #+BEGIN_SRC emacs-lisp
 248 (listenbrainz-playing-now "zzzkt")
 249 #+END_SRC
 250
 251 #+BEGIN_SRC emacs-lisp
 252 (listenbrainz-stats-artists "zzzkt")
 253 #+END_SRC
 254
 255 #+BEGIN_SRC emacs-lisp
 256 (listenbrainz-stats-releases "zzzkt")
 257 #+END_SRC
 258
 259 #+BEGIN_SRC emacs-lisp
 260 (listenbrainz-stats-recordings "zzzkt" 13 "month")
 261 #+END_SRC
 262
 263 ** incompleteness
 264 *** Core API endpoints
 265
 266 https://listenbrainz.readthedocs.io/en/production/dev/api/#core-api-endpoints
 267
 268 | POST /1/submit-listens                                  | listenbrainz-submit-listen        |
 269 |                                                         | listenbrainz-submit-single-listen |
 270 |                                                         | listenbrainz-submit-playing-now   |
 271 | GET /1/validate-token                                   | listenbrainz-validate-token       |
 272 | POST /1/delete-listen                                   | -                                 |
 273 | GET /1/user/(playlist_user_name)/playlists/collaborator | -                                 |
 274 | GET /1/user/(playlist_user_name)/playlists/createdfor   | -                                 |
 275 | GET /1/users/(user_list)/recent-listens                 | -                                 |
 276 | GET /1/user/(user_name)/similar-users                   | -                                 |
 277 | GET /1/user/(user_name)/listen-count                    | -                                 |
 278 | GET /1/user/(user_name)/playing-now                     | listenbrainz-playing-now          |
 279 | GET /1/user/(user_name)/similar-to/(other_user_name)    | -                                 |
 280 | GET /1/user/(playlist_user_name)/playlists              | -                                 |
 281 | GET /1/user/(user_name)/listens                         | listenbrainz-listens              |
 282 | GET /1/latest-import                                    | -                                 |
 283 | POST /1/latest-import                                   | -                                 |
 284
 285 *** Feedback API Endpoints
 286
 287 https://listenbrainz.readthedocs.io/en/production/dev/api/#feedback-api-endpoints
 288
 289 | POST /1/feedback/recording-feedback                          | - |
 290 | GET /1/feedback/recording/(recording_msid)/get-feedback      | - |
 291 | GET /1/feedback/user/(user_name)/get-feedback-for-recordings | – |
 292 | GET /1/feedback/user/(user_name)/get-feedback                | - |
 293
 294 *** Recording Recommendation API Endpoints
 295
 296 https://listenbrainz.readthedocs.io/en/production/dev/api/#core-api-endpoints
 297
 298 | GET /1/cf/recommendation/user/(user_name)/recording        | - |
 299
 300 *** Recording Recommendation Feedback API Endpoints
 301
 302 https://listenbrainz.readthedocs.io/en/production/dev/api/#recording-recommendation-feedback-api-endpoints
 303
 304 | POST /1/recommendation/feedback/submit                     | - |
 305 | POST /1/recommendation/feedback/delete                     | - |
 306 | GET /1/recommendation/feedback/user/(user_name)/recordings | - |
 307 | GET /1/recommendation/feedback/user/(user_name)            | - |
 308
 309 *** Statistics API Endpoints
 310
 311 https://listenbrainz.readthedocs.io/en/production/dev/api/#statistics-api-endpoints
 312
 313 | GET /1/stats/sitewide/artists                    | -                             |
 314 | GET /1/stats/user/(user_name)/listening-activity | -                             |
 315 | GET /1/stats/user/(user_name)/daily-activity     | -                             |
 316 | GET /1/stats/user/(user_name)/recordings         | listenbrainz-stats-recordings |
 317 | GET /1/stats/user/(user_name)/artist-map         | -                             |
 318 | GET /1/stats/user/(user_name)/releases           | listenbrainz-stats-releases   |
 319 | GET /1/stats/user/(user_name)/artists            | listenbrainz-stats-artists    |
 320
 321 *** Status API Endpoints
 322
 323 https://listenbrainz.readthedocs.io/en/production/dev/api/#status-api-endpoints
 324
 325 | GET /1/status/get-dump-info | - |
 326
 327 *** User Timeline API Endpoints
 328
 329 https://listenbrainz.readthedocs.io/en/production/dev/api/#user-timeline-api-endpoints
 330
 331 | POST /1/user/(user_name)/timeline-event/create/notification | - |
 332 | POST /1/user/(user_name)/timeline-event/create/recording    | - |
 333 | POST /1/user/(user_name)/feed/events/delete                 | - |
 334 | GET /1/user/(user_name)/feed/events                         | - |
 335
 336 *** Social API Endpoints
 337
 338 https://listenbrainz.readthedocs.io/en/production/dev/api/#social-api-endpoints
 339
 340 | GET /1/user/(user_name)/followers | listenbrainz-followers |
 341 | GET /1/user/(user_name)/following | listenbrainz-following |
 342 | POST /1/user/(user_name)/unfollow | -                      |
 343 | POST /1/user/(user_name)/follow   | -                      |
 344
 345 *** Pinned Recording API Endpoints
 346
 347 https://listenbrainz.readthedocs.io/en/production/dev/api/#pinned-recording-api-endpoints
 348
 349 | POST /1/pin/unpin                 | - |
 350 | POST /1/pin                       | - |
 351 | POST /1/pin/delete/(row_id)       | - |
 352 | GET /1/(user_name)/pins/following | - |
 353 | GET /1/(user_name)/pins           | - |
 354
 355
 356 * otherBrainz
 357  - [[https://critiquebrainz.org/][CritiqueBrainz]]
 358  - [[https://bookbrainz.org/][BookBrainz]] → https://api.test.bookbrainz.org/1/docs/
 359  - [[https://listenbrainz.org/messybrainz/][MessyBrainz]]
 360  - [[https://coverartarchive.org/][Cover art archive]]
 361
 362 * further
 363 - https://labs.api.listenbrainz.org/
 364 - https://troi.readthedocs.io/en/latest/
 365 - https://listenbrainz.org/user/troi-bot/playlists/
 366 - https://github.com/metabrainz/bono-data-sets/blob/main/top_discoveries.py