[1;34mXMMSCTRL version 1.8[0;0m (C) Alexandre David <adavid@cs.aau.dk>.
'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:
 [1;34mlaunch[0;0m : launch a xmms instance if none is running
 [1;34mnot[0;0m : negate the next condition test
 [1;34mclear[0;0m : clear the play list.
 [1;34mcur[0;0m : print the current mp3 song file.
 [1;34meject[0;0m : open xmms "Load file(s)" dialog window.
 [1;34mgetlength[0;0m : print the length of the play list.
 [1;34mgetpos[0;0m : print the current mp3 song position in the play list.
 [1;34mgettime[0;0m : print the current song's playback time in seconds.
 [1;34mgetvol[0;0m : print the master volume value.
 [1;34mhelp[0;0m : print this help message.
 [1;34mnext[0;0m : xmms next song command, go to the next song.
 [1;34mpause[0;0m : xmms pause command, pause the playing song.
 [1;34mplay[0;0m : xmms play command, play the current song.
 [1;34mplaylist[0;0m : print the play list songs.
 [1;34mplayfiles[0;0m : print the play list files.
 [1;34mpref[0;0m : open xmms preference window (as Ctrl-P).
 [1;34mprev[0;0m : xmms previous song command, go to the previous song.
 [1;34mprevious[0;0m : go to the previous song and wrap round to last if position is first.
 [1;34mremove[0;0m : xmms removes mp3 currently playing from playlist.
 [1;34mrepeat[0;0m : toggle xmms repeat flag.
 [1;34mshuffle[0;0m : toggle xmms shuffle flag.
 [1;34mstop[0;0m : xmms stop command, stop playing.
 [1;34mtitle[0;0m : print the current mp3 song title.
 [1;34muniq[0;0m : remove duplicate files from the playlist.
 [1;34mquit[0;0m : terminate xmms.
 [1;34m--help[0;0m : print this help message.

The flag setting commands are used with 0 or 1:
 [1;34mequalizer[0;0m : hide/show xmms equalizer window.
 [1;34mmain[0;0m : hide/show xmms main window.
 [1;34mplay_list[0;0m : hide/show xmms playing list window.

The condition testing commands are:
 [1;34mpaused[0;0m : returns OK if xmms is paused.
 [1;34mplaying[0;0m : returns OK if xmms is playing a song.
 [1;34mis_equalizer[0;0m : returns OK if xmms has its equalizer window open.
 [1;34mis_main[0;0m : returns OK if xmms has its main window open.
 [1;34mis_play_list[0;0m : returns OK if xmms has its playing list window open.
 [1;34mis_stream[0;0m : returns OK if xmms is playing a stream (http://somewhere).
 [1;34mrunning[0;0m : returns OK if xmms is running.

The other specific commands are:
 [1;34msession number[0;0m : use the session number 'number', xmmsctrl looks
                  automatically for the first working session.

 [1;34mdir <name>[0;0m : clear the play list and load the directory/file
              <name> as the play list. This works with devices
              like /dev/cdrom to handle music CDs.

 [1;34mtime [+|-|/]seconds[0;0m :
	 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.

 [1;34mtrack <n>[0;0m  : set the n'th track in the play list as the current track.
[1;34m track last[0;0m : set the last track in the play list as the current track.

 [1;34mvol [+|-]percent[0;0m, 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.

 [1;34mprint <string>[0;0m : general formatted print, similar to printf. The codes are:
	%n : new line,
	%t : tab,
	%F : current filename,
	%T : current title,
	%P : current position,
	%s : playback time in sec,
	%m : playback time in min:sec,
	%S : song length in sec,
	%M : song length in min:sec,
	%v : master volume,
	%l : playlist length,
	%p : playback time in percent,
	%(x): where x is a decimal number, evalutation string x depending if the current
	printed song == (eq) or != (neq) the currently played song (see playlist2html.sh).
	In addition, if the code is preceded by a number (say i), then the song i is
	taken instead of the current one. If * is used then print evaluates on all the
	songs. Examples: "%*P: %*T (%*M)%n" prints the whole playlist,
	"%T (%m:%M)%n" prints only the current song, and "%3F%n" prints the 3rd file.

 [1;34meq[0;0m : add evaluation string for the case treated song == current played song.

 [1;34mneq[0;0m : add evaluation string for the case treated song != current played song.

 [1;34m+file <file>[0;0m : add the file/directory to the playlist without clearing the playlist.
	You can use 'xmmsctrl +file something uniq' or 'xmmsctrl +file BEGIN dir1 dir2 END uniq' for
	a cleaner result.

 [1;34m-file <file>[0;0m : remove the file/directory from the playlist. You can use
	'xmmsctrl uniq -file something' for a cleaner result.

Except for 'session', these command now support a
batch mode. You can give a list of arguments beginning
with BEGIN and ending with END, e.g.,
 	xmmsctrl +file BEGIN dir1 dir2 song1 song2 END

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
