zzkt/metabrainz
1
0
Fork 0
Code Issues 12 Pull requests Projects Activity Actions
metabrainz/README.org

20 KiB
Raw Blame History

MusicBrainz

MusicBrainz is a community-maintained open source encyclopedia of music information. The REST-based webservice API can be used for direct access to MusicBrainz data with output in XML and JSON.

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.

MusicBrainz API

searching & browsing

Search supports the full Lucene search syntax.

some examples

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

The equivalent function (which returns a raw response as an alist) would be…

(musicbrainz-browse "release-group" "artist" "410c9baf-5469-44f6-9852-826524b80c61" "album|ep")

For slightly more legible output wrap with musicbrainz-format

(musicbrainz-format
 (musicbrainz-browse "release-group"
                     "artist"
                     "410c9baf-5469-44f6-9852-826524b80c61"
                     "album|ep"))

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

The MBID can be used for specific lookups (and checked if needed using musicbrainz-mbid-p )

(musicbrainz-lookup "artist" "410c9baf-5469-44f6-9852-826524b80c61" "releases")
(musicbrainz-lookup-artist "410c9baf-5469-44f6-9852-826524b80c61")
Autechre electronic music duo Group 410c9baf-5469-44f6-9852-826524b80c61 
(musicbrainz-lookup-artist-releases "410c9baf-5469-44f6-9852-826524b80c61")
(musicbrainz-lookup-artist-recordings "410c9baf-5469-44f6-9852-826524b80c61")
(musicbrainz-lookup-release "ec1ecfcc-f529-43d1-8aa6-2c7051ede00c")
1990 Autechre / Saw You Cassette Case ec1ecfcc-f529-43d1-8aa6-2c7051ede00c 
(musicbrainz-lookup-recording "83730176-89ec-41a5-a4b6-476998f6291c")
[untitled] 83730176-89ec-41a5-a4b6-476998f6291c 
(musicbrainz-search-label "Warp")
Warp 46f0f4cd-8aab-4b33-b698-f459faf64190 
(musicbrainz-search-label "Music" 5)
100 Sony Music global brand, excluding JP, owned by Sony Music Entertainment (1991 ongoing) 9e6b4d7f-4958-4db7-8504-d89e315836af
96 [no label] Special purpose label – white labels, self-published releases and other “no label” releases (ongoing) 157afde4-4bf5-4039-8ad2-5a15acc85176
91 Polydor worldwide imprint, see annotation (1913-04-02 ongoing) ce24ab18-1bd6-4293-a486-546d13d6a5e2
91 Universal Music plain logo: “Universal Music” (ongoing) 13a464dc-b9fd-4d16-a4f4-d4316f6a46c7
90 ZYX Music (1992 ongoing) 6844efda-a451-431e-8cc1-48ab111b4711

MBID

“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

(musicbrainz-artist-to-mbid "Autechre")

returns 410c9baf-5469-44f6-9852-826524b80c61

(musicbrainz-mbid-p "410c9baf-5469-44f6-9852-826524b80c61")

ambiguity

From the docs…

John Williams, the soundtrack composer and conductor, has an artist MBID of 53b106e7-0cc6-42cc-ac95-ed8d30a3a98e
John Williams, the classical guitar player, has an artist MBID of 8b8a38a9-a290-4560-84f6-3d4466e8d791

(musicbrainz-disambiguate-artist "John Williams" 3)
Artist: John Williams MBID
100 John Williams, American score composer 53b106e7-0cc6-42cc-ac95-ed8d30a3a98e
94 John Williams, classical guitarist 8b8a38a9-a290-4560-84f6-3d4466e8d791
92 John Williams, English A&R executive, producer, songwriter… eb5d7680-0c00-4b0c-b6eb-9605ff77723d

There are several “Bad Seeds”

(musicbrainz-artist-to-mbid "Bad Seeds")

Which returns the MBID 7feb02f2-51fa-422d-838e-2c14ecb4c7b8 for “Tomorrows Bad Seeds”, however…

