AudD® Music Recognition API Docs

Introduction

AudD is music recognition API.

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

API docs for audio streams live recognition are on streams.audd.io.

Required parameters

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 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 that files are uploaded via the 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. Not a recommended way, but supported and can be useful in some applications (usually front-end).
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.

API methods

recognize is the default API method. It is for standard music recognition that works like Shazam. File is required. Additional parameters:

  • return — field with comma-separated names of what you want to be returned. Example: lyrics,apple_music,deezer,spotify.
    The names 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); itunes – iTunes data and links (depricated; sometimes not accurate; use apple_music instead).
  • market — country code for Apple Music, iTunes and Spotify results. Default: us. Example: es.

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

findLyrics is the method for lyrics searching. It's required to send one parameter:

  • q — search query. Song title and artist or an excerpt from the lyrics.

Code examples

Results

All the API responses contain status field, which is "success" if everything is OK or "error" if there's been an error. In case of success requests, the result field is returned.

recognize method returns the result which is either null (means that there's no result) or a structure with artist, title, album, release_date, label, timecode (time in the recognized song when the fragment is being played) and song_link (a lis.tn link like lis.tn/Warriors) fields, and also all the data requested by the return parameter. Look at the example: api.audd.io/?url=https://audd.tech/example1.mp3&return=lyrics,apple_music,deezer,spotify,napster.

For recognizeWithOffser method, look at the example: api.audd.io/recognizeWithOffset/?url=https://audd.tech/example_h1.ogg.

For findLyrics method, look at the example: api.audd.io/findLyrics/?q=Adele Hello.

Authentication and limits

To send > 10 requests, you need to receive an api_token from our TG bot or contact us:
[email protected]
+1(302)283-9101
t.me/AudDhelp

Common errors

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

  • #901 — No api_token passed and the limit was reached (you need to obtain the api_token).
  • #900 — Wrong API token (api_token).
  • #600 — Incorrect audio url.
  • #700 — You haven't sent a file for recognition. If you use POST HTTP method, please 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 really big audio files, our Enterprise endpoint supports files that up to 24h long. Contact us.
  • #300 — Fingerprinting error: there was a problem with audio decoding or with the neural network. Most likely, the audio file is too small.
  • #100 — Unknown error. Contact us in this case.

Examples of Requests

GETor POST Music recognition with lyrics returning
https://api.audd.io/?url=https://audd.tech/example1.mp3&return=lyrics

Default music recognition

PARAMS or BODY

url
https://audd.tech/example1.mp3
return
lyrics


Sample Request
Music recognition with lyrics returning
curl --request GET \
  --url 'https://api.audd.io/?url=https://audd.tech/example1.mp3&return=lyrics'
Sample Response
{
  "status": "success",
  "result": {
    "artist": "Imagine Dragons",
    "title": "Warriors",
    "album": "Warriors",
    "release_date": "2014-09-18",
    "label": "Universal Music",
    "timecode": "00:40",
    "song_link": "https://lis.tn/Warriors",
    "lyrics": {
      "song_id": "520879",
      "artist_id": "29472",
      "title": "Warriors",
      "title_with_featured": "Warriors",
      "full_title": "Warriors by Imagine Dragons",
      "artist": "Imagine Dragons",
      "lyrics": "[Verse 1]\r\n As a child, you would wait and watch from far away\r\n But you always knew that you'd be the one\r\n To work while they all play\r\n In youth, you'd lay awake at night and scheme\r\n Of all the things that you would change\r\n But it was just a dream\r\n \r\n [Chorus]\r\n Here we are, don't turn away now\r\n We are the warriors that built this town\r\n Here we are, don't turn away now\r\n We are the warriors that built this town\r\n From dust\r\n \r\n [Verse 2]\r\n The time will come, when you will have to rise\r\n Above the best, and prove yourself\r\n Your spirit never dies\r\n Farewell, I've gone, to take my throne above\r\n But don't weep for me, 'cause this will be\r\n The labor of my love\r\n \r\n [Chorus]\r\n Here we are, don't turn away now\r\n We are the warriors that built this town\r\n Here we are, don't turn away now\r\n We are the warriors that built this town\r\n From dust\r\n Here we are, don't turn away now\r\n We are the warriors that built this town\r\n Here we are, don't turn away now\r\n We are the warriors that built this town\r\n From dust",
      "media": "[{\"provider\":\"apple_music\",\"provider_id\":\"1043732102\",\"type\":\"audio\",\"url\":\"https:\\/\\/itunes.apple.com\\/lookup?entity=song&id=1043732102\"},{\"native_uri\":\"spotify:track:1lgN0A2Vki2FTON5PYq42m\",\"provider\":\"spotify\",\"type\":\"audio\",\"url\":\"https:\\/\\/open.spotify.com\\/track\\/1lgN0A2Vki2FTON5PYq42m\"},{\"provider\":\"youtube\",\"start\":0,\"type\":\"video\",\"url\":\"http:\\/\\/www.youtube.com\\/watch?v=fmI_Ndrxy14\"}]"
    }
  }
}
GETor POST Recognition by humming
https://api.audd.io/recognizeWithOffset/?url=https://audd.tech/example_h1.ogg

Recognize by humming

PARAMS or BODY

url
https://audd.tech/example_h1.ogg
method
recognizeWithOffset


Sample Request
Recognition by humming
curl --request GET \
  --url 'https://api.audd.io/recognizeWithOffset/?url=https://audd.tech/example_h1.ogg'
Sample Response
{
  "status": "success",
  "result": {
    "underground": "humming",
    "humming": true,
    "count": 1,
    "list": [
      {
        "score": 0.96,
        "artist": "Taylor Swift",
        "title": "Last Christmas"
      }
    ]
  }
}
GETor POST Adele – Hello lyrics searching
https://api.audd.io/findLyrics/?q=adele hello

Lyrics search by artist and song title

PARAMS or BODY

method
findLyrics
q
adele hello


Sample Request
Adele – Hello lyrics searching
curl --request GET \
  --url 'https://api.audd.io/findLyrics/?q=adele%20hello'
Sample Response
{
  "status": "success",
  "result": [
    {
      "song_id": "2332455",
      "artist_id": "2300",
      "title": "Hello",
      "title_with_featured": "Hello",
      "full_title": "Hello by Adele",
      "artist": "Adele",
      "lyrics": "[Verse 1]\r\n Hello, it's me\r\n I was wondering if after all these years you'd like to meet\r\n To go over everything\r\n They say that time's supposed to heal ya, but I ain't done much healing\r\n Hello, can you hear me?\r\n I'm in California dreaming about who we used to be\r\n When we were younger and free\r\n I've forgotten how it felt before the world fell at our feet\r\n There's such a difference between us\r\n And a million miles\r\n \r\n [Chorus]\r\n Hello from the other side\r\n I must've called a thousand times\r\n To tell you I'm sorry\r\n For everything that I've done\r\n But when I call, you never seem to be home\r\n Hello from the outside\r\n At least I can say that I've tried\r\n To tell you I'm sorry, for breaking your heart\r\n But it don't matter\r\n It clearly doesn't tear you apart anymore\r\n \r\n [Verse 2]\r\n Hello, how are you?\r\n It's so typical of me to talk about myself, I'm sorry\r\n I hope that you're well\r\n Did you ever make it out of that town where nothing ever happened?\r\n It's no secret that the both of us\r\n Are running out of time\r\n [Chorus]\r\n So hello from the other side\r\n I must've called a thousand times\r\n To tell you I'm sorry\r\n For everything that I've done\r\n But when I call, you never seem to be home\r\n Hello from the outside\r\n At least I can say that I've tried\r\n To tell you I'm sorry, for breaking your heart\r\n But it don't matter\r\n It clearly doesn't tear you apart anymore\r\n \r\n [Bridge]\r\n (Highs, highs, highs, highs, lows, lows, lows, lows)\r\n Ooh, anymore\r\n (Highs, highs, highs, highs, lows, lows, lows, lows)\r\n Ooh, anymore\r\n (Highs, highs, highs, highs, lows, lows, lows, lows)\r\n Ooh, anymore\r\n (Highs, highs, highs, highs, lows, lows, lows, lows)\r\n Anymore\r\n \r\n [Chorus]\r\n Hello from the other side\r\n I must've called a thousand times\r\n To tell you I'm sorry\r\n For everything that I've done\r\n But when I call, you never seem to be home\r\n Hello from the outside\r\n At least I can say that I've tried\r\n To tell you I'm sorry, for breaking your heart\r\n But it don't matter\r\n It clearly doesn't tear you apart anymore\r\n [Produced by Greg Kurstin]\r\n [Music Video]"
    }
  ]
}
GETor POST Searching by excerpt from Radioactive lyrics
https://api.audd.io/findLyrics/?q=I'm waking up to ash and dust

Lyrics and metadata search by excerpt from the lyrics

PARAMS or BODY

method
findLyrics
q
I'm waking up to ash and dust


Sample Request
Searching by excerpt from Radioactive lyrics
curl --request GET \
  --url 'https://api.audd.io/findLyrics/?q=I%27m%20waking%20up%20to%20ash%20and%20dust'
Sample Response
{
  "status": "success",
  "result": [
    {
      "song_id": "98754",
      "artist_id": "29472",
      "title": "Radioactive",
      "title_with_featured": "Radioactive",
      "full_title": "Radioactive by Imagine Dragons",
      "artist": "Imagine Dragons",
      "lyrics": "[Verse 1]\r\n I'm waking up to ash and dust\r\n I wipe my brow and I sweat my rust\r\n I'm breathing in the chemicals\r\n \r\n [Refrain]\r\n I'm breaking in, shaping up\r\n Checking out on the prison bus\r\n This is it, the apocalypse – whoa\r\n \r\n [Pre-Chorus]\r\n I'm waking up, I feel it in my bones\r\n Enough to make my systems blow\r\n Welcome to the new age, to the new age\r\n Welcome to the new age, to the new age\r\n \r\n [Chorus]\r\n Whoa, whoa – I'm radioactive, radioactive\r\n Whoa, whoa – I'm radioactive, radioactive\r\n \r\n [Verse 2]\r\n I raise my flags, dye my clothes\r\n It's a revolution, I suppose\r\n We're painted red to fit right in, whoa\r\n \r\n [Refrain]\r\n I'm breaking in, shaping up\r\n Checking out on the prison bus\r\n This is it, the apocalypse – whoa\r\n \r\n [Pre-Chorus]\r\n I'm waking up, I feel it in my bones\r\n Enough to make my systems blow\r\n Welcome to the new age, to the new age\r\n Welcome to the new age, to the new age\r\n \r\n [Chorus]\r\n Whoa, whoa – I'm radioactive, radioactive\r\n Whoa, whoa – I'm radioactive, radioactive\r\n \r\n [Bridge]\r\n All systems go, sun hasn't died\r\n Deep in my bones, straight from inside\r\n \r\n [Pre-Chorus]\r\n I'm waking up, I feel it in my bones\r\n Enough to make my systems blow\r\n Welcome to the new age, to the new age\r\n Welcome to the new age, to the new age\r\n \r\n [Chorus]\r\n Whoa, whoa – I'm radioactive, radioactive\r\n Whoa, whoa – I'm radioactive, radioactive"
    }
  ]
}