UltraStar: Getting Started & Adding Songs

Please note: my UltraStar guides now have their own dedicated website on UltraGuide.net. An updated version of this article can be found here

Start off by downloading the program from the official website: http://ultrastardx.sourceforge.net/usdx-downloads/usdx/

There are a number of options on the above link. Though the current version of UltraStar isn’t actually final, it’s pretty damn awesome and much better than the older versions. It’s very stable and runs well. To obtain this version, click on the installation appropriate for your operating system, and download the installation file.

The ChallengeMod is fantastic as well, but that’s for another time.

Once it’s downloaded and installed, run UltraStar Deluxe. The start screen will look something like this:

1)       Sing – what it says on the tin. It will take you to your collection of songs, and you can browse through them using the left and right keys, pressing enter to make your selection.

2)       Party – As I mentioned in my last entry, this takes the game to a whole new level when you’ve got a group of people playing, with various different modes including blind (the notes do not show), first to 5000 (the song ends when 1 player has achieved this), and ‘pass the mic’ (where the whole group gets involved). The game chooses which players from each team are going to sing on each round. It is typically played across 7 rounds; the team with the most points across the rounds is the overall winner.

3)       Tools – this contains a MIDI file converter (more on this at another stage) and setup options. These will be necessary when you set up your microphones, and like most programs it offers options for changing the appearance and turning on/off certain features.

4)       Quit – self-explanatory.

I would recommend going into the ‘Sing’ option and selecting one of the sample songs as a starting point. There should be a couple of freebies in there. Even though your microphones won’t be set up yet, it gives you an idea of the gameplay. Use ‘escape’ to exit the song.

Adding songs

The necessary files for the songs are stored in a folder in the UltraStar directory. To add them, you should create a new folder for each song you add in C:\UltraStar Deluxe\Songs (unless you specified a different directory on installation). Give the folder a name that will make it easy to identify, such as ‘Cheryl Cole – Fight For This Love.’ Within each song folder, as the bare minimum, you will require:

1) A .txt file tailored for the song in question (more on this in a second)

2) An mp3 of the song

Optionally, the following types of file can also be added to the folder. These are not essential but do enhance the gameplay experience:

3) The song’s music video (most standard video formats are compatible with UltraStar, such as .avi, .flv, .wmv, .mp4).

4) An image to display in the background of the song while it is being played (this is an alternative option to having a video. If a video file is set to play, then the image will not be displayed).

5) A CD cover image of the song (or the album that it’s from). This will then be displayed when you flick through the songs on the selection screen.

I won’t go into the latter 3 options at this stage (they’re not hard to add, but I’m trying to keep this as simple as possible). Instead, I will concentrate on the 2 files that you really need: a txt file and an mp3.

First of all, to really get started, you can easily obtain all the files you need for all songs that are on the existing SingStar games. In certain places. On these places, just search for UltraStar, and you’ll have a number of things to choose, including homemade packs and the aforementioned SingStar games. If that method’s not your cup of tea, but you already own some of the SingStar games, there are programs that will rip your games onto the computer for you, which you can find on the old UltraStar Deluxe Wiki.

I’ve never tried these programs myself, and don’t know how up-to-date those links are, but presumably they’re straightforward enough.

The following method of adding songs applies to anyone reading this. If the options above aren’t applicable to you, or you want to add some non-SingStar songs, follow the steps below.

1)       In order to obtain a .txt file of a song, there are a number of websites you can use. By far the best one I’ve found is http://usdb.animux.de. You’ll need to sign up with an account first, but this is easy enough. Once you are able to login, you will have access to thousands of .txt files (NOTE: the mp3s are not available here, more on this in a second). Remember, .txt files only contain information about how to display the correct notes and lyrics at the correct time.

2)       Select “browse songs” on the left hand side, and you can surf this site by artist, genre, or SingStar editions (these files are direct rips from SingStar using a program like the ones I’ve linked above).

