libs/fluidsynth/fluidsynth/sfont.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_SFONT_H
  22 #define _FLUIDSYNTH_SFONT_H
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28
  29 /**
  30  * @file sfont.h
  31  * @brief SoundFont plugins
  32  *
  33  * It is possible to add new SoundFont loaders to the
  34  * synthesizer. This API allows for virtual SoundFont files to be loaded
  35  * and synthesized, which may not actually be SoundFont files, as long as they
  36  * can be represented by the SoundFont synthesis model.
  37  *
  38  * To add a new SoundFont loader to the synthesizer, call
  39  * fluid_synth_add_sfloader() and pass a pointer to an
  40  * #fluid_sfloader_t instance created by new_fluid_sfloader().
  41  * On creation, you must specify a callback function \p load
  42  * that will be called for every file attempting to load it and
  43  * if successful returns a #fluid_sfont_t instance, or NULL if it fails.
  44  *
  45  * The #fluid_sfont_t structure contains a callback to obtain the
  46  * name of the SoundFont. It contains two functions to iterate
  47  * though the contained presets, and one function to obtain a
  48  * preset corresponding to a bank and preset number. This
  49  * function should return a #fluid_preset_t instance.
  50  *
  51  * The #fluid_preset_t instance contains some functions to obtain
  52  * information from the preset (name, bank, number). The most
  53  * important callback is the noteon function. The noteon function
  54  * is called by fluidsynth internally and
  55  * should call fluid_synth_alloc_voice() for every sample that has
  56  * to be played. fluid_synth_alloc_voice() expects a pointer to a
  57  * #fluid_sample_t instance and returns a pointer to the opaque
  58  * #fluid_voice_t structure. To set or increment the values of a
  59  * generator, use fluid_voice_gen_set() or fluid_voice_gen_incr(). When you are
  60  * finished initializing the voice call fluid_voice_start() to
  61  * start playing the synthesis voice.
  62  */
  63
  64 /**
  65  * Some notification enums for presets and samples.
  66  */
  67 enum
  68 {
  69     FLUID_PRESET_SELECTED,                /**< Preset selected notify */
  70     FLUID_PRESET_UNSELECTED,              /**< Preset unselected notify */
  71     FLUID_SAMPLE_DONE                     /**< Sample no longer needed notify */
  72 };
  73
  74 /**
  75  * Indicates the type of a sample used by the _fluid_sample_t::sampletype field.
  76  */
  77 enum fluid_sample_type
  78 {
  79     FLUID_SAMPLETYPE_MONO = 0x1, /**< Used for mono samples */
  80     FLUID_SAMPLETYPE_RIGHT = 0x2, /**< Used for right samples of a stereo pair */
  81     FLUID_SAMPLETYPE_LEFT = 0x4, /**< Used for left samples of a stereo pair */
  82     FLUID_SAMPLETYPE_LINKED = 0x8, /**< Currently not used */
  83     FLUID_SAMPLETYPE_OGG_VORBIS = 0x10, /**< Used for Ogg Vorbis compressed samples @since 1.1.7 */
  84     FLUID_SAMPLETYPE_ROM = 0x8000 /**< Indicates ROM samples, causes sample to be ignored */
  85 };
  86
  87
  88 /**
  89  * Method to load an instrument file (does not actually need to be a real file name,
  90  * could be another type of string identifier that the \a loader understands).
  91  * @param loader SoundFont loader
  92  * @param filename File name or other string identifier
  93  * @return The loaded instrument file (SoundFont) or NULL if an error occured.
  94  */
  95 typedef fluid_sfont_t *(*fluid_sfloader_load_t)(fluid_sfloader_t *loader, const char *filename);
  96
  97 /**
  98  * The free method should free the memory allocated for a fluid_sfloader_t instance in
  99  * addition to any private data. Any custom user provided cleanup function must ultimately call
 100  * delete_fluid_sfloader() to ensure proper cleanup of the #fluid_sfloader_t struct. If no private data
 101  * needs to be freed, setting this to delete_fluid_sfloader() is sufficient.
 102  * @param loader SoundFont loader
 103  */
 104 typedef void (*fluid_sfloader_free_t)(fluid_sfloader_t *loader);
 105
 106
 107 FLUIDSYNTH_API fluid_sfloader_t *new_fluid_sfloader(fluid_sfloader_load_t load, fluid_sfloader_free_t free);
 108 FLUIDSYNTH_API void delete_fluid_sfloader(fluid_sfloader_t *loader);
 109
 110 FLUIDSYNTH_API fluid_sfloader_t *new_fluid_defsfloader(fluid_settings_t *settings);
 111
 112 /**
 113  * Opens the file or memory indicated by \c filename in binary read mode.
 114  * \c filename matches the string provided during the fluid_synth_sfload() call.
 115  *
 116  * @return returns a file handle on success, NULL otherwise
 117  */
 118 typedef void *(* fluid_sfloader_callback_open_t)(const char *filename);
 119
 120 /**
 121  * Reads \c count bytes to the specified buffer \c buf.
 122  *
 123  * @return returns #FLUID_OK if exactly \c count bytes were successfully read, else returns #FLUID_FAILED and leaves \a buf unmodified.
 124  */
 125 typedef int (* fluid_sfloader_callback_read_t)(void *buf, int count, void *handle);
 126
 127 /**
 128  * Same purpose and behaviour as fseek.
 129  *
 130  * @param origin either \c SEEK_SET, \c SEEK_CUR or \c SEEK_END
 131  *
 132  * @return returns #FLUID_OK if the seek was successfully performed while not seeking beyond a buffer or file, #FLUID_FAILED otherwise
 133  */
 134 typedef int (* fluid_sfloader_callback_seek_t)(void *handle, long offset, int origin);
 135
 136 /**
 137  * Closes the handle returned by #fluid_sfloader_callback_open_t and frees used ressources.
 138  *
 139  * @return returns #FLUID_OK on success, #FLUID_FAILED on error
 140  */
 141 typedef int (* fluid_sfloader_callback_close_t)(void *handle);
 142
 143 /** @return returns current file offset or #FLUID_FAILED on error */
 144 typedef long (* fluid_sfloader_callback_tell_t)(void *handle);
 145
 146
 147 FLUIDSYNTH_API int fluid_sfloader_set_callbacks(fluid_sfloader_t *loader,
 148         fluid_sfloader_callback_open_t open,
 149         fluid_sfloader_callback_read_t read,
 150         fluid_sfloader_callback_seek_t seek,
 151         fluid_sfloader_callback_tell_t tell,
 152         fluid_sfloader_callback_close_t close);
 153
 154 FLUIDSYNTH_API int fluid_sfloader_set_data(fluid_sfloader_t *loader, void *data);
 155 FLUIDSYNTH_API void *fluid_sfloader_get_data(fluid_sfloader_t *loader);
 156
 157
 158
 159 /**
 160  * Method to return the name of a virtual SoundFont.
 161  * @param sfont Virtual SoundFont
 162  * @return The name of the virtual SoundFont.
 163  */
 164 typedef const char *(*fluid_sfont_get_name_t)(fluid_sfont_t *sfont);
 165
 166 /**
 167  * Get a virtual SoundFont preset by bank and program numbers.
 168  * @param sfont Virtual SoundFont
 169  * @param bank MIDI bank number (0-16383)
 170  * @param prenum MIDI preset number (0-127)
 171  * @return Should return an allocated virtual preset or NULL if it could not
 172  *   be found.
 173  */
 174 typedef fluid_preset_t *(*fluid_sfont_get_preset_t)(fluid_sfont_t *sfont, int bank, int prenum);
 175
 176 /**
 177  * Start virtual SoundFont preset iteration method.
 178  * @param sfont Virtual SoundFont
 179  *
 180  * Starts/re-starts virtual preset iteration in a SoundFont.
 181  */
 182 typedef void (*fluid_sfont_iteration_start_t)(fluid_sfont_t *sfont);
 183
 184 /**
 185  * Virtual SoundFont preset iteration function.
 186  * @param sfont Virtual SoundFont
 187  * @param preset Caller supplied uninitialized buffer to fill in with current preset information
 188  * @return NULL when no more presets are available, otherwise the a pointer to the current preset
 189  *
 190  * Should store preset information to the caller supplied \a preset structure
 191  * and advance the internal iteration state to the next preset for subsequent
 192  * calls.
 193  */
 194 typedef fluid_preset_t *(*fluid_sfont_iteration_next_t)(fluid_sfont_t *sfont);
 195
 196 /**
 197  * Method to free a virtual SoundFont bank. Any custom user provided cleanup function must ultimately call
 198  * delete_fluid_sfont() to ensure proper cleanup of the #fluid_sfont_t struct. If no private data
 199  * needs to be freed, setting this to delete_fluid_sfont() is sufficient.
 200  * @param sfont Virtual SoundFont to free.
 201  * @return Should return 0 when it was able to free all resources or non-zero
 202  *   if some of the samples could not be freed because they are still in use,
 203  *   in which case the free will be tried again later, until success.
 204  */
 205 typedef int (*fluid_sfont_free_t)(fluid_sfont_t *sfont);
 206
 207
 208 FLUIDSYNTH_API fluid_sfont_t *new_fluid_sfont(fluid_sfont_get_name_t get_name,
 209         fluid_sfont_get_preset_t get_preset,
 210         fluid_sfont_iteration_start_t iter_start,
 211         fluid_sfont_iteration_next_t iter_next,
 212         fluid_sfont_free_t free);
 213
 214 FLUIDSYNTH_API int delete_fluid_sfont(fluid_sfont_t *sfont);
 215
 216 FLUIDSYNTH_API int fluid_sfont_set_data(fluid_sfont_t *sfont, void *data);
 217 FLUIDSYNTH_API void *fluid_sfont_get_data(fluid_sfont_t *sfont);
 218
 219 FLUIDSYNTH_API int fluid_sfont_get_id(fluid_sfont_t *sfont);
 220 FLUIDSYNTH_API const char *fluid_sfont_get_name(fluid_sfont_t *sfont);
 221 FLUIDSYNTH_API fluid_preset_t *fluid_sfont_get_preset(fluid_sfont_t *sfont, int bank, int prenum);
 222 FLUIDSYNTH_API void fluid_sfont_iteration_start(fluid_sfont_t *sfont);
 223 FLUIDSYNTH_API fluid_preset_t *fluid_sfont_iteration_next(fluid_sfont_t *sfont);
 224
 225 /**
 226  * Method to get a virtual SoundFont preset name.
 227  * @param preset Virtual SoundFont preset
 228  * @return Should return the name of the preset.  The returned string must be
 229  *   valid for the duration of the virtual preset (or the duration of the
 230  *   SoundFont, in the case of preset iteration).
 231  */
 232 typedef const char *(*fluid_preset_get_name_t)(fluid_preset_t *preset);
 233
 234 /**
 235  * Method to get a virtual SoundFont preset MIDI bank number.
 236  * @param preset Virtual SoundFont preset
 237  * @param return The bank number of the preset
 238  */
 239 typedef int (*fluid_preset_get_banknum_t)(fluid_preset_t *preset);
 240
 241 /**
 242  * Method to get a virtual SoundFont preset MIDI program number.
 243  * @param preset Virtual SoundFont preset
 244  * @param return The program number of the preset
 245  */
 246 typedef int (*fluid_preset_get_num_t)(fluid_preset_t *preset);
 247
 248 /**
 249  * Method to handle a noteon event (synthesize the instrument).
 250  * @param preset Virtual SoundFont preset
 251  * @param synth Synthesizer instance
 252  * @param chan MIDI channel number of the note on event
 253  * @param key MIDI note number (0-127)
 254  * @param vel MIDI velocity (0-127)
 255  * @return #FLUID_OK on success (0) or #FLUID_FAILED (-1) otherwise
 256  *
 257  * This method may be called from within synthesis context and therefore
 258  * should be as efficient as possible and not perform any operations considered
 259  * bad for realtime audio output (memory allocations and other OS calls).
 260  *
 261  * Call fluid_synth_alloc_voice() for every sample that has
 262  * to be played. fluid_synth_alloc_voice() expects a pointer to a
 263  * #fluid_sample_t structure and returns a pointer to the opaque
 264  * #fluid_voice_t structure. To set or increment the values of a
 265  * generator, use fluid_voice_gen_set() or fluid_voice_gen_incr(). When you are
 266  * finished initializing the voice call fluid_voice_start() to
 267  * start playing the synthesis voice.  Starting with FluidSynth 1.1.0 all voices
 268  * created will be started at the same time.
 269  */
 270 typedef int (*fluid_preset_noteon_t)(fluid_preset_t *preset, fluid_synth_t *synth, int chan, int key, int vel);
 271
 272 /**
 273  * Method to free a virtual SoundFont preset. Any custom user provided cleanup function must ultimately call
 274  * delete_fluid_preset() to ensure proper cleanup of the #fluid_preset_t struct. If no private data
 275  * needs to be freed, setting this to delete_fluid_preset() is sufficient.
 276  * @param preset Virtual SoundFont preset
 277  * @return Should return 0
 278  */
 279 typedef void (*fluid_preset_free_t)(fluid_preset_t *preset);
 280
 281 FLUIDSYNTH_API fluid_preset_t *new_fluid_preset(fluid_sfont_t *parent_sfont,
 282         fluid_preset_get_name_t get_name,
 283         fluid_preset_get_banknum_t get_bank,
 284         fluid_preset_get_num_t get_num,
 285         fluid_preset_noteon_t noteon,
 286         fluid_preset_free_t free);
 287 FLUIDSYNTH_API void delete_fluid_preset(fluid_preset_t *preset);
 288
 289 FLUIDSYNTH_API int fluid_preset_set_data(fluid_preset_t *preset, void *data);
 290 FLUIDSYNTH_API void *fluid_preset_get_data(fluid_preset_t *preset);
 291
 292 FLUIDSYNTH_API const char *fluid_preset_get_name(fluid_preset_t *preset);
 293 FLUIDSYNTH_API int fluid_preset_get_banknum(fluid_preset_t *preset);
 294 FLUIDSYNTH_API int fluid_preset_get_num(fluid_preset_t *preset);
 295 FLUIDSYNTH_API fluid_sfont_t *fluid_preset_get_sfont(fluid_preset_t *preset);
 296
 297 FLUIDSYNTH_API fluid_sample_t *new_fluid_sample(void);
 298 FLUIDSYNTH_API void delete_fluid_sample(fluid_sample_t *sample);
 299 FLUIDSYNTH_API size_t fluid_sample_sizeof(void);
 300
 301 FLUIDSYNTH_API int fluid_sample_set_name(fluid_sample_t *sample, const char *name);
 302 FLUIDSYNTH_API int fluid_sample_set_sound_data(fluid_sample_t *sample,
 303         short *data,
 304         char *data24,
 305         unsigned int nbframes,
 306         unsigned int sample_rate,
 307         short copy_data);
 308
 309 FLUIDSYNTH_API int fluid_sample_set_loop(fluid_sample_t *sample, unsigned int loop_start, unsigned int loop_end);
 310 FLUIDSYNTH_API int fluid_sample_set_pitch(fluid_sample_t *sample, int root_key, int fine_tune);
 311
 312 #ifdef __cplusplus
 313 }
 314 #endif
 315
 316 #endif /* _FLUIDSYNTH_SFONT_H */