This is a guide for those who wish to hack on the MPD source code. MPD is an open project, and we are always happy about contributions. So far, more than 150 people have contributed patches. This document is work in progress. Most of it may be incomplete yet. Please help!
Code Style
==========
**********
* indent with tabs (width 8)
* don't write CPP when you can write C++: use inline functions and constexpr instead of macros
...
...
@@ -18,7 +18,6 @@ Code Style
* classes and functions names use CamelCase; variables are lower-case with words separated by underscore
@@ -59,7 +58,7 @@ possible, to be sure that you don't break any disabled code.
Don't mix several changes in one single patch. Create a separate patch for every change. Tools like :program:`stgit` help you with that. This way, we can review your patches more easily, and we can pick the patches we like most first.
Basic stgit usage
-----------------
=================
stgit allows you to create a set of patches and refine all of them: you can go back to any patch at any time, and re-edit it (both the code and the commit message). You can reorder patches and insert new patches at any position. It encourages creating separate patches for tiny changes.
...
...
@@ -94,33 +93,7 @@ When the whole patch series is finished, convert stgit patches to git commits:
stg commit
Submitting Patches
==================
******************
Submit pull requests on GitHub:
https://github.com/MusicPlayerDaemon/MPD/pulls
Development Tools
=================
Clang Static Analyzer
---------------------
The `static analyzer <http://clang-analyzer.llvm.org/>`_ is a tool that helps find bugs. To run it on the MPD code base, install LLVM and clang. configure MPD to use clang:
The setting ``audio_output_format`` forces :program:`MPD` to use one
audio format for all outputs. Doing that is usually not a good idea.
...
...
@@ -526,7 +526,7 @@ 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.
...
...
@@ -539,7 +539,7 @@ Client Connections
.. _listeners:
Listeners
~~~~~~~~~
^^^^^^^^^
The setting :code:`bind_to_address` specifies which addresses
:program:`MPD` listens on for connections from clients. It can be
...
...
@@ -582,7 +582,7 @@ 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`.
...
...
@@ -645,7 +645,7 @@ Other Settings
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.
...
...
@@ -663,7 +663,7 @@ The State File
- 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
These settings are various limitations to prevent :program:`MPD` from using too many resources (denial of service).
...
...
@@ -702,7 +702,7 @@ These settings are various limitations to prevent :program:`MPD` from using too
- 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.
...
...
@@ -717,7 +717,7 @@ Do not change these unless you know what you are doing.
:samp:`4 MB` (4 MiB).
Zeroconf
~~~~~~~~
^^^^^^^^
If Zeroconf support (`Avahi <http://avahi.org/>`_ or Apple's Bonjour)
was enabled at compile time with :code:`-Dzeroconf=...`,
...
...
@@ -803,10 +803,12 @@ You can verify whether the real-time scheduler is active with the ps command:
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
~~~~
.. 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.
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
*********
...
...
@@ -834,7 +836,7 @@ Depending on the size of your music collection and the speed of the storage, thi
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:
...
...
@@ -980,18 +982,18 @@ 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!
* 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)?
...
...
@@ -999,22 +1001,22 @@ Question: I can't see my music in the MPD database!
* 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.
...
...
@@ -1033,7 +1035,7 @@ Your bug report should contain:
* 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.)