3)       Find and click on a song you like. To make this easier, though, try and find one that’s rated 5 stars. That’s not to say that anything less (or none at all) is a bad file, but it’ll make things easier to begin with. In bad text files, notes can be wrong and the lyrics may be out of time.

4)       It’s also advisable to make this a song that you already own in mp3 format. Unfortunately, this is the only compatible audio format with UltraStar, so if you’ve downloaded it from iTunes, for example, you may need to download a program to convert it into mp3 format.

5)       Click on ‘download text.’ This will then take around 30 seconds to load, unfortunately. As the site says, you can reduce this time by adding your own song files to the database.

6)       When it’s loaded, save the .txt onto your computer (preferably in the folder in the UltraStar songs directory that you’ve already created, e.g. C:\UltraStar Deluxe\Songs\Cheryl Cole – Fight For This Love).

7)       Find/obtain an mp3 of the song, and put this in the same folder.

8)       Open the .txt file. The document should look something like this:

9)       The information at the top of the file is known as ‘tags.’ Each aspect, e.g. #ARTIST, #SONG, #EDITION, #MP3, #GENRE etc, is known as a ‘tag.’ The one that we are interested in at this point is #MP3. The filename next to the tag should be identical to the filename of your mp3. If it’s not already, then either change the tag to the filename of your mp3, or change the name of the mp3 to that listed in the tag. When you have done this, you have effectively ‘synchronised’ the .txt with the mp3.

10)   Save the .txt, and load UltraStar Deluxe. If all goes to plan, when you go into the ‘Sing’ option, your new song will appear. If it doesn’t, retrace your steps and check the .txt file again. Does it have .mp3 on the end? This is essential. Is there a rogue space somewhere? It needs to match the filename exactly.

11)   You may want to try playing the song now. Do the lyrics start at the right time and enlarge at exactly the right points? If so, then you’re very lucky. If not, then it’s to be expected. This is because not all mp3s are the same – some contain a significant amount of silence before the song starts (and others don’t), though you may not realise it. The person who made the .txt file will have been working with a different mp3 to the one that you own (or possibly the video version of the song, which tend to have longer introductions).

12)   If you’re one of the lucky ones, and the lyrics of the song effectively pop up as Cheryl Cole is singing, then you don’t need to do any more at this stage. However, you’ll probably need the next bit of information, because the next song might not be as simple!

13)   Press escape to exit the song, and again until you’re back at the song menu (where it’s showing a preview of the song, just before you select it to start singing). Instead of pressing enter, hit the letter ‘E’ on the keyboard. This brings up the built in song editor.

14)   What you need to do, now, is adjust the #GAP tag on the song’s .txt file so that it allows the exact amount of time you need before the lyrics start, no more and no less. This can be achieved using this built-in song editor, on screen now.

15)   The #GAP is a given amount of time in milliseconds before the very first note/syllable starts. For Cheryl Cole’s Fight For This Love, this allows for a brief instrumental introduction at the beginning (and for most songs, this is the case).

16)   You’ll notice that the first line of the song is displayed, and the first syllable highlighted. Press the space bar. It will play a very brief snippet of the audio that is currently set to appear at that point. Is it before the syllable you want, or is it after? A general giveaway for this is whether it sounds instrumental (the song starts too early) or whether it is the singer’s voice (it starts too late).

17)   If it is too early, you need to INCREASE the gap by pressing the ‘0’ (zero) key. If it is too late, then you need to DECREASE the gap by pressing the ‘9’ key.

18)   You’ll see the #GAP tag on the above section starting to change. This may require some trial and error. As you alter the #GAP, press space every so often, and see what difference it’s made.

19)   Remember that you are decreasing/increasing the #GAP a millisecond (1000th of a second) at a time, so you’ll need to press it a few times. If the song is drastically out of synch, then press ‘shift’ + either 9 or 0. This will change the #GAP a second at a time, but this may be too much of a jump if the song is only slightly out of synch.

20)   In short, what you are looking for is for the first note to play the syllable at the start of the song, nothing more and nothing less. In this case, I want Cheryl Cole saying ‘Too,’ not a slight bit of music and ‘T-‘. It’s tedious, but once you get the hang of it, it’s straightforward.

