<sect1 id="howto-library">
<title
>Multimedia library</title>

<sect2 id="howto-library-overview">
<title
>Overblik</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 &Tab; or <keycombo action="simul"
>&Shift;&Tab;</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>
