# The &juk; Handbook

&Lauri.Watts; &Lauri.Watts.mail;
Scott
Wheeler

    wheeler@kde.org

2001
2002
Scott Wheeler
&FDLNotice;
12/07/2002
1.0

&juk; is a jukebox, tagger and music collection manager.

KDE
kdemultimedia

## Introduction

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

## Using &juk;

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

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 xmms) and you can manage playlists created in those applications from within &juk;.

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

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.

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

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

You can create a new playlist by choosing File New or the New 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 Save icon or File Save to save the playlist at any time.

### The Song List

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.

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.

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.

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.

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.

The View Columns 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.

&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.

&RMB; clicking on a file offers you several options:

Cut
Copy
Paste

  ...

Clear

  If you are viewing the Collection List, choosing Clear 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.

  If you are viewing a playlist, Clear will simply remove the song from the playlist.

Remove From Disk

  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.

Edit

  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.

  Changes made in this manner are always saved immediately as soon as you click elsewhere and are finished editing.

### The &juk; Tag Editor

For many file formats, it is practical to use the filename to describe the contents of the file: `Report for the board - June 2003.doc` 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: `Type O Negative - The Glorious Liberation Of The Peoples Technocratic Republic Of Vinnland By The Combined Forces Of The United Territories Of Europa.mp3` or `Various Artists_15_The Smithsonian Collection of Classic Jazz Volume II_Jimmie Lunceford & His Orchestra - Organ Grinder's Swing.mp3`. 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.

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.

&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.

#### Editing the Tags in a Single File

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 View Show Tag Editor. The tag editor displays in the bottom of the list view.

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.

##### Tag Editor Fields

Artist Name:

  The name of the Artist(s) who released the song.

Track name:

  The name of the song.

Album name:

  The name of the album the song was released on.

Genre:

  The Style 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.

File name:

  The file name of the actual file on disk. You can edit this directly, and when you save, the file will be renamed.

Track:

  The position of the track on the original recording.

Year:

  The year the song was released.

Length:

  This is not editable, simply shown for information.

Bitrate:

  This is not editable.

Comment:

  You can add your own free text comment here, with additional notes &etc;

You can explicitly and immediately save your changes at any time using the Tagger Save menu entry or by pressing &Ctrl;T.

#### Editing the Tags in Multiple Files

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

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

If the tag editor is not visible, you can enable it by choosing View Show Tag Editor. The tag editor displays in the bottom of the list view.

The tag editor behaves slightly differently when you have selected multiple files.

Each field in the tag editor will now show an Enable 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 Enable checkbox checked.

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

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

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.

You can explicitly and immediately save your changes at any time using the Tagger Save menu entry or by pressing &Ctrl;T.

## The &juk; Toolbar

### The Main Toolbar

The &juk; toolbar.
The &juk; toolbar.

The &juk; toolbar.

From left to right in the screenshot above, the icons on the default toolbar are:

New

  Create a new playlist

Open

  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.

Save

  Save the currently selected playlist. To save a tag you have edited, either select another item, or press &Ctrl;T instead.

Cut

  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.

Copy

  If the tag editor is active, this works like copy in any editor, placing a copy of the selected text on the clipboard.

  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.

Paste

  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.

Show Search Bar

  Show or hide the search bar.

Show Tag Editor

  Show or hide the tag editor.

Play controls

  These work like any standard media player you may have come across. The controls are Play, Pause, Stop, Skip to the previous song and Skip to the next song.

  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.

  Finally there is a volume slider. As you may expect, this raises and lowers the volume. Loud is on the right, and Quiet is on the left.

### The Search bar

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

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

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 <All Visible>. 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 Case Sensitive by checking the box labelled so. Finally there is a Clear to remove the search text.

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.

## Menu and Command Reference

### Menus

#### File Menu

&Ctrl;N File New

  Create a new playlist

&Ctrl;O File Open...

  Select a file (or files) to add to the collection list.

File Open Folder...

  Select a folder (or folders) to add to the collection list. These folders will also be rescanned whenever &juk; is started or View Redisplay is chosen.

File Rename...

  Rename a playlist.

File Duplicate...

  Create a duplicate of the selected playlist, and prompt for a new name.

File Remove

  Remove the selected item.

### Keybinding Reference

Key Combination | Action
--- | ---
&Ctrl;A | Select all
&Ctrl;C | Copy
&Ctrl;G | Guess tag entries based on filename
&Ctrl;N | New Playlist

## Credits and Licenses

&juk; Copyright © 2002, 2003 Scott Wheeler.

&juk; is developed and maintained by Scott Wheeler wheeler@kde.org.

Many thanks to the following people who have contributed to &juk;:

- Daniel Molkentin molkentin@kde.org for system tray docking, inline tag editing, bug fixes, evangelism, moral support.

- Tim Jansen tim@tjansen.de for the GStreamer port

Documentation Copyright © 2003, Lauri Watts.

&underFDL; &underGPL;

&documentation.index;