Audio effects are used to modify the final output of the audio mixer. They come in different flavors such as reverb, echo, chorus etc... Once placed on an effect slot they affect the way the mixer is modulating the final results. Depending on their slot order audio effect can prioritized; in addition each effect can have their own independent gain that will dictate how much they affect the output. Audio effects are a great way to add an extra level of realism to your world as they are simulating real environmental audio phenomenon.

By default the Sound system allow you to place up to four concurrent effect that will modify the mixer final result. The audio effects placed on theses slot can also be tuned dynamically at runtime. Learn more about the audio effect API by reading the help sections below.

Static Variables

Name	Description
`asset`	The Asset structure the current AudioEffect is associated to.
Declaration Asset *asset
`slot_index`	The active slot index the AudioEffect is attached to.
Declaration int slot_index
`data`	Data structure to access the properties available for the active AudioEffect EffectType.
Declaration EffectData data

Functions

Name	Description
`SetType`	Changes the type of the current AudioEffect.
Declaration void SetType( const EffectType type ) Parameters `type`: A valid EffectType constant value.
`SetReverbPreset`	Use a ReverbPreset to setup the properties of a `kEAXReverb` or `kReverb` AudioEffect.
Declaration bool SetReverbPreset( const ReverbPreset preset ) Parameters `preset`: A valid ReverbPreset value. Return Value `true` if the active AudioEffect is of the type `kEAXReverb` or `kReverb`; else return `false`.

EffectType

The base types used when creating a new AudioEffect.

kEAXReverb: EAX Reverb parameter set is a superset of the standard environmental reverb effect.
kReverb: Standard environmental reverb effect.
kAutowah: Emulates the sound of a wah-wah pedal used with an electric guitar, or a mute on a brass instrument.
kChorus: Essentially replays the input audio accompanied by another slightly delayed version of the signal, creating a doubling effect.
kCompressor: Performs the same task as a studio compressor; evening out the audio dynamic range of an input sound.
kDistortion: Simulates turning up the gain stage on a guitar amplifier or adding a distortion pedal to an instrument's output.
kEcho: Generates discrete, delayed instances of the input signal.
kEqualizer: Provies tonal control over four different adjustable frequency ranges.
kFlanger: Creates a tearing or whooshing sound (like a jet flying overhead).
kModulator: Multiplies an input signal by a carrier signal in the time domain, resulting in tremolo or inharmonic effects.
kLowFrequency: Is a single-sideband modulator, which translates all the component frequencies of the input signal by an equal amount.
kDialogue: Consists of a pair of 4-band formant filters, used to impose vocal tract effects upon the input signal.

Example

Lua
-- You can access a specific type using the AudioEffect base like this:
print( "The value of kReverb is " .. AudioEffect.EffectType.kReverb )

ReverbPreset

Available preset to use in conjunction with the reverb audio effect. Each preset have predefined reverb values that will be affected to the parameters of the AudioEffect when it is assigned.

`kPreset`	`kPadCell`	`kRoom`	`kBathroom`	`kLivingRoom`	`kStoneRoom`
`kAuditorium`	`kConcertHall`	`kCave`	`kArena`	`kHangar`	`kCarpetedHallway`
`kHallway`	`kStoneCorridor`	`kAlley`	`kForest`	`kCity`	`kMountains`
`kQuarry`	`kPlain`	`kParkingLot`	`kSewerPipe`	`kUnderwater`	`kDrugged`
`kDizzy`	`kPsychotic`	`kCastleSmallRoom`	`kCastleShortPassage`	`kCastleMediumRoom`	`kCastleLargeRoom`
`kCastleLongPassage`	`kCastleHall`	`kCastleCupboard`	`kCastleCourtyard`	`kCastleAlcove`	`kFactorySmallRoom`
`kFactoryShortPassage`	`kFactoryMediumRoom`	`kFactoryLargeRoom`	`kFactoryLongPassage`	`kFactoryHall`	`kFactorySmallRoom`
`kFactoryCupboard`	`kFactoryCourtyard`	`kFactoryAlcove`	`kIceSmallRoom`	`kIceShortPassage`	`kIceMediumRoom`
`kIceLargeRoom`	`kIceLongPassage`	`kIceHall`	`kIceCupboard`	`kIceCourtyard`	`kIceAlcove`
`kStationSmallRoom`	`kStationShortPassage`	`kStationMediumRoom`	`kStationLargeRoom`	`kStationLongPassage`	`kStationHall`
`kStationCupboard`	`kStationAlcove`	`kWoodenSmallRoom`	`kWoodenShortPassage`	`kWoodenMediumRoom`	`kWoodenLargeRoom`
`kWoodenLongPassage`	`kWoodenHall`	`kWoodenCupboard`	`kWoodenCourtyard`	`kWoodenAlcove`	`kEmptyStadium`
`kSquashCourt`	`kSmallSwimmingPool`	`kLargeSwimmingPool`	`kGymnasium`	`kFullStadium`	`kStadiumTannoy`
`kWorkshop`	`kSchoolRoom`	`kPracticeRoom`	`kOuthouse`	`kCaravan`	`kDomeTomb`
`kPipeSmall`	`kDomeStPaul`	`kPipeLongThin`	`kPipeLarge`	`kResonant`	`kBackyard`
`kRollingPlains`	`kDeepCanyon`	`kCreek`	`kValley`	`kHeaven`	`kHell`
`kMemory`	`kCommentator`	`kPitGarage`	`kIncarRacer`	`kIncarSports`	`kIncarLuxury`
`kFullGranStand`	`kEmptyGranStand`	`kUndergroundPassage`	`kStreet`	`kSubway`	`kMuseum`
`kLibrary`	`kUnderpass`	`kAbandoned`	`kDustyRoom`	`kChapel`	`kSmallWaterRoom`

Example

Lua
-- Reverb presets can be accessed as follow:
print( "The value of kWoodenSmallRoom is " .. AudioEffect.ReverbPreset.kWoodenSmallRoom )

EAXReverbEffect

Extended environmental reverb effect.

Variables

Name	Description
`density`	Controls the coloration of the late reverb.
Declaration float density Range 0.0 to 1.0 \remark Lowering the value adds more coloration to the late reverb. </td>
`diffusion`	Controls the echo density in the reverberation decay.
Declaration float diffusion Range 0.0 to 1.0
`gain`	Master volume control for the reflected sound (both early reflections and reverberation) that the reverb effect adds to all sound sources.
Declaration float gain Range 0.0 to 1.0
`gain_hf`	Tweaks reflected sound by attenuating it at high frequencies.
Declaration float gain_hf Range 0.0 to 1.0
`gain_lf`	Tweaks reflected sound by attenuating it at low frequencies.
Declaration float gain_lf Range 0.0 to 1.0
`decay_time`	Sets the reverberation decay time.
Declaration float decay_time Range 0.1 to 20.0 \note Ranges from 0.1 is a typical a small room with very dead surfaces to 20.0, a large room with very live surfaces. </td>
`decay_hf_ratio`	Adjusts the high frequencies spectral quality of the `decay_time` parameter.
Declaration float decay_hf_ratio Range 0.1 to 2.0
`decay_lf_ratio`	Adjusts the low frequencies spectral quality of the `decay_time` parameter.
Declaration float decay_lf_ratio Range 0.1 to 2.0
`reflections_gain`	Controls the overall amount of initial reflections relative to the `gain` property.
Declaration float reflections_gain Range 0.0 to 3.16
`reflections_delay`	The amount of delay between the arrival time of the direct path from the source to the first reflection from the source.
Declaration float reflections_delay Range 0.0 to 0.3
`reflections_pan`	A 3d vector that controls the spatial distribution of the cluster of early reflections.
Declaration vec3 reflections_pan
`late_reverb_gain`	Controls the overall amount of later reverberation relative to the Gain property.
Declaration float late_reverb_gain Range 0.0 to 10.0
`late_reverb_delay`	Defines the begin time of the late reverberation relative to the time of the initial reflection (the first of the early reflections).
Declaration float late_reverb_delay Range 0.0 to 0.1
`late_reverb_pan`	3d vector that controls the spatial distribution of the late reverb.
Declaration vec3 late_reverb_pan
`echo_time`	Controls the rate at which the cyclic echo repeats itself along the reverberation decay.
Declaration float echo_time Range 0.075 to 0.25
`echo_depth`	Control how long the echo effect will persist along the reverberation decay.
Declaration float echo_depth Range 0.0 to 1.0
`modulation_time`	Controls the speed of the vibrato (rate of periodic changes in pitch).
Declaration float modulation_time Range 0.04 to 4.0
`modulation_depth`	Controls the amount of pitch change.
Declaration float modulation_depth Range 0.0 to 1.0
`hf_reference`	Frequency at which the high-frequency effects.
Declaration float hf_reference Range 1000.0 to 20000.0
`lf_reference`	Frequency at which the low-frequency effects.
Declaration float lf_reference Range 20.0 to 1000.0
`room_rolloff_factor`	Property is one of two methods available (either 0.0 or 1.0) to attenuate the reflected sound according to source-listener distance.
Declaration float room_rolloff_factor Range 0.0 to 10.0
`air_absorb_gain_hf`	Controls the distance-dependent attenuation at high frequencies caused by the propagation medium.
Declaration float air_absorb_gain_hf Range 0.892 to 10.0
`decay_hf_limit`	When this flag is set, the high-frequency decay time automatically stays below a limit value that's derived from the setting of the property `air_absorb_gain_hf`.
Declaration bool decay_hf_limit

