Skip to main content

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

We wanted to make the API as simple as possible: you send us the URLs of radio streams, and 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.

After this, you can interact with the API using a web interface, which allows adding, removing, and updating streams, as well as downloading the last 40 music recognition results. (Please set the callback URL to https://audd.tech/empty/ if you don't have a server for callbacks).

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.

If you change the limit later, the unused amount of 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

(Please set the callback URL to https://audd.tech/empty/ if you don't have a server for callbacks).

post
3. Add the streams​

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

Add the streams using the addStream API method. By default, we will send new results after songs end playing. See the callbacks parameter description if you want to get the results when songs start playing.

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
POSSIBLY REQUIRED
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 starts playing (instead of when it finishes). Note that with callbacks=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​

Using callbacks​

Receiving the results in callbacks is the recommended method.
Callbacks will be sent to the specified URL as a JSON structure in the POST payload. The format is below.
You'll receive callbacks with results and with notifications.

  • The results contain the identified 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 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 in 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).

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

LongPoll​

You can use long polling instead of or together with receiving callbacks. See the LongPoll section for more info.

For it to work, if you're not planning to receive callbacks, set the callback URL to https://audd.tech/empty/ using the web interface. (You have to have some callback URL, or you won't be able to retrieve results using long polling.)

Manually download results​

This is not recommended, but the last 40 results should usually be available for download using our web stream management interface.

For this to work, if you're not planning to receive callbacks, set the callback URL to https://audd.tech/empty/ using the web interface.

What else can I do?​

We have additional methods to manage 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

LongPoll​

In addition to callbacks, you can use the HTTP longpolling to get the new results from any number of clients without having to spin up a web server or have a static IP.

Please use the longpolling after setting a working callback URL using the setCallbackUrl method; ensure that the callback URL response with the 200 OK HTTP status when receives the callbacks. If you don't have a server that can return 200 OK to POST requests, use https://audd.tech/empty/.

The long poll address is https://api.audd.io/longpoll/. As the subscription category, use the longpoll_category field from the /getStreams response, or calculate the first nine symbols of MD5(MD5("your api_token")+"radio_id"). You can share the categories with your clients or users, but please don't include your API tokens in the client-side software.

If you're making the long poll requests manually, here's an example of a LongPoll URL: https://api.audd.io/longpoll/?category=92b1cc7f0&timeout=50&since_time=1652123144400. When you receive a response containing the timestamp field, use it as the updated since_time for the new request.

We've implemented long polling clients in our Golang library and Twitch extension that's written in JS.

HTML Widget

You can also use our widget, https://widget.audd.tech/?ch=-92b1cc7f0&background&history&shadow. It's based on the Twitch extension's frontend and shows the last recognized song as well as the history (if you want it to show the history). Use the longpoll category with "-" before it as the ch URL parameter. You can also use the URL parameters to get the look you want, e.g. https://widget.audd.tech/?ch=-92b1cc7f0&black-font.

You can disable the Long Poll for your streams by adding "disable-lastsong=true" as a parameter your callback URL (e.g. add ?disable-lastsong=true or &disable-lastsong=true to the URL).

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.

Support​

Reach out to api@audd.io if you have any questions or need any help.