--- name: "xmmsctrl" section: "1" platform: "linux" package: "xmmsctrl" version: "1.9-1" release: "Debian 4.0 (Etch)" platforms: ["linux"] url: "https://new.carta.tech/xmmsctrl" --- # xmmsctrl(1) small utility to control xmms from the command line ## 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 \; then \; else \; 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 \** clear the play list and load the directory/file \ 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 \** 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 \** 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 \** 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 \** 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 \ This manual page was written by Sandro Tosi \, for the Debian project (but may be used by others).