kj_documentation.txt

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

                   tracks in the list. It behaves as if all ACTIVE track lists
                   are merged together into one giant track list.


- Track List Preferences Dialog -

The "Track List Preferences" dialog allows you to change how tracks are played
from the selected track list as well as the default cross-fade settings for all
tracks in the list.

The "Track List Preferences" dialog is layout as follows:

- At the top is the "Track List Options" group, which contains three (3) 
  options: 

    1. "Play Mode" -> "Sequencial" or "Random". Controls how tracks are played 
           from this track list.

    2. "Allow track list to be actived" -> Determines if the selected track 
           list is allow to be made "active". Some track lists may contain odd
           ball songs that you want to keep from playing unless requested. ;)

    3. "Allow requests when track list is active" -> Specifies that when a 
           track from the selected track list is playing, requests should be
           allowed to follow. This feature is typically used with the "Single"
           track pick mode and is useful for when you have a pre-sequenced 
           track list you don't want interrupted by requests.

- Below, appears the track list's cross-fading preferences. You can enable or
  disable the "default" cross-fading for all tracks within the track list. 
  Please refer to the section "Cross-fading Tips and Hints" for details on the
  cross-fading options.


- Section 3.2: Managing Tracks -

Tracks of a track list are managed via the "Tracks" menu in "Track List Editor" 
dialog. There are ten (10) menu items in this menu:
 
1.  Add Files...        -> Add one or more MP3 files to the selected track 
                           list.
2.  Add Folder...       -> Adds all MP3 files in the selected folder and its
                           sub-folders to the selected track list.
3.  Move                -> Reorder tracks in the selected track list. 
4.  Remove              -> Remove tracks in the selected track list.
5.  Remove All          -> Remove all tracks from the selected track list.
6.  Play Now            -> Plays the first selected track immediately.
7.  Play Next           -> Plays the first selected track next.
8.  Request             -> Adds the selected tracks to the request list.
9.  Reset Played Tracks -> Resets any tracks marked as played (grey).
10. Properties...       -> Displays the "Track Properties" dialog.

The "Move" menu contains a list of items that allow you to reorder tracks in a
track list. All of these items have short-cut keys (alt + up, left, pgup, etc.) 
to make it easier to use. You can move all selected tracks up or down the track
list one index, 10 indexes, to the top or bottom of the list.

The "Play Now", "Play Next", "Request" options can also be accessed by 
right-clicking in the track list box. A context menu will appear containing
these options. Tracks can also be requested by double clicking any track in the
track list box.


- The Track Properties Dialog -

The "Track Properties" dialog can be accessed in three (3) places:

1. From the "Juke Box" dialog via the "View -> Track Properties..." menu item.
2. From the "Track List Editor" via the "Tracks -> Properties..." menu item.
   You must have tracks selected in order for the dialog to appear.
3. By right-clicking the track list box in the "Track List Editor" and choosing
   the "Properties..." menu item.

If more than one track is selected when this dialog is displayed, the changes 
are applied to all of them.

The "Track Properties" dialog is divided into three (3) sections as follows:

1. Gain            -> Adjust the "gain" of the selected tracks. Allows you to
                      manually balance the volume of your tracks. 
2. Request Options -> Change how requests are played in relation to the 
                      selected tracks.
3. Cross-Fader     -> Cross-fading options for the selected tracks.

The track "gain" or volume compensation allows you to reduce or increase a 
track's volume independently from the "Juke Box" dialog's volume bar. Tracks
that where recorded too loud or quiet can be adjusted with this setting.

The "Request Options" only have one option for now: 

1. "Allow requests to follow tracks(s)" -> This options allows you to prevent
       request from playing after specific tracks. For example during a group
       of slow songs, or a pre-sequence mix. Disabling requesting for these
       tracks prevents a request from slipping in between them.

The "Cross-Fader" options for a track have three (3) options accessible via the
drop-down box:

1. Disabled                   -> No cross-fading for the selected tracks.
2. Use track-List cross-fader -> Use the cross-fading settings of the track list.
3. Custom                     -> Specifiy custom cross-fading settings for the
                                 selected tracks.

The rest of the cross-fading options are discussed in the "Cross-fading Tip and
Hints" section.


- Section 3.3: Searching for Tracks -

You can search for tracks in any track list using the options in the "Search"
menu of the "Track List Editor" dialog. There are four (4) options in this 
menu: 

1. Find              -> Displays the "find" dialog box to allow you to enter
                        words in the filename of the track you want to find.
2. Find Again        -> Repeats the search specified using the "Find" option.
3. Find Playing      -> Finds the playing track.
4. Find Next Playing -> Finds the track that will play next.

A search is not case sensitive and the words do not have to be in the right
order. As long as all of the specified words are found in the filename of a 
track, it'll come up as a search hit. 

Searching is performed across all track lists, whether they are active or not.
The "Find Again" option continues searching from the result of the previous
find.


- Section 3.4: Track List Tools -

The "Tools" menu in the "Track List Editor" dialog consists of two (2) options:

1. Clean... -> Remove duplicate tracks or files from the track list that are no
               longer on disk.
2. Sort     -> Sort the selected track list ascending or descending.


- The "Clean Track List" dialog -

The "Clean Track List" dialog allows you to clean up the selected track list.
There are three cleaning options:

