fluidsynth/doc/fluidsynth-v11-devdoc.txt

/*! 
\mainpage FluidSynth 2.0 Developer Documentation 
\author Peter Hanappe
\author Conrad Berhörster
\author Antoine Schmitt
\author Pedro López-Cabanillas
\author Josh Green
\author David Henningsson
\author Tom Moebert
\author Copyright © 2003-2017 Peter Hanappe, Conrad Berhörster, Antoine Schmitt, Pedro López-Cabanillas, Josh Green, David Henningsson, Tom Moebert
\version Revision 2.0.0ALPHA
\date 2017-10-14

All the source code examples in this document are in the public domain; you can use them as you please. This document is licensed under the Creative Commons Attribution-Share Alike 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/3.0/ . The FluidSynth library is distributed under the GNU Lesser General Public License. A copy of the GNU Lesser General Public License is contained in the FluidSynth package; if not, visit http://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt or write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

\section Abstract

<a href="http://www.fluidsynth.org">FluidSynth</a> is a software synthesizer based on the <a href="http://en.wikipedia.org/wiki/SoundFont">SoundFont 2</a> specifications. The synthesizer is available as a shared object that can easily be reused in any application that wants to use wave-table synthesis. This document explains the basic usage of FluidSynth. Some of the more advanced features are not yet discussed but will be added in future versions.

\section Contents Table of Contents

- \ref Disclaimer
- \ref Introduction
- \ref NewIn2_0_0
- \ref NewIn1_1_9
- \ref NewIn1_1_8
- \ref NewIn1_1_7
- \ref NewIn1_1_6
- \ref NewIn1_1_5
- \ref NewIn1_1_4
- \ref NewIn1_1_3
- \ref NewIn1_1_2
- \ref NewIn1_1_1
- \ref NewIn1_1_0
- \ref CreatingSettings 
- \ref CreatingSynth 
- \ref CreatingAudioDriver 
- \ref UsingSynth 
- \ref LoadingSoundfonts 
- \ref SendingMIDI
- \ref RealtimeMIDI
- \ref MIDIPlayer
- \ref MIDIPlayerMem
- \ref MIDIRouter 
- \ref Sequencer
- \ref Shell
- \ref Advanced 

\section Disclaimer

This documentation, in its current version, is incomplete. As always, the source code is the final reference.

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

\section Introduction

What is FluidSynth?

- FluidSynth is a software synthesizer based on the SoundFont 2 specifications. The synthesizer is available as a shared object (a concept also named Dynamic Linking Library, or DLL) that can be easily reused in any application for wave-table synthesis. This document explains the basic usage of FluidSynth.

- FluidSynth provides a Command Line Interface program ready to be used from the console terminal, offering most of the library functionalities to end users, among them the ability of render and play Standard MIDI Files, receive real-time MIDI events from external hardware ports and other applications, perform advanced routing of such events, enabling at the same time a local shell as well as a remote server commands interface.

- FluidSynth is an API (Application Programming Interface) relieving programmers from a lot of details of reading SoundFont and MIDI events and files, and sending the digital audio output to a Sound Card. These tasks can be accomplished using a small set of functions. This document explains most of the API functions and gives short examples about them.

- FluidSynth uses instrument samples contained in standard SF2 (SoundFont 2) files, having a file structure based on the RIFF format. The specification can be obtained here: http://connect.creativelabs.com/developer/SoundFont/Forms/AllItems.aspx but most users don't need to know any details of the format.

- 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, Mac OS X, and the Windows platforms, and support for OS/2 and OpenSolaris is experimental. It has audio and midi drivers for all mentioned platforms but you can use it with your own drivers if your application already handles MIDI and audio input/output. This document explains the basic usage of FluidSynth and provides examples that you can reuse. 

- FluidSynth is open source, in active development. For more details, take a look at http://www.fluidsynth.org

\section NewIn2_0_0 Whats new in 2.0.0?

FluidSynths SOVERSION was bumped. The API was reworked, deprecated functions were removed.

Changes in FluidSynth 2.0.0 concerning developers:

- remove deprecated fluid_synth_get_channel_info() in favour of fluid_synth_get_program() and fluid_synth_get_channel_preset()
- remove deprecated fluid_settings_getstr()
- remove deprecated fluid_synth_set_midi_router(), instead supply the midi-router instance when creating a command handler with new_fluid_cmd_handler()
- remove deprecated fluid_get_hinstance() and fluid_set_hinstance() (dsound driver now uses the desktop window)
- remove deprecated fluid_synth_create_key_tuning(), use fluid_synth_activate_key_tuning(synth, bank, prog, name, pitch, FALSE) instead
- remove deprecated fluid_synth_create_octave_tuning(), use fluid_synth_activate_octave_tuning(synth, bank, prog, name, pitch, FALSE) instead
- remove deprecated fluid_synth_select_tuning(), use fluid_synth_activate_tuning(synth, chan, bank, prog, FALSE) instead
- remove deprecated fluid_synth_reset_tuning(), use fluid_synth_deactivate_tuning(synth, chan, FALSE) instead
- remove deprecated FLUID_HINT_INTEGER
- remove deprecated fluid_synth_set_gen2() as there doesnt seem to be a use case for absolute generator values
- remove fluid_cmd_handler_register() and fluid_cmd_handler_unregister() from public API, as they seem to be unused downstream
- remove misspelled FLUID_SEQ_PITCHWHHELSENS macro
- remove obsolete "audio.[out|in]put-channels" settings
- remove unimplemented "synth.dump" setting
- remove struct _fluid_mod_t from public API, use the getters and setters of mod.h instead
- remove struct _fluid_gen_t, fluid_gen_set_default_values() and enum fluid_gen_flags from public API
- remove macros fluid_sfont_get_id() and fluid_sample_refcount() from public API
- remove FLUID_NUM_MOD macro from public API
- remove the following deprecated enum values from public API:
  - GEN_LAST
  - LAST_LOG_LEVEL
  - FLUID_SEQ_LASTEVENT
  - FLUID_MIDI_ROUTER_RULE_COUNT
<br /><br />
- all public \c fluid_settings_* functions that return an integer which is not meant to be interpreted as bool consistently return either FLUID_OK or FLUID_FAILED
- all public delete_* functions return void and are safe when called with NULL
- the shell command handler was decoupled internally, as a consequence the param list of new_fluid_server() and new_fluid_cmd_handler() was adapted
- reverb: roomsize is now limited to an upper threshold of 1.0 to avoid exponential volume increase
- use unique device names for the "audio.portaudio.device" setting
- rename fluid_mod_new() and fluid_mod_delete() to match naming conventions: new_fluid_mod() and delete_fluid_mod()
<br /><br />
- add <a href="fluidsettings.xml#midi.autoconnect">"midi.autoconnect"</a> a setting for automatically connecting fluidsynth to available MIDI input ports
- add <a href="fluidsettings.xml#synth.overflow.important">"synth.overflow.important"</a> and <a href="fluidsettings.xml#synth.overflow.important-channels">"synth.overflow.important-channels"</a> settings to take midi channels during overflow calculation into account that are considered to be "important"
- add support for polyphonic key pressure events, see fluid_event_key_pressure() and fluid_synth_key_pressure()
- add fluid_synth_add_default_mod() and fluid_synth_remove_default_mod() for manipulating default modulators
- add individual reverb setters: fluid_synth_set_reverb_roomsize(), fluid_synth_set_reverb_damp(), fluid_synth_set_reverb_width(), fluid_synth_set_reverb_level()
- add individual chorus setters: fluid_synth_set_chorus_nr(), fluid_synth_set_chorus_level(), fluid_synth_set_chorus_speed(), fluid_synth_set_chorus_depth(), fluid_synth_set_chorus_type()
- introduce a separate data type for sequencer client IDs: #fluid_seq_id_t
- add seek support to midi-player, see fluid_player_seek()
- expose functions to manipulate the ladspa effects unit (see ladspa.h)
- add support for text and lyrics midi events, see fluid_midi_event_set_lyrics() and fluid_midi_event_set_text()
- complete rewrite of the soundfont loader API, see sfont.h
  - support for 24 bit audio samples, see fluid_sample_set_sound_data()
  - expose new_fluid_defsfloader() to support loading soundfonts from memory, see fluid_sfloader_set_callbacks() and <a href="fluidsynth_sfload_mem_8c-example.html">fluidsynth_sfload_mem.c</a>
  - remove these structs from the public API and provide proper getter and setter functions instead:
    - struct _fluid_sfloader_t
    - struct _fluid_sample_t
    - struct _fluid_sfont_t
    - struct _fluid_preset_t
- add an additional general-purpose IIR filter, see fluid_synth_set_custom_filter()
- add a custom sinusoidal modulator mapping function, see #FLUID_MOD_SIN
- implement polymono support according to MIDI specs:
  - add basic channel support, see fluid_synth_reset_basic_channel(), fluid_synth_set_basic_channel(), fluid_synth_get_basic_channel()
  - implement MIDI modes Omni On, Omni Off, Poly, Mono, see #fluid_basic_channel_modes
  - implement portamento control, see fluid_synth_set_portamento_mode(), fluid_synth_get_portamento_mode()
  - implement legato control, see fluid_synth_set_legato_mode(), fluid_synth_get_legato_mode()
  - implement breath control, see fluid_synth_set_breath_mode(), fluid_synth_get_breath_mode()


\section NewIn1_1_9 Whats new in 1.1.9?

Changes in FluidSynth 1.1.9 concerning developers:

- add a function for registering audio drivers based on acutal needs: fluid_audio_driver_register()
- implement handling of #FLUID_SEQ_ALLSOUNDSOFF events in fluid_seq_fluidsynth_callback()
- fix return value of fluid_file_set_encoding_quality()

- For a full list of bug fixes, see
  https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-119

\section NewIn1_1_8 Whats new in 1.1.8?

Changes in FluidSynth 1.1.8 concerning developers:

- fluid_synth_get_channel_preset() is not deprecated anymore
- deprecate fluid_synth_get_channel_info()
- deprecate fluid_synth_set_midi_router()
- deprecate redundant tuning functions
- deprecate fluid_gen_set_default_values()
- deprecate struct _fluid_mod_t, use the respective getter and setter functions

- For a full list of bug fixes, see
  https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-118

\section NewIn1_1_7 Whats new in 1.1.7?

Changes in FluidSynth 1.1.7 concerning developers:

- "synth.parallel-render" has been deprecated
- fluid_synth_set_channel_type() was not exported properly
- "audio.jack.multi" had inverse logic
- fluid_synth_write_*() had timing issues when requesting more than 64 audio frames
- reverb and chorus are routed to distinct buffers in fluid_synth_nwrite_float()
- vorbis-compressed sf3 sound fonts are supported
- the following getters have been added: fluid_voice_is_on(), fluid_voice_is_sustained(), fluid_voice_is_sostenuto(), fluid_voice_get_channel(), fluid_voice_get_key(), fluid_voice_get_actual_key(), fluid_voice_get_velocity(), fluid_voice_get_actual_velocity(), fluid_player_get_current_tick(), fluid_player_get_total_ticks(), fluid_player_get_bpm(), fluid_player_get_midi_tempo()
- the following enum values have been deprecated: \c FLUID_SEQ_LASTEVENT, \c GEN_LAST, \c LAST_LOG_LEVEL

- For a full list of bug fixes, see
  https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-117


\section NewIn1_1_6 Whats new in 1.1.6?

Changes in FluidSynth 1.1.6 concerning developers:

- The player will not continue to the next song until all EOT (end of track events) have been reached.
- Enable long arguments on all platforms where getopt.h is available
- Windows: Fluidsynth.pc (pkg-config spec) is now installed.
- Mac OS X Lion: A build failure was fixed.

- For a full list of bug fixes, see
  https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-116


\section NewIn1_1_5 Whats new in 1.1.5?

Changes in FluidSynth 1.1.5 concerning developers:
- A change in the Jack driver might require a newer Jack version compared to 1.1.4.
- For a full list of bug fixes, see
  https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-115

\section NewIn1_1_4 Whats new in 1.1.4?

Changes in FluidSynth 1.1.4 concerning developers:

- You can now play MIDI files that reside in memory (instead of specifying a filename). See \ref MIDIPlayerMem for an example.
- A hook can be inserted for MIDI file playback, at playback time. This is done through the new fluid_player_set_playback_callback API function. You can use this to both inspect and modify MIDI events as they are being played (or add a MIDI router), just as you can for MIDI input drivers.
- Channel 10 used to be the one and only drum channel, this can now be changed using the fluid_synth_set_channel_type. 
- fluid_synth_all_sounds_off and fluid_synth_all_notes_off are new public API functions. You can use them to turn notes off (i e releasing all keys, voices advance to release phase) or sounds off (more like pressing the mute button), for one channel or all channels.
- For Mac OS X users: The CoreAudio driver has been adapted to use AuHAL, and the default build style has changed to "FluidSynth.framework".
- For a full list of other enhancements and bug fixes, see
  https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-114

\section NewIn1_1_3 Whats new in 1.1.3?

Changes in FluidSynth 1.1.3 concerning developers:

- There are no new API additions in 1.1.3, this is a pure bug-fix release.
  For a list of bugs fixed, see 
  https://github.com/FluidSynth/fluidsynth/wiki/ChangeLog#fluidsynth-113

\section NewIn1_1_2 Whats new in 1.1.2?

Changes in FluidSynth 1.1.2 concerning developers:

- Build system has switched from autotools to CMake. For more information, see
  README.cmake. The autotools build system is still working, but it is 
  deprecated. The "winbuild" and "macbuild" directories have been dropped in 
  favor of CMake's ability to create project files on demand.
- Thread safety has been reworked to overcome the limitations and bugs in 
  version 1.1.0 and 1.1.1. There are two new settings controlling the thread 
  safety, synth.threadsafe-api and synth.parallel-render. More information 
  about these settings is in the \ref CreatingSettings section. Please look
  them through and set them appropriately according to your use case.
- Voice overflow, i e what voice to kill when polyphony is exceeded, is now
  configurable.
- Possibility to update polyphony and sample rate real-time. Note that 
  updating polyphony is not hard real-time safe, and updating sample rate will 
  kill all currently sounding voices.
- MIDI Bank Select handling is now configurable. See the synth.midi-bank-select
  setting in the \ref CreatingSettings section for more information.
- Can use RealTimeKit (on Linux) to get real-time priority, if the original 
  attempt fails. Note that you'll need development headers for DBus to enable 
  this functionality.
- Shell commands for pitch bend and pitch bend range.
- PulseAudio driver: two new settings allows you to specify media role, 
  and control whether pulseaudio can adjust latency.

\section NewIn1_1_1 Whats new in 1.1.1?

Changes in FluidSynth 1.1.1 concerning developers:

- fluid_synth_get_channel_preset() marked as deprecated.  New function
  fluid_synth_get_channel_info() added which is thread safe and should replace
  most uses of the older function.
- Added fluid_synth_unset_program() to unset the active preset on a channel.

\section NewIn1_1_0 Whats new in 1.1.0?

Overview of changes in FluidSynth 1.1.0 concerning developers:

- Extensive work to make FluidSynth thread safe.  Previous versions had many multi-thread
  issues which could lead to crashes or synthesis glitches.  Some of the API additions,
  deprecations and function recommended conditions of use are related to this work.
- File renderer object for rendering audio to files.
- Sequencer objects can now use the system timer or the sample clock.  When using the sample
  clock, events are triggered based on the current output audio sample position.  This means
  that MIDI is synchronized with the audio and identical output will be achieved for the same
  MIDI event input.
- libsndfile support for rendering audio to different formats and file types.
- API for using the MIDI router subsystem.
- MIDI Tuning Standard functions were added for specifying whether to activate tuning changes
  in realtime or not.
- SYSEX support (MIDI Tuning Standard only at the moment).
- Changed all yes/no boolean string settings to integer #FLUID_HINT_TOGGLED settings with
  backwards compatibility (assignment and query of boolean values as strings).
- Many other improvements and bug fixes.

API additions:

- A file renderer can be created with new_fluid_file_renderer(), deleted with
  delete_fluid_file_renderer() and a block of audio processed with fluid_file_renderer_process_block().
- Additional functions were added for using the MIDI router subsystem.
  To clear all rules from a router use fluid_midi_router_clear_rules() and to set a router to default rules
  use fluid_midi_router_set_default_rules().
  To create a router rule use new_fluid_midi_router_rule() and to delete a rule use
  delete_fluid_midi_router_rule() (seldom used).  Set values of a router rule with
  fluid_midi_router_rule_set_chan(), fluid_midi_router_rule_set_param1() and fluid_midi_router_rule_set_param2().
  fluid_midi_router_add_rule() can be used to add a rule to a router.
- New MIDI event functions were added, including fluid_event_channel_pressure(), fluid_event_system_reset(),
  and fluid_event_unregistering().  
- Additional sequencer functions include fluid_sequencer_add_midi_event_to_buffer(),
  fluid_sequencer_get_use_system_timer() and fluid_sequencer_process().  new_fluid_sequencer2() was added to
  allow for the timer type to be specified (system or sample clock). 
- The settings subsystem has some new functions for thread safety: fluid_settings_copystr() and fluid_settings_dupstr().
  Also there are new convenience functions to count the number of string options for a setting: fluid_settings_option_count()
  and for concatenating setting options with a separator: fluid_settings_option_concat().
- MIDI Tuning Standard functions added include: fluid_synth_activate_key_tuning(), fluid_synth_activate_octave_tuning(),
  fluid_synth_activate_tuning() and fluid_synth_deactivate_tuning().  All of which provide a parameter for specifying if
  tuning changes should occur in realtime (affect existing voices) or not.
- Additional synthesizer API: fluid_synth_get_sfont_by_name() to get a SoundFont by name,
  fluid_synth_program_select_by_sfont_name() to select an instrument by SoundFont name/bank/program,
  fluid_synth_set_gen2() for specifying additional parameters when assigning a generator value,
  fluid_synth_sysex() for sending SYSEX messages to the synth and fluid_synth_get_active_voice_count() to
  get the current number of active synthesis voices.
- Miscellaneous additions: fluid_player_set_loop() to set playlist loop count and fluid_player_get_status() to get current player state.



\section CreatingSettings Creating and changing the settings

Before you can use the synthesizer, you have to create a settings object. The settings objects is used by many components of the FluidSynth library. It gives a unified API to set the parameters of the audio drivers, the midi drivers, the synthesizer, and so forth. A number of default settings are defined by the current implementation.

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_settings_setint() functions. For example: 

\code
#include <fluidsynth.h>

int main(int argc, char** argv) 
{
    fluid_settings_t* settings = new_fluid_settings();
    fluid_settings_setint(settings, "synth.polyphony", 128);
    /* ... */
    delete_fluid_settings(settings);
    return 0;
}
\endcode

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 minimum 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 settings.h API documentation for a description of all functions. 

