Glossary — AudD resources

This page defines the AudD-specific terms used across the API, the responses, and the SDKs, one concept per entry. Where an SDK uses a different name than the HTTP wire form, both names are given in the entry.

API token

Every API call must carry an API token, sent as the api_token form field (or query parameter). The token is an alphanumeric string with no prefix. Get your own token at dashboard.audd.io. The SDKs and the AudD CLI also read the token from the AUDD_API_TOKEN environment variable.

request

AudD bills based on requests: one call to the standard endpoint is one request. The enterprise endpoint counts one request for every 12 seconds of audio it recognizes, so a one-hour file can cost up to 300 requests unless skip, every, or limit reduce it. Each plan includes a monthly number of requests, and the first 300 requests are free. Parallel requests can be made to the standard endpoint, up to millions per hour, because it has no rate limits. If you plan to send a large volume, let AudD know 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 short audio clips. The maximum file size is 10 MB. The single best match is returned; if no match is found, result: null is returned instead. The response time is under two seconds.

Enterprise endpoint

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

Chunk

The enterprise endpoint reads each submitted file in 12-second pieces called chunks. Use the skip and every parameters to customize which chunks are fingerprinted. Billing is counted per chunk.

skip / every

Enterprise parameters for recognizing only some of the chunks. every is how many chunks to recognize in a row, and skip is how many chunks to skip after them. For example, skip=4&every=1 recognizes 12 seconds out of every 60, and skip=9&every=1 recognizes 12 out of every 120, which cuts the request count accordingly.

limit

An enterprise parameter that sets the maximum number of chunks the server will recognize in one file, which also caps the requests that the file can cost. Be sure to set it during development and on any file of unknown length.

skip_first_seconds / use_timecode

These are enterprise parameters for where recognition starts. skip_first_seconds is how many seconds at the start of the file are skipped. With use_timecode=true, the start time is taken 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, in the audio 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, start_offset and end_offset are the positions (in milliseconds, within the 12-second chunk, not within the whole file) of the start and end of the fragment that was matched to a song. To place a match in the full file, combine them with the chunk’s offset.

timecode

timecode is 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

The score field provides the confidence of each enterprise match, as a number from 0 to 100 showing how strongly the chunk matched that track. The higher the score, the stronger the match. Requires a Startup plan or higher to access.

ISRC

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

UPC

UPC stands for Universal Product Code, the identifier of a release (the product that the recording was published on). Like ISRC, it is returned as the upc field of a match, on enterprise responses and for accounts on a Startup plan or higher.

audio_id

The audio_id field holds the ID of a track in your own custom catalog, and is returned when a custom-catalog match is found. On such matches, artist and title may be null, since you map the catalog entries yourself; keep a record of which song each audio_id belongs to 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). The page it resolves to links out to the song on other services.

lis.tn

lis.tn is AudD’s short-link domain for song pages; song_link values point there.

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. It contains about 160 million songs, and the standard and enterprise endpoints match against it by default.

custom catalog

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

return / returnMetadata

The return form field takes comma-separated identifiers of the additional metadata to return, such as apple_music,spotify,deezer,musicbrainz. Each identifier adds that provider’s metadata block to a match. The SDKs expose it as returnMetadata (or the language’s idiomatic equivalent). The enterprise endpoint doesn’t return provider metadata by default; please write to [email protected] if you need it there.

market

Request parameter that sets the country code for Apple Music, iTunes, and Spotify results in the returned provider blocks. By default, it is set to us.

extras / model_extra

Each typed result and per-provider block has a map, extras, for the fields that the SDK does not surface as typed properties. You can 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, such as a radio station, livestream, or broadcast, registered for ongoing recognition via the streams endpoints. The radio_id is an integer you choose, which uniquely identifies the stream. Stream URLs can be direct stream URLs (HLS, Icecast, m3u/m3u8) or shortcuts such as twitch:<channel>, youtube:<video_id>, or youtube-ch:<channel_id>.

callback URL

Stream recognition results are sent to this URL as an HTTP POST request, with a JSON payload containing the recognized song. You can set it with setCallbackUrl. 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/. With HTTP long polling, you can receive stream results without running a callback server or having a static IP. Note that a callback URL must still be configured first. For an account with no callback URL set, longpoll may never return events, even when songs are being recognized.

longpoll category

The key that a longpoll client subscribes to, passed as the category parameter. You can find it in the longpoll_category field of each stream in the getStreams response. You can share a category with clients without exposing your API token.

AudD MCP server

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

AudD CLI

audd is the command-line tool for AudD. You can use it to recognize songs in files, URLs, folders, long recordings, and microphone input, to monitor streams, and to manage the account. Running audd without any arguments will open an interactive mode. When its output is piped, it is printed as JSON. For more information, see the CLI reference and the CLI guide for AI agents.

the test token

The public test token (api_token=test) only allows 10 requests per day. It works only on the standard endpoint, and not on enterprise or streams. Use it for hello-world snippets. To get your own token, go to dashboard.audd.io.

Related