Your Docusaurus site did not load properly.

A very common reason is a wrong site baseUrl configuration.

Current configured baseUrl = / (default value)

We suggest trying baseUrl =

AudD Music Recognition API Docs

Introduction#

AudDยฎ is music recognition API.

For the audio streams live music recognition, see docs for audio streams (it might be helpful for creating radio charts, now playing widgets or bots for YouTube and Twitch streams, etc.). We also have an endpoint that accepts large audio files (could be hours-long mixes or days-long recordings) and recognizes all the tracks in them: see docs for the enterprise endpoint.

You can send all the requests and all the parameters by GET and POST, in a query or a request body.

API methods#

Please note that the api.audd.io endpoint has methods for audio streams and methods that aren't published on this page. See the docs for audio streams or work with your AudD contact to coordinate access to the docs.

post
/
get
recognize#

https://api.audd.io/

recognize is the default API method. It's for the usual music recognition that works like Shazam. A file is required: see #Sending files or the Code examples tab below.

Form Data Parameters
api_token
REQUIRED
string
The token received from the Dashboard
url
POSSIBLY REQUIRED
string
The URL of the file for the recognition
file
POSSIBLY REQUIRED
binary
The file for the recognition
return
OPTIONAL
string
Comma-separated identifiers of the additional metadata, see below
market
OPTIONAL
integer
Country code for Apple Music, iTunes, and Spotify results, default: us

info

The return parameter is for comma-separated identifiers of the additional metadata you want to be returned. The identifiers you can send: musicbrainz โ€“ MusicBrainz metadata; apple_music, spotify, deezer, napster โ€“ Apple Music, Spotify, Deezer, Napster data and links respectively; lyrics โ€“ lyrics and additional metadata (sometimes not accurate). Example: lyrics,apple_music,spotify.

Tip: GET requests

You can also send GET requests, even though it's better to send the parameters in the POST body. Here's an example:
https://api.audd.io/?url=https://audd.tech/example1.mp3&return=apple_music,spotify&api_token=your%20api%20token
Just don't forget to url-encode the parameters.


post
/
get
recognizeWithOffset#

https://api.audd.io/recognizeWithOffset/

recognizeWithOffset is the method for recognition by humming/singing. The file is required. We can't guarantee any accuracy for this method.

Form Data Parameters
api_token
REQUIRED
string
The token received from the Dashboard
url
POSSIBLY REQUIRED
string
The URL of the file for the recognition
file
POSSIBLY REQUIRED
binary
The file for the recognition

Sending files#

For recognize and recognizeWithOffset API methods, you have to send a file for recognition. There are three ways to send files to our API:

  • Provide an HTTP URL for the file to be recognized. Our server will download the file and identify the music. Send the URL in the url parameter as a string. The parameter can be sent either in the request body or query parameters, by GET or POST. We highly recommend sending files this way. If the file is available by URL, it's the easiest way to send it.
  • Post the file using multipart/form-data in the usual way browsers upload files. Send the file in the file parameter, by POST. We recommend sending a file this way when the file is not available by a URL (for example, if they are recorded locally or are not on a server).
  • Send a base64 encoded file in the audio parameter, as a string, by POST. We discourage using this parameter and even don't list it on this page in the method descriptions, but we still support it as it can be useful in some frontend applications.

The API also supports async WebSockets: connect to wss://api.audd.io/ws/?api_token=[token] and send multiple requests (with files in binary form) without waiting for the server's responses/results.

Responses explained#

By default, the API responses are in JSON format.

All the responses contain the status field that equals either "success" if the request was successfully processed or "error" if there's been an error. In case of success, the server always returns the result field.

If the server has successfully processed the request, but there are no matches, the result field could be null or an empty array, depending on the method.

If there are matches, recognize method will return a result that's a structure that always contains artist, title, album, release_date, label, timecode, and song_link fields. Additionally, it has the data requested in the return parameter in fields corresponding to the identifiers. And just in case: timecode is the time in the recognized song when the fragment you sent is played; song_link links to a lis.tn song page like lis.tn/Warriors. Please let us know if you need album pages instead of song pages.

Authentication and limits#

To send requests, receive a token from the Dashboard. If you want to send >100 000 requests and don't want to use our Dashboard or create a Telegram account, we can manually issue a token. In this case contact us: api@audd.io, +1(302)283-9101, t.me/AudDhelp.

Where to find code examples#

Common errors#

We have about 40 different error codes. The API returns the errors with an explanation of what happened. The common errors:

  • #901 โ€” No api_token passed, and the limit was reached (you need to obtain an api_token).
  • #900 โ€” Wrong API token (check the api_token parameter).
  • #600 โ€” Incorrect audio url.
  • #700 โ€” You haven't sent a file for recognition. If you use the POST HTTP method, check the Content-Type header: it should be multipart/form-data.
  • #500 โ€” Incorrect audio file.
  • #400 โ€” Too big audio file. 10M or 25 seconds is the maximum. We recommend recording no more than 20 seconds (usually, it takes less than one megabyte). If you need to recognize larger audio files, use the enterprise endpoint instead, it supports even days-long files.
  • #300 โ€” Fingerprinting error: there was a problem with audio decoding or with the neural network. Possibly, the audio file is too small.
  • #100 โ€” An unknown error. Contact us in this case.