sonovault

Python client for the SonoVault music metadata API. 93M+ 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

pip install sonovault

Python 3.9+.

Quickstart

from sonovault import SonoVault

sv = SonoVault(api_key="YOUR_API_KEY")

# Find a track's ISRC from artist + title
page = sv.tracks.search(artist="Daft Punk", title="One More Time")
track = page["results"][0]
print(track["isrc"])   # "GBDUW0000053"
print(track["genre"], track["releases"][0]["label"]["name"])

# An album's tracklist, in playing order
release = sv.releases.get(7)
for t in release["tracks"]:
    print(t["disc_number"], t["track_number"], t["title"])  # 1 1 One More Time

# One record groups every edition of an album, so pick the one you mean
for e in release["editions"]:
    print(e["id"], e["format"], e["release_date"], e["track_count"])  # 16216 cd 2001-03-12 14
deluxe = sv.releases.get(7, edition=16216)

# Resolve that ISRC to its ID on every platform
links = sv.tracks.links(isrc=track["isrc"])
for link in links["links"]:
    print(link["source"], link["url"])  # spotify https://open.spotify.com/track/...

# Recording to composition (ISWC), for royalty and publishing workflows
work = sv.tracks.iswc(isrc=track["isrc"])

Bulk resolve

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

batch = sv.tracks.resolve(
    input_type="track_name",
    items=[
        {"artist": "Daft Punk", "title": "Harder, Better, Faster, Stronger"},
        {"artist": "Daft Punk", "title": "Around the World"},
    ],
)
for row in batch["results"]:
    print(row["status"], row["track"] and row["track"]["isrc"])

Pagination

List endpoints return {"results": [...], "next_cursor": ...}. Pass the cursor back for the next page. next_cursor is None on the last page.

from sonovault import paginate

for release in paginate(lambda cursor: sv.artists.releases(42, cursor=cursor)):
    print(release["title"])

Or walk the cursor yourself:

cursor = None
while True:
    page = sv.artists.releases(42, cursor=cursor)
    # ...use page["results"]
    cursor = page.get("next_cursor")
    if not cursor:
        break

Error handling

Non-2xx responses raise SonoVaultError:

from sonovault import SonoVaultError

try:
    sv.tracks.browse(genre="House")  # paid-tier endpoint
except SonoVaultError as err:
    print(err.status, err.is_forbidden, err)

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

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

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-js. The TypeScript/Node client.
• Free ISRC lookup and ISWC lookup. Browser tools built on the same API.

License

MIT