SoundFont Loader

Create custom SoundFont loaders.

It is possible to add new SoundFont loaders to the synthesizer. This API allows for virtual SoundFont files to be loaded and synthesized, which may not actually be SoundFont files, as long as they can be represented by the SoundFont synthesis model.

To add a new SoundFont loader to the synthesizer, call fluid_synth_add_sfloader() and pass a pointer to an fluid_sfloader_t instance created by new_fluid_sfloader(). On creation, you must specify a callback function load that will be called for every file attempting to load it and if successful returns a fluid_sfont_t instance, or NULL if it fails.

The fluid_sfont_t structure contains a callback to obtain the name of the SoundFont. It contains two functions to iterate though the contained presets, and one function to obtain a preset corresponding to a bank and preset number. This function should return a fluid_preset_t instance.

The fluid_preset_t instance contains some functions to obtain information from the preset (name, bank, number). The most important callback is the noteon function. The noteon function is called by fluidsynth internally and should call fluid_synth_alloc_voice() for every sample that has to be played. fluid_synth_alloc_voice() expects a pointer to a fluid_sample_t instance and returns a pointer to the opaque fluid_voice_t structure. To set or increment the values of a generator, use fluid_voice_gen_set() or fluid_voice_gen_incr(). When you are finished initializing the voice call fluid_voice_start() to start playing the synthesis voice.

Lifecycle Functions for SoundFont Loader

new_fluid_sfloader()

fluid_sfloader_t * new_fluid_sfloader(fluid_sfloader_load_t load, fluid_sfloader_free_t free)

Creates a new SoundFont loader.

Parameters:

Returns: the SoundFont loader instance on success, NULL otherwise.

delete_fluid_sfloader()

void delete_fluid_sfloader(fluid_sfloader_t *loader)

Frees a SoundFont loader created with new_fluid_sfloader().

Parameters:

new_fluid_defsfloader()

fluid_sfloader_t * new_fluid_defsfloader(fluid_settings_t *settings)

Creates a default soundfont2 loader that can be used with fluid_synth_add_sfloader().

By default every synth instance has an initial default soundfont loader instance. Calling this function is usually only necessary to load a soundfont from memory, by providing custom callback functions via fluid_sfloader_set_callbacks().

Parameters:

Returns: A default soundfont2 loader struct

Lifecycle Functions for SoundFont

new_fluid_sfont()

fluid_sfont_t * new_fluid_sfont(fluid_sfont_get_name_t get_name, fluid_sfont_get_preset_t get_preset, fluid_sfont_iteration_start_t iter_start, fluid_sfont_iteration_next_t iter_next, fluid_sfont_free_t free)

Creates a new virtual SoundFont instance structure.

Parameters:

Returns: The soundfont instance on success or NULL otherwise.

delete_fluid_sfont()

int delete_fluid_sfont(fluid_sfont_t *sfont)

Destroys a SoundFont instance created with new_fluid_sfont().

Parameters:

Returns: Always returns 0.

Implements fluid_sfont_free_t.

Lifecycle Functions for Preset

new_fluid_preset()

fluid_preset_t * new_fluid_preset(fluid_sfont_t *parent_sfont, fluid_preset_get_name_t get_name, fluid_preset_get_banknum_t get_bank, fluid_preset_get_num_t get_num, fluid_preset_noteon_t noteon, fluid_preset_free_t free)

Create a virtual SoundFont preset instance.

Parameters:

Returns: The preset instance on success, NULL otherwise.

delete_fluid_preset()

void delete_fluid_preset(fluid_preset_t *preset)

Destroys a SoundFont preset instance created with new_fluid_preset().

Parameters:

Implements fluid_preset_free_t.

Lifecycle Functions for Sample

new_fluid_sample()

fluid_sample_t * new_fluid_sample(void)

Create a new sample instance.

Returns: The sample on success, NULL otherwise.

delete_fluid_sample()

void delete_fluid_sample(fluid_sample_t *sample)

Destroy a sample instance previously created with new_fluid_sample().

Parameters:

Enumerations

@254110145054223374313306133161016057052170030000

Some notification enums for presets and samples.

fluid_sample_type

Indicates the type of a sample used by the _fluid_sample_t::sampletype field.

This enum corresponds to the SFSampleLink enum in the SoundFont spec. One flag may be bit-wise OR-ed with one value.

Types

fluid_preset_free_t

typedef void(* fluid_preset_free_t) (fluid_preset_t *preset);

