<chapter id="basics">
<title>Basics</title>

<important><para>Like all &kde; applications, &kplayer; is highly configurable.
The default settings have been chosen for optimal performance and maximum
compatibility. This chapter describes how &kplayer; behaves with these default
settings.</para></important>

<sect1 id="starting">
<title>Starting &kplayer;</title>

<para>There are several ways to start &kplayer;. Which one you use is your
personal preference, and may depend on what type of media you are going to
play.</para>

<itemizedlist>

<listitem><para>From the &kmenu;, select
<menuchoice><guisubmenu>Multimedia</guisubmenu>
<guimenuitem>&kplayer;</guimenuitem></menuchoice></para></listitem>

<listitem><para>Or you can put &kplayer; icon on the desktop or on the &kicker;
panel. Then you can <mousebutton>left</mousebutton> click it to start
&kplayer;.</para></listitem>

<listitem><para><keycombo action="simul">&Alt;<keycap>F2</keycap></keycombo>
will open a <guilabel>Run Command</guilabel> dialog box, type
<userinput><command>kplayer</command></userinput> (lower case) and press
&Enter; or click the <guibutton>Run</guibutton> button.</para></listitem>

<listitem><para>In a terminal program like &konsole; type
<userinput><command>kplayer</command></userinput> and press
&Enter;.</para></listitem>

<listitem><para>Depending on the type of content you are going to play,
there may be other ways to start &kplayer;. They are described in the
sections about playing <link linkend="playing">local files</link> and
<link linkend="playing-urls">remote addresses</link>.</para></listitem>

</itemizedlist>

</sect1>

<sect1 id="playing">
<title>Playing multimedia</title>

<para>&kplayer; can play multimedia from many different sources. In addition to
<link linkend="playing-files">local files</link>, it can play
<link linkend="playing-urls">remote network addresses</link> or
<acronym>URL</acronym>s, various devices like
<link linkend="playing-devices">disks and cards</link>, and many other sources
like <link linkend="playing-slaves">network locations and compressed
files</link> using &kde; feature known as <acronym>I/O</acronym> Slaves.</para>

<sect2 id="playing-files">
<title>Local files</title>

<para>Use any of the following ways to start playing local files from your
hard drive or any other device mounted as a directory on your system.</para>

<itemizedlist>

<listitem><para>Once &kplayer; started, select
<menuchoice><guimenu>File</guimenu><guimenuitem>Open</guimenuitem></menuchoice>,
or click the <guibutton>Open</guibutton> button on the main toolbar.
The standard <guilabel>Open File</guilabel>
dialog will appear, letting you choose a local file or several files. After
you click the <guibutton>Open</guibutton> button or press &Enter;, &kplayer;
will put your selection on the playlist and start playing it.</para></listitem>

<listitem><para>&kplayer; is associated with all media file types it can play.
If a type has more than one program associated to it, you need to move &kplayer;
to the top of the list on the <guilabel>File Associations</guilabel> page in the
&konqueror; configuration dialog. Then you can simply
<mousebutton>left</mousebutton> click a media file in &konqueror; File Manager,
and it will open &kplayer; if it is not yet running and start playing the
file.</para></listitem>

<listitem><para>You can also drag files from &konqueror; File Manager and drop
them on the &kplayer; window. &kplayer; will then add the files to the playlist
and start playing them.</para></listitem>

<listitem><para>In a terminal program like &konsole; type</para>

<para><userinput><command>kplayer</command>
<filename><replaceable>filename</replaceable></filename></userinput></para>

<para>where <filename><replaceable>filename</replaceable></filename> can be an
absolute or relative path to the file you want to play, or just the file name if
the file is in the current directory. You can give multiple file names separated
with spaces. After you press &Enter;, &kplayer; will start if it is not already
running, add the files to the playlist and start playing them.</para></listitem>

</itemizedlist>

</sect2>

<sect2 id="playing-urls">
<title>Remote URLs</title>