\section CreatingSynth Creating the synthesizer

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

\code
#include <fluidsynth.h>

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

    /* Do useful things here */

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

For a full list of available <strong>synthesizer settings</strong>, please refer to <a href="fluidsettings.xml" target="_blank"><b>FluidSettings Documentation</b></a>.



\section CreatingAudioDriver 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 the audio systems that are currently supported. It displays the name, as used by the fluidsynth library, and a description. 

- jack: JACK Audio Connection Kit (Linux, Mac OS X, Windows)
- alsa: Advanced Linux Sound Architecture (Linux)
- oss: Open Sound System (Linux, Unix)
- pulseaudio: PulseAudio (Linux, Mac OS X, Windows)
- coreaudio: Apple CoreAudio (Mac OS X)
- dsound: Microsoft DirectSound (Windows)
- portaudio: PortAudio Library (Mac OS 9 & X, Windows, Linux)
- sndman: Apple SoundManager (Mac OS Classic)
- dart: DART sound driver (OS/2)
- file: Driver to output audio to a file

The default audio driver depends on the settings with which FluidSynth was compiled. You can get the default driver with fluid_settings_getstr_default(). 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: 

\code
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);
}
\endcode

As soon as the audio driver is created, it will start playing. The audio driver creates a separate thread that uses the synthesizer object to generate the audio.
 
