projectm Documentation

Mandatory packages:

.. code:: bash

   sudo apt install build-essential cmake libgl1-mesa-dev mesa-common-dev

**Important:** projectM requires CMake 3.21 or newer. Current stable distributions already ship a new enough
CMake (e.g. Debian 12 "bookworm" with CMake 3.25, Ubuntu 22.04 and newer with CMake 3.22+). Only end-of-life releases
like Debian 11 "bullseye" (CMake 3.18) need a manual install, in which case get the latest CMake
release `from Kitware's download page <https://cmake.org/download/>`__.

Optional packages:

.. code:: bash

   sudo apt install ninja-build # To build projectM with Ninja instead of make
   sudo apt install libsdl2-dev # To build the development test UI

Download the projectM sources
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

For production use, it is highly recommended to use the latest stable version of projectM. Download the latest release
from the `Releases page on GitHub <https://github.com/projectM-visualizer/projectm/releases>`__ and unpack it.

Using a development version
^^^^^^^^^^^^^^^^^^^^^^^^^^^

If you prefer a bleeding-edge version or want to modify the code, clone the Git repository and initialize any
submodules:

.. code:: bash

   sudo apt install git # Probably already installed
   git clone https://github.com/projectM-visualizer/projectm.git /path/to/local/repo
   cd /path/to/local/repo
   git fetch --all --tags
   git submodule init
   git submodule update

Build and install projectM
~~~~~~~~~~~~~~~~~~~~~~~~~~

Replace ``/usr/local`` with your preferred installation prefix.

Configure the project using CMake
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code:: bash

   sudo apt install cmake
   mkdir build
   cd build
   cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr/local ..

To generate Ninja scripts instead of Makefiles, add ``-GNinja`` to the above command.

Build and install
^^^^^^^^^^^^^^^^^

These commands will build projectM and install it to /usr/local or the configured installation prefix set in the step
before:

.. code:: bash

   cmake --build . -- -j && sudo cmake --build . --target install

**Note**: You won't need to use ``sudo`` if the install prefix is writeable by your non-privileged user.

Test projectM
^^^^^^^^^^^^^

The SDL-based developer test UI is off by default. To build it, add ``-DENABLE_SDL_UI=ON`` to the configure command
above (requires SDL2, e.g. ``sudo apt install libsdl2-dev``). It is not installed; after building, run it from the build
directory, e.g. ``./src/sdl-test-ui/projectM-Test-UI``.

Dependencies
------------

Depending on the OS/distribution and packaging system, libraries might be split into separate packages with binaries and
development files. To build projectM, both binaries and development files need to be installed.

General build dependencies for all platforms:

- Linux distributions will have packages available for most (if not all) required libraries. The package names and
  commands to install them vary widely between distributions (and even versions of the same distribution). Please refer
  to the documentation of your build OS on how to find and install the required libraries.
- On *BSD*, install the appropriate Ports with ``pkg install``.
- On macOS, a working Xcode installation is required. CMake (and libSDL2 for the test UI) can be installed
  using `Homebrew <https://brew.sh/>`__.

Building
~~~~~~~~

The steps documented below are a bare minimum quickstart guide on how to build and install the project. If you want to
configure the build to your needs, require more in-depth information about the build process and available tweaks, or on
how to use libprojectM in your own CMake-based projects, see the `Building with CMake`_ reference section below.

Using CMake is the only supported way of building projectM since version 4.0. CMake is a platform-independent tool that
is able to generate files for multiple build systems and toolsets while using only a single set of build instructions.

Building the project with CMake requires two steps:

- Configure the build and generate project files.
- Build and install the project using the selected build tools.

**Note:** The build directory should always be different from the source directory. Generating the build files directly
inside the source tree is possible, but strongly discouraged. Using a subdirectory, e.g. ``cmake-build`` inside the source
directory is fine though.

This documentation only covers project-specific information. CMake is way too versatile and feature-rich to cover any
possible platform- and toolset-specific configuration details here. If you are not experienced in using CMake, please
first read the `official CMake documentation <https://cmake.org/cmake/help/latest/>`__ (at least
the `User Interaction Guide <https://cmake.org/cmake/help/latest/guide/user-interaction/index.html>`__) for basic usage
instructions.

Configure the build
^^^^^^^^^^^^^^^^^^^

Configuring a non-debug build with default options and install prefix (``/usr/local``) can be done with these commands,
building in a subdirectory inside the source directory:

.. code:: shell

   cd /path/to/source
   mkdir cmake-build
   cd cmake-build
   cmake -DCMAKE_BUILD_TYPE=Release ..