<para>Use any of the following ways to start playing a remote file or stream
with a remote <acronym>URL</acronym> using a network protocol like
<acronym>HTTP</acronym>, <acronym>FTP</acronym>, Samba, <acronym>MMS</acronym>,
<acronym>RTSP</acronym>, <acronym>PNM</acronym>, etc.</para>

<itemizedlist>

<listitem><para>Once &kplayer; started, select
<menuchoice><guimenu>File</guimenu><guimenuitem>Open
URL</guimenuitem></menuchoice>, or click the <guibutton>Open URL</guibutton>
button on the main toolbar. The standard <guilabel>Open URL</guilabel> dialog
will appear, letting you type or paste in a remote <acronym>URL</acronym>.
After you click the <guibutton>Open</guibutton> button or press &Enter;,
&kplayer; will start playing the <acronym>URL</acronym> you
entered.</para></listitem>

<listitem><para>&kplayer; is associated with all media types it can play.
If a type has more than one program associated to it, you need to move &kplayer;
to the top of the list on the <guilabel>File Associations</guilabel> page in the
&konqueror; configuration dialog. Then you can simply
<mousebutton>left</mousebutton> click a link to a media file or stream of that
type in &konqueror; Web Browser, and it will open &kplayer; if it is not yet
running, add the link to the playlist and start playing it.</para></listitem>

<listitem><para>Sometimes a web page will have a media object embedded in
it. If &kplayer; is at the top of the list of programs associated with the
media type of the object, when you open the page in &konqueror; Web Browser
it will embed &kplayer; into the web page and start playing the media. However,
it is recommended that you <mousebutton>right</mousebutton> click the media
object and choose <guimenuitem>Start &kplayer;</guimenuitem> so that the full
&kplayer; opens up and starts playing the media. This will give you a better
interface and more options than an embedded &kplayer;.</para></listitem>

<listitem><para>Just like with <link linkend="playing-files">local files</link>,
you can start &kplayer; from a terminal program like &konsole; with the
<acronym>URL</acronym> you want to play. This is useful for example if you
copied the <acronym>URL</acronym> to the clipboard in a text editor. In the
terminal program type</para>

<para><userinput><command>kplayer</command>
<filename><replaceable>mediaurl</replaceable></filename></userinput></para>

<para>where <filename><replaceable>mediaurl</replaceable></filename> can be any
of the many <acronym>URL</acronym> types &kplayer; supports. You have to give
the full <acronym>URL</acronym>, and if it has spaces or other special
characters in it, you need to enclose the <acronym>URL</acronym> in single
quotes so your shell does not try to interpret them. You can give multiple
<acronym>URL</acronym>s separated with spaces. After you press &Enter;,
&kplayer; will start if it is not already running, add the
<acronym>URL</acronym>s to the playlist and start playing
them.</para></listitem>

</itemizedlist>

</sect2>

<sect2 id="playing-devices">
<title>DVDs, video CDs, audio CDs, TV and DVB channels</title>

<para>Just like with <link linkend="playing-urls">remote URLs</link>, select
<menuchoice><guimenu>File</guimenu>
<guimenuitem>Open URL</guimenuitem></menuchoice>, or click the
<guibutton>Open URL</guibutton> button on the main toolbar. Type one of the
following special <acronym>URL</acronym>s into the <guilabel>Open URL</guilabel>
dialog box, then click the <guibutton>Open</guibutton> button or press
&Enter;.</para>

<itemizedlist>

<listitem><para>To play a <acronym>DVD</acronym>, use <literal>dvd://1</literal>
as the <acronym>URL</acronym>. This will play the first title of the
<acronym>DVD</acronym>. To play a different title, change <literal>1</literal>
to the title number you want to play.</para></listitem>

<listitem><para>To play a video <acronym>CD</acronym>, use
<literal>vcd://1</literal>, where <literal>1</literal> is the track
number.</para></listitem>

<listitem><para>To play an audio <acronym>CD</acronym>, use
<literal>cdda://1</literal>, where <literal>1</literal> is the track number.
Another way to play an audio <acronym>CD</acronym> is by using the
<literal>audiocd</literal> <link linkend="playing-slaves"><acronym>I/O</acronym>
Slave</link>.</para></listitem>

<listitem><para>To play from a <acronym>TV</acronym> card, use
<literal>tv://1</literal>, where <literal>1</literal> is the
<acronym>TV</acronym> channel number, or <literal>tv://channelname</literal>
to refer to the channel by name.</para></listitem>

<listitem><para>To play from a <acronym>DVB</acronym> card, use
<literal>dvb://channelname</literal>, where <literal>channelname</literal>
is one of the channel names defined in <filename>channels.conf</filename> file
for &mplayer;.</para></listitem>

</itemizedlist>

<para>As always, you can start &kplayer; from a terminal program like
&konsole; with the <acronym>URL</acronym> you want to play. In the terminal
program type</para>

<para><userinput><command>kplayer</command>
<filename><replaceable>mediaurl</replaceable></filename></userinput></para>

<para>where <filename><replaceable>mediaurl</replaceable></filename> can be any
of the <acronym>URL</acronym> types described above. If the
<acronym>URL</acronym> has spaces, you need to enclose it in single quotes so
your shell does not try to interpret them. After you press &Enter;, &kplayer;
will start if it is not already running, add the <acronym>URL</acronym> to the
playlist and start playing the media.</para>

</sect2>

<sect2 id="playing-slaves">
<title>&kde; I/O slaves: fish, sftp, webdav, tar, zip, audiocd, etc.</title>

<para>&kde; has a great way to access all kinds of data through a system known
as <acronym>I/O</acronym> Slaves. They are little programs that let you
represent many different sources of data as <acronym>URL</acronym> like
addresses, and open them in &kde; programs like &konqueror; and &kplayer;.
For example you can access a network host over <acronym>SSH</acronym> with
a <acronym>URL</acronym> like
<filename>fish:/<replaceable>host/path</replaceable></filename>, or a zip file
with a <acronym>URL</acronym> like
<filename>zip:/<replaceable>home/cooldude/my.zip</replaceable></filename>.</para>

<para>So you paste a <acronym>URL</acronym> like that in &konqueror; address
bar, hit &Enter; and see the data source as if it was a usual file or a
directory with files and subdirectories in it. If one of those files happens
to be a multimedia file like an MP3 file for example, you can
<mousebutton>left</mousebutton> click it so that &kplayer; opens up and starts
playing the file, just like with plain local files. As usual, for this to work
&kplayer; needs to be the top program for that file type on the
<guilabel>File Associations</guilabel> page in &konqueror; or
&kcontrolcenter;.</para>

<para>Those same <acronym>URL</acronym>s will work in the <guilabel>Open
File</guilabel> dialog that you get when you select
<menuchoice><guimenu>File</guimenu><guimenuitem>Open</guimenuitem></menuchoice>,
or click the <guibutton>Open</guibutton> button in &kplayer;. Or if you have the
full <acronym>URL</acronym> to the media file itself, like
<filename>fish:/<replaceable>host/path/song.mp3</replaceable></filename> or
<filename>zip:/<replaceable>home/cooldude/my.zip/subdir/song.mp3</replaceable></filename>,
you can paste it into the <guilabel>Open URL</guilabel> dialog that you get by
selecting <menuchoice><guimenu>File</guimenu><guimenuitem>Open
URL</guimenuitem></menuchoice> or clicking the <guibutton>Open URL</guibutton>
button in &kplayer;.</para>

<para>Just like with <link linkend="playing-files">local files</link> and
<link linkend="playing-urls">remote addresses</link>, you can start &kplayer;
from a terminal program like &konsole; with the <acronym>URL</acronym> you want
to play. This is useful for example if you copied the <acronym>URL</acronym> to
the clipboard in a text editor. In the terminal program type</para>

<para><userinput><command>kplayer</command>
<filename><replaceable>mediaurl</replaceable></filename></userinput></para>

