Radio API for Developers | Radio.co

Introduction

The Radio.co API is advanced. Intended for developers and those with a technical background, only proceed if you feel comfortable customising website code.

Player Initialization Code

Paste the following code between the <HEAD></HEAD> tags on your web page.

<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script><script src="https://public.radio.co/playerapi/jquery.radiocoplayer.min.js"></script>

Paste the following code just after the closing </BODY> tag on your web page.

<script>$('.radioplayer').radiocoPlayer();</script>

Player Element

Define where you want the player to be located. Copy the following code, changing the URL (/streaming.radio.co) with your station's listen link.

<div class="radioplayer" data-src="<em><strong>https://streaming.radio.co/your_station/listen</strong></em>" data-autoplay="false" data-playbutton="true" data-volumeslider="true" data-elapsedtime="true" data-nowplaying="true" data-showplayer="true" data-volume="50" data-showartwork="false"></div>

Change the options which are prefixed with data- to customise how the player functions and appears - full list below.

Player Kit Examples

Download our project showcase folder to get a sense of how the player can be customised, including examples you can draw from for your website.

NBC player example.
NBC player example.

The files contain real working example players which can be manipulated and used in your own projects. Use the projects to get up and running quickly.

Player Options

The following options passed to the referenced HTML element on the web page control certain functionality and visibility of the player elements.

Stream URL

Your radio.co listen stream URL, required to set up the player.

data-src="https://streaming.radio.co/your_station/listen"

Auto Play

Automatically start playing the stream when the page loads.

data-autoplay="true|false"

Play / Pause Button

Display a play and pause button on the page.

data-playbutton="true|false"

Volume Slider

Display the volume slider on the page.

data-volumeslider="true|false"

Now Playing Info

Display the current now playing information of the station.

data-nowplaying="true|false"

Elapsed Stream Time

Display the current streaming total elapsed time on the page.

data-elapsedtime="true|false"

Show / Hide Player

Show or hide the radio player from the page, use in conjunction with displaying only certain elements.

data-showplayer="true|false"

Initial Volume

Set the initial volume of the stream when the page loads, requires a number between 1 and 100.

data-volume="0-100"

Current Song Artwork

Display just the artwork of the currently playing song (use with data-showplayer='false').

data-showartwork="true|false"

Player Image

Changes the square image on the player to a custom image source.

data-image="path/to/image.jpg"

Player Background Image

Sets a custom background image behind the player.

data-bg="path/to/image.jpg"

Player Methods

Methods which allow further control over your player's functionality and event mechanisms.

Load Player

Load the stream source into the player.

load(callback)

Play Station

Play the station's stream.

play(<em>callback</em>)

Play / Pause Station

Play or pause the stream, depending on its current state.

playToggle(<em>playCallback</em>, <em>pauseCallback</em>)

Player Event Watcher

Listener for the player events and execute a callback function.

event(event, <em>callback</em>)

Elapsed Time

Return the time elapsed time, then add true to the parameter to format the returned time.

getTime(isFormatted)

Stream State

0 → No information on the status

1 → Metadata for the stream is ready

2 → Data for the current playback position is available but not enough to play

3 → Data for the current and at least the next packet is available

4 → Enough data available to start playing

getStreamState()

Track Artwork

Get currently playing track artwork at a certain dimension and quality.

getArtwork(width, height, callback, resolution)

Volume Set

If a parameter is not present, the volume of the player will be returned. But if a parameter is present, the volume will be set to 0 (muted) - 100 (max)

volume(volume)

Mute Stream

Immediately mute the volume of the stream.

mute()

Boolean of Active / Inactive Stream

Returns the boolean on whether the stream is currently playing or not.

isPlaying()

Player Event Watcher

Listen to events triggered by the player and executes a callback function when the event occurs.

event(event, <em>callback</em>)

Station Loaded Previously

Return true or false to whether the station has already been loaded previously.

hasLoaded()

Player Events

Events can be caught using player.event('event_name', callback) to execute the callback when the event is triggered.

Audio Loaded Successfully

When the audio has been loaded to the player successfully.

audioLoaded

Time Change

Fired after each second passed while listening to the stream.

timeChanged

User Plays Stream

When the user plays the stream.

audioPlay

User Pauses Stream

When the user pauses the stream.

audioPause

Stream Dead

Not a valid source of stream.

invalidStream

Song Change

The current playing song has changed on the station.

songChanged

No Stream Info

No stream information was received.

streamInfoError

Player Example

var player = $('.radioplayer').radiocoplayer();
player.event('audioPlay', function(event){
 //perform action when audio is played here
});

Station Info

Check your station's info directly in your browser, or manipulate for your website or app. Swap out /your_station_id/, accessible in your station's dashboard URL.

Status

From track history to bitrate, display your station's complete status.

https://public.radio.co/stations/your_station_id/status

Name, Logo, & Stream URL

Display your station's name, logo, and stream URL.

https://public.radio.co/api/v2/your_station_id

Current Track

Display your station's current track, start time, and artwork.

https://public.radio.co/api/v2/your_station_id/track/current

Ready to get started?

Join over 50,000 broadcasters who chose Radio.co

Smiling radio broadcaster

Create your station in less than 60 seconds, for free.

Pick a plan, cancel anytime, no hardware needed

Smiling radio broadcaster

Take a tour with a radio specialist and ask us anything.

No obligation, just a helping hand