From c6be661bb52b958f0442af56f5d1460c9153d604 Mon Sep 17 00:00:00 2001 From: Max Kellermann Date: Sun, 24 Aug 2014 12:42:00 +0200 Subject: doc/user: more markup --- doc/user.xml | 362 ++++++++++++++++++++++++++++++++++------------------------- 1 file changed, 206 insertions(+), 156 deletions(-) diff --git a/doc/user.xml b/doc/user.xml index f78f2803f..0087ea33d 100644 --- a/doc/user.xml +++ b/doc/user.xml @@ -13,10 +13,10 @@ - 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. + 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. @@ -26,8 +26,8 @@ - MPD supports also Gapless playback, buffered audio output, and - crossfading! + MPD supports also gapless playback, + buffered audio output, and crossfading! @@ -42,23 +42,26 @@ 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 MPD. + Most operating systems have a MPD + package, which is very easy to install.
Installing on Debian/Ubuntu - Install the package mpd via APT: + Install the package MPD via APT: apt-get install mpd - 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, MPD by + default looks for music in + /var/lib/mpd/music/; this may not be + correct. Look at your /etc/mpd.conf + file...
@@ -67,8 +70,9 @@ Download the source tarball from the MPD home - page and unpack it: + url="http://www.musicpd.org/download.html">the + MPD home page and unpack + it: tar xf mpd-version.tar.xz @@ -135,14 +139,15 @@ apt-get install g++ automake autoconf \ Using systemd, you can launch - mpd on demand when the first client + MPD on demand when the first client attempts to connect. - MPD comes with two systemd unit files: a - "service" unit and a "socket" unit. These will only be - installed when MPD was configured with + MPD comes with two + systemd unit files: a "service" + unit and a "socket" unit. These will only be installed when + MPD was configured with --with-systemdsystemunitdir=/lib/systemd. @@ -154,8 +159,8 @@ apt-get install g++ automake autoconf \ systemctl start mpd.socket - In this configuration, mpd will ignore - the bind_to_address and + In this configuration, MPD will + ignore the bind_to_address and port settings. @@ -170,16 +175,18 @@ systemctl start mpd.socket When you play local files, you should organize them within a directory called the "music directory". This is configured in - MPD with the music_directory setting. + MPD with the + music_directory setting. - By default, MPD follows symbolic links in the music directory. - This behavior can be switched off: - follow_outside_symlinks controls whether - MPD follows links pointing to files outside of the music - directory, and follow_inside_symlinks lets - you disable symlinks to files inside the music directory. + By default, MPD follows symbolic + links in the music directory. This behavior can be switched + off: follow_outside_symlinks controls + whether MPD follows links pointing + to files outside of the music directory, and + follow_inside_symlinks lets you disable + symlinks to files inside the music directory. @@ -365,10 +372,11 @@ systemctl start mpd.socket 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 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. @@ -457,8 +465,8 @@ systemctl start mpd.socket Specifies whether this audio output is enabled when - MPD is started. By default, all audio outputs are - enabled. + MPD is started. By + default, all audio outputs are enabled. @@ -467,10 +475,10 @@ systemctl start mpd.socket yes|no - 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 - httpd output plugin. + 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 httpd output plugin. @@ -479,10 +487,12 @@ systemctl start mpd.socket yes|no - 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 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. @@ -494,8 +504,9 @@ systemctl start mpd.socket 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. + (none). By default, the + hardware mixer is used for devices which support it, + and none for the others. @@ -505,10 +516,11 @@ systemctl start mpd.socket 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. + software, which uses an + internal software volume control. + mixer uses the configured + (hardware) mixer control. none + disables replay gain on this audio output. @@ -578,7 +590,8 @@ systemctl start mpd.socket Playlist plugins are used to load remote playlists. This is - not related to MPD's playlist directory. + not related to MPD's playlist + directory. @@ -643,9 +656,10 @@ systemctl start mpd.socket The setting audio_output_format forces - MPD to use one audio format for all outputs. Doing that is - usually not a good idea. The values are the same as in - format in the + MPD to use one audio format for + all outputs. Doing that is usually not a good idea. The + values are the same as in format in the audio_output section. @@ -661,9 +675,11 @@ systemctl start mpd.socket 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 MPD's CPU usage. - Since MPD comes with high quality defaults, it may appear - that MPD consumes more CPU than other software. + component that is responsible for most of + MPD's CPU usage. Since + MPD comes with high quality + defaults, it may appear that MPD + consumes more CPU than other software. @@ -675,7 +691,7 @@ systemctl start mpd.socket libsamplerate + url="http://www.mega-nerd.com/SRC/">libsamplerate a.k.a. Secret Rabbit Code (SRC). @@ -683,7 +699,7 @@ systemctl start mpd.socket libsoxr, + url="http://sourceforge.net/projects/soxr/">libsoxr, the SoX Resampler library @@ -691,15 +707,16 @@ systemctl start mpd.socket internal: low CPU usage, but very poor quality. This is - the fallback if MPD was compiled without an external - resampler. + the fallback if MPD was + compiled without an external resampler. The setting samplerate_converter controls - how MPD shall resample music. Possible values: + how MPD shall resample music. + Possible values: @@ -730,7 +747,8 @@ systemctl start mpd.socket "soxr very high" - Use libsoxr with "Very High Quality" setting. + Use libsoxr with "Very + High Quality" setting. @@ -740,7 +758,8 @@ systemctl start mpd.socket "soxr" - Use libsoxr with "High Quality" setting. + Use libsoxr with "High + Quality" setting. @@ -749,7 +768,8 @@ systemctl start mpd.socket "soxr medium" - Use libsoxr with "Medium Quality" setting. + Use libsoxr with "Medium + Quality" setting. @@ -758,7 +778,8 @@ systemctl start mpd.socket "soxr low" - Use libsoxr with "Low Quality" setting. + Use libsoxr with "Low + Quality" setting. @@ -767,7 +788,8 @@ systemctl start mpd.socket "soxr quick" - Use libsoxr with "Quick" setting. + Use libsoxr with "Quick" + setting. @@ -777,8 +799,9 @@ systemctl start mpd.socket "0" - libsamplerate: Band limited sinc interpolation, best - quality, 97dB SNR, 96% BW. + libsamplerate: Band + limited sinc interpolation, best quality, 97dB SNR, + 96% BW. @@ -788,8 +811,9 @@ systemctl start mpd.socket "1" - libsamplerate: Band limited sinc interpolation, - medium quality, 97dB SNR, 90% BW. + libsamplerate: Band + limited sinc interpolation, medium quality, 97dB + SNR, 90% BW. @@ -799,8 +823,9 @@ systemctl start mpd.socket "2" - libsamplerate: Band limited sinc interpolation, - fastest, 97dB SNR, 80% BW. + libsamplerate: Band + limited sinc interpolation, fastest, 97dB SNR, 80% + BW. @@ -810,8 +835,9 @@ systemctl start mpd.socket "3" - libsamplerate: Zero order hold interpolator, very - fast, very poor quality with audible distortions. + libsamplerate: Zero order + hold interpolator, very fast, very poor quality with + audible distortions. @@ -821,8 +847,8 @@ systemctl start mpd.socket "4" - libsamplerate: Linear interpolator, very fast, poor - quality. + libsamplerate: Linear + interpolator, very fast, poor quality. @@ -833,14 +859,15 @@ systemctl start mpd.socket - Using MPD + Using <application>MPD</application>
The client - After you have installed, configured and started MPD, you - choose a client to control the playback. + After you have installed, configured and started + MPD, you choose a client to control + the playback. @@ -851,7 +878,8 @@ systemctl start mpd.socket - The MPD + The MPD Wiki contains an extensive list of clients to choose from. @@ -862,10 +890,11 @@ systemctl start mpd.socket 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 mpc: + 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 + mpc: mpc update @@ -887,9 +916,9 @@ systemctl start mpd.socket 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 MPD. To play + a song, add it to the queue and start playback. Most clients + offer an interface to edit the queue.
@@ -946,11 +975,13 @@ systemctl start mpd.socket <varname>proxy</varname> - Provides access to the database of another MPD instance - using libmpdclient. 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 + MPD instance using + libmpdclient. 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. @@ -967,7 +998,8 @@ systemctl start mpd.socket host - The host name of the "master" MPD instance. + The host name of the "master" + MPD instance. @@ -975,7 +1007,8 @@ systemctl start mpd.socket port - The port number of the "master" MPD instance. + The port number of the "master" + MPD instance. @@ -999,9 +1032,10 @@ systemctl start mpd.socket <varname>local</varname> - The default plugin which gives MPD access to local files. - It is used when music_directory refers to - a local directory. + The default plugin which gives + MPD access to local files. It is + used when music_directory refers to a + local directory. @@ -1036,9 +1070,10 @@ systemctl start mpd.socket <varname>alsa</varname> - Allows MPD on Linux to play audio directly from a soundcard using - the scheme alsa://. Audio is formatted as - 44.1 kHz 16-bit stereo (CD format). Examples: + Allows MPD on Linux to play audio + directly from a soundcard using the scheme + alsa://. Audio is formatted as 44.1 kHz + 16-bit stereo (CD format). Examples: @@ -1075,9 +1110,10 @@ systemctl start mpd.socket little_endian|big_endian - 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. + 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. @@ -1227,11 +1263,11 @@ systemctl start mpd.socket <varname>nfs</varname> - Allows MPD 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 - nfs:// scheme are used according to - MPD 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 nfs:// scheme are used + according to RFC2224. Example: @@ -1243,12 +1279,12 @@ systemctl start mpd.socket Note that this usually requires enabling the "insecure" flag in the server's /etc/exports file, - because MPD 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. + because MPD 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. @@ -1256,9 +1292,10 @@ systemctl start mpd.socket <varname>smbclient</varname> - Allows MPD to access files on SMB/CIFS servers (e.g. Samba - or Microsoft Windows). All URIs with the - smb:// scheme are used. Example: + Allows MPD to access files on + SMB/CIFS servers (e.g. Samba or Microsoft Windows). All + URIs with the smb:// scheme are used. + Example: @@ -1293,7 +1330,7 @@ systemctl start mpd.socket Decode the least significant bit first. Default is - "no". + no. @@ -1732,10 +1769,11 @@ systemctl start mpd.socket If set to no, then libasound 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 + MPD. It is recommended + to let MPD resample (with + libsamplerate), because + ALSA is quite poor at doing so. @@ -1928,15 +1966,19 @@ systemctl start mpd.socket 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 + MPD is started, and + removed when MPD is + stopped. The FIFO will be created with the same + user and group as MPD 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 + 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. @@ -1948,8 +1990,8 @@ systemctl start mpd.socket <varname>jack</varname> - The jack plugin connects to a JACK - server. + The jack plugin connects to a + JACK server. @@ -1967,8 +2009,8 @@ systemctl start mpd.socket NAME - The name of the JACK client. Defaults to "Music - Player Daemon". + The name of the JACK + client. Defaults to "Music Player Daemon". @@ -1977,7 +2019,8 @@ systemctl start mpd.socket NAME - Optional name of the JACK server. + Optional name of the JACK + server. @@ -1988,7 +2031,8 @@ systemctl start mpd.socket If set to yes, then libjack will automatically - launch the JACK daemon. Disabled by default. + launch the JACK daemon. + Disabled by default. @@ -1997,10 +2041,10 @@ systemctl start mpd.socket A,B - 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 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. @@ -2009,7 +2053,8 @@ systemctl start mpd.socket A,B - The names of the JACK destination ports to connect to. + The names of the JACK + destination ports to connect to. @@ -2033,8 +2078,9 @@ systemctl start mpd.socket The httpd plugin creates a HTTP server, - similar to ShoutCast / IceCast. HTTP streaming clients like - mplayer can connect to it. + similar to ShoutCast / + IceCast. HTTP streaming clients + like mplayer can connect to it. @@ -2176,8 +2222,8 @@ systemctl start mpd.socket Sets the path of the PCM device. If not specified, - then MPD will attempt to open - /dev/sound/dsp and + then MPD will attempt to + open /dev/sound/dsp and /dev/dsp. @@ -2324,8 +2370,8 @@ systemctl start mpd.socket Sets the host name of the PulseAudio server. By - default, MPD connects to the local PulseAudio - server. + default, MPD connects to + the local PulseAudio server. @@ -2334,8 +2380,8 @@ systemctl start mpd.socket NAME - Specifies the name of the PulseAudio sink MPD should - play on. + Specifies the name of the PulseAudio sink + MPD should play on. @@ -2368,8 +2414,8 @@ systemctl start mpd.socket The host name of the RoarAudio server. If not - specified, then MPD will connect to the default - locations. + specified, then MPD will + connect to the default locations. @@ -2379,8 +2425,9 @@ systemctl start mpd.socket ROLE - The "role" that MPD registers itself as in the - RoarAudio server. The default is "music". + The "role" that MPD + registers itself as in the RoarAudio server. The + default is "music". @@ -2393,8 +2440,8 @@ systemctl start mpd.socket The recorder plugin writes the audio - played by MPD to a file. This may be useful for recording - radio streams. + played by MPD to a file. This + may be useful for recording radio streams. @@ -2522,7 +2569,8 @@ systemctl start mpd.socket URI - Mounts the MPD stream in the specified URI. + Mounts the MPD stream in + the specified URI. @@ -2588,7 +2636,7 @@ systemctl start mpd.socket Specifies whether the stream should be "public". - Default is "no". + Default is no. @@ -2737,7 +2785,9 @@ mpc load soundcloud://url/https://soundcloud.com/ARTIST/TRACK-NAME client_id - User apikey/client_id can override the MPD token provided by SoundCloud. + User apikey/client_id can override the + MPD token provided by + SoundCloud. -- cgit v1.2.3