1. "Remove missing tracks." -> Removes all tracks from the selected track list
       that are no longer on disk.
2. "Remove duplicate tracks." -> Removes all tracks from the selected track 
       list that already exist in same track list.
3. "Remove tracks in other track lists." -> Removes all tracks from the 
       selected track list that exist in other track lists.

After the clean-up is performed, you will see a status dialog explaining what 
changed.




- Section 4: The Request List Dialog -

The "Request List" dialog is used to manage requests from guest and integrate 
the request tracks into the venue when appropriate. Request tracks appear in 
purple in the "Track List Editor" dialog.

To request a track, simply double-click on any track list box. For more ways 
to request tracks, see "Section 3.2: Managing Tracks".

You can access the "Request List" dialog from the "Juke Box" dialog using the "View -> Request List" menu 
item.

The "Request List" dialog has two menus:

1. Request List -> Access the request list preferences, or hide the request 
                   list dialog.
2. Tracks       -> A similar menu to the one in the "Track List Editor", but
                   with less features. Reorder, remove, and display the 
                   properties of the selected tracks. Show the selected track
                   in the "Track List Editor" dialog.

Tracks of a request list are managed via the "Tracks" menu in "Request List" 
dialog. There are five (5) menu items in this menu:
 
1. Move                      -> Reorder tracks in the selected track list.
2. Remove                    -> Remove tracks in the selected track list.
3. Remove All                -> Remove all tracks from the selected track list.
4. Show in Track List Editor -> Shows the selectd track in the "Track List 
                                Editor" dialog.
5. Properties...             -> Displays the "Track Properties" dialog. (see: 
                                Section 3.2)

The "Move" menu contains a list of items that allow you to reorder tracks in 
the request list. All of these items have short-cut keys (alt + up, left, pgup,
etc.) to make it easier to use. You can move all selected tracks up or down the
request list one index, 10 indexes, to the top or bottom of the list. 

The "Show in Track List Editor", "Remove", and "Properties..." options can also
be accessed by right-clicking in the request list box. A context menu will 
appear containing these options. 


- The Request List Preferences Dialog -

The "Request List Preferences" dialog can be accessed via the "Request List ->
Preferences" menu item.

This dialog is used to control how requests are integrated into the already
playing tracks. There are three (3) options:

1. "Do not play request." -> Disables requesting for the venue.
2. "Play a requested track every..." -> Plays a requested track randomly 
       between the specified interval of minutes or tracks.
3. "Play requests immediately." -> Play all requests immediately following the
       playing track. As long as there are requests in the request list, only
       these tracks will be played.




- Section 5: The DSP Dialog -

The DSP dialog displays a visualisation for the playing track. Currently, there
are three (3) fixed visualisation with no options:

1. Scope
2. Spectrum Analyser
3. Volume Meter

To change between these visualisation, click the left mouse button anywhere
over the visualisation. 

Click the right mouse button to display debugging information about the DSP
dialog.




- Section 6: Cross-Fading Tips and Hints -

The section discusses the cross-fading features in KJ. There are three (3) main
parts to a cross-fade in KJ:

1. Position -> When in the track to start the cross-fading event.
2. Duration -> How long to cross-fade for in milliseconds.
3. Volume   -> What to do with the volume during the cross-fade.


- Cross-fade Position -

There are three (3) options for the "positon" part of a cross-fade: 

1. "Automatic" -> Uses "volume montoring" to automatically determine when to
       start cross-fading. (See below for details.) 
2. "Back end of track" -> Start cross-fading before the end of the track. When
       this occurs depends on the duration of the cross-fade.
3. "m:ss" -> At a specific place in the track in minutes and seconds.

In automatic mode, you can specify when to start "considering" to cross-fade
and what percentage the volume must hit to start cross-fading. This percentage
represents current volume over average volume across the track. The DSP 
debugging information mode display this percentage live. You can also force a
cross-fade at a position before the end of the playing track to shorten the 
delay between tracks that are not cross-faded.


- Cross-fade Volume -

The are two (2) option for the "volume" part of a cross-fade:
  
1. "Do not fade volume" -> Do not faded the volume. This option is used when 
       the track already has a volume slide at the end.
2. "Start% - End%" -> Fade the volume of the track from the "start" percentage
       to the "end" percentage. The volume fade is spread across duration of
       the cross-fade.

The "Start% - End%" option also allows you to push the start of the next track
later into the cross-fade instead of at the very beginning using the "Start 
next track #### milliseconds into cross-fade" option.  


- Tip and Hints -

1. Automatic cross-fading is far from perfect, but it does a nice job for
   many tracks. Still, certain tracks may fade too early or late. For these
   track, use a manual cross-fade. I find the nicest "Automatic" cross-fading
   settings are to start montioring the volume 15000 milliseconds before the
   end of the track for a volume of 40%, forcing the next track at about 500
   milliseconds before the end of the track, with a cross-fade duration of 
   15000 milliseconds.

2. For manual cross-fading, try the "Before end of track" option with a 
   duration of 15000 milliseconds, with a volume slide from 100% to 30%, 
   starting the next track 3000 milliseconds into the cross-fade.

3. Remember you can apply cross-fading setting for an entire track list as well
   as individual track in the track list.