UltraStar txt File Format - UltraStar-Deluxe/Play GitHub Wiki
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
andP2
. AndP3
was used as "notes for bothP1
andP3
". Note that UltraStar Play does not support thisP3
notation.
- UltraStar historically supports only duets with two players, i.e. only
- 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 byStartBeat
, and optionallyEndBeat
. Here,StartBeat
andEndBeat
describe how long this phrase will show, respectively when the next phrase will be shown.
- Note description: The values are separated by space in the following order:
- First a line with the target player, which is one of
- 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.
- The relative path to the audio file.
-
#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]
- Defines the grid for the notes. Recommendation is to use the beats-per-minute of the audio file.
-
#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.
- Example: Using
- Seconds to delay the video playback.
-
#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.