adblockradio-sdk

Adblock Radio client SDK

This is a JS Node & browser library to connect to adblockradio.com API servers. It provides live information about the nature of broadcast contents: either ads, talk or music. It also gives the average volume gain of radio streams so that channel-hopping between stations does not lead to volume variations.

Installation

$ npm install

Usage in browser:

The demo script demo.js requires libabr.js. To test it in a browser, you need to use browserify.

$ browserify demo.js -o bundle.js

or

$ npm run build

Then launch a local web server at http://localhost:5000:

$ serve -s

The demo has no UI, everything happens in the web console (F12 to display it in Firefox & Chrome).

Usage in Node:

Put a valid token in a token file. Then:

$ nodejs demo_node.js

How to get an API token

A token is required to use this API. To get one:

• register on https://www.adblockradio.com/player with a valid email, if not already done.
• watch your inbox for the confirmation email (it may not arrive immediately).
• the email contains a link to open the Adblock Radio player, of the form https://www.adblockradio.com/player/?t=redactedtokenblahblahcopypasteme&lang=fr
• with the example link above, the token would be "redactedtokenblahblahcopypasteme".

Documentation

The workflow is to call connectServer, then get the list of available streams with getSupportedRadios. You create a list of desired radios and send it to the server with sendPlaylist. You register to a prediction callback with setPredictionCallback. It will give you live updates about the streams status.

If a prediction is incorrect, use sendFlag to help improve the system. If you want to send some feedback with the API, use sendFeedback.

Demo usage

var abrsdk = require("./libabr.js")();
var token = "change me";

var onConnectionEvent = function(err, isConnected) {
	if (err) return console.log("connection error: " + err);
	if (!isConnected) return console.log("disconnected");

	abrsdk.getSupportedRadios(function(data) {
		console.log("supported radios: " + JSON.stringify(data));

		// here you can choose which stations you want to monitor.
		// you can monitor at most data.maxPlaylistLen stations at the same time.
		abrsdk.sendPlaylist(data.supportedRadios.slice(0, data.maxPlaylistLen), token, function(err, validatedPlaylist) {
			if (err) {
				console.log("sendPlaylist error = " + err);
			} else {
				// the validated playlist contains the list of monitored radios you have submitted,
				// minus the unavailable, invalid, or in excess station names.
				console.log("validated playlist = " + JSON.stringify(validatedPlaylist));
				abrsdk.setPredictionCallback(onPrediction);

				// to signal an incorrect radio status, send a flag and improve future predictions.
				//abrsdk.sendFlag(validatedPlaylist, token);

				// to send a feedback with the API, use abrsdk.sendFeedback(boolean isPositive, string feedback, string token)
				//abrsdk.sendFeedback(true, "test feedback", token);
			}
		});
	});
}

var onPrediction = function(predictions) {
	var status, volume;
	for (var i=0; i<predictions.radios.length; i++) {
		switch (predictions.status[i]) {
			case abrsdk.statusList.STATUS_AD: status = "AD"; break;
			case abrsdk.statusList.STATUS_SPEECH: status = "SPEECH"; break;
			case abrsdk.statusList.STATUS_MUSIC: status = "MUSIC"; break;
			default: status = "not available";
		}
		// normalized volume to apply to the audio tag to have similar loudness between channels
		volume = Math.pow(10, (Math.min(abrsdk.GAIN_REF-predictions.gain[i],0))/20);
		// you can now plug the data to your radio player.
		console.log(predictions.radios[i] + " has status " + status + " and volume " + Math.round(volume*100)/100);
	}
}

abrsdk.connectServer(onConnectionEvent);

Licence

MIT