Skip to content
sfizz.h File Reference

sfizz public C API More...

#include <stddef.h>
#include <stdbool.h>

Functions

SFIZZ_EXPORTED_API sfizz_synth_t * sfizz_create_synth ()
 Creates a sfizz synth. More...
 
SFIZZ_EXPORTED_API void sfizz_free (sfizz_synth_t *synth)
 Frees an existing sfizz synth. More...
 
SFIZZ_EXPORTED_API bool sfizz_load_file (sfizz_synth_t *synth, const char *path)
 Loads an SFZ file. More...
 
SFIZZ_EXPORTED_API int sfizz_get_num_regions (sfizz_synth_t *synth)
 Returns the number of regions in the currently loaded SFZ file. More...
 
SFIZZ_EXPORTED_API int sfizz_get_num_groups (sfizz_synth_t *synth)
 Returns the number of groups in the currently loaded SFZ file. More...
 
SFIZZ_EXPORTED_API int sfizz_get_num_masters (sfizz_synth_t *synth)
 Returns the number of masters in the currently loaded SFZ file. More...
 
SFIZZ_EXPORTED_API int sfizz_get_num_curves (sfizz_synth_t *synth)
 Returns the number of curves in the currently loaded SFZ file. More...
 
SFIZZ_EXPORTED_API char * sfizz_export_midnam (sfizz_synth_t *synth, const char *model)
 Export a MIDI Name document describing the the currently loaded SFZ file. More...
 
SFIZZ_EXPORTED_API size_t sfizz_get_num_preloaded_samples (sfizz_synth_t *synth)
 Returns the number of preloaded samples for the current SFZ file. More...
 
SFIZZ_EXPORTED_API int sfizz_get_num_active_voices (sfizz_synth_t *synth)
 Returns the number of active voices. More...
 
SFIZZ_EXPORTED_API void sfizz_set_samples_per_block (sfizz_synth_t *synth, int samples_per_block)
 Sets the expected number of samples per block. More...
 
SFIZZ_EXPORTED_API void sfizz_set_sample_rate (sfizz_synth_t *synth, float sample_rate)
 Sets the sample rate for the synth. More...
 
SFIZZ_EXPORTED_API void sfizz_send_note_on (sfizz_synth_t *synth, int delay, int note_number, char velocity)
 Send a note on event to the synth. More...
 
SFIZZ_EXPORTED_API void sfizz_send_note_off (sfizz_synth_t *synth, int delay, int note_number, char velocity)
 Send a note off event to the synth. More...
 
SFIZZ_EXPORTED_API void sfizz_send_cc (sfizz_synth_t *synth, int delay, int cc_number, char cc_value)
 Send a CC event to the synth. More...
 
SFIZZ_EXPORTED_API void sfizz_send_pitch_wheel (sfizz_synth_t *synth, int delay, int pitch)
 Send a pitch wheel event. More...
 
SFIZZ_EXPORTED_API void sfizz_send_aftertouch (sfizz_synth_t *synth, int delay, char aftertouch)
 Send an aftertouch event. More...
 
SFIZZ_EXPORTED_API void sfizz_send_tempo (sfizz_synth_t *synth, int delay, float seconds_per_quarter)
 Send a tempo event. More...
 
SFIZZ_EXPORTED_API void sfizz_render_block (sfizz_synth_t *synth, float **channels, int num_channels, int num_frames)
 Render a block audio data into a stereo channel. More...
 
SFIZZ_EXPORTED_API unsigned int sfizz_get_preload_size (sfizz_synth_t *synth)
 Get the size of the preloaded data. More...
 
SFIZZ_EXPORTED_API void sfizz_set_preload_size (sfizz_synth_t *synth, unsigned int preload_size)
 Sets the size of the preloaded data in number of floats (not bytes). More...
 
SFIZZ_EXPORTED_API sfizz_oversampling_factor_t sfizz_get_oversampling_factor (sfizz_synth_t *synth)
 Get the internal oversampling rate. More...
 
SFIZZ_EXPORTED_API bool sfizz_set_oversampling_factor (sfizz_synth_t *synth, sfizz_oversampling_factor_t oversampling)
 Set the internal oversampling rate. More...
 
SFIZZ_EXPORTED_API void sfizz_set_volume (sfizz_synth_t *synth, float volume)
 Set the global instrument volume. More...
 
SFIZZ_EXPORTED_API float sfizz_get_volume (sfizz_synth_t *synth)
 Get the global instrument volume. More...
 
SFIZZ_EXPORTED_API void sfizz_set_num_voices (sfizz_synth_t *synth, int num_voices)
 Sets the number of voices used by the synth. More...
 
