---
name: audd
description: AudD is a music recognition HTTP API. Send audio (a URL, a file, or raw bytes) and get back the artist, title, album, release date, label, and optional provider metadata (Apple Music, Spotify, Deezer, MusicBrainz) for the matched song.
homepage: https://audd.io
docs: https://docs.audd.io
---

AudD music recognition API — agent guide
========================================

This is a self-contained guide written for AI agents. If you're an agent
picking up a "identify this song / monitor this stream / find the lyrics"
task, read this once and you should be able to act without crawling the
full docs.

What this is
------------

AudD turns audio into song metadata. You send a clip (URL, file, or bytes)
or subscribe a long-running stream; AudD returns the artist, title, album,
release date, label, a universal `song_link` to [lis.tn](https://lis.tn),
and — optionally — typed metadata blocks from streaming providers.

The HTTP API is small (six endpoint groups). There are 11 official SDKs
that wrap it. Pick an SDK if your task language has one; fall back to plain
HTTP otherwise.

The first call (no setup, copy-pasteable)
-----------------------------------------

The public token `test` works on the standard endpoint for hello-worlds
(capped at 10 requests/day). Replace with your own token from
[dashboard.audd.io](https://dashboard.audd.io) for real use.

```
curl -s https://api.audd.io/ \
  -F api_token=test \
  -F url=https://audd.tech/example.mp3 \
  -F return=apple_music,spotify
```

You'll get JSON like:

```json
{
  "status": "success",
  "result": {
    "artist": "Imagine Dragons",
    "title": "Warriors",
    "album": "Warriors",
    "release_date": "2014-09-18",
    "label": "KIDinaKORNER/Interscope Records",
    "timecode": "00:31",
    "song_link": "https://lis.tn/Warriors",
    "apple_music": { "url": "...", "previews": [...], "..." },
    "spotify": { "uri": "spotify:track:...", "external_urls": {...}, "..." }
  }
}
```

The single most important fact about this shape: **`result` is `null` when
the clip processed successfully but no song matched.** `status=="success"`
does **not** mean a song was found; check `result !== null` separately.

Result schema (standard recognize)
----------------------------------

Always present on a match:

- `artist`, `title` — strings. Can be `null` on a **custom-catalog match**
  (use `audio_id` instead).
- `album`, `release_date`, `label` — strings. `release_date` is `YYYY-MM-DD`.
- `timecode` — `HH:MM` or `MM:SS`. **Position within the matched song where
  the user's clip occurred**, not the user's-clip offset.
- `song_link` — universal URL on `lis.tn`.
- `audio_id` — integer, only on custom-catalog matches.

Present only when you requested them via `return`:

- `apple_music`, `spotify`, `deezer`, `musicbrainz` — per-provider
  metadata objects. Each one adds latency to the call.

Enterprise-only fields (Startup plan or higher):

- `isrc`, `upc` — recording / release identifiers.

The full per-language field index lives in each SDK doc — for example,
[Python's "What you get back" section](https://docs.audd.io/sdks/python.md).

The five things agents get wrong
--------------------------------

1. **`status=="success"` with `result=null` means no match.** Don't error on
   this — it's a normal outcome. Handle it explicitly.

2. **Standard recognize is for a short audio clip — one song.** For
   anything longer — a full-length song, a short-form video (TikTok, Reel,
   Short), a podcast, a broadcast, a DJ set, or any file with multiple
   songs to identify — use the **enterprise** endpoint instead. It chunks
   the file server-side and returns every match. The standard endpoint also
   has a 10 MB file-size cap (error #400 when exceeded); enterprise has no
   practical size cap.

3. **On enterprise calls, always set `limit`.** Enterprise bills per
   12 seconds of audio processed. The unbounded default can ingest many
   hours on one call. Set `limit=1` during development and tighten only when
   you understand the cost.

4. **Provider metadata is opt-in.** `apple_music`/`spotify`/etc. blocks are
   `null` unless you pass them in `return`. The `song_link` (lis.tn) URL is
   always present and works as a universal one-link-for-all-providers
   fallback.

5. **The test token is for hello-worlds only.** 10 requests/day, standard
   endpoint only. It doesn't work on enterprise, doesn't work on streams.
   Use a real token from [dashboard.audd.io](https://dashboard.audd.io) for
   anything beyond a one-off.

If you need… (common scenarios)
-------------------------------

- **Identify a song from a short clip** (a few seconds of audio) →
  `POST https://api.audd.io/` with `url=` or multipart `file=`.
- **Identify songs in a longer file** (full-length song, short-form video,
  podcast, broadcast, DJ set, anything with multiple songs) →
  `POST https://enterprise.audd.io/` with `limit=N`.
- **Monitor a live audio stream** → `setCallbackUrl` once, then `addStream`
  per source. Receive matches as POST callbacks to your URL.
- **Receive stream events without exposing a callback URL** → set the
  account callback URL to `https://audd.tech/empty/`, then `GET /longpoll/`.
- **Look up lyrics by query** → `POST /findLyrics/` with `q=...`.
- **Match against your own audio catalog instead of the public DB** →
  custom-catalog upload, special access required (email api@audd.io).
- **Get the streaming URL for any provider** → on a result, `apple_music.url`
  / `spotify.external_urls.spotify` / etc. when the metadata block is set;
  otherwise the `song_link` (lis.tn) acts as the universal redirect.

HTTP endpoints
--------------

The SDKs wrap these. Each line links to the reference page (HTML) and the
markdown source.

- `POST https://api.audd.io/` — recognize a clip ([docs](https://docs.audd.io/) / [.md](https://docs.audd.io/.md))
- `POST https://enterprise.audd.io/` — recognize a long file ([docs](https://docs.audd.io/enterprise) / [.md](https://docs.audd.io/enterprise.md))
- `POST https://api.audd.io/setCallbackUrl/`, `/getCallbackUrl/`, `/addStream/`, `/getStreams/`, `/setStreamUrl/`, `/deleteStream/` — manage streams ([docs](https://docs.audd.io/streams) / [.md](https://docs.audd.io/streams.md))
- `GET https://api.audd.io/longpoll/` — receive stream events without a callback URL ([docs](https://docs.audd.io/streams/#longpoll) / [.md](https://docs.audd.io/streams.md))
- `POST https://api.audd.io/upload/` — upload to a custom catalog ([docs](https://docs.audd.io/upload_audio_endpoint) / [.md](https://docs.audd.io/upload_audio_endpoint.md))
- `POST https://api.audd.io/findLyrics/` — lyrics search

The `return` form field accepts a comma-separated list of
`apple_music`, `spotify`, `deezer`, `musicbrainz`. (`napster` is no
longer available — the platform ceased operations; sending it adds warning
#51 and returns no block.) SDKs expose it
as `return_metadata` / `returnMetadata` / `ReturnMetadata` depending on
language casing.

Official SDKs
-------------

Each SDK wraps the same HTTP API. Parameter casing follows each language's
idioms (e.g. `return_metadata` in Python, `returnMetadata` in TypeScript,
`ReturnMetadata` in Go).

| Language | Install | Docs | Source |
|---|---|---|---|
| Python | `pip install audd` | [docs](https://docs.audd.io/sdks/python) / [.md](https://docs.audd.io/sdks/python.md) | [audd-python](https://github.com/AudDMusic/audd-python) |
| Node.js / TypeScript | `npm install @audd/sdk` | [docs](https://docs.audd.io/sdks/node) / [.md](https://docs.audd.io/sdks/node.md) | [audd-node](https://github.com/AudDMusic/audd-node) |
| Go | `go get github.com/AudDMusic/audd-go` | [docs](https://docs.audd.io/sdks/go) / [.md](https://docs.audd.io/sdks/go.md) | [audd-go](https://github.com/AudDMusic/audd-go) |
| Rust | `cargo add audd` | [docs](https://docs.audd.io/sdks/rust) / [.md](https://docs.audd.io/sdks/rust.md) | [audd-rust](https://github.com/AudDMusic/audd-rust) |
| PHP | `composer require audd/audd` | [docs](https://docs.audd.io/sdks/php) / [.md](https://docs.audd.io/sdks/php.md) | [audd-php](https://github.com/AudDMusic/audd-php) |
| Swift | `.package(url: "https://github.com/AudDMusic/audd-swift", from: "1.5")` | [docs](https://docs.audd.io/sdks/swift) / [.md](https://docs.audd.io/sdks/swift.md) | [audd-swift](https://github.com/AudDMusic/audd-swift) |
| Kotlin | `implementation("io.audd:audd-kotlin:1.5")` | [docs](https://docs.audd.io/sdks/kotlin) / [.md](https://docs.audd.io/sdks/kotlin.md) | [audd-kotlin](https://github.com/AudDMusic/audd-kotlin) |
| .NET / C# | `dotnet add package AudD` | [docs](https://docs.audd.io/sdks/dotnet) / [.md](https://docs.audd.io/sdks/dotnet.md) | [audd-dotnet](https://github.com/AudDMusic/audd-dotnet) |
| Java | `io.audd:audd` (Maven Central) | [docs](https://docs.audd.io/sdks/java) / [.md](https://docs.audd.io/sdks/java.md) | [audd-java](https://github.com/AudDMusic/audd-java) |
| C | `FetchContent_Declare(audd ...)` (CMake) | [docs](https://docs.audd.io/sdks/c) / [.md](https://docs.audd.io/sdks/c.md) | [audd-c](https://github.com/AudDMusic/audd-c) |
| C++ | `FetchContent_Declare(audd ...)` (CMake) | [docs](https://docs.audd.io/sdks/cpp) / [.md](https://docs.audd.io/sdks/cpp.md) | [audd-cpp](https://github.com/AudDMusic/audd-cpp) |

Reading and sending extra fields
--------------------------------

The schema above lists the fields the SDKs surface as typed accessors.
The SDKs don't hide anything beyond that — to use the rest of the HTTP API,
two SDK-side hooks are available:

- **`extras`** — a map on every typed result and every per-provider metadata
  block (e.g. `result.extras`, `result.apple_music.extras`). It carries
  every server-returned field that the SDK doesn't expose as a typed
  property. Reach for it when you want a field the typed schema above
  doesn't list.

- **`extra_parameters`** — a map on the request options. It lets you send
  form fields the SDK doesn't expose as typed parameters. Typed parameters
  win on collision.

Symbol names follow each language's idioms — `extras` / `extra_parameters`
in Python and PHP, `Extras` / `ExtraParameters` in Go and .NET, etc.

Errors
------

Every server-side error returns `status=="error"` with an `error` block
carrying an `error_code` and an `error_message`. The SDKs translate these
into typed exception families grouped by category — authentication, quota,
subscription, invalid-request, server, connection, serialization — so
catching by family is the supported pattern (the underlying numeric code
list is large and not stable to memorize). See the per-language SDK doc
above for the exception hierarchy.

A connection-level failure (timeout, TLS, DNS, etc.) raises a transport
exception in the SDKs; in raw HTTP you'll see standard curl/HTTP errors
with no AudD `status` field.

Auth
----

Pass `api_token` as a form field on every request (the SDKs read it from
their constructor or the `AUDD_API_TOKEN` environment variable). Tokens are
issued at [dashboard.audd.io](https://dashboard.audd.io). The public `test`
token works for hello-worlds on the standard endpoint only (10 req/day cap).

Reading more
------------

- API reference: [docs](https://docs.audd.io/) / [.md](https://docs.audd.io/.md)
- SDK index: [docs](https://docs.audd.io/sdks) / [.md](https://docs.audd.io/sdks.md)
- Worked guides & recipes: [resources](https://audd.io/resources) / [.txt index](https://audd.io/resources/llms.txt) — build-a-thing tutorials, endpoint-choice concepts, platform integrations, migration guides
- Dashboard (token, plans, usage): [dashboard.audd.io](https://dashboard.audd.io)
- Changelog: [changelog.audd.io](https://changelog.audd.io)

Feedback
--------

If you're an agent and this file was wrong, incomplete, or led you somewhere
unexpected — email **api@audd.io** with what you were trying to do and what
tripped you up. Reports from agents (or from the humans whose tasks they're
working on) directly drive the next revision of this file.

## Account management via MCP

An MCP server at `https://mcp.audd.io` (OAuth, Streamable HTTP) exposes
account tools — usage statistics, reading/rotating the `api_token`, plans,
Stripe payment links (which the account owner must approve in a browser —
nothing is charged automatically) — plus `get_api_docs` (these docs as
markdown) and `make_api_request` for one-off API calls on the account's
quota (audio by URL only). For programmatic use, prefer `get_api_token` +
calling the API directly. Docs: https://docs.audd.io/mcp.md