Skip to main content

.esfx Reference

This page lists all functions that can be used in a .esfx file to generate sound effects.

AllPass​

AllPass(freq, q?)

An AllPass filter passes all frequencies, but delays some of them.

Parameters:

  • freq: Required. The frequency of the filter in Hz. Can be a single number, or an array of numbers to ramp the frequency over time.
  • q: Optional. The quality factor of the filter. Can be a single number, or an array of numbers to ramp the quality factor over time. See Q factors for more information.

BandPass​

BandPass(freq, q?)

A BandPass filter passes frequencies within a certain range, and dampens frequencies outside of that range.

Parameters:

  • freq: Required. The frequency of the filter in Hz. Can be a single number, or an array of numbers to ramp the frequency over time.
  • q: Optional. The quality factor of the filter. Can be a single number, or an array of numbers to ramp the quality factor over time. See Q factors for more information.

Examples:

A BandPass filter that passes frequencies around 220 Hz:

BandPass(freq=220)

BrownNoise​

BrownNoise(chaos?)

A BrownNoise function generates a random noise signal. Each sample is generated by modifying the previous sample by a small random value. Since the samples are related, this sounds more like wind or water than static.

Parameters:

  • chaos: Optional. The amount of randomness to add to the noise signal. Should be a number between 0 and 1. Defaults to 0.01. In most cases you should leave this at the default value.

BrownNoise is only generated once for each chaos value and then cached, and so it is good to use the same chaos value for many sound effects in a game.

Constant​

Constant(value)

A Constant function generates a constant signal. Since the signal is constant, it will not generate any sound on its own, and so this is usually used to modulate other signals.

Parameters:

  • value: Required. The value of the constant signal. This can be a single number, or an array of numbers to ramp the value over time.

Delay​

Delay(duration)

The Delay function delays the sound signal by a certain amount of time. This can be used to create echoes or reverberation.

Parameters:

  • duration: Required. The amount of time to delay the sound signal by, in seconds. Can be a single number, or an array of numbers to ramp the delay over time.

Envelope​

Envelope(attack, decay?, decayTo?, sustain?, release?)

An Envelope function applies an attack-decay-sustain-release (ADSR) envelope to the sound signal.

Parameters:

  • attack: Required. The time taken for the sound to ramp up to full volume. Defaults to 0.03s.
  • decay: Optional. After the sound has reached maximum volume, The time taken for the sound to ramp down to the decayTo volume. Defaults to 0s.
  • decayTo: Optional. The volume to ramp down to after the decay time. Defaults to 1.0 (full volume - no decay).
  • sustain: Optional. The time to hold the sound at the decayTo volume before releasing. If this is set to true instead of a Number, the sound will sustain at the decayTo volume indefinitely.
  • release: Optional. The time taken for the sound to ramp down to zero volume after the sustain time.

Normally, you would only specify either sustain or release but not both. The other parameter will be calculated automatically to fill the full duration of the sound effect. If neither sustain or release are specified, the sound will spend the rest of its duration releasing from the decayTo volume to zero volume.

Examples:

An Envelope that ramps up to full volume over 0.1 seconds, then spends the remaining 1.9 seconds releasing down to zero volume:

Play(duration=2s) {
    Oscillator(freq=500)
    Envelope(attack=0.1s)
}

An Envelope that ramps up to full volume over 0.01 seconds, then ramps down to 0.2 volume over 0.05 seconds, then spends the rest of its time releasing down to zero volume. The sharp but short attack and decay gives it more of a plucked sound and could represent the player hitting something:

Play(duration=2s) {
    Oscillator(freq=500)
	Envelope(attack=0.01s, decay=0.05s, decayTo=0.2)
}

An Envelope that ramps up to full volume over 0.1 seconds, then sustains at full volume indefinitely. This could be used for a energy beam that continues to fire as long as the button is held down:

Play(duration=2s) {
    Oscillator(freq=500)
    Envelope(attack=0.1s, sustain=true)
}

Gain​

Gain(volume)

A Gain function multiplies the volume of the sound signal by a constant factor.

Parameters:

  • volume: Required. The amount to multiply the volume by. Can be a single number, or an array of numbers to ramp the volume over time.

Examples:

A Gain that makes the sound signal half as loud:

Gain(volume=0.5)

Input​

Input(key)

The Input function allows you to route the output of a previous Output function to a later function.

Parameters:

  • key: Required. The key of the Output function that you want to route the output from.

