Effect Constants Name Candidates

The upcoming löve version (0.11.0) will include substantial amount of audio-related advancements. This page serves two functions:

• To decide on a neat and consistent terminology used for the to-be-added Filters and Effects (the other stuff has already been finalized),
• To have a compendium for people using the nightlies so they won't need to browse the source to find out what works how (and so that the wiki article creation will happen a bit more smoothly)

Alternative suggested names go into parentheses; Banter to be added to the respective sub-headers.

Refer to OpenAL EFX handbook for underlying system details: http://kcat.strangesoft.net/misc-downloads/Effects%20Extension%20Guide.pdf

Filter and Effect "Objects"

Effects and Filters are generic Lua tables with named parameters, e.g.:

{ type = "reverb", volume = 1.0, density = 0.3 } -- This is a reverb Effect.

More precisely, they are descriptions of Effects and Filters. When appropriate function is called, Effect and Filter parameters are modified using data from that table.

Passing nil as parameter value, as well as omitting the parameter, will apply default value. The "type" and "volume" parameters are mandatory for all Effects and Filters, all other parameters are optional. Values will be restricted to valid range internally.

Filters

Filters are basic low-pass, high-pass and band-pass (a combination of both high- and low-pass) frequency filters. They can be applied to each sound Source individually, but only one Filter per Source at a time.

Synopsis

-- Apply Filter to Source.
success = Source:setFilter(Filter)
--               applyFilter(Filter)

-- Get the currently bound Filter of a Source.
Filter = Source:getFilter()

Filter Arguments

FilterType type

The type of the Filter. See FilterType below.

number volume

Gain of the whole spectrum. Range: [0,1]

number lowgain

Gain on the low-end. Range: [0,1]

number highgain

Gain on the high-end. Range: [0,1]

Note: Low-pass Filters don't have a lowgain parameter, High-pass Filters don't have a highgain parameter.

FilterType

string lowpass

Used to remove high frequency content from a signal.

string highpass

Used to remove low frequency content from a signal.

string bandpass

Used to remove high and low frequency content from a signal.

Banter

I'd go with setFilter so it pairs up with getFilter, plain and simple; don't care about the implementation. Zorg (talk) 19:59, 1 February 2017 (CET)

Effects

Effects are advanced modules modifying the audio signals that can be used to recreate realistic acoustic properties of specific areas, as well as creating cool effects. This sound system is built on top of OpenAL, so it's only possible to set 4 Effects at a time.

Each Source can feed its output to any of these 4 Effects, and it can also feed to multiple Effects simultaneously. Each feed line can have a Filter attached to it, which will filter the sound between the Source and Effect.

Effects work continuously, even when no sound is fed, e.g. the reverb Effect can still output a decaying sound long after all input is cut.

Synopsis

-- Apply Effect to scene.
success = love.audio.setSceneEffect(slot, Effect)
--                   setEffect(slot, Effect)

-- Get current scene Effect.
Effect = love.audio.getSceneEffect()
--                  getEffect()

-- Use scene Effect with Source.
success = Source:setSceneEffect(line, slot, Filter)
--               useSceneEffect(line, slot, Filter)
--               setEffect(line, slot, Filter)

-- Get Source's currently used scene Effect.
slot, Filter = Source:getSceneEffect(line)
--                    getEffect(line)

Effect Arguments applicable for all types

EffectType type

Type of the Effect. See EffectType below.

number volume

Master volume of the Effect. Range: [0,1]

Note: Effect-specific parameters detailed below.

EffectType

string echo (delay)

Decaying feedback based effect on the order of seconds.

string reverb

Decaying feedback based effect on the order of milliseconds. Used to simulate location properities.

string chorus

Overlays the signal on top of itself with pitch and time variation. Used to make sounds sound "fuller".

string flanger

Overlays the signal on top of itself with phase variation.

string distortion

Clips the sound artificially to make it sound distorted.

string ringmodulator (ringmod)

Varies the volume over time; with a fast enough speed, it'll sound kinda like a bell.

string compressor

Increases loudness over the whole spectrum.

string equalizer

A 4-band equalizer used to modify the signal, boost or cut specific frequency ranges.

EffectWaveform

string sine

A sine wave.

string triangle

A triangle wave.

string sawtooth

A ramp / sawtooth wave.

string square

A symmetric pulse / square wave.

Banter

