Controlling BTplay

From Chumby Wiki
Revision as of 11:39, 30 August 2010 by Hgroover (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

BTPlay is an external music player that is used by the chumby Control Panel to play audio files and streams asynchronously. It is implemented as a persistent daemon that is controlled by a UNIX pipe, typically from the Flash Lite Player, or through some stub applications. When invoked as btplayd, it remains resident as a daemon; once the daemon is running, it can be controlled by running btplay. Note that the information on this page does not apply to the Sony Dash.

Flash Interface

Several ASnative() calls have been added to the Flash Lite implementation to control this daemon. These calls are only available to movies run locally (via -i) - they cannot be called from widgets.


_PlayAudio = ASnative(5,151);


_PlayLoopCount = ASnative(5,146);

Sets the number of times the next file provided to PlayAudio will play.


_StopAudio = ASnative(5,134);


_PauseAudio = ASnative(5,132);


_ResumeAudio = ASnative(5,133);


_PlayerState = ASnative(5,131);
playerState = _PlayerState();

returns -1 if player daemon not running, 0 if paused, 2 if playing a track


_SongAttributes = ASnative(5,135);
attrs = _SongAttributes();

returns information about the currently playing track, typically MP3 tags and other metadata


The Flash Player has a simple playlist built in, managed with ASnative calls.

_AddToPlaylist = ASnative(5,149);
_AddToPlaylist("audio/mpeg","/mnt/usb/3.mp3", "/mnt/usb/4.mp3", "/mnt/usb/5.mp3" );

adds the paths to the end of the playlist. The first argument should be the mimetype of the files, or "*" for autodetect.


_ResetPlaylist = ASnative(5,150);

clears the playlist


_SkipToNext = ASnative(5,147);

skip to the next item in the playlist

plays the next item in the playlist.


_SkipToPrev = ASnative(5,148);

skip to the previous item in the playlist

Pipe Interface

btplay and btplayd are symlink aliases for the same program. Normally at startup btplayd is invoked, and remains resident, listening for commands on /tmp/.btplay-cmdin and writing command feedback to /tmp/.btplay-cmdout

flashplayer uses the btplay front-end interface (via service_control inetradio) to invoke streaming and local music sources.

This page documents the client-server interface used internally between the client instance (btplay) and the server instance (btplayd).


On startup btplayd creates a named pipe for command input. The default name is /tmp/.btplay-cmdin

The default output command pipe (used for feedback from commands) is /tmp/.btplay-cmdout

With the exception of playlist, all command verbs (listed below) consist of a single line. Every command verb will have a single-line reply of 256 characters or less consisting of OK <serial> <msg> or ERR <serial> <msg>

Command response should take place immediately. No response indicates a hung btplayd. <serial> is a request serial number optionally issued with each command. For backwards compatibility all commands are accepted without a serial number, but if no serial number is specified 0 will be used in the reply.

There are some limitations built into the interface as it stands currently:

  • No single line may be longer than 1024 characters
  • The total contents of a playlist may not exceed 1024 characters. Multiple playlists may be submitted.
  • A single playlist may not have more than 256 entries.


Command verbs should be preceded with [serial] where serial is a nonzero positive integer which is unique for the command pipe. This request serial number will be issued back with the OK or ERR response. Command verbs are:

Skip to next song in playlist

Skip to previous song in playlist

play [type|*] [song file]
If song file is specified, cancel any current playback and begin playing song.
If no song file, begin playback of current playlist. When playback is finished,
playback will resume with next song in queue (if queue specified)

type is an optional mime type. btplay can normally figure out the type unless 
the server is really lame and sends something like application/octet-stream 
for the mime type.

playnow [type|*] [song file]
Insert specified song into queue and begin playing immediately. When playback
is finished, song will still be in queue and playback will continue with the next
song in queue.

playnext [type|*] [song file]
Same as play except that specified playback will begin after current song
finishes. If no song is playing, this has the same effect as play. Typically
used after loading a new playlist.

option songloop <count>
Loops playback of the next song (either via play or when the next playlist
entry begins) for count iterations. If count is 0, loops perpetually. Default
is 1.

option listloop <count>
Loops playback of current playlist. Default is 1, 0 to loop perpetually.

playlist length
Read length lines after this one containing playlist entries in the form
type|* resource_uri

Clear all playlist entries

skip offset
Not implemented in current releases

Pause playback. Remember offset in song and current playlist position.

Respond immediately with OK if alive. Used to tell if btplay is stuck.

Resume playback if paused, otherwise no effect

Stop playing current song. Forget current position

Stop playing any songs and exit immediately

flashplayer startup
Informative. Tells btplay that flashplayer has just started up

flashplayer exit
Informative. Tells btplay that flashplayer is exiting

dump <entity>
Debug dump of specified entity. Valid are:
	playlist	Entire playlist

debug [level]
If level is specified, set new debug level. Echoes debug level in response.

  • Revised 30-Aug-2010: removed unimplemented save and load