aboutsummaryrefslogtreecommitdiffstats
path: root/doc/protocol.xml
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--doc/protocol.xml146
1 files changed, 140 insertions, 6 deletions
diff --git a/doc/protocol.xml b/doc/protocol.xml
index abc74e4e6..360d2d22a 100644
--- a/doc/protocol.xml
+++ b/doc/protocol.xml
@@ -1258,6 +1258,44 @@ 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>
@@ -1455,12 +1493,15 @@ OK
<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>
@@ -1468,8 +1509,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>
@@ -1487,7 +1535,7 @@ OK
parameters — <parameter>file</parameter> to search by
full path (relative to the music directory),
- <parameter>in</parameter> to restrict the search to
+ <parameter>base</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
@@ -1512,27 +1560,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>
@@ -1545,6 +1608,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">
@@ -1560,6 +1629,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">
@@ -1580,6 +1680,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:///").
@@ -1601,6 +1705,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.
@@ -1952,6 +2060,32 @@ 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>