Skip to content

sfz::Sfizz Class Reference

#include <sfizz.hpp>

Synthesizer for SFZ instruments.

Public Types

ProcessMode

enum ProcessMode {
ProcessLive
ProcessFreewheeling
}

Processing mode.

Since
0.4.0

Public Member Functions

Sfizz

Sfizz ()

Construct a new Sfizz object.

The synth by default is set at 48 kHz and a block size of 1024. You should change these values if they are not suited to your application.

Sfizz

Sfizz (Sfizz &&other)

Move constructor.

Parameters
other

operator=

Sfizz & operator= (Sfizz &&other)

Move assignment operator.

Parameters
other

Sfizz

Sfizz (sfizz_synth_t *synth)

Reference an existing synth handle.

Parameters
synth

handle

sfizz_synth_t * handle ()

Get the synth handle.

loadSfzFile

bool loadSfzFile (const std::string &path)

Empties the current regions and load a new SFZ file into the synth.

Parameters
path The path to the file to load, as string.
Returns
false if the file was not found or no regions were loaded, true otherwise.
Since
0.2.0

loadSfzString

bool loadSfzString (const std::string &path,const std::string &text)

Empties the current regions and load a new SFZ document from memory.

This is similar to loadSfzFile() in functionality. 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
path The virtual path of the SFZ file, as string.
text The contents of the virtual SFZ file.
Returns
false if no regions were loaded, true otherwise.
Since
0.4.0

loadScalaFile

bool loadScalaFile (const std::string &path)

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

Parameters
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

loadScalaString

bool loadScalaString (const std::string &text)

Sets the tuning from a Scala file loaded from memory.

Parameters
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

setScalaRootKey

void setScalaRootKey (introotKey)

Sets the scala root key.

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

getScalaRootKey

int getScalaRootKey ()

Gets the scala root key.

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

setTuningFrequency

void setTuningFrequency (floatfrequency)

Sets the reference tuning frequency.

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

getTuningFrequency

float getTuningFrequency ()

Gets the reference tuning frequency.

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

loadStretchTuningByRatio

