musicbrainz-api

You can use include arguments to request additional related data when performing lookups. These are categorized into subqueries, arguments that affect subqueries, miscellaneous arguments, and relationships.

Subqueries

Subqueries allow you to request specific related entities. For example, requesting an artist with the releases include will return the artist's releases.

Arguments affecting subqueries

These specify the depth or specific details of the subqueries, such as including discids for all media in releases or artist-credits for all releases and recordings.

Relationships

Relationships allow you to load links between the requested entity and a specific entity type (e.g., artist-rels loads relationships between an artist and other artists). For deeper traversal, use:

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

/* See reference records for full enumeration of include arguments and relationships */

The musicbrainz-api library is a pure ESM module. If you are working in a CommonJS environment, you have three options for importing it depending on your Node.js version and build tool:

1. Node.js ≥ 22: You can use standard require() as Node.js now supports loading ESM modules via require.
2. Standard CommonJS: Use a dynamic import() call within an async function.
3. TypeScript CommonJS: Standard dynamic imports may be incorrectly converted to require() by the TypeScript compiler. In this case, use the load-esm package to ensure the module is loaded correctly.

// Option 1: Node.js ≥ 22
const { MusicBrainzApi } = require('musicbrainz-api');

// Option 2: Standard CommonJS dynamic import
async function run() {
  const { MusicBrainzApi } = await import('musicbrainz-api');
};
run();

// Option 3: TypeScript CommonJS using load-esm
import {loadEsm} from 'load-esm';

async function run() {
  const { MusicBrainzApi } = await loadEsm<typeof import('musicbrainz-api')>('musicbrainz-api');
};
run();

When instantiating MusicBrainzApi, you can provide several configuration options to control authentication, networking, and rate limiting.

const config = {
    // Optional: MusicBrainz bot account credentials
    botAccount: {
        username: 'myUserName_bot',
        password: 'myPassword',
    },

    // Optional: API base URL (default: 'https://musicbrainz.org')
    baseUrl: 'https://musicbrainz.org',

    // Required: Application details
    appName: 'my-app',
    appVersion: '0.1.0',
    appContactInfo: 'user@mail.org',

    // Optional: Proxy settings (default: no proxy server)
    proxy: {
        host: 'localhost',
        port: 8888,
    },

    // Optional: Disable rate limiting (default: false)
    disableRateLimiting: false,

    // Optional: Set max number of request with X seconds
    //           (default: 15 requests every 18 seconds)
    rateLimit: [15, 18]
};

const mbApi = new MusicBrainzApi(config);

The library defines several primary entities that represent the MusicBrainz data model. Most entities implement IEntity (providing an id) and often ITypedEntity (providing id, type, and type-id).

Key entities include:

• IArtist: Represents a musical artist, including aliases, gender, and life span.
• IRelease: Represents a specific release (e.g., a CD or digital album), including status, packaging, and media.
• IReleaseGroup: A higher-level grouping for releases (e.g., an album version), containing artist credits and primary types.
• IRecording: Represents a specific musical recording, including length, title, and associated releases.
• IWork: Represents a musical composition or work.
• ILabel: Represents a record label.
• ISeries: Represents a collection of release groups.
• IArea: Represents a geographic area (Country, City, etc.).
• IPlace: Represents a specific location with coordinates.

The library provides a CoverArtArchiveApi class to fetch cover art for releases and release groups.

Fetching Release Cover Art

• getReleaseCovers(releaseMbid): Returns all available cover art information for a release.
• getReleaseCover(releaseMbid, type): Fetches a specific cover (e.g., 'front' or 'back').

Fetching Release Group Cover Art

• getReleaseGroupCovers(releaseMbid): Returns all available cover art for a release group.
• getReleaseGroupCover(releaseMbid, type): Fetches a specific cover for a release group.

import { CoverArtArchiveApi } from 'musicbrainz-api';

const coverArtArchiveApiClient = new CoverArtArchiveApi();

// Example: Fetching all covers for a release
const coverInfo = await coverArtArchiveApiClient.getReleaseCovers('976e0677-a480-4a5e-a177-6a86c1900bbf');
for(const image of coverInfo.images) {
    console.log(`Cover art front=${image.front} back=${image.back} url=${image.image}`);
}

// Example: Fetching a specific front cover for a release
const frontCover = await coverArtArchiveApiClient.getReleaseCover('976e0677-a480-4a5e-a177-6a86c1900bbf', 'front');
console.log(`Cover art url=${frontCover.url}`);