UltraStar txt File Format

UltraStar txt files are plain text files for karaoke songs. They hold informations about the notes and lyrics to sing, as well as some metadata about the song (e.g. artist, title, year, genre, video file).

The layout of this information in file is

• Metadata
• Notes and lyrics for each player
  • First a line with the target player, which is one of P1, P2, P3, ...
    • UltraStar historically supports only duets with two players, i.e. only P1 and P2. And P3 was used as "notes for both P1 and P3". Note that UltraStar Play does not support this P3 notation.
  • Afterwards each line describes one note or marks the end of a phrase.
    • Note description: The values are separated by space in the following order: NoteType StartBeat Lenght Pitch Text
    • End of phrase: - (dash) character followed by StartBeat, and optionally EndBeat. Here, StartBeat and EndBeat describe how long this phrase will show, respectively when the next phrase will be shown.
• Optionally, the file ends with an E character on the last line to explicitly mark the end

Example:

#TITLE:My Cool Song (Duett)
#ARTIST:My Cool Artist
#MP3:audio.ogg
#BPM:100
#GAP:7500
#COVER:cover-image.jpg
#BACKGROUND:background-image-used-when-video-file-not-working.jpg
#GENRE:Pop
#YEAR:2007
#LANGUAGE:English
P1
: 0 5 0 Hello 
: 10 5 0 world!
- 15
: 20 5 0 How 
* 30 5 2 are 
* 40 5 4 you?
- 45
P2
: 50 5 0 Hello 
: 60 5 0 world!
- 70
E

Note Types

• : normal note
• *: golden note
  • Gives more points
• F: freestyle note
  • Does not contribute to the score
• R: Rap note
  • contributes to the score, but pitch is irrelevant. Accepts any noise above threshold as "correct pitch".
• G: Rap and golden note
  • Like rap, but gives more points

Pitch

The pitch corresponds to a MIDI note but shifted by 60.

A value of 0 in the txt file corresponds to MIDI note 60 (C4. aka. "middle C"). A value of 1 in the txt file corresponds to MIDI note 61, etc.

Metadata

The metadata is located at the start of the file. All metadata lines start with a # (hash sign), followed by the tag name in upper case, a colon, and the value of that tag. Example: #TITLE:Never Gonna Give You Up

Only few of the tags are mandatory, namely #Artist, #Title, #BPM, #MP3.

The following lists UltraStar txt tags. Note that the list is not exhaustive and UltraStar Play may not support all of them.

• #TITLE

  • The song's title.

• #ARTIST

  • The song's artist.

• #GENRE

  • The song's genre.

• #EDITION

  • Edition of the song, usually either the game it was ripped from or the TV show it was featured in.

• #CREATOR

  • The user who timed/created the song.

• #LANGUAGE

  • The song's language.

• #COVER

  • The relative path to the cover image.

• #MP3

  • The relative path to the audio file.
    • Note that other audio file formats such as ogg work as well.

• #VOCALS

  • If the song at #MP3 is an instrumental version you can add an audio file containing the vocals here.

• #VIDEO

  • The relative path to the video.

• #BACKGROUND

  • The relative path to the background image. If the song has a video, this will only be shown if: video playback is disabled in the settings; the system cannot render the video smoothly enough; the video is shorter than the song, the background will be shown after the video has ended.

• #BPM

  • Defines the grid for the notes. Recommendation is to use the beats-per-minute of the audio file.
    • Actually, the txt value will be multiplied by 4 to get the beats-per-minute. This is done to have more fine grained note positioning and note recording (pitch detection is done per beat).
    • Example: Using #BPM:100 in the txt file means a single beat has a duration of: 100*4 [beat/minute] = 400 [beat/minute] ~~> 1/400 [minute/beat] = 60/400 [second/beat] = 0.15 [second/beat]

• #RELATIVE

  • Boolean value (YES/NO) that indicates whether the note timestamps are relative to the previous note (YES) or to the start of the song (NO). Default is NO.
  • This tag is not supported by UltraStar Play. UltraStar Play always assumed a value of NO, i.e., non-relative beat positions.

• #GAP

  • Milliseconds to shift the timing of ALL the notes. Positive numbers delay the notes, negative numbers do the opposite.
  • Example: Using #GAP:10000 in the txt file will shift notes by 10 seconds.

• #VIDEOGAP

  • Seconds to delay the video playback.
    • Example: Using #VIDEOGAP:5 will cause the video to start after the music has been playing for 5 seconds.

• #PREVIEWSTART

  • While selected in the song browser, a short preview of the song will play, starting at this many seconds in. Defaults to halfway through the song.

• #MEDLEYSTARTBEAT

  • First beat to sing when the song was started as medley. A countdown is shown before this beat.

• #MEDLEYENDBEAT:

  • Last beat to sing when the song was started as medley. Afterwards, the next medley song will be started.

• #DUETSINGERP1

• #DUETSINGERP2

• #P1

• #P2

  • Custom names for players P1 and P2 of the song.