CMake will check all required dependencies and display any errors. If configuration was successful, a summary of the
build configuration is printed and CMake should display a ``Generating done`` line. The project is now ready to build.

Compile and install the project
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Depending on your generator choice, you can use your selected toolset as usual to build and install projectM:

- With ``Unix Makefiles``, run ``make && sudo make install``.
- With ``Ninja``, run ``ninja && sudo ninja install``.
- With ``Xcode``, select the appropriate target and configuration in Xcode and build it, or ``INSTALL`` to install the
  project.

You can also use CMake's build mode to run the selected toolset and build any specified target. CMake knows which
command to call and which parameters to pass, so the syntax works on all platforms with all generators. If you've
already set the top-level build directory as working directory, simply pass ``.`` as ``/path/to/build/dir``:

.. code:: shell

   cmake --build /path/to/build/dir --config Release
   sudo cmake --build /path/to/build/dir --config Release --target install

If you don't need root permissions to install to the given path, running the second command without ``sudo`` is
sufficient.

To control how many files are compiled in parallel, pass the ``--parallel N`` argument to the build command, with ``N``
being the number of concurrent compile commands. If not given explicitly, the build processor (make, ninja, MSBuild,
xcodebuild etc.) will decide the limit, which may range from one file at a time to all files at once.

If you want to provide arguments directly to the toolset command, add ``--`` at the end of the CMake command line followed
by any additional arguments. CMake will pass these *unchanged and unchecked* to the subcommand:

.. code:: shell

   cmake --build /path/to/build/dir --config Release -- <additional build tool args>

Building on Windows
-------------------

To build the projectM library and the SDL-based standalone application, CMake must be used to create the project files
first. Using vcpkg to pull in the build dependencies is highly recommended, as CMake can't use NuGet (NuGet pulls in
dependencies using the project files, while CMake requires the libraries before creating the project files).

Installing the dependencies with vcpkg

CMake provides separate generators for different Visual Studio versions. Newer CMake versions will support recent Visual
Studio releases, but may remove generators for older ones. To get a list of available generators from the command line,
use the ``-G`` switch without an argument. The CMake GUI will present you a dropdown list you can easily select from.

To set the build architecture in Visual Studio builds, use the ``-A`` switch and specify either ``Win32`` or ``X64`` as the
argument. If you want to build for both architectures, create separate build directories and configure them accordingly.

To make CMake aware of the installed vcpkg packages, simply use the provided toolchain file when configuring the
projectM build by
pointing `CMAKE_TOOLCHAIN_FILE <https://cmake.org/cmake/help/latest/variable/CMAKE_TOOLCHAIN_FILE.html>`__ to it.

Here is a full command line example to create a Visual Studio 2022 solution for X64:

.. code:: console

   cmake -G "Visual Studio 17 2022" -A "X64" -DCMAKE_TOOLCHAIN_FILE="<path to vcpkg>/scripts/buildsystems/vcpkg.cmake" -S "<path to source dir>" -B "<path to build dir>"

If you use the CMake GUI, check the "Specify toolchain file for cross-compiling" option in the first page of the
configuration assistant, then select the above ``vcpkg.cmake`` file on the second page.

Another option is to open the project folder in a recent Visual Studio version as a CMake project and configure CMake
using Visual Studio's JSON-based settings file.

Building the solution
~~~~~~~~~~~~~~~~~~~~~

To build the project, open the generated solution in Visual Studio and build it like any other solution. Each time the
CMake files are changed, Visual Studio will automatically regenerate the CMake build files and reload the solution
before continuing the build. Be aware that in old Visual Studio versions (2015 and earlier) the reload-and-continue
might not work properly.

You can also build the solution with msbuild via the command line, or use CMake's build wrapper to do that for you:

.. code:: console

   cmake --build "" --config Release

Using Ninja to build
~~~~~~~~~~~~~~~~~~~~

The Ninja build system is shipped with Visual Studio since version 2019 and used by default if loading a CMake project
directly from within the IDE. Ninja can also be `installed separately <https://github.com/ninja-build/ninja/releases>`__.

To configure the build directory for Ninja, pass ``Ninja`` or ``Ninja Multi-Config`` as the argument for the ``-G`` switch.
The difference between both generators is that the former uses ``CMAKE_BUILD_TYPE`` to specify the configuration (
e.g. ``Debug`` or ``Release``) while the latter supports all configurations in a single build directory, specified during
build time.

The architecture is determined from the toolset, so make sure to run the commands in the correct Visual Studio command
prompt, e.g. "Native Tools for X64".

