Skip to content

sfizz.h File Reference


sfizz public C API.

Macros

SFIZZ_OUT_OF_BOUNDS_LABEL_INDEX

#define SFIZZ_OUT_OF_BOUNDS_LABEL_INDEX -1

Index out of bound error for the requested CC/key label.

Since
0.4.0

Enumerations

sfizz_oversampling_factor_t

enum sfizz_oversampling_factor_t {
SFIZZ_OVERSAMPLING_X1 = 1
SFIZZ_OVERSAMPLING_X2 = 2
SFIZZ_OVERSAMPLING_X4 = 4
SFIZZ_OVERSAMPLING_X8 = 8
}

Oversampling factor.

Since
0.2.0

sfizz_process_mode_t

enum sfizz_process_mode_t {
SFIZZ_PROCESS_LIVE
SFIZZ_PROCESS_FREEWHEELING
}

Processing mode.

Since
0.4.1

Typedefs

sfizz_synth_t

typedef struct sfizz_synth_t sfizz_synth_t

Synth handle.

Since
0.2.0

Functions

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.

Since
0.2.0

sfizz_free

SFIZZ_EXPORTED_API void sfizz_free (sfizz_synth_t *synth)

Frees an existing sfizz synth.

Parameters
synth The synth to destroy.
Since
0.2.0

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
synth The synth.
path A null-terminated string representing a path to an SFZ file.
Returns
true when file loading went OK, false if some error occured while loading.
Since
0.2.0

sfizz_load_string

SFIZZ_EXPORTED_API bool sfizz_load_string (sfizz_synth_t *synth,const char *path,const char *text)

Loads an SFZ file from textual data.

This accepts a virtual path name for the imaginary sfz file, which is not required to exist on disk. The purpose of the virtual path is to locate samples with relative paths.

Parameters
synth The synth.
path The virtual path of the SFZ file.
text The contents of the virtual SFZ file.
Returns
true when file loading went OK, false if some error occured while loading.
Since
0.4.0

sfizz_load_scala_file

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

Sets the tuning from a Scala file loaded from the file system.

Parameters
synth The synth.
path The path to the file in Scala format.
Returns
true when tuning scale loaded OK, false if some error occurred.
Since
0.4.0

sfizz_load_scala_string

SFIZZ_EXPORTED_API bool sfizz_load_scala_string (sfizz_synth_t *synth,const char *text)

Sets the tuning from a Scala file loaded from memory.

Parameters
synth The synth.
text The contents of the file in Scala format.
Returns
true when tuning scale loaded OK, false if some error occurred.
Since
0.4.0

sfizz_set_scala_root_key

SFIZZ_EXPORTED_API void sfizz_set_scala_root_key (sfizz_synth_t *synth,introot_key)

Sets the scala root key.

Parameters
synth The synth.
root_key The MIDI number of the Scala root key (default 60 for C4).
Since
0.4.0

sfizz_get_scala_root_key

SFIZZ_EXPORTED_API int sfizz_get_scala_root_key (sfizz_synth_t *synth)

Gets the scala root key.

Parameters
synth The synth.
Returns
The MIDI number of the Scala root key (default 60 for C4).
Since
0.4.0

sfizz_set_tuning_frequency

SFIZZ_EXPORTED_API void sfizz_set_tuning_frequency (sfizz_synth_t *synth,floatfrequency)

Sets the reference tuning frequency.

Parameters
synth The synth.
frequency The frequency which indicates where standard tuning A4 is (default 440 Hz).
Since
0.4.0

sfizz_get_tuning_frequency

SFIZZ_EXPORTED_API float sfizz_get_tuning_frequency (sfizz_synth_t *synth)

Gets the reference tuning frequency.

Parameters
synth The synth.
Returns
The frequency which indicates where standard tuning A4 is (default 440 Hz).
Since
0.4.0

sfizz_load_stretch_tuning_by_ratio

SFIZZ_EXPORTED_API void sfizz_load_stretch_tuning_by_ratio (sfizz_synth_t *synth,floatratio)

Configure stretch tuning using a predefined parametric Railsback curve.

A ratio 1/2 is supposed to match the average piano; 0 disables (the default).

Parameters
synth The synth.
ratio The parameter in domain 0-1.
Since
0.4.0

sfizz_get_num_regions

SFIZZ_EXPORTED_API int sfizz_get_num_regions (sfizz_synth_t *synth)

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

Parameters
synth The synth.
Since
0.2.0

sfizz_get_num_groups

SFIZZ_EXPORTED_API int sfizz_get_num_groups (sfizz_synth_t *synth)

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

