sfz::Sfizz Class Reference
#include <sfizz.hpp>
Synthesizer for SFZ instruments.
Public Types
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
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 | ( | int | rootKey | ) |
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 | ( | float | frequency | ) |
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 | ( | float | ratio | ) |
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 | ( | int | samplesPerBlock | ) |
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 | ( | float | sampleRate | ) |
Set the sample rate.
If you do not call it it is initialized tosfz::config::defaultSampleRate
.- Parameters
-
sampleRate The sample rate.
- Since
- 0.2.0
getSampleQuality
int getSampleQuality | ( | ProcessMode | mode | ) |
Get the default resampling quality.
This is the quality setting which the engine uses when the instrument does not use the opcodesample_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 | ( | ProcessMode | mode | , | int | quality | ) |
Set the default resampling quality.
This is the quality setting which the engine uses when the instrument does not use the opcodesample_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 | ( | ProcessMode | mode | ) |
Get the default oscillator quality.
This is the quality setting which the engine uses when the instrument does not use the opcodeoscillator_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 | ( | ProcessMode | mode | , | int | quality | ) |
Set the default oscillator quality.
This is the quality setting which the engine uses when the instrument does not use the opcodeoscillator_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 | ( | float | volume | ) |
Set the value for the volume.
This value will be clamped withinsfz::default::volumeRange
.- Parameters
-
volume The new volume.
- Since
- 0.2.0
noteOn
void noteOn | ( | int | delay | , | int | noteNumber | , | int | velocity | ) |
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 | ( | int | delay | , | int | noteNumber | , | float | velocity | ) |
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 | ( | int | delay | , | int | noteNumber | , | int | velocity | ) |
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 | ( | int | delay | , | int | noteNumber | , | float | velocity | ) |
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 | ( | int | delay | , | int | ccNumber | , | int | ccValue | ) |
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 | ( | int | delay | , | int | ccNumber | , | float | normValue | ) |
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 | ( | int | delay | , | int | ccNumber | , | float | normValue | ) |
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 | ( | int | delay | , | int | pitch | ) |
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 | ( | int | delay | , | float | pitch | ) |
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 | ( | int | delay | , | int | aftertouch | ) |
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 | ( | int | delay | , | int | aftertouch | ) |
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 | ( | int | delay | , | float | aftertouch | ) |
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 | ( | int | delay | , | int | noteNumber | , | int | aftertouch | ) |
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 | ( | int | delay | , | int | noteNumber | , | float | aftertouch | ) |
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 | ( | int | delay | , | float | secondsPerBeat | ) |
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 | ( | int | delay | , | float | beatsPerMinute | ) |
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 | ( | int | delay | , | int | beatsPerBar | , | int | beatUnit | ) |
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 | ( | int | delay | , | int | bar | , | double | barBeat | ) |
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 | ( | int | delay | , | int | playbackState | ) |
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_t | numFrames | , | int | numOutputs | ) |
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 | ( | int | numVoices | ) |
Change the number of voices (the polyphony).
- Parameters
-
numVoices The number of voices.
- Since
- 0.2.0
setOversamplingFactor
bool setOversamplingFactor | ( | int | factor | ) |
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_t | preloadSize | ) |
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 | , | int | delay | , | 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