path: root/README

KPlayer is a KDE multimedia player.

With KPlayer you can easily play a wide variety of video and audio files and
streams using a rich and friendly interface compliant with KDE standards.

Features include
- video, audio and subtitle playback from file, URL, DVD, VCD,
  audio CD, TV, DVB, etc., as well as KDE I/O Slaves;
- volume, contrast, brightness, hue and saturation controls;
- zooming, full screen and fixed aspect options;
- status and progress display and seeking;
- multimedia library to organize your media files and streams;
- configuration dialog and file specific options;
- KPart for integration with Konqueror, KMLDonkey, etc.

Requirements
------------

A recent MPlayer

   KPlayer uses the famous MPlayer, www.mplayerhq.hu, as the backend for
   playing audio and video files and streams. This ensures the maximum
   variety of supported types of files and encodings.

   You need to have MPlayer version 1.0rc1 or later.

   If there are good binary packages for your distribution, use those.
   For example on Debian unstable you would do

   echo 'deb http://www.debian-multimedia.org unstable main' >> /etc/apt/sources.list
   apt-get update
   apt-get install mplayer kplayer libdvdcss w32codecs

   Substitute unstable for stable or testing as needed.

   As always compiling from source is an option.

   If you got an mplayer.conf in /etc/mplayer or a ~/.mplayer/config,
   check them to make sure that they do not have a line like "gui=yes".
   Kill it dead if you find it. Use 'gmplayer' if you ever decide to
   use MPlayer's own GUI (not recommended).

   It is perfectly fine if you want to remove the MPlayer config files
   entirely. However, they may be useful as an alternative way of
   specifying options that KPlayer does not yet support directly.

X11 and XVideo

   X11 is required. X.org is the best choice here.

   XVideo extension is recommended. You can check your /etc/X11/xorg.conf
   file for a line that reads

   Load "extmod"

   This is the line that loads XVideo extension, so make sure it is not
   disabled. Also check /var/log/Xorg.0.log to make sure that XVideo
   is loaded without error.

Qt and KDE

   KPlayer supports KDE 3.1 and later, so you need to either run a
   relatively recent KDE (recommended) or at least have KDE libraries
   and the corresponding Qt libraries on your system.

Installation
------------

See INSTALL.

Support
-------

If you have any problems, questions, support requests, come to the KPlayer
user forum: http://sourceforge.net/forum/forum.php?forum_id=244388

For issues that take longer time to resolve use the issue trackers:
bugs: http://sourceforge.net/tracker/?atid=532182&group_id=71710
support requests: http://sourceforge.net/tracker/?atid=532183&group_id=71710
feature requests: http://sourceforge.net/tracker/?atid=532185&group_id=71710
that way your issue will not be lost or forgotten.

The forum and the trackers require you to be registered and logged in.
This is so that people do not post questions only to never come back to
check on the response.

There is also an IRC channel for KPlayer discussions: #kplayer on FreeNode.

Playing video DVDs and CDs, audio CDs, data CDs and DVDs, TV, and DVB
---------------------------------------------------------------------

KPlayer 0.6 and later has much improved support for disk and tuner devices.
It will detect any CD, DVD, TV and DVB devices present on your system and
list them as submenus on the File menu. For disk devices it will also detect
when a disk is inserted or removed and update the submenu accordingly.

When a disk is in the drive, the submenu will list options to play the
entire disk or each individual track or title. There is also a Load Disk
command that you will only need if the disk is already in the drive when
KPlayer starts up or if your system does not tell KPlayer when a disk is
inserted or removed.

Submenus for TV and DVB devices list options for playing each channel.
The list of channels can be chosen in the device properties. Go to the
Multimedia Library, expand the Devices subtree, right click a device and
choose Properties. The Channel List option is on the General page. There
are many more options for both disk and tuner devices.

Multimedia Library
------------------

KPlayer 0.6 and later has a multimedia library that you can use to organize
your multimedia files and streams.

The Now Playing tree lists the files, URLs and folders on your current
playlist. This playlist is temporary and will be wiped out the next time
you play anything else.

