Update Fluidsynth to 2.0.1
[ardour.git] / libs / fluidsynth / fluidsynth / synth.h
1 /* FluidSynth - A Software Synthesizer
2  *
3  * Copyright (C) 2003  Peter Hanappe and others.
4  *
5  * This library is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU Lesser General Public License
7  * as published by the Free Software Foundation; either version 2.1 of
8  * the License, or (at your option) any later version.
9  *
10  * This library is distributed in the hope that it will be useful, but
11  * WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13  * Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public
16  * License along with this library; if not, write to the Free
17  * Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
18  * 02110-1301, USA
19  */
20
21 #ifndef _FLUIDSYNTH_SYNTH_H
22 #define _FLUIDSYNTH_SYNTH_H
23
24
25 #ifdef __cplusplus
26 extern "C" {
27 #endif
28
29
30 /**
31  * @file synth.h
32  * @brief Embeddable SoundFont synthesizer
33  *
34  * You create a new synthesizer with new_fluid_synth() and you destroy
35  * if with delete_fluid_synth(). Use the settings structure to specify
36  * the synthesizer characteristics.
37  *
38  * You have to load a SoundFont in order to hear any sound. For that
39  * you use the fluid_synth_sfload() function.
40  *
41  * You can use the audio driver functions described below to open
42  * the audio device and create a background audio thread.
43  *
44  * The API for sending MIDI events is probably what you expect:
45  * fluid_synth_noteon(), fluid_synth_noteoff(), ...
46  */
47
48
49 FLUIDSYNTH_API fluid_synth_t *new_fluid_synth(fluid_settings_t *settings);
50 FLUIDSYNTH_API void delete_fluid_synth(fluid_synth_t *synth);
51 FLUIDSYNTH_API fluid_settings_t *fluid_synth_get_settings(fluid_synth_t *synth);
52
53 /* MIDI channel messages */
54
55 FLUIDSYNTH_API int fluid_synth_noteon(fluid_synth_t *synth, int chan, int key, int vel);
56 FLUIDSYNTH_API int fluid_synth_noteoff(fluid_synth_t *synth, int chan, int key);
57 FLUIDSYNTH_API int fluid_synth_cc(fluid_synth_t *synth, int chan, int ctrl, int val);
58 FLUIDSYNTH_API int fluid_synth_get_cc(fluid_synth_t *synth, int chan, int ctrl, int *pval);
59 FLUIDSYNTH_API int fluid_synth_sysex(fluid_synth_t *synth, const char *data, int len,
60                                      char *response, int *response_len, int *handled, int dryrun);
61 FLUIDSYNTH_API int fluid_synth_pitch_bend(fluid_synth_t *synth, int chan, int val);
62 FLUIDSYNTH_API int fluid_synth_get_pitch_bend(fluid_synth_t *synth, int chan, int *ppitch_bend);
63 FLUIDSYNTH_API int fluid_synth_pitch_wheel_sens(fluid_synth_t *synth, int chan, int val);
64 FLUIDSYNTH_API int fluid_synth_get_pitch_wheel_sens(fluid_synth_t *synth, int chan, int *pval);
65 FLUIDSYNTH_API int fluid_synth_program_change(fluid_synth_t *synth, int chan, int program);
66 FLUIDSYNTH_API int fluid_synth_channel_pressure(fluid_synth_t *synth, int chan, int val);
67 FLUIDSYNTH_API int fluid_synth_key_pressure(fluid_synth_t *synth, int chan, int key, int val);
68 FLUIDSYNTH_API int fluid_synth_bank_select(fluid_synth_t *synth, int chan, int bank);
69 FLUIDSYNTH_API int fluid_synth_sfont_select(fluid_synth_t *synth, int chan, int sfont_id);
70 FLUIDSYNTH_API
71 int fluid_synth_program_select(fluid_synth_t *synth, int chan, int sfont_id,
72                                int bank_num, int preset_num);
73 FLUIDSYNTH_API int
74 fluid_synth_program_select_by_sfont_name(fluid_synth_t *synth, int chan,
75         const char *sfont_name, int bank_num,
76         int preset_num);
77 FLUIDSYNTH_API
78 int fluid_synth_get_program(fluid_synth_t *synth, int chan, int *sfont_id,
79                             int *bank_num, int *preset_num);
80 FLUIDSYNTH_API int fluid_synth_unset_program(fluid_synth_t *synth, int chan);
81 FLUIDSYNTH_API int fluid_synth_program_reset(fluid_synth_t *synth);
82 FLUIDSYNTH_API int fluid_synth_system_reset(fluid_synth_t *synth);
83
84 FLUIDSYNTH_API int fluid_synth_all_notes_off(fluid_synth_t *synth, int chan);
85 FLUIDSYNTH_API int fluid_synth_all_sounds_off(fluid_synth_t *synth, int chan);
86
87 /**
88  * The midi channel type used by fluid_synth_set_channel_type()
89  */
90 enum fluid_midi_channel_type
91 {
92     CHANNEL_TYPE_MELODIC = 0, /**< Melodic midi channel */
93     CHANNEL_TYPE_DRUM = 1 /**< Drum midi channel */
94 };
95
96 FLUIDSYNTH_API int fluid_synth_set_channel_type(fluid_synth_t *synth, int chan, int type);
97
98
99 /* Low level access */
100 FLUIDSYNTH_API fluid_preset_t *fluid_synth_get_channel_preset(fluid_synth_t *synth, int chan);
101 FLUIDSYNTH_API int fluid_synth_start(fluid_synth_t *synth, unsigned int id,
102                                      fluid_preset_t *preset, int audio_chan,
103                                      int midi_chan, int key, int vel);
104 FLUIDSYNTH_API int fluid_synth_stop(fluid_synth_t *synth, unsigned int id);
105
106
107 /* SoundFont management */
108
109 FLUIDSYNTH_API
110 int fluid_synth_sfload(fluid_synth_t *synth, const char *filename, int reset_presets);
111 FLUIDSYNTH_API int fluid_synth_sfreload(fluid_synth_t *synth, int id);
112 FLUIDSYNTH_API int fluid_synth_sfunload(fluid_synth_t *synth, int id, int reset_presets);
113 FLUIDSYNTH_API int fluid_synth_add_sfont(fluid_synth_t *synth, fluid_sfont_t *sfont);
114 FLUIDSYNTH_API int fluid_synth_remove_sfont(fluid_synth_t *synth, fluid_sfont_t *sfont);
115 FLUIDSYNTH_API int fluid_synth_sfcount(fluid_synth_t *synth);
116 FLUIDSYNTH_API fluid_sfont_t *fluid_synth_get_sfont(fluid_synth_t *synth, unsigned int num);
117 FLUIDSYNTH_API fluid_sfont_t *fluid_synth_get_sfont_by_id(fluid_synth_t *synth, int id);
118 FLUIDSYNTH_API fluid_sfont_t *fluid_synth_get_sfont_by_name(fluid_synth_t *synth,
119         const char *name);
120 FLUIDSYNTH_API int fluid_synth_set_bank_offset(fluid_synth_t *synth, int sfont_id, int offset);
121 FLUIDSYNTH_API int fluid_synth_get_bank_offset(fluid_synth_t *synth, int sfont_id);
122
123
124 /* Reverb  */
125
126
127 FLUIDSYNTH_API int fluid_synth_set_reverb(fluid_synth_t *synth, double roomsize,
128         double damping, double width, double level);
129 FLUIDSYNTH_API int fluid_synth_set_reverb_roomsize(fluid_synth_t *synth, double roomsize);
130 FLUIDSYNTH_API int fluid_synth_set_reverb_damp(fluid_synth_t *synth, double damping);
131 FLUIDSYNTH_API int fluid_synth_set_reverb_width(fluid_synth_t *synth, double width);
132 FLUIDSYNTH_API int fluid_synth_set_reverb_level(fluid_synth_t *synth, double level);
133
134 FLUIDSYNTH_API void fluid_synth_set_reverb_on(fluid_synth_t *synth, int on);
135 FLUIDSYNTH_API double fluid_synth_get_reverb_roomsize(fluid_synth_t *synth);
136 FLUIDSYNTH_API double fluid_synth_get_reverb_damp(fluid_synth_t *synth);
137 FLUIDSYNTH_API double fluid_synth_get_reverb_level(fluid_synth_t *synth);
138 FLUIDSYNTH_API double fluid_synth_get_reverb_width(fluid_synth_t *synth);
139
140
141 /* Chorus */
142
143 /**
144  * Chorus modulation waveform type.
145  */
146 enum fluid_chorus_mod
147 {
148     FLUID_CHORUS_MOD_SINE = 0,            /**< Sine wave chorus modulation */
149     FLUID_CHORUS_MOD_TRIANGLE = 1         /**< Triangle wave chorus modulation */
150 };
151
152 FLUIDSYNTH_API int fluid_synth_set_chorus(fluid_synth_t *synth, int nr, double level,
153         double speed, double depth_ms, int type);
154 FLUIDSYNTH_API int fluid_synth_set_chorus_nr(fluid_synth_t *synth, int nr);
155 FLUIDSYNTH_API int fluid_synth_set_chorus_level(fluid_synth_t *synth, double level);
156 FLUIDSYNTH_API int fluid_synth_set_chorus_speed(fluid_synth_t *synth, double speed);
157 FLUIDSYNTH_API int fluid_synth_set_chorus_depth(fluid_synth_t *synth, double depth_ms);
158 FLUIDSYNTH_API int fluid_synth_set_chorus_type(fluid_synth_t *synth, int type);
159
160 FLUIDSYNTH_API void fluid_synth_set_chorus_on(fluid_synth_t *synth, int on);
161 FLUIDSYNTH_API int fluid_synth_get_chorus_nr(fluid_synth_t *synth);
162 FLUIDSYNTH_API double fluid_synth_get_chorus_level(fluid_synth_t *synth);
163 FLUIDSYNTH_API double fluid_synth_get_chorus_speed(fluid_synth_t *synth);
164 FLUIDSYNTH_API double fluid_synth_get_chorus_depth(fluid_synth_t *synth);
165 FLUIDSYNTH_API int fluid_synth_get_chorus_type(fluid_synth_t *synth); /* see fluid_chorus_mod */
166
167
168 /* Audio and MIDI channels */
169
170 FLUIDSYNTH_API int fluid_synth_count_midi_channels(fluid_synth_t *synth);
171 FLUIDSYNTH_API int fluid_synth_count_audio_channels(fluid_synth_t *synth);
172 FLUIDSYNTH_API int fluid_synth_count_audio_groups(fluid_synth_t *synth);
173 FLUIDSYNTH_API int fluid_synth_count_effects_channels(fluid_synth_t *synth);
174 FLUIDSYNTH_API int fluid_synth_count_effects_groups(fluid_synth_t *synth);
175
176
177 /* Synthesis parameters */
178
179 FLUIDSYNTH_API void fluid_synth_set_sample_rate(fluid_synth_t *synth, float sample_rate);
180 FLUIDSYNTH_API void fluid_synth_set_gain(fluid_synth_t *synth, float gain);
181 FLUIDSYNTH_API float fluid_synth_get_gain(fluid_synth_t *synth);
182 FLUIDSYNTH_API int fluid_synth_set_polyphony(fluid_synth_t *synth, int polyphony);
183 FLUIDSYNTH_API int fluid_synth_get_polyphony(fluid_synth_t *synth);
184 FLUIDSYNTH_API int fluid_synth_get_active_voice_count(fluid_synth_t *synth);
185 FLUIDSYNTH_API int fluid_synth_get_internal_bufsize(fluid_synth_t *synth);
186
187 FLUIDSYNTH_API
188 int fluid_synth_set_interp_method(fluid_synth_t *synth, int chan, int interp_method);
189
190 /**
191  * Synthesis interpolation method.
192  */
193 enum fluid_interp
194 {
195     FLUID_INTERP_NONE = 0,        /**< No interpolation: Fastest, but questionable audio quality */
196     FLUID_INTERP_LINEAR = 1,      /**< Straight-line interpolation: A bit slower, reasonable audio quality */
197     FLUID_INTERP_4THORDER = 4,    /**< Fourth-order interpolation, good quality, the default */
198     FLUID_INTERP_7THORDER = 7,    /**< Seventh-order interpolation */
199
200     FLUID_INTERP_DEFAULT = FLUID_INTERP_4THORDER, /**< Default interpolation method */
201     FLUID_INTERP_HIGHEST = FLUID_INTERP_7THORDER, /**< Highest interpolation method */
202 };
203
204 /* Generator interface */
205
206 FLUIDSYNTH_API int fluid_synth_set_gen(fluid_synth_t *synth, int chan,
207                                        int param, float value);
208 FLUIDSYNTH_API float fluid_synth_get_gen(fluid_synth_t *synth, int chan, int param);
209
210
211 /* Tuning */
212
213 FLUIDSYNTH_API
214 int fluid_synth_activate_key_tuning(fluid_synth_t *synth, int bank, int prog,
215                                     const char *name, const double *pitch, int apply);
216 FLUIDSYNTH_API
217 int fluid_synth_activate_octave_tuning(fluid_synth_t *synth, int bank, int prog,
218                                        const char *name, const double *pitch, int apply);
219 FLUIDSYNTH_API
220 int fluid_synth_tune_notes(fluid_synth_t *synth, int bank, int prog,
221                            int len, const int *keys, const double *pitch, int apply);
222 FLUIDSYNTH_API
223 int fluid_synth_activate_tuning(fluid_synth_t *synth, int chan, int bank, int prog,
224                                 int apply);
225 FLUIDSYNTH_API
226 int fluid_synth_deactivate_tuning(fluid_synth_t *synth, int chan, int apply);
227 FLUIDSYNTH_API void fluid_synth_tuning_iteration_start(fluid_synth_t *synth);
228 FLUIDSYNTH_API
229 int fluid_synth_tuning_iteration_next(fluid_synth_t *synth, int *bank, int *prog);
230 FLUIDSYNTH_API int fluid_synth_tuning_dump(fluid_synth_t *synth, int bank, int prog,
231         char *name, int len, double *pitch);
232
233 /* Misc */
234
235 FLUIDSYNTH_API double fluid_synth_get_cpu_load(fluid_synth_t *synth);
236 FLUIDSYNTH_API const char *fluid_synth_error(fluid_synth_t *synth);
237
238
239 /* Default modulators */
240
241 /**
242  * Enum used with fluid_synth_add_default_mod() to specify how to handle duplicate modulators.
243  */
244 enum fluid_synth_add_mod
245 {
246     FLUID_SYNTH_OVERWRITE,        /**< Overwrite any existing matching modulator */
247     FLUID_SYNTH_ADD,              /**< Add (sum) modulator amounts */
248 };
249
250 FLUIDSYNTH_API int fluid_synth_add_default_mod(fluid_synth_t *synth, const fluid_mod_t *mod, int mode);
251 FLUIDSYNTH_API int fluid_synth_remove_default_mod(fluid_synth_t *synth, const fluid_mod_t *mod);
252
253
254 /*
255  * Synthesizer plugin
256  *
257  * To create a synthesizer plugin, create the synthesizer as
258  * explained above. Once the synthesizer is created you can call
259  * any of the functions below to get the audio.
260  */
261
262 FLUIDSYNTH_API int fluid_synth_write_s16(fluid_synth_t *synth, int len,
263         void *lout, int loff, int lincr,
264         void *rout, int roff, int rincr);
265 FLUIDSYNTH_API int fluid_synth_write_float(fluid_synth_t *synth, int len,
266         void *lout, int loff, int lincr,
267         void *rout, int roff, int rincr);
268 FLUIDSYNTH_API int fluid_synth_nwrite_float(fluid_synth_t *synth, int len,
269         float **left, float **right,
270         float **fx_left, float **fx_right);
271 FLUIDSYNTH_API int fluid_synth_process(fluid_synth_t *synth, int len,
272                                        int nfx, float *fx[],
273                                        int nout, float *out[]);
274
275
276 /* Synthesizer's interface to handle SoundFont loaders */
277
278 FLUIDSYNTH_API void fluid_synth_add_sfloader(fluid_synth_t *synth, fluid_sfloader_t *loader);
279 FLUIDSYNTH_API fluid_voice_t *fluid_synth_alloc_voice(fluid_synth_t *synth,
280         fluid_sample_t *sample,
281         int channum, int key, int vel);
282 FLUIDSYNTH_API void fluid_synth_start_voice(fluid_synth_t *synth, fluid_voice_t *voice);
283 FLUIDSYNTH_API void fluid_synth_get_voicelist(fluid_synth_t *synth,
284         fluid_voice_t *buf[], int bufsize, int ID);
285 FLUIDSYNTH_API int fluid_synth_handle_midi_event(void *data, fluid_midi_event_t *event);
286
287 /**
288  * Specifies the type of filter to use for the custom IIR filter
289  */
290 enum fluid_iir_filter_type
291 {
292     FLUID_IIR_DISABLED = 0, /**< Custom IIR filter is not operating */
293     FLUID_IIR_LOWPASS, /**< Custom IIR filter is operating as low-pass filter */
294     FLUID_IIR_HIGHPASS, /**< Custom IIR filter is operating as high-pass filter */
295     FLUID_IIR_LAST /**< @internal Value defines the count of filter types (#fluid_iir_filter_type) @warning This symbol is not part of the public API and ABI stability guarantee and may change at any time! */
296 };
297
298 /**
299  * Specifies optional settings to use for the custom IIR filter
300  */
301 enum fluid_iir_filter_flags
302 {
303     FLUID_IIR_Q_LINEAR = 1 << 0, /**< The Soundfont spec requires the filter Q to be interpreted in dB. If this flag is set the filter Q is instead assumed to be in a linear range */
304     FLUID_IIR_Q_ZERO_OFF = 1 << 1, /**< If this flag the filter is switched off if Q == 0 (prior to any transformation) */
305     FLUID_IIR_NO_GAIN_AMP = 1 << 2 /**< The Soundfont spec requires to correct the gain of the filter depending on the filter's Q. If this flag is set the filter gain will not be corrected. */
306 };
307
308 FLUIDSYNTH_API int fluid_synth_set_custom_filter(fluid_synth_t *, int type, int flags);
309
310
311 /* LADSPA */
312
313 #ifdef LADSPA
314 FLUIDSYNTH_API fluid_ladspa_fx_t *fluid_synth_get_ladspa_fx(fluid_synth_t *synth);
315 #endif
316
317
318 /* API: Poly mono mode */
319
320 /** Interface to poly/mono mode variables
321  *
322  * Channel mode bits OR-ed together so that it matches with the midi spec: poly omnion (0), mono omnion (1), poly omnioff (2), mono omnioff (3)
323  */
324 enum fluid_channel_mode_flags
325 {
326     FLUID_CHANNEL_POLY_OFF = 0x01, /**< if flag is set, the basic channel is in mono on state, if not set poly is on */
327     FLUID_CHANNEL_OMNI_OFF = 0x02, /**< if flag is set, the basic channel is in omni off state, if not set omni is on */
328 };
329
330 /** Indicates the breath mode a channel is set to */
331 enum fluid_channel_breath_flags
332 {
333     FLUID_CHANNEL_BREATH_POLY = 0x10,  /**< when channel is poly, this flag indicates that the default velocity to initial attenuation modulator is replaced by a breath to initial attenuation modulator */
334     FLUID_CHANNEL_BREATH_MONO = 0x20,  /**< when channel is mono, this flag indicates that the default velocity to initial attenuation modulator is replaced by a breath modulator */
335     FLUID_CHANNEL_BREATH_SYNC = 0x40,  /**< when channel is mono, this flag indicates that the breath controler(MSB)triggers noteon/noteoff on the running note */
336 };
337
338 /** Indicates the mode a basic channel is set to */
339 enum fluid_basic_channel_modes
340 {
341     FLUID_CHANNEL_MODE_MASK = (FLUID_CHANNEL_OMNI_OFF | FLUID_CHANNEL_POLY_OFF), /**< Mask Poly and Omni bits of #fluid_channel_mode_flags, usually only used internally */
342     FLUID_CHANNEL_MODE_OMNION_POLY = FLUID_CHANNEL_MODE_MASK & (~FLUID_CHANNEL_OMNI_OFF & ~FLUID_CHANNEL_POLY_OFF), /**< corresponds to MIDI mode 0 */
343     FLUID_CHANNEL_MODE_OMNION_MONO = FLUID_CHANNEL_MODE_MASK & (~FLUID_CHANNEL_OMNI_OFF & FLUID_CHANNEL_POLY_OFF), /**< corresponds to MIDI mode 1 */
344     FLUID_CHANNEL_MODE_OMNIOFF_POLY = FLUID_CHANNEL_MODE_MASK & (FLUID_CHANNEL_OMNI_OFF & ~FLUID_CHANNEL_POLY_OFF), /**< corresponds to MIDI mode 2 */
345     FLUID_CHANNEL_MODE_OMNIOFF_MONO = FLUID_CHANNEL_MODE_MASK & (FLUID_CHANNEL_OMNI_OFF | FLUID_CHANNEL_POLY_OFF), /**< corresponds to MIDI mode 3 */
346     FLUID_CHANNEL_MODE_LAST /**< @internal Value defines the count of basic channel modes (#fluid_basic_channel_modes) @warning This symbol is not part of the public API and ABI stability guarantee and may change at any time! */
347 };
348
349 FLUIDSYNTH_API int fluid_synth_reset_basic_channel(fluid_synth_t *synth, int chan);
350
351 FLUIDSYNTH_API int  fluid_synth_get_basic_channel(fluid_synth_t *synth, int chan,
352         int *basic_chan_out,
353         int *mode_chan_out,
354         int *basic_val_out);
355 FLUIDSYNTH_API int fluid_synth_set_basic_channel(fluid_synth_t *synth, int chan, int mode, int val);
356
357 /** Interface to mono legato mode
358  *
359  * Indicates the legato mode a channel is set to
360  * n1,n2,n3,.. is a legato passage. n1 is the first note, and n2,n3,n4 are played legato with previous note. */
361 enum fluid_channel_legato_mode
362 {
363     FLUID_CHANNEL_LEGATO_MODE_RETRIGGER, /**< Mode 0 - Release previous note, start a new note */
364     FLUID_CHANNEL_LEGATO_MODE_MULTI_RETRIGGER, /**< Mode 1 - On contiguous notes retrigger in attack section using current value, shape attack using current dynamic and make use of previous voices if any */
365     FLUID_CHANNEL_LEGATO_MODE_LAST /**< @internal Value defines the count of legato modes (#fluid_channel_legato_mode) @warning This symbol is not part of the public API and ABI stability guarantee and may change at any time! */
366 };
367
368 FLUIDSYNTH_API int fluid_synth_set_legato_mode(fluid_synth_t *synth, int chan, int legatomode);
369 FLUIDSYNTH_API int fluid_synth_get_legato_mode(fluid_synth_t *synth, int chan, int  *legatomode);
370
371 /** Interface to portamento mode
372  *
373  * Indicates the portamento mode a channel is set to
374  */
375 enum fluid_channel_portamento_mode
376 {
377     FLUID_CHANNEL_PORTAMENTO_MODE_EACH_NOTE, /**< Mode 0 - Portamento on each note (staccato or legato) */
378     FLUID_CHANNEL_PORTAMENTO_MODE_LEGATO_ONLY, /**< Mode 1 - Portamento only on legato note */
379     FLUID_CHANNEL_PORTAMENTO_MODE_STACCATO_ONLY, /**< Mode 2 - Portamento only on staccato note */
380     FLUID_CHANNEL_PORTAMENTO_MODE_LAST /**< @internal Value defines the count of portamento modes (#fluid_channel_portamento_mode) @warning This symbol is not part of the public API and ABI stability guarantee and may change at any time! */
381 };
382
383 FLUIDSYNTH_API int fluid_synth_set_portamento_mode(fluid_synth_t *synth,
384         int chan, int portamentomode);
385 FLUIDSYNTH_API int fluid_synth_get_portamento_mode(fluid_synth_t *synth,
386         int chan, int   *portamentomode);
387
388 /* Interface to breath mode   */
389 FLUIDSYNTH_API int fluid_synth_set_breath_mode(fluid_synth_t *synth,
390         int chan, int breathmode);
391 FLUIDSYNTH_API int fluid_synth_get_breath_mode(fluid_synth_t *synth,
392         int chan, int  *breathmode);
393
394
395 #ifdef __cplusplus
396 }
397 #endif
398
399 #endif /* _FLUIDSYNTH_SYNTH_H */