xmmsctrl1

Small utility to control xmms from the command line

Usage

xmmsctrl [command]

Overview

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