View on GitHub

SDL-Mixer-X

SDL Mixer X (Or "MixerX" shortly) - An audio mixer library based on the SDL library, a fork of SDL_mixer

MixerX - the extended SDL_mixer

A fork of SDL_mixer library

Description

SDL_Mixer is a sample multi-channel audio mixer library. It supports any number of simultaneously playing channels of 16 bit stereo audio, plus a single channel of music, mixed by the popular FLAC, OPUS, XMP, ModPlug, MikMod MOD, Timidity MIDI, FluidSynth, libADLMIDI, libOPNMIDI, Ogg Vorbis, stb_vorbis, FLAC, DRFLAC, DRMP3 and MPG123 MP3 libraries.

SDL Mixer X (or shorty MixerX) - It’s an extended fork of the SDL_mixer library made by Vitaly Novichkov “Wohlstand” in 13 January 2015. SDL_mixer is a quick and stable high-quality audio library, however, it has own bunch of deffects and lack of certain abilities such as inability to choose the MIDI backend in runtime, No support for cross-fade and parallel streams playing (has only one musical stream. Using of very long Chunks is ineffectively), etc. The goal of this fork is resolving those issues, providing more extended functionality than was originally, and providing support for more supported audio formats.

New features of MixerX in comparison to original SDL_mixer

Features introduced at MixerX later added into the mainstream SDL_mixer

Features introduced at MixerX later removed because of unnecessarity

How to build

Requirements

Minimal

To build library, the next conditions are required:

More file formats support

Without installing any codec libraries and without AudioCodecs pack use, these formats will be supported by the library by default:

If you want to enable support for more file formats, you will need to install optional libraries (listed below) into the system and, if needed, their use. You aren’t required to install every library into the system to build the library: any enabled component will be automatically disabled when the required library is missing from the system.

BSD/MIT/PD-licensed libraries

There are libraries licensed under any of permissive license. These libraries can be linked to any project (including closed-source proprietary projects). They are always used when detected to be installed in the system.

LGPL-licensed libraries

There are libraries that has LGPL license, and you will need to link them dynamically when your project is not compatible to GPL license. These libraries will not be used without -DMIXERX_ENABLE_LGPL=ON (or -DMIXERX_ENABLE_GPL=ON) CMake argument.

GPL-licensed libraries

There are libraries that currently has GPL license, and if you will take use of them, the license of MixerX will be GPLv3. These libraries will not ne used without -DMIXERX_ENABLE_GPL=ON CMake argument.

Build the project

License of library

The MixerX library has 3 different license modes (Zlib (default), LGPLv2.1+, and GPLv3+) depending on enabled components: you may get the LGPL license if you statically link LGPL components into the MixerX shared library, or GPL license when you link any GPL components to the library. By default, LGPL and GPL licensed modules are disabled. You may use the next CMake options to enable these modules:

If you want to statically link the library into GPL-incompatible software, don’t enable these options.

Build with default configuration

Once all necessary dependencies installed, run the next code in your terminal at the clonned repository directory:

# Prepare the build directory
mkdir build
cd build

# Configure the project
cmake -DCMAKE_BUILD_TYPE=Release ..

# Run the build
make -j 4 #where 4 - set number of CPU cores you have

# Install the built library and headers into the system
make install

It will enable these components which was detected at the system during CMake step.

The built library will have ZLib license that you can statically link with any application including closed-source proprietary.

This build will have next components always disabled:

Build with default configuration with LGPL mode

If you want to enable support for FluidSynth, GME, and MPG123, you will need to use the LGPL mode (adding the -DMIXERX_ENABLE_LGPL=ON argument), run the configure step with the next line:

# Configure the project
cmake -DCMAKE_BUILD_TYPE=Release -DMIXERX_ENABLE_LGPL=ON -DSDL_MIXER_X_SHARED=ON -DSDL_MIXER_X_STATIC=OFF ..

The resulted build will have LGPLv2.1 license that you can dynamically link with any application including commercial.

This build will have next components always disabled:

Build with default configuration and GPL license

If you want to enable support for libADLMIDI and libOPNMIDI, you will need to use the GPL mode (adding the -DMIXERX_ENABLE_GPL=ON argument), run the configure step with the next line:

# Configure the project
cmake -DCMAKE_BUILD_TYPE=Release -DMIXERX_ENABLE_GPL=ON ..

All supported components will be enabled in condition they are installed at the system. This version you can link with GPL-only applications. The final license of the library will be printed out after running CMake command.

Build with AudioCodecs

If you want to build the library with the complete functionality and you don’t want or can’t install any libraries into system, you can enable use of the AudioCodecs repository which is a collection of audio codec libraries bundled into single portable build project. This way is very useful on platforms such as Windows, mobile platforms such as Android where is required to build all dependencies from the source separately, or homebrew console toolchains with the similar case. You aren’t required to build and install separately, you can enable two CMake options to let CMake do all hard work instead of you. You will need to add -DDOWNLOAD_AUDIO_CODECS_DEPENDENCY=ON and -DAUDIO_CODECS_BUILD_LOCAL_SDL2=ON options into your CMake command line to enable use of AudioCodecs external package. This will allow you to build the library even SDL2 (the required dependency) is not installed at your system at all, or there is an older version than required minimum.

General build on UNIX-like platform and install into the system

The library will be built and installed into system in usual way

# Prepare the build directory
mkdir build
cd build

# Configure the project
cmake -DCMAKE_BUILD_TYPE=Release -DDOWNLOAD_AUDIO_CODECS_DEPENDENCY=ON -DAUDIO_CODECS_BUILD_LOCAL_SDL2=ON ..

# Run the build
make -j 4 #where 4 - set number of CPU cores you have

# Install the built library and headers into the system
make install

Build with installing into custom location

If you don’t want install the library into system, you may specify the different path for the library installation and then, copy it into another location or refer it directly at the project:

# Prepare the build directory
mkdir build
cd build

# Configure the project
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=output -DDOWNLOAD_AUDIO_CODECS_DEPENDENCY=ON -DAUDIO_CODECS_BUILD_LOCAL_SDL2=ON ..

# Run the build
cmake --build . --config Release -- j 4 #where 4 - set number of CPU cores you have

# Install the built library and headers into the system
make install

After run, the library, all dependencies, and headers will appear at the “output” sub-directory at the “build” directory inside the repository. You can refer use its content in your project directly.

Use standalone copy of AudioCodecs repository

You may totally avoid any network access during build if you make the full copy of the AudioCodecs repository and when you build it separately.

# Clonning both repositories (and in the next time, pack them into archive and take them at any time you want to use them)
git clone https://github.com/WohlSoft/AudioCodecs.git
git clone https://github.com/WohlSoft/SDL-Mixer-X.git

# Building AudioCodecs
cd AudioCodecs
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release -DUSE_LOCAL_SDL2=ON -DCMAKE_INSTALL_PREFIX=../../mixerx-install ..
make -j 5
make install
cd ../..

# Building MixerX and re-use libraries built at AudioCodecs
cd SDL-Mixer-X
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=../../mixerx-install -DAUDIO_CODECS_INSTALL_PATH=../../mixerx-install -DAUDIO_CODECS_REPO_PATH=../../AudioCodecs ..
make -j 5
make install

So, the complete build will appear at the “mixerx-install” directory among both AudioCodecs and SDL_Mixer_X repositories.

How to use library

Include

The API is backward-compatible with original SDL2_mixer and can be used as a drop-in replacement of original SDL2_mixer with exception of a different header name

#include <SDL2/SDL_mixer_ext.h>

and different linked library name SDL2_mixer_ext.

In addition, there are new API calls which can be used to take full ability of the MixerX fork.

Linking (Linux)

Dynamically

gcc playmus.c -o playmus -I/usr/local/include -L/usr/local/lib -lSDL2_mixer_ext -lSDL2 -lstdc++

Statically

To get it linked you should also link all dependencies of MixerX library itself and also dependencies of SDL2 too

gcc playmus.c -o playmus -I/usr/local/include -L/usr/local/lib -Wl,-Bstatic -lSDL2_mixer_ext -lopusfile -lopus -logg -lxmp -lmodplug -lADLMIDI -lOPNMIDI -lEDMIDI -lgme -lzlib -lSDL2 -Wl,-Bdynamic -lpthread -lm -ldl -static-libgcc -lstdc++

Documentation