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 [[file:img/musicbrainz-logo.svg]]
   7
   8 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.
   9
  10 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.
  11
  12 ** some examples
  13
  14 #+BEGIN_SRC emacs-lisp
  15 (musicbrainz-search "recording" "taema")
  16 #+END_SRC
  17
  18 Autechre albums & eps
  19
  20 docs provide the example URL https://musicbrainz.org/ws/2/release-group?artist=410c9baf-5469-44f6-9852-826524b80c61&type=album|ep
  21
  22 #+BEGIN_SRC emacs-lisp
  23 (musicbrainz-browse "release-group" "artist" "410c9baf-5469-44f6-9852-826524b80c61" "album|ep")
  24 #+END_SRC
  25
  26 #+BEGIN_SRC emacs-lisp
  27 (musicbrainz-search-artist "Autechre")
  28 #+END_SRC
  29
  30 #+RESULTS:
  31 | Autechre | 410c9baf-5469-44f6-9852-826524b80c61 |
  32
  33
  34 #+BEGIN_SRC emacs-lisp
  35 (musicbrainz-search-label "Warp")
  36 #+END_SRC
  37
  38 #+RESULTS:
  39 | Warp | 46f0f4cd-8aab-4b33-b698-f459faf64190 |
  40
  41 #+BEGIN_SRC emacs-lisp
  42 (musicbrainz-search-label "Music" 5)
  43 #+END_SRC
  44
  45 #+RESULTS:
  46 | 100 | Sony Music      | global brand, excluding JP, owned by Sony Music Entertainment (1991 ongoing)                          | 9e6b4d7f-4958-4db7-8504-d89e315836af |
  47 |  96 | [no label]      | Special purpose label – white labels, self-published releases and other “no label” releases (ongoing) | 157afde4-4bf5-4039-8ad2-5a15acc85176 |
  48 |  91 | Polydor         | worldwide imprint, see annotation (1913-04-02 ongoing)                                                | ce24ab18-1bd6-4293-a486-546d13d6a5e2 |
  49 |  91 | Universal Music | plain logo: “Universal Music” (ongoing)                                                               | 13a464dc-b9fd-4d16-a4f4-d4316f6a46c7 |
  50 |  90 | ZYX Music       | (1992 ongoing)                                                                                        | 6844efda-a451-431e-8cc1-48ab111b4711 |
  51
  52 ** MBID
  53
  54 “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.”
  55
  56 https://musicbrainz.org/doc/MusicBrainz_Identifier
  57
  58 #+BEGIN_SRC emacs-lisp
  59 (musicbrainz-artist-to-mbid "Autechre")
  60 #+END_SRC
  61
  62 =410c9baf-5469-44f6-9852-826524b80c61=
  63
  64 #+BEGIN_SRC emacs-lisp
  65 (musicbrainz-mbid-p "410c9baf-5469-44f6-9852-826524b80c61")
  66 #+END_SRC
  67
  68 ** ambiguity
  69
  70 from the docs…
  71
  72 #+BEGIN_SRC text
  73 John Williams, the soundtrack composer and conductor, has an artist MBID of 53b106e7-0cc6-42cc-ac95-ed8d30a3a98e
  74 John Williams, the classical guitar player, has an artist MBID of 8b8a38a9-a290-4560-84f6-3d4466e8d791
  75 #+END_SRC
  76
  77 #+BEGIN_SRC emacs-lisp
  78 (musicbrainz-disambiguate-artist "John Williams")
  79 #+END_SRC
  80
  81 #+BEGIN_SRC emacs-lisp
  82 (musicbrainz-artist-to-mbid "Bad Seeds")
  83 #+END_SRC
  84
  85 =7feb02f2-51fa-422d-838e-2c14ecb4c7b8= →  Tomorrows Bad Seeds
  86
  87 #+BEGIN_SRC emacs-lisp
  88 (musicbrainz-disambiguate-artist "Bad Seeds")
  89 #+END_SRC
  90
  91 #+RESULTS:
  92 |     | Artist: Bad Seeds                                         | MBID                                 |
  93 | 100 | Tomorrows Bad Seeds, nil                                  | [[https://musicbrainz.org/artist/7feb02f2-51fa-422d-838e-2c14ecb4c7b8][7feb02f2-51fa-422d-838e-2c14ecb4c7b8]] |
  94 |  98 | The Bad Seeds, 60s Texas rock band                        | [[https://musicbrainz.org/artist/3e593712-9f70-4b7a-b21b-466016998a3d][3e593712-9f70-4b7a-b21b-466016998a3d]] |
  95 |  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]] |
  96 |  98 | The Bad Seeds, backing band for Nick Cave                 | [[https://musicbrainz.org/artist/eb2a8edc-5670-4896-82be-87db38de9583][eb2a8edc-5670-4896-82be-87db38de9583]] |
  97 |  86 | Nick Cave & the Bad Seeds, nil                            | [[https://musicbrainz.org/artist/172e1f1a-504d-4488-b053-6344ba63e6d0][172e1f1a-504d-4488-b053-6344ba63e6d0]] |
  98 |  50 | The Lightning Seeds, nil                                  | [[https://musicbrainz.org/artist/1ba601a0-3401-4b28-8ddd-9af8203661e8][1ba601a0-3401-4b28-8ddd-9af8203661e8]] |
  99
 100
 101
 102
 103 [[file:img/listenbrainz-logo.svg]]
 104 * listening
 105
 106 - https://listenbrainz.org
 107 - https://listenbrainz.readthedocs.io/
 108
 109 * examples
 110
 111 #+BEGIN_SRC emacs-lisp
 112 (setq listenbrainz-api-token "000-000-000")
 113 #+END_SRC
 114
 115 #+BEGIN_SRC emacs-lisp
 116 (listenbrainz-validate-token listenbrainz-api-token)
 117 #+END_SRC
 118
 119 #+BEGIN_SRC emacs-lisp
 120 (listenbrainz-listens "zzzkt")
 121 #+END_SRC
 122
 123 #+BEGIN_SRC emacs-lisp
 124 (listenbrainz-listens "zzzkt" 33)
 125 #+END_SRC
 126
 127 #+BEGIN_SRC emacs-lisp
 128 (listenbrainz-submit-single-listen "farmersmanual" "808808008088 (11)")
 129 #+END_SRC
 130
 131 #+BEGIN_SRC emacs-lisp
 132 (listenbrainz-submit-single-listen "Matthew Thomas" "Taema" "Architecture")
 133 #+END_SRC
 134
 135 #+BEGIN_SRC emacs-lisp
 136 (listenbrainz-submit-playing-now "farmersmanual" "808808008088 (11)")
 137 #+END_SRC
 138
 139 #+BEGIN_SRC emacs-lisp
 140 (listenbrainz-playing-now "zzzkt")
 141 #+END_SRC
 142
 143 #+BEGIN_SRC emacs-lisp
 144 (listenbrainz-stats-artists "zzzkt") ;; defaults to ’all time’
 145 #+END_SRC
 146
 147 #+BEGIN_SRC emacs-lisp
 148 (listenbrainz-stats-releases "zzzkt")
 149 #+END_SRC
 150
 151 #+BEGIN_SRC emacs-lisp
 152 (listenbrainz-stats-recordings "zzzkt" 13 "month")
 153 #+END_SRC
 154
 155 * incompleteness
 156
 157 ** Core API endpoints
 158
 159 https://listenbrainz.readthedocs.io/en/production/dev/api/#core-api-endpoints
 160
 161 | POST /1/submit-listens                                  | listenbrainz-submit-listen        |
 162 |                                                         | listenbrainz-submit-single-listen |
 163 |                                                         | listenbrainz-submit-playing-now   |
 164 | GET /1/validate-token                                   | listenbrainz-validate-token       |
 165 | POST /1/delete-listen                                   | -                                 |
 166 | GET /1/user/(playlist_user_name)/playlists/collaborator | -                                 |
 167 | GET /1/user/(playlist_user_name)/playlists/createdfor   | -                                 |
 168 | GET /1/users/(user_list)/recent-listens                 | -                                 |
 169 | GET /1/user/(user_name)/similar-users                   | -                                 |
 170 | GET /1/user/(user_name)/listen-count                    | -                                 |
 171 | GET /1/user/(user_name)/playing-now                     | listenbrainz-playing-now          |
 172 | GET /1/user/(user_name)/similar-to/(other_user_name)    | -                                 |
 173 | GET /1/user/(playlist_user_name)/playlists              | -                                 |
 174 | GET /1/user/(user_name)/listens                         | listenbrainz-listens              |
 175 | GET /1/latest-import                                    | -                                 |
 176 | POST /1/latest-import                                   | -                                 |
 177
 178 ** Feedback API Endpoints
 179
 180 https://listenbrainz.readthedocs.io/en/production/dev/api/#feedback-api-endpoints
 181
 182 | POST /1/feedback/recording-feedback                          | - |
 183 | GET /1/feedback/recording/(recording_msid)/get-feedback      | - |
 184 | GET /1/feedback/user/(user_name)/get-feedback-for-recordings | – |
 185 | GET /1/feedback/user/(user_name)/get-feedback                | - |
 186
 187 ** Recording Recommendation API Endpoints
 188
 189 https://listenbrainz.readthedocs.io/en/production/dev/api/#core-api-endpoints
 190
 191 | GET /1/cf/recommendation/user/(user_name)/recording        | - |
 192
 193 ** Recording Recommendation Feedback API Endpoints
 194
 195 https://listenbrainz.readthedocs.io/en/production/dev/api/#recording-recommendation-feedback-api-endpoints
 196
 197 | POST /1/recommendation/feedback/submit                     | - |
 198 | POST /1/recommendation/feedback/delete                     | - |
 199 | GET /1/recommendation/feedback/user/(user_name)/recordings | - |
 200 | GET /1/recommendation/feedback/user/(user_name)            | - |
 201
 202 ** Statistics API Endpoints
 203
 204 https://listenbrainz.readthedocs.io/en/production/dev/api/#statistics-api-endpoints
 205
 206 | GET /1/stats/sitewide/artists                    | -                             |
 207 | GET /1/stats/user/(user_name)/listening-activity | -                             |
 208 | GET /1/stats/user/(user_name)/daily-activity     | -                             |
 209 | GET /1/stats/user/(user_name)/recordings         | listenbrainz-stats-recordings |
 210 | GET /1/stats/user/(user_name)/artist-map         | -                             |
 211 | GET /1/stats/user/(user_name)/releases           | listenbrainz-stats-releases   |
 212 | GET /1/stats/user/(user_name)/artists            | listenbrainz-stats-artists    |
 213
 214 ** Status API Endpoints
 215
 216 https://listenbrainz.readthedocs.io/en/production/dev/api/#status-api-endpoints
 217
 218 | GET /1/status/get-dump-info | - |
 219
 220 ** User Timeline API Endpoints
 221
 222 https://listenbrainz.readthedocs.io/en/production/dev/api/#user-timeline-api-endpoints
 223
 224 | POST /1/user/(user_name)/timeline-event/create/notification | - |
 225 | POST /1/user/(user_name)/timeline-event/create/recording    | - |
 226 | POST /1/user/(user_name)/feed/events/delete                 | - |
 227 | GET /1/user/(user_name)/feed/events                         | - |
 228
 229 ** Social API Endpoints
 230
 231 https://listenbrainz.readthedocs.io/en/production/dev/api/#social-api-endpoints
 232
 233 | GET /1/user/(user_name)/followers | listenbrainz-followers |
 234 | GET /1/user/(user_name)/following | listenbrainz-following |
 235 | POST /1/user/(user_name)/unfollow | -                      |
 236 | POST /1/user/(user_name)/follow   | -                      |
 237
 238 ** Pinned Recording API Endpoints
 239
 240 https://listenbrainz.readthedocs.io/en/production/dev/api/#pinned-recording-api-endpoints
 241
 242 | POST /1/pin/unpin                 | - |
 243 | POST /1/pin                       | - |
 244 | POST /1/pin/delete/(row_id)       | - |
 245 | GET /1/(user_name)/pins/following | - |
 246 | GET /1/(user_name)/pins           | - |
 247
 248
 249
 250 * further
 251 - https://listenbrainz.org/user/troi-bot/playlists/
 252 - https://github.com/metabrainz/bono-data-sets/blob/main/top_discoveries.py