From 8ddf607d9ff51bac7dd50a730924f00660a50ca6 Mon Sep 17 00:00:00 2001 From: Max Kellermann Date: Wed, 4 Jan 2017 08:04:20 +0100 Subject: [PATCH] doc/user: add brief "troubleshooting" chapter --- doc/user.xml | 265 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 265 insertions(+) diff --git a/doc/user.xml b/doc/user.xml index fe67b9332..a27b6be88 100644 --- a/doc/user.xml +++ b/doc/user.xml @@ -1462,6 +1462,271 @@ buffer_size: 16384 + + Troubleshooting + +
+ Where to start + + + Make sure you have the latest MPD + version (via 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 + MPD version. The most common + excuse is when your distribution ships an old + MPD version - in that case, please + ask your distribution for help, and not the + MPD project. + + + + Check the log file. Configure 'log_level + "verbose"' or pass + --verbose to mpd. + + + + Sometimes, it is helpful to run MPD + in a terminal and follow what happens. This is how to do it: + + + mpd --stdout --no-daemon --verbose +
+ +
+ Support + +
+ Getting Help + + + The MPD project runs a forum and an IRC + channel (#mpd on Freenode) for requesting + help. Visit the + MPD help page for details + on how to get help. + +
+ +
+ Common Problems + + + + Database + + + + + I can't see my music in the + MPD database! + + + + + + + Check your 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? mpd --version + will tell you. + + + + + + + + + + MPD doesn't read ID3 + tags! + + + + + You probably compiled MPD + without libid3tag. + mpd --version will tell you. + + + + + + + Playback + + + + I can't hear music on my client! + + + + That problem usually follows a misunderstanding of the + nature of MPD. + MPD is a remote-controlled + music player, not a music distribution system. + Usually, the speakers are connected to the box where + MPD runs, and the + MPD client only sends + control commands, but the client does not actually + play your music. + + + + MPD has output plugins + which allow hearing music on a remote host (such as + httpd), + but that is not MPD's + primary design goal. + + + + + + + "Device or resource busy" + + + + This ALSA error means that another program uses your + sound hardware exclusively. You can stop that + program to allow 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 MPD + to use PulseAudio + as well, instead of using ALSA directly. + + + + + +
+
+ +
+ Reporting Bugs + + + If you believe you found a bug in + MPD, report it on the bug + tracker. + + + + Your bug report should contain: + + + + + + the output of mpd --version + + + + + + your configuration file + (mpd.conf) + + + + + + relevant portions of the log file (--verbose) + + + + + + be clear about what you expect MPD to do, and what is + actually happening + + + + +
+ <application>MPD</application> crashes + + + All 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 MPD, and then that + library must be fixed; but in any case, the + MPD bug tracker 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 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 + mpd-dbg or + mpd-dbgsym on Debian, + mpd-debug on other distributions). + Make sure this package is installed. + + + + You can extract the backtrace from a core dump, or by + running MPD in a debugger, e.g.: + + + gdb --args mpd --stdout --no-daemon --verbose +run + + + As soon as you have reproduced the crash, type + "bt" on the gdb + command prompt. Copy the output to your bug report. + +
+
+ + Plugin reference