<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>libfluidsynth: FluidSynth 1.1 Developer Documentation</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.7.1 -->
<script type="text/javascript">
function hasClass(ele,cls) {
return ele.className.match(new RegExp('(\\s|^)'+cls+'(\\s|$)'));
}
function addClass(ele,cls) {
if (!this.hasClass(ele,cls)) ele.className += " "+cls;
}
function removeClass(ele,cls) {
if (hasClass(ele,cls)) {
var reg = new RegExp('(\\s|^)'+cls+'(\\s|$)');
ele.className=ele.className.replace(reg,' ');
}
}
function toggleVisibility(linkObj) {
var base = linkObj.getAttribute('id');
var summary = document.getElementById(base + '-summary');
var content = document.getElementById(base + '-content');
var trigger = document.getElementById(base + '-trigger');
if ( hasClass(linkObj,'closed') ) {
summary.style.display = 'none';
content.style.display = 'block';
trigger.src = 'open.png';
removeClass(linkObj,'closed');
addClass(linkObj,'opened');
} else if ( hasClass(linkObj,'opened') ) {
summary.style.display = 'block';
content.style.display = 'none';
trigger.src = 'closed.png';
removeClass(linkObj,'opened');
addClass(linkObj,'closed');
}
return false;
}
</script>
<div class="navigation" id="top">
<div class="tabs">
<ul class="tablist">
<li class="current"><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li><a href="examples.html"><span>Examples</span></a></li>
</ul>
</div>
</div>
<div class="header">
<div class="headertitle">
<h1>FluidSynth 1.1 Developer Documentation </h1> </div>
</div>
<div class="contents">
<h3 class="version">1.1.3 </h3><dl class="author"><dt><b>Author:</b></dt><dd>Peter Hanappe </dd>
<dd>
Conrad Berhörster </dd>
<dd>
Antoine Schmitt </dd>
<dd>
Pedro López-Cabanillas </dd>
<dd>
Josh Green </dd>
<dd>
David Henningsson </dd>
<dd>
Copyright © 2003-2010 Peter Hanappe, Conrad Berhörster, Antoine Schmitt, Pedro López-Cabanillas, Josh Green, David Henningsson </dd></dl>
<dl class="version"><dt><b>Version:</b></dt><dd>Revision 1.1.2 </dd></dl>
<dl class="date"><dt><b>Date:</b></dt><dd>2010-08-26</dd></dl>
<p>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 <a href="http://creativecommons.org/licenses/by-sa/3.0/">http://creativecommons.org/licenses/by-sa/3.0/</a> . The FluidSynth library is distributed under the GNU Library General Public License. A copy of the GNU Library General Public License is contained in the FluidSynth package; if not, visit <a href="http://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt">http://www.gnu.org/licenses/old-licenses/lgpl-2.1.txt</a> or write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.</p>
<h2><a class="anchor" id="Abstract"></a>
Abstract</h2>
<p><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.</p>
<h2><a class="anchor" id="Contents"></a>
Table of Contents</h2>
<ul>
<li><a class="el" href="index.html#Disclaimer">Disclaimer</a></li>
<li><a class="el" href="index.html#Introduction">Introduction</a></li>
<li><a class="el" href="index.html#NewIn1_1_3">Whats new in 1.1.3?</a></li>
<li><a class="el" href="index.html#NewIn1_1_2">Whats new in 1.1.2?</a></li>
<li><a class="el" href="index.html#NewIn1_1_1">Whats new in 1.1.1?</a></li>
<li><a class="el" href="index.html#NewIn1_1_0">Whats new in 1.1.0?</a></li>
<li><a class="el" href="index.html#CreatingSettings">Creating and changing the settings</a></li>
<li><a class="el" href="index.html#CreatingSynth">Creating the synthesizer</a></li>
<li><a class="el" href="index.html#CreatingAudioDriver">Creating the Audio Driver</a></li>
<li><a class="el" href="index.html#UsingSynth">Using the synthesizer without an audio driver</a></li>
<li><a class="el" href="index.html#LoadingSoundfonts">Loading and managing SoundFonts</a></li>
<li><a class="el" href="index.html#SendingMIDI">Sending MIDI Events</a></li>
<li><a class="el" href="index.html#RealtimeMIDI">Creating a Real-time MIDI Driver</a></li>
<li><a class="el" href="index.html#MIDIPlayer">Loading and Playing a MIDI file</a></li>
<li><a class="el" href="index.html#MIDIRouter">Real-time MIDI router</a></li>
<li><a class="el" href="index.html#Sequencer">Sequencer</a></li>
<li><a class="el" href="index.html#Shell">Shell interface</a></li>
<li><a class="el" href="index.html#Advanced">Advanced features, not yet documented. API reference may contain more info.</a></li>
</ul>
<h2><a class="anchor" id="Disclaimer"></a>
Disclaimer</h2>
<p>This documentation, in its current version, is incomplete. As always, the source code is the final reference.</p>
<p>SoundFont(R) is a registered trademark of E-mu Systems, Inc.</p>
<h2><a class="anchor" id="Introduction"></a>
Introduction</h2>
<p>What is FluidSynth?</p>
<ul>
<li>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.</li>
</ul>
<ul>
<li>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.</li>
</ul>
<ul>
<li>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.</li>
</ul>
<ul>
<li>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: <a href="http://connect.creativelabs.com/developer/SoundFont/Forms/AllItems.aspx">http://connect.creativelabs.com/developer/SoundFont/Forms/AllItems.aspx</a> but most users don't need to know any details of the format.</li>
</ul>
<ul>
<li>FluidSynth can easily be embedded in an application. It has a main header file, <a class="el" href="fluidsynth_8h.html" title="FluidSynth is a real-time synthesizer designed for SoundFont(R) files.">fluidsynth.h</a>, 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.</li>
</ul>
<ul>
<li>FluidSynth is open source, in active development. For more details, take a look at <a href="http://www.fluidsynth.org">http://www.fluidsynth.org</a></li>
</ul>
<h2><a class="anchor" id="NewIn1_1_3"></a>
Whats new in 1.1.3?</h2>
<p>Changes in FluidSynth 1.1.2 concerning developers:</p>
<ul>
<li>There are no new API additions in 1.1.3, this is a pure bug-fix release. For a list of bugs fixed, see <a href="https://sourceforge.net/apps/trac/fluidsynth/wiki/ChangeLog1_1_3">https://sourceforge.net/apps/trac/fluidsynth/wiki/ChangeLog1_1_3</a></li>
</ul>
<h2><a class="anchor" id="NewIn1_1_2"></a>
Whats new in 1.1.2?</h2>
<p>Changes in FluidSynth 1.1.2 concerning developers:</p>
<ul>
<li>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.</li>
<li>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 <a class="el" href="index.html#CreatingSettings">Creating and changing the settings</a> section. Please look them through and set them appropriately according to your use case.</li>
<li>Voice overflow, i e what voice to kill when polyphony is exceeded, is now configurable.</li>
<li>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.</li>
<li>MIDI Bank Select handling is now configurable. See the synth.midi-bank-select setting in the <a class="el" href="index.html#CreatingSettings">Creating and changing the settings</a> section for more information.</li>
<li>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.</li>
<li>Shell commands for pitch bend and pitch bend range.</li>
<li>PulseAudio driver: two new settings allows you to specify media role, and control whether pulseaudio can adjust latency.</li>
</ul>
<h2><a class="anchor" id="NewIn1_1_1"></a>
Whats new in 1.1.1?</h2>
<p>Changes in FluidSynth 1.1.1 concerning developers:</p>
<ul>
<li><a class="el" href="synth_8h.html#a3fba596ce8f5f4c0e54d8013348e80c4" title="Get active preset on a MIDI channel.">fluid_synth_get_channel_preset()</a> marked as deprecated. New function <a class="el" href="synth_8h.html#a00a22e3f06eba8c3d14d3f1aa49490e6" title="Get information on the currently selected preset on a MIDI channel.">fluid_synth_get_channel_info()</a> added which is thread safe and should replace most uses of the older function.</li>
<li>Added <a class="el" href="synth_8h.html#a5541af149bb98e0eaaf91f5d3419cb10" title="Set the preset of a MIDI channel to an unassigned state.">fluid_synth_unset_program()</a> to unset the active preset on a channel.</li>
</ul>
<h2><a class="anchor" id="NewIn1_1_0"></a>
Whats new in 1.1.0?</h2>
<p>Overview of changes in FluidSynth 1.1.0 concerning developers:</p>
<ul>
<li>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.</li>
<li>File renderer object for rendering audio to files.</li>
<li>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.</li>
<li>libsndfile support for rendering audio to different formats and file types.</li>
<li>API for using the MIDI router subsystem.</li>
<li>MIDI Tuning Standard functions were added for specifying whether to activate tuning changes in realtime or not.</li>
<li>SYSEX support (MIDI Tuning Standard only at the moment).</li>
<li>Changed all yes/no boolean string settings to integer <a class="el" href="settings_8h.html#a3a8898f5a93139fbc35f5dfe39ed9f5a" title="Hint FLUID_HINT_TOGGLED indicates that the data item should be considered a Boolean toggle...">FLUID_HINT_TOGGLED</a> settings with backwards compatibility (assignment and query of boolean values as strings).</li>
<li>Many other improvements and bug fixes.</li>
</ul>
<p>API additions:</p>
<ul>
<li>A file renderer can be created with <a class="el" href="audio_8h.html#a9d9338a870c5f71ba6fad6db7d17a93e" title="Create a new file renderer and open the file.">new_fluid_file_renderer()</a>, deleted with <a class="el" href="audio_8h.html#a6893d780de15030366e2399293ed7362" title="Close file and destroy a file renderer object.">delete_fluid_file_renderer()</a> and a block of audio processed with <a class="el" href="audio_8h.html#abdea2fb753cf1a5fa9b5dca38c177d80" title="Write period_size samples to file.">fluid_file_renderer_process_block()</a>.</li>
<li>Additional functions were added for using the MIDI router subsystem. To clear all rules from a router use <a class="el" href="midi_8h.html#a57aed5e84828c202452e13f265dd72f7" title="Clear all rules in a MIDI router.">fluid_midi_router_clear_rules()</a> and to set a router to default rules use <a class="el" href="midi_8h.html#a32ecd2bdcc9bce39d0e0c68e5c1b80cb" title="Set a MIDI router to use default "unity" rules.">fluid_midi_router_set_default_rules()</a>. To create a router rule use <a class="el" href="midi_8h.html#a128bc8b126cbabf7717149123815d235" title="Create a new MIDI router rule.">new_fluid_midi_router_rule()</a> and to delete a rule use <a class="el" href="midi_8h.html#af1ba4e46f279d4d177169446d85bf06c" title="Free a MIDI router rule.">delete_fluid_midi_router_rule()</a> (seldom used). Set values of a router rule with <a class="el" href="midi_8h.html#acc264709865c1e2dc972528cca55dc6f" title="Set the channel portion of a rule.">fluid_midi_router_rule_set_chan()</a>, <a class="el" href="midi_8h.html#ac4f572c218943ded7fe43692a265ddb5" title="Set the first parameter portion of a rule.">fluid_midi_router_rule_set_param1()</a> and <a class="el" href="midi_8h.html#a20afb0ffeb59c373534e5d46ed3d4b73" title="Set the second parameter portion of a rule.">fluid_midi_router_rule_set_param2()</a>. <a class="el" href="midi_8h.html#aa1894a103cde4f1efe80c7c9d5096ae2" title="Add a rule to a MIDI router.">fluid_midi_router_add_rule()</a> can be used to add a rule to a router.</li>
<li>New MIDI event functions were added, including <a class="el" href="event_8h.html#af6af8215438942a79dc953ba8419d1ac" title="Set a sequencer event to be a channel-wide aftertouch event.">fluid_event_channel_pressure()</a>, <a class="el" href="event_8h.html#ae58c2c79f68a9e8d9ba70281013a9bcf" title="Set a sequencer event to be a midi system reset event.">fluid_event_system_reset()</a>, and <a class="el" href="event_8h.html#a1af14ec5decbc1fcbdf1d5404f0c1bc6" title="Set a sequencer event to be an unregistering event.">fluid_event_unregistering()</a>.</li>
<li>Additional sequencer functions include <a class="el" href="seqbind_8h.html#aecf29486fa3b80514be4a6a535b02045" title="Transforms an incoming midi event (from a midi driver or midi router) to a sequencer event and adds i...">fluid_sequencer_add_midi_event_to_buffer()</a>, <a class="el" href="seq_8h.html#a2ae3552fe3a4f20b8a29854c93eed643" title="Check if a sequencer is using the system timer or not.">fluid_sequencer_get_use_system_timer()</a> and <a class="el" href="seq_8h.html#a3210e5a6b8a23c25038b91d0810a0a02" title="Advance a sequencer that isn't using the system timer.">fluid_sequencer_process()</a>. <a class="el" href="seq_8h.html#a3c27499606024a92bca0b32dbcf72c44" title="Create a new sequencer object.">new_fluid_sequencer2()</a> was added to allow for the timer type to be specified (system or sample clock).</li>
<li>The settings subsystem has some new functions for thread safety: <a class="el" href="settings_8h.html#ab77b24ccdb7d1eeb96f5933eb6099346" title="Copy the value of a string setting.">fluid_settings_copystr()</a> and <a class="el" href="settings_8h.html#aa2cf8ed808a4ce5fcfdfb208ea77811b" title="Duplicate the value of a string setting.">fluid_settings_dupstr()</a>. Also there are new convenience functions to count the number of string options for a setting: <a class="el" href="settings_8h.html#a2b0f4f5c31f722633b20e9f2aae45fcc" title="Count option string values for a string setting.">fluid_settings_option_count()</a> and for concatenating setting options with a separator: <a class="el" href="settings_8h.html#a7c78d673d39c3463339612f7a508cda4" title="Concatenate options for a string setting together with a separator between.">fluid_settings_option_concat()</a>.</li>
<li>MIDI Tuning Standard functions added include: <a class="el" href="synth_8h.html#a82eea41553b546ec063c2dc840ca711d" title="Set the tuning of the entire MIDI note scale.">fluid_synth_activate_key_tuning()</a>, <a class="el" href="synth_8h.html#a50ffe674e0e4ae9c778cfe41eabf110b" title="Activate an octave tuning on every octave in the MIDI note scale.">fluid_synth_activate_octave_tuning()</a>, <a class="el" href="synth_8h.html#ad370b81904a65188981c45ee840204d3" title="Activate a tuning scale on a MIDI channel.">fluid_synth_activate_tuning()</a> and <a class="el" href="synth_8h.html#a7d3c0e7ce720c8f1b8a2de2f950d438f" title="Clear tuning scale on a MIDI channel (use default equal tempered scale).">fluid_synth_deactivate_tuning()</a>. All of which provide a parameter for specifying if tuning changes should occur in realtime (affect existing voices) or not.</li>
<li>Additional synthesizer API: <a class="el" href="synth_8h.html#a5856acea557bb30b8c8cfbaf7bd008c6" title="Get SoundFont by name.">fluid_synth_get_sfont_by_name()</a> to get a SoundFont by name, <a class="el" href="synth_8h.html#a38d8dc2f680024ce927f01424c13d32b" title="Select an instrument on a MIDI channel by SoundFont name, bank and program numbers.">fluid_synth_program_select_by_sfont_name()</a> to select an instrument by SoundFont name/bank/program, <a class="el" href="synth_8h.html#a14386a2821c1f6d253fd2d53a21c3b98" title="Set a SoundFont generator (effect) value on a MIDI channel in real-time.">fluid_synth_set_gen2()</a> for specifying additional parameters when assigning a generator value, <a class="el" href="synth_8h.html#a28f34d0493b102ac4b99c021257b5b5e" title="Process a MIDI SYSEX (system exclusive) message.">fluid_synth_sysex()</a> for sending SYSEX messages to the synth and <a class="el" href="synth_8h.html#a5d6f71e63f60df1a83e8490a867d8910" title="Get current number of active voices.">fluid_synth_get_active_voice_count()</a> to get the current number of active synthesis voices.</li>
<li>Miscellaneous additions: <a class="el" href="midi_8h.html#af8343daaeb32ed1bd5bcc4c0be00c2fc" title="Enable looping of a MIDI player.">fluid_player_set_loop()</a> to set playlist loop count and <a class="el" href="midi_8h.html#ad9b5bd5dcacaa1c967275f537e2add26" title="Get MIDI player status.">fluid_player_get_status()</a> to get current player state.</li>
</ul>
<h2><a class="anchor" id="CreatingSettings"></a>
Creating and changing the settings</h2>
<p>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.</p>
<p>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 <a class="el" href="settings_8h.html#a855e6038c9946b206156eb1947746032" title="Set a string value for a named setting.">fluid_settings_setstr()</a>, <a class="el" href="settings_8h.html#a2a31fd030256303d4076df5abdd603e7" title="Set a numeric value for a named setting.">fluid_settings_setnum()</a>, and <a class="el" href="settings_8h.html#a26e4192ab084382492589f2c5d8b2e2f" title="Set an integer value for a setting.">fluid_settings_setint()</a> functions. For example:</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include <<a class="code" href="fluidsynth_8h.html" title="FluidSynth is a real-time synthesizer designed for SoundFont(R) files.">fluidsynth.h</a>></span>
<span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span>** argv)
{
<a class="code" href="types_8h.html#aa363402d3c77333b0f070ba531d034ba" title="Configuration settings instance.">fluid_settings_t</a>* settings = <a class="code" href="settings_8h.html#ad7ab9269a28c2b5852d512ffe3546949" title="Create a new settings object.">new_fluid_settings</a>();
fluid_synth_setint(settings, <span class="stringliteral">"synth.polyphony"</span>, 128);
<span class="comment">/* ... */</span>
<a class="code" href="settings_8h.html#a550270f09e4f3c645cbe9e6d3c514ca4" title="Delete the provided settings object.">delete_fluid_settings</a>(settings);
<span class="keywordflow">return</span> 0;
}
</pre></div><p>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 <a class="el" href="settings_8h.html" title="Synthesizer settings.">settings.h</a> API documentation for a description of all functions.</p>
<h2><a class="anchor" id="CreatingSynth"></a>
Creating the synthesizer</h2>
<p>To create the synthesizer, you pass it the settings object, as in the following example:</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include <<a class="code" href="fluidsynth_8h.html" title="FluidSynth is a real-time synthesizer designed for SoundFont(R) files.">fluidsynth.h</a>></span>
<span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span>** argv)
{
<a class="code" href="types_8h.html#aa363402d3c77333b0f070ba531d034ba" title="Configuration settings instance.">fluid_settings_t</a>* settings;
<a class="code" href="types_8h.html#ae265f10ae174a13afe010de50d87e1a4" title="Synthesizer instance.">fluid_synth_t</a>* synth;
settings = <a class="code" href="settings_8h.html#ad7ab9269a28c2b5852d512ffe3546949" title="Create a new settings object.">new_fluid_settings</a>();
synth = <a class="code" href="synth_8h.html#a344f7369c0f57d30f72702d0c88e6178" title="Create new FluidSynth instance.">new_fluid_synth</a>(settings);
<span class="comment">/* Do useful things here */</span>
<a class="code" href="synth_8h.html#a585a63f3a25b9df17b82ae87f2d38cfc" title="Delete a FluidSynth instance.">delete_fluid_synth</a>(synth);
<a class="code" href="settings_8h.html#a550270f09e4f3c645cbe9e6d3c514ca4" title="Delete the provided settings object.">delete_fluid_settings</a>(settings);
<span class="keywordflow">return</span> 0;
}
</pre></div><p>The following table provides details on all the settings used by the synthesizer.</p>
<table border="1" cellspacing="0">
<caption align="bottom">Table 1. Synthesizer settings</caption>
<tr>
<td>synth.audio-channels </td><td>Type </td><td>integer </td></tr>
<tr>
<td></td><td>Default </td><td>1 </td></tr>
<tr>
<td></td><td>Min-Max </td><td>1-128 </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">By default, the synthesizer outputs a single stereo signal. Using this option, the synthesizer can output multichannel audio. Sets the number of stereo channel pairs. So 1 is actually 2 channels (a stereo pair). </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.audio-groups </td><td>Type </td><td>integer </td></tr>
<tr>
<td></td><td>Default </td><td>1 </td></tr>
<tr>
<td></td><td>Min-Max </td><td>1-128 </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Normally the same value as synth.audio-channels. LADSPA effects subsystem can use this value though, in which case it may differ. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.chorus.active </td><td>Type </td><td>boolean </td></tr>
<tr>
<td></td><td>Default </td><td>1 (TRUE) </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">When set to 1 (TRUE) the chorus effects module is activated. Otherwise, no chorus will be added to the output signal. Note that the amount of signal sent to the chorus module depends on the "chorus send" generator defined in the SoundFont. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.cpu-cores </td><td>Type </td><td>integer </td></tr>
<tr>
<td></td><td>Default </td><td>1 </td></tr>
<tr>
<td></td><td>Min-Max </td><td>1-256 </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">(Experimental) Sets the number of synthesis CPU cores. If set to a value greater than 1, then additional synthesis threads will be created to take advantage of a multi CPU or CPU core system. This has the affect of utilizing more of the total CPU for voices or decreasing render times when synthesizing audio to a file. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.device-id </td><td>Type </td><td>integer </td></tr>
<tr>
<td></td><td>Default </td><td>0 </td></tr>
<tr>
<td></td><td>Min-Max </td><td>0-126 </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Device identifier used for SYSEX commands, such as MIDI Tuning Standard commands. Only those SYSEX commands destined for this ID or to all devices will be acted upon. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.dump </td><td>Type </td><td>boolean </td></tr>
<tr>
<td></td><td>Default </td><td>0 (FALSE) </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Does nothing currently. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.effects-channels </td><td>Type </td><td>integer </td></tr>
<tr>
<td></td><td>Default </td><td>2 </td></tr>
<tr>
<td></td><td>Min-Max </td><td>2-2 </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd"></p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.gain </td><td>Type </td><td>number </td></tr>
<tr>
<td></td><td>Default </td><td>0.2 </td></tr>
<tr>
<td></td><td>Min-Max </td><td>0.0-10.0 </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">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 many notes are played. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.ladspa.active </td><td>Type </td><td>boolean </td></tr>
<tr>
<td></td><td>Default </td><td>0 (FALSE) </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">When set to "yes" the LADSPA subsystem will be enabled. This subsystem allows to load and interconnect LADSPA plug-ins. 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. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.midi-channels </td><td>Type </td><td>integer </td></tr>
<tr>
<td></td><td>Default </td><td>16 </td></tr>
<tr>
<td></td><td>Min-Max </td><td>16-256 </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">This setting defines the number of MIDI channels of the synthesizer. The MIDI standard defines 16 channels, so MIDI hardware is limited to this number. Internally FluidSynth can use more channels which can be mapped to different MIDI sources. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.midi-bank-select </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>gs </td></tr>
<tr>
<td></td><td>Options </td><td>gm, gs, xg, mma </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">This setting defines how the synthesizer interprets Bank Select messages. </p>
<ul>
<li>
gm: ignores CC0 and CC32 messages. </li>
<li>
gs: (default) CC0 becomes the bank number, CC32 is ignored. </li>
<li>
xg: CC32 becomes the bank number, CC0 is ignored. </li>
<li>
mma: bank is calculated as CC0*128+CC32. </li>
</ul>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.min-note-length </td><td>Type </td><td>integer </td></tr>
<tr>
<td></td><td>Default </td><td>10 </td></tr>
<tr>
<td></td><td>Min-Max </td><td>0-65535 </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Sets the minimum note duration in milliseconds. This ensures that really short duration note events, such as percussion notes, have a better chance of sounding as intended. Set to 0 to disable this feature. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.parallel-render </td><td>Type </td><td>boolean </td></tr>
<tr>
<td></td><td>Default </td><td>1 (TRUE) </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">synth.parallel-render is the low-latency setting. If on, you're allowed to call fluid_synth_write_s16, fluid_synth_write_float, fluid_synth_nwrite_float or fluid_synth_process in parallel with the rest of the calls, and it won't be blocked by time intensive calls to the synth. Turn it off if throughput is more important than latency, e g in rendering-to-file scenarios where underruns is not an issue. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.polyphony </td><td>Type </td><td>integer </td></tr>
<tr>
<td></td><td>Default </td><td>256 </td></tr>
<tr>
<td></td><td>Min-Max </td><td>1-65535 </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">The polyphony defines how many voices can be played in parallel. A note event produces one or more voices. Its good to set this to a value which the system can handle and will thus limit FluidSynth's CPU usage. When FluidSynth runs out of voices it will begin terminating lower priority voices for new note events. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.reverb.active </td><td>Type </td><td>boolean </td></tr>
<tr>
<td></td><td>Default </td><td>1 (TRUE) </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">When set to 1 (TRUE) the reverb effects module is activated. Otherwise, no reverb will be added to the output signal. Note that the amount of signal sent to the reverb module depends on the "reverb send" generator defined in the SoundFont. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.sample-rate </td><td>Type </td><td>number </td></tr>
<tr>
<td></td><td>Default </td><td>44100 </td></tr>
<tr>
<td></td><td>Min-Max </td><td>22050-96000 </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">The sample rate of the audio generated by the synthesizer. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.threadsafe-api </td><td>Type </td><td>boolean </td></tr>
<tr>
<td></td><td>Default </td><td>1 (TRUE) </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">synth.threadsafe-api controls whether the synth's public API is protected by a mutex or not. Default is on, turn it off for slightly better performance if you know you're only accessing the synth from one thread only, this could be the case in many embedded use cases for example. Note that libfluidsynth can use many threads by itself (shell is one, midi driver is one, midi player is one etc) so you should usually leave it on. Also see synth.parallel-render. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>synth.verbose </td><td>Type </td><td>boolean </td></tr>
<tr>
<td></td><td>Default </td><td>0 (FALSE) </td></tr>
<tr>
<td></td><td>Description </td><td>When set to 1 (TRUE) the synthesizer will print out information about the received MIDI events to the stdout. This can be helpful for debugging. This setting cannot be changed after the synthesizer has started. </td></tr>
</table>
<h2><a class="anchor" id="CreatingAudioDriver"></a>
Creating the Audio Driver</h2>
<p>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.</p>
<p>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.</p>
<ul>
<li>jack: JACK Audio Connection Kit (Linux, Mac OS X, Windows)</li>
<li>alsa: Advanced Linux Sound Architecture (Linux)</li>
<li>oss: Open Sound System (Linux, Unix)</li>
<li>pulseaudio: PulseAudio (Linux, Mac OS X, Windows)</li>
<li>coreaudio: Apple CoreAudio (Mac OS X)</li>
<li>dsound: Microsoft DirectSound (Windows)</li>
<li>portaudio: PortAudio Library (Mac OS 9 & X, Windows, Linux)</li>
<li>sndman: Apple SoundManager (Mac OS Classic)</li>
<li>dart: DART sound driver (OS/2)</li>
<li><a href="file:">file:</a> Driver to output audio to a file</li>
</ul>
<p>The default audio driver depends on the settings with which FluidSynth was compiled. You can get the default driver with <a class="el" href="settings_8h.html#a9cfe000758040d2115c071b47d0fb8a2" title="Get the default value of a string setting.">fluid_settings_getstr_default()</a>. To get the list of available drivers use the <a class="el" href="settings_8h.html#aa9d54c924145af95e66a695230b8df71" title="Iterate the available options for a named string setting, calling the provided callback function for ...">fluid_settings_foreach_option()</a> function. Finally, you can set the driver with <a class="el" href="settings_8h.html#a855e6038c9946b206156eb1947746032" title="Set a string value for a named setting.">fluid_settings_setstr()</a>. In most cases, the default driver should work out of the box.</p>
<p>Additional options that define the audio quality and latency are "audio.sample-format", "audio.period-size", and "audio.periods". The details are described later.</p>
<p>You create the audio driver with the <a class="el" href="audio_8h.html#a4ad51317b10b89bfe94ade5db345864b" title="Create a new audio driver.">new_fluid_audio_driver()</a> function. This function takes the settings and synthesizer object as arguments. For example:</p>
<div class="fragment"><pre class="fragment"><span class="keywordtype">void</span> init()
{
<a class="code" href="types_8h.html#aa363402d3c77333b0f070ba531d034ba" title="Configuration settings instance.">fluid_settings_t</a>* settings;
<a class="code" href="types_8h.html#ae265f10ae174a13afe010de50d87e1a4" title="Synthesizer instance.">fluid_synth_t</a>* synth;
<a class="code" href="types_8h.html#ac3706330ce49cac5b7dd079e90d376d8" title="Audio driver instance.">fluid_audio_driver_t</a>* adriver;
settings = <a class="code" href="settings_8h.html#ad7ab9269a28c2b5852d512ffe3546949" title="Create a new settings object.">new_fluid_settings</a>();
<span class="comment">/* Set the synthesizer settings, if necessary */</span>
synth = <a class="code" href="synth_8h.html#a344f7369c0f57d30f72702d0c88e6178" title="Create new FluidSynth instance.">new_fluid_synth</a>(settings);
<a class="code" href="settings_8h.html#a855e6038c9946b206156eb1947746032" title="Set a string value for a named setting.">fluid_settings_setstr</a>(settings, <span class="stringliteral">"audio.driver"</span>, <span class="stringliteral">"jack"</span>);
adriver = <a class="code" href="audio_8h.html#a4ad51317b10b89bfe94ade5db345864b" title="Create a new audio driver.">new_fluid_audio_driver</a>(settings, synth);
}
</pre></div><p>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.</p>
<p>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 which are documented in another table.</p>
<table border="1" cellspacing="0">
<caption align="bottom">Table 2. General audio driver settings</caption>
<tr>
<td>audio.driver </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>jack (Linux), dsound (Windows), sndman (MacOS9), coreaudio (Mac OS X), dart (OS/2) </td></tr>
<tr>
<td></td><td>Options </td><td>jack, alsa, oss, pulseaudio, coreaudio, dsound, portaudio, sndman, dart, file </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">The audio system to be used. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.periods </td><td>Type </td><td>int </td></tr>
<tr>
<td></td><td>Default </td><td>16 (Linux, Mac OS X), 8 (Windows) </td></tr>
<tr>
<td></td><td>Min-Max </td><td>2-64 </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">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. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.period-size </td><td>Type </td><td>integer </td></tr>
<tr>
<td></td><td>Default </td><td>64 (Linux, Mac OS X), 512 (Windows) </td></tr>
<tr>
<td></td><td>Min-Max </td><td>64-8192 </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">The size of the audio buffers (in frames). </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.realtime-prio </td><td>Type </td><td>integer </td></tr>
<tr>
<td></td><td>Default </td><td>60 </td></tr>
<tr>
<td></td><td>Min-Max </td><td>0-99 </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Sets the realtime scheduling priority of the audio synthesis thread (0 disables high priority scheduling). Linux is the only platform which currently makes use of different priority levels. Drivers which use this option: alsa, oss and pulseaudio </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.sample-format </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>"16bits" </td></tr>
<tr>
<td></td><td>Options </td><td>"16bits", "float" </td></tr>
<tr>
<td></td><td>Description </td><td>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. </td></tr>
</table>
<p>The following table describes audio driver specific settings.</p>
<table border="1" cellspacing="0">
<caption align="bottom">Table 3. Audio driver specific settings</caption>
<tr>
<td>audio.alsa.device </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>"default" </td></tr>
<tr>
<td></td><td>Options </td><td>ALSA device string, such as: "hw:0", "plughw:1", etc. </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Selects the ALSA audio device to use. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.coreaudio.device </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>"default" </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Selects the CoreAudio device to use. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.dart.device </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>"default" </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Selects the Dart (OS/2 driver) device to use. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.dsound.device </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>"default" </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Selects the DirectSound (Windows) device to use. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.file.endian </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>'auto' if libsndfile support is built in, 'cpu' otherwise. </td></tr>
<tr>
<td></td><td>Options </td><td>auto, big, cpu, little ('cpu' is all that is supported if libsndfile support is not built in) </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Defines the byte order when using the 'file' driver or file renderer to store audio to a file. 'auto' uses the default for the given file type, 'cpu' uses the CPU byte order, 'big' uses big endian byte order and 'little' uses little endian byte order. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.file.format </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>s16 </td></tr>
<tr>
<td></td><td>Options </td><td>double, float, s16, s24, s32, s8, u8 ('s16' is all that is supported if libsndfile support not built in) </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Defines the audio format when rendering audio to a file. 'double' is 64 bit floating point, 'float' is 32 bit floating point, 's16' is 16 bit signed PCM, 's24' is 24 bit signed PCM, 's32' is 32 bit signed PCM, 's8' is 8 bit signed PCM and 'u8' is 8 bit unsigned PCM. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.file.name </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>'fluidsynth.wav' if libsndfile support is built in, 'fluidsynth.raw' otherwise. </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Specifies the file name to store the audio to, when rendering audio to a file. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.file.type </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>'auto' if libsndfile support is built in, 'raw' otherwise. </td></tr>
<tr>
<td></td><td>Options </td><td>aiff, au, auto, avr, caf, flac, htk, iff, mat, oga, paf, pvf, raw, sd2, sds, sf, voc, w64, wav, xi (actual list of types may vary and depends on the libsndfile library used, 'raw' is the only type available if no libsndfile support is built in). </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Sets the file type of the file which the audio will be stored to. 'auto' attempts to determine the file type from the audio.file.name file extension and falls back to 'wav' if the extension doesn't match any types. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.jack.autoconnect </td><td>Type </td><td>boolean </td></tr>
<tr>
<td></td><td>Default </td><td>0 (FALSE) </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">If 1 (TRUE), then FluidSynth output is automatically connected to jack system audio output. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.jack.id </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>fluidsynth </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">ID used when creating Jack client connection. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.jack.multi </td><td>Type </td><td>boolean </td></tr>
<tr>
<td></td><td>Default </td><td>0 (FALSE) </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">If 1 (TRUE), then multi-channel Jack output will be enabled if synth.audio-channels is greater than 1. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.jack.server </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td></td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Jack server to connect to. Defaults to an empty string, which uses default Jack server. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.oss.device </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>/dev/dsp </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Device to use for OSS audio output. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.portaudio.device </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>PortAudio Default </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Device to use for PortAudio driver output. Note that 'PortAudio Default' is a special value which outputs to the default PortAudio device. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.pulseaudio.device </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>"default" </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Device to use for PulseAudio driver output </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>audio.pulseaudio.server </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>"default" </td></tr>
<tr>
<td></td><td>Description </td><td>Server to use for PulseAudio driver output </td></tr>
</table>
<h2><a class="anchor" id="UsingSynth"></a>
Using the synthesizer without an audio driver</h2>
<p>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:</p>
<p><a class="el" href="synth_8h.html#a0d7c287342eb282d4ec63ea7f35cd791" title="Synthesize a block of 16 bit audio samples to audio buffers.">fluid_synth_write_s16()</a> fills two buffers (left and right channel) with samples coded as signed 16 bits (the endian-ness is machine dependent). <a class="el" href="synth_8h.html#ac86a79a943fc5d5d485ccc5a5fcad03d" title="Synthesize a block of floating point audio samples to audio buffers.">fluid_synth_write_float()</a> fills a left and right audio buffer with 32 bits floating point samples. For multi channel audio output, the function <a class="el" href="synth_8h.html#a2e394b30908133eed97fe903d5654bac" title="Synthesize a block of floating point audio to audio buffers.">fluid_synth_nwrite_float()</a> has to be used.</p>
<p>The function <a class="el" href="synth_8h.html#a1ac90e2732aa652679305f78cbd66670" title="Synthesize floating point audio to audio buffers.">fluid_synth_process()</a> is still experimental and its use is therefore not recommended but it will probably become the generic interface in future versions.</p>
<h2><a class="anchor" id="LoadingSoundfonts"></a>
Loading and managing SoundFonts</h2>
<p>Before any sound can be produced, the synthesizer needs a SoundFont.</p>
<p>SoundFonts are loaded with the <a class="el" href="synth_8h.html#aaf9376cf7189f9c64da5ffdeed85c9c4" title="Load a SoundFont file (filename is interpreted by SoundFont loaders).">fluid_synth_sfload()</a> 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.</p>
<p>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 <a class="el" href="synth_8h.html#ac783362b155fc9c3997f7fd3cf9b1d7f" title="Select an instrument on a MIDI channel by SoundFont ID, bank and program numbers.">fluid_synth_program_select()</a> can be used for unambiguously selecting a preset or bank offsets could be applied to each SoundFont with <a class="el" href="synth_8h.html#a8b533b00ff0884d3a2bb3f61abfe7682" title="Offset the bank numbers of a loaded SoundFont.">fluid_synth_set_bank_offset()</a>, to try and ensure that each preset has unique bank and program numbers.</p>
<p>The <a class="el" href="synth_8h.html#aaf9376cf7189f9c64da5ffdeed85c9c4" title="Load a SoundFont file (filename is interpreted by SoundFont loaders).">fluid_synth_sfload()</a> function returns the unique identifier of the loaded SoundFont, or -1 in case of an error. This identifier is used in subsequent management functions: <a class="el" href="synth_8h.html#a212bb602e9022c8d8cdb4bc5957f7693" title="Unload a SoundFont.">fluid_synth_sfunload()</a> removes the SoundFont, <a class="el" href="synth_8h.html#a578273544b162af97633430b5c9b23ae" title="Reload a SoundFont.">fluid_synth_sfreload()</a> reloads the SoundFont. When a SoundFont is reloaded, it retains it's ID and position on the SoundFont stack.</p>
<p>Additional API functions are provided to get the number of loaded SoundFonts and to get a pointer to the SoundFont.</p>
<h2><a class="anchor" id="SendingMIDI"></a>
Sending MIDI Events</h2>
<p>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 <a class="el" href="synth_8h.html#a4a98222fe1c36bfd598dc4cd89f4b75c" title="Send a note-on event to a FluidSynth object.">fluid_synth_noteon()</a>, <a class="el" href="synth_8h.html#a5e8f96cacbc6460f7677a6191cbd4472" title="Send a note-off event to a FluidSynth object.">fluid_synth_noteoff()</a>, <a class="el" href="synth_8h.html#a96b535f5acee6f807033d6cc9ccab555" title="Send a MIDI controller event on a MIDI channel.">fluid_synth_cc()</a>, <a class="el" href="synth_8h.html#ad5341f8e7c86835b197628f84a2d2c90" title="Set the MIDI pitch bend controller value on a MIDI channel.">fluid_synth_pitch_bend()</a>, <a class="el" href="synth_8h.html#adb4df1ba450816d42ef40a16b2993549" title="Set MIDI pitch wheel sensitivity on a MIDI channel.">fluid_synth_pitch_wheel_sens()</a>, and <a class="el" href="synth_8h.html#aad8df89a90669268b6bee09da40088a6" title="Send a program change event on a MIDI channel.">fluid_synth_program_change()</a> functions. For convenience, there's also a <a class="el" href="synth_8h.html#a97b0f45f00922a46b1c1961d5b1f8cb5" title="Set instrument bank number on a MIDI channel.">fluid_synth_bank_select()</a> function (the bank select message is normally sent using a control change message).</p>
<p>The following example show a generic graphical button that plays a note when clicked:</p>
<div class="fragment"><pre class="fragment"><span class="keyword">class </span>SoundButton : <span class="keyword">public</span> SomeButton
{
<span class="keyword">public</span>:
SoundButton() : SomeButton() {
<span class="keywordflow">if</span> (!_synth) {
initSynth();
}
}
<span class="keyword">static</span> <span class="keywordtype">void</span> initSynth() {
_settings = <a class="code" href="settings_8h.html#ad7ab9269a28c2b5852d512ffe3546949" title="Create a new settings object.">new_fluid_settings</a>();
_synth = <a class="code" href="synth_8h.html#a344f7369c0f57d30f72702d0c88e6178" title="Create new FluidSynth instance.">new_fluid_synth</a>(_settings);
_adriver = <a class="code" href="audio_8h.html#a4ad51317b10b89bfe94ade5db345864b" title="Create a new audio driver.">new_fluid_audio_driver</a>(_settings, _synth);
}
<span class="comment">/* ... */</span>
<span class="keyword">virtual</span> <span class="keywordtype">int</span> handleMouseDown(<span class="keywordtype">int</span> x, <span class="keywordtype">int</span> y) {
<span class="comment">/* Play a note on key 60 with velocity 100 on MIDI channel 0 */</span>
<a class="code" href="synth_8h.html#a4a98222fe1c36bfd598dc4cd89f4b75c" title="Send a note-on event to a FluidSynth object.">fluid_synth_noteon</a>(_synth, 0, 60, 100);
}
<span class="keyword">virtual</span> <span class="keywordtype">int</span> handleMouseUp(<span class="keywordtype">int</span> x, <span class="keywordtype">int</span> y) {
<span class="comment">/* Release the note on key 60 */</span>
<a class="code" href="synth_8h.html#a5e8f96cacbc6460f7677a6191cbd4472" title="Send a note-off event to a FluidSynth object.">fluid_synth_noteoff</a>(_synth, 0, 60);
}
<span class="keyword">protected</span>:
<span class="keyword">static</span> <a class="code" href="types_8h.html#aa363402d3c77333b0f070ba531d034ba" title="Configuration settings instance.">fluid_settings_t</a>* _settings;
<span class="keyword">static</span> <a class="code" href="types_8h.html#ae265f10ae174a13afe010de50d87e1a4" title="Synthesizer instance.">fluid_synth_t</a>* _synth;
<span class="keyword">static</span> <a class="code" href="types_8h.html#ac3706330ce49cac5b7dd079e90d376d8" title="Audio driver instance.">fluid_audio_driver_t</a>* _adriver;
};
</pre></div><h2><a class="anchor" id="RealtimeMIDI"></a>
Creating a Real-time MIDI Driver</h2>
<p>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 <a class="el" href="midi_8h.html#ad0971af69fb51398d468b151cba70bee" title="Create a new MIDI driver instance.">new_fluid_midi_driver()</a> function providing a callback function that will be invoked when a MIDI event is received. The following MIDI drivers are currently supported:</p>
<ul>
<li>jack: JACK Audio Connection Kit MIDI driver (Linux, Mac OS X)</li>
<li>oss: Open Sound System raw MIDI (Linux, Unix)</li>
<li>alsa_raw: ALSA raw MIDI interface (Linux)</li>
<li>alsa_seq: ALSA sequencer MIDI interface (Linux)</li>
<li>winmidi: Microsoft Windows MM System (Windows)</li>
<li>midishare: MIDI Share (Linux, Mac OS X)</li>
<li>coremidi: Apple CoreMIDI (Mac OS X)</li>
</ul>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include <<a class="code" href="fluidsynth_8h.html" title="FluidSynth is a real-time synthesizer designed for SoundFont(R) files.">fluidsynth.h</a>></span>
<span class="keywordtype">int</span> handle_midi_event(<span class="keywordtype">void</span>* data, <a class="code" href="types_8h.html#a61c72b76e3ee344637994c3071f74d94" title="MIDI event.">fluid_midi_event_t</a>* event)
{
printf(<span class="stringliteral">"event type: %d\n"</span>, <a class="code" href="midi_8h.html#a63c2b0009873e8a1761f3a3365b12244" title="Get the event type field of a MIDI event structure.">fluid_midi_event_get_type</a>(event));
}
<span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span>** argv)
{
<a class="code" href="types_8h.html#aa363402d3c77333b0f070ba531d034ba" title="Configuration settings instance.">fluid_settings_t</a>* settings;
<a class="code" href="types_8h.html#ab0f64d7ed81d7361e9600e4a480828df" title="MIDI driver instance.">fluid_midi_driver_t</a>* mdriver;
settings = <a class="code" href="settings_8h.html#ad7ab9269a28c2b5852d512ffe3546949" title="Create a new settings object.">new_fluid_settings</a>();
mdriver = <a class="code" href="midi_8h.html#ad0971af69fb51398d468b151cba70bee" title="Create a new MIDI driver instance.">new_fluid_midi_driver</a>(settings, handle_midi_event, NULL);
<span class="comment">/* ... */</span>
<a class="code" href="midi_8h.html#afe4c8e3657f654edde69e89ea87784eb" title="Delete a MIDI driver instance.">delete_fluid_midi_driver</a>(mdriver);
<span class="keywordflow">return</span> 0;
}
</pre></div><p>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, which are described in a following table.</p>
<table border="1" cellspacing="0">
<caption align="bottom">Table 4. General MIDI driver settings</caption>
<tr>
<td>midi.driver </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>alsa_seq (Linux), winmidi (Windows), jack (Mac OS X) </td></tr>
<tr>
<td></td><td>Options </td><td>alsa_raw, alsa_seq, coremidi, jack, midishare, oss, winmidi </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">The MIDI system to be used. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>midi.realtime-prio </td><td>Type </td><td>integer </td></tr>
<tr>
<td></td><td>Default </td><td>50 </td></tr>
<tr>
<td></td><td>Min-Max </td><td>0-99 </td></tr>
<tr>
<td></td><td>Description </td><td>Sets the realtime scheduling priority of the MIDI thread (0 disables high priority scheduling). Linux is the only platform which currently makes use of different priority levels. Drivers which use this option: alsa_raw, alsa_seq, oss </td></tr>
</table>
<p>The following table defines MIDI driver specific settings.</p>
<table border="1" cellspacing="0">
<caption align="bottom">Table 5. MIDI driver specific settings</caption>
<tr>
<td>midi.alsa.device </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>"default" </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">ALSA MIDI device to use for RAW ALSA MIDI driver. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>midi.alsa_seq.device </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>"default" </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">ALSA sequencer device to use for ALSA sequencer driver. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>midi.alsa_seq.id </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>pid </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">ID to use when registering ports with the ALSA sequencer driver. If set to "pid" then the ID will be "FLUID Synth (PID)", where PID is the FluidSynth process ID of the audio thread otherwise the provided string will be used in place of PID. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>midi.jack.id </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>fluidsynth-midi </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Client ID to use with the Jack MIDI driver. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>midi.jack.server </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td></td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Jack server to connect to for Jack MIDI driver. If an empty string then the default server will be used. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>midi.oss.device </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td>/dev/midi </td></tr>
<tr>
<td></td><td>Description </td><td><p class="starttd">Device to use for OSS MIDI driver. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>midi.portname </td><td>Type </td><td>string </td></tr>
<tr>
<td></td><td>Default </td><td></td></tr>
<tr>
<td></td><td>Description </td><td>Used by coremidi and alsa_seq drivers for the portnames registered with the MIDI subsystem. </td></tr>
</table>
<h2><a class="anchor" id="MIDIPlayer"></a>
Loading and Playing a MIDI file</h2>
<p>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 <a class="el" href="midi_8h.html#a6a8628edc77c83c6865fde4b1c296773" title="Create a new MIDI player.">new_fluid_player()</a>. Then, you can add some SMF file names to the player using <a class="el" href="midi_8h.html#a1ac5b59e4ab9d0f48e917dda0a9a4403" title="Add a MIDI file to a player queue.">fluid_player_add()</a>, and finally call <a class="el" href="midi_8h.html#a5ac629c8667dbf4eba2cf75d72e134e0" title="Activates play mode for a MIDI player if not already playing.">fluid_player_play()</a> to start the playback. You can check if the player has finished by calling <a class="el" href="midi_8h.html#ad9b5bd5dcacaa1c967275f537e2add26" title="Get MIDI player status.">fluid_player_get_status()</a>, or wait for the player to terminate using <a class="el" href="midi_8h.html#a78a49a72e02c2aafe41687dc3a59f533" title="Wait for a MIDI player to terminate (when done playing).">fluid_player_join()</a>.</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include <<a class="code" href="fluidsynth_8h.html" title="FluidSynth is a real-time synthesizer designed for SoundFont(R) files.">fluidsynth.h</a>></span>
<span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span>** argv)
{
<span class="keywordtype">int</span> i;
<a class="code" href="types_8h.html#aa363402d3c77333b0f070ba531d034ba" title="Configuration settings instance.">fluid_settings_t</a>* settings;
<a class="code" href="types_8h.html#ae265f10ae174a13afe010de50d87e1a4" title="Synthesizer instance.">fluid_synth_t</a>* synth;
<a class="code" href="types_8h.html#af6c718e19d8c9c6632cb8ffac6974d80" title="MIDI player instance.">fluid_player_t</a>* player;
<a class="code" href="types_8h.html#ac3706330ce49cac5b7dd079e90d376d8" title="Audio driver instance.">fluid_audio_driver_t</a>* adriver;
settings = <a class="code" href="settings_8h.html#ad7ab9269a28c2b5852d512ffe3546949" title="Create a new settings object.">new_fluid_settings</a>();
synth = <a class="code" href="synth_8h.html#a344f7369c0f57d30f72702d0c88e6178" title="Create new FluidSynth instance.">new_fluid_synth</a>(settings);
player = <a class="code" href="midi_8h.html#a6a8628edc77c83c6865fde4b1c296773" title="Create a new MIDI player.">new_fluid_player</a>(synth);
adriver = <a class="code" href="audio_8h.html#a4ad51317b10b89bfe94ade5db345864b" title="Create a new audio driver.">new_fluid_audio_driver</a>(settings, synth);
<span class="comment">/* process command line arguments */</span>
<span class="keywordflow">for</span> (i = 1; i < argc; i++) {
<span class="keywordflow">if</span> (<a class="code" href="misc_8h.html#a09b28945cdc794f1f9b5c8edb34fcd6e" title="Check if a file is a SoundFont file.">fluid_is_soundfont</a>(argv[i])) {
<a class="code" href="synth_8h.html#aaf9376cf7189f9c64da5ffdeed85c9c4" title="Load a SoundFont file (filename is interpreted by SoundFont loaders).">fluid_synth_sfload</a>(synth, argv[1], 1);
}
<span class="keywordflow">if</span> (<a class="code" href="misc_8h.html#abf08bf4bb750d787d551559471069fdf" title="Check if a file is a MIDI file.">fluid_is_midifile</a>(argv[i])) {
<a class="code" href="midi_8h.html#a1ac5b59e4ab9d0f48e917dda0a9a4403" title="Add a MIDI file to a player queue.">fluid_player_add</a>(player, argv[i]);
}
}
<span class="comment">/* play the midi files, if any */</span>
<a class="code" href="midi_8h.html#a5ac629c8667dbf4eba2cf75d72e134e0" title="Activates play mode for a MIDI player if not already playing.">fluid_player_play</a>(player);
<span class="comment">/* wait for playback termination */</span>
<a class="code" href="midi_8h.html#a78a49a72e02c2aafe41687dc3a59f533" title="Wait for a MIDI player to terminate (when done playing).">fluid_player_join</a>(player);
<span class="comment">/* cleanup */</span>
<a class="code" href="audio_8h.html#a05678e633d37da0f93000045393e9442" title="Deletes an audio driver instance.">delete_fluid_audio_driver</a>(adriver);
<a class="code" href="midi_8h.html#a678a3d103532b86dada3d2cd111fed0a" title="Delete a MIDI player instance.">delete_fluid_player</a>(player);
<a class="code" href="synth_8h.html#a585a63f3a25b9df17b82ae87f2d38cfc" title="Delete a FluidSynth instance.">delete_fluid_synth</a>(synth);
<a class="code" href="settings_8h.html#a550270f09e4f3c645cbe9e6d3c514ca4" title="Delete the provided settings object.">delete_fluid_settings</a>(settings);
<span class="keywordflow">return</span> 0;
}
</pre></div><p>Settings which the MIDI player uses are documented below.</p>
<table border="1" cellspacing="0">
<caption align="bottom">Table 6. General MIDI driver settings</caption>
<tr>
<td>player.reset-synth </td><td>type </td><td>boolean </td></tr>
<tr>
<td></td><td>default </td><td>1 (TRUE) </td></tr>
<tr>
<td></td><td>description </td><td><p class="starttd">If true, reset the synth before starting a new MIDI song, so the state of a previous song can't affect the new song. Turn it off for seamless looping of a song. </p>
<p class="endtd"></p>
</td></tr>
<tr>
<td>player.timing-source </td><td>type </td><td>string </td></tr>
<tr>
<td></td><td>default </td><td>'sample' </td></tr>
<tr>
<td></td><td>options </td><td>'sample', 'system' </td></tr>
<tr>
<td></td><td>description </td><td>Determines the timing source of the player sequencer. 'sample' uses the sample clock (how much audio has been output) to sequence events, in which case audio is synchronized with MIDI events. 'system' uses the system clock, audio and MIDI are not synchronized exactly. </td></tr>
</table>
<h2><a class="anchor" id="MIDIRouter"></a>
Real-time MIDI router</h2>
<p>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.</p>
<p>Some examples of MIDI router usage:</p>
<ul>
<li>Filter messages (Example: Pass sustain pedal CCs only to selected channels)</li>
<li>Split the keyboard (Example: noteon with notenr < x: to ch 1, >x to ch 2)</li>
<li>Layer sounds (Example: for each noteon received on ch 1, create a noteon on ch1, ch2, ch3,...)</li>
<li>Velocity scaling (Example: for each noteon event, scale the velocity by 1.27)</li>
<li>Velocity switching (Example: v <= 100: "Angel Choir"; v > 100: "Hell's Bells")</li>
<li>Get rid of aftertouch</li>
</ul>
<p>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.</p>
<p>MIDI events coming from the MIDI player do not pass through the MIDI router.</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include <<a class="code" href="fluidsynth_8h.html" title="FluidSynth is a real-time synthesizer designed for SoundFont(R) files.">fluidsynth.h</a>></span>
<span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span>** argv)
{
<a class="code" href="types_8h.html#aa363402d3c77333b0f070ba531d034ba" title="Configuration settings instance.">fluid_settings_t</a>* settings;
<a class="code" href="types_8h.html#ae265f10ae174a13afe010de50d87e1a4" title="Synthesizer instance.">fluid_synth_t</a>* synth;
<a class="code" href="types_8h.html#aa57b4746220e24506a169f109875e4ad" title="MIDI router instance.">fluid_midi_router_t</a>* router;
<a class="code" href="types_8h.html#a3154253ddb8f9b8f8f737c91f5973278" title="MIDI router rule.">fluid_midi_router_rule_t</a>* rule;
settings = <a class="code" href="settings_8h.html#ad7ab9269a28c2b5852d512ffe3546949" title="Create a new settings object.">new_fluid_settings</a>();
synth = <a class="code" href="synth_8h.html#a344f7369c0f57d30f72702d0c88e6178" title="Create new FluidSynth instance.">new_fluid_synth</a>(settings);
<span class="comment">/* Create the MIDI router and pass events to the synthesizer */</span>
router = <a class="code" href="midi_8h.html#ae28ddf804fa5ba108a65c24fcf6e9813" title="Create a new midi router.">new_fluid_midi_router</a> (settings, fluid_synth_handle_midi_event, synth);
<span class="comment">/* Clear default rules */</span>
<a class="code" href="midi_8h.html#a57aed5e84828c202452e13f265dd72f7" title="Clear all rules in a MIDI router.">fluid_midi_router_clear_rules</a> (router);
<span class="comment">/* Add rule to map all notes < MIDI note #60 on any channel to channel 4 */</span>
rule = <a class="code" href="midi_8h.html#a128bc8b126cbabf7717149123815d235" title="Create a new MIDI router rule.">new_fluid_midi_router_rule</a> ();
<a class="code" href="midi_8h.html#acc264709865c1e2dc972528cca55dc6f" title="Set the channel portion of a rule.">fluid_midi_router_rule_set_chan</a> (rule, 0, 15, 0.0, 4); <span class="comment">/* Map all to channel 4 */</span>
<a class="code" href="midi_8h.html#ac4f572c218943ded7fe43692a265ddb5" title="Set the first parameter portion of a rule.">fluid_midi_router_rule_set_param1</a> (rule, 0, 59, 1.0, 0); <span class="comment">/* Match notes < 60 */</span>
<a class="code" href="midi_8h.html#aa1894a103cde4f1efe80c7c9d5096ae2" title="Add a rule to a MIDI router.">fluid_midi_router_add_rule</a> (router, rule, <a class="code" href="midi_8h.html#ab798a0a5b95607556c9ecfbeaaab962ba44d3968ac6d884210bdace219f17c684" title="MIDI note rule.">FLUID_MIDI_ROUTER_RULE_NOTE</a>);
<span class="comment">/* Add rule to map all notes >= MIDI note #60 on any channel to channel 5 */</span>
rule = <a class="code" href="midi_8h.html#a128bc8b126cbabf7717149123815d235" title="Create a new MIDI router rule.">new_fluid_midi_router_rule</a> ();
<a class="code" href="midi_8h.html#acc264709865c1e2dc972528cca55dc6f" title="Set the channel portion of a rule.">fluid_midi_router_rule_set_chan</a> (rule, 0, 15, 0.0, 5); <span class="comment">/* Map all to channel 5 */</span>
<a class="code" href="midi_8h.html#ac4f572c218943ded7fe43692a265ddb5" title="Set the first parameter portion of a rule.">fluid_midi_router_rule_set_param1</a> (rule, 60, 127, 1.0, 0); <span class="comment">/* Match notes >= 60 */</span>
<a class="code" href="midi_8h.html#aa1894a103cde4f1efe80c7c9d5096ae2" title="Add a rule to a MIDI router.">fluid_midi_router_add_rule</a> (router, rule, <a class="code" href="midi_8h.html#ab798a0a5b95607556c9ecfbeaaab962ba44d3968ac6d884210bdace219f17c684" title="MIDI note rule.">FLUID_MIDI_ROUTER_RULE_NOTE</a>);
<span class="comment">/* Add rule to reverse direction of pitch bender on channel 7 */</span>
rule = <a class="code" href="midi_8h.html#a128bc8b126cbabf7717149123815d235" title="Create a new MIDI router rule.">new_fluid_midi_router_rule</a> ();
<a class="code" href="midi_8h.html#acc264709865c1e2dc972528cca55dc6f" title="Set the channel portion of a rule.">fluid_midi_router_rule_set_chan</a> (rule, 7, 7, 1.0, 0); <span class="comment">/* Match channel 7 only */</span>
<a class="code" href="midi_8h.html#ac4f572c218943ded7fe43692a265ddb5" title="Set the first parameter portion of a rule.">fluid_midi_router_rule_set_param1</a> (rule, 0, 16383, -1.0, 16383); <span class="comment">/* Reverse pitch bender */</span>
<a class="code" href="midi_8h.html#aa1894a103cde4f1efe80c7c9d5096ae2" title="Add a rule to a MIDI router.">fluid_midi_router_add_rule</a> (router, rule, <a class="code" href="midi_8h.html#ab798a0a5b95607556c9ecfbeaaab962ba087309f49bb501d67d74a9d5a128e621" title="MIDI pitch bend rule.">FLUID_MIDI_ROUTER_RULE_PITCH_BEND</a>);
<span class="comment">/* ... Create audio driver, process events, etc ... */</span>
<span class="comment">/* cleanup */</span>
<a class="code" href="midi_8h.html#a48f3cd2fcebc5f80c8a9ce43973b9fdc" title="Delete a MIDI router instance.">delete_fluid_midi_router</a>(router);
<a class="code" href="synth_8h.html#a585a63f3a25b9df17b82ae87f2d38cfc" title="Delete a FluidSynth instance.">delete_fluid_synth</a>(synth);
<a class="code" href="settings_8h.html#a550270f09e4f3c645cbe9e6d3c514ca4" title="Delete the provided settings object.">delete_fluid_settings</a>(settings);
<span class="keywordflow">return</span> 0;
}
</pre></div><h2><a class="anchor" id="Sequencer"></a>
Sequencer</h2>
<p>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.</p>
<p>The client program should first initialize the sequencer instance using the function <a class="el" href="seq_8h.html#a3c27499606024a92bca0b32dbcf72c44" title="Create a new sequencer object.">new_fluid_sequencer2()</a>. There is a complementary function <a class="el" href="seq_8h.html#a57d2277b188240e435b5fc3f39c0bc7e" title="Free a sequencer object.">delete_fluid_sequencer()</a> to delete it. After creating the sequencer instance, the destinations can be registered using <a class="el" href="seqbind_8h.html#a3680e34efa6745fcbe851fcd802cba39" title="Registers a synthesizer as a destination client of the given sequencer.">fluid_sequencer_register_fluidsynth()</a> for the synthesizer destination, and optionally using <a class="el" href="seq_8h.html#a749882ab2b9ce51fa6a265db2cd59915" title="Register a sequencer client.">fluid_sequencer_register_client()</a> for the client destination providing a suitable callback function. It can be unregistered using <a class="el" href="seq_8h.html#afca860d8580b2c19b2340ca4e9432e19" title="Unregister a previously registered client.">fluid_sequencer_unregister_client()</a>. After the initialization, events can be sent with <a class="el" href="seq_8h.html#ac6c0346378a9ce531ec428747dbe16fe" title="Send an event immediately.">fluid_sequencer_send_now()</a> and scheduled to the future with <a class="el" href="seq_8h.html#afb0c62f3a2cff3decbf628535f4511ef" title="Schedule an event for sending at a later time.">fluid_sequencer_send_at()</a>. The registration functions return identifiers, that can be used as destinations of an event using <a class="el" href="event_8h.html#ae0857e30ffdcfe4e277eb3c55df7ba32" title="Set destination of a sequencer event (DOCME).">fluid_event_set_dest()</a>.</p>
<p>The function <a class="el" href="seq_8h.html#a2a51cf34c359020eb6c9b7ab549ab239" title="Get the current tick of a sequencer.">fluid_sequencer_get_tick()</a> returns the current playing position. A program may choose a new timescale in milliseconds using <a class="el" href="seq_8h.html#aa62f856223ff035fcfca2517facc3205" title="Set the time scale of a sequencer.">fluid_sequencer_set_time_scale()</a>.</p>
<p>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.</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include "<a class="code" href="fluidsynth_8h.html" title="FluidSynth is a real-time synthesizer designed for SoundFont(R) files.">fluidsynth.h</a>"</span>
<a class="code" href="types_8h.html#ae265f10ae174a13afe010de50d87e1a4" title="Synthesizer instance.">fluid_synth_t</a>* synth;
<a class="code" href="types_8h.html#ac3706330ce49cac5b7dd079e90d376d8" title="Audio driver instance.">fluid_audio_driver_t</a>* adriver;
<a class="code" href="types_8h.html#a7c7acad4ee620fc954a7ad4d7e87e1c3" title="Sequencer instance.">fluid_sequencer_t</a>* sequencer;
<span class="keywordtype">short</span> synthSeqID, mySeqID;
<span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> now;
<span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> seqduration;
<span class="comment">// prototype</span>
<span class="keywordtype">void</span> seq_callback(<span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> time, <a class="code" href="types_8h.html#aca09348be1b6e6ee7fce49dd4734f1ba" title="Sequencer event.">fluid_event_t</a>* event, <a class="code" href="types_8h.html#a7c7acad4ee620fc954a7ad4d7e87e1c3" title="Sequencer instance.">fluid_sequencer_t</a>* seq, <span class="keywordtype">void</span>* data);
<span class="keywordtype">void</span> createsynth()
{
<a class="code" href="types_8h.html#aa363402d3c77333b0f070ba531d034ba" title="Configuration settings instance.">fluid_settings_t</a>* settings;
settings = <a class="code" href="settings_8h.html#ad7ab9269a28c2b5852d512ffe3546949" title="Create a new settings object.">new_fluid_settings</a>();
<a class="code" href="settings_8h.html#a855e6038c9946b206156eb1947746032" title="Set a string value for a named setting.">fluid_settings_setstr</a>(settings, <span class="stringliteral">"synth.reverb.active"</span>, <span class="stringliteral">"yes"</span>);
<a class="code" href="settings_8h.html#a855e6038c9946b206156eb1947746032" title="Set a string value for a named setting.">fluid_settings_setstr</a>(settings, <span class="stringliteral">"synth.chorus.active"</span>, <span class="stringliteral">"no"</span>);
synth = <a class="code" href="synth_8h.html#a344f7369c0f57d30f72702d0c88e6178" title="Create new FluidSynth instance.">new_fluid_synth</a>(settings);
adriver = <a class="code" href="audio_8h.html#a4ad51317b10b89bfe94ade5db345864b" title="Create a new audio driver.">new_fluid_audio_driver</a>(settings, synth);
sequencer = <a class="code" href="seq_8h.html#a3c27499606024a92bca0b32dbcf72c44" title="Create a new sequencer object.">new_fluid_sequencer2</a>(0);
<span class="comment">// register synth as first destination</span>
synthSeqID = <a class="code" href="seqbind_8h.html#a3680e34efa6745fcbe851fcd802cba39" title="Registers a synthesizer as a destination client of the given sequencer.">fluid_sequencer_register_fluidsynth</a>(sequencer, synth);
<span class="comment">// register myself as second destination</span>
mySeqID = <a class="code" href="seq_8h.html#a749882ab2b9ce51fa6a265db2cd59915" title="Register a sequencer client.">fluid_sequencer_register_client</a>(sequencer, <span class="stringliteral">"me"</span>, seq_callback, NULL);
<span class="comment">// the sequence duration, in ms</span>
seqduration = 1000;
}
<span class="keywordtype">void</span> deletesynth()
{
<a class="code" href="seq_8h.html#a57d2277b188240e435b5fc3f39c0bc7e" title="Free a sequencer object.">delete_fluid_sequencer</a>(sequencer);
<a class="code" href="audio_8h.html#a05678e633d37da0f93000045393e9442" title="Deletes an audio driver instance.">delete_fluid_audio_driver</a>(adriver);
<a class="code" href="synth_8h.html#a585a63f3a25b9df17b82ae87f2d38cfc" title="Delete a FluidSynth instance.">delete_fluid_synth</a>(synth);
}
<span class="keywordtype">void</span> loadsoundfont()
{
<span class="keywordtype">int</span> fluid_res;
<span class="comment">// put your own path here</span>
fluid_res = <a class="code" href="synth_8h.html#aaf9376cf7189f9c64da5ffdeed85c9c4" title="Load a SoundFont file (filename is interpreted by SoundFont loaders).">fluid_synth_sfload</a>(synth, <span class="stringliteral">"Inside:VintageDreamsWaves-v2.sf2"</span>, 1);
}
<span class="keywordtype">void</span> sendnoteon(<span class="keywordtype">int</span> chan, <span class="keywordtype">short</span> key, <span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> date)
{
<span class="keywordtype">int</span> fluid_res;
<a class="code" href="types_8h.html#aca09348be1b6e6ee7fce49dd4734f1ba" title="Sequencer event.">fluid_event_t</a> *evt = <a class="code" href="event_8h.html#a1d535480f26630b755102415a6d246cb" title="Create a new sequencer event structure.">new_fluid_event</a>();
<a class="code" href="event_8h.html#a22e7fc6d5ce4ca9eab6dd6d60c85d78b" title="Set source of a sequencer event (DOCME).">fluid_event_set_source</a>(evt, -1);
<a class="code" href="event_8h.html#ae0857e30ffdcfe4e277eb3c55df7ba32" title="Set destination of a sequencer event (DOCME).">fluid_event_set_dest</a>(evt, synthSeqID);
<a class="code" href="event_8h.html#a1337c75403ebf9c43607a3f3139c6bba" title="Set a sequencer event to be a note on event.">fluid_event_noteon</a>(evt, chan, key, 127);
fluid_res = <a class="code" href="seq_8h.html#afb0c62f3a2cff3decbf628535f4511ef" title="Schedule an event for sending at a later time.">fluid_sequencer_send_at</a>(sequencer, evt, date, 1);
<a class="code" href="event_8h.html#a473c54f0c43bdea789b211c23c7daeee" title="Delete a sequencer event structure.">delete_fluid_event</a>(evt);
}
<span class="keywordtype">void</span> schedule_next_callback()
{
<span class="keywordtype">int</span> fluid_res;
<span class="comment">// I want to be called back before the end of the next sequence</span>
<span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> callbackdate = now + seqduration/2;
<a class="code" href="types_8h.html#aca09348be1b6e6ee7fce49dd4734f1ba" title="Sequencer event.">fluid_event_t</a> *evt = <a class="code" href="event_8h.html#a1d535480f26630b755102415a6d246cb" title="Create a new sequencer event structure.">new_fluid_event</a>();
<a class="code" href="event_8h.html#a22e7fc6d5ce4ca9eab6dd6d60c85d78b" title="Set source of a sequencer event (DOCME).">fluid_event_set_source</a>(evt, -1);
<a class="code" href="event_8h.html#ae0857e30ffdcfe4e277eb3c55df7ba32" title="Set destination of a sequencer event (DOCME).">fluid_event_set_dest</a>(evt, mySeqID);
<a class="code" href="event_8h.html#aa99a8c9110e819b53fc42baa0bfd8fbf" title="Set a sequencer event to be a timer event.">fluid_event_timer</a>(evt, NULL);
fluid_res = <a class="code" href="seq_8h.html#afb0c62f3a2cff3decbf628535f4511ef" title="Schedule an event for sending at a later time.">fluid_sequencer_send_at</a>(sequencer, evt, callbackdate, 1);
<a class="code" href="event_8h.html#a473c54f0c43bdea789b211c23c7daeee" title="Delete a sequencer event structure.">delete_fluid_event</a>(evt);
}
<span class="keywordtype">void</span> schedule_next_sequence() {
<span class="comment">// Called more or less before each sequence start</span>
<span class="comment">// the next sequence start date</span>
now = now + seqduration;
<span class="comment">// the sequence to play</span>
<span class="comment">// the beat : 2 beats per sequence</span>
sendnoteon(0, 60, now + seqduration/2);
sendnoteon(0, 60, now + seqduration);
<span class="comment">// melody</span>
sendnoteon(1, 45, now + seqduration/10);
sendnoteon(1, 50, now + 4*seqduration/10);
sendnoteon(1, 55, now + 8*seqduration/10);
<span class="comment">// so that we are called back early enough to schedule the next sequence</span>
schedule_next_callback();
}
<span class="comment">/* sequencer callback */</span>
<span class="keywordtype">void</span> seq_callback(<span class="keywordtype">unsigned</span> <span class="keywordtype">int</span> time, <a class="code" href="types_8h.html#aca09348be1b6e6ee7fce49dd4734f1ba" title="Sequencer event.">fluid_event_t</a>* event, <a class="code" href="types_8h.html#a7c7acad4ee620fc954a7ad4d7e87e1c3" title="Sequencer instance.">fluid_sequencer_t</a>* seq, <span class="keywordtype">void</span>* data) {
schedule_next_sequence();
}
<span class="keywordtype">int</span> main(<span class="keywordtype">void</span>) {
createsynth();
loadsoundfont();
<span class="comment">// initialize our absolute date</span>
now = <a class="code" href="seq_8h.html#a2a51cf34c359020eb6c9b7ab549ab239" title="Get the current tick of a sequencer.">fluid_sequencer_get_tick</a>(sequencer);
schedule_next_sequence();
sleep(100000);
deletesynth();
<span class="keywordflow">return</span> 0;
}
</pre></div><h2><a class="anchor" id="Shell"></a>
Shell interface</h2>
<p>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.</p>
<table border="1" cellspacing="0">
<caption align="bottom">Table 7. General MIDI driver settings</caption>
<tr>
<td>shell.prompt </td><td>type </td><td>string </td></tr>
<tr>
<td></td><td>default </td><td>"" </td></tr>
<tr>
<td></td><td>description </td><td>In dump mode we set the prompt to "". the ui cannot easily handle lines, which don't end with cr. changing the prompt cannot be done through a command, because the current shell does not handle empty arguments. </td></tr>
<tr>
<td>shell.port </td><td>type </td><td>number </td></tr>
<tr>
<td></td><td>default </td><td>9800 </td></tr>
<tr>
<td></td><td>min-max </td><td>1-65535 </td></tr>
<tr>
<td></td><td>description </td><td>The shell can be used in a client/server mode. This setting controls what TCP/IP port the server uses. </td></tr>
</table>
<h2><a class="anchor" id="Advanced"></a>
Advanced features, not yet documented. API reference may contain more info.</h2>
<ul>
<li>Accessing low-level voice parameters</li>
<li>Reverb settings</li>
<li>Chorus settings</li>
<li>Interpolation settings (set_gen, get_gen, NRPN)</li>
<li>Voice overflow settings</li>
<li>LADSPA effects unit</li>
<li>Multi-channel audio</li>
<li>MIDI tunings</li>
<li>Fast file renderer for rendering audio to file in non-realtime </li>
</ul>
</div>
<hr class="footer"/><address class="footer"><small>Generated on Tue Oct 12 2010 for libfluidsynth by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.1 </small></address>
</body>
</html>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
0a2d1da5078620d6abbc0a5e920f2a92
>
files
>
64
