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, 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"
AUTHOR
xmmsctrl was written by Alexandre David <[email protected]>
This manual page was written by Sandro Tosi <[email protected]>, for the Debian project (but may be used by others).