Skip to content

sfz::Sfizz Class Reference

#include <sfizz.hpp>

Main class.

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.

loadSfzFile

bool loadSfzFile (const std::string &path)

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

This function will disable all callbacks so it is safe to call from a UI thread for example, although it may generate a click. However it is not reentrant, so you should not call it from concurrent threads.
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 1 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 1 to 10.
Since
0.4.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,uint8_tvelocity)

Send a note on event to the synth.

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.
velocity the midi note velocity.
Since
0.2.0

noteOff

void noteOff (intdelay,intnoteNumber,uint8_tvelocity)

Send a note off event to the synth.

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.
velocity the midi note velocity.
Since
0.2.0

cc

void cc (intdelay,intccNumber,uint8_tccValue)

Send a CC event to the synth.

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.
ccValue the cc value.
Since
0.2.0

hdcc

void hdcc (intdelay,intccNumber,floatnormValue)

Send a high precision CC event to the synth.

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.
normValue the normalized cc value, in domain 0 to 1.
Since
0.4.0

pitchWheel

void pitchWheel (intdelay,intpitch)

Send a pitch bend event to the synth.

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

aftertouch

void aftertouch (intdelay,uint8_taftertouch)

Send a aftertouch event to the synth.

(CURRENTLY UNIMPLEMENTED)
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.
Since
0.2.0

tempo

void tempo (intdelay,floatsecondsPerBeat)

Send a tempo event to the synth.

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

timeSignature

void timeSignature (intdelay,intbeatsPerBar,intbeatUnit)

Send the time signature.

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.4.1

timePosition

void timePosition (intdelay,intbar,floatbarBeat)

Send the time position.

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

playbackState

void playbackState (intdelay,intplaybackState)

Send the playback state.

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

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).

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
numVoices The number of voices.
Since
0.2.0

setOversamplingFactor

bool setOversamplingFactor (intfactor)

Set the oversampling factor to a new value.

It will kill all the voices, and trigger a reloading of every file in the FilePool under the new oversampling.

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
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.

Since
0.2.0

setPreloadSize

void setPreloadSize (uint32_tpreloadSize)

Set the preloaded file size.

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 preload size is the same as the current one, it will release the lock immediately and exit.
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

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

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