21)   If this note doesn’t give you much to go on and you’re finding it a struggle, you can try playing around with a different one. Navigate between notes using the left and right keys, and to different lines using the up and down keys. If the audio synchronises with the new syllable, it will synchronise with the rest.

22)   Hopefully you’ll achieve this without too much hassle, and remember that once you get the hang of it, the process will be much quicker (I usually jump straight to this editor before I even play the song, after adding a new one).


a.       Have you managed to make the song synchronise with the text? If so, press ‘S’ to save the changes. It will not prompt you to do this, so it’s very important to remember!

b.       Have you made a complete mess of it and want to start over? Just press escape and exit without saving… no harm done!

24)   Exit the editor by pressing escape. It will take you back to the song selection screen. Select the song you were working on, and hopefully it’ll display perfectly!

25)   Either repeat these steps for the other 1,999 songs you want to add, or add them automatically by other means ;)


a.       A small number of .txt files have a set starting point as well as a #GAP. It’s difficult to explain this, but if you come across one of these .txts, you can put the #GAP in negative figures if necessary! You don’t need to worry about this for now, just remember that it’s a possibility.

b.       Don’t despair if you don’t have an mp3 of the song. In my forthcoming guide to adding video files, you won’t need to have the mp3s already, because you use the audio that is on the video file.

Next up: how to set up the microphones!


