aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMax Kellermann <max@duempel.org>2008-11-19 21:16:19 +0100
committerMax Kellermann <max@duempel.org>2008-11-19 21:16:19 +0100
commita3fd74d0dcb3c51bf5fce949c1c6d5b0a22b3d6d (patch)
treebb874794ddf23c8bdc7c17fd1221e4ef0ab3d9fa
parent05f4629fa3785b9596024d24eaea6f9f5afd75fa (diff)
downloadmpd-a3fd74d0dcb3c51bf5fce949c1c6d5b0a22b3d6d.tar.gz
mpd-a3fd74d0dcb3c51bf5fce949c1c6d5b0a22b3d6d.tar.xz
mpd-a3fd74d0dcb3c51bf5fce949c1c6d5b0a22b3d6d.zip
doc: converted doc/COMMANDS to DocBook
The goal is to have one structured document which is the authoritative protocol specification. The documentation which currently resides in the wiki will be merged.
-rw-r--r--doc/COMMANDS325
-rw-r--r--doc/protocol.xml1064
2 files changed, 1064 insertions, 325 deletions
diff --git a/doc/COMMANDS b/doc/COMMANDS
deleted file mode 100644
index 35373a4d5..000000000
--- a/doc/COMMANDS
+++ /dev/null
@@ -1,325 +0,0 @@
- Music Player Daemon - Commands
-
- WARNING
- This document has not been updated to reflect recent changes in
- the MPD protocol. It does not contain all supported commands,
- and some commands may now take additional arguments. However,
- clients conforming to this specification should still be
- compatible with the latest release of MPD. For more up to date
- documentation, please see the protocol reference on the wiki at
- <http://mpd.wikia.com/wiki/Protocol_Reference>.
-
-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.
-
-NOTE:
------
-
-For manipulating playlists and playing, there are two sets of commands. One
-set uses the song id of a song in the playlist, while another set uses the
-playlist position of the song. The commands using song id's should be used
-instead of the commands that manipulate and control playback based on playlist
-position. Using song id's is a safer method when multiple clients are
-interacting with MPD.
-
-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
-
-addid <string path> <int position>
- _path_ is always a single file or URL
- _position_ is optional, a negative number means it is relative
- to the currently playing song in the playlist (if there is one)
- adds a song to the playlist (non-recursive) and returns the song id;
- example:
-
- addid "foo.mp3"
- Id: 999
- OK
-
-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
-
- When listing the root directory, this currently returns the
- list of stored playlists. This behavior is deprecated; use
- "listplaylists" instead.
-
-move <int from> <int to>
- move song at _from_ to _to_ in the playlist
- increments playlist version by 1
-
-moveid <int songid> <int to>
- move song with _songid_ to _to_ in the playlist
- increments playlist version by 1
- if _to_ is negative, it is relative to the current song in
- the playlist (if there is one).
-
-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 deprecated
-
-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 specifies a single song to display info for
-
-playlistid <int songid>
- displays list of songs in the playlist
- _songid_ is optional and specifies 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.
-
-plchangesposid <playlist version>
- displays changed songs currently in the playlist since
- _playlist version_
- This function only returns the position and the id of the changed song, not the complete metadata. This is more bandwidth efficient.
- 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
-
-listplaylists
- prints a list of the playlist directory
-
- After each playlist name, the server sends its last
- modification time as attribute "Last-Modified" in ISO 8601
- format. To avoid problems due to clock differences between
- clients and the server, clients should not compare this value
- with their local clock.
-
-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/efficient. 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
-
-idle
- Waits until there is a noteworthy change in one or more of
- MPD's subsystems. As soon as there is one, it lists all
- changed systems in a line in the format "changed: SUBSYSTEM",
- where SUBSYSTEM is one of the following:
-
- database: the song database has been updated
- stored_playlist: a stored playlist has been modified, renamed,
- created or deleted
- playlist: the current playlist has been modified
- player: the player has been started, stopped or seeked
- mixer: the volume has been changed
- output: an audio output has been enabled or disabled
- options: options like "repeat", "random", "crossfade"
-
- While a client waits for "idle" results, the server disables
- timeouts, allowing a client to wait for events as long as mpd
- runs. The "idle" command can be canceled by sending the
- command "noidle" (no other commands are allowed). MPD will
- then leave "idle" mode and print results immediately; might be
- empty at this time.
-
-
-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.
diff --git a/doc/protocol.xml b/doc/protocol.xml
new file mode 100644
index 000000000..cec521506
--- /dev/null
+++ b/doc/protocol.xml
@@ -0,0 +1,1064 @@
+<?xml version='1.0' encoding="utf-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+ "docbook/dtd/xml/4.2/docbookx.dtd">
+<book>
+ <title>The Music Player Daemon protocol</title>
+
+ <chapter>
+ <title>General protocol syntax</title>
+
+ <section>
+ <title>Requests</title>
+
+ <para>
+ If arguments contain spaces, they should be surrounded by double quotation
+ marks.
+ </para>
+
+ <cmdsynopsis>
+ <command>COMMAND</command>
+ <arg rep="Repeat"><replaceable>ARG</replaceable></arg>
+ </cmdsynopsis>
+
+ <para>
+ 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)
+ </para>
+ </section>
+
+ <section>
+ <title>Responses</title>
+
+ <para>
+ A command returns "OK\n" on completion or "ACK some error\n" on failure.
+ These denote the end of command execution.
+ </para>
+ </section>
+
+ <section>
+ <title>Command lists</title>
+
+ <para>
+ 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>command_list_begin</command> or
+ <command>command_list_ok_begin</command> and ends with
+ <command>command_list_end</command>.
+ </para>
+
+ <para>
+ 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.
+ </para>
+ </section>
+ </chapter>
+
+ <chapter>
+ <title>Command reference</title>
+
+ <note>
+ <para>
+ For manipulating playlists and playing, there are two sets of commands. One
+ set uses the song id of a song in the playlist, while another set uses the
+ playlist position of the song. The commands using song id's should be used
+ instead of the commands that manipulate and control playback based on playlist
+ position. Using song id's is a safer method when multiple clients are
+ interacting with MPD.
+ </para>
+ </note>
+
+ <section>
+ <title>Querying MPD's status</title>
+
+ <variablelist>
+ <varlistentry id="command_clearerror">
+ <term>
+ <cmdsynopsis>
+ <command>clearerror</command>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Clear the current error message in status (this is also
+ accomplished by any command that starts playback).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_currentsong">
+ <term>
+ <cmdsynopsis>
+ <command>currentsong</command>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Displays the song info of current song (same song that
+ is identified in status).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_idle">
+ <term>
+ <cmdsynopsis>
+ <command>idle</command>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Waits until there is a noteworthy change in one or more of
+ MPD's subsystems. As soon as there is one, it lists all
+ changed systems in a line in the format "changed: SUBSYSTEM",
+ where SUBSYSTEM is one of the following:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <returnvalue>database</returnvalue>: the song database
+ has been updated
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <returnvalue>stored_playlist</returnvalue>: a stored
+ playlist has been modified, renamed, created or
+ deleted
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <returnvalue>playlist</returnvalue>: the current
+ playlist has been modified
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <returnvalue>player</returnvalue>: the player has been
+ started, stopped or seeked
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <returnvalue>mixer</returnvalue>: the volume has been
+ changed
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <returnvalue>output</returnvalue>: an audio output has
+ been enabled or disabled
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <returnvalue>options</returnvalue>: options like
+ "repeat", "random", "crossfade"
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ While a client waits for <command>idle</command>
+ results, the server disables timeouts, allowing a client
+ to wait for events as long as mpd runs. The
+ <command>idle</command> command can be canceled by
+ sending the command <command>noidle</command> (no other
+ commands are allowed). MPD will then leave
+ <command>idle</command> mode and print results
+ immediately; might be empty at this time.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_status">
+ <term>
+ <cmdsynopsis>
+ <command>status</command>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ reports current status of player, and volume level.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>volume</term>
+ <listitem>
+ <para>0-100</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>repeat</term>
+ <listitem>
+ <para>0 or 1</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>playlist</term>
+ <listitem>
+ <para>
+ 31-bit unsigned integer, the playlist version
+ number
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>playlistlength</term>
+ <listitem>
+ <para>
+ integer, the length of the playlist
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>state</term>
+ <listitem>
+ <para>
+ "play", "stop", or "pause"
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>song</term>
+ <listitem>
+ <para>
+ current song stopped on or playing, playlist song
+ number
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>songid</term>
+ <listitem>
+ <para>
+ current song stopped on or playing, playlist
+ songid
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>time</term>
+ <listitem>
+ <para>
+ elapsed:total (of current playing/paused song)
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>bitrate</term>
+ <listitem>
+ <para>
+ instantaneous bitrate in kbps
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>xfade</term>
+ <listitem>
+ <para>
+ crossfade in seconds
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>audio</term>
+ <listitem>
+ <para>
+ sampleRate:bits:channels
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>updatings_db</term>
+ <listitem>
+ <para>
+ job id
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>error</term>
+ <listitem>
+ <para>
+ if there is an error, returns message here
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_stats">
+ <term>
+ <cmdsynopsis>
+ <command>stats</command>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Display statistics.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <varname>artists</varname>: number of artists
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>songs</varname>: number of albums
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>uptime</varname>: daemon uptime in seconds
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>db_playtime</varname>: sum of all song
+ times in db
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>db_update</varname>: last db update in UNIX
+ time
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <varname>playtime</varname>: time length of music played
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section>
+ <title>Playback options</title>
+
+ <variablelist>
+ <varlistentry id="command_crossfade">
+ <term>
+ <cmdsynopsis>
+ <command>crossfade</command>
+ <arg choice="req"><replaceable>SECONDS</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Sets crossfading between songs.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_random">
+ <term>
+ <cmdsynopsis>
+ <command>random</command>
+ <arg choice="req"><replaceable>STATE</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Set random state to <varname>STATE</varname>, should
+ be 0 or 1.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_repeat">
+ <term>
+ <cmdsynopsis>
+ <command>repeat</command>
+ <arg choice="req"><replaceable>STATE</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Set repeat state to <varname>STATE</varname>,
+ <varname>STATE</varname> should be 0 or 1.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_setvol">
+ <term>
+ <cmdsynopsis>
+ <command>setvol</command>
+ <arg choice="req"><replaceable>VOL</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Set volume to <varname>VOL</varname>, the range of
+ volume is 0-100.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_volume">
+ <term>
+ <cmdsynopsis>
+ <command>volume</command>
+ <arg choice="req"><replaceable>CHANGE</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Change volume by amount <varname>CHANGE</varname>.
+ </para>
+ <note>
+ <para>
+ <command>volume</command> is deprecated, use
+ <command>setvol</command> instead.
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section>
+ <title>Controlling playback</title>
+
+ <variablelist>
+ <varlistentry id="command_play">
+ <term>
+ <cmdsynopsis>
+ <command>play</command>
+ <arg><replaceable>SONGPOS</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Begin playing playlist at song number
+ <varname>SONGPOS</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_playid">
+ <term>
+ <cmdsynopsis>
+ <command>playid</command>
+ <arg><replaceable>SONGID</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Begin playing playlist at song
+ <varname>SONGID</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_next">
+ <term>
+ <cmdsynopsis>
+ <command>next</command>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Plays next song in playlist.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_previous">
+ <term>
+ <cmdsynopsis>
+ <command>previous</command>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Plays previous song in playlist.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_pause">
+ <term>
+ <cmdsynopsis>
+ <command>pause</command>
+ <arg choice="req"><replaceable>PAUSE</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Toggle pause/resume playing. <varname>PAUSE</varname> is 0 or 1.
+ </para>
+ <note>
+ <para>
+ Use of pause command w/o the _pause_ argument is
+ deprecated.
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_seek">
+ <term>
+ <cmdsynopsis>
+ <command>seek</command>
+ <arg choice="req"><replaceable>SONGPOS</replaceable></arg>
+ <arg choice="req"><replaceable>TIME</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Seeks to the position <varname>TIME</varname> (in
+ seconds) of entry <varname>SONGPOS</varname> in the
+ playlist.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_seekid">
+ <term>
+ <cmdsynopsis>
+ <command>seekid</command>
+ <arg choice="req"><replaceable>SONGID</replaceable></arg>
+ <arg choice="req"><replaceable>TIME</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Seeks to the position <varname>TIME</varname> (in
+ seconds) of song <varname>SONGID</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_stop">
+ <term>
+ <cmdsynopsis>
+ <command>stop</command>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Stop playing.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section>
+ <title>The current playlist</title>
+
+ <variablelist>
+ <varlistentry id="command_add">
+ <term>
+ <cmdsynopsis>
+ <command>add</command>
+ <arg choice="req"><replaceable>URI</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Add the file <varname>URI</varname> to the playlist
+ (directories add recursively).
+ <varname>URI</varname> can also be a single file.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_addid">
+ <term>
+ <cmdsynopsis>
+ <command>addid</command>
+ <arg choice="req"><replaceable>URI</replaceable></arg>
+ <arg><replaceable>POSITION</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Adds a song to the playlist (non-recursive) and returns the song id.
+ </para>
+ <para>
+ <varname>URI</varname> is always a single file or
+ URL. <varname>POSITION</varname> is optional, a
+ negative number means it is relative to the currently
+ playing song in the playlist (if there is one).
+ example:
+ </para>
+ <screen>
+addid "foo.mp3"
+Id: 999
+OK
+ </screen>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_clear">
+ <term>
+ <cmdsynopsis>
+ <command>clear</command>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Clears the current playlist.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_delete">
+ <term>
+ <cmdsynopsis>
+ <command>delete</command>
+ <arg choice="req"><replaceable>SONGPOS</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Deletes a song from the playlist.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_deleteid">
+ <term>
+ <cmdsynopsis>
+ <command>deleteid</command>
+ <arg choice="req"><replaceable>SONGID</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Delete song <varname>SONGID</varname> from playlist
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_move">
+ <term>
+ <cmdsynopsis>
+ <command>move</command>
+ <arg choice="req"><replaceable>FROM</replaceable></arg>
+ <arg choice="req"><replaceable>TO</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Move song at <varname>FROM</varname> to
+ <varname>TO</varname> in the playlist.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_moveid">
+ <term>
+ <cmdsynopsis>
+ <command>moveid</command>
+ <arg choice="req"><replaceable>FROM</replaceable></arg>
+ <arg choice="req"><replaceable>TO</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Move song with <varname>FROM</varname> to
+ <varname>TO</varname> (both song ids) in the
+ playlist. If <varname>TO</varname> is negative, it
+ is relative to the current song in the playlist (if
+ there is one).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_playlist">
+ <term>
+ <cmdsynopsis>
+ <command>playlist</command>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Displays the current playlist.
+ </para>
+ <note>
+ <para>
+ Do not use this, instead use <command>playlistinfo</command>.
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_playlistid">
+ <term>
+ <cmdsynopsis>
+ <command>playlistid</command>
+ <arg choice="req"><replaceable>SONGID</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Displays list of songs in the playlist.
+ <varname>SONGID</varname> is optional and specifies a
+ single song to display info for.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_playlistinfo">
+ <term>
+ <cmdsynopsis>
+ <command>playlistinfo</command>
+ <arg><replaceable>SONGPOS</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Displays list of songs in the playlist.
+ <varname>SONGPOS</varname> is optional and specifies
+ a single song to display info for.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_plchanges">
+ <term>
+ <cmdsynopsis>
+ <command>plchanges</command>
+ <arg choice="req"><replaceable>VERSION</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Displays changed songs currently in the playlist since
+ <varname>VERSION</varname>.
+ </para>
+ <para>
+ To detect songs that were deleted at the end of the
+ playlist, use playlistlength returned by status command.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_plchangesposid">
+ <term>
+ <cmdsynopsis>
+ <command>plchangesposid</command>
+ <arg choice="req"><replaceable>VERSION</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Displays changed songs currently in the playlist since
+ <varname>VERSION</varname>. This function only
+ returns the position and the id of the changed song, not
+ the complete metadata. This is more bandwidth efficient.
+ </para>
+ <para>
+ To detect songs that were deleted at the end of the
+ playlist, use playlistlength returned by status command.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_shuffle">
+ <term>
+ <cmdsynopsis>
+ <command>shuffle</command>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Shuffles the current playlist.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_swap">
+ <term>
+ <cmdsynopsis>
+ <command>swap</command>
+ <arg choice="req"><replaceable>SONG1</replaceable></arg>
+ <arg choice="req"><replaceable>SONG2</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Swap positions of <varname>SONG1</varname> and
+ <varname>SONG2</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_swapid">
+ <term>
+ <cmdsynopsis>
+ <command>swapid</command>
+ <arg choice="req"><replaceable>SONG1</replaceable></arg>
+ <arg choice="req"><replaceable>SONG2</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Swap positions of of songs of
+ <varname>SONG1</varname> and
+ <varname>SONG2</varname> (both song ids).
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section>
+ <title>Stored playlists</title>
+
+ <variablelist>
+ <varlistentry id="command_load">
+ <term>
+ <cmdsynopsis>
+ <command>load</command>
+ <arg choice="req"><replaceable>NAME</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Loads the playlist <filename>NAME.m3u</filename> from
+ the playlist directory.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_listplaylists">
+ <term>
+ <cmdsynopsis>
+ <command>listplaylists</command>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Prints a list of the playlist directory.
+ </para>
+ <para>
+ After each playlist name, the server sends its last
+ modification time as attribute "Last-Modified" in ISO
+ 8601 format. To avoid problems due to clock differences
+ between clients and the server, clients should not
+ compare this value with their local clock.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_rm">
+ <term>
+ <cmdsynopsis>
+ <command>rm</command>
+ <arg choice="req"><replaceable>NAME</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Removes the playlist <filename>NAME.m3u</filename> from
+ the playlist directory.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_save">
+ <term>
+ <cmdsynopsis>
+ <command>save</command>
+ <arg choice="req"><replaceable>NAME</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Saves the current playlist to
+ <filename>NAME.m3u</filename> in the playlist directory.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section>
+ <title>The music database</title>
+
+ <variablelist>
+ <varlistentry id="command_find">
+ <term>
+ <cmdsynopsis>
+ <command>find</command>
+ <arg choice="req"><replaceable>TYPE</replaceable></arg>
+ <arg choice="req"><replaceable>WHAT</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ finds songs in the db that are exactly
+ <varname>WHAT</varname>. <varname>TYPE</varname> should
+ be <parameter>album</parameter>,
+ <parameter>artist</parameter>, or
+ <parameter>title</parameter>. <varname>WHAT</varname>
+ is what to find.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_list">
+ <term>
+ <cmdsynopsis>
+ <command>list</command>
+ <arg choice="req"><replaceable>TYPE</replaceable></arg>
+ <arg><replaceable>ARTIST</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ List all tags of the specified type.
+ <varname>TYPE</varname> should be "album" or "artist".
+ </para>
+ <para>
+ <varname>ARTIST</varname> is an optional parameter
+ when type is album, this specifies to list albums by a
+ artist.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_listall">
+ <term>
+ <cmdsynopsis>
+ <command>listall</command>
+ <arg><replaceable>URI</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Lists all songs and directories in
+ <varname>URI</varname>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_listallinfo">
+ <term>
+ <cmdsynopsis>
+ <command>listallinfo</command>
+ <arg><replaceable>URI</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Same as <command>listall</command>, except it also
+ returns metadata info in the same format as
+ <command>lsinfo</command>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_lsinfo">
+ <term>
+ <cmdsynopsis>
+ <command>lsinfo</command>
+ <arg><replaceable>URI</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ List contents of directory <varname>URI</varname>.
+ </para>
+ <para>
+ When listing the root directory, this currently returns
+ the list of stored playlists. This behavior is
+ deprecated; use "listplaylists" instead.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_search">
+ <term>
+ <cmdsynopsis>
+ <command>search</command>
+ <arg choice="req"><replaceable>TYPE</replaceable></arg>
+ <arg choice="req"><replaceable>WHAT</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Searches for any song that contain
+ <varname>WHAT</varname>. <varname>TYPE</varname> can be
+ <parameter>title</parameter>,
+ <parameter>artist</parameter>,
+ <parameter>album</parameter> or
+ <parameter>filename</parameter>. Search is not case
+ sensitive.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_update">
+ <term>
+ <cmdsynopsis>
+ <command>update</command>
+ <arg><replaceable>URI</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Updates the music database.
+ </para>
+ <para>
+ <varname>URI</varname> is a particular directory or
+ song/file to update.
+ </para>
+ <para>
+ Prints "updating_db: JOBID" where
+ <varname>JOBID</varname> is the job id requested for
+ your update, and is displayed in status, while the
+ requested update is happening.
+ </para>
+ <para>
+ To update a number of paths/songs at once, use
+ command_list, it will be much more faster/efficient.
+ Also, if you use a command_list for updating, only one
+ <command>update</command> job id will be returned per
+ sequence of updates.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section>
+ <title>Connection settings</title>
+
+ <variablelist>
+ <varlistentry id="command_close">
+ <term>
+ <cmdsynopsis>
+ <command>close</command>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Closes the connection to MPD.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_kill">
+ <term>
+ <cmdsynopsis>
+ <command>kill</command>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Kill MPD.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_password">
+ <term>
+ <cmdsynopsis>
+ <command>password</command>
+ <arg choice="req"><replaceable>PASSWORD</replaceable></arg>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ This is used for authentication with the server.
+ <varname>PASSWORD</varname> is simply the plaintext
+ password.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="command_ping">
+ <term>
+ <cmdsynopsis>
+ <command>ping</command>
+ </cmdsynopsis>
+ </term>
+ <listitem>
+ <para>
+ Does nothing but return "OK".
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+ </chapter>
+</book>