SDL Mixer X

From Moondust Wiki
Jump to navigation Jump to search

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 Moondust 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-1/2/2.5 Layer 3, Lossy data compressed audio (dr_mp3, libMPG123).
  • OGG — OGG Vorbis, Lossy data compressed audio (libOGG, libVorbis, stb-vorbis), has loop support (by LOOPSTART/LOOPEND/LOOPLENGTH meta tags, also LOOP_START and LOOP_END).
  • OPUS — OPUS, Lossy data compressed audio (libOpus) (Support was added Since June 18, 2018), has loop support (by LOOPSTART/LOOPEND/LOOPLENGTH meta tags, also LOOP_START and LOOP_END).
  • FLAC — Free Lossless Audio Codec, Loss-less compressed (libFLAC, dr_flac), has loop support (by LOOPSTART/LOOPEND/LOOPLENGTH meta tags, also LOOP_START and LOOP_END (Support for FLAC loop was added Since November 17, 2019)).
  • MIDI — Music Instrument Digital Interface, commands list (libADLMIDI, libOPNMIDI, Timidity (hardcoded), Fluidsynth (FluidLite; Since March 29, 2021) ), has loop support (by loopStart/loopEnd markers and by CC111 like RPG Maker)

Extra music formats

Anything except Timidity and Non-Windows®Native MIDI

  • XMI — MIDI-like format used in AIL library and was widely used in many DOS games. 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.

ADLMIDI only

  • CMF — Creative Music Format, A MIDI file mixed with OPL2 FM instruments, widely used in many DOS games.
  • IMF — Id-Software Music File. Supported IMF-files which have length chunk in begin and uses 700Hz of the ticks rate.
Notice Tip: If your IMF-files are playing with the wrong tempo or rejecting as invalid files, you have to use this utility to convert frequency and automatically add length chunk into file begin

Game music emulators formats

All Game Music Emulators formats are provided with GME library.

Notice Tip: If you are looking for any existing chiptune musics, try to visit Zophar's archive (Not available in China) where you can find lots of chiptune songs from various games of all times.

Note that you should get ORIGINAL MUSIC FILES are actual chiptune files that will give you smaller file size and pure sounding quality.

  • 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/32X (PWM channel is not supported), BBC Micro

Tracker music formats

All tracker music formats are provided with libXMP and libOpenMPT libraries.

Common Tracker Formats

  • IT — Impulse Tracker
  • MOD — 15 and 31 instruments, ProTracker, Amiga Computer
  • S3M — Scream Tracker 3 (Doesn't support OPL Instruments due to libXMP issue)
  • XM — FastTracker 2 / Extended Module

Other Tracker Formats

  • 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
  • IMF — Imago Orpheus (Support has been repaired with using of libXMP since March 10, 2019)
  • LIQ — Liquid Tracker (libXMP)
  • MDL — Digitrakker (libXMP)
  • 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)
  • STM — Scream Tracker
  • STX — Scream Tracker Music Interface Kit
  • SFX — Amiga SoundFX (libXMP)
  • ULT — UltraTracker
  • UNI — MikMod
  • WOW — Mod's Grave (libXMP)

Other Music Formats

  • PTTUNE — PXTONE Music (Since 2023-05-14)
  • PTCOP — PXTONE Collage Music Project (Since 2023-05-14)

Notes

SFX Formats

Notice Note: Since Mixer X 2.0, almost all music formats also can be loaded as an SFX.


SDL Mixer X have a support for playback for next sound effects which can be preloaded into memory played in difference channels with mixing:

  • Almost all formats of music — since SDL Mixer X 2.0, almost any music format also can be used as SFX
  • 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 2nd of February, 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 LOOPLENGTH) 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 the support of additional path arguments in the Mix_LoadMUS function to allow changing of some decoding properties.

Game music emulators formats

The first argument - an 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;e0;c0;