HighPass​

HighPass(freq, q?)

A HighPass filter passes frequencies above a certain threshold, and dampens frequencies below that threshold.

Parameters:

  • freq: Required. The frequency of the filter in Hz. Can be a single number, or an array of numbers to ramp the frequency over time.
  • q: Optional. The quality factor of the filter. Can be a single number, or an array of numbers to ramp the quality factor over time. See Q factors for more information.

Examples:

A HighPass filter that passes frequencies above 220 Hz, while dampening frequencies below that:

HighPass(freq=220)

HighShelf​

HighShelf(freq, db, q?)

A HighShelf filter boosts or dampens frequencies above a certain threshold.

Parameters:

  • freq: Required. The frequency of the filter in Hz. Can be a single number, or an array of numbers to ramp the frequency over time.
  • db: Required. The amount of boost or dampening in dB. Can be a single number, or an array of numbers to ramp the amount over time.
  • q: Optional. The quality factor of the filter. Can be a single number, or an array of numbers to ramp the quality factor over time.

Examples:

A HighShelf filter that boosts frequencies above 220 Hz by 6 dB:

HighShelf(freq=220, db=6)

LowPass​

LowPass(freq, q?)

A LowPass filter passes frequencies below a certain threshold,

Parameters:

  • freq: Required. The frequency of the filter in Hz. Can be a single number, or an array of numbers to ramp the frequency over time.
  • q: Optional. The quality factor of the filter. Can be a single number, or an array of numbers to ramp the quality factor over time. See Q factors for more information.

Examples:

A LowPass filter that passes frequencies below 220 Hz, while dampening frequencies above that:

LowPass(freq=220)

LowShelf​

LowShelf(freq, db, q?)

A LowShelf filter boosts or dampens frequencies below a certain threshold.

Parameters:

  • freq: Required. The frequency of the filter in Hz. Can be a single number, or an array of numbers to ramp the frequency over time.
  • db: Required. The amount of boost or dampening in dB. Can be a single number, or an array of numbers to ramp the amount over time.
  • q: Optional. The quality factor of the filter. Can be a single number, or an array of numbers to ramp the quality factor over time. See Q factors for more information.

Examples:

A LowShelf filter that boosts frequencies below 220 Hz by 6 dB:

LowShelf(freq=220, db=6)

Notch​

Notch(freq, q?)

A Notch filter passes all frequencies except those within a certain range, which are dampened.

Parameters:

  • freq: Required. The frequency of the filter in Hz. Can be a single number, or an array of numbers to ramp the frequency over time.
  • q: Optional. The quality factor of the filter. Can be a single number, or an array of numbers to ramp the quality factor over time. See Q factors for more information.

Examples:

A Notch filter that passes all frequencies except those around 220 Hz:

Notch(freq=220)

Oscillator​

Oscillator(freq, wave = $sine, harmonics?, key?)

An Oscillator generates a periodic waveform at a given frequency. The waveform generates values between -1 and 1 which can be used to generate sound.

Parameters:

  • freq: Required. The frequency of the oscillator in Hz. You can specify a single number, or an array of numbers to ramp the frequency over time.
  • wave: Optional. The waveform to generate. One of $sine, $square, $sawtooth, or $triangle. Defaults to $sine.
  • harmonics: Optional. An array of harmonics to generate, which are waveforms that are multiples of the base frequency. You should normally include the base frequency of 1 as it does not get generated unless you specify it. Defaults to [1] (base frequency only).
  • key: Optional. This allows more complex chaining to be performed. Should be a symbol, e.g. $myOscillator. A Vibrato function that has its into parameter set to the same value as this key will modulate the frequency of this oscillator.

Examples:

An Oscillator that generates a sine wave at 500 Hz:

Oscillator(freq=500)

An Oscillator that generates a sawtooth wave that begins at 500 Hz and ramps up to 1000 Hz:

Oscillator(freq=[500,1000], wave=$sawtooth)

An Oscillator that generates a square wave at 500 Hz, but also the 2x and 3x harmonics of the base frequency (corresponding to 1000 Hz and 1500 Hz):

Oscillator(freq=500, wave=$square, harmonics=[2,3])

Output​

Output(into)

The Output function allows you to route the output of a previous function to a later Input function. This consumes the output of the function, so it will not be passed to the next function in the list.

