List of Commands

balance - set or query balance level
If <value> is given, the balance is set to that value. The valid range is -100 through 100 inclusive (any given value will be coerced into this range). A value of 0 specifies the same volume for both the left and right channels, while negative values imply a louder left channel and positive values imply a louder right channel. If no <value> is specified, the current balance setting is displayed.

Returns: If a value is specified, that value is returned. Otherwise the current balance level is returned.

band - view or set the value of equalizer bands
The BAND command outputs or sets the value of an equalizer band. If given no arguments, the BAND command outputs the current values of all 10 equalizer bands. If only a band value is specified (a value from 0 through 9) then the value of that particular band is output. Otherwise the second argument, which should be a decimal value between -20 and 20, is assigned to the given band.

Returns: Always 0

clear - clear the current playlist
Clears all entries from the playlist.

Returns: Always 0

downvolume - decrease the volume in either or both channels
If <step> is not given, it assumes a default value of 2. If no channel is specified, the volume of both channels is decreased by <step>. Otherwise the volume decrease is applied only to the given channel.

Alias: -
Returns: If no channel is specified, returns the average of the new volumes in the two channels. Otherwise, when the left or right channel is specified, returns the new volume of that channel.

echo - display a string
Displays all of the given arguments as strings, separating each by a single space, and followed by a newline. If no arguments are given, simply displays a newline.

Returns: Always 0

eject - cause XMMS to display its file load dialog
Causes XMMS to display its file load dialog.

Returns: Always 0

fade - adjust volume to specified level over time
The FADE command performs a simple fade effect on the currently playing track. If no song is being played, the command has no effect. Specifying either LEFT or RIGHT will cause the effect to be isolated to only the specified channel. The [target] specifies at which volume the fade effect should end. The volume is restored to its previous settings once the target has been reached. The [stepsize] indicates by how much to change the volume at a time. The [delay] specifies how long to wait (in microseconds) before decreasing or increasing the volume towards the target by the specified stepsize. By default the effect is applied to both channels, with a target of 0, stepsize of 1, and delay of 100000.

Returns: Always 0

fakepause - pause XMMS and release the output device
The FAKEPAUSE is similar to the PAUSE command in that it pauses playback. However, FAKEPAUSE is an interactive command. When you press [ENTER] at the prompt FAKEPAUSE provides, playback will resume where it left off. The usefulness of this command is that it forces XMMS to release the output device until you unpause it. Technically it does this by saving the current song and the position in it before executing the STOP command. Then, when it unpauses, it jumps back to the saved position in the song and resumes playback.

Returns: If no playback is currently in progress, returns COMERR_NOEFFECT. Otherwise returns 0.

help - list commands and show their usage
Given no arguments, HELP displays a list of commands and a brief description for each. If a command name is given as the first argument, HELP will display the usage of that command and a more in-depth description.

Alias: ?
Returns: 127 if an argument is specified that does not correspond to any command, 0 otherwise

jump - jump to a position in the playlist
The JUMP command instructs XMMS to move to a given position in the playlist. Positions are specified as numbers. The first file in the playlist is position 1. If XMMS is playing when the JUMP command is executed then playback will continue immediately on the new file.

Returns: Always 0

list - display the playlist
The PLAYLIST command lists all of the entries in XMMS's playlist. If a single number is provided as an argument, the PLAYLIST command lists all entries beginning at the position specified by that number. If a second number is specified as an argument, the PLAYLIST command will stop listing entries when it reaches that position in the playlist. By default PLAYLIST will list the titles of songs in the playlist. If [FILENAMES] is specified, filenames will be listed instead.

Returns: The number of playlist entries displayed

load - add music or playlist files to the playlist
Attempts to load each of the filenames given as arguments. If a file is a playlist file, the files specified within that playlist file are each appended to the playlist. Otherwise the file itself is appended to the playlist.

Returns: The number of successfully loaded

next - advance forward in the playlist
If [n] is not specified, it is 1 by default. NEXT advances the playlist forward by n entries. Whenever the end of the playlist is encountered during advancing, the beginning of the playlist is considered to be the next entry (hence the playlist is treated as circular). If shuffle mode is enabled in XMMS, the parameter n is effectively ignored.

Alias: forward
Returns: The new position of the playlist

pause - pause or unpause playback
The PAUSE command behaves as a toggle. If XMMS is currently paused, the PAUSE command will have it resume playback. If XMMS is currently playing, the PAUSE command will cause it to pause. If no song is currently playing, the PAUSE command will have no effect.

Returns: If no playback is currently in progress, returns COMERR_NOEFFECT. Otherwise returns 0 if playback is unpaused as a result of this command, and 1 otherwise.

