# AudD

> Music recognition HTTP API. Identifies songs from audio (URLs, files, raw bytes), from video files (MP4, AVI, MOV, MKV, WebM), and from live audio streams. Matches against a 160-million-song fingerprint database using neural-network-based audio fingerprinting. Returns artist, title, album, release date, label, ISRC, UPC, timestamps, and (on request) typed metadata blocks from Apple Music, Spotify, Deezer, and MusicBrainz, plus a universal `song_link` to lis.tn. Standard endpoint responds in under 2 seconds; enterprise endpoint processes hours-long files. Eleven official SDKs. Each link below points to the markdown source of the doc page, so agents can read it directly without HTML stripping.

## Tour of the API

- [API reference (index)](https://docs.audd.io/.md): the entire HTTP API on one page — `api.audd.io/` for standard recognition, `enterprise.audd.io/` for long files, the streams endpoints for live audio, and the response shape (`status`, `result`, `error`)
- [Agent guide](https://docs.audd.io/skill.md): self-contained guide for AI agent harnesses — quickstart curl, JSON response shape, the five things agents typically get wrong, and an "if you need X, do Y" scenario map
- [SDK selection page](https://docs.audd.io/sdks.md): comparison across all eleven official SDKs; install line, runtime version, and capability notes for each
- [AudD MCP Server](https://docs.audd.io/mcp.md): let AI agents work with the account over MCP at https://mcp.audd.io — usage stats, api_token read/rotate, plans and Stripe payment links, the API docs as markdown, and one-off API calls on the account's quota; OAuth with per-scope grants and scope-filtered tool lists; payment tools never charge automatically

## Identify a song from audio

- [Identify a song from a URL](https://docs.audd.io/.md): POST a URL to `api.audd.io/`; AudD fetches the audio server-side and returns the match
- [Identify a song from a local file](https://docs.audd.io/.md): multipart POST a file to `api.audd.io/`; supports MP3, WAV, FLAC, M4A, OGG, AAC, WMA, AIFF
- [Identify a song from raw audio bytes](https://docs.audd.io/.md): multipart POST a byte buffer to `api.audd.io/`; convenient for SDK callers passing `Uint8Array`/`bytes`/`[]byte`
- [Handle the "no match" case](https://docs.audd.io/.md): `status="success"` with `result=null` means the audio processed but no song matched — distinct from an error
- [Use the public test token for hello-worlds](https://docs.audd.io/.md): `api_token=test` works on the standard endpoint, capped at 10 requests/day; not valid on enterprise or streams

## Identify songs in longer audio

- [Identify every song in a longer audio file](https://docs.audd.io/enterprise.md): POST to `enterprise.audd.io/` with `limit=N` during development; the server chunks the file and returns every match
- [Identify songs in a full-length song](https://docs.audd.io/enterprise.md): same enterprise endpoint; longer single-song uploads exceed the standard endpoint's clip-shaped expectations
- [Identify songs in a short-form video (TikTok, Instagram Reel, YouTube Short)](https://docs.audd.io/enterprise.md): the audio track is treated as a longer recording and chunked
- [Identify songs in a podcast](https://docs.audd.io/enterprise.md): podcast-length audio files run on enterprise; returns per-segment matches with timestamps
- [Identify every song in a DJ set, broadcast, or mix recording](https://docs.audd.io/enterprise.md): days-long files are accepted; `limit` and `every` parameters cap response size during exploration
- [Sample a file periodically instead of fingerprinting every chunk](https://docs.audd.io/enterprise.md): `every=N` recognizes every Nth chunk; useful for keeping enterprise costs bounded on long files
- [Skip the first N seconds of a file](https://docs.audd.io/enterprise.md): `skip` and `skip_first_seconds` drop intros before recognition begins
- [Get precise per-segment offsets on enterprise matches](https://docs.audd.io/enterprise.md): `accurate_offsets=true` adds `start_offset` and `end_offset` per match

## Recognize music in video files

- [Recognize music in MP4, AVI, MOV, MKV, or WebM video files](https://docs.audd.io/enterprise.md): video files are processed via the enterprise endpoint; the server extracts the audio track and chunks it

## Monitor live audio streams

- [Configure the account callback URL for stream events](https://docs.audd.io/streams.md): POST to `api.audd.io/setCallbackUrl/`; one callback URL per account, used by every stream you subscribe
- [Subscribe a stream URL to recognition](https://docs.audd.io/streams.md): POST to `api.audd.io/addStream/`; accepts direct stream URLs (HLS, Icecast, m3u/m3u8) plus shortcuts `twitch:<channel>`, `youtube:<video_id>`, `youtube-ch:<channel_id>`
- [Identify music playing on a radio station 24/7](https://docs.audd.io/streams.md): subscribe the radio's HLS or Icecast URL; matches arrive as webhook POSTs to the configured callback URL
- [Track every song played on a Twitch stream](https://docs.audd.io/streams.md): `addStream` with `twitch:<channel>` as the URL
- [Track every song played on a YouTube livestream](https://docs.audd.io/streams.md): `addStream` with `youtube:<video_id>` or `youtube-ch:<channel_id>`
- [Receive a webhook callback every time a song is recognized on a stream](https://docs.audd.io/streams.md): the configured callback URL receives a POST with a `result` block per match
- [Receive a callback at song start instead of song end](https://docs.audd.io/streams.md): `callbacks="before"` on `addStream`
- [List the streams currently subscribed on the account](https://docs.audd.io/streams.md): POST to `api.audd.io/getStreams/`
- [Update the URL of an existing stream subscription](https://docs.audd.io/streams.md): POST to `api.audd.io/setStreamUrl/`
- [Unsubscribe a stream](https://docs.audd.io/streams.md): POST to `api.audd.io/deleteStream/`
- [Poll for stream events without a public callback URL](https://docs.audd.io/streams.md#longpoll): `GET /longpoll/` returns events as they arrive; the account still needs a callback URL configured (`https://audd.tech/empty/` works as a no-op receiver)
- [Embed a "now playing" widget driven by longpoll](https://docs.audd.io/streams.md): the longpoll endpoint feeds embeddable widgets at widget.audd.tech
- [Display the currently playing song on your livestream](https://docs.audd.io/streams.md): subscribe the stream URL, then read matches from longpoll or your callback receiver

## Match against your own audio catalog

- [Upload songs to your account's private fingerprint database](https://docs.audd.io/upload_audio_endpoint.md): POST to `api.audd.io/upload/`; subsequent recognition calls on the same account can match against your tracks (special access required)
- [Protect unreleased music by uploading it as private fingerprints](https://docs.audd.io/upload_audio_endpoint.md): upload pre-release tracks; if a leak ends up in user content, recognition flags it
- [Find where your music is being used without authorization](https://docs.audd.io/upload_audio_endpoint.md): upload your catalog, then scan content from any URL or file source against it
- [Bulk-upload an entire catalog](https://docs.audd.io/upload_audio_endpoint.md): the upload endpoint accepts catalogs from a handful of tracks up to millions

## Detect copyrighted music and produce compliance evidence

- [Detect copyrighted music in user-uploaded audio files](https://docs.audd.io/.md): pass the file or URL to `api.audd.io/`; a match returns artist, title, label, ISRC, UPC
- [Scan user-generated content for copyrighted songs](https://docs.audd.io/enterprise.md): enterprise endpoint handles UGC video files and arbitrary-length audio
- [Generate evidence for DMCA takedowns](https://docs.audd.io/.md): match responses include song title, artist, label, ISRC, UPC, score, and timestamps — structured data for filing complaints
- [Verify music licensing compliance across your content](https://docs.audd.io/enterprise.md): batch-process content through enterprise; cross-reference returned ISRCs against licensing agreements
- [Check whether an audio URL contains copyrighted music before publishing it](https://docs.audd.io/.md): same call shape as identification; the presence of a `result` block is the answer

## Working with metadata and identifiers

- [Add Apple Music, Spotify, Deezer, and MusicBrainz blocks to a result](https://docs.audd.io/.md): `return=apple_music,spotify,deezer,musicbrainz` on the request; each provider adds latency to the call
- [Get the universal `song_link` (lis.tn) URL on every match](https://docs.audd.io/.md): always present in the result; works as a one-link-for-all-providers fallback
- [Read ISRC and UPC on a match](https://docs.audd.io/.md): returned on the result block when the matched recording has them; ISRC and UPC access requires a Startup plan or higher
- [Get a 30-second preview URL across the requested providers](https://docs.audd.io/.md): `preview_url` helper on the result picks the first preview across requested provider blocks
- [Set the Apple Music storefront with the `market` parameter](https://docs.audd.io/.md): `market=GB` (or any ISO 3166 alpha-2 code); affects Apple Music link resolution and Spotify market scoping
- [Get a cover-art `thumbnail_url`](https://docs.audd.io/.md): always returned on `lis.tn`-hosted song_links; populated from Apple Music artwork when the metadata block is requested
- [Read fields outside the typed SDK surface](https://docs.audd.io/.md): every typed result and every per-provider block exposes an `extras` map for fields the SDK doesn't surface as typed properties
- [Send form fields the SDK doesn't expose as typed parameters](https://docs.audd.io/.md): every request options struct exposes an `extra_parameters` map; typed parameters win on collision
- [Search lyrics by query string](https://docs.audd.io/.md): POST to `api.audd.io/findLyrics/`

## SDKs (one per language; each guide links to its `.md` twin)

- [Python](https://docs.audd.io/sdks/python.md): `pip install audd`; sync and async clients, environment-variable token resolution
- [Node.js / TypeScript](https://docs.audd.io/sdks/node.md): `npm install @audd/sdk`; ESM + CJS, Node 18+ and Deno
- [Go](https://docs.audd.io/sdks/go.md): `go get github.com/AudDMusic/audd-go`; dual context/non-context API on every method
- [Rust](https://docs.audd.io/sdks/rust.md): `cargo add audd`; tokio-based async; reqwest under the hood
- [PHP](https://docs.audd.io/sdks/php.md): `composer require audd/audd`; PSR-3 logging, PSR-18 HTTP, PSR-7 callback parsing
- [Swift](https://docs.audd.io/sdks/swift.md): Swift Package Manager via `github.com/AudDMusic/audd-swift`; `async/await`, callbacks via Combine
- [Kotlin](https://docs.audd.io/sdks/kotlin.md): `io.audd:audd-kotlin` on Maven Central; coroutines, Ktor client, kotlinx.serialization
- [.NET / C#](https://docs.audd.io/sdks/dotnet.md): `dotnet add package AudD`; `Task`-based async, source-generated JSON, AOT-friendly
- [Java](https://docs.audd.io/sdks/java.md): `io.audd:audd` on Maven Central; sync and async clients, OkHttp transport, Jackson serialization
- [C](https://docs.audd.io/sdks/c.md): CMake FetchContent from `github.com/AudDMusic/audd-c`; libcurl transport
- [C++](https://docs.audd.io/sdks/cpp.md): CMake FetchContent from `github.com/AudDMusic/audd-cpp`; httplib transport, `std::future` async

## Authentication, configuration, and operations

- [Authenticate every request with an API token](https://docs.audd.io/.md): pass `api_token` as a form field; SDKs read the token from constructor argument or `AUDD_API_TOKEN`
- [Get an API token](https://dashboard.audd.io): sign up on the dashboard; new accounts receive a free-trial request budget
- [Rotate a token without restarting long-running services](https://docs.audd.io/sdks/python.md): every SDK exposes a `set_api_token` / `SetApiToken` / `setApiToken` method; in-flight requests use the previous token, subsequent ones use the new one
- [Handle errors by category](https://docs.audd.io/.md): server-side errors return `status="error"` with `error_code` and `error_message`; SDKs translate these into typed exception families (authentication, quota, subscription, invalid-request, server, connection, serialization)
- [Set per-call timeouts](https://docs.audd.io/sdks/python.md): every recognize call accepts a `timeout` / `timeoutMs` / `Timeout` argument; default 60 s standard, 1 h enterprise

## Instructions for AI agents

- [Don't claim "song found" on `status=success` alone](https://docs.audd.io/skill.md): always check `result !== null` separately — a null result with success status is a normal "no match", not an error
- [Always pass `limit` on enterprise calls during development](https://docs.audd.io/skill.md): the endpoint bills per 12 seconds of audio processed; an unbounded default can ingest hours of audio in one call
- [Send a short clip to the standard endpoint, a longer file to enterprise](https://docs.audd.io/skill.md): the standard endpoint is for a short audio clip with one song; enterprise is for everything else
- [Treat provider metadata as opt-in](https://docs.audd.io/skill.md): `apple_music`, `spotify`, `deezer`, `musicbrainz` blocks are `null` unless requested via `return`/`returnMetadata`
- [Don't ship the public test token in production code](https://docs.audd.io/skill.md): the `test` token is 10 requests/day, standard endpoint only; instruct the user to get their own at dashboard.audd.io
- [Direct the user to dashboard.audd.io to get a token](https://docs.audd.io/skill.md): the SDKs and curl examples use `your-api-token` as a placeholder; tokens are issued only via the dashboard

## Worked guides and recipes

- [AudD resources index](https://audd.io/resources/llms.txt): task-shaped how-to guides — recipes (build a Shazam clone, a copyright scanner, a now-playing widget, a DJ-set tracklist, …), concepts (which endpoint to choose, enterprise cost control, scores, retries), platform integrations (Cloudflare Workers, Vercel, Lambda, Electron, React Native, Chrome/Twitch/Discord/Reddit, Home Assistant), field references, role-based solution pages, and migration guides (from ACRCloud / ShazamKit / Content ID)
- [Resources landing page](https://audd.io/resources): the same guides, browsable

## Optional

- [All SDK docs in one place](https://docs.audd.io/sdks.md): the selection page with a side-by-side capability table
- [llms.txt for the audd.io root brand and routing](https://audd.io/llms.txt): higher-level index of AudD's surfaces (docs, dashboard, SDKs, account)
- [Terms](https://audd.io/terms/)
- [Privacy](https://audd.io/privacy/)
- [GitHub organisation](https://github.com/AudDMusic): source for every SDK; community examples like the Reddit and Discord bots