sfz File Format

This opcode defines which sample file the region will play.
The value of this opcode is the filename of the sample file, including the extension. The filename must be stored in the same folder where the definition file is, or specified relatively to it.

If the sample file is not found, the player will ignore the whole region contents.

Long names and names with blank spaces and other special characters (excepting the = character) are allowed in the sample definition.

The sample will play unchanged when a note equal to the pitch_keycenter opcode value is played. If pitch_keycenter is not defined for the region, sample will play unchanged on note 60 (middle C).

Examples:
sample=guitar_c4_ff.wav
sample=dog kick.ogg
sample=out of tune trombone (redundant).wav
sample=staccatto_snare.ogg

If incoming notes have a MIDI channel between lochan and hichan, the region will play.

Examples:
lochan=1 hichan=5

If a note equal to or higher than lokey AND equal to or lower than hikey is played, the region will play.

lokey and hikey can be entered in either MIDI note numbers (0 to 127) or in MIDI note names (C-1 to G9)

The key opcode sets lokey, hikey and pitch_keycenter to the same note.

Examples:
lokey=60 // middle C
hikey=63 // middle D#
lokey=c4 // middle C
hikey=d#4 // middle D#
hikey=eb4 // middle Eb (D#)

locc=0, hicc=127

for all controllers

lobend
hibend

Defines the range of the last Pitch Bend message required for the region to play.

Examples:
lobend=0 hibend=4000

The region will play only if last Pitch Bend message received was in the 0~4000 range.

Defines the range of last Channel Aftertouch message required for the region to play.

Examples:
lochanaft=30 hichanaft=100

The region will play only if last Channel Aftertouch message received was in the 30~100 range.

Defines the range of last Polyphonic Aftertouch message required for the region to play.

The incoming note information in the Polyphonic Aftertouch message is not relevant.

Examples:
lopolyaft=30 hipolyaft=100

The region will play only if last Polyphonic Aftertouch message received was in the 30~100 range.

Random values. The player will generate a new random number on every note-on event, in the range 0~1.

The region will play if the random number is equal to or higher than lorand, and lower than hirand.

Examples:
lorand=0.2 hirand=0.4
lorand=0.4 hirand=1

Host tempo value. The region will play if the host tempo is equal to or higher than lobpm, and lower than hibpm.

Examples:
lobpm=0 hibpm=100
lobpm=100 hibpm=200.5

Sequence length. The player will keep an internal counter creating a consecutive note-on sequence for each region, starting at 1 and resetting at seq_length.

Examples:
seq_length=3

Sequence position. The region will play if the internal sequence counter is equal to seq_position.

Examples:
seq_length=4 seq_position=2

In above example, the region will play on the second note every four notes.

Defines the range of the keyboard to be used as trigger selectors for the sw_last opcode.

sw_lokey and sw_hikey can be entered in either MIDI note numbers (0 to 127) or in MIDI note names (C-1 to G9)

Examples:
sw_lokey=48 sw_hikey=53

Enables the region to play if the last key pressed in the range specified by sw_lokey and sw_hikey is equal to the sw_last value.

sw_last can be entered in either MIDI note numbers (0 to 127) or in MIDI note names (C-1 to G9)

Examples:
sw_last=49

Enables the region to play if the key equal to sw_down value is depressed.

Key has to be in the range specified by sw_lokey and sw_hikey.

sw_down can be entered in either MIDI note numbers (0 to 127) or in MIDI note names (C-1 to G9)

Examples:
sw_down=Cb3

Enables the region to play if the key equal to sw_up value is not depressed.

Key has to be in the range specified by sw_lokey and sw_hikey.

sw_up can be entered in either MIDI note numbers (0 to 127) or in MIDI note names (C-1 to G9)

Examples:
sw_up=49

Previous note value. The region will play if last note-on message was equal to sw_previous value.

sw_previous can be entered in either MIDI note numbers (0 to 127) or in MIDI note names (C-1 to G9)

Examples:
sw_previous=60

This opcode allows overriding the velocity for the region with the velocity of the previous note. Values can be:

current: Region uses the velocity of current note.

previous: Region uses the velocity of the previous note.

Examples:
sw_vel=previous

Sets the trigger which will be used for the sample to play. Values can be:

attack (default): Region will play on note-on.
release: Region will play on note-off. The velocity used to play the note-off sample is the velocity value of the corresponding (previous) note-on message.
first: Region will play on note-on, but if there's no other note going on (staccato, or first note in a legato phrase).
legato: Region will play on note-on, but only if there's a note going on (notes after first note in a legato phrase).

Examples:
trigger=release

Exclusive group number for this region.

Examples:
group=3
group=334

Region off group. When a new region with a group number equal to off_by plays, this region will be turned off.

Examples:
off_by=3
off_by=334

Region off mode. This opcode will determinate how a region is turned off by an off_by opcode. Values can be:

fast (default): The voice will be turned off immediately. Release settings will not have any effect.

