summaryrefslogtreecommitdiffstats
path: root/doc/en/howto-troubleshooting.docbook
diff options
context:
space:
mode:
Diffstat (limited to 'doc/en/howto-troubleshooting.docbook')
-rw-r--r--doc/en/howto-troubleshooting.docbook301
1 files changed, 301 insertions, 0 deletions
diff --git a/doc/en/howto-troubleshooting.docbook b/doc/en/howto-troubleshooting.docbook
new file mode 100644
index 0000000..deb9d12
--- /dev/null
+++ b/doc/en/howto-troubleshooting.docbook
@@ -0,0 +1,301 @@
+<sect1 id="howto-troubleshooting">
+<title>Troubleshooting</title>
+
+<sect2 id="howto-troubleshooting-support">
+<title>Getting support</title>
+
+<para>There are several ways to get help with &kplayer;. If you want to ask a
+question, go to the <ulink url="irc://irc.freenode.net/#kplayer">#kplayer
+channel</ulink> on FreeNode <acronym>IRC</acronym> or post it on the <ulink
+url="http://sourceforge.net/forum/forum.php?forum_id=244388">user
+forum</ulink> where other users will be able to see it, as well as the developer
+who is of course subscribed to receive e-mail when a message is posted there.
+The <acronym>IRC</acronym> channel and the user forum are also good places to
+get help with a problem.</para>
+
+<para>Bugs should be reported through the <ulink
+url="http://sourceforge.net/tracker/?atid=532182&amp;group_id=71710">bug
+tracking system</ulink>, following the instructions in the
+<link linkend="howto-bug-reporting">Bug reporting micro-HOWTO</link>. Also there
+are special sections at the
+<ulink url="http://sourceforge.net/projects/kplayer/">&kplayer; project</ulink>
+on SourceForge for <ulink
+url="http://sourceforge.net/tracker/?atid=532183&amp;group_id=71710">support
+requests</ulink>, <ulink
+url="http://sourceforge.net/tracker/?atid=532185&amp;group_id=71710">feature
+requests</ulink> and <ulink
+url="http://sourceforge.net/tracker/?group_id=71710&amp;atid=532184">code
+patches</ulink>.</para>
+
+</sect2>
+
+<sect2 id="howto-troubleshooting-problems">
+<title>Common problems</title>
+
+<sect3>
+<title>Most commands on the menu and on the toolbar are missing</title>
+
+<para>The <filename>kplayerui.rc</filename> file was misplaced during
+installation, and &kplayer; cannot find it. If you installed using a binary
+package, complain to the package maintainer. When compiling from source, be sure
+to follow the instructions in the <link linkend="howto-compilation">Compilation
+micro-HOWTO</link>, especially the part about <command>kde-config</command>.
+Before starting, run</para>
+
+<para><userinput><command>kde-config</command>
+<option>--prefix</option></userinput></para>
+
+<para>from the command line to make sure that it returns the &kde; prefix
+path.</para>
+
+</sect3>
+
+<sect3>
+<title>After a &kplayer; upgrade new features are missing</title>
+
+<para>You may have a file called <filename>kplayerui.rc</filename> in
+<filename>~/.kde/share/apps/kplayer</filename>. Removing it will get you the new
+menus, but it will also reset any keyboard shortcuts you may have changed in
+the <link linkend="configuration-shortcuts">Key Bindings dialog</link>.</para>
+
+</sect3>
+
+<sect3>
+<title>&kplayer; is not showing up on the <guisubmenu>Multimedia</guisubmenu>
+submenu of the &kmenu;</title>
+
+<para>The <filename>kplayer.desktop</filename> file needs to be installed in the
+correct place, under either <filename>share/applnk/Multimedia</filename> or
+<filename>share/applications/kde</filename> in the global &kde;
+directory.</para>
+
+<para>There also may be a file called <filename>kde-kplayer.desktop</filename>
+in <filename>~/.local/share/applications</filename>. Removing it will get the
+<guisubmenu>Multimedia</guisubmenu> menu updated automatically again when you
+install or uninstall &kplayer;, but it will also reset changes you made to
+&kplayer; associations with media types on the <guilabel>File
+Associations</guilabel> page in &konqueror; configuration dialog or in
+&kcontrolcenter;.</para>
+
+<para>The <guilabel>Contents</guilabel> tab in &khelpcenter; should also list
+&kplayer; in the <guilabel>Multimedia</guilabel> section under
+<guilabel>Application Manuals</guilabel>.</para>
+
+</sect3>
+
+<sect3>
+<title>Could not start &mplayer;</title>
+
+<para>If you get this error when trying to play a file, you need to install
+&mplayer; before you can use &kplayer;. This error can also happen if the name
+of your &mplayer; executable is not <command>mplayer</command> or it is not in
+the current path. In that case go to the
+<link linkend="settings-advanced">Advanced</link> page in
+<guilabel>&kplayer; Settings</guilabel> and give the executable name or the
+full path in the <guilabel>Executable path</guilabel> field.</para>
+
+</sect3>
+
+<sect3>
+<title>configure: error: Can't find X includes</title>
+
+<para>That means that you are missing the X include files, which normally come
+with the X development package. So look for a package in your distribution that
+has files like X.h and XEvent.h. For example, on Debian it is called
+<literal>xlibs-dev</literal>.</para>
+
+<para>Similarly, if <command>configure</command> complains about missing Qt
+files, you need to find and install the Qt development package. If you look
+in the <filename>config.log</filename>, it will probably tell you the exact
+name of the file it couldn't find, somewhere near the bottom. The
+<filename>config.log</filename> file is quite verbose, so you would have to
+scroll a few pages up from the bottom to find the place where it reports the
+error.</para>
+
+</sect3>
+
+<sect3>
+<title>Cannot play any files</title>
+
+<para>Look at the end of the message log to see what errors &mplayer; gives when
+trying to play the files. Hit
+<keycombo action="simul">&Ctrl;<keycap>G</keycap></keycombo> if &kplayer; does
+not show the log automatically.</para>
+
+<para>Try playing the files with <command>mplayer</command> from the command
+line. If &mplayer; can play them, compare the options you used on the command
+line to the ones &kplayer; passed to &mplayer;. Set the required options in
+<link linkend="settings">&kplayer; Settings</link>. The most important ones are
+the <guilabel>Driver</guilabel> options on the
+<link linkend="settings-video">Video</link> and
+<link linkend="settings-audio">Audio</link> pages. On the
+<link linkend="settings-advanced">Advanced page</link>
+check the <guilabel>Executable path</guilabel> option to make sure &kplayer;
+will be able to find the &mplayer; executable, and if there are any options
+that are not found anywhere in the <guilabel>&kplayer; Settings</guilabel>
+dialog, put them in the <guilabel>Additional command line arguments</guilabel>
+field.</para>
+
+</sect3>
+
+<sect3>
+<title>Cannot play a specific file</title>
+
+<para>Look at the end of the message log to see what errors &mplayer; gives when
+trying to play the file. Hit
+<keycombo action="simul">&Ctrl;<keycap>G</keycap></keycombo> if &kplayer; does
+not show the log automatically.</para>
+
+<para>Try playing the file with <command>mplayer</command> from the command
+line. If &mplayer; can play it, but requires special option to play this
+particular file, put them in the <link linkend="properties">File
+Properties</link> for that file. Two options that sometimes help &mplayer; when
+it cannot detect the file type automatically are <option>-vc</option> and
+<option>-ac</option>, which correspond to the <guilabel>Codec</guilabel> options
+on the <link linkend="properties-video">Video</link> and
+<link linkend="properties-audio">Audio</link> pages in <guilabel>File
+Properties</guilabel>. If there are any options that are not found anywhere
+in the <guilabel>File Properties</guilabel> dialog, put them in the
+<guilabel>Additional command line arguments</guilabel> field.</para>
+
+<para>If it is a playlist file but it does not have one of the standard playlist
+file extensions, go to the
+<link linkend="properties-general">General page</link> in the <guilabel>File
+Properties</guilabel> and set the <guilabel>Playlist</guilabel> option to
+<guilabel>yes</guilabel>. In rare cases a file that is not a playlist may have a
+playlist extension. Then you will need to set the <guilabel>Playlist</guilabel>
+property to <guilabel>no</guilabel>. For more details see the
+<link linkend="howto-playlist-files">Playlist files</link> section in the
+Playlist micro-HOWTO.</para>
+
+</sect3>
+
+<sect3>
+<title>Cannot play any video files</title>
+
+<para>If &kplayer; only plays audio files but not video files, there may be a
+problem with the video output. By default &kplayer; uses
+<link linkend="howto-installation-xvideo">XVideo extension</link> for video
+output. If the extension is not enabled or is being used by another program like
+<application>Kino</application>, &kplayer; may not be able to use a different
+video output. You can either enable the XVideo extension or tell &kplayer; to
+use another video output. See the
+<link linkend="howto-configuration">Configuration micro-HOWTO</link> for
+details.</para>
+
+</sect3>
+
+<sect3>
+<title>Video plays fine, but there is no sound</title>
+
+<para>Look in the <link linkend="parts-message-log">Message Log</link> to see
+why &mplayer; cannot play audio. The most common problem is the audio device
+being locked by another program. In this case the chief suspect is
+<command>artsd</command>. Try running</para>
+
+<para><userinput><command>killall</command> artsd</userinput></para>
+
+<para>from the command line. If that helps then the permanent solution is to go
+to the &kcontrolcenter; and disable &arts;. &arts; and everything based on it is
+by far the worst part of &kde;. Fortunately it seems there are plans to finally
+get rid of it in &kde; 4.</para>
+
+<para>For more information on audio setup in &kplayer; see the
+<link linkend="howto-configuration-audio">Configuration
+micro-HOWTO</link>.</para>
+
+</sect3>
+
+<sect3>
+<title>&kplayer; cannot play a file that plays fine with &mplayer;</title>
+
+<para>When &kplayer; is in <guilabel>Running</guilabel> or
+<guilabel>Playing</guilabel> state, run</para>
+
+<para><userinput><command>ps</command> <option>auxww</option></userinput></para>
+
+<para>from the command line. Compare the command line options that &kplayer;
+uses to run &mplayer; to what you are using to play the file with &mplayer;.
+Then start adding missing options one by one until you get the same problem
+you are getting in &kplayer;. After you find out what option is causing the
+problem, you can open the <link linkend="settings">configuration dialog</link>
+in &kplayer; and remove or change that option. If you need to make the change
+just for that one file, go to the <link linkend="properties">File
+Properties</link> instead.</para>
+
+</sect3>
+
+<sect3>
+<title>Problems when coming back from full screen mode</title>
+
+<para>If you are getting problems when you try to go back to normal window size
+from full screen mode, for example the window becomes too large or you are
+seeing endless flickering, you can try unselecting the <guilabel>Resize main
+window automatically</guilabel> option on the
+<link linkend="settings-general">General page</link> in <guilabel>&kplayer;
+Settings</guilabel>. Also read the thread about this problem at the <ulink
+url="http://sourceforge.net/forum/forum.php?thread_id=1122221&amp;forum_id=244388">&kplayer;
+user forum</ulink> and watch it for updates.</para>
+
+</sect3>
+
+<sect3>
+<title>Radio station takes too long to start playing</title>
+
+<para>By default &kplayer; lets &mplayer; choose an optimal cache size. When
+playing low bitrate media like a radio station, it may take a long time to fill
+the cache if it is too big. If that happens, you can either choose a lower
+<guilabel>Cache size</guilabel> setting or give a lower minimum cache size on
+the <guilabel>Advanced</guilabel> page either globally in
+<link linkend="settings-advanced">&kplayer; Settings</link> or in the
+individual <link linkend="properties-advanced">File Properties</link>.
+Enter the minimum cache size into the <guilabel>Additional command line
+parameters</guilabel> field, for example <literal>-cache-min 5</literal>, or
+choose <guilabel>set size</guilabel> for the <guilabel>Cache</guilabel> option
+and enter a size in kilobytes. For more information on playing online media see
+the <link linkend="howto-streams">Streams micro-HOWTO</link>.</para>
+
+</sect3>
+
+<sect3>
+<title>Large video files take too long to start playing</title>
+
+<para>You may have set the <guilabel>Cache size</guilabel> option too low in
+<link linkend="settings-advanced">&kplayer; Settings</link>. If you need to
+set it higher or lower for an individual file or stream, you can do so on the
+<link linkend="properties-advanced">Advanced page</link> in <guilabel>File
+Properties</guilabel>.</para>
+
+</sect3>
+
+<sect3>
+<title>Only the video area is shown in &konqueror;</title>
+
+<para>If you open a web page with an embedded multimedia object in &konqueror;,
+only the video area is displayed, with no controls. Then you should
+<mousebutton>right</mousebutton> click the
+<link linkend="parts-video-area">video area</link> and choose the
+<guimenuitem>Start &kplayer;</guimenuitem> command. Playback will then stop, and
+the full &kplayer; will open up and start playing the file or
+<acronym>URL</acronym>.</para>
+
+</sect3>
+
+<sect3>
+<title>Contrast and brightness controls do not work</title>
+
+<para>You need to enable the <link linkend="howto-installation-xvideo">XVideo
+extension</link> in your X11 configuration and make sure the XVideo video output
+is selected on the <link linkend="settings-advanced"><guilabel>Video</guilabel>
+page</link> in <guilabel>&kplayer; Settings</guilabel>. However, if you cannot
+use the XVideo output, you can still make the video controls to work by putting
+the <literal>-vf eq2</literal> or <literal>-vf eq</literal> option into the
+<guilabel>Additional command line parameters</guilabel> field on the
+<link linkend="properties-advanced">Advanced page</link> in <guilabel>&kplayer;
+Settings</guilabel>.</para>
+
+</sect3>
+
+</sect2>
+
+</sect1>