Configure and build for a single-configuration Release build with vcpkg:

.. code:: console

   cmake -G "Ninja" -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE="/scripts/buildsystems/vcpkg.cmake" -S "" -B ""
   cmake --build ""

Same, but using the multi-configuration generator:

.. code:: console

   cmake -G "Ninja Multi-Config" -DCMAKE_TOOLCHAIN_FILE="/scripts/buildsystems/vcpkg.cmake" -S "" -B ""
   cmake --build "" --config Release

Notes on other platforms and features
-------------------------------------

Supported platforms
~~~~~~~~~~~~~~~~~~~

libprojectM is designed to be compatible with as many platforms and architectures as possible. Thus, the code base
doesn't use any non-portable code like OS-specific APIs or assembly instructions.

The code compiles for the following target architectures:

- i686 (x32 / x86)
- x86_64 (x64)
- armv7 (arm)
- aarch64 (arm64 / armv8)
- WASM

Other architectures such as PPC, RISC and MIPS should be supported as well. Big-endian support is untested and thus
might be buggy.

libprojectM builds at least on the following platforms:

- Windows
- Linux
- macOS (iOS/tvOS as well, but be aware that Apple's TOS may prevent its use in Store apps!)
- BSD derivatives
- Android
- WebGL/WASM (using emscripten)

As long as a platform provides OpenGL Core 3.3 or OpenGL ES 3.2 libraries and supports at least C++ 14, libprojectM
should build fine.

Raspberry Pi (and other embedded systems)

To build projectM using the Android SDK, please refer to the official NDK docs:

https://developer.android.com/ndk/guides/cmake

It is highly recommended using the latest NDK and CMake >= 3.21 for building.

Using libprojectM with pkgconfig

Previous projectM versions (before 4.0) shipped several UIs and audio capture implementations in this repository.
To reduce the size of the code base and separate the release cycles of the core library and the frontends, these were
moved into their own repositories under the `projectM-visualizer organization <https://github.com/projectM-visualizer>`__
(e.g. the SDL-based desktop app and the Qt-based desktop app with PipeWire/PulseAudio/JACK backends).

libprojectM on its own does not have any means of capturing audio, it simply takes PCM data via the API. Applications
using projectM can supply this data from their own audio sources, e.g. music playing in an audio player or capturing
audio data from OS or other external sources.

.. _Building with CMake:

Building with CMake
-------------------

This section contains in-depth information for building with the CMake build system.

To use the library in other projects, it is required to install it. Use ``CMAKE_INSTALL_PREFIX`` to specify the
installation directory. If you use other build systems, you have to specify the include and library paths manually.

Selecting a specific project file generator

CMake has no built-in way of printing all available configuration options. You can either refer to the
top-level ``CMakeLists.txt`` which contains a block of ``option`` and ``cmake_dependent_option`` commands, or use one of the
available CMake UIs which will display the options after configuring the project once.

Important build switches
^^^^^^^^^^^^^^^^^^^^^^^^

The following table also gives you an overview of important build options and their defaults. All options accept a
boolean
value (``YES``/``NO``, ``TRUE``/``FALSE``, ``ON``/``OFF`` or ``1``/``0``) and can be provided on the configuration-phase command line
using the ``-D`` switch.

.. list-table::
   :header-rows: 1

   * - CMake option
     - Default
     - Required dependencies
     - Description
   * - ``BUILD_TESTING``
     - ``OFF``
     -
     - Builds the unit tests.
   * - ``BUILD_DOCS``
     - ``OFF``
     - ``Doxygen``, ``Sphinx``
     - Builds the API/developer documentation in ``docs/``.
   * - ``BUILD_SHARED_LIBS``
     - ``ON``
     -
     - Build projectM as shared libraries. If ``OFF``, build static libraries.
   * - ``ENABLE_PLAYLIST``
     - ``ON``
     -
     - Builds and installs the playlist library.
   * - ``ENABLE_EMSCRIPTEN``
     - (auto)
     - ``Emscripten``
     - Forced ``ON`` when building with the Emscripten toolchain, otherwise ``OFF``. Not user-settable.
   * - ``ENABLE_GLES``
     - ``OFF``
     - ``GLES``
     - Use OpenGL ES 3 profile for rendering instead of the Core profile.

Note that ``ENABLE_GLES`` will be forcibly set to ``ON`` for Emscripten and Android builds, making it mandatory.

Experimental and application-dependent build switches
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following table contains a list of build options which are only useful in special circumstances, e.g. when
developing libprojectM, trying experimental features or building the library for a special use-case/environment.

.. list-table::
   :header-rows: 1

   * - CMake option
     - Default
     - Required dependencies
     - Description
   * - ``ENABLE_SDL_UI``
     - ``OFF``
     - ``SDL2``
     - Builds the SDL-based test application. Only used for development testing, will not be installed.
   * - ``ENABLE_INSTALL``
     - ``ON`` (top-level) / ``OFF`` (subproject)
     -
     - Enable projectM install targets. Automatically ``ON`` when built standalone, ``OFF`` when added via ``add_subdirectory()``.
   * - ``ENABLE_DEBUG_POSTFIX``
     - ``ON``
     -
     - Adds ``d`` (by default) to the name of any binary file in debug builds.
   * - ``ENABLE_SYSTEM_GLM``
     - ``OFF``
     -
     - Builds against a system-installed GLM library.
   * - ``ENABLE_SYSTEM_PROJECTM_EVAL``
     - ``ON``
     -
     - Uses a system-installed projectM-eval library if found, otherwise the bundled sources in ``vendor/``.
   * - ``ENABLE_BOOST_FILESYSTEM``
     - ``OFF``
     - ``Boost``
     - Forces the use of ``boost::filesystem`` instead of ``std::filesystem``. Only needed on toolchains without C++17 filesystem support.
   * - ``ENABLE_MACOS_FRAMEWORK``
     - ``OFF``
     - macOS
     - Build as macOS Framework bundles instead of plain shared libraries.
   * - ``ENABLE_CXX_INTERFACE``
     - ``OFF``
     -
     - Exports symbols for the ``ProjectM`` and ``PCM`` C++ classes and installs the additional the headers. Using the C++ interface is not recommended and unsupported.
   * - ``ENABLE_VERBOSE_LOGGING``
     - ``OFF``
     -
     - Enables code for ``TRACE`` and ``DEBUG`` log levels in release builds. By default, these will only be compiled for ``Debug`` builds. Enabling this will negatively affect performance, even if the actual log level is set to ``INFORMATION`` or higher.

Path options
^^^^^^^^^^^^

There are also a few textual parameters that can be used to fine-tune the installation directories. Relative paths in
the following options are appended to the value
of `CMAKE_INSTALL_PREFIX <https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html>`__ (which, on most UNIX
platforms, defaults to ``/usr/local``):

.. list-table::
   :header-rows: 1

   * - CMake option
     - Default
     - Description
   * - ``CMAKE_INSTALL_PREFIX``
     - (OS dependent)
     - Base directory where the projectM libraries, includes and support files will be installed.
   * - ``PROJECTM_BIN_DIR``
     - ``bin``
     - Directory where executables (e.g. the SDL standalone application) are installed.
   * - ``PROJECTM_LIB_DIR``
     - ``lib[64]``
     - Directory where libprojectM is installed.
   * - ``PROJECTM_INCLUDE_DIR``
     - ``include``
     - Directory where the libprojectM include files will be installed under.

Other options
^^^^^^^^^^^^^

Various other options for specific needs.

.. list-table::
   :header-rows: 1

   * - CMake option
     - Default
     - Description
   * - ``CMAKE_DEBUG_POSTFIX``
     - ``d`` (if ``ENABLE_DEBUG_POSTFIX`` is set)
     - Postfix appended to debug libraries.
   * - ``CMAKE_INSTALL_BINDIR``
     - ``bin``
     - Another way to specify the binary installation directory. Used as default value for ``PROJECTM_BIN_DIR``.
   * - ``CMAKE_INSTALL_LIBDIR``
     - ``lib`` or ``lib64``
     - Another way to specify the library installation directory. Used as default value for ``PROJECTM_LIB_DIR``.
   * - ``CMAKE_INSTALL_INCLUDEDIR``
     - ``include``
     - Another way to specify the include file installation directory. Used as default value for ``PROJECTM_INCLUDE_DIR``.

Always perform out-of-tree builds!
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Most classic IDEs and build systems directly make use of the source tree and create project files, temporary build
artifacts (e.g. object files) and the final binaries in the same directory structure as the source files. An advantage
of this approach is that you can find all compiled binaries side-by-side with their sources and generated headers are
already in the same directories as the source files including them. This approach has some drawbacks though:

- Only a single build configuration is supported as files are overwritten in-place.
- A lot of noise is created in the source directory, making it hard to distinguish between generated and original source
  files.
- A very large ``.gitignore`` file is required to cover all unwanted files.
- Mistakes in the build scripts can overwrite source files, causing errors and destroy uncommitted work.

Some of these can be mitigated by providing additional targets (``make clean`` and ``make distclean``) or creating
subdirectories for Debug/Release build configurations.

While CMake also supports in-tree builds, it is "discouraged" in the official documentation, for the above reasons.
Building out-of-tree allows it to create multiple build directories with different configurations which do not influence
each other in any way. If a build directory contains unwanted artifacts, and you want to start fresh, simply delete and
recreate the whole directory - no work is lost.

This project follow this principle by treating the original source tree as read-only and avoiding potential conflicts:

- Everything under `CMAKE_SOURCE_DIR <https://cmake.org/cmake/help/latest/variable/CMAKE_SOURCE_DIR.html>`__ must only be
  read, never changed or written to.
- Everything under `CMAKE_BINARY_DIR <https://cmake.org/cmake/help/latest/variable/CMAKE_BINARY_DIR.html>`__ is temporary
  and related to the current build configuration.
- When generating configuration-dependent files,
  use `CMAKE_CONFIGURATION_TYPES <https://cmake.org/cmake/help/latest/variable/CMAKE_CONFIGURATION_TYPES.html>`__
  and `CMAKE_BUILD_TYPE <https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html>`__ to create non-conflicting
  files in the build tree.

While this project will not force you to build out-of-tree, there is no mechanism to clean up the generated files after
running cmake in-tree.

CMake build directory layout
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you are new to CMake, the way of how CMake creates the build directory and where it creates the build targets might
be confusing. Here is a summary of what's in the build directory and how it is structured in general.

Using files from the build tree
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

It is generally not good practice to directly take binaries and other files from the build tree for packaging, for
several reasons:

1. The directory structure is generated by CMake and depends on the generator used. The layout might change between
   CMake versions, even for the same generator.
2. On platforms with RPATH support, CMake will store absolute paths in executables and shared libraries which point to
   the absolute paths of any linked dependencies, either from the build tree or external libraries as well. These
   binaries are not relocatable and will most certainly not work if run on any other computer (or even on the same after
   deleting the build directory).
3. For some configurations, even Release build artifacts may contain debug symbols until they are installed.

It is fine to build and run executables from the build directory for development and debugging. For packaging or using
libprojectM in other projects, always use the ``install`` target and copy files from there.

Generated files
^^^^^^^^^^^^^^^

In the top-level build directory, CMake creates a few files that are present on any platform:

- ``CMakeCache.txt``: This file contains all variables and build settings CMake needs to remember from the first
  configuration run. This file can be edited on demand either manually or using a CMake UI to change any values. On the
  next build, CMake will regenerate the project files if this file has been modified.
- ``cmake_install.cmake``: Contains generated install-related settings.
- ``install_manifest.txt``: After installing the project, this file contains a list with absolute filenames of all
  installed files. It can be used for packaging or deleting installed files as CMake doesn't define an ``uninstall``
  target.
- The top-level project file for use with the selected build toolset, e.g. ``Makefile``, ``build.ninja``, ``projectm.sln``
  or ``projectm.xcodeproj``, plus additional toolset-specific files.

The projectM build files generate additional files used in the build and install phases. These are scattered over the
build tree, but installed into the proper directories. Do not try and gather these files yourself from the build tree.

Subdirectory structure
^^^^^^^^^^^^^^^^^^^^^^

The rest of the directory structure generally resembles the source tree. Source directories containing
a ``CMakeLists.txt`` file will also be created in the build tree with the same relative path. Each of these subdirectories
contains a ``CMakeFiles`` directory with CMake-internal data, generated project files for the select toolset, e.g.
makefiles and any temporary compile artifacts.

The directory structure is created by CMake and may change depending on the generator and CMake version used.

Executable and library locations
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Build targets - shared/static libraries and executables - are created in the same subdirectory in the build tree as
the ``CMakeLists.txt`` file that defines the target in the source tree (which, in most cases, resides in the same
directory as the source files). Depending on the generator used, the binaries are created directly in the directory for
single-configuration generators (like ``Unix Makefiles`` or ``Ninja``) and in a subdirectory with the configuration name,
e.g. ``Debug`` or ``Release``, for multi-configuration generators like ``Xcode`` or ``Visual Studio 17 2022``.

You may also find additional files and symbolic links in the same location depending on the platform, e.g. ``.pdb`` files
on Windows.

Using libprojectM in other CMake projects

// Create the SDL window (will be tied to the Emscripten HTML5 canvas)
   SDL_window* window = NULL;
   SDL_renderer* renderer = NULL;
   SDL_CreateWindowAndRenderer(1024, 768, SDL_WINDOW_OPENGL, &window, &renderer);
   if (window == NULL || renderer == NULL)
   {
       fprintf(stderr, "Failed to create SDL renderer: %s\n", SDL_GetError());
       return 1;
   }

   // Enable floating-point texture support for motion vector grid.
   auto webGlContext = emscripten_webgl_get_current_context();
   emscripten_webgl_enable_extension(webGlContext, "OES_texture_float");

   // Initialize projectM and put all other stuff below.
   
   return 0;

This repository now only contains the projectM shared/static library.
All frontends, plug-ins and other tools were outsourced into separate
repositories. If you’re not a developer and just look for a download to
run projectM visuals on your machine or device, please use one of the
links listed below. The releases section in this repository only
contains source-code and binary releases of the projectM development
libraries and headers, which aren’t useful for end users.

End-User Applications
~~~~~~~~~~~~~~~~~~~~~

**Important**: projectM is currently undergoing heavy development. The
available end-user frontends are development previews, which are not
feature-complete and may have bugs.

Windows
^^^^^^^

-  Standalone (`projectMSDL 2.0
   pre-release <https://github.com/projectM-visualizer/frontend-sdl-cpp/releases>`__)
-  `Steam <https://store.steampowered.com/app/1358800/projectM_Music_Visualizer/>`__
   (Same as standalone development preview)
-  `Windows Store <https://www.microsoft.com/store/apps/9NDCVH0VCWJN>`__
   (Old 3.1.12 release)

macOS
^^^^^

-  Standalone

   -  `C++ app
      pre-release <https://github.com/projectM-visualizer/frontend-sdl-cpp/releases>`__
   -  `Rust app development preview
      (signed) <https://github.com/projectM-visualizer/frontend-sdl-rust/releases/tag/v0.1.0>`__
-  `Steam <https://store.steampowered.com/app/1358800/projectM_Music_Visualizer/>`__
   (Old 3.1.12 release)
-  Music.app Plugin (currently only available as an *unsigned*
   `development
   preview <https://github.com/kblaschke/frontend-music-plug-in/releases/tag/v3.0-pre1>`__)
-  `Brew <https://formulae.brew.sh/formula/projectm>`__ (Old 3.1.12
   release)

Linux
^^^^^

-  Standalone (`projectMSDL 2.0
   pre-release <https://github.com/projectM-visualizer/frontend-sdl-cpp/releases>`__,
   also available as ``.deb`` and ``.tar.gz``)
-  `Steam <https://store.steampowered.com/app/1358800/projectM_Music_Visualizer/>`__
   (Same as standalone development preview)

Or check your distribution’s package manager for a binary release. If it
is outdated, please contact the package maintainer, as the projectM
development team does not maintain any of the distribution-specific
packages.

Android
^^^^^^^

-  `Google
   Play <https://play.google.com/store/apps/details?id=com.psperl.prjM>`__

**Note**: Both the free and paid apps plus the Android TV app are *not*
created or supported by the projectM developers! If you have technical
troubles or other inquiries, please contact the app author via the means
provided in the Play Store. Any bug reports in the projectM issue
tracker regarding the apps will be closed immediately.

Xbox / Windows Phone
^^^^^^^^^^^^^^^^^^^^

-  `Windows Store <https://www.microsoft.com/store/apps/9NDCVH0VCWJN>`__
   (Old 3.1.12 release)

Other
^^^^^

Source code and other resources, mostly aimed at developers.

-  `Library source
   code <https://github.com/projectM-visualizer/projectm/>`__ (this
   repository)
-  `Qt <https://www.qt.io/>`__ based (Qt5/Qt6) desktop apps for Linux
   with `PipeWire <https://pipewire.org/>`__,
   `PulseAudio <https://www.freedesktop.org/wiki/Software/PulseAudio/>`__
   and JACK audio backends (`source
   code <https://github.com/projectM-visualizer/frontend-qt>`__,
   requires libprojectM 4.x).
-  `ALSA, XMMS, Winamp,
   JACK <https://sourceforge.net/projects/projectm/files/>`__ (legacy
   2.x sources for historic purposes, unmaintained since 2012)

Discord chat
~~~~~~~~~~~~

`Chat with us on Discord! <https://discord.gg/N9DyQfCH4j>`__

Click For Demo Videos
~~~~~~~~~~~~~~~~~~~~~

A demo playlist is available on
`YouTube <https://www.youtube.com/watch?v=jJmLQGhYWys&list=PLFLkbObX4o6TK1jGL6pm1wMwvq2FXnpYJ>`__.

Presets
~~~~~~~

The preset files define the visualizations via pixel shaders and
Milkdrop-style equations and parameters.

The projectM library does not ship with any presets. The frontends come
with varying preset packs which can be found in separate repositories in
the projectM repository list:

-  `Base Milkdrop texture
   pack <https://github.com/projectM-visualizer/presets-milkdrop-texture-pack>`__
   - Recommended for use with *any* preset pack!
-  `Cream of the Crop
   Pack <https://github.com/projectM-visualizer/presets-cream-of-the-crop>`__
   - A collection of about 10K presets compiled by Jason Fletcher.
   Currently, projectM’s default preset pack.
-  `Classic projectM
   Presets <https://github.com/projectM-visualizer/presets-projectm-classic>`__
   - A bit over 4K presets shipped with previous versions of projectM.
-  `Milkdrop 2
   Presets <https://github.com/projectM-visualizer/presets-milkdrop-original>`__
   - The original preset collection shipped with Milkdrop and Winamp.
-  `En D
   Presets <https://github.com/projectM-visualizer/presets-en-d>`__ -
   About 50 presets created by “En D”.

Included with projectM are the bltc201, Milkdrop 1 and 2, projectM,
tryptonaut and yin collections. You can grab these presets
`here <http://spiegelmc.com/pub/projectm_presets.zip>`__.

You can also download an enormous 130k+ presets from the MegaPack
`here <https://drive.google.com/file/d/1DlszoqMG-pc5v1Bo9x4NhemGPiwT-0pv/view>`__
(4.08GB zipped, incl. textures).

Also Featured In
~~~~~~~~~~~~~~~~

`|Kodi| Kodi (formerly XBMC) <https://kodi.tv/>`__

`|Helix|
Helix <https://web.archive.org/web/20180628174410/http://ghostfiregames.com/helixhome.html>`__

`|Silverjuke| Silverjuke (FOSS Jukebox) <https://www.silverjuke.net>`__

`|VLC Media Player| VLC Media Player (AKA VideoLAN
Client) <https://www.videolan.org/vlc/>`__

Reminder: These are all third-party integrations of libprojectM and not
developed or supported by the projectM development team. Please report
bugs in those applications to their respective developers.

Screenshots
-----------

.. figure:: web/projectM_screenshots/Screen\ Shot\ 2014-08-25\ at\ 12.31.20\ AM.png
   :alt: Screenshot

   Screenshot

.. figure:: web/projectM_screenshots/Screen\ Shot\ 2014-08-25\ at\ 12.33.50\ AM.png
   :alt: Screenshot

   Screenshot

.. figure:: web/projectM_screenshots/Screen\ Shot\ 2014-07-18\ at\ 2.14.41\ PM.png
   :alt: Screenshot

   Screenshot

.. figure:: web/projectM_screenshots/Screen\ Shot\ 2014-07-18\ at\ 2.13.53\ PM.png
   :alt: Screenshot

   Screenshot

.. figure:: web/projectM_screenshots/Screen\ Shot\ 2014-07-18\ at\ 2.15.36\ PM.png
   :alt: Screenshot

   Screenshot

.. figure:: web/projectM_screenshots/Screen\ Shot\ 2014-08-16\ at\ 4.49.32\ PM.png
   :alt: Screenshot

   Screenshot

.. figure:: web/projectM_screenshots/Screen\ Shot\ 2014-08-16\ at\ 4.50.37\ PM.png
   :alt: Screenshot

   Screenshot

.. figure:: web/projectM_screenshots/Screen\ Shot\ 2014-08-25\ at\ 12.31.07\ AM.png
   :alt: Screenshot

   Screenshot

Architecture
------------

-  `Article <https://lwn.net/Articles/750152/>`__

Building from source
--------------------

See :doc:`building` and the `developer documentation in the
wiki <https://github.com/projectM-visualizer/projectm/wiki/Building-libprojectM>`__.

Using the library
-----------------

At its core projectM is a library, `libprojectM <src/libprojectM>`__.
This library is responsible for parsing presets, analyzing audio PCM
data with beat detection and FFT, applying the preset to the audio
feature data and rendering the resulting output with OpenGL. It can
render to a dedicated OpenGL context or a texture.

To get started using projectM in your own projects, please go to the
wiki and read the `developer
documentation <https://github.com/projectM-visualizer/projectm/wiki#integrating-projectm-into-applications>`__
available there.

There are some open-source applications that make use of libprojectM
which can be found in the `projectM organization’s
repositories <https://github.com/projectM-visualizer>`__ and elsewhere.

Help
----

Report issues on GitHub in the respective repositories:

-  `Rendering issues, crashes or the libprojectM
   core/API <https://github.com/projectM-visualizer/projectm/issues>`__
-  `Standalone SDL
   app <https://github.com/projectM-visualizer/frontend-sdl2/issues>`__
   (including the Steam release)
-  `Windows Store
   App <https://github.com/projectM-visualizer/frontend-uwp/issues>`__
-  `Apple Music
   plug-in <https://github.com/projectM-visualizer/frontend-music-plug-in/issues>`__
-  Issues regarding the **projectM Android apps in the Play Store**,
   please contact the app author via the Play Store. We cannot help with
   any problems or requests.

If unsure, post your issue in the main `libprojectM issue
tracker <https://github.com/projectM-visualizer/projectm/issues>`__.
Please always check any existing issues if your problem has already been
posted by another user. If so, add your logs and findings to the
existing issue instead of opening a new ticket.

Get in contact with us
----------------------

`Chat with us on Discord. <https://discord.gg/N9DyQfCH4j>`__

Contribute to projectM
----------------------

If you would like to help improve this project, either with
documentation, code, porting, hardware or anything else please let us
know! We gladly accept pull requests and issues.

Before starting to write code, please take your time to read the
`contribution
guidelines <https://github.com/projectM-visualizer/projectm/wiki#contributing-to-projectm>`__
in our wiki.

Package Maintainers
-------------------

If you maintain packages of libprojectM, we are happy to work with you!
Please note well:

-  The main focus of this project is libprojectM. It’s a library that
   only really depends on OpenGL. The other applications are more like
   examples and demos.
-  Many of the frontend applications are likely outdated and of less
   utility than the core library. If you desire to use them or depend on
   them, please file an issue in the respective repository so we can
   help update them.
-  The “canonical” application for actually viewing the visualizations
   is now
   `projectMSDL <https://github.com/projectM-visualizer/frontend-sdl-cpp>`__,
   based on libSDL2 because it supports audio input and is completely
   cross-platform.
-  This is an open source project! If you don’t like something, feel
   free to contribute improvements!
-  Yes, you are looking at the official version. This is not a fork.

Authors
-------

`Authors <https://github.com/projectM-visualizer/projectm/raw/master/AUTHORS.txt>`__

License
-------

The core projectM library is released under the `GNU Lesser General
Public License
2.1 <https://github.com/projectM-visualizer/projectm/raw/master/LICENSE.txt>`__
to keep any changes open-sourced, but also enable the use of libprojectM
in closed-source applications (as a shared library) as long as the
license terms are adhered to. The up- and downstream projects may use
different licenses - please check all parts of the software to be
compatible with your specific project if you plan an integration.

Wiki
----

More information for developers is available from the `projectM
Wiki <https://github.com/projectM-visualizer/projectm/wiki>`__.

.. |Windows Build Status| image:: https://github.com/projectM-visualizer/projectm/actions/workflows/build_windows.yml/badge.svg?branch=master
   :target: https://github.com/projectM-visualizer/projectm/actions/workflows/build_windows.yml
.. |Linux Build Status| image:: https://github.com/projectM-visualizer/projectm/actions/workflows/build_linux.yml/badge.svg?branch=master
   :target: https://github.com/projectM-visualizer/projectm/actions/workflows/build_linux.yml
.. |macOS Build Status| image:: https://github.com/projectM-visualizer/projectm/actions/workflows/build_osx.yml/badge.svg?branch=master
   :target: https://github.com/projectM-visualizer/projectm/actions/workflows/build_osx.yml
.. |Emscripten Build Status| image:: https://github.com/projectM-visualizer/projectm/actions/workflows/build_emscripten.yml/badge.svg?branch=master
   :target: https://github.com/projectM-visualizer/projectm/actions/workflows/build_emscripten.yml
.. |Android Build Status| image:: https://github.com/projectM-visualizer/projectm/actions/workflows/build_android.yml/badge.svg?branch=master
   :target: https://github.com/projectM-visualizer/projectm/actions/workflows/build_android.yml
.. |Discord Shield| image:: https://discordapp.com/api/guilds/737206408482914387/widget.png?style=shield
.. |Kodi| image:: web/kodi.png
.. |Helix| image:: web/helix.jpg
.. |Silverjuke| image:: web/silverjuke.png
.. |VLC Media Player| image:: web/vlc.png

---

--- METRICS ---
- Files Extracted: 4
- Estimated Token Budget: ~15830 tokens
- Canonical Reference: https://codewiki.google/github.com/projectM-visualizer/projectm