Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up

JavaScript MusicBrainz API client for reading and submitting metadata

License

NotificationsYou must be signed in to change notification settings

Borewit/musicbrainz-api

Repository files navigation

Node.js CICodeQLNPM versionnpm downloadsCoverage StatusCodacy BadgeKnown VulnerabilitiesDeepScan gradeDiscordbundlejs.com badge

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.

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:

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',});

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

MusicBrainz API documentation:XML Web Service/Version 2 Lookups

Lookup Function

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

Arguments:

  • entity:'area' |'artist' |'collection' |'instrument' |'label' |'place' |'release' |'release-group' |'recording' |'series' |'work' |'url' |'event'
  • MBID(MusicBrainz identifier)
  • query
Query argumentQuery value
query.collectionCollection MBID

Browse artist

constartists=awaitmbApi.browse('artist',query);
Query argumentQuery value
query.areaArea MBID
query.collectionCollection MBID
query.recordingRecording MBID
query.releaseRelease MBID
query.release-groupRelease-group MBID
query.workWork MBID

Browse collection

constcollections=awaitmbApi.browse('collection',query);
Query argumentQuery value
query.areaArea MBID
query.artistArtist MBID
query.editorEditor MBID
query.eventEvent MBID
query.labelLabel MBID
query.placePlace MBID
query.recordingRecording MBID
query.releaseRelease MBID
query.release-groupRelease-group MBID
query.workWork MBID

Browse events

constevents=awaitmbApi.browse('event',query);
Query argumentQuery value
query.areaArea MBID
query.artistArtist MBID
query.collectionCollection MBID
query.placePlace MBID

Browse instruments

constinstruments=awaitmbApi.browse('event',query);
Query argumentQuery value
query.collectionCollection MBID

Browse labels

constlabels=awaitmbApi.browse('label',query);
Query argumentQuery value
query.areaArea MBID
query.collectionCollection MBID
query.releaseRelease MBID

Browse places

constplaces=awaitmbApi.browse('place',query);
Query argumentQuery value
query.areaArea MBID
query.collectionCollection MBID

Browse recordings

constrecordings=awaitmbApi.browse('recording',query);
Query argumentQuery value
query.artistArea MBID
query.collectionCollection MBID
query.releaseRelease MBID
query.workWork MBID

Browse releases

constreleases=awaitmbApi.browse('release',query);
Query argumentQuery value
query.areaArea MBID
query.artistArtist MBID
query.editorEditor MBID
query.eventEvent MBID
query.labelLabel MBID
query.placePlace MBID
query.recordingRecording MBID
query.releaseRelease MBID
query.release-groupRelease-group MBID
query.workWork MBID

Browse release-groups

constreleaseGroups=awaitmbApi.browse('release-group',query);
Query argumentQuery value
query.artistArtist MBID
query.collectionCollection MBID
query.releaseRelease MBID

Browse series

constseries=awaitmbApi.browse('series');
Query argumentQuery value
query.areaArea MBID
query.artistArtist MBID
query.editorEditor MBID
query.eventEvent MBID
query.labelLabel MBID
query.placePlace MBID
query.recordingRecording MBID
query.releaseRelease MBID
query.release-groupRelease-group MBID
query.workWork MBID

Browse works

constworks=awaitmbApi.browse('work');
Query argumentQuery value
query.artistArtist MBID
query.xollectionCollection MBID

Browse urls

consturls=awaitmbApi.browse('url');
Query argumentQuery value
query.artistArtist MBID
query.xollectionCollection MBID

Search (query)

ImplementsXML Web Service/Version 2/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:
  • 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'});

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

import{CoverArtArchiveApi}from'musicbrainz-api';constcoverArtArchiveApiClient=newCoverArtArchiveApi();asyncfunctiongetReleaseCoverArt(releaseMbid,coverType=''){try{constcoverInfo=awaitcoverArtArchiveApiClient.getReleaseCovers(releaseMbid,coverType);console.log(`Cover info for${coverType||'all covers'}`,coverInfo);}catch(error){console.error(`Failed to fetch${coverType||'all covers'}:`,error);}}(async()=>{constreleaseMbid='your-release-mbid-here';// Replace with actual MBIDawaitgetReleaseCoverArt(releaseMbid);// Get all coversawaitgetReleaseCoverArt(releaseMbid,'front');// Get best front coverawaitgetReleaseCoverArt(releaseMbid,'back');// Get best back cover})();

Release Group Cover Art

import{CoverArtArchiveApi}from'musicbrainz-api';constcoverArtArchiveApiClient=newCoverArtArchiveApi();asyncfunctiongetCoverArt(releaseGroupMbid,coverType=''){try{constcoverInfo=awaitcoverArtArchiveApiClient.getReleaseGroupCovers(releaseGroupMbid,coverType);console.log(`Cover info for${coverType||'all covers'}`,coverInfo);}catch(error){console.error(`Failed to fetch${coverType||'all covers'}:`,error);}}(async()=>{constreleaseGroupMbid='your-release-group-mbid-here';// Replace with actual MBIDawaitgetCoverArt(releaseGroupMbid);// Get all coversawaitgetCoverArt(releaseGroupMbid,'front');// Get best front coverawaitgetCoverArt(releaseGroupMbid,'back');// Get best back cover})();

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();

Licence

This project is licensed under theMIT License. Feel free to use, modify, and distribute as needed.

[8]ページ先頭
©2009-2025 Movatter.jp