README.org

   1 # -*- mode: org; coding: utf-8; -*-
   2 #+OPTIONS: toc:2 num:nil html-style:nil
   3 #+author:
   4 #+title:  MusicBrainz & ListenBrainz & other
   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 | 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)                          | 9e6b4d7f-4958-4db7-8504-d89e315836af |
  87 |  96 | [no label]      | Special purpose label – white labels, self-published releases and other “no label” releases (ongoing) | 157afde4-4bf5-4039-8ad2-5a15acc85176 |
  88 |  91 | Polydor         | worldwide imprint, see annotation (1913-04-02 ongoing)                                                | ce24ab18-1bd6-4293-a486-546d13d6a5e2 |
  89 |  91 | Universal Music | plain logo: “Universal Music” (ongoing)                                                               | 13a464dc-b9fd-4d16-a4f4-d4316f6a46c7 |
  90 |  90 | ZYX Music       | (1992 ongoing)                                                                                        | 6844efda-a451-431e-8cc1-48ab111b4711 |
  91
  92 ** MBID
  93
  94 “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.”
  95
  96 https://musicbrainz.org/doc/MusicBrainz_Identifier
  97
  98 #+BEGIN_SRC emacs-lisp
  99 (musicbrainz-artist-to-mbid "Autechre")
 100 #+END_SRC
 101
 102 returns =410c9baf-5469-44f6-9852-826524b80c61=
 103
 104 #+BEGIN_SRC emacs-lisp
 105 (musicbrainz-mbid-p "410c9baf-5469-44f6-9852-826524b80c61")
 106 #+END_SRC
 107
 108 ** ambiguity
 109
 110 From the docs…
 111
 112 #+BEGIN_SRC text
 113 John Williams, the soundtrack composer and conductor, has an artist MBID of 53b106e7-0cc6-42cc-ac95-ed8d30a3a98e
 114 John Williams, the classical guitar player, has an artist MBID of 8b8a38a9-a290-4560-84f6-3d4466e8d791
 115 #+END_SRC
 116
 117 #+BEGIN_SRC emacs-lisp
 118 (musicbrainz-disambiguate-artist "John Williams" 3)
 119 #+END_SRC
 120
 121 |     | Artist: John Williams                                         | MBID                                 |
 122 | 100 | John Williams, American score composer                        | [[https://musicbrainz.org/artist/53b106e7-0cc6-42cc-ac95-ed8d30a3a98e][53b106e7-0cc6-42cc-ac95-ed8d30a3a98e]] |
 123 |  94 | John Williams, classical guitarist                            | [[https://musicbrainz.org/artist/8b8a38a9-a290-4560-84f6-3d4466e8d791][8b8a38a9-a290-4560-84f6-3d4466e8d791]] |
 124 |  92 | John Williams, English A&R executive, producer, songwriter... | [[https://musicbrainz.org/artist/eb5d7680-0c00-4b0c-b6eb-9605ff77723d][eb5d7680-0c00-4b0c-b6eb-9605ff77723d]] |
 125
 126 There are several “Bad Seeds”
 127
 128 #+BEGIN_SRC emacs-lisp
 129 (musicbrainz-artist-to-mbid "Bad Seeds")
 130 #+END_SRC
 131
 132 Which returns the MBID =7feb02f2-51fa-422d-838e-2c14ecb4c7b8= for “Tomorrows Bad Seeds”, however…
 133
 134 #+BEGIN_SRC emacs-lisp
 135 (musicbrainz-disambiguate-artist "Bad Seeds" 7)
 136 #+END_SRC
 137
 138 #+RESULTS:
 139 |     | Artist: Bad Seeds                                         | MBID                                 |
 140 | 100 | Tomorrows Bad Seeds, nil                                  | [[https://musicbrainz.org/artist/7feb02f2-51fa-422d-838e-2c14ecb4c7b8][7feb02f2-51fa-422d-838e-2c14ecb4c7b8]] |
 141 |  98 | The Bad Seeds, 60s Texas rock band                        | [[https://musicbrainz.org/artist/3e593712-9f70-4b7a-b21b-466016998a3d][3e593712-9f70-4b7a-b21b-466016998a3d]] |
 142 |  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]] |
 143 |  98 | The Bad Seeds, backing band for Nick Cave                 | [[https://musicbrainz.org/artist/eb2a8edc-5670-4896-82be-87db38de9583][eb2a8edc-5670-4896-82be-87db38de9583]] |
 144 |  86 | Nick Cave & the Bad Seeds, nil                            | [[https://musicbrainz.org/artist/172e1f1a-504d-4488-b053-6344ba63e6d0][172e1f1a-504d-4488-b053-6344ba63e6d0]] |
 145 |  50 | The Lightning Seeds, nil                                  | [[https://musicbrainz.org/artist/1ba601a0-3401-4b28-8ddd-9af8203661e8][1ba601a0-3401-4b28-8ddd-9af8203661e8]] |
 146 |  49 | Seeds, UK dancehall                                       | [[https://musicbrainz.org/artist/a03cf587-a3d3-4847-ac41-e488f779a313][a03cf587-a3d3-4847-ac41-e488f779a313]] |
 147
 148
 149
 150 * ListenBrainz
 151
 152
 153 [[file:img/listenbrainz-logo.svg]]
 154
 155 * listening
 156
 157 - https://listenbrainz.org
 158 - https://listenbrainz.readthedocs.io/
 159
 160 * examples
 161
 162 #+BEGIN_SRC emacs-lisp
 163 (setq listenbrainz-api-token "000-000-000")
 164 #+END_SRC
 165
 166 #+BEGIN_SRC emacs-lisp
 167 (listenbrainz-validate-token listenbrainz-api-token)
 168 #+END_SRC
 169
 170 #+BEGIN_SRC emacs-lisp
 171 (listenbrainz-listens "zzzkt")
 172 #+END_SRC
 173
 174 #+BEGIN_SRC emacs-lisp
 175 (listenbrainz-listens "zzzkt" 33)
 176 #+END_SRC
 177
 178 #+BEGIN_SRC emacs-lisp
 179 (listenbrainz-submit-single-listen "Matthew Thomas" "Taema" "Architecture")
 180 #+END_SRC
 181
 182 #+BEGIN_SRC emacs-lisp
 183 (listenbrainz-submit-single-listen "farmersmanual" "808808008088 (11)")
 184 #+END_SRC
 185
 186 #+BEGIN_SRC emacs-lisp
 187 (listenbrainz-submit-playing-now "farmersmanual" "808808008088 (11)")
 188 #+END_SRC
 189
 190 #+BEGIN_SRC emacs-lisp
 191 (listenbrainz-playing-now "zzzkt")
 192 #+END_SRC
 193
 194 #+BEGIN_SRC emacs-lisp
 195 (listenbrainz-stats-artists "zzzkt")
 196 #+END_SRC
 197
 198 #+BEGIN_SRC emacs-lisp
 199 (listenbrainz-stats-releases "zzzkt")
 200 #+END_SRC
 201
 202 #+BEGIN_SRC emacs-lisp
 203 (listenbrainz-stats-recordings "zzzkt" 13 "month")
 204 #+END_SRC
 205
 206 * incompleteness
 207
 208 ** Core API endpoints
 209
 210 https://listenbrainz.readthedocs.io/en/production/dev/api/#core-api-endpoints
 211
 212 | POST /1/submit-listens                                  | listenbrainz-submit-listen        |
 213 |                                                         | listenbrainz-submit-single-listen |
 214 |                                                         | listenbrainz-submit-playing-now   |
 215 | GET /1/validate-token                                   | listenbrainz-validate-token       |
 216 | POST /1/delete-listen                                   | -                                 |
 217 | GET /1/user/(playlist_user_name)/playlists/collaborator | -                                 |
 218 | GET /1/user/(playlist_user_name)/playlists/createdfor   | -                                 |
 219 | GET /1/users/(user_list)/recent-listens                 | -                                 |
 220 | GET /1/user/(user_name)/similar-users                   | -                                 |
 221 | GET /1/user/(user_name)/listen-count                    | -                                 |
 222 | GET /1/user/(user_name)/playing-now                     | listenbrainz-playing-now          |
 223 | GET /1/user/(user_name)/similar-to/(other_user_name)    | -                                 |
 224 | GET /1/user/(playlist_user_name)/playlists              | -                                 |
 225 | GET /1/user/(user_name)/listens                         | listenbrainz-listens              |
 226 | GET /1/latest-import                                    | -                                 |
 227 | POST /1/latest-import                                   | -                                 |
 228
 229 ** Feedback API Endpoints
 230
 231 https://listenbrainz.readthedocs.io/en/production/dev/api/#feedback-api-endpoints
 232
 233 | POST /1/feedback/recording-feedback                          | - |
 234 | GET /1/feedback/recording/(recording_msid)/get-feedback      | - |
 235 | GET /1/feedback/user/(user_name)/get-feedback-for-recordings | – |
 236 | GET /1/feedback/user/(user_name)/get-feedback                | - |
 237
 238 ** Recording Recommendation API Endpoints
 239
 240 https://listenbrainz.readthedocs.io/en/production/dev/api/#core-api-endpoints
 241
 242 | GET /1/cf/recommendation/user/(user_name)/recording        | - |
 243
 244 ** Recording Recommendation Feedback API Endpoints
 245
 246 https://listenbrainz.readthedocs.io/en/production/dev/api/#recording-recommendation-feedback-api-endpoints
 247
 248 | POST /1/recommendation/feedback/submit                     | - |
 249 | POST /1/recommendation/feedback/delete                     | - |
 250 | GET /1/recommendation/feedback/user/(user_name)/recordings | - |
 251 | GET /1/recommendation/feedback/user/(user_name)            | - |
 252
 253 ** Statistics API Endpoints
 254
 255 https://listenbrainz.readthedocs.io/en/production/dev/api/#statistics-api-endpoints
 256
 257 | GET /1/stats/sitewide/artists                    | -                             |
 258 | GET /1/stats/user/(user_name)/listening-activity | -                             |
 259 | GET /1/stats/user/(user_name)/daily-activity     | -                             |
 260 | GET /1/stats/user/(user_name)/recordings         | listenbrainz-stats-recordings |
 261 | GET /1/stats/user/(user_name)/artist-map         | -                             |
 262 | GET /1/stats/user/(user_name)/releases           | listenbrainz-stats-releases   |
 263 | GET /1/stats/user/(user_name)/artists            | listenbrainz-stats-artists    |
 264
 265 ** Status API Endpoints
 266
 267 https://listenbrainz.readthedocs.io/en/production/dev/api/#status-api-endpoints
 268
 269 | GET /1/status/get-dump-info | - |
 270
 271 ** User Timeline API Endpoints
 272
 273 https://listenbrainz.readthedocs.io/en/production/dev/api/#user-timeline-api-endpoints
 274
 275 | POST /1/user/(user_name)/timeline-event/create/notification | - |
 276 | POST /1/user/(user_name)/timeline-event/create/recording    | - |
 277 | POST /1/user/(user_name)/feed/events/delete                 | - |
 278 | GET /1/user/(user_name)/feed/events                         | - |
 279
 280 ** Social API Endpoints
 281
 282 https://listenbrainz.readthedocs.io/en/production/dev/api/#social-api-endpoints
 283
 284 | GET /1/user/(user_name)/followers | listenbrainz-followers |
 285 | GET /1/user/(user_name)/following | listenbrainz-following |
 286 | POST /1/user/(user_name)/unfollow | -                      |
 287 | POST /1/user/(user_name)/follow   | -                      |
 288
 289 ** Pinned Recording API Endpoints
 290
 291 https://listenbrainz.readthedocs.io/en/production/dev/api/#pinned-recording-api-endpoints
 292
 293 | POST /1/pin/unpin                 | - |
 294 | POST /1/pin                       | - |
 295 | POST /1/pin/delete/(row_id)       | - |
 296 | GET /1/(user_name)/pins/following | - |
 297 | GET /1/(user_name)/pins           | - |
 298
 299
 300 * otherBrainz
 301  - [[https://critiquebrainz.org/][CritiqueBrainz]]
 302  - [[https://bookbrainz.org/][BookBrainz]] → https://api.test.bookbrainz.org/1/docs/
 303  - [[https://listenbrainz.org/messybrainz/][MessyBrainz]]
 304  - [[https://coverartarchive.org/][Cover art archive]]
 305
 306 * further
 307 - https://listenbrainz.org/user/troi-bot/playlists/
 308 - https://github.com/metabrainz/bono-data-sets/blob/main/top_discoveries.py