API Docs for audio streams

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)

It 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: api@audd.io.

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, contact us. You'll be able to use our service without interacting with the API.

Here's how you use it:

1. Set the limit of audio streams and pay

Set the limit of audio streams and pay using our Telegram bot. Please note that all the API requests requires the api_token from the bot 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 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.
Request
Response
Request
Form Data Parameters
api_token
required
string
The token received from the bot
url
required
string
The URL for the callbacks
Response
200: OK
The callback URL is successfully set
{
"status": "success",
"result": null
}

post
3. Add the streams

https://api.audd.io/addStream/
Add the streams using the addStream API method.
Request
Response
Request
Form Data Parameters
api_token
required
string
The token received from the bot
url
required
string
The URL of the audio stream
radio_id
required
integer
Any integer that will identify this stream
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 this case you won't receive the total played time in the callbacks.
Response
200: OK
The stream is successfully added
{
"status": "success",
"result": null
}

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.

  • Results contain the recognized songs.

  • Notifications are the 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.

Callback with a result
Callback with a notification
Callback with a result
{
"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"
}
]
}
}
Callback with a notification
{
"status": "-",
"notification": {
"radio_id": 3,
"stream_running": false,
"notification_code": 650,
"notification_message": "Recognition failed: can't connect to the audiostream"
},
"time":1587939136
}

If you want additional metadata to be returned (e.g. Apple Music, Spotify, MusicBrainz metadata) 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.
Request
Response
Request
Form Data Parameters
api_token
required
string
The token received from the bot
Response
200: OK
The current callback URL is showed
{
"status": "success",
"result": "https://yourwebsite.com/callbacks_handler/"
}

post
Get all the streams

https://api.audd.io/getStreams/
Use the getStreams method to get all the streams music is recognized from.
Request
Response
Request
Form Data Parameters
api_token
required
string
The token received from the bot
Response
200: OK
Returns the array of all the streams you sent us
{
"status": "success",
"result": [
{
"radio_id": 3249,
"url": "https://npr-ice.streamguys1.com/live.mp3",
"stream_running": true
},
...
]
}

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.
Request
Response
Request
Form Data Parameters
radio_id
optional
integer
api_token
required
string
The token received from the bot
Response
200: OK
The stream is successfully deleted
{
"status": "success",
"result": null
}

How to send API requests?

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

Here are examples of how to send a request by POST:

Curl
PHP
Python
Go
JS
NodeJS
Java
Curl
curl https://api.audd.io/addStream/ \
-F url='https://npr-ice.streamguys1.com/live.mp3' \
-F radio_id='3249' \
-F api_token='your api token'
PHP
<?php
$data = [
'url' => 'https://npr-ice.streamguys1.com/live.mp3',
'radio_id' => '3249',
'api_token' => 'your api token',
];
$ch = curl_init();
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_URL, 'https://api.audd.io/addStream/');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
$result = curl_exec($ch);
curl_close($ch);
echo $result;
Python
import requests
data = {
'url': 'https://npr-ice.streamguys1.com/live.mp3',
'radio_id': '3249',
'api_token': 'your api token'
}
result = requests.post('https://api.audd.io/addStream/', data=data)
print(result.text)
Go
package main
import (
"fmt"
"io/ioutil"
"net/http"
"net/url"
)
func main() {
data := url.Values{
"url": {"https://npr-ice.streamguys1.com/live.mp3"},
"radio_id": {"3249"},
"api_token": {"your api token"},
}
response, _ := http.PostForm("https://api.audd.io/addStream/", data)
defer response.Body.Close()
body, _ := ioutil.ReadAll(response.Body)
fmt.Println(string(body))
}
JS
//requires jQuery
var data = {
'url': 'https://npr-ice.streamguys1.com/live.mp3',
'radio_id': '3249',
'api_token': 'your api token'}
$.getJSON('https://api.audd.io/addStream/?jsonp=?', data, function(result){
console.log(result);
});
NodeJS
var request = require("request");
var data = {
'url': 'https://npr-ice.streamguys1.com/live.mp3',
'radio_id': '3249',
'api_token': 'your api token'
};
request({
uri: 'https://api.audd.io/addStream/',
form: data,
method: 'POST'
}, function (err, res, body) {
console.log(body);
});
Java
// requires OkHttp
public static void main() {
try {
OkHttpClient client = new OkHttpClient();
RequestBody data = new MultipartBody.Builder().setType(MultipartBody.FORM)
.addFormDataPart("url", "https://npr-ice.streamguys1.com/live.mp3")
.addFormDataPart("radio_id", "3249")
.addFormDataPart("api_token", "your api token").build();
Request request = new Request.Builder().url("https://api.audd.io/addStream/")
.post(data).build();
Response response = null;
response = client.newCall(request).execute();
String result = null;
result = response.body().string();
System.out.println(result);
} catch (Exception e) {
e.printStackTrace();
}
//Thanks to Yaniv Levy and Adam Cole for the help

You can also use 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.