SDL Mixer X

SDL Mixer X - SDL Mixer eXtended ( SDL2_mixer_ext ) - a fork from SDL mixer version 2.0 which an extension for Simple DirectMedia Layer (SDL) library which giving a complex audio functions, mainly for sound mixing.

This part appending to SDL additional functions which are giving able to play more sound and music formats.

Because of original SDL Mixer had some issues, Wohlstand has been forked it to resolve them and also implement a new features to it.

SDL Mixer X used in the PGE Project as part of default audio engine and also included by Wohlstand and Kevsoft into the LunaLua to replace the MCI audio engine to take able play more music formats inside SMBX. SMBX-38A also uses SDL Mixer X since 1.4.2 version. Because that built on VisualBasic 6, VB6 Wrapper has been made. Assembly with VB6 binding support (SDL2MixerVB.dll) has statically linked SDL2 library, but with Audio-only support, other SDL subsystems are not binded yet.

Music Formats
SDL Mixer X have support for playback for next formats which can be played in the music stream:

Standard music formats

 * WAV — Microsoft PCM, Uncompressed audio (hardcoded), has loop support (by SMPL chunk).
 * VOC — Creative Labs Audio File (hardcoded).
 * MP3 — MPEG-2 Layer 3, Lossy data compressed audio (libMAD).
 * OGG — OGG Vorbis, Lossy data compressed audio (libOGG, libVorbis), has loop support (by LOOPSTART/LOOPEND/LOOPLENGTH meta tags).
 * OPUS — OPUS, Lossy data compressed audio (libOpus) (Support was added Since June 18, 2018), has loop support (by LOOPSTART/LOOPEND/LOOPLENGTH meta tags).
 * FLAC — Free Lossless Audio Codec, Loss-less compressed (libFLAC).
 * MIDI — Music Instrument Digital Interface, commands list (libADLMIDI, Timidity (hardcoded), Fluidsynth (Usually not built with SDL Mixer X, but possible to use it) ), has loop support (by loopStart/loopEnd markers and by CC111 like RPG Maker)

Extra music formats

 * XMI — MIDI-like format used in AIL library and was widely used in many DOS games. Can be played by ADLMIDI and OPNMIDI synthesizers only. Has loop support (by CC116 and CC117).
 * MUS — MIDI-like format used in DMX library and known by Doom and Raptor game series are used DMX sound library. Can be played with ADLMIDI and OPNMIDI synthesizers only.
 * IMF — Id-Software Music File (will work only if ADLMIDI MIDI device will be toggled). Supported IMF-files which are has length chunk in begin and uses 700Hz of the ticks rate. (Tip: If your IMF-files are playing with wrong tempo or rejecting as invalid files, you have to use this utility to convert frequency and automatically add length chunk into file begin).
 * CMF — Creative Music Format, A MIDI file mixed with OPL2 FM instruments, widely used in many DOS games. Can be played with ADLMIDI synthesizer only.