There are a number of general audio driver settings. The audio.driver settings define 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. For a full list of available <strong>audio driver settings</strong>, please refer to <a href="fluidsettings.xml" target="_blank"><strong>FluidSettings Documentation</strong></a>.



\section UsingSynth 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. 

\section LoadingSoundfonts Loading and managing SoundFonts

Before any sound can be produced, the synthesizer needs a SoundFont.

SoundFonts are loaded with the fluid_synth_sfload() function. The function takes the path to a SoundFont file and a boolean to indicate whether the presets of the MIDI channels should be updated after the SoundFont is loaded. When the boolean value is TRUE, all MIDI channel bank and program numbers will be refreshed, which may cause new instruments to be selected from the newly loaded SoundFont.

The synthesizer can load any number of SoundFonts. The loaded SoundFonts are treated as a stack, where each new loaded SoundFont is placed at the top of the stack. When selecting presets by bank and program numbers, SoundFonts are searched beginning at the top of the stack. In the case where there are presets in different SoundFonts with identical bank and program numbers, the preset from the most recently loaded SoundFont is used. The fluid_synth_program_select() can be used for unambiguously selecting a preset or bank offsets could be applied to each SoundFont with fluid_synth_set_bank_offset(), to try and ensure that each preset has unique bank and program numbers.

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 and to get a pointer to the SoundFont. 

