diff options
Diffstat (limited to 'doc/protocol.xml')
| -rw-r--r-- | doc/protocol.xml | 262 |
1 files changed, 224 insertions, 38 deletions
diff --git a/doc/protocol.xml b/doc/protocol.xml index 5aa9c9114..2ebb891cd 100644 --- a/doc/protocol.xml +++ b/doc/protocol.xml @@ -4,7 +4,7 @@ <book> <title>The Music Player Daemon protocol</title> - <chapter> + <chapter id="syntax"> <title>General protocol syntax</title> <section> @@ -38,7 +38,7 @@ </para> </section> - <section> + <section id="request_syntax"> <title>Requests</title> <cmdsynopsis> @@ -70,7 +70,7 @@ </para> </section> - <section> + <section id="response_syntax"> <title>Responses</title> <para> @@ -79,7 +79,7 @@ denote the end of command execution. </para> - <section> + <section id="failure_response_syntax"> <title>Failure responses</title> <para> @@ -188,7 +188,7 @@ </para> </section> - <section> + <section id="range_syntax"> <title>Ranges</title> <para> @@ -203,10 +203,10 @@ </section> </chapter> - <chapter> + <chapter id="recipes"> <title>Recipes</title> - <section> + <section id="queuing_recipe"> <title>Queuing</title> <para> @@ -244,7 +244,7 @@ </section> </chapter> - <chapter> + <chapter id="command_reference"> <title>Command reference</title> <note> @@ -259,7 +259,7 @@ </para> </note> - <section> + <section id="status_commands"> <title>Querying MPD's status</title> <variablelist> @@ -612,7 +612,7 @@ </variablelist> </section> - <section> + <section id="playback_option_commands"> <title>Playback options</title> <variablelist> @@ -795,7 +795,7 @@ </variablelist> </section> - <section> + <section id="playback_commands"> <title>Controlling playback</title> <variablelist> @@ -882,8 +882,8 @@ <listitem> <para> Seeks to the position <varname>TIME</varname> (in - seconds) of entry <varname>SONGPOS</varname> in the - playlist. + seconds; fractions allowed) of entry + <varname>SONGPOS</varname> in the playlist. </para> </listitem> </varlistentry> @@ -898,7 +898,8 @@ <listitem> <para> Seeks to the position <varname>TIME</varname> (in - seconds) of song <varname>SONGID</varname>. + seconds; fractions allowed) of song + <varname>SONGID</varname>. </para> </listitem> </varlistentry> @@ -912,9 +913,10 @@ </term> <listitem> <para> - Seeks to the position <varname>TIME</varname> within the - current song. If prefixed by '+' or '-', then the time - is relative to the current playing position. + Seeks to the position <varname>TIME</varname> (in + seconds; fractions allowed) within the current song. If + prefixed by '+' or '-', then the time is relative to the + current playing position. </para> </listitem> </varlistentry> @@ -934,7 +936,7 @@ </variablelist> </section> - <section> + <section id="queue"> <title>The current playlist</title> <variablelist> @@ -1218,6 +1220,28 @@ OK </listitem> </varlistentry> + <varlistentry id="command_rangeid"> + <term> + <cmdsynopsis> + <command>rangeid</command> + <arg choice="req"><replaceable>ID</replaceable></arg> + <arg choice="req"><replaceable>START:END</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + <footnote id="since_0_19"><simpara>Since MPD + 0.19</simpara></footnote> Specifies the portion of the + song that shall be played. <varname>START</varname> and + <varname>END</varname> are offsets in seconds + (fractional seconds allowed); both are optional. + Omitting both (i.e. sending just ":") means "remove the + range, play everything". A song that is currently + playing cannot be manipulated this way. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_shuffle"> <term> <cmdsynopsis> @@ -1263,10 +1287,48 @@ OK </para> </listitem> </varlistentry> + + <varlistentry id="command_addtagid"> + <term> + <cmdsynopsis> + <command>addtagid</command> + <arg choice="req"><replaceable>SONGID</replaceable></arg> + <arg choice="req"><replaceable>TAG</replaceable></arg> + <arg choice="req"><replaceable>VALUE</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Adds a tag to the specified song. Editing song tags is + only possible for remote songs. This change is + volatile: it may be overwritten by tags received from + the server, and the data is gone when the song gets + removed from the queue. + </para> + </listitem> + </varlistentry> + + <varlistentry id="command_cleartagid"> + <term> + <cmdsynopsis> + <command>cleartagid</command> + <arg choice="req"><replaceable>SONGID</replaceable></arg> + <arg choice="opt"><replaceable>TAG</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Removes tags from the specified song. If + <varname>TAG</varname> is not specified, then all tag + values will be removed. Editing song tags is only + possible for remote songs. + </para> + </listitem> + </varlistentry> </variablelist> </section> - <section> + <section id="playlist_files"> <title>Stored playlists</title> <para> @@ -1456,16 +1518,19 @@ OK </variablelist> </section> - <section> + <section id="database"> <title>The music database</title> <variablelist> + <varlistentry id="command_count"> <term> <cmdsynopsis> <command>count</command> <arg choice="req"><replaceable>TAG</replaceable></arg> <arg choice="req"><replaceable>NEEDLE</replaceable></arg> + <arg choice="opt">group</arg> + <arg choice="opt"><replaceable>GROUPTYPE</replaceable></arg> </cmdsynopsis> </term> <listitem> @@ -1473,8 +1538,15 @@ OK Counts the number of songs and their total playtime in the db matching <varname>TAG</varname> exactly. </para> + <para> + The <parameter>group</parameter> keyword may be used to + group the results by a tag. The following prints + per-artist counts: + </para> + <programlisting>count group artist</programlisting> </listitem> </varlistentry> + <varlistentry id="command_find"> <term> <cmdsynopsis> @@ -1488,15 +1560,43 @@ OK <para> Finds songs in the db that are exactly <varname>WHAT</varname>. <varname>TYPE</varname> can - be any tag supported by MPD, or one of the three special - parameters — <parameter>file</parameter> to search by + be any tag supported by MPD, or one of the special + parameters: + </para> + + <itemizedlist> + <listitem> + <para> + <parameter>any</parameter> checks all tag values + </para> + </listitem> + + <listitem> + <para> + <parameter>file</parameter> checks the full path + (relative to the music directory) + </para> + </listitem> - full path (relative to the music directory), - <parameter>in</parameter> to restrict the search to - songs in the given directory (also relative to the music - directory) and - <parameter>any</parameter> to match against all - available tags. <varname>WHAT</varname> is what to find. + <listitem> + <para> + <parameter>base</parameter> restricts the search to + songs in the given directory (also relative to the + music directory) + </para> + </listitem> + + <listitem> + <para> + <parameter>modified-since</parameter> compares the + file's time stamp with the given value (ISO 8601 or + UNIX time stamp) + </para> + </listitem> + </itemizedlist> + + <para> + <varname>WHAT</varname> is what to find. </para> </listitem> </varlistentry> @@ -1517,27 +1617,42 @@ OK </para> </listitem> </varlistentry> + <varlistentry id="command_list"> <term> <cmdsynopsis> <command>list</command> <arg choice="req"><replaceable>TYPE</replaceable></arg> - <arg><replaceable>ARTIST</replaceable></arg> + <arg choice="opt"><replaceable>FILTERTYPE</replaceable></arg> + <arg choice="opt"><replaceable>FILTERWHAT</replaceable></arg> + <arg choice="opt"><replaceable>...</replaceable></arg> + <arg choice="opt">group</arg> + <arg choice="opt"><replaceable>GROUPTYPE</replaceable></arg> + <arg choice="opt"><replaceable>...</replaceable></arg> </cmdsynopsis> </term> <listitem> <para> - Lists all tags of the specified type. + Lists unique tags values of the specified type. <varname>TYPE</varname> can be any tag supported by MPD or <parameter>file</parameter>. </para> <para> - <varname>ARTIST</varname> is an optional parameter when - type is album, this specifies to list albums by an - artist. + Additional arguments may specify a filter like the one + in the <link + linkend="command_find"><command>find</command> + command</link>. + </para> + <para> + The <parameter>group</parameter> keyword may be used + (repeatedly) to group the results by one or more tags. + The following example lists all album names, + grouped by their respective (album) artist: </para> + <programlisting>list album group albumartist</programlisting> </listitem> </varlistentry> + <varlistentry id="command_listall"> <term> <cmdsynopsis> @@ -1550,6 +1665,12 @@ OK Lists all songs and directories in <varname>URI</varname>. </para> + <para> + Do not use this command. Do not manage a client-side + copy of MPD's database. That is fragile and adds huge + overhead. It will break with large databases. Instead, + query MPD whenever you need something. + </para> </listitem> </varlistentry> <varlistentry id="command_listallinfo"> @@ -1565,6 +1686,37 @@ OK returns metadata info in the same format as <command>lsinfo</command>. </para> + <para> + Do not use this command. Do not manage a client-side + copy of MPD's database. That is fragile and adds huge + overhead. It will break with large databases. Instead, + query MPD whenever you need something. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_listfiles"> + <term> + <cmdsynopsis> + <command>listfiles</command> + <arg><replaceable>URI</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Lists the contents of the directory + <varname>URI</varname>, including files are not + recognized by MPD. <varname>URI</varname> can be a path + relative to the music directory or an URI understood by + one of the storage plugins. The response contains at + least one line for each directory entry with the prefix + "file: " or "directory: ", and may be followed by file + attributes such as "Last-Modified" and "size". + </para> + <para> + For example, "smb://SERVER" returns a list of all shares + on the given SMB/CIFS server; "nfs://servername/path" + obtains a directory listing from the NFS server. + </para> </listitem> </varlistentry> <varlistentry id="command_lsinfo"> @@ -1585,6 +1737,10 @@ OK deprecated; use "listplaylists" instead. </para> <para> + This command may be used to list metadata of remote + files (e.g. URI beginning with "http://" or "smb://"). + </para> + <para> Clients that are connected via UNIX domain socket may use this command to read the tags of an arbitrary local file (URI beginning with "file:///"). @@ -1606,6 +1762,10 @@ OK "file:///foo/bar.ogg". </para> <para> + This command may be used to list metadata of remote + files (e.g. URI beginning with "http://" or "smb://"). + </para> + <para> The response consists of lines in the form "KEY: VALUE". Comments with suspicious characters (e.g. newlines) are ignored silently. @@ -1722,7 +1882,7 @@ OK </variablelist> </section> - <section> + <section id="stickers"> <title>Stickers</title> <para> @@ -1842,7 +2002,7 @@ OK </variablelist> </section> - <section> + <section id="connection_commands"> <title>Connection settings</title> <variablelist> @@ -1903,7 +2063,7 @@ OK </variablelist> </section> - <section> + <section id="output_commands"> <title>Audio output devices</title> <variablelist> @@ -1957,12 +2117,38 @@ OK <para> Shows information about all outputs. </para> + <screen> +outputid: 0 +outputname: My ALSA Device +outputenabled: 0 +OK + </screen> + <para> + Return information: + </para> + <itemizedlist> + <listitem> + <para> + <varname>outputid</varname>: ID of the output. May change between executions + </para> + </listitem> + <listitem> + <para> + <varname>outputname</varname>: Name of the output. It can be any. + </para> + </listitem> + <listitem> + <para> + <varname>outputenabled</varname>: Status of the output. 0 if disabled, 1 if enabled. + </para> + </listitem> + </itemizedlist> </listitem> </varlistentry> </variablelist> </section> - <section> + <section id="reflection_commands"> <title>Reflection</title> <variablelist> @@ -2078,7 +2264,7 @@ suffix: mpc</programlisting> </variablelist> </section> - <section> + <section id="client_to_client"> <title>Client to client</title> <para> |