Difference between revisions of "Controlling BTplay"
(New page: 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 ...) |
|||
(8 intermediate revisions by 2 users not shown) | |||
Line 1: | Line 1: | ||
− | 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. | + | 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 <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. | ||
+ | |||
+ | ==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: | ||
+ | |||
+ | <pre> | ||
+ | |||
+ | 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 <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 | ||
+ | |||
+ | 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 <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. | ||
+ | |||
+ | </pre> | ||
+ | |||
+ | * Revised 30-Aug-2010: removed unimplemented save and load |
Latest revision as of 11:39, 30 August 2010
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.
Contents
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 <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.
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 <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 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 <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