Glossary — AudD resources

Definitions of the AudD-specific terms that appear across the API, responses, and SDKs. Each entry is one concept; where an SDK uses a different name than the HTTP wire form, both are noted.

API token

The credential every API call carries, sent as the api_token form field (or query parameter). It’s an alphanumeric string with no prefix. Get one at dashboard.audd.io. The SDKs and the AudD CLI also read it from the AUDD_API_TOKEN environment variable.

request

The billing unit. One call to the standard endpoint is one request. The enterprise endpoint counts one request per 12 seconds of audio it recognizes, so a one-hour file is up to 300 requests unless skip, every, or limit reduce it. Plans include a monthly number of requests; the first 300 are free. The standard endpoint has no rate limits: requests can go out in parallel, up to millions per hour (for a large volume, tell AudD in advance at [email protected]). The enterprise endpoint has a default limit on concurrent requests, which AudD raises on request.

Standard endpoint

POST https://api.audd.io/. The default recognition method, for a short audio clip (file-size cap 10 MB). Returns a single best match, or result: null when nothing is recognized. Response time is under two seconds.

Enterprise endpoint

POST https://enterprise.audd.io/. For longer audio — full-length songs, short-form videos, podcasts, broadcasts, DJ sets — and files with multiple songs. It splits the file into chunks server-side and returns every recognized track. There is no practical file-size cap. Billing is metered per 12 seconds of audio processed, so always set limit during development.

Chunk

The unit the enterprise endpoint works in: each submitted file is treated as a sequence of 12-second audio chunks. The skip and every parameters control which chunks are fingerprinted, and billing is counted per chunk.

skip / every

Enterprise parameters that thin out which chunks get recognized. every is how many chunks to recognize in a row; skip is how many to skip after them. skip=4&every=1 recognizes 12 seconds out of every 60, and skip=9&every=1 recognizes 12 out of every 120, cutting the request count accordingly.

limit

Enterprise parameter that caps how many chunks the server recognizes for one file, and so caps the requests that file can cost. Set it during development and on any file of unknown length.

skip_first_seconds / use_timecode

Enterprise parameters for where recognition starts. skip_first_seconds skips that many seconds at the start of the file. use_timecode=true takes the start time from the URL’s own t, time_continue, or start parameter instead (as in a YouTube link with ?t=90). Use one or the other, not both.

offset

In an enterprise response, offset is the position within the file you submitted of the start of the 12-second chunk that contains a match. It locates the chunk in the overall file.

start_offset / end_offset

In an enterprise response, these are positions in milliseconds within the 12-second chunk (not within the whole file) marking where the matched fragment starts and ends. Combine with the chunk’s offset to place a match in the full file.

timecode

The position within the matched song at the point the submitted clip aligns to — for example, 02:32 means the clip matched the part of the recording two minutes and thirty-two seconds in. It is a position in the reference track, not an offset into the user’s clip.

score

A confidence value (0–100) on each enterprise match indicating how strongly the chunk matched that track. Higher is a stronger match. Access to score requires a Startup plan or higher.

ISRC

International Standard Recording Code — the unique identifier of a sound recording. Returned as isrc on a match. Available on enterprise responses and for accounts on a Startup plan or higher.

UPC

Universal Product Code — the identifier of a release (the product the recording was published on). Returned as upc on a match. Like ISRC, it is available on enterprise responses and on a Startup plan or higher.

audio_id

The identifier of a track in your own custom catalog, returned on a custom-catalog match. On such matches artist and title may be null, since the catalog entry is yours to map; you track the audio_id → song relationship on your side.

song_link

A universal link to the recognized song’s page on lis.tn, returned as song_link (for example, https://lis.tn/Warriors). It resolves to a page that links out to the song across services.

lis.tn

AudD’s short-link domain for song pages. song_link values point here.

fingerprint / audio fingerprinting

The compact, content-derived signature AudD computes from audio to identify it. Recognition works by fingerprinting the submitted audio and matching the fingerprint against the database, rather than comparing raw audio.

public database

AudD’s catalog of commercially released music — about 160 million songs — that the standard and enterprise endpoints match against by default.

custom catalog

A private fingerprint database attached to your account. You upload your own tracks via POST https://api.audd.io/upload/ (special access required; email [email protected]), and later recognition calls can match against them. Matches against your catalog carry an audio_id.

return / returnMetadata

The request option that asks for extra per-provider metadata blocks on a match. On the HTTP API it is the return form field (comma-separated identifiers such as apple_music,spotify,deezer,musicbrainz); the SDKs expose it as returnMetadata (or the language’s idiomatic equivalent). The enterprise endpoint doesn’t return provider metadata by default; if you need it there, write to [email protected].

market

Request parameter that sets the country code used for Apple Music, iTunes, and Spotify results in the returned provider blocks. Defaults to us.

extras / model_extra

A map on each typed result and per-provider block exposing fields that the SDK does not surface as typed properties — additional fields outside the typed surface. Read beta or newly added response fields through extras (some SDKs name the accessor model_extra) without waiting for a typed property.

stream / radio_id

A stream is a continuous audio source (radio, livestream, broadcast) registered for ongoing recognition via the streams endpoints. Each stream is identified by a radio_id, an integer you choose to label it. A stream URL can be a direct stream URL (HLS, Icecast, m3u/m3u8) or a shortcut such as twitch:<channel>, youtube:<video_id>, or youtube-ch:<channel_id>.

callback URL

The URL AudD POSTs stream recognition results to, set with setCallbackUrl. Each callback is a JSON payload with the recognized song. A working callback URL that returns 200 OK must be configured for the account even if you only consume results via longpoll.

longpoll

GET https://api.audd.io/longpoll/ — an HTTP long-polling way to receive stream results without running a callback server or holding a static IP. A callback URL must still be configured first; longpoll may never return events for an account that has no callback URL set, even when songs are being recognized.

longpoll category

The subscription key a longpoll client subscribes to, passed as the category parameter. It comes from the longpoll_category field on a stream in the getStreams response. You can share a category with clients without exposing your API token.

AudD MCP server

https://mcp.audd.io, a Model Context Protocol server that lets AI agents work with an AudD account: check usage, read or rotate the API token, prepare plan changes and payment links for the user to approve, search the docs, and make one-off API calls. Agents sign in with OAuth and get only the permissions the user grants. See the MCP server docs.

AudD CLI

audd, the command-line tool for recognizing songs in files, URLs, folders, long recordings, and microphone input, monitoring streams, and managing the account. Running audd with no arguments opens an interactive mode; piped output is JSON. See the CLI reference and the CLI guide for AI agents.

the test token

The public token api_token=test. It works only on the standard endpoint — not enterprise, not streams — and is limited to 10 requests per day. Use it for hello-world snippets; get your own token at dashboard.audd.io.

Related