diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/developer.xml | 50 | ||||
| -rw-r--r-- | doc/mpd.conf.5 | 83 | ||||
| -rw-r--r-- | doc/mpdconf.example | 32 | ||||
| -rw-r--r-- | doc/protocol.xml | 473 | ||||
| -rw-r--r-- | doc/user.xml | 1635 |
5 files changed, 1804 insertions, 469 deletions
diff --git a/doc/developer.xml b/doc/developer.xml index 729e6a513..aa3cc62c0 100644 --- a/doc/developer.xml +++ b/doc/developer.xml @@ -10,7 +10,7 @@ <para> This is a guide for those who wish to hack on the MPD source code. MPD is an open project, and we are always happy about - contributions. So far, more than 50 people have contributed + contributions. So far, more than 150 people have contributed patches. </para> @@ -155,7 +155,53 @@ foo(const char *abc, int xyz) <para> Send your patches to the mailing list: - mpd-devel@musicpd.org + <email>mpd-devel@musicpd.org</email> (<ulink + url="http://mailman.blarg.de/listinfo/mpd-devel">subscribe + here</ulink>) </para> + + <para> + <command>git pull</command> requests are preferred. Regular + contributors can get <ulink + url="http://git.musicpd.org/account-policy.html">an account on + git.musicpd.org</ulink>, but any public git repository will do. + </para> + </chapter> + + <chapter> + <title>Development Tools</title> + + <section> + <title>Clang Static Analyzer</title> + + <para> + The <ulink url="http://clang-analyzer.llvm.org/">clang static + analyzer</ulink> is a tool that helps find bugs. To run it on + the MPD code base, install LLVM and clang. Configure MPD to + use clang: + </para> + + <programlisting>./configure --enable-debug CXX=clang++ CC=clang ...</programlisting> + + <para> + It is recommended to use <option>--enable-debug</option>, + because the analyzer takes advantage of + <function>assert()</function> calls, which are only enabled in + the debug build. + </para> + + <para> + Now run the analyzer: + </para> + + <programlisting>scan-build --use-c++=clang++ --use-cc=clang make</programlisting> + + <para> + The options <option>--use-c++</option> and + <option>--use-cc</option> are necessary because it invokes + <command>cc</command> for actually compiling the sources by + default. That breaks, because MPD requires a C99 compiler. + </para> + </section> </chapter> </book> diff --git a/doc/mpd.conf.5 b/doc/mpd.conf.5 index 57b11a30f..0cd6c313d 100644 --- a/doc/mpd.conf.5 +++ b/doc/mpd.conf.5 @@ -136,53 +136,6 @@ for the format of this parameter. Multiple audio_output sections may be specified. If no audio_output section is specified, then MPD will scan for a usable audio output. .TP -.B audio_output_format <sample_rate:bits:channels> -This specifies the sample rate, bits per sample, and number of channels of -audio that is sent to each audio output. Note that audio outputs may specify -their own audio format which will be used for actual output to the audio -device. An example is "44100:16:2" for 44100Hz, 16 bits, and 2 channels. The -default is to use the audio format of the input file. -Any of the three attributes may be an asterisk to specify that this -attribute should not be enforced -.TP -.B samplerate_converter <integer or prefix> -This specifies the libsamplerate converter to use. The supplied value should -either be an integer or a prefix of the name of a converter. The default is -"Fastest Sinc Interpolator". - -At the time of this writing, the following converters are available: -.RS -.TP -Best Sinc Interpolator (0) - -Band limited sinc interpolation, best quality, 97dB SNR, 96% BW. -.TP -Medium Sinc Interpolator (1) - -Band limited sinc interpolation, medium quality, 97dB SNR, 90% BW. -.TP -Fastest Sinc Interpolator (2) - -Band limited sinc interpolation, fastest, 97dB SNR, 80% BW. -.TP -ZOH Interpolator (3) - -Zero order hold interpolator, very fast, very poor quality with audible -distortions. -.TP -Linear Interpolator (4) - -Linear interpolator, very fast, poor quality. -.TP -internal - -Poor quality, no floating point operations. This is the default (and -only choice) if MPD was compiled without libsamplerate. -.RE -.IP -For an up-to-date list of available converters, please see the libsamplerate -documentation (available online at <\fBhttp://www.mega\-nerd.com/SRC/\fP>). -.TP .B replaygain <off or album or track or auto> If specified, mpd will adjust the volume of songs played using ReplayGain tags (see <\fBhttp://www.replaygain.org/\fP>). Setting this to "album" will adjust @@ -198,39 +151,6 @@ This is the gain (in dB) applied to songs with ReplayGain tags. .B volume_normalization <yes or no> If yes, mpd will normalize the volume of songs as they play. The default is no. .TP -.B audio_buffer_size <size in KiB> -This specifies the size of the audio buffer in kibibytes. The default is 4096, -large enough for nearly 12 seconds of CD-quality audio. -.TP -.B buffer_before_play <0-100%> -This specifies how much of the audio buffer should be filled before playing a -song. Try increasing this if you hear skipping when manually changing songs. -The default is 10%, a little over 1 second of CD-quality audio with the default -buffer size. -.TP -.B http_proxy_host <hostname> -This setting is deprecated. Use the "proxy" setting in the "curl" -input block. See MPD user manual for details. -.TP -.B connection_timeout <seconds> -If a client does not send any new data in this time period, the connection is -closed. The default is 60. -.TP -.B max_connections <number> -This specifies the maximum number of clients that can be connected to mpd. The -default is 5. -.TP -.B max_playlist_length <number> -This specifies the maximum number of songs that can be in the playlist. The -default is 16384. -.TP -.B max_command_list_size <size in KiB> -This specifies the maximum size a command list can be. The default is 2048. -.TP -.B max_output_buffer_size <size in KiB> -This specifies the maximum size of the output buffer to a client. The default -is 8192. -.TP .B filesystem_charset <charset> This specifies the character set used for the filesystem. A list of supported character sets can be obtained by running "iconv \-l". The default is @@ -260,7 +180,8 @@ clients. Note that you must recreate (not update) your database for changes to this parameter to take effect. Possible values are artist, album, title, track, name, genre, date, composer, performer, comment, disc, musicbrainz_artistid, musicbrainz_albumid, musicbrainz_albumartistid, -musicbrainz_trackid. Multiple tags may be specified as a comma separated list. +musicbrainz_releasetrackid, musicbrainz_trackid. Multiple tags may be specified +as a comma separated list. An example value is "artist,album,title,track". The special value "none" may be used alone to disable all metadata. The default is to use all known tag types except for comments and those starting with "musicbrainz". diff --git a/doc/mpdconf.example b/doc/mpdconf.example index 470a5c98e..4b55f8801 100644 --- a/doc/mpdconf.example +++ b/doc/mpdconf.example @@ -373,38 +373,6 @@ input { # ############################################################################### - -# MPD Internal Buffering ###################################################### -# -# This setting adjusts the size of internal decoded audio buffering. Changing -# this may have undesired effects. Don't change this if you don't know what you -# are doing. -# -#audio_buffer_size "4096" -# -# This setting controls the percentage of the buffer which is filled before -# beginning to play. Increasing this reduces the chance of audio file skipping, -# at the cost of increased time prior to audio playback. -# -#buffer_before_play "10%" -# -############################################################################### - - -# Resource Limitations ######################################################## -# -# These settings are various limitations to prevent MPD from using too many -# resources. Generally, these settings should be minimized to prevent security -# risks, depending on the operating resources. -# -#connection_timeout "60" -#max_connections "10" -#max_playlist_length "16384" -#max_command_list_size "2048" -#max_output_buffer_size "8192" -# -############################################################################### - # Character Encoding ########################################################## # # If file or directory names do not display correctly for your locale then you 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> diff --git a/doc/user.xml b/doc/user.xml index 208e910e6..d1c7ff595 100644 --- a/doc/user.xml +++ b/doc/user.xml @@ -4,7 +4,7 @@ <book> <title>The Music Player Daemon - User's Manual</title> - <chapter> + <chapter id="intro"> <title>Introduction</title> <para> @@ -13,10 +13,10 @@ </para> <para> - MPD (Music Player Daemon) is, as the name suggests, a server - software allowing you to remotely play your music, handle - playlists, deliver music (HTTP STREAMS with various - sub-protocols) and organizze playlists. + <application>MPD</application> (Music Player Daemon) is, as the + name suggests, a server software allowing you to remotely play + your music, handle playlists, deliver music (HTTP streams with + various sub-protocols) and organizze playlists. </para> <para> @@ -26,8 +26,8 @@ </para> <para> - MPD supports also Gapless playback, buffered audio output, and - crossfading! + <application>MPD</application> supports also gapless playback, + buffered audio output, and crossfading! </para> <para> @@ -37,38 +37,42 @@ </para> </chapter> - <chapter> + <chapter id="install"> <title>Installation</title> <para> We recommend that you use the software installation routines of - your distribution to install MPD. Most operating systems have a - MPD package, which is very easy to install. + your distribution to install <application>MPD</application>. + Most operating systems have a <application>MPD</application> + package, which is very easy to install. </para> - <section> + <section id="install_debian"> <title>Installing on Debian/Ubuntu</title> <para> - Install the package <filename>mpd</filename> via APT: + Install the package <application>MPD</application> via APT: </para> <programlisting>apt-get install mpd</programlisting> <para> - When installed this way, MPD by default looks for music in - /var/lib/mpd/music/; this may not be correct. Look at your - /etc/mpd.conf file... + When installed this way, <application>MPD</application> by + default looks for music in + <filename>/var/lib/mpd/music/</filename>; this may not be + correct. Look at your <filename>/etc/mpd.conf</filename> + file... </para> </section> - <section> + <section id="install_source"> <title>Compiling from source</title> <para> Download the source tarball from <ulink - url="http://www.musicpd.org/download.html">the MPD home - page</ulink> and unpack it: + url="http://www.musicpd.org/download.html">the + <application>MPD</application> home page</ulink> and unpack + it: </para> <programlisting>tar xf mpd-version.tar.xz @@ -80,6 +84,38 @@ cd mpd-version</programlisting> </para> <para> + For example, the following installs a fairly complete list of + build dependencies on Debian Wheezy: + </para> + + <programlisting> +apt-get install g++ \ + libmad0-dev libmpg123-dev libid3tag0-dev \ + libflac-dev libvorbis-dev libopus-dev \ + libadplug-dev libaudiofile-dev libsndfile1-dev libfaad-dev \ + libfluidsynth-dev libgme-dev libmikmod2-dev libmodplug-dev \ + libmpcdec-dev libwavpack-dev libwildmidi-dev \ + libsidplay2-dev libsidutils-dev libresid-builder-dev \ + libavcodec-dev libavformat-dev \ + libmp3lame-dev \ + libsamplerate0-dev libsoxr-dev \ + libbz2-dev libcdio-paranoia-dev libiso9660-dev libmms-dev \ + libzzip-dev \ + libcurl4-gnutls-dev libyajl-dev libexpat-dev \ + libasound2-dev libao-dev libjack-jackd2-dev libopenal-dev \ + libpulse-dev libroar-dev libshout3-dev \ + libmpdclient-dev \ + libnfs-dev libsmbclient-dev \ + libupnp-dev \ + libavahi-client-dev \ + libsqlite3-dev \ + libsystemd-daemon-dev libwrap0-dev \ + libcppunit-dev xmlto \ + libboost-dev \ + libglib2.0-dev libicu-dev + </programlisting> + + <para> Now configure the source tree: </para> @@ -100,71 +136,74 @@ cd mpd-version</programlisting> <programlisting>make install</programlisting> </section> - <section> + <section id="systemd_socket"> <title><filename>systemd</filename> socket activation</title> <para> Using <filename>systemd</filename>, you can launch - <filename>mpd</filename> on demand when the first client - attempts to connect. Create two files in - <filename>/etc/systemd/system/</filename>; first - <filename>mpd.socket</filename>: + <application>MPD</application> on demand when the first client + attempts to connect. </para> - <programlisting>[Socket] -ListenStream=/run/mpd.socket -ListenStream=6600 -[Install] -WantedBy=sockets.target</programlisting> - <para> - Now create <filename>mpd.service</filename>: + <application>MPD</application> comes with two + <application>systemd</application> unit files: a "service" + unit and a "socket" unit. These will only be installed when + <application>MPD</application> was configured with + <parameter>--with-systemdsystemunitdir=/lib/systemd</parameter>. </para> - <programlisting>[Unit] -Description=Music Player Daemon -After=sound.target -[Service] -ExecStart=/usr/bin/mpd --stdout --no-daemon</programlisting> - <para> - Start the socket: + To enable socket activation, type: </para> <programlisting>systemctl enable mpd.socket systemctl start mpd.socket</programlisting> <para> - In this configuration, <filename>mpd</filename> will ignore - the <varname>bind_to_address</varname> and + In this configuration, <application>MPD</application> will + ignore the <varname>bind_to_address</varname> and <varname>port</varname> settings. </para> </section> </chapter> - <chapter> + <chapter id="config"> <title>Configuration</title> - <section> + <section id="config_music_directory"> <title>Configuring the music directory</title> <para> When you play local files, you should organize them within a directory called the "music directory". This is configured in - MPD with the <varname>music_directory</varname> setting. + <application>MPD</application> with the + <varname>music_directory</varname> setting. </para> <para> - By default, MPD follows symbolic links in the music directory. - This behavior can be switched off: - <varname>follow_outside_symlinks</varname> controls whether - MPD follows links pointing to files outside of the music - directory, and <varname>follow_inside_symlinks</varname> lets - you disable symlinks to files inside the music directory. + By default, <application>MPD</application> follows symbolic + links in the music directory. This behavior can be switched + off: <varname>follow_outside_symlinks</varname> controls + whether <application>MPD</application> follows links pointing + to files outside of the music directory, and + <varname>follow_inside_symlinks</varname> lets you disable + symlinks to files inside the music directory. + </para> + + <para> + Instead of using local files, you can use <link + linkend="storage_plugins">storage plugins</link> to access + files on a remote file server. For example, to use music from + the SMB/CIFS server "myfileserver" on the share called + "Music", configure the music directory + "<parameter>smb://myfileserver/Music</parameter>". For a + recipe, read the <link linkend="satellite">Satellite + MPD</link> section. </para> </section> - <section> + <section id="config_database_plugins"> <title>Configuring database plugins</title> <para> @@ -209,9 +248,65 @@ systemctl start mpd.socket</programlisting> </tbody> </tgroup> </informaltable> + + <para> + More information can be found in the <link + linkend="database_plugins">database plugin reference</link>. + </para> </section> - <section> + <section id="config_neighbor_plugins"> + <title>Configuring neighbor plugins</title> + + <para> + All neighbor plugins are disabled by default to avoid unwanted + overhead. To enable (and configure) a plugin, add a + <varname>neighbor</varname> block to + <filename>mpd.conf</filename>: + </para> + + <programlisting>neighbors { + plugin "smbclient" +} + </programlisting> + + <para> + The following table lists the <varname>neighbor</varname> + options valid for all plugins: + </para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry> + Name + </entry> + <entry> + Description + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + <varname>plugin</varname> + </entry> + <entry> + The name of the plugin. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para> + More information can be found in the <link + linkend="neighbor_plugins">neighbor plugin reference</link>. + </para> + </section> + + <section id="config_input_plugins"> <title>Configuring input plugins</title> <para> @@ -264,9 +359,14 @@ systemctl start mpd.socket</programlisting> </tbody> </tgroup> </informaltable> + + <para> + More information can be found in the <link + linkend="input_plugins">input plugin reference</link>. + </para> </section> - <section> + <section id="config_decoder_plugins"> <title>Configuring decoder plugins</title> <para> @@ -320,27 +420,36 @@ systemctl start mpd.socket</programlisting> </tbody> </tgroup> </informaltable> + + <para> + More information can be found in the <link + linkend="decoder_plugins">decoder plugin reference</link>. + </para> </section> - <section> + <section id="config_encoder_plugins"> <title>Configuring encoder plugins</title> <para> - Encoders are used by some of the output plugins (such as - <varname>shout</varname>). The encoder settings are included - in the <varname>audio_output</varname> section. + Encoders are used by some of the output plugins (such as <link + linkend="shout_output"><varname>shout</varname></link>). The + encoder settings are included in the + <varname>audio_output</varname> section. More information can + be found in the <link linkend="encoder_plugins">encoder plugin + reference</link>. </para> </section> - <section> + <section id="config_audio_outputs"> <title>Configuring audio outputs</title> <para> Audio outputs are devices which actually play the audio chunks - produced by MPD. You can configure any number of audio output - devices, but there must be at least one. If none is - configured, MPD attempts to auto-detect. Usually, this works - quite well with ALSA, OSS and on Mac OS X. + produced by <application>MPD</application>. You can configure + any number of audio output devices, but there must be at least + one. If none is configured, <application>MPD</application> + attempts to auto-detect. Usually, this works quite well with + ALSA, OSS and on Mac OS X. </para> <para> @@ -392,7 +501,7 @@ systemctl start mpd.socket</programlisting> a name registered in the PULSE server. </entry> </row> - <row> + <row id="ao_format"> <entry> <varname>format</varname> </entry> @@ -416,8 +525,6 @@ systemctl start mpd.socket</programlisting> (signed 8 bit integer samples), <varname>16</varname>, <varname>24</varname> (signed 24 bit integer samples padded to 32 bit), - <varname>24_3</varname> (signed 24 bit integer - samples, no padding, 3 bytes per sample), <varname>32</varname> (signed 32 bit integer samples), <varname>f</varname> (32 bit floating point, -1.0 to 1.0). @@ -431,8 +538,8 @@ systemctl start mpd.socket</programlisting> </entry> <entry> Specifies whether this audio output is enabled when - MPD is started. By default, all audio outputs are - enabled. + <application>MPD</application> is started. By + default, all audio outputs are enabled. </entry> </row> <row> @@ -441,10 +548,12 @@ systemctl start mpd.socket</programlisting> <parameter>yes|no</parameter> </entry> <entry> - If set to "no", then MPD will not send tags to this - output. This is only useful for output plugins that - can receive tags, for example the - <varname>httpd</varname> output plugin. + If set to <parameter>no</parameter>, then + <application>MPD</application> will not send tags to + this output. This is only useful for output plugins + that can receive tags, for example the <link + linkend="httpd_output"><varname>httpd</varname></link> + output plugin. </entry> </row> <row> @@ -453,10 +562,12 @@ systemctl start mpd.socket</programlisting> <parameter>yes|no</parameter> </entry> <entry> - If set to "yes", then MPD attempts to keep this audio - output always open. This may be useful for streaming - servers, when you don't want to disconnect all - listeners even when playback is accidentally stopped. + If set to <parameter>yes</parameter>, then + <application>MPD</application> attempts to keep this + audio output always open. This may be useful for + streaming servers, when you don't want to disconnect + all listeners even when playback is accidentally + stopped. </entry> </row> <row> @@ -466,10 +577,14 @@ systemctl start mpd.socket</programlisting> </entry> <entry> Specifies which mixer should be used for this audio - output: the hardware mixer (available for ALSA, OSS - and PulseAudio), the software mixer or no mixer - ("none"). By default, the hardware mixer is used for - devices which support it, and none for the others. + output: the hardware mixer (available for <link + linkend="alsa_output">ALSA</link>, <link + linkend="oss_output">OSS</link> and <link + linkend="pulse_output">PulseAudio</link>), the + software mixer or no mixer + (<parameter>none</parameter>). By default, the + hardware mixer is used for devices which support it, + and none for the others. </entry> </row> <row> @@ -479,10 +594,11 @@ systemctl start mpd.socket</programlisting> </entry> <entry> Specifies how replay gain is applied. The default is - "software", which uses an internal software volume - control. "mixer" uses the configured (hardware) mixer - control. "none" disables replay gain on this audio - output. + <parameter>software</parameter>, which uses an + internal software volume control. + <parameter>mixer</parameter> uses the configured + (hardware) mixer control. <parameter>none</parameter> + disables replay gain on this audio output. </entry> </row> </tbody> @@ -490,7 +606,7 @@ systemctl start mpd.socket</programlisting> </informaltable> </section> - <section> + <section id="config_filters"> <title>Configuring filters</title> <para> @@ -547,12 +663,13 @@ systemctl start mpd.socket</programlisting> </informaltable> </section> - <section> + <section id="config_playlist_plugins"> <title>Configuring playlist plugins</title> <para> Playlist plugins are used to load remote playlists. This is - not related to MPD's playlist directory. + not related to <application>MPD</application>'s playlist + directory. </para> <para> @@ -607,18 +724,484 @@ systemctl start mpd.socket</programlisting> </tbody> </tgroup> </informaltable> + + <para> + More information can be found in the <link + linkend="playlist_plugins">playlist plugin reference</link>. + </para> + </section> + + <section id="config_audio_format"> + <title>Audio Format Settings</title> + + <section id="config_global_audio_format"> + <title>Global Audio Format</title> + + <para> + The setting <varname>audio_output_format</varname> forces + <application>MPD</application> to use one audio format for + all outputs. Doing that is usually not a good idea. The + values are the same as in <link + linkend="ao_format"><varname>format</varname> in the <link + linkend="config_audio_outputs"><varname>audio_output</varname></link> + section</link>. + </para> + </section> + + <section> + <title>Resampler</title> + + <para> + Sometimes, music needs to be resampled before it can be + played; for example, CDs use a sample rate of 44,100 Hz + while many cheap audio chips can only handle 48,000 Hz. + Resampling reduces the quality and consumes a lot of CPU. + There are different options, some of them optimized for high + quality and others for low CPU usage, but you can't have + both at the same time. Often, the resampler is the + component that is responsible for most of + <application>MPD</application>'s CPU usage. Since + <application>MPD</application> comes with high quality + defaults, it may appear that <application>MPD</application> + consumes more CPU than other software. + </para> + + <para> + The following resamplers are available (if enabled at + compile time): + </para> + + <itemizedlist> + <listitem> + <para> + <ulink + url="http://www.mega-nerd.com/SRC/"><application>libsamplerate</application></ulink> + a.k.a. Secret Rabbit Code (SRC). + </para> + </listitem> + + <listitem> + <para> + <ulink + url="http://sourceforge.net/projects/soxr/"><application>libsoxr</application></ulink>, + the SoX Resampler library + </para> + </listitem> + + <listitem> + <para> + internal: low CPU usage, but very poor quality. This is + the fallback if <application>MPD</application> was + compiled without an external resampler. + </para> + </listitem> + </itemizedlist> + + <para> + The setting <varname>samplerate_converter</varname> controls + how <application>MPD</application> shall resample music. + Possible values: + </para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry> + Value + </entry> + <entry> + Description + </entry> + </row> + </thead> + <tbody> + <row> + <entry> + "<parameter>internal</parameter>" + </entry> + <entry> + The internal resampler. Low CPU usage, but very + poor quality. + </entry> + </row> + + <row> + <entry> + "<parameter>soxr very high</parameter>" + </entry> + <entry> + Use <application>libsoxr</application> with "Very + High Quality" setting. + </entry> + </row> + + <row> + <entry> + "<parameter>soxr high</parameter>" or + "<parameter>soxr</parameter>" + </entry> + <entry> + Use <application>libsoxr</application> with "High + Quality" setting. + </entry> + </row> + + <row> + <entry> + "<parameter>soxr medium</parameter>" + </entry> + <entry> + Use <application>libsoxr</application> with "Medium + Quality" setting. + </entry> + </row> + + <row> + <entry> + "<parameter>soxr low</parameter>" + </entry> + <entry> + Use <application>libsoxr</application> with "Low + Quality" setting. + </entry> + </row> + + <row> + <entry> + "<parameter>soxr quick</parameter>" + </entry> + <entry> + Use <application>libsoxr</application> with "Quick" + setting. + </entry> + </row> + + <row> + <entry> + "<parameter>Best Sinc Interpolator</parameter>" or + "<parameter>0</parameter>" + </entry> + <entry> + <application>libsamplerate</application>: Band + limited sinc interpolation, best quality, 97dB SNR, + 96% BW. + </entry> + </row> + + <row> + <entry> + "<parameter>Medium Sinc Interpolator</parameter>" or + "<parameter>1</parameter>" + </entry> + <entry> + <application>libsamplerate</application>: Band + limited sinc interpolation, medium quality, 97dB + SNR, 90% BW. + </entry> + </row> + + <row> + <entry> + "<parameter>Fastest Sinc Interpolator</parameter>" or + "<parameter>2</parameter>" + </entry> + <entry> + <application>libsamplerate</application>: Band + limited sinc interpolation, fastest, 97dB SNR, 80% + BW. + </entry> + </row> + + <row> + <entry> + "<parameter>ZOH Sinc Interpolator</parameter>" or + "<parameter>3</parameter>" + </entry> + <entry> + <application>libsamplerate</application>: Zero order + hold interpolator, very fast, very poor quality with + audible distortions. + </entry> + </row> + + <row> + <entry> + "<parameter>Linear Interpolator</parameter>" or + "<parameter>4</parameter>" + </entry> + <entry> + <application>libsamplerate</application>: Linear + interpolator, very fast, poor quality. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </section> + </section> + + <section id="config_other"> + <title>Other Settings</title> + + <section> + <title>The State File</title> + + <para> + The <emphasis>state file</emphasis> is a file where + <application>MPD</application> saves and restores its state + (play queue, playback position etc.) to keep it persistent + across restarts and reboots. It is an optional setting. + </para> + + <para> + <application>MPD</application> will attempt to load the + state file during startup, and will save it when shutting + down the daemon. Additionally, the state file is refreshed + every two minutes (after each state change). + </para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>Setting</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <varname>state_file</varname> + <parameter>PATH</parameter> + </entry> + <entry> + Specify the state file location. The parent + directory must be writable by the + <application>MPD</application> user + (<parameter>+wx</parameter>). + </entry> + </row> + + <row> + <entry> + <varname>state_file_interval</varname> + <parameter>SECONDS</parameter> + </entry> + <entry> + Auto-save the state file this number of seconds + after each state change. Defaults to + <parameter>120</parameter> (2 minutes). + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </section> + + <section> + <title>Resource Limitations</title> + + <para> + These settings are various limitations to prevent + <application>MPD</application> from using too many + resources (denial of service). + </para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>Setting</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + + <row> + <entry> + <varname>connection_timeout</varname> + <parameter>SECONDS</parameter> + </entry> + <entry> + If a client does not send any new data in this time + period, the connection is closed. Clients waiting + in "idle" mode are excluded from this. Default is + <parameter>60</parameter>. + </entry> + </row> + + <row> + <entry> + <varname>max_connections</varname> + <parameter>NUMBER</parameter> + </entry> + <entry> + This specifies the maximum number of clients that + can be connected to <application>MPD</application> + at the same time. Default is + <parameter>5</parameter>. + </entry> + </row> + + <row> + <entry> + <varname>max_playlist_length</varname> + <parameter>NUMBER</parameter> + </entry> + <entry> + The maximum number of songs that can be in the + playlist. Default is <parameter>16384</parameter>. + </entry> + </row> + + <row> + <entry> + <varname>max_command_list_size</varname> + <parameter>KBYTES</parameter> + </entry> + <entry> + The maximum size a command list. Default is + <parameter>2048</parameter> (2 MiB). + </entry> + </row> + + <row> + <entry> + <varname>max_output_buffer_size</varname> + <parameter>KBYTES</parameter> + </entry> + <entry> + The maximum size of the output buffer to a client + (maximum response size). Default is + <parameter>8192</parameter> (8 MiB). + </entry> + </row> + + </tbody> + </tgroup> + </informaltable> + </section> + + <section> + <title>Buffer Settings</title> + + <para> + Do not change these unless you know what you are doing. + </para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>Setting</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + + <row> + <entry> + <varname>audio_buffer_size</varname> + <parameter>KBYTES</parameter> + </entry> + <entry> + Adjust the size of the internal audio buffer. + Default is <parameter>4096</parameter> (4 MiB). + </entry> + </row> + + <row> + <entry> + <varname>buffer_before_play</varname> + <parameter>PERCENT</parameter> + </entry> + <entry> + Control the percentage of the buffer which is filled + before beginning to play. Increasing this reduces + the chance of audio file skipping, at the cost of + increased time prior to audio playback. Default is + <parameter>10%</parameter>. + </entry> + </row> + + </tbody> + </tgroup> + </informaltable> + </section> </section> </chapter> - <chapter> - <title>Using MPD</title> + <chapter id="advanced_config"> + <title>Advanced configuration</title> - <section> + <section id="satellite"> + <title>Satellite setup</title> + + <para> + <application>MPD</application> runs well on weak machines such + as the <ulink url="http://www.raspberrypi.org/">Raspberry + Pi</ulink>. However, such hardware tends to not have storage + big enough to hold a music collection. Mounting music from a + file server can be very slow, especially when updating the + database. + </para> + + <para> + One approach for optimization is running + <application>MPD</application> on the file server, which not + only exports raw files, but also provides access to a readily + scanned database. Example configuration: + </para> + + <programlisting>music_directory "nfs://fileserver.local/srv/mp3" +#music_directory "smb://fileserver.local/mp3" + +database { + plugin "proxy" + host "fileserver.local" +} + </programlisting> + + <para> + The <link + linkend="config_music_directory"><varname>music_directory</varname></link> + setting tells <application>MPD</application> to read files + from the given NFS server. It does this by connecting to the + server from userspace. This does not actually mount the file + server into the kernel's virtual file system, and thus + requires no kernel cooperation and no special privileges. It + does not even require a kernel with NFS support, only the + <link linkend="nfs_storage"><filename>nfs</filename></link> + storage plugin (using the <filename>libnfs</filename> + userspace library). The same can be done with SMB/CIFS using + the <link + linkend="smbclient_storage"><filename>smbclient</filename></link> + storage plugin (using <filename>libsmbclient</filename>). + </para> + + <para> + The <link + linkend="config_database_plugins"><varname>database</varname></link> + setting tells <application>MPD</application> to pass all + database queries on to the <application>MPD</application> + instance running on the file server (using the <link + linkend="proxy_database"><filename>proxy</filename></link> + plugin). + </para> + </section> + </chapter> + + <chapter id="use"> + <title>Using <application>MPD</application></title> + + <section id="client"> <title>The client</title> <para> - After you have installed, configured and started MPD, you - choose a client to control the playback. + After you have installed, configured and started + <application>MPD</application>, you choose a client to control + the playback. </para> <para> @@ -629,21 +1212,23 @@ systemctl start mpd.socket</programlisting> </para> <para> - The <ulink url="http://www.musicpd.org/clients/">MPD + The <ulink + url="http://www.musicpd.org/clients/"><application>MPD</application> Wiki</ulink> contains an extensive list of clients to choose from. </para> </section> - <section> + <section id="music_directory_and_database"> <title>The music directory and the database</title> <para> The "music directory" is where you store your music files. - MPD stores all relevant meta information about all songs in - its "database". Whenever you add, modify or remove songs in - the music directory, you have to update the database, for - example with <filename>mpc</filename>: + <application>MPD</application> stores all relevant meta + information about all songs in its "database". Whenever you + add, modify or remove songs in the music directory, you have + to update the database, for example with + <filename>mpc</filename>: </para> <programlisting>mpc update</programlisting> @@ -660,22 +1245,192 @@ systemctl start mpd.socket</programlisting> </para> </section> - <section> + <section id="queue"> <title>The queue</title> <para> The queue (sometimes called "current playlist") is a list of - songs to be played by MPD. To play a song, add it to the - queue and start playback. Most clients offer an interface to - edit the queue. + songs to be played by <application>MPD</application>. To play + a song, add it to the queue and start playback. Most clients + offer an interface to edit the queue. + </para> + </section> + </chapter> + + <chapter id="advanced_usage"> + <title>Advanced usage</title> + + <section id="bit_perfect"> + <title>Bit-perfect playback</title> + + <para> + "Bit-perfect playback" is a phrase used by audiophiles to + describe a setup that plays back digital music as-is, without + applying any modifications such as resampling, format + conversion or software volume. Naturally, this implies a + lossless codec. + </para> + + <para> + By default, <application>MPD</application> attempts to do + bit-perfect playback, unless you tell it not to. Precondition + is a sound chip that supports the audio format of your music + files. If the audio format is not supported, + <application>MPD</application> attempts to fall back to the + nearest supported audio format, trying to lose as little + quality as possible. + </para> + + <para> + To verify if <application>MPD</application> converts the audio + format, enable verbose logging, and watch for these lines: + </para> + + <programlisting>decoder: audio_format=44100:24:2, seekable=true +output: opened plugin=alsa name="An ALSA output" audio_format=44100:16:2 +output: converting from 44100:24:2</programlisting> + + <para> + This example shows that a 24 bit file is being played, but the + sond chip cannot play 24 bit. It falls back to 16 bit, + discarding 8 bit. + </para> + + <para> + However, this does not yet prove bit-perfect playback; + <application>ALSA</application> may be fooling + <application>MPD</application> that the audio format is + supported. To verify the format really being sent to the + physical sound chip, try: + </para> + + <programlisting>cat /proc/asound/card*/pcm*p/sub*/hw_params +access: RW_INTERLEAVED +format: S16_LE +subformat: STD +channels: 2 +rate: 44100 (44100/1) +period_size: 4096 +buffer_size: 16384</programlisting> + + <para> + Obey the "format" row, which indicates that the current + playback format is 16 bit (signed 16 bit integer, little + endian). + </para> + + <para> + Check list for bit-perfect playback: + </para> + + <itemizedlist> + <listitem> + <para> + Use the <link linkend="alsa_output">ALSA</link> output + plugin. + </para> + </listitem> + + <listitem> + <para> + Disable sound processing inside + <application>ALSA</application> by configuring a + "hardware" device (<parameter>hw:0,0</parameter> or + similar). + </para> + </listitem> + + <listitem> + <para> + Don't use software volume (setting <link + linkend="config_audio_outputs"><varname>mixer_type</varname></link>). + </para> + </listitem> + + <listitem> + <para> + Don't force <application>MPD</application> to use a + specific audio format (settings <link + linkend="config_audio_outputs"><varname>format</varname></link>, + <link + linkend="config_global_audio_format"><varname>audio_output_format</varname></link>). + </para> + </listitem> + + <listitem> + <para> + Verify that you are really doing bit-perfect playback + using <application>MPD</application>'s verbose log and + <filename>/proc/asound/card*/pcm*p/sub*/hw_params</filename>. + Some DACs can also indicate the audio format. + </para> + </listitem> + </itemizedlist> + </section> + + <section id="dsd"> + <title>Direct Stream Digital (DSD)</title> + + <para> + DSD (<ulink + url="https://en.wikipedia.org/wiki/Direct_Stream_Digital">Direct + Stream Digital</ulink>) is a digital format that stores audio + as a sequence of single-bit values at a very high sampling + rate. + </para> + + <para> + <application>MPD</application> understands the file formats + <link linkend="dsdiff_decoder"><filename>dff</filename></link> + and <link + linkend="dsf_decoder"><filename>dsf</filename></link>. There + are three ways to play back DSD: + </para> + + <itemizedlist> + <listitem> + <para> + Native DSD playback. Requires + <application>ALSA</application> 1.0.27.1 or later, a sound + driver/chip that supports DSD and of course a DAC that + supports DSD. + </para> + </listitem> + + <listitem> + <para> + DoP (DSD over PCM) playback. This wraps DSD inside fake + 24 bit PCM according to the <ulink + url="http://dsd-guide.com/dop-open-standard">DoP + standard</ulink>. Requires a DAC that supports DSD. No + support from ALSA and the sound chip required (except for + <link linkend="bit_perfect">bit-perfect</link> 24 bit PCM + support). + </para> + </listitem> + + <listitem> + <para> + Convert DSD to PCM on-the-fly. + </para> + </listitem> + </itemizedlist> + + <para> + Native DSD playback is used automatically if available. DoP + is only used if enabled explicitly using the <link + linkend="alsa_output"><varname>dop</varname></link> option, + because there is no way for <application>MPD</application> to + find out whether the DAC supports it. DSD to PCM conversion + is the fallback if DSD cannot be used directly. </para> </section> </chapter> - <chapter> + <chapter id="plugin_reference"> <title>Plugin reference</title> - <section> + <section id="database_plugins"> <title>Database plugins</title> <section> @@ -703,20 +1458,46 @@ systemctl start mpd.socket</programlisting> The path of the database file. </entry> </row> + + <row> + <entry> + <varname>cache_directory</varname> + </entry> + <entry> + The path of the cache directory for additional + storages mounted at runtime. This setting is + necessary for the <command>mount</command> protocol + command. + </entry> + </row> + + <row> + <entry> + <varname>compress</varname> + <parameter>yes|no</parameter> + </entry> + <entry> + Compress the database file using + <filename>gzip</filename>? Enabled by default (if + built with <filename>zlib</filename>). + </entry> + </row> </tbody> </tgroup> </informaltable> </section> - <section> + <section id="proxy_database"> <title><varname>proxy</varname></title> <para> - Provides access to the database of another MPD instance - using <filename>libmpdclient</filename>. This is useful - when you run mount the music directory via NFS/SMB, and the - file server already runs a MPD instance. Only the file - server needs to update the database. + Provides access to the database of another + <application>MPD</application> instance using + <filename>libmpdclient</filename>. This is useful when you + run mount the music directory via NFS/SMB, and the file + server already runs a <application>MPD</application> + instance. Only the file server needs to update the + database. </para> <informaltable> @@ -733,7 +1514,8 @@ systemctl start mpd.socket</programlisting> <varname>host</varname> </entry> <entry> - The host name of the "master" MPD instance. + The host name of the "master" + <application>MPD</application> instance. </entry> </row> <row> @@ -741,19 +1523,161 @@ systemctl start mpd.socket</programlisting> <varname>port</varname> </entry> <entry> - The port number of the "master" MPD instance. + The port number of the "master" + <application>MPD</application> instance. </entry> </row> </tbody> </tgroup> </informaltable> </section> + + <section> + <title><varname>upnp</varname></title> + + <para> + Provides access to UPnP media servers. + </para> + </section> </section> - <section> + <section id="storage_plugins"> + <title>Storage plugins</title> + + <section> + <title><varname>local</varname></title> + + <para> + The default plugin which gives + <application>MPD</application> access to local files. It is + used when <varname>music_directory</varname> refers to a + local directory. + </para> + </section> + + <section id="smbclient_storage"> + <title><varname>smbclient</varname></title> + + <para> + Load music files from a SMB/CIFS server. It used used when + <varname>music_directory</varname> contains a + <parameter>smb://</parameter> URI, for example + "<parameter>smb://myfileserver/Music</parameter>". + </para> + </section> + + <section id="nfs_storage"> + <title><varname>nfs</varname></title> + + <para> + Load music files from a NFS server. It used used when + <varname>music_directory</varname> contains a + <parameter>nfs://</parameter> URI according to <ulink + url="http://tools.ietf.org/html/rfc2224">RFC2224</ulink>, + for example "<parameter>nfs://servername/path</parameter>". + </para> + + <para> + This plugin uses <ulink + url="https://github.com/sahlberg/libnfs"><filename>libnfs</filename></ulink>, + which supports only NFS version 3. Since + <application>MPD</application> is not allowed to bind to + "privileged ports", the NFS server needs to enable the + "insecure" setting; example + <filename>/etc/exports</filename>: + </para> + + <programlisting>/srv/mp3 192.168.1.55(ro,insecure)</programlisting> + + <para> + Don't fear: "insecure" does not mean that your NFS server is + insecure. A few decades ago, people thought the concept of + "privileged ports" would make network services "secure", + which was a fallacy. The absence of this obsolete + "security" measure means little. + </para> + </section> + </section> + + <section id="neighbor_plugins"> + <title>Neighbor plugins</title> + + <section id="smbclient_neighbor"> + <title><varname>smbclient</varname></title> + + <para> + Provides a list of SMB/CIFS servers on the local network. + </para> + </section> + + <section id="upnp_neighbor"> + <title><varname>upnp</varname></title> + + <para> + Provides a list of UPnP servers on the local network. + </para> + </section> + </section> + + <section id="input_plugins"> <title>Input plugins</title> <section> + <title><varname>alsa</varname></title> + + <para> + Allows <application>MPD</application> on Linux to play audio + directly from a soundcard using the scheme + <filename>alsa://</filename>. Audio is formatted as 44.1 kHz + 16-bit stereo (CD format). Examples: + </para> + + <para> + <filename>mpc add alsa://</filename> plays audio from device hw:0,0 + </para> + <para> + <filename>mpc add alsa://hw:1,0</filename> plays audio from device + hw:1,0 + </para> + </section> + + <section> + <title><varname>cdio_paranoia</varname></title> + + <para> + Plays audio CDs. The URI has the form: + "<filename>cdda://[DEVICE][/TRACK]</filename>". The + simplest form <filename>cdda://</filename> plays the whole + disc in the default drive. + </para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>Setting</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <varname>default_byte_order</varname> + <parameter>little_endian|big_endian</parameter> + </entry> + <entry> + If the CD drive does not specify a byte order, + <application>MPD</application> assumes it is the + CPU's native byte order. This setting allows + overriding this. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </section> + + <section> <title><varname>curl</varname></title> <para> @@ -786,6 +1710,30 @@ systemctl start mpd.socket</programlisting> Configures proxy authentication. </entry> </row> + + <row> + <entry> + <varname>verify_peer</varname> + <parameter>yes|no</parameter> + </entry> + <entry> + Verify the peer's SSL certificate? <ulink + url="http://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYPEER.html">More + information</ulink>. + </entry> + </row> + + <row> + <entry> + <varname>verify_host</varname> + <parameter>yes|no</parameter> + </entry> + <entry> + Verify the certificate's name against host? <ulink + url="http://curl.haxx.se/libcurl/c/CURLOPT_SSL_VERIFYHOST.html">More + information</ulink>. + </entry> + </row> </tbody> </tgroup> </informaltable> @@ -808,45 +1756,54 @@ systemctl start mpd.socket</programlisting> </section> <section> - <title><varname>cdio_paranoia</varname></title> + <title><varname>nfs</varname></title> <para> - Plays audio CDs. The URI has the form: - "<filename>cdda://[DEVICE][/TRACK]</filename>". The - simplest form <filename>cdda://</filename> plays the whole - disc in the default drive. + Allows <application>MPD</application> to access files on + NFSv3 servers without actually mounting them (i.e. in + userspace, without help from the kernel's VFS layer). All + URIs with the <filename>nfs://</filename> scheme are used + according to <ulink + url="http://tools.ietf.org/html/rfc2224">RFC2224</ulink>. + Example: </para> - <informaltable> - <tgroup cols="2"> - <thead> - <row> - <entry>Setting</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <varname>default_byte_order</varname> - <parameter>little_endian|big_endian</parameter> - </entry> - <entry> - If the CD drive does not specify a byte order, MPD - assumes it is the CPU's native byte order. This - setting allows overriding this. - </entry> - </row> - </tbody> - </tgroup> - </informaltable> + <para> + <filename>mpc add nfs://servername/path/filename.ogg</filename> + </para> + + <para> + Note that this usually requires enabling the "insecure" flag + in the server's <filename>/etc/exports</filename> file, + because <application>MPD</application> cannot bind to + so-called "privileged" ports. Don't fear: this will not + make your file server insecure; the flag was named in a time + long ago when privileged ports were thought to be meaningful + for security. By today's standards, NFSv3 is not secure at + all, and if you believe it is, you're already doomed. + </para> + </section> + + <section> + <title><varname>smbclient</varname></title> + + <para> + Allows <application>MPD</application> to access files on + SMB/CIFS servers (e.g. Samba or Microsoft Windows). All + URIs with the <filename>smb://</filename> scheme are used. + Example: + </para> + + <para> + <filename>mpc add smb://servername/sharename/filename.ogg</filename> + </para> </section> </section> - <section> + <section id="decoder_plugins"> <title>Decoder plugins</title> - <section> + <section id="dsdiff_decoder"> <title><varname>dsdiff</varname></title> <para> @@ -869,7 +1826,7 @@ systemctl start mpd.socket</programlisting> </entry> <entry> Decode the least significant bit first. Default is - "no". + <parameter>no</parameter>. </entry> </row> </tbody> @@ -877,7 +1834,7 @@ systemctl start mpd.socket</programlisting> </informaltable> </section> - <section> + <section id="dsf_decoder"> <title><varname>dsf</varname></title> <para> @@ -890,7 +1847,8 @@ systemctl start mpd.socket</programlisting> <title><varname>fluidsynth</varname></title> <para> - MIDI decoder based on libfluidsynth. + MIDI decoder based on <ulink + url="http://www.fluidsynth.org/"><application>FluidSynth</application></ulink>. </para> <informaltable> @@ -930,7 +1888,8 @@ systemctl start mpd.socket</programlisting> <title><varname>mikmod</varname></title> <para> - Module player based on MikMod. + Module player based on <ulink + url="http://mikmod.sourceforge.net/"><application>MikMod</application></ulink>. </para> <informaltable> @@ -970,7 +1929,7 @@ systemctl start mpd.socket</programlisting> <title><varname>modplug</varname></title> <para> - Module player based on MODPlug. + Module player based on <application>MODPlug</application>. </para> <informaltable> @@ -1001,7 +1960,8 @@ systemctl start mpd.socket</programlisting> <title><varname>wildmidi</varname></title> <para> - MIDI decoder based on libwildmidi. + MIDI decoder based on <ulink + url="http://www.mindwerks.net/projects/wildmidi/"><application>libwildmidi</application></ulink>. </para> <informaltable> @@ -1029,14 +1989,15 @@ systemctl start mpd.socket</programlisting> </section> </section> - <section> + <section id="encoder_plugins"> <title>Encoder plugins</title> <section> <title><varname>flac</varname></title> <para> - Encodes into FLAC (lossless). + Encodes into <ulink + url="https://xiph.org/flac/">FLAC</ulink> (lossless). </para> <informaltable> @@ -1067,7 +2028,9 @@ systemctl start mpd.socket</programlisting> <title><varname>lame</varname></title> <para> - Encodes into MP3 using the LAME library. + Encodes into MP3 using the <ulink + url="http://lame.sourceforge.net/"><application>LAME</application></ulink> + library. </para> <informaltable> @@ -1112,10 +2075,42 @@ systemctl start mpd.socket</programlisting> </section> <section> + <title><varname>shine</varname></title> + + <para> + Encodes into MP3 using the <ulink + url="https://github.com/savonet/shine"><application>Shine</application></ulink> + library. + </para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>Setting</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <varname>bitrate</varname> + </entry> + <entry> + Sets the bit rate in kilobit per second. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </section> + + <section> <title><varname>twolame</varname></title> <para> - Encodes into MP2 using the <filename>twolame</filename> + Encodes into MP2 using the <ulink + url="http://www.twolame.org/"><application>TwoLAME</application></ulink> library. </para> @@ -1152,11 +2147,12 @@ systemctl start mpd.socket</programlisting> </informaltable> </section> - <section> + <section id="vorbis_encoder"> <title><varname>vorbis</varname></title> <para> - Encodes into Ogg Vorbis. + Encodes into <ulink url="http://www.vorbis.com/">Ogg + Vorbis</ulink>. </para> <informaltable> @@ -1201,14 +2197,17 @@ systemctl start mpd.socket</programlisting> </section> </section> - <section> + <section id="output_plugins"> <title>Output plugins</title> - <section> + <section id="alsa_output"> <title><varname>alsa</varname></title> <para> - The "Advanced Linux Sound Architecture" plugin uses + The <ulink + url="http://www.alsa-project.org/"><application>Advanced + Linux Sound Architecture</application> + (<application>ALSA</application>)</ulink> plugin uses <filename>libasound</filename>. It is recommended if you are using Linux. </para> @@ -1279,10 +2278,11 @@ systemctl start mpd.socket</programlisting> <entry> If set to <parameter>no</parameter>, then <filename>libasound</filename> will not attempt to - resample, handing the responsibility over to MPD. - It is recommended to let MPD resample (with - libsamplerate), because ALSA is quite poor at doing - so. + resample, handing the responsibility over to + <application>MPD</application>. It is recommended + to let <application>MPD</application> resample (with + <application>libsamplerate</application>), because + ALSA is quite poor at doing so. </entry> </row> <row> @@ -1310,15 +2310,15 @@ systemctl start mpd.socket</programlisting> </row> <row> <entry> - <varname>dsd_usb</varname> + <varname>dop</varname> <parameter>yes|no</parameter> </entry> <entry> If set to <parameter>yes</parameter>, then DSD over - USB according to the <ulink - url="http://www.sonore.us/DoP_openStandard_1v1.pdf">pro - posed standard by dCS and others</ulink> is enabled. This wraps - DSD samples in fake 24 bit PCM, and is understood by + PCM according to the <ulink + url="http://dsd-guide.com/dop-open-standard">DoP + standard</ulink> is enabled. This wraps DSD + samples in fake 24 bit PCM, and is understood by some DSD capable products, but may be harmful to other hardware. Therefore, the default is <parameter>no</parameter> and you can enable the @@ -1328,14 +2328,73 @@ systemctl start mpd.socket</programlisting> </tbody> </tgroup> </informaltable> + + <para> + The according hardware mixer plugin understands the + following settings: + </para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>Setting</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <varname>mixer_device</varname> + <parameter>DEVICE</parameter> + </entry> + <entry> + <para> + Sets the ALSA mixer device name, defaulting to + <parameter>default</parameter> which lets ALSA + pick a value. + </para> + </entry> + </row> + <row> + <entry> + <varname>mixer_control</varname> + <parameter>NAME</parameter> + </entry> + <entry> + <para> + Choose a mixer control, defaulting to + <parameter>PCM</parameter>. Type <command>amixer + scontrols</command> to get a list of available + mixer controls. + </para> + </entry> + </row> + <row> + <entry> + <varname>mixer_index</varname> + <parameter>NUMBER</parameter> + </entry> + <entry> + Choose a mixer control index. This is necessary if + there is more than one control with the same name. + Defaults to <parameter>0</parameter> (the first + one). + </entry> + </row> + </tbody> + </tgroup> + </informaltable> </section> <section> <title><varname>ao</varname></title> <para> - The <varname>ao</varname> plugin uses the portable - <filename>libao</filename> library. + The <varname>ao</varname> plugin uses the portable <ulink + url="https://www.xiph.org/ao/"><filename>libao</filename></ulink> + library. Use only if there is no native plugin for your + operating system. </para> <informaltable> @@ -1418,15 +2477,19 @@ systemctl start mpd.socket</programlisting> <entry> This specifies the path of the FIFO to write to. Must be an absolute path. If the path does not - exist, it will be created when MPD is started, and - removed when MPD is stopped. The FIFO will be - created with the same user and group as MPD is + exist, it will be created when + <application>MPD</application> is started, and + removed when <application>MPD</application> is + stopped. The FIFO will be created with the same + user and group as <application>MPD</application> is running as. Default permissions can be modified by - using the builtin shell command "umask". If a FIFO - already exists at the specified path it will be - reused, and will not be removed when MPD is stopped. - You can use the "mkfifo" command to create this, and - then you may modify the permissions to your liking. + using the builtin shell command + <filename>umask</filename>. If a FIFO already + exists at the specified path it will be reused, and + will not be removed when + <application>MPD</application> is stopped. You can + use the "mkfifo" command to create this, and then + you may modify the permissions to your liking. </entry> </row> </tbody> @@ -1438,7 +2501,8 @@ systemctl start mpd.socket</programlisting> <title><varname>jack</varname></title> <para> - The <varname>jack</varname> plugin connects to a JACK + The <varname>jack</varname> plugin connects to a <ulink + url="http://jackaudio.org/"><application>JACK</application></ulink> server. </para> @@ -1457,8 +2521,8 @@ systemctl start mpd.socket</programlisting> <parameter>NAME</parameter> </entry> <entry> - The name of the JACK client. Defaults to "Music - Player Daemon". + The name of the <application>JACK</application> + client. Defaults to "Music Player Daemon". </entry> </row> <row> @@ -1467,7 +2531,8 @@ systemctl start mpd.socket</programlisting> <parameter>NAME</parameter> </entry> <entry> - Optional name of the JACK server. + Optional name of the <application>JACK</application> + server. </entry> </row> <row> @@ -1478,7 +2543,8 @@ systemctl start mpd.socket</programlisting> <entry> If set to <parameter>yes</parameter>, then <filename>libjack</filename> will automatically - launch the JACK daemon. Disabled by default. + launch the <application>JACK</application> daemon. + Disabled by default. </entry> </row> <row> @@ -1487,10 +2553,10 @@ systemctl start mpd.socket</programlisting> <parameter>A,B</parameter> </entry> <entry> - The names of the JACK source ports to be created. - By default, the ports "left" and "right" are - created. To use more ports, you have to tweak this - option. + The names of the <application>JACK</application> + source ports to be created. By default, the ports + "left" and "right" are created. To use more ports, + you have to tweak this option. </entry> </row> <row> @@ -1499,7 +2565,8 @@ systemctl start mpd.socket</programlisting> <parameter>A,B</parameter> </entry> <entry> - The names of the JACK destination ports to connect to. + The names of the <application>JACK</application> + destination ports to connect to. </entry> </row> <row> @@ -1518,21 +2585,23 @@ systemctl start mpd.socket</programlisting> </informaltable> </section> - <section> + <section id="httpd_output"> <title><varname>httpd</varname></title> <para> The <varname>httpd</varname> plugin creates a HTTP server, - similar to ShoutCast / IceCast. HTTP streaming clients like - <filename>mplayer</filename> can connect to it. + similar to <ulink + url="http://www.shoutcast.com/"><application>ShoutCast</application></ulink> + / <ulink + url="http://icecast.org/"><application>IceCast</application></ulink>. + HTTP streaming clients like + <application>mplayer</application> can connect to it. </para> <para> - You must configure either <varname>quality</varname> or - <varname>bitrate</varname>. It is highly recommended to - configure a fixed <varname>format</varname>, because a - stream cannot switch its audio format on-the-fly when the - song changes. + It is highly recommended to configure a fixed + <varname>format</varname>, because a stream cannot switch + its audio format on-the-fly when the song changes. </para> <informaltable> @@ -1569,28 +2638,10 @@ systemctl start mpd.socket</programlisting> <parameter>NAME</parameter> </entry> <entry> - Chooses an encoder plugin, - e.g. <parameter>vorbis</parameter>. - </entry> - </row> - <row> - <entry> - <varname>quality</varname> - <parameter>Q</parameter> - </entry> - <entry> - Configures the encoder quality (for VBR) in the - range -1 .. 10. - </entry> - </row> - <row> - <entry> - <varname>bitrate</varname> - <parameter>BR</parameter> - </entry> - <entry> - Sets a constant encoder bit rate, in kilobit per - second. + Chooses an encoder plugin. A list of encoder + plugins can be found in the <link + linkend="encoder_plugins">encoder plugin + reference</link>. </entry> </row> <row> @@ -1642,7 +2693,7 @@ systemctl start mpd.socket</programlisting> </informaltable> </section> - <section> + <section id="oss_output"> <title><varname>oss</varname></title> <para> @@ -1650,6 +2701,13 @@ systemctl start mpd.socket</programlisting> platforms. </para> + <para> + On Linux, <application>OSS</application> has been superseded + by <application>ALSA</application>. Use the <link + linkend="alsa_output"><application>ALSA</application> output + plugin</link> instead of this one on Linux. + </para> + <informaltable> <tgroup cols="2"> <thead> @@ -1666,22 +2724,66 @@ systemctl start mpd.socket</programlisting> </entry> <entry> Sets the path of the PCM device. If not specified, - then MPD will attempt to open - <filename>/dev/sound/dsp</filename> and + then <application>MPD</application> will attempt to + open <filename>/dev/sound/dsp</filename> and <filename>/dev/dsp</filename>. </entry> </row> </tbody> </tgroup> </informaltable> + + <para> + The according hardware mixer plugin understands the + following settings: + </para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>Setting</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <varname>mixer_device</varname> + <parameter>DEVICE</parameter> + </entry> + <entry> + <para> + Sets the OSS mixer device path, defaulting to + <filename>/dev/mixer</filename>. + </para> + </entry> + </row> + <row> + <entry> + <varname>mixer_control</varname> + <parameter>NAME</parameter> + </entry> + <entry> + <para> + Choose a mixer control, defaulting to + <parameter>PCM</parameter>. + </para> + </entry> + </row> + </tbody> + </tgroup> + </informaltable> </section> <section> <title><varname>openal</varname></title> <para> - The "OpenAL" plugin uses <filename>libopenal</filename>. - It is supported on many platforms. + The "OpenAL" plugin uses <ulink + url="http://kcat.strangesoft.net/openal.html"><filename>libopenal</filename></ulink>. + It is supported on many platforms. Use only if there is no + native plugin for your operating system. </para> <informaltable> @@ -1748,11 +2850,12 @@ systemctl start mpd.socket</programlisting> </informaltable> </section> - <section> + <section id="pulse_output"> <title><varname>pulse</varname></title> <para> - The <varname>pulse</varname> plugin connects to a PulseAudio + The <varname>pulse</varname> plugin connects to a <ulink + url="http://www.freedesktop.org/wiki/Software/PulseAudio/"><application>PulseAudio</application></ulink> server. </para> @@ -1771,8 +2874,10 @@ systemctl start mpd.socket</programlisting> <parameter>HOSTNAME</parameter> </entry> <entry> - Sets the host name of the PulseAudio server. By - default, MPD connects to the local PulseAudio + Sets the host name of the + <application>PulseAudio</application> server. By + default, <application>MPD</application> connects to + the local <application>PulseAudio</application> server. </entry> </row> @@ -1782,8 +2887,9 @@ systemctl start mpd.socket</programlisting> <parameter>NAME</parameter> </entry> <entry> - Specifies the name of the PulseAudio sink MPD should - play on. + Specifies the name of the + <application>PulseAudio</application> sink + <application>MPD</application> should play on. </entry> </row> </tbody> @@ -1816,8 +2922,8 @@ systemctl start mpd.socket</programlisting> </entry> <entry> The host name of the RoarAudio server. If not - specified, then MPD will connect to the default - locations. + specified, then <application>MPD</application> will + connect to the default locations. </entry> </row> @@ -1827,8 +2933,9 @@ systemctl start mpd.socket</programlisting> <parameter>ROLE</parameter> </entry> <entry> - The "role" that MPD registers itself as in the - RoarAudio server. The default is "music". + The "role" that <application>MPD</application> + registers itself as in the RoarAudio server. The + default is "music". </entry> </row> </tbody> @@ -1841,13 +2948,8 @@ systemctl start mpd.socket</programlisting> <para> The <varname>recorder</varname> plugin writes the audio - played by MPD to a file. This may be useful for recording - radio streams. - </para> - - <para> - You must configure either <varname>quality</varname> or - <varname>bitrate</varname>. + played by <application>MPD</application> to a file. This + may be useful for recording radio streams. </para> <informaltable> @@ -1874,28 +2976,10 @@ systemctl start mpd.socket</programlisting> <parameter>NAME</parameter> </entry> <entry> - Chooses an encoder plugin, - e.g. <parameter>vorbis</parameter>. - </entry> - </row> - <row> - <entry> - <varname>quality</varname> - <parameter>Q</parameter> - </entry> - <entry> - Configures the encoder quality (for VBR) in the - range -1 .. 10. - </entry> - </row> - <row> - <entry> - <varname>bitrate</varname> - <parameter>BR</parameter> - </entry> - <entry> - Sets a constant encoder bit rate, in kilobit per - second. + Chooses an encoder plugin. A list of encoder + plugins can be found in the <link + linkend="encoder_plugins">encoder plugin + reference</link>. </entry> </row> </tbody> @@ -1903,12 +2987,15 @@ systemctl start mpd.socket</programlisting> </informaltable> </section> - <section> + <section id="shout_output"> <title><varname>shout</varname></title> <para> - The <varname>shout</varname> plugin connects to a ShoutCast - or IceCast server. It forwards tags to this server. + The <varname>shout</varname> plugin connects to a <ulink + url="http://www.shoutcast.com/"><application>ShoutCast</application></ulink> + or <ulink + url="http://icecast.org/"><application>IceCast</application></ulink> + server. It forwards tags to this server. </para> <para> @@ -1930,7 +3017,11 @@ systemctl start mpd.socket</programlisting> <parameter>HOSTNAME</parameter> </entry> <entry> - Sets the host name of the Shoutcast/Icecast server. + Sets the host name of the <ulink + url="http://www.shoutcast.com/"><application>ShoutCast</application></ulink> + / <ulink + url="http://icecast.org/"><application>IceCast</application></ulink> + server. </entry> </row> <row> @@ -1959,8 +3050,8 @@ systemctl start mpd.socket</programlisting> </entry> <entry> Specifies the protocol that wil be used to connect - to the icecast/shoutcast server. The default - is "<parameter>icecast2</parameter>". + to the server. The default is + "<parameter>icecast2</parameter>". </entry> </row> @@ -1970,7 +3061,8 @@ systemctl start mpd.socket</programlisting> <parameter>URI</parameter> </entry> <entry> - Mounts the MPD stream in the specified URI. + Mounts the <application>MPD</application> stream in + the specified URI. </entry> </row> <row> @@ -2036,7 +3128,7 @@ systemctl start mpd.socket</programlisting> </entry> <entry> Specifies whether the stream should be "public". - Default is "no". + Default is <parameter>no</parameter>. </entry> </row> <row> @@ -2045,10 +3137,11 @@ systemctl start mpd.socket</programlisting> <parameter>PLUGIN</parameter> </entry> <entry> - Sets the name of the encoder plugin. Default is - "vorbis". "vorbis" and "lame" are valid encoder - plugins (provided that you enabled them at compile - time). + Chooses an encoder plugin. Default is <link + linkend="vorbis_encoder"><parameter>vorbis</parameter></link>. + A list of encoder plugins can be found in the <link + linkend="encoder_plugins">encoder plugin + reference</link>. </entry> </row> </tbody> @@ -2089,7 +3182,7 @@ systemctl start mpd.socket</programlisting> </section> </section> - <section> + <section id="playlist_plugins"> <title>Playlist plugins</title> <section> |