mpd/doc/COMMANDS

                         Music Player Daemon - Commands

This document is intended for client developers, not end users.

Format:
-------

If arguments contain spaces, they should be surrounded by double quotation 
marks, ".

command <type arg1> <type arg2> ...
	explanation: w/ arg1 and arg2

Command Completion:
-------------------

A command returns "OK\n" on completion or "ACK some error\n" on failure.
These denote the end of command execution.

Commands:
---------

add <string path>
	add the file _path_ to the playlist (directories add recursively)
	_path_ can also be a single file
	increments playlist version by for each song added

clear	
	clears the current playlist
	increments playlist version by 1

clearerror	
	clear the current error message in status
	(this is also accomplished by any command that starts playback)

close
	close the connection with the MPD

crossfade <int seconds>
	sets and gets crossfading between songs
	(a value of 0 disables crossfading).
	if _seconds_ is not specified, then the return crossfade returns:
		crossfade: <unsigned integer >= 0>


delete <int song>
	delete _song_ from playlist
	increments playlist version by 1

find <string type> <string what>
	finds songs in the db that are exactly _what_
	_type_ should be "album", "artist", or "title"
	_what_ is what to find

kill
	kill MPD

list <string type> <string arg1>
	list all tags of _type_ 
	_type_ should be "album" or "artist"
	_arg1_ is an optional parameter when type is album, this specifies
		to list albums by a artist, where artist is specified with
		arg1

listall <string directory>
	lists all songs and directories in _directory_ (recursively)
	_directory_ is optional

listall <string directory>
	same as listall command, except it also returns metadata info
	in the same format as lsinfo

load <string name>
	loads the playlist _name_.m3u from the playlist directory
	increments playlist version by the number of songs added

lsinfo <string directory>
	list contents of _directory_, from the db.  _directory_ is optional

move <int from> <int to>
	move song at _from_ to _to_ in the playlist
	increments playlist version by 1

next
	plays next song in playlist

pause	<bool pause>
	toggle pause/resume playing
	_pause_ is optional and should be 0 or 1

password <string password>
	this is used for authentication with the server.
	_password_ is simply the plaintext password

ping
	does nothing but return "OK"

play <int song>
	begin playing playlist at song number _song_, _song_ is optional

playlist
	displays the current playlist
	NOTE: do not use this, instead use 'playlistinfo'

playlistinfo
	displays information about the current playlist

previous
	plays previous song in playlist

random <int state>
	set random state to _state_, _state_ should be 0 or 1

repeat <int state>
	set repeat state to _state_, _state_ should be 0 or 1

rm <string name>
	removes the playlist <name>.m3u from the playlist directory

save <string name>
	saves the current playlist to _name_.m3u in the playlist directory

search <string type> <string what>
	same as "find" but searches for any song that contain _what_
	search is not case sensitive

seek <int song> <int time>
	seeks to the position _time_ (in seconds) of entry _song_ in the 
	playlist

setvol <int vol>
	set volume to _vol_
	_vol_ the range of volume is 0-100

shuffle
	shuffles the current playlist
	increments playlist version by 1

stats
	display stats
	artists: number of artists
	albums: number of albums
	songs: number of songs
	uptime: daemon uptime in seconds
	db_update: last db update in UNIX time
	playtime: time length of music played

status
	reports current status of player, and volume level.
	volume: (0-100).
	repeat: (0 or 1)
	playlist: (31-bit unsigned integer, the playlist version number)
	playlistlength: (integer, the length of the playlist)
	state: ("play", "stop", or "pause")
	song: (current song playing/paused, playlist song number)
	time: <int elapsed>:<time total> (of current playing/paused song)
	bitrate: <int bitrate> (instantaneous bitrate in kbps)
	error: if there is an error, returns message here

stop
	stop playing

swap <int song1> <int song2>
	swap positions of _song1_ and _song2_
	increments playlist version by 1

update
	searches mp3 directory for new music and removes old music from the db

volume <int change>
	change volume by amount _change_
	NOTE: volume command is deprecated, use setvol instead

COMMAND LIST
------------

To facilitate faster adding of files, etc, you can pass a list of commands all
at once using a command list.  The command list beings with:

command_list_begin

And ends with:

command_list_end

It does not execute any commands until the list has ended.  The return
value is whatever the return for a list of commands is.  On success
for all commands, OK is returned.  If a command fails, no more commands
are executed and the appropriate ACK error is returned.