AudD API walkthrough: get started in under 10 minutes

AudD works the moment you paste your API token — no enterprise procurement, no weeks of setup. This walkthrough takes you from zero to your first successful recognition in a few minutes, using the official SDKs.

What you’ll build

By the end you’ll have a working integration that can:

Identify songs from audio files or URLs
Return metadata — artist, title, album, and streaming links
Read responses in your preferred language
Degrade gracefully when a field is missing

Prerequisites

An API token — get one at dashboard.audd.io
A terminal or editor
An audio file or URL to test with

AudD recognizes common formats including MP3, WAV, M4A, FLAC, and OGG.

Step 1: Get your API token

Sign up at dashboard.audd.io.
Copy your API token from the dashboard.
Store it in an environment variable rather than hard-coding it.

export AUDD_API_TOKEN=your-token

Step 2: Install the SDK

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

# Python
pip install audd

# Node / TypeScript
npm i @audd/sdk

Step 3: Your first recognition

The minimal call takes just a source — a URL or a file path. The standard endpoint takes a short audio clip — it analyzes up to about 12 seconds of audio — responds quickly, and returns the single top match.

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(f"{result.title} by {result.artist}")

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.title} by ${result.artist}`);
}

<?php
use AudD\AudD;

$audd = new AudD('your-token'); // dashboard.audd.io

$result = $audd->recognize('https://audd.tech/example.mp3');
if ($result) {
    echo $result->title . ' by ' . $result->artist;
}

You can pass a local file path the same way you pass a URL. The standard endpoint caps uploads at roughly 10 MB, so send a representative clip rather than a whole album — the endpoint analyzes up to about 12 seconds of audio, and within that range more audio generally helps accuracy.

Reading the result

A match exposes structured fields: artist, title, album, release_date, label, timecode (where in the audio the match landed), and a universal song_link on lis.tn. Treat any field as possibly null and don’t throw if one is missing.

Step 4: Request streaming-service metadata

To get provider links, opt in with return_metadata. AudD can return blocks for Apple Music, Spotify, Deezer, and MusicBrainz.

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 occasionally returns fields ahead of an SDK release. You can read them directly: in Python untyped fields are on model_extra, in Node on extras.

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.

Step 5: Handle errors and parse leniently

Parse responses leniently — a missing or wrong-typed field degrades to null, not an exception. Only treat these as real 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 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, not on the human-readable message.

Recognizing long audio and video

For a full mix, a podcast episode, or a video file, use enterprise recognition. AudD chunks the media server-side, bills per 12 seconds of audio, and 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)

Recognizing live streams

For 24/7 monitoring — radio stations, live broadcasts — use stream recognition. You register a stream and a callback URL, and AudD pushes each match to your endpoint (or you pull results with longpoll). This is the right tool for continuous monitoring; for a single file, use standard or enterprise recognition instead.

Recognizing your own audio

The public catalog covers commercial releases. To recognize your own jingles, idents, or unreleased tracks, use a custom catalog (special access): upload your recordings and assign each an integer audio_id that comes back on later matches. AudD can match your own audio — you’re not limited to the public catalog.

Next steps

Add metadata — request the provider blocks your product needs.
Scale up — move long media to enterprise recognition and live audio to streams.
Cache by content hash — reuse a result instead of paying for a duplicate recognition.

Getting help

AudD is built for self-service integration, but support is available at [email protected], with full reference at docs.audd.io.

Get a token at dashboard.audd.io.

Related