The most important and frequently accessed pieces of information that AzuraCast stores are all served as part of a single group of data, which we refer to as the "Now Playing" data.
This data includes:
Here's a real-world example of the Now Playing API's return data from the AzuraCast demo page.
AzuraCast always serves this data in the exact same format, regardless of whether you're broadcasting locally or remotely, or whether you're using Icecast or SHOUTcast.
Because of how valuable this information is, we serve it in a number of ways depending on whether performance or flexibility is your main concern.
This is the "Now Playing" API endpoint listed as part of the API documentation. On any installation, an array of now-playing data for all public stations is available at:
http://your-azuracast-site.example.com/api/nowplaying
The now-playing data for a specific station is available at:
http://your-azuracast-site.example.com/api/nowplaying/station_shortcode
...replacing station_shortcode with either the station's abbreviated name (i.e. azuratest_radio for "AzuraTest Radio") or the numeric ID of the station (visible in the URL when managing the station in AzuraCast).
current_song are automatically updated to reflect their current values (in seconds) at the moment you make the API request.Using the jQuery JavaScript library, an example implementation might look like:
var nowPlayingTimeout;
var nowPlaying;
function loadNowPlaying() {
$.ajax({
cache: false,
dataType: "json",
url: 'http://your-azuracast-site.example.com/api/nowplaying/station_shortcode',
success: function(np) {
// Do something with the Now Playing data.
nowPlaying = np;
nowPlayingTimeout = setTimeout(loadNowPlaying, 15000);
}
}).fail(function() {
nowPlayingTimeout = setTimeout(loadNowPlaying, 30000);
});
}
$(function() {
loadNowPlaying();
});
Using the Axios HTTP client library, an example implementation might look like:
var nowPlaying;
var nowPlayingTimeout;
function loadNowPlaying() {
axios.get('http://your-azuracast-site.example.com/api/nowplaying/station_shortcode').then((response) => {
// Do something with the Now Playing data.
nowPlaying = response.data;
}).catch((error) => {
console.error(error);
}).then(() => {
clearTimeout(nowPlayingTimeout);
nowPlayingTimeout = setTimeout(checkNowPlaying, 15000);
});
}
loadNowPlaying();
If your application is written in PHP, you can use the Composer package manager to install our PHP API Client, which has full support for the Now Playing API endpoints.
AzuraCast also writes its "Now Playing" API endpoint data to a static JSON file, which contains the same exact data as the standard API endpoint, but for a single station.
The Static Now Playing JSON file for a given station is available at:
http://your-azuracast-site.example.com/api/nowplaying_static/station_shortcode.json
...replacing station_shortcode with the station's abbreviated name (i.e. azuratest_radio for "AzuraTest Radio").
played_at timestamp.Implementations of this method look exactly the same as for the Standard Now Playing API (above), except with the URL updated to the static URL for the station.
We deliver a high-performance (low-latency and low server CPU burden) Now Playing feed thanks to a realtime messaging library called Centrifugo. Using this connection method, each listener gets immediate track updates while only maintaining a single lightweight HTTP connection.
Now Playing updates are delivered as unidirectional messages via Websocket, Server-Sent Events (SSE) or Long Polling web streams.
The URL for websocket connections is:
wss://your-azuracast-url/api/live/nowplaying/websocket
Upon connection, you should send a connection string in the form of a JSON request:
{ "subs": { "station:your_station_name": {} }}
Replacing your_station_name with your station's URL stub or short name.
You will start to receive a feed of empty pings ({}) and Now Playing updates. You can identify Now Playing updates as they will have, in their parsed JSON, pub.data.np.
An example JavaScript implementation is below:
let socket = new WebSocket("wss://your-azuracast-url/api/live/nowplaying/websocket");
socket.onopen = function(e) {
socket.send(JSON.stringify({
"subs": {
"station:azuratest_radio": {}
}
});
};
socket.onmessage = function(event) {
const data = JSON.parse(event.data);
const np = data?.pub?.data?.np || null;
if (np) {
// Process Now Playing data in `np` var.
}
};
The URL for SSE connections is:
https://your-azuracast-url/api/live/nowplaying/sse?cf_connect=TOKEN
Where the cf_connect URL parameter is the same connection token as the first message in the Websocket example.
An example JavaScript implementation is below:
const sseUri = "https://your-azuracast-url/api/live/nowplaying/sse?cf_connect="+JSON.stringify({
"subs": {
"station:azuratest_radio": {}
}
});
let sse = new EventSource(sseUri);
sse.onmessage = (e) => {
const data = JSON.parse(e.data);
const np = data?.pub?.data?.np || null;
if (np) {
// Handle Now Playing data update as `np` variable.
}
};
The URL for HTTP Stream connections is:
https://your-azuracast-url/api/live/nowplaying/http_stream?cf_connect=TOKEN
Where the cf_connect URL parameter is the same connection token as the first message in the Websocket example.
This method uses the Nchan plugin for Nginx to handle connections to browsers and relays a single update from AzuraCast immediately to a large number of recipients. Because it's an Nginx plugin, it's optimized for high performance and can handle many hundreds of thousands of concurrent users.
If this method is available, AzuraCast will automatically use it for all of its public players.
The Websocket/EventSource API URL for a given station is available at:
http://your-azuracast-site.example.com/api/live/nowplaying/station_shortcode
...replacing station_shortcode with the station's abbreviated name (i.e. azuratest_radio for "AzuraTest Radio").
played_at timestamp.To use this API method on a web site, first make sure the Nchan Subscriber JavaScript library is loaded. This library can also be loaded via the NPM package manager using the command npm i nchan.
An example implementation using the Nchan Subscriber library might look like:
var sub = new NchanSubscriber('http://your-azuracast-site.example.com/api/live/nowplaying/station_shortcode');
var nowPlaying;
sub.on("message", function(message, message_metadata) {
// Do something with the Now Playing data.
nowPlaying = JSON.parse(message);
});
sub.start();