shazamio-api

A robust, fully-typed Node.js wrapper for Shazam's reverse-engineered recognition API — identify songs from an audio file or buffer.

Fingerprinting is delegated to shazamio-core, the same WebAssembly signature engine used internally by the Python shazamio v2 library, so recognition happens entirely in-process — no external binaries, no API key, no Python.

Note: Shazam shut down its public catalog/search endpoints (search/v3, search/v4, amapi/*) server-side in 2026 — see dotX12/ShazamIO#145. Only the recognition endpoint used by this package is confirmed to still work.

Installation

npm install shazamio-api

Usage Guide

The API is fully Promise-based and returns strictly typed objects.

1. Recognizing a Song from a File

import shazam from 'shazamio-api';

async function identify() {
  const result = await shazam.recognize('./sample.mp3');

  console.log(result.track?.title); // Never Gonna Give You Up
  console.log(result.track?.subtitle); // Rick Astley
}

JSON Output Structure Example:

{
  "matches": [
    { "id": "507112683", "offset": 0.137, "timeskew": -0.0001, "frequencyskew": 0.0002 }
  ],
  "track": {
    "title": "Never Gonna Give You Up",
    "subtitle": "Rick Astley",
    "images": { "coverart": "https://is1-ssl.mzstatic.com/..." },
    "hub": { "actions": [{ "type": "uri", "uri": "https://music.apple.com/..." }] }
  }
}

2. Recognizing from Raw Bytes

Accepts a Buffer/Uint8Array directly — useful when audio is already in memory (an upload, a stream chunk, a recording buffer). Any container/codec shazamio-core can decode works: mp3, flac, wav, ogg, m4a, and more.

import shazam from 'shazamio-api';
import { readFileSync } from 'fs';

const bytes = readFileSync('./sample.flac');
const result = await shazam.recognize(bytes);

3. Sampling a Specific Window

Pass offset/seconds to fingerprint a slice of a longer recording instead of its start — handy for a full-length track or a long live recording.

import shazam from 'shazamio-api';

const result = await shazam.recognize('./full-concert.mp3', { offset: 120, seconds: 12 });

4. Custom Locale and Region

Pass options to the Shazam constructor to localize the recognition response (e.g. track titles/links for a specific storefront).

import { Shazam } from 'shazamio-api';

const shazam = new Shazam({
  language: 'tr-TR',
  endpointCountry: 'TR',
});

const result = await shazam.recognize('./sample.mp3');

5. Typed Errors

import shazam, { NoMatchesFoundError, ShazamNetworkError } from 'shazamio-api';

try {
  await shazam.recognize('./silence.wav');
} catch (err) {
  if (err instanceof NoMatchesFoundError) {
    // no song matched this sample
  } else if (err instanceof ShazamNetworkError) {
    // Shazam was unreachable, or returned a non-2xx / unparsable response
    console.log(err.status);
  }
  throw err;
}

6. Cancelling In-Flight Requests

import shazam from 'shazamio-api';

const controller = new AbortController();
setTimeout(() => controller.abort(), 5000);

await shazam.recognize('./sample.mp3', { signal: controller.signal });

API Reference

• new Shazam(options?: ShazamOptions) Creates a wrapper instance. options.language (default en-US), options.endpointCountry (default GB) and options.timezone (default Europe/Moscow) apply to every recognition request made through it.

• shazam.recognize(data: string | Buffer | Uint8Array, options?: RecognizeOptions): Promise<RecognizeResult> Generates a Shazam signature from an audio file (by path) or raw bytes and looks it up against Shazam's catalog. options.offset/options.seconds sample a specific window of the audio; options.signal aborts the request. Throws NoMatchesFoundError when nothing matches.

License

MIT