Music recognition API integration: a developer guide

Music recognition has become a building block for content analysis, “now playing” features, copyright scanning, and royalty reporting. This guide walks through integrating a music recognition API into your application, from first request to production deployment, using AudD and its official SDKs.

Understanding music recognition APIs

A music recognition API identifies a recording from an audio sample. AudD uses neural-network audio fingerprinting: it analyzes the acoustic content of your audio and matches it against a public database of about 160 million songs, returning structured metadata like artist, title, album, and links to streaming services.

AudD accepts audio in several ways:

Audio files (MP3, WAV, M4A, FLAC, OGG, and more)
A URL pointing to a hosted audio or video file
Live audio streams for continuous recognition

The core workflow is the same in every case: send audio, get back a structured match. AudD also supports a custom catalog — you can upload your own tracks (with special access) and assign each an integer audio_id that comes back on later recognitions, so the API can match your own or unreleased audio, not only the public catalog.

Choosing how to recognize: standard, enterprise, or streams

AudD exposes three surfaces. Pick by the shape of your audio, not by plan tier.

Standard (api.audd.io/) takes a short audio clip, responds in under two seconds, caps files at roughly 10 MB, and returns the single top match. This is what most apps need.
Enterprise (enterprise.audd.io/) takes long audio and video. AudD chunks it server-side, bills per 12 seconds of audio, and returns every match with timestamps. Use it for full DJ sets, podcasts, or video files.
Streams (addStream) recognize live audio 24/7 — radio stations, live broadcasts — and deliver results through webhook callbacks or longpoll.

When you select a provider, the factors that actually matter are runtime fit and the capability you need (single match vs. every match with timestamps vs. continuous monitoring), plus the metadata depth your product requires.

Setting up your development environment

Get an API token from dashboard.audd.io, then install the SDK for your language. Store the token in an environment variable rather than hard-coding it.

export AUDD_API_TOKEN=your-token

# Python
pip install audd

# Node / TypeScript
npm i @audd/sdk

AudD ships eleven official SDKs: Python, Node/TypeScript, Go, Rust, PHP, Swift, Kotlin, .NET, Java, C, and C++.

Basic integration steps

Authenticate. Pass your API token when you construct the client.
Provide audio. A file path, a URL, or raw bytes.
Request metadata if you need it. Ask for provider links with return_metadata.
Read the response. Pull the fields you care about; treat any field as possibly null.
Handle errors. Distinguish caller-input errors from transport errors and retry only what’s retryable.

Recognizing a file

The minimal call takes just a source.

from audd import AudD

audd = AudD(api_token="your-token")  # get a token at dashboard.audd.io

result = audd.recognize("https://audd.tech/example.mp3")
if result:
    print(result.artist, "-", result.title)

import { AudD } from "@audd/sdk";

const audd = new AudD({ apiToken: "your-token" }); // dashboard.audd.io

const result = await audd.recognize("https://audd.tech/example.mp3");
if (result) {
  console.log(`${result.artist} - ${result.title}`);
}

To get streaming-service links and other metadata, opt in. AudD can return blocks for Apple Music, Spotify, Deezer, and MusicBrainz, plus a universal song_link on lis.tn.

result = audd.recognize(
    "https://audd.tech/example.mp3",
    return_metadata=["apple_music", "spotify"],
)
if result:
    print(result.title, result.song_link)

const result = await audd.recognize("https://audd.tech/example.mp3", {
  returnMetadata: ["apple_music", "spotify"],
});

With raw HTTP you’d pass return=apple_music,spotify; in the SDKs use return_metadata. Note that isrc, upc, and the match score require a Startup plan or higher.

Reading undocumented or beta fields

AudD sometimes returns fields ahead of an SDK release. You can read them directly. In Python, untyped fields are available via model_extra; in Node they’re on extras.

# A field not yet modeled by the SDK
value = result.model_extra.get("some_new_field")

