diff --git a/fluidsynth/doc/fluidsynth-v10-devdoc.xml b/fluidsynth/doc/fluidsynth-v10-devdoc.xml index 9c818bf5..5772df13 100644 --- a/fluidsynth/doc/fluidsynth-v10-devdoc.xml +++ b/fluidsynth/doc/fluidsynth-v10-devdoc.xml @@ -2,8 +2,7 @@
- FluidSynth - Developer Documentation + FluidSynth 1.0 - Developer Documentation @@ -25,15 +24,42 @@ SoundFont 2 specifications. The synthesizer is available as a shared object that can easily be reused in any application that wants to use wavetable synthesis. This documents explains the - nitty-gritty. + basic usage of FluidSynth. Some of the more advanced features + are not yet discussed but will be added in future + versions. - + Using the synthesizer as a plugin - FluidSynth can easily be embedded in an application. + FluidSynth can easily be embedded in an application. It has + a main header file, fluidsynth.h, and one dynamically linkable + library. FluidSynth runs on Linux, MacOS 9, MacOS X, and the Win32 + platforms. It has audio and midi drivers for all mentioned + platforms but you can use it with your own drivers if your + application already handles audio and MIDI IO. This document + explains the basic usage of FluidSynth and provides and example + that you can reuse. + + + + + + License + + All the source code examples in this document are in the + public domain; you can use it as you please. This document is + licensed under the Creative Commons Attribution License. To view a + copy of this license, visit + http://creativecommons.org/licenses/by/1.0/ or send a letter to + Creative Commons, 559 Nathan Abbott Way, Stanford, California + 94305, USA. FluidSynth 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, write to + the Free Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA + 02111-1307 USA. @@ -46,9 +72,8 @@ FluidSynth library. It gives a unified API to set the parameters of the audio drivers, the midi drivers, the synthesizer, andsoforth. A number of default settings are defined by the - current implementation. In future versions the use of the settings - will probably be generalized and used also for LADSPA plugins. - + current implementation. In future versions, the use of the + settings will probably be generalized. All settings have a name that follows the "dotted-name" @@ -61,12 +86,16 @@ fluid_synth_setint functions. For example: -void init() +#include <fluidsynth.h> + +int main(int argc, char** argv) { - fluid_settings_t* settings; - - settings = new_fluid_settings(); + fluid_settings_t* settings = new_fluid_settings(); + fluid_synth_setint(settings, "synth.polyphony", 128); + + delete_fluid_settings(settings); + return 0; } @@ -74,7 +103,7 @@ void init() The API contains the functions to query the type, the current - value, the default value, the range and and the "hints" of a + value, the default value, the range and the "hints" of a setting. The range is the minumum and maximum value of the setting. The hints gives additional information about a setting. For example, whether a string represents a filename. Or @@ -89,20 +118,26 @@ void init() Creating the synthesizer - To create the synthesizer, you pass it the settings object, like + To create the synthesizer, you pass it the settings object, as in the following example: -void init() +#include <fluidsynth.h> + +int main(int argc, char** argv) { fluid_settings_t* settings; fluid_synth_t* synth; - - settings = new_fluid_settings(); - - /* Set the settings, if necessary */ + + fluid_settings_t* settings = new_fluid_settings(); synth = new_fluid_synth(settings); + + /* Do useful things here */ + + delete_fluid_synth(synth); + delete_fluid_settings(settings); + return 0; } @@ -111,34 +146,294 @@ void init() The default settings should be fine for most uses. A detailed description of all the settings used by the synthesizer described below. - +Synthesizer settings + + + + + + synth.gain + Type + number + + + + Default + 0.2 + + + + Min-Max + 0.0-10.0 + + + + Description + The gain is applied to the final or master output of the +synthesizer. It is set to a low value by default to avoid the +saturation of the output when random MIDI files are played. + + + + + synth.sample-rate + Type + number + + + + Default + 44100 + + + + Min-Max + 22050-96000 + + + + Description + The sample rate of the audio generated by the synthesizer. + + + + + synth.polyphony + Type + integer + + + + Default + 256 + + + + Min-Max + 16-4096 + + + + Description + The polyphony defines how many voices can be played in parallel. The +number of voices is not necessarily equivalent to the number of notes +played simultaniously. Indeed, when a note is struck on a specific +MIDI channel, the preset on that channel may created several voices, +for example, one for the left audio channel and one for the right +audio channels. The number of voices activated depends on the number +of instrument zones that fall in the correspond to the velocity and +key of the played note. + + + + + synth.midi-channels + Type + integer + + + + Default + 16 + + + + Min-Max + 16-256 + + + + Description + This setting defines the number of MIDI channels of the +synthesizer. The MIDI standard defines 16 channels, so most hardware +keyboards are limited to 16. If you plan to use the synthesizer as a +plugin in an application, it might be interesting to set the number of +channels to a larger value. In this case you can program a greater +number of presets. + + + + + synth.reverb.active + Type + string + + + + Default + "yes" + + + + Description + When set to "yes" the reverb effects module is activated. Otherwise, +no reverb will be added to the output signal. Note that when the +reverb module is active, the amount of signal send to the reverb +module depends on the "reverb send" generator defined in the +SoundFont. + + + + + synth.chorus.active + Type + string + + + + Default + "yes" + + + + Description + When set to "yes" the chorus effects module is activated. Otherwise, +no chorus will be added to the output signal. Note that when the +reverb module is active, the amount of signal send to the chorus +module depends on the "chorus send" generator defined in the +SoundFont. + + + + + synth.ladspa.active + Type + string + + + + Default + "no" + + + + Description + When set to "yes" the LADSPA subsystem will be called. This subsystem +allows to load and interconnect LADSPA plugins. The output of the +synthesizer is processed by the LADSPA subsystem. Note that the +synthesizer has to be compiled with LADSPA support. More information +about the LADSPA subsystem later. + + + + + synth.audio-groups + Type + integer + + + + Default + 1 + + + + Min-Max + 1-128 + + + + Description + By default, the synthesizer outputs a single stereo signal. Using this +option, the synthesizer can output multichannel audio. + + + + + synth.effects-channels + Type + integer + + + + Default + 2 + + + + Min-Max + 2-2 + + + + Description + + + + + + synth.verbose + Type + string + + + + Default + "no" + + + + Description + + When set to "yes" the synthesizer will print out information + about the received MIDI events to the stdout. This can be helpful + for debugging. This setting can not be changed after the synthesizer + has started. + + + + + + synth.dump + Type + string + + + + Default + "no" + + + + Description + + + + + +
+ + + Creating the audio driver - The synthesizer itself does not send any audio to the audio - output. This allows application developers who want to integrate - the synthesizer in their application to manage the audio output - themselves. The following sections describes the use of the - synthesizer without an audio driver in more detail. + 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 libraries, you may want to change what - audio subsystem you want to use. Currently the following audio - systems are supported: - + support for several audio systems, you may want to change which + one you want to use. The list below shows theaudio systems that + are currently supported. It displays the name, as used by the + fluidsynth library, and a description. - Linux: OSS, ALSA, Jack, PortAudio (not tested) - MacOS Classic: SoundManager, PortAudio - MacOS X: PortAudio, CoreAudio (experimental) - Windows: DirectSound, PortAudio (not tested) + alsa: Advanced Linux Sound Architecture + oss: Open Sound System (Linux) + jack: JACK Audio Connection Kit (Linux, Mac OS X) + portaudio: Portaudio Library (MacOS 9 & X, Windows, Linux) + sndmgr: Apple SoundManager (Mac OS Classic) + coreaudio: Apple CoreAudio (MacOS X, experimental) + dsound: Microsoft DirectSound (Windows) @@ -190,6 +485,120 @@ void init() synthesizer object to generate the audio. + + + There are a number of general audio driver settings. The + audio.driver settings defines the audio subsystem that will be + used. The audio.periods and audio.period-size settings define the + latency and robustness against scheduling delays. There are + additional settings for the audio subsystems used. They will be + documented later. + + +General audio driver settings + + + + + + audio.driver + Type + string + + + + Default + alsa (Linux), dsound (Windows), sndman (MacOS9), coreaudio (MacOS X) + + + + Options + alsa, oss, jack, dsound, sndman, coreaudio, portaudio + + + + Description + The audio system to be used. + + + + + audio.periods + Type + int + + + + Default + 16 (Linux, MacOS X), 8 (Windows) + + + + Min-Max + 2-64 + + + + Description + The number of the audio buffers used by the driver. This + number of buffers, multiplied by the buffer size (see setting + audio.period-size), determines the maximum latency of the audio + driver. + + + + + audio.period-size + Type + int + + + + Default + 64 (Linux, MacOS X), 512 (Windows) + + + + Min-Max + 64-8192 + + + + Description + The size of the audio buffers (in frames). + + + + + audio.sample-format + Type + string + + + + Default + "16bits" + + + + Options + "16bits", "float" + + + + Description + + The format of the audio samples. This is currently only an + indication; the audio driver may ignore this setting if it can't + handle the specified format. + + + + + +
+ + @@ -370,133 +779,21 @@ protected: - Advanced control features - - + Advanced features, not yet documented - - MIDI tunings - - - - - Multi channel audio output - - - - - Overview of all settings - - - The settings for the synthesizer - - - -synth.verbose: type string, default "no" - -When set to "yes" the synthesizer will print out information about the -received MIDI events to the stdout. This can be helpful for -debugging. This setting can not be changed after the synthesizer has -started. - -synth.dump: type string, default "no" - -??? - - -synth.reverb.active: type string, default "yes" - -When set to "yes" the reverb effects module is activated. Otherwise, -no reverb will be added to the output signal. Note that when the -reverb module is active, the amount of signal send to the reverb -module depends on the "reverb send" generator defined in the -SoundFont. - -synth.chorus.active: type string, default "yes" - -When set to "yes" the chorus effects module is activated. Otherwise, -no chorus will be added to the output signal. Note that when the -reverb module is active, the amount of signal send to the chorus -module depends on the "chorus send" generator defined in the -SoundFont. - - -synth.ladspa.active: type string, default no - -When set to "yes" the LADSPA subsystem will be called. This subsystem -allows to load and interconnect LADSPA plugins. The output of the -synthesizer is processed by the LADSPA subsystem. Note that the -synthesizer has to be compiled with LADSPA support. More information -about the LADSPA subsystem later. - - -synth.polyphony: type integer, default 256, min. 16, max. 4096 - -The polyphony defines how many voices can be played in parallel. The -number of voices is not necessarily equivalent to the number of notes -played simultaniously. Indeed, when a note is struck on a specific -MIDI channel, the preset on that channel may created several voices, -for example, one for the left audio channel and one for the right -audio channels. The number of voices activated depends on the number -of instrument zones that fall in the correspond to the velocity and -key of the played note. - -synth.midi-channels: type integer, default 16, min. 16, max. 256 - -This setting defines the number of MIDI channels of the -synthesizer. The MIDI standard defines 16 channels, so most hardware -keyboards are limited to 16. If you plan to use the synthesizer as a -plugin in an application, it might be interesting to set the number of -channels to a larger value. In this case you can program a greater -number of presets. - -synth.gain: type number, default 0.2, min. 0.0, max. 10.0 - -The gain is applied to the final or master output of the -synthesizer. It is set to a low value by default to avoid the -saturation of the output when random MIDI files are played. - -synth.audio-channels: type integer, default 1, min. 1, max. 128 - -By default, the synthesizer outputs a single stereo signal. Using this -option, the synthesizer can output multichannel audio. - -synth.audio-groups", 1, 1, 128, 0, NULL, NULL); -synth.effects-channels", 2, 2, 2, 0, NULL, NULL); -synth.sample-rate", 44100.0f, 22050.0f, 96000.0f, - - -The settings for the audio driver - -audio.sample-format: type string, default "16bits", options ("16bits", "float") - -audio.period-size: type integer, default 512, min. 64, max. 8192 - -audio.periods: type integer, default 8, min. 2, max. 64 - -audio.output-channels: type integer, default 2, min. 2, max. 32 - -audio.input-channels: type integer, default 0, min. 0, max. 2 - -audio.driver: type string, default platform and compilation dependent - - - -SoundFont: - -Preset: - -Preset Zone: - -Instrument: - -Instrument Zone: - -Program: - -MIDI Channel: - - + +Accessing low-level voice parameters +Reverb settings +Chorus settings +Interpolation settings (set_gen, get_gen, NRPN) +Sequencer +LADSPA effects unit +MIDI router +Multi-channel audio +MIDI tunings +MIDI file player +SoundFont loader +