Parameters
synth The synth.
Since
0.2.0

sfizz_get_num_masters

SFIZZ_EXPORTED_API int sfizz_get_num_masters (sfizz_synth_t *synth)

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

Parameters
synth The synth.
Since
0.2.0

sfizz_get_num_curves

SFIZZ_EXPORTED_API int sfizz_get_num_curves (sfizz_synth_t *synth)

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

Parameters
synth The synth.
Since
0.2.0

sfizz_export_midnam

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

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

Parameters
synth The synth.
model The model name used if a non-empty string, otherwise generated.
Returns
A newly allocated XML string, which must be freed after use.
Since
0.3.1

sfizz_get_num_preloaded_samples

SFIZZ_EXPORTED_API size_t sfizz_get_num_preloaded_samples (sfizz_synth_t *synth)

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

Parameters
synth The synth.
Since
0.2.0

sfizz_get_num_active_voices

SFIZZ_EXPORTED_API int sfizz_get_num_active_voices (sfizz_synth_t *synth)

Return 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
synth The synth.
Since
0.2.0

sfizz_set_samples_per_block

SFIZZ_EXPORTED_API void sfizz_set_samples_per_block (sfizz_synth_t *synth,intsamples_per_block)

Set 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
synth The synth.
samples_per_block The number of samples per block.
Since
0.2.0

sfizz_set_sample_rate

SFIZZ_EXPORTED_API void sfizz_set_sample_rate (sfizz_synth_t *synth,floatsample_rate)

Set the sample rate for the synth.

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

Parameters
synth The synth
sample_rate The sample rate.
Since
0.2.0

sfizz_send_note_on

SFIZZ_EXPORTED_API void sfizz_send_note_on (sfizz_synth_t *synth,intdelay,intnote_number,charvelocity)

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
synth The synth.
delay The delay of the event in the block, in samples.
note_number The MIDI note number.
velocity The MIDI velocity.
Since
0.2.0

sfizz_send_note_off

SFIZZ_EXPORTED_API void sfizz_send_note_off (sfizz_synth_t *synth,intdelay,intnote_number,charvelocity)

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.

Parameters
synth The synth.
delay The delay of the event in the block, in samples.
note_number The MIDI note number.
velocity The MIDI velocity.
Since
0.2.0

sfizz_send_cc

