audio-thumbnail.js (ESM-only)

Generate album art URLs for audio files in the browser.

Features

• Browser-only, ESM-only API
• Sidecar discovery (for example folder.jpg, cover.jpg, song.jpg)
• Embedded extraction:
  • MP3 (APIC / PIC)
  • M4A/MP4 (covr)
  • MKA/MKV attachments and common cover-art patterns
• Sidecar output returns direct URL candidates (no re-encode)
• Embedded output returns blob: object URLs (default) or data: URIs
• Optional embedded resize/transcode (output.size, output.mime)
• Source strategies: race (default), prefer-sidecar, all
• Sidecar session cache (sessionStorage) to avoid repeat validation

Usage

import audioThumbnail, { cleanupObjectURLs } from 'audio-thumbnail.js';

const results = await audioThumbnail('/audio/sidecar.mp3');
console.log(results.best?.URI, results.best?.source);

// Call when you no longer need blob: URLs created by this library
cleanupObjectURLs();

Common Options

const results = await audioThumbnail('/audio/track.mka', {
  sources: ['sidecar', 'embedded'],
  sourceStrategy: 'race',

  sidecarExts: ['jpg', 'jpeg', 'png', 'webp'],
  sidecarValidate: 'auto', // 'none' | 'head' | 'get-range' | 'img' | 'auto'
  sidecarConcurrency: 6,
  sidecarMaxResults: 1,
  sidecarIncludeBasename: true,

  embedded: {
    maxBytes: 1_000_000,
    preferPicture: 'front' // 'front' | 'any'
  },

  output: {
    type: 'objectURL', // or 'dataURI'
    mime: { type: 'image/webp', quality: 0.9 },
    size: 512
  }
});

Defaults

• sources: ['sidecar', 'embedded']
• sourceStrategy: 'race'
• sidecarNames: ['folder','cover','albumart','front','album','default','thumb','artwork','thumbnail']
• sidecarExts: ['jpg', 'jpeg']
• sidecarIncludeBasename: true
• sidecarValidate: 'auto'
• sidecarConcurrency: 6
• sidecarMaxResults: 1
• sidecarCache: true
• sidecarCacheKeyPrefix: 'audio-thumbnail.js'
• embedded.maxBytes: 1_000_000
• embedded.preferPicture: 'front'
• output.type: 'objectURL'
• timeoutMs: 15000

API

Default export:

• audioThumbnail(url: string, options?: Options): Promise<ArtworkResults>

Named exports:

• cleanupObjectURLs(): number
• clearCanvasPool(): boolean
• getMemoryUsage(): { canvasPoolEntries, activeObjectURLs }

ArtworkResults is an array of result objects with non-enumerable helpers:

• results.best: best candidate or null
• results.timing: { totalMs, fetchMsTotal, decodeMsTotal, encodeMsTotal }

Each result item includes:

• URI
• source ('sidecar' | 'embedded')
• kind ('front' | 'other')
• optional metadata like container, inputMime, outputMime, width, height

Local Testing

This repo includes sample media under audio/ and a demo harness at src/demo.html.

python -m http.server 8000

Open http://localhost:8000/src/demo.html.