README.md

July 27, 2026 ยท View on GitHub

WildMIDI is a simple software midi player which has a core softsynth library that can be used in other applications.

The WildMIDI library converts MIDI files into audio which is then passed back to the calling application. Instruments can come from Gravis Ultrasound patch files, SoundFont2 (SF2) files, GENMIDI (OP2) FM banks, or the built-in OPL3 FM synthesizer. The library API is designed so that it is easy to include WildMIDI into applications that wish to include MIDI file playback.

Version: 0.5.0 Licenses: GPLv3+ and LGPLv3 Website: https://github.com/Mindwerks/wildmidi

PLATFORMS:

  • Linux: Arch, Debian, Fedora, Ubuntu, etc (player: ALSA, OSS, or optionally OpenAL output.)
  • Windows: x86 and x64
  • macOS: x86, x64, and powerpc (player: CoreAudio output.)
  • FreeBSD, Debian kFreeBSD (player: OSS output)
  • OpenBSD (player: sndio output)
  • NetBSD (player: netbsd output)
  • GNU/Hurd (Debian)
  • DOS (player: sound blaster or compatibles output)
  • OS/2 (player: DART output.)
  • AmigaOS & variants like MorphOS, AROS (player: AHI output)

BUILD FROM SOURCE:

Requirements:

  • cmake
  • GCC or clang / Xcode / VisualStudio / MinGW or MinGW-w64
  • DOS port: DJGPP / GNU make
  • OS/2 port: OpenWatcom (tested with version 1.9 and newer), or EMX/GCC KLIBC environment (build tested under linux using cross-os2emx toolchain at https://github.com/komh/cross-os2emx)
  • Nintendo 3DS port: devkitARM
  • Nintendo Wii port: devkitPPC
  • Nintendo Switch port: devkitA64
  • PSVita port: Vitasdk

TESTING YOUR CHANGES:

Besides cmake, eight hand-maintained makefiles (amiga/Makefile, amiga/Makefile.vbcc, djgpp/Makefile, macosx/Makefile, mingw/Makefile, os2/makefile.emx, os2/makefile.wat, win32wat/makefile) each keep their own list of objects, so a change that builds fine under cmake can still break them. ci-local.sh runs the GitHub CI jobs locally to catch that before you push:

./ci-local.sh --docker              compile jobs, in a container
./ci-local.sh --all                 those plus the BSD VMs
./ci-local.sh --docker native       run only named jobs
./ci-local.sh --list                show all job names

The first run builds a ~5GB image from .ci/Dockerfile with every toolchain the workflows use, then caches it. Exits 0 on success, 1 on failure with the failing job and a log tail; full logs in .ci-local/. Without --docker it uses whatever is installed on the host and reports the rest as SKIP.

--qemu (implied by --all) additionally boots FreeBSD, OpenBSD and NetBSD under qemu/kvm, the same way the bsd.yml workflow does, all three at once. It needs qemu, mtools, rsync, sfdisk, OVMF firmware (for OpenBSD) and access to /dev/kvm, which is why it is opt-in. The first run per OS installs cmake in the guest and saves the result, so later runs take about half a minute for all three; pass --refresh to .ci/bsd-vm.sh to rebuild those cached images.

This does not replace CI: the macOS and Windows jobs need runners a Linux host cannot provide.

CHANGELOG

0.5.1 (unreleased)

  • Support for playing and converting Yamaha SMAF (.mmf) ringtone files: the HandyPhone (MA-1/MA-2) and Mobile Standard (MA-3/MA-5) score formats. The MA-7 "SEQU" also supported.
  • Yamaha MA-series FM synthesis for SMAF: a file carrying a custom FM voice bank plays with its own instruments and embedded ADPCM percussion instead of a General MIDI approximation. WANT_MAFM=ON; see docs/SMAF_FM.md.
  • Modulation wheel (CC 1) support, previously parsed but discarded: GUS patches gain a 5Hz vibrato LFO, while SF2 voices and the MA FM synth route the wheel to their vibrato LFO depth (bug #143.)
  • Player: playlist support. A filename given to the player may now be a directory, which is searched recursively for files to play (bug #215.)
  • Player: new -S/--shuffle switch plays the files in random order.
  • Player: new -L/--loop switch repeats playback at the end. With a single file the file itself is looped at end-of-track; with several files, or a directory, the whole playlist is repeated instead, reshuffling each pass when combined with -S.
  • Added ci-local.sh to run the GitHub CI jobs locally before pushing, including the BSD builds under qemu.

0.5.0 (2026-07-24)

  • SoundFont2 (SF2) rendering support via TinySoundFont. Enabled by default, cmake configuration: WANT_SF2=ON. Pass either an .sf2 file, or a config file with a soundfont directive to WildMidi_Init().
  • Built-in OPL3 FM softsynth using the Nuked OPL3 emulator. Pass @opl3 to WildMidi_Init(), or use the player's -O/--opl3 switch to play MIDI files without any patch, soundfont, or bank files. The GM voice bank is embedded in the library.
  • GENMIDI (OP2) FM bank support: an .op2 bank, such as the one shipped with Doom, can be given to WildMidi_Init() in place of a config file, and is rendered through the OPL3 emulator.
  • HMP and HMI to MIDI converters: WildMidi_ConvertToMidi() and the player's -x/--tomidi switch now convert HMP and HMI files in addition to XMI and MUS (bug #181).
  • Support for playing and converting compressed ("mangled") HMP files as shipped by Gremlin Interactive games such as Fatal Racing / Whiplash.
  • Fix XMI looping / wrong duration issues (bug #149.)
  • Fix GUS patch handling to obey scale frequency and scale factor (bug #264.)
  • Find and use a GUS patch with neareset patchid in case of missing patches: 349_Jesu_meiner_Freuden_Freude.mid, for e.g., now plays well with alternative patches instead of producing silence. (thanks to Yotam Medini, PR #254)
  • Discard extraneous end-of-track events in Type 1 MIDI files: Fixes certain midis from Rise of the Triad looping too soon. (thanks to Clownacy, PR #263)
  • Fix infinite loop when looping empty channels. (thanks to Clownacy, PR #263)
  • Fix certain notes ending too soon and excessive echo/reverb/sustain issues (bugs #229 and #230.)
  • Fix certain midis having breaks (bug #158.)
  • Support spaces in config files using quoted strings.
  • Hardened event-pool and mix-buffer growth against realloc failure across the Linear/Gauss/SF2 renderers; the event-setup helpers now propagate allocation errors instead of writing past the buffer.
  • Fix a possible double-free on library shutdown.
  • Fix player WAV writer not closing its output properly (0.4.6 bug)
  • Security hardening across the file parsers.
  • Assorted overflow guards.
  • Added Zig bindings (thanks to Simon Hartcher, PR #260)
  • Cmake build system fixes, other minor fixes/clean-ups.
  • The library is API/ABI compatible with 0.4.x versions.

0.4.6 (2024-04-11)

  • A lot of player cleanup and refactoring, thanks to initial work by Azamat H. Hackimov, with addition of several safeguards and minor fixes.
  • Ability to choose which audio output backends to include in the build system: see the cmake script for the relevant WANT_??? options. Player's --help command line switch lists the available backends. Thanks to initial work by Azamat H. Hackimov.
  • New native audio output backends for player: coreaudio for macOS, sndio for OpenBSD, and netbsd (sunaudio) for NetBSD.
  • Improved pkg-config file generation in cmake script (bug #236).
  • Workaround a link failure on AmigaOS4 with newer SDKs (bug #241).
  • Other minor source clean-ups.
  • CMake project clean-ups. Cmake v3.4 or newer is now required.

0.4.5 (2023-01-14)

  • Fixed MUS drum channels 9 and 15 being swapped if the same file is played twice from the same memory buffer (bug #234).
  • Player: Fixed save MIDI reading wrong argv if there are no path seperators (bug #227).
  • Other code and build system clean-ups.

0.4.4 (2021-03-21)

  • Fixed integer overflow in MIDI parser sample count calculation (bug #200).
  • Fixed 8-bit ping pong GUS patch loaders (bug #207).
  • Fixed wrong variable use in reverb code (bug #210).
  • Reset block status of tty after playback (bug #211).
  • Fixed broken file name handling for 'save as midi' command during playback.
  • Clamp MUS volume commands (PR #226).
  • CMake project improvements (bugs: #214, #216, #217, #218); cmake version 3.1 or newer is now required.

0.4.3 (2018-11-24)

  • New API addition: WildMidi_InitVIO(). It is like WildMidi_Init(), but tells the library to use caller-provided functions for file IO. See wildmidi_lib.h or the man page WildMidi_InitVIO(3) for details. This was suggested and implemented by Christian Breitwieser.
  • Fixed Visual Studio optimized builds (bug #192, function ptr issue.)
  • Fixed a thinko in one of the buffer size checks added in v0.4.2.
  • Fixed possible out of bounds reads in sysex commands (bug #190).
  • Fixed invalid reads during config parse with short patch file names.
  • Do not treat a missing end-of-track marker as an error for type-0 MIDI files (bug #183).
  • Fixed bad reading of high delta values in XMI converter (bug #199).
  • Fixed a memory leak when freeing a midi (bug #204).
  • Fixed slurred/echoy playback at quick tempos on looped instruments (bug #185).
  • Fixed certain MIDIs sounding different compared to timidity, as if instruments not turned off (bug #186).
  • Fixed compilation on systems without libm.
  • Support for RISC OS, Nintendo Switch, and PS Vita.
  • Several clean-ups.

0.4.2 (2017-11-20)

  • Fixed CVE-2017-11661, CVE-2017-11662, CVE-2017-11663, CVE-2017-11664 (bug #175).
  • Fixed CVE-2017-1000418 (bug #178).
  • Fixed a buffer overflow during playback with malformed MIDI files (bug #180).
  • GUS patch processing changes to meet users expectations (bug #132).
  • Worked around a build failure with newer FreeBSD versions failing to retrieve the ONLCR constant (bug #171).
  • Fixed a minor Windows unicode issue (PR #170).
  • A few other fixes / clean-ups.

0.4.1 (2017-03-17)

  • Fixed bug in handling of the "source" directive in config files.
  • Fixed a nasty bug in dBm_pan_volume. Other fixes and clean-ups.
  • Build system updates. Install a pkg-config file on supported platforms such as Linux. New android ndk makefile.
  • File I/O updates.
  • Support for OS/2.
  • Support for Nintendo 3DS.
  • Support for Nintendo Wii.
  • Support for AmigaOS and its variants like MorphOS and AROS.

0.4.0 (2016-06-16)

  • API change: The library now returns audio data in host-endian format, not little-endian.
  • API change: WildMidi_GetVersion() added to the API, along with new numeric version macros in the wildmidi_lib.h header. the dso version is changed from 1 to 2.
  • API change: All long or unsigned long type _WM_Info fields changed into strictly 32-bit fields (int32_t or uint32_t.)
  • API change: WildMidi_OpenBuffer() and WildMidi_GetOutput() changed to accept strictly 32-bit size parameters, i.e. uint32_t, instead of unsigned long.
  • API change: WildMidi_ConvertToMidi() and WildMidi_ConvertBufferToMidi() added for MIDI-like files to be converted to MIDI.
  • API change: WildMidi_SetCvtOption() added to support conversion options.
  • API change: WildMidi_SongSeek() added to support Type 2 MIDI files.
  • API change: WildMidi_GetLyric() added to support embedded text, such as KAR files.
  • API change: WildMidi_GetError() and WildMidi_ClearError() added to cleanly check for, retrieve, and clear error messages. They no longer go to stderr.
  • Support for loading XMI (XMIDI format) and XFM files, such as from Arena. Thanks Ryan Nunn for releasing his code under the LGPL.
  • Support for loading MUS (MUS Id format) files, such as from Doom.
  • Support for loading HMP/HMI files, such as from Daggerfall.
  • Support for loading KAR (MIDI with Lyrics) and Type 2 MIDI files.
  • Build requires cmake-2.8.11 or newer now.

0.3.9 (2016-03-11)

  • Library: Fixed a segmentation fault with bad MIDI files.

0.3.8 (2015-01-27)

  • Library: Fixed a seek-to-0 bug in order to cure an issue of truncated start (bug #100, gnome/gstreamer bug #694811.)
  • Player, OpenAL: Reduced buffers from 8 to 4 so as to cure some output delay issues (bug #85.)

0.3.7 (2014-06-05)

  • Plug a memory leak in case of broken MIDIs.
  • Properly reset global state upon library shutdown.
  • Support for type-2 MIDI files.
  • Fix a possible crash in WildMidi_SetOption.
  • DOS port: Support for Sound Blaster output in player.
  • Uglify the library's private global variable and function names.
  • Build: Add option for a statically linked player.
  • Build: Add headers to project files. Use -fno-common flag.
  • Other small fixes/clean-ups.

0.3.6 (2014-04-05)

  • Fix some portability issues.
  • Fix a double-free issue during library shutdown when several midis were alive.
  • Fix the invalid option checking in WildMidi_Init().
  • Fix the roundtempo option which had been broken since its invention in 0.2.3.5 (WM_MO_ROUNDTEMPO: was 0xA000 instead of 0x2000.)
  • Fix cfg files without a newline at the end weren't parsed correctly.
  • Handle cfg files with Mac line-endings.
  • Refuse loading suspiciously long files.

0.3.5 (2014-03-18)

  • Greatly reduced the heap usage (was a regression introduced in 0.2.3)
  • OpenAL support: Fixed audio output on big-endian systems. Fixed audio skips at song start.
  • OSS support: No longer uses mmap mode for better compatibility. This gains us NetBSD and OpenBSD support.
  • Worked around an invalid memory read found by valgrind when playing Beethoven's Fur Elise.rmi at 44100 Hz using the old MIDIA patch-set from 1994.
  • Build fixes for MSVC. Revised visibility attributes usage.

0.3.4 (2014-02-24)

  • OpenAL support: This gains us OSX and other platforms that OpenAL supports for sound output!
  • DOS (DJGPP) support: This goes a long way to helping other DOS based applications.
  • MinGW support: This gains us win32 and win64 support using this toolchain.
  • OSS fixes.
  • Add missing parts of the absolute paths fix in config parsing.
  • New portable file and path-name system to handle cross-platform support.
  • Support for Debian/kFreeBSD, Debian/Hurd, and other Debian archs.
  • Many bug fixes, code clean-ups, and cosmetic fixes.

0.3.3 (2014-02-11)

  • Default to hidden visibility and only export our API functions
  • Windows lean and mean to help compile times on Windows
  • CLI and XCode work now on OSX
  • Better FreeBSD support
  • Supported platforms are Debian, FreeBSD, Windows, and OSX (but only for WAV output)

0.3.1 - 0.3.2

  • Cmake updates/fixes/cleanups.

0.3.0

  • Initial CMake support.
  • Process non-registered params. Fix issue of notes ending before attack envelope completed. (sf.net svn r149/r151.)