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)

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: [e-mail].

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 require 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.

2. Set the URL for callbacks

POST 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 Body

Name	Type	Description
api_token	string	The token received from the bot
url	string	The URL for the callbacks

200 The callback URL is successfully set

{
    "status": "success",
    "result": null
}

3. Add the streams

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

Add the streams using the addStream API method.

Request Body

Name	Type	Description
api_token	string	The token received from the bot
url	string	The URL of the audio stream
radio_id	integer	Any integer that will identify this stream
callbacks	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.

200 The stream is successfully added

{
    "status": "success",
    "result": null
}

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 also natively support Twitch and YouTube live streams, and you can send twitch:[channel name] and youtube:[video id] as the URL - like twitch:monstercat or youtube:5qap5aO4i9A.

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.

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.

Get the current callback URL

POST 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 Body

Name	Type	Description
api_token	string	The token received from the bot

200 The current callback URL is showed

{
    "status": "success",
    "result": "https://yourwebsite.com/callbacks_handler/"
}

Get all the streams

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

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

Request Body

Name	Type	Description
api_token	string	The token received from the bot

200 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
        },
        {
            "radio_id": 5512,
            "url": "youtube:5qap5aO4i9A",
            "stream_running": true
        },
        {
            "radio_id": 5513,
            "url": "twitch:monstercat",
            "stream_running": true
        },
        ...
    ]
}

Delete a stream

POST 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 Body

Name	Type	Description
radio_id	integer
api_token	string	The token received from the bot

200 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

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"
	"github.com/AudDMusic/audd-go"
	"io/ioutil"
	"net/http"
	"net/url"
)

func main() {
	client := audd.NewClient("your api token")
	Url := "https://npr-ice.streamguys1.com/live.mp3"
	err := client.AddStream(Url, 3249, "", nil)
	if err != nil {
		panic(err)
	}
}

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.