const value = result.extras?.some_new_field;

This is the supported way to read metadata the typed model doesn’t cover yet.

Recognizing long audio and video

For a full mix, a podcast episode, or a video file, use the enterprise endpoint. It returns every match with timestamps. During development, always set a small limit.

matches = audd.recognize_enterprise(
    "https://audd.tech/example.mp3",
    limit=1,
)
for m in matches:
    print(m.title, m.timecode)

Real-time stream recognition

Stream recognition continuously monitors a live audio feed — a radio station or a live broadcast — and reports each song it hears. You register a stream and receive results over a webhook callback, or poll with longpoll. Streams are the right tool for 24/7 monitoring; for a one-off file you’d use standard or enterprise recognition instead.

Error handling and retries

Parse responses leniently: a missing or wrong-typed field should degrade to null, not throw. Only treat these as errors: a status: error response, undecodable JSON, a transport failure, or a caller-input mistake (bad token, unreadable file). Retry transport and server errors with exponential backoff; don’t retry a rejected input.

import time

def recognize_with_retry(source, max_retries=3):
    for attempt in range(max_retries):
        try:
            return audd.recognize(source)
        except ConnectionError:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

AudD returns specific error codes for conditions like an invalid token, a file that’s too large, or a rate limit. Branch on the code rather than matching on the human-readable message.

Performance

A few habits keep latency and cost down:

Send a short clip to the standard endpoint. You don’t need the whole file; the standard endpoint analyzes up to about 12 seconds of audio, so a short representative segment recognizes just as well and uploads faster.
Cache by content hash. If you process the same file twice, reuse the first result instead of paying for a second recognition.
Reuse the client. Construct the SDK client once and share it; don’t build a new one per request.

Testing and debugging

Mock the SDK client in unit tests so they don’t hit the network, and assert on the parsed fields you depend on. Add logging around each recognition — the source, whether a match came back, and the resulting artist/title — so production issues are diagnosable. Because fields can be null, write a regression test that feeds a response missing score and confirms your code degrades gracefully instead of throwing.

Production deployment

Keep tokens in secrets management, never in source control, and rotate them periodically.
Use HTTPS for every call (the SDKs do by default).
Monitor response times, success and failure rates, and request volume.
Plan for rate limits. Queue work during spikes rather than hammering the API.

Common challenges

File size. The standard endpoint caps uploads near 10 MB. For larger media, send a clip or move to the enterprise endpoint.

Audio quality. Heavy compression, low volume behind speech, or very short samples reduce match confidence. A few seconds of clear audio is usually enough.

Your own audio. If you need to match unreleased tracks or proprietary content, use the custom catalog: upload your tracks, get an audio_id back on matches. AudD can match your own audio — you don’t have to settle for the public catalog only.

FAQ

What audio formats does AudD support? Common formats including MP3, WAV, M4A, FLAC, and OGG, plus URLs to hosted audio or video, and live streams.

What’s the typical response time? The standard endpoint responds in under two seconds for a short clip. Enterprise recognition takes longer because it scans the whole file and returns every match.

Can I recognize my own or unreleased music? Yes. Upload your tracks to a custom catalog (special access) and AudD returns the audio_id you assigned when it matches them later.

What metadata comes back? Artist, title, album, release date, label, and a universal song_link, plus optional provider blocks (Apple Music, Spotify, Deezer, MusicBrainz). isrc, upc, and score require a Startup plan or higher.

How do I handle rate limits in production? Retry with exponential backoff on transport and server errors, queue work during spikes, and cache results by content hash to avoid duplicate recognitions.

Conclusion

Integrating music recognition comes down to a short loop: send audio, read structured metadata, parse leniently, and pick the surface — standard, enterprise, or streams — that fits your audio. Start with a single file against the standard endpoint, then expand to long media or live streams as your product grows.

Get a token at dashboard.audd.io and read the full reference at docs.audd.io.

Related