diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/mpd.1 | 10 | ||||
| -rw-r--r-- | doc/mpd.conf.5 | 27 | ||||
| -rw-r--r-- | doc/mpdconf.example | 83 | ||||
| -rw-r--r-- | doc/protocol.xml | 119 | ||||
| -rw-r--r-- | doc/user.xml | 368 |
5 files changed, 514 insertions, 93 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..0784ea393 100644 --- a/doc/mpd.conf.5 +++ b/doc/mpd.conf.5 @@ -168,26 +168,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 @@ -285,6 +266,12 @@ whatever audio format is passed to the audio output. .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..3b9e460b1 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. @@ -179,6 +186,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 +199,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 +223,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): @@ -255,6 +277,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 +296,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 +353,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 +362,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..ca63eccd9 100644 --- a/doc/user.xml +++ b/doc/user.xml @@ -319,13 +319,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 +456,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 +570,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> @@ -694,6 +868,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 +983,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 +1213,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> |