All arguments after the first integer are optional. The leading integer is required, even it's a single-track file. The last argument must be closed with semicolon.

  • t= - Initial tempo factor (1.0 is the 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 the 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 the volume of too silent songs, or decrease the volume of too loud songs.
  • e - Disable the native echo effect of SPC files. 1 - native SPC echo will be disabled, 0 - native SPC echo will be kept working.
  • c - Forbids dynamic change of the "SPC echo disable" flag (makes it being constant). 1 enable constant echo state, 0 disable constant echo state (default).

MIDI

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

Example 1: 

mymusic.mid|s0;b62;t0;v0;m0;t=1.0;g=2.0;x=/path/to/bank1.wopl;

Example 2: 

mymusic.mid|s4;r1;rr0.2;rd0.4;rw0.9;rl0.8;c1;cn10;cl4.2;cs3.5;p256;t=1.0;g=1.0;x=/path/to/bank1.sf2&/path/to/bank2.sf2&/path/to/bank3.sf2;

All arguments are optional. The last argument must be closed with a semicolon.

  • s - Synthesizer type:
    • 0 - ADLMIDI, emulated OPL3 (YMF262) synthesizer with loop tags and System Exclusive Messages support. Working by Default. (Recorded examples to listen to are presented here). OPL3 chip was widely used on PC sound cards in 80/90'th years.
    • 1 - Native MIDI, uses the default operating system MIDI interface. Don't use it on Windows (MSGS only) due to Microsoft side bug that may mute sound of entire app (details below).**
    • 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 and System Exclusive Messages support. OPN2 chip is used on the Sega MegaDrive / Genesis game console. This synthesizer has been added since May 14, 2017.
    • 4 - FluidSynth (FluidLite), the WaveTable MIDI synthesizer with SoundFont banks support, has the support for loop tags support. This synthesizer has been added since March 29, 2021.
Notice Important note: ** Note for Native MIDI: Pausing is not works with Native MIDI on Windows [Fixed]. Fade-IN/OUT and volume manipulation on Windows with the "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 Canvas, 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).
Notice Note: *** Note for Timidity: If you wish it works, you must have one of the banks in GUS format which you can take here or in any other place around the Internet.

General flags

  • t= - (ADLMIDI, OPNMIDI, and FluidSynth) Initial tempo factor (1.0 is the 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 it with `t0` and `t1` which are different.
  • g= - (ADLMIDI, OPNMIDI and FluidSynth) Gain factor (2.0 is the 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 the volume of too silent songs, or decrease the volume of too loud songs.

ADLMIDI and OPNMIDI

  • b - (ADLMIDI) Set bank ID (look for available banks list in Moondust Music Player application to preview them). The default is 58.
  • t - (ADLMIDI) Deep tremolo (1 or 0), increase the amplitude of the tremolo effect for instruments that are using the tremolo OPL flag. Default 1. Don't be confused with `t=` which is different.
  • v - (ADLMIDI) Deep vibrato (1 or 0), increase the amplitude of the vibrato effect for instruments that are using the vibrato OPL flag. Default 1.
  • m - (ADLMIDI) Enables scalable modulation (1 or 0), Allows dynamic scaling of the modulator result with volume. Default 0.
  • j - (ADLMIDI and OPNMIDI) Enables automatical arpeggio (1 or 0), Allows to squash chords into arpeggio when not enough free polyphony channels are left. When disabled, the oldest note gets replaced with the newest. Default 1 (since 2022-07-22, Default 0). Supported since 2021-10-25.
  • o - (ADLMIDI and OPNMIDI) Changes the channel allocation algorithm (-1 - auto, 0 - sounding delay based, 1 - any released channel with the same instrument, 2 - any released channel). Supported since 2022-07-22.
  • 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 all chip emulators (6 channels maximum per every chip. For example, you have used 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 quotes, for example, `x=/path/to/bank/file.wopn;`

Obsolete

  • a - (ADLMIDI) In previous versions it had to enable the enforced OPL2's rhythm mode percussion (1 or 0). This is a workaround for some embedded banks. Functionless since the libADLMIDI version 1.5.0 (released on 28th of September, 2020), as now the selected bank defines the work of rhythm mode per every percussion instrument instead of user.

FluidSynth (Since March 29, 2021)

Notice Tip: Depending on the SoundFonts, the song may get too loud and clipped. You can fix it by specifying the lower gaining factor, for example g=0.25;. You may tune the value as you want until you will get the approvable sounding.
  • r - (FluidSynth) Enable or disable the reverb effect: 0 - disabled, 1 - enabled
  • rr - (FluidSynth) Reverb room size value (0.0-1.0)
  • rd - (FluidSynth) Reverb damping value (0.0-1.0)
  • rw - (FluidSynth) Reverb width value (0.0-100.0)
  • rl - (FluidSynth) Reverb level value (0.0-1.0)
  • c - (FluidSynth) Enable or disable the chorus effect: 0 - disabled, 1 - enabled
  • cn - (FluidSynth) Chorus voice count (0-99, CPU time consumption proportional to this value)
  • cl - (FluidSynth) Chorus level (0.0-10.0)
  • cs - (FluidSynth) Chorus speed in Hz (0.1-5.0)
  • cd - (FluidSynth) Chorus depth (max value depends on synth sample-rate, 0.0-21.0 is safe for sample-rate values up to 96KHz)
  • ct - (FluidSynth) Chorus waveform type: 0 - Sine, 1 - Triangle
  • p - (FluidSynth) Define the allowed polyphony (8-512)
  • x= - (FluidSynth) Load custom SoundFont files by absolute path. Accepting strings without quotes, for example, x=/path/to/bank/file.sf2;. You can specify multiple SoundFont files by using an ampersand separator: x=/p/file1.sf2&/p/file2.sf2&/p/filen.sf2;

Preview examples of difference between ADLMIDI flags

Deep Tremolo Deep Vibrato Scalable Modulation

DISABLED

DISABLED

DISABLED

ENABLED

ENABLED

ENABLED

Notice Note: For ADLMIDI and OPNMIDI with SysEx, and for Fluidsynth, Setting Bank MSB1 LSB0 in a track in a midi file, will be rhythm track.


OGG Vorbis

Available since the 2th of June 2023. This functionality right now is avilable when the library was built with using of stb_vorbis library. 

mymusic.ogg|m1;c2;r1;s=1.0;

All arguments after the first integer are optional. The leading integer is required, even it's a single-track file. The last argument must be closed with semicolon.

  • m - Enable the multi-track mode: turn multi-channel song into multi-track stream with an ability to mute each separated "track". 0 - disabled, 1 - enabled.
  • c - Number of channels for each track. (Max is 8 due to SDL AudioStream)
  • r - Total number of available tracks.
  • s= - Initial speed factor (1.0 is the default value, accepting positive floating-point number values, for example, `s=1.75;`), increase or decrease the initial speed of the song (i.e. both tempo and pitch gets changed).
Notice Note: OGG Vorbis files do allow storing of multiple channels (up to 255). Typically these channels being used to store the Stereo or Surround streams. However, it's possible to store even more channels into the Vorbis files, and it's possible to utilise them as tracks rather than as surround channels: when multitrack mode is enabled, the stream will be allocalted with a selected number of channels (in this example, 2 - i.e. stereo). All other channels in the scope of defined tracks number, will be mixed with the output stereo stream. It's possible to mute each "track" on the fly, so, they will not being mixed until unmuting.
Notice Important note: You should not define the number of channels and tracks bigger than OGG file actually contains. The product of channels and tracks number must be smaller than the actual number of channels at your OGG Vorbis file. For example, you have 4 channels at your OGG vorbis file, and you want to make it produce two stereo tracks: you need to specify the number of channels 2 (i.e stereo), and tracks number 2.


Special engine-specific values

Since September 10, 2021, development builds for TheXTech have the support of engine exclusive arguments intended to use the functionality of the engine itself.

  • ym=x; - Set the track (or channel) number (Starts with 0) for the pet mode. That means the selected track/channel of the chiptune, tracker or MIDI song will be muted by default while the player doesn't ride pet. When a player gets pet riding, the selected track gets resumed. Example: ym=5;.

Macros (TheXTech and Moondust Project only)

Since March 31, 2020, development builds for TheXTech, Moondust Editor, and Moondust Engine has the support for the macros in the path arguments. They allow you to specify the relative path to a certain file (such as a WOPL/WOPN bank file, or the SoundFont®, depending on the synthesizer used):

  • {e} - The absolute path to the current episode root.
  • {d} - The absolute path to the current level/world data directory.
  • {r} - The absolute path to the config-pack default music root.

Example: 

mymusic.mid|s0;b62;t0;v0;a0;m0;t=1.0;g=2.0;x={e}bank1.wopl;

Projects using the MixerX library

There are some known projects that use this library. That means, all formats and the rest of MixerX's features supported by this library, will work with those projects in a condition the library is up to date.

  • Moondust Project (formerly known as PGE Project) - the WIP game engine and the development kit for it. The Moondust Devkit is also often combined with other projects while the main engine is still in development.
    • Moondust Engine - The main runtime engine of the Moondust Project, is still in development.
    • Moondust Editor - The level and world map editor. It is part of the Moondust Development Kit.
    • Moondust Music Player - The simple music player for music testing out of the game, for example, to verify the work of loop points or other things. It is part of the Moondust Development Kit.
  • LunaLua-SMBX - The SMBX game modded using the LunaLua hacking library.
    • Super Mario Bros. X2 - is a collaborative, open-source project to improve and expand upon the original SMBX, the successor of the LunaLua-SMBX.
  • Super Mario Bros. X by 38A - is a Mario fan game engine, written by 5438A38A as an unofficial successor to the original Super Mario Bros. X by Redigit.
  • TheXTech - it's a platform game engine written in C++ and is a full port of the source code of SMBX 1.3 which was initially written in Visual Basic 6.

Other projects

  • Sonic Robo Blast 2 - is a 3D open-source Sonic the Hedgehog fangame built using a modified version of the Doom Legacy port of Doom. It has the option to use the original SDL Mixer library and the SDL Mixer X library as well.
  • Super Mario War by 72dpiarmy - is a Super Mario deathmatch game with small maps, lots of creative game modes, and unlimited customization. It has the option to use the original SDL Mixer library and the SDL Mixer X library as well.
  • Space Engine - is an interactive 3D planetarium and astronomy software developed by Russian astronomer and programmer Vladimir Romanyuk. Initially, it used the OpenAL but later had to switch to the SDL Mixer X library due to the complexity and compatibility issues at the OpenAL.

See also

Links

Retrieved from "https://wohlsoft.ru/wiki/index.php?title=SDL_Mixer_X&oldid=9976"