I'd again vote for keeping function names simple; with a disclaimer on the wiki page that modifying an effect's parameter won't apply it here until you call this again... at least that's how i understood it from the docs; i may be wrong. Also, the docs state that only sine and triangle waveforms are implemented, then again, i guess the other two might exist in AL-Soft. Zorg (talk) 19:59, 1 February 2017 (CET)

The waveforms are implemented in ALsoft. And yes audio state only changes when you apply any settings. Tables are descriptions of effects, not Effect objects. Raidho36 (talk) 21:34, 1 February 2017 (CET)

I think I prefer echo, which is the OpenAL name anyway. The others are fine. -Bartbes (talk) 20:55, 1 February 2017 (CET)

Reverb Arguments

number density

Reverb Modal Density controls the coloration of the late reverb. Lowering the value adds more coloration to the late reverb. Range: [0,1]

number diffusion

The Reverb Diffusion property controls the echo density in the reverberation decay. It’s set by default to 1.0, which provides the highest density. Reducing diffusion gives the reverberation a more “grainy” character that is especially noticeable with percussive sound sources. If you set a diffusion value of 0.0, the later reverberation sounds like a succession of distinct echoes. Range: [0,1]

number gain (reverbgain)

The Reverb Gain property is the master volume control for the reflected sound (both early reflections and reverberation) that the reverb effect adds to all sound sources. It sets the maximum amount of reflections and reverberation added to the final sound mix. The value of the Reverb Gain property ranges from 1.0 (0db) (the maximum amount) to 0.0 (-100db) (no reflected sound at all).

number hfgain (reverbhighgain, highgain)

The Reverb Gain HF property further tweaks reflected sound by attenuating it at high frequencies. It controls a low-pass filter that applies globally to the reflected sound of all sound sources feeding the particular instance of the reverb effect. The value of the Reverb Gain HF property ranges from 1.0 (0db) (no filter) to 0.0 (-100db) (virtually no reflected sound).

number decay (decaytime)

The Decay Time property sets the reverberation decay time. It ranges from 0.1 (typically a small room with very dead surfaces) to 20.0 (typically a large room with very live surfaces).

number hfdecay (decayhighratio)

The Decay HF Ratio property adjusts the spectral quality of the Decay Time parameter. It is the ratio of high-frequency decay time relative to the time set by Decay Time. The Decay HF Ratio value 1.0 is neutral: the decay time is equal for all frequencies. As Decay HF Ratio increases above 1.0, the high-frequency decay time increases so it’s longer than the decay time at mid frequencies. You hear a more brilliant reverberation with a longer decay at high frequencies. As the Decay HF Ratio value decreases below 1.0, the high-frequency decay time decreases so it’s shorter than the decay time of the mid frequencies. You hear a more natural reverberation. Range: [0.1,2.0]

number earlygain

The Reflections Gain property controls the overall amount of initial reflections relative to the Gain property. (The Gain property sets the overall amount of reflected sound: both initial reflections and later reverberation.) The value of Reflections Gain ranges from a maximum of 3.16 (+10 dB) to a minimum of 0.0 (-100 dB) (no initial reflections at all), and is corrected by the value of the Gain property. The Reflections Gain property does not affect the subsequent reverberation decay. Range: [0,3.16]

number earlydelay

The Reflections Delay property is the amount of delay between the arrival time of the direct path

from the source to the first reflection from the source. It ranges from 0 to 300 milliseconds. You can reduce or increase Reflections Delay to simulate closer or more distant reflective surfaces— and therefore control the perceived size of the room. Range: [0,0.3]

number lategain

The Late Reverb Gain property controls the overall amount of later reverberation relative to the Gain property. (The Gain property sets the overall amount of both initial reflections and later reverberation.) The value of Late Reverb Gain ranges from a maximum of 10.0 (+20 dB) to a minimum of 0.0 (-100 dB) (no late reverberation at all). Range: [0,10]

number latedelay

The Late Reverb Delay property defines the begin time of the late reverberation relative to the time of the initial reflection (the first of the early reflections). It ranges from 0 to 100 milliseconds. Reducing or increasing Late Reverb Delay is useful for simulating a smaller or larger room. Range: [0,0.1]

number rolloff (roomrolloff)

The Room Rolloff Factor property is one of two methods available to attenuate the reflected

sound (containing both reflections and reverberation) according to source-listener distance. Range: [0,10]

number airhfgain (airabsorptionhfgain, highdamp, airabsorption)

The Air Absorption Gain HF property controls the distance-dependent attenuation at high frequencies caused by the propagation medium. It applies to reflected sound only. You can use Air Absorption Gain HF to simulate sound transmission through foggy air, dry air, smoky atmosphere, and so on. Range: [0.892,1]

