diff options
Diffstat (limited to 'doc/en/howto-troubleshooting.docbook')
-rw-r--r-- | doc/en/howto-troubleshooting.docbook | 301 |
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&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&group_id=71710">support +requests</ulink>, <ulink +url="http://sourceforge.net/tracker/?atid=532185&group_id=71710">feature +requests</ulink> and <ulink +url="http://sourceforge.net/tracker/?group_id=71710&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&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> |