(musicbrainz-disambiguate-artist "Bad Seeds" 7)
Artist: Bad Seeds MBID
100 Tomorrows Bad Seeds, nil 7feb02f2-51fa-422d-838e-2c14ecb4c7b8
98 The Bad Seeds, 60s Texas rock band 3e593712-9f70-4b7a-b21b-466016998a3d
98 The Bad Seeds, 60's US garage rock band from Erlanger, KY 34bc9a97-fa78-424e-8ca8-a904f978f041
98 The Bad Seeds, backing band for Nick Cave eb2a8edc-5670-4896-82be-87db38de9583
86 Nick Cave & the Bad Seeds, nil 172e1f1a-504d-4488-b053-6344ba63e6d0
50 The Lightning Seeds, nil 1ba601a0-3401-4b28-8ddd-9af8203661e8
49 Seeds, UK dancehall a03cf587-a3d3-4847-ac41-e488f779a313 
(musicbrainz-lookup-artist "172e1f1a-504d-4488-b053-6344ba63e6d0")

incompleteness

general, specific and partial API coverage

Searching & browsing

Search supports the full Lucene search syntax in queries.

(musicbrainz-search type query &optional limit offset) see musicbrainz-search-types
(musicbrainz-browse entity link query &optional type) and musicbrainz-entities-*
(musicbrainz-search-artist artist &optional limit)
(musicbrainz-artist-to-mbid artist)
(musicbrainz-disambiguate-artist artist &optional limit)
(musicbrainz-search-label label &optional limit)
(musicbrainz-search-recording query &optional limit)
(musicbrainz-search-release query &optional limit)
(musicbrainz-search-work query &optional limit)

Lookup queries & subqueries

(musicbrainz-lookup entity MBID &optional inc) valid entities listed in musicbrainz-entities-core
Functions & formatted output example MBID
(musicbrainz-lookup-area MBID) c9ac1239-e832-41bc-9930-e252a1fd1105
(musicbrainz-lookup-artist MBID) 410c9baf-5469-44f6-9852-826524b80c61
(musicbrainz-lookup-artist-recordings MBID) …
(musicbrainz-lookup-artist-releases MBID) …
(musicbrainz-lookup-artist-release-groups MBID) …
(musicbrainz-lookup-artist-works MBID) …
(musicbrainz-lookup-collection MBID) …
(musicbrainz-lookup-collection-user-collections MBID) …
(musicbrainz-lookup-event MBID) 7c132556-e902-4481-b9cb-ec76a175628a
(musicbrainz-lookup-genre MBID) 68c81274-5770-4e7b-a4bf-ab0d7d425d99
(musicbrainz-lookup-instrument MBID) 303d4f1a-f799-4c42-9bac-dbedd9139e91
(musicbrainz-lookup-label MBID) 8943d408-940c-403b-a01d-9036c227d50f
(musicbrainz-lookup-label-releases MBID) …
(musicbrainz-lookup-place MBID) 73cba8a4-cacb-45b9-8e02-654f716e2e7a
(musicbrainz-lookup-recording MBID) ef8b34c1-8548-472c-872f-03e0d8d3bb37
(musicbrainz-lookup-recording-artists MBID) …
(musicbrainz-lookup-recording-releases MBID) …
(musicbrainz-lookup-recording-isrcs MBID) …
(musicbrainz-lookup-recording-url-rels MBID) …
(musicbrainz-lookup-release MBID) …
(musicbrainz-lookup-release-artists MBID) …
(musicbrainz-lookup-release-collections MBID) …
(musicbrainz-lookup-release-labels MBID) …
(musicbrainz-lookup-release-recordings MBID) …
(musicbrainz-lookup-release-release-groups MBID) …
(musicbrainz-lookup-release-group MBID) fe4acfe9-6d1e-3565-8857-fb16ddc492ab
(musicbrainz-lookup-release-group-artists MBID) …
(musicbrainz-lookup-release-group-releases MBID) …
(musicbrainz-lookup-series MBID) …
(musicbrainz-lookup-work MBID) 4ee2545d-2be5-3841-b568-0b4554eccc67
(musicbrainz-lookup-url MBID) …

ListenBrainz

listening

examples

