@beatsphere/musicbrainz-client

MusicBrainz API client with Cover Art Archive, Wikidata, and iTunes fallback chain for music metadata enrichment. Handles rate limiting, retries with exponential backoff, and Last.fm placeholder image replacement. Battle-tested in BeatSphere.

Install

npm install @beatsphere/musicbrainz-client

Quick Start

import {
  configure,
  getArtistMbid,
  getArtistImage,
  getCoverArt,
  getAlbumCover,
  getAudioPreview,
} from '@beatsphere/musicbrainz-client';

// Optional: configure User-Agent (MusicBrainz requires one)
configure({ userAgent: 'MyApp/1.0.0 ([email protected])' });

// Find an artist
const mbid = await getArtistMbid('Radiohead');

// Get artist image (tries: MB relations → Wikidata → release cover art)
const image = await getArtistImage(mbid!);

// Get track cover art from Cover Art Archive
const cover = await getCoverArt('Radiohead', 'Creep');

// Get album cover art
const albumCover = await getAlbumCover('Radiohead', 'OK Computer');

// Get iTunes audio preview URL
const preview = await getAudioPreview('Radiohead', 'Creep');

Image Enrichment

The killer feature — replace Last.fm's placeholder images with real artwork:

import {
  enrichArtistImages,
  enrichTrackImages,
  enrichAlbumImages,
} from '@beatsphere/musicbrainz-client';

// Items with Last.fm's grey placeholder (2a96cbd8b46e...)
const artists = [{ name: 'Radiohead', image: [...] }];

// Returns items with real images from MusicBrainz/Wikidata/Cover Art Archive
const enriched = await enrichArtistImages(artists);

// Also works for tracks and albums
const enrichedTracks = await enrichTrackImages(tracks);
const enrichedAlbums = await enrichAlbumImages(albums);

Image Fallback Chain

Artist images

1. MusicBrainz direct image relation
2. Wikidata P18 (image property) via MusicBrainz Wikidata relation
3. Cover art from artist's releases (albums/EPs)

Track cover art

1. Cover Art Archive via MusicBrainz recording → release lookup

Album cover art

1. Cover Art Archive via release group
2. Cover Art Archive via individual releases (fallback)

Configuration

import { configure } from '@beatsphere/musicbrainz-client';

configure({
  userAgent: 'MyApp/1.0.0 ([email protected])', // Required by MusicBrainz
  maxRetries: 3,           // Retries on 503/429/ECONNRESET
  initialRetryDelay: 2000, // Doubles on each retry
  apiTimeout: 15000,       // MusicBrainz API timeout
  coverArtTimeout: 10000,  // Cover Art Archive timeout
  itunesTimeout: 10000,    // iTunes API timeout
  rateLimitDelay: 1500,    // Delay between enrichment requests
});

API

| Function | Description | |----------|-------------| | configure(opts) | Set User-Agent, timeouts, retry settings | | getArtistMbid(name) | Search for artist MBID by name | | getArtistImage(mbid) | Get artist image (full fallback chain) | | getArtistReleaseImage(mbid) | Get image from artist's release cover art | | getCoverArt(artist, track) | Get track cover art via Cover Art Archive | | getAlbumCover(artist, album) | Get album cover art | | getAudioPreview(artist, track?) | Get iTunes 30s audio preview URL | | enrichArtistImages(items) | Batch-enrich artist items with real images + previews | | enrichTrackImages(items) | Batch-enrich track items with real images + previews | | enrichAlbumImages(items) | Batch-enrich album items with real cover art |

All functions return null on failure instead of throwing (except network errors from axios).

License

MIT