# KR Maker V 0.1 Manual

## Requirements

- Any Linux, Window's PC, or Mac (untested) with around 512 MB of ram or more.
- Sun's Java Runtime Environment or Java Development Kit 1.5 or better. Go to http://java.sun.com/j2se/1.5.0/download.jsp and choose "JRE 5.0 Update 5".
- Modded Xbox with the Karaoke Revolution game. Currently, no PS2 support.

## Installing and Starting KRMaker

To install:
1. Create a directory "krmaker" on your hard drive.
2. Unzip "krmaker-0.1.zip" inside the krmaker directory.
To start KRMaker:

- In windows, run or double click on "KRMaker.bat"
- In Linux and mac, run "sh krmaker.sh". java must be in your path.

If it works correctly, the KRMaker window should appear.

## Overview

KRMaker is used to manually create a song capable of being played in Karaoke Revolution for the Xbox (referenced here as KR). KRMaker is used to create lyrics and a vocal tune matched with a song which KR uses to score the players performance.
Here is the main KRMaker screen:
It's composed of several sections:

- Vocal Notes Panel - contains the notes that are displayed in KR and are used to judge the singers performance.
- Tempo Panel - contains the beat of the song. This controls the timing of crowd hand clapping within KR as well as a few other things in the venue (such as the timing of the lights)
- Lyrics Panel - Lyrics to be displayed in KR can be entered here.
- Vocal / Master Track Panel - This is a stereo audio clip representing the vocals of the KR song.
- Background Track Panel - This is a stereo audio clip representing the background music of a KR song
- KR Events Panel - These are special events specific to KR, such as the keyboard player playing or the singer bringing his/her mic up.
- Controls Panel - These are various controls for changing the current shown position of the song, playing and changing the volume.

The File and Edit Menu contain the following:
File Menu:

- Load Vocals / Master Audio Track
- Load Background Audio Track
- Clear Vocals / Master Audio Track
- Clear Background Audio Track
- Load Midi Tune
- Save KR Midi Only
- Save KR Song Package

Edit Menu:

- Derive Background from Vocals / Master (L-R method)
- View Vocals FFT in note scale
- Generate KR Events

The tool KRUnpackager, will allow you to copy a song generated in KR Maker into an existing KR installation on the Xbox.

## Vocal Notes Panel

This panel is used to add, modify and delete notes.
To add a note, click and drag the right mouse button. Only one note can occupy the same horizontal space.
To select multiple notes, click to highlight the first note, and then shift-click to highlight a range of notes.
To move a note, click and drag it using the left mouse button. To move the current note and all notes after it, ctrl-click and drag using the left mouse button.
Note: Using ctrl-click can be very useful when a midi file is not exactly timed perfectly to the audio clip. By going through the song from start to end and continually adjusting the position of the notes using ctrl-click, is much easier then selecting a bunch of notes at a time and shifting them individually.
To delete a note, select one or more notes, and hit the Del key.
The size of notes be modified by adjusting the end points of the notes. Several notes can be adjusted at once by selecting the notes and holding down the shift key when adjusting the end point.
Also, selected notes can be cut, copied and pasted using Ctrl-X, Ctrl-C, and Ctrl-V respectively. For pasting, just click the mouse at the location you want to paste to before hitting Ctrl-V.

## Tempo Panel

This panel keeps track of the tempo of the song. There are only two uses of this panel, and both are kind of minor:

- to help line up the notes in the Vocal Notes Panel with the audio clip.
- to line up the beat to the notes so that when KR decides to make people in the crowd clap to the music, they do it to the beat of the song and not some random beat (which makes it seem like they hate the song and are going to rush the stage or something...). Also, some things in the venue beat to the music as well, such as lights.