play - start or resume playback
The PLAY command forces playback to begin or resume. If a track is currently playing, this command has the effect of causing playback of the track to start over. If playback is paused, PLAY resumes playback where it left off. Otherwise playback begins at the beginning of the current track.

Returns: If playback was previously paused, 2 is returned. If a track was already being played when this command was issued, 1 is returned. Otherwise 0 is returned.

preamp - view or set the equalizer's preamp value
The PREAMP command will output the equalizer's preamp value if no arguments are given. Otherwise its argument, which should be a decimal value between -20 and 20, is assigned.

Returns: Always 0

preferences - cause XMMS to display its preferences dialog
Causes XMMS to display its preferences dialog.

Returns: Always 0

previous - advance backward in the playlist
If [n] is not specified, it is 1 by default. PREVIOUS advances the playlist backward by n entries. Whenever the beginning of the playlist is encountered during advancing, the end of the playlist is considered to be the previous entry (hence the playlist is treated as circular). If shuffle mode is enabled in XMMS, the parameter n is effectively ignored.

Alias: backward
Returns: The new position of the playlist

quit - terminate the shell
The QUIT command instructs XMMS-Shell to immediately exit with an exit code of 0.

Alias: exit
Returns: Always 0

randomtrack - jump to random track
The RANDOMTRACK command causes XMMS to jump to a random track in the playlist. Its effect is the same as the JUMP command. If the playlist contains fewer than two entries, this command has no effect.

Returns: Always 0

repeat - set repeat mode
Clears, sets, or toggles repeat mode. If neither OFF nor ON is given, TOGGLE is assumed to be the default.

Returns: Returns 1 if repeat mode is turned on, 0 otherwise

resetdevice - force XMMS to reset the output device
The RESETDEVICE command forces XMMS to reset the output device. This is useful if you wish to apply new output device settings immediately without interrupting playback. This is technically implemented in the same manner as the FAKEPAUSE command.

Returns: Always 0

save - save playlist to file
The SAVE command saves the playlist currently loaded by XMMS to a file of your choice. The contents of the file will consist of the filenames of each of the files in the playlist, one per line.

Returns: The number of entries saved to the file

shuffle - set shuffle mode
Clears, sets, or toggles shuffle mode. If neither OFF nor ON is given, TOGGLE is assumed to be the default.

Returns: Returns 1 if shuffle mode is turned on, 0 otherwise

status - display the current status of XMMS
The STATUS command queries XMMS for general information, such as the current track, playback mode, and various other settings.

Returns: Always 0

stop - stop playback
The STOP command forces playback to stop. If playback is subsequently resumed, it begins at the beginning of the current track.

Returns: If playback was previously paused, 2 is returned. If a track was being played when this command was issued, 1 is returned. Otherwise 0 is returned.

upvolume - increase the volume in either or both channels
If <step> is not given, it assumes a default value of 2. If no channel is specified, the volume of both channels is increased by <step>. Otherwise the volume increase is applied only to the given channel.

Alias: +
Returns: If no channel is specified, returns the average of the new volumes in the two channels. Otherwise, when the left or right channel is specified, returns the new volume of that channel.

version - display XMMS-Shell and XMMS version information
Displays version information regarding XMMS-Shell, and attempts to obtain and display version information regarding XMMS (the XMMS version number may or may not mean anything).

Returns: Always 0

volume - set the volume in either or both channels to a given level
The VOLUME command queries or sets the volume level of XMMS. If the <value> argument is given, then the volume will be set. If not, a volume will be displayed and returned. If a volume is given, it should be specified as an integer from 0 through 100 inclusive (any given value will be coerced into this range). If [left] or [right] is given, only that channel is operated upon. That is, if a channel is specified and no volume is given, the current volume setting for that channel is displayed and returned. If a volume and channel are specified, the volume will only be applied to the given channel. If a volume is given and no channel is specified, both channels will be set to the given volume.

Returns: If no parameters are given, returns the average of the volumes in the two channels. If a value is given, that value is returned. Otherwise, when the left or right channel is specified, returns the volume of that channel.

window - show or hide XMMS windows
The WINDOW command hides and shows XMMS windows. The first argument must be the window to operate on (the main, playlist, or equalizer window, or all three) and the second argument must be a command (HIDE, SHOW, or TOGGLE). The TOGGLE command will toggle the display of a window.

Returns: A 3-bit integer, the bits of which represent the display status of each window. The least significant bit represents the equalizer window, the second bit the main window, and the third bit the playlist window.

xmmsquit - force XMMS and XMMS-Shell to exit
Forces XMMS to exit, followed by XMMS-Shell exiting. If you don't want to kill XMMS, just use the QUIT command instead.

Alias: xmmsexit
Returns: Always 0