ReverbEffect

Environmental reverb effect.

Variables

Name	Description
`density`	Controls the coloration of the late reverb. Lowering the value adds more coloration to the late reverb.
Declaration float density Range 0.0 to 1.0
`diffusion`	Controls the echo density in the reverberation decay.
Declaration float diffusion Range 0.0 to 1.0
`gain`	Master volume control for the reflected sound (both early reflections and reverberation) that the reverb effect adds to all sound sources.
Declaration float gain Range 0.0 to 1.0
`gain_hf`	Tweaks reflected sound by attenuating it at high frequencies.
Declaration float gain_hf Range 0.0 to 1.0
`decay_time`	Sets the reverberation decay time.
Declaration float decay_time Range 0.1 to 20.0
`decay_hf_ratio`	Adjusts the high frequencies spectral quality of the `decay_time` parameter.
Declaration float decay_hf_ratio Range 0.1 to 2.0
`reflections_gain`	Controls the overall amount of initial reflections relative to the `gain` property.
Declaration float reflections_gain Range 0.0 to 3.16
`reflections_delay`	The amount of delay between the arrival time of the direct path from the source to the first reflection from the source.
Declaration float reflections_delay Range 0.0 to 0.3
`late_reverb_gain`	Controls the overall amount of later reverberation relative to the Gain property.
Declaration float late_reverb_gain Range 0.0 to 10.0
`late_reverb_delay`	Defines the begin time of the late reverberation relative to the time of the initial reflection (the first of the early reflections).
Declaration float late_reverb_delay Range 0.0 to 0.1
`room_rolloff_factor`	Property is one of two methods available (either 0.0 or 1.0) to attenuate the reflected sound according to source-listener distance.
Declaration float room_rolloff_factor Range 0.0 to 10.0
`air_absorb_gain_hf`	Controls the distance-dependent attenuation at high frequencies caused by the propagation medium.
Declaration float air_absorb_gain_hf Range 0.892 to 1.0
`decay_hf_limit`	When this flag is set, the high-frequency decay time automatically stays below a limit value that's derived from the setting of the property `air_absorb_gain_hf`.
Declaration bool decay_hf_limit

AutowahEffect

Emulates the sound of a wah-wah pedal generally used with an electric guitar.

Variables

Name	Description
`attack_time`	Controls the time the filtering effect takes to sweep from minimum to maximum center frequency when it is triggered by input signal.
Declaration float attack_time Range 0.0001 to 1.0
`release_time`	Controls the time the filtering effect takes to sweep from maximum back to base center frequency, when the input signal ends.
Declaration float release_time Range 0.0001 to 1.0
`peak_gain`	controls the input signal level at which the band-pass filter will be fully opened.
Declaration float peak_gain Range 0.00003 to 31621.0
`resonance`	Controls the resonant peak, sometimes known as emphasis, of the auto-wah band-pass filter.
Declaration float resonance Range 2.0 to 1000.0

ChorusEffect

Replays the input audio accompanied by another slightly delayed version of the signal.

Variables

Name	Description
`waveform`	Sets the waveform shape of the LFO that controls the delay time of the delayed signals.
Declaration int waveform Range 0 or 1 \remark Setting this value to `0` will use a `sin` shape and `1` a `triangle` (peak). </td>
`phase`	Controls the phase difference between the left and right LFO.
Declaration int phase Range -180 to 180
`rate`	Sets the modulation rate of the LFO that controls the delay time of the delayed signals.
Declaration float rate Range 0.0 to 10.0
`depth`	Controls the amount by which the delay time is modulated by the LFO.
Declaration float depth Range 0.0 to 1.0
`feedback`	Controls the amount of processed signal that is fed back to the input of the chorus effect.
Declaration float feedback Range -1.0 to 1.0
`delay`	Controls the average amount of time the sample is delayed before it is played back, and with feedback, the amount of time between iterations of the sample.
Declaration float delay Range 0.0 to 0.016

CompressorEffect

Evening out the audio dynamic range of an input sound.

Variables

Name Description

enable Toggle the compressor on/off; no adjustment is possible.

Declaration

int enable

DistortionEffect

Simulates turning up the gain stage on a guitar amplifier.

Variables

Name	Description
`edge`	The shape of the distortion; the higher the `dirtier` the lower `fuzzier`.
Declaration float edge Range 0.0 to 1.0
`gain`	Allows you to attenuate the distorted sound.
Declaration float gain Range 0.01 to 1.0
`lowpass_cutoff`	Limit the amount of high frequency signal feeding into the distortion effect.
Declaration float lowpass_cutoff Range 80.0 to 24000.0
`eq_center`	Controls the frequency at which the post-distortion attenuation.
Declaration float eq_center Range 80.0 to 24000.0
`eq_bandwidth`	Controls the bandwidth of the post-distortion attenuation.
Declaration float eq_bandwidth Range 80.0 to 24000.0

EchoEffect

Generates discrete, delayed instances of the input signal.

Variables

Name	Description
`delay`	Controls the delay between the original sound and the first echo instance.
Declaration float delay Range 0.0 to 0.207
`lr_delay`	Controls the delay between the first "tap" and the second "tap".
Declaration float lr_delay Range 0.0 to 0.404
`damping`	Controls the amount of high frequency damping applied to each echo.
Declaration float damping Range 0.0 to 0.99
`feedback`	Controls the amount of feedback the output signal fed back into the input.
Declaration float feedback Range 0.0 to 1.0
`spread`	Controls how hard panned the individual echoes are.
Declaration float spread Range -1.0 to 1.0

EqualizerEffect

Provides tonal control over four different adjustable frequency ranges.

Variables

Name	Description
`low_cutoff`	Low frequency below which signal will be cut off.
Declaration float low_cutoff Range 50.0 to 800.0
`low_gain`	Controls amount of cut / boost on the low frequency range.
Declaration float low_gain Range 0.126 to 7.943
`mid1_gain`	Allows you to cut or boost signal on the mid1 range.
Declaration float mid1_gain Range 0.126 to 7.943
`mid1_center`	Sets the center frequency for the mid1 range.
Declaration float mid1_center Range 200.0 to 3000.0
`mid1_width`	Controls the width of the mid1 range.
Declaration float mid1_width Range 0.01 to 1.0
`mid2_gain`	Allows you to cut or boost signal on the mid2 range.
Declaration float mid2_gain Range 0.126 to 7.943
`mid2_center`	Sets the center frequency for the mid2 range.
Declaration float mid2_center Range 1000.0 to 8000.0
`mid2_width`	Controls the width of the mid2 range.
Declaration float mid2_width Range 0.01 to 1.0
`high_cutoff`	High frequency above which signal will be cut off.
Declaration float high_cutoff Range 4000.0 to 16000.0
`high_gain`	Allows you to cut or boost the signal at high frequencies.
Declaration float high_gain Range 0.126 to 7.943

FlangerEffect

Creates a "tearing" or "whooshing" sound.

Variables

