.\" It was generated by help2man 1.36.
.TH  XMMSCTRL "1" "August 2006"
.SH NAME
xmmsctrl \- small utility to control xmms from the command line
.SH USAGE
.B xmmsctrl
[command]
.SH DESCRIPTION
.B 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:
.PP
\- simple commands, e.g. "xmmsctrl play", which perform a simple task,
.PP
\- commands with a flag argument, e.g. "xmmsctrl main 1", which set a particular state,
.PP
\- condition testing, e.g. "xmmsctrl playing", which can be used in if statements in shells.
.IP
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,
.PP
\- more specific commands with particular arguments.
.SH COMMANDS
.SS "The simple commands are:"
.B launch
launch a xmms instance if none is running
.TP
.B not
negate the next condition test
.TP
.B clear
clear the play list
.TP
.B cur
print the current mp3 song file
.TP
.B eject
open xmms "Load file(s)" dialog window
.TP
.B getlength
print the length of the play list
.TP
.B getpos
print the current mp3 song position in the play list
.TP
.B gettime
print the current song's playback time in seconds
.TP
.B getvol
print the master volume value
.TP
.B help
print this help message
.TP
.B next
xmms next song command, go to the next song
.TP
.B pause
xmms pause command, pause the playing song
.TP
.B play
xmms play command, play the current song
.TP
.B playlist
print the play list songs
.TP
.B playfiles
print the play list files
.TP
.B pref
open xmms preference window (as Ctrl\-P)
.TP
.B prev
xmms previous song command, go to the previous song
.TP
.B previous
go to the previous song and wrap round to last if position is first
.TP
.B remove
xmms removes mp3 currently playing from playlist
.TP
.B repeat
toggle xmms repeat flag
.TP
.B shuffle
toggle xmms shuffle flag
.TP
.B stop
xmms stop command, stop playing
.TP
.B title
print the current mp3 song title
.TP
.B uniq
remove duplicate files from the playlist
.TP
.B quit
terminate xmms
.TP
.B \-\-help  : print this help message
.SS "The flag setting commands are used with 0 or 1:"
.B equalizer
hide/show xmms equalizer window
.TP
.B main
hide/show xmms main window
.TP
.B play_list
hide/show xmms playing list window
.SS "The condition testing commands are:"
.B paused
returns OK if xmms is paused
.TP
.B playing  
returns OK if xmms is playing a song
.TP
.B is_equalizer  
returns OK if xmms has its equalizer window open
.TP
.B is_main  
returns OK if xmms has its main window open
.TP
.B is_play_list  
returns OK if xmms has its playing list window open
.TP
.B is_stream  
returns OK if xmms is playing a stream (http://somewhere)
.TP
.B running  
returns OK if xmms is running.
.SS "The other specific commands are:"
.B session number  
use the session number 'number', xmmsctrl looks automatically for the first working session
.TP
.B 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
.TP
.B time [+|\-|/]seconds
.IP
.B seconds 
set the playback time to seconds
.IP
.B +seconds 
advance the playback by seconds
.IP
.B -seconds 
rewind the playback by seconds
.IP
.B /seconds 
set the playback time to seconds from the end of the song
.IP
Examples : xmmsctrl time 30, xmmsctrl time +10
.TP
.B track <n>
set the n'th track in the play list as the current track
.TP
.B track last
set the last track in the play list as the current track
.TP
.B vol [+|\-]percent 
with the following effects
.IP
.B percent 
set the volume to percent
.IP
.B +percent 
increase the volume with percent
.IP
.B \-percent
decrease the volume with percent
.IP
Examples : xmmsctrl vol 40, xmmsctrl vol +5, xmmsctrl vol \-5
.TP
.B print <string>  
general formatted print, similar to printf. The codes are:
.IP
\fB%n\fR: new line
.IP
\fB%t\fR: tab
.IP
\fB%F\fR: current filename
.IP
\fB%T\fR: current title
.IP
\fB%P\fR: current position
.IP
\fB%s\fR: playback time in sec
.IP
\fB%m\fR: playback time in min:sec
.IP
\fB%S\fR: song length in sec
.IP
\fB%M\fR: song length in min:sec
.IP
\fB%v\fR: master volume
.IP
\fB%l\fR: playlist length
.IP
\fB%p\fR: playback time in percent
.IP
\fB%(x)\fR: 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
.IP
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
.TP
.B eq  
add evaluation string for the case treated song == current played song
.TP
.B neq  
add evaluation string for the case treated song != current played song
.TP
.B +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
.TP
.B \-file <file>  
remove the file/directory from the playlist. You can use 'xmmsctrl uniq \-file something' for a cleaner result
.PP
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.,
.IP
xmmsctrl +file BEGIN dir1 dir2 song1 song2 END
.SS "Examples of shell scripts to define simple functions:"
.TP
Play/Stop :
.IP
sh \-c "if xmmsctrl playing;\e
.IP
then xmmsctrl stop;\e
else xmmsctrl play; fi"
.TP
Play/Pause :
.IP
sh \-c "if xmmsctrl playing;\e
.IP
then xmmsctrl pause;\e
else xmmsctrl play; fi"
.PP
.SH AUTHOR
xmmsctrl was written by Alexandre David <adavid@cs.aau.dk>
.PP
This manual page was written by Sandro Tosi <matrixhasu@gmail.com>,
for the Debian project (but may be used by others).