Method to free a virtual SoundFont preset.

Parameters:

Returns: Should return 0

Any custom user provided cleanup function must ultimately call delete_fluid_preset() to ensure proper cleanup of the fluid_preset_t struct. If no private data needs to be freed, setting this to delete_fluid_preset() is sufficient.

fluid_preset_get_banknum_t

typedef int(* fluid_preset_get_banknum_t) (fluid_preset_t *preset);

Method to get a virtual SoundFont preset MIDI bank number.

Parameters:

Returns: The bank number of the preset

fluid_preset_get_name_t

typedef const char *(* fluid_preset_get_name_t) (fluid_preset_t *preset);

Method to get a virtual SoundFont preset name.

Parameters:

Returns: Should return the name of the preset. The returned string must be valid for the duration of the virtual preset (or the duration of the SoundFont, in the case of preset iteration).

fluid_preset_get_num_t

typedef int(* fluid_preset_get_num_t) (fluid_preset_t *preset);

Method to get a virtual SoundFont preset MIDI program number.

Parameters:

Returns: The program number of the preset

fluid_preset_noteon_t

typedef int(* fluid_preset_noteon_t) (fluid_preset_t *preset, fluid_synth_t *synth, int chan, int key, int vel);

Method to handle a noteon event (synthesize the instrument).

Parameters:

Returns: FLUID_OK on success (0) or FLUID_FAILED (-1) otherwise

This method may be called from within synthesis context and therefore should be as efficient as possible and not perform any operations considered bad for realtime audio output (memory allocations and other OS calls).

Call fluid_synth_alloc_voice() for every sample that has to be played. fluid_synth_alloc_voice() expects a pointer to a fluid_sample_t structure and returns a pointer to the opaque fluid_voice_t structure. To set or increment the values of a generator, use fluid_voice_gen_set() or fluid_voice_gen_incr(). When you are finished initializing the voice call fluid_voice_start() to start playing the synthesis voice. Starting with FluidSynth 1.1.0 all voices created will be started at the same time.

fluid_sfloader_callback_close_t

typedef int(* fluid_sfloader_callback_close_t) (void *handle);

Closes the handle returned by fluid_sfloader_callback_open_t and frees used resources.

Returns: returns FLUID_OK on success, FLUID_FAILED on error

fluid_sfloader_callback_open_t

typedef void *(* fluid_sfloader_callback_open_t) (const char *filename);

Opens the file or memory indicated by filename in binary read mode.

Returns: returns a file handle on success, NULL otherwise

filename matches the string provided during the fluid_synth_sfload() call.

fluid_sfloader_callback_read_t

typedef int(* fluid_sfloader_callback_read_t) (void *buf, fluid_long_long_t count, void *handle);

Reads count bytes to the specified buffer buf.

Returns: returns FLUID_OK if exactly count bytes were successfully read, else returns FLUID_FAILED and leaves buf unmodified.

fluid_sfloader_callback_seek_t

typedef int(* fluid_sfloader_callback_seek_t) (void *handle, fluid_long_long_t offset, int origin);

Same purpose and behaviour as fseek.

Parameters:

Returns: returns FLUID_OK if the seek was successfully performed while not seeking beyond a buffer or file, FLUID_FAILED otherwise

fluid_sfloader_callback_tell_t

typedef fluid_long_long_t(* fluid_sfloader_callback_tell_t) (void *handle);

Returns: returns current file offset or FLUID_FAILED on error

fluid_sfloader_free_t

typedef void(* fluid_sfloader_free_t) (fluid_sfloader_t *loader);

The free method should free the memory allocated for a fluid_sfloader_t instance in addition to any private data.

Parameters:

Any custom user provided cleanup function must ultimately call delete_fluid_sfloader() to ensure proper cleanup of the fluid_sfloader_t struct. If no private data needs to be freed, setting this to delete_fluid_sfloader() is sufficient.

fluid_sfloader_load_t

typedef fluid_sfont_t *(* fluid_sfloader_load_t) (fluid_sfloader_t *loader, const char *filename);

Method to load an instrument file (does not actually need to be a real file name, could be another type of string identifier that the loader understands).

Parameters:

Returns: The loaded instrument file (SoundFont) or NULL if an error occurred.

fluid_sfont_free_t

typedef int(* fluid_sfont_free_t) (fluid_sfont_t *sfont);

Method to free a virtual SoundFont bank.