43 Responses to “UltraStar: Getting Started & Adding Songs”

  1. […] I actually really hate Cheryl Cole’s ‘Fight For This Love,’ the song that I used in my adding songs tutorial, but I decided to put it on there, because some people like it (failing that, a lot of people at […]

  2. Hi,

    Your tutorial is really useful, but i still have a problem:
    If i make a change in the song by changing the GAP because the synchronisation isn’t right, i can’t save it. There’s a save error. So i can’t synchronise my songs with the text.
    Do you have a solution for that?


    • Hi

      I don’t have a straightforward answer for that question as it’s not a problem I’ve come across before. Does it happen with all of the songs or did you just try one? What does the save error say?

      If it’s occurring with all of them, then the main cause I can think of is if the .txt file is somehow write-protected. If you go into your UltraStar directory and find the .txt file, and right click on it and go to ‘Properties,’ is there a box ticked saying ‘Read Only?’ If so, that might be why the editor can’t save the changes. If you unselect read only for the whole directory then it should work.

      Failing that, have you tried the ChallengeMod (http://ultrastardx.sourceforge.net/usdx-downloads/usdx/#stable) version of UltraStar? I find that the editor on that is a bit better, and if we can’t work out why the main version of UltraStar isn’t saving the changes, then for whatever reason, the ChallengeMod might be able to save the file where the main version can’t. You can still use the main version of UltraStar to play the game, but you can use the ChallengeMod to edit the songs (it works in exactly the same way). If you download the latest version of the ChallengeMod, it’ll install by default to a different directory, so you can have both versions on your computer at the same time. Copy some songs over to the songs folder in the ChallengeMod directory and see if they will work with the built-in editor. It’ll be a slightly different way of doing things but it won’t make much of a difference. If the song works in ChallengeMod, then it’ll work in the main version.

      If these solutions don’t work then let me know

  3. Brill! Have fun :D

  4. Hi,

    Thanks a lot for making these guides! They’ve really gotten me started using UltraStar.

    One problem you rather helped create than aid with is where I can find that Super Mario tune? It would be awesome to have!

    I’ve searched the normal sites but I can’t seem to find it…

    Any hint regarding this would be greatly appreciated!

    • One additional thing actually;
      I’m trying to add a song and the preview works fine with both sound and video, but when I press enter and want to start singing – it says that the song couldn’t be loaded.

      Any solution spring to mind?

      Thanks again,

      • The reason that it’s not loading will be to do with an error in the .txt file somewhere; for example, a line break may appear in the wrong place, it might be missing a #BPM tag… there are a few things that can make it fail to load. Within the UltraStar directory there is a .txt file called “Error” that will list all the problems with all of your .txt files – there will probably be quite a few errors listed across your collection, but it’s not normally a problem.

        You need to find the song that isn’t loading within this list of errors, and rectify all problems with the file. The statements will read like this:

        Note length error in sentence 34, on beat 1190 in song C:\UltraStar Deluxe\Songs\Artist – Title.txt

        This means that the problem lies with beat 1190, so you need to scroll down the list of notes/lyrics until you find that particular beat:

        : 1188 2 7 Gott
        : 1190 8 5 catch
        : 1192 2 14 ’em
        : 1194 2 12 all
        : 1196 12 10 ~
        : 1212 2 14 ~

        The number in the middle part of each line (after the beat) refers to the note length. The note length should not be so long that it overlaps the next beat… in the example above, line 1190 lasts for 8 beats on its own, which is silly, because the next line starts just 2 beats afterwards (1192). This would require the player to sing two different notes at the same time, which doesn’t make sense. So you just need to change the note length to ‘2’ instead of ‘8.’ The example would then read as follows:

        : 1188 2 7 Gott
        : 1190 2 5 catch
        : 1192 2 14 ’em
        : 1194 2 12 all
        : 1196 12 10 ~
        : 1212 2 14 ~

        You can also get a ‘beat error,’ which reads like this:

        Beat error in sentence 52, on beat 2229 in song C:\Program Files\UltraStar Deluxe\Songs\Artist – Title.txt

        These usually occur when the beats, or the line breaks, are listed in the wrong order. For example:

        : 2196 11 19 Oh,
        : 2207 3 19 you’re
        : 2210 5 22 my
        : 2215 5 19 best
        : 2220 9 17 friend
        – 2232
        : 2229 3 10 In
        : 2232 2 12 a
        : 2234 6 14 world
        : 2240 3 14 we
        : 2243 5 12 must
        : 2248 4 10 def
        : 2252 19 14 end

        The error referred to beat 2229, and if we look at it, we will see that the line break that occurs right before it signifies the beat to occur on beat 2232, which doesn’t make sense, as we want it to be a number less than 2229. Line breaks can occur at any time between beats, so you don’t need to worry about how you change this – just make sure it allows enough time for the previous line to finish, and the next line to start. As the previous note (2220) has a note length of 9 beats, the line break should really read 2229, as it is the only possible way that it can wait for the last line to finish and the next line to start. So, with the correct adjustments:

        : 2196 11 19 Oh,
        : 2207 3 19 you’re
        : 2210 5 22 my
        : 2215 5 19 best
        : 2220 9 17 friend
        – 2229
        : 2229 3 10 In
        : 2232 2 12 a
        : 2234 6 14 world
        : 2240 3 14 we
        : 2243 5 12 must
        : 2248 4 10 def
        : 2252 19 14 end

        This may be a little bit convoluted and for that I apologise. I’d recommend giving it a go though, as it really helps you to understand the ins and outs of .txt files (I learned a lot about UltraStar by going through and troubleshooting all of them!). However, if you’re stuck, feel free to email me the .txt file or point out where it is, and I’ll see what’s up with it :) Hope this is some help anyway!

    • Thanks for commenting Jacob. The Mario theme is a special acapella version called “Platforms a Plenty!” by Koji Kondo & Shinobu Tanaka (this is how it’s listed on USDB!) and you can find it here: http://www.youtube.com/watch?v=10OF-sYzvHE

      • Whoa! The answer was so massive that I managed to miss it, thanks a lot!

        However, sadly none of the errors you listed is what I receive (even though I believe that will be very helpful to know eventually!) – it simply says “ERROR: BPM tag missing: E:\ (directory + song.txt)”.

        At first I thought that it meant that the .txt author had missed one of the three figures in one line so that the program read it wrong, but I don’t think that’s the case after looking it through.

        Do you know what the error I receive might mean?

        Thanks again,

  5. Ah, so that’s why I couldn’t find it. I searched for Super Mario and stuff.

    Do you have any idea regarding the second question?

    • RE: BPM tag – this refers to the Beats Per Minute and it is needed in the topmost section of the file for the .txt file to work, so that would explain why US is refusing to load it. I’m not sure why it wouldn’t be there, what song is it? Where did you get it from?

      • On row 5 it says “#BPM:274,17”, is that what you refer to?

        The song is Red Hot Chili Peppers – Can’t Stop. Got the audio & video from youtube and the .txt from USDB.

        Would you mind to take a quick look at it if I send it too you?

    • Feel free to, though I think I know that you need to do. According to USDB, the BPM is 274,17, so you just need to add the #BPM tag into the file (may be it got deleted by accident when you were changing the mp3 filename or something, I think I’ve done that before).

      Should read something like this:

      #ARTIST:Red Hot Chili Peppers
      #TITLE:Can´t Stop
      #MP3:Red Hot Chili Peppers – Can´t Stop.mp3

      • I’m sorry if I was vague, but what I meant to say was that the said tag has been there the entire time.

        I’ll send you the .txt, in the exact shape I’m using it.

        2 sec,

  6. My download Ultra star can not be marvelous as it is now without your effort creating this page with a very good impressive explanation you have done benefiting us all…..

    Thank you very much!!!!!!

  7. Elaine Nelson Says:

    I have been using Ultrastar for a few years & decided to make my own text files, unfortunately they are not showing & I Have no understanding as to the why!!! Exact titles etc what can be the reason for none of the lyrics to show? Any advice much appreciated guys. Thanks Elaine x

    • Elaine

      Feel free to email me the .txt file, or you could simply paste its contents into a comment. It’s tricky to know why without examining it in more detail, there could be a few reasons why it’s not working.

  8. Hi thanks for the tutorial – any ideas on how to fix my problem:
    I have correctly saved and named the txt and mp3 files but US deluxe still doesn’t pick up the songs.
    When chosing tools>editor to find songs, rather than looking in registry C:\Program Files\Ultrastar Deluxe\Songs it defaults to C:\Program Files\Ultrastar Deluxe\mid. and if you try to change it instanly crashes?!?

    Looks like a really neat bit of software if only Icould ever get it to recognize a song!

    Any tips greatly appreciated.

    • Hi Jon

      I’m really sorry for the delayed reply, but I only just saw this comment in my inbox!

      I hope this isn’t too late and that you’re still interested in trying the software, or you’ve managed to fix it. Can I just clarify – are you trying to get UltraStar to read the song directory? The editor on the tools menu is there for song creation from scratch, rather than to read .txt files that already exist. The directory that this toll defaults to is unrelated to your normal songs directory.

      How many songs have you got saved? Is it not picking up any of them?

      – Kokairu

  9. Hi there – thanks for the really really helpful tutorial!! :)
    Just a query that i’ll probably kick myself for not knowing… haha
    I have a mac and downloaded the mac version of Ultrastar and when I try to go to the ‘Editor’ section it says that ‘this feature is not included for mac’…. is there a way around this?
    Your help would be verrrrry greatly appreciated! :)
    Many thanks :)


    • Hi Emily,

      I’m sorry to say that I am completely unfamiliar with the mac version of UltraStar – it’s news to me that the editor doesn’t work! Have you tried different versions of UltraStar or just the one? It’s possible to have multiple installations on one computer. Failing that, have you got a Windows PC that you could use just for the editing part?

      Sorry I can’t be more helpful. I recommend posting in the “Say something” section of USDB – they’re always really helpful on there :)

  10. Amazing tutorial. Thanks a lot… Thanks a lo… Thanks a lot, Kokairu!

  11. myeolchi Says:

    can someone tell me why the music video won’t show? :/

  12. Kallos Tamas Says:

    Hey there guys! I just wanted to ask something…I have this little problem at ultrastar,when I change to 2 players the no.1 microphone is singing the no.2 microphone too,so actually I’m playing alone but I would like to battle and play 1v1…Could somebody help me? Thanks

  13. Alas, I can’t play because I always get “”Loadlibrary fialed with error 126”. Same thing with Performous. I am exiled to the world of Vocaluxe :/

    Do you know how to define a cover image for a *folder* ?

    • Well, it could be worse! Vocaluxe looks very promising, it’s just a shame that it’s not quite at the same stage in terms of features.

      Sorry I didn’t get back to you earlier – I’ve still not migrated to Vocaluxe yet and had to have a play around. In order to define a cover image for a folder, you need to name your image of choice the same name as your folder in PNG format (though JPG might work too, I haven’t tried it) and move it to \Cover\Blue section of your Vocaluxe directory. The game should automatically pick it up :)

      I must confess that’s a pretty nifty feature…!

      • Alas, that didn’t work for me. My folder name has spaces in it, and so did my jpg, maybe there’s a bug regarding that. But really the covers should be part of the songs folder (shared between Ultrastar, Performous, and Vocaluxe for me)… they should have decided that when making “the standard” that all 3 games use. Hrm.

        I did get my driver problem worked out. Had to uninstall my drivers and re-install them. What a pain :) :)

      • Have you tried saving the images in PNG format though? Spaces shouldn’t affect it; I tested with spaces and it worked for me…

      • Yup…
        C:\GAMES\RHYTHM & MUSIC\KARAOKE\Vocaluxe v0.1.2 Final (0062)\Cover\Blue\My Little Pony.png

        for the folder:
        C:\GAMES\RHYTHM & MUSIC\KARAOKE\Vocaluxe v0.1.2 Final (0062)\songs\My Little Pony\

        No go…. Drat. Is there a maximum filesize? And how do you know the answers to these? I don’t seem to be able to find much documentation, or else I’d be looking there instead of asking on this blog, hehe :)

      • I found it on the Vocaluxe FB page, but I just realised it was probably you that asked the question… that, or it’s another Clint! ;) How useful is that, I post back an answer that was directed to you in the first place. I should just lie and say that I dug deep into the game’s source code to find out…

        Feel free to email me your image and I’ll see if I have any more luck? Have you had success with other image files?

      • Well, that is the only one I ever tried. Haven’t tried any others. Running back into me–haha! I guess there’s not much on the ‘net about this :) Too bad it isn’t in the docs. Is there a max image size perhaps?

        Really, the cover image for a folder of folders really ought to be in the \songs\ folder if you ask me anyway, so that it’s a repository-specific and not game-specific setting, as this repository of karaoke songs works for several different games (I have Ultrastar, Performous, and Vocaluxe all installed and pointing to the same repository of songs). I could email but I don’t know your email address. :) It was an image I pulled from one of the subfolders in question…. :)

      • As I’m not sure what image it is, mind sending it to me? It’s theultraguide (at) gmail (dot) com :)

        I need to get back onto the MLP karaoke project, got a bit sidelined with my new project unfortunately!

        Yeah, I have to say I still haven’t used Vocaluxe much at all, it doesn’t seem quite as intuitive as USDX (and even then I had to learn a lot of that through trial and error!).

  14. Hey I had the same problem as jandr but I’d where the ultrastar directory is? Help! Sorry I’m not smart:/ thanks!:)

  15. hye kokairu..
    can you teach me how to created my own text file b’coz most of the songs i like, i couldn’t find it on USDB..btw,thnk you so much for this tutorial..

  16. I actually blog too and I’m writing a little something related to this
    particular post, “UltraStar: Getting Started & Adding Songs The Bricky Blog”.

    Do you mind if perhaps Iapply a bit of of your suggestions?
    I appreciate it ,Sanford

  17. Genuinely when someone doesn’t understand after that its up to other visitors that they will help, so here it occurs.

  18. Javier Pizarro Says:

    Amazing tutorial, learned a lot in just an hour ;)

  19. […] definerer tekst og sang. Alt du trenger er en lydfil med selve låten du vil tralle deg gjennom. les mer her om hvordan du kan gjøre dette […]

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: