diff options
Diffstat (limited to 'doc/en')
56 files changed, 8405 insertions, 0 deletions
diff --git a/doc/en/Makefile.am b/doc/en/Makefile.am new file mode 100644 index 0000000..3e72f3c --- /dev/null +++ b/doc/en/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kplayer diff --git a/doc/en/basics.docbook b/doc/en/basics.docbook new file mode 100644 index 0000000..d77b616 --- /dev/null +++ b/doc/en/basics.docbook @@ -0,0 +1,513 @@ +<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>When &kplayer; is running, select +<menuchoice><guimenu>Library</guimenu><guisubmenu>Go</guisubmenu> +<guimenuitem>Home Directory</guimenuitem></menuchoice>. &kplayer; will open your +home directory in the <link linkend="parts-library"><interface>multimedia +library</interface></link> and list any multimedia files you have in it. Then +you can select the file or files you want to play or look for multimedia files +in other directories.</para></listitem> + +<listitem><para>The <interface>multimedia library</interface> allows you to +organize your multimedia collection for easier access. For example, once you +create some playlists, playing one of them becomes as easy as selecting +<menuchoice><guimenu>File</guimenu><guisubmenu>Play List</guisubmenu> +</menuchoice> and then selecting the playlist name from the +submenu.</para></listitem> + +<listitem><para>If your file does not show up in the library, select +<menuchoice><guimenu>File</guimenu><guimenuitem>Play...</guimenuitem></menuchoice>, +or click the <guibutton>Play</guibutton> button on the main toolbar. +The standard <guilabel>Play files</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 current 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 execute a media file in +&konqueror; File Manager with the <mousebutton>left</mousebutton> mouse button, +and it will open &kplayer; if it is not yet running and start playing the +file.</para></listitem> + +<listitem><para><mousebutton>Right</mousebutton> click context menu in +&konqueror; File Manager will show the <guimenuitem>Play</guimenuitem> command +when a multimedia file or files are selected. Selecting the command will open +&kplayer;, put all the selected files on the current playlist and play them. +You can also <mousebutton>right</mousebutton> click a directory and play all +multimedia files contained in it and in all of its +subdirectories.</para></listitem> + +<listitem><para>You can also drag files and directories from &konqueror; File +Manager and drop them on the &kplayer; window. &kplayer; will then put them on +the current 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 or directory you want to play, or just the +name if the file or directory is in the current directory. You can give multiple +file and directory names separated with spaces. After you press &Enter;, +&kplayer; will start if it is not already running, add the files and directories +to the current 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; starts, select +<menuchoice><guimenu>File</guimenu><guimenuitem>Play +URL...</guimenuitem></menuchoice>, or click the <guibutton>Play URL</guibutton> +button on the main toolbar. The standard <guilabel>Play 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, put the link on the <link linkend="parts-toolbar-playlist">current +playlist</link> 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, put the +<acronym>URL</acronym>s on the <link linkend="parts-toolbar-playlist">current +playlist</link> and start playing them.</para></listitem> + +<listitem><para>And of course you can keep your favorite multimedia links in the +<link linkend="parts-library">multimedia library</link> and include them on your +playlists. Then you can play a playlist by choosing its name from the +<menuchoice><guimenu>File</guimenu><guisubmenu>Play +List</guisubmenu></menuchoice> submenu.</para></listitem> + +</itemizedlist> + +</sect2> + +<sect2 id="playing-devices"> +<title>Disk and tuner devices</title> + +<para>&kplayer; finds any disk and tuner devices you have on your computer +and shows them on the <link linkend="submenu-device"><guimenu>File</guimenu> +menu</link> and in the <interface>Devices</interface> section of the <link +linkend="parts-library">multimedia library</link>.</para> + +<para>When you insert a disk into a <acronym>DVD</acronym> or +<acronym>CD</acronym> device, &kplayer; finds the titles or tracks on the disk +and shows them on the <link linkend="submenu-device">device submenu</link> under +the <guimenu>File</guimenu> menu as well as in the <interface>multimedia +library</interface>.</para> + +<para>To play the whole disk:</para> + +<itemizedlist> + +<listitem><para>Select <menuchoice><guimenuitem>Play +Disk</guimenuitem></menuchoice> from the device submenu under the +<guimenu>File</guimenu> menu, or</para></listitem> + +<listitem><para><mousebutton>Right</mousebutton> click the device node in the +<interface>Devices</interface> section of the <interface>multimedia +library</interface> and select +<menuchoice><guimenuitem>Play</guimenuitem></menuchoice>, or</para></listitem> + +<listitem><para><mousebutton>Left</mousebutton> click the disk icon when it +shows in the <interface>Devices</interface> applet in the &kde; task bar and +select <menuchoice><guimenuitem>Play</guimenuitem></menuchoice> from the +menu, or</para></listitem> + +<listitem><para><mousebutton>Right</mousebutton> click the disk icon when it +shows on the desktop and select +<menuchoice><guimenuitem>Play</guimenuitem></menuchoice> from the +menu.</para></listitem> + +</itemizedlist> + +<para>To play a title or track:</para> + +<itemizedlist> + +<listitem><para>Select the title or track from the device submenu under the +<guimenu>File</guimenu> menu, or</para></listitem> + +<listitem><para>Open the device node in the <interface>Devices</interface> +section of the <interface>multimedia library</interface> and execute the title +or track with the <mousebutton>left</mousebutton> mouse button or +<mousebutton>right</mousebutton> click it and select +<menuchoice><guimenuitem>Play</guimenuitem></menuchoice>.</para></listitem> + +</itemizedlist> + +<para>For tuner devices like <acronym>TV</acronym> or <acronym>DVB</acronym> +&kplayer; shows the available channels on the device submenu under the +<guimenu>File</guimenu> menu as well as under the device node in the +<interface>Devices</interface> section of the <interface>multimedia +library</interface>.</para> + +<para>To play a channel:</para> + +<itemizedlist> + +<listitem><para>Select the channel from the device submenu under the +<guimenu>File</guimenu> menu, or</para></listitem> + +<listitem><para>Open the device node in the <interface>Devices</interface> +section of the <interface>multimedia library</interface> and execute the channel +with the <mousebutton>left</mousebutton> mouse button or +<mousebutton>right</mousebutton> click it and select +<menuchoice><guimenuitem>Play</guimenuitem></menuchoice>.</para></listitem> + +</itemizedlist> + +</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 execute it with +the <mousebutton>left</mousebutton> mouse button 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>Play +files</guilabel> dialog that you get when you select +<menuchoice><guimenu>File</guimenu><guimenuitem>Play...</guimenuitem></menuchoice>, +or click the <guibutton>Play</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>Play URL</guilabel> dialog that you get by +selecting <menuchoice><guimenu>File</guimenu><guimenuitem>Play +URL...</guimenuitem></menuchoice> or clicking the <guibutton>Play 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> + +<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>, +the <link linkend="parts-library">multimedia library</link>, +the <link linkend="parts-message-log">message log</link> +and the <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> + +<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 & 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-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-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 an 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> + +<sect2 id="parts-library"> +<title>Multimedia library</title> + +<mediaobject> +<imageobject><imagedata format="PNG" fileref="multimedia-library.png"/></imageobject> +<textobject> +<phrase>A screenshot of the multimedia library</phrase> +</textobject> +</mediaobject> + +<para><interface>Multimedia library</interface> allows you to easily access the +multimedia available to you from your computer. In the <interface>multimedia +library</interface> window you can browse directories mounted on your system +for multimedia files, which include all video, audio and playlist files. +A separate section shows your <acronym>CD</acronym> and <acronym>DVD</acronym> +drives, disks you insert in them, titles or tracks on those disks, as well as +tuner devices like <acronym>TV</acronym> or <acronym>DVB</acronym> cards you +have on your system and channels available on those devices.</para> + +<para>Other sections allow you to organize your multimedia files and links +to Internet media in a multimedia collection, create playlists, and view the +currently and recently played multimedia. You can use the commands on the <link +linkend="menu-library"><guimenu>Library</guimenu> menu</link> or the <link +linkend="popup-library"><mousebutton>right</mousebutton> click menu</link> to +add entries to the collection and playlists, move them around, and play your +selection. Additional commands allow you to show or change various information +about the media and its <link linkend="properties">properties</link>.</para> + +<para>For details on the available commands and options see the <link +linkend="menu-library"><guilabel>Library</guilabel> menu</link> and the <link +linkend="popup-library">library popup menu</link> sections of this manual. +For a detailed description of the multimedia library feature see the +<link linkend="howto-library">Multimedia library micro-HOWTO</link>.</para> + +</sect2> + +<sect2 id="parts-message-log"> +<title>Message log</title> + +<mediaobject> +<imageobject><imagedata format="PNG" fileref="message-log.png"/></imageobject> +<textobject> +<phrase>A screenshot of the message log</phrase> +</textobject> +</mediaobject> + +<para><interface>Message log</interface> is a window where &kplayer; shows +messages it receives from &mplayer; and &kde; <acronym>I/O</acronym> Slaves. +<mousebutton>Right</mousebutton> clicking the message log brings up the <link +linkend="popup-message-log">message log popup menu</link> that allows you to +select all messages, copy the current selection or remove all messages.</para> + +</sect2> + +</sect1> + +</chapter> diff --git a/doc/en/commands.docbook b/doc/en/commands.docbook new file mode 100644 index 0000000..df67d1f --- /dev/null +++ b/doc/en/commands.docbook @@ -0,0 +1,1940 @@ +<chapter id="commands"> +<title>Command reference</title> + +<para>The shortcut key combinations shown in this chapter are the default +ones. They can of course be +<link linkend="configuration-shortcuts">changed</link>.</para> + +<sect1 id="menubar"> +<title>Menu bar</title> + +<para>Note that many menu entries are only enabled when they are applicable +to the file currently loaded in &kplayer;. For example, the items on the +<guimenu>View</guimenu> menu will be disabled when playing audio only +files.</para> + +<sect2 id="menu-file"> +<title><guimenu>File</guimenu> menu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo> +</shortcut> +<guimenuitem>Play...</guimenuitem> +</menuchoice></term> +<listitem><para>Displays the standard <guilabel>Play files</guilabel> dialog +and lets you choose a file or several files to put on the playlist and start +playing.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>U</keycap></keycombo> +</shortcut> +<guimenuitem>Play URL...</guimenuitem> +</menuchoice></term> +<listitem><para>Displays the standard <guilabel>Play URL</guilabel> dialog +and lets you type or paste in a <acronym>URL</acronym> to put on the playlist +and start playing. The <acronym>URL</acronym> can be a remote network location, +a local file path, or a &kde; <acronym>I/O</acronym> Slave +<acronym>URL</acronym>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guisubmenu>Play List</guisubmenu> +</menuchoice></term> +<listitem><para>Displays a submenu listing all playlists and lets you choose one +of them to play.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guisubmenu>Play Recent</guisubmenu> +</menuchoice></term> +<listitem><para>Displays a submenu listing the most recently played files and +<acronym>URL</acronym>s and lets you choose one to put on the playlist and start +playing.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guisubmenu>Device</guisubmenu> +</menuchoice></term> +<listitem><para>Displays a submenu with commands for the particular device. Each +device has its own submenu. The submenu label reflects the kind of device it is, +for example <guilabel>TV Device</guilabel> or <guilabel>DVD Device</guilabel>. +When you put a disk in a disk drive, after a few seconds the label will change +to reflect the kind of disk you inserted, for example <guilabel>Audio CD in DVD +Device</guilabel>. The list of commands on the submenu will also be updated +accordingly to include commands applicable to the disk and the tracks it has. +See <link linkend="submenu-device">below</link> for details about the +commands.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo> +</shortcut> +<guimenuitem>Load Subtitles...</guimenuitem> +</menuchoice></term> +<listitem><para>Displays the standard <guilabel>Load subtitles</guilabel> dialog +and lets you choose a subtitle file or files to use with the current file or +<acronym>URL</acronym>.</para> +<para>After you click <guibutton>Open</guibutton>, &kplayer; +will start showing subtitles from the first of the files immediately if the +video is already playing, and list the subtitle files on the <link +linkend="submenu-subtitles"><guisubmenu>Subtitles</guisubmenu> submenu</link> +of the <guimenu>Player</guimenu> menu. By default it will also remember the +subtitles you choose in the current file +<link linkend="properties">properties</link>.</para> +<para>This command is available for video files. You can also drag subtitle +files from &konqueror; File Manager and drop them anywhere in &kplayer; except +the <interface>multimedia library</interface> to load and display +them.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Alt;&Enter;</keycombo> +</shortcut> +<guimenuitem>Properties...</guimenuitem> +</menuchoice></term> +<listitem><para>Opens the <link linkend="properties">File Properties</link> +dialog that lets you choose many options specific to the currently loaded file. +See the <link linkend="howto-properties">File properties micro-HOWTO</link> +for details.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo> +</shortcut> +<guimenuitem>Quit</guimenuitem> +</menuchoice></term> +<listitem><para>Saves the playlist and all settings, stops playing and closes +&kplayer;.</para></listitem> +</varlistentry> + +</variablelist> + +<sect3 id="submenu-device"> +<title><guisubmenu>Device</guisubmenu> submenu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Play Disk</guimenuitem> +</menuchoice></term> +<listitem><para>Plays the entire disk. This command is available if the device +is a disk drive.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Play Title</guimenuitem> +</menuchoice></term> +<listitem><para>Plays one title of a video <acronym>DVD</acronym>. This command +is available when &kplayer; detects a video <acronym>DVD</acronym> in a +<acronym>DVD</acronym> drive and finds out the number of titles on it. Each +title on the <acronym>DVD</acronym> has its own command on this +submenu.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Play Track</guimenuitem> +</menuchoice></term> +<listitem><para>Plays one track of an audio or video <acronym>CD</acronym>. This +command is available when &kplayer; detects an audio or video +<acronym>CD</acronym> in a disk drive and finds out the number of tracks on it. +Each track on the <acronym>CD</acronym> has its own command on this +submenu.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Load Disk</guimenuitem> +</menuchoice></term> +<listitem><para>Detects the kind of disk that is in the disk drive, finds the +number of titles or tracks on the disk and updates the submenu accordingly. +Usually &kplayer; detects this information automatically, but sometimes this +command can be useful to initiate the detection process manually. This command +is available if the device is a disk drive.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Play Channel</guimenuitem> +</menuchoice></term> +<listitem><para>Plays a channel from a tuner device. This command is available +if the device is a tuner device. Each channel on the device has its own command +on this submenu.</para></listitem> +</varlistentry> + +</variablelist> + +</sect3> + +</sect2> + +<sect2 id="menu-view"> +<title><guimenu>View</guimenu> menu</title> + +<para>Commands on this menu are only available for video files.</para> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>F</keycap></keycombo> +</shortcut> +<guimenuitem>Full Screen</guimenuitem> +</menuchoice></term> +<listitem><para>Switches to <link linkend="howto-full-screen">full screen</link> +video display and back to normal mode. Double clicking the video area also +switches between full screen and normal window size.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>+</keycap></keycombo> +</shortcut> +<guimenuitem>Zoom In</guimenuitem> +</menuchoice></term> +<listitem><para>Enlarges the video area by one half of the original +video size of the current file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>-</keycap></keycombo> +</shortcut> +<guimenuitem>Zoom Out</guimenuitem> +</menuchoice></term> +<listitem><para>Reduces the video area by one half of the original +video size of the current file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Zoom to 50%</guimenuitem> +</menuchoice></term> +<listitem><para>Resizes the video area to one half of the original +video size of the current file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;&Backspace;</keycombo> +</shortcut> +<guimenuitem>Zoom to 100%</guimenuitem> +</menuchoice></term> +<listitem><para>Resizes the video area to the original +video size of the current file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Zoom to 150%</guimenuitem> +</menuchoice></term> +<listitem><para>Resizes the video area to 150% of the original +video size of the current file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Zoom to 200%</guimenuitem> +</menuchoice></term> +<listitem><para>Resizes the video area to twice the original +video size of the current file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Zoom to 250%</guimenuitem> +</menuchoice></term> +<listitem><para>Resizes the video area to 250% of the original +video size of the current file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Zoom to 300%</guimenuitem> +</menuchoice></term> +<listitem><para>Resizes the video area to thrice the original +video size of the current file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Maintain Original Aspect</guimenuitem> +</menuchoice></term> +<listitem><para>Toggles the option to maintain the original video aspect +ratio of the current file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Maintain Current Aspect</guimenuitem> +</menuchoice></term> +<listitem><para>Toggles the option to maintain the current video aspect +ratio.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Force 4 to 3 Aspect</guimenuitem> +</menuchoice></term> +<listitem><para>Toggles the option to maintain four to three video aspect +ratio.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Force 16 to 9 Aspect</guimenuitem> +</menuchoice></term> +<listitem><para>Toggles the option to maintain sixteen to nine video aspect +ratio.</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="menu-player"> +<title><guimenu>Player</guimenu> menu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<shortcut> +&Enter; +</shortcut> +<guimenuitem>Play</guimenuitem> +</menuchoice></term> +<listitem><para>Starts playback of the current file. If the player has been +paused, this command resumes playback. This command is available when +a file is loaded.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycap>Space</keycap> +</shortcut> +<guimenuitem>Pause</guimenuitem> +</menuchoice></term> +<listitem><para>Pauses or resumes playback of the current file. This command +is available when the player is not idle.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +&Esc; +</shortcut> +<guimenuitem>Stop</guimenuitem> +</menuchoice></term> +<listitem><para>Stops playback of the current file. This command +is available when the player is not idle.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Alt;<keycap>Down Arrow</keycap></keycombo> +</shortcut> +<guimenuitem>Next</guimenuitem> +</menuchoice></term> +<listitem><para>Starts playing the next item on the current +playlist.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Alt;<keycap>Up Arrow</keycap></keycombo> +</shortcut> +<guimenuitem>Previous</guimenuitem> +</menuchoice></term> +<listitem><para>Starts playing the previous item on the current +playlist.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Loop</guimenuitem> +</menuchoice></term> +<listitem><para>Toggles the option to start playing items from the beginning +of the playlist after playing the last item on the playlist.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Shuffle</guimenuitem> +</menuchoice></term> +<listitem><para>Toggles the option to play playlist items in a random +order.</para></listitem> +</varlistentry> + +</variablelist> + +<sect3 id="submenu-position"> +<title><guisubmenu>Position</guisubmenu> submenu</title> + +<para>This submenu and the commands it contains are available when playing a +file.</para> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycap>Right Arrow</keycap> +</shortcut> +<guimenuitem>Forward</guimenuitem> +</menuchoice></term> +<listitem><para>Moves playback forward by one percent of the time length of the +current file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>Right Arrow</keycap></keycombo> +</shortcut> +<guimenuitem>Fast Forward</guimenuitem> +</menuchoice></term> +<listitem><para>Moves playback forward by ten percent of the time length of the +current file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycap>Left Arrow</keycap> +</shortcut> +<guimenuitem>Backward</guimenuitem> +</menuchoice></term> +<listitem><para>Moves playback backward by one percent of the time length of the +current file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>Left Arrow</keycap></keycombo> +</shortcut> +<guimenuitem>Fast Backward</guimenuitem> +</menuchoice></term> +<listitem><para>Moves playback backward by ten percent of the time length of the +current file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>Home</keycap></keycombo> +</shortcut> +<guimenuitem>Back to Start</guimenuitem> +</menuchoice></term> +<listitem><para>Moves playback to the beginning of the current +file.</para></listitem> +</varlistentry> + +</variablelist> + +</sect3> + +<sect3 id="submenu-audio"> +<title><guisubmenu>Audio</guisubmenu> submenu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Track</guimenuitem> +</menuchoice></term> +<listitem><para>Switches to the selected audio track. If the currently loaded +file or stream has more than one audio track, each track will have a command +that allows you to switch to that audio track. The command will be labelled with +the audio track language if it is known. If there is only one audio track, this +command will not be available.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycap>Down Arrow</keycap> +</shortcut> +<guimenuitem>Decrease Volume</guimenuitem> +</menuchoice></term> +<listitem><para>Decreases the sound volume.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycap>Up Arrow</keycap> +</shortcut> +<guimenuitem>Increase Volume</guimenuitem> +</menuchoice></term> +<listitem><para>Increases the sound volume.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>\</keycap></keycombo> +</shortcut> +<guimenuitem>Mute</guimenuitem> +</menuchoice></term> +<listitem><para>Turns the sound on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>]</keycap></keycombo> +</shortcut> +<guimenuitem>Decrease Delay</guimenuitem> +</menuchoice></term> +<listitem><para>Decreases the delay of sound relative to video.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>[</keycap></keycombo> +</shortcut> +<guimenuitem>Increase Delay</guimenuitem> +</menuchoice></term> +<listitem><para>Increases the delay of sound relative to video.</para></listitem> +</varlistentry> + +</variablelist> + +</sect3> + +<sect3 id="submenu-video"> +<title><guisubmenu>Video</guisubmenu> submenu</title> + +<para>This submenu is only available for video files.</para> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Track</guimenuitem> +</menuchoice></term> +<listitem><para>Switches to the selected video track. If the currently loaded +file or stream has more than one video track, each track will have a command +that allows you to switch to that video track. If there is only one video track, +this command will not be available.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>1</keycap></keycombo> +</shortcut> +<guimenuitem>Decrease Contrast</guimenuitem> +</menuchoice></term> +<listitem><para>Decreases the video contrast.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>2</keycap></keycombo> +</shortcut> +<guimenuitem>Increase Contrast</guimenuitem> +</menuchoice></term> +<listitem><para>Increases the video contrast.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>3</keycap></keycombo> +</shortcut> +<guimenuitem>Decrease Brightness</guimenuitem> +</menuchoice></term> +<listitem><para>Decreases the video brightness.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>4</keycap></keycombo> +</shortcut> +<guimenuitem>Increase Brightness</guimenuitem> +</menuchoice></term> +<listitem><para>Increases the video brightness.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>5</keycap></keycombo> +</shortcut> +<guimenuitem>Decrease Hue</guimenuitem> +</menuchoice></term> +<listitem><para>Decreases the video hue.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>6</keycap></keycombo> +</shortcut> +<guimenuitem>Increase Hue</guimenuitem> +</menuchoice></term> +<listitem><para>Increases the video hue.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>7</keycap></keycombo> +</shortcut> +<guimenuitem>Decrease Saturation</guimenuitem> +</menuchoice></term> +<listitem><para>Decreases the video saturation.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>8</keycap></keycombo> +</shortcut> +<guimenuitem>Increase Saturation</guimenuitem> +</menuchoice></term> +<listitem><para>Increases the video saturation.</para></listitem> +</varlistentry> + +</variablelist> + +</sect3> + +<sect3 id="submenu-subtitles"> +<title><guisubmenu>Subtitles</guisubmenu> submenu</title> + +<para>This menu is only available when a video file has embedded subtitles or +when external subtitles are loaded.</para> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<guimenuitem>None</guimenuitem> +</menuchoice></term> +<listitem><para>Stops showing subtitles while playing video.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Track</guimenuitem> +</menuchoice></term> +<listitem><para>Switches to the selected subtitles. If the currently loaded +file or stream has embedded subtitle tracks, each track will have a command +that allows you to switch to that subtitle track. The command will be labelled +with the subtitle track language if it is known. If you load external subtitles, +they will also have a command, labelled with the subtitle file name, that allows +you to switch to the external subtitles.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>,</keycap></keycombo> +</shortcut> +<guimenuitem>Move Down</guimenuitem> +</menuchoice></term> +<listitem><para>Moves the subtitles down in the video area.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>.</keycap></keycombo> +</shortcut> +<guimenuitem>Move Up</guimenuitem> +</menuchoice></term> +<listitem><para>Moves the subtitles up in the video area.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>'</keycap></keycombo> +</shortcut> +<guimenuitem>Decrease Delay</guimenuitem> +</menuchoice></term> +<listitem><para>Decreases the delay of subtitles relative to video.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>;</keycap></keycombo> +</shortcut> +<guimenuitem>Increase Delay</guimenuitem> +</menuchoice></term> +<listitem><para>Increases the delay of subtitles relative to video.</para></listitem> +</varlistentry> + +</variablelist> + +</sect3> + +<sect3 id="submenu-advanced"> +<title><guisubmenu>Advanced</guisubmenu> submenu</title> + +<para>If your system is too slow to play a file, &mplayer; can drop some frames +so playback does not slow down. This submenu lets you choose a frame dropping +option. The soft frame dropping option drops frames less agressively than the +hard one and should not cause playback problems. You should try it when you get +video lagging behind audio, for example because you cannot use an accelerated +video output. The hard option drops frames more agressively than the soft one +and may sometimes break decoding.</para> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Soft Frame Dropping</guimenuitem> +</menuchoice></term> +<listitem><para>Toggles the soft frame dropping option.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Hard Frame Dropping</guimenuitem> +</menuchoice></term> +<listitem><para>Toggles the hard frame dropping option.</para></listitem> +</varlistentry> + +</variablelist> + +<para>To turn frame dropping off, unselect the currently selected frame dropping +option. The <guilabel>Frame drop</guilabel> option can also be set on the +<guilabel>Advanced</guilabel> page either globally in <link +linkend="settings-advanced">&kplayer; Settings</link> or for a particular file +in the <link linkend="properties-advanced">File Properties</link>.</para> + +</sect3> + +</sect2> + +<sect2 id="menu-library"> +<title><guimenu>Library</guimenu> menu</title> + +<para>The commands on this menu work on the <link +linkend="parts-library">multimedia library</link>. Most of the commands are +available when the library is shown using the <guimenuitem>Show +Library</guimenuitem> command on the <link +linkend="menu-settings"><guimenu>Settings</guimenu> menu</link> or one of the +commands on the <link linkend="submenu-go"><guisubmenu>Go</guisubmenu> +submenu</link>. Other commands become available when you select some items in +the library. For a detailed description of the multimedia library feature see +the <link linkend="howto-library">Multimedia library micro-HOWTO</link>.</para> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>Enter</keycap></keycombo> +</shortcut> +<guimenuitem>Play</guimenuitem> +</menuchoice></term> +<listitem><para>Puts the selected items on the current playlist and starts +playing them.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Play Next</guimenuitem> +</menuchoice></term> +<listitem><para>Puts the selected items on the current playlist and plays them +after the currently playing item.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Queue</guimenuitem> +</menuchoice></term> +<listitem><para>Adds the selected items to the current +playlist.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Queue Next</guimenuitem> +</menuchoice></term> +<listitem><para>Adds the selected items to the current playlist and plays them +after the currently playing item.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Add to</guimenuitem> +</menuchoice></term> +<listitem><para>Shows a submenu with commands that add the current selection to +different locations in the <interface>multimedia library</interface>. +See <link linkend="submenu-add-to">below</link> for details on each available +command.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Add</guimenuitem> +</menuchoice></term> +<listitem><para>Shows a submenu with commands that allow you to add items to the +current folder. See <link linkend="submenu-add">below</link> for details on each +available command.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Select All</guimenuitem> +</menuchoice></term> +<listitem><para>Selects all items in the current folder.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Move Up</guimenuitem> +</menuchoice></term> +<listitem><para>Moves the currently selected items up in the +<interface>multimedia library</interface>. This command is available for items +in the <guilabel>Now Playing</guilabel>, <guilabel>Recent</guilabel> and +<guilabel>Playlists</guilabel> sections of the library. You can also move items +around in those sections by clicking and dragging them with the +&LMB;.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Move Down</guimenuitem> +</menuchoice></term> +<listitem><para>Moves the currently selected items down in the +<interface>multimedia library</interface>. This command is available for items +in the <guilabel>Now Playing</guilabel>, <guilabel>Recent</guilabel> and +<guilabel>Playlists</guilabel> sections of the library. You can also move items +around in those sections by clicking and dragging them with the +&LMB;.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycap>Delete</keycap> +</shortcut> +<guimenuitem>Remove</guimenuitem> +</menuchoice></term> +<listitem><para>Removes the currently selected items from the +<interface>multimedia library</interface>. Note that &kplayer; never deletes any +multimedia files from your system, so this command is not available for files +and directories.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycap>F2</keycap> +</shortcut> +<guimenuitem>Rename</guimenuitem> +</menuchoice></term> +<listitem><para>Starts edit mode for the current item in the +<interface>multimedia library</interface> so that you can change the item +name.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Edit</guimenuitem> +</menuchoice></term> +<listitem><para>Shows a submenu with commands that start edit mode for the +chosen field of the current item in the <interface>multimedia +library</interface>. Each editable field has its own command on this submenu. +If the field column is not shown, this command will show it. After you are done +editing the field, press &Enter; to apply the changes, or 	 or +<keycombo action="simul">&Shift;	</keycombo> to apply the changes and edit +the next or the previous field, or <keycap>Down Arrow</keycap> or <keycap>Up +Arrow</keycap> to apply the changes and edit the same field of the next or +previous item.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Properties...</guimenuitem> +</menuchoice></term> +<listitem><para>Opens the <link linkend="properties">File Properties</link> +dialog for the current item in the <interface>multimedia library</interface>. +This command currently does not apply to folders, but it is available for +devices and optical disks as well as other items. See the +<link linkend="howto-properties">File properties micro-HOWTO</link> for +details.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Columns</guimenuitem> +</menuchoice></term> +<listitem><para>Shows a submenu with commands that show or hide the chosen +column in the <interface>list view</interface> of the <interface>multimedia +library</interface>. Each available column has its own command on this +submenu.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Go</guimenuitem> +</menuchoice></term> +<listitem><para>Shows a submenu with commands that let you navigate the +<interface>multimedia library</interface>. +See <link linkend="submenu-go">below</link> for details on each available +command.</para></listitem> +</varlistentry> + +</variablelist> + +<sect3 id="submenu-add-to"> +<title><guisubmenu>Add to</guisubmenu> submenu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Playlist</guimenuitem> +</menuchoice></term> +<listitem><para>Adds the selected items to the playlist you choose from the +list. Each playlist in the <guilabel>Playlist</guilabel>s section of the library +has its own command on this submenu.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>New Playlist...</guimenuitem> +</menuchoice></term> +<listitem><para>Shows a dialog allowing you to enter a name for a new playlist +to add to the <guilabel>Playlists</guilabel> section of the +<interface>multimedia library</interface> and adds the selected items to the new +playlist.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Playlists</guimenuitem> +</menuchoice></term> +<listitem><para>Adds the selected items to the <guilabel>Playlists</guilabel> +section of the <interface>multimedia library</interface>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Collection</guimenuitem> +</menuchoice></term> +<listitem><para>Adds the selected items to the <guilabel>Collection</guilabel> +section of the <interface>multimedia library</interface>.</para></listitem> +</varlistentry> + +</variablelist> + +</sect3> + +<sect3 id="submenu-add"> +<title><guisubmenu>Add</guisubmenu> submenu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Files...</guimenuitem> +</menuchoice></term> +<listitem><para>Displays the standard <guilabel>Add files</guilabel> dialog +and lets you choose a file or several files to add to the current +folder.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>URL...</guimenuitem> +</menuchoice></term> +<listitem><para>Displays the standard <guilabel>Add URL</guilabel> dialog +and lets you type or paste in a <acronym>URL</acronym> to add to the current +folder.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Folder...</guimenuitem> +</menuchoice></term> +<listitem><para>Shows a dialog allowing you to enter a name for a new subfolder +to add to the current folder.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Playlist...</guimenuitem> +</menuchoice></term> +<listitem><para>Shows a dialog allowing you to enter a name for a new playlist +to add to the playlist selected in the <interface>multimedia +library</interface>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Device...</guimenuitem> +</menuchoice></term> +<listitem><para>Shows a dialog allowing you to enter a name, type and path for a +new device to add to the <guilabel>Devices</guilabel> section of the +<interface>multimedia library</interface>. Some device types need additional +settings. See the <link linkend="howto-devices">Devices micro-HOWTO</link> for +details.</para></listitem> +</varlistentry> + +</variablelist> + +</sect3> + +<sect3 id="submenu-go"> +<title><guisubmenu>Go</guisubmenu> submenu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Folder</guimenuitem> +</menuchoice></term> +<listitem><para>Opens the selected folder in the <interface>multimedia +library</interface>. If the library window is not shown, this command will show +it. Each folder in the recent history has its own command on this submenu. Each +top level folder also has its own command.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Alt;<keycap>Left Arrow</keycap></keycombo> +</shortcut> +<guimenuitem>Back</guimenuitem> +</menuchoice></term> +<listitem><para>Opens the previous folder.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Alt;<keycap>Right Arrow</keycap></keycombo> +</shortcut> +<guimenuitem>Forward</guimenuitem> +</menuchoice></term> +<listitem><para>Opens the next folder. This command will be available after you +use the <guimenuitem>Back</guimenuitem> command.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Alt;&Shift;<keycap>Up Arrow</keycap></keycombo> +</shortcut> +<guimenuitem>Up</guimenuitem> +</menuchoice></term> +<listitem><para>Opens the parent folder of the selected +folder.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Alt;&Shift;<keycap>Down Arrow</keycap></keycombo> +</shortcut> +<guimenuitem>Down</guimenuitem> +</menuchoice></term> +<listitem><para>Opens the selected folder.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Alt;&Shift;<keycap>Left Arrow</keycap></keycombo> +</shortcut> +<guimenuitem>To Origin</guimenuitem> +</menuchoice></term> +<listitem><para>Opens the origin folder of the selected folder. This command is +available when the currently selected folder is linked to an origin folder. For +an explanation of linked folders, see the +<link linkend="howto-library-linked-folders">Multimedia library +micro-HOWTO</link>.</para></listitem> +</varlistentry> + +</variablelist> + +</sect3> + +</sect2> + +<sect2 id="menu-settings"> +<title><guimenu>Settings</guimenu> menu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>M</keycap></keycombo> +</shortcut> +<guimenuitem>Show Menubar</guimenuitem> +</menuchoice></term> +<listitem><para>Shows or hides the <link linkend="parts-menu-bar">menu +bar</link>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Show Statusbar</guimenuitem> +</menuchoice></term> +<listitem><para>Shows or hides the <link linkend="parts-status-bar">status +bar</link>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo> +</shortcut> +<guimenuitem>Show Playlist</guimenuitem> +</menuchoice></term> +<listitem><para>Shows or hides the +<link linkend="parts-toolbar-playlist">playlist +toolbar</link>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>L</keycap></keycombo> +</shortcut> +<guimenuitem>Show Library</guimenuitem> +</menuchoice></term> +<listitem><para>Shows or hides the +<link linkend="parts-library">multimedia library</link>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>G</keycap></keycombo> +</shortcut> +<guimenuitem>Show Message Log</guimenuitem> +</menuchoice></term> +<listitem><para>Shows or hides the <link linkend="parts-message-log">message +log</link>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Show Main Toolbar</guimenuitem> +</menuchoice></term> +<listitem><para>Shows or hides the <link linkend="toolbar-main">main +toolbar</link>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Show Progress Toolbar</guimenuitem> +</menuchoice></term> +<listitem><para>Shows or hides the <link linkend="toolbar-progress">progress +toolbar</link>. This command is available when the time length of the current +file is known.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Show Volume Toolbar</guimenuitem> +</menuchoice></term> +<listitem><para>Shows or hides the <link linkend="toolbar-volume">volume +toolbar</link>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Show Contrast Toolbar</guimenuitem> +</menuchoice></term> +<listitem><para>Shows or hides the <link linkend="toolbar-contrast">contrast +toolbar</link>. This command is available for video files.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Show Brightness Toolbar</guimenuitem> +</menuchoice></term> +<listitem><para>Shows or hides the <link linkend="toolbar-brightness">brightness +toolbar</link>. This command is available for video files.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Show Hue Toolbar</guimenuitem> +</menuchoice></term> +<listitem><para>Shows or hides the <link linkend="toolbar-hue">hue +toolbar</link>. This command is available for video files.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Show Saturation Toolbar</guimenuitem> +</menuchoice></term> +<listitem><para>Shows or hides the <link linkend="toolbar-saturation">saturation +toolbar</link>. This command is available for video files.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Configure Shortcuts...</guimenuitem> +</menuchoice></term> +<listitem><para>Opens a <link linkend="configuration-shortcuts">dialog</link> +that lets you see and change &kplayer;'s shortcut key bindings, or associations +between actions and the corresponding keys or combinations of keys that activate +them. If you change the bindings, make sure not to duplicate an existing +shortcut and also not to use the &Shift; key for your new shortcuts, because the +&Shift; key has a <link linkend="howto-properties">special function</link> in +&kplayer;.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Configure Toolbars...</guimenuitem> +</menuchoice></term> +<listitem><para>Opens a <link linkend="configuration-toolbars">dialog</link> +that lets you see and change the command buttons available on &kplayer;'s +toolbars.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Configure &kplayer;...</guimenuitem> +</menuchoice></term> +<listitem><para>Opens a dialog that lets you configure the program, modifying +various aspects of its functionality, user interface and interaction with +&mplayer;. For more information see the <link linkend="settings">Configuration +dialog chapter</link> and the <link linkend="howto-settings">Advanced +configuration micro-HOWTO</link> in this manual.</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="menu-help"> +<title><guimenu>Help</guimenu> menu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<guimenuitem>&kplayer; Handbook</guimenuitem> +</menuchoice></term> +<listitem><para>Opens and displays the &kplayer; user manual.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>What's This...</guimenuitem> +</menuchoice></term> +<listitem><para>Changes the mouse pointer to a question mark and lets you click +a &kplayer; interface element to get a quick description of its purpose and +functionality.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Report Bug...</guimenuitem> +</menuchoice></term> +<listitem><para>Opens a <link linkend="howto-bug-reporting">help topic</link> +that explains the recommended way to report a bug in +&kplayer;.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>About &kplayer;...</guimenuitem> +</menuchoice></term> +<listitem><para>Displays some brief information about &kplayer;'s version +number, authors and license agreement.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>About &kde;...</guimenuitem> +</menuchoice></term> +<listitem><para>Shows some information about the version of &kde; that +you are running.</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +</sect1> + +<sect1 id="toolbars"> +<title>Toolbars</title> + +<sect2 id="toolbar-main"> +<title><guilabel>Main</guilabel> toolbar</title> + +<para>The main toolbar contains the most useful &kplayer; commands and +options.</para> + +<itemizedlist> + +<listitem><para><guimenuitem>Play</guimenuitem> and <guimenuitem>Play +URL</guimenuitem> buttons invoke the corresponding actions from the <link +linkend="menu-file"><guimenu>File</guimenu> menu</link> that display dialog +boxes allowing you to play local files or remote +<acronym>URL</acronym>s.</para></listitem> + +<listitem><para><guimenuitem>Properties</guimenuitem> button corresponds to the +command on the <link linkend="menu-file"><guimenu>File</guimenu> menu</link> +that will open the <link linkend="properties">File Properties</link> dialog for +the current file.</para></listitem> + +<listitem><para><guimenuitem>Play</guimenuitem>, +<guimenuitem>Pause</guimenuitem> and <guimenuitem>Stop</guimenuitem> buttons +correspond to the commands on the +<link linkend="menu-player"><guimenu>Player</guimenu> menu</link> and will +respectively start, pause and stop playback of the current +file.</para></listitem> + +<listitem><para><guimenuitem>Zoom In</guimenuitem> and +<guimenuitem>Zoom Out</guimenuitem> buttons invoke the commands on the +<link linkend="menu-view"><guimenu>View</guimenu> menu</link> that respectively +enlarge and reduce the <link linkend="parts-video-area">video area</link> by one +half of the original video size of the current file.</para></listitem> + +<listitem><para><guimenuitem>Maintain Aspect</guimenuitem> button corresponds +to the command on the <link linkend="popup-main">general popup menu</link> that +will toggle the option to maintain the video aspect ratio.</para></listitem> + +<listitem><para><guimenuitem>Full Screen</guimenuitem> button invokes the +command on the <link linkend="menu-view"><guimenu>View</guimenu> menu</link> +that switches to the <link linkend="howto-full-screen">full screen mode</link> +and back the to normal mode.</para></listitem> + +<listitem><para><guimenuitem>Volume</guimenuitem>, +<guimenuitem>Contrast</guimenuitem>, <guimenuitem>Brightness</guimenuitem>, +<guimenuitem>Hue</guimenuitem> and <guimenuitem>Saturation</guimenuitem> +buttons display popup sliders allowing you to adjust those settings. If you +want the slider to stay visible instead of disappearing when it loses the input +focus, use the <link linkend="parts-toolbar-slider">slider toolbars</link> +instead. As usual, if you hold the &Shift; key down, the changes you make to the +settings will be applied only to the current file and stored in its +<link linkend="howto-properties">properties</link>.</para></listitem> + +</itemizedlist> + +</sect2> + +<sect2 id="toolbar-playlist"> +<title><guilabel>Playlist</guilabel> toolbar</title> + +<para>The <link linkend="parts-toolbar-playlist">playlist toolbar</link> +contains the current playlist and the most frequently used playlist commands and +options.</para> + +<itemizedlist> + +<listitem><para><guimenuitem>Next</guimenuitem> and +<guimenuitem>Previous</guimenuitem> buttons correspond to the commands +on the <link linkend="menu-player"><guimenu>Player</guimenu> +menu</link> and will select the next or previous item on the playlist +and start playing it.</para></listitem> + +<listitem><para>The playlist combo box in the closed state displays the +current playlist item. You can drop down the combo box to see the entire +list and select a different item to load and play.</para></listitem> + +<listitem><para><guimenuitem>Loop</guimenuitem> button is the same as the +corresponding command on the +<link linkend="menu-player"><guimenu>Player</guimenu> menu</link> that toggles +the option to continue playing from the top of the current playlist after +playing the last item.</para></listitem> + +<listitem><para><guimenuitem>Shuffle</guimenuitem> button is also the same +as the corresponding command on the +<link linkend="menu-player"><guimenu>Player</guimenu> menu</link> that toggles +the option to play items in random order.</para></listitem> + +</itemizedlist> + +</sect2> + +<sect2 id="toolbar-progress"> +<title><guilabel>Progress</guilabel> and seeking toolbar</title> + +<para>The progress and seeking toolbar is available when &kplayer; knows +the time length of the current file. It shows the current playback progress +and lets you seek, which is to say, move the playback position forward or +backward.</para> + +<itemizedlist> + +<listitem><para>The progress slider reflects the current playback position +relative to the total time length of the current file, and also lets you +seek or change the current position. To seek forward and backward by the +distance between the tick marks on the slider, <mousebutton>left</mousebutton> +click to the right or left of the slider thumb. To seek to a specific point, +<mousebutton>middle</mousebutton> click that point, or +<mousebutton>left</mousebutton> click and drag the slider thumb to that +point. If your mouse has a wheel, you can roll it up (away from you) to seek +forward or down (towards you) to seek backward when the mouse pointer is over +the slider. If you hold down the &Ctrl; key on the keyboard when rolling the +wheel, seeking will be faster.</para></listitem> + +<listitem><para><guimenuitem>Fast Forward</guimenuitem> and <guimenuitem>Fast +Backward</guimenuitem> buttons corresponds to the commands on the +<link linkend="menu-player"><guimenu>Player</guimenu> menu</link> +that seek forward or backward by the amount which by default is the same +as the distance between slider marks. However, internally they use different +seeking technique (relative as opposed to absolute), and so sometimes may +give different results than <mousebutton>left</mousebutton> clicking the +slider.</para></listitem> + +</itemizedlist> + +</sect2> + +<sect2 id="toolbar-volume"> +<title><guilabel>Volume</guilabel> toolbar</title> + +<para>The volume toolbar allows you to control the sound volume.</para> + +<itemizedlist> + +<listitem><para>The volume slider allows you to change the sound volume. If you +hold the &Shift; key down, the setting will be applied only to the current file +and stored in its <link linkend="howto-properties">properties</link>. If you +want the slider to always disappear after you have changed the volume, hide this +toolbar and use the popup slider on the <link linkend="toolbar-main">main +toolbar</link> instead.</para></listitem> + +<listitem><para><guimenuitem>Show Volume Toolbar</guimenuitem> button +corresponds to the command on the +<link linkend="menu-settings"><guimenu>Settings</guimenu> menu</link> +and will hide the toolbar when clicked.</para></listitem> + +<listitem><para><guimenuitem>Mute</guimenuitem> button turns the sound +off and back on, without changing the normal sound volume. It is the same +as the command on the +<link linkend="submenu-audio"><guisubmenu>Audio</guisubmenu> submenu</link> +of the <guimenu>Player</guimenu> menu.</para></listitem> + +</itemizedlist> + +</sect2> + +<sect2 id="toolbar-contrast"> +<title><guilabel>Contrast</guilabel> toolbar</title> + +<para>The contrast toolbar allows you to control the video contrast.</para> + +<itemizedlist> + +<listitem><para>The contrast slider allows you to change the video contrast. If +you hold the &Shift; key down, the setting will be applied only to the current +file and stored in its <link linkend="howto-properties">properties</link>. If +you want the slider to always disappear after you have changed the contrast, +hide this toolbar and use the popup slider on the +<link linkend="toolbar-main">main toolbar</link> instead.</para></listitem> + +<listitem><para><guimenuitem>Show Contrast Toolbar</guimenuitem> button +corresponds to the command on the +<link linkend="menu-settings"><guimenu>Settings</guimenu> menu</link> +and will hide the toolbar when clicked.</para></listitem> + +</itemizedlist> + +</sect2> + +<sect2 id="toolbar-brightness"> +<title><guilabel>Brightness</guilabel> toolbar</title> + +<para>The brightness toolbar allows you to control the video brightness.</para> + +<itemizedlist> + +<listitem><para>The brightness slider allows you to change the video brightness. +If you hold the &Shift; key down, the setting will be applied only to the +current file and stored in its +<link linkend="howto-properties">properties</link>. If you want the slider to +always disappear after you have changed the brightness, hide this toolbar and +use the popup slider on the <link linkend="toolbar-main">main toolbar</link> +instead.</para></listitem> + +<listitem><para><guimenuitem>Show Brightness Toolbar</guimenuitem> button +corresponds to the command on the +<link linkend="menu-settings"><guimenu>Settings</guimenu> menu</link> +and will hide the toolbar when clicked.</para></listitem> + +</itemizedlist> + +</sect2> + +<sect2 id="toolbar-hue"> +<title><guilabel>Hue</guilabel> toolbar</title> + +<para>The hue toolbar allows you to control the video hue.</para> + +<itemizedlist> + +<listitem><para>The hue slider allows you to change the video hue. If you hold +the &Shift; key down, the setting will be applied only to the current file and +stored in its <link linkend="howto-properties">properties</link>. If you want +the slider to always disappear after you have changed the hue, hide this toolbar +and use the popup slider on the <link linkend="toolbar-main">main toolbar</link> +instead.</para></listitem> + +<listitem><para><guimenuitem>Show Hue Toolbar</guimenuitem> button +corresponds to the command on the +<link linkend="menu-settings"><guimenu>Settings</guimenu> menu</link> +and will hide the toolbar when clicked.</para></listitem> + +</itemizedlist> + +</sect2> + +<sect2 id="toolbar-saturation"> +<title><guilabel>Saturation</guilabel> toolbar</title> + +<para>The saturation toolbar allows you to control the video saturation.</para> + +<itemizedlist> + +<listitem><para>The saturation slider allows you to change the video saturation. +If you hold the &Shift; key down, the setting will be applied only to the +current file and stored in its +<link linkend="howto-properties">properties</link>. If you want the slider to +always disappear after you have changed the saturation, hide this toolbar and +use the popup slider on the <link linkend="toolbar-main">main toolbar</link> +instead.</para></listitem> + +<listitem><para><guimenuitem>Show Saturation Toolbar</guimenuitem> button +corresponds to the command on the +<link linkend="menu-settings"><guimenu>Settings</guimenu> menu</link> +and will hide the toolbar when clicked.</para></listitem> + +</itemizedlist> + +</sect2> + +</sect1> + +<sect1 id="popup-menus"> +<title>Popup menus</title> + +<para>Like any half decent &kde; program, &kplayer; sports popup menus that +you can get by <mousebutton>right</mousebutton> clicking different +<link linkend="parts">parts</link> of it.</para> + +<sect2 id="popup-main"> +<title>General popup menu</title> + +<para>When you <mousebutton>right</mousebutton> click the +<link linkend="parts-video-area">video area</link>, the +<link linkend="parts-menu-bar">menu bar</link> or the +<link linkend="parts-status-bar">status bar</link>, you get the general popup +menu that includes the most frequently used &kplayer; commands and +options.</para> + +<itemizedlist> + +<listitem><para><guimenuitem>Play</guimenuitem> and <guimenuitem>Play +URL</guimenuitem> commands invoke the corresponding actions from the <link +linkend="menu-file"><guimenu>File</guimenu> menu</link> that display dialog +boxes allowing you to play local files or remote +<acronym>URL</acronym>s.</para></listitem> + +<listitem><para><guisubmenu>Play List</guisubmenu> and <guisubmenu>Play +Recent</guisubmenu> show the submenus from the <link +linkend="menu-file"><guimenu>File</guimenu> menu</link> that allow you to +play a playlist or a recent item respectively.</para></listitem> + +<listitem><para><guimenuitem>Properties</guimenuitem> command corresponds to the +command on the <link linkend="menu-file"><guimenu>File</guimenu> menu</link> +that will open the <link linkend="properties">File Properties</link> dialog for +the current file.</para></listitem> + +<listitem><para><guimenuitem>Play</guimenuitem>, +<guimenuitem>Pause</guimenuitem> and <guimenuitem>Stop</guimenuitem> commands +correspond to the actions on the +<link linkend="menu-player"><guimenu>Player</guimenu> menu</link> and will +respectively start, pause and stop playback of the current +file.</para></listitem> + +<listitem><para><guimenuitem>Maintain Aspect</guimenuitem> command toggles the +option to maintain the video aspect ratio.</para></listitem> + +<listitem><para><guimenuitem>Full Screen</guimenuitem> command invokes the +action on the <link linkend="menu-view"><guimenu>View</guimenu> menu</link> +that switches to the <link linkend="howto-full-screen">full screen mode</link> +and back to the normal mode.</para></listitem> + +<listitem><para>The commands on the <guisubmenu>Settings</guisubmenu> submenu +are the same as the commands on the +<link linkend="menu-settings"><guimenu>Settings</guimenu> menu</link> and will +show or hide the <link linkend="parts-menu-bar">menu bar</link>, +<link linkend="parts-status-bar">status bar</link>, +<link linkend="toolbar-playlist">playlist toolbar</link>, +<link linkend="parts-library">multimedia library</link>, +<link linkend="parts-message-log">message log</link>, +<link linkend="toolbar-main">main toolbar</link>, +<link linkend="toolbar-progress">progress and seeking toolbar</link> +and <link linkend="toolbar-volume">volume toolbar</link>.</para></listitem> + +<listitem><para><guimenuitem>Quit</guimenuitem> command invokes the action on +the <link linkend="menu-file"><guimenu>File</guimenu> menu</link> that stops +playback, saves all settings and closes &kplayer;.</para></listitem> + +</itemizedlist> + +</sect2> + +<sect2 id="popup-playlist"> +<title>Playlist popup menu</title> + +<para>When you <mousebutton>right</mousebutton> click the playlist drop down box +on the <link linkend="toolbar-playlist">playlist toolbar</link>, &kplayer; +displays a menu that lists commands that work on the current playlist.</para> + +<itemizedlist> + +<listitem><para><guimenuitem>Play...</guimenuitem> and <guimenuitem>Play +URL...</guimenuitem> commands invoke the corresponding actions from the <link +linkend="menu-file"><guimenu>File</guimenu> menu</link> that display dialog +boxes allowing you to play local files or remote +<acronym>URL</acronym>s.</para></listitem> + +<listitem><para><guisubmenu>Play List</guisubmenu> and <guisubmenu>Play +Recent</guisubmenu> show the submenus from the <link +linkend="menu-file"><guimenu>File</guimenu> menu</link> that allow you to +play a playlist or a recent item respectively.</para></listitem> + +<listitem><para><guisubmenu>Device</guisubmenu> submenus are also the same as +the ones on the <link linkend="menu-file"><guimenu>File</guimenu> menu</link>. +Please refer to the <link linkend="submenu-device">description above</link> for +details.</para></listitem> + +<listitem><para><guimenuitem>Next</guimenuitem> and +<guimenuitem>Previous</guimenuitem> commands invoke the corresponding actions +from the <link linkend="menu-player"><guimenu>Player</guimenu> +menu</link> and will select the next or previous item on the playlist +and start playing it.</para></listitem> + +<listitem><para><guimenuitem>Loop</guimenuitem> and +<guimenuitem>Shuffle</guimenuitem> commands are also the same as the ones on the +<link linkend="menu-player"><guimenu>Player</guimenu> menu</link> that toggle +the options to continue playing from the top of the current playlist after +playing the last item and to play items in random order +respectively.</para></listitem> + +<listitem><para><guimenuitem>Edit</guimenuitem> command opens the current +playlist in the <link linkend="parts-library">multimedia library</link>, +allowing you to edit it.</para></listitem> + +</itemizedlist> + +<sect3 id="submenu-playlist-add"> +<title><guisubmenu>Add</guisubmenu> submenu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Files...</guimenuitem> +</menuchoice></term> +<listitem><para>Displays the standard <guilabel>Add files</guilabel> dialog +and lets you choose a file or several files to add to the current +playlist.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>URL...</guimenuitem> +</menuchoice></term> +<listitem><para>Displays the standard <guilabel>Add URL</guilabel> dialog +and lets you type or paste in a <acronym>URL</acronym> to add to the current +playlist.</para></listitem> +</varlistentry> + +</variablelist> + +</sect3> + +<sect3 id="submenu-add-playlist-to"> +<title><guisubmenu>Add to</guisubmenu> submenu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Playlist</guimenuitem> +</menuchoice></term> +<listitem><para>Adds the contents of the current playlist to the playlist you +choose from the list. Each playlist in the <guilabel>Playlists</guilabel> +section of the library has its own command on this submenu.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Playlists...</guimenuitem> +</menuchoice></term> +<listitem><para>Shows a dialog allowing you to enter a name for a new playlist +and saves the current playlist in the <guilabel>Playlists</guilabel> section of +the <interface>multimedia library</interface> under that name.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Collection...</guimenuitem> +</menuchoice></term> +<listitem><para>Shows a dialog allowing you to enter a name for a new folder +and saves the current playlist in the <guilabel>Collection</guilabel> section of +the <interface>multimedia library</interface> under that name.</para></listitem> +</varlistentry> + +</variablelist> + +</sect3> + +</sect2> + +<sect2 id="popup-library"> +<title>Library popup menu</title> + +<para>When you <mousebutton>right</mousebutton> click an item in the +<link linkend="parts-library"><interface>multimedia library</interface></link>, +&kplayer; displays a menu that lists commands applicable to that item or to the +currently selected items or to the current folder. The menu is the same as the +<link linkend="menu-library"><guimenu>Library</guimenu> menu</link> on the menu +bar.</para> + +</sect2> + +<sect2 id="popup-message-log"> +<title>Message log popup menu</title> + +<para>When you <mousebutton>right</mousebutton> click the +<link linkend="parts-message-log">message log</link>, &kplayer; displays a menu +that lists commands applicable to the message log.</para> + +<itemizedlist> + +<listitem><para><guimenuitem>Select All</guimenuitem> command selects all the +text in the message log.</para></listitem> + +<listitem><para><guimenuitem>Copy</guimenuitem> command copies the selected +message log text to the clipboard.</para></listitem> + +<listitem><para><guimenuitem>Clear</guimenuitem> command removes all messages +from the message log.</para></listitem> + +</itemizedlist> + +</sect2> + +<sect2 id="popup-toolbar"> +<title>Toolbar popup menu</title> + +<para>When you <mousebutton>right</mousebutton> click a &kplayer; toolbar, you +get a standard &kde; toolbar popup menu. It contains options that allow you to +change the toolbar orientation, text position and icon size, as well as a +command that opens the <link linkend="configuration-toolbars-dialog">Toolbar +configuration dialog</link>.</para> + +</sect2> + +<sect2 id="popup-title-bar"> +<title>Title bar popup menu</title> + +<para>When you <mousebutton>right</mousebutton> click the &kplayer; title bar, +you get a standard &kde; title bar popup menu. You can also get it by +<mousebutton>left</mousebutton> clicking the little button in the top left +corner of &kplayer; window or by pressing +<keycombo action="simul">&Alt;<keycap>F3</keycap></keycombo>. The menu contains +commands that let you maximize, minimize, restore, move and resize the &kplayer; +window, as well as a few options, some of which you may find useful. For +example, the <guimenuitem>Keep Above Others</guimenuitem> option on the +<guisubmenu>Advanced</guisubmenu> submenu lets you keep the &kplayer; window on +top of all other program windows.</para> + +</sect2> + +</sect1> + +<sect1 id="kpart"> +<title>KPart</title> + +<para>&kplayer; features a KPart, which is an applet that can be embedded into +other programs and used to watch video or play audio. You can configure programs +like &konqueror; File Manager and &kmldonkey; to embed the &kplayer;'s KPart and +play files with it. &konqueror; Web Browser can also be configured to use the +&kplayer; KPart to display multimedia objects embedded in web pages.</para> + +<para>You can tell &konqueror; to use &kplayer; for playing multimedia files and +<acronym>URL</acronym>s by going to the <guilabel>File Associations</guilabel> +page either in the &konqueror; configuration dialog or in &kcontrolcenter; and +moving &kplayer; to the top of the list of programs for each media type you want +&kplayer; to play, both on the <guilabel>Program</guilabel> tab and on the +<guilabel>Embedded</guilabel> tab. It is recommended that you choose the option +to <guilabel>Open Separate Program</guilabel>, which will give you a whole lot +more options and better interface when playing multimedia compared to an +embedded KPart. However, when an object is embedded into a web page, &konqueror; +has no choice but to use the KPart. In that situation the best thing is to +<mousebutton>right</mousebutton> click the multimedia object and select the +<guilabel>Start &kplayer;</guilabel> command described +<link linkend="kpart-popup">below</link>.</para> + +<para>Following is a complete list of user interface elements that &kplayer;'s +KPart provides whenever possible. However, when the KPart is embedded into a web +page, only the <mousebutton>right</mousebutton> click +<link linkend="kpart-popup">popup menu</link> will be available.</para> + +<sect2 id="kpart-menu"> +<title><guilabel>Player</guilabel> menu</title> + +<para>This menu contains the following commands, most of which are the same as +the corresponding commands in the full &kplayer;:</para> + +<itemizedlist> + +<listitem><para><guilabel>Play</guilabel>, <guilabel>Pause</guilabel>, +<guilabel>Stop</guilabel>, <guilabel>Forward</guilabel>, <guilabel>Fast +Forward</guilabel>, <guilabel>Backward</guilabel>, <guilabel>Fast +Backward</guilabel> and <guilabel>Back to Start</guilabel> commands from the +<link linkend="menu-player"><guimenu>Player</guimenu> menu</link> of the full +&kplayer;;</para></listitem> + +<listitem><para><guilabel>Decrease Volume</guilabel>, <guilabel>Increase +Volume</guilabel> and <guilabel>Mute</guilabel> commands from the +<link linkend="submenu-audio"><guisubmenu>Audio</guisubmenu> +submenu</link> of the <guimenu>Player</guimenu> menu of the full +&kplayer;;</para></listitem> + +<listitem><para><guilabel>Maintain Aspect</guilabel> command from the +<link linkend="popup-main">general popup menu</link> of the full +&kplayer;;</para></listitem> + +<listitem><para><guilabel>Properties</guilabel> command from the +<link linkend="menu-file"><guimenu>File</guimenu> menu</link> of the full +&kplayer;;</para></listitem> + +<listitem><para><guilabel>Start &kplayer;</guilabel> command from the +<link linkend="kpart-popup">KPart popup menu</link> described +below.</para></listitem> + +</itemizedlist> + +</sect2> + +<sect2 id="kpart-toolbar"> +<title>Main toolbar</title> + +<para>This toolbar contains <guilabel>Play</guilabel>, +<guilabel>Pause</guilabel>, <guilabel>Stop</guilabel>, <guilabel>Maintain +Aspect</guilabel>, <guilabel>Volume</guilabel> and +<guilabel>Properties</guilabel> buttons which as the same as the ones on the +<link linkend="toolbar-main">main toolbar</link> in the full &kplayer;.</para> + +</sect2> + +<sect2 id="kpart-toolbar-progress"> +<title>Progress toolbar</title> + +<para>This toolbar is the same as the <link linkend="toolbar-progress">Progress +toolbar</link> in the full &kplayer;.</para> + +</sect2> + +<sect2 id="kpart-toolbar-volume"> +<title>Volume toolbar</title> + +<para>This toolbar is the same as the <link linkend="toolbar-volume">Volume +toolbar</link> in the full &kplayer;.</para> + +</sect2> + +<sect2 id="kpart-popup"> +<title>Popup menu</title> + +<para><mousebutton>Right</mousebutton> clicking the video area of &kplayer; +KPart embedded into another program gives you a popup menu.</para> + +<para>The top item on the menu is <guilabel>Start &kplayer;</guilabel> command +that will stop playback, open the full &kplayer;, put the multimedia file or +<acronym>URL</acronym> on the +<link linkend="parts-toolbar-playlist">playlist</link> and start playing it. +It is always recommended that you choose this command, since it will give you +better interface and more options when playing the multimedia.</para> + +<para>The popup menu also contains <guilabel>Play</guilabel>, +<guilabel>Pause</guilabel>, <guilabel>Stop</guilabel>, <guilabel>Maintain +Aspect</guilabel> and <guilabel>Properties</guilabel> commands which as the same +as the ones on the <link linkend="popup-main">general popup menu</link> in the +full &kplayer;.</para> + +</sect2> + +</sect1> + +<sect1 id="mouse-wheel"> +<title>Mouse wheel</title> + +<para>The action of the mouse wheel in &kplayer; depends on where the mouse +cursor is positioned.</para> + +<para>If the cursor is positioned over a slider, rolling the mouse wheel +will change the setting that the slider controls, like +<link linkend="toolbar-progress">playback position</link>, +<link linkend="toolbar-volume">sound volume</link>, +<link linkend="toolbar-contrast">video contrast</link> and so on. Rolling the +wheel up (away from you) increases the setting, while rolling it down (towards +you) decreases it. You can hold down the &Ctrl; key on the keyboard when rolling +the wheel to change the setting faster.</para> + +<para>Rolling the wheel when the mouse pointer is positioned over a window that +has a scroll bar, like the <link linkend="parts-library">multimedia +library</link> or the <link linkend="parts-message-log">message log</link>, will +scroll the window up or down. Rolling the wheel over the +<link linkend="toolbar-playlist">playlist combo box</link> will likewise scroll +it up or down, switch to a different entry and start playing it.</para> + +<para>When the mouse pointer is in the video area, rolling the wheel up (away +from you) will zoom in, that is, enlarge the video area, and rolling the wheel +down (towards you) will zoom out, or reduce the video area. However, if +&kplayer; cannot resize the video area, for example when the window is full +screen or maximized, it will instead seek, or move the playback point, forward +when rolling the wheel up (away from you) or backward when rolling it down +(towards you). In that case you can also hold down the &Ctrl; key on the keyboard +to seek faster.</para> + +</sect1> + +</chapter> diff --git a/doc/en/configuration.docbook b/doc/en/configuration.docbook new file mode 100644 index 0000000..bed6af5 --- /dev/null +++ b/doc/en/configuration.docbook @@ -0,0 +1,563 @@ +<chapter id="configuration"> +<title>Configuring &kplayer;</title> + +<para>Like other &kde; programs, &kplayer; is highly configurable. When you +<link linkend="howto-installation">install &kplayer;</link> and its multimedia +playing backend <link linkend="howto-installation-mplayer">&mplayer;</link>, +the default settings should enable your system to play multimedia content +without any additional configuration. This chapter describes ways to make +&kplayer;'s user interface best fit your tastes and configure media playback +for optimal quality and performance.</para> + +<sect1 id="configuration-ui"> +<title>User interface</title> + +<para>When &kplayer; is first installed, its window contains a +<link linkend="parts-menu-bar">menu bar</link>, a +<link linkend="parts-toolbar-main">main toolbar</link>, a +<link linkend="parts-toolbar-playlist">playlist toolbar</link> and a +<link linkend="parts-status-bar">status bar</link>. Additionally, a +<link linkend="parts-toolbar-slider">progress toolbar</link> will usually appear +when you start playing a file.</para> + +<para>On the <link linkend="menu-settings"><guimenu>Settings</guimenu> +menu</link> you will find options to hide toolbars that you do not need and to +show <link linkend="parts-toolbar-slider">other available toolbars</link>. Some +of them will only be available for video files, while the progress toolbar is +available when &kplayer; can detect the time length of the current file.</para> + +<para>The menu bar itself can be toggled on and off with the shortcut key +combination <keycombo action="simul">&Ctrl;<keycap>M</keycap></keycombo>. +You can also hide the status bar if you do not need the information it +displays.</para> + +<para>To show or hide the +<link linkend="parts-library">multimedia library</link>, press +<keycombo action="simul">&Ctrl;<keycap>L</keycap></keycombo> or choose +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Show +Library</guimenuitem></menuchoice>. To show or hide the +<link linkend="parts-message-log">message log</link> detailing internal +operation of &mplayer; backend as well as &kde; <acronym>I/O</acronym> Slaves, +press <keycombo action="simul">&Ctrl;<keycap>G</keycap></keycombo> or choose +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Show +Message Log</guimenuitem></menuchoice>.</para> + +<para>Each toolbar has a small area on one of its sides where you can press and +hold the &LMB; to drag the toolbar into a new position. You can place most +toolbars either horizontally at the top or bottom of &kplayer; window or +vertically at the left or right side of it, while the playlist toolbar can only +be positioned horizontally.</para> + +<para>Similarly, you can move around the multimedia library and the message log +by pressing and holding the &LMB; on the title area of the window and dragging +it above or below the <link linkend="parts-video-area">video area</link> and +positioning it in relation to the toolbars.</para> + +<para>If you <mousebutton>right</mousebutton> click a toolbar, you will get a +<link linkend="popup-toolbar">menu</link> to configure it. You can choose the +toolbar orientation, text position and icon size.</para> + +<para>&kplayer; will of course remember all the settings you choose and the +positions where you put your toolbars. It will remember visibility settings +for <link linkend="howto-full-screen">full screen mode</link> and for normal +mode separately.</para> + +</sect1> + +<sect1 id="configuration-playlist"> +<title>Playlist</title> + +<para>&kplayer;'s <link linkend="toolbar-playlist">playlist toolbar</link> has +a drop down box that shows the current playlist. It stores files and streams +that have been played or are going to be played and lets you easily switch to a +different item and play it. For details on the playlist feature see the +<link linkend="howto-playlist">Playlist micro-HOWTO</link>. +Following is a description of options that affect the playlist behavior.</para> + +<itemizedlist> + +<listitem><para><guimenuitem>Loop</guimenuitem> option is available from the +<link linkend="menu-player"><guimenu>Player</guimenu> menu</link>, the +<link linkend="toolbar-playlist">playlist toolbar</link> and the +<link linkend="popup-playlist">playlist popup menu</link>. When enabled, it +makes &kplayer; start playing items from the beginning of the list after it +finishes playing the last item on the list.</para></listitem> + +<listitem><para><guimenuitem>Shuffle</guimenuitem> option is also available from +the <link linkend="menu-player"><guimenu>Player</guimenu> menu</link>, the +<link linkend="toolbar-playlist">playlist toolbar</link> and the +<link linkend="popup-playlist">playlist popup menu</link>. When enabled, it +makes &kplayer; play items in a random order. When the +<guimenuitem>Loop</guimenuitem> option is also enabled, items will be reshuffled +every time &kplayer; restarts playback from the top of the list. To reshuffle +immediately, disable the <guimenuitem>Shuffle</guimenuitem> option and then +enable it again.</para></listitem> + +<listitem><para><guilabel>Allow duplicate entries on playlists</guilabel> option +is available on the +<link linkend="settings-general"><guilabel>General</guilabel> page</link> of the +&kplayer; Configuration dialog. When enabled, it allows &kplayer; to put +identical entries on the playlist. By default it is disabled, and if you queue +the same file twice, the old entry will be removed before adding the new one at +the bottom of the playlist.</para></listitem> + +</itemizedlist> + +<para>The <guimenuitem>Edit</guimenuitem> command opens the current playlist in +the <link linkend="parts-library">multimedia library</link> where you can add +new items and remove or change the order of existing ones. It is available from +the <link linkend="popup-playlist">playlist popup menu</link> that you can open +by <mousebutton>right</mousebutton> clicking the playlist drop down box on the +<link linkend="parts-toolbar-playlist">playlist toolbar</link>.</para> + +<para>To save the current playlist in the <guilabel>Playlists</guilabel> section +of the <interface>multimedia library</interface>, +<mousebutton>right</mousebutton> click the playlist drop down box on the +<link linkend="parts-toolbar-playlist">playlist toolbar</link>, select +<menuchoice><guisubmenu>Add +to</guisubmenu><guimenuitem>Playlists...</guimenuitem></menuchoice> and enter a +playlist name. The new playlist will then be added to each menu that works on +playlists. See the <link linkend="configuration-playlists">multimedia library +configuration</link> for details.</para> + +</sect1> + +<sect1 id="configuration-library"> +<title>Multimedia library</title> + +<para>&kplayer;'s <link linkend="parts-library"><interface>multimedia +library</interface></link> is the place to access all your multimedia and +arrange it into playlists. The things you create in the library affect other +parts of &kplayer;, in particular some menus and the current playlist. For +details on the multimedia library feature see the +<link linkend="howto-library">Multimedia library micro-HOWTO</link>.</para> + +<sect2 id="configuration-now-playing"> +<title>Now Playing</title> + +<para>This section shows the contents of the current playlist and lets you +modify it, for example by adding new files, streams and directories, removing +existing items or changing their order. The changes are reflected on the current +playlist shown on the <link linkend="parts-toolbar-playlist">playlist +toolbar</link>. The commands to modify the playlist contents are available from +the <link linkend="menu-library"><guimenu>Library</guimenu> menu</link> or the +<link linkend="popup-library">library <mousebutton>right</mousebutton> click +menu</link>.</para> + +</sect2> + +<sect2 id="configuration-recent"> +<title>Recent</title> + +<para>This section shows the recently played files and streams and lets you +modify the list. The top few entries are shown on the <guisubmenu>Play +Recent</guisubmenu> submenu of the +<link linkend="menu-file"><guimenu>File</guimenu> menu</link> and +<mousebutton>right</mousebutton> click <link linkend="popup-menus">popup +menus</link>.</para> + +<para>The <guilabel>Maximum Recent entries in the library</guilabel> option on +the <link linkend="settings-general"><guilabel>General</guilabel> page</link> of +the &kplayer; Configuration dialog gives the maximum number of files, folders +and streams the <guilabel>Recent</guilabel> section can hold. When a new entry +is added and the total number of entries exceeds this number, the bottom entry +is removed from the list.</para> + +<para>The <guilabel>Maximum entries on Play Recent menu</guilabel> option on the +<link linkend="settings-general">same page</link> of the global settings gives +the maximum number of commands the <guisubmenu>Play Recent</guisubmenu> submenus +can have. When a new entry is added and the total number of entries exceeds this +number, the last entry is removed from the menus.</para> + +</sect2> + +<sect2 id="configuration-playlists"> +<title>Playlists</title> + +<para>This section stores the playlists you create and lets you add new +playlists and change or remove the existing ones. You can also add new playlists +by selecting files, folders or streams elsewhere in the multimedia library, +<mousebutton>right</mousebutton> clicking the selection and choosing +<menuchoice><guisubmenu>Add to</guisubmenu><guimenuitem>New +Playlist...</guimenuitem></menuchoice> from the popup menu. +<mousebutton>Right</mousebutton> clicking a folder and choosing +<menuchoice><guisubmenu>Add +to</guisubmenu><guimenuitem>Playlists</guimenuitem></menuchoice> will also add +the folder to the list of playlists.</para> + +<para><guisubmenu>Play List</guisubmenu> submenu on the +<link linkend="menu-file"><guimenu>File</guimenu> menu</link> and +<guisubmenu>Add to</guisubmenu> submenu on the +<link linkend="menu-library"><guimenu>Library</guimenu> menu</link> as well as +their equivalents on <link linkend="popup-menus">popup menus</link> each have a +list of commands to either play a playlist or add new content to it. Each +playlist in this section has its own command on each of those menus. When you +add, remove or rename a playlist, the menus are updated to reflect the +changes.</para> + +<para>The <guilabel>Maximum entries on playlist menus</guilabel> option on the +<link linkend="settings-general"><guilabel>General</guilabel> page</link> of the +&kplayer; Configuration dialog gives the maximum number of playlists that will +be included on the submenus that work on playlists.</para> + +</sect2> + +<sect2 id="configuration-devices"> +<title>Devices</title> + +<para>This section lists the disk and tuner devices available on your system +as well as the <acronym>CD</acronym> tracks and <acronym>DVD</acronym> titles +found on the disks you insert into the disk devices and the channels available +on the tuner devices. &kplayer; puts any devices it finds on this list, and you +can add new devices or remove existing ones.</para> + +<para>The <link linkend="menu-file"><guimenu>File</guimenu> menu</link> and some +of the <mousebutton>right</mousebutton> click <link linkend="popup-menus">popup +menus</link> have submenus that let you easily access and play multimedia +available on these devices. Each device from this section has its own +<link linkend="submenu-device">submenu</link>. When you add, remove or rename a +device, the menus are updated to reflect the changes.</para> + +<para>When &kplayer; finds titles on a <acronym>DVD</acronym> disk or tracks on +a <acronym>CD</acronym> disk, it updates the corresponding menu to include +commands to play the individual titles or tracks. &kplayer; looks for titles and +tracks when you insert a disk into a drive or when you select <guimenuitem>Play +Disk</guimenuitem> or <guimenuitem>Load Disk</guimenuitem> command for a disk +device that does not yet have any titles or tracks listed.</para> + +<para>Similarly, when you change the channel list for a tuner device, &kplayer; +updates the corresponding menu to include commands to play each of the available +channels. The option to change the channel list is on the +<link linkend="properties-general"><guilabel>General</guilabel> page</link> of +the device properties dialog that you can open by selecting the device in the +multimedia library and choosing the <guimenuitem>Properties...</guimenuitem> +command from the +<link linkend="menu-library"><guimenu>Library</guimenu> menu</link> or the +<mousebutton>right</mousebutton> click <link linkend="popup-library">popup +menu</link>.</para> + +<para>To add a new device, select the <guilabel>Devices</guilabel> node and +choose <menuchoice><guisubmenu>Add</guisubmenu> +<guimenuitem>Device...</guimenuitem></menuchoice> command from the +<link linkend="menu-library"><guimenu>Library</guimenu> menu</link> or the +<mousebutton>right</mousebutton> click <link linkend="popup-library">popup +menu</link>. This will bring up a dialog box as shown below.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="device-add.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Add device dialog</phrase> +</textobject> +</mediaobject> + +<para>Enter a unique descriptive name for the device into the +<guilabel>Name</guilabel> field and the path to the device node under the +<filename>/dev</filename> directory into the <guilabel>Path</guilabel> field. +Select the device type from the <guilabel>Type</guilabel> drop down box. +For a tuner device you will need to choose a channel list, and for TV device +also an input driver. Click the <guibutton>OK</guibutton> button to add the +device to the <interface>multimedia library</interface> and to the +<guimenu>File</guimenu> menu and various <link linkend="popup-menus">popup +menus</link>.</para> + +<para>There are many more device specific options that you can see and change +in the <link linkend="properties">device properties dialog</link>. To open it, +select the device in the <interface>multimedia library</interface> and choose +the <guimenuitem>Properties...</guimenuitem> command from the +<link linkend="menu-library"><guimenu>Library</guimenu> menu</link> or the +<mousebutton>right</mousebutton> click <link linkend="popup-library">popup +menu</link>. For more information on disk and tuner device support in &kplayer; +see the <link linkend="howto-devices">Devices micro-HOWTO</link>.</para> + +</sect2> + +<sect2 id="configuration-list-view"> +<title>List view</title> + +<para>There are several ways you can customize the <interface>list +view</interface> where the library shows the multimedia found in the folder you +select from the <interface>tree view</interface>.</para> + +<para>The <guisubmenu>Columns</guisubmenu> submenu of the +<link linkend="menu-library"><guimenu>Library</guimenu> menu</link> and the +<link linkend="popup-library">library popup menu</link> allows you to choose +what columns to show in the <interface>list view</interface>. Each available +column has a command on this submenu that either shows or hides that column. +What columns are available depends on the folder selected in the tree view and +on its contents.</para> + +<para>To change the order of columns in the <interface>list view</interface>, +click and drag a column header with the &LMB;. However, the +<guilabel>Name</guilabel> always has to be the first column. To change the width +of a column, click and drag the divider on the right side of the column +header.</para> + +<para>To change the sorting order of items in the <interface>list +view</interface>, <mousebutton>left</mousebutton> click the header of the column +you want to sort by. To sort in the reverse order, click the same header again. +The new sorting order will apply to all folders in the multimedia library, +except for <link linkend="howto-library-playlist-folders">playlist +folders</link> with a <link linkend="howto-library-ordering-sorting">custom +order</link> of items.</para> + +</sect2> + +</sect1> + +<sect1 id="configuration-shortcuts"> +<title>Shortcuts</title> + +<para>To change the shortcut key arrangements used by &kplayer; select +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +Shortcuts...</guimenuitem></menuchoice>. This will open a dialog box +as shown below.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="shortcuts-configure.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Shortcut configuration dialog</phrase> +</textobject> +</mediaobject> + +<para>If you change the key bindings, make sure not to duplicate an existing +shortcut and also not to use the &Shift; key for your new shortcuts, because +the &Shift; key has a <link linkend="howto-properties">special function</link> +in &kplayer;.</para> + +<para>Search through the list to find the action for which you want to add or +change the shortcut keys and select it by <mousebutton>left</mousebutton> +clicking the name. You will then be able to change the shortcut by selecting +the <guilabel>None</guilabel>, <guilabel>Default</guilabel> or +<guilabel>Custom</guilabel> radio button or by clicking the large button in the +<guilabel>Shortcut for Selected Action</guilabel> area. The <guilabel>Define +Shortcut</guilabel> dialog box will then open.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="shortcuts-define.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Define Shortcut dialog</phrase> +</textobject> +</mediaobject> + +<para>Choose whether you want to change the <guilabel>Primary</guilabel> or +<guilabel>Alternate</guilabel> shortcut, then press the key or key combination +you want to act as the shortcut. If the <guilabel>Auto-Close</guilabel> box is +checked, the dialog will vanish as soon as you enter the key combination, else +it will remain until you press <guibutton>OK</guibutton> or +<guibutton>Cancel</guibutton>. Clicking the little black icon with a white +cross in it clears the shortcut.</para> + +<sect2 id="configuration-userdefmenus"> +<title>User defined menus</title> + +<para>You can add your own pop up menu to &kplayer;, so that pressing one key +combination will make the menu appear, then pressing a second key, or using the +<keysym>Up arrow</keysym> and <keysym>Down arrow</keysym> keys and pressing +<keycap>Enter</keycap>, will select an item from it.</para> + +<para>To do this add a <guilabel>Custom</guilabel> shortcut for each of the +actions you want to appear in the menu and in the <guilabel>Define +Shortcut</guilabel> dialog check the <guilabel>Multi-Key</guilabel> box, press +the key combination that you want to bring up your new menu, then, separately, +press the key that will choose that item from the menu.</para> + +</sect2> + +</sect1> + +<sect1 id="configuration-toolbars"> +<title>Toolbars</title> + +<sect2 id="configuration-toolbars-style"> +<title>Toolbar style and position</title> + +<para>The <link linkend="popup-toolbar">toolbar popup menu</link> has several +options to change the toolbar appearance. To display this menu, +<mousebutton>right</mousebutton> click the toolbar for which you want to change +the options.</para> + +<para>The <guisubmenu>Orientation</guisubmenu> submenu contains options to place +the toolbar at the <guimenuitem>Top</guimenuitem>, +<guimenuitem>Bottom</guimenuitem>, <guimenuitem>Left</guimenuitem> or +<guimenuitem>Right</guimenuitem> side of the &kplayer; window. You can also +click and drag the toolbar by the handle on its left border with the &LMB; to +move it to a new position. The <guimenuitem>Floating</guimenuitem> option +displays the toolbar on top of other parts of &kplayer; window. The +<guimenuitem>Flat</guimenuitem> option makes the toolbar show as small lines +that you need to <mousebutton>left</mousebutton> click to expand the +toolbar.</para> + +<para>The <guisubmenu>Text Position</guisubmenu> submenu allows you to display +a description of each icon on the toolbar either underneath or alongside the +icon, or display only the description instead of the icon. By default only the +icon is displayed without the description.</para> + +<para>The <guisubmenu>Icon Size</guisubmenu> submenu allows you to choose the +size of the icons on the toolbar. The choices are +<guimenuitem>Default</guimenuitem>, <guimenuitem>Small</guimenuitem>, +<guimenuitem>Medium</guimenuitem>, <guimenuitem>Large</guimenuitem> and +<guimenuitem>Huge</guimenuitem>.</para> + +</sect2> + +<sect2 id="configuration-toolbars-dialog"> +<title>Toolbar configuration dialog</title> + +<para>To configure &kplayer;'s toolbars, select +<guimenuitem>Configure Toolbars...</guimenuitem> from the +<link linkend="menu-settings"><guimenu>Settings</guimenu> menu</link> or from +the <link linkend="popup-toolbar">toolbar popup menu</link>. This will open a +dialog box as shown below.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="toolbars-configure.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Toolbar configuration dialog</phrase> +</textobject> +</mediaobject> + +<para>The drop down list box at the top of this dialog shows the name of the +selected toolbar and lets you switch to another toolbar. The <guilabel>Current +actions</guilabel> list box shows the actions included on the currently selected +toolbar, and the <guilabel>Available actions</guilabel> list box shows all the +other actions that exist in &kplayer;.</para> + +<para>The buttons in the middle part of the dialog let you include or exclude +actions from the selected toolbar and change the order of buttons and other +elements on the toolbar. The right arrow button puts the action selected in the +<guilabel>Available actions</guilabel> box on the toolbar, and the left arrow +button takes the action selected in the <guilabel>Current actions</guilabel> +box off the toolbar. The up and down arrow buttons move the action selected in +the <guilabel>Current actions</guilabel> box back and forward within the toolbar +respectively.</para> + +<para>To be included on a toolbar, an action needs an icon that will be shown on +the toolbar if the action is shown as a button. Some actions already have icons, +but for others you need to choose one. The <guilabel>Change Icon...</guilabel> +button opens a dialog box that allows you to choose an icon for the selected +action.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="toolbars-change-icon.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Change icon dialog</phrase> +</textobject> +</mediaobject> + +<para>When the <guilabel>System icons</guilabel> option is selected, the drop +down box on the right lets you select a category of system icons to choose an +icon from. By default the <guilabel>Actions</guilabel> category is selected +that shows the action icons in your system icon theme. If you have icons other +than the system icon theme that you want to choose from, select the +<guilabel>Other icons</guilabel> option and click the +<guibutton>Browse</guibutton> button to open the standard dialog to find the +directory where your icons are stored. The <guilabel>Search</guilabel> box lets +you filter the icons by name.</para> + +</sect2> + +</sect1> + +<sect1 id="configuration-dialog"> +<title>Other settings</title> + +<para>&kde; is known as the most flexible and configurable desktop environment, +and &kplayer; is no exception. In addition to the configuration options +described in previous sections, there are many more options, most of which +are accessible through the <link linkend="settings">&kplayer; configuration +dialog</link>. Select <menuchoice><guimenu>Settings</guimenu><guimenuitem> +Configure &kplayer;...</guimenuitem></menuchoice> to open it.</para> + +<para>The dialog is divided into several sections. Some of them affect &kplayer; +behavior, including <link linkend="settings-general">general</link> options. The +<link linkend="settings-controls">Controls section</link> tells &kplayer; which +changes it should remember globally and which ones it should store in individual +<link linkend="howto-properties">file properties</link>, and its subsections +allow you to fine tune individual &kplayer; controls, including +<link linkend="settings-progress">progress</link>, +<link linkend="settings-volume">volume</link>, +<link linkend="settings-contrast">contrast</link>, +<link linkend="settings-brightness">brightness</link>, +<link linkend="settings-hue">hue</link>, +<link linkend="settings-saturation">saturation</link>, and +<link linkend="settings-sliders">slider controls</link> in general. Other +sections affect options that &kplayer; uses for interaction with +<link linkend="howto-installation-mplayer">&mplayer;</link> and control various +aspect of multimedia playback, including +<link linkend="settings-video">video</link>, +<link linkend="settings-audio">audio</link>, +<link linkend="settings-subtitles">subtitles</link> and +<link linkend="settings-advanced">advanced</link> options.</para> + +<para>The <link linkend="settings">Configuration dialog chapter</link> gives +complete details on each section and all the available options. Also the +<link linkend="howto-settings">Advanced configuration micro-HOWTO</link> +describes some of the more advanced options in more detail.</para> + +<para>Some additional options that apply to the main &kplayer; window are +available from the <link linkend="popup-title-bar">title bar popup menu</link> +that you can get by <mousebutton>right</mousebutton> clicking the +<link linkend="parts-title-bar">title bar</link> or +<mousebutton>left</mousebutton> clicking the little button in the top left +corner of &kplayer; window or by pressing +<keycombo action="simul">&Alt;<keycap>F3</keycap></keycombo>.</para> + +</sect1> + +<sect1 id="configuration-properties"> +<title>File properties</title> + +<para>&kplayer; has a unique feature that lets you choose many different options +on per-file basis. These options are called File Properties and are stored along +with the <acronym>URL</acronym> of each individual file or network +location.</para> + +<para>There are two ways to set a file property. The easiest one is by holding +down the &Shift; key when changing a setting like video size or aspect, sound +volume, video contrast or brightness, etc. &kplayer; will apply the change to +the currently loaded file and remember it in the corresponding file property. +When it loads another file, it will revert the setting back to where it was +before the change (unless the other file also has the same property set). When +you load and play that first file again, &kplayer; will again apply the change +you made to the setting and keep it until you load another file or +<acronym>URL</acronym>.</para> + +<para>The other way to set a file property is through the +<link linkend="properties">File Properties dialog</link>. The properties in the +dialog are arranged according to their function. General properties like +<guilabel>Name</guilabel>, <guilabel>Length</guilabel> and others are in the +<link linkend="properties-general">General</link> section. Properties that +control the video size are in the <link linkend="properties-size">Size</link> +section. Other sections contain properties that affect &kplayer; interaction +with <link linkend="howto-installation-mplayer">&mplayer;</link> and control +multimedia playback, including <link linkend="properties-video">video</link>, +<link linkend="properties-audio">audio</link>, +<link linkend="properties-subtitles">subtitles</link> and +<link linkend="properties-advanced">advanced</link> properties.</para> + +<para>Select <menuchoice><guimenu>File</guimenu> +<guimenuitem>Properties...</guimenuitem></menuchoice> to open the properties +of the current file or <acronym>URL</acronym>. You can also +<mousebutton>right</mousebutton> click an item in the +<link linkend="parts-library"><interface>multimedia library</interface></link> +and select the <guimenuitem>Properties...</guimenuitem> command to open the +properties dialog for that item.</para> + +<para>The <link linkend="properties">File properties dialog chapter</link> gives +complete details on each section and all the available properties. Also the +<link linkend="howto-properties">File properties micro-HOWTO</link> +describes this feature in more detail and gives some examples.</para> + +</sect1> + +</chapter> diff --git a/doc/en/device-add.png b/doc/en/device-add.png Binary files differnew file mode 100644 index 0000000..afb30e1 --- /dev/null +++ b/doc/en/device-add.png diff --git a/doc/en/device-properties-advanced.png b/doc/en/device-properties-advanced.png Binary files differnew file mode 100644 index 0000000..5b48cf0 --- /dev/null +++ b/doc/en/device-properties-advanced.png diff --git a/doc/en/device-properties-audio.png b/doc/en/device-properties-audio.png Binary files differnew file mode 100644 index 0000000..f22f28b --- /dev/null +++ b/doc/en/device-properties-audio.png diff --git a/doc/en/device-properties-general.png b/doc/en/device-properties-general.png Binary files differnew file mode 100644 index 0000000..447eac2 --- /dev/null +++ b/doc/en/device-properties-general.png diff --git a/doc/en/device-properties-subtitles.png b/doc/en/device-properties-subtitles.png Binary files differnew file mode 100644 index 0000000..a86feea --- /dev/null +++ b/doc/en/device-properties-subtitles.png diff --git a/doc/en/device-properties-video.png b/doc/en/device-properties-video.png Binary files differnew file mode 100644 index 0000000..f4e6432 --- /dev/null +++ b/doc/en/device-properties-video.png diff --git a/doc/en/dvd-bear.png b/doc/en/dvd-bear.png Binary files differnew file mode 100644 index 0000000..e0a8be2 --- /dev/null +++ b/doc/en/dvd-bear.png diff --git a/doc/en/howto-bug-reporting.docbook b/doc/en/howto-bug-reporting.docbook new file mode 100644 index 0000000..f45a1a1 --- /dev/null +++ b/doc/en/howto-bug-reporting.docbook @@ -0,0 +1,92 @@ +<sect1 id="howto-bug-reporting"> +<title>Reporting bugs</title> + +<sect2 id="howto-bug-reporting-duplicates"> +<title>Checking for duplicate bugs</title> + +<para>Before you report a bug, please first make sure the bug has not been +reported yet. Look through the list of <ulink +url="http://cvs.sourceforge.net/viewcvs.py/kplayer/kplayer/BUGS?rev=HEAD">known +issues</ulink>, then in the <ulink +url="http://sourceforge.net/tracker/?atid=532182&group_id=71710">bug +tracking system</ulink>. Also look in <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 the <ulink +url="http://sourceforge.net/forum/forum.php?forum_id=244388">user +forum</ulink>.</para> + +</sect2> + +<sect2 id="howto-bug-reporting-submitting"> +<title>Submitting a bug</title> + +<para>Please report bugs through the <ulink +url="http://sourceforge.net/tracker/?group_id=71710&atid=532182">&kplayer; +bug tracking system</ulink>. Using SourceForge is much preferable over private +e-mail, for it helps prevent duplicate requests.</para> + +<para>When you <ulink +url="http://sourceforge.net/account/login.php?return_to=%2Ftracker%3Ffunc%3Dadd%26group_id%3D71710%26atid%3D532182">submit +a bug</ulink>, please include all of the following information.</para> + +<itemizedlist> + +<listitem><para>The versions of all relevant programs you are using: + +<itemizedlist> + +<listitem><para>&kplayer;,</para></listitem> + +<listitem><para>&mplayer;,</para></listitem> + +<listitem><para>&kde;,</para></listitem> + +<listitem><para>Qt,</para></listitem> + +<listitem><para>XFree,</para></listitem> + +<listitem><para>the window manager, normally &kwin;.</para></listitem> + +</itemizedlist> + +</para></listitem> + +<listitem><para>&kplayer; debug log.</para> + +<para>Make sure your console history size is unlimited, for example in &konsole; +go to <menuchoice><guimenu>Preferences</guimenu> +<guimenuitem>History</guimenuitem></menuchoice> and set the +<guilabel>Unlimited</guilabel> option.</para> + +<para>Run &kplayer; from the console. If the bug is in &kplayer;'s KPart, run +the program that uses the KPart instead.</para> + +<para>Reproduce the bug.</para> + +<para>Then post on SourceForge whatever shows up on the console, clearly marking +the point where the problem occurs.</para> + +<para>If the problem happened only once and you cannot reproduce it, you can +look in the <filename>~/.xsession-errors</filename> file to see if it recorded +the &kplayer; output when the problem occurred.</para> + +<para>If you are not getting any console output from &kplayer;, you may need +to recompile &kplayer; with debug information. Follow the instructions in the +<link linkend="howto-compilation">Compilation micro-HOWTO</link> and give an +additional <option>--enable-debug=yes</option> option to the +<command>configure</command> script.</para> + +<para>The &kplayer; debug output includes &mplayer; messages. To make &mplayer; +more verbose put a <option>-v</option> option in the <guilabel>Additional +command line arguments</guilabel> field on the +<link linkend="settings-advanced">Advanced page</link> in <guilabel>&kplayer; +Settings</guilabel>. You can repeat the option up to three times, separated +by spaces, to get even more &mplayer; output.</para></listitem> + +</itemizedlist> + +</sect2> + +</sect1> diff --git a/doc/en/howto-compilation.docbook b/doc/en/howto-compilation.docbook new file mode 100644 index 0000000..23bfd77 --- /dev/null +++ b/doc/en/howto-compilation.docbook @@ -0,0 +1,143 @@ +<sect1 id="howto-compilation"> +<title>Compiling from source</title> + +<para>First, download and install development packages for &kde;, Qt, and X11. +Those should be available in your distribution, for example in Debian the +package names are <literal>kdelibs4-dev</literal>, +<literal>libqt3-mt-dev</literal> and <literal>xlibs-dev</literal>. You may need +other development packages as well.</para> + +<sect2 id="howto-compilation-sources"> +<title>Getting sources</title> + +<sect3 id="howto-compilation-release"> +<title>Official release</title> + +<para>Download the latest <literal>.tar.bz2</literal> from the +<ulink url="http://sourceforge.net/project/showfiles.php?group_id=71710">Files +section</ulink> of &kplayer; project at SourceForge. Then extract it</para> + +<para><userinput><command>tar</command> <option>xjf</option> +<filename>kplayer-0.6.2.tar.bz2</filename></userinput></para> + +<para>The code will be in the <filename>kplayer-0.6.2</filename> +subdirectory</para> + +<para><userinput><command>cd</command> +<filename>kplayer-0.6.2</filename></userinput></para> + +</sect3> + +<sect3 id="howto-compilation-cvs"> +<title>Current CVS</title> + +<para>Login to SourceForge CVS</para> + +<para><userinput><command>cvs</command> +<option>-d:pserver:anonymous@kplayer.cvs.sourceforge.net:/cvsroot/kplayer</option> +login</userinput></para> + +<para>and hit &Enter; if it asks for a password. Then download the code</para> + +<para><userinput><command>cvs</command> <option>-z3</option> +<option>-d:pserver:anonymous@kplayer.cvs.sourceforge.net:/cvsroot/kplayer</option> +co <option>-P</option> kplayer</userinput></para> + +<para>The code will be in the <filename>kplayer</filename> subdirectory</para> + +<para><userinput><command>cd</command> +<filename>kplayer</filename></userinput></para> + +</sect3> + +</sect2> + +<sect2 id="howto-compilation-compilation"> +<title>Compile, install, run</title> + +<para>Create the <filename>configure</filename> script</para> + +<para><userinput><command>make</command> <option>-f</option> +<filename>Makefile.dist</filename></userinput></para> + +<para>and run it</para> + +<para><userinput><command>./configure</command> <option>--prefix</option> +`kde-config --prefix`</userinput></para> + +<para>If at this point you are getting errors about missing libraries, you will +probably need to install more development packages from your distribution. The +<filename>configure</filename> script is very verbose, you will be able to tell +which package you need from its output. If you need even more information, look +in the <filename>config.log</filename> file. You will need to go to the bottom +and then scroll a page or two up to get to the point where it reported the +error. If everything fails, ask for help on the +<ulink url="http://sourceforge.net/forum/forum.php?forum_id=244388">&kplayer; +user forum</ulink>. Do not forget to include the full output of +<filename>configure</filename> and the <filename>config.log</filename> +file.</para> + +<para>Once <command>configure</command> succeeds, compile the code</para> + +<para><userinput><command>make</command></userinput></para> + +<para>If this step fails, you can again ask for help on the +<ulink url="http://sourceforge.net/forum/forum.php?forum_id=244388">&kplayer; +user forum</ulink> providing the full output of <command>make</command>.</para> + +<para>Once <command>make</command> finishes, install the program</para> + +<para><userinput><command>su</command> <option>-c</option> +'<command>make</command> install'</userinput></para> + +<para>and run it</para> + +<para><userinput><command>kplayer</command></userinput></para> + +<para>This last command will also produce quite verbose output on your console. +This is the output you need to send in if you ever +<link linkend="howto-bug-reporting">submit a bug report</link> or ask for +help.</para> + +</sect2> + +<sect2 id="howto-compilation-notes"> +<title>Notes</title> + +<sect3 id="howto-compilation-mandrake"> +<title>Mandrake 10</title> + +<para>At least some Mandrake 10 versions put <filename>libGL.la</filename> in +the wrong place, so if the <filename>configure</filename> script cannot find it, +you will have to create a symbolic link</para> + +<para><userinput><command>ln</command> <option>-s</option> +<filename>/usr/lib/libGL.la</filename> +<filename>/usr/X11R6/lib/libGL.la</filename></userinput></para> + +<para>Ales Tosovsky wrote a detailed HOWTO +<ulink url="http://linux.tosovsky.info/exec.php?show=kplayer">in Czech</ulink> +about compiling &kplayer; on Mandrake 10 and translated it into <ulink +url="http://linux.tosovsky.info/exec.php?show=kplayeren">English</ulink>.</para> + +</sect3> + +<sect3 id="howto-compilation-fedora"> +<title>Fedora Core 2 on x86_64</title> + +<para>Fred successfully compiled &kplayer; on x86_64 using Fedora Core 2 and +2.6.6-1.435.2.3smp kernel. Here is how he ran +<command>configure</command>:</para> + +<para><userinput><command>./configure</command> <option>--prefix=`kde-config +--prefix`</option> <option>--enable-libsuffix=64</option> +<option>--with-qt-includes=/usr/lib64/qt-3.3/include</option> +<option>--with-qt-libraries=/usr/lib64/qt-3.3/lib</option></userinput></para> + +<para>all on one line of course.</para> + +</sect3> + +</sect2> + +</sect1> diff --git a/doc/en/howto-configuration.docbook b/doc/en/howto-configuration.docbook new file mode 100644 index 0000000..7a1a2f9 --- /dev/null +++ b/doc/en/howto-configuration.docbook @@ -0,0 +1,162 @@ +<sect1 id="howto-configuration"> +<title>Basic configuration</title> + +<para>As a general rule, the initial &kplayer; settings are chosen for optimal +performance and playback, so no additional setup is needed. However, in some +cases changing the initial settings can improve &kplayer; performance.</para> + +<sect2 id="howto-configuration-video"> +<title>Video setup</title> + +<para>XVideo is the video output &kplayer; uses by default. For many systems +this is the optimal choice. Make sure your X Server has XVideo extension +enabled. Look in your <filename>/etc/X11/xorg.conf</filename> or +<filename>/etc/X11/XF86Config-4</filename> file for a line that reads</para> + +<para><userinput>Load "extmod"</userinput></para> + +<para>This is the line that loads the XVideo extension, so make sure it is not +disabled. Also check <filename>/var/log/Xorg.0.log</filename> or +<filename>/var/log/XFree86.0.log</filename> to make sure that XVideo is loaded +without error.</para> + +<para>If &kplayer; cannot use XVideo for any reason, it will fall back on using +X11 video output in the default configuration. X11 output is OK except it forces +the use of software scaler, which will consume significantly more processor +cycles, and it does not support changing contrast, brightness, hue and +saturation, so those controls will not be functional.</para> + +<para>Depending on your video card, you may find that a different +&mplayer; video output type(s) work better for you. For example you can try +VIDIX output if you have a Matrox or ATI card. For Matrox cards there is also +XMGA output.</para> + +<para>You can change the video output type on the +<link linkend="settings-video">Video page</link> in <guilabel>&kplayer; +Settings</guilabel>. However, some video outputs may not support embedding video +into &kplayer; and will open their own window instead. Those video outputs are +not recommended.</para> + +</sect2> + +<sect2 id="howto-configuration-audio"> +<title>Audio setup</title> + +<para>The optimal audio output to use with &kplayer; is <acronym>ALSA</acronym>, +which is the default setting when &kplayer; is first installed. +If <acronym>ALSA</acronym> is not available, <acronym>OSS</acronym> is the +second best choice.</para> + +<para>If the audio output is configured correctly, but &kplayer; cannot use it, +usually it is because another program has locked the audio device. The optimal +solution for this is to allow multiple programs access the audio device at the +same time.</para> + +<para>For example, to set up <acronym>ALSA</acronym> to allow more than one +program to use the same device, put something along these lines into your +<filename>~/.asourndrc</filename>:</para> + +<screen>pcm.!default +{ + type dmix + ipc_key 1234 + slave.pcm "hw:<replaceable>card-name</replaceable>" +}</screen> + +<para>where <replaceable>card-name</replaceable> is the name of the audio card +that you can find out by running <userinput><command>cat</command> +<filename>/proc/asound/cards</filename></userinput>. Before trying the new +configuration, be sure to stop any programs that are known to lock audio devices +and keep them locked, for example <userinput><command>killall</command> +artsd</userinput></para> + +<para>You can change the audio output type on the +<link linkend="settings-audio">Audio page</link> in <guilabel>&kplayer; +Settings</guilabel>.</para> + +<para>However, some audio outputs like <acronym>SDL</acronym> or sound server +outputs like <acronym>ARTS</acronym> or <acronym>ESD</acronym> are not +recommended since they may cause stability problems, degraded performance and +a broken volume control.</para> + +<para></para> + +</sect2> + +<sect2 id="howto-configuration-mplayer"> +<title>&mplayer; setup</title> + +<para>Depending on how you installed &mplayer; you may have gotten a global +<filename>mplayer.conf</filename> file in a directory like +<filename>/etc/mplayer</filename>. The local version of that file is +<filename>~/.mplayer/config</filename>. Make sure that those files do not have +a <option>gui=yes</option> option. Remove or comment it out if you find it. +If you ever want to use &mplayer;'s own <acronym>GUI</acronym> (not +recommended), you can get it by running <command>gmplayer</command>.</para> + +<para>Also make sure there are no other options that may interfere with +&kplayer; operation. If you see any, either comment them out or override them +in <guilabel>&kplayer; Settings</guilabel>.</para> + +</sect2> + +<sect2 id="howto-configuration-smooth"> +<title>Smooth playback</title> + +<para>A while ago Arpi wrote a +<ulink url="http://freshmeat.net/articles/view/747/">Fine-tuning +&mplayer;</ulink> article where you can find more useful tips on optimizing +&mplayer;.</para> + +<para>One thing you can do to get smoother playback is enable the hardware +<acronym>RTC</acronym> timer. Run</para> + +<para><userinput><command>echo</command> 1024 > +<filename>/proc/sys/dev/rtc/max-user-freq</filename></userinput></para> + +<para>as root, and also make sure <filename>/dev/rtc</filename> is user +readable.</para> + +<para>Arpi also recommends trying options like <option>-mc 0.001</option> and +<option>-autosync 30</option>. Put them into the <guilabel>Additional command +line arguments</guilabel> field on the +<link linkend="settings-advanced">Advanced page</link> in <guilabel>&kplayer; +Settings</guilabel> and see if they make a noticeable difference for you.</para> + +<para>The <option>-vop</option> &mplayer; option has since been replaced by the +<option>-vf</option> option, so that section of the article may be somewhat +obsolete or the tips may need some adjustment for the current &mplayer;.</para> + +</sect2> + +<sect2 id="howto-configuration-preview"> +<title>Previews in the Open File dialog</title> + +<para>There is some obsolete &kde; based software, like &kaboodle;, that tells +&kde; that it wants to be used for previewing media files, even those it does +not support, in the standard <guilabel>Open File</guilabel> dialog, which is +what &kplayer; uses. This makes browsing directories with media files painfully +slow, and unfortunately there is no option to turn off previewing selectively +for certain file types. Even if you turn off the <guilabel>Play +automatically</guilabel> option, the preview program will still be loaded. The +workaround is to either turn off previewing in &kplayer; entirely if you don't +need it, or remove the offending program from your system.</para> + +</sect2> + +<sect2 id="howto-configuration-donkey"> +<title>Previewing files in &kmldonkey;</title> + +<para>The recent official &mldonkey; <acronym>GUI</acronym>s have been badly +broken, leaving <ulink url="http://kmldonkey.org/">&kmldonkey;</ulink> as +the most usable, albeit crashy, &mldonkey; frontend. &kmldonkey; supports +embedding of &kplayer; for previewing files, but it is recommended that you +change your <application>mldonkey_preview</application> script to start the +full &kplayer; for previewing partial downloads, since that will give better +interface and more options. If &mplayer; cannot play a partial download, +probably nothing else will, so just wait for a larger chunk to get +downloaded.</para> + +</sect2> + +</sect1> diff --git a/doc/en/howto-devices.docbook b/doc/en/howto-devices.docbook new file mode 100644 index 0000000..67835d1 --- /dev/null +++ b/doc/en/howto-devices.docbook @@ -0,0 +1,182 @@ +<sect1 id="howto-devices"> +<title>Disk and tuner devices</title> + +<sect2 id="howto-devices-setup"> +<title>Setting up devices</title> + +<para>&kplayer; tries to find any disk and tuner devices you have on your +system. The ones it finds it puts on the +<link linkend="menu-file"><guimenu>File</guimenu> menu</link> and on several +<mousebutton>right</mousebutton> click <link linkend="popup-menus">popup +menus</link>, as well as in the <guilabel>Devices</guilabel> section of the +<link linkend="parts-library"><interface>multimedia +library</interface></link>.</para> + +<para>If the device you want &kplayer; to use does not show up on those lists, +you can add it manually by selecting the <guilabel>Devices</guilabel> node in +the <interface>multimedia library</interface> and choosing +<menuchoice><guisubmenu>Add</guisubmenu> +<guimenuitem>Device...</guimenuitem></menuchoice> command from the +<link linkend="menu-library"><guimenu>Library</guimenu> menu</link> or the +<mousebutton>right</mousebutton> click <link linkend="popup-library">popup +menu</link>. &kplayer; will show the <guilabel>Add device</guilabel> +dialog:</para> + +<mediaobject> +<imageobject> +<imagedata fileref="device-add.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Add device dialog</phrase> +</textobject> +</mediaobject> + +<para>Enter a unique descriptive name for the device and the path to the device +node under the <filename>/dev</filename> directory. Select the device type from +the drop down box. For a <acronym>TV</acronym> device select a channel list and +an input driver, usually <guilabel>Video4Linux 2</guilabel> or +<guilabel>Video4Linux</guilabel>. A <acronym>DVB</acronym> device needs the path +to a channel file in the <quote>zap</quote> format. You can get the file from +the Internet or create it using the <command>scan</command> utility that comes +with <acronym>DVB</acronym> drivers. &kplayer; looks for existing +<filename>channels.conf</filename> files and selects the first one it finds by +default.</para> + +<para>To set additional options for a device, select it in the +<interface>multimedia library</interface> and choose the +<guimenuitem>Properties...</guimenuitem> command from the +<link linkend="menu-library"><guimenu>Library</guimenu> menu</link> or the +<mousebutton>right</mousebutton> click <link linkend="popup-library">popup +menu</link>. Most of the options are the same +<link linkend="howto-properties">properties</link> available for every +multimedia item in &kplayer;.</para> + +<para>Tuner devices have several specific options detailed in the <link +linkend="properties"><guilabel>Properties</guilabel> dialog</link> chapter. The +<link linkend="properties-general"><guilabel>General</guilabel> page</link> +has the options to select a list of channels available from the device and an +input driver as discussed above. Other options are on the +<link linkend="properties-video"><guilabel>Video</guilabel></link>, +<link linkend="properties-audio"><guilabel>Audio</guilabel></link> and +<link linkend="properties-advanced"><guilabel>Advanced</guilabel></link> pages +of the dialog.</para> + +<para>For a detailed description of the multimedia library feature see the +<link linkend="howto-library">Multimedia library micro-HOWTO</link>.</para> + +<para>If you had <userinput><option>-dvd-device</option></userinput> or +<userinput><option>-cdrom-device</option></userinput> options in the +<guilabel>Additional command line parameters</guilabel> box on the +<guilabel>Advanced</guilabel> page in +<link linkend="settings-advanced">&kplayer; Settings</link>, you have to remove +them, because since version 0.6 &kplayer; supplies those options to &mplayer; +automatically.</para> + +</sect2> + +<sect2 id="howto-devices-playing"> +<title>Playing from devices</title> + +<para>When you put a disk into a <acronym>CD</acronym> or <acronym>DVD</acronym> +drive, &kplayer; detects what kind of disk it is and how many tracks or titles +it has, and updates the <link linkend="submenu-device">device submenu</link> of +the <guilabel>File</guilabel> menu accordingly. The submenu includes commands to +play the whole disk or an individual track or title from it.</para> + +<para>&kplayer; supports video <acronym>DVD</acronym>, video +<acronym>CD</acronym>, including <acronym>SVCD</acronym> and other +<acronym>VCD</acronym> varieties, audio <acronym>CD</acronym>, data +<acronym>DVD</acronym> and data <acronym>CD</acronym> disks. If &kplayer; does +not detect your disk automatically for any reason, you can kick off the +detection process manually by selecting the <guimenuitem>Load Disk</guimenuitem> +command from the <link linkend="submenu-device">device submenu</link>.</para> + +<para>Tuner devices like <acronym>TV</acronym> or <acronym>DVB</acronym> also +have their own submenus that contain commands to play each individual channel +available on the device. Or you can open the device in the <interface>multimedia +library</interface>, select some channels and play them using the commands on +the <link linkend="menu-library"><guimenu>Library</guimenu> menu</link> or the +<mousebutton>right</mousebutton> click <link linkend="popup-library">popup +menu</link>.</para> + +<para>Another way to play an entire disk is through the +<filename>media:/</filename> or <filename>system:/</filename> +<acronym>I/O</acronym> Slaves. If you have the <interface>Devices</interface> +applet enabled in the &kicker; panel, it will show disks you insert into disk +drives. You can then <mousebutton>left</mousebutton> click the disk icon and +select the <guimenuitem>Play</guimenuitem> command. This will start &kplayer; +if it is not already running and play the disk. Similarly, if disk icons show +up on your desktop, you can <mousebutton>right</mousebutton> click them and +select <guimenuitem>Play</guimenuitem>. You can also display the disk icons +in &konqueror; file manager by opening <filename>media:/</filename> or +<filename>system:/media</filename> <acronym>URL</acronym>s in it.</para> + +</sect2> + +<sect2 id="howto-devices-deinterlacing"> +<title>Inverse telecine and deinterlacing</title> + +<para>Video on <acronym>DVD</acronym> disks is often telecined. The +<literal>pullup</literal> filter does a decent inverse telecine. To use it, +select the disk or one of its titles in the <guilabel>Devices</guilabel> section +of the +<link linkend="parts-library"><interface>multimedia library</interface></link> +and choose the <guimenuitem>Properties...</guimenuitem> command from the +<link linkend="menu-library"><guimenu>Library</guimenu> menu</link> or the +<mousebutton>right</mousebutton> click <link linkend="popup-library">popup +menu</link> to open the disk properties, then go to the +<link linkend="properties-advanced">Advanced page</link> and enter <option>-vf +pullup</option> in the <guilabel>Additional command line arguments</guilabel> +field before playing the video. Setting the property on the disk will apply the +filter to all titles on the <acronym>DVD</acronym>.</para> + +<para>Some <acronym>DVD</acronym> disks and many <acronym>TV</acronym> and +<acronym>DVB</acronym> channels are interlaced. There are several deinterlacing +filters in &mplayer;. Each of them has its own advantages and disadvantages, so +try a few of them starting with <option>-vf yadif</option> and see which one +gives the best results for the particular video you are trying to watch. The +full list is available by running</para> + +<para><userinput><command>mplayer</command> <option>-vf help</option> +<option>-pphelp</option> | <command>grep</command> +<option>deint</option></userinput></para> + +</sect2> + +<sect2 id="howto-devices-deblocking"> +<title>Deblocking, deringing, denoising</title> + +<para>The <option>-vf</option> option is in charge of video filtering in +&mplayer;. To get the full list of available filters, run</para> + +<para><userinput><command>mplayer</command> +<option>-vf help</option></userinput></para> + +<para>from the command line. Most of them are described on the +<ulink url="man:/mplayer">&mplayer; manpage</ulink>. One of the most useful +filters is <literal>pp</literal>, the postprocessing filter. Among other things +it can smooth blocky <acronym>MPEG</acronym>s using the deblocking filters +<literal>hb</literal> and <literal>vb</literal> or <literal>h1</literal> and +<literal>v1</literal>, usually combined with the deringing filter +<literal>dr</literal> like this: <option>-vf pp=hb/vb/dr</option> or +<option>-vf pp=h1/v1/dr</option>. To get a full list of <literal>pp</literal> +filters, run</para> + +<para><userinput><command>mplayer</command> +<option>-pphelp</option></userinput></para> + +<para>from the command line. Another useful filter is <literal>hqdn3d</literal> +that does high quality denoising: <option>-vf hqdn3d</option>.</para> + +<para>You can combine several filters together and use them on the same device +or file by separating them with a comma without spaces, for example:</para> + +<para><option>-vf pullup,pp=h1/v1/dr,hqdn3d</option></para> + +<para>Put that into the <guilabel>Additional command line arguments</guilabel> +field on the <link linkend="properties-advanced">Advanced page</link> in +<guilabel>File Properties</guilabel>.</para> + +</sect2> + +</sect1> diff --git a/doc/en/howto-full-screen.docbook b/doc/en/howto-full-screen.docbook new file mode 100644 index 0000000..5eb8d96 --- /dev/null +++ b/doc/en/howto-full-screen.docbook @@ -0,0 +1,62 @@ +<sect1 id="howto-full-screen"> +<title>Full screen and maximized window</title> + +<sect2 id="howto-full-screen-mode"> +<title>Full screen mode</title> + +<para>In the full screen mode the &kplayer; window has no border and no +<link linkend="parts-title-bar">title bar</link>. By default it will also hide +all other windows so the <link linkend="parts-video-area">video area</link> will +cover your entire screen. If you have any &kde; panels, they will also be hidden +until you return to the normal mode.</para> + +<para>To watch a movie in full screen in &kplayer; select <guimenuitem>Full +Screen</guimenuitem> from the <guimenu>View</guimenu> menu or just hit <keycombo +action="simul">&Ctrl;<keycap>F</keycap></keycombo>. To go back to normal display +hit <keycombo action="simul">&Ctrl;<keycap>F</keycap></keycombo> again or +<mousebutton>right</mousebutton> click to open the +<link linkend="popup-main">popup menu</link> and unselect the <guimenuitem>Full +Screen</guimenuitem> option. Double clicking the video area also switches +between full screen and normal size. Pressing &Esc; will stop playback and also +return to normal display.</para> + +<para>The <guisubmenu>Settings</guisubmenu> submenu of the +<link linkend="popup-main"><mousebutton>right</mousebutton> click menu</link> +lets you show the <link linkend="parts-menu-bar">menu bar</link>, +<link linkend="parts-toolbar-main">toolbars</link>, +<link linkend="parts-library">multimedia library</link>, +<link linkend="parts-message-log">message log</link> and +<link linkend="parts-status-bar">status bar</link> in full screen mode. +&kplayer; will remember your choices and show the same user interface next time +you go to full screen mode.</para> + +</sect2> + +<sect2 id="howto-maximized-window"> +<title>Maximized window</title> + +<para>A maximized window covers the entire screen area not used by &kde; panels, +and has a title and borders, as well as all the same user interface as a normal +window. &kplayer; will not try to resize a maximized window automatically. To +maximize the &kplayer; window <mousebutton>left</mousebutton> click the +<guibutton>Maximize</guibutton> button on the right side of the +<link linkend="parts-title-bar">title bar</link> or right click the middle +portion of the title bar to get a <link linkend="popup-title-bar">popup +menu</link> and select the <guimenuitem>Maximize</guimenuitem> command from it. +To go back to normal window size, click the <guibutton>Restore</guibutton> +button or select the <guimenuitem>Maximize</guimenuitem> command again.</para> + +</sect2> + +<sect2 id="howto-full-screen-mouse-wheel"> +<title>Mouse wheel</title> + +<para>When the &kplayer; window is full screen or maximized, and the mouse +pointer is in the video area, rolling the mouse wheel will seek, or move the +playback point, forward when rolling the wheel up (away from you) or backward +when rolling it down (towards you). If you hold down the &Ctrl; key on the +keyboard, seeking will be faster.</para> + +</sect2> + +</sect1> diff --git a/doc/en/howto-installation.docbook b/doc/en/howto-installation.docbook new file mode 100644 index 0000000..5dad72d --- /dev/null +++ b/doc/en/howto-installation.docbook @@ -0,0 +1,105 @@ +<sect1 id="howto-installation"> +<title>Installation</title> + +<sect2 id="howto-installation-dependencies"> +<title>Dependencies</title> + +<sect3 id="howto-installation-mplayer"> +<title>MPlayer</title> + +<para>&kplayer; uses <ulink url="http://www.mplayerhq.hu/">&mplayer;</ulink> +as the multimedia backend for playing audio and video files and streams. +This ensures maximum variety of supported types of files and encodings.</para> + +<para>You need to have &mplayer; version 1.0-pre8 or later. If there are good +binary packages for your distribution, use those. For example on Debian you +would do</para> + +<para><userinput><command>echo</command> +'deb http://debian-multimedia.org unstable main' >> +<filename>/etc/apt/sources.list</filename></userinput></para> + +<para><userinput><command>apt-get</command> update</userinput></para> + +<para><userinput><command>apt-get</command> install mplayer</userinput></para> + +<para>Substitute <literal>unstable</literal> for <literal>stable</literal> or +<literal>testing</literal> as required. The same repository also has a &kplayer; +package, so you can install it as well:</para> + +<para><userinput><command>apt-get</command> install kplayer</userinput></para> + +<para>As always <ulink +url="http://www.mplayerhq.hu/DOCS/HTML/en/faq.html#faq-compilation">compiling +from source</ulink> is an option.</para> + +</sect3> + +<sect3 id="howto-installation-xvideo"> +<title>X11 and XVideo</title> + +<para>X11 is required. The X Server and libraries released by X.org are +recommended. XFree86 may also work.</para> + +<para>XVideo extension is recommended. You can check your +<filename>/etc/X11/xorg.conf</filename> or +<filename>/etc/X11/XF86Config-4</filename> file for a line that reads</para> + +<para><userinput>Load "extmod"</userinput></para> + +<para>This is the line that loads XVideo extension, so make sure it is not +disabled. Also check <filename>/var/log/Xorg.0.log</filename> or +<filename>/var/log/XFree86.0.log</filename> to make sure that XVideo is loaded +without error.</para> + +<para>See the <link linkend="howto-configuration">Configuration +micro-HOWTO</link> if you want to use a different video output.</para> + +</sect3> + +<sect3 id="howto-installation-kde"> +<title>Qt and KDE</title> + +<para>&kplayer; 0.6 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.</para> + +</sect3> + +</sect2> + +<sect2 id="howto-installation-installation"> +<title>Installation</title> + +<sect3 id="howto-installation-binary"> +<title>Binary install</title> + +<para>The recommended way to install &kplayer; is by using the binary package +built specifically for your distribution. The +<ulink url="http://kplayer.sourceforge.net/#downloads">Downloads section</ulink> +of the &kplayer; home page lists the available packages and repositories.</para> + +</sect3> + +<sect3 id="howto-installation-source"> +<title>Compiling from source</title> + +<para>If you cannot install a precompiled binary for any reason, you can compile +&kplayer; yourself. See the <link linkend="howto-compilation">Compilation +Micro-HOWTO</link> for instructions.</para> + +</sect3> + +<sect3 id="howto-installation-cvs"> +<title>Compiling from CVS</title> +<para>If you want to try the latest and greatest &kplayer; features at the risk +of getting some parts of it broken, you can compile the latest +<acronym>CVS</acronym> code. See the +<link linkend="howto-compilation">Compilation Micro-HOWTO</link> for +details.</para> + +</sect3> + +</sect2> + +</sect1> diff --git a/doc/en/howto-library.docbook b/doc/en/howto-library.docbook new file mode 100644 index 0000000..6274104 --- /dev/null +++ b/doc/en/howto-library.docbook @@ -0,0 +1,382 @@ +<sect1 id="howto-library"> +<title>Multimedia library</title> + +<sect2 id="howto-library-overview"> +<title>Overview</title> + +<para>The +<link linkend="parts-library"><interface>multimedia library</interface></link> +is the central place for accessing, storing and organizing all your multimedia +in &kplayer;. When you first install and run the program, the library is +initially not shown. Use one of the following ways to show it:</para> + +<itemizedlist> + +<listitem><para>Select <menuchoice><guimenu>Settings</guimenu><guimenuitem>Show +Library</guimenuitem></menuchoice> or press +<keycombo action="simul">&Ctrl;<keycap>L</keycap></keycombo>.</para></listitem> + +<listitem><para>Select any of the available choices from the +<menuchoice><guimenu>Library</guimenu><guisubmenu>Go</guisubmenu></menuchoice> +submenu.</para></listitem> + +<listitem><para><mousebutton>Right</mousebutton> click the playlist drop down +box on the <link linkend="toolbar-playlist">playlist toolbar</link> and select +the <guimenuitem>Edit</guimenuitem> command from the +<link linkend="popup-playlist">popup menu</link>.</para></listitem> + +</itemizedlist> + +<para>The library consists of several sections that have different purpose. +You can see and open the sections in the <interface>tree view</interface> +on the left side of the library window.</para> + +<itemizedlist> + +<listitem><para><link linkend="howto-library-now-playing"><guilabel>Now +Playing</guilabel></link> section contains the current playlist, including all +of its subfolders.</para></listitem> + +<listitem><para><link linkend="howto-library-recent"><guilabel>Recent</guilabel></link> +section contains the most recently played items and playlists.</para></listitem> + +<listitem><para><link linkend="howto-library-playlists"><guilabel>Playlists</guilabel></link> +section stores the playlists that you create and allows you to manage them.</para></listitem> + +<listitem><para><link linkend="howto-library-collection"><guilabel>Collection</guilabel></link> +section contains the multimedia collection and allows you to manage it.</para></listitem> + +<listitem><para><link linkend="howto-library-devices"><guilabel>Devices</guilabel></link> +section contains multimedia devices that are present on your system and the +multimedia available on them.</para></listitem> + +<listitem><para><link linkend="howto-library-directories"><guilabel>Root +Directory</guilabel></link> section allows you to access multimedia stored +anywhere on your file system.</para></listitem> + +<listitem><para><link linkend="howto-library-directories"><guilabel>Home +Directory</guilabel></link> section allows you to access multimedia stored in +your home directory and its subdirectories.</para></listitem> + +</itemizedlist> + +<para>Selecting a folder in the <interface>tree view</interface> opens its +contents in the <interface>list view</interface> on the right side of the +library window. The <interface>list view</interface> shows the name of each +multimedia item along with an icon depicting the kind of the item. Also, many of +the items can have additional information displayed in separate columns. Most of +that information is hidden by default, but you can choose the columns that you +want to show from the <guisubmenu>Columns</guisubmenu> submenu of the +<link linkend="menu-library"><guimenu>Library</guimenu> menu</link> and the +<link linkend="popup-library">library popup menu</link>.</para> + +<para>Depending on the items present in the currently displayed folder, the +available columns may include <guilabel>Length</guilabel>, +<guilabel>Frequency</guilabel>, <guilabel>Type</guilabel>, +<guilabel>Demuxer</guilabel>, <guilabel>Video size</guilabel>, +<guilabel>Video codec</guilabel>, <guilabel>Video bit rate</guilabel>, +<guilabel>Frame rate</guilabel>, <guilabel>Audio codec</guilabel>, +<guilabel>Audio bit rate</guilabel>, <guilabel>Sample rate</guilabel>, +<guilabel>Channels</guilabel>, <guilabel>Track</guilabel>, +<guilabel>Title</guilabel>, <guilabel>Album</guilabel>, +<guilabel>Artist</guilabel>, <guilabel>Year</guilabel>, +<guilabel>Genre</guilabel>, <guilabel>Path</guilabel>, +<guilabel>External subtitles</guilabel> and other information. +The <link linkend="configuration-list-view">configuration chapter</link> has +details on how you can customize the <interface>list view</interface>.</para> + +<para>You can edit some of the fields, like <guilabel>Name</guilabel>, +<guilabel>Track</guilabel>, <guilabel>Title</guilabel>, +<guilabel>Album</guilabel>, <guilabel>Artist</guilabel>, +<guilabel>Year</guilabel> and <guilabel>Genre</guilabel>, by choosing the name +of the field from the <guisubmenu>Edit</guisubmenu> submenu of the +<link linkend="menu-library"><guimenu>Library</guimenu> menu</link> or the +<link linkend="popup-library">library popup menu</link>. To edit the +<guilabel>Name</guilabel> field, choose the <guimenuitem>Rename</guimenuitem> +command instead or press the <keycap>F2</keycap> key. Type or paste in the new +value of the field, and then press &Enter; to apply the changes, or 	 or +<keycombo action="simul">&Shift;	</keycombo> to apply the changes and edit +the next or the previous field, or <keycap>Down Arrow</keycap> or <keycap>Up +Arrow</keycap> to apply the changes and edit the same field of the next or +previous item that can have that field.</para> + +</sect2> + +<sect2 id="howto-library-playlist-folders"> +<title>Playlist folders</title> + +<para>Folders in the <guilabel>Now Playing</guilabel>, +<guilabel>Recent</guilabel> and <guilabel>Playlists</guilabel> section are known +as playlist folders. When you open a playlist folder, the <interface>list +view</interface> lets you expand its subfolders inside the same view, so that +you have access to the entire contents of the selected folder. When you open a +folder in another section, the <interface>list view</interface> will show the +contents of that folder only, including the subfolders, and to access the +contents of a subfolder, you can execute or <quote>drill down</quote> to the +subfolder to open it.</para> + +<para>The <interface>multimedia library</interface> allows you to create an +unlimited number of subfolders in a playlist folder or in a folder in the +<guilabel>Collection</guilabel> section, and the subfolders can be nested to +an unlimited number of levels.</para> + +</sect2> + +<sect2 id="howto-library-ordering-sorting"> +<title>Ordering and sorting</title> + +<para>You can arrange the contents of playlist folders in any order, by dragging +items with the &LMB; and dropping them in a new place, or by using the +<guimenuitem>Move Up</guimenuitem> and <guimenuitem>Move Down</guimenuitem> +commands from the <link linkend="menu-library"><guimenu>Library</guimenu> +menu</link> or the <link linkend="popup-library">library popup +menu</link>.</para> + +<para>Folders in other sections do not have this ability, but they let you sort +their contents by any column, by <mousebutton>left</mousebutton> clicking the +column header. To sort items in the reverse order, click the column header +again. If you click the column header in a playlist folder, the folder and any +expanded subfolders are likewise sorted by that column, while collapsed folders +retain the custom order of items if they had it.</para> + +<para>The sorting column and direction (ascending or descending) is shared by +all folders in the library, except playlist folders where you put items in a +custom order as described above. So if you sort files in a directory by their +time length, and then go to a folder in the <guilabel>Collection</guilabel> +section for example, its contents will also be sorted by their time +length.</para> + +<para>Subfolders are always listed before other items in folders that are not +playlist folders, while in playlist folders subfolders are listed after other +items unless you change the order manually and arrange the contents differently. +As a result, when you play a playlist, the contents of a playlist folder will +be played before the contents of its subfolders, again unless you set a custom +order of items in that playlist folder.</para> + +</sect2> + +<sect2 id="howto-library-editing"> +<title>Managing multimedia</title> + +<para>If you have some multimedia files on your computer, you can put them into +the <guilabel>Collection</guilabel> and on the <guilabel>Playlists</guilabel>, +by dragging files or directories from the <guilabel>Home Directory</guilabel> or +<guilabel>Root Directory</guilabel> section or from &konqueror; File Manager and +dropping them into the folder of your choice. Or you can select the files and +directories in the <interface>multimedia library</interface> and use the +commands on the <guisubmenu>Add to</guisubmenu> submenus of the +<link linkend="menu-library"><guimenu>Library</guimenu> menu</link> and the +<link linkend="popup-library">library popup menu</link>.</para> + +<para>Another way of adding multimedia to the library is by using the +<menuchoice><guisubmenu>Add</guisubmenu> +<guimenuitem>Files...</guimenuitem></menuchoice> command, which uses the +standard &kde; file dialog, or the +<menuchoice><guisubmenu>Add</guisubmenu> +<guimenuitem>URL...</guimenuitem></menuchoice> command, which lets you paste in +the path to a local file or directory or the <acronym>URL</acronym> of a remote +file or stream. Both commands are on the +<link linkend="menu-library"><guimenu>Library</guimenu> menu</link> and the +<link linkend="popup-library">library popup menu</link>. You can also drag a +link from &konqueror; Web Browser and drop it into the library.</para> + +<para>There are four commands that put multimedia on the current playlist that +is shown in the <guilabel>Now Playing</guilabel> section of the library and in +the playlist drop down box on the <link +linkend="parts-toolbar-playlist">playlist toolbar</link>. Again, all of them are +on the <link linkend="menu-library"><guimenu>Library</guimenu> menu</link> and +the <link linkend="popup-library">library popup menu</link>.</para> + +<itemizedlist> + +<listitem><para><guimenuitem>Play</guimenuitem> command clears the current +playlist, puts the selected items on it and starts playing +them.</para></listitem> + +<listitem><para><guimenuitem>Play Next</guimenuitem> command clears the current +playlist, puts the selected items on it, and if &kplayer; is playing something, +plays the new items after the currently playing item finishes +playing.</para></listitem> + +<listitem><para><guimenuitem>Queue</guimenuitem> command adds the selected items +to the end of the current playlist.</para></listitem> + +<listitem><para><guimenuitem>Queue Next</guimenuitem> command adds the selected +items to the end of the current playlist, and makes them next items in the +playing queue. If &kplayer; is playing something, it will play the new items +after the currently playing item finishes playing, else it will play them when +you choose <menuchoice><guimenu>Player</guimenu><guimenuitem>Next</guimenuitem> +</menuchoice> or click the <guibutton>Next</guibutton> on the playlist +toolbar.</para></listitem> + +</itemizedlist> + +<para>The <guilabel>Play</guilabel>, <guilabel>Play next</guilabel>, +<guilabel>Queue</guilabel>, <guilabel>Queue next</guilabel>, +<guilabel>Add to collection</guilabel>, <guilabel>Add to playlists</guilabel> +and <guilabel>Add to new playlist</guilabel> commands are also available in +&konqueror; File Manager. Select the files and directories you want to add to +the <interface>multimedia library</interface>, <mousebutton>right</mousebutton> +click to open the popup menu and select an action from the menu or from the +<guilabel>Actions</guilabel> submenu.</para> + +<para>When you drag and drop items and folders within the same section, +&kplayer; will move them to the new location. If you want to copy them instead, +hold the &Ctrl; key while dragging and dropping. To move multimedia to another +section instead of copying it, hold the &Shift; key while dragging and dropping. +To remove items and folders from the library, select them and choose the +<guimenuitem>Remove</guimenuitem> command from the +<link linkend="menu-library"><guimenu>Library</guimenu> menu</link> or the +<link linkend="popup-library">library popup menu</link> or press the +<keycap>Delete</keycap> key. This will only work in collection and playlist +folders, since &kplayer; never deletes multimedia files or directories from your +file system.</para> + +</sect2> + +<sect2 id="howto-library-linked-folders"> +<title>Linked folders</title> + +<para>Adding a directory to a collection or playlist folder in the +<interface>multimedia library</interface> creates a subfolder that is linked to +that directory, so that when you put new multimedia into the directory or any of +its subdirectories, it will show up in the folder or the corresponding subfolder +automatically, or if you remove some files from the directory, &kplayer; will +remove them from the library as well. Similarly, when you put a collection +folder on a playlist, the new playlist folder is linked to the collection +folder, and when you play a playlist, the new folders in the <guilabel>Now +Playing</guilabel> and <guilabel>Recent</guilabel> sections are linked to the +playlist folder.</para> + +<para>For example, if you take a directory full of <acronym>MP3</acronym> files +and add it to the <guilabel>Collection</guilabel> section of the +<interface>multimedia library</interface>, then take the collection folder and +put it on a playlist, then play the playlist, and then go back and put some more +<acronym>MP3</acronym>s into the directory, &kplayer; will see them and +automatically add them to the collection, the playlist and the current playlist, +and play them along with the other <acronym>MP3</acronym>s.</para> + +<para>If you play a playlist and then change the order of items in a folder in +that playlist, the order of items on the current playlist will also change. The +new order will be reflected in the <guilabel>Now Playing</guilabel> section and +in the playlist drop down box on the playlist toolbar.</para> + +<para>To open the origin folder of a linked folder, select the linked folder in +the <interface>multimedia library</interface> and choose +<menuchoice><guisubmenu>Go</guisubmenu><guimenuitem>To +Origin</guimenuitem></menuchoice> from the +<link linkend="menu-library"><guimenu>Library</guimenu> menu</link> or the +<link linkend="popup-library">library popup menu</link>.</para> + +<para>When you add more items or remove existing items to a linked folder, it +will break the link, and the folder will no longer be updated when there are +changes in the origin folder. The folder icon will change to reflect that. When +you change the order of items in a folder in the +<guilabel>Now Playing</guilabel> section that is linked to another folder in +the <guilabel>Playlists</guilabel> section, the order of items in the two +folders will be different, but the current playlist will still get updated +items from the playlist folder.</para> + +<para>To copy the folder contents instead of creating a link, hold the &Ctrl; +key while dragging and dropping the folder into the new location. However, the +copy process may take a while if the folder contains a lot of multimedia, and of +course the new folder will not be updated when the original one changes, so +this is not recommended.</para> + +</sect2> + +<sect2 id="howto-library-now-playing"> +<title>Now Playing section</title> + +<para>This section contains the current playlist as a tree of folders and +multimedia items in them. Any changes you make here are going to be reflected +in the playlist drop down box on the <link linkend="toolbar-playlist">playlist +toolbar</link>, which displays the current playlist as a flat list of +multimedia items in the actual order they are going to be played or have been +played.</para> + +<para>See the <link linkend="howto-playlist">Playlist micro-HOWTO</link> for +details about the current playlist in &kplayer;.</para> + +</sect2> + +<sect2 id="howto-library-recent"> +<title>Recent section</title> + +<para>This section contains the recently played multimedia items and playlists. +If you select several items and tell &kplayer; to play or queue them, they are +added to this section as one folder. If you only play one item, &kplayer; will +add it as a single item to this list. The item or folder will also show up on +the <guisubmenu>Play Recent</guisubmenu> submenu of the +<link linkend="menu-file"><guimenu>File</guimenu> menu</link> and several +<mousebutton>right</mousebutton> click <link linkend="popup-menus">popup +menus</link>.</para> + +<para>The <link linkend="configuration-recent">configuration chapter</link> +describes settings that affect this section.</para> + +</sect2> + +<sect2 id="howto-library-playlists"> +<title>Playlists section</title> + +<para>This is where you create and manage your playlists. The playlists can of +course have any number of subfolders to any depth. The playlists will show up on +the <guisubmenu>Play List</guisubmenu> submenu of the +<link linkend="menu-file"><guimenu>File</guimenu> menu</link> and several +<link linkend="popup-menus">popup menus</link> and on the +<guisubmenu>Add to</guisubmenu> submenus of the +<link linkend="menu-library"><guimenu>Library</guimenu> menu</link> and the +<link linkend="popup-library">library popup menu</link>.</para> + +<para>See the <link linkend="howto-playlist">Playlist micro-HOWTO</link> for +more information.</para> + +</sect2> + +<sect2 id="howto-library-collection"> +<title>Collection section</title> + +<para>This section is the central place where you can store, access and manage +your entire multimedia collection, including local files and directories and +remote <acronym>URL</acronym>s.</para> + +</sect2> + +<sect2 id="howto-library-devices"> +<title>Devices section</title> + +<para>This section shows the disk and tuner devices found on your system and the +multimedia available on them. &kplayer; automatically finds and adds devices to +this section, and also automatically detects any disks you insert into your disk +drives, and displays titles or tracks available on them and channels available +on the tuner devices. The devices, channels, disks, titles and tracks are also +available as <link linkend="submenu-device">submenus</link> on the +<link linkend="menu-file"><guimenu>File</guimenu> menu</link> and several +<link linkend="popup-menus">popup menus</link> for easy access.</para> + +<para>See the <link linkend="howto-devices">Devices micro-HOWTO</link> for a +detailed description of this &kplayer; feature.</para> + +</sect2> + +<sect2 id="howto-library-directories"> +<title>Directory sections</title> + +<para>These sections let you access multimedia stored on your local file system. +They only show multimedia files, so if your videos or music don't show up here, +you need to make sure their media types are set up under either +<literal>audio</literal> or <literal>video</literal> in the <guilabel>File +Associations</guilabel> configuration in &kcontrolcenter; or &konqueror;.</para> + +<para>&kplayer; never changes or deletes any multimedia files or directories on +your system, so these sections are mostly useful for finding your multimedia and +<link linkend="howto-library-editing">putting</link> it in the +<link linkend="howto-library-collection"><guilabel>Collection</guilabel></link>, +on <link linkend="howto-library-playlists"><guilabel>Playlists</guilabel></link> +or on the <link linkend="howto-library-now-playing">current +playlist</link>.</para> + +</sect2> + +</sect1> diff --git a/doc/en/howto-playlist.docbook b/doc/en/howto-playlist.docbook new file mode 100644 index 0000000..2ac734c --- /dev/null +++ b/doc/en/howto-playlist.docbook @@ -0,0 +1,239 @@ +<sect1 id="howto-playlist"> +<title>Playlist</title> + +<sect2 id="howto-playlist-builtin"> +<title>Current playlist</title> + +<para>&kplayer; keeps a list of files, directories, streams, tracks, titles and +channels that are being played or are going to be played or have recently been +played. It shows the current playlist in a drop down box on the +<link linkend="parts-toolbar-playlist">playlist toolbar</link>. If there are any +directories on the current playlist, the drop down list shows their contents +instead of the directories themselves.</para> + +<para>The <link linkend="toolbar-playlist">playlist toolbar</link>, the +<link linkend="menu-player"><guimenu>Player</guimenu> menu</link> and the +<link linkend="popup-playlist">playlist popup menu</link> have +<guimenuitem>Next</guimenuitem> and <guimenuitem>Previous</guimenuitem> commands +that tell &kplayer; to play the next and previous item from the list +respectively. Also, selecting an entry from the drop down list on the toolbar +will make it the current entry and start playing it.</para> + +<para>When you ask &kplayer; to play things in any of the following ways, it +wipes out the current playlist and puts the new items on it:</para> + +<itemizedlist> + +<listitem><para>any of the various <guimenuitem>Play</guimenuitem> commands on +the <link linkend="menu-file"><guimenu>File</guimenu> menu</link> or its +submenus;</para></listitem> + +<listitem><para><guimenuitem>Play</guimenuitem> or +<guimenuitem>Play Next</guimenuitem> command from the +<link linkend="menu-library"><guimenu>Library</guimenu> menu</link>, except when +you use them on items that are already on the current +playlist;</para></listitem> + +<listitem><para>an equivalent command from a <mousebutton>right</mousebutton> +click <link linkend="popup-menus">popup menu;</link></para></listitem> + +<listitem><para>running &kplayer; with a file or directory path or a +<acronym>URL</acronym> from &konqueror;, from the command line, from a script, +etc.;</para></listitem> + +<listitem><para><guilabel>Play</guilabel> or <guilabel>Play Next</guilabel> +action in &konqueror;, &kicker; or any other program that supports those +actions;</para></listitem> + +<listitem><para>dragging and dropping files and directories or a +<acronym>URL</acronym> from &konqueror; or another program onto any part of +&kplayer; except the <link linkend="parts-library"><interface>multimedia +library</interface></link>.</para></listitem> + +</itemizedlist> + +<para>There are also several ways to add entries to the current playlist:</para> + +<itemizedlist> + +<listitem><para><guimenuitem>Queue</guimenuitem> or +<guimenuitem>Queue Next</guimenuitem> command on the +<link linkend="menu-library"><guimenu>Library</guimenu> menu</link> or the +<link linkend="popup-library">library popup menu</link> in the +<interface>multimedia library</interface>; if you use these commands on items +that are already on the current playlist, &kplayer; will move them to the end +of the playlist;</para></listitem> + +<listitem><para><guilabel>Queue</guilabel> or <guilabel>Queue Next</guilabel> +action in &konqueror;, &kicker; or any other program that supports those +actions;</para></listitem> + +<listitem><para><menuchoice><guisubmenu>Add</guisubmenu> +<guimenuitem>Files...</guimenuitem></menuchoice> or +<menuchoice><guisubmenu>Add</guisubmenu> +<guimenuitem>URL...</guimenuitem></menuchoice> on the +<link linkend="menu-library"><guimenu>Library</guimenu> menu</link> or the +<link linkend="popup-library">library popup menu</link> in the +<guilabel>Now Playing</guilabel> section of the +<interface>multimedia library</interface> or from the +<link linkend="popup-playlist">playlist popup menu</link>;</para></listitem> + +<listitem><para>dragging and dropping items from &konqueror; or another program +or another part of the <interface>multimedia library</interface> into the +<guilabel>Now Playing</guilabel> section of the library.</para></listitem> + +</itemizedlist> + +<para>&kplayer; has a few options that control the playlist behavior:</para> + +<itemizedlist> + +<listitem><para><guilabel>Loop</guilabel> option tells &kplayer; to play the +current playlist again from the beginning after it finishes playing +it.</para></listitem> + +<listitem><para><guilabel>Shuffle</guilabel> option arranges items on the +current playlist in a random order.</para> + +<para>If the <guilabel>Loop</guilabel> option is also turned on, the playlist +will be reshuffled after each loop. To reshuffle at any time, turn the +<guilabel>Shuffle</guilabel> option off and then back on.</para> + +<para>These two options are available on the +<link linkend="toolbar-playlist">playlist toolbar</link>, the +<link linkend="menu-player"><guimenu>Player</guimenu> menu</link> and the +<link linkend="popup-playlist">playlist popup menu</link>.</para></listitem> + +<listitem><para><guilabel>Allow duplicate entries on playlists</guilabel> option +lets you put more than one entry with exactly the same <acronym>URL</acronym> on +the playlist. When this option is turned off, &kplayer; will automatically +remove duplicate entries from the playlist. However, you still can put the same +entry in two different folders in the <guilabel>Now Playing</guilabel> section +of the <link linkend="parts-library"><interface>multimedia +library</interface></link>, and then they both will be on +the current playlist. This option also affects playlists stored in the +<guilabel>Playlists</guilabel> section of the library, as well as folders in the +<guilabel>Recent</guilabel> section. This option is on the +<link linkend="settings-general"><guilabel>General</guilabel> page</link> +in <guilabel>&kplayer; Settings</guilabel>.</para></listitem> + +</itemizedlist> + +<para>To remove entries from the current playlist, or to change the order of +entries, open the <guilabel>Now Playing</guilabel> section of the +<interface>multimedia library</interface> by choosing +<menuchoice><guimenu>Library</guimenu><guisubmenu>Go</guisubmenu> +<guimenuitem>Now Playing</guimenuitem></menuchoice> or +<mousebutton>right</mousebutton> clicking the playlist drop down box on the +<link linkend="parts-toolbar-playlist">playlist toolbar</link> and choosing +<menuchoice><guimenuitem>Edit</guimenuitem></menuchoice>. Then use the +<guimenuitem>Remove</guimenuitem>, <guimenuitem>Move Up</guimenuitem> and +<guimenuitem>Move Down</guimenuitem> commands from the +<link linkend="menu-library"><guimenu>Library</guimenu> menu</link> or the +<link linkend="popup-library">library popup menu</link> to edit the +playlist. Clicking a column header in the <interface>list view</interface> +resets the order of items in the current playlist folder and any expanded +subfolders and sorts the folder by that column.</para> + +<para>You can save the current playlist in the <guilabel>Playlists</guilabel> +or the <guilabel>Collection</guilabel> section of the <interface>multimedia +library</interface> by <mousebutton>right</mousebutton> clicking the playlist +drop down box on the <link linkend="parts-toolbar-playlist">playlist +toolbar</link> and choosing <menuchoice><guisubmenu>Add to</guisubmenu> +<guimenuitem>Playlists...</guimenuitem></menuchoice> or +<menuchoice><guisubmenu>Add to</guisubmenu> +<guimenuitem>Collection...</guimenuitem></menuchoice> respectively. The playlist +will then appear on the <guisubmenu>Play List</guisubmenu> submenu of the +<link linkend="menu-file"><guimenu>File</guimenu> menu</link> and several +<link linkend="popup-menus">popup menus</link>, as well as on the +<guisubmenu>Add to</guisubmenu> submenus of the +<link linkend="menu-library"><guimenu>Library</guimenu> menu</link> and the +<link linkend="popup-library">library popup menu</link>. +<mousebutton>Right</mousebutton> clicking the playlist +drop down box and choosing <menuchoice><guisubmenu>Add to</guisubmenu> +<guimenuitem>an existing playlist name</guimenuitem></menuchoice> will add the +contents of the current playlist to the existing playlist you choose.</para> + +<para>For more information on the multimedia library feature see the +<link linkend="howto-library">Multimedia library micro-HOWTO</link>.</para> + +</sect2> + +<sect2 id="howto-playlist-stored"> +<title>Stored playlists</title> + +<para>To create a new playlist and store it in the +<guilabel>Playlists</guilabel> section of the +<link linkend="parts-library"><interface>multimedia library</interface></link>, +select the multimedia you want to put on it in another section of the library, +choose <menuchoice><guisubmenu>Add to</guisubmenu> +<guimenuitem>New Playlist...</guimenuitem></menuchoice> from the +<link linkend="menu-library"><guimenu>Library</guimenu> menu</link> or the +<link linkend="popup-library">library popup menu</link>, and enter the name +of the new playlist. If the multimedia is already stored in a folder, you can +use the <menuchoice><guisubmenu>Add to</guisubmenu> +<guimenuitem>Playlists</guimenuitem></menuchoice> command instead. These +commands are also available on the <guisubmenu>Actions</guisubmenu> submenu +of the <mousebutton>right</mousebutton> click popup menu in &konqueror;, +&kicker; and other programs.</para> + +<para>The playlists you create in the <guilabel>Playlists</guilabel> section +will appear on the <guisubmenu>Play List</guisubmenu> submenu of the +<link linkend="menu-file"><guimenu>File</guimenu> menu</link> and several +<link linkend="popup-menus">popup menus</link> that lets you play a list by +choosing it from the menu, as well as on the <guisubmenu>Add to</guisubmenu> +submenu of the <link linkend="menu-library"><guimenu>Library</guimenu> +menu</link> and the <link linkend="popup-library">library popup menu</link> +that allows you add more multimedia to an existing playlist. The +<guilabel>Maximum entries on playlist menus</guilabel> option on the +<link linkend="settings-general"><guilabel>General</guilabel> page</link> of +<guilabel>&kplayer; Settings</guilabel> gives the maximum number of playlists +that will be included on the submenus.</para> + +<para>Just like with the current playlist, you can edit a playlist stored in the +<guilabel>Playlists</guilabel> section by opening the list in the +<interface>multimedia library</interface> and using commands from the +<link linkend="menu-library"><guimenu>Library</guimenu> menu</link> and the +<link linkend="popup-library">library popup menu</link>, or add more items to it +by dragging and dropping them onto the playlist or any of its subfolders.</para> + +<para>For more details see the <link linkend="howto-library">Multimedia library +micro-HOWTO</link>.</para> + +</sect2> + +<sect2 id="howto-playlist-files"> +<title>Playlist files</title> + +<para><link linkend="howto-installation-mplayer">&mplayer;</link> currently +cannot automatically detect and play playlist files like <literal>m3u</literal>, +<literal>pls</literal>, <literal>asx</literal>, <literal>ram</literal> and so +on. &kplayer; needs to pass a special option to &mplayer; for it to play a +playlist file correctly.</para> + +<para>&kplayer; tries to detect playlist files by file extension. However, +sometimes a playlist file will not have a playlist extension, or a file that +is not a playlist can have a playlist extension. In those cases playback will +initially fail. You can then go to the <link linkend="properties">General +page</link> in <guilabel>File Properties</guilabel> and set the +<guilabel>Playlist</guilabel> option correctly. &kplayer; will remember the +option and use it the next time you play the same file or +<acronym>URL</acronym>.</para> + +<para>If setting the <guilabel>Playlist</guilabel> option does not help, you +will need to manually extract the actual path or <acronym>URL</acronym> from the +file and paste it into the <guilabel>Play URL</guilabel> dialog that you can +open from the <guimenu>File</guimenu> menu or the <guilabel>Add URL</guilabel> +dialog that you get when you <mousebutton>right</mousebutton> click the +<link linkend="toolbar-playlist">playlist toolbar</link> and choose +<menuchoice><guisubmenu>Add</guisubmenu> +<guimenuitem>URL...</guimenuitem></menuchoice>.</para> + +<para>The playlist extensions &kplayer; recognizes are <literal>ram</literal>, +<literal>rpm</literal>, <literal>smi</literal>, <literal>smil</literal>, +<literal>asx</literal>, <literal>m3u</literal>, <literal>pls</literal> and +<literal>strm</literal>.</para> + +</sect2> + +</sect1> diff --git a/doc/en/howto-properties.docbook b/doc/en/howto-properties.docbook new file mode 100644 index 0000000..c2d720d --- /dev/null +++ b/doc/en/howto-properties.docbook @@ -0,0 +1,539 @@ +<sect1 id="howto-properties"> +<title>File properties</title> + +<para>Starting from &kplayer; 0.5 each file and <acronym>URL</acronym> 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.</para> + +<para>Most properties can be set through the <link linkend="properties">File +Properties dialog</link>. The <guilabel>Properties</guilabel> dialog for the +currently loaded file or <acronym>URL</acronym> can be opened from the +<link linkend="menu-file"><guimenu>File</guimenu></link> menu, or using the +<guibutton>Properties</guibutton> button on the +<link linkend="toolbar-main">main toolbar</link>, or from the <link +linkend="popup-main">right click popup menu</link>. You can also open the +<guilabel>Properties</guilabel> dialog for an entry in the +<link linkend="parts-library"><interface>multimedia library</interface></link> +by <mousebutton>right</mousebutton> clicking it and selecting +<guimenuitem>Properties...</guimenuitem>, or by using the +<guimenuitem>Properties...</guimenuitem> command on the +<link linkend="menu-library"><guimenu>Library</guimenu> menu</link>.</para> + +<para>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 +<guimenuitem>Soft Frame Dropping</guimenuitem> from the +<guimenu>Player</guimenu> menu, &kplayer; will remember that setting for +the current <acronym>URL</acronym>, and use it the next time you play it. +After it is done playing the current <acronym>URL</acronym>, it will revert +the <guilabel>Frame drop</guilabel> setting to the default, the one that +was in effect before you changed it with &Shift;. On the other hand, if you +change the <guilabel>Frame drop</guilabel> setting without holding &Shift;, +the new setting will become the default, and will be used for all +<acronym>URL</acronym>s that do not have it set explicitly.</para> + +<para>Volume, contrast, brightness, hue and saturation are handled in a +special way when it comes to file properties. Instead of remembering the +exact setting when you hold &Shift;, &kplayer; will remember the setting +relatively to the default.</para> + +<para>For example, if you have a file that was recorded louder than your +other files, when playing that file you can hold &Shift; and adjust the +volume level to be the same as for other files. &kplayer; will remember +this as something like <quote>lower the volume by 10 units when playing +this file</quote>. If later you for example have a party and need to play +your files louder than usual, you turn the volume up (without holding &Shift;), +so all files play louder, then when the turn of that one file comes, &kplayer; +will lower the volume by 10 units while playing it, so it again has the same +volume level as the other files, and then turn the volume 10 units up when +it moves to the next file.</para> + +<para>Another example, you find a video that is dark and so needs to be +played with higher brightness than other videos. So you hold the &Shift; +key and drag the brightness slider up. &kplayer; remembers the higher +brightness for this file, and then goes back to playing at normal brightness +when you play another file. Suppose you did that at night, and next time you +play the videos during daylight, so you want to play all of them at higher +brightness. Then you drag the brightness slider up, this time without holding +&Shift;, so the setting is made the default and applied to all videos that do +not have a brightness property set. When the turn of the dark video comes, +&kplayer; sees that it needs to be played at an even higher brightness and +turns it further up, but only for the duration of that one video, and then +restores it back to the default you set.</para> + +<para>Choosing the <guimenuitem>Full Screen</guimenuitem> command or clicking +the <guibutton>Maximize</guibutton> or <guibutton>Restore</guibutton> button +in the <link linkend="parts-title-bar">title bar</link> while holding &Shift; +will set the <guilabel>Full screen</guilabel> property. Choosing an aspect +command with &Shift; will set the <guilabel>Display size</guilabel> property +to <guilabel>set aspect</guilabel> and the aspect you choose, and also will +set the <guilabel>Maintain aspect</guilabel> property. A zooming command on +the <guimenu>View</guimenu> menu when chosen with &Shift; will set the +<guilabel>Display size</guilabel> property to <guilabel>set size</guilabel> +and the fixed size, and so will resizing the window if you press &Shift; +before you begin resizing the window.</para> + +<para>This special function of the &Shift; key can be turned off on the +<link linkend="settings-controls">Controls page</link> in <guilabel>&kplayer; +Settings</guilabel>.</para> + +<para>There are two special cases when you can also hold &Shift; to modify +&kplayer; behavior. First, you can hold &Shift; when telling it to play a file +or <acronym>URL</acronym> or dropping files onto &kplayer; window. &kplayer; +will then load the first file or <acronym>URL</acronym> but will not start +playing it. You can then open its <guilabel>File Properties</guilabel> and make +your choices before starting to play it.</para> + +<para>Second, if you hold &Shift; when choosing the +<guimenuitem>Play</guimenuitem> command from the <guimenu>Player</guimenu> +menu or clicking the <guibutton>Play</guibutton> button, &kplayer; will +first stop the helper process that it runs once for each file to try and +figure out the time length of the file. This is needed rarely if ever, only +when the helper process causes any problems.</para> + +<para>&kplayer; will remember properties for every file or +<acronym>URL</acronym> that it opens, even those that are removed from the +playlist, until the total number reaches the limit set on the +<link linkend="settings-general"><guilabel>General</guilabel> page</link> in +<guilabel>&kplayer; Settings</guilabel> under <guilabel>Meta information cache +size limit</guilabel>, by default 10000. After that it will start discarding the +oldest entries. Playing an entry makes it the most recent entry in the cache. If +you have very many files, you can set the cache size limit higher, but as some +point it may start affecting &kplayer; performance.</para> + +<para>Following are the available file properties, listed by pages in the +<link linkend="properties">File Properties</link> dialog.</para> + +<sect2 id="howto-properties-general"> +<title><link linkend="properties-general">General</link> properties</title> + +<variablelist> + +<varlistentry><term><guilabel>Name</guilabel></term> +<listitem><para>This is the name that &kplayer; will display for this file or +<acronym>URL</acronym> in the +<link linkend="parts-library"><interface>multimedia library</interface></link>, +on the current playlist and also in the <link linkend="parts-title-bar">title +bar</link> when the file is loaded. Changing this property will not change the +actual file system name of the file.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Path or URL</guilabel></term> +<listitem><para>The file system path to the file or the <acronym>URL</acronym> +of the file or stream. This property is read only. To use a different path or +<acronym>URL</acronym>, open it with the <guimenuitem>Play...</guimenuitem> or +<guimenuitem>Play URL...</guimenuitem> command on the <guimenu>File</guimenu> +menu, or by dragging and dropping it onto &kplayer; window, or starting +&kplayer; with <acronym>URL</acronym> argument(s), for example by launching +files from &konqueror; File Manager or clicking a link in &konqueror; Web +Browser.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Type</guilabel></term> +<listitem><para>The type of the item. For a device, track, title or channel it +is the device type. For other items it is the <acronym>MIME</acronym> type if +known.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Frequency</guilabel></term> +<listitem><para>The frequency in <acronym>MHz</acronym> of a +<acronym>DVB</acronym>, <acronym>PVR</acronym> or <acronym>TV</acronym> channel. +For other items this property is not applicable and not +shown.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Playlist</guilabel></term> +<listitem><para>&mplayer; currently is not smart enough to automatically detect +and play a playlist file like <literal>pls</literal> or <literal>m3u</literal>, +so &kplayer; has to explicitly tell it to parse a file as a playlist. The +<guilabel>auto</guilabel> setting lets &kplayer; use the file extension to guess +if it is a playlist file. The playlist extensions &kplayer; recognizes are +<literal>ram</literal>, <literal>rpm</literal>, <literal>smi</literal>, +<literal>smil</literal>, <literal>asx</literal>, <literal>m3u</literal>, +<literal>pls</literal> and <literal>strm</literal>. If a file that is not a +playlist has one of these extensions, or a playlist file has a different +extension, you will need to correctly set this property in order to be able to +play the file or stream.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Length</guilabel></term> +<listitem><para>The time length of the file. &kplayer; tries to detect it with +precision of one tenth of a second, and usually gets it pretty close to the +real length. This property is read only.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Channels</guilabel></term> +<listitem><para>The list of channels available on a <acronym>TV</acronym> or +<acronym>PVR</acronym> device. &kplayer; chooses the default channel list based +on the country setting in &kcontrolcenter;, or <guilabel>Western +Europe</guilabel> if that is not set. You can change the channel list here. +Not applicable to other items.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Driver</guilabel></term> +<listitem><para>Input driver for a <acronym>TV</acronym> or +<acronym>PVR</acronym> device. By default this is set to +<guilabel>Video4Linux 2</guilabel>, but if your driver only supports the old +Video4Linux interface, like for example the <literal>gspcav1</literal> driver, +select <guilabel>Video4Linux</guilabel> from this list. Not applicable to other +items.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Channel file</guilabel></term> +<listitem><para>A <acronym>DVB</acronym> device needs a file listing the +available channels and their properties. &kplayer; looks for a file having +<literal>channels.conf</literal> as part of its name in +<filename>~/.mplayer</filename>, <filename>/etc/mplayer</filename> and +<filename>/usr/local/etc/mplayer</filename> and uses the first matching file +it finds. You can change the channel file path here. If you don't have a channel +file, you can generate it using the <command>scan</command> utility that comes +with <acronym>DVB</acronym> drivers.</para></listitem></varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="howto-properties-size"> +<title><link linkend="properties-size">Size</link> properties</title> + +<variablelist> + +<varlistentry><term><guilabel>Resolution</guilabel>, <guilabel>Original +size</guilabel> and <guilabel>Current size</guilabel></term> +<listitem><para>Resolution of the video is adjusted to the correct aspect ratio +to get the original video size, which is then adjusted to get the current size +by taking into account any filters applied to the video. These properties are +empty for audio only files, and they are read only, but see the next +property.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Display size</guilabel></term> +<listitem><para>Here you can set the initial video size &kplayer; will use +when it starts playing the file, unless you turned off the option to +<guilabel>Resize main window automatically</guilabel> on the +<link linkend="settings-general">General page</link> in <guilabel>&kplayer; +Settings</guilabel>. The <guilabel>default</guilabel> setting will use the +<guilabel>Minimum initial video width</guilabel> option from the +<link linkend="settings-general">General page</link> in <guilabel>&kplayer; +Settings</guilabel>. The <guilabel>set size</guilabel> setting will use the +fixed initial size you specify. The <guilabel>set aspect</guilabel> setting +will again use the <guilabel>Minimum initial video width</guilabel> option, +but will apply the fixed initial aspect you +specify.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Full screen</guilabel></term> +<listitem><para>Normally you would leave this at the +<guilabel>default</guilabel> setting, which will keep the full screen state of +the previous file. The <guilabel>yes</guilabel> setting will force full screen +mode unless this is an audio only file, and the <guilabel>no</guilabel> setting +will force the normal windowed mode.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Maximized</guilabel></term> +<listitem><para>When the file is not played full screen, the +<guilabel>yes</guilabel> setting for this option will force maximized window +mode, and the <guilabel>no</guilabel> setting will force normal window mode. +The <guilabel>default</guilabel> setting will keep the window state of the +previous file.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Maintain aspect</guilabel></term> +<listitem><para>Here you can set the <guilabel>Maintain aspect</guilabel> option +specifically for this file. The <guilabel>default</guilabel> setting will keep +the <guilabel>Maintain aspect</guilabel> option you choose +globally.</para></listitem></varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="howto-properties-video"> +<title><link linkend="properties-video">Video</link> properties</title> + +<variablelist> + +<varlistentry><term><guilabel>Track</guilabel></term> +<listitem><para>The <guilabel>auto</guilabel> option tells &mplayer; to choose +a video track automatically. The <guilabel>set ID</guilabel> option lets you +enter a number giving the video track ID to play. This option is set when you +select a video track from the +<link linkend="submenu-video"><guisubmenu>Video</guisubmenu></link> submenu of +the <guimenu>Player</guimenu> menu. The submenu will list the available video +tracks for files and streams that have more than one video +track.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Contrast</guilabel>, +<guilabel>Brightness</guilabel>, <guilabel>Hue</guilabel> +and <guilabel>Saturation</guilabel></term> +<listitem><para>The <guilabel>default</guilabel> option uses the same setting +as for other files. The <guilabel>set to</guilabel> option sets the specified +initial contrast, brightness, hue or saturation when loading the file. +The <guilabel>add</guilabel> and <guilabel>substract</guilabel> options adjust +the contrast, brightness, hue or saturation relative to the normal setting. See +the <link linkend="howto-properties">introduction section</link> of this HOWTO +for more details and some examples of how this +works.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Codec</guilabel></term> +<listitem><para>Specifies the video codec to use when playing this file. The +<guilabel>default</guilabel> setting will use the codec chosen on the +<link linkend="settings-video">Video page</link> in <guilabel>&kplayer; +Settings</guilabel>, normally <guilabel>auto</guilabel>. The +<guilabel>auto</guilabel> setting will tell &mplayer; to choose the codec it +thinks is the best for playing this file.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Bitrate</guilabel> and +<guilabel>Framerate</guilabel></term> +<listitem><para>The video bitrate and framerate of the file or stream. These +properties are read only.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Input</guilabel></term> +<listitem><para>The <guilabel>auto</guilabel> option tells &mplayer; to choose +a <acronym>TV</acronym> or <acronym>DVB</acronym> input automatically. The +<guilabel>set to</guilabel> option lets you enter a number giving the device +input to use. Only applicable to <acronym>TV</acronym>, <acronym>PVR</acronym> +and <acronym>DVB</acronym> devices.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Format</guilabel></term> +<listitem><para>The <guilabel>auto</guilabel> option tells &mplayer; to choose a +<acronym>TV</acronym> video output format automatically. The other options let +you specify the video format explicitly. Only applicable to +<acronym>TV</acronym> and <acronym>PVR</acronym> +devices.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Norm</guilabel></term> +<listitem><para>The <guilabel>auto</guilabel> option tells &mplayer; to choose +a <acronym>TV</acronym> norm automatically. The <guilabel>set ID</guilabel> +option lets you enter a number giving the <acronym>TV</acronym> norm. The other +options let you specify the <acronym>TV</acronym> norm explicitly. Only +applicable to <acronym>TV</acronym> and <acronym>PVR</acronym> +devices.</para></listitem></varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="howto-properties-audio"> +<title><link linkend="properties-audio">Audio</link> properties</title> + +<variablelist> + +<varlistentry><term><guilabel>Track</guilabel></term> +<listitem><para>The <guilabel>auto</guilabel> option tells &mplayer; to choose +an audio track automatically. The <guilabel>set ID</guilabel> option lets you +enter a number giving the audio track ID to play. This option is set when you +select an audio track from the +<link linkend="submenu-audio"><guisubmenu>Audio</guisubmenu></link> submenu of +the <guimenu>Player</guimenu> menu. The submenu will list the available audio +tracks for files and streams that have more than one audio +track.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Volume</guilabel></term> +<listitem><para>The <guilabel>default</guilabel> option uses the same sound +volume as for other files. The <guilabel>set to</guilabel> option sets the +specified initial volume when loading the file. The <guilabel>add</guilabel> +and <guilabel>substract</guilabel> options will adjust the volume relative +to the normal volume level. See the +<link linkend="howto-properties">introduction section</link> of this HOWTO +for more details and some examples of how this +works.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Delay</guilabel></term> +<listitem><para>Delay of the sound relative to video. By default this property +is remembered automatically when you use <guimenuitem>Increase +Delay</guimenuitem> and <guimenuitem>Decrease Delay</guimenuitem> commands +from the <link linkend="submenu-audio"><guisubmenu>Audio</guisubmenu> +submenu</link> of the <guimenu>Player</guimenu> menu. The +<guilabel>default</guilabel> setting always resets audio delay to zero when a +file is loaded.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Codec</guilabel></term> +<listitem><para>This specifies the audio codec to use when playing this file. +The <guilabel>default</guilabel> setting will use the codec chosen on the +<link linkend="settings-audio">Audio page</link> in <guilabel>&kplayer; +Settings</guilabel>, normally <guilabel>auto</guilabel>. The +<guilabel>auto</guilabel> setting will tell &mplayer; to choose the codec it +thinks is the best for playing this file.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Bitrate</guilabel> and +<guilabel>Samplerate</guilabel></term> +<listitem><para>The audio bitrate and samplerate of the file or stream. These +properties are read only.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Mode</guilabel></term> +<listitem><para>The <guilabel>auto</guilabel> option tells &mplayer; to choose +a <acronym>TV</acronym> audio mode automatically. The other options let you +specify the audio mode explicitly. Only applicable to <acronym>TV</acronym> and +<acronym>PVR</acronym> devices.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Input</guilabel></term> +<listitem><para>The <guilabel>auto</guilabel> option tells &mplayer; to choose +a <acronym>TV</acronym> or <acronym>DVB</acronym> audio input automatically. The +<guilabel>set to</guilabel> option lets you enter a number giving the audio +input to use. Only applicable to <acronym>TV</acronym>, <acronym>PVR</acronym> +and <acronym>DVB</acronym> devices.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Immediate mode</guilabel></term> +<listitem><para>When disabled, &mplayer; will capture audio from the same device +as video. When enabled, tells &mplayer; to capture audio through a cable going +from the <acronym>TV</acronym> card to the sound card. Only applicable to +<acronym>TV</acronym> and <acronym>PVR</acronym> +devices.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Capture</guilabel> and +<guilabel>Device</guilabel></term> +<listitem><para>The audio capture system, either <acronym>ALSA</acronym> or +<acronym>OSS</acronym>, and the input device. Only applicable to +<acronym>TV</acronym> and <acronym>PVR</acronym> +devices.</para></listitem></varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="howto-properties-subtitles"> +<title><link linkend="properties-subtitles">Subtitle</link> properties</title> + +<variablelist> + +<varlistentry><term><guilabel>Track</guilabel></term> +<listitem><para>The <guilabel>none</guilabel> option disables subtitle display. +The <guilabel>external</guilabel> option tells &mplayer; to display subtitles +loaded from an external file given by the <guilabel>External path</guilabel> +property below. The <guilabel>set ID</guilabel> option lets you enter a number +giving the ID of an internal subtitle track to display. This option is set when +you load subtitles from a subtitle file or when you select a subtitle track or +the <guilabel>None</guilabel> option from the +<link linkend="submenu-subtitles"><guisubmenu>Subtitles</guisubmenu></link> +submenu of the <guimenu>Player</guimenu> menu. The submenu lists the available +subtitles for files and streams that have embedded subtitle tracks or for which +you load subtitles from a subtitle file.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>External path</guilabel></term> +<listitem><para>Path to the subtitle file to be loaded for this file or stream. +This property is set automatically when you use the <guimenuitem>Load +Subtitles...</guimenuitem> command on the <guimenu>File</guimenu> +menu or drag and drop subtitle files onto &kplayer; window or use a command on +the <guisubmenu>Subtitles</guisubmenu> submenu of the <guimenu>Player</guimenu> +menu to display subtitles from an external subtitle +file.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>External type</guilabel></term> +<listitem><para>The <guilabel>auto</guilabel> option tells &kplayer; to +determine the type of the external subtitles based on the file extension. The +<guilabel>vobsub</guilabel> option sets the VobSub type explicitly, and the +<guilabel>normal</guilabel> option tells &kplayer; that these are not VobSub +subtitles.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Encoding</guilabel></term> +<listitem><para>The encoding of the text in the subtitle file. If &mplayer; +does not decode the subtitles properly, set this property to the correct +encoding. You can also set the encoding globally in <link +linkend="settings-subtitles"><guilabel>&kplayer; Settings</guilabel></link> +if most of your subtitle files share the same +encoding.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Framerate</guilabel></term> +<listitem><para>The <guilabel>auto</guilabel> option uses the frame rate of the +video file. If the subtitle file does not have the same framerate as the video, +specify it in this property.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Autoload</guilabel></term> +<listitem><para>Tells &kplayer; whether to try to autoload subtitles for this +file. The <guilabel>default</guilabel> setting uses the +<guilabel>Autoload</guilabel> options from the +<link linkend="settings-subtitles">Subtitles page</link> in <guilabel>&kplayer; +Settings</guilabel>. This property is only available for local files. For all +other <acronym>URL</acronym>s it is set to +<guilabel>no</guilabel>.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Position</guilabel></term> +<listitem><para>Vertical subtitle position, 0 being at the top of the video +area, and 100 at the bottom. The <guilabel>default</guilabel> setting simply +keeps the last used position.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Delay</guilabel></term> +<listitem><para>Delay of the subtitles relative to video. By default this +property is remembered automatically when you use <guimenuitem>Increase +Delay</guimenuitem> and <guimenuitem>Decrease Delay</guimenuitem> commands +from the <link linkend="submenu-subtitles"><guisubmenu>Subtitles</guisubmenu> +submenu</link> of the <guimenu>Player</guimenu> menu. The +<guilabel>default</guilabel> setting always resets subtitle delay to zero when +a file with subtitles is loaded.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Closed caption</guilabel></term> +<listitem><para>Choose whether to display or hide closed caption subtitles. +You can set this property on a device, on a disk, or on an individual title on +a <acronym>DVD</acronym>. Other kinds of media do not have this +property.</para></listitem></varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="howto-properties-advanced"> +<title><link linkend="properties-advanced">Advanced</link> properties</title> + +<variablelist> + +<varlistentry><term><guilabel>Additional command line arguments</guilabel></term> +<listitem><para>Lets you specify additional arguments to be passed to &mplayer;. +You can either <guilabel>append</guilabel> the arguments to the ones given on the +<link linkend="settings-advanced">Advanced page</link> in <guilabel>&kplayer; +Settings</guilabel> or override them. The <guilabel>default</guilabel> option +uses the arguments given in <guilabel>&kplayer; +Settings</guilabel>.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Demuxer</guilabel></term> +<listitem><para>This specifies the demultiplexer to use when playing this file. +The <guilabel>default</guilabel> setting will use the demuxer chosen on the +<link linkend="settings-advanced">Advanced page</link> in <guilabel>&kplayer; +Settings</guilabel>, normally <guilabel>auto</guilabel>. The +<guilabel>auto</guilabel> setting will tell &mplayer; to choose the demuxer it +thinks is the best for playing this file.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Frame drop</guilabel></term> +<listitem><para>If your system is too slow to play the file properly, you can +tell &mplayer; to drop some frames. The <guilabel>soft</guilabel> setting drops +fewer frames than the <guilabel>hard</guilabel> one, so you should try it first. +The <guilabel>default</guilabel> setting uses the <guilabel>Frame +drop</guilabel> option from the +<link linkend="settings-advanced">Advanced page</link> in <guilabel>&kplayer; +Settings</guilabel>. You can also change this option while playing a file using +commands on the +<link linkend="submenu-advanced"><guisubmenu>Advanced</guisubmenu> +submenu</link> of the <link linkend="menu-player"><guimenu>Player</guimenu> +menu</link>. If you hold &Shift; when choosing them, &kplayer; by default will +remember the property for the current file.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Cache size</guilabel></term> +<listitem><para>Here you can set the cache size &mplayer; should use for this +file. See the <guilabel>Cache size</guilabel> sections in +<link linkend="howto-settings">Advanced configuration micro-HOWTO</link>, +<link linkend="howto-slaves">&kde; <acronym>I/O</acronym> Slaves +micro-HOWTO</link> and <link linkend="howto-streams">Online Radio and TV +micro-HOWTO</link> for details.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Build index</guilabel></term> +<listitem><para>This property allows you to choose whether &mplayer; should +build a new index always (<guilabel>force</guilabel>), never +(<guilabel>no</guilabel>) or only if the file does not have it +(<guilabel>yes</guilabel>).</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Use KIOSlave</guilabel></term> +<listitem><para>Some <acronym>URL</acronym> types, like +<acronym>HTTP</acronym>, <acronym>FTP</acronym> and Samba, can be played +either directly with &mplayer; or through a <link linkend="howto-slaves">&kde; +<acronym>I/O</acronym> Slave</link>. Generally you should set this option if +&mplayer; cannot play those <acronym>URL</acronym>s +directly.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Use temporary file</guilabel></term> +<listitem><para>When playing a <acronym>URL</acronym> using a &kde; +<acronym>I/O</acronym> Slave, data can either be passed to &mplayer; through +a named pipe or stored in a temporary file before playing. For +<acronym>URL</acronym>s passed directly to &mplayer; this option has no +effect.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Hardware compression</guilabel></term> +<listitem><para>Enables <acronym>MJPEG</acronym> compression in hardware for a +<acronym>TV</acronym> device and lets you specify the decimation (image size) +and the compression quality from 0 to 100. Only applicable to +<acronym>PVR</acronym> and <acronym>TV</acronym> devices that support hardware +compression.</para></listitem></varlistentry> + +</variablelist> + +</sect2> + +</sect1> diff --git a/doc/en/howto-settings.docbook b/doc/en/howto-settings.docbook new file mode 100644 index 0000000..3e53bd1 --- /dev/null +++ b/doc/en/howto-settings.docbook @@ -0,0 +1,372 @@ +<sect1 id="howto-settings"> +<title>Advanced configuration</title> + +<para>This micro-HOWTO describes some of the more advanced settings available +in the <link linkend="settings">&kplayer; Settings</link> dialog that you can +open using the <guimenuitem>Configure &kplayer;</guimenuitem> command on the +<link linkend="menu-settings"><guimenu>Settings</guimenu> menu</link>.</para> + +<sect2 id="howto-settings-general"> +<title><link linkend="settings-general">General</link> settings</title> + +<variablelist> + +<varlistentry><term><guilabel>Resize main window automatically</guilabel></term> +<listitem><para>By default &kplayer; resizes the main window automatically +unless it is maximized or full screen. When &kplayer; loads and starts playing +a new video, it scales it in increments of 50% of the original video size until +the video width reaches the <guilabel>Minimum initial video width</guilabel> +setting. It also automatically resizes the window to maintain the video aspect +if that option is turned on.</para> + +<para>If you would like to avoid automatic resizing and always keep the window +the size you make it, turn this option off. &kplayer; will then maintain the +video aspect by constraining the video within the window, as if the window was +maximized for example. You will also want to turn this option off if you get +problems coming back from full screen mode, like endless flickering for example. +But in that case you should also report the bug following instructions in the +<link linkend="howto-bug-reporting">Reporting bugs +micro-HOWTO</link>.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Maximum entries on playlist menus</guilabel>, +<guilabel>Maximum entries on Play Recent menu</guilabel> and +<guilabel>Maximum Recent entries in the library</guilabel></term> +<listitem><para>These options control the size of playlist menus, the recent +menu and the recent list in the +<link linkend="parts-library"><interface>multimedia library</interface></link> +respectively. If the limits are exceeded, the menus will show the top items +up to the limit you provide, and items from the <guilabel>Recent</guilabel> +section of the library that exceed the limit will be +removed.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Meta information cache size +limit</guilabel></term> +<listitem><para>&kplayer; will remember the +<link linkend="howto-properties">properties</link> of any files or +<acronym>URL</acronym>s it has played, even when they are removed from the +<interface>multimedia library</interface>. It will only start forgetting old +file properties after a large number of files have been played. This setting +controls that number, by default it is 10000. This has nothing to do with +&mplayer; cache, look on the <link linkend="howto-settings-advanced">Advanced +page</link> for that.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Allow duplicate entries on +playlists</guilabel></term> +<listitem><para>By default &kplayer; removes duplicate entries from playlists +when adding new entries. Turning the option on allows you to have duplicate +entries on playlists. Duplicate means that the entries' <acronym>URL</acronym>s +are exactly the same. Note however that different playlist folders can have +identical entries regardless of this setting.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Show messages if a file fails to +play</guilabel></term> +<listitem><para>When an error occurs while trying to play a file, &kplayer; +shows an <guilabel>Error</guilabel> indicator in the status bar. You can then +<mousebutton>left</mousebutton> click the indicator to show the +<link linkend="parts-message-log">message log</link> containing the full output +from &mplayer; and &kde; <acronym>I/O</acronym> Slaves. When this option is +turned on, &kplayer; will show the message log automatically whenever an error +occurs.</para></listitem></varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="howto-settings-controls"> +<title><link linkend="settings-controls">Control</link> settings</title> + +<variablelist> + +<varlistentry><term><guilabel>Always remember the following settings for +each file</guilabel></term> +<listitem><para>&kplayer; 0.5 and later comes with the ability to set a good +number of different options on a per file or <acronym>URL</acronym> basis. Those +options are called file properties. The <link linkend="howto-properties">File +properties micro-HOWTO</link> has more information.</para> + +<para>On this page you can choose the properties that will be remembered +automatically for each file or <acronym>URL</acronym>. By default &kplayer; +remembers the video aspect ratio, audio delay and subtitle +delay.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Remember for current file any changes made with +&Shift;</guilabel></term> +<listitem><para>Alternatively, you can make &kplayer; remember a setting for +the current file by holding the &Shift; key while changing that setting. For +example, if you have a video file that needs too much resources to play +correctly on your system, you can hold the &Shift; key and choose a frame +dropping setting from the +<link linkend="submenu-advanced"><guisubmenu>Advanced</guisubmenu> +submenu</link> of the <link linkend="menu-player"><guimenu>Player</guimenu> +menu</link>. &kplayer; will then use that setting for this file only, and will +continue using the default setting for all other +files.</para></listitem></varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="howto-settings-progress"> +<title><link linkend="settings-progress">Progress</link> and seeking control +settings</title> + +<variablelist> + +<varlistentry><term><guilabel>Seek amount</guilabel></term> +<listitem><para>This option allows you to choose how much &kplayer; will seek +forward or backward when you use the seek commands on the +<link linkend="menu-player"><guimenu>Player</guimenu> menu</link>. You can set +the amounts in percentages of the video length or in +seconds.</para></listitem></varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="howto-settings-volume"> +<title><link linkend="settings-volume">Volume</link> and +<link linkend="settings-contrast">video</link> control settings</title> + +<variablelist> + +<varlistentry><term><guilabel>Adjustment amount</guilabel></term> +<listitem><para>This is the amount by which a setting like volume or contrast +will change when you use commands like <guimenuitem>Increase +Volume</guimenuitem> or <guimenuitem>Decrease Contrast</guimenuitem> on the +<link linkend="menu-player"><guimenu>Player</guimenu> +menu</link>.</para></listitem></varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="howto-settings-audio-video"> +<title><link linkend="settings-audio">Audio</link> and +<link linkend="settings-video">video</link> settings</title> + +<variablelist> + +<varlistentry><term><guilabel>Driver</guilabel></term> +<listitem><para>This option allows you to choose the video or audio output that +<link linkend="howto-installation-mplayer">&mplayer;</link> will use. The +recommended outputs are XVideo for video and <acronym>ALSA</acronym> for +audio.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Device</guilabel></term> +<listitem><para>For some output types you can also specify the device that +&mplayer; will use for output. For other output types this sets the output +subtype instead. For still other output types this setting may not be meaningful +at all. You can find the details on the <ulink url="man:/mplayer">&mplayer; +manpage</ulink>.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Codec</guilabel></term> +<listitem><para>This sets the preferred decoder and codec that &mplayer; should +use for decoding video or audio. This option is not of much use anymore since +&kplayer; 0.5 introduced <link linkend="howto-properties">file properties</link> +and the ability to set the codec for each file or <acronym>URL</acronym> +individually.</para></listitem></varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="howto-settings-video"> +<title><link linkend="settings-video">Video</link> settings</title> + +<variablelist> + +<varlistentry><term><guilabel>Scaler</guilabel></term> +<listitem><para>When using a video output that does not support hardware +scaling, like X11, this option sets the scaler type to use. Since normally +you would use XVideo or another video output that supports hardware scaling, +this option will have no effect. But if you use X11 output or otherwise +enable software scaler, you can play around with this option to see what +setting gives you the best results. Bicubic and bicubic spline are supposed +to give smooth picture in most cases.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Double buffering</guilabel></term> +<listitem><para>This option is enabled by default. It gives smoother video +in most cases.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Direct rendering</guilabel></term> +<listitem><para>This option may give better performance. However, it will +not work with double buffering, and also causes subtitles to be jerky. +It is disabled by default.</para></listitem></varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="howto-settings-audio"> +<title><link linkend="settings-audio">Audio</link> settings</title> + +<variablelist> + +<varlistentry><term><guilabel>Control volume independently of other +programs</guilabel></term> +<listitem><para>This option tells &mplayer; to use software volume control, +which does not affect global volume settings on your system, but may result +in some distortion of the sound. When this is enabled, the maximum volume +level is controlled by the <guilabel>Maximum volume</guilabel> setting, which +is in percent of the normal volume level.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Mixer device</guilabel> and +<guilabel>Mixer channel</guilabel></term> +<listitem><para>These options let you choose an <acronym>ALSA</acronym> or +<acronym>OSS</acronym> device and channel that will be used to control the +sound volume. These options are not available when the software volume option +above is enabled.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Delay adjustment amount</guilabel></term> +<listitem><para>This option and a similar one for subtitles gives the amount by +which the delay of audio or subtitles relative to video will be changed when +using the <guimenuitem>Increase Delay</guimenuitem> and <guimenuitem>Decrease +Delay</guimenuitem> commands on the +<link linkend="submenu-audio"><guisubmenu>Audio</guisubmenu></link> or +<link linkend="submenu-subtitles"><guisubmenu>Subtitles</guisubmenu></link> +submenu of the <guimenu>Player</guimenu> menu or the corresponding keyboard +shortcuts.</para></listitem></varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="howto-settings-subtitles"> +<title><link linkend="settings-subtitles">Subtitle</link> settings</title> + +<variablelist> + +<varlistentry><term><guilabel>Font name</guilabel>, <guilabel>Bold</guilabel>, +<guilabel>Italic</guilabel> and <guilabel>Outline</guilabel></term> +<listitem><para>These options select the font for subtitle display and determine +its style and appearance.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Text size</guilabel> +and <guilabel>Auto scale</guilabel></term> +<listitem><para>These options determine the size of subtitle text. When +<guilabel>Auto scale</guilabel> is checked, the size option gives the scale +factor, otherwise it gives the font size in +points.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Encoding</guilabel></term> +<listitem><para>This option selects the default encoding of text in subtitle +files. You can also specify the encoding of individual subtitle files in the +<link linkend="properties-subtitles">subtitle properties</link> of the +corresponding video file.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Auto expand video area to aspect ratio</guilabel></term> +<listitem><para>This option automatically expands the video area to fit the +aspect ratio you choose and displays subtitles in the black area below or above +the video. &kplayer; will only expand the video when playing it with subtitles, +and only if the video is wider than the aspect ratio you choose.</para> + +<para>Normally you should choose the aspect ratio to match your monitor, usually +<guilabel>4:3</guilabel>. Then, if the video aspect ratio is higher, for example +16:9, and you play it with subtitles, &kplayer; will expand it to fit the 4:3 +aspect ratio, so that the subtitles appear in the black area below the +video.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Autoload subtitles</guilabel> +and <guilabel>Extensions</guilabel></term> +<listitem><para>These options enable automatic loading of external subtitle +files from the same directory where the video file is located. &kplayer; will +use the name of the video file and the specified extensions to look for any +matching subtitle files and automatically load them. If any files are found, +one of them will be automatically used to display subtitles, and all of the +subtitle files will appear on the <guisubmenu>Subtitles</guisubmenu> submenu +of the <guimenu>Player</guimenu> menu, allowing you to choose another file to +display.</para></listitem></varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="howto-settings-advanced"> +<title><link linkend="settings-advanced">Advanced</link> settings</title> + +<variablelist> + +<varlistentry><term><guilabel>Additional command line +arguments</guilabel></term> +<listitem><para>In this field you can place additional command line options +you want to pass to <link linkend="howto-installation-mplayer">&mplayer;</link>. +For example, to get more informational output in the +<link linkend="parts-message-log">message log</link>, put the +<option>-v</option> option in this field. You can add more options for an +individual file or <acronym>URL</acronym> in its +<link linkend="howto-properties-advanced">file +properties</link>.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Preferred demuxer</guilabel></term> +<listitem><para>This sets the preferred demultiplexer that &mplayer; should +use for decoding files and streams. You can also choose a demuxer for each +individual file or stream in its <link linkend="howto-properties-advanced">file +properties</link>. For example you can choose the <literal>lavf</literal> +option if the <literal>libavformat</literal> demuxer works better for your +multimedia than other &mplayer; demuxers.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Frame drop</guilabel></term> +<listitem><para>If your system is too slow to play your files properly, this +option will tell &mplayer; to drop some frames. You can also set the frame +dropping option on a per file or <acronym>URL</acronym> basis. Just hold down +the &Shift; key when selecting a frame dropping option from the +<link linkend="submenu-advanced"><guisubmenu>Advanced</guisubmenu> +submenu</link> of the <link linkend="menu-player"><guimenu>Player</guimenu> +menu</link>, and &kplayer; will remember it for the current file or +<acronym>URL</acronym>. If you need frame dropping, try the +<guilabel>soft</guilabel> option first.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Cache</guilabel></term> +<listitem><para>This is probably the most tricky of &mplayer; options. It is +especially important when playing directly from a +<link linkend="howto-slaves">&kde; <acronym>I/O</acronym> Slave</link>. Although +most audio files will play fine with only 64 kilobyte cache, such a small cache +will cause problems with many video files. Also, some slow media types like +<acronym>DVD</acronym>, <acronym>VCD</acronym>, <acronym>NFS</acronym>, Samba, +etc. may sometimes require much larger cache like eight megabytes. On the other +hand, low bitrate media like <link linkend="howto-streams">online radio +stations</link> may need smaller cache so they start playing more quickly. Also, +according to &mplayer; crashing message, non-interleaved <acronym>AVI</acronym> +files may need cache to be turned off. As usual, you can set the +<guilabel>Cache</guilabel> option for each individual file or +<acronym>URL</acronym> in its <link linkend="properties-advanced">file +properties</link>.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Build new index</guilabel></term> +<listitem><para>If a file does not have an index or has a broken one, so seeking +is not functional, you can try setting this option to see if it gives an +improvement. Turning it on usually does not hurt, but the +<guilabel>force</guilabel> setting should only be set in the +<link linkend="properties-advanced">properties</link> of an individual file or +<acronym>URL</acronym>.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Use temporary file for playing from +KIOSlave</guilabel></term> +<listitem><para>This option will only have effect when using a +<link linkend="howto-slaves">&kde; <acronym>I/O</acronym> Slave</link>. By +default it is turned off, so data is sent to &mplayer; through a named pipe. +This works most of the time, the only disadvantage being that seeking is not +possible and the time length will usually be unknown. If playing directly from +a &kde; <acronym>I/O</acronym> Slave does not work for you, turn this option on. +Then &kplayer; will download and save the file locally before playing it. This +will take more time and also take up some disk space temporarily, but it will +make length detection and seeking possible. This option is also available in +<link linkend="properties-advanced">file properties</link>, so you can change it +for individual files and +<acronym>URL</acronym>s.</para></listitem></varlistentry> + +<varlistentry><term><guilabel>Use KIOSlave for HTTP, FTP, SMB</guilabel></term> +<listitem><para>Those three <acronym>URL</acronym> types can be played either +directly by &mplayer; or using a <link linkend="howto-slaves">&kde; +<acronym>I/O</acronym> Slave</link>. All three options are turned off by +default, so the <acronym>URL</acronym>s are passed to &mplayer; directly. But +if that does not work for any reason, you will want to turn the corresponding +option on, so that &kplayer; uses the <acronym>I/O</acronym> Slave. You can also +set this option in the individual <link linkend="howto-properties-advanced">file +properties</link>.</para></listitem></varlistentry> + +</variablelist> + +</sect2> + +</sect1> diff --git a/doc/en/howto-slaves.docbook b/doc/en/howto-slaves.docbook new file mode 100644 index 0000000..de590c2 --- /dev/null +++ b/doc/en/howto-slaves.docbook @@ -0,0 +1,91 @@ +<sect1 id="howto-slaves"> +<title>Playing from &kde; I/O Slaves</title> + +<sect2 id="howto-slaves-about"> +<title>What are &kde; I/O Slaves</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:/host/path/</filename>, or a zip file +with <filename>zip:/home/cooldude/my.zip</filename>.</para> + +</sect2> + +<sect2 id="howto-slaves-using"> +<title>How &kplayer; uses them</title> + +<para>Many of the &kde; <acronym>I/O</acronym> Slaves can return video and audio +files and streams, for example <literal>fish:</literal>, +<literal>sftp:</literal>, <literal>webdav:</literal>, <literal>tar:</literal>, +<literal>zip:</literal>, <literal>audiocd:</literal> and so on. &kplayer; will +play them just like any other type of file. By default it will pass the data +directly to &mplayer; through a named pipe. If that does not work for any +reason, you can tell &kplayer; to use a temporary file for playing from &kde; +<acronym>I/O</acronym> Slaves on the <guilabel>Advanced</guilabel> page either +globally in <link linkend="settings-advanced">&kplayer; Settings</link> or in +individual <link linkend="properties-advanced">File Properties</link>. &kplayer; +will then download the entire file into a temporary directory before playing it, +which will consume some disk space temporarily, but will allow seeking and +length detection.</para> + +<para>Note that using the <literal>audiocd</literal> slave is not recommended. +Instead you should use &kplayer;'s own support for disk devices. It will detect +an audio <acronym>CD</acronym>, find audio tracks on it and list them on a +<link linkend="submenu-device">submenu</link> under the <guimenu>File</guimenu> +menu for easy playback, and will also try to retrieve the disk and track titles +from an online database.</para> + +</sect2> + +<sect2 id="howto-slaves-http"> +<title>HTTP, FTP and Samba</title> + +<para>The best way to play <acronym>URL</acronym>s that +<link linkend="howto-installation-mplayer">&mplayer;</link> supports is by +passing them on to &mplayer; directly. But if &mplayer; cannot play an +<acronym>HTTP</acronym>, <acronym>FTP</acronym> or Samba <acronym>URL</acronym> +for any reason, you have the option to tell &kplayer; to use a &kde; +<acronym>I/O</acronym> Slave. You can do that on the +<guilabel>Advanced</guilabel> page either for that individual +<acronym>URL</acronym> in its <link linkend="properties-advanced">File +Properties</link> or globally for all <acronym>URL</acronym>s of a particular +type in <link linkend="settings-advanced">&kplayer; Settings</link>.</para> + +</sect2> + +<sect2 id="howto-slaves-cache"> +<title>Cache size</title> + +<para>When playing directly from a &kde; <acronym>I/O</acronym> Slave, the +<guilabel>Cache</guilabel> setting is important. It should not be too small so +&mplayer; can detect the encoding type without discarding data, but on the other +hand with large values it will take longer to fill the cache, especially with +low bitrate streams like <link linkend="howto-streams">online radio +stations</link>.</para> + +<para>&kplayer; lets &mplayer; choose an optimal cache by default, but if you +experience problems, you can try a cache size setting of one megabyte. The cache +size can be set on the <guilabel>Advanced</guilabel> page either globally in +<link linkend="settings-advanced">&kplayer; Settings</link> or in individual +<link linkend="properties-advanced">File Properties</link>. Keep in mind that +the global setting will also affect files played directly by &mplayer;, and +changing it can cause unwanted side effects.</para> + +</sect2> + +<sect2 id="howto-slaves-playlists"> +<title>Playlist files</title> + +<para>When using a &kde; <acronym>I/O</acronym> Slave to play a playlist file, +only the playlist file itself will be retrieved from the +<acronym>I/O</acronym> Slave. All the <acronym>URL</acronym>s it contains will +be played by &mplayer; directly. You have to give &kplayer; the +<acronym>URL</acronym> contained in the playlist if you want it to be played +through an <acronym>I/O</acronym> Slave.</para> + +</sect2> + +</sect1> diff --git a/doc/en/howto-streams.docbook b/doc/en/howto-streams.docbook new file mode 100644 index 0000000..1a50ae2 --- /dev/null +++ b/doc/en/howto-streams.docbook @@ -0,0 +1,142 @@ +<sect1 id="howto-streams"> +<title>Online radio and TV</title> + +<para>One of the major advantages of &kplayer; is the use of +<link linkend="howto-installation-mplayer">&mplayer;</link> as the multimedia +playing backend. It allows &kplayer; to support the widest variety of media +types and encodings. In addition to that, &kplayer; detects most playlist file +types and ensures that they are reproduced correctly.</para> + +<sect2 id="howto-streams-types"> +<title>Major stream types</title> + +<para>The most widely used stream types for online media are RealMedia, +QuickTime, Windows Media and ShoutCast (MP3). &kplayer; will play all but very +few streams of those types. Choose <guimenuitem>Play URL...</guimenuitem> on +&kplayer;'s <guimenu>File</guimenu> menu, paste the stream address into the +<acronym>URL</acronym> box and select <guibutton>Open</guibutton>. +Alternatively, make sure your browser is configured to open &kplayer; +for the <acronym>MIME</acronym> types you would like to play with it, as well +as for <literal>rtsp:</literal>, <literal>pnm:</literal> and +<literal>mms:</literal> <acronym>URL</acronym>s. When you install &kplayer;, +&konqueror; configuration is done automatically, you +then just need to open <guilabel>File Association</guilabel> settings in +&konqueror; or in &kcontrolcenter; and move &kplayer; to the top of the list +for those file types that already had another program associated with them, +including the special types under the <literal>uri</literal> section. +Then you can simply click an <literal>http:</literal>, <literal>rtsp:</literal>, +<literal>pnm:</literal> or <literal>mms:</literal> link to your media, and +&kplayer; will start up and play it.</para> + +<para>If a stream has meta information embedded in it, &kplayer; will extract it +and display it in the <link linkend="parts-library">multimedia library</link>, +and if it finds the station name, it will also display it in the +<link linkend="parts-title-bar">title bar</link> and on the +<link linkend="parts-toolbar-playlist">current playlist</link>. Some music +streams also provide the name of the song currently being played. &kplayer; will +then display it in the title bar and on the current playlist instead of the +station name.</para> + +</sect2> + +<sect2 id="howto-streams-playlists"> +<title>Playlist files</title> + +<para>If the file a URL points to is a playlist, +<link linkend="howto-installation-mplayer">&mplayer;</link> needs a special +option to be able to play that file correctly. &kplayer; tries to detect +playlist files by looking at the file extension. If the extension is +<literal>ram</literal>, <literal>smi</literal>, <literal>smil</literal>, +<literal>rpm</literal>, <literal>asx</literal>, <literal>pls</literal>, +<literal>m3u</literal> or <literal>strm</literal>, and the protocol is +<literal>file</literal>, <literal>http</literal>, <literal>http_proxy</literal>, +<literal>ftp</literal> or <literal>smb</literal>, then &kplayer; passes the +playlist option to &mplayer;. But sometimes a playlist file may have a different +extension, or a file that is not a playlist may have one of those extensions. +In those cases playback will initially fail, and you will need to open the +<link linkend="properties-general">File Properties dialog</link> from the +<guimenu>File</guimenu> menu and set the <guilabel>Playlist</guilabel> option +correctly.</para> + +</sect2> + +<sect2 id="howto-streams-cache"> +<title>Cache size</title> + +<para>By default &kplayer; lets &mplayer; choose an optimal cache size, which +will work in almost all cases. But if you play a low bitrate media like a radio +station, it may take a while to fill the cache. In that case you can lower the +cache setting to 128 or even 64 kilobytes if &mplayer; does not do it +automatically. You can do that on the <guilabel>Advanced</guilabel> page for an +individual stream in the <link linkend="properties-advanced">File Properties +dialog</link>, or globally in <link linkend="settings-advanced">&kplayer; +Settings</link>. Alternatively, you can set a lower minimum cache size required +to start playback, the default one being 20%. That setting goes into the +<guilabel>Additional command line parameters</guilabel> field on the same +<guilabel>Advanced</guilabel> page, for example +<literal>-cache-min 5</literal>.</para> + +</sect2> + +<sect2 id="howto-streams-embedded"> +<title>Embedded streams</title> + +<para>A lot of times a media stream will be embedded as an object into a web +page. &kplayer; supports that and will play the stream if it is configured as +the default player for that media type. But it is recommended that you right +click on the web page object and choose <guimenuitem>Start +&kplayer;</guimenuitem>. You will then get better interface and more +options.</para> + +</sect2> + +<sect2 id="howto-streams-slaves"> +<title>Playing through HTTP I/O Slave</title> + +<para>In &mplayer; 1.0-pre4 there was a bug that made it impossible to play +<acronym>HTTP</acronym> <acronym>URL</acronym>s that had <acronym>URL</acronym> +encodable characters like a space in them. For those <acronym>URL</acronym>s +you can turn on the <guilabel>Use KIOSlave</guilabel> option in the +<link linkend="properties-advanced">File Properties</link>. &kplayer; will then +use the <acronym>HTTP</acronym> <acronym>I/O</acronym> Slave to play the file, +sending data to &mplayer; through a named pipe.</para> + +</sect2> + +<sect2 id="howto-streams-finding"> +<title>Where to find stations</title> + +<para>There is no single best resource for finding online radio and TV stations. +<ulink url="http://www.vtuner.com/">VTuner</ulink> online directory is pretty +good but not very complete. +<ulink url="http://www.radios.com.br/">Radios.com.br</ulink> is rather spammy +but more complete, their directory of online +<ulink url="http://www.radios.com.br/novo/tvs.htm">TV</ulink> and +<ulink url="http://www.radios.com.br/novo/inter.htm">radio</ulink> stations from +all over the world probably is the most complete on the Internet today. Finally, +<ulink url="http://www.tvradioworld.com/">TVRadioWorld</ulink> is an excellent +resource for finding on-the-air <acronym>TV</acronym> and radio stations (online +or not), and it links to online streams for some of them.</para> + +</sect2> + +<sect2 id="howto-streams-recording"> +<title>Recording streams</title> + +<para>Open <menuchoice><guimenu>File</guimenu> +<guimenuitem>Properties</guimenuitem></menuchoice> for the stream you want to +record, go to the +<link linkend="properties-advanced">Advanced page</link> and enter +<option>-dumpstream</option> into the <guilabel>Additional command line +arguments</guilabel> field. Then start playing the stream. +A <filename>stream.dump</filename> file will then be created in the current +directory. You can later rename it with the correct extension. Or add +<userinput><option>-dumpfile</option> +<filename><replaceable>filename.ext</replaceable></filename></userinput> to the +same <guilabel>Additional command line arguments</guilabel> field. The option in +that field have to be separated with spaces, and the file name must not have +spaces in it.</para> + +</sect2> + +</sect1> diff --git a/doc/en/howto-subtitles.docbook b/doc/en/howto-subtitles.docbook new file mode 100644 index 0000000..42b1a3f --- /dev/null +++ b/doc/en/howto-subtitles.docbook @@ -0,0 +1,130 @@ +<sect1 id="howto-subtitles"> +<title>Subtitles</title> + +<sect2 id="howto-subtitles-internal"> +<title>Embedded subtitles</title> + +<para>Some file types like Ogg or Matroska can have subtitles in them along with +audio and video. Often they have several internal subtitles, usually in +different languages. <acronym>DVD</acronym> video disks also often come with +subtitles on them. &kplayer; finds any of those subtitles and lists them on +the <link linkend="submenu-subtitles"><guisubmenu>Subtitles</guisubmenu> +submenu</link> of the <guimenu>Player</guimenu> menu. If the languages of the +subtitles are known, the entries on the submenu are labelled with the language +names.</para> + +<para>Selecting a subtitle track from the submenu displays the subtitles in the +<link linkend="parts-video-area">video area</link>. The +<guimenuitem>None</guimenuitem> option disables subtitle display for the current +file, title, track or stream. &kplayer; remembers the subtitle selection and +displays the same subtitles the next time you play the file. The <link +linkend="properties-subtitles"><guilabel>Subtitles</guilabel> section</link> of +the <guilabel>File Properties</guilabel> is another place where you can see and +select the subtitle track to be displayed when playing a video.</para> + +</sect2> + +<sect2 id="howto-subtitles-external"> +<title>External subtitles</title> + +<para>To load subtitles from a separate file or files, choose +<menuchoice><guimenu>File</guimenu><guimenuitem>Load Subtitles...</guimenuitem> +</menuchoice>. &kplayer; will display subtitles from the first of the loaded +files in the <link linkend="parts-video-area">video area</link> if the video is +playing or the next time you play it. You can also drag and drop subtitle files +from &konqueror; File Manager and drop them anywhere in &kplayer; except the +<interface>multimedia library</interface> to load and display them.</para> + +<para>The <link linkend="submenu-subtitles"><guisubmenu>Subtitles</guisubmenu> +submenu</link> of the <guimenu>Player</guimenu> menu shows the name of the +loaded external subtitle file along with any internal subtitle tracks and the +<guimenuitem>None</guimenuitem> option as described above. You can freely switch +between all the available subtitles. &kplayer; will display the ones you choose +without any interruption in video and audio playback. It will also remember your +choice and load the subtitles again the next time you play the same file or +<acronym>URL</acronym>.</para> + +<para>The <link linkend="properties-subtitles"><guilabel>Subtitles</guilabel> +section</link> of the <guilabel>File Properties</guilabel> also shows and lets +you change the external subtitle path. In some cases you may also need to tell +&kplayer; if they are VobSub or normal subtitles. This happens when you choose +the <filename>.sub</filename> file when loading VobSub subtitles. Pointing +&kplayer; to the <filename>.idx</filename> or <filename>.ifo</filename> file +should allow it to display the VobSub subtitles correctly without the need to +specify the external subtitle type explicitly.</para> + +</sect2> + +<sect2 id="howto-subtitles-autoloading"> +<title>Autoloading</title> + +<para>You can also let &kplayer; load subtitles automatically by placing them +in the same directory as the movie and giving them the same name as the movie +and the correct subtitle extension. For example, if you play a file called +<filename><replaceable>Carandiru.avi</replaceable></filename>, and you have +<literal>srt</literal> subtitles for it, you can name the subtitle file +<filename><replaceable>Carandiru.srt</replaceable></filename>, +<filename><replaceable>Carandiru.SRT</replaceable></filename>, +<filename><replaceable>Carandiru.avi.srt</replaceable></filename> or +<filename><replaceable>Carandiru.avi.SRT</replaceable></filename>.</para> + +<para>&kplayer; will autoload subtitle types you choose on the +<link linkend="settings-subtitles">Subtitles page</link> in <guilabel>&kplayer; +Settings</guilabel>. Autoloading only works for local files, and &kplayer; will +not remember autoloaded subtitles, rather it will autoload them every +time.</para> + +</sect2> + +<sect2 id="howto-subtitles-settings"> +<title>Subtitle settings</title> + +<para>The <link linkend="settings-subtitles"><guilabel>Subtitles</guilabel> +section</link> of the <guilabel>&kplayer; Settings</guilabel> dialog allows you +to customize the way subtitles are displayed in the +<link linkend="parts-video-area">video area</link>. You can select the font +face, bold and italic style, text size and autoscaling, font outline and text +width.</para> + +<para>There is also an option to add black areas below and above the video and +show the subtitles in them. That only works when the video aspect ratio is +greater than the one you choose. Normally you should choose the aspect ratio to +match your monitor, which is <guilabel>4:3</guilabel> for a regular monitor or +<guilabel>16:9</guilabel> for a wide one.</para> + +<para>Another important option is the subtitle encoding. You may need to select +it if &mplayer; does not display your subtitles correctly. If most of your +subtitle files have the same encoding, you can select it in <link +linkend="settings-subtitles"><guilabel>&kplayer; Settings</guilabel></link>. +But if some of them have different encoding, go to the <link +linkend="properties-subtitles"><guilabel>Subtitles</guilabel> section</link> of +the <guilabel>File Properties</guilabel> and select the encoding there. If the +framerate of the subtitles is different from the framerate of the video, you can +specify the subtitle framerate in the +<link linkend="properties-subtitles"><guilabel>File Properties</guilabel></link> +as well.</para> + +<para>The vertical position of the subtitles and their delay relative to video +can be changed using commands on the +<link linkend="submenu-subtitles"><guisubmenu>Subtitles</guisubmenu> +submenu</link> of the <guimenu>Player</guimenu> menu. As usual, using keyboard +shortcuts is recommended. By default &kplayer; will remember the subtitle delay +for each file or <acronym>URL</acronym>, and will keep the vertical position +across files. This can be changed on the +<link linkend="settings-controls">Controls page</link> in <guilabel>&kplayer; +Settings</guilabel>.</para> + +</sect2> + +<sect2 id="howto-subtitles-finding"> +<title>Finding subtitles</title> + +<para>There are a few good places for finding subtitles on the Net, among them +<ulink url="http://titles.box.sk/">Titles.box.sk</ulink>, +<ulink url="http://www.opensubtitles.org/">OpenSubtitles.org</ulink> and +<ulink url="http://www.divxsubtitles.net/">DivXSubtitles.net</ulink>. +Make sure to enable popup blocking before going to those sites though.</para> + +</sect2> + +</sect1> diff --git a/doc/en/howto-translation.docbook b/doc/en/howto-translation.docbook new file mode 100644 index 0000000..5622813 --- /dev/null +++ b/doc/en/howto-translation.docbook @@ -0,0 +1,76 @@ +<sect1 id="howto-translation"> +<title>Translation</title> + +<sect2 id="howto-translation-interface"> +<title>Translating the user interface</title> + +<para>If &kplayer; is not yet translated into your language and you want to make +a translation, first find out what is the abbreviated code for your language by +looking in the <ulink url="http://i18n.kde.org/teams/">list of &kde; +languages</ulink> for your language code. For example the code for Portuguese +is <literal>pt</literal>.</para> + +<para>Next look at the +<ulink url="http://cvs.sourceforge.net/viewcvs.py/kplayer/kplayer/po/">list of +existing &kplayer; translations</ulink> to see if the file for your translation +already exists. For example an Italian translation file +<filename>it.po</filename> does exist, which means that someone already did at +least part of the job. If so, download the latest version of the file and see if +it needs some work.</para> + +<para>If the file does not exist, download the +<ulink url="http://cvs.sourceforge.net/viewcvs.py/kplayer/kplayer/po/kplayer.pot?rev=HEAD">latest +<filename>kplayer.pot</filename> file</ulink> and rename it with your language +code and the <literal>.po</literal> extension. For example a Portuguese +translation file will be called <filename>pt.po</filename>. If there already +is a translation to a language that is close to yours, you can use that as a +template instead.</para> + +<para><ulink url="http://i18n.kde.org/tools/kbabel/">&kbabel;</ulink> is a great +&kde; program for translating <literal>.po</literal> files. Once you are done, +send your translation to +<ulink url="http://kplayer.sourceforge.net/email.html">kiriuja</ulink>.</para> + +</sect2> + +<sect2 id="howto-translation-manual"> +<title>Translating the user manual</title> + +<para>Go to the <ulink +url="http://cvs.sourceforge.net/viewcvs.py/kplayer/kplayer/doc/">&kplayer; +documentation directory</ulink> and look for a subdirectory for your language +code. If you find it, get the latest versions of all <literal>.po</literal> +files from it and see if they have any untranslated text.</para> + +<para>If the subdirectory for your language code does not exist, go to the <ulink +url="http://cvs.sourceforge.net/viewcvs.py/kplayer/kplayer/doc/templates/"><filename>templates</filename> +subdirectory</ulink>, download the latest versions of all +<literal>.pot</literal> files from it, open each one of them in &kbabel;, +translate and save with the <literal>.po</literal> extension.</para> + +<para>When you are done translating all the files, send the finished translation +to <ulink url="http://kplayer.sourceforge.net/email.html">kiriuja</ulink>.</para> + +<important><para>Do not translate the <literal>.docbook</literal> files +directly. Such translation is very difficult to maintain, and therefore will not +be accepted.</para></important> + +</sect2> + +<sect2 id="howto-translation-desktop"> +<title>Translating the .desktop files</title> + +<para>Action names and comments in the <literal>.desktop</literal> files that +come with &kplayer; are also translatable. The translations go into the files +themselves. Open the files with a <acronym>UTF</acronym> capable text editor and +translate the entries using the same format as the translations to other +languages in the same files and replacing the language code with the code for +your language. Keep in mind that the action names are verbs, for example +<guilabel>Queue</guilabel> means <quote>put in the queue</quote>. See the +section of this manual describing the +<link linkend="menu-library"><guimenu>Library</guimenu> menu</link> for details +about those actions.</para> + +</sect2> + +</sect1> 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> diff --git a/doc/en/howto.docbook b/doc/en/howto.docbook new file mode 100644 index 0000000..e434cf0 --- /dev/null +++ b/doc/en/howto.docbook @@ -0,0 +1,88 @@ +<chapter id="howto"> +<title>Micro-HOWTOs</title> + +<sect1 id="howto-overview"> +<title>Overview</title> + +<para>This chapter contains lots of useful information covering installation, +configuration and various uses of &kplayer;. Following is a list of the topics +covered.</para> + +<itemizedlist> + +<listitem><para><link linkend="howto-installation">Installation +micro-HOWTO</link> describes &kplayer; requirements, dependencies and +installation steps.</para></listitem> + +<listitem><para><link linkend="howto-compilation">Compilation micro-HOWTO</link> +gives quick instructions on compiling &kplayer; from source.</para></listitem> + +<listitem><para><link linkend="howto-configuration">Basic configuration +micro-HOWTO</link> gives some useful hints for optimal &kplayer; +setup.</para></listitem> + +<listitem><para><link linkend="howto-settings">Advanced configuration +micro-HOWTO</link> introduces some of the most useful &kplayer; +settings.</para></listitem> + +<listitem><para><link linkend="howto-properties">File properties +micro-HOWTO</link> explains the file properties feature in +detail.</para></listitem> + +<listitem><para><link linkend="howto-full-screen">Full screen and maximized +window micro-HOWTO</link> gives some tips on running &kplayer; full screen or +maximized.</para></listitem> + +<listitem><para><link linkend="howto-playlist">Playlist micro-HOWTO</link> +describes playlist support in &kplayer;.</para></listitem> + +<listitem><para><link linkend="howto-library">Multimedia library +micro-HOWTO</link> explains the multimedia library in detail.</para></listitem> + +<listitem><para><link linkend="howto-subtitles">Subtitles micro-HOWTO</link> +gives useful information on playing video with subtitles.</para></listitem> + +<listitem><para><link linkend="howto-devices">Devices micro-HOWTO</link> +provides details on how to play <acronym>DVD</acronym>, video +<acronym>CD</acronym>, audio <acronym>CD</acronym>, <acronym>TV</acronym> +and <acronym>DVB</acronym>.</para></listitem> + +<listitem><para><link linkend="howto-streams">Online radio and TV +micro-HOWTO</link> gives useful tips for playing online media.</para></listitem> + +<listitem><para><link linkend="howto-slaves">&kde; I/O Slaves micro-HOWTO</link> +gives details on playing files through &kde; <acronym>I/O</acronym> +Slaves.</para></listitem> + +<listitem><para><link linkend="howto-troubleshooting">Troubleshooting +micro-HOWTO</link> gives solutions for the most common +problems.</para></listitem> + +<listitem><para><link linkend="howto-bug-reporting">Bug reporting +micro-HOWTO</link> details the steps to make your bug report really +helpful.</para></listitem> + +<listitem><para><link linkend="howto-translation">Translation micro-HOWTO</link> +is a quick guide to help &kplayer; translators get going.</para></listitem> + +</itemizedlist> + +</sect1> + +&kplayer-howto-installation; +&kplayer-howto-compilation; +&kplayer-howto-configuration; +&kplayer-howto-settings; +&kplayer-howto-properties; +&kplayer-howto-full-screen; +&kplayer-howto-playlist; +&kplayer-howto-library; +&kplayer-howto-subtitles; +&kplayer-howto-devices; +&kplayer-howto-streams; +&kplayer-howto-slaves; +&kplayer-howto-troubleshooting; +&kplayer-howto-bug-reporting; +&kplayer-howto-translation; + +</chapter> diff --git a/doc/en/index.docbook b/doc/en/index.docbook new file mode 100644 index 0000000..3d4d95e --- /dev/null +++ b/doc/en/index.docbook @@ -0,0 +1,110 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kplayer "<application>KPlayer</application>"> + <!ENTITY mplayer "<application>MPlayer</application>"> + <!ENTITY mldonkey "<application>MLDonkey</application>"> + <!ENTITY kmldonkey "<application>KMLDonkey</application>"> + <!ENTITY kappname "&kplayer;"> + <!ENTITY kplayer-introduction SYSTEM "introduction.docbook"> + <!ENTITY kplayer-basics SYSTEM "basics.docbook"> + <!ENTITY kplayer-commands SYSTEM "commands.docbook"> + <!ENTITY kplayer-configuration SYSTEM "configuration.docbook"> + <!ENTITY kplayer-settings SYSTEM "settings.docbook"> + <!ENTITY kplayer-properties SYSTEM "properties.docbook"> + <!ENTITY kplayer-howto SYSTEM "howto.docbook"> + <!ENTITY kplayer-howto-installation SYSTEM "howto-installation.docbook"> + <!ENTITY kplayer-howto-compilation SYSTEM "howto-compilation.docbook"> + <!ENTITY kplayer-howto-configuration SYSTEM "howto-configuration.docbook"> + <!ENTITY kplayer-howto-settings SYSTEM "howto-settings.docbook"> + <!ENTITY kplayer-howto-properties SYSTEM "howto-properties.docbook"> + <!ENTITY kplayer-howto-full-screen SYSTEM "howto-full-screen.docbook"> + <!ENTITY kplayer-howto-bug-reporting SYSTEM "howto-bug-reporting.docbook"> + <!ENTITY kplayer-howto-playlist SYSTEM "howto-playlist.docbook"> + <!ENTITY kplayer-howto-library SYSTEM "howto-library.docbook"> + <!ENTITY kplayer-howto-subtitles SYSTEM "howto-subtitles.docbook"> + <!ENTITY kplayer-howto-devices SYSTEM "howto-devices.docbook"> + <!ENTITY kplayer-howto-streams SYSTEM "howto-streams.docbook"> + <!ENTITY kplayer-howto-slaves SYSTEM "howto-slaves.docbook"> + <!ENTITY kplayer-howto-translation SYSTEM "howto-translation.docbook"> + <!ENTITY kplayer-howto-troubleshooting SYSTEM "howto-troubleshooting.docbook"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> + <!ENTITY % addindex "IGNORE"> +]> + +<book lang="&language;"> + +<bookinfo> +<title>&kplayer; user manual</title> + +<copyright> +<year>2004-2007</year> +<holder>kiriuja</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2007-05-13</date> +<releaseinfo>0.6.2</releaseinfo> + +<abstract> +<para><ulink url="http://kplayer.sourceforge.net/">&kplayer;</ulink> is a &kde; +multimedia player that uses the +<ulink url="http://www.mplayerhq.hu/">&mplayer;</ulink> engine.</para> + +<para>If you are having problems with &kplayer;, please have a look at the +<link linkend="howto-troubleshooting">Troubleshooting micro-HOWTO</link>.</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>kdemultimedia</keyword> +<keyword>KPlayer</keyword> +<keyword>MPlayer</keyword> +<keyword>multimedia</keyword> +<keyword>media</keyword> +<keyword>video</keyword> +<keyword>movie</keyword> +<keyword>audio</keyword> +<keyword>sound</keyword> +<keyword>music</keyword> +<keyword>player</keyword> +<keyword>subtitles</keyword> +</keywordset> + +</bookinfo> + +&kplayer-introduction; +&kplayer-basics; +&kplayer-commands; +&kplayer-configuration; +&kplayer-settings; +&kplayer-properties; +&kplayer-howto; + +<chapter id="credits"> + +<title>Credits and License</title> + +<para> +&kplayer; +</para> +<para> +Program copyright 2002-2007 kiriuja (<ulink url="http://kplayer.sourceforge.net/email.html">e-mail</ulink>) +</para> +<para> +Documentation copyright 2002-2007 kiriuja (<ulink url="http://kplayer.sourceforge.net/email.html">e-mail</ulink>) +</para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; <!-- FDL: do not remove --> + +</chapter> + +&documentation.index; + +</book> + +<!-- +vim:tabstop=2:shiftwidth=2:expandtab +--> diff --git a/doc/en/introduction.docbook b/doc/en/introduction.docbook new file mode 100644 index 0000000..cd445ca --- /dev/null +++ b/doc/en/introduction.docbook @@ -0,0 +1,31 @@ +<chapter id="introduction"> +<title>Overview</title> + +<para>&kplayer; is a multimedia player for the K Desktop Environment.</para> + +<para>&kplayer; uses <ulink url="http://www.mplayerhq.hu/">&mplayer;</ulink> as +the media playing backend, and therefore offers the best playback quality and +performance and the widest variety of supported video, audio and subtitle +formats, input methods and output options. Specifically, &mplayer; supports +<link linkend="playing">playing</link> from local files, +<acronym>DVD</acronym>s, video <acronym>CD</acronym>s, audio +<acronym>CD</acronym>s, <acronym>TV</acronym> and <acronym>DVB</acronym> cards, +as well as network locations using many types of protocols.</para> + +<para>However, &kplayer; is much more that just an &mplayer; frontend. In +addition to &kde; integration and an easy to use interface that follows &kde; +standards, it offers a <link linkend="howto-library">multimedia library</link>, +<link linkend="howto-playlist">playlist</link> support, many additional input +methods using <link linkend="howto-slaves">&kde; I/O Slaves</link>, and last but +not least the <link linkend="howto-properties">ability</link> to easily choose +many different options for each individual file or <acronym>URL</acronym>, +giving you flexibility not found in any other media player.</para> + +<para>&kplayer; is a fully customizable program that you can +<link linkend="configuration">configure</link> and fine tune for your system and +your personal preferences, from changing the way video is shown and sound is +played and setting any playback option &mplayer; understands to arranging the +player controls inside &kplayer; window, changing the buttons on the toolbars +and defining new shortcut key combinations.</para> + +</chapter> diff --git a/doc/en/message-log.png b/doc/en/message-log.png Binary files differnew file mode 100644 index 0000000..29e4066 --- /dev/null +++ b/doc/en/message-log.png diff --git a/doc/en/multimedia-library.png b/doc/en/multimedia-library.png Binary files differnew file mode 100644 index 0000000..fc80674 --- /dev/null +++ b/doc/en/multimedia-library.png diff --git a/doc/en/properties-advanced.png b/doc/en/properties-advanced.png Binary files differnew file mode 100644 index 0000000..fd3e291 --- /dev/null +++ b/doc/en/properties-advanced.png diff --git a/doc/en/properties-audio.png b/doc/en/properties-audio.png Binary files differnew file mode 100644 index 0000000..def1365 --- /dev/null +++ b/doc/en/properties-audio.png diff --git a/doc/en/properties-general.png b/doc/en/properties-general.png Binary files differnew file mode 100644 index 0000000..b193ad0 --- /dev/null +++ b/doc/en/properties-general.png diff --git a/doc/en/properties-size.png b/doc/en/properties-size.png Binary files differnew file mode 100644 index 0000000..5520399 --- /dev/null +++ b/doc/en/properties-size.png diff --git a/doc/en/properties-subtitles.png b/doc/en/properties-subtitles.png Binary files differnew file mode 100644 index 0000000..ab55f5d --- /dev/null +++ b/doc/en/properties-subtitles.png diff --git a/doc/en/properties-video.png b/doc/en/properties-video.png Binary files differnew file mode 100644 index 0000000..91aed43 --- /dev/null +++ b/doc/en/properties-video.png diff --git a/doc/en/properties.docbook b/doc/en/properties.docbook new file mode 100644 index 0000000..143ba79 --- /dev/null +++ b/doc/en/properties.docbook @@ -0,0 +1,883 @@ +<chapter id="properties"> +<title>File properties</title> + +<sect1 id="properties-overview"> +<title>Overview</title> + +<para>The <guilabel>File Properties</guilabel> dialog allows you to choose +various options that will apply only to a particular file, stream, device, +track, title, or channel. Many of the options are the same or similar to the +ones that can be chosen globally in the <link linkend="settings">&kplayer; +Settings</link> dialog. The options set in file properties will override the +global ones. Additionally, options set for a track, title or channel will +override options set for the disk or device it comes from. The file properties +give you full control of how the file is played, including options that are +passed to &mplayer;. Other properties display information that &kplayer; found +out about the file or stream, like time length, video size, and audio and video +bitrates.</para> + +<para>Select <menuchoice><guimenu>File</guimenu> +<guimenuitem>Properties...</guimenuitem></menuchoice> to open the dialog +box for the currently loaded file or <acronym>URL</acronym>. You can also open +the properties for any item in the <link linkend="parts-library">multimedia +library</link> by <mousebutton>right</mousebutton> clicking the item and +selecting <guimenuitem>Properties...</guimenuitem> from the +<link linkend="popup-library">library popup menu</link> or by selecting +<menuchoice><guimenu>Library</guimenu><guimenuitem>Properties...</guimenuitem> +</menuchoice>.</para> + +<para>The dialog contains several sections which are selected by +<mousebutton>left</mousebutton> clicking one of the items on the +left side of the dialog box.</para> + +<variablelist> + +<varlistentry> +<term><link linkend="properties-general">General</link> section</term> +<listitem><para>Shows general information about the multimedia item and lets you +set a few essential properties.</para></listitem> +</varlistentry> + +<varlistentry> +<term><link linkend="properties-size">Size</link> section</term> +<listitem><para>If the file or stream contains video, tells you the video +resolution and lets you control the video area size when playing +it.</para></listitem> +</varlistentry> + +<varlistentry> +<term><link linkend="properties-video">Video</link> section</term> +<listitem><para>Contains properties that show technical information about +the video and let you control video output when playing the file, if it has +a video component.</para></listitem> +</varlistentry> + +<varlistentry> +<term><link linkend="properties-audio">Audio</link> section</term> +<listitem><para>Contains properties that show technical information about +the audio and let you control audio output when playing the file, if it has +an audio component.</para></listitem> +</varlistentry> + +<varlistentry> +<term><link linkend="properties-subtitles">Subtitles</link> section</term> +<listitem><para>Contains properties that control subtitle loading and +display, if the file is played with subtitles.</para></listitem> +</varlistentry> + +<varlistentry> +<term><link linkend="properties-advanced">Advanced</link> section</term> +<listitem><para>Contains various properties that affect advanced command +line parameters passed to &mplayer;, as well as interaction with the &kde; +I/O Slave if it is used to transfer the file.</para></listitem> +</varlistentry> + +</variablelist> + +<para>The buttons at the bottom of the dialog let you make choices +about the contents of all sections of the dialog.</para> + +<variablelist> + +<varlistentry> +<term><guibutton>OK</guibutton> button</term> +<listitem><para>Accepts your changes and closes the dialog.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Cancel</guibutton> button</term> +<listitem><para>Closes the dialog without saving the changes.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Apply</guibutton> button</term> +<listitem><para>Applies the changes without closing the dialog.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Defaults</guibutton> button</term> +<listitem><para>Restores all settings to their original, predefined values +and applies them.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Close</guibutton> button</term> +<listitem><para>After you choose <guibutton>Apply</guibutton> or +<guibutton>Defaults</guibutton>, the <guibutton>Cancel</guibutton> button +changes to <guibutton>Close</guibutton>. Clicking it closes the dialog +and discards changes you made since the last time changes were +applied.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Help</guibutton> button</term> +<listitem><para>Opens this user manual and displays the section that describes +the currently selected section of the dialog.</para></listitem> +</varlistentry> + +</variablelist> + +<note><para>You can also click the small <guibutton>What's This</guibutton> +button with a question mark at the top right of the dialog and then click a +property to get a brief explanation of it.</para></note> + +<para>Clicking the rightmost button at the top of the dialog closes the dialog +discarding any unapplied changes.</para> + +</sect1> + +<sect1 id="properties-general"> +<title><guilabel>General</guilabel> section</title> + +<para>This section shows general information about the multimedia item and lets +you set a few essential properties.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="properties-general.png" format="PNG"/> +</imageobject> +</mediaobject> + +<variablelist> + +<varlistentry> +<term><guilabel>Name</guilabel></term> + +<listitem><para>This property shows and lets you change the name of the item +that is displayed in the <link linkend="parts-toolbar-playlist">playlist drop +down box</link>, the <link linkend="parts-library">multimedia library</link>, +and also in the &kplayer; title bar when the item is loaded for +playing.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Path or URL</guilabel></term> + +<listitem><para>This property shows the file path for local files or the full +<acronym>URL</acronym> for all other files. The <acronym>URL</acronym> +identifies the file or stream, and all other properties are attached to it. +This property is read only. It is not applicable and not shown for +<acronym>CD</acronym> tracks, <acronym>DVD</acronym> titles and tuner device +channels.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Type</guilabel></term> + +<listitem><para>This property shows the type of the multimedia item. For a +device, track, title or channel it is the device type. For other items it is the +<acronym>MIME</acronym> type if it is known. This property is read +only.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Playlist</guilabel></term> + +<listitem><para>This property shows and lets you choose whether this item +is a playlist file. &mplayer; cannot automatically detect and play a playlist +file, so &kplayer; has to explicitly tell it to parse a file as a playlist. +<guilabel>Auto</guilabel> lets &kplayer; use the file extension to guess +if it is a playlist file. The playlist extensions KPlayer recognizes are ram, +rpm, smi, smil, asx, m3u, pls and strm. If a file that is not a playlist has +one of these extensions, or a playlist file has a different extension, you +will need to correctly set this property in order to be able to play the file +or stream.</para> + +<para>This property is not applicable and not shown for devices, disks, titles, +tracks and channels.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Length</guilabel></term> + +<listitem><para>This property shows the time length of the file. +&kplayer; tries to detect it with precision of one tenth of a second, +and usually it gets it pretty close to the real length. This property +is read only. It is not applicable and not shown for devices and +channels.</para></listitem> +</varlistentry> + +</variablelist> + +<para>Tuner <link linkend="howto-devices">devices</link> like +<acronym>DVB</acronym>, <acronym>PVR</acronym> and <acronym>TV</acronym> and +channels available on them have some specific properties that are not applicable +to other items.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="device-properties-general.png" format="PNG"/> +</imageobject> +</mediaobject> + +<variablelist> + +<varlistentry> +<term><guilabel>Frequency</guilabel></term> + +<listitem><para>This property shows and lets you change the frequency in +<acronym>MHz</acronym> of a <acronym>DVB</acronym>, <acronym>PVR</acronym> or +<acronym>TV</acronym> channel. For other items this property is not applicable +and not shown.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Channels</guilabel></term> + +<listitem><para>This property shows and lets you choose the list of channels +available on a <acronym>TV</acronym> or <acronym>PVR</acronym> device. For other +items this property is not applicable and not shown.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Driver</guilabel></term> + +<listitem><para>This property shows and lets you choose the input driver for a +<acronym>TV</acronym> or <acronym>PVR</acronym> device. For other items this +property is not applicable and not shown.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Channel file</guilabel></term> + +<listitem><para>This property shows and lets you change the path to a file +listing the available channels on a <acronym>DVB</acronym> device and their +properties. For other items this property is not applicable and not +shown.</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="properties-size"> +<title><guilabel>Size</guilabel> section</title> + +<para>This section shows the video resolution and lets you control the +<link linkend="parts-video-area">video area</link> size when playing this file, +if it has video.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="properties-size.png" format="PNG"/> +</imageobject> +</mediaobject> + +<variablelist> + +<varlistentry> +<term><guilabel>Resolution</guilabel></term> + +<listitem><para>This property shows the resolution of the video in pixels. +It is read only, and it is empty for audio only files.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Original size</guilabel></term> + +<listitem><para>This property shows the original size of the video in pixels. +Original video size is the video resolution adjusted to the correct aspect +ratio. It is read only, and it is empty for audio only files.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Current size</guilabel></term> + +<listitem><para>This property shows the current size of the video in pixels. +Current video size is the video size after application of any filters. It is +read only, and it is empty for audio only files.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Display size</guilabel></term> + +<listitem><para>This property lets you choose the initial video size &kplayer; +will use when it starts playing the file, unless you turned off the option to +<guilabel>Resize main window automatically</guilabel> on the +<link linkend="settings-general"><guilabel>General</guilabel> page</link> in +<guilabel>&kplayer; Settings</guilabel>. The <guilabel>auto</guilabel> setting +will use the <guilabel>Minimum initial video width</guilabel> option from the +<guilabel>General</guilabel> settings. The <guilabel>set size</guilabel> setting +will use the fixed initial size you specify. The <guilabel>set aspect</guilabel> +setting will again use the <guilabel>Minimum initial video width</guilabel> +option, but will apply the fixed initial aspect you specify.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Full screen</guilabel></term> + +<listitem><para>This property lets you choose the full screen mode when playing +this file. The <guilabel>default</guilabel> setting will keep the full screen +mode of the previous file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Maximized</guilabel></term> + +<listitem><para>This property lets you choose the maximized window state when +this file is not played full screen. The <guilabel>default</guilabel> setting +will keep the maximized state of the previous file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Maintain aspect</guilabel></term> + +<listitem><para>This property lets you choose the <guilabel>Maintain +Aspect</guilabel> option specifically for this file. The +<guilabel>default</guilabel> setting will keep the <guilabel>Maintain +Aspect</guilabel> setting you choose globally.</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="properties-video"> +<title><guilabel>Video</guilabel> section</title> + +<para>This section contains properties that show technical information about +the video and let you control video output when playing the file, if it has +a video component.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="properties-video.png" format="PNG"/> +</imageobject> +</mediaobject> + +<variablelist> + +<varlistentry> +<term><guilabel>Track</guilabel></term> + +<listitem><para>This property lets you choose the video track to use when +playing this file or stream. The <guilabel>auto</guilabel> option lets &mplayer; +choose a video track automatically. The <guilabel>set ID</guilabel> option +allows you to enter a video track ID to play. The other options choose a video +track from the list of detected tracks. An easy way to set this property for a +file or stream that has more than one video track is by selecting a video track +from the <link linkend="submenu-video"><guisubmenu>Video</guisubmenu> +submenu</link> of the <guimenu>Player</guimenu> menu.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Contrast</guilabel></term> + +<listitem><para>This property controls the video contrast for this file. +The <guilabel>default</guilabel> option uses the same contrast as for other +files. The <guilabel>set to</guilabel> option sets the specified initial +contrast when loading the file. The <guilabel>add</guilabel> and +<guilabel>subtract</guilabel> settings will adjust the contrast relative +to the default setting.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Brightness</guilabel></term> + +<listitem><para>This property controls the video brightness for this file. +The <guilabel>default</guilabel> option uses the same brightness as for other +files. The <guilabel>set to</guilabel> option sets the specified initial +brightness when loading the file. The <guilabel>add</guilabel> and +<guilabel>subtract</guilabel> settings will adjust the brightness relative +to the default setting.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Hue</guilabel></term> + +<listitem><para>This property controls the video hue for this file. +The <guilabel>default</guilabel> option uses the same hue as for other +files. The <guilabel>set to</guilabel> option sets the specified initial +hue when loading the file. The <guilabel>add</guilabel> and +<guilabel>subtract</guilabel> settings will adjust the hue relative +to the default setting.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Saturation</guilabel></term> + +<listitem><para>This property controls the video saturation for this file. +The <guilabel>default</guilabel> option uses the same saturation as for other +files. The <guilabel>set to</guilabel> option sets the specified initial +saturation when loading the file. The <guilabel>add</guilabel> and +<guilabel>subtract</guilabel> settings will adjust the saturation relative +to the default setting.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Codec</guilabel></term> + +<listitem><para>This property specifies the video codec to use when playing this +file. The <guilabel>default</guilabel> setting will use the codec chosen on the +<link linkend="settings-video"><guilabel>Video</guilabel> page</link> in +<guilabel>&kplayer; Settings</guilabel>, normally <guilabel>auto</guilabel>. The +<guilabel>auto</guilabel> setting will tell &mplayer; to choose the codec it +thinks is the best for playing this file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Bitrate</guilabel></term> + +<listitem><para>This property shows the video bitrate of this file. +It is read only, and it is empty for audio only files.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Framerate</guilabel></term> + +<listitem><para>This property shows the video framerate of this file. +It is read only, and it is empty for audio only files.</para></listitem> +</varlistentry> + +</variablelist> + +<para>Tuner <link linkend="howto-devices">devices</link> like +<acronym>DVB</acronym>, <acronym>PVR</acronym> and <acronym>TV</acronym> have +some specific properties that are not applicable to other items.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="device-properties-video.png" format="PNG"/> +</imageobject> +</mediaobject> + +<variablelist> + +<varlistentry> +<term><guilabel>Input</guilabel></term> + +<listitem><para>This property lets you choose the video input to use when +playing from the tuner device. The <guilabel>auto</guilabel> option tells +&mplayer; to choose a <acronym>TV</acronym> or <acronym>DVB</acronym> input +automatically. The <guilabel>set to</guilabel> option allows you to enter an +input ID to be used. For other items this property is not applicable and not +shown.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Format</guilabel></term> + +<listitem><para>This property lets you choose the video format to use when +playing from the <acronym>PVR</acronym> or <acronym>TV</acronym> device. The +<guilabel>auto</guilabel> option tells &mplayer; to choose a video output format +automatically. The other options let you specify a particular video format. +For other items this property is not applicable and not shown.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Norm</guilabel></term> + +<listitem><para>This property lets you choose the video norm to use when +playing from the <acronym>PVR</acronym> or <acronym>TV</acronym> device. +The <guilabel>auto</guilabel> option tells &mplayer; to choose a video norm +automatically. The <guilabel>set ID</guilabel> option allows you to enter a norm +ID to be used. The other options let you choose a particular video norm. For +other items this property is not applicable and not shown.</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="properties-audio"> +<title><guilabel>Audio</guilabel> section</title> + +<para>This section contains properties that show technical information about +the audio and let you control audio output when playing the file, if it has +an audio component.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="properties-audio.png" format="PNG"/> +</imageobject> +</mediaobject> + +<variablelist> + +<varlistentry> +<term><guilabel>Track</guilabel></term> + +<listitem><para>This property lets you choose the audio track to use when +playing this file or stream. The <guilabel>auto</guilabel> option lets &mplayer; +choose an audio track automatically. The <guilabel>set ID</guilabel> option +allows you to enter a audio track ID to play. The other options choose an audio +track from the list of detected tracks. An easy way to set this property for a +file or stream that has more than one audio track is by selecting an audio track +from the <link linkend="submenu-audio"><guisubmenu>Audio</guisubmenu> +submenu</link> of the <guimenu>Player</guimenu> menu.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Volume</guilabel></term> + +<listitem><para>This property controls the sound volume for this file. +The <guilabel>default</guilabel> option uses the same volume as for other +files. The <guilabel>set to</guilabel> option sets the specified initial +volume when loading the file. The <guilabel>add</guilabel> and +<guilabel>subtract</guilabel> settings will adjust the volume relative +to the default setting.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Delay</guilabel></term> + +<listitem><para>This property controls delay of the sound relative to video. +By default this property is remembered automatically when you use the +<guimenuitem>Increase Delay</guimenuitem> and <guimenuitem>Decrease +Delay</guimenuitem> commands from the +<link linkend="submenu-audio"><guisubmenu>Audio</guisubmenu> submenu</link> +of the <guimenu>Player</guimenu> menu. The <guilabel>default</guilabel> +setting always resets audio delay to zero when the file is +loaded.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Codec</guilabel></term> + +<listitem><para>This property specifies the audio codec to use when playing this +file. The <guilabel>default</guilabel> setting will use the codec chosen on the +<link linkend="settings-audio"><guilabel>Audio</guilabel> page</link> in +<guilabel>&kplayer; Settings</guilabel>, normally <guilabel>auto</guilabel>. The +<guilabel>auto</guilabel> setting will tell &mplayer; to choose the codec it +thinks is the best for playing this file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Bitrate</guilabel></term> + +<listitem><para>This property shows the audio bitrate of this file. It is +read only, and it is empty for files without an audio track.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Samplerate</guilabel></term> + +<listitem><para>This property shows the audio samplerate of this file. It is +read only, and it is empty for files without an audio track.</para></listitem> +</varlistentry> + +</variablelist> + +<para>Tuner <link linkend="howto-devices">devices</link> like +<acronym>DVB</acronym>, <acronym>PVR</acronym> and <acronym>TV</acronym> have +some specific properties that are not applicable to other items.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="device-properties-audio.png" format="PNG"/> +</imageobject> +</mediaobject> + +<variablelist> + +<varlistentry> +<term><guilabel>Mode</guilabel></term> + +<listitem><para>This property lets you choose the audio mode to use when +playing from the <acronym>PVR</acronym> or <acronym>TV</acronym> device. +The <guilabel>auto</guilabel> option tells &mplayer; to choose an audio mode +automatically. The other options let you specify a particular audio mode. +For other items this property is not applicable and not shown.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Input</guilabel></term> + +<listitem><para>This property lets you choose the audio input to use when +playing from the tuner device. The <guilabel>auto</guilabel> option tells +&mplayer; to choose a <acronym>TV</acronym> or <acronym>DVB</acronym> audio +input automatically. The <guilabel>set to</guilabel> option allows you to enter +an input ID to be used. For other items this property is not applicable and not +shown.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Immediate mode</guilabel></term> + +<listitem><para>This property lets you choose the immediate mode for playing +from the <acronym>PVR</acronym> or <acronym>TV</acronym> device. When disabled, +&mplayer; will capture audio from the same device as video. When enabled, tells +&mplayer; to capture audio through a cable going from the <acronym>TV</acronym> +card to the sound card. For other items this property is not applicable and not +shown.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Capture</guilabel></term> + +<listitem><para>This property lets you choose the audio capture system, either +<acronym>ALSA</acronym> or <acronym>OSS</acronym>, for playing from the +<acronym>PVR</acronym> or <acronym>TV</acronym> device. For other items this +property is not applicable and not shown.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Capture device</guilabel></term> + +<listitem><para>This property lets you specify the audio capture device for +playing from the <acronym>PVR</acronym> or <acronym>TV</acronym> device. For +other items this property is not applicable and not shown.</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="properties-subtitles"> +<title><guilabel>Subtitles</guilabel> section</title> + +<para>This section contains properties that control subtitle loading and +display, if the file is played with subtitles.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="properties-subtitles.png" format="PNG"/> +</imageobject> +</mediaobject> + +<variablelist> + +<varlistentry> +<term><guilabel>Track</guilabel></term> + +<listitem><para>This property lets you choose the subtitles to use when playing +this file or stream. The <guilabel>none</guilabel> option disables subtitle +display. The <guilabel>external</guilabel> option tells &mplayer; to display +subtitles loaded from an external file given by the <guilabel>External +path</guilabel> property below. The <guilabel>set ID</guilabel> option allows +you to enter an internal subtitle track ID to play. The other options choose an +internal subtitle track from the list of detected tracks. An easy way to set +this property is by selecting a subtitle track or file or the +<guimenuitem>None</guimenuitem> option from the +<link linkend="submenu-subtitles"><guisubmenu>Subtitles</guisubmenu> +submenu</link> of the <guimenu>Player</guimenu> menu.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>External path</guilabel></term> + +<listitem><para>This property specifies the path to the external subtitle file +to be used for this file. This property is set automatically when you use the +<guimenuitem>Load Subtitles...</guimenuitem> command from the +<guimenu>File</guimenu> menu or drag and drop subtitle files onto the &kplayer; +window, and the <guilabel>Track</guilabel> property above is set to +<guilabel>external</guilabel>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>External type</guilabel></term> + +<listitem><para>This property allows you to specify the type of the external +subtitles. The <guilabel>auto</guilabel> option tells &kplayer; to determine +the type based on the subtitle file extension.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Encoding</guilabel></term> + +<listitem><para>This property lets you specify the encoding of text in the +external subtitle file. The <guilabel>default</guilabel> option tells &kplayer; +to use the encoding specified in +<link linkend="settings-subtitles"><guilabel>&kplayer; +Settings</guilabel></link>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Framerate</guilabel></term> + +<listitem><para>This property lets you specify the frame rate of the external +subtitle file. The <guilabel>auto</guilabel> option uses the frame rate of the +video file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Autoload</guilabel></term> + +<listitem><para>If this is a local file, this property tells &kplayer; whether +to try to autoload subtitles for it. The <guilabel>default</guilabel> setting +uses the <guilabel>Autoload</guilabel> settings from the +<link linkend="settings-subtitles"><guilabel>Subtitles</guilabel> page</link> +in <guilabel>&kplayer; Settings</guilabel>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Position</guilabel></term> + +<listitem><para>This property lets you set vertical position of subtitles. +The <guilabel>default</guilabel> setting will use the same subtitle position +as for other files. An easy way to set this property is by using keyboard +shortcuts for subtitle position commands on the +<link linkend="submenu-subtitles"><guisubmenu>Subtitles</guisubmenu> +submenu</link> of the <guimenu>Player</guimenu> menu while holding down the +&Shift; key.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Delay</guilabel></term> + +<listitem><para>This property controls delay of the subtitles relative to +video. By default this property is remembered automatically when you use +the <guimenuitem>Increase Delay</guimenuitem> and <guimenuitem>Decrease +Delay</guimenuitem> commands from the +<link linkend="submenu-subtitles"><guisubmenu>Subtitles</guisubmenu> +submenu</link> of the <guimenu>Player</guimenu> menu. The +<guilabel>default</guilabel> setting always resets subtitle delay to zero when +the file is loaded.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Closed caption</guilabel></term> + +<listitem><para>This property lets you choose to display or omit closed caption +subtitles on a specific device or disk or for each individual title on a +<acronym>DVD</acronym>. This property is not available for files or remote +streams.</para></listitem> +</varlistentry> + +</variablelist> + +<mediaobject> +<imageobject> +<imagedata fileref="device-properties-subtitles.png" format="PNG"/> +</imageobject> +</mediaobject> + +</sect1> + +<sect1 id="properties-advanced"> +<title><guilabel>Advanced</guilabel> section</title> + +<para>This section contains various properties that affect advanced command +line parameters passed to &mplayer;, as well as interaction with the &kde; +I/O Slave if it is used to transfer the file.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="properties-advanced.png" format="PNG"/> +</imageobject> +</mediaobject> + +<variablelist> + +<varlistentry> +<term><guilabel>Additional command line arguments</guilabel></term> + +<listitem><para>This property lets you specify additional arguments to be +passed to &mplayer;. You can either <guilabel>append</guilabel> the arguments +to the ones given on the +<link linkend="settings-advanced"><guilabel>Advanced</guilabel></link> page in +<guilabel>&kplayer; Settings</guilabel> or use the <guilabel>set to</guilabel> +setting to override them. The <guilabel>default</guilabel> option uses the +arguments given in <guilabel>&kplayer; Settings</guilabel>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Demuxer</guilabel></term> + +<listitem><para>This property specifies the demultiplexer to use when playing +this file. The <guilabel>default</guilabel> setting will use the demuxer chosen +on the <link linkend="settings-advanced"><guilabel>Advanced</guilabel> +page</link> in <guilabel>&kplayer; Settings</guilabel>, normally +<guilabel>auto</guilabel>. The <guilabel>auto</guilabel> setting will tell +&mplayer; to choose the demuxer it thinks is the best for playing this +file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Frame drop</guilabel></term> + +<listitem><para>This property allows you to tell &mplayer; to drop some frames +if your system is too slow to play the file properly. +The <guilabel>soft</guilabel> setting drops less frames than +the <guilabel>hard</guilabel> one, so you should try it first. +The <guilabel>default</guilabel> option uses the <guilabel>Frame drop</guilabel> +setting from the <link linkend="settings-advanced"><guilabel>Advanced</guilabel> +page</link> in <guilabel>&kplayer; Settings</guilabel>. You can also change this +option while playing a file using commands on the +<link linkend="submenu-advanced"><guisubmenu>Advanced</guisubmenu> +submenu</link> of the <guimenu>Player</guimenu> menu. If you hold &Shift; when +choosing them, &kplayer; by default will use the setting only for the current +file and remember it in this property.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Cache</guilabel></term> + +<listitem><para>This property lets you choose whether to use cache for this +file and set its size. The <guilabel>default</guilabel> setting uses the cache +options from the <link linkend="settings-advanced"><guilabel>Advanced</guilabel> +page</link> in <guilabel>&kplayer; Settings</guilabel>, +<guilabel>auto</guilabel> lets &mplayer; choose an optimal cache size, +<guilabel>none</guilabel> tells &mplayer; to use no cache, and <guilabel>set +size</guilabel> lets you set a specific size.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Build new index</guilabel></term> + +<listitem><para>This property lets you choose whether &mplayer; should build +a new index for seeking. The <guilabel>default</guilabel> setting uses the +option from <link linkend="settings-advanced"><guilabel>&kplayer; +Settings</guilabel></link>, <guilabel>yes</guilabel> builds an index if the file +does not have it, <guilabel>no</guilabel> tells &mplayer; not to build an index, +and <guilabel>force</guilabel> tells it to always build an +index.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Use KIOSlave</guilabel></term> + +<listitem><para>This property lets you choose whether to use a &kde; I/O +Slave to transfer and play this file. The <guilabel>auto</guilabel> setting +tells &kplayer; to decide it automatically using options set in +<link linkend="settings-advanced"><guilabel>&kplayer; +Settings</guilabel></link>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Use temporary file</guilabel></term> + +<listitem><para>This property lets you choose whether to use a temporary +file for playing from &kde; I/O Slave. The <guilabel>default</guilabel> +setting uses the option from <link +linkend="settings-advanced"><guilabel>&kplayer; Settings</guilabel></link>. This +property has no effect for URLs passed directly to &mplayer;.</para></listitem> +</varlistentry> + +</variablelist> + +<para><acronym>PVR</acronym> and <acronym>TV</acronym> +<link linkend="howto-devices">devices</link> have some specific properties that +are not applicable to other items.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="device-properties-advanced.png" format="PNG"/> +</imageobject> +</mediaobject> + +<variablelist> + +<varlistentry> +<term><guilabel>Hardware compression</guilabel></term> + +<listitem><para>This property lets you choose whether to use +<acronym>MJPEG</acronym> hardware compression for a <acronym>PVR</acronym> or +<acronym>TV</acronym> device and lets you specify the decimation or image size. +For other items this property is not applicable and not shown.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Compression quality</guilabel></term> + +<listitem><para>This property lets you specify the compression quality from 0 to +100 when hardware compression is enabled for a <acronym>PVR</acronym> or +<acronym>TV</acronym> device. For other items this property is not applicable +and not shown.</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +</chapter> diff --git a/doc/en/settings-advanced.png b/doc/en/settings-advanced.png Binary files differnew file mode 100644 index 0000000..39e69fc --- /dev/null +++ b/doc/en/settings-advanced.png diff --git a/doc/en/settings-audio.png b/doc/en/settings-audio.png Binary files differnew file mode 100644 index 0000000..2823717 --- /dev/null +++ b/doc/en/settings-audio.png diff --git a/doc/en/settings-brightness.png b/doc/en/settings-brightness.png Binary files differnew file mode 100644 index 0000000..3e9c7e8 --- /dev/null +++ b/doc/en/settings-brightness.png diff --git a/doc/en/settings-contrast.png b/doc/en/settings-contrast.png Binary files differnew file mode 100644 index 0000000..55c2c3c --- /dev/null +++ b/doc/en/settings-contrast.png diff --git a/doc/en/settings-controls.png b/doc/en/settings-controls.png Binary files differnew file mode 100644 index 0000000..4d93888 --- /dev/null +++ b/doc/en/settings-controls.png diff --git a/doc/en/settings-general.png b/doc/en/settings-general.png Binary files differnew file mode 100644 index 0000000..52bb047 --- /dev/null +++ b/doc/en/settings-general.png diff --git a/doc/en/settings-hue.png b/doc/en/settings-hue.png Binary files differnew file mode 100644 index 0000000..c0e4cc5 --- /dev/null +++ b/doc/en/settings-hue.png diff --git a/doc/en/settings-progress.png b/doc/en/settings-progress.png Binary files differnew file mode 100644 index 0000000..5a12dbe --- /dev/null +++ b/doc/en/settings-progress.png diff --git a/doc/en/settings-saturation.png b/doc/en/settings-saturation.png Binary files differnew file mode 100644 index 0000000..1ce9b7f --- /dev/null +++ b/doc/en/settings-saturation.png diff --git a/doc/en/settings-sliders.png b/doc/en/settings-sliders.png Binary files differnew file mode 100644 index 0000000..0b9f494 --- /dev/null +++ b/doc/en/settings-sliders.png diff --git a/doc/en/settings-subtitles.png b/doc/en/settings-subtitles.png Binary files differnew file mode 100644 index 0000000..9abbd8d --- /dev/null +++ b/doc/en/settings-subtitles.png diff --git a/doc/en/settings-video.png b/doc/en/settings-video.png Binary files differnew file mode 100644 index 0000000..06a6c92 --- /dev/null +++ b/doc/en/settings-video.png diff --git a/doc/en/settings-volume.png b/doc/en/settings-volume.png Binary files differnew file mode 100644 index 0000000..59d6bf6 --- /dev/null +++ b/doc/en/settings-volume.png diff --git a/doc/en/settings.docbook b/doc/en/settings.docbook new file mode 100644 index 0000000..7251a41 --- /dev/null +++ b/doc/en/settings.docbook @@ -0,0 +1,1257 @@ +<chapter id="settings"> +<title>Configuration dialog</title> + +<sect1 id="settings-overview"> +<title>Overview</title> + +<para>The <guilabel>&kplayer; Settings</guilabel> dialog allows you to control +most aspects of &kplayer;'s behavior, as well as choose options that are passed +to &mplayer; and control quality and performance of media playback.</para> + +<para>Select <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +&kplayer;...</guimenuitem></menuchoice> to open the dialog box.</para> + +<para>The dialog contains several sections which are selected by +<mousebutton>left</mousebutton> clicking one of the items on the left side of +the dialog box.</para> + +<variablelist> + +<varlistentry> +<term><link linkend="settings-general">General</link> section</term> +<listitem><para>Contains options that affect general &kplayer; +behavior.</para></listitem> +</varlistentry> + +<varlistentry> +<term><link linkend="settings-controls">Controls</link> section</term> +<listitem><para>Contains advanced options that control how your choices made +using various &kplayer; controls are applied and stored.</para> + +<variablelist> + +<varlistentry> +<term><link linkend="settings-progress">Progress</link> section</term> +<listitem><para>Contains options that affect the progress slider control +and the seeking function.</para></listitem> +</varlistentry> + +<varlistentry> +<term><link linkend="settings-volume">Volume</link> section</term> +<listitem><para>Contains options that affect the volume slider +control.</para></listitem> +</varlistentry> + +<varlistentry> +<term><link linkend="settings-contrast">Contrast</link> section</term> +<listitem><para>Contains options that affect the contrast slider +control.</para></listitem> +</varlistentry> + +<varlistentry> +<term><link linkend="settings-brightness">Brightness</link> section</term> +<listitem><para>Contains options that affect the brightness slider +control.</para></listitem> +</varlistentry> + +<varlistentry> +<term><link linkend="settings-hue">Hue</link> section</term> +<listitem><para>Contains options that affect the hue slider +control.</para></listitem> +</varlistentry> + +<varlistentry> +<term><link linkend="settings-saturation">Saturation</link> section</term> +<listitem><para>Contains options that affect the saturation slider +control.</para></listitem> +</varlistentry> + +<varlistentry> +<term><link linkend="settings-sliders">Sliders</link> section</term> +<listitem><para>Contains miscellaneous options that affect all slider +controls in &kplayer;.</para></listitem> +</varlistentry> + +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><link linkend="settings-video">Video</link> section</term> +<listitem><para>Contains options that control video output.</para></listitem> +</varlistentry> + +<varlistentry> +<term><link linkend="settings-audio">Audio</link> section</term> +<listitem><para>Contains options that control audio output.</para></listitem> +</varlistentry> + +<varlistentry> +<term><link linkend="settings-subtitles">Subtitles</link> section</term> +<listitem><para>Contains options that control subtitle display.</para></listitem> +</varlistentry> + +<varlistentry> +<term><link linkend="settings-advanced">Advanced</link> section</term> +<listitem><para>Contains various options that affect advanced command line +parameters passed to &mplayer;, as well as interaction with &kde; I/O +Slaves.</para></listitem> +</varlistentry> + +</variablelist> + +<para>The buttons at the bottom of the dialog let you make choices about the +contents of all sections of the dialog.</para> + +<variablelist> + +<varlistentry> +<term><guibutton>OK</guibutton> button</term> +<listitem><para>Accepts your changes and closes the dialog.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Cancel</guibutton> button</term> +<listitem><para>Closes the dialog without saving the changes.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Apply</guibutton> button</term> +<listitem><para>Applies the changes without closing the dialog.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Defaults</guibutton> button</term> +<listitem><para>Restores all settings to their original, predefined values and +applies them.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Close</guibutton> button</term> +<listitem><para>After you choose <guibutton>Apply</guibutton> or +<guibutton>Defaults</guibutton>, the <guibutton>Cancel</guibutton> button +changes to <guibutton>Close</guibutton>. Clicking it closes the dialog +and discards changes you made since the last time changes were +applied.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Help</guibutton> button</term> +<listitem><para>Opens this user manual and displays the section that describes +the currently selected section of the dialog.</para></listitem> +</varlistentry> + +</variablelist> + +<note><para>You can also click the small <guibutton>What's This</guibutton> +button with a question mark at the top right of the dialog and then click a +configuration option to get a brief explanation of it.</para></note> + +<para>Clicking the rightmost button at the top of the dialog closes the dialog +discarding any unapplied changes.</para> + +</sect1> + +<sect1 id="settings-general"> +<title><guilabel>General</guilabel> section</title> + +<para>This section contains options that affect general &kplayer; +behavior.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="settings-general.png" format="PNG"/> +</imageobject> +</mediaobject> + +<variablelist> + +<varlistentry> +<term><guilabel>Resize main window automatically</guilabel></term> + +<listitem><para>By default &kplayer; resizes the main window automatically +unless it is maximized or full screen. When &kplayer; loads and starts +playing a new video, it scales it in increments of 50% of the original +video size until the video width reaches the <guilabel>Minimum initial +video width</guilabel> setting. It also automatically resizes the window +to maintain the video aspect if that option is turned on.</para> + +<para>If you would like to avoid automatic resizing and always keep the window +the size you make it, turn this option off. &kplayer; will then maintain the +video aspect by constraining the video within the window, as if the window was +maximized for example. You will also want to turn this option off if you get +problems coming back from full screen mode, like endless flickering for example. +But in that case you should also report the bug following instructions in +Reporting bugs HOWTO.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Minimum initial video width</guilabel></term> + +<listitem><para>If <guilabel>Resize main window automatically</guilabel> +option is enabled, when &kplayer; loads and starts playing a new video, +it scales it in increments of 50% of the original video size until the +video width in pixels reaches this setting.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Maximum entries on playlist menus</guilabel></term> + +<listitem><para>This option tells &kplayer; the maximum number of entries to put +on the <guisubmenu>Play List</guisubmenu> submenu of the +<link linkend="menu-file"><guimenu>File</guimenu> menu</link> and +<mousebutton>right</mousebutton> click <link linkend="popup-menus">popup +menus</link> and on the <guisubmenu>Add to</guisubmenu> submenu of the +<link linkend="menu-library"><guimenu>Library</guimenu> menu</link> and the +<link linkend="popup-library">library popup menu</link>. The +<link linkend="parts-library"><interface>multimedia library</interface></link> +allows you to create as many playlists as you like, and you can always access +them in the <guilabel>Playlists</guilabel> section of the library regardless of +this setting.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Maximum entries on Play Recent menu</guilabel></term> + +<listitem><para>This option tells &kplayer; the maximum number of entries to put +on the <guisubmenu>Play Recent</guisubmenu> submenu of the +<link linkend="menu-file"><guimenu>File</guimenu> menu</link> and +<mousebutton>right</mousebutton> click <link linkend="popup-menus">popup +menus</link>. When the number of entries is exceeded, &kplayer; will remove the +oldest entries from the menu, but depending on the option below you may still +find them in the <interface>multimedia library</interface>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Maximum Recent entries in the library</guilabel></term> + +<listitem><para>This option tells &kplayer; the maximum number of entries to put +in the <guilabel>Recent</guilabel> section of the <interface>multimedia +library</interface>. When the number of entries is exceeded, &kplayer; will +remove the oldest entries. Note that playing a directory or a selection of files +and directories creates only one entry in the <guilabel>Recent</guilabel> +section and on the <guisubmenu>Play Recent</guisubmenu> menu.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Meta information cache size limit</guilabel></term> + +<listitem><para>This option gives the maximum number of multimedia items for +which &kplayer; should store the <link linkend="howto-properties">file +properties</link>. These items include local files, remote +<acronym>URL</acronym>s, <acronym>CD</acronym> tracks, <acronym>DVD</acronym> +titles and tuner device channels. &kplayer; remembers the properties of each +of those items, and when the total number of items exceeds this setting, it will +start discarding the properties of the items that have not been played for the +longest time.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Allow duplicate entries on playlists</guilabel></term> + +<listitem><para>If this option is selected, &kplayer; will let you add items +with identical <acronym>URL</acronym>s to the playlist. When the option is +turned off and you add new entries to a playlist, &kplayer; will remove any +existing entries that have the same <acronym>URL</acronym> as one of the new +entries from the same playlist folder. Also if some of the new entries have +identical <acronym>URL</acronym>s, it will add only one for each +<acronym>URL</acronym>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show messages if a file fails to play</guilabel></term> + +<listitem><para>This option tells &kplayer; whether to automatically show the +<link linkend="parts-message-log">message log</link> if &kplayer; encounters an +error when trying to play a file. If this option is enabled, &kplayer; will show +the log and scroll to the last messages from the first file with an error, so +you can see what the error was. If the option is disabled, &kplayer; will +instead display the word <guilabel>Error</guilabel> in the left portion of the +<link linkend="parts-status-bar">status bar</link>, and then you can +<mousebutton>left</mousebutton> click it to show the message +log.</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="settings-controls"> +<title><guilabel>Controls</guilabel> section</title> + +<para>This section contains advanced options that control how your choices +made using various &kplayer; controls are applied and stored. For more +information on applying options to individual files see the File Properties +section of this manual.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="settings-controls.png" format="PNG"/> +</imageobject> +</mediaobject> + +<variablelist> + +<varlistentry> +<term><guilabel>Remember for current file any changes made with +Shift</guilabel></term> + +<listitem><para>If this option is selected, when you adjust one of the +settings listed below while holding the &Shift; key down, &kplayer; will +apply the change only to the current file, store it in the file properties, +and revert to the setting prior to the change before loading another file. +You will be able to see and modify the stored setting in the File Properties +dialog. The next time the file is played, the setting stored in its +properties will again take effect until another file is loaded.</para> + +<para>If you make the change without pressing the &Shift; key, and the +corresponding option below is not selected, the new setting will apply to the +current file and all files played after it until you change the setting +again.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Always remember the following settings for each +file</guilabel></term> + +<listitem><para>The following options let you choose what settings &kplayer; +will automatically remember in the file properties for each individual file. +By default it stores the video aspect ratio, subtitle delay and audio delay +separately for each file, and resets the delays for each new file, while other +settings are preserved when loading new files. Normally you should leave the +options below at their defaults. Settings for which the corresponding options +below are not selected can still be easily stored for each file by holding down +the &Shift; key while changing them, as long as the <guilabel>Remember for +current file any changes made with Shift</guilabel> option is +selected.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Display size</guilabel></term> + +<listitem><para>If this option is selected, &kplayer; will automatically +remember in the file properties for the currently loaded file the video +display size you choose by resizing the main KPlayer window or the video +area. As mentioned above, if this option is not selected, you can still +make &kplayer; remember the display size by holding down the &Shift; key, +but for that to work in this case it is important that you start holding +the &Shift; key before resizing.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Display aspect</guilabel></term> + +<listitem><para>If this option is selected, &kplayer; will automatically +remember in the file properties for the currently loaded file the video +aspect you choose by using commands on <guimenu>View</guimenu> +menu.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Full screen</guilabel></term> + +<listitem><para>If this option is selected, &kplayer; will automatically +remember in the file properties for the currently loaded file the full +screen option you choose on the <guimenu>View</guimenu> +menu.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Maximized</guilabel></term> + +<listitem><para>If this option is selected, &kplayer; will automatically +remember the maximized window state in the file properties for the currently +loaded file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Maintain aspect</guilabel></term> + +<listitem><para>If this option is selected, &kplayer; will automatically +remember the maintain aspect setting in the file properties for the currently +loaded file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Volume</guilabel></term> + +<listitem><para>If this option is selected, &kplayer; will automatically +remember volume adjustments in the file properties for the currently loaded +file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Audio delay</guilabel></term> + +<listitem><para>If this option is selected, &kplayer; will automatically +remember the audio delay setting in the file properties for the currently +loaded file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Contrast</guilabel></term> + +<listitem><para>If this option is selected, &kplayer; will automatically +remember contrast adjustments in the file properties for the currently +loaded file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Brightness</guilabel></term> + +<listitem><para>If this option is selected, &kplayer; will automatically +remember brightness adjustments in the file properties for the currently +loaded file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Hue</guilabel></term> + +<listitem><para>If this option is selected, &kplayer; will automatically +remember hue adjustments in the file properties for the currently loaded +file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Saturation</guilabel></term> + +<listitem><para>If this option is selected, &kplayer; will automatically +remember saturation adjustments in the file properties for the currently +loaded file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Subtitle position</guilabel></term> + +<listitem><para>If this option is selected, &kplayer; will automatically +remember the subtitle vertical position in the file properties for the +currently loaded file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Subtitle delay</guilabel></term> + +<listitem><para>If this option is selected, &kplayer; will automatically +remember the subtitle delay setting in the file properties for the currently +loaded file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Frame drop</guilabel></term> + +<listitem><para>If this option is selected, &kplayer; will automatically +remember the frame drop setting in the file properties for the currently +loaded file.</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="settings-progress"> +<title><guilabel>Progress</guilabel> subsection</title> + +<para>This section contains options that affect the progress slider control +and the seeking function.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="settings-progress.png" format="PNG"/> +</imageobject> +</mediaobject> + +<variablelist> + +<varlistentry> +<term><guilabel>Normal seek amount</guilabel></term> + +<listitem><para>This option tells &kplayer; how far to seek (move the +current playback position) forward or backward when using +<guimenuitem>Forward</guimenuitem> and <guimenuitem>Backward</guimenuitem> +commands on <guimenu>Player</guimenu> menu, either in seconds or in +percents of the time length of the file if it is known.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Fast seek amount</guilabel></term> + +<listitem><para>This option tells &kplayer; how far to seek (move the +current playback position) forward or backward when using +<guimenuitem>Fast Forward</guimenuitem> and <guimenuitem>Fast +Backward</guimenuitem> commands on <guimenu>Player</guimenu> menu, either +in seconds or in percents of the time length of the file if it is +known.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Distance between slider marks</guilabel></term> + +<listitem><para>This option gives the distance between tick marks on the +progress slider, in percents of the slider length.</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="settings-volume"> +<title><guilabel>Volume</guilabel> subsection</title> + +<para>This section contains options that affect the volume slider +control.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="settings-volume.png" format="PNG"/> +</imageobject> +</mediaobject> + +<variablelist> + +<varlistentry> +<term><guilabel>Minimum</guilabel></term> + +<listitem><para>This option gives the lower limit on the sound volume +setting.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Maximum</guilabel></term> + +<listitem><para>This option gives the upper limit on the sound volume +setting.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Distance between slider marks</guilabel></term> + +<listitem><para>This option gives the distance between tick marks on the +volume slider, in percents of the slider length.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Adjustment amount</guilabel></term> + +<listitem><para>This option tells &kplayer; by how much to adjust the +sound volume when using the <guimenuitem>Increase Volume</guimenuitem> +and <guimenuitem>Decrease Volume</guimenuitem> commands on the +<guisubmenu>Audio</guisubmenu> submenu of the <guimenu>Player</guimenu> +menu or the corresponding keyboard shortcuts.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Reset</guilabel></term> + +<listitem><para>This option lets you reset the sound volume to a specific +setting every time before loading a new file or when starting +&kplayer;.</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="settings-contrast"> +<title><guilabel>Contrast</guilabel> subsection</title> + +<para>This section contains options that affect the contrast slider +control.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="settings-contrast.png" format="PNG"/> +</imageobject> +</mediaobject> + +<variablelist> + +<varlistentry> +<term><guilabel>Minimum</guilabel></term> + +<listitem><para>This option gives the lower limit on the video contrast +setting.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Maximum</guilabel></term> + +<listitem><para>This option gives the upper limit on the video contrast +setting.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Distance between slider marks</guilabel></term> + +<listitem><para>This option gives the distance between tick marks on the +contrast slider, in percents of the slider length.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Adjustment amount</guilabel></term> + +<listitem><para>This option tells &kplayer; by how much to adjust the +video contrast when using the <guimenuitem>Increase Contrast</guimenuitem> +and <guimenuitem>Decrease Contrast</guimenuitem> commands on the +<guisubmenu>Video</guisubmenu> submenu of the <guimenu>Player</guimenu> +menu or the corresponding keyboard shortcuts.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Reset</guilabel></term> + +<listitem><para>This option lets you reset the video contrast to a specific +setting every time before loading a new file or when starting +&kplayer;.</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="settings-brightness"> +<title><guilabel>Brightness</guilabel> subsection</title> + +<para>This section contains options that affect the brightness slider +control.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="settings-brightness.png" format="PNG"/> +</imageobject> +</mediaobject> + +<variablelist> + +<varlistentry> +<term><guilabel>Minimum</guilabel></term> + +<listitem><para>This option gives the lower limit on the video brightness +setting.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Maximum</guilabel></term> + +<listitem><para>This option gives the upper limit on the video brightness +setting.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Distance between slider marks</guilabel></term> + +<listitem><para>This option gives the distance between tick marks on the +brightness slider, in percents of the slider length.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Adjustment amount</guilabel></term> + +<listitem><para>This option tells &kplayer; by how much to adjust the +video brightness when using the <guimenuitem>Increase Brightness</guimenuitem> +and <guimenuitem>Decrease Brightness</guimenuitem> commands on the +<guisubmenu>Video</guisubmenu> submenu of the <guimenu>Player</guimenu> +menu or the corresponding keyboard shortcuts.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Reset</guilabel></term> + +<listitem><para>This option lets you reset the video brightness to a specific +setting every time before loading a new file or when starting +&kplayer;.</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="settings-hue"> +<title><guilabel>Hue</guilabel> subsection</title> + +<para>This section contains options that affect the hue slider +control.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="settings-hue.png" format="PNG"/> +</imageobject> +</mediaobject> + +<variablelist> + +<varlistentry> +<term><guilabel>Minimum</guilabel></term> + +<listitem><para>This option gives the lower limit on the video hue +setting.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Maximum</guilabel></term> + +<listitem><para>This option gives the upper limit on the video hue +setting.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Distance between slider marks</guilabel></term> + +<listitem><para>This option gives the distance between tick marks on the +hue slider, in percents of the slider length.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Adjustment amount</guilabel></term> + +<listitem><para>This option tells &kplayer; by how much to adjust the +video hue when using the <guimenuitem>Increase Hue</guimenuitem> +and <guimenuitem>Decrease Hue</guimenuitem> commands on the +<guisubmenu>Video</guisubmenu> submenu of the <guimenu>Player</guimenu> +menu or the corresponding keyboard shortcuts.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Reset</guilabel></term> + +<listitem><para>This option lets you reset the video hue to a specific +setting every time before loading a new file or when starting +&kplayer;.</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="settings-saturation"> +<title><guilabel>Saturation</guilabel> subsection</title> + +<para>This section contains options that affect the saturation slider +control.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="settings-saturation.png" format="PNG"/> +</imageobject> +</mediaobject> + +<variablelist> + +<varlistentry> +<term><guilabel>Minimum</guilabel></term> + +<listitem><para>This option gives the lower limit on the video saturation +setting.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Maximum</guilabel></term> + +<listitem><para>This option gives the upper limit on the video saturation +setting.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Distance between slider marks</guilabel></term> + +<listitem><para>This option gives the distance between tick marks on the +saturation slider, in percents of the slider length.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Adjustment amount</guilabel></term> + +<listitem><para>This option tells &kplayer; by how much to adjust the +video saturation when using the <guimenuitem>Increase Saturation</guimenuitem> +and <guimenuitem>Decrease Saturation</guimenuitem> commands on the +<guisubmenu>Video</guisubmenu> submenu of the <guimenu>Player</guimenu> +menu or the corresponding keyboard shortcuts.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Reset</guilabel></term> + +<listitem><para>This option lets you reset the video saturation to a specific +setting every time before loading a new file or when starting +&kplayer;.</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="settings-sliders"> +<title><guilabel>Sliders</guilabel> subsection</title> + +<para>This section contains miscellaneous options that affect all slider +controls in &kplayer;.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="settings-sliders.png" format="PNG"/> +</imageobject> +</mediaobject> + +<variablelist> + +<varlistentry> +<term><guilabel>Minimum slider length</guilabel></term> + +<listitem><para>This option gives the minimum length of a slider control. +It affects all sliders embedded in toolbars.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Preferred slider length</guilabel></term> + +<listitem><para>This option gives the preferred length of a slider control. +It affects both popup sliders and sliders embedded in toolbars.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show tick marks on sliders</guilabel></term> + +<listitem><para>If this option is selected, &kplayer; will put tick marks on +each slider on the <link linkend="toolbars">toolbars</link>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Distance between slider marks</guilabel></term> + +<listitem><para>This option gives the distance between tick marks on a slider, +in percents of the slider length.</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="settings-video"> +<title><guilabel>Video</guilabel> section</title> + +<para>This section contains options that control video output.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="settings-video.png" format="PNG"/> +</imageobject> +</mediaobject> + +<variablelist> + +<varlistentry> +<term><guilabel>Driver</guilabel></term> + +<listitem><para>This option lists available video outputs and lets you +choose the one to use for playing video.</para> + +<para>Recommended choice depends on the video card you have. If you have a +Matrox card, try XMGA, for other cards either XVidix (if supported) or XVideo +provide the best quality. With NVidia drivers you can also try XVMC output. +If after trying hard you cannot make any of these work, you can use X11 +output as the last resort. Video outputs that open a separate window instead +of using &kplayer; video area are not recommended.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Device</guilabel></term> + +<listitem><para>This option specifies the video device to use for the selected +video output. Leave it blank to use the default device.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Codec</guilabel></term> + +<listitem><para>This option lists the available video codecs and lets you +choose the one to be used for decoding video. <guilabel>Auto</guilabel> is the +recommended choice, it lets &mplayer; decide which codec to use automatically. +If you need to tell &mplayer; to use a particular codec for a particular file +or stream, set this option in the File Properties.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Scaler</guilabel></term> + +<listitem><para>This option specifies the video scaler to be used when doing +software scaling. Software scaling consumes considerable amount of system +resources, so unless you have plenty of them and software scaling gives you +better image quality, you should choose a video output above that uses +hardware scaling.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Enable double buffering</guilabel></term> + +<listitem><para>This option lets you choose whether double buffering should +be used for video output. This option is recommended, it gives smoother +display in many cases.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Enable direct rendering</guilabel></term> + +<listitem><para>This option lets you choose whether direct rendering should +be used for video output. This option may give performance improvement, but +may also cause video display problems, for example when used along with +double buffering option or when playing with subtitles.</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="settings-audio"> +<title><guilabel>Audio</guilabel> section</title> + +<para>This section contains options that control audio output.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="settings-audio.png" format="PNG"/> +</imageobject> +</mediaobject> + +<variablelist> + +<varlistentry> +<term><guilabel>Output driver</guilabel></term> + +<listitem><para>This option lists available audio outputs and lets you +choose the one to use for playing sound.</para> + +<para>Recommended choice is <acronym>ALSA</acronym>, or <acronym>OSS</acronym> +as the last resort if you cannot use <acronym>ALSA</acronym>. +<acronym>ARTS</acronym>, <acronym>ESD</acronym> and <acronym>SDL</acronym> are +not recommended. The <guilabel>auto</guilabel> option will let &mplayer; choose +an audio output according to its own configuration.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Output device</guilabel></term> + +<listitem><para>This option specifies the audio device to use for the selected +audio output. Leave it blank to use the default device.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Control volume independently of other programs</guilabel></term> + +<listitem><para>This option tells &mplayer; to use software volume control, +which does not affect global volume settings on your system, but may result +in some distortion of the sound.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Maximum volume</guilabel></term> + +<listitem><para>When the software volume option above is turned on, this option +gives the maximum volume level in percent of the normal level.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Mixer device</guilabel></term> + +<listitem><para>When <acronym>ALSA</acronym> or <acronym>OSS</acronym> audio +output is selected, and the software volume option above is turned off, this +option specifies the mixer device that should be used to control the sound +volume. Leave it blank to use the default device.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Mixer channel</guilabel></term> + +<listitem><para>When <acronym>ALSA</acronym> or <acronym>OSS</acronym> audio +output is selected, and the software volume option above is turned off, this +option specifies the mixer channel that should be used to control the sound +volume. Leave it blank to use the default channel, normally +<acronym>PCM</acronym>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Codec</guilabel></term> + +<listitem><para>This option lists the available audio codecs and lets you +choose the one to be used for decoding audio. <guilabel>Auto</guilabel> is the +recommended choice, it lets &mplayer; decide which codec to use automatically. +If you need to tell &mplayer; to use a particular codec for a particular file +or stream, set this option in the File Properties.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Delay adjustment amount</guilabel></term> + +<listitem><para>This option tells &kplayer; by how much to adjust the +audio delay when using the <guimenuitem>Increase Delay</guimenuitem> +and <guimenuitem>Decrease Delay</guimenuitem> commands on the +<guisubmenu>Audio</guisubmenu> submenu of the <guimenu>Player</guimenu> +menu or the corresponding keyboard shortcuts.</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="settings-subtitles"> +<title><guilabel>Subtitles</guilabel> section</title> + +<para>This section contains options that control subtitle display.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="settings-subtitles.png" format="PNG"/> +</imageobject> +</mediaobject> + +<variablelist> + +<varlistentry> +<term><guilabel>Font name</guilabel></term> + +<listitem><para>This option lets you choose the name of the font that &mplayer; +should use to display subtitles.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Bold</guilabel></term> + +<listitem><para>This option tells &mplayer; to use a bold font to display +subtitles.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Italic</guilabel></term> + +<listitem><para>This option tells &mplayer; to use an italic font to display +subtitles.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Text size</guilabel></term> + +<listitem><para>This option specifies the text size that &mplayer; should use +to display subtitles. If the <guilabel>Auto scale</guilabel> option below is +selected, this option gives the scaling factor, otherwise it gives the font +size in points.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Auto scale</guilabel></term> + +<listitem><para>This option indicates whether &mplayer; should scale the font +according to the size of the video or always use the same font +size.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Outline</guilabel></term> + +<listitem><para>This option specifies the width of the black outline for the +subtitle font.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Width</guilabel></term> + +<listitem><para>This option gives the width of the area for subtitle text in +percent of the width of the video area.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Position adjustment amount</guilabel></term> + +<listitem><para>This option tells &kplayer; how far to move the subtitles, in +percents of the video height, when using the <guimenuitem>Move Up</guimenuitem> +and <guimenuitem>Move Down</guimenuitem> commands on the +<guisubmenu>Subtitles</guisubmenu> submenu of the <guimenu>Player</guimenu> +menu or the corresponding keyboard shortcuts.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Delay adjustment amount</guilabel></term> + +<listitem><para>This option tells &kplayer; by how much to adjust the +subtitle delay when using the <guimenuitem>Increase Delay</guimenuitem> +and <guimenuitem>Decrease Delay</guimenuitem> commands on the +<guisubmenu>Subtitles</guisubmenu> submenu of the <guimenu>Player</guimenu> +menu or the corresponding keyboard shortcuts.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Encoding</guilabel></term> + +<listitem><para>This option specifies the encoding of text in subtitle files. +For individual subtitle files that use a different encoding you can override +this setting in the <link linkend="properties-subtitles"><guilabel>File +Properties</guilabel></link> of the corresponding video file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Use embedded fonts when available</guilabel></term> + +<listitem><para>This option tells &mplayer; to use the embedded fonts to display +subtitles if a video file contains embedded fonts. For example, the Matroska +file format allows embedding of fonts.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Display closed caption subtitles</guilabel></term> + +<listitem><para>This options tells &mplayer; to display closed caption subtitles +if the video has them. Closed caption subtitles are found on some +<acronym>DVD</acronym>s.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Auto expand video area to aspect ratio</guilabel></term> + +<listitem><para>This option tells &kplayer; to expand the video area to fit +the aspect ratio you choose and display subtitles in the black bands below or +above the video. It is recommended that you choose the aspect ratio to match +the aspect ratio of your monitor, normally +<guilabel>4:3</guilabel>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Autoload subtitles</guilabel></term> + +<listitem><para>This option tells &kplayer; to automatically load +subtitle files that have the extensions given in the field below. &kplayer; will +look for subtitle files in the directory where the video file is, by looking for +files that have one of the extensions given by the next field and contain the +name of the video file in their name. Autoloading only works in directories +mounted on your file system.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Extensions</guilabel></term> + +<listitem><para>This option lists the extensions of subtitle files that +&kplayer; should automatically load and display in the video area. The +extensions can be separated by commas, semicolons, colons, periods or +spaces.</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="settings-advanced"> +<title><guilabel>Advanced</guilabel> section</title> + +<para>This section contains various options that affect advanced command +line parameters passed to &mplayer;, as well as interaction with &kde; +I/O Slaves.</para> + +<mediaobject> +<imageobject> +<imagedata fileref="settings-advanced.png" format="PNG"/> +</imageobject> +</mediaobject> + +<variablelist> + +<varlistentry> +<term><guilabel>Executable path</guilabel></term> + +<listitem><para>This option tells &kplayer; where to find the &mplayer; +executable. It is either an absolute path or a name to look for in the +current environment path.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Additional command line arguments</guilabel></term> + +<listitem><para>This option gives additional options that will be passed +to &mplayer; on the command line. See the <ulink url="man:/mplayer">&mplayer; +manpage</ulink> for a complete list of possible options. You can also set this +option for an individual file or <acronym>URL</acronym> in the +<link linkend="properties-advanced"><guilabel>File +Properties</guilabel></link>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Preferred demuxer</guilabel></term> + +<listitem><para>This option lists the available demultiplexers and lets you +choose the one to be used for decoding files and streams. +<guilabel>Auto</guilabel> is the recommended choice, it lets &mplayer; decide +which demuxer to use automatically. If you need to tell &mplayer; to use a +particular demuxer for a particular file or stream, set this option in the +<link linkend="properties-advanced"><guilabel>File +Properties</guilabel></link>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Frame drop</guilabel></term> + +<listitem><para>If your system is too slow to play a file, &mplayer; can +drop some frames so playback does not slow down. The <guilabel>none</guilabel> +option disables frame dropping, <guilabel>soft</guilabel> drops less frames, and +<guilabel>hard</guilabel> drops more frames and may sometimes break decoding. +You can also set this option for an individual file or <acronym>URL</acronym> in +the <link linkend="properties-advanced"><guilabel>File +Properties</guilabel></link>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Cache</guilabel></term> + +<listitem><para>This option lets you choose whether to use cache and set its +size. The <guilabel>auto</guilabel> option lets &mplayer; choose an optimal +cache size automatically, <guilabel>none</guilabel> tells &mplayer; to use no +cache, and <guilabel>set size</guilabel> lets you set a specific size. You can +also set this option for an individual file or <acronym>URL</acronym> in the +<link linkend="properties-advanced"><guilabel>File +Properties</guilabel></link>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Build new index</guilabel></term> + +<listitem><para>This option lets you choose whether to build a new index for +seeking. The <guilabel>yes</guilabel> option builds an index if the file does +not have it, <guilabel>no</guilabel> tells &mplayer; not to build an index, and +<guilabel>force</guilabel> tells it to always build an index. You can also +choose this option for an individual file or <acronym>URL</acronym> in the +<link linkend="properties-advanced"><guilabel>File +Properties</guilabel></link>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Use temporary file for playing from KIOSlave</guilabel></term> + +<listitem><para>This option lets you choose whether to use a temporary file +for playing from &kde; I/O Slaves. This option has no effect for URLs passed +directly to &mplayer;. You can also choose it for individual file or URL in +File Properties.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Use KIOSlave for</guilabel> <guilabel>HTTP</guilabel></term> + +<listitem><para>This option lets you choose whether to use a &kde; I/O Slave +to play HTTP URLs. You can also choose this option for individual file or +stream in File Properties.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Use KIOSlave for</guilabel> <guilabel>FTP</guilabel></term> + +<listitem><para>This option lets you choose whether to use a &kde; I/O Slave +to play FTP URLs. You can also choose this option for individual file or +stream in File Properties.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Use KIOSlave for</guilabel> <guilabel>SMB</guilabel></term> + +<listitem><para>This option lets you choose whether to use a &kde; I/O Slave +to play Samba URLs. You can also choose this option for individual file or +stream in File Properties.</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +</chapter> diff --git a/doc/en/shortcuts-configure.png b/doc/en/shortcuts-configure.png Binary files differnew file mode 100644 index 0000000..5de889b --- /dev/null +++ b/doc/en/shortcuts-configure.png diff --git a/doc/en/shortcuts-define.png b/doc/en/shortcuts-define.png Binary files differnew file mode 100644 index 0000000..e2ac476 --- /dev/null +++ b/doc/en/shortcuts-define.png diff --git a/doc/en/toolbars-change-icon.png b/doc/en/toolbars-change-icon.png Binary files differnew file mode 100644 index 0000000..3763f8c --- /dev/null +++ b/doc/en/toolbars-change-icon.png diff --git a/doc/en/toolbars-configure.png b/doc/en/toolbars-configure.png Binary files differnew file mode 100644 index 0000000..f32e66b --- /dev/null +++ b/doc/en/toolbars-configure.png |
