{"_id":"@beatsphere/musicbrainz-client","name":"@beatsphere/musicbrainz-client","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@beatsphere/musicbrainz-client","version":"0.1.0","description":"MusicBrainz API client with Cover Art Archive, Wikidata, and iTunes fallback chain for music metadata enrichment","main":"build/index.js","types":"build/index.d.ts","scripts":{"build":"tsc","prepublishOnly":"tsc","clean":"rm -rf build"},"keywords":["musicbrainz","cover-art","cover-art-archive","wikidata","itunes","music-metadata","album-art","artist-image","zod","typescript"],"author":{"name":"BeatSphere","email":"hello@beatsphere.live"},"license":"MIT","homepage":"https://github.com/Beatsphere/musicbrainz-client#readme","repository":{"type":"git","url":"git+https://github.com/Beatsphere/musicbrainz-client.git"},"bugs":{"url":"https://github.com/Beatsphere/musicbrainz-client/issues"},"dependencies":{"axios":"^1.6.0","zod":"^3.22.0"},"devDependencies":{"typescript":"^5.0.0"},"gitHead":"101b630a8def696d35e0a67e42c746c0e5f11b58","_id":"@beatsphere/musicbrainz-client@0.1.0","_nodeVersion":"24.12.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-vkTRMVohQkT0VQYdtgDfAivP6QTMIeVn3qLLF7uoMeO/dJk783VUKGW1FEtz5QW6km+hB9odc5AvJnnIE1iPXg==","shasum":"c1fe296f695ab01556432df32751200b7ff0003a","tarball":"https://registry.npmjs.org/@beatsphere/musicbrainz-client/-/musicbrainz-client-0.1.0.tgz","fileCount":13,"unpackedSize":71942,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDTZKVS3qYafKW17688N1ifPmCl/2NAuRdbO/haq/UZ4AiEArPUgkbzc4QeO/hu4E0NKwpmn/zDOj66MAQlXV45RvXs="}]},"_npmUser":{"name":"ayushh2k","email":"rustichouse042@gmail.com"},"directories":{},"maintainers":[{"name":"ayushh2k","email":"rustichouse042@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/musicbrainz-client_0.1.0_1776972126898_0.1974386670603292"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-23T19:22:06.777Z","0.1.0":"2026-04-23T19:22:07.065Z","modified":"2026-04-23T19:22:07.309Z"},"maintainers":[{"name":"ayushh2k","email":"rustichouse042@gmail.com"}],"description":"MusicBrainz API client with Cover Art Archive, Wikidata, and iTunes fallback chain for music metadata enrichment","homepage":"https://github.com/Beatsphere/musicbrainz-client#readme","keywords":["musicbrainz","cover-art","cover-art-archive","wikidata","itunes","music-metadata","album-art","artist-image","zod","typescript"],"repository":{"type":"git","url":"git+https://github.com/Beatsphere/musicbrainz-client.git"},"author":{"name":"BeatSphere","email":"hello@beatsphere.live"},"bugs":{"url":"https://github.com/Beatsphere/musicbrainz-client/issues"},"license":"MIT","readme":"# @beatsphere/musicbrainz-client\n\nMusicBrainz 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](https://beatsphere.live).\n\n## Install\n\n```bash\nnpm install @beatsphere/musicbrainz-client\n```\n\n## Quick Start\n\n```typescript\nimport {\n  configure,\n  getArtistMbid,\n  getArtistImage,\n  getCoverArt,\n  getAlbumCover,\n  getAudioPreview,\n} from '@beatsphere/musicbrainz-client';\n\n// Optional: configure User-Agent (MusicBrainz requires one)\nconfigure({ userAgent: 'MyApp/1.0.0 (contact@myapp.com)' });\n\n// Find an artist\nconst mbid = await getArtistMbid('Radiohead');\n\n// Get artist image (tries: MB relations → Wikidata → release cover art)\nconst image = await getArtistImage(mbid!);\n\n// Get track cover art from Cover Art Archive\nconst cover = await getCoverArt('Radiohead', 'Creep');\n\n// Get album cover art\nconst albumCover = await getAlbumCover('Radiohead', 'OK Computer');\n\n// Get iTunes audio preview URL\nconst preview = await getAudioPreview('Radiohead', 'Creep');\n```\n\n## Image Enrichment\n\nThe killer feature — replace Last.fm's placeholder images with real artwork:\n\n```typescript\nimport {\n  enrichArtistImages,\n  enrichTrackImages,\n  enrichAlbumImages,\n} from '@beatsphere/musicbrainz-client';\n\n// Items with Last.fm's grey placeholder (2a96cbd8b46e...)\nconst artists = [{ name: 'Radiohead', image: [...] }];\n\n// Returns items with real images from MusicBrainz/Wikidata/Cover Art Archive\nconst enriched = await enrichArtistImages(artists);\n\n// Also works for tracks and albums\nconst enrichedTracks = await enrichTrackImages(tracks);\nconst enrichedAlbums = await enrichAlbumImages(albums);\n```\n\n## Image Fallback Chain\n\n### Artist images\n1. MusicBrainz direct image relation\n2. Wikidata P18 (image property) via MusicBrainz Wikidata relation\n3. Cover art from artist's releases (albums/EPs)\n\n### Track cover art\n1. Cover Art Archive via MusicBrainz recording → release lookup\n\n### Album cover art\n1. Cover Art Archive via release group\n2. Cover Art Archive via individual releases (fallback)\n\n## Configuration\n\n```typescript\nimport { configure } from '@beatsphere/musicbrainz-client';\n\nconfigure({\n  userAgent: 'MyApp/1.0.0 (me@example.com)', // Required by MusicBrainz\n  maxRetries: 3,           // Retries on 503/429/ECONNRESET\n  initialRetryDelay: 2000, // Doubles on each retry\n  apiTimeout: 15000,       // MusicBrainz API timeout\n  coverArtTimeout: 10000,  // Cover Art Archive timeout\n  itunesTimeout: 10000,    // iTunes API timeout\n  rateLimitDelay: 1500,    // Delay between enrichment requests\n});\n```\n\n## API\n\n| Function | Description |\n|----------|-------------|\n| `configure(opts)` | Set User-Agent, timeouts, retry settings |\n| `getArtistMbid(name)` | Search for artist MBID by name |\n| `getArtistImage(mbid)` | Get artist image (full fallback chain) |\n| `getArtistReleaseImage(mbid)` | Get image from artist's release cover art |\n| `getCoverArt(artist, track)` | Get track cover art via Cover Art Archive |\n| `getAlbumCover(artist, album)` | Get album cover art |\n| `getAudioPreview(artist, track?)` | Get iTunes 30s audio preview URL |\n| `enrichArtistImages(items)` | Batch-enrich artist items with real images + previews |\n| `enrichTrackImages(items)` | Batch-enrich track items with real images + previews |\n| `enrichAlbumImages(items)` | Batch-enrich album items with real cover art |\n\nAll functions return `null` on failure instead of throwing (except network errors from axios).\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-8730016342f836e6c52f64d31572bc49"}