SFIZZ_EXPORTED_API int sfizz_get_num_voices (sfizz_synth_t *synth)
 Returns the number of voices. More...
 
SFIZZ_EXPORTED_API int sfizz_get_num_buffers (sfizz_synth_t *synth)
 Get the number of allocated buffers from the synth. More...
 
SFIZZ_EXPORTED_API int sfizz_get_num_bytes (sfizz_synth_t *synth)
 Get the number of bytes allocated from the synth. More...
 
SFIZZ_EXPORTED_API void sfizz_enable_freewheeling (sfizz_synth_t *synth)
 Enables freewheeling on the synth. More...
 
SFIZZ_EXPORTED_API void sfizz_disable_freewheeling (sfizz_synth_t *synth)
 Disables freewheeling on the synth. More...
 
SFIZZ_EXPORTED_API char * sfizz_get_unknown_opcodes (sfizz_synth_t *synth)
 Get a comma separated list of unknown opcodes. More...
 
SFIZZ_EXPORTED_API bool sfizz_should_reload_file (sfizz_synth_t *synth)
 Check if the SFZ should be reloaded. More...
 
SFIZZ_EXPORTED_API void sfizz_enable_logging (sfizz_synth_t *synth)
 Enable logging of timings to sidecar CSV files. More...
 
SFIZZ_EXPORTED_API void sfizz_disable_logging (sfizz_synth_t *synth)
 Disable logging. More...
 

Detailed Description

sfizz public C API

Function Documentation

◆ sfizz_create_synth()

SFIZZ_EXPORTED_API sfizz_synth_t* sfizz_create_synth ( )

Creates a sfizz synth.

This object has to be freed by the caller using sfizz_free(). The synth by default is set at 48 kHz and a maximum block size of 1024. You should change these values if they are not correct for your application.

Returns
sfizz_synth_t*

◆ sfizz_disable_freewheeling()

SFIZZ_EXPORTED_API void sfizz_disable_freewheeling ( sfizz_synth_t *  synth)

Disables freewheeling on the synth.

Parameters
synth

◆ sfizz_disable_logging()

SFIZZ_EXPORTED_API void sfizz_disable_logging ( sfizz_synth_t *  synth)

Disable logging.

Parameters
synth

◆ sfizz_enable_freewheeling()

SFIZZ_EXPORTED_API void sfizz_enable_freewheeling ( sfizz_synth_t *  synth)

Enables freewheeling on the synth.

Parameters
synth

◆ sfizz_enable_logging()

SFIZZ_EXPORTED_API void sfizz_enable_logging ( sfizz_synth_t *  synth)

Enable logging of timings to sidecar CSV files.

This can produce many outputs so use with caution.

Parameters
synth

◆ sfizz_export_midnam()

SFIZZ_EXPORTED_API char* sfizz_export_midnam ( sfizz_synth_t *  synth,
const char *  model 
)

Export a MIDI Name document describing the the currently loaded SFZ file.

Parameters
synthThe synth
modelthe model name used if a non-empty string, otherwise generated
Returns
char* a newly allocated XML string, which must be freed after use

◆ sfizz_free()

SFIZZ_EXPORTED_API void sfizz_free ( sfizz_synth_t *  synth)

Frees an existing sfizz synth.

Parameters
synthThe synth to destroy

◆ sfizz_get_num_active_voices()

SFIZZ_EXPORTED_API int sfizz_get_num_active_voices ( sfizz_synth_t *  synth)

Returns the number of active voices.

Note that this function is a basic indicator and does not aim to be perfect. In particular, it runs on the calling thread so voices may well start or stop while the function is checking which voice is active.

Parameters
synthThe synth
Returns
size_t the number of playing voices

◆ sfizz_get_num_buffers()

SFIZZ_EXPORTED_API int sfizz_get_num_buffers ( sfizz_synth_t *  synth)

Get the number of allocated buffers from the synth.

Parameters
synthThe synth
Returns
The number of buffers held by the synth

◆ sfizz_get_num_bytes()

SFIZZ_EXPORTED_API int sfizz_get_num_bytes ( sfizz_synth_t *  synth)

Get the number of bytes allocated from the synth.

Note that this value can be less than the actual memory usage since it only counts the buffer objects managed by sfizz.

Parameters
synthThe synth
Returns
The number of bytes held by the synth in buffers;

◆ sfizz_get_num_curves()

SFIZZ_EXPORTED_API int sfizz_get_num_curves ( sfizz_synth_t *  synth)

Returns the number of curves in the currently loaded SFZ file.

