Warning, /multimedia/juk/doc/index.docbook is written in an unsupported language. File is not indexed.

0001 <?xml version="1.0" ?>
0002 <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [
0003   <!ENTITY juk "<application>JuK</application>">
0004   <!ENTITY % addindex "IGNORE">
0005   <!ENTITY % English "INCLUDE">
0006 ]>
0008 <book id="juk" lang="&language;">
0010 <bookinfo>
0011 <title>The &juk; Handbook</title>
0013 <authorgroup>
0014 <author>&Lauri.Watts; &Lauri.Watts.mail;</author>
0015 <author>
0016 <firstname>Michael</firstname>
0017 <surname>Pyne</surname>
0018 <affiliation>
0019 <address><email>michael.pyne@kdemail.net</email></address>
0020 </affiliation>
0021 </author>
0023 <othercredit role="developer">
0024 <firstname>Scott</firstname>
0025 <surname>Wheeler</surname>
0026 <affiliation>
0027 <address>&Scott.Wheeler.mail;</address>
0028 </affiliation>
0029 </othercredit>
0033 </authorgroup>
0035 <copyright>
0036 <year>2001</year>
0037 <year>2002</year>
0038 <year>2004</year>
0039 <holder>&Scott.Wheeler;</holder>
0040 </copyright>
0041 <legalnotice>&FDLNotice;</legalnotice>
0043 <date>2013-11-08</date>
0044 <releaseinfo>3.11 (&kde; 4.12)</releaseinfo>
0046 <abstract>
0047 <para>
0048 &juk; is a jukebox, tagger and music collection manager.
0049 </para>
0050 </abstract>
0052 <keywordset>
0053 <keyword>KDE</keyword>
0054 <keyword>kdemultimedia</keyword>
0055 <keyword>audio</keyword>
0056 <keyword>tagger</keyword>
0057 <keyword>player</keyword>
0058 <keyword>jukebox</keyword>
0059 <keyword>JuK</keyword>
0060 </keywordset>
0062 </bookinfo>
0064 <chapter id="introduction">
0065 <title>Introduction</title>
0067 <para>
0068 &juk; is, well, a jukebox.  As is typical with many jukebox
0069 applications, &juk; allows you to edit the <quote>tags</quote> of your
0070 audio files, and manage your collection and playlists.
0071 </para>
0072 </chapter>
0074 <chapter id="using-juk">
0075 <title>Using &juk;</title>
0077 <para>
0078 <screenshot>
0079 <screeninfo>Here's a screenshot of &juk;</screeninfo>
0080         <mediaobject>
0081           <imageobject>
0082             <imagedata fileref="juk-main.png" format="PNG"/>
0083           </imageobject>
0084           <textobject>
0085             <phrase>Screenshot of &juk; in action.</phrase>
0086           </textobject>
0087         </mediaobject>
0088 </screenshot>
0089 </para>
0091 <para>&juk; maintains a list of all files that it knows about.  This
0092 is called the <guilabel>Collection List</guilabel>.  The collection
0093 list is specific to &juk; and is not shared with other
0094 applications.</para>
0096 <para>Independent of the Collection List, are playlists.  You can have
0097 as many playlists as you want. You can use &juk; created playlists
0098 with other media players (such as &amarok; or
0099 <application>xmms</application>) and you can manage playlists created
0100 in those applications from within &juk;.</para>
0102 <para>You can add files to the Collection List individually, using
0103 <menuchoice><guimenu>File</guimenu><guimenuitem>Open
0104 ...</guimenuitem></menuchoice> and selecting them from a standard
0105 &kde; file dialog.  You can add entire folders using
0106 <menuchoice><guimenu>File</guimenu><guimenuitem>Manage
0107 Folders...</guimenuitem></menuchoice>.  Folders added this way
0108 will be rescanned every time you start &juk;. You can even define folders
0109 inside these folders that will be excluded from scan.
0110 <!-- ask scott:
0111      Asked 2004-04-27 (mpyne), Choosing Reload from the Collection
0112      List context menu will result in a rescan.  Also, a KDirWatch
0113      watches the folders, but is apparently not recursive. -->
0114 You can force the folders to be rescanned by right-clicking on the <guilabel>Collection List</guilabel>
0115 icon, and selecting <guimenuitem>Reload</guimenuitem>.</para>
0117 <para>Adding a song to a playlist will automatically add its file to
0118 the Collection List, but adding a file to the Collection List won't
0119 automatically add the song to any playlists.</para>
0121 <para>You can quickly create a playlist from your entire Collection
0122 List, by &RMB; clicking on the <guilabel>Collection List</guilabel>
0123 icon, and choosing <guimenuitem>Duplicate</guimenuitem>.  The
0124 resulting playlist is a normal playlist, and editing it will not
0125 affect the <guilabel>Collection List</guilabel>.</para>
0127 <para>You can add playlist files created outside &juk; individually by
0128 selecting them with
0129 <menuchoice><guimenu>File</guimenu><guimenuitem>Open
0130 ...</guimenuitem></menuchoice>.  Any playlist files found in
0131 folders you add with
0132 <menuchoice><guimenu>File</guimenu><guimenuitem>Manage
0133 Folders...</guimenuitem></menuchoice> will also be added
0134 automatically.</para>
0136 <para>You can create a new empty playlist, a search playlist or a 
0137 playlist from a folder by choosing
0138 <menuchoice><guimenu>File</guimenu><guisubmenu>New</guisubmenu></menuchoice>
0139 or the <guiicon>New</guiicon> icon on the toolbar.  You will be
0140 prompted for a name, and then an icon for that playlist will appear in
0141 the playlist pane.  You can now drag and drop files from the
0142 Collection List, or from other playlists, to your playlist.  Use the <guiicon>Save</guiicon>
0143 icon or
0144 <menuchoice><guimenu>File</guimenu><guimenuitem>Save</guimenuitem></menuchoice> to
0145 save the playlist at any time.</para>
0147 <sect1 id="collection-list-gui">
0148 <title>The Song List</title>
0150 <para>When you are viewing the Collection List, the main pane contains
0151 all the files that &juk; knows about.  When you are viewing a
0152 playlist, only the songs that are in that playlist are shown.  In
0153 either case, the appearance and behavior of the list is the
0154 same.</para>
0156 <para>Each song takes one row in the display. There is a column for
0157 each metadata field that &juk; tracks.  These columns correspond to
0158 the fields available to edit in the tag editor.</para>
0160 <para>You can reorder the list at any time by &LMB; clicking on the
0161 column header.  This will first sort the files in ascending order
0162 based on the contents of that column.  If you &LMB; click again on the
0163 same header, the files will be re-sorted in descending order.</para>
0165 <para>The columns are initially sized wide enough to show the longest
0166 entry available. You can resize the columns by placing your mouse
0167 cursor on the divider between two columns.  When the cursor changes
0168 from a pointer, &LMB; click and drag in the direction you want to
0169 resize the columns.</para>
0171 <para>You can reorder the columns by &LMB; clicking on a header and
0172 dragging the header to the left or right.  You cannot drag past the
0173 edge of the window when doing this however, so you may need to scroll
0174 a little to the left or right, and repeat dragging the header, until
0175 you have placed it in your preferred position.</para>
0177 <para>You can hide or unhide columns by &RMB; clicking on a column header,
0178 and clicking on the name of the column to change.</para>
0180 <para>&LMB; double clicking on a file will play it with the built-in
0181 player.  If another song was already playing, it will stop, and the
0182 new song will play.</para>
0184 <para>&RMB; clicking on a file offers you several options:</para>
0186 <variablelist>
0187 <varlistentry>
0188 <term><guimenuitem>Add to Play Queue</guimenuitem></term>
0189 <listitem>
0190 <para>This will start playing the file as soon as the current
0191 song is over.  If no song is playing, the file will be played when
0192 you next hit the <guiicon>Play</guiicon> button.  If you have already
0193 chosen the <guimenuitem>Add to Play Queue</guimenuitem> option on a 
0194 different file, then this file will override that selection.</para>
0195 </listitem>
0196 </varlistentry>
0198 <varlistentry>
0199 <term><guimenuitem>Cut</guimenuitem></term>
0200 <term><guimenuitem>Copy</guimenuitem></term>
0201 <term><guimenuitem>Paste</guimenuitem></term>
0202 <listitem>
0203 <para>...</para>
0204 </listitem>
0205 </varlistentry>
0207 <varlistentry>
0208 <term><guimenuitem>Remove from Playlist</guimenuitem></term>
0209 <listitem>
0210 <para>If you are viewing the Collection List, choosing
0211 this action will remove the file from the list,
0212 and will also remove all corresponding entries for this song from all
0213 playlists.  You should note that if this file is in a folder that
0214 &juk; scans on startup, it will be readded to the Collection List the
0215 next time you start up &juk; but it won't be automatically added to
0216 any playlists.</para>
0217 <para>If you are viewing a playlist, <guimenuitem>Remove from Playlist</guimenuitem>
0218 will simply remove the song from the playlist.</para>
0220 </listitem>
0221 </varlistentry>
0223 <varlistentry>
0224 <term><guimenuitem>Edit <replaceable>Column Title</replaceable></guimenuitem></term>
0225 <listitem>
0226 <para>Will allow you to edit the currently highlighted song, in the
0227 column you clicked in.  For example, if you do not have the tag editor
0228 visible, and you are busy creating a playlist, but you notice a
0229 mis-spelling in an artist name, you can edit it directly with this
0230 menu item.</para>
0231 <para>Changes made in this manner are always saved immediately as soon
0232 as you click elsewhere and are finished editing.</para>
0233 <para>This menu item will be disabled if &juk; detects that the track you
0234 have selected is read-only.</para>
0235 </listitem>
0236 </varlistentry>
0238 <varlistentry>
0239 <term><guimenuitem>Refresh</guimenuitem></term>
0240 <listitem>
0241 <para>This will reload the tag information of the selected files, in
0242 case the files have been changed while &juk; was running.</para>
0243 </listitem>
0244 </varlistentry>
0246 <varlistentry>
0247 <term><guimenuitem>Delete</guimenuitem></term>
0248 <listitem>
0249 <para>This will remove the file from the Collection List, remove all
0250 entries for the song in all playlists, and delete the file from your
0251 disk.  You cannot undo this, although you will be asked to confirm
0252 your choice.  Use this with caution.</para>
0253 </listitem>
0254 </varlistentry>
0256 <varlistentry>
0257 <term><guisubmenu>Guess Tag Information</guisubmenu></term>
0258 <listitem>
0259 <para>This will make &juk; try to guess information such as the
0260 Artist and Title of a song.  &juk; employs different methods of guessing:
0261   <variablelist>
0263   <varlistentry><term><guimenuitem>From File Name</guimenuitem></term>
0264   <listitem><para>&juk; will try to guess the tags of the song based on its filename.
0265   For example, a song name such as <filename>Roxette - You've Got the Look.mp3</filename>
0266   would guess Roxette for the artist and You've Got the Look as the title.  You
0267   can adjust the way &juk; guesses for tags by selecting <menuchoice><guimenu>Settings
0268   </guimenu><guimenuitem>Tag Guesser...</guimenuitem></menuchoice>, which will open the
0269   <link linkend="juk-tag-guesser-configuration">Tag Guesser dialog</link>. &juk; will not
0270   replace tags that it did not guess from the file name.</para>
0271   </listitem>
0272   </varlistentry>
0274   <varlistentry><term><guimenuitem>From Internet</guimenuitem></term>
0275   <listitem><para>&juk; will try to guess the tags of the song by using the
0276   MusicBrainz program.  You must have MusicBrainz installed for this command to work.
0277   </para>
0278   </listitem>
0279   </varlistentry>
0281   </variablelist>
0282 </para>
0283 </listitem>
0284 </varlistentry>
0286 <varlistentry>
0287 <term><guimenuitem>Rename File</guimenuitem></term>
0288 <listitem>
0289 <para>This will rename the selected files to conform to a given format.  You must
0290 choose the way you want the files renamed first by selecting <menuchoice>
0291 <guimenu>Settings</guimenu><guimenuitem>File Renamer...</guimenuitem></menuchoice>.
0292 The resulting name of each file is based on its metadata tags.  For example,
0293 the Ogg Vorbis song <quote>The Theme (Metroid)</quote> by Stemage could result in
0294 <filename>/usr/share/music/Stemage/The Theme (Metroid).ogg</filename>.
0295 </para>
0296 </listitem>
0297 </varlistentry>
0298 <!--missing Cover Manager
0299 View Cover
0300 Get Cover From File
0301 Get Cover From Internet
0302 Delete Cover
0303 Show Cover Manager
0304 -->
0305 <varlistentry>
0306 <term><guimenuitem>Create Playlist From Selected Items</guimenuitem></term>
0307 <listitem>
0308 <para>This allows you to quickly create a playlist from songs in your Collection List.
0309 This function will prompt you for a name for the new playlist, and will then insert all of
0310 the songs that are selected into the new playlist.</para>
0311 </listitem>
0312 </varlistentry>
0314 <varlistentry>
0315 <term><guimenuitem>Add Selected Items to Audio or Data CD</guimenuitem></term>
0316 <listitem>
0317 <para>This allows you to quickly create a K3b &CD;-burning project from your selected songs.  &juk; will ask you if you would like an Audio &CD; project or a Data &CD; project, unless K3b already has a project open.</para>
0319 <para>If K3b is not already running, &juk; will start it up for you.  After that, &juk; will add your selected files to the current K3b project.  You can then save the project in K3b for burning later, or burn the &CD; right away.
0320 </para>
0322 </listitem>
0323 </varlistentry>
0325 </variablelist>
0327 </sect1>
0329 <sect1 id="juk-playlists">
0330 <title>&juk; Playlists</title>
0331 <para>A playlist is simply a collection of songs grouped by some category.  For example, you
0332 may have a playlist of songs that you listen to while coding, while trying to sleep, or even
0333 when you need a laugh.  &juk; supports several different types of playlists.
0334 </para>
0336 <variablelist>
0338 <varlistentry>
0339 <term id="juk-normal-playlists">Normal playlists</term>
0340 <listitem><para><inlinemediaobject><imageobject><imagedata format="PNG" fileref="normal-playlist.png"/></imageobject></inlinemediaobject>
0341 This is the most common kind of playlist.  It is a playlist composed of files, just
0342 like the Collection List.</para></listitem>
0343 </varlistentry>
0345 <varlistentry>
0346 <term id="juk-history-playlists">The history playlist</term>
0347 <listitem><para><inlinemediaobject><imageobject><imagedata format="PNG" fileref="history-playlist.png"/></imageobject></inlinemediaobject>
0348 If you enable this playlist (by enabling <menuchoice><guimenu>View</guimenu><guimenuitem>Show History</guimenuitem></menuchoice>,
0349 this playlist will record every song that &juk; plays.  The playlist will have an extra column, <guilabel>Time</guilabel>, which
0350 records the exact time and date the song played.  The playlist doesn't start tracking the history until it is enabled, however.
0351 </para></listitem>
0352 </varlistentry>
0354 <varlistentry>
0355 <term id="juk-search-playlists">Search playlists</term>
0356 <listitem><para><inlinemediaobject><imageobject><imagedata format="PNG" fileref="search-playlist.png"/></imageobject></inlinemediaobject>
0357 This is a playlist which is based off of a search.  You can create a playlist like this by clicking <menuchoice>
0358 <guimenu>File</guimenu><guisubmenu>New</guisubmenu><guimenuitem>Search Playlist</guimenuitem></menuchoice>, or by clicking on the
0359 <link linkend="juk-advanced-search-dialog">Search Playlist</link>
0360  button on the toolbar.</para>
0361 <para>After creating this playlist, it will keep track of which songs in the Collection List match your criteria, and automatically update itself accordingly whenever the
0362 Collection List changes.</para></listitem>
0363 </varlistentry>
0365 </variablelist>
0367 <para>Playlists are organized in the <guilabel>Playlist pane</guilabel>, which is the vertical bar at the left.  In this pane is an icon
0368 for every playlist you have.  There are different view mode for this pane, which can be selected from the
0369 <menuchoice><guimenu>View</guimenu><guisubmenu>View Modes</guisubmenu></menuchoice> menu.
0371 <variablelist>
0373 <varlistentry>
0374 <term id="juk-viewmode-default">Default View mode</term>
0375 <listitem>
0376 <para>
0377 This is the default view mode.  In this mode, all the playlists are shown as large icons, one above the other in the view mode.
0378 </para>
0379 </listitem>
0380 </varlistentry>
0382 <varlistentry>
0383 <term id="juk-viewmode-compact">Compact View mode</term>
0384 <listitem>
0385 <para>
0386 This mode is similar to the Normal Viewmode, with the exception that the playlists are represented with horizontal bars with small icons instead
0387 of with square boxes.
0388 </para>
0389 </listitem>
0390 </varlistentry>
0392 <varlistentry>
0393 <term id="juk-viewmode-tree">Tree View mode</term>
0394 <listitem>
0395 <para>This mode is the most powerful.  This mode is just like the Compact viewmode, except that the Collection List is now the root of a tree of virtual
0396 playlists.  The Collection List has three children nodes, Artist, Album, and Genre.  Each of these node has children representing all of the entries
0397 from that specific category.  For example, if your Collection List contains music from 4 different artists, you would have 4 entries under the artist
0398 node.</para>
0399 <para>One nifty feature of the tree view mode is something called drag-and-drop retagging.  Simply select some files in the track list, and drag them
0400 onto one of the artist, album, or genre nodes under Collection List.  The songs will automatically be retagged to match the item you dropped the
0401 tracks on.  For example, if you drag a group of tracks onto a Genre called "Rock", all of the tracks will be retagged will a Genre tag of Rock.
0402 </para>
0403 </listitem>
0404 </varlistentry>
0406 </variablelist>
0408 </para>
0410 </sect1>
0412 <sect1 id="juk-tagger">
0413 <title>The &juk; Tag Editor</title>
0415 <para>For many file formats, it is practical to use the filename to
0416 describe the contents of the file: <quote><filename>Report for the
0417 board - June 2003.doc</filename></quote> for example, may be all the
0418 information you need in order to find that file again.  Trying to
0419 capture all the useful information about a particular song however,
0420 could lead to filenames like this: <quote><filename>Type O Negative -
0421 The Glorious Liberation Of The Peoples Technocratic Republic Of
0422 Vinnland By The Combined Forces Of The United Territories Of
0423 Europa.mp3</filename></quote> or <quote><filename>Various
0424 Artists_15_The Smithsonian Collection of Classic Jazz Volume II_Jimmie
0425 Lunceford &amp; His Orchestra - Organ Grinder's
0426 Swing.mp3</filename></quote>.  These are neither very practical to
0427 use, nor do they contain all of the useful information that you might
0428 have collected about the song.  Adding the album, and track number,
0429 for example, to the first would make it even longer and more
0430 unmanageable, while still not telling you at a glance the year it was
0431 released, or what style of music it is, if you're not familiar with
0432 the artist.</para>
0434 <para>The solution then, is to store this kind of metadata inside the
0435 files themselves. Mp3 and ogg files can also contain small snippets of
0436 text which you can use to describe the content of the file.  There are
0437 several formats, but &juk; hides the details of the differences
0438 between them, and provides a standard way to edit a standard subset of
0439 well known tags for all your audio files.</para>
0441 <para>&juk;'s full featured tag editor allows you to edit the tags in
0442 both mp3 and ogg files.  You can edit single files or multiple files,
0443 and you can select a mix of mp3 and ogg files to edit.  The only
0444 requirement is that you have write access to the files themselves; you
0445 cannot edit the tags of a file that is mounted from a &CD-ROM; for
0446 example.</para>
0448 <sect2 id="tagging-a-single-file">
0449 <title>Editing the Tags in a Single File</title>
0451 <para>To edit the tag in a single file, select it in either the
0452 collection list or any entries it has in any playlist.  If the tag
0453 editor is not visible, enable it by choosing
0454 <menuchoice><guimenu>View</guimenu><guimenuitem>Show Tag
0455 Editor</guimenuitem></menuchoice>.  The tag editor displays in the
0456 bottom of the list view.</para>
0458 <para>Simply type into any of the editable fields to change the
0459 information.  When you are done, &LMB; click back in the list, and you
0460 will be prompted to save your changes.</para>
0462 <para>You may find that the tag editor remains disabled when you've
0463 clicked on a file.  This happens when &juk; has detected that the track
0464 is read-only.</para>
0466 <variablelist>
0467 <title>Tag Editor Fields</title>
0468 <varlistentry>
0469 <term><guilabel>Artist Name:</guilabel></term>
0470 <listitem>
0471 <para>The name of the Artist(s) who released the song.</para>
0472 </listitem>
0473 </varlistentry>
0475 <varlistentry>
0476 <term><guilabel>Track name:</guilabel></term>
0477 <listitem>
0478 <para>The name of the song.</para>
0479 </listitem>
0480 </varlistentry>
0482 <varlistentry>
0483 <term><guilabel>Album name:</guilabel></term>
0484 <listitem>
0485 <para>The name of the album the song was released on.</para>
0486 </listitem>
0487 </varlistentry>
0489 <varlistentry>
0490 <term><guilabel>Genre:</guilabel></term>
0491 <listitem>
0492 <para>The <quote>Style</quote> of the music.  &juk; provides a list
0493 corresponding roughly to the informal id3 standard, but you are free
0494 to type your own entries in this list.</para>
0495 </listitem>
0496 </varlistentry>
0498 <varlistentry>
0499 <term><guilabel>File name:</guilabel></term>
0500 <listitem>
0501 <para>The file name of the actual file on disk.  You can edit this
0502 directly, and when you save, the file will be renamed.</para>
0503 </listitem>
0504 </varlistentry>
0506 <varlistentry>
0507 <term><guilabel>Track:</guilabel></term>
0508 <listitem>
0509 <para>The position of the track on the original recording.</para>
0510 </listitem>
0511 </varlistentry>
0513 <varlistentry>
0514 <term><guilabel>Year:</guilabel></term>
0515 <listitem>
0516 <para>The year the song was released.</para>
0517 </listitem>
0518 </varlistentry>
0520 <varlistentry>
0521 <term><guilabel>Length:</guilabel></term>
0522 <listitem>
0523 <para>This is not editable, it is simply shown for information.</para>
0524 </listitem>
0525 </varlistentry>
0527 <varlistentry>
0528 <term><guilabel>Bitrate:</guilabel></term>
0529 <listitem>
0530 <para>This is not editable, it is simply shown for information.</para>
0531 </listitem>
0532 </varlistentry>
0534 <varlistentry>
0535 <term><guilabel>Comment:</guilabel></term>
0536 <listitem>
0537 <para>You can add your own free text comment here, with additional
0538 notes &etc;</para>
0539 </listitem>
0540 </varlistentry>
0541 </variablelist>
0543 <para>You can explicitly and immediately save your changes at any time
0544 using the
0545 <menuchoice><guimenu>Tagger</guimenu><guimenuitem>Save</guimenuitem></menuchoice>
0546 menu entry or by pressing
0547 <keycombo action="simul">&Ctrl;<keycap>T</keycap></keycombo>.</para>
0549 </sect2>
0551 <sect2 id="tagging-multiple-files">
0552 <title>Editing the Tags in Multiple Files</title>
0554 <para>You can select multiple files in the list view, and edit one or
0555 more fields in the tags for all files at once.</para>
0557 <para>Use &Shift; and the &LMB; to select a contiguous
0558 list of files, and &Ctrl; and &LMB; to select individual
0559 non-contiguous files.</para>
0561 <para>If the tag editor is not visible, you can enable it by choosing
0562 <menuchoice><guimenu>View</guimenu><guimenuitem>Show Tag
0563 Editor</guimenuitem></menuchoice>.  The tag editor displays in the
0564 bottom of the list view.</para>
0566 <para>The tag editor behaves slightly differently when you have
0567 selected multiple files.</para>
0569 <para>Each field in the tag editor will now show an
0570 <guilabel>Enable</guilabel> check box next to it.  Any field that has
0571 exactly the same contents for all the files you selected, displays
0572 that content, and is enabled for editing, with the
0573 <guilabel>Enable</guilabel> check box checked.</para>
0575 <!-- put screeny here -->
0577 <para>Any field that does not have matching contents in all selected
0578 files is not initially editable, and does not display any contents at
0579 all.</para>
0581 <para>To change the content of any field, check the
0582 <guilabel>Enable</guilabel> check box if it is not already checked, and
0583 edit the field as you normally would.</para>
0585 <para>When you are done, &LMB; click back in the list view and you
0586 will be prompted to save your changes.  The prompt dialog will show
0587 you a list of the affected files, so you have a chance to check that
0588 you are indeed altering the files you intended to.</para>
0590 <para>You can explicitly and immediately save your changes at any time
0591 using the
0592 <menuchoice><guimenu>Tagger</guimenu><guimenuitem>Save</guimenuitem></menuchoice>
0593 menu entry or by pressing
0594 <keycombo action="simul">&Ctrl;<keycap>T</keycap></keycombo>.</para>
0596 </sect2>
0598 </sect1>
0600 <sect1 id="juk-rename-dialog">
0601 <title>The Rename File dialog</title>
0602 <para>
0603 <screenshot>
0604 <screeninfo>The Rename File dialog</screeninfo>
0605         <mediaobject>
0606           <imageobject>
0607             <imagedata fileref="juk-file-renamer.png" format="PNG"/>
0608           </imageobject>
0609           <textobject>
0610             <phrase>Screenshot of the Rename File dialog.</phrase>
0611           </textobject>
0612         </mediaobject>
0613 </screenshot>
0614 </para>
0616 <para>
0617   The File Renamer Configuration dialog box is used to configure the
0618   Rename File action, which renames a song's based on the information contained
0619   within its metadata tags.
0620 </para>
0621 <para>
0622   The whole Rename File feature is used to get consistent file names for your
0623   music collection (including moving the files if necessary). For example you
0624   may have some songs which appear on disk as <filename>01 - Title.mp3</filename>
0625   if you got them from <ulink url="http://amazon.com">Amazon</ulink>, while songs
0626   from <ulink url="http://ocremix.org/">OCRemix</ulink> might be <filename>Ailsean-
0627   Mega_Man_3_Mega_Fire_(OC_Remix).mp3</filename> or something along those lines.
0628 </para>
0629 <para>
0630   Using the file renamer allows &juk; to rename those songs to something <quote>sane</quote>
0631   on-disk, such as <filename>Ailsean - Mega Fire.mp3</filename> and <filename>The Strokes - Reptilia.mp3</filename>.
0632   You can even include paths throughout to automatically sort the music (&eg;
0633   by year or album), like <filename>$HOME/Music/2003/The Strokes - Reptilia.mp3</filename>.
0634 </para>
0635 <para>
0636   Doing this is as simple as activating the <quote>Rename File</quote> action, either from
0637   the <guimenu>Tagger</guimenu> menu, or right-clicking on the files. The default is the
0638   <keycombo>&Ctrl;<keycap>R</keycap></keycombo> shortcut. But before this is done you should
0639   setup how the files are to be renamed.
0640 </para>
0641 <para>
0642   That is done from the above mentioned dialog that can be opened with 
0643   <menuchoice><guimenu>Settings</guimenu><guimenuitem>File Renamer...</guimenuitem></menuchoice> menu item.
0644   You can define a destination path, by using a base music folder and
0645   then adding pieces to there. These path pieces would be based on the music
0646   metadata such as song title, artist, &etc;, and are added using the <guilabel>Add Category</guilabel>
0647   selector.
0648 </para>
0649 <para>
0650   Each "path piece" has a check box between it allowing a folder separator to be added.
0651 </para>
0652 <para>
0653   The options for each piece, which
0654   simply control what happens if the appropriate metadata is empty, and allow a
0655   prefix/suffix when the entry is substituted in, can help you to make the renaming
0656   procedure more effective.
0657 </para>
0658 </sect1>
0660 <sect1 id="juk-tag-guesser-configuration">
0661 <title>The Tag Guesser Configuration dialog</title>
0662 <para>
0663 <screenshot>
0664 <screeninfo>The Tag Guesser Configuration dialog</screeninfo>
0665         <mediaobject>
0666           <imageobject>
0667             <imagedata fileref="juk-tag-guesser.png" format="PNG"/>
0668           </imageobject>
0669           <textobject>
0670             <phrase>Screenshot of the Tag Guesser Configuration dialog.</phrase>
0671           </textobject>
0672         </mediaobject>
0673 </screenshot>
0674 </para>
0676 <para>The Tag Guesser Configuration dialog is used to configure the
0677 <guilabel>Guess from File Name</guilabel> action.</para>
0679 <para>In the dialog you will see a list on the left of different filename scheme patterns.
0680 &juk; includes an extensive set of defaults patterns to match most common filenaming styles.
0681 If you'd like to add a new scheme, click on the <guibutton>Add</guibutton> button, and type
0682 in your scheme and click on <guibutton>OK</guibutton>.</para>  
0684 <para>Here you can see the currently configured file name schemes which the 
0685 tag editor uses to extract tag information from a 
0686 file name. Each string may contain one of the following placeholders:</para>
0688 <para><itemizedlist>
0689 <listitem><para>%t: Title</para></listitem>
0690 <listitem><para>%A: Album</para></listitem>
0691 <listitem><para>%a: Artist</para></listitem>
0692 <listitem><para>%T: Track</para></listitem>
0693 <listitem><para>%c: Comment</para></listitem>
0694 </itemizedlist>
0695 </para>
0697 <para>For example, the file name scheme <quote>[%T] %a - %t</quote> would match <quote>[01] Deep 
0698 Purple - Smoke on the water</quote> but not <quote>(Deep Purple) Smoke on the water</quote>. 
0699 For that second name, you would use the scheme <quote>(%a) %t</quote>.</para>
0701 <para>&juk; will try the schemes you have listed one at a time, starting at the top of the list.
0702 The first scheme which results in a match will be the scheme used to guess the song's tags.
0703 Some songs may match more than one scheme.  You can make sure that the correct scheme matches
0704 first by selecting the scheme in the list box and then using the arrow buttons to move it to the
0705 top of the list.
0706 </para>
0708 <para>You can also edit or remove a scheme from the list.  Just select the scheme in the list,
0709 and use the <guibutton>Modify</guibutton> button to change the scheme, or the
0710 <guibutton>Remove</guibutton> button to remove the scheme from the list.
0711 </para>
0712 </sect1>
0714 <sect1 id="juk-advanced-search-dialog">
0715 <title>The Advanced Search dialog</title>
0716 <para>
0717 <screenshot>
0718 <screeninfo>The Advanced Search dialog</screeninfo>
0719         <mediaobject>
0720           <imageobject>
0721             <imagedata fileref="juk-adv-search.png" format="PNG"/>
0722           </imageobject>
0723           <textobject>
0724             <phrase>Screenshot of the Advanced Search Dialog.</phrase>
0725           </textobject>
0726         </mediaobject>
0727 </screenshot>
0728 </para>
0730 <para>The Advanced Search dialog is used to create <link linkend="juk-search-playlists">Search
0731 Playlists</link>.  It allows you to make a fine-grained search among the different tags of
0732 your song collection.</para>
0734 <para>At the top of the dialog, you can type in the name of your search playlist.  Then, you
0735 can define your search criteria in the <guilabel>Search Criteria</guilabel> group.
0736 </para>
0738 <para>The top of the <guilabel>Search Criteria</guilabel> group has two radio buttons,
0739 <guilabel>Match any of the following</guilabel> and <guilabel>Match all of the
0740 following</guilabel>.  If you select <guilabel>Match any of the following</guilabel>, then
0741 a match by any of the conditions you define will include the song in the playlist.  Otherwise,
0742 every condition you define must match in order to include the song in the playlist.
0743 </para>
0745 <para>Below the radio buttons are the condition definitions.  You can add more conditions
0746 by using the <guibutton>More</guibutton> button, and remove conditions by using the
0747 <guibutton>Fewer</guibutton> button.  Any conditions you leave blank are ignored, so you do
0748 not have to use <guibutton>Fewer</guibutton> to eliminate empty conditions.
0749 </para>
0751 <para>Every condition definition has three parts:  The tag chooser list on the left, the
0752 matching style list on the right, and the search text in the middle.  The tag chooser
0753 lets &juk; know what tag you want to search for the text in.  If you choose the special
0754 tag "&lt;All Visible&gt;", then any tag that you can see in the Collection List listing
0755 is fair game to match the search text.
0756 </para>
0758 <para>The match style list lets &juk; know which search method to use.
0759 The search methods you can use are as follows:
0760 <variablelist>
0761 <varlistentry>
0762 <term>Normal Matching</term>
0763 <listitem><para>This is the default matching style.  It searches for the given
0764 text anywhere in the chosen tag, ignoring case differences.  For example a
0765 search for mode in the Artist tag would match Depeche Mode.</para></listitem>
0766 </varlistentry>
0768 <varlistentry>
0769 <term>Case Sensitive</term>
0770 <listitem><para>This search is just like Normal Matching, except that
0771 the search must match the exact case of the text.</para></listitem>
0772 </varlistentry>
0774 <varlistentry>
0775 <term>Pattern Matching</term>
0776 <listitem><para>This is the most powerful search method.  The search
0777 text you type in will define a regular expression used to search within
0778 the tag.  Regular expressions are beyond the scope of this documentation, but
0779 the application &kregexpeditor; can help you form a regular expression.
0780 &juk; uses the &Qt; regular expression style.</para></listitem>
0781 </varlistentry>
0783 </variablelist>
0785 </para>
0787 <para>Simply choose the conditions you want to include in your search, and
0788 click <guibutton>OK</guibutton> to create your search playlist!
0789 </para>
0790 </sect1>
0791 <!-- is this still relevant?
0793 write new for kde4
0795 <sect1 id="juk-cover-manager">
0797 <title>The &juk; Cover Manager</title>
0799 <para>&juk; 2.3 (part of &kde; 3.5) includes improved cover management code which introduces some new possibilities for users compared with &juk; 2.2 (which was shipped with &kde; 3.4).  It also can change the workflow slightly for you if you are used to the way covers were handled in &juk; 2.2.  So first, let's review how things used to be.</para>
0801 <sect2 id="covers-in-juk-2.2">
0802 <title>How Covers Worked in &juk; 2.2</title>
0804 <para>In &juk; 2.2, the cover for a track was strictly tied to its <guilabel>Artist</guilabel> and <guilabel>Album</guilabel> information. Although this proved useful enough, and had a few advantages, it wasn't a great way to organize the covers. If you wanted to use a cover for a different track, you either had to rename the tags in the track, or you had to duplicate the cover, wasting hard disk space. And if your track had no <guilabel>Artist</guilabel> or <guilabel>Album</guilabel> information, &juk; would prevent you from setting a cover since it had no information to go by. It worked, but it could be better.</para>
0806 </sect2>
0808 <sect2 id="covers-in-juk-2.3">
0810 <title>How Covers work in &juk; 2.3</title>
0812 <para>In &juk; 2.3, the code was redesigned to add a core component responsible for dealing with cover art.  Instead of looking on disk for a picture file with a specific name like &juk; 2.2, the Cover Manager in &juk; 2.3 associates every cover with an identification tag, and then uses the tag with your music.  It's still not perfect, but it works, and it can save you time while allowing you to do more.</para>
0814 <sect3 id="examples-adding-covers">
0816 <title>Examples of adding covers</title>
0818 <para>So just as an example, let's say you wanted to set a cover for tracks you just ripped off of your &CD;. We'll use <quote>Alabama - Greatest Hits III</quote> for the sake of discussion. In &juk; 2.2, you could simply select any one of those tracks, and import a cover from the Internet by right-clicking on that track, and using the <menuchoice><guimenu>Tagger</guimenu> <guisubmenu>Cover Manager</guisubmenu> <guimenuitem>Get Cover From Internet</guimenuitem></menuchoice> command. As a side effect of the way &juk; worked, the cover would then be immediately applied to <emphasis>all</emphasis> of the <quote>Alabama - Greatest Hits III</quote> tracks, <emphasis>whether you wanted that or not</emphasis>.</para>
0820 <para>In &juk; 2.3, the procedure is exactly the same, with one exception: You should select all of the tracks you want to apply the cover to first. So you would select all the <quote>Alabama - Greatest Hits III</quote> tracks before using the <menuchoice><guimenuitem>Get Cover From Internet</guimenuitem></menuchoice> command. Or if you only wanted to set cover art to half of the tracks for some reason, you'd only select half the tracks before running the <menuchoice><guimenuitem>Get Cover From Internet</guimenuitem></menuchoice> command. Don't worry about duplicating covers, either: &juk; is smart enough to re-use the same image, so you won't get 14 duplicate <literal role="extension">.png</literal> images cluttering your hard drive.</para>
0821 </sect3>
0823 <sect3 id="reusing-old-covers">
0825 <title>Reusing Old Covers</title>
0827 <para>But what happens if you forgot to select all the tracks you wanted to tag? You could select them and repeat the process, but that would leave a duplicate cover on your hard drive because &juk; cannot quickly tell that the cover you've found is the same as one you already have. But that's alright, because you can tell &juk; to use the cover from another track.</para>
0829 <para>There are two ways of doing this:</para>
0831 <para>1. Open the <guilabel>Cover Manager</guilabel> dialog using the <guimenu>Tagger</guimenu> menu (<menuchoice><guimenu>Tagger Cover</guimenu> <guisubmenu>Manager</guisubmenu> <guimenuitem>Show Cover Manager</guimenuitem></menuchoice>). The Cover Manager will display a list of all the covers &juk; knows about on the right, and after they have loaded you can quickly pare the list down using the search line at the top, or by using the list of Artists on the left. Once you see the cover you want to use, you can drag-and-drop the cover onto a track to apply it. It should happen nearly instantaneously since &juk; is reusing the same cover (and you'll see the cover while you're dragging it as well). Unfortunately, it can take awhile to load the covers in the first place, and the Cover Manager isn't really useful for much else besides.</para>
0833 <para>2. I prefer to use this method because it's rather easy. All you do is double-click on the track that has the cover you want, in order to start it playing. This will cause its cover to show up in the <interface>Now Playing bar</interface>, and you can drag-and-drop the cover to the track you want to change exactly as you would for the Cover Manager.</para>
0835 </sect3>
0837 <sect3 id="dragging-covers">
0839 <title>Dragging covers to more than one track at once</title>
0841 <para>Also note that you can use drag-and-drop to quickly apply covers to more than one track. Just select the tracks you want to apply a cover to, and drag the cover onto any one of the selected tracks.</para>
0842 </sect3>
0844 <sect3 id="old-covers">
0846 <title>What happens to my old covers?</title>
0848 <para>You may be wondering what &juk; will do if you already have covers from &juk; 2.2.  What happens is that &juk; will automatically convert the old covers and merge them into the cover management system.</para>
0850 <para>Because this is a time consuming process, it does not happen all at once.  Instead, the old cover is only converted when the cover needs to be shown on screen.  As the conversion process is happening, &juk; will recognize what tracks would have shown the cover being converted, and will automatically apply the new cover to those tracks.  The end result is that there should be no visible changes: &juk; will keep the same cover on your tracks that they've always had, except that now you can immediately take advantage of the new cover management features.</para>
0852 </sect3>
0853 <sect3 id="removing-covers">
0855 <title>Removing Covers</title>
0857 <para>Another side effect is that you can now remove a cover from a track without simultaneously removing it from all other tracks with the same <guilabel>Artist</guilabel> and <guilabel>Album</guilabel>.</para>
0859 <para>In &juk; 2.3, the Remove Cover command now only removes the covers from the selected tracks.
0860 </para>
0862 </sect3>
0863 <sect3 id="suggested-use">
0865 <title>Suggested Uses:</title>
0867 <para>1. You can now apply the same cover to tracks with Albums that have <quote>Disc 1</quote>, <quote>Disc 2</quote>, etc, which you couldn't do in &juk; 2.2 without duplicating the cover.</para>
0869 <para>
0870 2. Applying a generic cover to tracks if you simply must have a cover on every track, or if you have music that wasn't released as an album but fits a genre well.  You could make yourself a cover for that type of music and apply it to the songs in question.</para>
0872 </sect3>
0873 </sect2>
0874 </sect1>
0875 -->
0876 </chapter>
0878 <chapter id="toolbar-reference">
0879 <title>The &juk; Toolbar</title>
0881 <sect1 id="main-toolbar">
0882 <title>The Main Toolbar</title>
0884 <screenshot>
0885 <screeninfo>The &juk; toolbar.</screeninfo>
0886 <mediaobject>
0887 <imageobject>
0888 <imagedata format="PNG" fileref="toolbar.png" />
0889 </imageobject>
0890 <textobject>
0891 <phrase>The &juk; toolbar.</phrase>
0892 </textobject>
0893 <caption><para>The &juk; toolbar.</para></caption>
0894 </mediaobject>
0895 </screenshot>
0897 <para>From left to right in the screenshot above, the icons on the
0898 default toolbar are:</para>
0900 <variablelist>
0901 <varlistentry>
0902 <term><guiicon>New</guiicon></term>
0903 <listitem><para>Create a new playlist.  If you hold down the button, a
0904 menu will pop up allowing you to select the different kinds of playlists
0905 to create.
0906 </para>
0907   <variablelist>
0908   <varlistentry><term><guimenuitem>Empty Playlist...</guimenuitem></term>
0909   <listitem><para>This prompts you for a playlist name, and then inserts it into the
0910     Playlist view.  The playlist starts out completely empty.</para></listitem>
0911   </varlistentry>
0913   <varlistentry><term><guimenuitem>Playlist From Folder...</guimenuitem></term>
0914   <listitem><para>This prompts you for a folder to open, and then creates a playlist
0915     containing the music within the folder and any sub-folders.  The name of the created
0916     playlist is the same as the name of the selected folder.</para></listitem>
0917   </varlistentry>
0919   <varlistentry><term><guimenuitem>Search Playlist...</guimenuitem></term>
0920   <listitem><para>This brings up the Advanced Search Dialog, allowing you to create a
0921   <quote>virtual playlist</quote>.  Any songs in your Collection List that match the search
0922   criteria that you specify in the Advanced Search Dialog will be added to the new playlist.
0923   As your Collection List changes, the new playlist will as well.  For example, if you create a playlist
0924   of all of your Depeche Mode songs, and then add another Depeche Mode song to your Collection List,
0925   it will show up in the Depeche Mode playlist with no special action required on your part.
0926   </para></listitem>
0927   </varlistentry>
0929   </variablelist>
0930 </listitem>
0931 </varlistentry>
0933 <varlistentry>
0934 <term><guiicon>Open</guiicon></term>
0935 <listitem><para>Add a file to the collection list (if it's active) or
0936 to the currently selected playlist.  Adding a file to a playlist will
0937 add it to the collection list automatically, but not vice
0938 versa.</para></listitem>
0939 </varlistentry>
0941 <varlistentry>
0942 <term><guiicon>Save</guiicon></term>
0943 <listitem><para>Save the currently selected playlist.  To save a tag
0944 you have edited, either select another item, or press <keycombo
0945 action="simul">&Ctrl;<keycap>T</keycap></keycombo>
0946 instead.</para></listitem>
0947 </varlistentry>
0949 <varlistentry>
0950 <term><guiicon>Cut</guiicon></term>
0951 <listitem><para>If a playlist or song is selected, cut (remove) it from the
0952 list.  If the tag editor is active, this works like cut in any editor,
0953 removing the selected text, but keeping a copy on the
0954 clipboard.</para></listitem>
0955 </varlistentry>
0957 <varlistentry>
0958 <term><guiicon>Copy</guiicon></term>
0959 <listitem><para>If the tag editor is active, this works like copy in
0960 any editor, placing a copy of the selected text on the
0961 clipboard.</para>
0962 <para>If you use copy on a song in the collection list, the url is
0963 placed on the clipboard, so you can paste it.  For example, you could
0964 paste the url into a text editor, &konqueror;, or another
0965 playlist.</para></listitem>
0966 </varlistentry>
0968 <varlistentry>
0969 <term><guiicon>Paste</guiicon></term>
0970 <listitem><para>If you previously either cut or copied a url from the
0971 collection list, you can paste the url back into a new playlist.  You
0972 could also paste a url you have copied from &konqueror; or any other
0973 application. If you are operating in the tag editor, paste will paste
0974 any text currently on the clipboard into the selected
0975 field.</para></listitem>
0976 </varlistentry>
0978 <varlistentry>
0979 <term><guiicon>Show Search Bar</guiicon></term>
0980 <listitem><para>Show or hide <link linkend="search-bar">the search
0981 bar</link>.</para></listitem>
0982 </varlistentry>
0984 <varlistentry>
0985 <term><guiicon>Show Tag Editor</guiicon></term>
0986 <listitem><para>Show or hide <link linkend="tagging-a-single-file">the
0987 tag editor</link>.</para></listitem>
0988 </varlistentry>
0990 <varlistentry id="play-toolbar">
0991 <term>Play controls</term>
0992 <listitem>
0993 <para>These work like any standard media player you may have come
0994 across.  The controls are <guiicon>Play</guiicon>,
0995 <guiicon>Pause</guiicon>, <guiicon>Stop</guiicon>, <guiicon>Previous
0996 </guiicon> and <guiicon>Next</guiicon>.</para>
0997 <para>There is also a tracking bar, showing how far along (relatively)
0998 in the current song you are.  You can drag this slider with the mouse
0999 in order to skip forwards or backwards within a track.</para>
1000 <para>Finally there is a volume slider.  As you may expect, this
1001 raises and lowers the volume.  <quote>Loud</quote> is on the right,
1002 and <quote>Quiet</quote> is on the left.</para></listitem>
1003 </varlistentry>
1004 </variablelist>
1006 </sect1>
1008 <sect1 id="search-bar">
1009 <title>The Search bar</title>
1011 <para>The search bar allows you to quickly search for a song in the
1012 collection list or a playlist.</para>
1014 <para>Simply typing text into the search bar will reduce the visible
1015 list of songs to those which contain that text in any visible
1016 column.  Pressing &Enter; will start playing the top match in the playlist view.</para>
1018 <para>Searching begins instantly when text is entered into the search
1019 field.  Searching is incremental, that is, as you type each character
1020 into the text field, the search is narrowed further.  This is useful
1021 to find a song where you only remember part of a name, for
1022 instance.</para>
1024 <!-- Not here in KDE 4.11
1025 <para>If you would like to make a more fine-grained search, you can click
1026 the Advanced Search button to the right of the search bar, which will allow
1027 you to create a virtual playlist.  If you would like to cancel the search,
1028 you can simply click on the Clear button to the left of the search bar.</para>
1029 -->
1031 </sect1>
1033 </chapter>
1035 <chapter id="menu-and-command-reference">
1036 <title>Menu and Command Reference</title>
1038 <sect1 id="menus">
1039 <title>Menus</title>
1041 <sect2 id="menu-file">
1042 <title>File Menu</title>
1044 <variablelist>
1045 <varlistentry>
1046 <term><menuchoice>
1047 <shortcut><keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
1048 </shortcut>
1049 <guimenu>File</guimenu><guisubmenu>New</guisubmenu><guimenuitem>Empty Playlist...</guimenuitem>
1050 </menuchoice>
1051 </term>
1052 <listitem><para>Create a new playlist</para>
1053 </listitem>
1054 </varlistentry>
1056 <varlistentry>
1057 <term><menuchoice>
1058 <shortcut><keycombo action="simul">&Ctrl;<keycap>F</keycap></keycombo>
1059 </shortcut>
1060 <guimenu>File</guimenu><guisubmenu>New</guisubmenu><guimenuitem>Search Playlist...</guimenuitem>
1061 </menuchoice>
1062 </term>
1063 <listitem><para>Creates a new <link linkend="juk-search-playlists">search playlist</link>.</para>
1064 </listitem>
1065 </varlistentry>
1067 <varlistentry>
1068 <term><menuchoice>
1069 <shortcut><keycombo action="simul">&Ctrl;<keycap>D</keycap></keycombo>
1070 </shortcut>
1071 <guimenu>File</guimenu><guisubmenu>New</guisubmenu><guimenuitem>Playlist From
1072 Folder...</guimenuitem>
1073 </menuchoice>
1074 </term>
1075 <listitem><para>Creates a new playlist, containing all music files
1076 in a folder and any sub-folders.  Any music within playlists files that
1077 &juk; recognizes will also be added.</para>
1078 </listitem>
1079 </varlistentry>
1081 <varlistentry>
1082 <term><menuchoice>
1083 <shortcut>
1084 <keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo>
1085 </shortcut>
1086 <guimenu>File</guimenu>
1087 <guimenuitem>Open...</guimenuitem>
1088 </menuchoice>
1089 </term>
1090 <listitem><para>Select a file (or files) to add to the collection list.  If you select
1091 a playlist file, every file in the playlist will be added.</para>
1092 </listitem>
1093 </varlistentry>
1095 <varlistentry>
1096 <term><menuchoice>
1097 <guimenu>File</guimenu><guimenuitem>Manage Folders...</guimenuitem>
1098 </menuchoice>
1099 </term>
1100 <listitem><para>This menu item opens the same window that is shown on a first &juk; start
1101 </para>
1102 <para>Select a folder (or folders) to add to the
1103 collection list.  These folders will also be rescanned whenever
1104 &juk; is started or
1105 <menuchoice><guimenu>File</guimenu><guimenuitem>Reload</guimenuitem>
1106 </menuchoice> is chosen.</para>
1107 <para>You can also select folders that
1108 should not be automatically searched (which would override
1109 the list of folders to scan on startup). This way you can avoid having
1110 to completely change up your music layout on-disk just to keep &juk; from
1111 automatically grabbing songs you do not want or need managed from within
1112 &juk;.
1113 </para>
1114 <para>
1115 <screenshot>
1116 <screeninfo>The Manage Folders dialog</screeninfo>
1117         <mediaobject>
1118           <imageobject>
1119             <imagedata fileref="juk-manage-folders.png" format="PNG"/>
1120           </imageobject>
1121           <textobject>
1122             <phrase>Screenshot of the Manage Folders Dialog.</phrase>
1123           </textobject>
1124         </mediaobject>
1125 </screenshot>
1126 </para>
1127 <note>
1128 <para>
1129 If you want to remove files that are already in the collection
1130 list, you can enable the <guilabel>File Name (full path)</guilabel> column in a playlist
1131 and then use the search bar to find the offending path name, select and remove
1132 the files that are shown.
1133 </para>
1134 </note>
1135 </listitem>
1136 </varlistentry>
1138 <varlistentry>
1139 <term><menuchoice>
1140 <guimenu>File</guimenu>
1141 <guimenuitem>Rename...</guimenuitem></menuchoice>
1142 </term>
1143 <listitem><para>Rename a playlist.</para>
1144 </listitem>
1145 </varlistentry>
1147 <!-- Edit Search... -->
1148 <varlistentry>
1149 <term><menuchoice>
1150 <guimenu>File</guimenu><guimenuitem>Duplicate...</guimenuitem></menuchoice>
1151 </term>
1152 <listitem><para>Create a duplicate of the selected playlist, and
1153 prompt for a new name.
1154 </para>
1155 </listitem>
1156 </varlistentry>
1158 <varlistentry>
1159 <term><menuchoice>
1160 <guimenu>File</guimenu><guimenuitem>Reload</guimenuitem></menuchoice>
1161 </term>
1162 <listitem><para>Reloads the tag information on every file in the selected
1163 playlist.
1164 </para>
1165 </listitem>
1166 </varlistentry>
1168 <varlistentry>
1169 <term><menuchoice><guimenu>File</guimenu><guimenuitem>Remove</guimenuitem></menuchoice></term>
1170 <listitem><para>Remove the selected playlist.</para></listitem>
1171 </varlistentry>
1173 <varlistentry>
1174 <term><menuchoice>
1175 <shortcut><keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo>
1176 </shortcut>
1177 <guimenu>File</guimenu><guimenuitem>Save</guimenuitem>
1178 </menuchoice>
1179 </term>
1180 <listitem><para>Save the selected playlist.</para>
1181 </listitem>
1182 </varlistentry>
1184 <varlistentry>
1185 <term><menuchoice>
1186 <guimenu>File</guimenu><guimenuitem>Save As...</guimenuitem>
1187 </menuchoice>
1188 </term>
1189 <listitem><para>Save the selected playlist, with a different name.</para>
1190 </listitem>
1191 </varlistentry>
1193 </variablelist>
1194 </sect2>
1196 <sect2 id="menu-edit">
1197 <title>Edit Menu</title>
1199 <variablelist>
1201 <varlistentry>
1202 <term><menuchoice>
1203 <guimenu>Edit</guimenu><guimenuitem>Clear</guimenuitem>
1204 </menuchoice>
1205 </term>
1206 <listitem><para>Removes the selected songs from the playlist.</para>
1207 </listitem>
1208 </varlistentry>
1209 <!-- Undo Cut Copy Paste Clear Select All -->
1210 </variablelist>
1211 </sect2>
1213 <sect2 id="menu-view">
1214 <title>View Menu</title>
1216 <variablelist>
1217 <varlistentry>
1218 <term><menuchoice>
1219 <guimenu>View</guimenu><guimenuitem>Show Search Bar</guimenuitem>
1220 </menuchoice>
1221 </term>
1222 <listitem><para>This is a toggle action that sets whether or not the
1223 <link linkend="search-bar">Search Bar</link> is shown.</para>
1224 </listitem>
1225 </varlistentry>
1227 <varlistentry>
1228 <term><menuchoice>
1229 <guimenu>View</guimenu><guimenuitem>Show Tag Editor</guimenuitem>
1230 </menuchoice>
1231 </term>
1232 <listitem><para>This is a toggle action that sets whether or not the
1233 <interface>Tag Editor</interface> is shown.</para>
1234 </listitem>
1235 </varlistentry>
1236 <!--Show Lyrics-->
1237 <varlistentry>
1238 <term><menuchoice>
1239 <guimenu>View</guimenu><guimenuitem>Show History</guimenuitem>
1240 </menuchoice>
1241 </term>
1242 <listitem><para>This is a toggle action that sets whether or not the
1243 <link linkend="juk-history-playlists">History Playlist</link> is shown.</para>
1244 </listitem>
1245 </varlistentry>
1247 <!-- missing
1248 Show Play Queue
1249 Show Columns
1250 Resize Playlist Columns Manually
1251 -->
1252 <varlistentry>
1253 <term><menuchoice>
1254 <guimenu>View</guimenu><guisubmenu>View Modes</guisubmenu><guimenuitem>Default</guimenuitem>
1255 </menuchoice>
1256 </term>
1257 <listitem><para>Switches to <link linkend="juk-viewmode-default">Default View mode</link>.
1258 </para>
1259 </listitem>
1260 </varlistentry>
1262 <varlistentry>
1263 <term><menuchoice>
1264 <guimenu>View</guimenu><guisubmenu>View Modes</guisubmenu><guimenuitem>Compact</guimenuitem>
1265 </menuchoice>
1266 </term>
1267 <listitem><para>Switches to <link linkend="juk-viewmode-compact">Compact View mode</link>.
1268 </para>
1269 </listitem>
1270 </varlistentry>
1272 <varlistentry>
1273 <term><menuchoice>
1274 <guimenu>View</guimenu><guisubmenu>View Modes</guisubmenu><guimenuitem>Tree</guimenuitem>
1275 </menuchoice>
1276 </term>
1277 <listitem><para>Switches to <link linkend="juk-viewmode-tree">Tree View mode</link>.
1278 </para>
1279 </listitem>
1280 </varlistentry>
1282 </variablelist>
1283 </sect2>
1285 <sect2 id="menu-player">
1286 <title>Player Menu</title>
1288 <variablelist>
1289 <varlistentry>
1290 <term><menuchoice>
1291 <guimenu>Player</guimenu><guimenuitem>Random Play</guimenuitem>
1292 </menuchoice>
1293 </term>
1294 <listitem><para>This is a toggle option which controls the Random Play setting.
1295 If Random Play is enabled, then &juk; will randomly select a random song from the
1296 current playlist when the currently playing song is over.</para>
1297 </listitem>
1298 </varlistentry>
1300 <varlistentry>
1301 <term><menuchoice>
1302 <guimenu>Player</guimenu><guimenuitem>Loop Playlist</guimenuitem>
1303 </menuchoice>
1304 </term>
1305 <listitem><para>This is a toggle option which controls the Loop Playlist setting.
1306 If Loop Playlist is enabled, then &juk; will start playing from the beginning when
1307 it has finished playing every song in the current playlist.</para>
1308 </listitem>
1309 </varlistentry>
1310 <!--
1311 Crossfade Between Tracks
1312 -->
1313 <varlistentry>
1314 <term><menuchoice>
1315 <guimenu>Player</guimenu><guimenuitem>Play</guimenuitem>
1316 </menuchoice>
1317 </term>
1318 <listitem><para>This command starts playing the currently selected song, or resumes
1319 playback of the song if it was paused.</para>
1320 </listitem>
1321 </varlistentry>
1323 <varlistentry>
1324 <term><menuchoice>
1325 <guimenu>Player</guimenu><guimenuitem>Pause</guimenuitem>
1326 </menuchoice>
1327 </term>
1328 <listitem><para>This command pauses the currently playing song.  Use the
1329 Play command to restart playback.</para>
1330 </listitem>
1331 </varlistentry>
1333 <varlistentry>
1334 <term><menuchoice>
1335 <guimenu>Player</guimenu><guimenuitem>Stop</guimenuitem>
1336 </menuchoice>
1337 </term>
1338 <listitem><para>This command stops the playback of the currently playing song.
1339 You cannot resume playback from its current position after that.</para>
1340 </listitem>
1341 </varlistentry>
1343 <varlistentry>
1344 <term><menuchoice>
1345 <guimenu>Player</guimenu><guimenuitem>Next</guimenuitem>
1346 </menuchoice>
1347 </term>
1348 <listitem><para>This command skips to the next song to play in the
1349 playlist.</para>
1350 </listitem>
1351 </varlistentry>
1353 <varlistentry>
1354 <term><menuchoice>
1355 <guimenu>Player</guimenu><guimenuitem>Previous</guimenuitem>
1356 </menuchoice>
1357 </term>
1358 <listitem><para>This command plays the song that was playing before
1359 the currently playing song.</para>
1360 </listitem>
1361 </varlistentry>
1362 <!--
1363 Play Next Album
1364 -->
1365 </variablelist>
1366 </sect2>
1368 <sect2 id="menu-tagger">
1369 <title>Tagger Menu</title>
1371 <variablelist>
1373 <varlistentry>
1374 <term><menuchoice>
1375 <shortcut><keycombo action="simul">&Ctrl;<keycap>T</keycap></keycombo></shortcut>
1376 <guimenu>Tagger</guimenu><guimenuitem>Save</guimenuitem>
1377 </menuchoice>
1378 </term>
1379 <listitem><para>This command saves any changes to the tags that you are
1380 editing.  Normally, changes are not saved until you deselect the file you
1381 are editing.</para>
1382 </listitem>
1383 </varlistentry>
1385 <varlistentry>
1386 <term><menuchoice>
1387 <guimenu>Tagger</guimenu><guimenuitem>Delete</guimenuitem>
1388 </menuchoice>
1389 </term>
1390 <listitem><para>This command deletes the currently selected files from
1391 the Collection List and any playlists containing it, and then deletes
1392 the selected file from the disk.
1393 <!-- God this is a dumb place to put this particular command --></para>
1394 </listitem>
1395 </varlistentry>
1397 <varlistentry>
1398 <term><menuchoice>
1399 <guimenu>Tagger</guimenu><guimenuitem>Refresh</guimenuitem>
1400 </menuchoice>
1401 </term>
1402 <listitem><para>This command allows you to refresh playlist tags after
1403 changing them.
1404 </para>
1405 </listitem>
1406 </varlistentry>
1408 <varlistentry>
1409 <term><menuchoice>
1410 <shortcut><keycombo action="simul">&Ctrl;<keycap>G</keycap></keycombo></shortcut>
1411 <guimenu>Tagger</guimenu><guisubmenu>Guess Tag
1412 Information</guisubmenu><guimenuitem>From Filename</guimenuitem>
1413 </menuchoice>
1414 </term>
1415 <listitem><para>This command tries to guess the tags of the selected files
1416 by scanning the filename.  You can configure the patterns used for guessing
1417 by selecting <menuchoice><guimenu>Settings</guimenu>
1418 <guimenuitem>Tag Guesser...</guimenuitem></menuchoice>, which opens the
1419 <link linkend="juk-tag-guesser-configuration">Tag Guesser Configuration dialog</link>.</para>
1420 </listitem>
1421 </varlistentry>
1423 <varlistentry>
1424 <term><menuchoice>
1425 <shortcut><keycombo action="simul">&Ctrl;<keycap>I</keycap></keycombo></shortcut>
1426 <guimenu>Tagger</guimenu><guisubmenu>Guess Tag
1427 Information</guisubmenu><guimenuitem>From Internet</guimenuitem>
1428 </menuchoice>
1429 </term>
1430 <listitem><para>This command tries to guess the tags of the selected files
1431 by using the <application>TunePimp</application> library provided with
1432 <ulink url="http://www.musicbrainz.org/">MusicBrainz</ulink>.</para>
1433 </listitem>
1434 </varlistentry>
1435 <!--missing
1436 Cover Manager
1437   -->
1438 <varlistentry>
1439 <term><menuchoice>
1440 <shortcut><keycombo action="simul">&Ctrl;<keycap>R</keycap></keycombo></shortcut>
1441 <guimenu>Tagger</guimenu><guimenuitem>Rename File</guimenuitem>
1442 </menuchoice>
1443 </term>
1444 <listitem>
1445   <para>
1446     This command allows you to rename a file or a group of files for the selected songs in the playlist.
1447     Before the real rename happens &juk; will show a preview dialog where you can confirm or cancel the action.
1448   </para>
1449   <para>
1450     The files will be renamed according to the parameters defined using <link linkend="juk-rename-dialog">Rename File dialog</link>.
1451   </para> 
1452 </listitem>
1453 </varlistentry>
1454 </variablelist>
1456 </sect2>
1458 <sect2 id="menu-settings">
1459 <title>Settings Menu</title>
1461 <variablelist>
1463 <varlistentry>
1464 <term><menuchoice>
1465 <guimenu>Settings</guimenu><guisubmenu>Toolbars Shown</guisubmenu>
1466 <guimenuitem>Main / Play Toolbar</guimenuitem> 
1467 </menuchoice>
1468 </term>
1469 <listitem><para>These commands show or hide the <link linkend="main-toolbar">Main
1470 Toolbar</link> and the <link linkend="play-toolbar">Play Toolbar</link>.</para>
1471 </listitem>
1472 </varlistentry>
1474 <varlistentry>
1475 <term><menuchoice>
1476 <guimenu>Settings</guimenu>
1477 <guimenuitem>Dock in System Tray</guimenuitem>
1478 </menuchoice>
1479 </term>
1480 <listitem><para>This is a toggle option.  If enabled, &juk; will display an
1481 icon in your system tray.  You can use the system
1482 tray icon to tell if &juk; is playing, and control playback.</para>
1483 </listitem>
1484 </varlistentry>
1486 <varlistentry>
1487 <term><menuchoice>
1488 <guimenu>Settings</guimenu>
1489 <guimenuitem>Stay in System Tray on Close</guimenuitem>
1490 </menuchoice>
1491 </term>
1492 <listitem><para>This is a toggle option.  If enabled, &juk; will remain
1493   running if you close the main window.  The <guimenuitem>Dock in System Tray</guimenuitem> option must
1494 also be enabled.  To quit &juk;, use the <menuchoice><guimenu>File</guimenu>
1495 <guimenuitem>Quit</guimenuitem></menuchoice> command from the main window, or
1496 the <guimenuitem>Quit</guimenuitem> command from the system tray's context
1497 menu.</para>
1498 <para>
1499 If &juk; is started up when it is set to dock in the system tray on startup
1500 a simple notification will be shown (as otherwise the user may wonder why &juk;
1501 window did not open up). It is possible to remove this additional
1502 notification by going to <menuchoice><guimenu>Common Appearance and Behavior</guimenu>
1503 <guimenuitem>Application and System Notifications</guimenuitem></menuchoice> in
1504 &systemsettings; to manage <guilabel>JuK music player</guilabel> application notifications.
1505 Just uncheck <guilabel>Show a message in a popup</guilabel> item for <guimenuitem>JuK running
1506 in dock mode</guimenuitem>. More information on &kde; notification settings can be found
1507 <ulink url="help:/kcontrol/kcmnotify">here</ulink>.
1508 </para>
1509 </listitem>
1510 </varlistentry>
1512 <varlistentry>
1513 <term><menuchoice>
1514 <guimenu>Settings</guimenu>
1515 <guimenuitem>Popup Track Announcement</guimenuitem>
1516 </menuchoice>
1517 </term>
1518 <listitem><para>This is a toggle option.  If enabled, &juk; will display
1519 an indicator whenever a song starts playing, with information on the artist and
1520 title, and with buttons allowing you to quickly switch to a different song.  The
1521 Dock in System Tray option must also be enabled.</para>
1522 </listitem>
1523 </varlistentry>
1525 <varlistentry>
1526 <term><menuchoice>
1527 <guimenu>Settings</guimenu>
1528 <guimenuitem>Tag Guesser...</guimenuitem>
1529 </menuchoice>
1530 </term>
1531 <listitem><para>This command brings up the <link linkend="juk-tag-guesser-configuration">Tag Guesser Configuration
1532 dialog box</link>, where you can alter the patterns used to guess tag information
1533 from filenames.</para>
1534 </listitem>
1535 </varlistentry>
1537 <varlistentry>
1538 <term><menuchoice>
1539 <guimenu>Settings</guimenu>
1540 <guimenuitem>File Renamer...</guimenuitem>
1541 </menuchoice>
1542 </term>
1543 <listitem><para>This command brings up the <link linkend="juk-rename-dialog">File Renamer Configuration
1544 dialog box</link>, where you can alter the way &juk; renames files for you.</para>
1545 </listitem>
1546 </varlistentry>
1547 <!--missing
1548 Configure scrobbling
1549   -->
1550 </variablelist>
1552 <para>
1553 Additionally &juk; has the common &kde; <guimenu>Settings</guimenu> and <guimenu>Help</guimenu>
1554 menu items, for more information read the sections about the
1555 <ulink url="help:/fundamentals/menus.html#menus-settings">Settings Menu</ulink> and
1556 <ulink url="help:/fundamentals/menus.html#menus-help">Help Menu</ulink> of the &kde; Fundamentals.
1557 </para>
1559 </sect2>
1561 </sect1>
1563 <sect1 id="keybindings">
1564 <title>Keybinding Reference</title>
1566 <!--
1567 ctrl-a select all
1568 ctrl-c copy
1569 ctrl-r rename file
1570 ctrl-i guess tag entries from internet
1571 ctrl-f guess tag entries based on filename
1572 ctrl-f new search playlist
1573 ctrl-n new empty playlist
1574 ctrl-d new playlist from folder
1575 ctrl-o open file (add to the collection or a playlist)
1576 ctrl-q quit
1577 ctrl-s save
1578 ctrl-t save edited tag information
1579 ctrl-v paste
1580 ctrl-x cut
1581 f1 Show manual
1582 shift-f1 what's this help
1584 -->
1585 <informaltable>
1586 <tgroup cols="2">
1587 <thead>
1588 <row>
1589 <entry>Key Combination</entry>
1590 <entry>Action</entry>
1591 </row>
1592 </thead>
1593 <tbody>
1594 <row>
1595 <entry><keycombo
1596 action="simul">&Ctrl;<keycap>A</keycap></keycombo></entry>
1597 <entry>Select all</entry>
1598 </row>
1599 <row>
1600 <entry><keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo></entry>
1601 <entry>Copy</entry>
1602 </row>
1603 <row>
1604 <entry><keycombo
1605 action="simul">&Ctrl;<keycap>R</keycap></keycombo></entry>
1606 <entry>Rename file</entry>
1607 </row>
1608 <row>
1609 <entry><keycombo
1610 action="simul">&Ctrl;<keycap>I</keycap></keycombo></entry>
1611 <entry>Guess tags from the Internet.</entry>
1612 </row>
1613 <row>
1614 <entry><keycombo
1615 action="simul">&Ctrl;<keycap>G</keycap></keycombo></entry>
1616 <entry>Guess tags from the filename.</entry>
1617 </row>
1618 <row>
1619 <entry><keycombo
1620 action="simul">&Ctrl;<keycap>F</keycap></keycombo></entry>
1621 <entry>New <link linkend="juk-search-playlists">search playlist</link>.</entry>
1622 </row>
1623 <row>
1624 <entry><keycombo
1625 action="simul">&Ctrl;<keycap>N</keycap></keycombo></entry>
1626 <entry>New empty Playlist</entry>
1627 </row>
1628 <row>
1629 <entry><keycombo
1630 action="simul">&Ctrl;<keycap>D</keycap></keycombo></entry>
1631 <entry>New playlist from folder.</entry>
1632 </row>
1633 <row>
1634 <entry><keycombo
1635 action="simul">&Ctrl;<keycap>T</keycap></keycombo></entry>
1636 <entry>Save changes to edited tags.</entry>
1637 </row>
1638 </tbody>
1639 </tgroup>
1640 </informaltable>
1642 </sect1>
1643 </chapter>
1645 <chapter id="credits-and-license">
1646 <title>Credits and License</title>
1648 <para>&juk; Copyright &copy; 2002-2013 &Scott.Wheeler;, Michael Pyne, and others.
1649 </para>
1651  <para>&juk; is developed and maintained by &Scott.Wheeler;
1652 &Scott.Wheeler.mail; and Michael Pyne <email>michael.pyne@kdemail.net</email>.</para>
1654 <para>Many thanks to the following people who have contributed to &juk;:</para>
1656 <itemizedlist>
1657 <listitem><para>&Daniel.Molkentin; &Daniel.Molkentin.mail; for system tray docking, <quote>inline</quote> tag
1658 editing, bug fixes, evangelism, moral support.</para>
1659 </listitem>
1660 <listitem><para>Tim Jansen <email>tim@tjansen.de</email> for
1661 the <application>GStreamer</application> port</para>
1662 </listitem>
1664 <listitem><para>Stefan Asserh&auml;ll <email>stefan.asserhall@telia.com</email>
1665 for global shortcut support.</para>
1666 </listitem>
1668 <listitem><para>Stephen Douglas <email>stephen_douglas@yahoo.com</email>
1669 for track announcement popups.</para>
1670 </listitem>
1672 <listitem><para>&Frerich.Raabe; &Frerich.Raabe.mail;
1673 for automagical track data guessing, and bugfixes.</para>
1674 </listitem>
1676 <listitem><para>Zack Rusin <email>zack@kde.org</email>
1677 for more automagical things, including MusicBrainz support.</para>
1678 </listitem>
1680 <listitem><para>Adam Treat <email>manyoso@yahoo.com</email>
1681 for co-conspiring in MusicBrainz wizardry.</para>
1682 </listitem>
1684 <listitem><para>Matthias Kretz <email>kretz@kde.org</email>
1685 for being the friendly neighborhood &arts; guru.</para>
1686 </listitem>
1688 <listitem><para>Maks Orlovich <email>maksim@kde.org</email>
1689 for making &juk; friendlier to people with terabytes of music.</para>
1690 </listitem>
1692 <listitem><para>Antonio Larrosa Jimenez <email>larrosa@kde.org</email>
1693 for the &DCOP; interface.</para>
1694 </listitem>
1696 <listitem><para>Allan Sandfield Jensen <email>kde@carewolf.com</email>
1697 for the <acronym>FLAC</acronym> and <acronym>MPC</acronym> support.</para>
1698 </listitem>
1700 <listitem><para>Nathan Toone <email>nathan@toonetown.com</email>
1701 for the Album cover manager.</para>
1702 </listitem>
1704 <listitem><para>Pascal Klein <email>4pascal@tpg.com.au</email>
1705 for the splash screen.</para>
1706 </listitem>
1708 <listitem><para>Laurent Montel <email>montel@kde.org</email>
1709 for the porting to &kde; 4 when no one else around.</para>
1710 </listitem>
1712 <listitem><para>Georg Grabler <email>georg@grabler.net</email>
1713 for the &kde; Platform porting efforts.</para>
1714 </listitem>
1716 <listitem><para>Martin Sandsmark <email>martin.sandsmark@kde.org</email>
1717 for the Last.fm scrobbling support, lyrics, prepping for &kde; Frameworks.</para>
1718 </listitem>
1720 <listitem><para>Eike Hein <email>hein@kde.org</email>
1721 for the MPRIS2 interface implementation.</para>
1722 </listitem>
1724 </itemizedlist>
1726 <para>Documentation Copyright &copy; 2003, &Lauri.Watts;, and copyright
1727 &copy; 2004-2013 Michael Pyne.</para>
1731 &underFDL;
1732 &underGPL;
1734 </chapter>
1736 &documentation.index;
1738 </book>
1739 <!--
1740 Local Variables:
1741 mode: sgml
1742 sgml-minimize-attributes:nil
1743 sgml-general-insert-case:lower
1744 sgml-indent-step:0
1745 sgml-indent-data:nil
1746 End:
1747 -->