kj_documentation.txt

KJ is a simple MP3 player written purely in the programming language, Java.

Documentation for KJ Audio Player
---------------------------------

- Table of Contents -

1. Quick Start Guide

2. The Juke Box Dialog

    2.1 Using the Juke Box dialog.

        - Track Information
        - Seek Bar
        - Control Bar
        - Volume Bar
        - Menus
        - Microphone priority
        - Special Options
        - Venue Preferences Dialog
        - Volume monitoring

    2.2 Venues 

        - What's a venue
        - Creating, Loading and Saving Venues

3. Track List Editor Dialog

    3.1 Managing Track Lists
    
        - Track list pick modes
        - Track list preferences dialog

    3.2 Managing Tracks 

        - Moving tracks
        - Play Now, Play Next, Request
        - The Track Properties Dialog

    3.3 Searching for Tracks
    3.4 Track List Tools

4. The Request List Dialog

5. The DSP Dialog

6. Cross-Fading Tips and Hints




- Section 1: Quick Start Guide -

Use the following steps to play something with KJ:

1. When KJ is first started, the "Juke Box" dialog will be displayed and a 
   default venue created, as well as the "Track List Editor" dialog. In the
   "Track List Editor" dialog, choose "Add Folder..." from the "Tracks" menu.
   
2. A file chooser dialog will appear. Choose a folder containing your MP3
   files. KJ will scan this folder and all sub-folders for MP3 files and
   add them to the "<default>" track list.

3. Click the "Play" button on the "Juke Box" dialog. You should here some
   groovy tune playing through your speakers now. ;)

4. When exiting KJ by clicking the "X" or choosing "File -> Exit" on the 
   "Juke Box" dialog, a file chooser dialog will appear ask you to choose a
   filename for the venue you just added you song to. Choose a filename without
   the extension, one will be supplied, the click the "Save Venue" button.
   KJ will automatically reload this venue next time you fire it up.




- Section 2: The Juke Box Dialog -

The "Juke Box" dialog is the main dialog of KJ, with it you can:

- Open the "Track List Editor", "Request List", and "DSP" dialog.
- Create, load and save venues.
- Play, pause, stop or swtich between the previous and next tracks.
- See the name of the current and next playing tracks as well as the position
  of the current track.
- Seek through the playing track using the seek bar.
- Adjust the volume and enable or disable the microphone priority option.
- Display this help information.


- Secion 2.1: Using the Juke Box Dialog -

This section discusses how to use the "Juke Box" dialog. The "Juke Box" dialog
is using to display information about the current and next playing track. There
are five rows of information and options (excluding the menu bar) :

1. The filename of the currently playing track and it's status (see below). 
2. The filename of the track that will be played next.
3. The position and duration in minutes and seconds of the playing track.
4. The "seek bar" used to jump to any part of the track.
5. The "control bar" used to play, pause, stop and change tracks.

On the right side of the dialog is the "volume bar" that allow you to adjust the
output volume of KJ.  

The "status" of the playing track can be one of several things:

1. Playing: Displays the track filename in green or yellow.
2. Paused:  Displays the track filename suffixed with the tag -> <Paused> in 
            green or yellow.
3. Stopped: Displays "No track. <Stopped>" in red.

Whenever the current track is displayed in "yellow", KJ is crossfading the
current track out.


- Menus

There are five (5) menus in the "Juke Box" menu bar:

1. File     -> Create, load and save venues, adjust global venue settings, exit
               KJ.

2. View     -> Show or hide the "Track List Editor", "Request List", or "DSP"
               dialogs. Also bring up the "Track Properties" dialog for the 
               playing track.

3. Playback -> Play, pause, or stop the current track, switch to the previous 
               or next track, repeat the current track, switch to microphone
               priority mode or mute the volume.

4. Options  -> Adjust the "Fade when navigating" or "Mark played tracks" 
               options.

5. Help     -> Display this help file or the "About" dialog.


- Microphone Priority -

Microphone priority is simply an adjustable setting that KJ will fade the 
volume to when the "Microphone Priority" option is enabled. It is typically
used when the DJ wishes to voice over the music currenly playing.

Use the "Venue Preferences" dialog (File -> Preferences) to change the 
"Microphone Priority" volume level. 


- Special Options -

The "Options" menus currently contains two options:

1. "Fade when navigating"
2. "Mark played tracks"

The "Fade when navigating" option controlls whether or not cross-fading is 
performed when manually switching tracks using the "previous/next" buttons
on the "Juke Box" or manual override via the "Track List Editor" dialog.

Use the "Venue Preferences" dialog (File -> Preferences) to change the 
navigation cross-fade settings.

The "Mark played tracks" option controlls whether or not KJ should mark a 
track as "played" and to not play it again until the entire track list has been
played. Once all of the tracks in a track list have been played, all of the 
"played" flags are reset. You can also manually reset the "played" tracks via
the "Track List Editor" dialog using the "Tracks -> Reset Played Tracks" 
option.


- The Venue Preferences Dialog -

The "Venue Preferences" dialog contains some volume options and the 
configuration of the navigation cross-fading.

The volume options consist of the following settings:

