TypeScript icon, indicating that this package has built-in type declarations

    0.6.0 • Public • Published

    Node.js CI NPM version npm downloads Coverage Status Codacy Badge Language grade: JavaScript Dependencies Known Vulnerabilities Total alerts DeepScan grade Discord


    A MusicBrainz-API-client for reading and submitting metadata


    • Access metadata from MusicBrainz
    • Submit metadata
    • Smart and adjustable throttling, like MusicBrainz, it allows a bursts of requests
    • Build in TypeScript definitions

    Before using this library

    MusicBrainz asks that you identifying your application by filling in the 'User-Agent' Header. By passing appName, appVersion, appMail musicbrainz-api takes care of that.

    Submitting metadata

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


    Import the module JavaScript example, how to import 'musicbrainz-api:

    const MusicBrainzApi = require('musicbrainz-api').MusicBrainzApi;
    const mbApi = new MusicBrainzApi({
      appName: 'my-app',
      appVersion: '0.1.0',
      appContactInfo: ''

    In TypeScript you it would look like this:

    import {MusicBrainzApi} from 'musicbrainz-api';
    const mbApi = new MusicBrainzApi({
      appName: 'my-app',
      appVersion: '0.1.0',
      appContactInfo: '' // Or URL to application home page

    The following configuration settings can be passed

    import {MusicBrainzApi} from '../src/musicbrainz-api';
    const config = {
      // MusicBrainz bot account username & password (optional)
      botAccount: { 
        username: 'myUserName_bot',
        password: 'myPassword' 
      // API base URL, default: '' (optional)
      baseUrl: '',
      appName: 'my-app',
      appVersion: '0.1.0',
      // Optional, default: no proxy server
      proxy: {
        host: 'localhost',
        port: 8888
      // Your e-mail address, required for submitting ISRCs
      appMail: string
    const mbApi = new MusicbrainzApi(config);

    Lookup MusicBrainz Entities

    MusicBrainz API documentation: XML Web Service/Version 2 Lookups

    Generic lookup function


    • entity: 'artist' | 'label' | 'recording' | 'release' | 'release-group' | 'work' | 'area' | 'url'
    • MBID (MusicBrainz identifier)
    const artist = await mbApi.getEntity('artist', 'ab2528d9-719f-4261-8098-21849222a0f2');

    Lookup area

    const area = await mbApi.getArea('ab2528d9-719f-4261-8098-21849222a0f2');

    Lookup artist

    Lookup an artist and include their releases, release-groups and aliases

    const artist = await mbApi.getArtist('ab2528d9-719f-4261-8098-21849222a0f2');

    The second argument can be used to pass subqueries, which will return more (nested) information:

    const artist = await mbApi.getArtist('ab2528d9-719f-4261-8098-21849222a0f2', ['releases', 'recordings', 'url-rels']);

    Lookup recording

    The second argument can be used to pass subqueries:

    const artist = await mbApi.getRecording('16afa384-174e-435e-bfa3-5591accda31c', ['artists', 'url-rels']);

    Lookup release

    const release = await mbApi.getRelease('976e0677-a480-4a5e-a177-6a86c1900bbf', ['artists', 'url-rels']);

    Lookup release-group

    const releaseGroup = await mbApi.getReleaseGroup('19099ea5-3600-4154-b482-2ec68815883e');

    Lookup work

    const work = await mbApi.getWork('b2aa02f4-6c95-43be-a426-aedb9f9a3805');

    Search (query)

    Implements XML Web Service/Version 2/Search.

    There are different search fields depending on the entity.

    Generic search function

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

    Example: search Île-de-France'area', 'Île-de-France');
    Example: search release by barcode

    Search a release with the barcode 602537479870:'release', {barcode: 602537479870});
    Example: search by object

    Same as previous example, but automatically serialize parameters to search query'release', 'barcode: 602537479870');

    Entity specific search functions

    The following entity specific search functions are available:

    searchArtist(query: string | IFormData, offset?: number, limit?: number): Promise<mb.IArtistList>
    searchReleaseGroup(query: string | IFormData, offset?: number, limit?: number): Promise<mb.IReleaseGroupList>`


    • 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 at Lucene 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 find any recordings of 'We Will Rock You' by Queen:

    const query = 'query="We Will Rock You" AND arid:0383dadf-2a4e-4d10-a46a-e9e041da8eb3';
    const result = await mbApi.query<mb.IReleaseGroupList>('release-group', {query});

    Specialized search functions

    Search artist:

    const result = await mbApi.searchArtist('Stromae');

    Search release-group:

    const result = await mbApi.searchReleaseGroup('Racine carrée');

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

    const result = await mbApi.searchReleaseGroup({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 the XML ISRC submission API.

    const mbid_Formidable = '16afa384-174e-435e-bfa3-5591accda31c';
    const isrc_Formidable = 'BET671300161';
    const xmlMetadata = new XmlMetadata();
    const xmlRecording = xmlMetadata.pushRecording(mbid_Formidable);
    await'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 as side effect.
    const mbid_Formidable = '16afa384-174e-435e-bfa3-5591accda31c';
    const isrc_Formidable = 'BET671300161';
    const recording = await mbApi.getRecording(mbid_Formidable);
    // Authentication the http-session against MusicBrainz (as defined in config.baseUrl)
    const succeed = await mbApi.login();
    assert.isTrue(succeed, 'Login successful');
    // To submit the ISRC, the `` and `recording.title` are required
    await mbApi.addIsrc(recording, isrc_Formidable);

    Submit recording URL

    const recording = await mbApi.getRecording('16afa384-174e-435e-bfa3-5591accda31c');
    const succeed = await mbApi.login();
    assert.isTrue(succeed, 'Login successful');
    await mbApi.addUrlToRecording(recording, {
      linkTypeId: LinkType.stream_for_free,
      text: ''

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

    const recording = await mbApi.getRecording('16afa384-174e-435e-bfa3-5591accda31c');
    const succeed = await mbApi.login();
    assert.isTrue(succeed, 'Login successful');
    await mbApi.addSpotifyIdToRecording(recording, '2AMysGXOe0zzZJMtH3Nizb');


    The JavaScript in runtime is compliant with ECMAScript 2017 (ES8). Requires Node.js® version 6 or higher.


    npm i musicbrainz-api

    DownloadsWeekly Downloads






    Unpacked Size

    430 kB

    Total Files


    Last publish


    • avatar