Skip to content

M
mpd
Commit 8ddf607d authored by Max Kellermann's avatar Max Kellermann
Browse files
Options

doc/user: add brief "troubleshooting" chapter

parent 5900253b
Hide whitespace changes
Inline Side-by-side
Showing with 265 additions and 0 deletions
doc/user.xml
View file @ 8ddf607d
......@@ -1462,6 +1462,271 @@ buffer_size: 16384</programlisting>
</section>
</chapter>
<chapter id="troubleshooting">
<title>Troubleshooting</title>
<section id="troubleshooting_start">
<title>Where to start</title>
<para>
Make sure you have the latest <application>MPD</application>
version (via <command>mpd --version</command>, not
<command>mpc version</command>). 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
<application>MPD</application> version. The most common
excuse is when your distribution ships an old
<application>MPD</application> version - in that case, please
ask your distribution for help, and not the
<application>MPD</application> project.
</para>
<para>
Check the log file. Configure '<varname>log_level</varname>
"<parameter>verbose</parameter>"' or pass
<parameter>--verbose</parameter> to <filename>mpd</filename>.
</para>
<para>
Sometimes, it is helpful to run <application>MPD</application>
in a terminal and follow what happens. This is how to do it:
</para>
<programlisting>mpd --stdout --no-daemon --verbose</programlisting>
</section>
<section id="support">
<title>Support</title>
<section id="help">
<title>Getting Help</title>
<para>
The <application>MPD</application> project runs <ulink
url="https://forum.musicpd.org/">a forum</ulink> and an IRC
channel (<varname>#mpd</varname> on Freenode) for requesting
help. Visit <ulink url="https://www.musicpd.org/help/">the
<application>MPD</application> help page</ulink> for details
on how to get help.
</para>
</section>
<section id="faq">
<title>Common Problems</title>
<qandaset defaultlabel='qanda'>
<qandadiv>
<title>Database</title>
<qandaentry>
<question>
<para>
I can't see my music in the
<application>MPD</application> database!
</para>
</question>
<answer>
<itemizedlist>
<listitem>
<para>
Check your <varname>music_directory</varname>
setting.
</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para>
Does the <application>MPD</application> user
have read permission on all music files, and
read+execute permission on all music directories
(and all of their parent directories)?
</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para>
Did you update the database? (<command>mpc
update</command>)
</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para>
Did you enable all relevant decoder plugins at
compile time? <command>mpd --version</command>
will tell you.
</para>
</listitem>
</itemizedlist>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>
<application>MPD</application> doesn't read ID3
tags!
</para>
</question>
<answer>
<para>
You probably compiled <application>MPD</application>
without <filename>libid3tag</filename>.
<command>mpd --version</command> will tell you.
</para>
</answer>
</qandaentry>
</qandadiv>
<qandadiv>
<title>Playback</title>
<qandaentry>
<question>
<para>I can't hear music on my client!</para>
</question>
<answer>
<para>
That problem usually follows a misunderstanding of the
nature of <application>MPD</application>.
<application>MPD</application> is a remote-controlled
music player, not a music distribution system.
Usually, the speakers are connected to the box where
<application>MPD</application> runs, and the
<application>MPD</application> client only sends
control commands, but the client does not actually
play your music.
</para>
<para>
<application>MPD</application> has output plugins
which allow hearing music on a remote host (such as
<link
linkend="httpd_output"><varname>httpd</varname></link>),
but that is not <application>MPD</application>'s
primary design goal.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>"Device or resource busy"</para>
</question>
<answer>
<para>
This ALSA error means that another program uses your
sound hardware exclusively. You can stop that
program to allow <application>MPD</application> to
use it.
</para>
<para>
Sometimes, this other program is
<application>PulseAudio</application>, 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 <link
linkend="pulse_output"><application>MPD</application>
to use <application>PulseAudio</application></link>
as well, instead of using ALSA directly.
</para>
</answer>
</qandaentry>
</qandadiv>
</qandaset>
</section>
</section>
<section id="bugs">
<title>Reporting Bugs</title>
<para>
If you believe you found a bug in
<application>MPD</application>, report it on <ulink
url="https://bugs.musicpd.org/my_view_page.php">the bug
tracker</ulink>.
</para>
<para>
Your bug report should contain:
</para>
<itemizedlist>
<listitem>
<para>
the output of <command>mpd --version</command>
</para>
</listitem>
<listitem>
<para>
your <link linkend="config_file">configuration file</link>
(<filename>mpd.conf</filename>)
</para>
</listitem>
<listitem>
<para>
relevant portions of the log file (--verbose)
</para>
</listitem>
<listitem>
<para>
be clear about what you expect MPD to do, and what is
actually happening
</para>
</listitem>
</itemizedlist>
<section id="crash">
<title><application>MPD</application> crashes</title>
<para>
All <application>MPD</application> 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 <application>MPD</application>, and then that
library must be fixed; but in any case, the
<application>MPD</application> bug tracker is a good place
to report it first if you don't know.)
</para>
<para>
A crash bug report needs to contain a "backtrace".
</para>
<para>
First of all, your <application>MPD</application> 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
<filename>mpd-dbg</filename> or
<filename>mpd-dbgsym</filename> on Debian,
<filename>mpd-debug</filename> on other distributions).
Make sure this package is installed.
</para>
<para>
You can extract the backtrace from a core dump, or by
running <application>MPD</application> in a debugger, e.g.:
</para>
<programlisting>gdb --args mpd --stdout --no-daemon --verbose
run</programlisting>
<para>
As soon as you have reproduced the crash, type
"<command>bt</command>" on the <filename>gdb</filename>
command prompt. Copy the output to your bug report.
</para>
</section>
</section>
</chapter>
<chapter id="plugin_reference">
<title>Plugin reference</title>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment