Encoding & TXT

Encoding has to be UTF-8 (without BOM).

Why? UTF-8 (without BOM) is a great encoding that can represent a vast number of symbols from all kinds of languages. Other encodings, like Windows code pages, are far more limited and are only suitable for a small family of languages.

File-Container has to be TXT.

Why? The TXT files are quite simple and easy to understand for non-coders. You can read them and edit them with a simple txt-editor. That's what made the format so popular in the first place. So even if there are many good mark up languages like xml we keep on using TXT-Files for this decade unless there are good reasons to change that.

Mandatory Attributes

VERSION (new)

The version attribute helps the game and apps to understand how uptodate a song file is and how it should be treated. Ideally all txt files will be upgraded to the latest version. The value are version numbers according to semantic versioning. Song Editors, Managing tools or txt-hostings should set this automatically.

#VERSION:1.1.0

TITLE

The title of the song. This is the song name that will appear in the song selection screen.

#TITLE:Song Title

ARTIST

The artist of the song. This is the name of the person or group who performed the song.

#ARTIST:Artist

MP3 (deprecated)

Filename of the audio file. This is the file that contains the sound of the song. It must be in the same folder as the txt file and should have the same name as the folder. All software support at least .mp3 (CBR), .wav and .ogg audio files. Please use #AUDIO. #MP3 will be removed in 2025.

#MP3:Artist - Title.mp3

AUDIO (new)