Parameters
synthThe synth
Returns
int the number of curves

◆ sfizz_get_num_groups()

SFIZZ_EXPORTED_API int sfizz_get_num_groups ( sfizz_synth_t *  synth)

Returns the number of groups in the currently loaded SFZ file.

Parameters
synthThe synth
Returns
int the number of groups

◆ sfizz_get_num_masters()

SFIZZ_EXPORTED_API int sfizz_get_num_masters ( sfizz_synth_t *  synth)

Returns the number of masters in the currently loaded SFZ file.

Parameters
synthThe synth
Returns
int the number of masters

◆ sfizz_get_num_preloaded_samples()

SFIZZ_EXPORTED_API size_t sfizz_get_num_preloaded_samples ( sfizz_synth_t *  synth)

Returns the number of preloaded samples for the current SFZ file.

Parameters
synthThe synth
Returns
int the number of preloaded samples

◆ sfizz_get_num_regions()

SFIZZ_EXPORTED_API int sfizz_get_num_regions ( sfizz_synth_t *  synth)

Returns the number of regions in the currently loaded SFZ file.

Parameters
synthThe synth
Returns
int the number of regions

◆ sfizz_get_num_voices()

SFIZZ_EXPORTED_API int sfizz_get_num_voices ( sfizz_synth_t *  synth)

Returns the number of voices.

Parameters
synth
Returns
num_voices

◆ sfizz_get_oversampling_factor()

SFIZZ_EXPORTED_API sfizz_oversampling_factor_t sfizz_get_oversampling_factor ( sfizz_synth_t *  synth)

Get the internal oversampling rate.

This is the sampling rate of the engine, not the output or expected rate of the calling function. For the latter use the get_sample_rate() functions.

Parameters
synthThe synth
Returns
The internal sample rate of the engine

◆ sfizz_get_preload_size()

SFIZZ_EXPORTED_API unsigned int sfizz_get_preload_size ( sfizz_synth_t *  synth)

Get the size of the preloaded data.

This returns the number of floats used in the preloading buffers.

Parameters
synthThe synth
Returns
the preloaded data size in sizeof(floats)

◆ sfizz_get_unknown_opcodes()

SFIZZ_EXPORTED_API char* sfizz_get_unknown_opcodes ( sfizz_synth_t *  synth)

Get a comma separated list of unknown opcodes.

The caller has to free() the string returned. This function allocates memory, do not call on the audio thread.

Parameters
synth
Returns
char*

◆ sfizz_get_volume()

SFIZZ_EXPORTED_API float sfizz_get_volume ( sfizz_synth_t *  synth)

Get the global instrument volume.

Parameters
synthThe synth
Returns
float the instrument volume

◆ sfizz_load_file()

SFIZZ_EXPORTED_API bool sfizz_load_file ( sfizz_synth_t *  synth,
const char *  path 
)

Loads an SFZ file.

The file path can be absolute or relative. All file operations for this SFZ file will be relative to the parent directory of the SFZ file.

Parameters
synthThe sfizz synth.
pathA null-terminated string representing a path to an SFZ file.
Returns
true when file loading went OK.
false if some error occured while loading.

◆ sfizz_render_block()

SFIZZ_EXPORTED_API void sfizz_render_block ( sfizz_synth_t *  synth,
float **  channels,
int  num_channels,
int  num_frames 
)

Render a block audio data into a stereo channel.

No other channel configuration is supported. The synth will gracefully ignore your request if you provide a value. You should pass all the relevant events for the block (midi notes, CCs, ...) before rendering each block. The synth will memorize the inputs and render sample accurates envelopes depending on the input events passed to it.

Parameters
synthThe synth
channelspointers to the left and right channel of the output
num_channelsshould be equal to 2 for the time being.
num_framesnumber of frames to fill. This should be less than or equal to the expected samples_per_block.

◆ sfizz_send_aftertouch()

SFIZZ_EXPORTED_API void sfizz_send_aftertouch ( sfizz_synth_t *  synth,
int  delay,
char  aftertouch 
)

Send an aftertouch event.

(CURRENTLY UNIMPLEMENTED)

Parameters
synth
delay
aftertouch

◆ sfizz_send_cc()

SFIZZ_EXPORTED_API void sfizz_send_cc ( sfizz_synth_t *  synth,
int  delay,
int  cc_number,
char  cc_value 
)

Send a CC event to the synth.

As with all MIDI events, this needs to happen before the call to sfizz_render_block in each block and should appear in order of the delays.

Parameters
synthThe synth
delaythe delay of the event in the block, in samples.
cc_numberthe MIDI CC number
cc_valuethe MIDI CC value

