Initial import of kplayer 0.6.3

1 files changed, 239 insertions, 0 deletions

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>