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 (musicbrainz-browse "release-group" "artist" "410c9baf-5469-44f6-9852-826524b80c61" "album|ep"))
  36 #+END_SRC
  37
  38 A more interactive approach could start with  =(musicbrainz-search "artist" "Autechre")= or =(musicbrainz-search-artist "Autechre")= Which returns the MBID required for the lookup → =410c9baf-5469-44f6-9852-826524b80c61=
  39
  40 The MBID can be checked if needed,  with =(musicbrainz-mbid-p "410c9baf-5469-44f6-9852-826524b80c61")=
  41
  42 The MBID can then be used for specific lookups…
  43 #+BEGIN_SRC emacs-lisp
  44 (musicbrainz-lookup "artist" "410c9baf-5469-44f6-9852-826524b80c61" "releases")
  45 #+END_SRC
  46
  47 #+BEGIN_SRC emacs-lisp
  48 (musicbrainz-lookup-artist "410c9baf-5469-44f6-9852-826524b80c61")
  49 #+END_SRC
  50
  51 | Autechre | electronic music duo | Group | [[https://musicbrainz.org/artist/410c9baf-5469-44f6-9852-826524b80c61][410c9baf-5469-44f6-9852-826524b80c61]] |
  52
  53
  54 #+BEGIN_SRC emacs-lisp
  55 (musicbrainz-lookup-artist-releases  "410c9baf-5469-44f6-9852-826524b80c61")
  56 #+END_SRC
  57
  58 #+BEGIN_SRC emacs-lisp
  59 (musicbrainz-lookup-artist-recordings  "410c9baf-5469-44f6-9852-826524b80c61")
  60 #+END_SRC
  61
  62 #+BEGIN_SRC emacs-lisp
  63 (musicbrainz-lookup-release "ec1ecfcc-f529-43d1-8aa6-2c7051ede00c")
  64 #+END_SRC
  65
  66 | 1990 | Autechre / Saw You | Cassette Case | [[https://musicbrainz.org/release/ec1ecfcc-f529-43d1-8aa6-2c7051ede00c][ec1ecfcc-f529-43d1-8aa6-2c7051ede00c]] |
  67
  68 #+BEGIN_SRC emacs-lisp
  69 (musicbrainz-lookup-recording "83730176-89ec-41a5-a4b6-476998f6291c")
  70 #+END_SRC
  71
  72 | [untitled] | [[https://musicbrainz.org/recording/83730176-89ec-41a5-a4b6-476998f6291c][83730176-89ec-41a5-a4b6-476998f6291c]] |
  73
  74
  75 #+BEGIN_SRC emacs-lisp
  76 (musicbrainz-search-label "Warp")
  77 #+END_SRC
  78
  79 #+RESULTS:
  80 | Warp | 46f0f4cd-8aab-4b33-b698-f459faf64190 |
  81
  82 #+BEGIN_SRC emacs-lisp
  83 (musicbrainz-search-label "Music" 5)
  84 #+END_SRC
  85
  86 #+RESULTS:
  87 | 100 | Sony Music      | global brand, excluding JP, owned by Sony Music Entertainment (1991 ongoing)                          | 9e6b4d7f-4958-4db7-8504-d89e315836af |
  88 |  96 | [no label]      | Special purpose label – white labels, self-published releases and other “no label” releases (ongoing) | 157afde4-4bf5-4039-8ad2-5a15acc85176 |
  89 |  91 | Polydor         | worldwide imprint, see annotation (1913-04-02 ongoing)                                                | ce24ab18-1bd6-4293-a486-546d13d6a5e2 |
  90 |  91 | Universal Music | plain logo: “Universal Music” (ongoing)                                                               | 13a464dc-b9fd-4d16-a4f4-d4316f6a46c7 |
  91 |  90 | ZYX Music       | (1992 ongoing)                                                                                        | 6844efda-a451-431e-8cc1-48ab111b4711 |
  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.”
  96
  97 https://musicbrainz.org/doc/MusicBrainz_Identifier
  98
  99 #+BEGIN_SRC emacs-lisp
 100 (musicbrainz-artist-to-mbid "Autechre")
 101 #+END_SRC
 102
 103 =410c9baf-5469-44f6-9852-826524b80c61=
 104
 105 #+BEGIN_SRC emacs-lisp
 106 (musicbrainz-mbid-p "410c9baf-5469-44f6-9852-826524b80c61")
 107 #+END_SRC
 108
 109 ** ambiguity
 110
 111 from the docs…
 112
 113 #+BEGIN_SRC text
 114 John Williams, the soundtrack composer and conductor, has an artist MBID of 53b106e7-0cc6-42cc-ac95-ed8d30a3a98e
 115 John Williams, the classical guitar player, has an artist MBID of 8b8a38a9-a290-4560-84f6-3d4466e8d791
 116 #+END_SRC
 117
 118 #+BEGIN_SRC emacs-lisp
 119 (musicbrainz-disambiguate-artist "John Williams")
 120 #+END_SRC
 121
 122 #+BEGIN_SRC emacs-lisp
 123 (musicbrainz-artist-to-mbid "Bad Seeds")
 124 #+END_SRC
 125
 126 =7feb02f2-51fa-422d-838e-2c14ecb4c7b8= →  Tomorrows Bad Seeds
 127
 128 #+BEGIN_SRC emacs-lisp
 129 (musicbrainz-disambiguate-artist "Bad Seeds" 7)
 130 #+END_SRC
 131
 132 #+RESULTS:
 133 |     | Artist: Bad Seeds                                         | MBID                                 |
 134 | 100 | Tomorrows Bad Seeds, nil                                  | [[https://musicbrainz.org/artist/7feb02f2-51fa-422d-838e-2c14ecb4c7b8][7feb02f2-51fa-422d-838e-2c14ecb4c7b8]] |
 135 |  98 | The Bad Seeds, 60s Texas rock band                        | [[https://musicbrainz.org/artist/3e593712-9f70-4b7a-b21b-466016998a3d][3e593712-9f70-4b7a-b21b-466016998a3d]] |
 136 |  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]] |
 137 |  98 | The Bad Seeds, backing band for Nick Cave                 | [[https://musicbrainz.org/artist/eb2a8edc-5670-4896-82be-87db38de9583][eb2a8edc-5670-4896-82be-87db38de9583]] |
 138 |  86 | Nick Cave & the Bad Seeds, nil                            | [[https://musicbrainz.org/artist/172e1f1a-504d-4488-b053-6344ba63e6d0][172e1f1a-504d-4488-b053-6344ba63e6d0]] |
 139 |  50 | The Lightning Seeds, nil                                  | [[https://musicbrainz.org/artist/1ba601a0-3401-4b28-8ddd-9af8203661e8][1ba601a0-3401-4b28-8ddd-9af8203661e8]] |
 140 |  49 | Seeds, UK dancehall                                       | [[https://musicbrainz.org/artist/a03cf587-a3d3-4847-ac41-e488f779a313][a03cf587-a3d3-4847-ac41-e488f779a313]] |
 141
 142
 143
 144 * ListenBrainz
 145
 146
 147 [[file:img/listenbrainz-logo.svg]]
 148
 149 * listening
 150
 151 - https://listenbrainz.org
 152 - https://listenbrainz.readthedocs.io/
 153
 154 * examples
 155
 156 #+BEGIN_SRC emacs-lisp
 157 (setq listenbrainz-api-token "000-000-000")
 158 #+END_SRC
 159
 160 #+BEGIN_SRC emacs-lisp
 161 (listenbrainz-validate-token listenbrainz-api-token)
 162 #+END_SRC
 163
 164 #+BEGIN_SRC emacs-lisp
 165 (listenbrainz-listens "zzzkt")
 166 #+END_SRC
 167
 168 #+BEGIN_SRC emacs-lisp
 169 (listenbrainz-listens "zzzkt" 33)
 170 #+END_SRC
 171
 172 #+BEGIN_SRC emacs-lisp
 173 (listenbrainz-submit-single-listen "Matthew Thomas" "Taema" "Architecture")
 174 #+END_SRC
 175
 176 #+BEGIN_SRC emacs-lisp
 177 (listenbrainz-submit-single-listen "farmersmanual" "808808008088 (11)")
 178 #+END_SRC
 179
 180 #+BEGIN_SRC emacs-lisp
 181 (listenbrainz-submit-playing-now "farmersmanual" "808808008088 (11)")
 182 #+END_SRC
 183
 184 #+BEGIN_SRC emacs-lisp
 185 (listenbrainz-playing-now "zzzkt")
 186 #+END_SRC
 187
 188 #+BEGIN_SRC emacs-lisp
 189 (listenbrainz-stats-artists "zzzkt")
 190 #+END_SRC
 191
 192 #+BEGIN_SRC emacs-lisp
 193 (listenbrainz-stats-releases "zzzkt")
 194 #+END_SRC
 195
 196 #+BEGIN_SRC emacs-lisp
 197 (listenbrainz-stats-recordings "zzzkt" 13 "month")
 198 #+END_SRC
 199
 200 * incompleteness
 201
 202 ** Core API endpoints
 203
 204 https://listenbrainz.readthedocs.io/en/production/dev/api/#core-api-endpoints
 205
 206 | POST /1/submit-listens                                  | listenbrainz-submit-listen        |
 207 |                                                         | listenbrainz-submit-single-listen |
 208 |                                                         | listenbrainz-submit-playing-now   |
 209 | GET /1/validate-token                                   | listenbrainz-validate-token       |
 210 | POST /1/delete-listen                                   | -                                 |
 211 | GET /1/user/(playlist_user_name)/playlists/collaborator | -                                 |
 212 | GET /1/user/(playlist_user_name)/playlists/createdfor   | -                                 |
 213 | GET /1/users/(user_list)/recent-listens                 | -                                 |
 214 | GET /1/user/(user_name)/similar-users                   | -                                 |
 215 | GET /1/user/(user_name)/listen-count                    | -                                 |
 216 | GET /1/user/(user_name)/playing-now                     | listenbrainz-playing-now          |
 217 | GET /1/user/(user_name)/similar-to/(other_user_name)    | -                                 |
 218 | GET /1/user/(playlist_user_name)/playlists              | -                                 |
 219 | GET /1/user/(user_name)/listens                         | listenbrainz-listens              |
 220 | GET /1/latest-import                                    | -                                 |
 221 | POST /1/latest-import                                   | -                                 |
 222
 223 ** Feedback API Endpoints
 224
 225 https://listenbrainz.readthedocs.io/en/production/dev/api/#feedback-api-endpoints
 226
 227 | POST /1/feedback/recording-feedback                          | - |
 228 | GET /1/feedback/recording/(recording_msid)/get-feedback      | - |
 229 | GET /1/feedback/user/(user_name)/get-feedback-for-recordings | – |
 230 | GET /1/feedback/user/(user_name)/get-feedback                | - |
 231
 232 ** Recording Recommendation API Endpoints
 233
 234 https://listenbrainz.readthedocs.io/en/production/dev/api/#core-api-endpoints
 235
 236 | GET /1/cf/recommendation/user/(user_name)/recording        | - |
 237
 238 ** Recording Recommendation Feedback API Endpoints
 239
 240 https://listenbrainz.readthedocs.io/en/production/dev/api/#recording-recommendation-feedback-api-endpoints
 241
 242 | POST /1/recommendation/feedback/submit                     | - |
 243 | POST /1/recommendation/feedback/delete                     | - |
 244 | GET /1/recommendation/feedback/user/(user_name)/recordings | - |
 245 | GET /1/recommendation/feedback/user/(user_name)            | - |
 246
 247 ** Statistics API Endpoints
 248
 249 https://listenbrainz.readthedocs.io/en/production/dev/api/#statistics-api-endpoints
 250
 251 | GET /1/stats/sitewide/artists                    | -                             |
 252 | GET /1/stats/user/(user_name)/listening-activity | -                             |
 253 | GET /1/stats/user/(user_name)/daily-activity     | -                             |
 254 | GET /1/stats/user/(user_name)/recordings         | listenbrainz-stats-recordings |
 255 | GET /1/stats/user/(user_name)/artist-map         | -                             |
 256 | GET /1/stats/user/(user_name)/releases           | listenbrainz-stats-releases   |
 257 | GET /1/stats/user/(user_name)/artists            | listenbrainz-stats-artists    |
 258
 259 ** Status API Endpoints
 260
 261 https://listenbrainz.readthedocs.io/en/production/dev/api/#status-api-endpoints
 262
 263 | GET /1/status/get-dump-info | - |
 264
 265 ** User Timeline API Endpoints
 266
 267 https://listenbrainz.readthedocs.io/en/production/dev/api/#user-timeline-api-endpoints
 268
 269 | POST /1/user/(user_name)/timeline-event/create/notification | - |
 270 | POST /1/user/(user_name)/timeline-event/create/recording    | - |
 271 | POST /1/user/(user_name)/feed/events/delete                 | - |
 272 | GET /1/user/(user_name)/feed/events                         | - |
 273
 274 ** Social API Endpoints
 275
 276 https://listenbrainz.readthedocs.io/en/production/dev/api/#social-api-endpoints
 277
 278 | GET /1/user/(user_name)/followers | listenbrainz-followers |
 279 | GET /1/user/(user_name)/following | listenbrainz-following |
 280 | POST /1/user/(user_name)/unfollow | -                      |
 281 | POST /1/user/(user_name)/follow   | -                      |
 282
 283 ** Pinned Recording API Endpoints
 284
 285 https://listenbrainz.readthedocs.io/en/production/dev/api/#pinned-recording-api-endpoints
 286
 287 | POST /1/pin/unpin                 | - |
 288 | POST /1/pin                       | - |
 289 | POST /1/pin/delete/(row_id)       | - |
 290 | GET /1/(user_name)/pins/following | - |
 291 | GET /1/(user_name)/pins           | - |
 292
 293
 294 * otherBrainz
 295  - [[https://critiquebrainz.org/][CritiqueBrainz]]
 296  - [[https://bookbrainz.org/][BookBrainz]] → https://api.test.bookbrainz.org/1/docs/
 297  - [[https://listenbrainz.org/messybrainz/][MessyBrainz]]
 298  - [[https://coverartarchive.org/][Cover art archive]]
 299
 300 * further
 301 - https://listenbrainz.org/user/troi-bot/playlists/
 302 - https://github.com/metabrainz/bono-data-sets/blob/main/top_discoveries.py