Game music emulators formats
All Game Music Emulators formats are provided with GME library.


 * AY — ZX Spectrum/Amstrad CPC
 * GBS — Nintendo Game Boy
 * GYM — Sega Genesis/Mega Drive
 * HES — NEC TurboGrafx-16/PC Engine
 * KSS — MSX Home Computer/other Z80 systems (doesn't support FM sound)
 * NSF/NSFE — Nintendo NES/Famicom (with VRC 6, Namco 106, and FME-7 sound)
 * SAP — Atari systems using POKEY sound chip
 * SPC — Super Nintendo/Super Famicom
 * VGM/VGZ — Sega Master System/Mark III, Sega Genesis/Mega Drive,BBC Micro

Tracker music formats
All tracker music formats are provided with libXMP and libModPlug libraries.
 * 669 — Composer 669, Unis 669
 * AMF — DSMI Advanced Module Format
 * AMF — ASYLUM Music Format V1.0
 * APUN — APlayer
 * DSM — DSIK internal format
 * DBM — DigiBooster Pro (libXMP)
 * DTM — Digital Tracker (libXMP)
 * DIGI — DIGI Booster (libXMP)
 * EMOD — Quadra Composer (libXMP)
 * FAR — Farandole Composer
 * FLX — Flextrax (libXMP)
 * FNK — Funktracker (libXMP)
 * GDM — General DigiMusic
 * IT — Impulse Tracker
 * IMF — Imago Orpheus (Support has been repaired with using of libXMP since March 10, 2019)
 * LIQ — Liquid Tracker (libXMP)
 * MDL — Digitrakker (libXMP)
 * MOD — 15 and 31 instruments
 * MED — OctaMED
 * MTM — MultiTracker Module editor
 * MTN — ST 2.6, Ice Tracker (libXMP)
 * MGT — Megatracker (libXMP)
 * OKT — Amiga Oktalyzer
 * PTM — Poly Tracker (libXMP)
 * RTM — Real Tracker (libXMP)
 * S3M — Scream Tracker 3
 * STM — Scream Tracker
 * STX — Scream Tracker Music Interface Kit
 * SFX — Amiga SoundFX (libXMP)
 * ULT — UltraTracker
 * UNI — MikMod
 * WOW — Mod's Grave (libXMP)
 * XM — FastTracker 2

SFX Formats
SDL Mixer X have a support for playback for next sound effects which can be preloaded into memory played in difference channels with mixing:
 * WAV — Microsoft PCM, Uncompressed audio
 * VOC — Creative Labs Audio File
 * OGG — OGG Vorbis, Lossy data compressed audio
 * FLAC — Free Lossless Audio Codec, Loss-less compressed
 * MP3 — MPEG-2 Layer 3, Lossy data compressed audio (Note: before update since February 2 2016 MP3 chunks are not supported!)

Differences and improvements in comparison to original SDL Mixer

 * Added much more music formats (Such a game music emulators)
 * Added support of the loop points in the OGG files (via LOOPSTART and LOOPEND (or LOOPLENGHT ) meta-tags)
 * In the Modplug module enabled internal loops (tracker musics with internal loops are will be looped rightly)
 * Added ability to append custom config path for Timidity synthesizer
 * Forked version now has ADLMIDI and OPNMIDI midi synthesizers together with Native MIDI, Timidity and Fluidsynth. ADLMIDI is a synthesizer based on Yamaha YMF262 OPL3 FM Synthesizer chip emulation. OPNMIDI is a synthesizer based on Yamaha YM2612 OPN2 FM Synthesizer chip emulation.
 * Added new API functions
 * Ability to redefine Timidity patches path. So, patches folders are can be stored in any place!
 * Added functions to retrieve some meta-tags: Title, Artist, Album, Copyright
 * Added ADLMIDI Extra functions: Change bank ID, enable/disable high-level tremolo, enable/disable high-level vibrato, enable/disable scalable modulation
 * Added chunk play functions with initial volume value
 * Own re-sampling implementation which avoids glitches caused with inaccurate re-sampler implementation from SDL. Removed, no more needed as SDL2 since 2.0.8 has much better resampler.
 * Added support of extra arguments in the tail of the file path, passed into Mix_LoadMUS function.
 * Added ability to build shared library in the stdcall mode with static linking of libSDL on Windows to use it as independent audio library with other languages like VB6 or .NET.
 * Improved support for WAV and AIFF files, addedd support for more sample formats like PCM24, PCM32, PCM64, Float32, Float64, ALAW, and uLAW.

Path arguments
SDL Mixer X has support of additional path arguments in the Mix_LoadMUS function to allow changing of some decoding properties.

Game music emulators formats

Alone argument - integer from 0 to n - a number of the track from multi-track file formats like NSF, NSFE, HES, GBS, etc.

Example: mymusic.nsf|21

Since October 15, 2019 the syntax has been extened and now it supports addional arguments: mymusic.nsf|21;g=1.0;t=1.0 All arguments after first integer are optional. The leading integer is required, even it's a single-track file. Last argument must be closed with semicolon.
 * t= - Initial tempo factor (1.0 is default value, accepting positive floating point number values, for example, `t=1.75;`), increase or decrease the initial tempo of the song.
 * g= - Gain factor (1.0 is default value, accepting positive floating point number values, for example, `g=1.75;`), increase or decrease the volume level of the song. Use it to increase volume of too silent songs, or decrease a volume of too loud songs.

MIDI

Accepts list of letter-marked integer arguments separated by semicolons.

Example: mymusic.mid|s0;b62;t0;v0;a0;m0;t=1.0;g=2.0; All arguments are optional. Last argument must be closed with semicolon.
 * s - Synthesizer type:
 * 0 - ADLMIDI, emulated OPL3 (YMF262) synthesizer with loop tags support. Working by Default. (Recorded examples to listen are presented here). OPL3 chip was widely used on PC sound cards in 80/90'th years.
 * 1 - Native MIDI, uses default operating system MIDI interface. Not supports loop tags and system exclusive messages.***
 * 2 - Timidity, requires patches bank in the "timidity" folder in the application path (can be customized with "MIX_Timidity_addToPathList(const char*path)" function called before library initialization) **
 * 3 - OPNMIDI, emulated OPN2 (YM2612) synthesizer with loop tags support. OPN2 chip is used on Sega MegaDrive / Genesis game console. This synthesizer has been added since May 14, 2017.
 * b - (ADLMIDI) Set bank ID (look for available banks list into PGE MusPlay application to preview them). Default is 58.
 * t - (ADLMIDI) Deep tremolo (1 or 0), increase amplitude of tremolo effect for instruments which are using tremolo OPL flag. Default 1. Don't confuse with `t=` which is different.
 * t= - (ADLMIDI and OPNMIDI) Initial tempo factor (1.0 is default value, accepting positive floating point number values, for example, `t=1.75;`), increase or decrease the initial tempo of the song. Don't confuse with `t0` and `t1` which is different.
 * g= - Gain factor (2.0 is default value, accepting positive floating point number values, for example, `g=1.75;`), increase or decrease the volume level of the song. Use it to increase volume of too silent songs, or decrease a volume of too loud songs.
 * v - (ADLMIDI) Deep vibrato (1 or 0), increase amplitude of vibrato effect for instruments which are using vibrato OPL flag. Default 1.
 * a - (ADLMIDI) Enables AdLIB drums mode (1 or 0), enables legacy OPL2 drums mode. Default 0.
 * m - (ADLMIDI) Enables scalable modulation (1 or 0), Allows dynamic scaling of the modulator result with volume. Default 0.
 * c - (ADLMIDI and OPNMIDI) Count of chip emulators are allowing to excite limit of voice channels. Default 4. Allowed value from 1 to 100.
 * f - (ADLMIDI) Count of four-operator channels between of all chip emulators (6 channels maximum per every chip. For example, you have using 2 chips, you can have 12 four-op channels maximum).
 * l - (ADLMIDI and OPNMIDI) Volume scaling model code (0 - auto, 1 - Generic, - 2 OPL3-Native, 3 - DMX, 4 - Apogee, - 5 - Win9X-like) - an algorithm to scale a volume level, affects music expressionism.
 * r - (ADLMIDI and OPNMIDI) Use full-ranged CC74 Brightness MIDI controller (1 or 0). Default 0.
 * p - (ADLMIDI and OPNMIDI) Enable full-panning stereo support (1 or 0). Default 1.
 * e - (ADLMIDI) Choose OPL3 emulator: 0 - Nuked OPL3 (Very accurate, may lag on older CPUs), 1 - Nuked OPL3 1.7.4 that was optimized by Troosh, and 2 - DosBox 0.74 (Well-accurate, fastest).
 * e - (OPNMIDI) Choose OPN2 emulator: 0 - Mame YM2612 (Well-accurate, fast), 1 - Nuked OPN2 (Very accurate, requires VERY powerful CPU. Suggested to use up to 2 chips max with it), 2 - GENS 2.10 (Very outdated, inaccurate, but fastest)
 * x= - (ADLMIDI and OPNMIDI) Load custom bank file by absolute path (WOPN bank for OPNMIDI or WOPL for ADLMIDI). Accepting strings without quoties, for example, `x=/path/to/bank/file.wopn;`

** Note for Timidity: If you wish it works, you must have one of banks in GUS format which you can take here or in any other place around Internet.

*** Note for Native MIDI: Pausing is not works with Native MIDI on Windows [Fixed]. Fade-IN/OUT and volume manipulation on Windows with "Microsoft GS Wavetable synthesizer" driver may cause global mixer volume changing which can cause confusion. To avoid this effect, you can install a custom MIDI sequencer (for example software Yamaha XG, Virtual Sound Convas, BASSMIDI Driver, Virtual OPL3 Driver (Not works on WinXP, MIDI device switch tool has been included), or plug a hardware MIDI synthesizer if you have it).

Preview examples of difference between ADLMIDI flags

Issues
Here is a list of known issues of SDL Mixer v2.0 library:
 * Fade-IN in some cases is not working correctly, but Fade-Out working perfectly [Fixed]
 * Official build of SMPEG library can't play MP3 on Windows and Linux system, but on some Mac OS computers it working fine. To fix this issue need a rebuild of SDL_mixer library with using of libMAD library. (libMAD is GPL-licenced [not LGPL], and if you will build (or use pre-built with libMAD) SDL Mixer X in your project, you should license it with GPL too!). [Fixed]
 * Wrongly working real-time re-sampling of music files to get fit into united audio stream. For example, musics with sample rate less than sample rate of stream will cause soft breakthroughs of playback. But if musics have a sample rate more than sample rate of stream will cause noisy playback. (for example, musics with 32000 Hz will be played with breakthroughs in the 44100 Hz stream, but in the same stream musics with 48000 Hz will be played noisy and buggy). To escape this issue you should re-sample your music file manually to get correct playback in the defined sample rate of stream. [Fixed]

Links

 * SDL Mixer X documentation, based on original SDL_mixer documentation
 * Official documentation of original SDL Mixer library API
 * Source code of a forked SDL Mixer version by Wohlstand (SDL Mixer X) (Building with CMake).