Voice Manipulation

Synthesis voice manipulation functions.

The interface to the synthesizer's voices. Examples on using them can be found in the source code of the default SoundFont loader (fluid_defsfont.c).

Most of these functions should only be called from within synthesis context, such as the SoundFont loader's noteon method.

Enumerations

`fluid_voice_add_mod`

Enum used with fluid_voice_add_mod() to specify how to handle duplicate modulators.

Value	Description
`FLUID_VOICE_OVERWRITE`	Overwrite any existing matching modulator.
`FLUID_VOICE_ADD`	Add (sum) modulator amounts.
`FLUID_VOICE_DEFAULT`	For default modulators only, no need to check for duplicates.

`fluid_voice_callback_reason`

Enum indicating the reason a voice callback was invoked.

Value	Description
`FLUID_VOICE_CALLBACK_NOTEOFF`	A true noteoff is about to be processed for this voice by the next rendering call, i.e. the voice is neither sustained nor sostenutoed and is about to enter its release phase with the next rendering call. This event may not be fired if the sample ends before the voice receives a noteoff event. Think of short and unlooped percussion samples, for example.

`FLUID_VOICE_CALLBACK_FINISHED`	The voice has finished playing and is about to be removed from the DSP loop. The voice remains valid until the callback returns. After that, the voice instance should be considered invalid as it may be reclaimed immediately afterwards. This event will always be fired, even when the voice is being killed or stolen due to polyphony overflow.

Since

2.6.0

Types

`fluid_voice_callback_t`

typedef void(* fluid_voice_callback_t) (const fluid_voice_t *voice, int reason, void *data);

Callback function type for voice events.

Parameters:

Name	Description
`voice`	The voice instance that triggered the callback.
`reason`	The reason why the callback was invoked (see `fluid_voice_callback_reason`).
`data`	User-defined data pointer as passed to `fluid_voice_set_callback()`.

Note

It is unspecified from which thread the callback is called. However, the callback may be invoked from the synthesis context. In this case, audio synthesis will be blocked until the callback returns. It is therefore highly recommended to keep the callback code short, efficient and non-blocking. In realtime-rendering scenarios it is particularly discouraged to call any public API functions of the synth or the sequencer from within the callback, as this may acquire a mutex.

Since

2.6.0

Functions

`fluid_voice_add_mod()`

void fluid_voice_add_mod(fluid_voice_t *voice, fluid_mod_t *mod, int mode)

Adds a modulator to the voice if the modulator has valid sources.

Parameters:

Name	Description
`voice`	Voice instance.
`mod`	Modulator info (copied).
`mode`	Determines how to handle an existing identical modulator. `FLUID_VOICE_ADD` to add (offset) the modulator amounts, `FLUID_VOICE_OVERWRITE` to replace the modulator, `FLUID_VOICE_DEFAULT` when adding a default modulator - no duplicate should exist so don't check.

`fluid_voice_gen_get()`

float fluid_voice_gen_get(fluid_voice_t *voice, int gen)

Get the value of a generator.

Parameters:

Name	Description
`voice`	Voice instance
`gen`	Generator ID (`fluid_gen_type`)

Returns: Current generator value

`fluid_voice_gen_incr()`

void fluid_voice_gen_incr(fluid_voice_t *voice, int gen, float val)

Offset the value of a generator.

Parameters:

Name	Description
`voice`	Voice instance
`i`	Generator ID (`fluid_gen_type`)
`val`	Value to add to the existing value

`fluid_voice_gen_set()`

void fluid_voice_gen_set(fluid_voice_t *voice, int gen, float val)

Set the value of a generator.

Parameters:

Name	Description
`voice`	Voice instance
`i`	Generator ID (`fluid_gen_type`)
`val`	Generator value

`fluid_voice_get_actual_key()`

int fluid_voice_get_actual_key(const fluid_voice_t *voice)

Return the effective MIDI key of the playing voice.

Parameters:

Name	Description
`voice`	Voice instance

Returns: The MIDI key this voice is playing at

If the voice was started from an instrument which uses a fixed key generator, it returns that. Otherwise returns the same value as fluid_voice_get_key.

Note

The result of this function is only valid if the voice is playing.

Since

1.1.7

`fluid_voice_get_actual_velocity()`

int fluid_voice_get_actual_velocity(const fluid_voice_t *voice)

Return the effective MIDI velocity of the playing voice.

Parameters:

Name	Description
`voice`	Voice instance

Returns: The MIDI velocity this voice is playing at

If the voice was started from an instrument which uses a fixed velocity generator, it returns that. Otherwise it returns the same value as fluid_voice_get_velocity.

Note

The result of this function is only valid if the voice is playing.

Since

1.1.7

`fluid_voice_get_channel()`