<para>where <filename><replaceable>mediaurl</replaceable></filename> can be any
of the many <acronym>URL</acronym> types &kplayer; supports. You have to give
the full <acronym>URL</acronym>, and if it has spaces or other special
characters in it, you need to enclose the <acronym>URL</acronym> in single
quotes so your shell does not try to interpret them. You can give multiple
<acronym>URL</acronym>s separated with spaces. After you press &Enter;,
&kplayer; will start if it is not already running, add the
<acronym>URL</acronym>s to the playlist and start playing them.</para>

</sect2>

</sect1>

<sect1 id="parts">
<title>Parts of &kplayer;</title>

<para>Here is a brief look at the main parts of &kplayer; window:</para>

<mediaobject>
<imageobject><imagedata format="PNG" fileref="dvd-bear.png"/></imageobject>
<textobject>
<phrase>A screenshot of &kplayer;</phrase>
</textobject>
</mediaobject>

<note><para>&kplayer; lets you choose what parts of it you want to be visible
and position them exactly where you want. You can use the
<link linkend="menu-settings"><guimenu>Settings</guimenu></link> menu to choose
whether to show or hide the <link linkend="parts-menu-bar">menu bar</link>,
<link linkend="parts-toolbar-main">toolbars</link>,
<link linkend="parts-playlist-editor">playlist editor</link>,
<link linkend="parts-message-log">message log</link>
and <link linkend="parts-status-bar">status bar</link>.
The <link linkend="parts-title-bar">title bar</link> as well as the window
borders will be hidden when you choose the <guimenuitem>Full
Screen</guimenuitem> option from the <guimenu>View</guimenu> menu.</para></note>

<sect2 id="parts-title-bar">
<title>Title bar</title>

<para><interface>Title bar</interface> is the strip across the top of &kplayer;
window, and operates in the same way as for other &kde; applications.
<mousebutton>Right</mousebutton> click the central portion to bring up the
<link linkend="popup-title-bar">title bar popup menu</link>.</para>

</sect2>

<sect2 id="parts-menu-bar">
<title>Menu bar</title>

<para><interface>Menu bar</interface> is the strip containing names of drop-down
menus. <mousebutton>Left</mousebutton> click a name to alternately show and hide
that menu, or use <keycombo action="simul">&Alt;<keycap>the underlined
letter</keycap></keycombo> in the name as a hot key, for example
<keycombo action="simul">&Alt;<keycap>F</keycap></keycombo> to show the
<guimenu>File</guimenu> menu. The various menus are described in the <link 
linkend="menubar">Menu bar</link> section of this document.</para>

</sect2>

<sect2 id="parts-toolbar-main">
<title>Main toolbar</title>

<para><interface>Main toolbar</interface> contains buttons for commonly used
operations. <mousebutton>Left</mousebutton> clicking an icon will activate
the corresponding action. If you have enabled tooltips in the &kcontrolcenter;
<menuchoice><guimenu>Appearance &amp; Themes</guimenu>
<guisubmenu>Style</guisubmenu></menuchoice> dialog, a brief description of what
that icon does will appear when you hover the mouse pointer over it. Some of the
main toolbar buttons will pop up slider controls when clicked. The sliders let
you change various player controls: sound volume, video contrast, brightness,
hue and saturation. The video controls will only be available for video
files. See the <link linkend="toolbar-main">Toolbars</link> section of this
manual for a full description of the buttons and their actions.</para>

</sect2>

<sect2 id="parts-toolbar-playlist">
<title>Playlist toolbar</title>

<para><interface>Playlist toolbar</interface> shows the multimedia title
currently loaded or being played, offers commands to go to the next or previous
items on the playlist, and also lets you see the entire playlist that consists
of items that are currently being played or have been played recently. If you
select a different item from the list, &kplayer; will load and start playing it.
The toolbar also contains options to loop and shuffle the playlist.
See the <link linkend="toolbar-playlist">Playlist toolbar</link> section of the
<link linkend="commands">Command reference</link> chapter of this manual for a
full description of the buttons and their actions.</para>

</sect2>