◆ sfizz_send_note_off()

SFIZZ_EXPORTED_API void sfizz_send_note_off ( sfizz_synth_t *  synth,
int  delay,
int  note_number,
char  velocity 
)

Send a note off event to the synth.

As with all MIDI events, this needs to happen before the call to sfizz_render_block in each block and should appear in order of the delays. As per the SFZ spec the velocity of note-off events is usually replaced by the note-on velocity.

Parameters
synthThe synth
delaythe delay of the event in the block, in samples.
note_numberthe MIDI note number
velocitythe MIDI velocity

◆ sfizz_send_note_on()

SFIZZ_EXPORTED_API void sfizz_send_note_on ( sfizz_synth_t *  synth,
int  delay,
int  note_number,
char  velocity 
)

Send a note on event to the synth.

As with all MIDI events, this needs to happen before the call to sfizz_render_block in each block and should appear in order of the delays.

Parameters
synthThe synth
delaythe delay of the event in the block, in samples.
note_numberthe MIDI note number
velocitythe MIDI velocity

◆ sfizz_send_pitch_wheel()

SFIZZ_EXPORTED_API void sfizz_send_pitch_wheel ( sfizz_synth_t *  synth,
int  delay,
int  pitch 
)

Send a pitch wheel event.

As with all MIDI events, this needs to happen before the call to sfizz_render_block in each block and should appear in order of the delays.

Parameters
synthThe synth
delayThe delay
pitchThe pitch

◆ sfizz_send_tempo()

SFIZZ_EXPORTED_API void sfizz_send_tempo ( sfizz_synth_t *  synth,
int  delay,
float  seconds_per_quarter 
)

Send a tempo event.

(CURRENTLY UNIMPLEMENTED)

Parameters
synthThe synth
delayThe delay
seconds_per_quarterThe seconds per quarter

◆ sfizz_set_num_voices()

SFIZZ_EXPORTED_API void sfizz_set_num_voices ( sfizz_synth_t *  synth,
int  num_voices 
)

Sets the number of voices used by the synth.

Parameters
synthThe synth
num_voicesThe number voices

◆ sfizz_set_oversampling_factor()

SFIZZ_EXPORTED_API bool sfizz_set_oversampling_factor ( sfizz_synth_t *  synth,
sfizz_oversampling_factor_t  oversampling 
)

Set the internal oversampling rate.

This is the sampling rate of the engine, not the output or expected rate of the calling function. For the latter use the set_sample_rate() functions.

Increasing this value (up to x8 oversampling) improves the quality of the output at the expense of memory consumption and background loading speed. The main render path still uses the same linear interpolation algorithm and should not see its performance decrease, but the files are oversampled upon loading which increases the stress on the background loader and reduce the loading speed. You can tweak the size of the preloaded data to compensate for the memory increase, but the full loading will need to take place anyway.

Parameters
synthThe synth
[in]preload_sizeThe preload size
Returns
True if the oversampling factor was correct

◆ sfizz_set_preload_size()

SFIZZ_EXPORTED_API void sfizz_set_preload_size ( sfizz_synth_t *  synth,
unsigned int  preload_size 
)

Sets the size of the preloaded data in number of floats (not bytes).

This will disable the callbacks for the duration of the load.

Parameters
synthThe synth
[in]preload_sizeThe preload size

◆ sfizz_set_sample_rate()

SFIZZ_EXPORTED_API void sfizz_set_sample_rate ( sfizz_synth_t *  synth,
float  sample_rate 
)

Sets the sample rate for the synth.

This is the output sample rate. This setting does not affect the internal processing.

Parameters
synthThe synth
sample_ratethe sample rate

◆ sfizz_set_samples_per_block()

SFIZZ_EXPORTED_API void sfizz_set_samples_per_block ( sfizz_synth_t *  synth,
int  samples_per_block 
)

Sets the expected number of samples per block.

If unsure, give an upper bound since right now ugly things may happen if you go over this number.

Parameters
synthThe synth
samples_per_blockthe number of samples per block

◆ sfizz_set_volume()

SFIZZ_EXPORTED_API void sfizz_set_volume ( sfizz_synth_t *  synth,
float  volume 
)

Set the global instrument volume.

Parameters
synthThe synth
volumethe new volume

◆ sfizz_should_reload_file()

SFIZZ_EXPORTED_API bool sfizz_should_reload_file ( sfizz_synth_t *  synth)

Check if the SFZ should be reloaded.

Depending on the platform this can create file descriptors.

Parameters
synth
Returns
true if any included files (including the root file) have been modified since the sfz file was loaded.
false