normal: The region will be set into release stage. All envelope generators will enter in release stage, and region will expire when the amplifier envelope generator expired.

Examples:
off_mode=fast
off_mode=normal

Sample trigger on MIDI continuous control N. If a MIDI control message with a value between on_loccN and on_hiccN is received, the region will play.

Examples:
on_locc1=0 on_hicc1=0

Region will play when a MIDI CC1 (modulation wheel) message with zero value is received.

Region delay time, in seconds.
If a delay value is specified, the region playback will be postponed for the specified time.
If the region receives a note-off message before delay time, the region won't play.

All envelope generators delay stage will start counting after region delay time.

Examples:
delay=1
delay=0.2

Region random delay time, in seconds.
If the region receives a note-off message before delay time, the region won't play.

Examples:
delay_random=1
delay_random=0.2

Region delay time after MIDI continuous controller N messages are received, in seconds.
If the region receives a note-off message before delay time, the region won't play.

Examples:
delay_cc1=1
delay_cc2=.5

The offset used to play the sample, in sample units.
The player will reproduce samples starting with the very first sample in the file, unless offset is specified. It will start playing the file at the offset sample in this case.

Examples:
offset=3000
offset=32425

Random offset added to the region offset, in sample units.

Examples:
offset_random=300
offset_random=100

The offset used to play the sample according to last position of MIDI continuous controller N, in sample units.

This opcode is useful to specify an alternate sample start point based on MIDI controllers.

Examples:
offset_cc1=3000
offset_cc64=1388

The endpoint of the sample, in sample units.
The player will reproduce the whole sample if end is not specified.

If end value is -1, the sample will not play. Marking a region end with -1 can be used to use a silent region to turn off other regions by using the group and off_by opcodes.

Examples:
end=133000
end=4432425

The number of times the sample will be played. If this opcode is specified, the sample will restart as many times as defined. Envelope generators will not be retriggered on sample restart.
When this opcode is defined, loopmode is automatically set to one_shot.

Examples:
count=3
count=2

If loop_mode is not specified, each sample will play according to its predefined loop mode. That is, the player will play the sample looped using the first defined loop, if available. If no loops are defined, the wave will play unlooped.

The loop_mode opcode allows playing samples with loops defined in the unlooped mode. The possible values are:

no_loop: no looping will be performed. Sample will play straight from start to end, or until note off, whatever reaches first.
one_shot: sample will play from start to end, ignoring note off.
This mode is engaged automatically if the count opcode is defined.
loop_continuous: once the player reaches sample loop point, the loop will play until note expiration.
loop_sustain: the player will play the loop while the note is held, by keeping it depressed or by using the sustain pedal (CC64). The rest of the sample will play after note release.

Examples:
loop_mode=no_loop
loop_mode=loop_continuous

The loop start point, in samples.

If loop_start is not specified and the sample has a loop defined, the sample start point will be used.

If loop_start is specified, it will overwrite the loop start point defined in the sample.

This opcode will not have any effect if loopmode is set to no_loop.

Examples:
loop_start=4503
loop_start=12445

The loop end point, in samples. This opcode will not have any effect if loopmode is set to no_loop.

If loop_end is not specified and the sample have a loop defined, the sample loop end point will be used.

If loop_end is specified, it will overwrite the loop end point defined in the sample.

Examples:
loop_end=34503
loop_end=212445

Pitch EG decay time, in seconds.

Examples:
pitcheg_decay=1.5
pitcheg_decay=3

Velocity effect on pitch EG depth, in cents.

Examples:
pitcheg_vel2depth=100
pitcheg_vel2depth=-1200

Filter type. Avaliable types are:

lpf_1p: one-pole low pass filter (6dB/octave).
hpf_1p: one-pole high pass filter (6dB/octave).
lpf_2p: two-pole low pass filter (12dB/octave).
hpf_2p: two-pole high pass filter (12dB/octave).
bpf_2p: two-pole band pass filter (12dB/octave).
brf_2p: two-pole band rejection filter (12dB/octave).

Examples:
fil_type=lpf_2p
fil_type=hpf_1p

The filter cutoff frequency, in Hertz.

If the cutoff is not specified, the filter will be disabled, with the consequent CPU drop in the player.

Examples:
cutoff=343
cutoff=4333

Filter EG decay time, in seconds.

Examples:
fileg_decay=1.5
fileg_decay=3

Only operational for stereo samples, width defines the amount of channel mixing applied to play the sample.

A width value of 0 makes a stereo sample play as if it were mono (adding both channels and compensating for the resulting volume change). A value of 100 will make the stereo sample play as original.

Any value in between will mix left and right channels with a part of the other, resulting in a narrower stereo field image.

Negative width values will reverse left and right channels.

Examples:
width=100 // stereo
width=0 // play this stereo sample as mono
width=50 // mix 50% of one channel with the other

Only operational for stereo samples, position defines the position in the stereo field of a stereo signal, after channel mixing as defined in the width opcode.

