libADLMIDI

libADLMIDI is a free Software MIDI synthesizer library with OPL3 emulation

Original ADLMIDI code: Copyright (c) 2010-2014 Joel Yliluoma bisqwit@iki.fi

ADLMIDI Library API: Copyright (c) 2015-2026 Vitaly Novichkov admin@wohlnet.ru

Library is based on the ADLMIDI, a MIDI player for Linux and Windows with OPL3 emulation:

https://bisqwit.iki.fi/source/adlmidi.html

• Semaphore-CI:
• AppVeyor CI:
• GitHub Actions:

Differences with original tool

• Reverb code has been removed.
• Doesn't contains platform specific code. Library can be used with various purposes include making of a custom music decoders for a media players and usage with a games.
• Supports custom non-hardcoded WOPL banks and ability to build without of embedded banks

Tested on platforms

• Linux GCC 4.8, 4.9, 5.4 / CLang
• Mac OS X CLang (Xcode 7.x)
• Windows MinGW 4.9.x, 5.2
• Android NDK 12b/13
• DJGPP GCC 7.2 cross compiler from Linux to MS-DOS 32-bit
• OpenBSD
• Haiku
• Emscripten

Key features

• OPL3 emulation with four-operator mode support
• FM patches from a number of known PC games, copied from files typical to AIL = Miles Sound System / DMX / HMI = Human Machine Interfaces / Creative IBK.
• Stereo sound
• Number of simulated OPL3 chips can be specified as 1-100 (maximum channels 1800!)
• Pan (binary panning, i.e. left/right side on/off)
• Pitch-bender with adjustable range
• Vibrato that responds to RPN/NRPN parameters
• Sustain (a.k.a. Pedal hold) and Sostenuto enable/disable
• MIDI and RMI file support
• Real-Time MIDI API support
• loopStart / loopEnd tag support (Final Fantasy VII)
• 111-th controller based loop start (RPG-Maker)
• Use automatic arpeggio with chords to relieve channel pressure
• Support for multiple concurrent MIDI synthesizers (per-track device/port select FF 09 message), can be used to overcome 16 channel limit
• Support for playing Id-software Music File format (IMF)
• Support for custom banks of WOPL format
• Partial support for GS and XG standards (having more instruments than in one 128:128 GM set and ability to use multiple channels for percussion purposes, and a support for some GS/XG exclusive controllers)
• CC74 "Brightness" affects a modulator scale (to simulate frequency cut-off on WT synths)
• Portamento support (CC5, CC37, and CC65)
• SysEx support that supports some generic, GS, and XG features
• Full-panning stereo option (works for emulators only)

How to build

To build libADLMIDI you need to use CMake:

mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make
sudo make install

Notes

• To compile for DOS via DJGPP on Linux, use cmake/djgpp/djgpp-cmake.sh script which a wrapper over CMake to pass DJGPP's stuff required for build

License

The library is licensed under in it's parts LGPL 2.1+, GPL v2+, GPL v3+, and MIT.

• Nuked OPL3 emulators are licensed under LGPL v2.1+.
• DosBox OPL3 emulator is licensed under GPL v2+.
• Chip interfaces are licensed under LGPL v2.1+.
• File Reader class and MIDI Sequencer is licensed under MIT.
• WOPL reader and writer module is licensed under MIT.
• Other parts of library are licensed under GPLv3+.

Available CMake options

Library options

• CMAKE_INSTALL_PREFIX - destination directory where libADLMIDI will be installed. On Linux it is /usr/local/ by default.

• CMAKE_BUILD_TYPE - Build types: Debug or Release. Also MinSizeRel or RelWithDebInfo.

• libADLMIDI_STATIC - (ON/OFF, default ON) Build static library

• libADLMIDI_SHARED - (ON/OFF, default OFF) Build shared library

• WITH_UNIT_TESTS - (ON/OFF, default OFF) Enable unit testing

• WITH_MIDI_SEQUENCER - (ON/OFF, default ON) Build with embedded MIDI sequencer. Disable this if you want use library in real-time MIDI drivers or plugins.)

• WITH_EMBEDDED_BANKS - (ON/OFF, default ON) Enable or disable embedded banks (Original ADLMIDI and older versions of libADLMIDI are had embedded-only banks with no ability to load custom banks in runtime).

• WITH_HQ_RESAMPLER - (ON/OFF, default OFF) Build with support for high quality resampling (requires zita-resampler to be installed)

• WITH_MUS_SUPPORT - (ON/OFF, default ON) Build with support for DMX MUS files)

• WITH_XMI_SUPPORT - (ON/OFF, default ON) Build with support for AIL XMI files)

• USE_DOSBOX_EMULATOR - (ON/OFF, default ON) Enable support for DosBox 0.74 emulator. (Well-accurate and fast)

• USE_NUKED_EMULATOR - (ON/OFF, default ON) Enable support for Nuked OPL3 emulator. (Very-accurate, needs more CPU power)

• USE_OPAL_EMULATOR - (ON/OFF, default ON) Enable support for Opal emulator by Reality (Taken from RAD v2 release package). (Inaccurate)

• USE_JAVA_EMULATOR - (ON/OFF, default ON) Enable support for JavaOPL emulator (Taken from GZDoom). (Semi-accurate)

Utils and extras

• WITH_GENADLDATA - (ON/OFF, default OFF) Build and execute the utility which will rebuild the embedded banks database (which is an adldata.cpp file).

• WITH_GENADLDATA_COMMENTS - (ON/OFF, default OFF) Enable comments in generated ADLDATA cache file

• GENADLDATA_CUSTOM_BANKLIST - (Path) Set the absolute path to the custom INI file that declares a list of embedded banks. If not specified, the banks.ini at the repository root will be used.

• WITH_MIDIPLAY - (ON/OFF, default OFF) Build demo MIDI player (Requires SDL2 and also pthread on Windows with MinGW)

• MIDIPLAY_WAVE_ONLY - (ON/OFF, default OFF) Build Demo MIDI player without support of real time playing. It will output into WAV only.

• WITH_ADLMIDI2 - (ON/OFF, default OFF) Build Classic ADLMIDI MIDI player (Requires SDL2 on Linux and macOS, requires pthread on Windows with MinGW, SDL doesn't required on Windows).

• WITH_VLC_PLUGIN - (ON/OFF, default OFF) Compile VLC plugin. For now, works on Linux and VLC. Support for other platforms comming soon!

• WITH_WINMMDRV - (ON/OFF, default OFF) (Windows platform only) Compile the WinMM MIDI driver to use libOPNMIDI as a system MIDI device.

  • WITH_WINMMDRV_PTHREADS - (ON/OFF, default ON) Link libwinpthreads statically (when using pthread-based builds).
  • WITH_WINMMDRV_MINGWEX - (ON/OFF, default OFF) Link libmingwex statically (when using vanilla MinGW builds). Useful for targetting to pre-XP Windows versions.

• WITH_OLD_UTILS - (ON/OFF, default OFF) Build old utilities to dump some bank formats, made by original creator of ADLMIDI

• EXAMPLE_SDL2_AUDIO - (ON/OFF, default OFF) Build also a simple SDL2 demo MIDI player

You also can build library manually:

You need to make in the any IDE a library project and put into it next files (or include those files into subfolder of your exist project instead if you want to use it statically):

Useful macros

• BWMIDI_DISABLE_XMI_SUPPORT - Disables XMI to MIDI converter
• BWMIDI_DISABLE_MUS_SUPPORT - Disables MUS to MIDI converter
• ADLMIDI_DISABLE_MIDI_SEQUENCER - Completely disables built-in MIDI sequencer.
• ADLMIDI_DISABLE_DOSBOX_EMULATOR - Disables DosBox 0.74 OPL3 emulator.
• ADLMIDI_DISABLE_NUKED_EMULATOR - Disables Nuked OPL3 emulator.
• ADLMIDI_DISABLE_JAVA_EMULATOR - Disable JavaOPL3 emulator.
• ADLMIDI_DISABLE_OPAL_EMULATOR - Disable Opal OPL3-only emulator.
• ADLMIDI_DISABLE_ESFMU_EMULATOR - Disable ESFMu ESFM/OPL3 emulator.
• ENABLE_HW_OPL_SERIAL_PORT and ADLMIDI_ENABLE_HW_SERIAL - Enable support of the Serial Port support for hardware OPL3 chip interfaces.
• DISABLE_EMBEDDED_BANKS - Disables usage of embedded banks. Use it to use custom-only banks.
• ADLMIDI_ENABLE_HQ_RESAMPLER - Enable high-quality resampler (requires zipa-resampler external dependency).

Public header (include)

• adlmidi.h - Library Public API header, use it to control library

Internal code (src)

• chips/* - Various OPL3 chip emulators and commonized interface over them

• wopl/* - WOPL bank format library

• adldata.hh - bank structures definition

• adldata_db.h - Embedded banks database structures and containers definitions

• adlmidi_private.hpp - header of internal private APIs

• adlmidi_bankmap.h - MIDI bank hash table

• adlmidi_bankmap.tcc - MIDI bank hash table (Implementation)

• adlmidi_cvt.hpp - Instrument conversion template

• adlmidi_ptr.hpp - Custom implementations of smart pointers for C++98

• file_reader.hpp - Generic file and memory reader

• adldata.cpp - Automatically generated database of FM banks from "fm_banks" directory via "gen_adldata" tool. Don't build it if you defined the DISABLE_EMBEDDED_BANKS macro!

• adlmidi.cpp - code of library

• adlmidi_load.cpp - Source of file loading and parsing processing

• adlmidi_midiplay.cpp - MIDI event sequencer

• adlmidi_opl3.cpp - OPL3 chips manager

• adlmidi_private.cpp - some internal functions sources

MIDI Sequencer

To remove MIDI Sequencer, define ADLMIDI_DISABLE_MIDI_SEQUENCER macro and remove all those files

• adlmidi_sequencer.cpp - MIDI Sequencer related source
• cvt_mus2mid.hpp - MUS2MID conv