xazam
A modular, async Python client for the Shazam API, built on top of shazamio_core for robust audio fingerprinting.
Features
- Track identification — send audio bytes and get back track metadata.
- Artist metadata scraping — resolve artist pages and query the Apple Music catalog proxy.
- Modular transport —
ShazamTransporthandles headers and sessions;ShazamClientandShazamScraperbuild on top of it.
Install
pip install -e .
# or with dev dependencies
pip install -e ".[dev]"
Quick start
Identify a track (typed API — recommended)
import asyncio
from xazam import ShazamClient, ShazamTransport
async def main():
with open("song.mp3", "rb") as f:
audio = f.read()
async with ShazamTransport() as transport:
client = ShazamClient(transport)
result = await client.identify(audio)
if result.matched:
track = result.track
print(f"{track.title} — {track.subtitle}")
print(f"Cover art: {track.cover_art}")
print(f"Apple Music: {track.apple_music_url}")
print(f"Spotify: {track.spotify_uri}")
print(f"Lyrics: {track.lyrics[:200]}...")
else:
print("No match")
asyncio.run(main())
Fetch extra track metadata
After identification, query the track detail endpoint for lyrics, related videos, and extended metadata:
extra = await client.get_track_info(track.key)
print(extra.metadata_table) # {'Album': '…', 'Released': '…', 'Label': '…'}
print(extra.related_videos) # ['https://youtube.com/watch?v=…', ...]
Identify a track (legacy raw-dict API)
identify_track() still returns the raw Shazam JSON for backwards
compatibility:
result = await client.identify_track(audio)
print(result["track"]["title"], "—", result["track"]["subtitle"])
Scrape artist metadata
import asyncio
from xazam import ShazamScraper, ShazamTransport
async def main():
async with ShazamTransport() as transport:
scraper = ShazamScraper(transport)
data = await scraper.get_artist_metadata("3996865")
artist = data["results"]["artists"]["data"][0]
print(artist["attributes"]["name"])
asyncio.run(main())
CLI
# Identify a file
python -m xazam_cli identify --file song.mp3
# Scrape artist metadata
python -m xazam_cli scrape --artist-id 3996865
Tests
Live integration tests hit the real Shazam API. Set a custom audio file via the environment:
export SHAZAMPY_TEST_AUDIO="/path/to/track.mp3"
pytest tests/test_integration.py -v
Architecture
| Module | Purpose |
|---|---|
client.py |
ShazamClient — high-level track identification |
scraper.py |
ShazamScraper — artist name resolution + catalog search |
transport.py |
ShazamTransport — aiohttp sessions, headers, request helpers |
models.py |
Track, Artist dataclasses |
Status
- ✅ Artist metadata scraping (405 resolved via dedicated web-page session)
- ✅ Track identification (matches returned correctly via
shazamio_corefingerprinting)
License
MIT
Metadata
Release files for xazam 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| xazam-0.1.2.tar.gz | 9.9 kB | Without provenance | Details for xazam-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| xazam-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for xazam-0.1.2-py3-none-any.whl |
Total release size: 19.0 kB
Release files / xazam-0.1.2.tar.gz
| Download URL | xazam-0.1.2.tar.gz |
|---|---|
| Size | 9.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
819a09524339041c99b35689df36b0fa669b68dd8e1c0759f3498953e50e6b84
|
|
BLAKE2b-256 checksum How to use checksums |
35a121cc33f723b4e2e07b76177512aa5640667ef4c5c6f7ff2ff1db89000441
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Release files / xazam-0.1.2-py3-none-any.whl
| Download URL | xazam-0.1.2-py3-none-any.whl |
|---|---|
| Size | 9.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a1d19a732edcf38fbc43356927e64a983d02214cc6bf87f9302fe647c237348d
|
|
BLAKE2b-256 checksum How to use checksums |
a59b1222e6ca80dcc2ed54b9c384dbc9ce57be86f8213a917fa521d7541b697e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Security for xazam 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.