Parameters:

Returns: Should return 0 when it was able to free all resources or non-zero if some of the samples could not be freed because they are still in use, in which case the free will be tried again later, until success.

Any custom user provided cleanup function must ultimately call delete_fluid_sfont() to ensure proper cleanup of the fluid_sfont_t struct. If no private data needs to be freed, setting this to delete_fluid_sfont() is sufficient.

fluid_sfont_get_name_t

typedef const char *(* fluid_sfont_get_name_t) (fluid_sfont_t *sfont);

Method to return the name of a virtual SoundFont.

Parameters:

Returns: The name of the virtual SoundFont.

fluid_sfont_get_preset_t

typedef fluid_preset_t *(* fluid_sfont_get_preset_t) (fluid_sfont_t *sfont, int bank, int prenum);

Get a virtual SoundFont preset by bank and program numbers.

Parameters:

Returns: Should return an allocated virtual preset or NULL if it could not be found.

fluid_sfont_iteration_next_t

typedef fluid_preset_t *(* fluid_sfont_iteration_next_t) (fluid_sfont_t *sfont);

Virtual SoundFont preset iteration function.

Parameters:

Returns: NULL when no more presets are available, otherwise the a pointer to the current preset

Returns preset information to the caller. The returned buffer is only valid until a subsequent call to this function.

fluid_sfont_iteration_start_t

typedef void(* fluid_sfont_iteration_start_t) (fluid_sfont_t *sfont);

Start virtual SoundFont preset iteration method.

Parameters:

Starts/re-starts virtual preset iteration in a SoundFont.

Functions

fluid_preset_get_banknum()

int fluid_preset_get_banknum(fluid_preset_t *preset)

Retrieves the presets bank number by executing the get_bank function provided on its creation.

Parameters:

Returns: The bank number of preset.

fluid_preset_get_data()

void * fluid_preset_get_data(fluid_preset_t *preset)

Retrieve the private data of a SoundFont preset instance.

Parameters:

Returns: The private data or NULL if none explicitly set before.

fluid_preset_get_name()

const char * fluid_preset_get_name(fluid_preset_t *preset)

Retrieves the presets name by executing the get_name function provided on its creation.

Parameters:

Returns: Pointer to a NULL-terminated string containing the presets name.

fluid_preset_get_num()

int fluid_preset_get_num(fluid_preset_t *preset)

Retrieves the presets (instrument) number by executing the get_num function provided on its creation.

Parameters:

Returns: The number of preset.

fluid_preset_get_sfont()

fluid_sfont_t * fluid_preset_get_sfont(fluid_preset_t *preset)

Retrieves the presets parent SoundFont instance.

Parameters:

Returns: The parent SoundFont of preset.

fluid_preset_set_data()

int fluid_preset_set_data(fluid_preset_t *preset, void *data)

Set private data to use with a SoundFont preset instance.

Parameters:

Returns: FLUID_OK on success, FLUID_FAILED otherwise.

fluid_sample_set_loop()

int fluid_sample_set_loop(fluid_sample_t *sample, unsigned int loop_start, unsigned int loop_end)

Set the loop of a sample.

Parameters:

Returns: FLUID_OK on success, FLUID_FAILED otherwise.

fluid_sample_set_name()

int fluid_sample_set_name(fluid_sample_t *sample, const char *name)

Set the name of a SoundFont sample.

Parameters:

Returns: FLUID_OK on success, FLUID_FAILED otherwise

fluid_sample_set_pitch()

int fluid_sample_set_pitch(fluid_sample_t *sample, int root_key, int fine_tune)

Set the pitch of a sample.

Parameters:

Returns: FLUID_OK on success, FLUID_FAILED otherwise.

fluid_sample_set_sound_data()

int fluid_sample_set_sound_data(fluid_sample_t *sample, short *data, char *data24, unsigned int nbframes, unsigned int sample_rate, short copy_data)

Assign sample data to a SoundFont sample.

Parameters:

Returns: FLUID_OK on success, FLUID_FAILED otherwise

fluid_sample_sizeof()

size_t fluid_sample_sizeof(void)

Returns the size of the fluid_sample_t structure.

Returns: Size of fluid_sample_t in bytes

Useful in low latency scenarios e.g. to allocate a pool of samples.

fluid_sfloader_get_data()

void * fluid_sfloader_get_data(fluid_sfloader_t *loader)

Obtain private data previously set with fluid_sfloader_set_data().

