shazamio-core

Audio fingerprinting for Shazam, written in Rust and exposed to Python.

It turns an audio file, or its bytes, into the signature Shazam's endpoint accepts. It does not talk to Shazam itself: ShazamIO is the client that sends the signature and reads the answer back.

Install

pip install shazamio-core

Or with uv:

uv add shazamio-core

Python 3.10 and newer. Prebuilt wheels:

Everything else builds from the source distribution, which needs a Rust toolchain 1.87 or newer, CMake and a C compiler. libopus is built from vendored sources rather than linked against a system copy, so without CMake the build stops on is 'cmake' not installed?.

Usage

Both entry points return an asyncio.Future rather than a coroutine, so they need a running event loop at the call and the work starts there rather than at the await. await, asyncio.ensure_future and asyncio.gather all accept what they return; asyncio.create_task takes a coroutine alone and rejects it. Cancelling one drops its result but not its work: the decode runs to the end on a worker thread, and later calls are unaffected.

import asyncio
from pathlib import Path

from shazamio_core import Recognizer


async def main() -> None:
    recognizer = Recognizer()

    from_path = await recognizer.recognize_path("track.mp3")
    from_bytes = await recognizer.recognize_bytes(Path("track.mp3").read_bytes())

    print(from_path.signature.uri == from_bytes.signature.uri)


asyncio.run(main())

recognize_path accepts a str or an os.PathLike[str]. A __fspath__ returning bytes is rejected.

What comes back

Both return a Signature:

Every field above is read only: assigning to one raises AttributeError. Neither class can be built by hand: Signature() raises TypeError.

The URI is the part a client sends on:

data:audio/vnd.shazam.sig;base64,gCX+ypQoAnWcBQAAAJwRlAAAAAA...

How much audio is analysed

Ten seconds by default, taken from the middle of the file. A file shorter than the segment is used whole. Audio is converted to mono and downsampled to 16 kHz before analysis, whatever it started as.

Set it per recognizer, or per call:

import asyncio

from shazamio_core import Recognizer, SearchParams


async def main() -> None:
    recognizer = Recognizer(segment_duration_seconds=5)

    signature = await recognizer.recognize_path(
        "track.mp3",
        SearchParams(segment_duration_seconds=15),
    )

    print(signature.signature.samples)


asyncio.run(main())

SearchParams wins where both are given. The duration must be at least 1; zero raises ValueError. A value at or above the length of the file analyses it whole, whatever the value.

Errors

Anything the decoder cannot use raises SignatureError, and the message opens with the input that failed: the path for recognize_path, the byte payload for recognize_bytes.

A recording cut short is refused rather than fingerprinted from what is left, with three exceptions. MP4 and Matroska fail before decoding starts and report that no reader recognises the stream. MP3 and MP2 decode up to the cut and are not refused, because a run of MPEG frames does not reliably say how long it is. A chained Ogg file cut inside a later link loses that link and is not refused either, which is a bug in symphonia.

What follows the input is symphonia's wording, or the operating system's, and differs between platforms.

An argument of the wrong type raises TypeError instead, and raises it at the call rather than on the await, so nothing is scheduled.

A panic inside the extension is a bug here rather than bad input. It raises RustPanic, an Exception subclass the package does not export, on the await, with the panic message after rust future panicked: .

import asyncio

from shazamio_core import Recognizer, SignatureError


async def main() -> None:
    try:
        await Recognizer().recognize_path("not-audio.txt")
    except SignatureError as error:
        print(error)


asyncio.run(main())

Formats

Decoding goes through symphonia with every codec and container it ships enabled, and resampling to mono 16 kHz through rubato. Opus is the one codec symphonia has no decoder for, so it goes through libopus, which is compiled into the wheel rather than loaded from the system. Nothing is shelled out to, so no external binary has to be installed.

That leaves these codecs, each one probed through the public API in the container named beside it:

MP1 is the one row taken from what symphonia registers rather than from a run: nothing here encodes it. The containers recognised are ADTS, AIFF, CAF, FLAC, Matroska and WebM, MP4, MPEG, Ogg and WAV, and the test suite runs on Linux, macOS and Windows.

Anything else raises SignatureError, and a container from that list is no guarantee: what has to be decodable is the codec inside it. The two refusals differ in how far the file gets:

Windows Media Audio decoded in earlier releases through an ffmpeg fallback that has since been removed.

Development

Setting up a checkout, what to run before a pull request and how commits are shaped: CONTRIBUTING.md.

License

MIT. See LICENSE.

The wheel statically links its Rust dependencies, so the terms in THIRD-PARTY-NOTICES.md apply to it as well. That file says how it is generated; just licenses-check fails once a dependency change has left it behind.