\section SendingMIDI Sending MIDI Events

Once the synthesizer is up and running and a SoundFont is loaded, most people will want to do something useful with it. Make noise, for example. MIDI messages can be sent 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 note when clicked: 

\code
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;
};
\endcode

\section RealtimeMIDI Creating a Real-time MIDI Driver

FluidSynth can process real-time MIDI events received from hardware MIDI ports or other applications. To do so, the client must create a MIDI input driver. It is a very similar process to the creation of the audio driver: you initialize some properties in a settings instance and call the new_fluid_midi_driver() function providing a callback function that will be invoked when a MIDI event is received. The following MIDI drivers are currently supported:

- jack: JACK Audio Connection Kit MIDI driver (Linux, Mac OS X)
- oss: Open Sound System raw MIDI (Linux, Unix)
- alsa_raw: ALSA raw MIDI interface (Linux)
- alsa_seq: ALSA sequencer MIDI interface (Linux)
- winmidi: Microsoft Windows MM System (Windows)
- midishare: MIDI Share (Linux, Mac OS X)
- coremidi: Apple CoreMIDI (Mac OS X)

\code
#include <fluidsynth.h>

int handle_midi_event(void* data, fluid_midi_event_t* event)
{
    printf("event type: %d\n", fluid_midi_event_get_type(event));
}

