xmmsctrl(1)

NAME

xmmsctrl - small utility to control xmms from the command

line

USAGE

xmmsctrl [command]

DESCRIPTION

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.

COMMANDS

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, xmmsc

trl 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 addi

tion, 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"

AUTHOR

xmmsctrl was written by Alexandre David <adavid@cs.aau.dk>

This manual page was written by Sandro Tosi <matrixha

su@gmail.com>, for the Debian project (but may be used by oth

ers).

August 2006

XMMSCTRL(1)