Portable software MIDI output with SF2 soundfonts using the open source [[http://sourceforge.net/apps/trac/fluidsynth/|FluidSynth]].

The FluidSynth audio plugin implements a Doomsday Music interface that synthesizes MIDI music into a raw PCM samples using libfluidsynth. However, because the PCM data's length is not known beforehand, it needs to be played in streaming mode.


====== How to use {{veradd|1.9.9}} ======



===== Enabling audio_fluidsynth =====


  *  On Mac OS X (10.6+ package), FluidSynth is automatically loaded when using FMOD as the audio plugin. 

  *  On Linux, FluidSynth uses one of its own audio drivers to play music ("pulseaudio" by default). The default driver can be [[configuration#Unix_system-level_config_files|configured]]. {{veradd|1.9.10}}

  *  FluidSynth is //not// available on Windows at the moment.

To verify that the plugin is in use, look for the "Audio configuration" printed in [[doomsday.out]]. It should contain a mention of FluidSynth being used as a Music interface. The command-line option
  -imusic fluidsynth
forces the engine to use FluidSynth for music playback.


===== Loading an SF2 soundfont =====


You must set the cvar [[music-soundfont]] to the full path of an SF2 soundfont file.
The first time you set the cvar, it takes until the start of the next song for the SF2 to be taken into use, i.e., it won't happen immediately.


===== Changing/unloading the SF2 soundfont =====


If a MUS/MIDI song is already playing with an SF2 soundfont, changing the value of [[music-soundfont]] will immediately have an effect and the MIDI music continues to play using the new soundfont.

If a MUS/MIDI song is playing with an SF2 soundfont and you clear [[music-soundfont]] or change it to a .DLS file, the current music will stop and when the next song starts, it will play through another music interface (if available; e.g., FMOD with .DLS).


====== Technical notes ======


The FluidSynth plugin supports Mac OS X and Linux, but not Windows (needs [[http://www.linuxfromscratch.org/blfs/view/cvs/general/glib2.html|GLib 2]] library).

A streaming sample is similar to standard samples (''sfxsample_t'') with the exception that instead of having a direct pointer to the sample data, it has a callback function through which the sample data is returned on demand. The existing audio drivers need to be modified to support streaming samples.

For distribution packaging, GLib and its dependencies must be included as shared libraries/dependencies.


===== Build configuration =====


The plugin can be compiled in one of two ways:
  *  System-wide libfluidsynth on UNIX. The plugin will output audio on its own (assuming the system-wide libfluidsynth has been compiled with a suitable output driver).
  *  Embedded FluidSynth synthesizer that outputs PCM sample data using Doomsday's main SFX interface. In this mode, FluidSynth does not have audio output capabilities of its own.((This is mostly due to minimizing duplicate functionality: the existing audio plugins are fully capable of handling PCM output. It would be possible for [[audio_fluidsynth]] to output the audio on its own, but that would mean additional external dependencies and platform-specific compilation setup.))

  *  qmake <code>CONFIG</code> option ''deng_fluidsynth'' determines whether [[audio_fluidsynth]] is built is not enabled by default.


==== libfluidsynth mode ====

  *  uses the libfluidsynth present on the system
  *  outputs audio on its own; music volume controls the FluidSynth synthesizer gain

==== Embedded mode ====

  *  supports FMOD as the audio playback target
  *  needs streaming samples; music volume controls the stream sample's volume
  *  ''deng_embedfluidsynth'' build option not enabled by default


====== Notes ======


<references/>


====== See also ======


  *  Project using FluidSynth: http://www.doomworld.com/v​b/source-ports/55307-modif​ied-prboom-for-producing-v​ideos/