SFIZZ_EXPORTED_API void sfizz_send_cc (sfizz_synth_t *synth,intdelay,intcc_number,charcc_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
synth The synth.
delay The delay of the event in the block, in samples.
cc_number The MIDI CC number.
cc_value The MIDI CC value.
Since
0.2.0

sfizz_send_hdcc

SFIZZ_EXPORTED_API void sfizz_send_hdcc (sfizz_synth_t *synth,intdelay,intcc_number,floatnorm_value)

Send a high precision 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
synth The synth.
delay The delay of the event in the block, in samples.
cc_number The MIDI CC number.
norm_value The normalized CC value, in domain 0 to 1.
Since
0.4.0

sfizz_send_pitch_wheel

SFIZZ_EXPORTED_API void sfizz_send_pitch_wheel (sfizz_synth_t *synth,intdelay,intpitch)

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
synth The synth.
delay The delay.
pitch The pitch.
Since
0.4.0

sfizz_send_aftertouch

SFIZZ_EXPORTED_API void sfizz_send_aftertouch (sfizz_synth_t *synth,intdelay,charaftertouch)

Send an aftertouch event.

(CURRENTLY UNIMPLEMENTED)

Parameters
synth The synth.
delay The delay at which the event occurs; this should be lower than the size of the block in the next call to renderBlock().
aftertouch The aftertouch value.
Since
0.2.0

sfizz_send_tempo

SFIZZ_EXPORTED_API void sfizz_send_tempo (sfizz_synth_t *synth,intdelay,floatseconds_per_beat)

Send a tempo event.

Parameters
synth The synth.
delay The delay.
seconds_per_beat The seconds per beat.
Since
0.2.0

sfizz_send_time_signature

SFIZZ_EXPORTED_API void sfizz_send_time_signature (sfizz_synth_t *synth,intdelay,intbeats_per_bar,intbeat_unit)

Send the time signature.

Parameters
synth The synth.
delay The delay.
beats_per_bar The number of beats per bar, or time signature numerator.
beat_unit The note corresponding to one beat, or time signature denominator.
Since
0.4.1

sfizz_send_time_position

SFIZZ_EXPORTED_API void sfizz_send_time_position (sfizz_synth_t *synth,intdelay,intbar,floatbar_beat)

Send the time position.

Parameters
synth The synth.
delay The delay.
bar The current bar.
bar_beat The fractional position of the current beat within the bar.
Since
0.4.1

sfizz_send_playback_state

SFIZZ_EXPORTED_API void sfizz_send_playback_state (sfizz_synth_t *synth,intdelay,intplayback_state)

Send the playback state.

Parameters
synth The synth.
delay The delay.
playback_state The playback state, 1 if playing, 0 if stopped.
Since
0.4.1

sfizz_render_block

SFIZZ_EXPORTED_API void sfizz_render_block (sfizz_synth_t *synth,float **channels,intnum_channels,intnum_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
synth The synth.
channels Pointers to the left and right channel of the output.
num_channels Should be equal to 2 for the time being.
num_frames Number of frames to fill. This should be less than or equal to the expected samples_per_block.
Since
0.2.0

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
synth The synth.
Since
0.2.0

sfizz_set_preload_size

SFIZZ_EXPORTED_API void sfizz_set_preload_size (sfizz_synth_t *synth,unsigned intpreload_size)

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

This will disable the callbacks for the duration of the load. This function takes a lock ; prefer calling it out of the RT thread. It can also take a long time to return. If the new preload size is the same as the current one, it will release the lock immediately and exit.

Parameters
synth The synth.
preload_size The preload size.
Since
0.2.0

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 sfizz_get_sample_rate() function.

Parameters
synth The synth.
Since
0.2.0

sfizz_set_oversampling_factor

SFIZZ_EXPORTED_API bool sfizz_set_oversampling_factor (sfizz_synth_t *synth,sfizz_oversampling_factor_toversampling)

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 sfizz_set_sample_rate() function.

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.

This function takes a lock and disables the callback; prefer calling it out of the RT thread. It can also take a long time to return. If the new oversampling factor is the same as the current one, it will release the lock immediately and exit.

Parameters
synth The synth.
oversampling The oversampling factor.
Returns
true if the oversampling factor was correct, false otherwise.
Since
0.2.0

sfizz_get_sample_quality

SFIZZ_EXPORTED_API int sfizz_get_sample_quality (sfizz_synth_t *synth,sfizz_process_mode_tmode)

Get the default resampling quality.

This is the quality setting which the engine uses when the instrument does not use the opcode sample_quality. The engine uses distinct default quality settings for live mode and freewheeling mode, which both can be accessed by the means of this function.

Parameters
synth The synth.
mode The processing mode.
Returns
The sample quality for the given mode, in the range 1 to 10.
Since
0.4.0

sfizz_set_sample_quality

SFIZZ_EXPORTED_API void sfizz_set_sample_quality (sfizz_synth_t *synth,sfizz_process_mode_tmode,intquality)

Set the default resampling quality.

This is the quality setting which the engine uses when the instrument does not use the opcode sample_quality. The engine uses distinct default quality settings for live mode and freewheeling mode, which both can be accessed by the means of this function.

Parameters
synth The synth.
mode The processing mode.
quality The desired sample quality, in the range 1 to 10.
Since
0.4.0

sfizz_set_volume

SFIZZ_EXPORTED_API void sfizz_set_volume (sfizz_synth_t *synth,floatvolume)

Set the global instrument volume.

Parameters
synth The synth.
volume The new volume.
Since
0.2.0

sfizz_get_volume

SFIZZ_EXPORTED_API float sfizz_get_volume (sfizz_synth_t *synth)

Return the global instrument volume.

Parameters
synth The synth.
Since
0.2.0

sfizz_set_num_voices

SFIZZ_EXPORTED_API void sfizz_set_num_voices (sfizz_synth_t *synth,intnum_voices)

Set the number of voices used by the synth.

This function takes a lock and disables the callback; prefer calling it out of the RT thread. It can also take a long time to return. If the new number of voices is the same as the current one, it will release the lock immediately and exit.

Parameters
synth The synth.
num_voices The number of voices.
Since
0.2.0

sfizz_get_num_voices

SFIZZ_EXPORTED_API int sfizz_get_num_voices (sfizz_synth_t *synth)

Return the number of voices.

Parameters
synth The synth.
Since
0.2.0

sfizz_get_num_buffers

SFIZZ_EXPORTED_API int sfizz_get_num_buffers (sfizz_synth_t *synth)

Return the number of allocated buffers from the synth.

Parameters
synth The synth.
Since
0.2.0

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
synth The synth.
Since
0.2.0

sfizz_enable_freewheeling

SFIZZ_EXPORTED_API void sfizz_enable_freewheeling (sfizz_synth_t *synth)

Enable freewheeling on the synth.

Parameters
synth The synth.
Since
0.2.0

sfizz_disable_freewheeling

SFIZZ_EXPORTED_API void sfizz_disable_freewheeling (sfizz_synth_t *synth)

Disable freewheeling on the synth.

Parameters
synth The synth.
Since
0.2.0

sfizz_get_unknown_opcodes

SFIZZ_EXPORTED_API char * sfizz_get_unknown_opcodes (sfizz_synth_t *synth)

Return 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 The synth.
Since
0.2.0

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 The synth.
Returns
true if any included files (including the root file) have been modified since the sfz file was loaded, false otherwise.
Since
0.2.0

sfizz_should_reload_scala

SFIZZ_EXPORTED_API bool sfizz_should_reload_scala (sfizz_synth_t *synth)

Check if the scala file should be reloaded.

Depending on the platform this can create file descriptors.

Parameters
synth The synth.
Returns
true if the scala file has been modified since loading.
Since
0.4.0

sfizz_enable_logging

SFIZZ_EXPORTED_API void sfizz_enable_logging (sfizz_synth_t *synth)

Enable logging of timings to sidecar CSV files.

Parameters
synth The synth.
Since
0.3.0
Note
This can produce many outputs so use with caution.

sfizz_disable_logging

SFIZZ_EXPORTED_API void sfizz_disable_logging (sfizz_synth_t *synth)

Disable logging.

Parameters
synth The synth.
Since
0.3.0

sfizz_set_logging_prefix

SFIZZ_EXPORTED_API void sfizz_set_logging_prefix (sfizz_synth_t *synth,const char *prefix)

Enable logging of timings to sidecar CSV files.

Parameters
synth The synth.
prefix The prefix.
Since
0.3.2
Note
This can produce many outputs so use with caution.

sfizz_all_sound_off

SFIZZ_EXPORTED_API void sfizz_all_sound_off (sfizz_synth_t *synth)

Shuts down the current processing, clear buffers and reset the voices.

Parameters
synth The synth.
Since
0.3.2

sfizz_add_external_definitions

SFIZZ_EXPORTED_API void sfizz_add_external_definitions (sfizz_synth_t *synth,const char *id,const char *value)

Add external definitions prior to loading.

Parameters
synth The synth.
id The definition variable name.
value The definition value.
Since
0.4.0
Note
These do not get reset by loading or resetting the synth. You need to call sfizz_clear_external_definitions() to erase them.

sfizz_clear_external_definitions

SFIZZ_EXPORTED_API void sfizz_clear_external_definitions (sfizz_synth_t *synth)

Clears external definitions for the next file loading.

Parameters
synth The synth.
Since
0.4.0

sfizz_get_num_key_labels

SFIZZ_EXPORTED_API unsigned int sfizz_get_num_key_labels (sfizz_synth_t *synth)

Get the number of key labels registered in the current sfz file.

Parameters
synth The synth.
Since
0.4.0

sfizz_get_key_label_number

SFIZZ_EXPORTED_API int sfizz_get_key_label_number (sfizz_synth_t *synth,intlabel_index)

Get the key number for the label registered at index label_index.

Parameters
synth The synth.
label_index The label index.
Returns
the number or SFIZZ_OUT_OF_BOUNDS_LABEL_INDEX if the index is out of bounds.
Since
0.4.0

sfizz_get_key_label_text

SFIZZ_EXPORTED_API const char * sfizz_get_key_label_text (sfizz_synth_t *synth,intlabel_index)

Get the key text for the label registered at index label_index.

Parameters
synth The synth.
label_index The label index.
Returns
the label or NULL if the index is out of bounds.
Since
0.4.0

sfizz_get_num_cc_labels

SFIZZ_EXPORTED_API unsigned int sfizz_get_num_cc_labels (sfizz_synth_t *synth)

Get the number of CC labels registered in the current sfz file.

Parameters
synth The synth.
Since
0.4.0

sfizz_get_cc_label_number

SFIZZ_EXPORTED_API int sfizz_get_cc_label_number (sfizz_synth_t *synth,intlabel_index)

Get the CC number for the label registered at index label_index.

Parameters
synth The synth.
label_index The label index.
Returns
the number or SFIZZ_OUT_OF_BOUNDS_LABEL_INDEX if the index is out of bounds.
Since
0.4.0

sfizz_get_cc_label_text

SFIZZ_EXPORTED_API const char * sfizz_get_cc_label_text (sfizz_synth_t *synth,intlabel_index)

Get the CC text for the label registered at index label_index.

Parameters
synth The synth.
label_index The label index.
Returns
the label or NULL if the index is out of bounds.
Since
0.4.0