# FluidSynth 1.0 — Developer Documentation

## Disclaimer

This documentation, in its current version, is probably outdated and most certainly incomplete. As always, the source code is the final reference.

SoundFont(R) is a registered trademark of E-mu Systems, Inc.

## Introduction

FluidSynth can easily be embedded in an application. It has a main header file, fluidsynth.h, and one dynamically linkable library. FluidSynth runs on Linux, MacOS 9, MacOS X, and the Win32 platforms. It has audio and midi drivers for all mentioned platforms but you can use it with your own drivers if your application already handles audio and MIDI input/output. This document explains the basic usage of FluidSynth and provides examples that you can reuse.

## Creating and changing the settings

Before you can use the synthesizer, you have to create a settings object. The settings objects is used by all components of the FluidSynth library. It gives a unified API to set the parameters of the audio drivers, the midi drivers, the synthesizer, andsoforth. A number of default settings are defined by the current implementation. In future versions, the use of the settings will probably be generalized.

All settings have a name that follows the "dotted-name" notation. For example, "synth.polyphony" refers to the number of voices (polyphony) preallocated by the synthesizer. The settings also have a type. There are currently three types: strings, numbers (double floats), and integers. You can change the values of a setting using the `fluid_settings_setstr`, `fluid_settings_setnum`, and `fluid_synth_setint` functions. For example:

    #include <fluidsynth.h>

    int main(int argc, char** argv)
    {
      fluid_settings_t* settings = new_fluid_settings();

      fluid_synth_setint(settings, "synth.polyphony", 128);

      delete_fluid_settings(settings);
      return 0;
    }

The API contains the functions to query the type, the current value, the default value, the range and the "hints" of a setting. The range is the minumum and maximum value of the setting. The hints gives additional information about a setting. For example, whether a string represents a filename. Or whether a number should be interpreted on on a logarithmic scale. Check the API documentation for a description of all functions.

## Creating the synthesizer

To create the synthesizer, you pass it the settings object, as in the following example:

    #include <fluidsynth.h>

    int main(int argc, char** argv)
    {
      fluid_settings_t* settings;
      fluid_synth_t* synth;

      fluid_settings_t* settings = new_fluid_settings();

      synth = new_fluid_synth(settings);

      /* Do useful things here */

      delete_fluid_synth(synth);
      delete_fluid_settings(settings);
      return 0;
    }

The default settings should be fine for most uses. A detailed description of all the settings used by the synthesizer described below.

## Synthesizer settings

synth.gain | Type | number
| Default | 0.2
| Min-Max | 0.0-10.0
| Description | The gain is applied to the final or master output of the synthesizer. It is set to a low value by default to avoid the saturation of the output when random MIDI files are played.
synth.sample-rate | Type | number
| Default | 44100
| Min-Max | 22050-96000
| Description | The sample rate of the audio generated by the synthesizer.
synth.polyphony | Type | integer
| Default | 256
| Min-Max | 16-4096
| Description | The polyphony defines how many voices can be played in parallel. The number of voices is not necessarily equivalent to the number of notes played simultaniously. Indeed, when a note is struck on a specific MIDI channel, the preset on that channel may created several voices, for example, one for the left audio channel and one for the right audio channels. The number of voices activated depends on the number of instrument zones that fall in the correspond to the velocity and key of the played note.
synth.midi-channels | Type | integer
| Default | 16
| Min-Max | 16-256
| Description | This setting defines the number of MIDI channels of the synthesizer. The MIDI standard defines 16 channels, so most hardware keyboards are limited to 16. If you plan to use the synthesizer as a plugin in an application, it might be interesting to set the number of channels to a larger value. In this case you can program a greater number of presets.
synth.reverb.active | Type | string
| Default | "yes"
| Description | When set to "yes" the reverb effects module is activated. Otherwise, no reverb will be added to the output signal. Note that when the reverb module is active, the amount of signal send to the reverb module depends on the "reverb send" generator defined in the SoundFont.
synth.chorus.active | Type | string
| Default | "yes"
| Description | When set to "yes" the chorus effects module is activated. Otherwise, no chorus will be added to the output signal. Note that when the reverb module is active, the amount of signal send to the chorus module depends on the "chorus send" generator defined in the SoundFont.
synth.ladspa.active | Type | string
| Default | "no"
| Description | When set to "yes" the LADSPA subsystem will be called. This subsystem allows to load and interconnect LADSPA plugins. The output of the synthesizer is processed by the LADSPA subsystem. Note that the synthesizer has to be compiled with LADSPA support. More information about the LADSPA subsystem later.
synth.audio-groups | Type | integer
| Default | 1
| Min-Max | 1-128
| Description | By default, the synthesizer outputs a single stereo signal. Using this option, the synthesizer can output multichannel audio.
synth.effects-channels | Type | integer
| Default | 2
| Min-Max | 2-2
| Description |
synth.verbose | Type | string
| Default | "no"
| Description | When set to "yes" the synthesizer will print out information about the received MIDI events to the stdout. This can be helpful for debugging. This setting can not be changed after the synthesizer has started.
synth.dump | Type | string
| Default | "no"
| Description |

## Creating the audio driver

The synthesizer itself does not write any audio to the audio output. This allows application developers to manage the audio output themselves if they wish. The next section describes the use of the synthesizer without an audio driver in more detail.

Creating the audio driver is straightforward: set the appropriate settings and create the driver object. Because the FluidSynth has support for several audio systems, you may want to change which one you want to use. The list below shows theaudio systems that are currently supported. It displays the name, as used by the fluidsynth library, and a description.

- alsa: Advanced Linux Sound Architecture

- oss: Open Sound System (Linux)

- jack: JACK Audio Connection Kit (Linux, Mac OS X)

- portaudio: Portaudio Library (MacOS 9 & X, Windows, Linux)

- sndmgr: Apple SoundManager (Mac OS Classic)

- coreaudio: Apple CoreAudio (MacOS X, experimental)

- dsound: Microsoft DirectSound (Windows)

The default audio driver depends on the settings with which FluidSynth was compiled. You can get the default driver with fluid_settings_getstr_default(settings, "audio.driver"). To get the list of available drivers use the `fluid_settings_foreach_option` function. Finally, you can set the driver with `fluid_settings_setstr`. In most cases, the default driver should work out of the box.

Additional options that define the audio quality and latency are "audio.sample-format", "audio.period-size", and "audio.periods". The details are described later.

You create the audio driver with the `new_fluid_audio_driver` function. This function takes the settings and synthesizer object as arguments. For example:

    void init()
    {
      fluid_settings_t* settings;
      fluid_synth_t* synth;
      fluid_audio_driver_t* adriver;

      settings = new_fluid_settings();

      /* Set the synthesizer settings, if necessary */

      synth = new_fluid_synth(settings);

      fluid_settings_setstr(settings, "audio.driver", "jack");
      adriver = new_fluid_audio_driver(settings, synth);
    }

As soon as the audio driver is created, it will start playing. The audio driver creates a separate thread that runs in real-time mode (is the application has sufficient privileges) and call the synthesizer object to generate the audio.

There are a number of general audio driver settings. The audio.driver settings defines the audio subsystem that will be used. The audio.periods and audio.period-size settings define the latency and robustness against scheduling delays. There are additional settings for the audio subsystems used. They will be documented later.

## General audio driver settings

audio.driver | Type | string
| Default | alsa (Linux), dsound (Windows), sndman (MacOS9), coreaudio (MacOS X)
| Options | alsa, oss, jack, dsound, sndman, coreaudio, portaudio
| Description | The audio system to be used.
audio.periods | Type | int
| Default | 16 (Linux, MacOS X), 8 (Windows)
| Min-Max | 2-64
| Description | The number of the audio buffers used by the driver. This number of buffers, multiplied by the buffer size (see setting audio.period-size), determines the maximum latency of the audio driver.
audio.period-size | Type | int
| Default | 64 (Linux, MacOS X), 512 (Windows)
| Min-Max | 64-8192
| Description | The size of the audio buffers (in frames).
audio.sample-format | Type | string
| Default | "16bits"
| Options | "16bits", "float"
| Description | The format of the audio samples. This is currently only an indication; the audio driver may ignore this setting if it can't handle the specified format.

## Using the synthesizer without an audio driver

It is possible to use the synthesizer object without creating an audio driver. This is desirable if the application using FluidSynth manages the audio output itself. The synthesizer has several API functions that can be used to obtain the audio output:

`fluid_synth_write_s16` fills two buffers (left and right channel) with samples coded as signed 16 bits (the endian-ness is machine dependent). `fluid_synth_write_float` fills a left and right audio buffer with 32 bits floating point samples. For multi channel audio output, the function `fluid_synth_nwrite_float` has to be used.

The function `fluid_synth_process` is still experimental and its use is therefore not recommended but it will probably become the generic interface in future versions.

## Loading and managing SoundFonts

Before any sound can be produced, the synthesizer needs a SoundFont. For a discussion on SoundFont please refer to some other, not yet existing, therefore virtual document.

SoundFonts are loaded with the `fluid_synth_sfload` function. The function takes the path to a SoundFont file as argument and a boolean to indicate whether the presets of the MIDI channels should be updated after the SoundFont is loaded. More on the preset updates below.

The synthesizer can load any number of SoundFonts. This is an advantage, of course, but there are some issues that you must be aware of. The presets in a SoundFont are identified by their bank and preset number. The MIDI specifications allows the change of a preset on a MIDI channel using the combination of "bank select" and the "program change" messages. An ambiguity arrizes when a preset with a specific bank and preset number is defined in multiple loaded SoundFonts. This is solved by searching the SoundFonts in the inverse order they were loaded, i.e. the lastly loaded SoundFont is searched first for the request preset (identified by bank and preset number) then the on but last loaded SoundFont, and so on until. The first preset found is then used. You can somehow consider the SoundFonts placed on a stack. The SoundFont on top of the stack is inspected first, followed by the SoundFont down on the stack. Newly loaded SoundFonts are always placed on top of the stack. This is how commercial, hardware synthesizers work. The inconvenience is that a preset in a SoundFont at the bottom end of the stack may be masked by a preset in a SoundFont at the top of the stack. Using the standard MIDI messages, bank select and program change, there is no way to select a masked preset. However, FluidSynth has an API function to unambiguously select a preset (`fluid_synth_program_select`). This function is not invokeable through MIDI messages, though.

The `fluid_synth_sfload` function returns the unique identifier of the loaded SoundFont, or -1 in case of an error. This identifier is used in subsequent management functions: `fluid_synth_sfunload` removes the SoundFont, `fluid_synth_sfreload` reloads the SoundFont. When a SoundFont is reloaded, it retains it's ID and position on the SoundFont stack.

Additional API functions are provided to get the number of loaded SoundFonts ot to get a pointer to the SoundFont.

Another issue that needs some explanation is the reprogramming of the presets after a SoundFont load or unload. The default behavior of commercial synthesizers is to reset all the preset that are programmed on the MIDI channels when a SoundFont is loaded or unloaded. Consider the case where MIDI channel 1 uses preset (0, 0) (the couple indicates the bank and program number). This preset was found in the SoundFont with ID 3, for example. When a new SoundFont is loaded that also contains a preset with bank number 0 and program number 0, then the newly loaded preset will be used on channel 1 for future events. This behavior is as if a bank select and program change message is send to all channels after a load/unload using the channel's bank and program number. This may be sometimes confusing or unwanted. A user may not want to loose its preset setup when a new SoundFont is loaded. To avoid the reprogramming of the presets, the third parameter to the `fluid_synth_sfload` and `fluid_synth_sfunload` functions should be set to zero.

## Sending MIDI events

Once the synthesizer is up and running and a SoundFont is loaded, most people will want to do something usefull with it. Make noise, for example. The synthesizer aims to be compatible with the MIDI standard, so it accepts almost all MIDI messages (details on the MIDI compatibility elsewhere). The MIDI channel messages can be send using the `fluid_synth_noteon`, `fluid_synth_noteoff`, `fluid_synth_cc`, `fluid_synth_pitch_bend`, `fluid_synth_pitch_wheel_sens`, and `fluid_synth_program_change` functions. For convenience, there's also a `fluid_synth_bank_select` function (the bank select message is normally sent using a control change message).

The following example show a generic graphical button that plays a not when clicked:

    class SoundButton : public SomeButton
    {
    public:

      SoundButton() : SomeButton() {
        if (!_synth) {
           initSynth();
        }
      }

      static void initSynth() {
        _settings = new_fluid_settings();
        _synth = new_fluid_synth(_settings);
        _adriver = new_fluid_audio_driver(_settings, _synth);
      }

      /* ... */

      virtual int handleMouseDown(int x, int y) {
        /* Play a note on key 60 with velocity 100 on MIDI channel 0 */
        fluid_synth_noteon(_synth, 0, 60, 100);
      }

      virtual int handleMouseUp(int x, int y) {
        /* Release the note on key 60 */
        fluid_synth_noteoff(_synth, 0, 60);
      }

    protected:

      static fluid_settings_t* _settings;
      static fluid_synth_t* _synth;
      static fluid_audio_driver_t* _adriver;
    };

## Advanced features, not yet documented

- Accessing low-level voice parameters

- Reverb settings

- Chorus settings

- Interpolation settings (set_gen, get_gen, NRPN)

- Sequencer

- LADSPA effects unit

- MIDI router

- Multi-channel audio

- MIDI tunings

- MIDI file player

- SoundFont loader