MusicBrainz API Client

Common errors

• ERR_REQUIRE_ESM

  cause Attempting to use `require()` to import the `musicbrainz-api` package in a CommonJS module, but the library is pure ESM.
  fix Change your import statement to `import { MusicBrainzApi } from 'musicbrainz-api';` and ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`).

• Error searching for artist: MusicBrainzApiError: Bad Request (status: 400)

  cause The MusicBrainz API requires a User-Agent header, which is constructed from `appName`, `appVersion`, and `appContactInfo`. This error indicates one of these was likely missing or invalid.
  fix When initializing `MusicBrainzApi`, ensure all three fields (`appName`, `appVersion`, `appContactInfo`) are provided and valid, e.g., `new MusicBrainzApi({ appName: 'MyApp', appVersion: '1.0.0', appContactInfo: 'me@example.com' })`.

• UnhandledPromiseRejectionWarning: MusicBrainzApiError: Too Many Requests (status: 429)

  cause Your application has sent too many requests in a short period, exceeding MusicBrainz's rate limits.
  fix Review your application's request frequency. While the library implements retries, sustained high volume can still trigger this. Ensure `appContactInfo` is valid. Consider spacing out requests or implementing custom back-off strategies if necessary.

• Cannot find name 'Artist'.

  cause In TypeScript, the `Artist` type was imported using a regular `import` statement instead of `import type`, or the import path was incorrect.
  fix For type-only imports, use `import type { Artist } from 'musicbrainz-api';`. If `Artist` is used as a value, ensure it's exported as such (though typically it's only a type).

Warnings

• breaking Starting from version 8.0.0, `musicbrainz-api` is a pure ECMAScript Module (ESM) and no longer supports CommonJS `require()`. This also elevates the minimum required Node.js version to 16 or higher.
  Fix: Migrate your project to ESM by adding `"type": "module"` to your `package.json` and updating `require()` calls to `import` statements. Ensure your Node.js version is 16 or newer.
• gotcha MusicBrainz API clients are required to identify their application via the User-Agent header. Failure to provide `appName`, `appVersion`, and `appContactInfo` when initializing `MusicBrainzApi` will result in HTTP 400 Bad Request errors.
  Fix: Always initialize the client with `new MusicBrainzApi({ appName: 'YourAppName', appVersion: 'X.Y.Z', appContactInfo: 'you@example.com' })`.
• breaking Error reporting for `400 Bad Request` responses was improved in `v1.1.0`. Code relying on specific error message formats or structures for 400-level errors in older versions may behave differently.
  Fix: Review error handling logic, especially for 400 Bad Request responses, and adapt to potentially more detailed or structured error objects. Implement robust error parsing to avoid future breaking changes.
• gotcha While the library implements intelligent throttling and retries on rate limit hits, excessive or misconfigured requests can still lead to temporary IP bans or persistent `429 Too Many Requests` errors from the MusicBrainz server. Ensure `appContactInfo` is valid for communication.
  Fix: Ensure your application adheres to reasonable request patterns. For heavy usage, consider distributing requests over time or reaching out to MusicBrainz for specific permissions if necessary. Provide accurate `appContactInfo`.
• breaking Prior to version 0.24.0, the `browse` function was more restrictive, only allowing a single MusicBrainz ID (MBID) per entity. Version 0.24.0 introduced new overloads allowing more flexible usage with optional `inc` parameters.
  Fix: If migrating from older versions, update calls to `browse` to utilize the new overloads, which may require adjusting how entity IDs and include parameters are passed. For new development, prefer the most flexible `browse` signatures.

Install

• npm install musicbrainz-api npm
• yarn add musicbrainz-api yarn
• pnpm add musicbrainz-api pnpm

Imports

• MusicBrainzApi
  wrong:

  const MusicBrainzApi = require('musicbrainz-api')

  correct:

  import { MusicBrainzApi } from 'musicbrainz-api'

  The library is pure ECMAScript Module (ESM) since v8. CommonJS `require()` is not supported.
• Artist
  wrong:

  import { Artist } from 'musicbrainz-api'

  correct:

  import type { Artist } from 'musicbrainz-api'

  When importing types for type annotations in TypeScript, use `import type` to ensure they are stripped from the JavaScript output.
• ReleaseIncludes

  import type { ReleaseIncludes } from 'musicbrainz-api'

  Used to specify included relations when fetching data, enabling more comprehensive responses from the API.

Quickstart

Initializes the MusicBrainz API client and performs a search for an artist, logging basic details.

import { MusicBrainzApi } from 'musicbrainz-api';
import type { Artist } from 'musicbrainz-api';

const client = new MusicBrainzApi({
  appName: 'MyAwesomeApp',
  appVersion: '1.0.0',
  appContactInfo: 'mailto:me@example.com' // Required by MusicBrainz API
});

async function searchArtist(query: string) {
  try {
    console.log(`Searching for artist: ${query}...`);
    const result = await client.searchArtist(query);
    if (result.artists && result.artists.length > 0) {
      const firstArtist: Artist = result.artists[0];
      console.log(`Found artist: ${firstArtist.name} (MBID: ${firstArtist.id})`);
      if (firstArtist.area) {
        console.log(`  Area: ${firstArtist.area.name}`);
      }
      if (firstArtist['life-span']) {
        console.log(`  Life Span: ${firstArtist['life-span'].begin || 'Unknown'} - ${firstArtist['life-span'].end || 'Present'}`);
      }
    } else {
      console.log('No artists found.');
    }
  } catch (error) {
    console.error('Error searching for artist:', error);
  }
}

searchArtist('Radiohead');
searchArtist('Pink Floyd');