void loadStretchTuningByRatio (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
ratio The parameter in domain 0-1.
Since
0.4.0

getNumRegions

int getNumRegions ()

Return the current number of regions loaded.

Since
0.2.0

getNumGroups

int getNumGroups ()

Return the current number of groups loaded.

Since
0.2.0

getNumMasters

int getNumMasters ()

Return the current number of masters loaded.

Since
0.2.0

getNumCurves

int getNumCurves ()

Return the current number of curves loaded.

Since
0.2.0

getUnknownOpcodes

const std::vector< std::string > & getUnknownOpcodes ()

Return a list of unsupported opcodes, if any.

Since
0.2.0

getNumPreloadedSamples

size_t getNumPreloadedSamples ()

Return the number of preloaded samples in the synth.

Since
0.2.0

setSamplesPerBlock

void setSamplesPerBlock (intsamplesPerBlock)

Set the maximum size of the blocks for the callback.

The actual size can be lower in each callback but should not be larger than this value.
Parameters
samplesPerBlock The number of samples per block.
Since
0.2.0

setSampleRate

void setSampleRate (floatsampleRate)

Set the sample rate.

If you do not call it it is initialized to sfz::config::defaultSampleRate.
Parameters
sampleRate The sample rate.
Since
0.2.0

getSampleQuality

int getSampleQuality (ProcessModemode)

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
mode The processing mode.
Returns
The sample quality for the given mode, in the range 0 to 10.
Since
0.4.0

setSampleQuality

void setSampleQuality (ProcessModemode,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
mode The processing mode.
quality The desired sample quality, in the range 0 to 10.
Since
0.4.0

getOscillatorQuality

int getOscillatorQuality (ProcessModemode)

Get the default oscillator quality.

This is the quality setting which the engine uses when the instrument does not use the opcode oscillator_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
mode The processing mode.
Returns
The oscillator quality for the given mode, in the range 0 to 3.
Since
1.0.0

setOscillatorQuality

void setOscillatorQuality (ProcessModemode,intquality)

Set the default oscillator quality.

This is the quality setting which the engine uses when the instrument does not use the opcode oscillator_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
mode The processing mode.
quality The desired oscillator quality, in the range 0 to 3.
Since
1.0.0

getVolume

float getVolume ()

Return the current value for the volume, in dB.

Since
0.2.0

setVolume

void setVolume (floatvolume)

Set the value for the volume.

This value will be clamped within sfz::default::volumeRange.
Parameters
volume The new volume.
Since
0.2.0

noteOn

void noteOn (intdelay,intnoteNumber,intvelocity)

Send a note on event to the synth.

This command should be delay-ordered with all other midi-type events (notes, CCs, aftertouch and pitch-wheel), otherwise the behavior of the synth is undefined.
Parameters
delay the delay at which the event occurs; this should be lower than the size of the block in the next call to renderBlock().
noteNumber the midi note number, in domain 0 to 127.
velocity the midi note velocity, in domain 0 to 127.
Since
0.2.0

hdNoteOn

void hdNoteOn (intdelay,intnoteNumber,floatvelocity)

Send a high-precision note on event to the synth.

This command should be delay-ordered with all other midi-type events (notes, CCs, aftertouch and pitch-wheel), otherwise the behavior of the synth is undefined.
Parameters
delay the delay at which the event occurs; this should be lower than the size of the block in the next call to renderBlock().
noteNumber the midi note number, in domain 0 to 127.
velocity the normalized midi note velocity, in domain 0 to 1.
Since
1.0.0

noteOff

void noteOff (intdelay,intnoteNumber,intvelocity)

Send a note off event to the synth.

This command should be delay-ordered with all other midi-type events (notes, CCs, aftertouch and pitch-wheel), otherwise the behavior of the synth is undefined.
Parameters
delay the delay at which the event occurs; this should be lower than the size of the block in the next call to renderBlock().
noteNumber the midi note number, in domain 0 to 127.
velocity the midi note velocity, in domain 0 to 127.
Since
0.2.0

hdNoteOff

void hdNoteOff (intdelay,intnoteNumber,floatvelocity)

Send a note off event to the synth.

This command should be delay-ordered with all other midi-type events (notes, CCs, aftertouch and pitch-wheel), otherwise the behavior of the synth is undefined.
Parameters
delay the delay at which the event occurs; this should be lower than the size of the block in the next call to renderBlock().
noteNumber the midi note number, in domain 0 to 127.
velocity the normalized midi note velocity, in domain 0 to 1.
Since
1.0.0

cc

void cc (intdelay,intccNumber,intccValue)

Send a CC event to the synth.

This command should be delay-ordered with all other midi-type events (notes, CCs, aftertouch and pitch-wheel), otherwise the behavior of the synth is undefined.
Parameters
delay the delay at which the event occurs; this should be lower than the size of the block in the next call to renderBlock().
ccNumber the cc number, in domain 0 to 127.
ccValue the cc value, in domain 0 to 127.
Since
0.2.0

hdcc

void hdcc (intdelay,intccNumber,floatnormValue)

Send a high precision CC event to the synth.

This command should be delay-ordered with all other midi-type events (notes, CCs, aftertouch and pitch-wheel), otherwise the behavior of the synth is undefined.
Parameters
delay the delay at which the event occurs; this should be lower than the size of the block in the next call to renderBlock().
ccNumber the cc number, in domain 0 to 127.
normValue the normalized cc value, in domain 0 to 1.
Since
0.4.0

automateHdcc

void automateHdcc (intdelay,intccNumber,floatnormValue)

Send a high precision CC automation to the synth.

This updates the CC value known to the synth, but without performing additional MIDI-specific interpretations. (eg. the CC 120 and up)
Parameters
delay the delay at which the event occurs; this should be lower than the size of the block in the next call to renderBlock().
ccNumber the cc number, in domain 0 to 127.
normValue the normalized cc value, in domain 0 to 1.
Since
1.0.0

pitchWheel

void pitchWheel (intdelay,intpitch)

Send a pitch bend event to the synth.

This command should be delay-ordered with all other midi-type events (notes, CCs, aftertouch and pitch-wheel), otherwise the behavior of the synth is undefined.
Parameters
delay the delay at which the event occurs; this should be lower than the size of the block in the next call to renderBlock().
pitch the pitch value centered between -8192 and 8192.
Since
0.2.0

hdPitchWheel

void hdPitchWheel (intdelay,floatpitch)

Send a high-precision pitch bend event to the synth.

This command should be delay-ordered with all other midi-type events (notes, CCs, aftertouch and pitch-wheel), otherwise the behavior of the synth is undefined.
Parameters
delay the delay at which the event occurs; this should be lower than the size of the block in the next call to renderBlock().
pitch the normalized pitch, in domain -1 to 1.
Since
1.0.0

aftertouch

SFIZZ_DEPRECATED_API void aftertouch (intdelay,intaftertouch)

Send an aftertouch event to the synth.

This command should be delay-ordered with all other midi-type events (notes, CCs, aftertouch and pitch-wheel), otherwise the behavior of the synth is undefined.
Parameters
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, in domain 0 to 127.
Since
0.2.0

channelAftertouch

void channelAftertouch (intdelay,intaftertouch)

Send a channel aftertouch (channel pressure) event to the synth.

This command should be delay-ordered with all other midi-type events (notes, CCs, aftertouch and pitch-wheel), otherwise the behavior of the synth is undefined.
Parameters
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, in domain 0 to 127.
Since
0.2.0

hdChannelAftertouch

void hdChannelAftertouch (intdelay,floataftertouch)

Send a high-precision aftertouch event to the synth.

This command should be delay-ordered with all other midi-type events (notes, CCs, aftertouch and pitch-wheel), otherwise the behavior of the synth is undefined.
Parameters
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 normalized aftertouch value, in domain 0 to 1.
Since
1.0.0

polyAftertouch

void polyAftertouch (intdelay,intnoteNumber,intaftertouch)

Send a polyphonic aftertouch event to the synth.

This feature is experimental and needs more testing in the internal engine.
Parameters
delay the delay at which the event occurs; this should be lower than the size of the block in the next call to renderBlock().
noteNumber the note number, in domain 0 to 127.
aftertouch the aftertouch value, in domain 0 to 127.
Since
1.0.0

hdPolyAftertouch

void hdPolyAftertouch (intdelay,intnoteNumber,floataftertouch)

Send a high-precision polyphonic aftertouch event to the synth.

This feature is experimental and needs more testing in the internal engine.
Parameters
delay the delay at which the event occurs; this should be lower than the size of the block in the next call to renderBlock().
noteNumber the note number, in domain 0 to 127.
aftertouch the normalized aftertouch value, in domain 0 to 1.
Since
1.0.0

tempo

SFIZZ_DEPRECATED_API void tempo (intdelay,floatsecondsPerBeat)

Send a tempo event to the synth.

This command should be delay-ordered with all other time/signature commands, namely tempo(), timeSignature(), timePosition(), and playbackState(), otherwise the behavior of the synth is undefined.
Parameters
delay the delay at which the event occurs; this should be lower than the size of the block in the next call to renderBlock().
secondsPerBeat the new period of the beat.
Since
0.2.0

bpmTempo

void bpmTempo (intdelay,floatbeatsPerMinute)

Send a tempo event to the synth.

This command should be delay-ordered with all other time/signature commands, namely tempo(), timeSignature(), timePosition(), and playbackState(), otherwise the behavior of the synth is undefined.
Parameters
delay the delay at which the event occurs; this should be lower than the size of the block in the next call to renderBlock().
beatsPerMinute the new tempo, in beats per minute.
Since
1.0.0

timeSignature

void timeSignature (intdelay,intbeatsPerBar,intbeatUnit)

Send the time signature.

This command should be delay-ordered with all other time/signature commands, namely tempo(), timeSignature(), timePosition(), and playbackState(), otherwise the behavior of the synth is undefined.
Parameters
delay The delay.
beatsPerBar The number of beats per bar, or time signature numerator.
beatUnit The note corresponding to one beat, or time signature denominator.
Since
0.5.0

timePosition

void timePosition (intdelay,intbar,doublebarBeat)

Send the time position.

This command should be delay-ordered with all other time/signature commands, namely tempo(), timeSignature(), timePosition(), and playbackState(), otherwise the behavior of the synth is undefined.
Parameters
delay The delay.
bar The current bar.
barBeat The fractional position of the current beat within the bar.
Since
0.5.0

playbackState

void playbackState (intdelay,intplaybackState)

Send the playback state.

This command should be delay-ordered with all other time/signature commands, namely tempo(), timeSignature(), timePosition(), and playbackState(), otherwise the behavior of the synth is undefined.
Parameters
delay The delay.
playbackState The playback state, 1 if playing, 0 if stopped.
Since
0.5.0

renderBlock

void renderBlock (float **buffers,size_tnumFrames,intnumOutputs)

Render an block of audio data in the buffer.

This call will reset the synth in its waiting state for the next batch of events. The buffers must be float[numSamples][numOutputs * 2].
Parameters
buffers the buffers to write the next block into.
numFrames the number of stereo frames in the block.
numOutputs the number of stereo outputs.
Since
0.2.0

getNumActiveVoices

int getNumActiveVoices ()

Return the number of active voices.

Since
0.2.0

getNumVoices

int getNumVoices ()

Return the total number of voices in the synth (the polyphony).

Since
0.2.0

setNumVoices

void setNumVoices (intnumVoices)

Change the number of voices (the polyphony).

Parameters
numVoices The number of voices.
Since
0.2.0

setOversamplingFactor

bool setOversamplingFactor (intfactor)

Set the oversampling factor to a new value.

As of 1.0, This is an inactive stub for future work on oversampling in the engine.
Parameters
factor The oversampling factor.
Returns
true if the factor did indeed change, false otherwise.
Since
0.2.0

getOversamplingFactor

int getOversamplingFactor ()

Return the current oversampling factor.

As of 1.0, This is an inactive stub for future work on oversampling in the engine.
Since
0.2.0

setPreloadSize

void setPreloadSize (uint32_tpreloadSize)

Set the preloaded file size.

Parameters
preloadSize The preload size.
Since
0.2.0

getPreloadSize

uint32_t getPreloadSize ()

Return the current preloaded file size.

Since
0.2.0

getAllocatedBuffers

int getAllocatedBuffers ()

Return the number of allocated buffers.

Since
0.2.0

getAllocatedBytes

int getAllocatedBytes ()

Return the number of bytes allocated through the buffers.

Since
0.2.0

enableFreeWheeling

void enableFreeWheeling ()

Enable freewheeling on the synth.

This will wait for background loaded files to finish loading before each render callback to ensure that there will be no dropouts.
Since
0.2.0

disableFreeWheeling

void disableFreeWheeling ()

Disable freewheeling on the synth.

You should disable freewheeling before live use of the plugin otherwise the audio thread will lock.
Since
0.2.0

shouldReloadFile

bool shouldReloadFile ()

Check if the SFZ should be reloaded.

Depending on the platform this can create file descriptors.
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

shouldReloadScala

bool shouldReloadScala ()

Check if the tuning (scala) file should be reloaded.

Depending on the platform this can create file descriptors.
Returns
true if a scala file has been loaded and has changed, false otherwise.
Since
0.4.0

enableLogging

SFIZZ_DEPRECATED_API void enableLogging ()

Enable logging of timings to sidecar CSV files.

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

enableLogging

void enableLogging (const std::string &prefix)

Enable logging of timings to sidecar CSV files.

Parameters
prefix the file prefix to use for logging.
Since
0.3.2
Note
This can produce many outputs so use with caution.

setLoggingPrefix

SFIZZ_DEPRECATED_API void setLoggingPrefix (const std::string &prefix)

Set the logging prefix.

Parameters
prefix
Since
0.3.2

disableLogging

void disableLogging ()

Disable logging of timings to sidecar CSV files.

Since
0.3.0

allSoundOff

void allSoundOff ()

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

Since
0.3.2

addExternalDefinition

void addExternalDefinition (const std::string &id,const std::string &value)

Add external definitions prior to loading.

Parameters
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 clearExternalDefintions() to erase them.

clearExternalDefinitions

void clearExternalDefinitions ()

Clears external definitions for the next file loading.

Since
0.4.0

getKeyLabels

const std::vector< std::pair< uint8_t, std::string > > & getKeyLabels ()

Get the key labels, if any.

Since
0.4.0

getCCLabels

const std::vector< std::pair< uint16_t, std::string > > & getCCLabels ()

Get the CC labels, if any.

Since
0.4.0

exportMidnam

std::string exportMidnam (const std::string &model)

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

Parameters
model The model name used if a non-empty string, otherwise generated.
Returns
A XML string.
Since
1.0.0

sendMessage

void sendMessage (Client &client,intdelay,const char *path,const char *sig,const sfizz_arg_t *args)

Send a message to the synth engine.

Parameters
client The client sending the message.
delay The delay of the message in the block, in samples.
path The OSC address pattern.
sig The OSC type tag string.
args The OSC arguments, whose number and format is determined the type tag string.
Since
1.0.0

setBroadcastCallback

void setBroadcastCallback (sfizz_receive_t *broadcast,void *data)

Set the function which receives broadcast messages from the synth engine.

Parameters
broadcast The pointer to the receiving function.
data The opaque data pointer which is passed to the receiver.
Since
1.0.0

createClient

Create a new messaging client.

Since
1.0.0

getClientData

Get the client data.

Since
1.0.0

setReceiveCallback

Set the function which receives reply messages from the synth engine.

Since
1.0.0