Song Editor - UltraStar-Deluxe/Play GitHub Wiki
UltraStar Play comes with an integrated editor for song files. UltraStar songs are simple txt files along with the audio file and optionally a video or background image.
- Content
- Open the editor
- Editor overview
- Play / pause audio
- Scroll, zoom, navigate
- Manipulate notes
- Record notes
- Edit lyrics
- MIDI
- Song properties and actions
- Create a new song
- Troubleshooting
- Shortcut summary
You can open the editor from the Song Select Scene and from the Sing Scene by pressing Ctrl+E on your keyboard.
As alternative, you can use the right click context menu (long press on mobile) to open the song editor.
The editor UI has the following main parts:
- Note Area: Shows the notes.
- Lyrics Area: Shows the lyrics.
- Video Area: Shows the video for the song, or a cover / background image for the song.
- Overview Area (for the complete song): Shows the waveform of the audio file, the position in the song and the viewport of the note area. Also, the overview area shows an overview of the notes.
- Button bar at the top. Some buttons, such as the
Optionsbutton opens a menu with further controls.
A typical workflow for creating a song is to
- Record notes via button tapping
- Move notes to correct pitch
- You might be able to find the correct pitch from sheet music on the internet, midi files, or by singing into the microphone.
- Assign notes to player
- Copy and paste parts for other verse / chorus
- Add lyrics
Press Space or P to toggle play / pause. The note area and overview area will follow the playback position when playing.
Press Ctrl+Space or Ctrl+P or Keypad5 to play only the currently selected notes and stop automatically after the last selected note has been played.
You can click in the note area and overview bar to change the playback position. When you click on a note then the playback position is set to the start of that note.
When paused, you can adjust the playback position precisely via Ctrl+left arrow / Ctrl+right arrow
Scroll
You can scroll in the note area using the mouse wheel. As alternative, you can use the left arrow and right arrow on your keyboard. It is also possible to scroll in the note area by holding the middle mouse button (the scroll wheel button) and dragging it horizontally.
All these actions will scroll horizontally. You can scroll vertically (to see different pitch values) via Shift+mouse wheel.
Zoom
You can zoom in the note area using Ctrl+mouse wheel. This will zoom horizontally. You can zoom vertically (to see more or less pitch values) via Ctrl+Shift+mouse wheel.
As alternative, you can zoom horizontal via Ctrl+'+' and Ctrl+'-'. You can zoom vertical via Ctrl+Shift+'+' and Ctrl+Shift+'-'
The viewport can be set to view all selected notes. To do so, first select the desired notes and afterwards use the right click context menu on the note area ("Fit horizontal to selection").
Navigate
You can click in the overview bar to jump to any position in the song. Similarly, you can click on the lyrics in the lyrics area to jump to the position of that note.
The Home key will move the playback position to the start of the song.
The End key will move the playback position to the end of the song.
Select notes by holding the left mouse button and dragging in the note area. All notes that are completely inside of the selection rectangle will be selected.
Hold Shift to add more notes to a selection. An existing selection is not removed while holding Shift.
Similarly, hold Ctrl+Shift to remove notes from an existing selection.
You can also use Tab to select the next note and Shift+Tab to select the previous note. The same can be achieved via Keypad4 and Keypad6.
Ctrl+A selects all notes in the song.
Position the mouse in the center of a selected note. Then drag the selected notes with the left mouse button to move them.
As alternative, use Shift+arrow key to move notes.
Inspired by the controls of the Yass song editor, you can also move notes left / right, using Keypad1 / Keypad3. Similarly, you can move notes up / down using KeypadMinus / KeypadPlus.
You can move notes a complete octave up / down via Ctrl+Shift+ArrowUp / Ctrl+Shift+ArrowDown.
Position the mouse over the left side of a note. This will highlight its left handle. Similarly, hovering with the mouse over the right side of a note will highlight its right handle.
Notes can be changed in size by dragging these handles horizontally.
As alternative, use Ctrl+arrow key to extend / shrink the left side of a note and use Alt+arrow key to extend / shrink the right side of a note.
Inspired by the controls of the Yass song editor, you can also use Keypad7 and Keypad9 to shorten/lengthen notes.
The song editor options contain a checkbox to "adjust following notes". If this option is active, then following notes in the song will move with the selected notes. Furthermore, when extending / shrinking a note's right side, then following notes will move to keep the same distance as before.
Delete selected notes via Del keyboard button or via the right click context menu.
New notes can be added in various ways:
- Copy and paste notes
- Split an existing note
- Record notes via microphone or button tapping
- Use the right click context menu on the note area
Double click on a note to edit its lyrics.
As alternative, when only a single note is selected you can hit F2 to edit its lyrics.
Use the right click context menu on a note to split / merge it.
Splitting a note will make it half its original length and create a new note that takes the space of the other half. Merging notes performs the opposite operation.
Use the context menu on a note to make it golden (gives double points), freestyle (pitch is irrelevant when singing, does not contribute to score), or normal.
As alternative, use the keyboard button G / F / N to make notes golden / freestyle / normal.
Hit Ctrl+C to copy selected notes. The copied notes will follow the playback position. Thus, change the playback position to where the notes should be inserted. Insert the copied notes via Ctrl+V.
Newly inserted notes are not added directly to the song. Instead, they are added to a temporary layer. You can arrange and modify the inserted notes on this layer as needed. Afterwards, move them to the player who should sing them via the right click context menu (e.g. "Move to player 1").
A song can be made as a duet song that has two separate sets of notes.
Change the singer of the selected notes via the right click context menu (e.g. "move to player 2").
You can hide the notes for a singer in the song editor options.
You can record notes either by singing into a microphone or by tapping a keyboard button (F8 button). Choose the desired method in the song editor options.
You can also configure the following parameters:
- Mic octave offset: This is useful to sing in a different octave and still record notes with the same absolute pitch as in the song.
- Mic delay (in milliseconds): There is always a delay from the mic input, to processing the signal, to recording it in the game. Adjust this option to synchronize your singing with the recording.
- Button pitch: The midi note that is used when doing recording via button tapping. You can find a comparison of midi note, its English name, German name and frequency over here.
- Playback speed of the song. Reduce this for more precise button tapping.
The available microphones are the same as for the normal singing game. They are configured in the game's settings menu.
Recorded notes are not directly added to the song. Instead they are added to a temporarly layer. Thereby, mic recording and button recording use different layers. Move the notes to the desired player via the right click context menu (e.g. "move to player 1").
You can hide the notes from button / mic recording in the song editor options.
The Lyrics Area allows to edit the text of the whole song using few special characters.
- A semicolon separates syllables that should be placed on different notes
- A space character separates words
- Spaces are shown as dots (•)
- The space is added to the end of the previous note (instead of the beginning of the following note)
- A line break separates phrases
- Line breaks are shown as arrow (↵)
It is also possible to prepare the lyrics in an external text editor and just paste the result into the Lyrics Area.
On the left hand side is a virtual piano keyboard, which can aid in finding the correct pitch for a note in the song. Click on the keys to play the corresponding MIDI sound for that pitch.
You can play the MIDI sound for a single note via Ctrl+Left mouse button. When hovering over a note and holding the Ctrl key, the cursor will change to indicate that a MIDI sound can be played.
MIDI sounds for notes can also be played along with the normal music audio. This feature can be enabled / disabled in the options. Thereby, only the notes are played that are assigned to a player. No MIDI sound is played for notes on temporary layers, such as imported MIDI files or recorded notes.
You can import notes from a MIDI file (.mid file extension).
The imported notes are not added directly to the song. Instead, they are added to a temporary layer. You can arrange and modify the imported notes on this layer as needed. Afterwards, move them to the player who should sing them via the right click context menu (e.g. "Move to player 1").
It might be easier to edit a MIDI file before importing it, for example to remove notes until only the voice track is left. There are various MIDI editors that can be used, including free and open-source software, such as MidiEditor (GitHub).
There are buttons to double (and even triple) the BPM for the song txt file. This will make the grid more fine grained to position notes more accurately.
In contrast to this, the button "recude BPM" will cancel the greatest common divisor of the note position. As a result, the grid will be less fine grained. For example, consider a song with only two notes. The first ranges from beat 0 to 5 and the second from beat 10 to 15. Then they could be written as ranging from beat 0 to 1 and from beat 2 to 3 instead (the greatest common divisor is 5).
This will set a new BPM value but preserve the position and length of notes in milliseconds.
There is a button to set the GAP for the song txt file to the current playback position.
The GAP is the pause between the audio file start, and the start of the singing. For example, consider a song with 3 seconds of piano intro before the singer begins. In this case, the #GAP tag in the txt file needs to be be set to 3000 (the value in the txt file is in milliseconds).
This can be achieved by first clicking in the note area to move the playback position 3 seconds into the song. Afterwards, click the button that sets the GAP to the playback position.
An offset for the video playback can be defined to synchronize video and audio. You can change this offset by dragging horizontally inside the video area.
In the UltraStar txt file format, the video offset is saved as #VIDEOGAP in seconds.
The "Add Space Between Notes" action will shorten notes that are directly adjacent to one another. Thereby, the minimum amount of space that is created between notes is given in beats.
In a well made UltraStar song, the notes are not placed directly adjacent to one another because the player needs time to breathe.
Click the button to save the song txt file or hit Ctrl+S.
A copy of the original song file is saved with a '.bak' extension if it does not exist yet. You can disable this behaviour in the song editor options.
You can undo / redo actions using the corresponding buttons.
You can also undo / redo via Ctrl+Z / Ctrl+Y
- Copy an existing song as basis for a new song.
- Replace the audio file, image and video as needed.
- Open the txt file, set the most important tags: #MP3 (also for non-mp3 files such as ogg), #BPM, #TITLE, #ARTIST
- There are tools to find the BPM for a song, for example tap for BPM.
- Remove the notes from the txt file
- Save it in UTF-8 encoding
- Restart UltraStar Play. Then open this newly created, empty song in the editor and add some notes
The editor works best when using audio files that are encoded as Ogg. If you have issues with MP3 files in the editor then convert the file to Ogg first and change the #MP3 tag in the song txt file accordingly (e.g. #MP3:my-cool-song.ogg instead
#MP3:my-cool-song.mp3).
Scroll and zoom
| Left arrow | Scroll left in the note area |
| Right arrow | Scroll right in the note area |
| Ctrl+'+' | Zoom in horizontal |
| Ctrl+'-' | Zoom out horizontal |
| Ctrl+Shift+'+' | Zoom in vertical |
| Ctrl+Shift+'-' | Zoom out vertical |
| Mouse wheel | Scroll horizontal in the note area |
| Ctrl+Mouse wheel | Zoom horizontal in the note area |
| Shift+Mouse wheel | Scroll vertical in the note area |
| Ctrl+Shift+Mouse wheel | Zoom vertical in the note area |
Edit notes
| Shift+Arrow keys | Move selected notes |
| Ctrl+Arrow keys | Extend / shrink left side of selected notes |
| Alt+Arrow keys | Extend / shrink right side of selected notes |
| Ctrl+Shift+Arrow up / Ctrl+Shift+Arrow down | Move selected notes one octave up / down |
| Tab | Select next note |
| Shift+Tab | Select previous note |
| Ctrl+A | Select all |
| Ctrl+C | Copy selected notes |
| Ctrl+V | Paste selected notes |
| F2 | Edit lyrics of selected note (must select a single note) |
| G / F / N | Make selected notes "golden" / "freestyle" / "normal" |
Keypad Controls
| Keypad1 / Keypad3 | Move selected notes left / right |
| KeypadMinus / KeypadPlus | Move selected notes up / down |
| Keypad7 / Keypad9 | Shorten / lengthen selected notes |
| Keypad4 / Keypad6 | Select previous / next note |
| Keypad5 | Play selected notes |
Editor controls
| E | Open song editor from song select or sing scene |
| Escape | Exit song editor or editing of lyrics |
| Space | Toggle play / pause |
| Ctrl+Arrow keys | Change playback position (fine grained) |
| Home | Move playback position to start of the song |
| End | Move playback position to end of the song |
| Ctrl+S | Save file |