doc/user: add brief "troubleshooting" chapter
This commit is contained in:
Max Kellermann
parent
5900253b85
commit
8ddf607d9f
265
doc/user.xml
265
doc/user.xml
|
|
@ -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>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue