<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY package "kdemultimedia">
  <!ENTITY kappname "&juk;">
  <!ENTITY juk "<application>JuK</application>">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE">
]>

<book lang="&language;">

<bookinfo>
<title>The &juk; Handbook</title>

<authorgroup>
<author>&Lauri.Watts; &Lauri.Watts.mail;</author>

<othercredit role="developer">
<firstname>Scott</firstname>
<surname>Wheeler</surname>
<affiliation>
<address><email>wheeler@kde.org</email></address>
</affiliation>
</othercredit>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

</authorgroup>

<copyright>
<year>2001</year>
<year>2002</year>
<holder>Scott Wheeler</holder>
</copyright>
<legalnotice>&FDLNotice;</legalnotice>

<date>12/07/2002</date>
<releaseinfo>1.0</releaseinfo>

<abstract>
<para>
&juk; is a jukebox, tagger and music collection manager.
</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>kdemultimedia</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<para>
&juk; is well, a jukebox.  As is typical with many jukebox
applications, &juk; allows you to edit the <quote>tags</quote> of the
audio files, and manage your collection and playlists.
</para>
</chapter>

<chapter id="using-juk">
<title>Using &juk;</title>

<!--

<para>
<screenshot>
<screeninfo>Here's a screenshot of &juk;</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="screenshot.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>Screenshot</phrase>
	  </textobject>
	</mediaobject>
</screenshot>
</para>

-->

<para>&juk; maintains a list of all files that it knows about.  This
is called the <guilabel>Collection List</guilabel>.  The collection
list is specific to &juk; and is not shared with other
applications.</para>

<para>Independent of the Collection List, are playlists.  You can have
as many playlists as you want. You can use &juk; created playlists
with other media players (such as &noatun; or
<application>xmms</application>) and you can manage playlists created
in those applications from within &juk;.</para>

<para>You can add files to the Collection List individually, using
<menuchoice><guimenu>File</guimenu><guimenuitem>Open
File...</guimenuitem></menuchoice> and selecting them from a standard
&kde; file dialog.  You can add entire folders using
<menuchoice><guimenu>File</guimenu><guimenuitem>Open
Folder...</guimenuitem></menuchoice>.  Folders added this way
will be rescanned every time you start &juk; and <!-- ask scott -->
whenever you choose
<menuchoice><guimenu>View</guimenu><guimenuitem>Redisplay</guimenuitem></menuchoice>.</para>

<para>Adding a song to a playlist will automatically add its file to
the Collection List, but adding a file to the collection list won't
automatically add the song to any playlists.</para>

<para>You can quickly create a playlist from your entire Collection
List, by &RMB; clicking on the <guilabel>Collection List</guilabel>
icon, and choosing <guimenuitem>Duplicate</guimenuitem>.  The
resulting playlist is a normal playlist, and editing it will not
affect the <guilabel>Collection List</guilabel>.</para>

<para>You can add playlist files created outside &juk; individually by
selecting them with
<menuchoice><guimenu>File</guimenu><guimenuitem>Open
File...</guimenuitem></menuchoice>.  Any playlist files found in
folders you add with
<menuchoice><guimenu>File</guimenu><guimenuitem>Open
Folder...</guimenuitem></menuchoice> will also be added
automatically.</para>

<para>You can create a new playlist by choosing
<menuchoice><guimenu>File</guimenu><guimenuitem>New</guimenuitem></menuchoice>
or the <guiicon>New</guiicon> icon on the toolbar.  You will be
prompted for a name, and then an icon for that playlist will appear in
the playlist pane.  You can now drag and drop files from the
Collection List to your playlist.  Use the <guiicon>Save</guiicon>
icon or
<menuchoice><guimenu>File</guimenu><guimenuitem>Save</guimenuitem></menuchoice> to
save the playlist at any time.</para>

<sect1 id="collection-list-gui">
<title>The Song List</title>

<para>When you are viewing the Collection List, the main pane contains
all the files that &juk; knows about.  When you are viewing a
playlist, only the songs that are in that playlist are shown.  In
either case, the appearance and behavior of the list is the
same.</para>