Parameters:

Returns: The private data or NULL if none explicitly set before.

fluid_sfloader_set_callbacks()

int fluid_sfloader_set_callbacks(fluid_sfloader_t *loader, fluid_sfloader_callback_open_t open, fluid_sfloader_callback_read_t read, fluid_sfloader_callback_seek_t seek, fluid_sfloader_callback_tell_t tell, fluid_sfloader_callback_close_t close)

Set custom callbacks to be used upon soundfont loading.

Parameters:

Returns: FLUID_OK if the callbacks have been successfully set, FLUID_FAILED otherwise.

Useful for loading a soundfont from memory, see doc/fluidsynth_sfload_mem.c as an example.

fluid_sfloader_set_data()

int fluid_sfloader_set_data(fluid_sfloader_t *loader, void *data)

Specify private data to be used by fluid_sfloader_load_t.

Parameters:

Returns: FLUID_OK on success, FLUID_FAILED otherwise.

fluid_sfont_get_data()

void * fluid_sfont_get_data(fluid_sfont_t *sfont)

Retrieve the private data of a SoundFont instance.

Parameters:

Returns: The private data or NULL if none explicitly set before.

fluid_sfont_get_default_mod()

int fluid_sfont_get_default_mod(fluid_sfont_t *sfont, fluid_mod_t **mod_out)

Retrieve a deep copy of all default modulators attached to the provided sfont instance.

If a SoundFont has any default modulators set, the synth's default modulators (see fluid_synth_add_default_mod()) will be ignored. A SF2 will have default modulators attached when the file contained a DMOD chunk. For a DLS file, fluidsynth will always add (custom) default modulators to allow the file being synthesized as accurately as possible.

Parameters:

Returns: FLUID_FAILED on error (e.g. out of memory). Otherwise it contains the number of modulators saved into the buffer. The caller must always free the buffer, even if the return value is zero!

fluid_sfont_get_id()

int fluid_sfont_get_id(fluid_sfont_t *sfont)

Retrieve the unique ID of a SoundFont instance.

Parameters:

Returns: The SoundFont ID.

fluid_sfont_get_name()

const char * fluid_sfont_get_name(fluid_sfont_t *sfont)

Retrieve the name of a SoundFont instance.

Parameters:

Returns: The name of the SoundFont.

fluid_sfont_get_preset()

fluid_preset_t * fluid_sfont_get_preset(fluid_sfont_t *sfont, int bank, int prenum)

Retrieve the preset assigned the a SoundFont instance for the given bank and preset number.

Parameters:

Returns: The preset instance or NULL if none found.

fluid_sfont_iteration_next()

fluid_preset_t * fluid_sfont_iteration_next(fluid_sfont_t *sfont)

Virtual SoundFont preset iteration function.

Returns preset information to the caller and advances the internal iteration state to the next preset for subsequent calls. Parameters:

Returns: NULL when no more presets are available, otherwise the a pointer to the current preset

fluid_sfont_iteration_start()

void fluid_sfont_iteration_start(fluid_sfont_t *sfont)

Starts / re-starts virtual preset iteration in a SoundFont.

Parameters:

fluid_sfont_set_data()

int fluid_sfont_set_data(fluid_sfont_t *sfont, void *data)

Set private data to use with a SoundFont instance.

Parameters:

Returns: FLUID_OK on success, FLUID_FAILED otherwise.

fluid_sfont_set_default_mod()

int fluid_sfont_set_default_mod(fluid_sfont_t *sfont, const fluid_mod_t *mods, int nmods)

Sets the default modulators of a SoundFont instance.

Parameters:

Returns: FLUID_OK on success, FLUID_FAILED otherwise.

fluid_synth_add_sfloader()

void fluid_synth_add_sfloader(fluid_synth_t *synth, fluid_sfloader_t *loader)

Add a SoundFont loader to the synth.

This function takes ownership of loader and frees it automatically upon synth destruction. Parameters:

SoundFont loaders are used to add custom instrument loading to FluidSynth. The caller supplied functions for loading files, allocating presets, retrieving information on them and synthesizing note-on events. Using this method even non SoundFont instruments can be synthesized, although limited to the SoundFont synthesis model.

fluid_synth_get_channel_preset()

fluid_preset_t * fluid_synth_get_channel_preset(fluid_synth_t *synth, int chan)

Get active preset on a MIDI channel.

Parameters:

Returns: Preset or NULL if no preset active on chan