Borewit/musicbrainz-apiPublic

NotificationsYou must be signed in to change notification settings
Fork42
Star183

JavaScript MusicBrainz API client for reading and submitting metadata

License

MIT license

183 stars 42 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 873 Commits
.github		.github
doc		doc
lib		lib
test		test
.c8rc.json		.c8rc.json
.gitattributes		.gitattributes
.gitignore		.gitignore
.mocharc.json		.mocharc.json
.yarnrc.yml		.yarnrc.yml
LICENSE.txt		LICENSE.txt
README.md		README.md
biome.jsonc		biome.jsonc
lgtm.yml		lgtm.yml
package.json		package.json
tsconfig.json		tsconfig.json
yarn.lock		yarn.lock

Repository files navigation

musicbrainz-api

A MusicBrainz-API-client for reading and submitting metadata.

Features

Access Metadata: Retrieve detailed metadata from theMusicBrainz database.
Submit metadata: Easily submit new metadata toMusicBrainz.
Smart throttling: Implements intelligent throttling, allowing bursts of requests while adhering toMusicBrainz rate limits.
TypeScript Definitions: Fully typed with built-inTypeScript definitions for a seamless development experience.

Compatibility

Module: version 8 migrated fromCommonJS topure ECMAScript Module (ESM).The distributed JavaScript codebase is compliant with theECMAScript 2020 (11th Edition) standard.

Note

Requirements

Node.js: RequiresNode.js version 16 or higher.
Browser: Can be used in browser environments when bundled with a module bundler (not actively tested).

Note

We are looking into making this package usable in the browser as well.

Support the Project

If you find this project useful and would like to support its development, consider sponsoring or contributing:

Become a sponsor to Borewit
Buy me a coffee:

Getting Started

Identifying Your Application

MusicBrainz requires all API clients toidentify their application.Ensure you set the User-Agent header by providingappName,appVersion, andappContactInfo when configuring the client.This library will automatically handle this for you.

Submitting metadata

If you plan to use this module for submitting metadata, please ensure you comply withthe MusicBrainz Code of conduct/Bots.

Example Usage

Importing the Library

import{MusicBrainzApi}from'musicbrainz-api';constmbApi=newMusicBrainzApi({appName:'my-app',appVersion:'0.1.0',appContactInfo:'user@mail.org',});

Note

Configuration Options

