Karaoke Mapping Guide 3

Original guide by Zoggoth.
Karaoke Mapping Guide 2 last updated in 2023.
Current guide last updated in 2026.

To start mapping, it's a good idea to check how far along the process you should begin:

1. Check Our Karaoke Map System:
   We have our own system for karaoke maps, so start by checking there. These will display whether they are TV length or not, so check to make sure we have the correct version you'd like.
2. Community of Ultrastar Mappers:
   There is a community of Ultrastar mappers from which you can get maps. If the song you want is there, you can use the request page on our website, and the AV will get it from the aforementioned site.

These are the only ways we have to avoid you doing any work. Now, let's move on to the actual mapping section - but there’s one more thing to check.

3. Kara.moe Database:
   There's another database of songs on kara.moe. These are in the wrong format, but they can be reformatted with Karaluxer. This will greatly reduce the work you'll need to put in, but there is editing required in this process.
4. Not in Any Database?
   If the song you wish to map isn't in this database, then you will need to do everything yourself - this will be fully explained later.

Required Programs:

Begin with creating a folder to store all of these programs to ensure nothing is misplaced.

To convert songs from kara.moe you will need Karaluxer.
- Go through the README.md - it outlines some additional programs you’ll need to install.

To actually map songs install either Yass or Karedi, these are discussed in detail later.

For assistance in pitching your maps, use Ultrastar-Pitch.

To test your maps for any errors, use UltraStar Deluxe

If you ever have difficulty with acquiring these programs, feel free to ask for advice on our Discord channel under #karaoke-discussion.

Using Karaluxer:

There are two required dialogue boxes for Karaluxer:

• the Kara.moe URL
• a cover image (must be square and in standard format like JPEG or PNG).

To note, if the Kara.moe URL doesn’t work, you can input the specific files yourself (or if you want to improve/replace them).

Additional Understanding:

To have better comprehension to what Karaluxer is doing, you can go to the Kara.moe page click the download icon, and look at the pop-up that has a .json, .ass, and two .mp4 files (or any other video files). Karaluxer uses these files to generate files that are compatible with Ultrastar. These would be the files you need for inputting the files yourself.

Now that you have the Kara.moe URL and a cover image, you might notice a lot of other options. Most of these can be ignored, but some should be considered:

• TV Sized:
  Obviously, click this if it’s a TV-sized song, normally ~1.5 minutes, but openings and endings up to 2.5 minutes are allowed if they are the standard op or ed.
• BPM:
  To make a high-quality map and save you time, you want the BPM to be correct; As seen in the dialogue, this is defaulted to 1500. There are multiple ways of checking a song's BPM. The main two are using the song's sheet music or using a BPM checker. The BPM from an analyser will likely be wrong by a factor of 2 or 4 so multiply by whichever to land between 300-400. (You may need to run the Karaluxer twice in order to obtain a .mp3 for analysing).
• I do not recommend using any of the other dialogue options. The only one to consider would be to generate pitches, but it’s much easier to space the characters before pitching them.

Note for those mapping songs for Anisoc:
The output of Karaluxer without edits is not considered up to par for a submission. It won’t be added by the AV or will be deleted once we see it unless you improve the quality of the map.

Once Karaluxer completes the process, there will be a new file in output within the Karaluxer-main folder. The files will be named [artist] - [song name] [(TV)]. These files consist of:

• A cover image
• An audio file (MP3)
• A video file (normally MP4)
• A text file that contains the 'notes'

This is the only file that will be changed by any further editing. If you want, you can open it up and have a look. You can even manually change it, this is sometimes faster than using other applications.

Inside you will see a set of metadata for the song. Some of these can be changed and may need to be:

• If the #TITLE, #ARTIST or the file names have any special characters, they will need to be changed. (If the file names are changed they will have to be done so everywhere to ensure everything is read correctly)
• Add your name under #CREATOR if you’d like credit.
• You will also see #MP3, #COVER, and #VIDEO tags. These must correspond to the other files, if they don’t, the map will not work.
• The #BPM and #GAP are auto-set by Karaluxer, so they can be ignored.
• The last one would be #TAGS. These are not used on our system, but they can be cleared up if they look messy. Just make sure to keep the show name and the type of song (OP, ED, etc.).

The Map Content:

Note format:
: = Sung (regular note)
* = Gold note (worth 2x points)
F = Spoken (not worth points, use for dialogue)
- = Line break
E = End of song

The sung, gold and spoken notes are written as;

[format type] [note_start] [note_length] [pitch] [character]

And line breaks as;

- [note_start]

In addition to this, you need spaces within the characters to split up words. For instance:

: 303 5 1 One
: 309 7 3 piece
    

: 303 5 1 One
: 309 7 3  piece
    

Making Your Own Map:

Please skip this section if you do not plan to make your own map, as it may be confusing especially if you have no experience. It is recommended to use the Karaluxer method before this to gain experience.

There are a few options that you can start from to make your own map, but this section will briefly explain where to start if you plan to only use the programs listed above.

To make a map you will need to acquire a cover image, audio file and video file yourself, they will have to meet the same conditions as previously discussed.