Note that, I believe the above clapping to the beat can be turned off in KR by adding the KR event "clap_off" near the start of the song (although I haven't tried it).
Since songs often subtly change their tempo, we need to be able to set and adjust the beat as the song goes along. To do this, we have Tempo Events and Tempo Lines:
A Tempo Event marks the start of a new beat. Each Tempo Line after a Tempo Event is evenly spaced out represents the beat until the next Tempo Event.
To create a new Tempo Event, right click on the Tempo Panel. To shift a Tempo Event, left-click and drag the Tempo Event. This will cause all the Tempo Lines after the Tempo Event to also shift in the same direction.
Tempo Lines can not be created directly, only shifted to change the rate of the beat. To shift a set of Tempo Lines, click and drag on any tempo line to shift it left or right. You will notice the others shift automatically so that the entire set between the last and next Tempo Event is evenly spaced.
Tempo Events can be deleted by selecting them and hitting the Del key.
An additional feature that the Tempo Panel can do is display natural beats of the song, although creating this beats is a little tedious. In order to do so, go to the beginning and hit the Play button. Now at each song beat, hit the "b" key. Although KR Maker won't react, it is recording every time the "b" key is hit.
When the song finishes or is stopped, red lines will appear whenever the "b" key is hit, showing the natural beat of the song. The "c" key can be used to clear out all the red marks so this process can be repeated.
In addition, you can use the "b" and "c" keys to mark when words are sung in the song. This should help you line up the notes.
Note: the beat timing are not perfect, since the program has difficulty determining exactly how long the delay is before the audio is played through the speakers.

## Lyrics Panel

The Lyrics Panel is used to add lyrics to the notes. Each note line can contain a piece of text, and text cannot exist without a note line.

### Adding a Period

If the text contains a '.', this will end the verse and causes a line to appear in KR Maker at the end of the note. This corresponds with a line marking the end of the verse within KR:
Verse Line within KR Maker, created by adding a '.' to the text.
Verse Line highlighted in red within KR

### Adding a Dollar Sign

A '.' with a '$' will cause KR not to score the verse. A '$' must have a '.' to go along with it, and the entire previous verse will note be scored
Adding a '$' will cause KR not to score a verse.
An unscored verse in KR.

### Adding a Plus Sign

A '+' will cause KR to add a diagonal line between notes. A '+' can be added to a note containing any combination of no text, text, '.' and '.$'.
A '+' sign will cause KR to slur notes together
Notes slurred together in KR

## Vocal / Master Track Panel

This shows the vocal or master track (if there is only one track, then the vocal channel is used for it).
A loop can be selected, by clicking the left mouse button at the start of the loop and the right mouse button at the end of the loop (or vice versa). Then, it can be played by clicking the Play button.

## Background Track Panel

This shows the background track, if any. Along with the vocals channel, a loop selected can be made here. See Vocal / Master Track Panel for more details.

## KR Events Panel

This panel contains KR Events which perform various operations.
KR Events can be added by holding down the right mouse button and selecting the event type from the menu.
KR Events can moved by dragging them with the left mouse button and deleted by selecting the event and hitting the Del key.
Here is a list of all of them with a description if I have any idea what they do. All events beginning with "tut_" deal with the tutorial are aren't present in the normal songs.

- bass_off - causes the bass player in the background to stop playing
- bass_on - causes the bass player in the background to start playing
- bridge
- chorus
- clap_off - turns off audience clap
- dj_off
- dj_on
- drum_off - causes the drummer in the background to stop playing
- drum_on - causes the drummer in the background to start playing
- gtr_off - causes the guitar player in the background to stop playing
- gtr_on - causes the guitar player in the background to start playing
- gtr_solo_1 - causes the guitar player to do some special movement
- gtr_solo_2 - causes the guitar player to do some other special movement
- gtr_solo_off - turns off that special movement
- intro_end - should to be present before the lyrics begin, not sure what it does
- keys_off - causes the keyboard player in the background to stop playing
- keys_on - causes the keyboard player in the background to start playing
- keys_solo_1 - causes the keyboard player to do some special movement
- keys_solo_off - turns off that special movement
- long_off
- long_on
- singer_final_pos - should be done sometime after singing
- singer_mic_down - singer moves the mic down
- singer_mic_up - singer moves the mic up to begin singing
- singer_no_changes
- song_end - should be present at the end of the song
- tut_arrow_off
- tut_box_off
- tut_combo_box_on
- tut_crowdmeter_boot
- tut_crowdmeter_box_on
- tut_crowdmeter_green
- tut_crowdmeter_peak
- tut_crowdmeter_red
- tut_crowdmeter_yellow
- tut_interactive1_demo
- tut_interactive1_start
- tut_interactive2_start
- tut_limit_rating_bad
- tut_limit_rating_good
- tut_limit_rating_great
- tut_limit_rating_ok
- tut_lyrics_box_on
- tut_msg_complete
- tut_msg_getready
- tut_msg_go
- tut_msg_lastone
- tut_msg_listenclosely
- tut_msg_onemore
- tut_msg_ready
- tut_msg_welcome
- tut_notetubes_box_on
- tut_nowbar_arrow_on
- tut_phrasemeter_box_on
- tut_pitcharrow_box_on
- tut_score_box_on
- tut_stop_mic
- venue_bonus - this causes some special thing to happen, if the singer is singing well enough, (ex. in the station, a train will go by. On stage, rose petals will come down)
- verse
- win_lose - needs to be shown after the last verse is displayed. I think this corresponds with the notes disappearing and the song ending

## Controls Panel

These are pretty self explanatory, but here is a description of each component.

- The Slider - controls the position in the song
- Play - Plays the song. Sound is generated for each note created in the Note Panel (except sliding sounds)
- Play Loop - if loop markers are created in the Vocals or Background Track Panels, then this will play the song, looping from the first marker to the second
- Stop - Stops playing
- 1/2 speed, 3/4 speed, full speed - change the speed of the song when playing. This will also change the pitch of the notesto match the adjusted pitch of the song.
- Output Volume - Master Volume
- Bkg Volume - Volume of Background Audio Track
- Vocals Volume - Volume of Vocals Audio Track
- Tune Volume - Volume of midi notes played when playing the song
- UI Volume - Volume of the sounds created when adjusting notes and not playing a song.

Note that with exception to the Output Volume, if one volume control is turned down or muted, the rest of the volume for the inputs will go up.

## File Menu

### Load Vocals / Master Audio Track

This will allow you to load an audio clip into the Vocals Track Panel. Currently, mp3 and wav are supported. If you do not have separate vocals and background audio files, (which is true for most music), you can use this option and "Edit / Derive background from vocals (L-R method)" to create a background track. See Derive background from vocals (L-R method) for more info.
This track will correspond to what the user hears when they turn up the "Vocals" volume in KR.

### Load Background Audio Track

This loads an audio clip into the Background Track Panel. As mentioned above, the background track can also be derived from the vocals (sort of) using "Edit / Derive background from vocals (L-R method)"
This track will correspond to what the user hears when they turn up the "Backgrounds" volume in KR.

### Clear Vocals / Master Audio Track

Deletes the audio clip from memory for the Vocals / Master Track.

### Clear Background Audio Track

Deletes the audio clip from memory for the Background Track.

### Load Midi Tune

Load Midi Tune will allow you to load the following:

- A KR Midi file or a midi file you have already been working on.
- A standard midi or karaoke midi file(not created to be played within KR.)

After specifying the midi file to load, and if the midi file is not a KR midi, a window will pop up showing the tracks within the midi:
The Lyrics column lets you choose which track to extract text from. KR Maker will attempt to line up the text with the notes from the melody. If there are not enough notes, some text may be clipped. KR Maker will usually select the correct track for lyrics when the panel comes up. (It does this by searching for the track with the most text in it, so if it chooses none, you can be pretty certain the midi file doesn't contain lyrics.)
The Tune column lets you choose which track to extract the tune from. Only one note can exist at any one time in the KR song. If two notes overlap, then the second note will be clipped so it does not overlap with the first. KR Maker will attempt to choose a midi track for the tune if it was able to find a probable Lyrics column. If the midi file does not contain lyrics, KR Maker will not attempt to find a Tune midi track and the track must be selected manually. KR attempts to determine the best midi track by finding the one with the most notes that match the lyrics track.
The KR Events column chooses a track which contains KR Events. These are specific to KR and won't be in any midi or karaoke file not specifically made for KR, and you will usually want to leave this as none. If set to none, KR Maker will create some default KR Events, so that the song will play correctly within KR, but these can be adjusted for in-song effects. For more info on KR Events, see KR Events Panel.

### Save KR Midi Only

Saves a KR Midi file which will include all changes to the Vocal Notes Panel, Tempo Panel, Lyrics Panel, and KR Event Panel.

### Save KR Song Package

This will save the KR Song in a zip file that can be later placed into KR.
When selected, the following dialog will appear:

- Song Abbreviation

The zip file produced will be in the form <song abbr>.zip.

- Directory

The package will be placed in this directory.

- db.dta entry

This text will be inserted into the "db.dta" file when unpackaged into KR.
The text "<Artist - Album - Song>" should be replaced with the song details.

- songs.dta entry

This text will be inserted into the "songs.dta" file when unpackaged into KR.
The "<Title>" and "<Artist>" text needs to be replaced in songs.dta. The complexity, bpm, genre, preview, hud_time_scale, hud_lyric_scale, boot_sound and stage_chars can also be tweaked.
A KR package can be unpackaged using KRUnpackager, or unpackaged manually.
It contains the following files:

- db.dta.entry - inserted into db.dta "hi_scores" entry
- songs.dta.entry - added to the end of songs.dta
- xadpcm/<song_abbr>_bg.wav - background audio track
- xadpcm/<song_abbr>_vox.wav - foreground audio track
- songs/<song_abbr>/<song_abbr>.mid - KR midi file

## Edit Menu

### Derive Background from Vocals / Master (L-R method)

This assumes that a master audio clip has been loaded into the Vocals track. (A master audio clip contains both the background and vocals merged into one single audio clip, which is the format of most music). This operation will attempt to derive the background music without vocals by subtracting the left channel from the right channel from the Vocals audio clip and place it in the Right Background Audio Clip. It will also subtract the right channel from the left and place it in the Left Background Audio Clip. The vocals track will be left alone.
The idea behind this method, is that in some songs the main singer is exactly centered on both the left and the right channels. By inverting the right channel and adding it to the left, the sound that is exactly centered will disappear, leaving just the right and the left channels. Mathematically, it looks sort of like this:

- Vocals Left is L + C (left + center)
- Vocals Right is R + C (right + center)
- Background Left is Vocals Right minus Vocals Left which is (R + C) - (L + C) = R - L
- Background Right is Vocals Left minus Vocals Right which is (L + C) - (R + C) = L - R

In KR, the vocals and background tracks are mixed, so what is outputted to the speakers looks something like this:

- KR Left is (Vocals Left * Vocals Volume) + (Background Left * Background Volume) which is (L + C) * vv + (R - L) * bv
- KR Right is (Vocals Right * Vocals Volume) + (Background Right * Background Volume) which is (R + C) * vv + (L - R) * bv

So the end result is that by turning up the background and lowering the vocals in KR, the singers vocals will be drowned out. If you turn up the vocals without the background, the song will sound normal. If you turn up the vocals and the background up, the left and right channels will be switched. It's a little screwy, but it's the best I could think of.

### View Vocals FFT in note scale

This will perform a Fourier Transform on the Vocals / Master track and display the frequencies in the Vocal Note Panel. This may help when creating the notes, depending on the song.

### Generate KR Events

This will clear and regenerate a default set of KREvents to match the song. The correct intro and end song events will be created, and the singer mic up and mic down events will also be created before and after groups of notes.

## KRUnpackager

The KRUnpackager is used to transfer one or more songs into the directory structure of KR. To use, perform the following steps:

1. Make a directory for unpacking.
2. Copy <kr_base>/config/db.dta and <kr_base>/config/songs.dta from the installation into the directory.
3. Copy all the files from <kr_base>/songs/<any random song>/ into the directory. There are some files which handle the singer's lip syncing and so forth that need to be present. KRUnpackager will copy these extra files into the songs that are created.
4. cd to the directory and run:

In Linux:
<krmaker_home>/krupackager.sh -songs songs.dta -db db.dta song1.zip song2.zip ...
or in Windows:
<krmaker_home>\KRUnpackager.bat -songs songs.dta -db db.dta song1.zip song2.zip ...
where song1.zip, song2.zip ... are the song packages that you want to extract.
KRUnpackager will update "songs.dta", "db.dta" and create a "songs" directory and an "xadpcm" directory.
4. Copy the following from the unpacking directory to the Xbox installation directory:

- db.dta,songs.dta to <kr_base>/config/.
- everything in the "songs" dir into <kr_base>/songs/
- everything in the "xadpcm" directory into <kr_base>/xadpcm/

5. Remove cache. The cache has to be removed on the xbox for KR to recognize the new songs. In order to do this, remove everything in the X:, Y:, and Z: drives and everything in E:/CACHE on the xbox.
6. When starting KR, it will prompt you to load the existing save file, and select "No" for this. (Hopefully in the future, I will find someway to add new songs while still using the save file..)

## How to Quickly Create A Song

NOTE: You will probably need to refer to the manual above some to follow this tutorial.
The easiest way to create a song for KR is to find a midi karaoke (.kar) file, and combine it with the mp3 or audio clip of the same song, do this with "File - Load Midi Tune" and "File - Load Vocals / Master Track".
Then shift the notes back and forth to match the song. To do this, go through the song from the beginning, and shift the notes until they match the tune by holding down the ctrl key and the left mouse button. This will allow you to move the current note and all notes past it forwards and backwards.
To help you with this, play the song for a particular verse, and hit the 'b' key when each word is sung. This will show up as red lines when the song is stopped, and this should allow you to line up the notes to the words much easier. To clear the red lines, hit 'c'.
You can setup where verses will end, by adding or removing a '.' at the end of words. You can join notes together by adding a '+' to the corresponding word of the second note.
After you are done, choose "Edit - Generate KR Events" and then setup the tempo lines, or add the "clap_off" KR event at the beginning of the song to turn off audience clapping.
To save your in progress work, use "File - Save KR Midi Only" (and then "File - Load Midi Tune" to reload it). When you are ready to create your KR song, use "Save KR Song Package". In the window that pops up, choose a song abbreviation and just fill in "<Title>" and "<Artist>" in the songs.dta entry. Hit Submit and you are done!

## Building from Source

Requirements:

- Sun's jdk 1.5
- Apache Apache Ant (tested with version 1.6.5)

1. Create a krmaker directory.
2. cd to that directory and type "unzip krmaker-0.1.zip".
3. cd to "src", unset your classpath and run "ant" to build the project.
You can also use eclipse or some other IDE. Include source files in:

- krmaker/src
- krmaker/tritonus/src/classes
- krmaker/tritonus/src/packaging/tritonus_all

Include all libraries in "krmaker/lib".

## TODO

- Update KR Maker to work using Karaoke Revolution Party.

The major difference between KRP and KR is that KRP uses a 4 channel ogg/vorbis file for audio clips. This should make it pretty simple, the only problem is that KRP uses a special archive with a ".ark" extension to hold all it's files, so the archive needs to be understood before files could be added to KRP.
If someone has some information to add / edit files to the archive or knows some other way to get around this, please email me.

- Make the FFT view work better.

Currently, the FFT view is accurate, but the singers notes are usually hidden by the instruments. I'd like to find some way to make it easier to see the singers notes.

- Support ogg and maybe some other formats.

I just haven't gotten around to do this.

- Nicer kr package creation screen

Currently, it makes you edit the songs.dta and db.dta by hand.

- Keep save file when adding songs.

Currently, the save file must not be loaded to see new songs.

- Make the singers lips move correctly to the music.

This seems kind of hopeless, and I don't think it detracts too much to have the singer not follow the music exactly

## Requests for Help

I think the most important of these is to get KR Maker to work with Karaoke Revolution Party. In order to do this, I need help with the ".ark" files. If someone could

- find a way to edit / add files to the .ark files, or
- find a way so that KRP will read song files outside of the archive

The other thing I would like is the ability to keep save files when adding songs to KR. If someone could figure this out, I would be grateful.
Given this, I should be able to get KR Maker to work with Karaoke Revolution Party. If
anyone has info about this, put up a message on the xbox-scene forums in "Xbox-Scene Online Web Community > Xbox Game Forums > Game Hacking > Game Hacking - * Everything Else.*"
Also, if anyone wants to work on KR Maker themselves, or host it, go ahead...