int main(int argc, char** argv)
{
    fluid_settings_t* settings;
    fluid_midi_driver_t* mdriver;
    settings = new_fluid_settings();
    mdriver = new_fluid_midi_driver(settings, handle_midi_event, NULL);
    /* ... */    
    delete_fluid_midi_driver(mdriver);
    return 0;
}
\endcode

There are a number of general MIDI driver settings. The midi.driver setting
defines the MIDI subsystem that will be used. There are additional settings for
the MIDI subsystems used. For a full list of available <strong>midi driver settings</strong>, please refer to <a href="fluidsettings.xml" target="_blank"><strong>FluidSettings Documentation</strong></a>.



\section MIDIPlayer Loading and Playing a MIDI file

FluidSynth can be used to play MIDI files, using the MIDI File Player interface. It follows a high level implementation, though its implementation is currently incomplete. After initializing the synthesizer, create the player passing the synth instance to new_fluid_player(). Then, you can add some SMF file names to the player using fluid_player_add(), and finally call fluid_player_play() to start the playback. You can check if the player has finished by calling fluid_player_get_status(), or wait for the player to terminate using fluid_player_join().

\code
#include <fluidsynth.h>

int main(int argc, char** argv) 
{
    int i;
    fluid_settings_t* settings;
    fluid_synth_t* synth;
    fluid_player_t* player;
    fluid_audio_driver_t* adriver;
    settings = new_fluid_settings();
    synth = new_fluid_synth(settings);
    player = new_fluid_player(synth);
    adriver = new_fluid_audio_driver(settings, synth);
    /* process command line arguments */
    for (i = 1; i < argc; i++) {
        if (fluid_is_soundfont(argv[i])) {
           fluid_synth_sfload(synth, argv[1], 1);
        }
        if (fluid_is_midifile(argv[i])) {
            fluid_player_add(player, argv[i]);
        }
    }
    /* play the midi files, if any */
    fluid_player_play(player);
    /* wait for playback termination */
    fluid_player_join(player);
    /* cleanup */
    delete_fluid_audio_driver(adriver);
    delete_fluid_player(player);
    delete_fluid_synth(synth);
    delete_fluid_settings(settings);
    return 0;
}
\endcode


A list of available <strong>MIDI player settings</strong> can be found in <a href="fluidsettings.xml" target="_blank"><b>FluidSettings Documentation</b></a>.



\section MIDIPlayerMem Playing a MIDI file from memory

FluidSynth can be also play MIDI files directly from a buffer in memory. If you need to play a file from a stream (such as stdin, a network, or a high-level file interface), you can load the entire file into a buffer first, and then use this approach. Use the same technique as above, but rather than calling fluid_player_add(), load it into memory and call fluid_player_add_mem() instead. Once you have passed a buffer to fluid_player_add_mem(), it is copied, so you may use it again or free it immediately (it is your responsibility to free it if you allocated it).

\code
#include <stdlib.h>
#include <string.h>
#include <fluidsynth.h>

/* An example midi file */
const char MIDIFILE[] = {
    0x4d, 0x54, 0x68, 0x64, 0x00, 0x00, 0x00, 0x06,
    0x00, 0x01, 0x00, 0x01, 0x01, 0xe0, 0x4d, 0x54,
    0x72, 0x6b, 0x00, 0x00, 0x00, 0x20, 0x00, 0x90,
    0x3c, 0x64, 0x87, 0x40, 0x80, 0x3c, 0x7f, 0x00,
    0x90, 0x43, 0x64, 0x87, 0x40, 0x80, 0x43, 0x7f,
    0x00, 0x90, 0x48, 0x64, 0x87, 0x40, 0x80, 0x48,
    0x7f, 0x83, 0x60, 0xff, 0x2f, 0x00
};

int main(int argc, char** argv)
{
    int i;
    void* buffer;
    size_t buffer_len;
    fluid_settings_t* settings;
    fluid_synth_t* synth;
    fluid_player_t* player;
    fluid_audio_driver_t* adriver;
    settings = new_fluid_settings();
    synth = new_fluid_synth(settings);
    player = new_fluid_player(synth);
    adriver = new_fluid_audio_driver(settings, synth);
    /* process command line arguments */
    for (i = 1; i < argc; i++) {
        if (fluid_is_soundfont(argv[i])) {
           fluid_synth_sfload(synth, argv[1], 1);
        }
    }
    /* queue up the in-memory midi file */
    fluid_player_add_mem(player, MIDIFILE, sizeof(MIDIFILE));
    /* play the midi file */
    fluid_player_play(player);
    /* wait for playback termination */
    fluid_player_join(player);
    /* cleanup */
    delete_fluid_audio_driver(adriver);
    delete_fluid_player(player);
    delete_fluid_synth(synth);
    delete_fluid_settings(settings);
    return 0;
}
\endcode

\section MIDIRouter Real-time MIDI router

The MIDI router is one more processing layer directly behind the MIDI input. It processes incoming MIDI events and generates control events for the synth. It can be used to filter or modify events prior to sending them to the synthesizer. When created, the MIDI router is transparent and simply passes all MIDI events. Router "rules" must be added to actually make use of its capabilities.

Some examples of MIDI router usage:

- Filter messages (Example: Pass sustain pedal CCs only to selected channels)
- Split the keyboard (Example: noteon with notenr < x: to ch 1, >x to ch 2)
- Layer sounds (Example: for each noteon received on ch 1, create a noteon on ch1, ch2, ch3,...)
- Velocity scaling (Example: for each noteon event, scale the velocity by 1.27)
- Velocity switching (Example: v <= 100: "Angel Choir"; v > 100: "Hell's Bells")
- Get rid of aftertouch

The MIDI driver API has a clean separation between the midi thread and the synthesizer. That opens the door to add a midi router module.

MIDI events coming from the MIDI player do not pass through the MIDI router.

\code
#include <fluidsynth.h>

int main(int argc, char** argv) 
{
    fluid_settings_t* settings;
    fluid_synth_t* synth;
    fluid_midi_router_t* router;
    fluid_midi_router_rule_t* rule;

    settings = new_fluid_settings();
    synth = new_fluid_synth(settings);

    /* Create the MIDI router and pass events to the synthesizer */
    router = new_fluid_midi_router (settings, fluid_synth_handle_midi_event, synth);

    /* Clear default rules */
    fluid_midi_router_clear_rules (router);

    /* Add rule to map all notes < MIDI note #60 on any channel to channel 4 */
    rule = new_fluid_midi_router_rule ();
    fluid_midi_router_rule_set_chan (rule, 0, 15, 0.0, 4);	/* Map all to channel 4 */
    fluid_midi_router_rule_set_param1 (rule, 0, 59, 1.0, 0);	/* Match notes < 60 */
    fluid_midi_router_add_rule (router, rule, FLUID_MIDI_ROUTER_RULE_NOTE);

    /* Add rule to map all notes >= MIDI note #60 on any channel to channel 5 */
    rule = new_fluid_midi_router_rule ();
    fluid_midi_router_rule_set_chan (rule, 0, 15, 0.0, 5);	/* Map all to channel 5 */
    fluid_midi_router_rule_set_param1 (rule, 60, 127, 1.0, 0);	/* Match notes >= 60 */
    fluid_midi_router_add_rule (router, rule, FLUID_MIDI_ROUTER_RULE_NOTE);

    /* Add rule to reverse direction of pitch bender on channel 7 */
    rule = new_fluid_midi_router_rule ();
    fluid_midi_router_rule_set_chan (rule, 7, 7, 1.0, 0);	      /* Match channel 7 only */
    fluid_midi_router_rule_set_param1 (rule, 0, 16383, -1.0, 16383);  /* Reverse pitch bender */
    fluid_midi_router_add_rule (router, rule, FLUID_MIDI_ROUTER_RULE_PITCH_BEND);

    /* ... Create audio driver, process events, etc ... */

    /* cleanup */
    delete_fluid_midi_router(router);
    delete_fluid_synth(synth);
    delete_fluid_settings(settings);
    return 0;
}
\endcode



\section Sequencer

FluidSynth's sequencer can be used to play MIDI events in a more flexible way than using the MIDI file player, which expects the events to be stored as Standard MIDI Files. Using the sequencer, you can provide the events one by one, with an optional timestamp for scheduling. 

The client program should first initialize the sequencer instance using the function new_fluid_sequencer2(). There is a complementary function delete_fluid_sequencer() to delete it. After creating the sequencer instance, the destinations can be registered using fluid_sequencer_register_fluidsynth() for the synthesizer destination, and optionally using fluid_sequencer_register_client() for the client destination providing a suitable callback function. It can be unregistered using fluid_sequencer_unregister_client(). After the initialization, events can be sent with fluid_sequencer_send_now() and scheduled to the future with fluid_sequencer_send_at(). The registration functions return identifiers, that can be used as destinations of an event using fluid_event_set_dest().

The function fluid_sequencer_get_tick() returns the current playing position. A program may choose a new timescale in milliseconds using fluid_sequencer_set_time_scale().

The following example uses the fluidsynth sequencer to implement a sort of music box. FluidSynth internal clock is used to schedule repetitive sequences of notes. The next sequence is scheduled on advance before the end of the current one, using a timer event that triggers a callback function. The scheduling times are always absolute values, to avoid slippage.

\code
#include "fluidsynth.h"

fluid_synth_t* synth;
fluid_audio_driver_t* adriver;
fluid_sequencer_t* sequencer;
short synthSeqID, mySeqID;
unsigned int now;
unsigned int seqduration;

