---
title: "Music recognition API integration: a developer guide"
description: "A practical guide to integrating a music recognition API with the AudD SDKs, covering setup, file and stream recognition, metadata, error handling, and production deployment."
slug: "/resources/articles/music-recognition-api-integration-guide"
section: "articles"
keywords: [audd, music recognition api, audio fingerprinting, song identification, sdk integration, stream recognition]
---

# 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](https://dashboard.audd.io), then install the SDK for your language. Store the token in an environment variable rather than hard-coding it.

```bash
export AUDD_API_TOKEN=your-token
```

```bash
# 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

1. **Authenticate.** Pass your API token when you construct the client.
2. **Provide audio.** A file path, a URL, or raw bytes.
3. **Request metadata if you need it.** Ask for provider links with `return_metadata`.
4. **Read the response.** Pull the fields you care about; treat any field as possibly null.
5. **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.

```python
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)
```

```javascript
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.

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

```javascript
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`.

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

```javascript
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`.

```python
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.

```python
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](https://dashboard.audd.io) and read the full reference at [docs.audd.io](https://docs.audd.io).

**Related**
- [Build a Shazam-style music identification app](/resources/recipes/shazam-clone)
- [Standard vs. enterprise vs. streams](/resources/concepts/standard-vs-enterprise-vs-streams)
- [AudD documentation](https://docs.audd.io)