Information on the new Scripts controller
=========================================

The Scripts controller relays UI-related messages to any
script that you add to its "playlist". The protocol command
and any parameters are sent as command-line parameters to
the active script.

For example, if the active script is "YourScript" and you
press Pause in the Bemused client, the following command
will be executed:

   /path/to/yourscripts/YourScript PAUS

Likewise, if you turn on Shuffle in the client, 

   /path/to/yourscripts/YourScript SHFL 1


Supported commands
==================

Of the protocol commands listed at

  http://www.compsoc.man.ac.uk/~ashley/bemused/BemusedProtocol.html

the following commands are relayed to your script:

  DINF                  <= Control/Track info 
  FADE                  <= See "When stopping" setting
 *FULL                  <= Control/Full screen
  FFWD                  <= Hold down Next for 2+ seconds
  INF0                  <= Routinely called
  LADD /path/to/file    <= Add to playlist
  NEXT
  PAUS
  PLAY /path/to/file    <= See "Selecting an item" setting
  PLST                  <= Playlist tab
  PREV
  REPT 0|1
  RMAL                  <= Playlist/Remove all
  RWND                  <= Hold down Previous for 2+ seconds
  SHFL 0|1
  STEN                  <= See "When stopping" setting
  SLCT playlist_pos     <= Playlist, select item; 0-based
  STOP
  STRT
  VOLM volume           <= 0 to 255
**GVOL
**PLEN

 * FULL is a new command sent by the 1.71+ client when the
  "Control/Full screen" menu option is selected
** GVOL and PLEN are new in 1.73

You may choose to not implement any of the above commands.


Expected script output
======================

DINF
----
If your script can return bitrate, sample rate, and channel
rate info, it should give the following output:

bitrate
sampleRate
channels

e.g.

128    <= kbps
44     <= kHz
2      <= 1=mono 2=stereo, etc.


PLST
----
If your script manages a playlist, it should output the list
in the following format:

selected_position           <= zero based
playlist_entry_0
playlist_entry_1
..

e.g.

1
/path/to/Some Music.mpg
/path/to/Other Music.mpg    <= this is selected
/path/to/My Ogg File.ogg

If the script manages a playlist, but it is currently empty,
output a "0". If it doesn't, don't output anything at all.


INFO
----

Likewise, if your script can return information about the
currently playing file, it should respond to "INFO" as
follows:

length           <= in seconds
currentTime      <= in seconds
playState        <= 0=stopped, 1=playing, 3=paused
repeat           <= 0 or 1
shuffle          <= 0 or 1
trackName        <= name to display on client

Please note that the trackName will consistently show up
correctly in the client only if you have the "Use ID3 tags"
option set to "Yes".


GVOL
----
Return the current volume, from 0 to 255


PLEN
----
Return the playlist length

All other commands don't require any output.


Using the Scripts controller
============================

a. Upon connection, add an alias (e.g. Scripts) to your KDE
   Bemused Server configuration. Point it to the location of
   your scripts.
b. In the phone, refresh the list and select "#scripts" at
   the root directory.
c. Browse to your scripts alias and add some scripts to your
   playlist.
d. Go to the playlist and select a script
e. The controls will now relay events to the script you just
   selected.

If your active script does not have a playlist, the client's
Playlist will always show the list of scripts. Otherwise, you
will get your custom playlist like so (after a refresh):

  [up]
  Some Music
  Other Music
  My Ogg File

Selecting "My Ogg File" in this example will call your
script with SLCT 2 as parameters.

To go back to the list of scripts, select "[up]" and refresh
the playlist.

Enjoy!


Alex Ibrado <alex@kdex.org>