int fluid_voice_get_channel(const fluid_voice_t *voice)

Return the MIDI channel the voice is playing on.

Parameters:

Name	Description
`voice`	Voice instance

Returns: The channel assigned to this voice

Note

The result of this function is only valid if the voice is playing.

Since

1.1.7

`fluid_voice_get_id()`

unsigned int fluid_voice_get_id(const fluid_voice_t *voice)

Get the unique ID of the noteon-event.

Parameters:

Name	Description
`voice`	Voice instance

Returns: Note on unique ID

A SoundFont loader may store pointers to voices it has created for realtime control during the operation of a voice (for example: parameter changes in SoundFont editor). The synth uses a pool of voices internally which are 'recycled' and never deallocated. However, before modifying an existing voice, check - that its state is still 'playing' - that the ID is still the same

Otherwise the voice has finished playing.

`fluid_voice_get_key()`

int fluid_voice_get_key(const fluid_voice_t *voice)

Return the MIDI key from the starting noteon event.

Parameters:

Name	Description
`voice`	Voice instance

Returns: The MIDI key of the noteon event that originally turned on this voice

Note

The result of this function is only valid if the voice is playing.

Since

1.1.7

`fluid_voice_get_velocity()`

int fluid_voice_get_velocity(const fluid_voice_t *voice)

Return the MIDI velocity from the starting noteon event.

Parameters:

Name	Description
`voice`	Voice instance

Returns: The MIDI velocity which originally turned on this voice

Note

The result of this function is only valid if the voice is playing.

Since

1.1.7

`fluid_voice_is_on()`

int fluid_voice_is_on(const fluid_voice_t *voice)

Check if a voice is ON.

A voice is in ON state as soon as a call to fluid_synth_start_voice() has been made (which is typically done in a fluid_preset_t's noteon function). A voice stays ON as long as it has not received a noteoff event.

Parameters:

Name	Description
`voice`	Voice instance

Returns: TRUE if on, FALSE otherwise

Since

1.1.7

`fluid_voice_is_playing()`

int fluid_voice_is_playing(const fluid_voice_t *voice)

Check if a voice is producing sound.

Like fluid_voice_is_on() this will return TRUE once a call to fluid_synth_start_voice() has been made. Contrary to fluid_voice_is_on(), this might also return TRUE after the voice received a noteoff event, as it may still be playing in release phase, or because it has been sustained or sostenuto'ed.

Parameters:

Name	Description
`voice`	Voice instance

Returns: TRUE if playing, FALSE otherwise

`fluid_voice_is_sostenuto()`

int fluid_voice_is_sostenuto(const fluid_voice_t *voice)

Check if a voice keeps playing after it has received a noteoff due to being held by sostenuto.

Parameters:

Name	Description
`voice`	Voice instance

Returns: TRUE if sostenuto, FALSE otherwise

Since

1.1.7

`fluid_voice_is_sustained()`

int fluid_voice_is_sustained(const fluid_voice_t *voice)

Check if a voice keeps playing after it has received a noteoff due to being held by sustain.

Parameters:

Name	Description
`voice`	Voice instance

Returns: TRUE if sustained, FALSE otherwise

Since

1.1.7

`fluid_voice_optimize_sample()`

int fluid_voice_optimize_sample(fluid_sample_t *s)

Calculate the peak volume of a sample for voice off optimization.

Parameters:

Name	Description
`s`	Sample to optimize

Returns: FLUID_OK on success, FLUID_FAILED otherwise

If the peak volume during the loop is known, then the voice can be released earlier during the release phase. Otherwise, the voice will operate (inaudibly), until the envelope is at the nominal turnoff point. So it's a good idea to call fluid_voice_optimize_sample() on each sample once.

`fluid_voice_set_callback()`

void fluid_voice_set_callback(fluid_voice_t *voice, fluid_voice_callback_t callback, void *data)

Set a callback function for a voice to be notified about voice state changes.

Only one callback function can be registered per voice. Setting a new callback replaces the previous one. Passing NULL as the callback removes any previously registered callback.

The callback is automatically cleared when the voice is re-initialized for a new note.

Parameters:

Name	Description
`voice`	Voice instance
`callback`	Callback function to register, or NULL to unregister.
`data`	User-defined data pointer passed to the callback.

Note

This function should be called after fluid_synth_alloc_voice() and before fluid_synth_start_voice() to be guaranteed to receive the callback.

Since

2.6.0

`fluid_voice_update_param()`

void fluid_voice_update_param(fluid_voice_t *voice, int gen)

Update all the synthesis parameters which depend on generator gen.

Parameters:

Name	Description
`voice`	Voice instance
`gen`	Generator id (`fluid_gen_type`)

Calling this function is only necessary after changing a generator of an already playing voice.