(setq listenbrainz-api-token "000-000-000")
(listenbrainz-validate-token listenbrainz-api-token)
(listenbrainz-listens "zzzkt")
(listenbrainz-listens "zzzkt" 33)
(listenbrainz-submit-single-listen "Matthew Thomas" "Taema" "Architecture")
(listenbrainz-submit-single-listen "farmersmanual" "808808008088 (11)")
(listenbrainz-submit-playing-now "farmersmanual" "808808008088 (11)")
(listenbrainz-playing-now "zzzkt")
(listenbrainz-stats-artists "zzzkt")
(listenbrainz-stats-releases "zzzkt")
(listenbrainz-stats-recordings "zzzkt" 13 "month")

incompleteness

Core API endpoints

https://listenbrainz.readthedocs.io/en/production/dev/api/#core-api-endpoints

POST /1/submit-listens listenbrainz-submit-listen
listenbrainz-submit-single-listen
listenbrainz-submit-playing-now
GET /1/validate-token listenbrainz-validate-token
POST /1/delete-listen -
GET /1/user/(playlistusername)/playlists/collaborator -
GET /1/user/(playlistusername)/playlists/createdfor -
GET /1/users/(userlist)/recent-listens -
GET /1/user/(username)/similar-users -
GET /1/user/(username)/listen-count -
GET /1/user/(username)/playing-now listenbrainz-playing-now
GET /1/user/(username)/similar-to/(otherusername) -
GET /1/user/(playlistusername)/playlists -
GET /1/user/(username)/listens listenbrainz-listens
GET /1/latest-import -
POST /1/latest-import -

Feedback API Endpoints

https://listenbrainz.readthedocs.io/en/production/dev/api/#feedback-api-endpoints

POST /1/feedback/recording-feedback -
GET /1/feedback/recording/(recordingmsid)/get-feedback -
GET /1/feedback/user/(username)/get-feedback-for-recordings –
GET /1/feedback/user/(username)/get-feedback -

Recording Recommendation API Endpoints

https://listenbrainz.readthedocs.io/en/production/dev/api/#core-api-endpoints

GET /1/cf/recommendation/user/(username)/recording -

Recording Recommendation Feedback API Endpoints

https://listenbrainz.readthedocs.io/en/production/dev/api/#recording-recommendation-feedback-api-endpoints

POST /1/recommendation/feedback/submit -
POST /1/recommendation/feedback/delete -
GET /1/recommendation/feedback/user/(username)/recordings -
GET /1/recommendation/feedback/user/(username) -

Statistics API Endpoints

https://listenbrainz.readthedocs.io/en/production/dev/api/#statistics-api-endpoints

GET /1/stats/sitewide/artists -
GET /1/stats/user/(username)/listening-activity -
GET /1/stats/user/(username)/daily-activity -
GET /1/stats/user/(username)/recordings listenbrainz-stats-recordings
GET /1/stats/user/(username)/artist-map -
GET /1/stats/user/(username)/releases listenbrainz-stats-releases
GET /1/stats/user/(username)/artists listenbrainz-stats-artists

Status API Endpoints

https://listenbrainz.readthedocs.io/en/production/dev/api/#status-api-endpoints

GET /1/status/get-dump-info -

User Timeline API Endpoints

https://listenbrainz.readthedocs.io/en/production/dev/api/#user-timeline-api-endpoints

POST /1/user/(username)/timeline-event/create/notification -
POST /1/user/(username)/timeline-event/create/recording -
POST /1/user/(username)/feed/events/delete -
GET /1/user/(username)/feed/events -

Social API Endpoints

https://listenbrainz.readthedocs.io/en/production/dev/api/#social-api-endpoints

GET /1/user/(username)/followers listenbrainz-followers
GET /1/user/(username)/following listenbrainz-following
POST /1/user/(username)/unfollow -
POST /1/user/(username)/follow -

Pinned Recording API Endpoints

https://listenbrainz.readthedocs.io/en/production/dev/api/#pinned-recording-api-endpoints

POST /1/pin/unpin -
POST /1/pin -
POST /1/pin/delete/(rowid) -
GET /1/(username)/pins/following -
GET /1/(username)/pins -

otherBrainz

further