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.)