Agent notes: streams and longpoll

You can use the AudD real-time music recognition service for audio streams to identify the songs that are being played on radio stations (or any other streams). You send us the URLs of the streams, we send you the recognition results in real time. Callbacks are the requests with recognition results our servers will send to your server. We recommend reviewing the following caveats before you write a streams integration.

1. The callback URL is set once for the whole account

Set the URL for callbacks using the setCallbackUrl API method. You can change the URL at any time using this method. The callbacks from all the streams will be sent to the specified URL as a JSON structure in the POST payload. There is no per-stream callback URL.

curl -s https://api.audd.io/setCallbackUrl/ \
  -F api_token=your-api-token \
  -F url=https://yourwebsite.com/callbacks_handler/

Don’t call setCallbackUrl on every addStream. The callback URL should be set once, at setup, otherwise every call will silently change the URL for all the existing streams, not only the new one. You can tell the streams apart by the radio_id in every callback: the integer you passed to addStream.

2. `addStream` accepts direct URLs and three shortcuts

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, Icecast, 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. So just send the shortcut, not the URL of the watch page.

3. Longpoll needs a callback URL too

In addition to callbacks, you can use HTTP longpoll (GET https://api.audd.io/longpoll/) to get the new results from any number of clients without having to spin up a web server or have a static IP. Longpoll only works after you set a working callback URL with setCallbackUrl; make sure it responds 200 OK to callbacks. If the callback URL isn’t set, longpoll returns no results and no error about it. Agents often conclude longpoll is broken because of this.

Please set the callback URL to an actual URL that can receive POST requests even if you want to use long polling only. If you don’t have one, set https://audd.tech/empty/ as the callback URL: it always responds with 200 OK.

# one-time setup, even for a longpoll-only integration
curl -s https://api.audd.io/setCallbackUrl/ \
  -F api_token=your-api-token \
  -F url=https://audd.tech/empty/

You can use long polling instead of or together with receiving callbacks. Longpoll is part of streams, not a standalone feature. So if the results are missing from your longpoll loop, check the callback URL first.

4. A callback body carries a result OR a notification, never both

You’ll receive callbacks with results and with notifications. A callback contains either a result or a notification, never both.

The results contain the recognized songs:

{ "status": "success", "result": { "artist": "...", "title": "...", "song_link": "..." } }

Notifications are information about problems with the streams, and they don’t contain songs:

{
  "status": "-",
  "notification": {
    "radio_id": 3,
    "stream_running": false,
    "notification_code": 650,
    "notification_message": "Recognition failed: can't connect to the audiostream"
  },
  "time": 1587939136
}

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 you must handle:

Code	Meaning
`0`	Everything’s fine
`650`	AudD can’t connect to the stream: the URL is dead or unreachable
`651`	AudD is connected, but receives only white noise and no music from the stream

Notifications also contain the time of sending.

Don’t assume every callback has a result. Check the notification field first: if it’s there, there is no result, and code that reads body["result"] in every callback will fail on every 650 or 651 notification. Report 650 (fix or re-set the stream URL) and 651 (the source isn’t playing music) instead of crashing.

If your server doesn’t respond with 200 OK or we can’t connect to it, we’ll put the callbacks in a queue and gradually send the backlog once your server is back online.

5. `callbacks="before"` sends callbacks when songs start

By default, we will send new results after songs end playing, with the total streamed time of the song. Send callbacks=before to addStream if you want to get the results when songs start playing.

curl -s https://api.audd.io/addStream/ \
  -F api_token=your-api-token \
  -F url=twitch:monstercat \
  -F callbacks=before

With callbacks=before, there is no total played time in the callbacks: the song hasn’t finished yet. Use before if you want to show the song that is playing now. Use the default if you want to know how long the songs played.

6. The test token doesn’t work with streams

Please note that all the streams API requests require the api_token from the Dashboard: api_token=test works only on the standard endpoint, with a limit of 10 requests per day, and the setCallbackUrl, addStream, and longpoll methods don’t accept it. There’s no test token for streams. Get your own token at dashboard.audd.io and send it as api_token in every request.

Related