audio.h File Reference

Functions for audio driver output. More...

Typedefs
typedef int(*	fluid_audio_func_t )(void *data, int len, int nfx, float *fx[], int nout, float *out[])
	Callback function type used with new_fluid_audio_driver2() to allow for custom user audio processing before the audio is sent to the driver. More...

Functions
FLUIDSYNTH_API fluid_audio_driver_t *	new_fluid_audio_driver (fluid_settings_t *settings, fluid_synth_t *synth)
	Create a new audio driver. More...
FLUIDSYNTH_API fluid_audio_driver_t *	new_fluid_audio_driver2 (fluid_settings_t *settings, fluid_audio_func_t func, void *data)
	Create a new audio driver. More...
FLUIDSYNTH_API void	delete_fluid_audio_driver (fluid_audio_driver_t *driver)
	Deletes an audio driver instance. More...
FLUIDSYNTH_API fluid_file_renderer_t *	new_fluid_file_renderer (fluid_synth_t *synth)
	Create a new file renderer and open the file. More...
FLUIDSYNTH_API int	fluid_file_renderer_process_block (fluid_file_renderer_t *dev)
	Write period_size samples to file. More...
FLUIDSYNTH_API void	delete_fluid_file_renderer (fluid_file_renderer_t *dev)
	Close file and destroy a file renderer object. More...
FLUIDSYNTH_API int	fluid_file_set_encoding_quality (fluid_file_renderer_t *dev, double q)
	Set vbr encoding quality (only available with libsndfile support) More...
FLUIDSYNTH_API int	fluid_audio_driver_register (const char **adrivers)
	Registers audio drivers to use. More...

Detailed Description

Functions for audio driver output.

Typedef Documentation

typedef int(* fluid_audio_func_t)(void *data, int len, int nfx, float *fx[], int nout, float *out[])

Callback function type used with new_fluid_audio_driver2() to allow for custom user audio processing before the audio is sent to the driver.

This function is responsible for rendering audio to the buffers. The buffers passed to this function are allocated and owned by the respective audio driver and are only valid during that specific call (do not cache them). For further details please refer to fluid_synth_process().

Note

Whereas fluid_synth_process() allows aliasing buffers, there is the guarentee that out and fx buffers provided by fluidsynth's audio drivers never alias. This prevents downstream applications from e.g. applying a custom effect accidentially to the same buffer multiple times.

Parameters

data	The user data parameter as passed to new_fluid_audio_driver2().
len	Count of audio frames to synthesize.
nfx	Count of arrays in fx.
fx	Array of buffers to store effects audio to. Buffers may alias with buffers of out.
nout	Count of arrays in out.
out	Array of buffers to store (dry) audio to. Buffers may alias with buffers of fx.

Returns

Should return FLUID_OK on success, FLUID_FAILED if an error occurred.

Function Documentation

FLUIDSYNTH_API fluid_audio_driver_t* new_fluid_audio_driver	(	fluid_settings_t *	settings,
		fluid_synth_t *	synth
	)

Create a new audio driver.

Parameters

settings	Configuration settings used to select and create the audio driver.
synth	Synthesizer instance for which the audio driver is created for.

Returns

The new audio driver instance or NULL on error

Creates a new audio driver for a given synth instance with a defined set of configuration settings. The settings instance must be the same that you have passed to new_fluid_synth() when creating the synth instance. Otherwise the behaviour is undefined.

Note

As soon as an audio driver is created, the synth starts rendering audio. This means that all necessary sound-setup should be completed after this point, thus of all object types in use (synth, midi player, sequencer, etc.) the audio driver should always be the last one to be created and the first one to be deleted! Also refer to the order of object creation in the code examples.

Examples:

example.c, fluidsynth_arpeggio.c, fluidsynth_metronome.c, fluidsynth_register_adriver.c, and fluidsynth_simple.c.

FLUIDSYNTH_API fluid_audio_driver_t* new_fluid_audio_driver2	(	fluid_settings_t *	settings,
		fluid_audio_func_t	func,
		void *	data
	)

Create a new audio driver.

Parameters

settings	Configuration settings used to select and create the audio driver.
func	Function called to fill audio buffers for audio playback
data	User defined data pointer to pass to func

Returns

The new audio driver instance or NULL on error

Like new_fluid_audio_driver() but allows for custom audio processing before audio is sent to audio driver. It is the responsibility of the callback func to render the audio into the buffers. If func uses a fluid_synth_t synth, the settings instance must be the same that you have passed to new_fluid_synth() when creating the synth instance. Otherwise the behaviour is undefined.

Note

Not as efficient as new_fluid_audio_driver().

As soon as an audio driver is created, a new thread is spawned starting to make callbacks to func. This means that all necessary sound-setup should be completed after this point, thus of all object types in use (synth, midi player, sequencer, etc.) the audio driver should always be the last one to be created and the first one to be deleted! Also refer to the order of object creation in the code examples.

Examples:

fluidsynth_fx.c.

References FLUID_DBG.

FLUIDSYNTH_API void delete_fluid_audio_driver

(

fluid_audio_driver_t *

driver

)

Deletes an audio driver instance.

Parameters

driver

Audio driver instance to delete

Shuts down an audio driver and deletes its instance.

Examples:

example.c, fluidsynth_arpeggio.c, fluidsynth_fx.c, fluidsynth_metronome.c, fluidsynth_register_adriver.c, and fluidsynth_simple.c.

FLUIDSYNTH_API fluid_file_renderer_t* new_fluid_file_renderer

(

fluid_synth_t *

synth

)

Create a new file renderer and open the file.

Parameters

synth

The synth that creates audio data.

Returns

the new object, or NULL on failure

Since

1.1.0

NOTE: Available file types and formats depends on if libfluidsynth was built with libsndfile support or not. If not then only RAW 16 bit output is supported.

Uses the following settings from the synth object:

• audio.file.name: Output filename
• audio.file.type: File type, "auto" tries to determine type from filename extension with fallback to "wav".
• audio.file.format: Audio format
• audio.file.endian: Endian byte order, "auto" for file type's default byte order
• audio.period-size: Size of audio blocks to process
• synth.sample-rate: Sample rate to use

References delete_fluid_file_renderer(), FLUID_ERR, fluid_settings_dupstr(), fluid_settings_getint(), and fluid_settings_getnum().

FLUIDSYNTH_API int fluid_file_renderer_process_block

(

fluid_file_renderer_t *

dev

)

Write period_size samples to file.

Parameters

dev	File renderer instance

Returns

FLUID_OK or FLUID_FAILED if an error occurred

Since

1.1.0

References FLUID_ERR, FLUID_FAILED, FLUID_OK, fluid_synth_write_float(), and fluid_synth_write_s16().

FLUIDSYNTH_API void delete_fluid_file_renderer

(

fluid_file_renderer_t *

dev

)

Close file and destroy a file renderer object.

Parameters

dev	File renderer object.

Since

1.1.0

References FLUID_WARN.

Referenced by new_fluid_file_renderer().

FLUIDSYNTH_API int fluid_file_set_encoding_quality	(	fluid_file_renderer_t *	dev,
		double	q
	)

Set vbr encoding quality (only available with libsndfile support)

Parameters

dev	File renderer object.
q	The encoding quality, see libsndfile documentation of SFC_SET_VBR_ENCODING_QUALITY

Returns

FLUID_OK if the quality has been successfully set, FLUID_FAILED otherwise

Since

1.1.7

References FLUID_FAILED, and FLUID_OK.

FLUIDSYNTH_API int fluid_audio_driver_register

(

const char **

adrivers

)

Registers audio drivers to use.

When creating a settings instance with new_fluid_settings(), all audio drivers are initialized once. In the past this has caused segfaults and application crashes due to buggy soundcard drivers.

This function enables the user to only initialize specific audio drivers when settings instances are created. Therefore pass a NULL-terminated array of C-strings containing the names of audio drivers to register for the usage with fluidsynth. The names are the same as being used for the audio.driver setting.

By default all audio drivers fluidsynth has been compiled with are registered, so calling this function is optional.

Warning

This function may only be called if no thread is residing in fluidsynth's API and no instances of any kind are alive (e.g. as it would be the case right after fluidsynth's initial creation). Else the behaviour is undefined. Furtermore any attempt of using audio drivers that have not been registered is undefined behaviour!

Parameters

adrivers

NULL-terminated array of audio drivers to register. Pass NULL to register all available drivers.

Returns

FLUID_OK if all the audio drivers requested by the user are supported by fluidsynth and have been successfully registered. Otherwise FLUID_FAILED is returned and this function has no effect.

Note

This function is not thread safe and will never be!

Since

1.1.9

Examples:

fluidsynth_register_adriver.c.

References FLUID_FAILED, and FLUID_OK.