Skip to content
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Go to file

UltraStar Deluxe Development README

Travis Build Status AppVeyor Build Status License

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
                   _______  _________
            ___   /       \/         \
           /   \  \      _/    /\____/\__________
          /   _/  /     / \______      \         \___    _____
         /   |___/      \     \_/       /          \  \  /     \
         \              /\             /   |\       \  \/      /
          \            /  \_____/    |/       /         /
           \__________/              |_____________/          \
                                                 /      /\      \
                                                 \_____/  \_____/  .eu
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Official Project Website:

UltraStar Deluxe Logo

1. About

UltraStar Deluxe (USDX) is a free and open source karaoke game. It allows up to six players to sing along with music using microphones in order to score points, depending on the pitch of the voice and the rhythm of singing. UltraStar Deluxe is a fork of the original UltraStar (developed by corvus5). Many features have been added like party mode, theme support and support for more audio and video formats. The improved stability and code quality of USDX enabled ports to Linux and Mac OS X.

2. Configuration

  • To set additional song directories change your config.ini like this:
  SongDir...=... (some more directories)
  • To enable joypad support change config.ini Joypad=Off to Joypad=On
  • To enable 2 or 3 player each on 2 screens, disable the full screen mode, extend your desktop horizontally and set the resolution to fill one screen. Then, in the config.ini set Screens=2 and restart the game.
  • The primary folder for songs on OS X is $HOME/Music/UltraStar Deluxe, which is created when UltraStar Deluxe is run for the first time.
  • On OS X, by default the config.ini file is created in $HOME/Library/Application Support/UltraStarDeluxe when UltraStar Deluxe is run for the first time.

3. Command-Line Parameters


4. Controls


5. Build and Run

Freepascal 3.0.0 or newer is required to compile UltraStar Deluxe. If you had some older version of fpc installed before, make sure to remove everything of it correctly before trying to install freepascal (otherwise compiling will fail with various weird error messages). Also, using the 3.0-development branch with current fixes is suggested. If you want to help the project by coding patches, we suggest you to use the Lazarus 1.6 or newer integrated development environment. For linking and running the game, the following libraries are also required:

  • SDL2, SDL2_image
  • ffmpeg 2.8 or older
  • sqlite
  • bass
  • some fonts like DejaVu
  • portaudio
  • lua 5.1 or 5.2 or 5.3
  • opencv if you want webcam support
  • projectM if you want audio visualisation support

Compiling using Lazarus

  1. Start Lazarus.
  2. Choose Project → Open Project … in the menu bar. A file-dialog box will show.
  3. Change to the src subdirectory of your USDX working copy (e.g. ultrastardx/src).
  • If you are running Windows, open the ultrastardx-win.lpi project-file (Preferably use the win32 verison of lazarus, as the included libraries are 32 bit).
  • On Unix-like systems use the ultrastardx-unix.lpi file.
  1. Now you can compile USDX by choosing the menu entry Run → Build or pressing Ctrl+F9.
  2. If you want to compile and/or start USDX directly choose Run → Run or press F9.

Compiling using make

Install prequisites

Required libraries:

  • Debian/Ubuntu: git automake make gcc fpc libsdl2-image-dev libavformat-dev libswscale-dev libsqlite3-dev libfreetype6-dev portaudio19-dev libportmidi-dev liblua5.3-dev libopencv-videoio-dev fonts-dejavu
  • Fedora: git automake make gcc fpc SDL2_image-devel ffmpeg-devel sqlite-devel freetype-devel portaudio-devel portmidi-devel lua-devel opencv-devel
  • Archlinux: see the dependencies in the ultrastardx-git AUR package

Optional libraries:

  • ProjectM visualization: g++ libprojectm-dev (Debian/Ubuntu) or gcc-c++ libprojectM-devel (Fedora)
  • Webcam: g++ libopencv-dev (Debian/Ubuntu)
MacOS (High Sierra and above)
  • Install Homebrew. Follow instructions from
  • brew install fpc or get it from
  • xcode-select --install
  • brew install sdl2 sdl2_image automake portaudio binutils sqlite freetype lua libtiff pkg-config ffmpeg
Windows using MSYS2
  • Install MSYS2
  • Install FPC. You need at least a custom installation with the Free Pascal Utils (for fpcres) and the Units.
  • pacman -S autoconf-wrapper automake-wrapper gcc git make mingw-w64-x86_64-SDL2 mingw-w64-x86_64-SDL2_gfx mingw-w64-x86_64-SDL2_image mingw-w64-x86_64-SDL2_mixer mingw-w64-x86_64-SDL2_net mingw-w64-x86_64-SDL2_ttf mingw-w64-x86_64-ffmpeg mingw-w64-x86_64-lua51 pkgconf
  • Add some information to .bash_profile:
    • Path to FPC, something like PATH="${PATH}:/c/FPC/3.2.2/bin/i386-win32"
    • Path to mingw64 libraries, PKG_CONFIG_PATH="${PKG_CONFIG_PATH}:/mingw64/lib/pkgconfig"
Compile and run
  • git clone
  • cd USDX
  • ./
  • ./configure
  • make (on MacOS: make macosx-standalone-app)
  • ./game/ultrastardx[.exe] (on MacOS: open

Compiling on Linux using flatpak-builder

  • The Flatpak manifest uses the org.freedesktop.Platform 20.08 runtime, which is available for the major architectures on the Flathub remote. If it isn't available for your architecture, you can lower the version in the manifest. Below 19.08 you either need to enable the dav1d module or disable AV1 support in the ffmpeg module by removing the --enable-libdav1d configure option. For some architectures the runtime is not hosted by Flathub but can be downloaded from the Freedesktop SDK remote.
  • The build has to be done outside of the USDX source code tree since flatpak-builder will to copy the whole source tree into the build directory. Also note that flatpak-builder will create a hidden directory .flatpak-builder in the directory it was called in where downloads and build results are cached.
  • Assuming you can use the Flathub remote and you didn't already add it to your flatpak configuration, you can do it with
    • flatpak remote-add --user flathub
  • Then building and installing the USDX flatpak is just a matter of
    • flatpak-builder --user --install-deps-from=flathub --install build $USDX_SOURCE_TREE/dists/flatpak/eu.usdx.UltraStarDeluxe.yaml
  • The .flatpak-builder and build directories can be removed afterwards.
  • Songs must be placed in ~/.var/app/eu.usdx.UltraStarDeluxe/.ultrastardx/songs

6. Making a release

  • Find and replace the contents of VERSION everywhere throughout the code This should be three places:
    • UConfig.pas (also recompile the game after this)
    • variables.nsh (update both blocks when making the release and swap the comments, then after the release you only have to swap the comments back)
  • Create Windows portable version: zip the contents of the game directory
  • Create Windows installer:
    • Install NSIS (also install the Graphics and Language components during setup)
    • Copy the DLLs from game to installer/dependencies/dll
    • C:\...\makensis "installer/UltraStar Deluxe.nsi" (this will take a while)
    • The .exe will be placed in installer/dist

Feel free to fork this project, modify it to your hearts content and maybe also do pull requests to this repository for additional features, improvements or clean-ups.