Class SfzMappedRegion
An SFZ region with its Tier-1 and Tier-2 opcodes interpreted into typed, engine-ready synthesis parameters: absolute key/velocity ranges (note names resolved, offsets applied), tuning in cents, volume in dB, pan normalised to ±1, the amplitude envelope in seconds, the filter, loop behaviour, sample offsets, group/trigger routing, note-on selection (keyswitches, round-robin, random and CC windows), crossfades, the per-region LFOs/EGs and EQ bands, effect sends and release decay.
This is the SFZ semantic layer, the counterpart to the SoundFont generator model. It does not load samples or touch the voice engine — projecting both formats onto one neutral model the engine plays is the next step.
public sealed class SfzMappedRegion- Inheritance
-
SfzMappedRegion
- Inherited Members
Properties
AmpLfo
Amplitude (tremolo) LFO (amplfo_freq/amplfo_depth/amplfo_delay; depth in dB).
public SfzLfo AmpLfo { get; }Property Value
AmpVelTrack
Velocity-to-amplitude tracking percentage (amp_veltrack, default 100).
public float AmpVelTrack { get; }Property Value
AmpegAttack
Amplitude-envelope attack in seconds (ampeg_attack).
public float AmpegAttack { get; }Property Value
AmpegDecay
Amplitude-envelope decay in seconds (ampeg_decay).
public float AmpegDecay { get; }Property Value
AmpegDelay
Amplitude-envelope delay in seconds (ampeg_delay).
public float AmpegDelay { get; }Property Value
AmpegHold
Amplitude-envelope hold in seconds (ampeg_hold).
public float AmpegHold { get; }Property Value
AmpegRelease
Amplitude-envelope release in seconds (ampeg_release).
public float AmpegRelease { get; }Property Value
AmpegSustain
Amplitude-envelope sustain level, 0…1 (ampeg_sustain%, default 1).
public float AmpegSustain { get; }Property Value
CcGates
CC value windows that must all hold for the region to sound (loccN/hiccN).
public IReadOnlyList<(int Controller, int Low, int High)> CcGates { get; }Property Value
- IReadOnlyList<(int Controller, int Low, int High)>
CutoffHz
Filter cutoff in Hz (cutoff), valid when HasCutoff.
public float CutoffHz { get; }Property Value
Effect1Percent
Send level to the first effect bus as a percentage (effect1, default 0).
public float Effect1Percent { get; }Property Value
Effect2Percent
Send level to the second effect bus as a percentage (effect2, default 0).
public float Effect2Percent { get; }Property Value
End
Sample end in frames (end, an inclusive index per the SFZ
spec), meaningful when HasEnd is true. An explicit −1 means
the region is disabled (not played) per the spec.
public int End { get; }Property Value
EqBands
The EQ bands the region specifies (eq1_/eq2_/eq3_*),
with unspecified members defaulted (centre frequency 50/500/5000 Hz by band,
bandwidth 1 octave, gain 0); null when no EQ opcode is present.
public IReadOnlyList<SfzEqBand> EqBands { get; }Property Value
FilterEg
Filter-cutoff modulation envelope (fileg_*; depth in cents).
public SfzModulationEnvelope FilterEg { get; }Property Value
FilterLfo
Filter-cutoff LFO (fillfo_freq/fillfo_depth/fillfo_delay; depth in cents).
public SfzLfo FilterLfo { get; }Property Value
FilterType
The filter family (fil_type, default low-pass).
public SfzFilterType FilterType { get; }Property Value
Group
Exclusive group (group, 0 = none).
public int Group { get; }Property Value
HasCutoff
Whether a filter cutoff was specified.
public bool HasCutoff { get; }Property Value
HasEnd
Whether an end opcode was specified.
public bool HasEnd { get; }Property Value
HasLoopEnd
Whether a loop_end/loopend opcode was specified.
public bool HasLoopEnd { get; }Property Value
HasLoopMode
Whether a loop_mode/loopmode opcode was specified.
public bool HasLoopMode { get; }Property Value
HasLoopStart
Whether a loop_start/loopstart opcode was specified.
public bool HasLoopStart { get; }Property Value
HiKey
Highest MIDI key (inclusive) the region responds to (default 127).
public int HiKey { get; }Property Value
HiVel
Highest velocity (inclusive) the region responds to (default 127).
public int HiVel { get; }Property Value
HighRandom
High end of the random window (hirand, default 1).
public float HighRandom { get; }Property Value
KeyFadeCurve
Key-crossfade curve (xf_keycurve, default power).
public SfzCrossfadeCurve KeyFadeCurve { get; }Property Value
KeyFadeInHigh
Key crossfade-in high.
public int KeyFadeInHigh { get; }Property Value
KeyFadeInLow
Key crossfade-in low/high (xfin_lokey/xfin_hikey), or −1.
public int KeyFadeInLow { get; }Property Value
KeyFadeOutHigh
Key crossfade-out high.
public int KeyFadeOutHigh { get; }Property Value
KeyFadeOutLow
Key crossfade-out low/high (xfout_lokey/xfout_hikey), or −1.
public int KeyFadeOutLow { get; }Property Value
KeyswitchDefault
The keyswitch active before any is pressed (sw_default), or −1.
public int KeyswitchDefault { get; }Property Value
KeyswitchHigh
Highest keyswitch key (sw_hikey), or −1.
public int KeyswitchHigh { get; }Property Value
KeyswitchLast
The keyswitch that must have been pressed last (sw_last), or −1.
public int KeyswitchLast { get; }Property Value
KeyswitchLow
Lowest keyswitch key (sw_lokey), or −1 if no keyswitch range.
public int KeyswitchLow { get; }Property Value
LoKey
Lowest MIDI key (inclusive) the region responds to (default 0).
public int LoKey { get; }Property Value
LoVel
Lowest velocity (inclusive) the region responds to (default 0).
public int LoVel { get; }Property Value
LoopEnd
Loop end in frames (loop_end, an inclusive index per the
SFZ spec), meaningful when HasLoopEnd is true; overrides any loop
end embedded in the sample file.
public int LoopEnd { get; }Property Value
LoopMode
Loop behaviour (loop_mode). Only meaningful when
HasLoopMode is true: per the SFZ spec an absent opcode
defaults to loop_continuous when the sample file defines a loop
(e.g. a WAV smpl chunk) and no_loop otherwise, which only
the sample loader can decide.
public SfzLoopMode LoopMode { get; }Property Value
LoopStart
Loop start in frames (loop_start), meaningful when
HasLoopStart is true; overrides any loop start embedded in the sample file.
public int LoopStart { get; }Property Value
LowRandom
Low end of the random window (lorand, default 0).
public float LowRandom { get; }Property Value
OffBy
The group whose notes this region silences (off_by, 0 = none).
public int OffBy { get; }Property Value
OffMode
How this region is silenced by its group (off_mode, default fast).
public SfzOffMode OffMode { get; }Property Value
Offset
Sample start offset in frames (offset, default 0).
public int Offset { get; }Property Value
OnCcTriggers
CC value windows that trigger the region when the controller
rises into them (on_loccN/on_hiccN); null when the region is
not CC-triggered.
public IReadOnlyList<(int Controller, int Low, int High)> OnCcTriggers { get; }Property Value
- IReadOnlyList<(int Controller, int Low, int High)>
Pan
Pan normalised to −1 (left) … +1 (right) from SFZ's −100…100.
public float Pan { get; }Property Value
PitchEg
Pitch modulation envelope (pitcheg_*; depth in cents).
public SfzModulationEnvelope PitchEg { get; }Property Value
PitchKeycenter
The key that plays the sample at its recorded pitch (default 60).
public int PitchKeycenter { get; }Property Value
PitchKeytrack
Cents per key of pitch tracking across the keyboard (default 100).
public int PitchKeytrack { get; }Property Value
PitchLfo
Pitch (vibrato) LFO (pitchlfo_freq/pitchlfo_depth/pitchlfo_delay; depth in cents).
public SfzLfo PitchLfo { get; }Property Value
Polyphony
Maximum simultaneous voices (polyphony, −1 = unlimited).
public int Polyphony { get; }Property Value
Region
The underlying parsed region (raw opcodes, resolved sample path).
public SfzRegion Region { get; }Property Value
ReleaseDecayDbPerSecond
Release-trigger decay in dB per second the note was held (rt_decay, default 0).
public float ReleaseDecayDbPerSecond { get; }Property Value
ResonanceDb
Filter resonance in dB (resonance, default 0).
public float ResonanceDb { get; }Property Value
Sample
The region's sample path (from Sample).
public string Sample { get; }Property Value
SequenceLength
Round-robin length (seq_length, default 1 = none).
public int SequenceLength { get; }Property Value
SequencePosition
This region's 1-based round-robin slot (seq_position, default 1).
public int SequencePosition { get; }Property Value
Trigger
When the region plays (trigger, default attack).
public SfzTrigger Trigger { get; }Property Value
TuneCents
Fixed detune in cents (tune/pitch plus transpose×100).
public double TuneCents { get; }Property Value
VelocityCurvePoints
The region's velocity-curve points (amp_velcurve_N): the
normalised amplitude (0…1) at velocity N (1…127), sorted by velocity;
null when the region defines none. Points whose N is outside 1…127 or
whose value does not parse are ignored; levels are clamped to 0…1.
Resolve the full per-velocity curve with BuildVelocityCurve().
public IReadOnlyList<(int Velocity, float Level)> VelocityCurvePoints { get; }Property Value
VelocityFadeCurve
Velocity-crossfade curve (xf_velcurve, default power).
public SfzCrossfadeCurve VelocityFadeCurve { get; }Property Value
VelocityFadeInHigh
Velocity crossfade-in high.
public int VelocityFadeInHigh { get; }Property Value
VelocityFadeInLow
Velocity crossfade-in low/high (xfin_lovel/xfin_hivel), or −1.
public int VelocityFadeInLow { get; }Property Value
VelocityFadeOutHigh
Velocity crossfade-out high.
public int VelocityFadeOutHigh { get; }Property Value
VelocityFadeOutLow
Velocity crossfade-out low/high (xfout_lovel/xfout_hivel), or −1.
public int VelocityFadeOutLow { get; }Property Value
VolumeDb
Region gain in decibels (volume, default 0).
public float VolumeDb { get; }Property Value
Methods
BuildVelocityCurve()
Resolves VelocityCurvePoints into a full 128-entry curve
indexed by MIDI velocity: defined points give their level, undefined
velocities are linearly interpolated between the nearest defined
neighbours — from (0, 0) below the lowest defined point and to (127, 1)
above the highest, unless velocity 127 is itself defined. Returns null
when the region defines no points; the resolved curve replaces the
default velocity-squared term inside the amp_veltrack law.
public float[] BuildVelocityCurve()Returns
- float[]
Map(SfzRegion, int, int)
Interprets a parsed SfzRegion's opcodes. The
noteOffset and octaveOffset (from
the instrument's <control> section) transpose incoming MIDI
notes; here that is realised by shifting the explicitly specified
key-valued opcodes the opposite way.
public static SfzMappedRegion Map(SfzRegion region, int noteOffset = 0, int octaveOffset = 0)Parameters
Returns
Remarks
key versus explicit lokey/hikey/pitch_keycenter:
strict SFZ semantics apply opcodes in document order (the later one
wins), but the merged opcode set this maps from no longer carries that
order. This mapping deliberately deviates with a pragmatic rule:
key supplies defaults for whichever of the three are not
explicitly present, and an explicit opcode always wins regardless of
where it was written — so <group> key=36 <region>
lokey=35 hikey=37 keeps the region's range, with the keycenter
defaulting from key.
Matches(int, int)
Whether this region should sound for the given key and velocity.
public bool Matches(int key, int velocity)