Music recognition for audio streams API Docs#

You can use AudD real-time music recognition service for audio streams to identify the songs that are being played on radio stations (or any other streams)

info

The music recognition costs $45 per audio stream per month with our music DB. Or $25 per stream per month if you have your own content that you want to recognize instead of using our music DB. In the second case, contact us: [email protected].

We wanted to make the API as simple as possible: you send us the URLs of radio streams, we send you the recognition results in real-time.

If you don't have a server to receive the results and just want to download reports as e.g. tables, or a bot that posts what the song is now playing in YouTube, Twitch or Discord chat, or a Twitch extension, contact us. You'll be able to use our service without interacting with the API.

How to use it:#

1. Set the limit of audio streams and pay#

Set the limit of audio streams and pay on the API Dashboard.

Please note that all the API requests require the api_token from the Dashboard to be specified as either the query parameter or the POST field. So just send it in all the requests as api_token.

By the way, if you change the limit later, the unused amount pf time will be applied as a discount.

post
2. Set the URL for callbacks#

https://api.audd.io/setCallbackUrl/

Set the URL for callbacks using the setCallbackUrl API method.
You can change the URL at any time using this method.
Callbacks are the requests with recognition results our servers will send to your server.

Form Data Parameters
api_token
REQUIRED
string
The token received from the Dashboard
url
REQUIRED
string
The URL for the callbacks

post
3. Add the streams#

https://api.audd.io/addStream/

Add the streams using the addStream API method.

Form Data Parameters
api_token
REQUIRED
string
The token received from the Dashboard
url
REQUIRED
string
The URL of the audio stream
radio_id
REQUIRED
integer
Any integer that will identify this stream for you
callbacks
OPTIONAL
string
By default, callbacks are sent after the song ended playing and contain the total streamed time of the song. Set this parameter to "before", if you want to receive the callbacks as soon as a song started playing (not when it ended). In case you send "before", you won't receive the total played time in the callbacks.

info

As the URL of the audio stream, you can simply send the URL of a stream, like https://npr-ice.streamguys1.com/live.mp3. We support most of the stream formats, including DASH, Isecast, HLS, m3u/m3u8.

We also natively support Twitch broadcasts and YouTube live streams, and you can send twitch:[channel name], youtube:[video id], and youtube-ch:[channel id] as the URL - like twitch:monstercat for twitch.tv/monstercat, youtube:5qap5aO4i9A for youtube.com/watch?v=5qap5aO4i9A, or youtube-ch:UC3zwjSYv4k5HKGXCHMpjVRg for the current live stream on youtube.com/channel/UC3zwjSYv4k5HKGXCHMpjVRg.

4. Receive the results#

Receive the results in the callbacks.
The callbacks will be sent to the specified URL as a JSON structure in the POST payload. The format is bellow.
You'll receive callbacks with results and with notifications.

  • The results contain the recognized songs.
  • Notifications are information about problems with the streams. If something happens to an audio stream, we'll let you know by sending a notification so you can fix the stream or change its URL. There are 3 codes: 0 (which means that everything's fine), 650 (which means that we can't connect to the stream) and 651 (which means that we don't receive any music from the stream, only white noise). Notifications also contain the time of sending.
{
"status": "success",
"result": {
"radio_id": 7,
"timestamp": "2020-04-13 10:31:43",
"play_length": 111,
"results": [
{
"artist": "Alan Walker, A$AP Rocky",
"title": "Live Fast (PUBGM)",
"album": "Live Fast (PUBGM)",
"release_date": "2019-07-25",
"label": "MER Recordings",
"score": 100,
"song_link": "https://lis.tn/LiveFastPUBGM"
}
]
}
}

If you want additional metadata (e.g. Apple Music, Spotify, MusicBrainz metadata) to be returned with the callbacks, contact us.

If your server doesn't respond to the callbacks with the 200 OK status or we can't connect to your server, we'll put the callbacks to a queue. When your server is back online, we'll send all the backlog.

We have a rate limit for the requests we're sending: you'll not receive more than 3 callbacks per second (with a burst size of 15).

What else can I do?#

We have additional methods for the full management of the streams.

post
Get the current callback URL#

https://api.audd.io/getCallbackUrl/

Use the getCallbackUrl method to get the current callback URL. You can always change it with the setCallbackUrl method.

Form Data Parameters
api_token
REQUIRED
string
The token received from the Dashboard

post
Get all the streams#

https://api.audd.io/getStreams/

Use the getStreams method to get all the streams the music is being recognized from.

Form Data Parameters
api_token
REQUIRED
string
The token received from the Dashboard

post
Update stream URL#

https://api.audd.io/setStreamUrl/

Use the setStreamUrl method to update the URL of a stream.

Form Data Parameters
api_token
REQUIRED
string
The token received from the Dashboard
url
REQUIRED
string
The new URL of the audio stream
radio_id
REQUIRED
integer
The integer that identifies this stream

post
Delete a stream#

https://api.audd.io/deleteStream/

Use the deleteStream method to delete a stream. We'll stop to recognize music from it and forget about it's existence.

Form Data Parameters
api_token
REQUIRED
string
The token received from the Dashboard
radio_id
REQUIRED
integer
The integer that identifies this stream

How to send API requests?#

There are the Code example tabs in each of the request descriptions. You can use them for reference.

You can send all the fields as GET URL parameters or as POST form data parameters.

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/getStreams/?api_token=your%20api%20token
Just don't forget to url-encode the data.