diff options
Diffstat (limited to 'doc/protocol.xml')
| -rw-r--r-- | doc/protocol.xml | 473 |
1 files changed, 390 insertions, 83 deletions
diff --git a/doc/protocol.xml b/doc/protocol.xml index 5aa9c9114..839aa2d03 100644 --- a/doc/protocol.xml +++ b/doc/protocol.xml @@ -4,18 +4,18 @@ <book> <title>The Music Player Daemon protocol</title> - <chapter> + <chapter id="syntax"> <title>General protocol syntax</title> <section> <title>Protocol overview</title> <para> - The MPD command protocol exchanges line-based text records - between client and server over TCP. Once the client is - connected to the server, they conduct a conversation until the - client closes the connection. The conversation flow is always - initiated by the client. + The <application>MPD</application> command protocol exchanges + line-based text records between client and server over TCP. + Once the client is connected to the server, they conduct a + conversation until the client closes the connection. The + conversation flow is always initiated by the client. </para> <para> @@ -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,21 +203,21 @@ </section> </chapter> - <chapter> + <chapter id="recipes"> <title>Recipes</title> - <section> + <section id="queuing_recipe"> <title>Queuing</title> <para> - Often, users run MPD with "<link + Often, users run <application>MPD</application> with "<link linkend="command_random">random</link>" enabled, but want to be able to insert songs "before" the rest of the playlist. That is commonly called "queuing". </para> <para> - MPD implements this by allowing the client to specify a + <application>MPD</application> implements this by allowing the client to specify a "priority" for each song in the playlist (commands <link linkend="command_prio"><command>prio</command></link> and <link @@ -227,24 +227,25 @@ </para> <para> - In "random" mode, MPD maintains an internal randomized - sequence of songs. In this sequence, songs with a higher - priority come first, and all songs with the same priority are - shuffled (by default, all songs are shuffled, because all have - the same priority "0"). When you increase the priority of a - song, it is moved to the front of the sequence according to - its new priority, but always after the current one. A song - that has been played already (it's "before" the current song - in that sequence) will only be scheduled for repeated playback - if its priority has become bigger than the priority of the - current song. Decreasing the priority of a song will moved it - farther to the end of the sequence. Changing the priority of - the current song has no effect on the sequence. + In "random" mode, <application>MPD</application> maintains an + internal randomized sequence of songs. In this sequence, + songs with a higher priority come first, and all songs with + the same priority are shuffled (by default, all songs are + shuffled, because all have the same priority "0"). When you + increase the priority of a song, it is moved to the front of + the sequence according to its new priority, but always after + the current one. A song that has been played already (it's + "before" the current song in that sequence) will only be + scheduled for repeated playback if its priority has become + bigger than the priority of the current song. Decreasing the + priority of a song will moved it farther to the end of the + sequence. Changing the priority of the current song has no + effect on the sequence. </para> </section> </chapter> - <chapter> + <chapter id="command_reference"> <title>Command reference</title> <note> @@ -255,12 +256,12 @@ commands using song ids should be used instead of the commands that manipulate and control playback based on playlist position. Using song ids is a safer method when multiple - clients are interacting with MPD. + clients are interacting with <application>MPD</application>. </para> </note> - <section> - <title>Querying MPD's status</title> + <section id="status_commands"> + <title>Querying <application>MPD</application>'s status</title> <variablelist> <varlistentry id="command_clearerror"> @@ -298,12 +299,14 @@ </term> <listitem> <para> - <footnote id="since_0_14"><simpara>Introduced with MPD 0.14</simpara></footnote> + <footnote id="since_0_14"><simpara>Introduced with + <application>MPD</application> 0.14</simpara></footnote> 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 - <returnvalue>changed: SUBSYSTEM</returnvalue>, where - SUBSYSTEM is one of the following: + of <application>MPD</application>'s subsystems. As soon + as there is one, it lists all changed systems in a line + in the format <returnvalue>changed: + SUBSYSTEM</returnvalue>, where SUBSYSTEM is one of the + following: </para> <itemizedlist> <listitem> @@ -385,14 +388,15 @@ 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. + commands are allowed). <application>MPD</application> + will then leave <command>idle</command> mode and print + results immediately; might be empty at this time. </para> <para> - If the optional <varname>SUBSYSTEMS</varname> argument is used, - MPD will only send notifications when something changed in - one of the specified subsytems. + If the optional <varname>SUBSYSTEMS</varname> argument + is used, <application>MPD</application> will only send + notifications when something changed in one of the + specified subsytems. </para> </listitem> </varlistentry> @@ -429,7 +433,7 @@ <listitem> <para> <varname>single</varname>: - <footnote id="since_0_15"><simpara>Introduced with MPD 0.15</simpara></footnote> + <footnote id="since_0_15"><simpara>Introduced with <application>MPD</application> 0.15</simpara></footnote> <returnvalue>0 or 1</returnvalue> </para> </listitem> @@ -504,7 +508,7 @@ <listitem> <para> <varname>elapsed</varname>: - <footnote id="since_0_16"><simpara>Introduced with MPD 0.16</simpara></footnote> + <footnote id="since_0_16"><simpara>Introduced with <application>MPD</application> 0.16</simpara></footnote> <returnvalue> Total time elapsed within the current song, but with higher resolution. @@ -612,7 +616,7 @@ </variablelist> </section> - <section> + <section id="playback_option_commands"> <title>Playback options</title> <variablelist> @@ -745,7 +749,7 @@ <parameter>album</parameter>, <parameter>auto</parameter><footnote id="replay_gain_auto_since_0_16"> - <simpara>added in MPD 0.16</simpara> + <simpara>added in <application>MPD</application> 0.16</simpara> </footnote>. </para> <para> @@ -795,7 +799,7 @@ </variablelist> </section> - <section> + <section id="playback_commands"> <title>Controlling playback</title> <variablelist> @@ -882,8 +886,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 +902,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 +917,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 +940,7 @@ </variablelist> </section> - <section> + <section id="queue"> <title>The current playlist</title> <variablelist> @@ -1035,7 +1041,7 @@ OK at <varname>START:END</varname> to <varname>TO</varname> in the playlist. <footnote id="range_since_0_15"> - <simpara>Ranges are supported since MPD 0.15</simpara> + <simpara>Ranges are supported since <application>MPD</application> 0.15</simpara> </footnote> </para> </listitem> @@ -1135,7 +1141,7 @@ OK </term> <listitem> <para> - Searches case-sensitively for partial matches in the + Searches case-insensitively for partial matches in the current playlist. </para> </listitem> @@ -1218,6 +1224,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 <application>MPD</application> + 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 +1291,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 +1522,20 @@ 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"><replaceable>...</replaceable></arg> + <arg choice="opt">group</arg> + <arg choice="opt"><replaceable>GROUPTYPE</replaceable></arg> </cmdsynopsis> </term> <listitem> @@ -1473,8 +1543,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 +1565,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 <application>MPD</application>, 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> + + <listitem> + <para> + <parameter>base</parameter> restricts the search to + songs in the given directory (also 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>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 +1622,43 @@ 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. - <varname>TYPE</varname> can be any tag supported by MPD or + Lists unique tags values of the specified type. + <varname>TYPE</varname> can be any tag supported by + <application>MPD</application> 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 +1671,14 @@ 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 <application>MPD</application>'s database. That + is fragile and adds huge overhead. It will break with + large databases. Instead, query + <application>MPD</application> whenever you need + something. + </para> </listitem> </varlistentry> <varlistentry id="command_listallinfo"> @@ -1565,6 +1694,40 @@ 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 <application>MPD</application>'s database. That + is fragile and adds huge overhead. It will break with + large databases. Instead, query + <application>MPD</application> 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 <application>MPD</application>. + <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 +1748,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 +1773,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,22 +1893,131 @@ OK </variablelist> </section> - <section> + <section id="mount"> + <title>Mounts and neighbors</title> + + <para> + A "storage" provides access to files in a directory tree. The + most basic storage plugin is the "local" storage plugin which + accesses the local file system, and there are plugins to + access NFS and SMB servers. + </para> + + <para> + Multiple storages can be "mounted" together, similar to the + <application>mount</application> command on many operating + systems, but without cooperation from the kernel. No + superuser privileges are necessary, beause this mapping exists + only inside the <application>MPD</application> process + </para> + + <variablelist> + + <varlistentry id="command_mount"> + <term> + <cmdsynopsis> + <command>mount</command> + <arg choice="req"><replaceable>PATH</replaceable></arg> + <arg choice="req"><replaceable>URI</replaceable></arg> + </cmdsynopsis> + </term> + + <listitem> + <para> + Mount the specified remote storage URI at the given + path. Example: + </para> + + <programlisting>mount foo nfs://192.168.1.4/export/mp3</programlisting> + </listitem> + </varlistentry> + + <varlistentry id="command_umount"> + <term> + <cmdsynopsis> + <command>unmount</command> + <arg choice="req"><replaceable>PATH</replaceable></arg> + </cmdsynopsis> + </term> + + <listitem> + <para> + Unmounts the specified path. Example: + </para> + + <programlisting>unmount foo</programlisting> + </listitem> + </varlistentry> + + <varlistentry id="command_listmounts"> + <term> + <cmdsynopsis> + <command>listmounts</command> + </cmdsynopsis> + </term> + + <listitem> + <para> + Queries a list of all mounts. By default, this contains + just the configured <varname>music_directory</varname>. + Example: + </para> + + <programlisting>listmounts +mount: +storage: /home/foo/music +mount: foo +storage: nfs://192.168.1.4/export/mp3 +OK +</programlisting> + </listitem> + </varlistentry> + + <varlistentry id="command_listneighbors"> + <term> + <cmdsynopsis> + <command>listneighbors</command> + </cmdsynopsis> + </term> + + <listitem> + <para> + Queries a list of "neighbors" (e.g. accessible file + servers on the local net). Items on that list may be + used with the <link + linkend="command_mount"><command>mount</command></link> + command. Example: + </para> + + <programlisting>listneighbors +neighbor: smb://FOO +name: FOO (Samba 4.1.11-Debian) +OK +</programlisting> + </listitem> + </varlistentry> + + </variablelist> + </section> + + <section id="stickers"> <title>Stickers</title> <para> "Stickers"<footnoteref linkend="since_0_15"/> are pieces of - information attached to existing MPD objects (e.g. song files, + information attached to existing + <application>MPD</application> objects (e.g. song files, directories, albums). Clients can create arbitrary name/value - pairs. MPD itself does not assume any special meaning in - them. + pairs. <application>MPD</application> itself does not assume + any special meaning in them. </para> <para> The goal is to allow clients to share additional (possibly dynamic) information about songs, which is neither stored on the client (not available to other clients), nor stored in the - song files (MPD has no write access). + song files (<application>MPD</application> has no write + access). </para> <para> @@ -1842,7 +2122,7 @@ OK </variablelist> </section> - <section> + <section id="connection_commands"> <title>Connection settings</title> <variablelist> @@ -1854,7 +2134,8 @@ OK </term> <listitem> <para> - Closes the connection to MPD. MPD will try to send the + Closes the connection to <application>MPD</application>. + <application>MPD</application> will try to send the remaining output buffer before it actually closes the connection, but that cannot be guaranteed. This command will not generate a response. @@ -1869,7 +2150,7 @@ OK </term> <listitem> <para> - Kills MPD. + Kills <application>MPD</application>. </para> </listitem> </varlistentry> @@ -1903,7 +2184,7 @@ OK </variablelist> </section> - <section> + <section id="output_commands"> <title>Audio output devices</title> <variablelist> @@ -1957,12 +2238,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 +2385,7 @@ suffix: mpc</programlisting> </variablelist> </section> - <section> + <section id="client_to_client"> <title>Client to client</title> <para> |