Name	Description
`waveform`	Low frequency below which signal will be cut off.
Declaration int waveform Range 0 or 1 \remark Setting this value to `0` will use a `sin` shape and `1` a `triangle` (peak). </td>
`phase`	Changes the phase difference between the left and right LFO.
Declaration int phase Range -180 to 180 \note At zero degrees the two LFOs are synchronized. </td>
`rate`	Number of times per second the LFO controlling the amount of delay repeats.
Declaration float rate Range 0.0 to 10.0 \remark Higher values increase the pitch modulation. </td>
`depth`	Ratio by which the delay time is modulated by the LFO.
Declaration float depth Range 0.0 to 1.0 \remark Use this parameter to increase the pitch modulation. </td>
`feedback`	Amount of the output signal level fed back into the effect's input.
Declaration float feedback Range -1.0 to 1.0 \remark Use this parameter to create an "intense metallic" effect. At full magnitude, the identical sample will repeat endlessly. At less than full magnitude, the sample will repeat and fade out over time. </td>
`delay`	The amount of time between iterations of the sample.
Declaration float delay Range 0.0 to 0.004

ModulatorEffect

Multiplies an input signal by a carrier signal in the time domain, resulting in tremolo or inharmonic effects.

Variables

Name	Description
`frequency`	Low frequency below which signal will be cut off.
Declaration float frequency Range 0.0 to 8000.0
`high_pass_cutoff`	Controls the cutoff frequency at which the input signal is high-pass filtered before being ring modulated.
Declaration float high_pass_cutoff Range 0.0 to 24000.0
`waveform`	Controls which waveform is used as the carrier signal.
Declaration int waveform Range 0 to 2 \remark Setting this value to `0` will result in a `sin` form, `1` a `saw` and `2` a `square`. </td>

DedicatedEffect

Used by either kLowFrequency and kDialogue to control the gain level of the effect.

Variables

Name Description

gain Control the master gain level of the effect.

Declaration

float gain

Range

0.0 to 1.0

 </td>

EffectData

Container used to store the necessary data based on the EffectType the AudioEffect have been created with.

Static Variables

Name	Description
`type`	The current EffectType type the active AudioEffect.
Declaration EffectType type
`eaxreverb`	Gain access to the EAXReverbEffect properties.
Declaration EAXReverbEffect *eaxreverb `nil` if the AudioEffect `type` is not `kEAXReverb`.
`reverb`	Gain access to the ReverbEffect properties.
Declaration ReverbEffect *reverb `nil` if the AudioEffect `type` is not `kReverb`.
`autowah`	Gain access to the AutowahEffect properties.
Declaration AutowahEffect *autowah `nil` if the AudioEffect `type` is not `kAutowah`.
`chorus`	Gain access to the ChorusEffect properties.
Declaration ChorusEffect *chorus `nil` if the AudioEffect `type` is not `kChorus`.
`compressor`	Gain access to the CompressorEffect properties.
Declaration CompressorEffect *compressor `nil` if the AudioEffect `type` is not `kCompressor`.
`distortion`	Gain access to the DistortionEffect properties.
Declaration DistortionEffect *distortion `nil` if the AudioEffect `type` is not `kDistortion`.
`echo`	Gain access to the EchoEffect properties.
Declaration EchoEffect *echo `nil` if the AudioEffect `type` is not `kEcho`.
`equalizer`	Gain access to the EqualizerEffect properties.
Declaration EqualizerEffect *equalizer `nil` if the AudioEffect `type` is not `kEqualizer`.
`flanger`	Gain access to the EchoEffect properties.
Declaration FlangerEffect *flanger `nil` if the AudioEffect `type` is not `kFlanger`.
`modulator`	Gain access to the ModulatorEffect properties.
Declaration ModulatorEffect *modulator `nil` if the AudioEffect `type` is not `kModulator`.
`low_frequency`	Gain access to the DedicatedEffect properties.
Declaration DedicatedEffect *low_frequency `nil` if the AudioEffect `type` is not `kLowFrequency`.
`dialogue`	Gain access to the DedicatedEffect properties.
Declaration DedicatedEffect *dialogue `nil` if the AudioEffect `type` is not `kDialogue`.