| blob | e1e62eb92232f633e6bb4195518c655ee83ed5af |
1 <?xml version='1.0' encoding="utf-8"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "docbook/dtd/xml/4.2/docbookx.dtd">
4 <book>
5 <title>The Music Player Daemon - User's Manual</title>
7 <chapter>
8 <title>Introduction</title>
10 <para>
11 This document is work in progress. Most of it may be incomplete
12 yet. Please help!
13 </para>
15 <para>
16 MPD (Music Player Daemon) is, as the name suggests, a server
17 software allowing you to remotely play your music, handle
18 playlists, deliver music (HTTP STREAMS with various
19 sub-protocols) and organizze playlists.
20 </para>
22 <para>
23 It has been written with minimal resource usage and stability in
24 mind! Infact, it runs fine on a Pentium 75, allowing you to use
25 your cheap old PC to create a stereo system!
26 </para>
28 <para>
29 MPD supports also Gapless playback, buffered audio output, and
30 crossfading!
31 </para>
33 <para>
34 The separate client and server design allows users to choose a
35 user interface that best suites their tastes independently of
36 the underlying daemon, which actually plays music!
37 </para>
38 </chapter>
40 <chapter>
41 <title>Installation</title>
43 <para>
44 We recommend that you use the software installation routines of
45 your distribution to install MPD. Most operating systems have a
46 MPD package, which is very easy to install.
47 </para>
49 <section>
50 <title>Installing on Debian/Ubuntu</title>
52 <para>
53 Install the package <filename>mpd</filename> via APT:
54 </para>
56 <programlisting>apt-get install mpd</programlisting>
58 <para>
59 When installed this way, MPD by default looks for music in
60 /var/lib/mpd/music/; this may not be correct. Look at your
61 /etc/mpd.conf file...
62 </para>
63 </section>
65 <section>
66 <title>Compiling from source</title>
68 <para>
69 Download the source tarball from <ulink
70 url="http://mpd.wikia.com/wiki/Server">the MPD home
71 page</ulink> and unpack it:
72 </para>
74 <programlisting>tar xjf mpd-version.tar.bz
75 cd mpd-version</programlisting>
77 <para>
78 Make sure that all the required libraries and build tools are
79 installed. The <filename>INSTALL</filename> file has a list.
80 </para>
82 <para>
83 Now configure the source tree:
84 </para>
86 <programlisting>./configure</programlisting>
88 <para>
89 The <parameter>--help</parameter> argument shows a list of
90 compile-time options. When everything is ready and
91 configured, compile:
92 </para>
94 <programlisting>make</programlisting>
96 <para>
97 And install:
98 </para>
100 <programlisting>make install</programlisting>
101 </section>
102 </chapter>
104 <chapter>
105 <title>Configuration</title>
107 <section>
108 <title>Configuring the music directory</title>
110 <para>
111 When you play local files, you should organize them within a
112 directory called the "music directory". This is configured in
113 MPD with the <varname>music_directory</varname> setting.
114 </para>
116 <para>
117 By default, MPD follows symbolic links in the music directory.
118 This behavior can be switched off:
119 <varname>follow_outside_symlinks</varname> controls whether
120 MPD follows links pointing to files outside of the music
121 directory, and <varname>follow_inside_symlinks</varname> lets
122 you disable symlinks to files inside the music directory.
123 </para>
124 </section>
126 <section>
127 <title>Configuring input plugins</title>
129 <para>
130 To configure an input plugin, add a <varname>input</varname>
131 block to <filename>mpd.conf</filename>:
132 </para>
134 <programlisting>input {
135 plugin "lastfm"
136 user "foo"
137 password "bar"
138 }
139 </programlisting>
141 <para>
142 The following table lists the <varname>input</varname> options
143 valid for all plugins:
144 </para>
146 <informaltable>
147 <tgroup cols="2">
148 <thead>
149 <row>
150 <entry>
151 Name
152 </entry>
153 <entry>
154 Description
155 </entry>
156 </row>
157 </thead>
158 <tbody>
159 <row>
160 <entry>
161 <varname>plugin</varname>
162 </entry>
163 <entry>
164 The name of the plugin.
165 </entry>
166 </row>
167 <row>
168 <entry>
169 <varname>enabled</varname>
170 <parameter>yes|no</parameter>
171 </entry>
172 <entry>
173 Allows you to disable a input plugin without
174 recompiling. By default, all plugins are enabled.
175 </entry>
176 </row>
177 </tbody>
178 </tgroup>
179 </informaltable>
180 </section>
182 <section>
183 <title>Configuring decoder plugins</title>
185 <para>
186 Most decoder plugins do not need any special configuration.
187 To configure a decoder, add a <varname>decoder</varname> block
188 to <filename>mpd.conf</filename>:
189 </para>
191 <programlisting>decoder {
192 plugin "wildmidi"
193 config_file "/etc/timidity/timidity.cfg"
194 }
195 </programlisting>
197 <para>
198 The following table lists the <varname>decoder</varname>
199 options valid for all plugins:
200 </para>
202 <informaltable>
203 <tgroup cols="2">
204 <thead>
205 <row>
206 <entry>
207 Name
208 </entry>
209 <entry>
210 Description
211 </entry>
212 </row>
213 </thead>
214 <tbody>
215 <row>
216 <entry>
217 <varname>plugin</varname>
218 </entry>
219 <entry>
220 The name of the plugin.
221 </entry>
222 </row>
223 <row>
224 <entry>
225 <varname>enabled</varname>
226 <parameter>yes|no</parameter>
227 </entry>
228 <entry>
229 Allows you to disable a decoder plugin without
230 recompiling. By default, all plugins are enabled.
231 </entry>
232 </row>
233 </tbody>
234 </tgroup>
235 </informaltable>
236 </section>
238 <section>
239 <title>Configuring audio outputs</title>
241 <para>
242 Audio outputs are devices which actually play the audio chunks
243 produced by MPD. You can configure any number of audio output
244 devices, but there must be at least one. If none is
245 configured, MPD attempts to auto-detect. Usually, this works
246 quite well with ALSA, OSS and on Mac OS X.
247 </para>
249 <para>
250 To configure an audio output manually, add an
251 <varname>audio_output</varname> block to
252 <filename>mpd.conf</filename>:
253 </para>
255 <programlisting>audio_output {
256 type "alsa"
257 name "my ALSA device"
258 device "hw:0"
259 }
260 </programlisting>
262 <para>
263 The following table lists the <varname>audio_output</varname>
264 options valid for all plugins:
265 </para>
267 <informaltable>
268 <tgroup cols="2">
269 <thead>
270 <row>
271 <entry>
272 Name
273 </entry>
274 <entry>
275 Description
276 </entry>
277 </row>
278 </thead>
279 <tbody>
280 <row>
281 <entry>
282 <varname>type</varname>
283 </entry>
284 <entry>
285 The name of the plugin.
286 </entry>
287 </row>
288 <row>
289 <entry>
290 <varname>name</varname>
291 </entry>
292 <entry>
293 The name of the audio output. It is visible to the
294 client. Some plugins also use it internally, e.g. as
295 a name registered in the PULSE server.
296 </entry>
297 </row>
298 <row>
299 <entry>
300 <varname>format</varname>
301 </entry>
302 <entry>
303 <para>
304 Always open the audio output with the specified audio
305 format (samplerate:bits:channels), regardless of the
306 format of the input file. This is optional for most
307 plugins.
308 </para>
309 <para>
310 Any of the three attributes may be an asterisk to
311 specify that this attribute should not be enforced,
312 example: <parameter>48000:16:*</parameter>.
313 <parameter>*:*:*</parameter> is equal to not having
314 a <varname>format</varname> specification.
315 </para>
316 <para>
317 The following values are valid for
318 <varname>bits</varname>: <varname>8</varname>
319 (signed 8 bit integer samples),
320 <varname>16</varname>, <varname>24</varname> (signed
321 24 bit integer samples padded to 32 bit),
322 <varname>24_3</varname> (signed 24 bit integer
323 samples, no padding, 3 bytes per sample),
324 <varname>32</varname> (signed 32 bit integer
325 samples).
326 </para>
327 </entry>
328 </row>
329 <row>
330 <entry>
331 <varname>enabled</varname>
332 <parameter>yes|no</parameter>
333 </entry>
334 <entry>
335 Specifies whether this audio output is enabled when
336 MPD is started. By default, all audio outputs are
337 enabled.
338 </entry>
339 </row>
340 <row>
341 <entry>
342 <varname>always_on</varname>
343 <parameter>yes|no</parameter>
344 </entry>
345 <entry>
346 If set to "yes", then MPD attempts to keep this audio
347 output always open. This may be useful for streaming
348 servers, when you don't want to disconnect all
349 listeners even when playback is accidently stopped.
350 </entry>
351 </row>
352 <row>
353 <entry>
354 <varname>mixer_type</varname>
355 <parameter>hardware|software|none</parameter>
356 </entry>
357 <entry>
358 Specifies which mixer should be used for this audio
359 output: the hardware mixer (available for ALSA, OSS
360 and PulseAudio), the software mixer or no mixer
361 ("none"). By default, the hardware mixer is used for
362 devices which support it, and none for the others.
363 </entry>
364 </row>
365 <row>
366 <entry>
367 <varname>replay_gain_handler</varname>
368 <parameter>software|mixer|none</parameter>
369 </entry>
370 <entry>
371 Specifies how replay gain is applied. The default is
372 "software", which uses an internal software volume
373 control. "mixer" uses the configured (hardware) mixer
374 control. "none" disables replay gain on this audio
375 output.
376 </entry>
377 </row>
378 </tbody>
379 </tgroup>
380 </informaltable>
381 </section>
383 <section>
384 <title>Configuring filters</title>
386 <para>
387 Filters are plugins which modify an audio stream.
388 </para>
390 <para>
391 To configure a filter, add a <varname>filter</varname> block
392 to <filename>mpd.conf</filename>:
393 </para>
395 <programlisting>filter {
396 plugin "volume"
397 name "software volume"
398 }
399 </programlisting>
401 <para>
402 The following table lists the <varname>filter</varname>
403 options valid for all plugins:
404 </para>
406 <informaltable>
407 <tgroup cols="2">
408 <thead>
409 <row>
410 <entry>
411 Name
412 </entry>
413 <entry>
414 Description
415 </entry>
416 </row>
417 </thead>
418 <tbody>
419 <row>
420 <entry>
421 <varname>plugin</varname>
422 </entry>
423 <entry>
424 The name of the plugin.
425 </entry>
426 </row>
427 <row>
428 <entry>
429 <varname>name</varname>
430 </entry>
431 <entry>
432 The name of the filter.
433 </entry>
434 </row>
435 </tbody>
436 </tgroup>
437 </informaltable>
438 </section>
440 <section>
441 <title>Configuring playlist plugins</title>
443 <para>
444 Playlist plugins are used to load remote playlists. This is
445 not related to MPD's playlist directory.
446 </para>
448 <para>
449 To configure a filter, add a
450 <varname>playlist_plugin</varname> block to
451 <filename>mpd.conf</filename>:
452 </para>
454 <programlisting>playlist_plugin {
455 name "m3u"
456 enabled "true"
457 }
458 </programlisting>
460 <para>
461 The following table lists the
462 <varname>playlist_plugin</varname> options valid for all
463 plugins:
464 </para>
466 <informaltable>
467 <tgroup cols="2">
468 <thead>
469 <row>
470 <entry>
471 Name
472 </entry>
473 <entry>
474 Description
475 </entry>
476 </row>
477 </thead>
478 <tbody>
479 <row>
480 <entry>
481 <varname>name</varname>
482 </entry>
483 <entry>
484 The name of the plugin.
485 </entry>
486 </row>
487 <row>
488 <entry>
489 <varname>enabled</varname>
490 <parameter>yes|no</parameter>
491 </entry>
492 <entry>
493 Allows you to disable a input plugin without
494 recompiling. By default, all plugins are enabled.
495 </entry>
496 </row>
497 </tbody>
498 </tgroup>
499 </informaltable>
500 </section>
501 </chapter>
503 <chapter>
504 <title>Using MPD</title>
506 <section>
507 <title>The client</title>
509 <para>
510 After you have installed, configured and started MPD, you
511 choose a client to control the playback.
512 </para>
514 <para>
515 The most basic client is <filename>mpc</filename>, which
516 provides a command line interface. It is useful in shell
517 scripts. Many people bind specific <filename>mpc</filename>
518 commands to hotkeys.
519 </para>
521 <para>
522 The <ulink url="http://mpd.wikia.com/wiki/Clients">MPD
523 Wiki</ulink> contains an extensive list of clients to choose
524 from.
525 </para>
526 </section>
528 <section>
529 <title>The music directory and the database</title>
531 <para>
532 The "music directory" is where you store your music files.
533 MPD stores all relevant meta information about all songs in
534 its "database". Whenever you add, modify or remove songs in
535 the music directory, you have to update the database, for
536 example with <filename>mpc</filename>:
537 </para>
539 <programlisting>mpc update</programlisting>
541 <para>
542 Depending on the size of your music collection and the speed
543 of the storage, this can take a while.
544 </para>
546 <para>
547 To exclude a file from the update, create a file called
548 <filename>.mpdignore</filename> in its parent directory. Each
549 line of that file may contain a list of shell wildcards.
550 </para>
551 </section>
553 <section>
554 <title>The queue</title>
556 <para>
557 The queue (sometimes called "current playlist") is a list of
558 songs to be played by MPD. To play a song, add it to the
559 queue and start playback. Most clients offer an interface to
560 edit the queue.
561 </para>
562 </section>
563 </chapter>
565 <chapter>
566 <title>Plugin reference</title>
568 <section>
569 <title>Input plugins</title>
571 <section>
572 <title><varname>curl</varname></title>
574 <para>
575 Opens remote files or streams over HTTP.
576 </para>
578 <informaltable>
579 <tgroup cols="2">
580 <thead>
581 <row>
582 <entry>Setting</entry>
583 <entry>Description</entry>
584 </row>
585 </thead>
586 <tbody>
587 <row>
588 <entry>
589 <varname>proxy</varname>
590 </entry>
591 <entry>
592 Sets the address of the HTTP proxy server.
593 </entry>
594 </row>
595 <row>
596 <entry>
597 <varname>proxy_user</varname>,
598 <varname>proxy_password</varname>
599 </entry>
600 <entry>
601 Configures proxy authentication.
602 </entry>
603 </row>
604 </tbody>
605 </tgroup>
606 </informaltable>
607 </section>
609 <section>
610 <title><varname>file</varname></title>
612 <para>
613 Opens local files.
614 </para>
615 </section>
617 <section>
618 <title><varname>mms</varname></title>
620 <para>
621 Plays streams with the MMS protocol.
622 </para>
623 </section>
624 </section>
626 <section>
627 <title>Decoder plugins</title>
629 <section>
630 <title><varname>mikmod</varname></title>
632 <para>
633 Module player based on MikMod.
634 </para>
636 <informaltable>
637 <tgroup cols="2">
638 <thead>
639 <row>
640 <entry>Setting</entry>
641 <entry>Description</entry>
642 </row>
643 </thead>
644 <tbody>
645 <row>
646 <entry>
647 <varname>sample_rate</varname>
648 </entry>
649 <entry>
650 Sets the sample rate generated by
651 <filename>libmikmod</filename>. Default is 44100.
652 </entry>
653 </row>
654 </tbody>
655 </tgroup>
656 </informaltable>
657 </section>
658 </section>
660 <section>
661 <title>Output plugins</title>
663 <section>
664 <title><varname>alsa</varname></title>
666 <para>
667 The "Advanced Linux Sound Architecture" plugin uses
668 <filename>libasound</filename>. It is recommended if you
669 are using Linux.
670 </para>
672 <informaltable>
673 <tgroup cols="2">
674 <thead>
675 <row>
676 <entry>Setting</entry>
677 <entry>Description</entry>
678 </row>
679 </thead>
680 <tbody>
681 <row>
682 <entry>
683 <varname>device</varname>
684 <parameter>NAME</parameter>
685 </entry>
686 <entry>
687 Sets the device which should be used. This can be
688 any valid ALSA device name. The default value is
689 "default", which makes
690 <filename>libasound</filename> choose a device. It
691 is recommended to use a "hw" or "plughw" device,
692 because otherwise, <filename>libasound</filename>
693 automatically enables "dmix", which has major
694 disadvantages (fixed sample rate, poor resampler,
695 ...).
696 </entry>
697 </row>
698 <row>
699 <entry>
700 <varname>use_mmap</varname>
701 <parameter>yes|no</parameter>
702 </entry>
703 <entry>
704 If set to <parameter>yes</parameter>, then
705 <filename>libasound</filename> will try to use
706 memory mapped I/O.
707 </entry>
708 </row>
709 <row>
710 <entry>
711 <varname>buffer_time</varname>
712 <parameter>US</parameter>
713 </entry>
714 <entry>
715 Sets the device's buffer time in microseconds.
716 Don't change unless you know what you're doing.
717 </entry>
718 </row>
719 <row>
720 <entry>
721 <varname>period_time</varname>
722 <parameter>US</parameter>
723 </entry>
724 <entry>
725 Sets the device's period time in microseconds.
726 Don't change unless you really know what you're
727 doing.
728 </entry>
729 </row>
730 <row>
731 <entry>
732 <varname>auto_resample</varname>
733 <parameter>yes|no</parameter>
734 </entry>
735 <entry>
736 If set to <parameter>no</parameter>, then
737 <filename>libasound</filename> will not attempt to
738 resample, handing the responsibility over to MPD.
739 It is recommended to let MPD resample (with
740 libsamplerate), because ALSA is quite poor at doing
741 so.
742 </entry>
743 </row>
744 <row>
745 <entry>
746 <varname>auto_channels</varname>
747 <parameter>yes|no</parameter>
748 </entry>
749 <entry>
750 If set to <parameter>no</parameter>, then
751 <filename>libasound</filename> will not attempt to
752 convert between different channel numbers.
753 </entry>
754 </row>
755 <row>
756 <entry>
757 <varname>auto_format</varname>
758 <parameter>yes|no</parameter>
759 </entry>
760 <entry>
761 If set to <parameter>no</parameter>, then
762 <filename>libasound</filename> will not attempt to
763 convert between different sample formats (16 bit, 24
764 bit, floating point, ...).
765 </entry>
766 </row>
767 </tbody>
768 </tgroup>
769 </informaltable>
770 </section>
772 <section>
773 <title><varname>ao</varname></title>
775 <para>
776 The <varname>ao</varname> plugin uses the portable
777 <filename>libao</filename> library.
778 </para>
779 </section>
781 <section>
782 <title><varname>fifo</varname></title>
784 <para>
785 The <varname>fifo</varname> plugin writes raw PCM data to a
786 FIFO (First In, First Out) file. The data can be read by
787 another program.
788 </para>
789 </section>
791 <section>
792 <title><varname>jack</varname></title>
794 <para>
795 The <varname>jack</varname> plugin connects to a JACK
796 server.
797 </para>
799 <informaltable>
800 <tgroup cols="2">
801 <thead>
802 <row>
803 <entry>Setting</entry>
804 <entry>Description</entry>
805 </row>
806 </thead>
807 <tbody>
808 <row>
809 <entry>
810 <varname>client_name</varname>
811 <parameter>NAME</parameter>
812 </entry>
813 <entry>
814 The name of the JACK client. Defaults to "Music
815 Player Daemon".
816 </entry>
817 </row>
818 <row>
819 <entry>
820 <varname>server_name</varname>
821 <parameter>NAME</parameter>
822 </entry>
823 <entry>
824 Optional name of the JACK server.
825 </entry>
826 </row>
827 <row>
828 <entry>
829 <varname>autostart</varname>
830 <parameter>yes|no</parameter>
831 </entry>
832 <entry>
833 If set to <parameter>yes</parameter>, then
834 <filename>libjack</filename> will automatically
835 launch the JACK daemon. Disabled by default.
836 </entry>
837 </row>
838 <row>
839 <entry>
840 <varname>source_ports</varname>
841 <parameter>A,B</parameter>
842 </entry>
843 <entry>
844 The names of the JACK source ports to be created.
845 By default, the ports "left" and "right" are
846 created. To use more ports, you have to tweak this
847 option.
848 </entry>
849 </row>
850 <row>
851 <entry>
852 <varname>destination_ports</varname>
853 <parameter>A,B</parameter>
854 </entry>
855 <entry>
856 The names of the JACK destination ports to connect to.
857 </entry>
858 </row>
859 <row>
860 <entry>
861 <varname>ringbuffer_size</varname>
862 <parameter>NBYTES</parameter>
863 </entry>
864 <entry>
865 Sets the size of the ring buffer for each channel.
866 Do not configure this value unless you know what
867 you're doing.
868 </entry>
869 </row>
870 </tbody>
871 </tgroup>
872 </informaltable>
873 </section>
875 <section>
876 <title><varname>mvp</varname></title>
878 <para>
879 The <varname>mvp</varname> plugin uses the proprietary
880 Hauppauge Media MVP interface. We do not know any user of
881 this plugin, and we do not know if it actually works.
882 </para>
883 </section>
885 <section>
886 <title><varname>httpd</varname></title>
888 <para>
889 The <varname>httpd</varname> plugin creates a HTTP server,
890 similar to ShoutCast / IceCast. HTTP streaming clients like
891 <filename>mplayer</filename> can connect to it.
892 </para>
894 <para>
895 You must configure either <varname>quality</varname> or
896 <varname>bitrate</varname>. It is highly recommended to
897 configure a fixed <varname>format</varname>, because a
898 stream cannot switch its audio format on-the-fly when the
899 song changes.
900 </para>
902 <informaltable>
903 <tgroup cols="2">
904 <thead>
905 <row>
906 <entry>Setting</entry>
907 <entry>Description</entry>
908 </row>
909 </thead>
910 <tbody>
911 <row>
912 <entry>
913 <varname>port</varname>
914 <parameter>P</parameter>
915 </entry>
916 <entry>
917 Binds the HTTP server to the specified port (on all
918 interfaces).
919 </entry>
920 </row>
921 <row>
922 <entry>
923 <varname>encoder</varname>
924 <parameter>NAME</parameter>
925 </entry>
926 <entry>
927 Chooses an encoder plugin,
928 e.g. <parameter>vorbis</parameter>.
929 </entry>
930 </row>
931 <row>
932 <entry>
933 <varname>quality</varname>
934 <parameter>Q</parameter>
935 </entry>
936 <entry>
937 Configures the encoder quality (for VBR) in the
938 range -1 .. 10.
939 </entry>
940 </row>
941 <row>
942 <entry>
943 <varname>bitrate</varname>
944 <parameter>BR</parameter>
945 </entry>
946 <entry>
947 Sets a constant encoder bit rate, in kilobit per
948 second.
949 </entry>
950 </row>
951 <row>
952 <entry>
953 <varname>max_clients</varname>
954 <parameter>MC</parameter>
955 </entry>
956 <entry>
957 Sets a limit, number of concurrent clients. When set
958 to 0 no limit will apply.
959 </entry>
960 </row>
961 </tbody>
962 </tgroup>
963 </informaltable>
964 </section>
966 <section>
967 <title><varname>null</varname></title>
969 <para>
970 The <varname>null</varname> plugin does nothing. It
971 discards everything sent to it.
972 </para>
974 <informaltable>
975 <tgroup cols="2">
976 <thead>
977 <row>
978 <entry>Setting</entry>
979 <entry>Description</entry>
980 </row>
981 </thead>
982 <tbody>
983 <row>
984 <entry>
985 <varname>sync</varname>
986 <parameter>yes|no</parameter>
987 </entry>
988 <entry>
989 If set to <parameter>no</parameter>, then the timer
990 is disabled - the device will accept PCM chunks at
991 arbitrary rate (useful for benchmarking). The
992 default behaviour is to play in real time.
993 </entry>
994 </row>
995 </tbody>
996 </tgroup>
997 </informaltable>
998 </section>
1000 <section>
1001 <title><varname>oss</varname></title>
1003 <para>
1004 The "Open Sound System" plugin is supported on most Unix
1005 platforms.
1006 </para>
1008 <informaltable>
1009 <tgroup cols="2">
1010 <thead>
1011 <row>
1012 <entry>Setting</entry>
1013 <entry>Description</entry>
1014 </row>
1015 </thead>
1016 <tbody>
1017 <row>
1018 <entry>
1019 <varname>device</varname>
1020 <parameter>PATH</parameter>
1021 </entry>
1022 <entry>
1023 Sets the path of the PCM device. If not specified,
1024 then MPD will attempt to open
1025 <filename>/dev/sound/dsp</filename> and
1026 <filename>/dev/dsp</filename>.
1027 </entry>
1028 </row>
1029 </tbody>
1030 </tgroup>
1031 </informaltable>
1032 </section>
1034 <section>
1035 <title><varname>openal</varname></title>
1037 <para>
1038 The "OpenAL" plugin uses <filename>libopenal</filename>.
1039 It is supported on many platforms.
1040 </para>
1042 <informaltable>
1043 <tgroup cols="2">
1044 <thead>
1045 <row>
1046 <entry>Setting</entry>
1047 <entry>Description</entry>
1048 </row>
1049 </thead>
1050 <tbody>
1051 <row>
1052 <entry>
1053 <varname>device</varname>
1054 <parameter>NAME</parameter>
1055 </entry>
1056 <entry>
1057 Sets the device which should be used. This can be
1058 any valid OpenAL device name. If not specified, then
1059 <filename>libopenal</filename> will choose a default device.
1060 </entry>
1061 </row>
1062 </tbody>
1063 </tgroup>
1064 </informaltable>
1065 </section>
1067 <section>
1068 <title><varname>osx</varname></title>
1070 <para>
1071 The "Mac OS X" plugin uses Apple's CoreAudio API.
1072 </para>
1073 </section>
1075 <section>
1076 <title><varname>pipe</varname></title>
1078 <para>
1079 The <varname>pipe</varname> plugin starts a program and
1080 writes raw PCM data into its standard input.
1081 </para>
1083 <informaltable>
1084 <tgroup cols="2">
1085 <thead>
1086 <row>
1087 <entry>Setting</entry>
1088 <entry>Description</entry>
1089 </row>
1090 </thead>
1091 <tbody>
1092 <row>
1093 <entry>
1094 <varname>command</varname>
1095 <parameter>CMD</parameter>
1096 </entry>
1097 <entry>
1098 This command is invoked with the shell.
1099 </entry>
1100 </row>
1101 </tbody>
1102 </tgroup>
1103 </informaltable>
1104 </section>
1106 <section>
1107 <title><varname>pulse</varname></title>
1109 <para>
1110 The <varname>pulse</varname> plugin connects to a PulseAudio
1111 server.
1112 </para>
1114 <informaltable>
1115 <tgroup cols="2">
1116 <thead>
1117 <row>
1118 <entry>Setting</entry>
1119 <entry>Description</entry>
1120 </row>
1121 </thead>
1122 <tbody>
1123 <row>
1124 <entry>
1125 <varname>server</varname>
1126 <parameter>HOSTNAME</parameter>
1127 </entry>
1128 <entry>
1129 Sets the host name of the PulseAudio server. By
1130 default, MPD connects to the local PulseAudio
1131 server.
1132 </entry>
1133 </row>
1134 <row>
1135 <entry>
1136 <varname>sink</varname>
1137 <parameter>NAME</parameter>
1138 </entry>
1139 <entry>
1140 Specifies the name of the PulseAudio sink MPD should
1141 play on.
1142 </entry>
1143 </row>
1144 </tbody>
1145 </tgroup>
1146 </informaltable>
1147 </section>
1149 <section>
1150 <title><varname>recorder</varname></title>
1152 <para>
1153 The <varname>recorder</varname> plugin writes the audio
1154 played by MPD to a file. This may be useful for recording
1155 radio streams.
1156 </para>
1158 <para>
1159 You must configure either <varname>quality</varname> or
1160 <varname>bitrate</varname>.
1161 </para>
1163 <informaltable>
1164 <tgroup cols="2">
1165 <thead>
1166 <row>
1167 <entry>Setting</entry>
1168 <entry>Description</entry>
1169 </row>
1170 </thead>
1171 <tbody>
1172 <row>
1173 <entry>
1174 <varname>path</varname>
1175 <parameter>P</parameter>
1176 </entry>
1177 <entry>
1178 Write to this file.
1179 </entry>
1180 </row>
1181 <row>
1182 <entry>
1183 <varname>encoder</varname>
1184 <parameter>NAME</parameter>
1185 </entry>
1186 <entry>
1187 Chooses an encoder plugin,
1188 e.g. <parameter>vorbis</parameter>.
1189 </entry>
1190 </row>
1191 <row>
1192 <entry>
1193 <varname>quality</varname>
1194 <parameter>Q</parameter>
1195 </entry>
1196 <entry>
1197 Configures the encoder quality (for VBR) in the
1198 range -1 .. 10.
1199 </entry>
1200 </row>
1201 <row>
1202 <entry>
1203 <varname>bitrate</varname>
1204 <parameter>BR</parameter>
1205 </entry>
1206 <entry>
1207 Sets a constant encoder bit rate, in kilobit per
1208 second.
1209 </entry>
1210 </row>
1211 </tbody>
1212 </tgroup>
1213 </informaltable>
1214 </section>
1216 <section>
1217 <title><varname>shout</varname></title>
1219 <para>
1220 The <varname>shout</varname> plugin connects to a ShoutCast
1221 or IceCast server. It forwards tags to this server.
1222 </para>
1224 <para>
1225 You must set a <varname>format</varname>.
1226 </para>
1228 <informaltable>
1229 <tgroup cols="2">
1230 <thead>
1231 <row>
1232 <entry>Setting</entry>
1233 <entry>Description</entry>
1234 </row>
1235 </thead>
1236 <tbody>
1237 <row>
1238 <entry>
1239 <varname>host</varname>
1240 <parameter>HOSTNAME</parameter>
1241 </entry>
1242 <entry>
1243 Sets the host name of the Shoutcast/Icecast server.
1244 </entry>
1245 </row>
1246 <row>
1247 <entry>
1248 <varname>port</varname>
1249 <parameter>PORTNUMBER</parameter>
1250 </entry>
1251 <entry>
1252 Connect to this port number on the specified host.
1253 </entry>
1254 </row>
1255 <row>
1256 <entry>
1257 <varname>timeout</varname>
1258 <parameter>SECONDS</parameter>
1259 </entry>
1260 <entry>
1261 Set the timeout for the shout connection in seconds.
1262 Defaults to 2 seconds.
1263 </entry>
1264 </row>
1265 <row>
1266 <entry>
1267 <varname>mount</varname>
1268 <parameter>URI</parameter>
1269 </entry>
1270 <entry>
1271 Mounts the MPD stream in the specified URI.
1272 </entry>
1273 </row>
1274 <row>
1275 <entry>
1276 <varname>user</varname>
1277 <parameter>USERNAME</parameter>
1278 </entry>
1279 <entry>
1280 Sets the user name for submitting the stream to the
1281 server. Default is "source".
1282 </entry>
1283 </row>
1284 <row>
1285 <entry>
1286 <varname>password</varname>
1287 <parameter>PWD</parameter>
1288 </entry>
1289 <entry>
1290 Sets the password for submitting the stream to the
1291 server.
1292 </entry>
1293 </row>
1294 <row>
1295 <entry>
1296 <varname>name</varname>
1297 <parameter>NAME</parameter>
1298 </entry>
1299 <entry>
1300 Sets the name of the stream.
1301 </entry>
1302 </row>
1303 <row>
1304 <entry>
1305 <varname>genre</varname>
1306 <parameter>GENRE</parameter>
1307 </entry>
1308 <entry>
1309 Sets the genre of the stream (optional).
1310 </entry>
1311 </row>
1312 <row>
1313 <entry>
1314 <varname>description</varname>
1315 <parameter>DESCRIPTION</parameter>
1316 </entry>
1317 <entry>
1318 Sets a short description of the stream (optional).
1319 </entry>
1320 </row>
1321 <row>
1322 <entry>
1323 <varname>public</varname>
1324 <parameter>yes|no</parameter>
1325 </entry>
1326 <entry>
1327 Specifies whether the stream should be "public".
1328 Default is "no".
1329 </entry>
1330 </row>
1331 <row>
1332 <entry>
1333 <varname>encoder</varname>
1334 <parameter>PLUGIN</parameter>
1335 </entry>
1336 <entry>
1337 Sets the name of the encoder plugin. Default is
1338 "vorbis". "vorbis" and "lame" are valid encoder
1339 plugins (provided that you enabled them at compile
1340 time).
1341 </entry>
1342 </row>
1343 </tbody>
1344 </tgroup>
1345 </informaltable>
1346 </section>
1348 <section>
1349 <title><varname>solaris</varname></title>
1351 <para>
1352 The "Solaris" plugin runs only on SUN Solaris, and plays via
1353 <filename>/dev/audio</filename>.
1354 </para>
1356 <informaltable>
1357 <tgroup cols="2">
1358 <thead>
1359 <row>
1360 <entry>Setting</entry>
1361 <entry>Description</entry>
1362 </row>
1363 </thead>
1364 <tbody>
1365 <row>
1366 <entry>
1367 <varname>device</varname>
1368 <parameter>PATH</parameter>
1369 </entry>
1370 <entry>
1371 Sets the path of the audio device, defaults to
1372 <filename>/dev/audio</filename>.
1373 </entry>
1374 </row>
1375 </tbody>
1376 </tgroup>
1377 </informaltable>
1378 </section>
1379 </section>
1381 <section>
1382 <title>Playlist plugins</title>
1384 <section>
1385 <title><varname>lastfm</varname></title>
1387 <para>
1388 Plays last.fm radio.
1389 </para>
1391 <informaltable>
1392 <tgroup cols="2">
1393 <thead>
1394 <row>
1395 <entry>Setting</entry>
1396 <entry>Description</entry>
1397 </row>
1398 </thead>
1399 <tbody>
1400 <row>
1401 <entry>
1402 <varname>user</varname>
1403 <parameter>USERNAME</parameter>
1404 </entry>
1405 <entry>
1406 The last.fm user name.
1407 </entry>
1408 </row>
1409 <row>
1410 <entry>
1411 <varname>password</varname>
1412 <parameter>PWD</parameter>
1413 </entry>
1414 <entry>
1415 The last.fm password.
1416 </entry>
1417 </row>
1418 </tbody>
1419 </tgroup>
1420 </informaltable>
1421 </section>
1423 <section>
1424 <title><varname>m3u</varname></title>
1426 <para>
1427 Reads <filename>.m3u</filename> playlist files.
1428 </para>
1429 </section>
1431 <section>
1432 <title><varname>extm3u</varname></title>
1434 <para>
1435 Reads extended <filename>.m3u</filename> playlist files.
1436 </para>
1437 </section>
1439 <section>
1440 <title><varname>pls</varname></title>
1442 <para>
1443 Reads <filename>.pls</filename> playlist files.
1444 </para>
1445 </section>
1447 <section>
1448 <title><varname>xspf</varname></title>
1450 <para>
1451 Reads <ulink url="http://www.xspf.org/">XSPF</ulink>
1452 playlist files.
1453 </para>
1454 </section>
1455 </section>
1456 </chapter>
1457 </book>