Defines the audio file that contains the whole music in one (consisting of VOCALS (the singers voice(s)) and INSTRUMENTAL(S). This is the new tag for the deprecated #MP3 tag. It must be in the same folder as the txt file and should have the same name as the folder. All software support at least .mp3 (CBR), .wav and .ogg audio files.

#AUDIO:Artist - Title.mp3

BPM

Speed of the song in Ultrastar - Beats Per Minute. Which is not the real song BPM. UltraStar BPM is quarter notes, thus it’s quadruple of the song’s BPM (ideally). "Ideally" means that any song could be tapped with any BPM (not even remotely related to the song’s BPM).

#BPM:400

Notes

Note description

The sing line is defined so that it has the NoteType, StartBeat, Length, Pitch and Text.

• For the styles see NoteTypes.
• The StartBeat and Length must be calculated against the BPM, GAP and Relative. Is a beat number.
• The pitch describes the note as a number. The number 0 corresponds to the note C4 and Midi Note 60.
• Text is the part of the lyrics that is sung in this note.

NoteType StartBeat Length Pitch Text

: 10 10 10 Text

End of phrase

- represents the end of a phrase and how long it lasts by the StartBeat. The length is calculated against the BPM, GAP and Relative. Is a beat number.

- StartBeat

End of file

E represents the end of a file.

E

Player delimiter

P1 or P2 player delimiter. The following section of notes are for player 1 or player 2.

P1

NoteTypes

Normal :

The normal note.

: 0 1 8 Normal

Golden *

The golden note. Gives twice the point of a normal point

* 0 1 8 Golden
                    

Freestyle F

Note that will NOT be scored.

F 0 1 8 Freestyle
                    

Rap R

Rap note

R 0 1 8 Rap
                    

Rap Golden G

Golden Rap note. Gives twice the point of a rap point

G 0 1 8 RapGolden
                    

Optional Attributes

GAP

Delay for the start the lyric in milliseconds. Its used that the first word starts at 0. Otherwise the delay gap would be added to the start of the first line.

#GAP:12345

COVER

Filename of the cover image. Should end with *[CO].jpg This is an image that shows the album cover or a picture related to the song. It should be in 1:1 aspect ratio. It should not be larger than 1920x1920px. All software support at least JPG/JPEG-Files.

#COVER:Artist - Title [CO].jpg

BACKGROUND

Filename of the background image. Can be shown instead of a video or if no video is available. Should with *[BG].jpg This will be shown when there is no VIDEO available.

#BACKGROUND:Artist - Title [BG].jpg

VIDEO

Filename of the video file. This is a video that shows a music video or other visual content related to the song. The sound of the video is generally not played. Exception: If there's no audio file UltraStar Deluxe and Vocaluxe play the audio track from the video. It must be in a format supported by UltraStar, such as MP4 or AVI. See format support here: here

#VIDEO:Artist - Title.mp4
                    

VIDEOGAP

Specifies the delay in seconds between the start of the video and the start of the song. This value can be used to synchronize the video with the music. This attribute is useful when the video and audio files are not perfectly synchronized and you need to adjust the timing of the video to match the audio. By setting a positive or negative value for VIDEOGAP, you can delay or advance the start of the video relative to the start of the song.

#VIDEOGAP:12345
                    

VOCALS (new)

#VOCALS defines the audio file that contains only the vocals of a singers voice. It's the acapella. This comes in handy when some games have the feature to change the volume of a singer while playing a song from 100%-0%. So that you can decide how loud the singer sings along to your own vocals. Needs to be complemented with #INSTRUMENTAL.

It also can be used for sing accappela with the singer. Please add [VOC] to the file name.

#VOCALS:Artist - Title of the song [VOC].mp3
                    

INSTRUMENTAL (new)

#INSTRUMENTAL defines the audio file that contains only the instruments of a song without the singers voice. This is for real karaoke. Please add to the file name [INSTR].

#INSTRUMENTAL: Artist - Title of the song [INSTR].mp3
                    

GENRE

Specifies the genre of the song. This information can be used to categorize songs by their musical style. The value of the GENRE attribute can be any text string that describes the genre of the song. Some common genres include Pop, Rock, Hip-Hop, Country, and Jazz. You can add multiple tags and seperate them with comma.

#GENRE:Pop, Rock, Punkfunk
                    

TAGS (new)

#TAGS allows you to add any reasonable keyword for this song. This helps to categorize songs by keywords. You can add multiple tags and seperate them with comma. You can use #TAGS if #EDITION is not enough.

Some common keywords are: Party, Feel-Good, Charts, Cover Songs, Summer, Love Songs, Guilty Pleasure, Disney, Christmas, Halloween, Eurovision Song Contest [YEAR], Club, Dancefloor, Underground, Mainstream, Slow

#TAGS:Love Songs, Movie, 80s
                    

EDITION

This attribute specifices a value out of a curated list where a song belongs to. Aside from this list certain games can be used like SingStar - Pop Hits, GuitarHero Live, Rockband vol.4, Let's Sing 2020. See list of editions here:

• List of SingStar Editions
• List of RockBand Editions
• List of GuitarHero Editions

#EDITION:SingStar Rocks! [DE]
                    

CREATOR

Specifies the name of the person who created the ultrastar txt file. This information can be used to give credit to the person who created the file. The value of the CREATOR attribute can be any text string that represents the name of the person who created the ultrastar txt file. You can add multiple creators and seperate them with comma.

#CREATOR:dagegg, bohning, roller girl
                    

LANGUAGE

Specifies the language of the song. This information can be used to categorize songs by their language. The value of the LANGUAGE attribute should be English language names, not translated language names (e.g. "French", not "Français" or "Französisch"). You can add multiple languages and seperate them with comma.

#LANGUAGE:English, French
                    

YEAR

Specifies the year the song was released. This information can be used to categorize songs by their release date. The value of the YEAR attribute should be a four-digit number that represents the year the song was released.

#YEAR:2022
                    

START

START specifies the time in seconds from the beginning of the audio file at which the song starts. This value can be used to skip any silence or intro at the beginning of the audio file. The value should be positive integers that represent the start time of the song in seconds.

#START:1.5
                    

END

Specifies the time in milliseconds from the beginning of the audio file at which the song ends. This value can be used to stop playback before any silence or outro at the end of the audio file. The value should be positive integers that represent the end time of the song in milliseconds.

Keep it simple, its just seconds + 000

#END:678000
                    

PREVIEWSTART

Specifies the time in seconds from the beginning of the audio file at which the preview of the song starts. This value can be used to set the start time of the preview that is played when browsing songs.

#PREVIEWSTART:12,34
                    

MEDLEYSTARTBEAT

Specify the start beat of a medley section within the song. These value can be used to create a medley of multiple songs by specifying which section of each song should be included in the medley. Needs MEDLEYENDBEAT

#MEDLEYSTARTBEAT:10
                    

MEDLEYENDBEAT

Specify the end beat of a medley section within the song. These value can be used to create a medley of multiple songs by specifying which section of each song should be included in the medley. Needs MEDLEYSTARTBEAT

#MEDLEYENDBEAT:20
                    

CALCMEDLEY

Specifies whether UltraStar should automatically calculate the medley section of the song. If this attribute is set to on, UltraStar will automatically determine the most suitable section of the song for a medley based on the note data. If it is set to off, the automatic medley calculation can be disabled.

#CALCMEDLEY:on
                    

P1 and P2

Specify the names of the singers for a duet song. These values can be used to display the names of the singers on screen during a duet.

#P1:John
                    

PROVIDEDBY (new)

#PROVIDEDBY helps to understand where a txt-file cames from. This is important cause there are many third-parties that host txt-files with different quality standards. This information should be normally set automatically from the provider. But you can set it as well manually with a song editor if you know where you got it from. Value should be a URL.

#PROVIDEDBY: https://usdb.animux.de
                    

COMMENT

Use comment to write any important information in the text file that might be interesting for song creators. Right now there is no definition for what this attribute should be used excactly. It's not displayed in the games.

#COMMENT:made with Karedi and YASS Editor
                    

Deprecated

Here are all the #-attributes that you shouldn't use anymore. Why? They are technical not necessesary today or just duplicates in the history of UltraStar games.

RESOLUTION

Changes the grid resolution of the UltraStar Deluxe editor. Only for the editor and nothing for singing.

#RESOLUTION:
                    

NOTESGAP

Nobody knows what this was meant for but it was found in the some older codes of games. Don't use it.

#NOTESGAP:
                    

RELATIVE

Specifies whether the note timings in the file are relative to the previous note or absolute. If this attribute is set to yes, the note timings are relative to the previous note. If it is set to no or not present, the note timings are absolute. If this line is missing, then the timestamps are absolute.

Relative timestamps make working on a TXT file much easier, because if you want to insert a pause, you don't have to adjust all following timestamps, but only the ones until the end of the line.

Switching from absolute to relative and back is easy using either UltraStar Manager (two tasks) or USDX editor (S vs. SHIFT-S in the editor).

#RELATIVE:yes
                    

DUETSINGERP1 / DUETSINGERP2

Specify the names of the singers for a duet song. These values can be used to display the names of the singers on screen during a duet. This is a duplicate. Use P1/P2 instead.

#DUETSINGERP1:John
                    

ENCODING

Specifies the character encoding used in the txt file. This attribute can be used to ensure that special characters are displayed correctly. Possible values are UTF-8, CP1252 and CP1250.This is not needed. All TXT should be UTF-8 (without BOM).

#ENCODING:UTF8
                    

More duplicates

#AUTHOR is a duplicate of #CREATOR. PREVIEW is a duplicate of #PREVIEWSTART. #ALBUM, #SOURCE, #YOUTUBE, #LENGTH and #FIXER are not necessary. Please change or delete these tags to update txt files.

#AUTHOR, #FIXER, #ALBUM, #SOURCE, #YOUTUBE, #LENGTH