// prototype
void seq_callback(unsigned int time, fluid_event_t* event, fluid_sequencer_t* seq, void* data);

void createsynth() 
{
    fluid_settings_t* settings;
    settings = new_fluid_settings();
    fluid_settings_setstr(settings, "synth.reverb.active", "yes");
    fluid_settings_setstr(settings, "synth.chorus.active", "no");
    synth = new_fluid_synth(settings);
    adriver = new_fluid_audio_driver(settings, synth);
    sequencer = new_fluid_sequencer2(0);

    // register synth as first destination
    synthSeqID = fluid_sequencer_register_fluidsynth(sequencer, synth);

    // register myself as second destination
    mySeqID = fluid_sequencer_register_client(sequencer, "me", seq_callback, NULL);

    // the sequence duration, in ms
    seqduration = 1000;
}

void deletesynth() 
{
    delete_fluid_sequencer(sequencer);
    delete_fluid_audio_driver(adriver);
    delete_fluid_synth(synth);
}

void loadsoundfont() 
{
    int fluid_res;
    // put your own path here
    fluid_res = fluid_synth_sfload(synth, "Inside:VintageDreamsWaves-v2.sf2", 1);
}

void sendnoteon(int chan, short key, unsigned int date) 
{
    int fluid_res;
    fluid_event_t *evt = new_fluid_event();
    fluid_event_set_source(evt, -1);
    fluid_event_set_dest(evt, synthSeqID);
    fluid_event_noteon(evt, chan, key, 127);
    fluid_res = fluid_sequencer_send_at(sequencer, evt, date, 1);
    delete_fluid_event(evt);
}

void schedule_next_callback() 
{
    int fluid_res;
    // I want to be called back before the end of the next sequence
    unsigned int callbackdate = now + seqduration/2;
    fluid_event_t *evt = new_fluid_event();
    fluid_event_set_source(evt, -1);
    fluid_event_set_dest(evt, mySeqID);
    fluid_event_timer(evt, NULL);
    fluid_res = fluid_sequencer_send_at(sequencer, evt, callbackdate, 1);
    delete_fluid_event(evt);
}

void schedule_next_sequence() {
    // Called more or less before each sequence start
    // the next sequence start date
    now = now + seqduration;

    // the sequence to play

    // the beat : 2 beats per sequence
    sendnoteon(0, 60, now + seqduration/2);
    sendnoteon(0, 60, now + seqduration);

    // melody
    sendnoteon(1, 45, now + seqduration/10);
    sendnoteon(1, 50, now + 4*seqduration/10);
    sendnoteon(1, 55, now + 8*seqduration/10);

    // so that we are called back early enough to schedule the next sequence
    schedule_next_callback();
}

/* sequencer callback */
void seq_callback(unsigned int time, fluid_event_t* event, fluid_sequencer_t* seq, void* data) {
    schedule_next_sequence();
}

int main(void) {
    createsynth();
    loadsoundfont();

    // initialize our absolute date
    now = fluid_sequencer_get_tick(sequencer);
    schedule_next_sequence();

    sleep(100000);
    deletesynth();
    return 0;
}
\endcode

\section Shell Shell interface

The shell interface allows you to send simple textual commands to the synthesizer, to parse a command file, or to read commands from the stdin or other input streams. To find the list of currently supported commands, please check the fluid_cmd.c file or type "help" in the fluidsynth command line shell. For a full list of available <strong>command line settings</strong>, please refer to <a href="fluidsettings.xml" target="_blank"><b>FluidSettings Documentation</b></a>.



\section Advanced Advanced features, not yet documented.  API reference may contain more info.

- Accessing low-level voice parameters
- Reverb settings
- Chorus settings
- Interpolation settings (set_gen, get_gen, NRPN)
- Voice overflow settings
- LADSPA effects unit
- Multi-channel audio
- MIDI tunings
- Fast file renderer for rendering audio to file in non-realtime
*/

/*!
\example example.c
Example producing short random music with FluidSynth
*/

/*!
\example fluidsynth_simple.c
A basic example of using fluidsynth to play a single note
*/

/*!
\example fluidsynth_fx.c
Example of using effects with fluidsynth
*/

/*!
\example fluidsynth_metronome.c
Example of a simple metronome using the MIDI sequencer API 
*/

/*!
\example fluidsynth_arpeggio.c
Example of an arpeggio generated using the MIDI sequencer API
*/

/*!
\example fluidsynth_register_adriver.c
Example of how to register audio drivers using fluid_audio_driver_register() (advanced users only)
*/

/*!
\example fluidsynth_sfload_mem.c
Example of how read a soundfont from memory (advanced users only)
*/