boolean hflimiter (highlimit)

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 Absorption HF. This limit applies regardless of the setting of the property Decay HF Ratio, and the limit doesn’t affect the value of Decay HF Ratio.

Banter

I prefer the alternate names pretty much everywhere (and I suggested mine otherwise), for completeness sake, these are gain, highgain, decaytime, decayhighratio, roomrolloff, airabsorption and highlimit. An additional note on airabsorption: It's not like there's a parameter to set any other value, so I think adding "high" or "hf" is superfluous. -Bartbes (talk) 20:55, 1 February 2017 (CET)

Chorus Arguments

EffectWaveform waveform

This property sets the waveform shape of the LFO that controls the delay time of the delayed signals.

number phase

This property controls the phase difference between the left and right LFO’s. At zero degrees the two LFOs are synchronized. Use this parameter to create the illusion of an expanded stereo field of the output signal. Range: [-180,+180]

number rate

This property sets the modulation rate of the LFO that controls the delay time of the delayed signals. Range: [0,10]

number depth

This property controls the amount by which the delay time is modulated by the LFO.

number delay

This property 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. Larger values lower the pitch. Smaller values make the chorus sound like a flanger, but with different frequency characteristics. Range: [0,0.016]

number feedback

This property controls the amount of processed signal that is fed back to the input of the chorus effect. Negative values will reverse the phase of the feedback signal. At full magnitude the identical sample will repeat endlessly. At lower magnitudes the sample will repeat and fade out over time. Use this parameter to create a “cascading” chorus effect. Range: [-1,1]

Banter

Phase offset extremes are represented in degrees, may alternatively be normalized to math.pi or 1. Raidho36 (talk) 21:40, 1 February 2017 (CET)

I'd be for math.pi, but if positional audio also uses 1 as units then that's fine too. Zorg (talk) 23:12, 1 February 2017 (CET)

Distortion Arguments

number gain (distortiongain)

This property allows you to attenuate the distorted sound. Range: [0.01,1]

number edge

This property controls the shape of the distortion. The higher the value for Edge, the ‘dirtier’ and ‘fuzzier’ the effect. Range: [0,1]

number lowcut

Input signal can have a low pass filter applied, to limit the amount of high frequency signal feeding into the distortion effect. Range: [80,24000]

number eqcenter

This property controls the frequency at which the post-distortion attenuation (Distortion Gain) is active. Range: [80,24000]

number eqbandwidth

This property controls the bandwidth of the post-distortion attenuation. Range: [80,24000]

Banter

What does "eq" mean here? Equalizer? And how does that relate to distortion? As, admittedly, an audio noob these two param names confuse me the most. -Bartbes (talk) 20:55, 1 February 2017 (CET)

Distortion effect has a 1-band post-distortion equalizer; gain, eqcenter and eqbandwidth control it. Raidho36 (talk) 21:41, 1 February 2017 (CET)

Echo ("Delay") Arguments

number delay

This property controls the delay between the original sound and the first ‘tap’, or echo instance. Subsequently, the value for Echo Delay is used to determine the time delay between each ‘second tap’ and the next ‘first tap’. Range: [0,0.207]

number lrdelay

This property controls the delay between the first ‘tap’ and the second ‘tap’. Subsequently, the value for Echo LR Delay is used to determine the time delay between each ‘first tap’ and the next ‘second tap’. Range: [0,0.404]

number damping

This property controls the amount of high frequency damping applied to each echo. As the sound is subsequently fed back for further echoes, damping results in an echo which progressively gets softer in tone as well as intensity. Range: [0,0.99]

number feedback

This property controls the amount of feedback the output signal fed back into the input. Use this parameter to create “cascading” echoes. At full magnitude, the identical sample will repeat endlessly. Below full magnitude, the sample will repeat and fade. Range: [0,1]

number spread

This property controls how hard panned the individual echoes are. With a value of 1.0, the first ‘tap’ will be panned hard left, and the second tap hard right. A value of –1.0 gives the opposite result. Settings nearer to 0.0 result in less emphasized panning. Range: [-1,1]

Banter

As mentioned in IRC, I'm confused by lrdelay, as I'm not sure what LR means, if it's not Left/Right. And if it is Left/Right, what does that have to do with echo? -Bartbes (talk) 20:55, 1 February 2017 (CET)

Echo effect produces two taps (echoes) of the same sound, lrdelay defines the delay between first and second tap. The parameter that controls stereo separation of those two taps is spread.Raidho36 (talk) 21:44, 1 February 2017 (CET)

