Okay. Here we go.

Having a nice front end for xmmsctrl could turn out to be the best way to go that's easy enough to finish in creating an awesome release.


'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
clear : clear the play list.
cur : print the current mp3 song file.
eject : open xmms "Load file(s)" dialog window.
getlength : print the length of the play list.
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.
uniq : remove duplicate files from the playlist.
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 directory/file
<name> as the play list. This works 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.
track last : set the last 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.

print <string> : 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.

eq : add evaluation string for the case treated song == current played song.
neq : add evaluation string for the case treated song != current played song.

+file <file> : 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.

-file <file> : 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.