sonovault

TypeScript/Node client for the SonoVault music metadata API. 90M+ tracks with ISRC, ISWC, genre, record label, canonical release dates, and cross-platform IDs for Spotify, Apple Music, Tidal, Beatport, Discogs, and MusicBrainz. One call resolves them all.

• One key, no OAuth. A single x-api-key header, no approval queue.
• Free tier. 1,000 requests/month, no credit card: get an API key.
• Docs. Full API reference at sonovault.now/docs.

Install

npm install sonovault

Node 18+ (uses the built-in fetch). ESM and CommonJS both supported.

Use this library server-side. Shipping your API key in browser code exposes it to anyone who opens devtools. If a key leaks, rotate it in your dashboard.

Quickstart

import { SonoVault } from "sonovault";

const sv = new SonoVault({ apiKey: process.env.SONOVAULT_API_KEY! });

// Find a track's ISRC from artist + title
const { results } = await sv.tracks.search({ artist: "Daft Punk", title: "One More Time" });
console.log(results[0].isrc); // "GBDUW0000053"
console.log(results[0].genre, results[0].releases[0]?.label?.name);

// Resolve that ISRC to its ID on every platform
const { links } = await sv.tracks.links({ isrc: "GBDUW0000053" });
for (const link of links) {
  console.log(link.source, link.url); // spotify https://open.spotify.com/track/...
}

// Recording to composition (ISWC), for royalty and publishing workflows
const work = await sv.tracks.iswc({ isrc: "GBDUW0000053" });

Bulk resolve

Resolve up to 100 lines in one request: track names, ISRCs, or platform IDs. Useful for enriching play logs and library exports.

const batch = await sv.tracks.resolve({
  input_type: "track_name",
  items: [
    { artist: "Daft Punk", title: "Harder, Better, Faster, Stronger" },
    { artist: "Daft Punk", title: "Around the World" },
  ],
});

for (const row of batch.results) {
  console.log(row.status, row.track?.isrc, row.track?.releases[0]?.label?.name);
}

Pagination

List endpoints return { results, next_cursor }. Pass the cursor back to get the next page. next_cursor is null on the last page.

import { paginate } from "sonovault";

for await (const release of paginate((cursor) => sv.artists.releases(42, { cursor }))) {
  console.log(release.title);
}

Or walk the cursor yourself:

let cursor: string | undefined;
do {
  const page = await sv.artists.releases(42, { cursor });
  // ...use page.results
  cursor = page.next_cursor ?? undefined;
} while (cursor);

Error handling

Non-2xx responses throw a typed SonoVaultError:

import { SonoVaultError } from "sonovault";

try {
  await sv.tracks.browse({ genre: "House" }); // paid-tier endpoint
} catch (err) {
  if (err instanceof SonoVaultError) {
    console.log(err.status, err.isForbidden, err.message);
  }
}

Rate-limited responses that carry a Retry-After header are retried automatically. The default is 2 retries, configurable with maxRetries.

Examples

Runnable scripts live in examples/: find an ISRC, resolve cross-platform links, enrich a play log, follow live stream events over SSE, and verify webhook deliveries.

API coverage

| Namespace | Methods | |---|---| | sv.tracks | search, get, byIsrc, iswc, byIswc, links, resolve, identify, identifyAudio, browse | | sv.artists | search, get, releases | | sv.labels | search, get, releases, artists | | sv.releases | search, get, latest | | sv.genres | list | | sv.suggestions | submit, list | | sv.streams | create, list, get, update, history, report, live, stop | | sv.webhooks | create, list, get, update, delete, test, deliveries |

Some endpoints (audio identify, browse, stream monitoring) need a paid tier. See pricing. Everything else works on the free tier.

Related

• SonoVault API docs. Full endpoint reference with examples in 8 languages.
• sonovault-python. The Python client.
• Free ISRC lookup and ISWC lookup. Browser tools built on the same API.

License

MIT