path: root/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

All data between the client and server is encoded in UTF-8. (Note,
that in UTF-8 all standard ansi characters, 0-127, are the same as a standard
ansi encoding. Also, no ansi character appears in any multi-byte
characters.  So, you can use standard C functions like strlen, and strcpy
just fine with UTF-8 encoded strings. For example: "OK\n" encoded in UTF-8 is
simply "OK\n".  For more information on UTF=8: 
http://www.cl.cam.ac.uk/~mgk25/unicode.html#utf-8 )

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 crossfading between songs

currentsong
	displays the song info of current song (same song that is identified
	in status)

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

deleteid <int songid>
	delete song with _songid_ 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 path>
	lists all songs and directories in _path_ (recursively)
	_path_ is optional and maybe a directory or path

listallinfo <string path>
	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

move <int songid> <int to>
	move song with _songid_ 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 required and should be 0 or 1
	NOTE: use of pause command w/o the _pause_ argument is depricated

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

playid <int songid>
	begin playing playlist at song with _songid_, _songid_ is optional

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

playlistinfo <int song>
	displays list of songs in the playlist
	_song_ is optional and species a single song to displa info for

playlistiid <int songid>
	displays list of songs in the playlist
	_songid_ is optional and species a single song to display info for

plchanges <playlist version>
	displays changed songs currently in the playlist since 
	_playlist version_
	NOTE: to detect songs that were deleted at the end of the playlist,
	use playlistlength returned by status command.

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>
	searches for any song that contain _what_
	_type_ can be "title","artist","album", or "filename"
	search is not case sensitive

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

seekid <int songid> <int time>
	seeks to the position _time_ (in seconds) of song with _songid_

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_playtime: sum of all song times in db
	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 stopped on or playing, playlist song number)
	songid: (current song stopped on or playing, playlist songid)
	time: <int elapsed>:<time total> (of current playing/paused song)
	bitrate: <int bitrate> (instantaneous bitrate in kbps)
	xfade: <int seconds> (crossfade in seconds)
	audio: <int sampleRate>:<int bits>:<int channels>
	updatings_db: <int job id>
	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

swapid <int songid1> <int songid2>
	swap positions of of songs with song id's of _songid1_ and _songid2_
	increments playlist version by 1

update <string path>
	searches mp3 directory for new music and removes old music from the db
	_path_ is an optional argument that maybe a particular directory or 
		song/file to update.
	returned:
		updating_db: <int job id>
	where job id, is the job id requested for your update, and is displayed
	in status, while the requested update is happening
	increments playlist version by 1
	NOTE: To update a number of paths/songs at once, use command_list,
	it will be much more faster/effecient.  Also, if you use a 
	command_list for updating, only one update_db job id will be returned
	per sequence of updates.

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

or:

command_list_ok_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. If "command_list_ok_begin is used", "list_OK\n" is returned for each successful command executed
in the command list.