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
 168 *** Lookup queries & subqueries
 169
 170 | (musicbrainz-lookup /entity/ /MBID/ &optional /inc/) | valid entities listed in =musicbrainz-entities-core= |
 171
 172 | *Functions & formatted output*                          | example MBID                         |
 173 | (musicbrainz-lookup-area /MBID/)                        | [[https://musicbrainz.org/area/c9ac1239-e832-41bc-9930-e252a1fd1105][c9ac1239-e832-41bc-9930-e252a1fd1105]] |
 174 | (musicbrainz-lookup-artist /MBID/)                      | [[https://musicbrainz.org/artist/410c9baf-5469-44f6-9852-826524b80c61][410c9baf-5469-44f6-9852-826524b80c61]] |
 175 | (musicbrainz-lookup-artist-recordings /MBID/)           | …                                    |
 176 | (musicbrainz-lookup-artist-releases /MBID/)             | …                                    |
 177 | (musicbrainz-lookup-artist-release-groups /MBID/)       | …                                    |
 178 | (musicbrainz-lookup-artist-works /MBID/)                | …                                    |
 179 | (musicbrainz-lookup-collection /MBID/)                  | …                                    |
 180 | (musicbrainz-lookup-collection-user-collections /MBID/) | …                                    |
 181 | (musicbrainz-lookup-event /MBID/)                       | [[https://musicbrainz.org/event/7c132556-e902-4481-b9cb-ec76a175628a][7c132556-e902-4481-b9cb-ec76a175628a]] |
 182 | (musicbrainz-lookup-genre /MBID/)                       | [[https://musicbrainz.org/genre/68c81274-5770-4e7b-a4bf-ab0d7d425d99][68c81274-5770-4e7b-a4bf-ab0d7d425d99]] |
 183 | (musicbrainz-lookup-instrument /MBID/)                  | [[https://musicbrainz.org/instrument/303d4f1a-f799-4c42-9bac-dbedd9139e91][303d4f1a-f799-4c42-9bac-dbedd9139e91]] |
 184 | (musicbrainz-lookup-label /MBID/)                       | [[https://musicbrainz.org/label/8943d408-940c-403b-a01d-9036c227d50f][8943d408-940c-403b-a01d-9036c227d50f]] |
 185 | (musicbrainz-lookup-label-releases /MBID/)              | …                                    |
 186 | (musicbrainz-lookup-place /MBID/)                       | [[https://musicbrainz.org/place/73cba8a4-cacb-45b9-8e02-654f716e2e7a][73cba8a4-cacb-45b9-8e02-654f716e2e7a]] |
 187 | (musicbrainz-lookup-recording /MBID/)                   | [[https://musicbrainz.org/recording/ef8b34c1-8548-472c-872f-03e0d8d3bb37][ef8b34c1-8548-472c-872f-03e0d8d3bb37]] |
 188 | (musicbrainz-lookup-recording-artists /MBID/)           | …                                    |
 189 | (musicbrainz-lookup-recording-releases /MBID/)          | …                                    |
 190 | (musicbrainz-lookup-recording-isrcs /MBID/)             | …                                    |
 191 | (musicbrainz-lookup-recording-url-rels /MBID/)          | …                                    |
 192 | (musicbrainz-lookup-release /MBID/)                     | …                                    |
 193 | (musicbrainz-lookup-release-artists /MBID/)             | …                                    |
 194 | (musicbrainz-lookup-release-collections /MBID/)         | …                                    |
 195 | (musicbrainz-lookup-release-labels /MBID/)              | …                                    |
 196 | (musicbrainz-lookup-release-recordings /MBID/)          | …                                    |
 197 | (musicbrainz-lookup-release-release-groups /MBID/)      | …                                    |
 198 | (musicbrainz-lookup-release-group /MBID/)               | [[https://musicbrainz.org/release-group/fe4acfe9-6d1e-3565-8857-fb16ddc492ab][fe4acfe9-6d1e-3565-8857-fb16ddc492ab]] |
 199 | (musicbrainz-lookup-release-group-artists /MBID/)       | …                                    |
 200 | (musicbrainz-lookup-release-group-releases /MBID/)      | …                                    |
 201 | (musicbrainz-lookup-series /MBID/)                      | …                                    |
 202 | (musicbrainz-lookup-work /MBID/)                        | …                                    |
 203 | (musicbrainz-lookup-url /MBID/)                         | …                                    |
 204
 205
 206 * ListenBrainz
 207
 208
 209 [[file:img/listenbrainz-logo.svg]]
 210
 211 ** listening
 212
 213 - https://listenbrainz.org
 214 - https://listenbrainz.readthedocs.io/
 215
 216 ** examples
 217
 218 #+BEGIN_SRC emacs-lisp
 219 (setq listenbrainz-api-token "000-000-000")
 220 #+END_SRC
 221
 222 #+BEGIN_SRC emacs-lisp
 223 (listenbrainz-validate-token listenbrainz-api-token)
 224 #+END_SRC
 225
 226 #+BEGIN_SRC emacs-lisp
 227 (listenbrainz-listens "zzzkt")
 228 #+END_SRC
 229
 230 #+BEGIN_SRC emacs-lisp
 231 (listenbrainz-listens "zzzkt" 33)
 232 #+END_SRC
 233
 234 #+BEGIN_SRC emacs-lisp
 235 (listenbrainz-submit-single-listen "Matthew Thomas" "Taema" "Architecture")
 236 #+END_SRC
 237
 238 #+BEGIN_SRC emacs-lisp
 239 (listenbrainz-submit-single-listen "farmersmanual" "808808008088 (11)")
 240 #+END_SRC
 241
 242 #+BEGIN_SRC emacs-lisp
 243 (listenbrainz-submit-playing-now "farmersmanual" "808808008088 (11)")
 244 #+END_SRC
 245
 246 #+BEGIN_SRC emacs-lisp
 247 (listenbrainz-playing-now "zzzkt")
 248 #+END_SRC
 249
 250 #+BEGIN_SRC emacs-lisp
 251 (listenbrainz-stats-artists "zzzkt")
 252 #+END_SRC
 253
 254 #+BEGIN_SRC emacs-lisp
 255 (listenbrainz-stats-releases "zzzkt")
 256 #+END_SRC
 257
 258 #+BEGIN_SRC emacs-lisp
 259 (listenbrainz-stats-recordings "zzzkt" 13 "month")
 260 #+END_SRC
 261
 262 ** incompleteness
 263 *** Core API endpoints
 264
 265 https://listenbrainz.readthedocs.io/en/production/dev/api/#core-api-endpoints
 266
 267 | POST /1/submit-listens                                  | listenbrainz-submit-listen        |
 268 |                                                         | listenbrainz-submit-single-listen |
 269 |                                                         | listenbrainz-submit-playing-now   |
 270 | GET /1/validate-token                                   | listenbrainz-validate-token       |
 271 | POST /1/delete-listen                                   | -                                 |
 272 | GET /1/user/(playlist_user_name)/playlists/collaborator | -                                 |
 273 | GET /1/user/(playlist_user_name)/playlists/createdfor   | -                                 |
 274 | GET /1/users/(user_list)/recent-listens                 | -                                 |
 275 | GET /1/user/(user_name)/similar-users                   | -                                 |
 276 | GET /1/user/(user_name)/listen-count                    | -                                 |
 277 | GET /1/user/(user_name)/playing-now                     | listenbrainz-playing-now          |
 278 | GET /1/user/(user_name)/similar-to/(other_user_name)    | -                                 |
 279 | GET /1/user/(playlist_user_name)/playlists              | -                                 |
 280 | GET /1/user/(user_name)/listens                         | listenbrainz-listens              |
 281 | GET /1/latest-import                                    | -                                 |
 282 | POST /1/latest-import                                   | -                                 |
 283
 284 *** Feedback API Endpoints
 285
 286 https://listenbrainz.readthedocs.io/en/production/dev/api/#feedback-api-endpoints
 287
 288 | POST /1/feedback/recording-feedback                          | - |
 289 | GET /1/feedback/recording/(recording_msid)/get-feedback      | - |
 290 | GET /1/feedback/user/(user_name)/get-feedback-for-recordings | – |
 291 | GET /1/feedback/user/(user_name)/get-feedback                | - |
 292
 293 *** Recording Recommendation API Endpoints
 294
 295 https://listenbrainz.readthedocs.io/en/production/dev/api/#core-api-endpoints
 296
 297 | GET /1/cf/recommendation/user/(user_name)/recording        | - |
 298
 299 *** Recording Recommendation Feedback API Endpoints
 300
 301 https://listenbrainz.readthedocs.io/en/production/dev/api/#recording-recommendation-feedback-api-endpoints
 302
 303 | POST /1/recommendation/feedback/submit                     | - |
 304 | POST /1/recommendation/feedback/delete                     | - |
 305 | GET /1/recommendation/feedback/user/(user_name)/recordings | - |
 306 | GET /1/recommendation/feedback/user/(user_name)            | - |
 307
 308 *** Statistics API Endpoints
 309
 310 https://listenbrainz.readthedocs.io/en/production/dev/api/#statistics-api-endpoints
 311
 312 | GET /1/stats/sitewide/artists                    | -                             |
 313 | GET /1/stats/user/(user_name)/listening-activity | -                             |
 314 | GET /1/stats/user/(user_name)/daily-activity     | -                             |
 315 | GET /1/stats/user/(user_name)/recordings         | listenbrainz-stats-recordings |
 316 | GET /1/stats/user/(user_name)/artist-map         | -                             |
 317 | GET /1/stats/user/(user_name)/releases           | listenbrainz-stats-releases   |
 318 | GET /1/stats/user/(user_name)/artists            | listenbrainz-stats-artists    |
 319
 320 *** Status API Endpoints
 321
 322 https://listenbrainz.readthedocs.io/en/production/dev/api/#status-api-endpoints
 323
 324 | GET /1/status/get-dump-info | - |
 325
 326 *** User Timeline API Endpoints
 327
 328 https://listenbrainz.readthedocs.io/en/production/dev/api/#user-timeline-api-endpoints
 329
 330 | POST /1/user/(user_name)/timeline-event/create/notification | - |
 331 | POST /1/user/(user_name)/timeline-event/create/recording    | - |
 332 | POST /1/user/(user_name)/feed/events/delete                 | - |
 333 | GET /1/user/(user_name)/feed/events                         | - |
 334
 335 *** Social API Endpoints
 336
 337 https://listenbrainz.readthedocs.io/en/production/dev/api/#social-api-endpoints
 338
 339 | GET /1/user/(user_name)/followers | listenbrainz-followers |
 340 | GET /1/user/(user_name)/following | listenbrainz-following |
 341 | POST /1/user/(user_name)/unfollow | -                      |
 342 | POST /1/user/(user_name)/follow   | -                      |
 343
 344 *** Pinned Recording API Endpoints
 345
 346 https://listenbrainz.readthedocs.io/en/production/dev/api/#pinned-recording-api-endpoints
 347
 348 | POST /1/pin/unpin                 | - |
 349 | POST /1/pin                       | - |
 350 | POST /1/pin/delete/(row_id)       | - |
 351 | GET /1/(user_name)/pins/following | - |
 352 | GET /1/(user_name)/pins           | - |
 353
 354
 355 * otherBrainz
 356  - [[https://critiquebrainz.org/][CritiqueBrainz]]
 357  - [[https://bookbrainz.org/][BookBrainz]] → https://api.test.bookbrainz.org/1/docs/
 358  - [[https://listenbrainz.org/messybrainz/][MessyBrainz]]
 359  - [[https://coverartarchive.org/][Cover art archive]]
 360
 361 * further
 362 - https://labs.api.listenbrainz.org/
 363 - https://troi.readthedocs.io/en/latest/
 364 - https://listenbrainz.org/user/troi-bot/playlists/
 365 - https://github.com/metabrainz/bono-data-sets/blob/main/top_discoveries.py