{"id":16131,"library":"musicbrainz-api","title":"MusicBrainz API Client","description":"The `musicbrainz-api` package provides a TypeScript-first client for interacting with the MusicBrainz web service, enabling both reading detailed metadata and submitting new information to the database. Currently at stable version 1.2.0, the library maintains an active release cadence with updates typically occurring every few weeks or months. Key differentiators include its robust support for retrieving various entity types, comprehensive TypeScript definitions for enhanced developer experience, and intelligent request throttling that automatically adheres to MusicBrainz API rate limits, including retries for rate-limit hits. It simplifies the required application identification (User-Agent) by prompting for `appName`, `appVersion`, and `appContactInfo` during client configuration. This library exclusively uses ECMAScript Modules (ESM) since version 8, requiring Node.js 16 or higher for usage.","status":"active","version":"1.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/Borewit/musicbrainz-api","tags":["javascript","MusicBrainz","metadata","meta","tag","tags","Picard","json","xml","typescript"],"install":[{"cmd":"npm install musicbrainz-api","lang":"bash","label":"npm"},{"cmd":"yarn add musicbrainz-api","lang":"bash","label":"yarn"},{"cmd":"pnpm add musicbrainz-api","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library is pure ECMAScript Module (ESM) since v8. CommonJS `require()` is not supported.","wrong":"const MusicBrainzApi = require('musicbrainz-api')","symbol":"MusicBrainzApi","correct":"import { MusicBrainzApi } from 'musicbrainz-api'"},{"note":"When importing types for type annotations in TypeScript, use `import type` to ensure they are stripped from the JavaScript output.","wrong":"import { Artist } from 'musicbrainz-api'","symbol":"Artist","correct":"import type { Artist } from 'musicbrainz-api'"},{"note":"Used to specify included relations when fetching data, enabling more comprehensive responses from the API.","symbol":"ReleaseIncludes","correct":"import type { ReleaseIncludes } from 'musicbrainz-api'"}],"quickstart":{"code":"import { MusicBrainzApi } from 'musicbrainz-api';\nimport type { Artist } from 'musicbrainz-api';\n\nconst client = new MusicBrainzApi({\n  appName: 'MyAwesomeApp',\n  appVersion: '1.0.0',\n  appContactInfo: 'mailto:me@example.com' // Required by MusicBrainz API\n});\n\nasync function searchArtist(query: string) {\n  try {\n    console.log(`Searching for artist: ${query}...`);\n    const result = await client.searchArtist(query);\n    if (result.artists && result.artists.length > 0) {\n      const firstArtist: Artist = result.artists[0];\n      console.log(`Found artist: ${firstArtist.name} (MBID: ${firstArtist.id})`);\n      if (firstArtist.area) {\n        console.log(`  Area: ${firstArtist.area.name}`);\n      }\n      if (firstArtist['life-span']) {\n        console.log(`  Life Span: ${firstArtist['life-span'].begin || 'Unknown'} - ${firstArtist['life-span'].end || 'Present'}`);\n      }\n    } else {\n      console.log('No artists found.');\n    }\n  } catch (error) {\n    console.error('Error searching for artist:', error);\n  }\n}\n\nsearchArtist('Radiohead');\nsearchArtist('Pink Floyd');","lang":"typescript","description":"Initializes the MusicBrainz API client and performs a search for an artist, logging basic details."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=8.0.0"},{"fix":"Always initialize the client with `new MusicBrainzApi({ appName: 'YourAppName', appVersion: 'X.Y.Z', appContactInfo: 'you@example.com' })`.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.1.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=0.25.1"},{"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.","message":"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.","severity":"breaking","affected_versions":"<0.24.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`).","cause":"Attempting to use `require()` to import the `musicbrainz-api` package in a CommonJS module, but the library is pure ESM.","error":"ERR_REQUIRE_ESM"},{"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' })`.","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.","error":"Error searching for artist: MusicBrainzApiError: Bad Request (status: 400)"},{"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.","cause":"Your application has sent too many requests in a short period, exceeding MusicBrainz's rate limits.","error":"UnhandledPromiseRejectionWarning: MusicBrainzApiError: Too Many Requests (status: 429)"},{"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).","cause":"In TypeScript, the `Artist` type was imported using a regular `import` statement instead of `import type`, or the import path was incorrect.","error":"Cannot find name 'Artist'."}],"ecosystem":"npm"}