<sect2 id="parts-video-area">
<title>Video area</title>

<para><interface>Video area</interface> is the central part of &kplayer;.
When playing a file that has video, it will display the video and optionally
subtitles. Normally it will be hidden when playing an audio only file.
<mousebutton>Right</mousebutton> clicking the video area brings up the
<link linkend="popup-main">general popup menu</link>.</para>

</sect2>

<sect2 id="parts-playlist-editor">
<title>Playlist editor</title>

<para><interface>Playlist editor</interface> is a window where &kplayer;
remembers files and <acronym>URL</acronym>s you played and shows various pieces
of information about them, lets you play existing items, rename them and set
their <link linkend="properties">properties</link>, add new entries, move
entries around, remove them and choose several options. For details on the
available commands and options see the <link linkend="menu-playlist">Playlist
menu</link> section of this manual. <mousebutton>Right</mousebutton> clicking
an entry in the playlist editor brings up the
<link linkend="popup-playlist">playlist popup menu</link>. For a detailed
description of the playlist feature see the
<link linkend="howto-playlist">Playlist micro-HOWTO</link>.</para>

</sect2>

<sect2 id="parts-toolbar-editor">
<title>Playlist editor toolbar</title>

<para>This toolbar is embedded into the
<link linkend="parts-playlist-editor">Playlist editor</link> and contains
buttons that activate commands that apply to the editor and the items selected
in it. See the <link linkend="toolbar-playlist">Playlist editor toolbar</link>
section of the <link linkend="commands">Command reference</link> chapter of this
manual for a full description of the buttons and their actions.</para>

</sect2>

<sect2 id="parts-toolbar-slider">
<title>Slider toolbars</title>

<para><interface>Slider toolbars</interface> contain a slider and one or more
related buttons. The <link linkend="toolbar-progress">progress and seeking
toolbar</link> is shown when the time length of a media file is known. It
displays the playback progress and also allows seeking, that is, moving the
playback point back and forth within the file. To seek to a specific position,
drag the slider thumb to that position with the &LMB;, or simply click at that
position with the &MMB;. To move forward or backward in steps,
<mousebutton>left</mousebutton> click the slider to the left or right of the
thumb, or click the <guibutton>Forward</guibutton> and
<guibutton>Backward</guibutton> buttons.</para>

<para>Other <interface>slider toolbars</interface> show sliders for volume,
contrast, brightness, hue and saturation. These are the same sliders you get
from the pop-up slider buttons on the <link linkend="parts-toolbar-main">main
toolbar</link>, but they will not disappear when you click elsewhere. The
sliders show the current setting and allow you to change it. You can get these
toolbars using options on the
<link linkend="menu-settings"><guimenu>Settings</guimenu> menu</link>.</para>

</sect2>

<sect2 id="parts-message-log">
<title>Message log</title>

<para><interface>Message log</interface> is a window where &kplayer; shows
messages it receives from &mplayer;. This window is initially hidden but
&kplayer; can show it automatically when it detects an &mplayer; error if that
option is selected in <link linkend="settings-messages">&kplayer;
Settings</link>. <mousebutton>Right</mousebutton> clicking the message log
brings up the <link linkend="popup-message-log">message log popup
menu</link>.</para>

</sect2>

<sect2 id="parts-status-bar">
<title>Status bar</title>

<para><interface>Status bar</interface> runs across the bottom of the &kplayer;
window and shows general information about the player status and progress.</para>

<para>If and error occurs during playback, the left portion of the status bar
will show the word <guilabel>Error</guilabel>, and then you can
<mousebutton>left</mousebutton> click it to show the
<link linkend="parts-message-log">message log</link> and see the error
messages.</para>

<para>The middle portion displays the current player state, whether it is
<guilabel>Idle</guilabel>, <guilabel>Running</guilabel>,
<guilabel>Playing</guilabel> or <guilabel>Paused</guilabel>. The right portion
displays the current playback time, as well as the total time if it is
known.</para>

</sect2>

</sect1>

</chapter>