diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/doxygen.conf | 2 | ||||
| -rw-r--r-- | doc/mpd.1 | 10 | ||||
| -rw-r--r-- | doc/mpd.conf.5 | 57 | ||||
| -rw-r--r-- | doc/mpdconf.example | 100 | ||||
| -rw-r--r-- | doc/protocol.xml | 238 | ||||
| -rw-r--r-- | doc/sticker.xml | 91 | ||||
| -rw-r--r-- | doc/user.xml | 553 |
7 files changed, 841 insertions, 210 deletions
diff --git a/doc/doxygen.conf b/doc/doxygen.conf index 625e070ae..ddece77e8 100644 --- a/doc/doxygen.conf +++ b/doc/doxygen.conf @@ -534,7 +534,7 @@ WARN_LOGFILE = # directories like "/usr/src/myproject". Separate the files or directories # with spaces. -INPUT = src +INPUT = src/ # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is @@ -25,17 +25,11 @@ Output a brief help message. Kill the currently running mpd session. The pid_file parameter must be specified in the config file for this to work. .TP -.BI --create-db -Force (re)creation of database. -.TP -.BI --no-create-db -Do not create database, even if it doesn't exist. -.TP .BI --no-daemon Don't detach from console. .TP -.BI --stdout -Print messages to stdout and stderr. +.BI --stderr +Print messages stderr. .TP .BI --verbose Verbose logging. diff --git a/doc/mpd.conf.5 b/doc/mpd.conf.5 index 776fdbefd..4cddd7ba9 100644 --- a/doc/mpd.conf.5 +++ b/doc/mpd.conf.5 @@ -129,6 +129,8 @@ 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 @@ -168,31 +170,14 @@ only choice) if MPD was compiled without libsamplerate. 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 mixer_type <alsa, oss, software, hardware or disabled> -This specifies which mixer to use. The default is hardware and depends on -what audio output support mpd was built with. Options alsa and oss are -legacy and should not be used in new configs, but when set mixer_device -and mixer_control will apply. -.TP -.B mixer_device <mixer dev> -This specifies which mixer to use. The default for oss is -"/dev/mixer"; the default for alsa is "default". This global option is -deprecated and should not be used. Look at the mixer_device option of -corresponding output device instead. -.TP -.B mixer_control <mixer ctrl> -This specifies which mixer control to use (sometimes referred to as -the "device"). Examples of mixer controls are PCM, Line1, Master, -etc. An example for OSS is "Pcm", and an example for alsa is -"PCM". This global option is deprecated and should not be used. Look -at the mixer_control option of corresponding output device instead. -.TP -.B replaygain <album or track> +.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 volume using the album's ReplayGain tags, while setting it to "track" will -adjust it using the track ReplayGain tags. Currently only FLAC, Ogg Vorbis, -Musepack, and MP3 (through ID3v2 ReplayGain tags, not APEv2) are supported. +adjust it using the track ReplayGain tags. "auto" uses the track ReplayGain +tags if random play is activated otherwise the album ReplayGain tags. Currently +only FLAC, Ogg Vorbis, Musepack, and MP3 (through ID3v2 ReplayGain tags, not +APEv2) are supported. .TP .B replaygain_preamp <-15 to 15> This is the gain (in dB) applied to songs with ReplayGain tags. @@ -265,6 +250,15 @@ 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. +.TP +.B auto_update <yes or no> +This specifies the wheter to support automatic update of music database when +files are changed in music_directory. The default is to disable autoupdate +of database. +.TP +.B auto_update_depth <N> +Limit the depth of the directories being watched, 0 means only watch +the music directory itself. There is no limit by default. .SH REQUIRED AUDIO OUTPUT PARAMETERS .TP .B type <type> @@ -280,11 +274,25 @@ This specifies the sample rate, bits per sample, and number of channels of audio that is sent to the audio output device. See documentation for the \fBaudio_output_format\fP parameter for more details. The default is to use whatever audio format is passed to the audio output. +Any of the three attributes may be an asterisk to specify that this +attribute should not be enforced +.TP +.B replay_gain_handler <software, mixer or none> +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. .SH OPTIONAL ALSA OUTPUT PARAMETERS .TP .B device <dev> This specifies the device to use for audio output. The default is "default". .TP +.B mixer_type <hardware, software or none> +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. +.TP .B mixer_device <mixer dev> This specifies which mixer to use. The default is "default". To use the second sound card in a system, use "hw:1". @@ -352,13 +360,12 @@ after another until it successfully establishes a connection. .TP .B sink <sink> The sink to output to. The default is to let PulseAudio choose a sink. -.SH REQUIRED JACK OUTPUT PARAMETERS +.SH OPTIONAL JACK OUTPUT PARAMETERS .TP -.B name <name> +.B client_name <name> The client name to use when connecting to JACK. The output ports <name>:left and <name>:right will also be created for the left and right channels, respectively. -.SH OPTIONAL JACK OUTPUT PARAMETERS .TP .B ports <left_port,right_port> This specifies the left and right ports to connect to for the left and right diff --git a/doc/mpdconf.example b/doc/mpdconf.example index 11b14bd93..b14337c76 100644 --- a/doc/mpdconf.example +++ b/doc/mpdconf.example @@ -49,6 +49,11 @@ # #state_file "~/.mpd/state" # +# The location of the sticker database. This is a database which +# manages dynamic information attached to songs. +# +#sticker_file "~/.mpd/sticker.sql" +# ############################################################################### @@ -61,6 +66,13 @@ # #user "nobody" # +# This setting specifies the group that MPD will run as. If not specified +# primary group of user specified with "user" setting will be used (if set). +# This is useful if MPD needs to be a member of group such as "audio" to +# have permission to use sound card. +# +#group "nogroup" +# # This setting sets the address for the daemon to listen on. Careful attention # should be paid if this is assigned to anything other then the default, any. # This setting can deny access to control of the daemon. @@ -102,6 +114,16 @@ # #metadata_to_use "artist,album,title,track,name,genre,date,composer,performer,disc" # +# This setting enables automatic update of MPD's database when files in +# music_directory are changed. +# +#auto_update "yes" +# +# Limit the depth of the directories being watched, 0 means only watch +# the music directory itself. There is no limit by default. +# +#auto_update_depth "3" +# ############################################################################### @@ -179,6 +201,7 @@ input { # name "My ALSA Device" ## device "hw:0,0" # optional ## format "44100:16:2" # optional +## mixer_type "hardware" # optional ## mixer_device "default" # optional ## mixer_control "PCM" # optional ## mixer_index "0" # optional @@ -191,6 +214,7 @@ input { # name "My OSS Device" ## device "/dev/dsp" # optional ## format "44100:16:2" # optional +## mixer_type "hardware" # optional ## mixer_device "/dev/mixer" # optional ## mixer_control "PCM" # optional #} @@ -214,6 +238,19 @@ input { ## genre "jazz" # optional ## public "no" # optional ## timeout "2" # optional +## mixer_type "software" # optional +#} +# +# An example of a recorder output: +# +#audio_output { +# type "recorder" +# name "My recorder" +# encoder "vorbis" # optional, vorbis or lame +# path "/var/lib/mpd/recorder/mpd.ogg" +## quality "5.0" # do not define if bitrate is defined +# bitrate "128" # do not define if quality is defined +# format "44100:16:1" #} # # An example of a httpd output (built-in HTTP streaming server): @@ -223,9 +260,11 @@ input { # name "My HTTP Stream" # encoder "vorbis" # optional, vorbis or lame # port "8000" +# bind_to_address "0.0.0.0" # optional, IPv4 or IPv6 ## quality "5.0" # do not define if bitrate is defined # bitrate "128" # do not define if quality is defined # format "44100:16:1" +# max_clients "0" # optional 0=no limit #} # # An example of a pulseaudio output (streaming to a remote pulseaudio server) @@ -255,6 +294,7 @@ input { #audio_output { # type "null" # name "My Null Output" +# mixer_type "none" # optional #} # # This setting will change all decoded audio to be converted to the specified @@ -273,38 +313,11 @@ input { ############################################################################### -# Volume control mixer ######################################################## -# -# These are the global volume control settings. By default, this setting will -# be detected to the available audio output device, with preference going to -# hardware mixing. Hardware and software mixers for individual audio_output -# sections cannot yet be mixed. -# -# An example for controlling an ALSA, OSS or Pulseaudio mixer; If this -# setting is used other sound applications will be affected by the volume -# being controlled by MPD. -# -#mixer_type "hardware" -# -# An example for controlling all mixers through software. This will control -# all controls, even if the mixer is not supported by the device and will not -# affect any other sound producing applications. -# -#mixer_type "software" -# -# This example will not allow MPD to touch the mixer at all and will disable -# all volume controls. -# -#mixer_type "disabled" -# -############################################################################### - - # Normalization automatic volume adjustments ################################## # # This setting specifies the type of ReplayGain to use. This setting can have -# the argument "album" or "track". See <http://www.replaygain.org> for more -# details. This setting is disabled by default. +# the argument "off", "album" or "track". See <http://www.replaygain.org> +# for more details. This setting is off by default. # #replaygain "album" # @@ -357,8 +370,7 @@ input { # Character Encoding ########################################################## # # If file or directory names do not display correctly for your locale then you -# may need to modify this setting. After modification of this setting mpd -# --create-db must be run to change the database. +# may need to modify this setting. # #filesystem_charset "UTF-8" # @@ -367,3 +379,29 @@ input { #id3v1_encoding "ISO-8859-1" # ############################################################################### + + +# SIDPlay decoder ############################################################# +# +# songlength_database: +# Location of your songlengths file, as distributed with the HVSC. +# The sidplay plugin checks this for matching MD5 fingerprints. +# See http://www.c64.org/HVSC/DOCUMENTS/Songlengths.faq +# +# default_songlength: +# This is the default playing time in seconds for songs not in the +# songlength database, or in case you're not using a database. +# A value of 0 means play indefinitely. +# +# filter: +# Turns the SID filter emulation on or off. +# +#decoder { +# plugin "sidplay" +# songlength_database "/media/C64Music/DOCUMENTS/Songlengths.txt" +# default_songlength "120" +# filter "true" +#} +# +############################################################################### + diff --git a/doc/protocol.xml b/doc/protocol.xml index 2bc7d55ae..3eb5aa932 100644 --- a/doc/protocol.xml +++ b/doc/protocol.xml @@ -67,6 +67,20 @@ successful command executed in the command list. </para> </section> + + <section> + <title>Ranges</title> + + <para> + Some commands (e.g. <link + linkend="command_delete"><command>delete</command></link>) + allow specifying a range in the form + <parameter>START:END</parameter> (the <varname>END</varname> + item is not included in the range, similar to ranges in the + Python programming language). If <varname>END</varname> is + omitted, then the maximum possible value is assumed. + </para> + </section> </chapter> <chapter> @@ -123,7 +137,7 @@ </term> <listitem> <para> - <footnote id="since_0_14"><simpara>Since MPD 0.14</simpara></footnote> + <footnote id="since_0_14"><simpara>Introduced with MPD 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 @@ -139,6 +153,15 @@ </listitem> <listitem> <para> + <returnvalue>update</returnvalue>: a database update + has started or finished. If the database was + modified during the update, the + <returnvalue>database</returnvalue> event is also + emitted. + </para> + </listitem> + <listitem> + <para> <returnvalue>stored_playlist</returnvalue>: a stored playlist has been modified, renamed, created or deleted @@ -172,7 +195,7 @@ <para> <returnvalue>options</returnvalue>: options like <option>repeat</option>, <option>random</option>, - <option>crossfade</option> + <option>crossfade</option>, replay gain </para> </listitem> </itemizedlist> @@ -191,9 +214,6 @@ MPD will only send notifications when something changed in one of the specified subsytems. </para> - <simpara> - Since <application>MPD</application> 0.14 - </simpara> </listitem> </varlistentry> <varlistentry id="command_status"> @@ -221,17 +241,23 @@ </para> </listitem> <listitem> + <para> + <varname>random</varname>: + <returnvalue>0 or 1</returnvalue> + </para> + </listitem> + <listitem> <para> <varname>single</varname>: + <footnote id="since_0_15"><simpara>Introduced with MPD 0.15</simpara></footnote> <returnvalue>0 or 1</returnvalue> - <footnote id="since_0_15"><simpara>Since MPD 0.15</simpara></footnote> </para> </listitem> <listitem> <para> <varname>consume</varname>: - <returnvalue>0 or 1</returnvalue> <footnoteref linkend="since_0_15"/> + <returnvalue>0 or 1</returnvalue> </para> </listitem> <listitem> @@ -297,6 +323,16 @@ </listitem> <listitem> <para> + <varname>elapsed</varname>: + <footnote id="since_0_16"><simpara>Introduced with MPD 0.16</simpara></footnote> + <returnvalue> + Total time elapsed within the current song, but + with higher resolution. + </returnvalue> + </para> + </listitem> + <listitem> + <para> <varname>bitrate</varname>: <returnvalue>instantaneous bitrate in kbps</returnvalue> @@ -310,6 +346,18 @@ </listitem> <listitem> <para> + <varname>mixrampdb</varname>: + <returnvalue>mixramp threshold in dB</returnvalue> + </para> + </listitem> + <listitem> + <para> + <varname>mixrampdelay</varname>: + <returnvalue>mixrampdelay in seconds</returnvalue> + </para> + </listitem> + <listitem> + <para> <varname>audio</varname>: <returnvalue>sampleRate:bits:channels</returnvalue> </para> @@ -412,6 +460,32 @@ </para> </listitem> </varlistentry> + <varlistentry id="command_mixrampdb"> + <term> + <cmdsynopsis> + <command>mixrampdb</command> + <arg choice="req"><replaceable>deciBels</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Sets the threshold at which songs will be overlapped. Like crossfading but doesn't fade the track volume, just overlaps. The songs need to have MixRamp tags added by an external tool. 0dB is the normalized maximum volume so use negative values, I prefer -17dB. In the absence of mixramp tags crossfading will be used. See http://sourceforge.net/projects/mixramp + </para> + </listitem> + </varlistentry> + <varlistentry id="command_mixrampdelay"> + <term> + <cmdsynopsis> + <command>mixrampdelay</command> + <arg choice="req"><replaceable>SECONDS</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Additional time subtracted from the overlap calculated by mixrampdb. A value of "nan" disables MixRamp overlapping and falls back to crossfading. + </para> + </listitem> + </varlistentry> <varlistentry id="command_random"> <term> <cmdsynopsis> @@ -471,23 +545,43 @@ </para> </listitem> </varlistentry> - <varlistentry id="command_volume"> + <varlistentry id="command_replay_gain_mode"> <term> <cmdsynopsis> - <command>volume</command> - <arg choice="req"><replaceable>CHANGE</replaceable></arg> + <command>replay_gain_mode</command> + <arg choice="req"><replaceable>MODE</replaceable></arg> </cmdsynopsis> </term> <listitem> <para> - Changes volume by amount <varname>CHANGE</varname>. + Sets the replay gain mode. One of + <parameter>off</parameter>, + <parameter>track</parameter>, + <parameter>album</parameter>. + </para> + <para> + Changing the mode during playback may take several + seconds, because the new settings does not affect the + buffered data. + </para> + <para> + This command triggers the + <returnvalue>options</returnvalue> idle event. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_replay_gain_status"> + <term> + <cmdsynopsis> + <command>replay_gain_status</command> + </cmdsynopsis> + </term> + <listitem> + <para> + Prints replay gain options. Currently, only the + variable <varname>replay_gain_mode</varname> is + returned. </para> - <note> - <para> - <command>volume</command> is deprecated, use - <command>setvol</command> instead. - </para> - </note> </listitem> </varlistentry> </variablelist> @@ -648,10 +742,7 @@ </para> <para> <varname>URI</varname> is always a single file or - URL. <varname>POSITION</varname> is optional, a - negative number means it is relative to the currently - playing song in the playlist (if there is one). - For example: + URL. For example: </para> <screen> addid "foo.mp3" @@ -676,7 +767,10 @@ OK <term> <cmdsynopsis> <command>delete</command> - <arg choice="req"><replaceable>SONGPOS</replaceable></arg> + <group> + <arg choice="req"><replaceable>POS</replaceable></arg> + <arg choice="req"><replaceable>START:END</replaceable></arg> + </group> </cmdsynopsis> </term> <listitem> @@ -910,6 +1004,20 @@ OK <section> <title>Stored playlists</title> + <para> + Playlists are stored inside the configured playlist directory. + They are addressed with their file name (without the directory + and without the <filename>.m3u</filename> suffix). + </para> + + <para> + Some of the commands described in this section can be used to + run playlist plugins instead of the hard-coded simple + <filename>m3u</filename> parser. They can access playlists in + the music directory (relative path including the suffix) or + remote playlists (absolute URI with a supported scheme). + </para> + <variablelist> <varlistentry id="command_listplaylist"> <term> @@ -920,8 +1028,8 @@ OK </term> <listitem> <para> - Lists the files in the playlist - <filename>NAME.m3u</filename>. + Lists the songs in the playlist. Playlist plugins are + supported. </para> </listitem> </varlistentry> @@ -934,7 +1042,8 @@ OK </term> <listitem> <para> - Lists songs in the playlist <filename>NAME.m3u</filename>. + Lists the songs with metadata in the playlist. Playlist + plugins are supported. </para> </listitem> </varlistentry> @@ -966,8 +1075,8 @@ OK </term> <listitem> <para> - Loads the playlist <filename>NAME.m3u</filename> from - the playlist directory. + Loads the playlist into the current queue. Playlist + plugins are supported. </para> </listitem> </varlistentry> @@ -1105,16 +1214,35 @@ OK <command>find</command> <arg choice="req"><replaceable>TYPE</replaceable></arg> <arg choice="req"><replaceable>WHAT</replaceable></arg> + <arg choice="opt"><replaceable>...</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <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 two special + parameters — <parameter>file</parameter> to search by + full path (relative to database root), and + <parameter>any</parameter> to match against all + available tags. <varname>WHAT</varname> is what to find. + </para> + </listitem> + </varlistentry> + <varlistentry id="command_findadd"> + <term> + <cmdsynopsis> + <command>findadd</command> + <arg choice="req"><replaceable>TYPE</replaceable></arg> + <arg choice="req"><replaceable>WHAT</replaceable></arg> + <arg choice="opt"><replaceable>...</replaceable></arg> </cmdsynopsis> </term> <listitem> <para> Finds songs in the db that are exactly - <varname>WHAT</varname>. <varname>TYPE</varname> should - be <parameter>album</parameter>, - <parameter>artist</parameter>, or - <parameter>title</parameter>. <varname>WHAT</varname> - is what to find. + <varname>WHAT</varname> and adds them to current playlist. + Parameters have the same meaning as for <command>find</command>. </para> </listitem> </varlistentry> @@ -1129,7 +1257,8 @@ OK <listitem> <para> Lists all tags of the specified type. - <varname>TYPE</varname> should be album or artist. + <varname>TYPE</varname> can be any tag supported by MPD or + <parameter>file</parameter>. </para> <para> <varname>ARTIST</varname> is an optional parameter when @@ -1192,17 +1321,15 @@ OK <command>search</command> <arg choice="req"><replaceable>TYPE</replaceable></arg> <arg choice="req"><replaceable>WHAT</replaceable></arg> + <arg choice="opt"><replaceable>...</replaceable></arg> </cmdsynopsis> </term> <listitem> <para> Searches for any song that contains - <varname>WHAT</varname>. <varname>TYPE</varname> can be - <parameter>title</parameter>, - <parameter>artist</parameter>, - <parameter>album</parameter> or - <parameter>filename</parameter>. Search is not case - sensitive. + <varname>WHAT</varname>. Parameters have the same meaning + as for <command>find</command>, except that search is not + case sensitive. </para> </listitem> </varlistentry> @@ -1231,6 +1358,20 @@ OK </para> </listitem> </varlistentry> + <varlistentry id="command_rescan"> + <term> + <cmdsynopsis> + <command>rescan</command> + <arg choice="opt"><replaceable>URI</replaceable></arg> + </cmdsynopsis> + </term> + <listitem> + <para> + Same as <command>update</command>, but also rescans + unmodified files. + </para> + </listitem> + </varlistentry> </variablelist> </section> @@ -1508,6 +1649,25 @@ OK </para> </listitem> </varlistentry> + <varlistentry id="command_decoders"> + <term> + <cmdsynopsis> + <command>decoders</command> + </cmdsynopsis> + </term> + <listitem> + <para> + Print a list of decoder plugins, followed by their + supported suffixes and MIME types. Example response: + </para> + <programlisting>plugin: mad +suffix: mp3 +suffix: mp2 +mime_type: audio/mpeg +plugin: mpcdec +suffix: mpc</programlisting> + </listitem> + </varlistentry> </variablelist> </section> </chapter> diff --git a/doc/sticker.xml b/doc/sticker.xml deleted file mode 100644 index 0e27ba8cf..000000000 --- a/doc/sticker.xml +++ /dev/null @@ -1,91 +0,0 @@ -<?xml version='1.0' encoding="utf-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "docbook/dtd/xml/4.2/docbookx.dtd"> -<book> - <title>The Music Player Daemon Sticker Database</title> - - <chapter> - <title>Introduction to MPD's Sticker Database</title> - <para> - This document shell give a short guideline for recommended tags - for use in MPD's Sticker Database. - MPD's Sticker Database is a subsystem that enables users to add - custom tags. MPD does not alter the media files. - </para> - </chapter> - - <chapter> - <title>Guideline for recommended tags</title> - <para> - Since there is no standard for tags in media files, this - document is trying to give you some help deciding what tags to - use. The selection of these tags tries to cover the most - widely used tags. This way the tags might still work in other - players, if you sync the database with your original media - files. - Keep in mind that we stick with lower case tags with underscores - instead of spaces. If there will be a Sync tool in future - its easy to change this on the fly, if needed. - </para> - - <variablelist> - <varlistentry> - <term><varname>rating</varname></term> - <listitem> - <para> - Will store a rating value from 1 (worst) to 5 (best) for a - given song. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>album_rating</varname></term> - <listitem> - <para> - Will store a rating value from 1 (worst) to 5 (best) for a - given album. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>style</varname></term> - <listitem> - <para> - This tag is used to keep the Genre tag clean, by now - having 1000's of genres. Instead you define a Main Genre - for each file and can make a more specific - description. This should be one Keyword like "Post Punk" - or "Progressive Death Metal" An Alternative name for this - tag is "Subgenre", time will tell which one gets more - support. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>lyrics</varname></term> - <listitem> - <para> - This one is self explaining. This gives the option to - store lyrics of a song where they belong to: mapped to the - song - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term><varname>similar_artists</varname> (Comma seperated list of artists)</term> - <listitem> - <para> - This tag enables a last.fm alike aproach which will still - work when being offline Keep in mind, that this tag is - absolutely non-standard! I am not aware of any other - player that uses a comparable tag. - </para> - </listitem> - </varlistentry> - </variablelist> - </chapter> -</book> diff --git a/doc/user.xml b/doc/user.xml index 6c3f5edeb..c783a981b 100644 --- a/doc/user.xml +++ b/doc/user.xml @@ -300,10 +300,30 @@ cd mpd-version</programlisting> <varname>format</varname> </entry> <entry> - Always open the audio output with the specified audio - format (samplerate:bits:channels), regardless of the - format of the input file. This is optional for most - plugins. + <para> + Always open the audio output with the specified audio + format (samplerate:bits:channels), regardless of the + format of the input file. This is optional for most + plugins. + </para> + <para> + Any of the three attributes may be an asterisk to + specify that this attribute should not be enforced, + example: <parameter>48000:16:*</parameter>. + <parameter>*:*:*</parameter> is equal to not having + a <varname>format</varname> specification. + </para> + <para> + The following values are valid for + <varname>bits</varname>: <varname>8</varname> + (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). + </para> </entry> </row> <row> @@ -319,13 +339,159 @@ cd mpd-version</programlisting> </row> <row> <entry> - <varname>mixer_enabled</varname> + <varname>always_on</varname> + <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 accidently stopped. + </entry> + </row> + <row> + <entry> + <varname>mixer_type</varname> + <parameter>hardware|software|none</parameter> + </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. + </entry> + </row> + <row> + <entry> + <varname>replay_gain_handler</varname> + <parameter>software|mixer|none</parameter> + </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. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </section> + + <section> + <title>Configuring filters</title> + + <para> + Filters are plugins which modify an audio stream. + </para> + + <para> + To configure a filter, add a <varname>filter</varname> block + to <filename>mpd.conf</filename>: + </para> + + <programlisting>filter { + plugin "volume" + name "software volume" +} + </programlisting> + + <para> + The following table lists the <varname>filter</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> + <row> + <entry> + <varname>name</varname> + </entry> + <entry> + The name of the filter. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </section> + + <section> + <title>Configuring playlist plugins</title> + + <para> + Playlist plugins are used to load remote playlists. This is + not related to MPD's playlist directory. + </para> + + <para> + To configure a filter, add a + <varname>playlist_plugin</varname> block to + <filename>mpd.conf</filename>: + </para> + + <programlisting>playlist_plugin { + name "m3u" + enabled "true" +} + </programlisting> + + <para> + The following table lists the + <varname>playlist_plugin</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>name</varname> + </entry> + <entry> + The name of the plugin. + </entry> + </row> + <row> + <entry> + <varname>enabled</varname> <parameter>yes|no</parameter> </entry> <entry> - Specifies whether the hardware mixer of this audio - output should be used. By default, all hardware - mixers are enabled if available. + Allows you to disable a input plugin without + recompiling. By default, all plugins are enabled. </entry> </row> </tbody> @@ -335,6 +501,68 @@ cd mpd-version</programlisting> </chapter> <chapter> + <title>Using MPD</title> + + <section> + <title>The client</title> + + <para> + After you have installed, configured and started MPD, you + choose a client to control the playback. + </para> + + <para> + The most basic client is <filename>mpc</filename>, which + provides a command line interface. It is useful in shell + scripts. Many people bind specific <filename>mpc</filename> + commands to hotkeys. + </para> + + <para> + The <ulink url="http://mpd.wikia.com/wiki/Clients">MPD + Wiki</ulink> contains an extensive list of clients to choose + from. + </para> + </section> + + <section> + <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>: + </para> + + <programlisting>mpc update</programlisting> + + <para> + Depending on the size of your music collection and the speed + of the storage, this can take a while. + </para> + + <para> + To exclude a file from the update, create a file called + <filename>.mpdignore</filename> in its parent directory. Each + line of that file may contain a list of shell wildcards. + </para> + </section> + + <section> + <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. + </para> + </section> + </chapter> + + <chapter> <title>Plugin reference</title> <section> @@ -387,20 +615,45 @@ cd mpd-version</programlisting> </section> <section> - <title><varname>lastfm</varname></title> + <title><varname>mms</varname></title> <para> - Plays last.fm radio. This plugin is experimental, and will - be superseded by a better solution in MPD 0.16. + Plays streams with the MMS protocol. </para> </section> + </section> + + <section> + <title>Decoder plugins</title> <section> - <title><varname>mms</varname></title> + <title><varname>mikmod</varname></title> <para> - Plays streams with the MMS protocol. + Module player based on MikMod. </para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>Setting</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <varname>sample_rate</varname> + </entry> + <entry> + Sets the sample rate generated by + <filename>libmikmod</filename>. Default is 44100. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> </section> </section> @@ -542,6 +795,81 @@ cd mpd-version</programlisting> The <varname>jack</varname> plugin connects to a JACK server. </para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>Setting</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <varname>client_name</varname> + <parameter>NAME</parameter> + </entry> + <entry> + The name of the JACK client. Defaults to "Music + Player Daemon". + </entry> + </row> + <row> + <entry> + <varname>server_name</varname> + <parameter>NAME</parameter> + </entry> + <entry> + Optional name of the JACK server. + </entry> + </row> + <row> + <entry> + <varname>autostart</varname> + <parameter>yes|no</parameter> + </entry> + <entry> + If set to <parameter>yes</parameter>, then + <filename>libjack</filename> will automatically + launch the JACK daemon. Disabled by default. + </entry> + </row> + <row> + <entry> + <varname>source_ports</varname> + <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. + </entry> + </row> + <row> + <entry> + <varname>destination_ports</varname> + <parameter>A,B</parameter> + </entry> + <entry> + The names of the JACK destination ports to connect to. + </entry> + </row> + <row> + <entry> + <varname>ringbuffer_size</varname> + <parameter>NBYTES</parameter> + </entry> + <entry> + Sets the size of the ring buffer for each channel. + Do not configure this value unless you know what + you're doing. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> </section> <section> @@ -586,8 +914,17 @@ cd mpd-version</programlisting> <parameter>P</parameter> </entry> <entry> - Binds the HTTP server to the specified port (on all - interfaces). + Binds the HTTP server to the specified port. + </entry> + </row> + <row> + <entry> + <varname>bind_to_address</varname> + <parameter>ADDR</parameter> + </entry> + <entry> + Binds the HTTP server to the specified address (IPv4 or + IPv6). Multiple addresses in parallel are not supported. </entry> </row> <row> @@ -620,6 +957,16 @@ cd mpd-version</programlisting> second. </entry> </row> + <row> + <entry> + <varname>max_clients</varname> + <parameter>MC</parameter> + </entry> + <entry> + Sets a limit, number of concurrent clients. When set + to 0 no limit will apply. + </entry> + </row> </tbody> </tgroup> </informaltable> @@ -694,6 +1041,39 @@ cd mpd-version</programlisting> </section> <section> + <title><varname>openal</varname></title> + + <para> + The "OpenAL" plugin uses <filename>libopenal</filename>. + It is supported on many platforms. + </para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>Setting</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <varname>device</varname> + <parameter>NAME</parameter> + </entry> + <entry> + Sets the device which should be used. This can be + any valid OpenAL device name. If not specified, then + <filename>libopenal</filename> will choose a default device. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </section> + + <section> <title><varname>osx</varname></title> <para> @@ -776,6 +1156,73 @@ cd mpd-version</programlisting> </section> <section> + <title><varname>recorder</varname></title> + + <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>. + </para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>Setting</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <varname>path</varname> + <parameter>P</parameter> + </entry> + <entry> + Write to this file. + </entry> + </row> + <row> + <entry> + <varname>encoder</varname> + <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. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </section> + + <section> <title><varname>shout</varname></title> <para> @@ -939,5 +1386,81 @@ cd mpd-version</programlisting> </informaltable> </section> </section> + + <section> + <title>Playlist plugins</title> + + <section> + <title><varname>lastfm</varname></title> + + <para> + Plays last.fm radio. + </para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>Setting</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <varname>user</varname> + <parameter>USERNAME</parameter> + </entry> + <entry> + The last.fm user name. + </entry> + </row> + <row> + <entry> + <varname>password</varname> + <parameter>PWD</parameter> + </entry> + <entry> + The last.fm password. + </entry> + </row> + </tbody> + </tgroup> + </informaltable> + </section> + + <section> + <title><varname>m3u</varname></title> + + <para> + Reads <filename>.m3u</filename> playlist files. + </para> + </section> + + <section> + <title><varname>extm3u</varname></title> + + <para> + Reads extended <filename>.m3u</filename> playlist files. + </para> + </section> + + <section> + <title><varname>pls</varname></title> + + <para> + Reads <filename>.pls</filename> playlist files. + </para> + </section> + + <section> + <title><varname>xspf</varname></title> + + <para> + Reads <ulink url="http://www.xspf.org/">XSPF</ulink> + playlist files. + </para> + </section> + </section> </chapter> </book> |