AudD Music Recognition API Docs
#
IntroductionAudDยฎ 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 enteprise entpoint.
You can send all the requests and all the parameters by GET and POST, in a query or a request body.
api_token
โ auth token that's required for all your requests. You can get one from the API Dashboard. Sign up with a Telegram account to get the first 300 requests for free.
#
API methodsPlease note that the api.audd.io endpoint also has methods for audio streams and methods that aren't published. See the docs for audio streams or work with your AudD contact to coordinate access to the docs.
post/getrecognize#
recognize
is the default API method. It's for standard music recognition that works like Shazam. A file is required, see #Sending files or the Code examples tab below.
- Request
- Response
- Code examples
string
string
binary
string
integer
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/getrecognizeWithOffset#
recognizeWithOffset
is the method for recognition by humming/singing. The file is required. We can't guarantee any accuracy for this method.
- Request
- Response
- Code examples
string
string
binary
#
Sending filesFor 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 and recognize the file. Send the URL in the
url
parameter, as a string. The parameter can be sent either in request body or query parameters, by GET or POST. This way is highly recommended. 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 files are uploaded by browser. Send the file in the
file
parameter, by POST. Recommended using if 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 really discourage the usage of this parameter and even don't list it below 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 server's responses/results.
#
Responses explainedBy default, the API responses are in the JSON format.
All the responses contain the status
field that equals either "success" if everything is OK or "error" if there's been an error. In case of a success, the result
field is always returned.
If the request was successfully processed but there's no matches, the result
field could be null
or an empty array, depending on the method.
If there are matches, for the recognize
method the result
is a structure that always contains artist
, title
, album
, release_date
, label
, timecode
and song_link
fields. Additionaly, it has the data requested in the return
parameter in corresponding identifiers.
And just in case: timecode
is the time in the recognized song when the fragment you sent is played; song_link
is a lis.tn link like lis.tn/Warriors. Please let us know if you need album links instead of song links.
#
Authentication and limitsTo send requests, receive a token from the Dashboard (requires a Telegram account).
If you want to send >100 000 requests and don't want to use our Dashboard or to create a Telegram account, we can issue a token for you manually, in this case contact us: [email protected], +1(302)283-9101, t.me/AudDhelp.
#
Where to find code examples- There are the Code example tabs in each of the request descriptions. You can use them for reference.
- You can search for code examples on GitHub.
- We have a Chrome extension written in JS that recognizes music from the opened tab of your browser. Source code: github.com/AudDMusic/audd-chrome-extension.
- We've published an example Discord bot source code in Golang that recognizes music from a voice channel: github.com/AudDMusic/discord-bot.
#
Common errorsWe 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 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 maximum, we recommend to record 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 the files that are days-long.
- #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.