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