Permanent playlists live on the Playlists tree. Copy your current playlist
from Now Playing here if you want to keep it. Items on playlists can be
arranged in any order you like by dragging them around or using Move Down
and Move Up commands.

Collection tree can contain folders with items sorted by any available
field. By default only the most useful fields are displayed in both
the playlists and the collection, but other fields can be shown using the
Columns submenu on the Library menu. Some fields can be changed, those are
listed on the Edit submenu of the Library menu.

Devices tree lists the disk and tuner devices KPlayer found on your system,
and under those you will find the available tracks, titles or channels.
Devices, disks, tracks, titles and channels all have their own properties
that you can access using the Properties option on the Library menu or on
the right click context menu.

Root Directory and Home Directory list multimedia files found in those
directories and their subdirectories. Find the directories that contain
your multimedia files and put them into your collection. Then create and
organize your playlists from the collection. Both the collection and the
playlists can have as many levels as you need.

Remote files and streams can be put on the collection and playlists by
using the Add URL command on the Library menu or the right click context
menu.

Multitrack files and streams
----------------------------

Some media files and streams have more than one video, audio or subtitle
tracks in them. Those will be listed on the Video, Audio and Subtitles
submenus of the Player menu. Audio and subtitle tracks will be labelled
with their language if it is known. You can also choose the tracks in the
File Properties.

Configuration
-------------

KPlayer's initial settings have been tuned to the optimal values so that
the program should be fully usable out of the box. In fact, version 0.2
did not have a configuration dialog and was quite useful nevertheless.

For advanced users the configuration dialog offers a lot of different
settings affecting both the KPlayer user interface and MPlayer options.
If you mess KPlayer up by playing with them, the Defaults button is there
to help you out.

However, if KPlayer does not work for you in the first place, please first
test MPlayer itself from the command line to see if it needs any command
line options to work on your system. Then you can set those options in the
KPlayer configuration dialog.

Before you put anything into the Additional Command Line Arguments box,
please first look around the dialog to make sure the option you need is not
yet supported directly. For example, the only time you'll ever need to put
-ao, -ac, -vo or -vc in there is when you want to list more than one output
or codec separated by a comma. In that case please first set the respective
option on the Audio or Video page to 'auto'.

Warning about -vo sdl and -vo svga: if you set these anywhere other than the
Video page in the KPlayer config dialog, you will likely have to either wait
for your file to finish playing or kill your X session. If you really have
to, you can edit or remove the input.conf file in share/apps/kplayer, but
that is not recommended, nor are -vo sdl and -vo svga for that matter.

File properties
---------------

Starting from KPlayer 0.5 each file and URL has its own set of properties.
They include information that KPlayer found out about the file, like time
length, video size, frame rate, bitrates, and so on, as well as various
options you can set, like name, video aspect, subtitles, and many more.

Most properties can be set through the File Properties dialog. The
Properties dialog for the currently loaded file or URL can be opened from
the File menu, or using a button on the main toolbar, or from the right
click popup menu. You can also open Properties dialog for any entry in
the multimedia library by right clicking on it, or by using the Properties
command on the Library menu.

An easier way to set file properties is by holding the Shift key when
changing a setting. For example, if you hold Shift and select Soft Frame
Drop from the Player menu, KPlayer will remember that setting for the
current URL, and use it the next time you play it. After it is done playing
the current URL, it will revert the Frame Drop setting to the default, the
one that was in effect before you changed it with Shift. On the other hand,
if you change Frame Drop without holding Shift, the new setting will become
the default, and will be used for all URLs that do not have it set
explicitly.

Full screen mode
----------------

To return from the full screen mode to the normal mode just hit Ctrl+F or
right click anywhere in the video area and choose Full Screen from the menu.
Double clicking the video area also switches between full screen and normal
mode. You can also hit the Esc key, which will stop playback and end the
full screen mode.

History
-------

See ChangeLog.

Known issues
------------

See BUGS.

Online manuals and HOWTOs
-------------------------

KPlayer user manual is available online at
http://docs.kde.org/development/en/extragear-multimedia/kplayer/
or http://kplayer.sourceforge.net/manual/

In particular the manual has a few micro HOWTOs that will give you many
useful tips on how to get the most out of KPlayer and your multimedia.