coverartarchive-api

TypeScript bindings for the Cover Art Archive API.

Based on the Java implementation: lastfm/coverartarchive-api

Installation

npm install coverartarchive-api
# or
pnpm add coverartarchive-api
# or
yarn add coverartarchive-api

Requirements

• Node.js >= 18.0.0 (uses native fetch)

Usage

Basic Usage

import { CoverArtArchiveClient } from 'coverartarchive-api'

const client = new CoverArtArchiveClient()

// Get all cover art for a release
const mbid = '76df3287-6cda-33eb-8e9a-044b5e15ffdd' // Portishead - Dummy
const coverArt = await client.getByMbid(mbid)

if (coverArt) {
  console.log(`Found ${coverArt.images.length} images`)

  for (const image of coverArt.images) {
    console.log(`Image ID: ${image.id}`)
    console.log(`Types: ${image.types.join(', ')}`)
    console.log(`URL: ${image.image}`)
    console.log(`Thumbnail (500px): ${image.thumbnails.large}`)
  }
}

Get Release Group Cover Art

// Get cover art for a release group (album)
const coverArt = await client.getReleaseGroupByMbid(mbid)

Get Front/Back Image

// Get front image directly
const frontImage = await client.getFrontImage(mbid)
if (frontImage) {
  console.log(`Front image URL: ${frontImage.image}`)
}

// Get back image
const backImage = await client.getBackImage(mbid)

URL Generation (No API Call)

// Get direct URLs without making API calls
const frontUrl = client.getFrontImageUrl(mbid)
const frontUrl500 = client.getFrontImageUrl(mbid, 500) // 500px thumbnail
const backUrl = client.getBackImageUrl(mbid)

// For release groups
const releaseGroupFrontUrl = client.getReleaseGroupFrontImageUrl(mbid)

// Specific image by ID
const imageUrl = client.getImageUrl(mbid, '829521842', 1200) // 1200px thumbnail

Download Image Data

// Download image as ArrayBuffer
const imageData = await client.fetchImage(frontUrl)

Configuration Options

const client = new CoverArtArchiveClient({
  useHttps: true,                     // Use HTTPS (default: true)
  baseUrl: 'coverartarchive.org',     // Custom base URL
  userAgent: 'MyApp/1.0.0'            // Custom User-Agent header
})

Error Handling

import {
  CoverArtArchiveClient,
  InvalidMbidError,
  RateLimitError,
  CoverArtError
} from 'coverartarchive-api'

try {
  const coverArt = await client.getByMbid('invalid-mbid')
} catch (error) {
  if (error instanceof InvalidMbidError) {
    console.error('Invalid MBID format')
  } else if (error instanceof RateLimitError) {
    console.error('Rate limited, please wait')
  } else if (error instanceof CoverArtError) {
    console.error(`API error: ${error.statusCode} - ${error.message}`)
  }
}

API Reference

CoverArtArchiveClient

| Method | Description | |--------|-------------| | getByMbid(mbid) | Get all cover art for a release | | getReleaseGroupByMbid(mbid) | Get all cover art for a release group | | getFrontImage(mbid) | Get the front image of a release | | getBackImage(mbid) | Get the back image of a release | | getImageById(mbid, imageId) | Get a specific image by ID | | getFrontImageUrl(mbid, size?) | Get URL for front image | | getBackImageUrl(mbid, size?) | Get URL for back image | | getImageUrl(mbid, imageId, size?) | Get URL for specific image | | getReleaseGroupFrontImageUrl(mbid, size?) | Get URL for release group front | | fetchImage(url) | Download image as ArrayBuffer |

Types

type CoverArtType = 
  | 'Front' | 'Back' | 'Booklet' | 'Medium'
  | 'Tray' | 'Obi' | 'Spine' | 'Track'
  | 'Liner' | 'Sticker' | 'Poster' | 'Watermark'
  | 'Raw/Unedited' | 'Matrix/Runout' | 'Top' | 'Bottom' | 'Other'

type ThumbnailSize = 250 | 500 | 1200

interface CoverArtImage {
  id: string
  types: CoverArtType[]
  front: boolean
  back: boolean
  comment: string
  approved: boolean
  edit: number
  image: string
  thumbnails: CoverArtThumbnails
}

interface CoverArt {
  images: CoverArtImage[]
  release: string
}

License

MIT License - see LICENSE for details.