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 Library General Public License
   7  * as published by the Free Software Foundation; either version 2 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  * Library General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Library 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 #define FLUID_SYNTH_CHANNEL_INFO_NAME_SIZE   32    /**< Length of channel info name field (including zero terminator) */
  49
  50 /**
  51  * Channel information structure for fluid_synth_get_channel_info().
  52  * @since 1.1.1
  53  */
  54 struct _fluid_synth_channel_info_t
  55 {
  56   int assigned : 1;     /**< TRUE if a preset is assigned, FALSE otherwise */
  57   /* Reserved flag bits (at the least 31) */
  58   int sfont_id;         /**< ID of parent SoundFont */
  59   int bank;             /**< MIDI bank number (0-16383) */
  60   int program;          /**< MIDI program number (0-127) */
  61   char name[FLUID_SYNTH_CHANNEL_INFO_NAME_SIZE];     /**< Channel preset name */
  62   char reserved[32];    /**< Reserved data for future expansion */
  63 };
  64
  65 FLUIDSYNTH_API fluid_synth_t* new_fluid_synth(fluid_settings_t* settings);
  66 FLUIDSYNTH_API int delete_fluid_synth(fluid_synth_t* synth);
  67 FLUIDSYNTH_API fluid_settings_t* fluid_synth_get_settings(fluid_synth_t* synth);
  68
  69
  70 /* MIDI channel messages */
  71
  72 FLUIDSYNTH_API int fluid_synth_noteon(fluid_synth_t* synth, int chan, int key, int vel);
  73 FLUIDSYNTH_API int fluid_synth_noteoff(fluid_synth_t* synth, int chan, int key);
  74 FLUIDSYNTH_API int fluid_synth_cc(fluid_synth_t* synth, int chan, int ctrl, int val);
  75 FLUIDSYNTH_API int fluid_synth_get_cc(fluid_synth_t* synth, int chan, int ctrl, int* pval);
  76 FLUIDSYNTH_API int fluid_synth_sysex(fluid_synth_t *synth, const char *data, int len,
  77                                      char *response, int *response_len, int *handled, int dryrun);
  78 FLUIDSYNTH_API int fluid_synth_pitch_bend(fluid_synth_t* synth, int chan, int val);
  79 FLUIDSYNTH_API int fluid_synth_get_pitch_bend(fluid_synth_t* synth, int chan, int* ppitch_bend);
  80 FLUIDSYNTH_API int fluid_synth_pitch_wheel_sens(fluid_synth_t* synth, int chan, int val);
  81 FLUIDSYNTH_API int fluid_synth_get_pitch_wheel_sens(fluid_synth_t* synth, int chan, int* pval);
  82 FLUIDSYNTH_API int fluid_synth_program_change(fluid_synth_t* synth, int chan, int program);
  83 FLUIDSYNTH_API int fluid_synth_channel_pressure(fluid_synth_t* synth, int chan, int val);
  84 FLUIDSYNTH_API int fluid_synth_bank_select(fluid_synth_t* synth, int chan, unsigned int bank);
  85 FLUIDSYNTH_API int fluid_synth_sfont_select(fluid_synth_t* synth, int chan, unsigned int sfont_id);
  86 FLUIDSYNTH_API
  87 int fluid_synth_program_select(fluid_synth_t* synth, int chan, unsigned int sfont_id,
  88                                unsigned int bank_num, unsigned int preset_num);
  89 FLUIDSYNTH_API int
  90 fluid_synth_program_select_by_sfont_name (fluid_synth_t* synth, int chan,
  91                                           const char *sfont_name, unsigned int bank_num,
  92                                           unsigned int preset_num);
  93 FLUIDSYNTH_API
  94 int fluid_synth_get_program(fluid_synth_t* synth, int chan, unsigned int* sfont_id,
  95                             unsigned int* bank_num, unsigned int* preset_num);
  96 FLUIDSYNTH_API int fluid_synth_unset_program (fluid_synth_t *synth, int chan);
  97 FLUIDSYNTH_API int fluid_synth_get_channel_info (fluid_synth_t *synth, int chan,
  98                                                  fluid_synth_channel_info_t *info);
  99 FLUIDSYNTH_API int fluid_synth_program_reset(fluid_synth_t* synth);
 100 FLUIDSYNTH_API int fluid_synth_system_reset(fluid_synth_t* synth);
 101
 102 FLUIDSYNTH_API int fluid_synth_all_notes_off(fluid_synth_t* synth, int chan);
 103 FLUIDSYNTH_API int fluid_synth_all_sounds_off(fluid_synth_t* synth, int chan);
 104
 105 enum fluid_midi_channel_type
 106 {
 107   CHANNEL_TYPE_MELODIC = 0,
 108   CHANNEL_TYPE_DRUM = 1
 109 };
 110
 111 int fluid_synth_set_channel_type(fluid_synth_t* synth, int chan, int type);
 112
 113
 114 /* Low level access */
 115 FLUIDSYNTH_API fluid_preset_t* fluid_synth_get_channel_preset(fluid_synth_t* synth, int chan);
 116 FLUIDSYNTH_API int fluid_synth_start(fluid_synth_t* synth, unsigned int id,
 117                                      fluid_preset_t* preset, int audio_chan,
 118                                      int midi_chan, int key, int vel);
 119 FLUIDSYNTH_API int fluid_synth_stop(fluid_synth_t* synth, unsigned int id);
 120
 121
 122 /* SoundFont management */
 123
 124 FLUIDSYNTH_API
 125 int fluid_synth_sfload(fluid_synth_t* synth, const char* filename, int reset_presets);
 126 FLUIDSYNTH_API int fluid_synth_sfreload(fluid_synth_t* synth, unsigned int id);
 127 FLUIDSYNTH_API int fluid_synth_sfunload(fluid_synth_t* synth, unsigned int id, int reset_presets);
 128 FLUIDSYNTH_API int fluid_synth_add_sfont(fluid_synth_t* synth, fluid_sfont_t* sfont);
 129 FLUIDSYNTH_API void fluid_synth_remove_sfont(fluid_synth_t* synth, fluid_sfont_t* sfont);
 130 FLUIDSYNTH_API int fluid_synth_sfcount(fluid_synth_t* synth);
 131 FLUIDSYNTH_API fluid_sfont_t* fluid_synth_get_sfont(fluid_synth_t* synth, unsigned int num);
 132 FLUIDSYNTH_API fluid_sfont_t* fluid_synth_get_sfont_by_id(fluid_synth_t* synth, unsigned int id);
 133 FLUIDSYNTH_API fluid_sfont_t *fluid_synth_get_sfont_by_name (fluid_synth_t* synth,
 134                                                              const char *name);
 135 FLUIDSYNTH_API int fluid_synth_set_bank_offset(fluid_synth_t* synth, int sfont_id, int offset);
 136 FLUIDSYNTH_API int fluid_synth_get_bank_offset(fluid_synth_t* synth, int sfont_id);
 137
 138
 139 /* Reverb  */
 140
 141 FLUIDSYNTH_API void fluid_synth_set_reverb(fluid_synth_t* synth, double roomsize,
 142                                            double damping, double width, double level);
 143 FLUIDSYNTH_API void fluid_synth_set_reverb_on(fluid_synth_t* synth, int on);
 144 FLUIDSYNTH_API double fluid_synth_get_reverb_roomsize(fluid_synth_t* synth);
 145 FLUIDSYNTH_API double fluid_synth_get_reverb_damp(fluid_synth_t* synth);
 146 FLUIDSYNTH_API double fluid_synth_get_reverb_level(fluid_synth_t* synth);
 147 FLUIDSYNTH_API double fluid_synth_get_reverb_width(fluid_synth_t* synth);
 148
 149 #define FLUID_REVERB_DEFAULT_ROOMSIZE 0.2f      /**< Default reverb room size */
 150 #define FLUID_REVERB_DEFAULT_DAMP 0.0f          /**< Default reverb damping */
 151 #define FLUID_REVERB_DEFAULT_WIDTH 0.5f         /**< Default reverb width */
 152 #define FLUID_REVERB_DEFAULT_LEVEL 0.9f         /**< Default reverb level */
 153
 154
 155 /* Chorus */
 156
 157 /**
 158  * Chorus modulation waveform type.
 159  */
 160 enum fluid_chorus_mod {
 161   FLUID_CHORUS_MOD_SINE = 0,            /**< Sine wave chorus modulation */
 162   FLUID_CHORUS_MOD_TRIANGLE = 1         /**< Triangle wave chorus modulation */
 163 };
 164
 165 FLUIDSYNTH_API void fluid_synth_set_chorus(fluid_synth_t* synth, int nr, double level,
 166                                          double speed, double depth_ms, int type);
 167 FLUIDSYNTH_API void fluid_synth_set_chorus_on(fluid_synth_t* synth, int on);
 168 FLUIDSYNTH_API int fluid_synth_get_chorus_nr(fluid_synth_t* synth);
 169 FLUIDSYNTH_API double fluid_synth_get_chorus_level(fluid_synth_t* synth);
 170 FLUIDSYNTH_API double fluid_synth_get_chorus_speed_Hz(fluid_synth_t* synth);
 171 FLUIDSYNTH_API double fluid_synth_get_chorus_depth_ms(fluid_synth_t* synth);
 172 FLUIDSYNTH_API int fluid_synth_get_chorus_type(fluid_synth_t* synth); /* see fluid_chorus_mod */
 173
 174 #define FLUID_CHORUS_DEFAULT_N 3                                /**< Default chorus voice count */
 175 #define FLUID_CHORUS_DEFAULT_LEVEL 2.0f                         /**< Default chorus level */
 176 #define FLUID_CHORUS_DEFAULT_SPEED 0.3f                         /**< Default chorus speed */
 177 #define FLUID_CHORUS_DEFAULT_DEPTH 8.0f                         /**< Default chorus depth */
 178 #define FLUID_CHORUS_DEFAULT_TYPE FLUID_CHORUS_MOD_SINE         /**< Default chorus waveform type */
 179
 180
 181 /* Audio and MIDI channels */
 182
 183 FLUIDSYNTH_API int fluid_synth_count_midi_channels(fluid_synth_t* synth);
 184 FLUIDSYNTH_API int fluid_synth_count_audio_channels(fluid_synth_t* synth);
 185 FLUIDSYNTH_API int fluid_synth_count_audio_groups(fluid_synth_t* synth);
 186 FLUIDSYNTH_API int fluid_synth_count_effects_channels(fluid_synth_t* synth);
 187
 188
 189 /* Synthesis parameters */
 190
 191 FLUIDSYNTH_API void fluid_synth_set_sample_rate(fluid_synth_t* synth, float sample_rate);
 192 FLUIDSYNTH_API void fluid_synth_set_gain(fluid_synth_t* synth, float gain);
 193 FLUIDSYNTH_API float fluid_synth_get_gain(fluid_synth_t* synth);
 194 FLUIDSYNTH_API int fluid_synth_set_polyphony(fluid_synth_t* synth, int polyphony);
 195 FLUIDSYNTH_API int fluid_synth_get_polyphony(fluid_synth_t* synth);
 196 FLUIDSYNTH_API int fluid_synth_get_active_voice_count(fluid_synth_t* synth);
 197 FLUIDSYNTH_API int fluid_synth_get_internal_bufsize(fluid_synth_t* synth);
 198
 199 FLUIDSYNTH_API
 200 int fluid_synth_set_interp_method(fluid_synth_t* synth, int chan, int interp_method);
 201
 202 /**
 203  * Synthesis interpolation method.
 204  */
 205 enum fluid_interp {
 206   FLUID_INTERP_NONE = 0,        /**< No interpolation: Fastest, but questionable audio quality */
 207   FLUID_INTERP_LINEAR = 1,      /**< Straight-line interpolation: A bit slower, reasonable audio quality */
 208   FLUID_INTERP_4THORDER = 4,    /**< Fourth-order interpolation, good quality, the default */
 209   FLUID_INTERP_7THORDER = 7     /**< Seventh-order interpolation */
 210 };
 211
 212 #define FLUID_INTERP_DEFAULT    FLUID_INTERP_4THORDER   /**< Default interpolation method from #fluid_interp. */
 213 #define FLUID_INTERP_HIGHEST    FLUID_INTERP_7THORDER   /**< Highest interpolation method from #fluid_interp. */
 214
 215
 216 /* Generator interface */
 217
 218 FLUIDSYNTH_API
 219 int fluid_synth_set_gen(fluid_synth_t* synth, int chan, int param, float value);
 220 FLUIDSYNTH_API int fluid_synth_set_gen2 (fluid_synth_t* synth, int chan,
 221                                          int param, float value,
 222                                          int absolute, int normalized);
 223 FLUIDSYNTH_API float fluid_synth_get_gen(fluid_synth_t* synth, int chan, int param);
 224
 225
 226 /* Tuning */
 227
 228 FLUIDSYNTH_API
 229 int fluid_synth_create_key_tuning(fluid_synth_t* synth, int bank, int prog,
 230                                   const char* name, const double* pitch);
 231 FLUIDSYNTH_API
 232 int fluid_synth_activate_key_tuning(fluid_synth_t* synth, int bank, int prog,
 233                                     const char* name, const double* pitch, int apply);
 234 FLUIDSYNTH_API
 235 int fluid_synth_create_octave_tuning(fluid_synth_t* synth, int bank, int prog,
 236                                      const char* name, const double* pitch);
 237 FLUIDSYNTH_API
 238 int fluid_synth_activate_octave_tuning(fluid_synth_t* synth, int bank, int prog,
 239                                        const char* name, const double* pitch, int apply);
 240 FLUIDSYNTH_API
 241 int fluid_synth_tune_notes(fluid_synth_t* synth, int bank, int prog,
 242                            int len, const int *keys, const double* pitch, int apply);
 243 FLUIDSYNTH_API
 244 int fluid_synth_select_tuning(fluid_synth_t* synth, int chan, int bank, int prog);
 245 FLUIDSYNTH_API
 246 int fluid_synth_activate_tuning(fluid_synth_t* synth, int chan, int bank, int prog,
 247                                 int apply);
 248 FLUIDSYNTH_API int fluid_synth_reset_tuning(fluid_synth_t* synth, int chan);
 249 FLUIDSYNTH_API
 250 int fluid_synth_deactivate_tuning(fluid_synth_t* synth, int chan, int apply);
 251 FLUIDSYNTH_API void fluid_synth_tuning_iteration_start(fluid_synth_t* synth);
 252 FLUIDSYNTH_API
 253 int fluid_synth_tuning_iteration_next(fluid_synth_t* synth, int* bank, int* prog);
 254 FLUIDSYNTH_API int fluid_synth_tuning_dump(fluid_synth_t* synth, int bank, int prog,
 255                                            char* name, int len, double* pitch);
 256
 257 /* Misc */
 258
 259 FLUIDSYNTH_API double fluid_synth_get_cpu_load(fluid_synth_t* synth);
 260 FLUIDSYNTH_API char* fluid_synth_error(fluid_synth_t* synth);
 261
 262
 263 /*
 264  * Synthesizer plugin
 265  *
 266  * To create a synthesizer plugin, create the synthesizer as
 267  * explained above. Once the synthesizer is created you can call
 268  * any of the functions below to get the audio.
 269  */
 270
 271 FLUIDSYNTH_API int fluid_synth_write_s16(fluid_synth_t* synth, int len,
 272                                        void* lout, int loff, int lincr,
 273                                        void* rout, int roff, int rincr);
 274 FLUIDSYNTH_API int fluid_synth_write_float(fluid_synth_t* synth, int len,
 275                                          void* lout, int loff, int lincr,
 276                                          void* rout, int roff, int rincr);
 277 FLUIDSYNTH_API int fluid_synth_nwrite_float(fluid_synth_t* synth, int len,
 278                                           float** left, float** right,
 279                                           float** fx_left, float** fx_right);
 280 FLUIDSYNTH_API int fluid_synth_process(fluid_synth_t* synth, int len,
 281                                      int nin, float** in,
 282                                      int nout, float** out);
 283
 284 /**
 285  * Type definition of the synthesizer's audio callback function.
 286  * @param synth FluidSynth instance
 287  * @param len Count of audio frames to synthesize
 288  * @param out1 Array to store left channel of audio to
 289  * @param loff Offset index in 'out1' for first sample
 290  * @param lincr Increment between samples stored to 'out1'
 291  * @param out2 Array to store right channel of audio to
 292  * @param roff Offset index in 'out2' for first sample
 293  * @param rincr Increment between samples stored to 'out2'
 294  */
 295 typedef int (*fluid_audio_callback_t)(fluid_synth_t* synth, int len,
 296                                      void* out1, int loff, int lincr,
 297                                      void* out2, int roff, int rincr);
 298
 299 /* Synthesizer's interface to handle SoundFont loaders */
 300
 301 FLUIDSYNTH_API void fluid_synth_add_sfloader(fluid_synth_t* synth, fluid_sfloader_t* loader);
 302 FLUIDSYNTH_API fluid_voice_t* fluid_synth_alloc_voice(fluid_synth_t* synth, fluid_sample_t* sample,
 303                                                       int channum, int key, int vel);
 304 FLUIDSYNTH_API void fluid_synth_start_voice(fluid_synth_t* synth, fluid_voice_t* voice);
 305 FLUIDSYNTH_API void fluid_synth_get_voicelist(fluid_synth_t* synth,
 306                                               fluid_voice_t* buf[], int bufsize, int ID);
 307 FLUIDSYNTH_API int fluid_synth_handle_midi_event(void* data, fluid_midi_event_t* event);
 308 FLUIDSYNTH_API void fluid_synth_set_midi_router(fluid_synth_t* synth,
 309                                                 fluid_midi_router_t* router);
 310
 311 #ifdef __cplusplus
 312 }
 313 #endif
 314
 315 #endif /* _FLUIDSYNTH_SYNTH_H */