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.
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.
This project requires third-party libraries in addition to libprojectM's core library dependencies:
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
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.
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
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:
%APPDATA%\projectM\projectMSDL.properties
XDG_CONFIG_HOME
env var is non-empty: $XDG_CONFIG_HOME/projectM/projectMSDL.properties
~/.config/projectM/projectMSDL.properties
~/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.
The following examples show how to configure and build projectMSDL with CMake on the different supported platforms.
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
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
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