Controlling BTplay

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
_PlayAudio = ASnative(5,151); _PlayAudio('/mnt/usb/somemusicfile.mp3');

PlayLoopCount
_PlayLoopCount = ASnative(5,146); _PlayLoopCount(10);

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

StopAudio
_StopAudio = ASnative(5,134); _StopAudio;

PauseAudio
_PauseAudio = ASnative(5,132); _PauseAudio;

ResumeAudio
_ResumeAudio = ASnative(5,133); _ResumeAudio;

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

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

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

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

AddToPlaylist
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
_ResetPlaylist = ASnative(5,150); _ResetPlaylist;

clears the playlist

SkipToNext
_SkipToNext = ASnative(5,147); _SkipToNext;

skip to the next item in the playlist

plays the next item in the playlist.

SkipToPrev
_SkipToPrev = ASnative(5,148); _SkipToPrev;

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).

Interface
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 or ERR

Command response should take place immediately. No response indicates a hung btplayd. 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.

Verbs
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:

next Skip to next song in playlist

prev 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 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 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

resetplaylist Clear all playlist entries

skip offset Not implemented in current releases

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

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

resume Resume playback if paused, otherwise no effect

stop Stop playing current song. Forget current position

quit 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 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