Manual: SFZ Implementation

From OpenMPT Wiki
Jump to: navigation, search

It is possible to load SFZ instruments through the Instrument Editor. SFZ is a loosely standardized text-based instrument format with external sample files. OpenMPT tries to support as many SFZ opcodes as possible, including some that are specific to other vendors; its sampler only supports a fraction of the features of a fully fletched SFZ player, though.

The following SFZ opcodes are supported:

<control>[edit]

  • default_path: The default path to search sample files in.
  • note_offset: Global transposition in semitones
  • octave_offset: Global transposition in octaves

<global>, <master>, <group>, <region>[edit]

  • sample: The sample filename, relative to the SFZ file or default_path, if specified.
  • lokey: The lowest key this region is mapped to, either as a MIDI note index (0 to 127, 60 is middle-C) or scientific pitch designation (C, C#/Db, D, D#/Eb, E, F, F#/Gb, G, G#/Ab, A, A#/Bb, B) followed by an octave number (4 is the middle octave, so C4 is middle-C).
  • hikey: The highest key this region is mapped to, in the same format as lokey.
  • pitch_keycenter: The pitch at which the sample is played at its original sample rate, in the same format as lokey.
  • key: Sets lokey, hikey and pitch_key_center to the specified value, which is in the same format as lokey.
  • bend_up / bendup: Sets the MIDI pitch-bend depth in cents.
  • pitchlfo_fade: Sets the sample auto-vibrato sweep in seconds (approximately).
  • pitchlfo_depth: Sets the sample auto-vibrato depth.
  • pitchlfo_freq: sample auto-vibrato rate.
  • volume: Sets the sample global volume, ranging from -144dB to +6dB.
  • pan: Sets the sample pan position, ranging from -100 (left) to +100 (right).
  • transpose: Transposes the region up or down by the specified amount of semitones.
  • tune: Detunes the sample by the specified amount of cents, ranging from -100 to +100.
  • end: Trims the sample to the specified length.
  • offset: Starts playing the sample at the specified offset. OpenMPT completely removes any leading waveform data.
  • loop_start / loopstart: Start of the sample loop.
  • loop_end / loopend: End of the sample loop.
  • loop_mode / loopmode: One of the following sample loop modes:
    • loop_continuous: Normal sample loop.
    • one_shot: Treated like loop_continuous.
    • loop_sustain: Sustain loop.
    • no_loop: Disable loop completely.
  • loop_type / looptype: One of the following sample loop types:
    • forward: Normal forward loop.
    • backward: Reverse loop.
    • alternate: Ping-pong loop.
  • cutoff: Sets the filter cutoff frequency in Hz.
  • fil_random: Random cutoff variation in cents.
  • resonance: Sets the filter resonance in dB.
  • fil_type / filtype: One of the following filter types:
    • lpf_1p / lpf_2p / lpf_4p / lpf_6p: All treated as internal two-pole low-pass filter
    • hpf_1p / hpf_2p / hpf_4p / hpf_6p: All treated as internal two-pole high-pass filter
  • polyphony: The allowed maximum polyphony for this sample. Only a value of 1 is supported, in which case the Duplicate Note Check is set to Note Cut.
  • phase: Setting this to invert inverts the sample phase.
  • Envelopes: ampeg_… (volume envelope), fileg_… (filter envelope), pitcheg_…: (pitch envelope):
    • …eg_start: Start level of the envelope, ranging from -100 to +100.
    • …eg_delay: Delay, in seconds, until the attack phase of the envelope starts.
    • …eg_attack: Duration of the attack phase in seconds.
    • …eg_hold: Duration of the hold phase in seconds.
    • …eg_decay: Duration of the decay phase in seconds.
    • …eg_sustain: Sustain level of the envelope, ranging from -100 to +100.
    • …eg_release: Duration of the release phase in seconds.
    • …eg_depth: The depth of the envelope in cents. Only applies to pitch and filter envelopes.

Miscellaneous[edit]

  • #define macros are supported. Macro names must start with a $, e.g. #define $duration 0.5
  • Sample files can be of any type supported by OpenMPT’s sample editor (WAV, FLAC, Ogg, Opus, MediaFoundation codecs, etc.)
  • Loop points are read from sample files (as far as they are supported by OpenMPT) if a region’s loop_mode is set but no loop points are provided.