constconfig={// Optional: MusicBrainz bot account credentialsbotAccount:{username:'myUserName_bot',password:'myPassword',},// Optional: API base URL (default: 'https://musicbrainz.org')baseUrl:'https://musicbrainz.org',// Required: Application detailsappName:'my-app',appVersion:'0.1.0',appMail:'user@mail.org',// Optional: Proxy settings (default: no proxy server)proxy:{host:'localhost',port:8888,},// Optional: Disable rate limiting (default: false)disableRateLimiting:false,};constmbApi=newMusicBrainzApi(config);

Accessing MusicBrainz Data

The MusicBrainz API allows you to look up various entities. Here’s how to use the lookup function:

Lookup MusicBrainz Entities

You can use the lookup function, to look up an entity, when you have the MBID for that entity.MusicBrainz API documentation:MusicBrainz API - Lookups

Lookup Function

constartist=awaitmbApi.lookup('artist','ab2528d9-719f-4261-8098-21849222a0f2',['recordings']);

Arguments:

entity (string):'area' |'artist' |'collection' |'instrument' |'label' |'place' |'release' |'release-group' |'recording' |'series' |'work' |'url' |'event'
MBID (string):(MusicBrainz identifier)
include arguments (string[]), seeInclude arguments

Lookup URLs

There is special method to lookup URL entity / entities by one, or an array of URLs(MusicBrainz API documentation: url (by text)):

consturls=awaitmbApi.lookupUrl(['https://open.spotify.com/track/2AMysGXOe0zzZJMtH3Nizb','https://open.spotify.com/track/78Teboqh9lPIxWlIW5RMQL']);

consturl=awaitmbApi.lookupUrl('https://open.spotify.com/track/2AMysGXOe0zzZJMtH3Nizb');

Arguments:

url (string |string[]): URL or array of URLs
include arguments (string[]), seeInclude arguments

Note that the return type is different, depending on if a single URL or an array of URLs is provided.

Browse requests

Browse requests are a direct lookup of all the entities directly linked to another entity ("directly linked" here meaning it does not include entities linked by a relationship).

For example, browsereleases:

constartist_mbid='ab2528d9-719f-4261-8098-21849222a0f2';constreleases=awaitmbApi.browse('release',{track_artist:artist_mbid,limit:0,offset:0,},['url-rels','isrcs','recordings']);

For the optional include arguments (string[]), seeInclude arguments.

Browse artist

constartists=awaitmbApi.browse('artist',query);constartists=awaitmbApi.browse('artist',query,['area','collection']);

Query argument	Query value
`query.area`	Area MBID
`query.collection`	Collection MBID
`query.recording`	Recording MBID
`query.release`	Release MBID
`query.release-group`	Release-group MBID
`query.work`	Work MBID

Browse collection

constcollections=awaitmbApi.browse('collection',query);constcollections=awaitmbApi.browse('collection',query,['area','artist']);

Query argument	Query value
`query.area`	Area MBID
`query.artist`	Artist MBID
`query.editor`	Editor MBID
`query.event`	Event MBID
`query.label`	Label MBID
`query.place`	Place MBID
`query.recording`	Recording MBID
`query.release`	Release MBID
`query.release-group`	Release-group MBID
`query.work`	Work MBID

Browse events

constevents=awaitmbApi.browse('event',query);constevents=awaitmbApi.browse('instrument',query,['area','artist']);

Query argument	Query value
`query.area`	Area MBID
`query.artist`	Artist MBID
`query.collection`	Collection MBID
`query.place`	Place MBID

Browse instruments

constinstruments=awaitmbApi.browse('instrument',query);constinstruments=awaitmbApi.browse('instrument',query,['collection']);

Query argument	Query value
`query.collection`	Collection MBID

Browse labels

constlabels=awaitmbApi.browse('label',query);constplaces=awaitmbApi.browse('place',query,['area','collection']);

Query argument	Query value
`query.area`	Area MBID
`query.collection`	Collection MBID
`query.release`	Release MBID

Browse places

constplaces=awaitmbApi.browse('place',query);constplaces=awaitmbApi.browse('place',query,['area','collection']);

Query argument	Query value
`query.area`	Area MBID
`query.collection`	Collection MBID

Browse recordings

constrecordings=awaitmbApi.browse('recording',query,['artist']);

Query argument	Query value
`query.artist`	Area MBID
`query.collection`	Collection MBID
`query.release`	Release MBID
`query.work`	Work MBID

Browse releases

constreleases=awaitmbApi.browse('release',query);constreleases=awaitmbApi.browse('release',query,['artist','track']);

Query argument	Query value
`query.area`	Area MBID
`query.artist`	Artist MBID
`query.editor`	Editor MBID
`query.event`	Event MBID
`query.label`	Label MBID
`query.place`	Place MBID
`query.recording`	Recording MBID
`query.release`	Release MBID
`query.release-group`	Release-group MBID
`query.work`	Work MBID

Browse release-groups

constreleaseGroups=awaitmbApi.browse('release-group',query);constreleaseGroups=awaitmbApi.browse('release-group',query,['artist','release']);

Query argument	Query value
`query.artist`	Artist MBID
`query.collection`	Collection MBID
`query.release`	Release MBID

Browse series

constseries=awaitmbApi.browse('series');constseries=awaitmbApi.browse('series',['collection']);

Query argument	Query value
`query.area`	Area MBID
`query.artist`	Artist MBID
`query.editor`	Editor MBID
`query.event`	Event MBID
`query.label`	Label MBID
`query.place`	Place MBID
`query.recording`	Recording MBID
`query.release`	Release MBID
`query.release-group`	Release-group MBID
`query.work`	Work MBID

Browse works

constworks=awaitmbApi.browse('work');constseries=awaitmbApi.browse('series',['artist','collection']);

Query argument	Query value
`query.artist`	Artist MBID
`query.xollection`	Collection MBID

Browse urls

consturls=awaitmbApi.browse('url');constseries=awaitmbApi.browse('series',['artist','collection','artist-rels']);

Query argument	Query value
`query.artist`	Artist MBID
`query.xollection`	Collection MBID

Search (query)

ImplementsMusicBrainz API: Search.

There are different search fields depending on the entity.

Search function

Searches can be performed using the generic search function:query(entity: mb.EntityType, query: string | IFormData, offset?: number, limit?: number): Promise<entity>

Arguments:

Entity type, which can be one of:
- annotation:search fields
- area:search fields
- artist:search fields
- cdstub:search fields
- event:search fields
- instrument:search fields
- label:search fields
- place:search fields
- recording:search fields
- release:search fields
- release-group:search fields
- series:search fields
- tag:search fields
- url:search fields
- work:search fields
query {query: string, offset: number, limit: number}
- query.query: supports the full Lucene Search syntax; you can find a detailed guide atLucene Search Syntax. For example, you can set conditions while searching for a name with the AND operator.
- query.offset: optional, return search results starting at a given offset. Used for paging through more than one page of results.
- limit.query: optional, an integer value defining how many entries should be returned. Only values between 1 and 100 (both inclusive) are allowed. If not given, this defaults to 25.

For example, to search forrelease-group:"We Will Rock You" byQueen:

constquery='query=artist:"Queen" AND release:"We Will Rock You"';constresult=awaitmbApi.search('release-group',{query});

Example: search Île-de-France

mbApi.search('area','Île-de-France');

Example: search release by barcode

Search a release with the barcode 602537479870:

mbApi.search('release',{query:{barcode:602537479870}});

Example: search by object

Same as previous example, but automatically serialize parameters to search query

mbApi.search('release','barcode: 602537479870');

Example: search artist by artist name

Search artist:

constresult=awaitmbApi.search('artist',{query:'Stromae'});

Example: search release-group by artist name

Search release-group:

constresult=awaitmbApi.search('release-group',{query:'Racine carrée'});

Example: search release-group by release-group and an artist

Search a combination of a release-group and an artist.

constresult=awaitmbApi.search('release-group',{artist:'Racine carrée',releasegroup:'Stromae'});

Include arguments

Subqueries

Include Arguments which allow you to request more information to be included about the entity.

entity	supportedinclude arguments
`area`
`artist`	`recordings`,`releases`,`release-groups`,`works`
`collection`	`user-collections` (includes private collections, requires authentication)
`event`
`genre`
`instrument`
`label`	`releases`
`place`
`recording`	`artists`,`releases`,`release-groups`,`isrcs`,`url-rels`
`release`	`artists`,`collections`,`labels`,`recordings`,`release-groups`
`release-group`	`artists`,`releases`
`series`
`work`
`url`

Arguments which affect subqueries

Some additionalinclude parameters are supported to specify how much of the data about the linked entities should be included:

include argument	Description
`discids`	include discids for all media in the releases
`media`	include media for all releases, this includes the # of tracks on each medium and its format.
`isrcs`	user-collections (includes private collections, requires authentication)include isrcs for all recordings
`artist-credits`	include artists credits for all releases and recordings
`various-artists`	include only those releases where the artist appears on one of the tracks, but not in the artist credit for the release itself (this is only valid on entity`"artist"` andinclude argument`"releases request"`).

Miscellaneous arguments

include argument	Description
`aliases`	include artist, label, area or work aliases; treat these as a set, as they are not deliberately ordered
`annotation`	include annotation
`tags`,`ratings`	include tags and/or ratings for the entity
`user-tags`,`user-ratings`	same as above, but only return the tags and/or ratings submitted by the specified user
`genres`,`user-genres`	include genres (tags in thegenres list): either all or the ones submitted by the user, respectively

Relationships

You can request relationships with the appropriate includes:

area-rels
artist-rels
event-rels
genre-rels
instrument-rels
label-rels
place-rels
recording-rels
release-rels
release-group-rels
series-rels
url-rels
work-rels

These will load relationships between the requested entity and the specific entity type.For example, if you request "work-rels" when looking up an artist,you'll get all the relationships between this artist and any works,and if you request "artist-rels" you'll get the relationships between this artist and any other artists.As such, keep in mind requesting "artist-rels" for an artist, "release-rels" for a release, etc. will not load all the relationships for the entity, just the ones to other entities of the same type.

In a release request, you might also be interested on relationships for the recordings linked to the release, or the release group linked to the release, or even for the works linked to those recordings that are linked to the release (for example, to find out who played guitar on a specific track, who wrote the lyrics for the song being performed, or whether the release group is part of a series). Similarly, for a recording request, you might want to get the relationships for any linked works.There are three additional includes for this:

recording-level-rels
release-group-level-rels (for releases only)
work-level-rels

Submitting data via XML POST

Submitting data via XML POST may be done using personal MusicBrainz credentials.

Submit ISRC code using XML POST

Using theXML ISRC submission API.

constmbid_Formidable='16afa384-174e-435e-bfa3-5591accda31c';constisrc_Formidable='BET671300161';constxmlMetadata=newXmlMetadata();constxmlRecording=xmlMetadata.pushRecording(mbid_Formidable);xmlRecording.isrcList.pushIsrc(isrc_Formidable);awaitmbApi.post('recording',xmlMetadata);

Submitting data via user form-data

For all of the following function you need to use a dedicated bot account.

Submitting ISRC via post user form-data

Use with caution, and only on a test server, it may clear existing metadata has side effect.

constmbid_Formidable='16afa384-174e-435e-bfa3-5591accda31c';constisrc_Formidable='BET671300161';constrecording=awaitmbApi.lookup('recording',mbid_Formidable);// Authentication the http-session against MusicBrainz (as defined in config.baseUrl)constsucceed=awaitmbApi.login();assert.isTrue(succeed,'Login successful');// To submit the ISRC, the `recording.id` and `recording.title` are requiredawaitmbApi.addIsrc(recording,isrc_Formidable);

Submit recording URL

constrecording=awaitmbApi.lookup('recording','16afa384-174e-435e-bfa3-5591accda31c');constsucceed=awaitmbApi.login();assert.isTrue(succeed,'Login successful');awaitmbApi.addUrlToRecording(recording,{linkTypeId:LinkType.stream_for_free,text:'https://open.spotify.com/track/2AMysGXOe0zzZJMtH3Nizb'});

Actually a Spotify-track-ID can be submitted easier:

constrecording=awaitmbApi.lookup('recording','16afa384-174e-435e-bfa3-5591accda31c');constsucceed=awaitmbApi.login();assert.isTrue(succeed,'Login successful');awaitmbApi.addSpotifyIdToRecording(recording,'2AMysGXOe0zzZJMtH3Nizb');

Cover Art Archive API

This library also supports theCover Art Archive API.

Fetch Release Cover Art

Fetch available cover art information

import{CoverArtArchiveApi}from'musicbrainz-api';constcoverArtArchiveApiClient=newCoverArtArchiveApi();asyncfunctionfetchCoverArt(releaseMbid,coverType=''){constcoverInfo=awaitcoverArtArchiveApiClient.getReleaseCovers(releaseMbid);for(constimageofcoverInfo.images){console.log(`Cover art front=${image.front} back=${image.back} url=${image.image}`);}}fetchCoverArt('976e0677-a480-4a5e-a177-6a86c1900bbf').catch(error=>{console.error(`Failed to fetch cover art:${error.message}`);})

Fetch front or back cover for a release

import{CoverArtArchiveApi}from'musicbrainz-api';constcoverArtArchiveApiClient=newCoverArtArchiveApi();asyncfunctionfetchCoverArt(releaseMbid,coverType=''){constcoverInfo=awaitcoverArtArchiveApiClient.getReleaseCover(releaseMbid,'front');console.log(`Cover art url=${coverInfo.url}`);}fetchCoverArt('976e0677-a480-4a5e-a177-6a86c1900bbf').catch(error=>{console.error(`Failed to fetch cover art:${error.message}`);})

Release Group Cover Art

import{CoverArtArchiveApi}from'musicbrainz-api';constcoverArtArchiveApiClient=newCoverArtArchiveApi();asyncfunctionfetchCoverArt(releaseMbid,coverType=''){constcoverInfo=awaitcoverArtArchiveApiClient.getReleaseGroupCovers(releaseMbid);for(constimageofcoverInfo.images){console.log(`Cover art front=${image.front} back=${image.back} url=${image.image}`);}}fetchCoverArt('976e0677-a480-4a5e-a177-6a86c1900bbf').catch(error=>{console.error(`Failed to fetch cover art:${error.message}`);})

Fetch front or back cover for a release-group

import{CoverArtArchiveApi}from'musicbrainz-api';constcoverArtArchiveApiClient=newCoverArtArchiveApi();asyncfunctionfetchCoverArt(releaseMbid,coverType=''){constcoverInfo=awaitcoverArtArchiveApiClient.getReleaseGroupCover(releaseMbid,'front');console.log(`Cover art url=${coverInfo.url}`);}fetchCoverArt('976e0677-a480-4a5e-a177-6a86c1900bbf').catch(error=>{console.error(`Failed to fetch cover art:${error.message}`);})

CommonJS backward compatibility

I recommend CommonJS projects to consider upgrading their project to ECMAScript Module (ESM).Please continue reading how to usemusicbrainz-api in a CommonJS project.

Using Node.js ≥ 22, which is support loading ESM module via require, you can use:

const{ MusicBrainzApi}=require('musicbrainz-api');

Other CommonJS projects have to usedynamic import to load themusicbrainz-api pure ESM module:

asyncfunctionrun(){// Dynamically loads the ESM module in a CommonJS projectconst{ MusicBrainzApi}=awaitimport('musicbrainz-api');};run();

This is known not to work in TypeScript CommonJS projects, as the TypeScript compiler, in my opinion,incorrectly converts thedynamic importtorequire(). To perform the dynamic import in TypeScript, you can useload-esm:

import{loadEsm}from'load-esm';asyncfunctionrun(){// Dynamically loads the ESM module in a TypeScript CommonJS projectconst{ MusicBrainzApi}=awaitloadEsm<typeofimport('musicbrainz-api')>('musicbrainz-api');};run();