summaryrefslogtreecommitdiff
path: root/doc/user.rst
blob: 3ddb3561041beb752436c13ec22a904274ac63ea (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
User's Manual
#############

Introduction
************

Music Player Daemon (:program:`MPD`) is a flexible, powerful, server-side application for playing music. Through plugins and libraries it can play a variety of sound files while being controlled by its network protocol.

This document is work in progress. Most of it may be incomplete yet. Please help!

Installation
************

Installing on Debian/Ubuntu
---------------------------

Install the package :file:`mpd` via :program:`apt`:

.. code-block:: none

    apt install mpd

When installed this way, :program:`MPD` by default looks for music in :file:`/var/lib/mpd/music/`; this may not be correct. Look at your :file:`/etc/mpd.conf` file... 

.. note::

   Debian and Ubuntu are infamous for shipping heavily outdated
   software.  The :program:`MPD` version in their respective stable
   releases are usually too old to be supported by this project.
   Ironically, the :program:`MPD` version in Debian "*unstable*" is
   more stable than the version in Debian "*stable*".


Installing on Android
---------------------

An experimental Android build is available on Google Play. After installing and launching it, :program:`MPD` will scan the music in your Music directory and you can control it as usual with a :program:`MPD` client.

If you need to tweak the configuration, you can create a file called :file:`mpd.conf` on the data partition (the directory which is returned by Android's :dfn:`getExternalStorageDirectory()` API function). 

ALSA is not available on Android; only the :ref:`OpenSL ES
<sles_output>` output plugin can be used for local playback.

Compiling from source
---------------------

Download the source tarball from the `MPD home page <https://musicpd.org>`_ and unpack it:

.. code-block:: none

    tar xf mpd-version.tar.xz
    cd mpd-version

In any case, you need:

* a C++14 compiler (e.g. gcc 6.0 or clang 3.9)
* `Meson 0.49.0 <http://mesonbuild.com/>`__ and `Ninja
  <https://ninja-build.org/>`__
* Boost 1.58
* pkg-config 

Each plugin usually needs a codec library, which you also need to
install. Check the :doc:`plugins` for details about required libraries

For example, the following installs a fairly complete list of build dependencies on Debian Buster:

.. code-block:: none

    apt install meson g++ \
      libpcre3-dev \
      libmad0-dev libmpg123-dev libid3tag0-dev \
      libflac-dev libvorbis-dev libopus-dev libogg-dev \
      libadplug-dev libaudiofile-dev libsndfile1-dev libfaad-dev \
      libfluidsynth-dev libgme-dev libmikmod-dev libmodplug-dev \
      libmpcdec-dev libwavpack-dev libwildmidi-dev \
      libsidplay2-dev libsidutils-dev libresid-builder-dev \
      libavcodec-dev libavformat-dev \
      libmp3lame-dev libtwolame-dev libshine-dev \
      libsamplerate0-dev libsoxr-dev \
      libbz2-dev libcdio-paranoia-dev libiso9660-dev libmms-dev \
      libzzip-dev \
      libcurl4-gnutls-dev libyajl-dev libexpat-dev \
      libasound2-dev libao-dev libjack-jackd2-dev libopenal-dev \
      libpulse-dev libshout3-dev \
      libsndio-dev \
      libmpdclient-dev \
      libnfs-dev libsmbclient-dev \
      libupnp-dev \
      libavahi-client-dev \
      libsqlite3-dev \
      libsystemd-dev \
      libgtest-dev \
      libboost-dev \
      libicu-dev \
      libchromaprint-dev \
      libgcrypt20-dev
      

Now configure the source tree:

.. code-block:: none

 meson . output/release --buildtype=debugoptimized -Db_ndebug=true

The following command shows a list of compile-time options:

.. code-block:: none

 meson configure output/release

When everything is ready and configured, compile:

.. code-block:: none

 ninja -C output/release

And install:

.. code-block:: none

 ninja -C output/release install

Compiling for Windows
---------------------

Even though it does not "feel" like a Windows application, :program:`MPD` works well under Windows. Its build process follows the "Linux style" and may seem awkward for Windows people (who are not used to compiling their software, anyway).

Basically, there are two ways to compile :program:`MPD` for Windows:

* Build as described above: with :program:`meson` and
  :program:`ninja`.  To cross-compile from Linux, you need `a Meson
  cross file <https://mesonbuild.com/Cross-compilation.html>`__.

  The remaining difficulty is installing all the external libraries.
  And :program:`MPD` usually needs many, making this method cumbersome
  for the casual user.

* Build on Linux for Windows using :program:`MPD`'s library build script. 

This section is about the latter.

Just like with the native build, unpack the :program:`MPD` source
tarball and change into the directory.  Then, instead of
:program:`meson`, type:

.. code-block:: none

 mkdir -p output/win64
 cd output/win64
 ../../win32/build.py --64

This downloads various library sources, and then configures and builds
:program:`MPD` (for x64; to build a 32 bit binary, pass
:code:`--32`). The resulting EXE files is linked statically, i.e. it
contains all the libraries already and you do not need carry DLLs
around. It is large, but easy to use. If you wish to have a small
mpd.exe with DLLs, you need to compile manually, without the
:file:`build.py` script.

Compiling for Android
---------------------

:program:`MPD` can be compiled as an Android app. It can be installed easily with Google Play, but if you want to build it from source, follow this section.

You need:

* Android SDK
* Android NDK 

Just like with the native build, unpack the :program:`MPD` source
tarball and change into the directory.  Then, instead of
:program:`meson`, type:

.. code-block:: none

 mkdir -p output/android
 cd output/android
 ../../android/build.py SDK_PATH NDK_PATH ABI
 meson configure -Dandroid_debug_keystore=$HOME/.android/debug.keystore
 ninja android/apk/mpd-debug.apk

:envvar:`SDK_PATH` is the absolute path where you installed the
Android SDK; :envvar:`NDK_PATH` is the Android NDK installation path;
ABI is the Android ABI to be built, e.g. ":code:`arm64-v8a`".

This downloads various library sources, and then configures and builds :program:`MPD`. 

systemd socket activation
-------------------------

Using systemd, you can launch :program:`MPD` on demand when the first client attempts to connect.

:program:`MPD` comes with two systemd unit files: a "service" unit and
a "socket" unit.  These will be installed to the directory specified
with :code:`-Dsystemd_system_unit_dir=...`,
e.g. :file:`/lib/systemd/system`.

To enable socket activation, type:

.. code-block:: none

    systemctl enable mpd.socket
    systemctl start mpd.socket

In this configuration, :program:`MPD` will ignore the :ref:`listener
settings <listeners>` (``bind_to_address`` and ``port``).

systemd user unit
-----------------

You can launch :program:`MPD` as a systemd user unit.  These will be
installed to the directory specified with
:code:`-Dsystemd_user_unit_dir=...`,
e.g. :file:`/usr/lib/systemd/user` or
:file:`$HOME/.local/share/systemd/user`.

Once the user unit is installed, you can start and stop :program:`MPD` like any other service:

.. code-block:: none

    systemctl --user start mpd

To auto-start :program:`MPD` upon login, type:

.. code-block:: none

    systemctl --user enable mpd

Configuration
*************

The Configuration File
----------------------

:program:`MPD` reads its configuration from a text file. Usually, that is :file:`/etc/mpd.conf`, unless a different path is specified on the command line. If you run :program:`MPD` as a user daemon (and not as a system daemon), the configuration is read from :file:`$XDG_CONFIG_HOME/mpd/mpd.conf` (usually :file:`~/.config/mpd/mpd.conf`). On Android, :file:`mpd.conf` will be loaded from the top-level directory of the data partition.

Each line in the configuration file contains a setting name and its value, e.g.:

:code:`connection_timeout "5"`

For settings which specify a filesystem path, the tilde is expanded:

:code:`music_directory "~/Music"`

Some of the settings are grouped in blocks with curly braces, e.g. per-plugin settings:

.. code-block:: none

    audio_output {
        type "alsa"
        name "My ALSA output"
        device "iec958:CARD=Intel,DEV=0"
        mixer_control "PCM"
    }

The :code:`include` directive can be used to include settings from
another file; the given file name is relative to the current file:

.. code-block:: none

  include "other.conf"

Configuring the music directory
-------------------------------

When you play local files, you should organize them within a directory called the "music directory". This is configured in :program:`MPD` with the music_directory setting.

By default, :program:`MPD` follows symbolic links in the music directory. This behavior can be switched off: :code:`follow_outside_symlinks` controls whether :program:`MPD` follows links pointing to files outside of the music directory, and :code:`follow_inside_symlinks` lets you disable symlinks to files inside the music directory.

Instead of using local files, you can use storage plugins to access
files on a remote file server. For example, to use music from the
SMB/CIFS server ":file:`myfileserver`" on the share called "Music",
configure the music directory ":file:`smb://myfileserver/Music`". For
a recipe, read the Satellite :program:`MPD` section :ref:`satellite`.

You can also use multiple storage plugins to assemble a virtual music directory consisting of multiple storages. 

Configuring database plugins
----------------------------

If a music directory is configured, one database plugin is used. To
configure this plugin, add a :code:`database` block to
:file:`mpd.conf`:

.. code-block:: none

    database {
        plugin "simple"
        path "/var/lib/mpd/db"
    }
    
More information can be found in the :ref:`database_plugins`
reference.

Configuring neighbor plugins
----------------------------

All neighbor plugins are disabled by default to avoid unwanted
overhead. To enable (and configure) a plugin, add a :code:`neighbor`
block to :file:`mpd.conf`:

.. code-block:: none

    neighbors {
        plugin "smbclient"
    }
      
More information can be found in the :ref:`neighbor_plugin` reference.

Configuring input plugins
-------------------------

To configure an input plugin, add an :code:`input` block to
:file:`mpd.conf`:

.. code-block:: none

    input {
        plugin "curl"
        proxy "proxy.local"
    }
      

The following table lists the input options valid for all plugins:

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - Name
     - Description
   * - **plugin**
     - The name of the plugin
   * - **enabled yes|no**
     - Allows you to disable a input plugin without recompiling. By default, all plugins are enabled.

More information can be found in the :ref:`input_plugins` reference.

Configuring decoder plugins
---------------------------

Most decoder plugins do not need any special configuration. To
configure a decoder, add a :code:`decoder` block to :file:`mpd.conf`:

.. code-block:: none

    decoder {
        plugin "wildmidi"
        config_file "/etc/timidity/timidity.cfg"
    }
      
The following table lists the decoder options valid for all plugins:

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - Name
     - Description
   * - **plugin**
     - The name of the plugin
   * - **enabled yes|no**
     - Allows you to disable a decoder plugin without recompiling. By default, all plugins are enabled.

More information can be found in the :ref:`decoder_plugins` reference.

Configuring encoder plugins
---------------------------

Encoders are used by some of the output plugins (such as shout). The
encoder settings are included in the ``audio_output`` section, see :ref:`config_audio_output`.

More information can be found in the :ref:`encoder_plugins` reference.


.. _config_audio_output:

Configuring audio outputs
-------------------------

Audio outputs are devices which actually play the audio chunks produced by :program:`MPD`. You can configure any number of audio output devices, but there must be at least one. If none is configured, :program:`MPD` attempts to auto-detect. Usually, this works quite well with ALSA, OSS and on Mac OS X.

To configure an audio output manually, add one or more
:code:`audio_output` blocks to :file:`mpd.conf`:

.. code-block:: none

    audio_output {
        type "alsa"
        name "my ALSA device"
        device "hw:0"
    }

The following table lists the audio_output options valid for all plugins:


.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - Name
     - Description
   * - **type**
     - The name of the plugin
   * - **name**
     - The name of the audio output. It is visible to the client. Some plugins also use it internally, e.g. as a name registered in the PULSE server.
   * - **format samplerate:bits:channels**
     -  Always open the audio output with the specified audio format, regardless of the format of the input file. This is optional for most plugins.
        See :ref:`audio_output_format` for a detailed description of the value.
   * - **enabed yes|no**
     - Specifies whether this audio output is enabled when :program:`MPD` is started. By default, all audio outputs are enabled. This is just the default setting when there is no state file; with a state file, the previous state is restored.
   * - **tags yes|no**
     - If set to no, then :program:`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.
   * - **always_on yes|no**
     - If set to yes, then :program:`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.
   * - **mixer_type hardware|software|null|none**
     - Specifies which mixer should be used for this audio output: the
       hardware mixer (available for ALSA :ref:`alsa_plugin`, OSS
       :ref:`oss_plugin` and PulseAudio :ref:`pulse_plugin`), the
       software mixer, the ":samp:`null`" mixer (allows setting the
       volume, but with no effect; this can be used as a trick to
       implement an external mixer :ref:`external_mixer`) or no mixer
       (:samp:`none`). By default, the hardware mixer is used for
       devices which support it, and none for the others.
   * - **filters "name,...**"
     - The specified configured filters are instantiated in the given
       order.  Each filter name refers to a ``filter`` block, see
       :ref:`config_filter`.

More information can be found in the :ref:`output_plugins` reference.


.. _config_filter:

Configuring filters
-------------------

Filters are plugins which modify an audio stream.

To configure a filter, add a :code:`filter` block to :file:`mpd.conf`:

.. code-block:: none

    filter {
        plugin "volume"
        name "software volume"
    }

Configured filters may then be added to the ``filters`` setting of an
``audio_output`` section, see :ref:`config_audio_output`.

The following table lists the filter options valid for all plugins:

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - Name
     - Description
   * - **plugin**
     - The name of the plugin
   * - **name**
     - The name of the filter

More information can be found in the :ref:`filter_plugins` reference.


Configuring playlist plugins
----------------------------

Playlist plugins are used to load remote playlists (protocol commands
load, listplaylist and listplaylistinfo). This is not related to
:program:`MPD`'s :ref:`playlist directory <stored_playlists>`.

To configure a playlist plugin, add a :code:`playlist_plugin` block to
:file:`mpd.conf`:

.. code-block:: none

    playlist_plugin {
        name "m3u"
        enabled "true"
    }

The following table lists the playlist_plugin options valid for all plugins:

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - Name
     - Description
   * - **plugin**
     - The name of the plugin
   * - **enabled yes|no**
     - Allows you to disable a playlist plugin without recompiling. By default, all plugins are enabled.

More information can be found in the :ref:`playlist_plugins`
reference.

Audio Format Settings
---------------------

.. _audio_output_format:

Global Audio Format
^^^^^^^^^^^^^^^^^^^

The setting ``audio_output_format`` forces :program:`MPD` to use one
audio format for all outputs.  Doing that is usually not a good idea.

The value is specified as ``samplerate:bits:channels``.

Any of the three attributes may be an asterisk to specify that this
attribute should not be enforced, example: ``48000:16:*``.
``*:*:*`` is equal to not having a format specification.

The following values are valid for bits: ``8`` (signed 8 bit integer
samples), ``16``, ``24`` (signed 24 bit integer samples padded to 32
bit), ``32`` (signed 32 bit integer samples), ``f`` (32 bit floating
point, -1.0 to 1.0), ``dsd`` means DSD (Direct Stream Digital). For
DSD, there are special cases such as ``dsd64``, which allows you to
omit the sample rate (e.g. ``dsd512:2`` for stereo DSD512,
i.e. 22.5792 MHz).

The sample rate is special for DSD: :program:`MPD` counts the number
of bytes, not bits. Thus, a DSD "bit" rate of 22.5792 MHz (DSD512) is
2822400 from :program:`MPD`'s point of view (44100*512/8).

Resampler
^^^^^^^^^

Sometimes, music needs to be resampled before it can be played; for example, CDs use a sample rate of 44,100 Hz while many cheap audio chips can only handle 48,000 Hz. Resampling reduces the quality and consumes a lot of CPU. 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 :program:`MPD`'s CPU usage. Since :program:`MPD` comes with high quality defaults, it may appear that :program:`MPD` consumes more CPU than other software.

Check the :ref:`resampler_plugins` reference for a list of resamplers
and how to configure them.

Client Connections
------------------

.. _listeners:

Listeners
^^^^^^^^^

The setting :code:`bind_to_address` specifies which addresses
:program:`MPD` listens on for connections from clients.  It can be
used multiple times to bind to more than one address.  Example::

 bind_to_address "192.168.1.42"
 bind_to_address "127.0.0.1"

The default is "any", which binds to all available addresses.
Additionally, MPD binds to :code:`$XDG_RUNTIME_DIR/mpd/socket` (if it
was launched as a per-user daemon and no :code:`bind_to_address`
setting exists).

You can set a port that is different from the global port setting,
e.g. "localhost:6602".  IPv6 addresses must be enclosed in square
brackets if you want to configure a port::

 bind_to_address "[::1]:6602"

To bind to a local socket (UNIX domain socket), specify an absolute
path or a path starting with a tilde (~).  Some clients default to
connecting to :file:`/var/run/mpd/socket` so this may be a good
choice::

 bind_to_address "/var/run/mpd/socket"

On Linux, local sockets can be bound to a name without a socket inode
on the filesystem; MPD implements this by prepending ``@`` to the
address::

 bind_to_address "@mpd"

If no port is specified, the default port is 6600.  This default can
be changed with the port setting::

 port "6601"

These settings will be ignored if `systemd socket activation`_ is
used.


Permissions and Passwords
^^^^^^^^^^^^^^^^^^^^^^^^^

By default, all clients are unauthenticated and have a full set of permissions. This can be restricted with the settings :code:`default_permissions` and :code:`password`.

:code:`default_permissions` controls the permissions of a new client. Its value is a comma-separated list of permissions:

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - Name
     - Description
   * - **read**
     - Allows reading of the database, displaying the current playlist, and current status of :program:`MPD`.
   * - **add**
     - Allows adding songs and loading playlists.
   * - **control**
     - Allows all other player and playlist manipulations.
   * - **admin**
     - Allows database updates and allows shutting down :program:`MPD`.

:code:`local_permissions` may be used to assign other permissions to clients connecting on a local socket.

:code:`password` allows the client to send a password to gain other permissions. This option may be specified multiple times with different passwords.

Note that the :code:`password` option is not secure: passwords are sent in clear-text over the connection, and the client cannot verify the server's identity.

Example:

.. code-block:: none

    default_permissions "read"
    password "the_password@read,add,control"
    password "the_admin_password@read,add,control,admin"

Other Settings
--------------

.. _metadata_to_use:

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - Setting
     - Description
   * - **metadata_to_use TAG1,TAG2,...**
     - Use only the specified tags, and ignore the others. This
       setting can reduce the database size and :program:`MPD`'s
       memory usage by omitting unused tags. By default, all tags but
       comment are enabled. The special value "none" disables all
       tags.

       If the setting starts with ``+`` or ``-``, then the following
       tags will be added or remoted to/from the current set of tags.
       This example just enables the "comment" tag without disabling all
       the other supported tags

         metadata_to_use "+comment"

       Section :ref:`tags` contains a list of supported tags.

The State File
^^^^^^^^^^^^^^

 The state file is a file where :program:`MPD` saves and restores its state (play queue, playback position etc.) to keep it persistent across restarts and reboots. It is an optional setting.

:program:`MPD` will attempt to load the state file during startup, and will save it when shutting down the daemon. Additionally, the state file is refreshed every two minutes (after each state change).

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - Setting
     - Description
   * - **state_file PATH**
     - Specify the state file location. The parent directory must be writable by the :program:`MPD` user (+wx).
   * - **state_file_interval SECONDS**
     - Auto-save the state file this number of seconds after each state change. Defaults to 120 (2 minutes).

The Sticker Database
^^^^^^^^^^^^^^^^^^^^

"Stickers" are pieces of information attached to songs. Some clients
use them to store ratings and other volatile data. This feature
requires :program:`SQLite`, compile-time configure option
:code:`-Dsqlite=...`.

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - Setting
     - Description
   * - **sticker_file PATH**
     - The location of the sticker database.

Resource Limitations
^^^^^^^^^^^^^^^^^^^^

These settings are various limitations to prevent :program:`MPD` from using too many resources (denial of service).

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - Setting
     - Description
   * - **connection_timeout SECONDS**
     - If a client does not send any new data in this time period, the connection is closed. Clients waiting in "idle" mode are excluded from this. Default is 60.
   * - **max_connections NUMBER**
     - This specifies the maximum number of clients that can be connected to :program:`MPD` at the same time. Default is 5.
   * - **max_playlist_length NUMBER**
     - The maximum number of songs that can be in the playlist. Default is 16384.
   * - **max_command_list_size KBYTES**
     - The maximum size a command list. Default is 2048 (2 MiB).
   * - **max_output_buffer_size KBYTES**
     - The maximum size of the output buffer to a client (maximum response size). Default is 8192 (8 MiB).

Buffer Settings
^^^^^^^^^^^^^^^

Do not change these unless you know what you are doing.

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - Setting
     - Description
   * - **audio_buffer_size KBYTES**
     - Adjust the size of the internal audio buffer. Default is 4096 (4 MiB).

Zeroconf
^^^^^^^^

If Zeroconf support (`Avahi <http://avahi.org/>`_ or Apple's Bonjour)
was enabled at compile time with :code:`-Dzeroconf=...`,
:program:`MPD` can announce its presence on the network. The following
settings control this feature:

.. list-table::
   :widths: 20 80
   :header-rows: 1

   * - Setting
     - Description
   * - **zeroconf_enabled yes|no**
     - Enables or disables this feature. Default is yes.
   * - **zeroconf_name NAME**
     - The service name to publish via Zeroconf. The default is "Music Player @ %h".
       %h will be replaced with the hostname of the machine running :program:`MPD`.

Advanced configuration
**********************

.. _satellite:

Satellite setup
---------------

:program:`MPD` runs well on weak machines such as the Raspberry Pi. However, such hardware tends to not have storage big enough to hold a music collection. Mounting music from a file server can be very slow, especially when updating the database.

One approach for optimization is running :program:`MPD` on the file server, which not only exports raw files, but also provides access to a readily scanned database. Example configuration:

.. code-block:: none

    music_directory "nfs://fileserver.local/srv/mp3"
    #music_directory "smb://fileserver.local/mp3"

    database {
        plugin "proxy"
        host "fileserver.local"
    }
      
The :code:`music_directory` setting tells :program:`MPD` to read files from the given NFS server. It does this by connecting to the server from userspace. This does not actually mount the file server into the kernel's virtual file system, and thus requires no kernel cooperation and no special privileges. It does not even require a kernel with NFS support, only the nfs storage plugin (using the libnfs userspace library). The same can be done with SMB/CIFS using the smbclient storage plugin (using libsmbclient).

The database setting tells :program:`MPD` to pass all database queries on to the :program:`MPD` instance running on the file server (using the proxy plugin).

Real-Time Scheduling
--------------------

On Linux, :program:`MPD` attempts to configure real-time scheduling for some threads that benefit from it.

This is only possible you allow :program:`MPD` to do it. This privilege is controlled by :envvar:`RLIMIT_RTPRIO` :envvar:`RLIMIT_RTTIME`. You can configure this privilege with :command:`ulimit` before launching :program:`MPD`:

.. code-block:: none

    ulimit -HS -r 50; mpd

Or you can use the :command:`prlimit` program from the util-linux package:

.. code-block:: none

    prlimit --rtprio=50 --rttime=unlimited mpd

The systemd service file shipped with :program:`MPD` comes with this setting.

This works only if the Linux kernel was compiled with :makevar:`CONFIG_RT_GROUP_SCHED` disabled. Use the following command to check this option for your current kernel:

.. code-block:: none

    zgrep ^CONFIG_RT_GROUP_SCHED /proc/config.gz

You can verify whether the real-time scheduler is active with the ps command:

.. code-block:: none

    # ps H -q `pidof -s mpd` -o 'pid,tid,cls,rtprio,comm'
      PID   TID CLS RTPRIO COMMAND
    16257 16257  TS      - mpd
    16257 16258  TS      - io
    16257 16259  FF     50 rtio
    16257 16260  TS      - player
    16257 16261  TS      - decoder
    16257 16262  FF     50 output:ALSA
    16257 16263 IDL      0 update

The CLS column shows the CPU scheduler; TS is the normal scheduler; FF and RR are real-time schedulers. In this example, two threads use the real-time scheduler: the output thread and the rtio (real-time I/O) thread; these two are the important ones. The database update thread uses the idle scheduler ("IDL in ps), which only gets CPU when no other process needs it.

.. note::

   There is a rumor that real-time scheduling improves audio
   quality. That is not true. All it does is reduce the probability of
   skipping (audio buffer xruns) when the computer is under heavy
   load.

Using MPD
*********

The client
----------

After you have installed, configured and started :program:`MPD`, you choose a client to control the playback.

The most basic client is :program:`mpc`, which provides a command line interface. It is useful in shell scripts. Many people bind specific :program:`mpc` commands to hotkeys.

The `MPD Wiki <http://www.musicpd.org/clients/>`_ contains an extensive list of clients to choose from.

The music directory and the database
------------------------------------

The "music directory" is where you store your music files. :program:`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:

.. code-block:: none

    mpc update

Depending on the size of your music collection and the speed of the storage, this can take a while.

To exclude a file from the update, create a file called :file:`.mpdignore` in its parent directory. Each line of that file may contain a list of shell wildcards. Matching files in the current directory and all subdirectories are excluded.

Mounting other storages into the music directory
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

:program:`MPD` has various storage plugins of which multiple instances can be "mounted" into the music directory. This way, you can use local music, file servers and USB sticks at the same time. Example:

.. code-block:: none

    mpc mount foo nfs://192.168.1.4/export/mp3
    mpc mount usbstick udisks://by-uuid-2F2B-D136
    mpc unmount usbstick

:program:`MPD`'s neighbor plugins can be helpful with finding mountable storages:

.. code-block:: none

    mpc listneighbors

Mounting is only possible with the simple database plugin and a :code:`cache_directory`, e.g.:

.. code-block:: none

    database {
      plugin "simple"
      path "~/.mpd/db"
      cache_directory "~/.mpd/cache"
    }
        
This requires migrating from the old :code:`db_file` setting to a database section. The cache directory must exist, and :program:`MPD` will put one file per mount there, which will be reused when the same storage is used again later.

Metadata
--------

When scanning or playing a song, :program:`MPD` parses its metadata.
See :ref:`tags` for a list of supported tags.

The :ref:`metadata_to_use <metadata_to_use>` setting can be used to
enable or disable certain tags.

The queue
---------

The queue (sometimes called "current playlist") is a list of songs to be played by :program:`MPD`. To play a song, add it to the queue and start playback. Most clients offer an interface to edit the queue.

.. _stored_playlists:

Stored Playlists
----------------

Stored playlists are some kind of secondary playlists which can be
created, saved, edited and deleted by the client. They are addressed
by their names.  Its contents can be loaded into the queue, to be
played back.  The :code:`playlist_directory` setting specifies where
those playlists are stored.

Advanced usage
**************

Bit-perfect playback
--------------------

"Bit-perfect playback" is a phrase used by audiophiles to describe a setup that plays back digital music as-is, without applying any modifications such as resampling, format conversion or software volume. Naturally, this implies a lossless codec.

By default, :program:`MPD` attempts to do bit-perfect playback, unless you tell it not to. Precondition is a sound chip that supports the audio format of your music files. If the audio format is not supported, :program:`MPD` attempts to fall back to the nearest supported audio format, trying to lose as little quality as possible.

To verify if :program:`MPD` converts the audio format, enable verbose logging, and watch for these lines:

.. code-block:: none

    decoder: audio_format=44100:24:2, seekable=true
    output: opened plugin=alsa name="An ALSA output" audio_format=44100:16:2
    output: converting from 44100:24:2

This example shows that a 24 bit file is being played, but the sound chip cannot play 24 bit. It falls back to 16 bit, discarding 8 bit.

However, this does not yet prove bit-perfect playback; ALSA may be fooling :program:`MPD` that the audio format is supported. To verify the format really being sent to the physical sound chip, try:

.. code-block:: none

    cat /proc/asound/card*/pcm*p/sub*/hw_params
    access: RW_INTERLEAVED
    format: S16_LE
    subformat: STD
    channels: 2
    rate: 44100 (44100/1)
    period_size: 4096
    buffer_size: 16384

Obey the "format" row, which indicates that the current playback format is 16 bit (signed 16 bit integer, little endian).

Check list for bit-perfect playback:

* Use the ALSA output plugin.
* Disable sound processing inside ALSA by configuring a "hardware"
  device (:samp:`hw:0,0` or similar).
* Don't use software volume (setting :code:`mixer_type`).
* Don't force :program:`MPD` to use a specific audio format (settings
  :code:`format`, :ref:`audio_output_format <audio_output_format>`).
* Verify that you are really doing bit-perfect playback using :program:`MPD`'s verbose log and :file:`/proc/asound/card*/pcm*p/sub*/hw_params`. Some DACs can also indicate the audio format.

Direct Stream Digital (DSD)
---------------------------

DSD (`Direct Stream Digital <https://en.wikipedia.org/wiki/Direct_Stream_Digital>`_) is a digital format that stores audio as a sequence of single-bit values at a very high sampling rate.

:program:`MPD` understands the file formats dff and dsf. There are three ways to play back DSD:

* Native DSD playback. Requires ALSA 1.0.27.1 or later, a sound driver/chip that supports DSD and of course a DAC that supports DSD.

* DoP (DSD over PCM) playback. This wraps DSD inside fake 24 bit PCM according to the DoP standard. Requires a DAC that supports DSD. No support from ALSA and the sound chip required (except for bit-perfect 24 bit PCM support).
* Convert DSD to PCM on-the-fly. 

Native DSD playback is used automatically if available. DoP is only
used if enabled explicitly using the :code:`dop` option, because there
is no way for :program:`MPD` to find out whether the DAC supports
it. DSD to PCM conversion is the fallback if DSD cannot be used
directly.

Client Hacks
************

.. _external_mixer:

External Mixer
--------------

The setting :code:`mixer_type "null"` asks MPD to pretend that there is a mixer, but not actually do something. This allows you to implement a :program:`MPD` client which listens for mixer events, queries the current (fake) volume, and uses it to program an external mixer. For example, your client can forward this setting to your amplifier.

Troubleshooting
***************

Where to start
--------------

Make sure you have the latest :program:`MPD` version (via :code:`mpd --version`, not mpc version). All the time, bugs are found and fixed, and your problem might be a bug that is fixed already. Do not ask for help unless you have the latest :program:`MPD` version. The most common excuse is when your distribution ships an old :program:`MPD` version - in that case, please ask your distribution for help, and not the :program:`MPD` project.

Check the log file. Configure :code:`log_level "verbose"` or pass :option:`--verbose` to mpd.

Sometimes, it is helpful to run :program:`MPD` in a terminal and follow what happens. This is how to do it:

.. code-block:: none

    mpd --stdout --no-daemon --verbose

Support
-------

Getting Help
^^^^^^^^^^^^

The :program:`MPD` project runs a `forum <https://forum.musicpd.org/>`_ and an IRC channel (#mpd on Freenode) for requesting help. Visit the MPD help page for details on how to get help.

Common Problems
^^^^^^^^^^^^^^^

1. Database
"""""""""""

Question: I can't see my music in the MPD database!
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* Check your :code:`music_directory` setting. 
* Does the MPD user have read permission on all music files, and read+execute permission on all music directories (and all of their parent directories)? 
* Did you update the database? (mpc update) 
* Did you enable all relevant decoder plugins at compile time? :command:`mpd --version` will tell you. 

Question: MPD doesn't read ID3 tags!
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* You probably compiled :program:`MPD` without libid3tag. :command:`mpd --version` will tell you.

2. Playback
"""""""""""

Question: I can't hear music on my client!
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

* That problem usually follows a misunderstanding of the nature of :program:`MPD`. :program:`MPD` is a remote-controlled music player, not a music distribution system. Usually, the speakers are connected to the box where :program:`MPD` runs, and the :program:`MPD` client only sends control commands, but the client does not actually play your music.

  :program:`MPD` has output plugins which allow hearing music on a remote host (such as httpd), but that is not :program:`MPD`'s primary design goal. 

Question: "Device or resource busy"
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

*  This ALSA error means that another program uses your sound hardware exclusively. You can stop that program to allow :program:`MPD` to use it.

  Sometimes, this other program is PulseAudio, which can multiplex sound from several applications, to allow them to share your sound chip. In this case, it might be a good idea for :program:`MPD` to use PulseAudio as well, instead of using ALSA directly.

Reporting Bugs
--------------

If you believe you found a bug in :program:`MPD`, report it on the `bug tracker <https://github.com/MusicPlayerDaemon/MPD/issues>`_.

Your bug report should contain:

* the output of :command:`mpd --version`
* your configuration file (:file:`mpd.conf`)
* relevant portions of the log file (:option:`--verbose`)
* be clear about what you expect MPD to do, and what is actually happening

MPD crashes
^^^^^^^^^^^

All :program:`MPD` crashes are bugs which must be fixed by a developer, and you should write a bug report. (Many crash bugs are caused by codec libraries used by :program:`MPD`, and then that library must be fixed; but in any case, the :program:`MPD` `bug tracker <https://github.com/MusicPlayerDaemon/MPD/issues>`_ is a good place to report it first if you don't know.)

A crash bug report needs to contain a "backtrace".

First of all, your :program:`MPD` executable must not be "stripped"
(i.e. debug information deleted).  The executables shipped with Linux
distributions are usually stripped, but some have so-called "debug"
packages (package :file:`mpd-dbgsym` or :file:`mpd-dbg` on Debian,
:file:`mpd-debug` on other distributions).  Make sure this package is
installed.

If you built :program:`MPD` from sources, please recompile with Meson
option ":code:`--buildtype=debug -Db_ndebug=false`", because this will
add more helpful information to the backtrace.

You can extract the backtrace from a core dump, or by running :program:`MPD` in a debugger, e.g.:

.. code-block:: none

    gdb --args mpd --stdout --no-daemon --verbose
    run

As soon as you have reproduced the crash, type ":command:`bt`" on the
gdb command prompt. Copy the output to your bug report.