Remote Control API

Click to Display Table of Contents

Navigation:  Operation >

Remote Control API

You can control RadioBOSS remotely by using its Remote Control API.

 

Enable and configure this feature via the Settings window: Configure Remote Control API.

 

HTTP remote control API reference

 

Note: When generating a request string, use one of the URL Encoding functions for parameters. For example, use urlencode (http://www.php.net/manual/en/function.urlencode.php) for PHP. Requests should be sent in UTF8 encoding.

 

I. Executing a command. You can use the same commands as in the scheduler. Here’s the list of commands available: Scheduler commands

Commands that can not be used from the API: getrandomplaylist, getfile, playrequestedsong

 

Syntax:

http://IP:Port/?pass=PASSWORD&cmd=COMMAND

(substitute “COMMAND” and “PASSWORD” accordingly)

 

Example 1: Play the next track (command: next)

http://127.0.0.1:9001/?pass=WxPe2JXh&cmd=next

 

Example 2: Play the first track in the playlist (command: “play 1”)

http://127.0.0.1:9001/?pass=WxPe2JXh&cmd=play%201

 

II. Performing an action

 

Syntax:

http://IP:Port/?pass=PASSWORD&action=ACTION

(substitute “ACTION” and “PASSWORD” accordingly)

 

Possible ACTION values:

 

playbackinfo

get playback information

Returns an XML containing the current and next track information, and playback position, state and some other information.

 

Example

http://127.0.0.1:9001/?pass=WxPe2JXh&action=playbackinfo

 

An example of data returned: show

inserttrack

insert a track into the playlist

Parameters

"filename" — local file name

"pos" — a position in the playlist where track should be inserted (1 ... N).

Other possible values:

 -1: insert into the end of the playlist

 -2: insert after the playing track

-3: insert after scheduled tracks

"streamingtitle" — set broadcasting title for the inserted item

 

Example

Insert the track “D:\music\track.mp3”

http://127.0.0.1:9001/?pass=WxPe2JXh&action=inserttrack&filename=D%3A%5Cmusic%5Ctrack.mp3&pos=-2

 

Returns OK if successful

library

download a music library file (xml)

Parameters

"filename" — music library name

 

Returns: music library contents

 

Example

http://127.0.0.1:9001/?pass=WxPe2JXh&action=library&filename=Base

library_edit

edit music library

Parameters

"type" — request type:

odelete - delete music track from a music library

"library" — music library name

"fn" — path to music file

 

Returns OK if successful

 

Example

http://127.0.0.1:9001/?pass=WxPe2JXh&action=library_edit&type=delete&library=Base&fn=C%3A%5CMusic%5CTrack01.mp3

trackartwork

download artwork for the current track

Returns: artwork for the currently playing track (or nothing if there is no artwork)

nexttrackartwork

download artwork for the next track

Returns: artwork for the next track (or nothing if there is no artwork)

setnexttrack

set the next track

Parameters

"pos" — the position of a track in the playlist, which will be selected as a next track (1 ... N)

 

Example

Set the first track in the playlist to be played next.

http://127.0.0.1:9001/?pass=WxPe2JXh&action=setnexttrack&pos=1

 

Returns OK if successful

delete

delete a track from playlist

Parameters

"pos" — the position of a track in the playlist, which will be deleted (1 ... N). Multiple values can be specified, comma separated, e.g. 1,3,10.

 

Example

Delete second track in the playlist

http://127.0.0.1:9001/?pass=WxPe2JXh&action=delete&pos=2

 

Returns OK if successful

move

move a track to another position in the playlist

Parameters

"pos1" — original track position

"pos2" — new track position

 

Returns OK if successful

mic

turn microphone on and off or query microphone status

Parameters

"on" - 0 to turn microphone off, 1 to turn on. If the parameter is omitted, returns microphone status, if parameter presents, returns OK if successful.

0 - off

1 - on

 

Example (turn microphone on):

http://127.0.0.1:9001/?pass=WxPe2JXh&action=mic&on=1

 

Example (query status):

http://127.0.0.1:9001/?pass=WxPe2JXh&action=mic

getplaylist

get playlist contents

 

deprecated, please use getplaylist2 instead

Returns: an XML containing the playlist contents. This function reads tag information and can be slow for large playlists.

 

Parameters:

(optional) "from", "to" - if set, get tracks from position from to position to (inclusive), instead of retrieving the whole playlist.

 

An example of data returned: show

getplaylist2

get playlist contents

Returns: an XML containing the playlist contents.

 

Parameters

(optional) "cnt" - max number of tracks to return, 0 = return all tracks

 

An example of data returned: show

trackinfo

get track information

Parameters

"pos" — the position of a track in the playlist

 

Example

http://127.0.0.1:9001/?pass=WxPe2JXh&action=trackinfo&pos=2

 

An example of data returned: show

songrequest

add song request

Parameters

"filename" - file name of a requested song (full path)

"message" - optional, message from a user who requested a song

 

To manually view the list of requested songs, in the menu click View->Song Requests...

To automatically play the requested songs use the playrequestedsong scheduler command.

 

Returns OK if successful

songrequestclear

clear the requested songs list

Clears the requested songs list.

 

Returns OK if successful

songrequestlist

get requested songs list

Returns: an XML with requested songs list. Show example

encoderstatus

get status of broadcasting encoders

Returns: an XML containing with encoder status information. Show example

streamarchivestatus

get stream archive status

Returns Stream Archive status

0 - off

1 - on

schedule

control scheduled events

Parameters

"type" - the request type, one of:

olist - list events (returns all events in XML format)

odelete - delete an event

orun - run event

oadd - add new event

oupdate - edit event

ostate - turn scheduler on or off or retrieve scheduler state

"event" - XML event data (when type is "update" or "add")

"id" - event ID, you get the event ID when you perform "list" query (used when type is "delete", "run", or "update")

"set" - on or off (when type is "state"), if parameter is omitted - returns current scheduler state

"skipnext" - set to 1 to skip the scheduled event launch (when type is "run").

 

Returns

for delete, run, add, update requests: OK if successful

for state request: on - schedule enabled, off - scheduler disabled

 

Event list XML example

 

Explanation of some XML event attributes

Imm - Run scheduled launch without waiting for current track to finish

bRepeat - Repeat every

Enqueue - Queue after the scheduled tracks

DelPrev - Replace scheduled tracks

Above - Overlay playback

MuteLev - Playlist level when overlay event is playing

PausePlaylist - Pause the playlist while overlay event is playing

getlastplayed

get list of last played tracks

Parameters

"filter" = 1 - (optional) exclude tracks whose titles have not been sent to the server

 

Returns: an XML containing information about recently played tracks. Show example

readtag

read track tag information

Parameters

"fn" - file name

"artwork" (optional) - 1 to include artwork in response (base64-encoded)

 

Example

http://127.0.0.1:9001/?pass=WxPe2JXh&action=readtag&fn=D:\Metallica\Metallica%20-%20Darkness.mp3&artwork=1

 

An example of data returned: show

writetag

write track tag information

Parameters

"fn" - file name

"data" - new tag data in XML format (same as returned by readtag).

 

Return value

OK if successful

Error with error message text on error

writeartwork

update artwork for a track

Parameters

"fn" - file name

"artwork" - artwork data, base-64 encoded

 

Request must be made using POST method, content type application/x-www-form-urlencoded

 

Request example using PHP: show

 

Return value

OK if successful

Error with error message text on error

setcasttitle

set new title on streaming servers

Parameters

"title" - new cast title

 

Return value

OK if successful

status

Returns: an XML containing RadioBOSS version and uptime in seconds.

 

An example of data returned: show

getencoder

get encoder configuration

Parameters

"id" - encoder ID (0..N), 0 - first encoder in the list

 

Returns: XML data with encoder configuration

 

An example of data returned: show

setencoder

edit encoder configuration

Parameters

"id" - encoder ID (0..N), 0 - first encoder in the list, -1 - add new encoder

"data" - encoder data in XML format (as returned by getencoder).

 

Return value

OK if successful

deleteencoder

delete encoder

Parameters

"id" - encoder ID (0..N), 0 - first encoder in the list

 

Return value

OK if successful