1. "Microphone Priority": A preset volume level to apply to the master volume 
       when the microphone priority option is enabled. It is represented as a
       percentage, 0% being the quietest and 100% being the loudest. The
       default setting is 30%.

2. "Disable volume monitoring": Prevents KJ from monitoring the output volume of
       the playing track, saving CPU.

3. "Monitor volume #### milliseconds after start of track": Delays volume 
       monitoring the specificed number of milliseconds before each track. 
       Prevents any "clicks" or "pops" from interfering with the volume 
       averaging calculations.

The rest is of the dialog contains navigation cross-fading options. These 
allow you to change how KJ cross-fades tracks when using the "Previous/Next"
buttons on the "Juke Box" dialog and during manual overrides from the 
"Track List Editor" dialog. 

You can enable or disable navigation cross-fading from here as well as with the
"Options -> Fade when navigating" menu item in the "Juke Box" dialog.

The actual cross-fading settings are explained in detail in the "Cross-fading
Tips and Hints" section.


- Volume Monitoring -

The "Volume Monitoring" option is accessed through the "Venue Preferences" 
dialog, where you may enable or disable it. When enabled, KJ will monitor
the output volume of the current track in realtime allowing for features
like automatic cross-fading and (in the future) volume balancing.

If you disable volume monitoring, KJ will use less CPU but the above mentioned
features will not work. You should only disable volume monitoring if the audio
playback seems to cut out often when using KJ on a slower computer.


- Section 2.2: Venues -

This section discusses venues. A venue is a collection of track lists, tracks 
and settings for a particular event you might be using KJ for. For example, if
you where to use KJ to DJ a wedding, then maybe at a dance club, follow by
your grand parents polka bash, each of these would be considered different 
venues. It makes it easier to manage different event rather than having 
everything in one huge venue.

Venues contain a set of names track lists, containing tracks. All preferences,
crossfading settings, and any other options you can adjust in KJ are all stored
in the venue (.kjv) file. These files are actually in XML format, so you can
even browse them with a text editor and make changes manually.

Everything to do with creating, loading and saving venues is available in the 
"File" menu of the "Juke Box" dialog.


- Creating a Venue -

When you first start KJ, a default venue will be created. You can add track 
lists and tracks to it via the "Track List Editor" dialog. To create a new
venue if one if already loaded, choose the "File -> New Venue..." option
in the "Juke Box" dialog. All track list, tracks, and preferences will be
reset to the defaults and you will be asked to save the venue when you 
exit KJ.


- Loading a venue -

A venue can be loaded into KJ using the "File -> Open Venue..." menu item. A
file chooser dialog will appear prompting you for a venue file to open. KJ 
venue files are suffixed with the ".kjv" extension. Once you've found the
venue file you wish to open, click the "Open" button on the file chooser.

We you start KJ it will always automatically load the last venue you opened.


- Saving a venue -

A venue file can be saved to disk using the "File -> Save Venue..." menu item.
If you have already chosen a file for this venue, it will be automatically
overwritten, otherwise you will be prompted to choose a filename for the 
venue. When choosing a filename, you do not have to supply the ".kjv" suffix,
KJ will do this automatically.

If you wish to save the current venue in a new location, use the "File -> Save 
Venue As..." menu item. 

KJ will also automatically save the current venue to disk when exiting.




- Section 3: The Track List Editor Dialog -

The "Track List Editor" dialog is used to prepare and organize lists of tracks
you want KJ to play.

The layout of the dialog consists of the following parts:

1. A menu bar containing 4 menus: Track Lists, Tracks, Search, and Tools.
2. A drop-down box containing the list of track lists in this venue. 
3. To the right of the track list drop-down box is the "Active" check box.
4. Below the track list drop-down and "active" check box is the track list
   box.

The "track list drop-down box" contains all of the track lists for the loaded
venue. There can be any number of track list in a venue. The track list 
displayed in the drop-down box is considered to be the "selected" track list, 
and has it's list of tracks displayed in the "track list box" below the 
drop-down. When even a different list is choosen, the "track list box" changes
to reflect the choosen track list. 

The "active check box" specifies if the selected track list is activated, 
meaning should KJ play tracks from this track list. When ever a track list is
"active" an asterisk '*' is displayed in front of the track list's name in the
"track list drop-down box". More that one track list can be activated.


- Section 3.1: Managing Track Lists -

Track lists are managed via the "Track Lists" menu in "Track List Editor" 
dialog. There are seven (7) menu items in this menu:

1. Add...         -> Adds a new, empty track list to this venue.
2. Import...      -> Imports one or more Winamp playlist (.m3u) files.
3. Remove...      -> Removes the selected track list.
4. Rename...      -> Allow you to rename the selected track list.
5. Preferences... -> Display the "track list preferences" dialog.
6. Pick Mode      -> Contains a list of track list pick modes (see below).
7. Close          -> Hides the "Track List Editor" dialog.

The "track list pick mode" controls how track lists are choosen when there
is more than one track list actived:

1. Single       -> Only plays tracks from the selected track list.
2. Sequencial   -> Sequencially chooses an ACTIVE track list to play a track 
                   from.
3. Random       -> Randomly chooses an ACTIVE track list to play a track from.
4. Proportional -> Randomly picks a track list in proportion to the number of