A value of zero means centered, negative values move the panoramic to the left, positive to the right.

Examples:
// mix both channels and play the result at left
width=0 position=-100

// make the stereo image narrower and play it
// slightly right
width=50 position=30

amp_veltrack

Amplifier velocity tracking, represents how much the amplitude changes with incoming note velocity.

Volume changes with incoming velocity in a concave shape according to the following expression:

Amplitude(dB) = 20 log (127^2 / Velocity^2)

The amp_velcurve_N opcodes allow overriding the default velocity curve.

Examples:
amp_veltrack=0
amp_veltrack=100

User-defined amplifier velocity curve. This opcode range allows defining a specific curve for the amplifier velocity. The value of the opcode indicates the normalized amplitude (0 to 1) for the specified velocity.

The player will interpolate lineraly between specified opcodes for unspecified ones:

amp_velcurve_1=0.2 amp_velcurve_3=0.3
// amp_velcurve_2 is calculated to 0.25

If amp_velcurve_127 is not specified, the player will assign it the value of 1.

Examples:
// linear, compressed dynamic range
// amplitude changes from 0.5 to 1
amp_velcurve_1=0.5

Gain applied on MIDI control N, in decibels.

Examples:
gain_cc1=12

Fade in control.

xfin_lokey and xfin_hikey define the fade-in keyboard zone for the region.

The volume of the region will be zero for keys lower than or equal to xfin_lokey, and maximum (as defined by the volume opcode) for keys greater than or equal to xfin_hikey.

Examples:
xfin_lokey=c3 xfin_hikey=c4

Fade out control.

xfout_lokey and xfout_hikey define the fade-out keyboard zone for the region.

The volume of the region will be maximum (as defined by the volume opcode) for keys lower than or equal to xfout_lokey, and zero for keys greater than or equal to xfout_hikey.

Examples:
xfout_lokey=c5 xfout_hikey=c6

Keyboard crossfade curve for the region. Values can be:

gain: Linear gain crossfade. This setting is best when crossfading phase-aligned material. Linear gain crossfades keep constant amplitude during the crossfade, preventing clipping.

power: Equal-power RMS crossfade. This setting works better to mix very different material, as a constant power level is kept during the crossfade.

Fade in control.

xfin_lovel and xfin_hivel define the fade-in velocity range for the region.

The volume of the region will be zero for velocities lower than or equal to xfin_lovel, and maximum (as defined by the volume opcode) for velocities greater than or equal to xfin_hivel.

Examples:
xfin_lovel=0 xfin_hivel=127

Fade out control.

xfout_lokey and xfout_hikey define the fade-out velocity range for the region.

The volume of the region will be maximum (as defined by the volume opcode) for velocities lower than or equal to xfout_lovel, and zero for velocities greater than or equal to xfout_hivel.

Examples:
xfout_lovel=0 xfout_hivel=127

Velocity crossfade curve for the region. Values can be:

gain: Linear gain crossfade. This setting is best when crossfading phase-aligned material. Linear gain crossfades keep constant amplitude during the crossfade, preventing clipping.

power: Equal-power RMS crossfade. This setting works better to mix very different material, as a constant power level is kept during the crossfade.

Fade in control.

xfin_loccN and xfin_hiccN set the range of values in the MIDI continuous controller N which will perform a fade-in in the region.

The volume of the region will be zero for values of the MIDI continuous controller N lower than or equal to xfin_loccN, and maximum (as defined by the volume opcode) for values greater than or equal to xfin_hiccN.

Examples:
xfin_locc1=64 xfin_hicc1=127

Fade out control.

xfout_loccN and xfout_hiccN set the range of values in the MIDI continuous controller N which will perform a fade-out in the region.

The volume of the region will be maximum (as defined by the volume opcode) for values of the MIDI continuous controller N lower than or equal to xfout_loccN, and zero for values greater than or equal to xfout_hiccN.

Examples:
xfout_locc1=64 xfout_hicc1=127

MIDI controllers crossfade curve for the region. Values can be:

gain: Linear gain crossfade. This setting is best when crossfading phase-aligned material. Linear gain crossfades keep constant amplitude during the crossfade, preventing clipping.

power: Equal-power RMS crossfade. This setting works better to mix very different material, as a constant power level is kept during the crossfade.

Amplifier EG decay time, in seconds.

Examples:
ampeg_decay=1.5
ampeg_decay=3

Amplifier EG decay time added on MIDI control N, in seconds.

Examples:
ampeg_decaycc20=1.5
ampeg_decaycc1=3

Frequency change of the equalizer band when MIDI continuous control N messages are received, in Hertz.

Examples:
eq1_freqcc1=80

Frequency change of the equalizer band with MIDI velocity, in Hertz.

Examples:
eq1_vel2freq=1000

Gain change of the equalizer band with MIDI velocity, in decibels.

Examples:
eq1_vel2gain=12