Next, create a .txt file containing the map. Normally this is done by Karaluxer, but you can make your own file manually using this metadata:

#TITLE:Song Title
#ARTIST:Song Artist
#LANGUAGE:Japanese
#YEAR:
#CREATOR:
#MP3:Title.mp3
#COVER:Title [CO].jpg
#VIDEO:Title.mp4
#BPM: (use double or quadruple bpm for more precision)
#GAP:0
#TAGS: (can just be anime title and opening or ending e.g. Bleach, Opening)
    

Make sure all filenames exactly match the metadata in the .txt file otherwise the map will not load, also add "(TV)" at the end if needed (e.g., Aimer - Torches (TV).mp3). If you are having trouble, look at another map's .txt file and copy the format.

Lastly, you'll need to write in all the lyrics yourself and then position them the same way you would a normal map.

Editing a Map:

There are two main editors we use: Yass and Karedi. Both do the same thing but have positives and negatives. Have a go with both and see which one you prefer. The key binds of both programs are extremely similar but some might not work for Karedi:

In Yass, you will need to set the library to read from. I recommend creating a separate folder for the songs you are editing. They will then appear on the main page, which you can select to edit.

Whereas in Karedi, you need to open the desired song file each time. This can be done by selecting File and then Open.

In either case, you will now see a set of notes like this:

These should be in the rough locations of where the words are, but they will need to be edited.

Start with the first character in the line and move it to the left, so that at the end of the note you hear the beginning of said note. Then, move it to the other side of that position to get it in the correct place.

Next, make the note length too long (so you can hear the start of the next character) and then shorten it until you can no longer hear the next character (you can slow the song down in the top right).

The next note will likely start one beat after the previous one. Repeat these steps for the whole line and song. You’ll get better with practice, so don’t worry if this takes a while at first.

Additionally, if you have the correct BPM, then these notes will always start on an odd beat and be of odd length (1, 3, 5, etc.). Doing this will make your job much easier, and you’ll always have a one-space gap between notes at a minimum. This is important for producing a good map.

This process requires practice and you'll learn your own process to do it, this is advice and not rules for making a successful map.

The next step to a good map is pitching. This can be difficult, especially if you're tone-deaf, but there are ways to help. The easiest method is using Ultrastar-pitch.

This automatically pitches a song and produces a new file called notes_new. Rename this to the .txt file name in use and delete the old one.

This is not perfect as it pitches across the same octave. Very high pitches (C, D) can often end up at the bottom while they should be at the top, and very low pitches (A, B) can end up at the top. The main solution is to move blocks of notes that are obviously in the wrong place to the correct location.

This will still need to be checked as some notes can still be placed in the wrong locations. In both Yass and Karedi, there are ways to play the song alongside a piano to check if it’s correct. In Yass, press Shift + P, and in Karedi, press Ctrl + Space.

There are multiple strategies for pitching aside from the auto-pitcher: humming into a mic, using a MIDI, referencing sheet music, or checking YouTube piano covers. But this is completely up to you, as long as the pitching is very close they will be accepted (enough to where no one can tell during a karaoke).

Completing a Map and Testing:

The last step of the actual mapping is the lyrics. It's a good idea to check them for errors. The best way to do this is to open any online song lyric page. The easiest way to change them is to open the text file in Notepad and manually edit them.

Furthermore, there are issues with apostrophes in both the lyrics and filename that can cause issues in our system. Please remove them before submitting the map.

The last part of this is when the lines break. There aren’t specific rules, but think about how it would feel to sing them (a lot of times, online lyrics will be broken up appropriately).

Before submitting a map, test it by running it on your own system. Ultrastar or Vocaluxe can be used to check the lyrics, line breaks, and ensure the map works properly.

A convenient tool to make sure all maps run correctly is Ultrastar-Manager. It will show any issues with maps that may cause it to not run.

If you ever need help, you can ask on our Discord in #karaoke-discussion, and someone will help you out.

Anisoc Specific Submission Guide:

Once you have a map, you’ll need to submit it to the AV through discord so they can add it to the Karaoke system. Here are a few things you can do to help the AV out and ensure your song is working when you go to pick it:

1. Anime Source:
   If the song comes from an anime, provide the AV with the Anilist link for the anime along with your submission. This makes it easier to add the song to the website as it saves the AV from having to search for which anime the song is from.
2. Google Drive Upload:
   If you're uploading the song to Google Drive, make sure there aren’t any apostrophes in the filenames. Apostrophes will be replaced with underscores (e.g., MINMI - Who's Theme.mp3 becomes MINMI - Who_s Theme.mp3). This will break the map, as Vocaluxe won’t be able to find the files for the map. You can avoid this by removing apostrophes (make sure to update the Ultrastar file to point to the new filenames) or by placing the song inside a zip and uploading that.
3. Video File Size:
   Lastly, if the video file for your map is very large (>100-200MB), it’s worth encoding it to a lower quality to reduce its size (some very large videos can also lag). You’ll need to find out how to do this yourself, but Handbrake and FFMPEG are free tools with plenty of documentation that will help you do this easily.