Parameters:

  • into: Optional. The key of the Input function that you want to route the output to. You can specify either a single symbol or an array of symbols to route the output to multiple Input functions. If not specified, sends to the final output of the sound effect.

Examples:

Two Oscillator functions that generate sound signals at different frequencies, and then route the output to the final output of the sound effect:

Oscillator(freq=500)
Envelope(attack=0.1s)
Output

Oscillator(freq=1250)
Envelope(attack=0.5s)
Output

Two Oscillator functions that generate sound signals at different frequencies, and then route the output to a single Input function:

Oscillator(freq=500)
Output(into=$abc)

Oscillator(freq=1250)
Output(into=$abc)

Input(key=$abc)
Envelope(attack=0.1s)

A single Oscillator routed to two different outputs:

Oscillator(freq=500)
Output(into=[$abc, $def])

Input(key=$abc)
Delay(0.1s)
Output

Input(key=$def)
Output

Peaking​

Peaking(freq, db, q?)

A Peaking filter boosts or dampens frequencies within a certain range.

Parameters:

  • freq: Required. The frequency of the filter in Hz. Can be a single number, or an array of numbers to ramp the frequency over time.
  • db: Required. The amount of boost or dampening in dB. Can be a single number, or an array of numbers to ramp the amount over time.
  • q: Optional. The quality factor of the filter. Can be a single number, or an array of numbers to ramp the quality factor over time. See Q factors for more information.

Examples:

A Peaking filter that boosts frequencies around 220 Hz by 6 dB:

Peaking(freq=220, db=6)

Play​

Play(duration, delay?, cutoff?) {
    ...
}

The Play function can be used to play a sub-sound effect for a certain duration. This can be used to create a sub-tree of sound processing functions that are played for a certain amount of time.

Parameters:

  • duration: Required. The duration of the sub-sound effect.
  • delay: Optional. The amount of time to wait before starting the sub-sound effect. Defaults to 0s.
  • cutoff: Optional. If the sound is stopped early (for example, if using Sing) and the sound is not finished playing, the sound will be faded out over this duration. Note this parameter is only accepted at the top level of a sound effect. Attempting to give a subsound a cutoff will result in a compile error.

Examples:

Playing a sound with two beeps, the second one starting after a 0.5 second delay:

Play(duration=3s) {
  Play(duration=0.5s) {
      Oscillator(freq=500)
      Envelope(attack=0.1s)
  }
  Play(duration=1s, delay=0.5s) {
      Oscillator(freq=1000)
      Envelope(attack=0.2s)
  }
}

Tremolo​

Tremolo(volumeModulation) {
    ...
}

A Tremolo function modulates the volume of the sound signal. It is normally combined with an Oscillator to modulate the volume up and down over time.

Parameters:

  • volumeModulation: Required. The amount that the volume will be modified by. Can be a single number, or an array of numbers to ramp the volume modulation over time.

Tremolo expects an Oscillator inside of it that goes between the range of -1 and 1. It scales this input so the volume modulation so that the volume will go between 1 - volumeModulation and 1.

Examples:

A Tremolo that modulates the volume of a sound signal to be between 0.85 and 1, at a rate of 10 times per second:

Tremolo(volumeModulation=0.15) {
    Oscillator(wave=$sine, freq=10)
}

Vibrato​

Vibrato(freqModulation, into?) {
    ...
}

A Vibrato function modulates the frequency of the next Oscillator in the chain (unless the into parameter is set).

Parameters:

  • freqModulation: Required. The amount that the frequency will be modified by, in Hz. The output of the body of the Vibrato function will be multiplied by this value, then added to the frequency of the target Oscillator.
  • into: Optional. The key of the Oscillator that this Vibrato should modulate.

The body of the Vibrato must contain sound-generating functions to determine how to modulate the frequency.

Examples:

An Oscillator that generates a sine wave at 500 +/- 100 Hz. The oscillator will go up and down by 100 Hz at a rate of 20 times per second:

Vibrato(freqModulation=100) {
    Oscillator(freq=20)
}
Oscillator(freq=500)

An Oscillator that is modulated by WhiteNoise. This approach is often used to make explosion sounds:

Vibrato(freqModulation=2500) {
    WhiteNoise
}
Oscillator(wave=$triangle, freq=160)

WhiteNoise​

WhiteNoise

A WhiteNoise function generates a random noise signal. The noise signal is generated by uniformly sampling random values between -1 and 1. There is no pattern to the noise signal, so it sounds like static.

This function has no parameters.