ProjectM SDL2 Frontend

This is a reference implementation of an applicatiaon that makes use of the projectM music visualization library.

It will listen to audio input and produce mesmerizing visuals. Some commands are supported.

This project is in a bit of a transition state and is in the process of being modernized. There are many rough edges at present.

Building from source

Build and install libprojectM

First, build libprojectM or get it via your favorite dependency management/packaging tool. For testing, you can install libprojectM somewhere inside your home/development directory using CMAKE_INSTALL_PREFIX, then pass the same install path to the frontend-sdl2 build using CMAKE_PREFIX_PATH. Please refer to CMake's documentation for details.

Dependencies

This project requires third-party libraries in addition to libprojectM's core library dependencies:

• SDL2 (version 2.0.16 or higher)
• POCO (recommended version 1.12 or higher, minimum is 1.9.x)
• Freetype 2 (optional, will provide better looking UI text)

Important: projectMSDL will not compile against Poco versions from 1.10.0 up to 1.11.1, as these versions of Poco include a serious issue that causes the application to crash. Either use Poco 1.9.x, or upgrade to 1.11.2 or higher.

Depending on your needs, you can either build them yourself or install them using your favorite package manager. Here are some examples for the three major desktop platforms:

sudo apt install libsdl2-dev libpoco-dev libfreetype-dev cmake  # Debian/Ubuntu Linux
brew install sdl2 poco freetype  # macOS
vcpkg install sdl2 poco freetype # Windows, should be pulled in automatically via vcpkg.json

Configure and build projectMSDL

After cloning or updating the Git repository, always remember to initialize and update the submodules as well. this is not required when building from a release tarball or ZIP.

# Newer git versions also support "git submodule update --init" to perform both step in a single command.
git submodule init
git submodule update

If all dependencies are in the CMake and/or the system search directories, you can configure and build the application with these commands, executed from the source dir:

mkdir cmake-build
cmake -S . -B cmake-build -DCMAKE_BUILD_TYPE=Release
cmake --build cmake-build --config Release

You can optionally add the --parallel argument with the number of CPU cores to use to the build command to speed up the build.

If your dependencies are in different locations than the default search paths, or you're cross-compiling, you'll need to add more options like CMAKE_PREFIX_PATH. Covering all CMake options is out of the scope of this document. Please read the Mastering CMake guide and the CMake documentation for more information.

The above command will use CMake's default build file generator for your current platform and build the project in Release (optimized) configuration. If the build was successful, you should have an executable in the build directory. On Windows, you may need to specify the correct Visual Studio generator and architecture manually.

Install projectMSDL

While you can run projectMSDL directly from the build directory, it's recommended to install the project. This will copy all required files, including a default configuration file, into the installation dir.

You can set the installation target path in the first CMake command which configures the build. The install target will then copy everything under this directory:

mkdir cmake-build
cmake -S . -B cmake-build -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/path/to/install/dir
cmake --build cmake-build --config Release --target install

Run directly from the build dir

You should have a directory of visual presets you wish to use. You can fetch a giant trove of curated presets here. You will also need textures (images) used in many presets. The projectM team has assembled a pack of textures, which covers the needs of most presets.

If you want to run the executable from the build dir, you'll need to pass any non-default settings via arguments. You can also create a user configuration file in your user's home directory. Depending on the platform, this will be:

• Windows: %APPDATA%\projectM\projectMSDL.properties
• Linux:
  • If XDG_CONFIG_HOME env var is non-empty: $XDG_CONFIG_HOME/projectM/projectMSDL.properties
  • Otherwise: ~/.config/projectM/projectMSDL.properties
• macOS: ~/Library/Preferences/projectM/projectMSDL.properties

You can copy the config file template there and change anything in @@.

Depending on the build system, you'll find the projectM executable in cmake-build/src/, or a subdirectory with the name of your build type (Release, Debug and so on).

If you're not using a config file, provide the presets and texture paths you wish to use when starting projectMSDL:

cmake-build/src/projectMSDL --presetPath /path/to/presets-cream-of-the-crop --texturePath /path/to/textures

Press ESC to toggle the UI.

System-Specific CMake Examples

The following examples show how to configure and build projectMSDL with CMake on the different supported platforms.

Windows

To generate a Visual Studio 2022 project for Win64 and build for Release, with then option to also compile a Debug build from within the generated solution:

mkdir cmake-build
cmake -G "Visual Studio 17 2022" -A x64 -S . -B cmake-build -DCMAKE_CONFIGURATION_TYPES=Debug,Release
cmake --build cmake-build --config Release

Linux

To generate a UNIX Makefile project build for Release:

mkdir cmake-build
cmake -G "Unix Makefile" -S . -B cmake-build -DCMAKE_BUILD_TYPE=Release
cmake --build cmake-build

To generate a Ninja project build for Release:

mkdir cmake-build
cmake -G "Ninja" -S . -B cmake-build -DCMAKE_BUILD_TYPE=Release
cmake --build cmake-build

macOS

To generate an Xcode project and build for Release:

mkdir cmake-build
cmake -G Xcode -S . -B cmake-build -DCMAKE_CONFIGURATION_TYPES=Debug,Release
cmake --build cmake-build --config Release