diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/mpd.1 | 10 | ||||
| -rw-r--r-- | doc/mpd.conf.5 | 36 | ||||
| -rw-r--r-- | doc/mpdconf.example | 88 | ||||
| -rw-r--r-- | doc/protocol.xml | 119 | ||||
| -rw-r--r-- | doc/user.xml | 395 |
5 files changed, 551 insertions, 97 deletions
@@ -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..c64dfb94c 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,26 +170,7 @@ 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> 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 @@ -265,6 +248,11 @@ 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. .SH REQUIRED AUDIO OUTPUT PARAMETERS .TP .B type <type> @@ -280,11 +268,19 @@ 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 .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". diff --git a/doc/mpdconf.example b/doc/mpdconf.example index 11b14bd93..6da84fc37 100644 --- a/doc/mpdconf.example +++ b/doc/mpdconf.example @@ -61,6 +61,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 +109,10 @@ # #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" ############################################################################### @@ -179,6 +190,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 +203,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 +227,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): @@ -226,6 +252,7 @@ input { ## 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 +282,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 +301,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 +358,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 +367,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..eb48185e9 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 @@ -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"> @@ -223,15 +243,15 @@ <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 +317,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> @@ -471,23 +501,39 @@ </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> + </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 +694,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 +719,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> @@ -1118,6 +1164,23 @@ OK </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> + </cmdsynopsis> + </term> + <listitem> + <para> + Finds songs in the db that are exactly + <varname>WHAT</varname> and adds them to current playlist. + <varname>TYPE</varname> can be any tag supported by MPD. + <varname>WHAT</varname> is what to find. + </para> + </listitem> + </varlistentry> <varlistentry id="command_list"> <term> <cmdsynopsis> @@ -1231,6 +1294,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> diff --git a/doc/user.xml b/doc/user.xml index 6c3f5edeb..2e4261d3e 100644 --- a/doc/user.xml +++ b/doc/user.xml @@ -300,10 +300,19 @@ 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> </entry> </row> <row> @@ -319,13 +328,134 @@ cd mpd-version</programlisting> </row> <row> <entry> - <varname>mixer_enabled</varname> + <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> + </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 +465,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,15 +579,6 @@ cd mpd-version</programlisting> </section> <section> - <title><varname>lastfm</varname></title> - - <para> - Plays last.fm radio. This plugin is experimental, and will - be superseded by a better solution in MPD 0.16. - </para> - </section> - - <section> <title><varname>mms</varname></title> <para> @@ -620,6 +803,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 +887,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 +1002,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 +1232,73 @@ 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>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> |