So then why is it called lrdelay? -Bartbes (talk) 22:47, 1 February 2017 (CET)

No clue. That's what it's called in OpenAL and it's a direct carry over.Raidho36 (talk) 23:06, 1 February 2017 (CET)

Flanger Arguments

EffectWaveform waveform

Selects the shape of the LFO waveform that controls the amount of the delay of the sampled signal.

number phase

This changes the phase difference between the left and right LFO’s. At zero degrees the two LFOs are synchronized. Range: [-180,+180]

number rate

The number of times per second the LFO controlling the amount of delay repeats. Higher values increase the pitch modulation. Range: [0,10]

number depth

The ratio by which the delay time is modulated by the LFO. Use this parameter to increase the pitch modulation. Range: [0,1]

number delay

The average amount of time the sample is delayed before it is played back; with feedback, the amount of time between iterations of the sample. Range: [0,0.004]

number feedback

This is the amount of the output signal level fed back into the effect’s input. A negative value will reverse the phase of the feedback signal. 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. Range: [-1,1]

Ring modulator Arguments

EffectWaveform waveform

This controls which waveform is used as the carrier signal. Traditional ring modulator and tremolo effects generally use a sinusoidal carrier. Sawtooth and square waveforms are may cause unpleasant aliasing.

number frequency

This is the frequency of the carrier signal. If the carrier signal is slowly varying (less than 20 Hz), the result is a tremolo (slow amplitude variation) effect. If the carrier signal is in the audio range, audible upper and lower sidebands begin to appear, causing an inharmonic effect. The carrier signal itself is not heard in the output. Range: [0,8000]

number highcut

This controls the cutoff frequency at which the input signal is high-pass filtered before being ring modulated. If the cutoff frequency is 0, the entire signal will be ring modulated. If the cutoff frequency is high, very little of the signal (only those parts above the cutoff) will be ring modulated. Range: [0,24000]

Compressor Arguments

None.

Banter

Technically it has an ON/OFF switch, dunno if you want to expose that or not. Zorg (talk) 19:59, 1 February 2017 (CET)

Equalizer Arguments

number lowgain

This property controls amount of cut or boost on the low frequency range.

number lowcut

This property controls the low frequency below which signal will be cut off.

number mid1gain (lowmidgain)

This property allows you to cut / boost signal on the “mid1” range.

number mid1frequency (lowmidfrequency)

This property sets the center frequency for the “mid1” range.

number mid1bandwidth (lowmidbandwidth)

This property controls the width of the “mid1” range.

number mid2gain ( highmidgain)

This property allows you to cut / boost signal on the “mid2” range.

number mid2frequency (highmidfrequency)

This property sets the center frequency for the “mid2” range.

number mid2bandwidth (highmidbandwidth)

This property controls the width of the “mid2” range.

number highgain

This property allows you to cut / boost the signal at high frequencies.

number highcut

This property controls the high frequency above which signal will be cut off.

Banter

I'm not sure how accurate lowmid and highmid are (it looks like openal doesn't care), but I definitely prefer that over mid1 and mid2. -Bartbes (talk) 20:55, 1 February 2017 (CET)

It does care, lower mid band has lower frequency range than higher mid band.Raidho36 (talk) 21:47, 1 February 2017 (CET)

In that case lowmid/highmid is definitely better than mid1/mid2 -Bartbes (talk) 22:47, 1 February 2017 (CET)

Took a look at openal.. the Low Mid is sweepable between 200-1000Hz and the High Mid is sweepable between 1000-8000Hz. therefore the codes lowmid and highmid would be correct.

Unsupported Effects

Following effects and their constants are not supported in current version of AL-soft but as they get support in the future they may get enabled in LÖVE.

Effect types:

• frequencyshifter
• freqshifter
• vocalmorpher
• morpher
• pitchshifter
• autowah

Frequency shifter:

• frequency
• leftdirection
• rightdirection
• Frequency shifting directions:
  • up
  • down
  • none

Vocal morpher:

• waveform
• rate
• phonemea (formant1)
• phonemeb (formant2)
• tunea
• tuneb

Vocal morpher includes a substantial range of effect-specific phoneme constants, but they are no subject for debate, the only variable is letter casing: capital or lowercase, current being latter. Not that it matters, since it's unsupported for now, but i'd vote for uppercase for better legibility.

Pitch shifter:

• pitch

Autowah:

• attack
• release
• resonance
• peakgain