<para>Each song takes one row in the display. There is a column for
each metadata field that &juk; tracks.  These columns correspond to
the fields available to edit in the tag editor.</para>

<para>You can reorder the list at any time by &LMB; clicking on the
column header.  This will first sort the files in ascending order
based on the contents of that column.  If you &LMB; click again on the
same header, the files will be re-sorted in descending order.</para>

<para>The columns are initially sized wide enough to show the longest
entry available. You can resize the columns by placing your mouse
cursor on the divider between two columns.  When the cursor changes
from a pointer, &LMB; click and drag in the direction you want to
resize the columns.</para>

<para>You can reorder the columns by &LMB; clicking on a header and
dragging the header to the left or right.  You can't drag past the
edge of the window when doing this however, so you may need to scroll
a little to the left or right, and repeat dragging the header, until
you have placed it in your preferred position.</para>

<para>The
<menuchoice><guimenu>View</guimenu><guisubmenu>Columns</guisubmenu></menuchoice>
menu allows you to hide (and later unhide) columns you are not
presently interested in.  You can also hide or unhide columns by &RMB;
clicking on a column header.</para>

<para>&LMB; double clicking on a file will play it with the inbuilt
player.  If another song was already playing, it will stop, and the
new song will play.</para>

<para>&RMB; clicking on a file offers you several options:</para>

<variablelist>
<varlistentry>
<term><guimenuitem>Cut</guimenuitem></term>
<term><guimenuitem>Copy</guimenuitem></term>
<term><guimenuitem>Paste</guimenuitem></term>
<listitem>
<para>...</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Clear</guimenuitem></term>
<listitem>
<para>If you are viewing the Collection List, choosing
<guimenuitem>Clear</guimenuitem> will remove the file from the list,
and will also remove all corresponding entries for this song from all
playlists.  You should note that if this file is in a folder that
&juk; scans on startup, it will be readded to the Collection List the
next time you start up &juk; but it won't be automatically added to
any playlists.</para>
<para>If you are viewing a playlist, <guimenuitem>Clear</guimenuitem>
will simply remove the song from the playlist.</para>

</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Remove From Disk</guimenuitem></term>
<listitem>
<para>This will remove the file from the Collection List, remove all
entries for the song in all playlists, and delete the file from your
disk.  You cannot undo this, although you will be asked to confirm
your choice.  Use this with caution.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guimenuitem>Edit</guimenuitem></term>
<listitem>
<para>Will allow you to edit the currently highlighted song, in the
column you clicked in.  For example, if you do not have the tag editor
visible, and you are busy creating a playlist, but you notice a
mis-spelling in an artist name, you can edit it directly with this
menu item.</para>
<para>Changes made in this manner are always saved immediately as soon
as you click elsewhere and are finished editing.</para>
</listitem>
</varlistentry>

</variablelist>

</sect1>

<sect1 id="juk-tagger">
<title>The &juk; Tag Editor</title>

<para>For many file formats, it is practical to use the filename to
describe the contents of the file: <quote><filename>Report for the
board - June 2003.doc</filename></quote> for example, may be all the
information you need in order to find that file again.  Trying to
capture all the useful information about a particular song however,
could lead to filenames like this: <quote><filename>Type O Negative -
The Glorious Liberation Of The Peoples Technocratic Republic Of
Vinnland By The Combined Forces Of The United Territories Of
Europa.mp3</filename></quote> or <quote><filename>Various
Artists_15_The Smithsonian Collection of Classic Jazz Volume II_Jimmie
Lunceford &amp; His Orchestra - Organ Grinder's
Swing.mp3</filename></quote>.  These are neither very practical to
use, nor do they contain all of the useful information that you might
have collected about the song.  Adding the album, and track number,
for example, to the first would make it even longer and more
unmanageable, while still not telling you at a glance the year it was
released, or what style of music it is, if you're not familiar with
the artist.</para>

<para>The solution then, is to store this kind of metadata inside the
files themselves. Mp3 and ogg files can also contain small snippets of
text which you can use to describe the content of the file.  There are
several formats, but &juk; hides the details of the differences
between them, and provides a standard way to edit a standard subset of
well known tags for all your audio files.</para>

<para>&juk;'s full featured tag editor allows you to edit the tags in
both mp3 and ogg files.  You can edit single files or multiple files,
and you can select a mix of mp3 and ogg files to edit.  The only
requirement is that you have write access to the files themselves; you
cannot edit the tags of a file that is mounted from a &CD-ROM; for
example.</para>

<sect2 id="tagging-a-single-file">
<title>Editing the Tags in a Single File</title>

<para>To edit the tag in a single file, select it in either the
collection list or any entries it has in any playlist.  If the tag
editor is not visible, enable it by choosing
<menuchoice><guimenu>View</guimenu><guimenuitem>Show Tag
Editor</guimenuitem></menuchoice>.  The tag editor displays in the
bottom of the list view.</para>

<para>Simply type into any of the editable fields to change the
information.  When you are done, &LMB; click back in the list, and you
will be prompted to save your changes.</para>

<variablelist>
<title>Tag Editor Fields</title>
<varlistentry>
<term><guilabel>Artist Name:</guilabel></term>
<listitem>
<para>The name of the Artist(s) who released the song.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Track name:</guilabel></term>
<listitem>
<para>The name of the song.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Album name:</guilabel></term>
<listitem>
<para>The name of the album the song was released on.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Genre:</guilabel></term>
<listitem>
<para>The <quote>Style</quote> of the music.  &juk; provides a list
corresponding roughly to the informal id3 standard, but you are free
to type your own entries in this list.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>File name:</guilabel></term>
<listitem>
<para>The file name of the actual file on disk.  You can edit this
directly, and when you save, the file will be renamed.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Track:</guilabel></term>
<listitem>
<para>The position of the track on the original recording.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Year:</guilabel></term>
<listitem>
<para>The year the song was released.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Length:</guilabel></term>
<listitem>
<para>This is not editable, simply shown for information.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Bitrate:</guilabel></term>
<listitem>
<para>This is not editable.</para>
</listitem>
</varlistentry>

<varlistentry>
<term><guilabel>Comment:</guilabel></term>
<listitem>
<para>You can add your own free text comment here, with additional
notes &etc;</para>
</listitem>
</varlistentry>
</variablelist>

<para>You can explicitly and immediately save your changes at any time
using the
<menuchoice><guimenu>Tagger</guimenu><guimenuitem>Save</guimenuitem></menuchoice>
menu entry or by pressing
<keycombo>&Ctrl;<keycap>T</keycap></keycombo>.</para>

</sect2>

<sect2 id="tagging-multiple-files">
<title>Editing the Tags in Multiple Files</title>

<para>You can select multiple files in the list view, and edit one or
more fields in the tags for all files at once.</para>

<para>Use <keycap>Shift</keycap> and the &LMB; to select a contiguous
list of files, and &Ctrl; and &LMB; to select individual
non-contiguous files.</para>

<para>If the tag editor is not visible, you can enable it by choosing
<menuchoice><guimenu>View</guimenu><guimenuitem>Show Tag
Editor</guimenuitem></menuchoice>.  The tag editor displays in the
bottom of the list view.</para>

<para>The tag editor behaves slightly differently when you have
selected multiple files.</para>

<para>Each field in the tag editor will now show an
<guilabel>Enable</guilabel> checkbox next to it.  Any field that has
exactly the same contents for all the files you selected, displays
that content, and is enabled for editing, with the
<guilabel>Enable</guilabel> checkbox checked.</para>

<!-- put screeny here -->

<para>Any field that does not have matching contents in all selected
files is not initially editable, and does not display any contents at
all.</para>

<para>To change the content of any field, check the
<guilabel>Enable</guilabel> checkbox if it is not already checked, and
edit the field as you normally would.</para>

<para>When you are done, &LMB; click back in the list view and you
will be prompted to save your changes.  The prompt dialog will show
you a list of the affected files, so you have a chance to check that
you are indeed altering the files you intended to.</para>

<para>You can explicitly and immediately save your changes at any time
using the
<menuchoice><guimenu>Tagger</guimenu><guimenuitem>Save</guimenuitem></menuchoice>
menu entry or by pressing
<keycombo>&Ctrl;<keycap>T</keycap></keycombo>.</para>

</sect2>

</sect1>

</chapter>

<chapter id="toolbar-reference">
<title>The &juk; Toolbar</title>

<sect1 id="main-toolbar">
<title>The Main Toolbar</title>

<screenshot>
<screeninfo>The &juk; toolbar.</screeninfo>
<mediaobject>
<imageobject>
<imagedata format="PNG" fileref="toolbar.png" />
</imageobject>
<textobject>
<phrase>The &juk; toolbar.</phrase>
</textobject>
<caption><para>The &juk; toolbar.</para></caption>
</mediaobject>
</screenshot>

<para>From left to right in the screenshot above, the icons on the
default toolbar are:</para>

<variablelist>
<varlistentry>
<term><guiicon>New</guiicon></term>
<listitem><para>Create a new playlist</para></listitem>
</varlistentry>

<varlistentry>
<term><guiicon>Open</guiicon></term>
<listitem><para>Add a file to the collection list (if it's active) or
to the currently selected playlist.  Adding a file to a playlist will
add it to the collection list automatically, but not vice
versa.</para></listitem>
</varlistentry>

<varlistentry>
<term><guiicon>Save</guiicon></term>
<listitem><para>Save the currently selected playlist.  To save a tag
you have edited, either select another item, or press <keycombo
action="simul">&Ctrl;<keycap>T</keycap></keycombo>
instead.</para></listitem>
</varlistentry>

<varlistentry>
<term><guiicon>Cut</guiicon></term>
<listitem><para>If a playlist or song is selected, cut (remove) it from the
list.  If the tag editor is active, this works like cut in any editor,
removing the selected text, but keeping a copy on the
clipboard.</para></listitem>
</varlistentry>

<varlistentry>
<term><guiicon>Copy</guiicon></term>
<listitem><para>If the tag editor is active, this works like copy in
any editor, placing a copy of the selected text on the
clipboard.</para>
<para>If you use copy on a song in the collection list, the url is
placed on the clipboard, so you can paste it.  For example, you could
paste the url into a text editor, &konqueror;, or another
playlist.</para></listitem>
</varlistentry>

<varlistentry>
<term><guiicon>Paste</guiicon></term> 
<listitem><para>If you previously either cut or copied a url from the
collection list, you can paste the url back into a new playlist.  You
could also paste a url you have copied from &konqueror; or any other
application. If you are operating in the tag editor, paste will paste
any text currently on the clipboard into the selected
field.</para></listitem>
</varlistentry>

<varlistentry>
<term><guiicon>Show Search Bar</guiicon></term>
<listitem><para>Show or hide <link linkend="search-bar">the search
bar</link>.</para></listitem>
</varlistentry>

<varlistentry>
<term><guiicon>Show Tag Editor</guiicon></term>
<listitem><para>Show or hide <link linkend="tagging-a-single-file">the
tag editor</link>.</para></listitem>
</varlistentry>

<varlistentry>
<term>Play controls</term>
<listitem>
<para>These work like any standard media player you may have come
across.  The controls are <guiicon>Play</guiicon>,
<guiicon>Pause</guiicon>, <guiicon>Stop</guiicon>, <guiicon>Skip to
the previous song</guiicon> and <guiicon>Skip to the next
song</guiicon>.</para>
<para>There is also a tracking bar, showing how far along (relatively)
in the current song you are.  You can drag this slider with the mouse
in order to skip forwards or backwards within a track.</para>
<para>Finally there is a volume slider.  As you may expect, this
raises and lowers the volume.  <quote>Loud</quote> is on the right,
and <quote>Quiet</quote> is on the left.</para></listitem>
</varlistentry>
</variablelist>

</sect1>

<sect1 id="search-bar">
<title>The Search bar</title>

<para>The search bar allows you to quickly search for a song in the
collection list or a playlist.</para>

<para>Simply typing text into the search bar will reduce the visible
list of songs to those which contain that text in any visible
column.</para>

<para>You can refine the search in various ways.  You can have &juk;
search only in a particular column by choosing it from the dropdown
list.  The default is <guilabel>&lt;All Visible&gt;</guilabel>.  The
dropdown list contains all the visible columns so that you can
specify one in particular you are interested in.  You can also make
the searching <guilabel>Case Sensitive</guilabel> by checking the box
labelled so.  Finally there is a <guibutton>Clear</guibutton> to
remove the search text.</para>

<para>Searching begins instantly when text is entered into the search
field.  Searching is incremental, that is, as you type each character
into the text field, the search is narrowed further.  This is useful
to find a song where you only remember part of a name, for
instance.</para>

</sect1>

</chapter>

<chapter id="menu-and-command-reference">
<title>Menu and Command Reference</title>

<sect1 id="menus">
<title>Menus</title>

<sect2 id="menu-file">
<title><guimenu>File</guimenu> Menu</title>

<variablelist>
<varlistentry>
<term><menuchoice>
<shortcut><keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu><guimenuitem>New</guimenuitem>
</menuchoice>
</term>
<listitem><para>Create a new playlist</para>
</listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo>
</shortcut>
<guimenu>File</guimenu>
<guimenuitem>Open...</guimenuitem>
</menuchoice>
</term>
<listitem><para>Select a file (or files) to add to the collection list.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu><guimenuitem>Open Folder...</guimenuitem>
</menuchoice>
</term>
<listitem><para>Select a folder (or folders) to add to the
collection list.  These folders will also be rescanned whenever
&juk; is started or
<menuchoice><guimenu>View</guimenu><guimenuitem>Redisplay</guimenuitem>
</menuchoice> is chosen.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu>
<guimenuitem>Rename...</guimenuitem></menuchoice>
</term>
<listitem><para>Rename a playlist.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><menuchoice>
<guimenu>File</guimenu><guimenuitem>Duplicate...</guimenuitem></menuchoice>
</term>
<listitem><para>Create a duplicate of the selected playlist, and
prompt for a new name.<!-- File menu entry seems not to be working -->
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><menuchoice><guimenu>File</guimenu><guimenuitem>Remove</guimenuitem></menuchoice></term>
<listitem><para>Remove the selected item. <!-- File menu entry seems -->
<!-- not to be working --></para></listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>

<sect1 id="keybindings">
<title>Keybinding Reference</title>

<!--
ctrl-a select all
ctrl-c copy
ctrl-g guess tag entries based on filename
ctrl-n new playlist
ctrl-o open file (add to the collection or a playlist)
ctrl-q quit
ctrl-s save
ctrl-t save edited tag information
ctrl-v paste
ctrl-x cut
f1 Show manual
shift-f1 what's this help

-->
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Key Combination</entry>
<entry>Action</entry>
</row>
</thead>
<tbody>
<row>
<entry><keycombo
action="simul">&Ctrl;<keycap>A</keycap></keycombo></entry>
<entry>Select all</entry>
</row>
<row>
<entry><keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo></entry>
<entry>Copy</entry>
</row>
<row>
<entry><keycombo action="simul">&Ctrl;<keycap>G</keycap></keycombo></entry>
<entry>Guess tag entries based on filename</entry>
</row>
<row>
<entry><keycombo
action="simul">&Ctrl;<keycap>N</keycap></keycombo></entry>
<entry>New Playlist</entry>
</row>
</tbody>
</tgroup>
</informaltable>

</sect1>
</chapter>

<chapter id="credits-and-licenses">
<title>Credits and Licenses</title>

<para>&juk; Copyright &copy; 2002, 2003 Scott Wheeler.</para>

<para>&juk; is developed and maintained by Scott Wheeler
<email>wheeler@kde.org</email>.</para>

<para>Many thanks to the following people who have contributed to &juk;:</para>

<itemizedlist>
<listitem><para>Daniel Molkentin <email>molkentin@kde.org</email> for system tray docking, <quote>inline</quote> tag
editing, bug fixes, evangelism, moral support.</para>
</listitem>
<listitem><para>Tim Jansen <email>tim@tjansen.de</email> for
the <application>GStreamer</application> port</para>
</listitem>
</itemizedlist>

<para>Documentation Copyright &copy; 2003, Lauri Watts.</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;
&underGPL;

</chapter>

&documentation.index;

</book>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:
-->













