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 "" 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 -> in green or yellow. 3. Stopped: Displays "No track. " 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 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.