XMMSCTRL version 1.6, main author Alexandre David <adavid@docs.uu.se>:
xmmsctrl is a simple tool designed to be used at the shell level,
typically in a small shell script associated to a keyboard shortcut. There
are 4 different command types:
- simple commands, e.g. "xmmsctrl play", which perform a simple task
- commands with a flag argument, e.g. "xmmsctrl main 1", which set
  a particular state
- condition testing, e.g. "xmmsctrl playing", which can be used in
  if statements in shells. Something to notice: this was designed to be
  used simply, which is, directly in if statements: if <command>; then
  <command>; else <command>; fi. There you put directly "xmmsctrl playing"
  to test if xmms is playing. Notice how the if statement works: if the
  command succeeds, it returns a 0, which means OK, otherwise it returns
  an error code.
- more specific commands with particular arguments

The simple commands are
 launch : launch a xmms instance if none is running
 not : negate the next condition test
 cur : print the current mp3 song file
 eject : open xmms "Load file(s)" dialog window
 getpos : print the current mp3 song position in the play list
 gettime : print the current song's playback time in seconds
 getvol : print the master volume value
 help : print this help message
 next : xmms next song command, go to the next song
 pause : xmms pause command, pause the playing song
 play : xmms play command, play the current song
 playlist : print the play list songs
 playfiles : print the play list files
 pref : open xmms preference window (as Ctrl-P)
 prev : xmms previous song command, go to the previous song
 previous : go to the previous song and wrap round to last if position is first
 remove : xmms removes mp3 currently playing from playlist
 repeat : toggle xmms repeat flag
 shuffle : toggle xmms shuffle flag
 stop : xmms stop command, stop playing
 title : print the current mp3 song title
 quit : terminate xmms
 --help : print this help message

The flag setting commands are used with 0 or 1
 equalizer : hide/show xmms equalizer window
 main : hide/show xmms main window
 play_list : hide/show xmms playing list window

The condition testing commands are
 paused : returns OK if xmms is paused
 playing : returns OK if xmms is playing a song
 is_equalizer : returns OK if xmms has its equalizer window open
 is_main : returns OK if xmms has its main window open
 is_play_list : returns OK if xmms has its playing list window open
 is_stream : returns OK if xmms is playing a stream (http://somewhere)
 running : returns OK if xmms is running

The other specific commands are
 session number : use the session number 'number', xmmsctrl looks
                  automatically for the first working session.

 dir <name> : clear the play list and load the (hopefully) directory
              <name> as the play list. This should work with devices
              like /dev/cdrom to handle music CDs.

 time [+|-|/]seconds :
	 seconds : set the playback time to seconds
	+seconds : advance the playback by seconds
	-seconds : rewind the playback by seconds
	/seconds : set the playback time to seconds from the end
	           of the song
    examples : xmmsctrl time 30, xmmsctrl time +10

 track <n> : set the n'th track in the play list as the current track

 vol [+|-]percent, with the following effects
	 percent : set the volume to percent
	+percent : increase the volume with percent
	-percent : decrease the volume with percent
    examples : xmmsctrl vol 40, xmmsctrl vol +5, xmmsctrl vol -5


Examples of shell scripts to define simple functions:
 Play/Stop :
 	sh -c "if xmmsctrl playing;\
 	       then xmmsctrl stop;\
 	       else xmmsctrl play; fi"
 Play/Pause :
 	sh -c "if xmmsctrl playing;\
 	       then xmmsctrl pause;\
 	       else xmmsctrl play; fi"
(with xmmsctrl in your path). See more examples in the bindings
for twm in the distribution.
Have fun. Alexandre
