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