kplayer/README.md

KPlayer - a TDE 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 TDE standards.

Features include
- video, audio and subtitle playback from file, URL, DVD, VCD,
  audio CD, TV, DVB, etc., as well as TDE 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
------------

   You need to have MPlayer version 1.0rc1 or later.
   X11 is required. X.org is the best choice here.
   XVideo extension is recommended.


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.


Contributing
--------------

If you wish to contribute to kplayer, you might do so:

- TDE Gitea Workspace (TGW) collaboration tool.
  https://mirror.git.trinitydesktop.org/gitea

- TDE Weblate Translation Workspace (TWTW) collaboration tool.
  https://mirror.git.trinitydesktop.org/weblate


Translations status
---------------------

### messages
[![Translations status](https://mirror.git.trinitydesktop.org/weblate/widgets/applications/-/kplayer/multi-auto.svg
"Engage in translating")](https://mirror.git.trinitydesktop.org/weblate/projects/applications/kplayer/)

### desktop files
[![Translations status](https://mirror.git.trinitydesktop.org/weblate/widgets/applications/-/kplayer-desktop-files/multi-auto.svg
"Engage in translating")](https://mirror.git.trinitydesktop.org/weblate/projects/applications/kplayer-desktop-files/)