View source for Effect Constants Name Candidates

The upcoming löve version (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.:
<source lang="lua">
{ type = "reverb", volume = 1.0, density = 0.3 } -- This is a reverb Effect.
</source>
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 ===
<source lang="lua">
-- Apply Filter to Source.
success = Source:setFilter(Filter)
--               applyFilter(Filter)

-- Get the currently bound Filter of a Source.
Filter = Source:getFilter()
</source>

=== Filter Arguments ===
{{param|FilterType|type|The type of the Filter. See FilterType below.}}
{{param|number|volume|Gain of the whole spectrum. Range: [0,1]}}
{{param|number|lowgain|Gain on the low-end. Range: [0,1]}}
{{param|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 ===
{{param|string|lowpass|Used to remove high frequency content from a signal.}}
{{param|string|highpass|Used to remove low frequency content from a signal.}}
{{param|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. [[User:Zorg|Zorg]] ([[User talk:Zorg|talk]]) 19:59, 1 February 2017 (CET)
::i dont think the argument name <code>volume</code> is smart as it might make people use the filter section in a wrong manner. a more suitable name would be <code>outgain</code> or <code>output</code>--[[User:Roccdcasbah|Roccdcasbah]] ([[User talk:Roccdcasbah|talk]]) 18:32, 13 March 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 ===
<source lang="lua">
-- 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)
</source>

=== Effect Arguments applicable for all types ===
{{param|EffectType|type|Type of the Effect. See EffectType below.}}
{{param|number|volume|Master volume of the Effect. Range: [0,1]}}
Note: Effect-specific parameters detailed below.

=== EffectType ===
{{param|string|echo (delay)|Decaying feedback based effect on the order of seconds.}}
{{param|string|reverb|Decaying feedback based effect on the order of milliseconds. Used to simulate location properities.}}

{{param|string|chorus|Overlays the signal on top of itself with pitch and time variation. Used to make sounds sound "fuller".}}
{{param|string|flanger|Overlays the signal on top of itself with phase variation.}}

{{param|string|distortion|Clips the sound artificially to make it sound distorted.}}
{{param|string|ringmodulator (ringmod)|Varies the volume over time; with a fast enough speed, it'll sound kinda like a bell.}}

{{param|string|compressor|Increases loudness over the whole spectrum.}}
{{param|string|equalizer|A 4-band equalizer used to modify the signal, boost or cut specific frequency ranges.}}

=== EffectWaveform ===
{{param|string|sine|A sine wave.}}
{{param|string|triangle|A triangle wave.}}
{{param|string|sawtooth|A ramp / sawtooth wave.}}
{{param|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. [[User:Zorg|Zorg]] ([[User talk: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. [[User:Raidho36|Raidho36]] ([[User talk:Raidho36|talk]]) 21:34, 1 February 2017 (CET)
I think I prefer <code>echo</code>, which is the OpenAL name anyway. The others are fine. -[[User:Bartbes|Bartbes]] ([[User talk:Bartbes|talk]]) 20:55, 1 February 2017 (CET)

== Reverb Arguments ==
{{param|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]}}
{{param|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]}}

{{param|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).}}
{{param|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).}}

{{param|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).}}
{{param|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]}}

{{param|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]}}
{{param|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]}}

{{param|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]}}
{{param|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]}}

{{param|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]}}

{{param|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]}}
{{param|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 <code>gain</code>, <code>highgain</code>, <code>decaytime</code>, <code>decayhighratio</code>, <code>roomrolloff</code>, <code>airabsorption</code> and <code>highlimit</code>. An additional note on <code>airabsorption</code>: It's not like there's a parameter to set any other value, so I think adding "high" or "hf" is superfluous. -[[User:Bartbes|Bartbes]] ([[User talk:Bartbes|talk]]) 20:55, 1 February 2017 (CET)

== Chorus Arguments ==
{{param|EffectWaveform|waveform|This property sets the waveform shape of the LFO that controls the delay time of the delayed signals.}}
{{param|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]}}
{{param|number|rate|This property sets the modulation rate of the LFO that controls the delay time of the delayed signals. Range: [0,10]}}
{{param|number|depth|This property controls the amount by which the delay time is modulated by the LFO.}}
{{param|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]}}
{{param|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. [[User:Raidho36|Raidho36]] ([[User talk: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. [[User:Zorg|Zorg]] ([[User talk:Zorg|talk]]) 23:12, 1 February 2017 (CET)

== Distortion Arguments ==
{{param|number|gain (distortiongain)|This property allows you to attenuate the distorted sound. Range: [0.01,1]}}
{{param|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]}}
{{param|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]}}
{{param|number|eqcenter|This property controls the frequency at which the post-distortion attenuation (Distortion Gain) is active. Range: [80,24000]}}
{{param|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. -[[User:Bartbes|Bartbes]] ([[User talk:Bartbes|talk]]) 20:55, 1 February 2017 (CET)
:Distortion effect has a 1-band post-distortion equalizer; gain, eqcenter and eqbandwidth control it. [[User:Raidho36|Raidho36]] ([[User talk:Raidho36|talk]]) 21:41, 1 February 2017 (CET)

== Echo ("Delay") Arguments ==
{{param|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]}}
{{param|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]}}
{{param|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]}}
{{param|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]}}
{{param|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 <code>lrdelay</code>, 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? -[[User:Bartbes|Bartbes]] ([[User talk: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.[[User:Raidho36|Raidho36]] ([[User talk:Raidho36|talk]]) 21:44, 1 February 2017 (CET)
::So then why is it called <code>lrdelay</code>? -[[User:Bartbes|Bartbes]] ([[User talk: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.[[User:Raidho36|Raidho36]] ([[User talk:Raidho36|talk]]) 23:06, 1 February 2017 (CET)

== Flanger Arguments ==
{{param|EffectWaveform|waveform|Selects the shape of the LFO waveform that controls the amount of the delay of the sampled signal.}}
{{param|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]}}
{{param|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]}}
{{param|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]}}
{{param|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]}}
{{param|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]}}
=== Banter ===

== Ring modulator Arguments ==
{{param|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. }}
{{param|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]}}
{{param|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]}}
=== Banter ===



== Compressor Arguments ==
None.
=== Banter ===
Technically it has an ON/OFF switch, dunno if you want to expose that or not. [[User:Zorg|Zorg]] ([[User talk:Zorg|talk]]) 19:59, 1 February 2017 (CET)



== Equalizer Arguments ==
{{param|number|lowgain|This property controls amount of cut or boost on the low frequency range.}}
{{param|number|lowcut|This property controls the low frequency below which signal will be cut off.}}
{{param|number|mid1gain (lowmidgain)|This property allows you to cut / boost signal on the “mid1” range.}}
{{param|number|mid1frequency (lowmidfrequency)|This property sets the center frequency for the “mid1” range.}}
{{param|number|mid1bandwidth (lowmidbandwidth)|This property controls the width of the “mid1” range.}}
{{param|number|mid2gain ( highmidgain)|This property allows you to cut / boost signal on the “mid2” range.}}
{{param|number|mid2frequency (highmidfrequency)|This property sets the center frequency for the “mid2” range.}}
{{param|number|mid2bandwidth (highmidbandwidth)|This property controls the width of the “mid2” range.}}
{{param|number|highgain|This property allows you to cut / boost the signal at high frequencies.}}
{{param|number|highcut|This property controls the high frequency above which signal will be cut off.}}
=== Banter ===

I'm not sure how accurate <code>lowmid</code> and <code>highmid</code> are (it looks like openal doesn't care), but I definitely prefer that over <code>mid1</code> and <code>mid2</code>. -[[User:Bartbes|Bartbes]] ([[User talk:Bartbes|talk]]) 20:55, 1 February 2017 (CET)
:It does care, lower mid band has lower frequency range than higher mid band.[[User:Raidho36|Raidho36]] ([[User talk:Raidho36|talk]]) 21:47, 1 February 2017 (CET)
::In that case <code>lowmid</code>/<code>highmid</code> is definitely better than <code>mid1</code>/<code>mid2</code> -[[User:Bartbes|Bartbes]] ([[User talk: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 <code>lowmid</code> and <code>highmid</code> would be correct.--[[User:Roccdcasbah|Roccdcasbah]] ([[User talk:Roccdcasbah|talk]]) 18:32, 13 March 2017 (CET)

::::And the argument "bandwidth" is not really common "soundlingo", the more correct name would simply be "Q". so <code>mid1bandwidth</code> would become <code>mid1Q</code> or if you use the suggestion in my previous comment <code>lowmidQ</code>.--[[User:Roccdcasbah|Roccdcasbah]] ([[User talk:Roccdcasbah|talk]]) 18:32, 13 March 2017 (CET)

:::::I tend to agree with using Q here, but only because it both makes the parameter names shorter, and that it is an accepted term for these kinds of parameters, as said above. ("In physics and engineering the quality factor or Q factor is a dimensionless parameter that describes how under-damped an oscillator or resonator is,[1] and characterizes a resonator's bandwidth relative to its center frequency." ~ [https://en.wikipedia.org/wiki/Q_factor Wikipedia]) That said, from a somewhat layman's perspective, explaining it as the bandwidth from the center frequency of the bands on the wiki should be good enough. --[[User:Zorg|Zorg]] ([[User talk:Zorg|talk]]) 18:41, 13 March 2017 (CET)

== 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

== Queuable Sources ==

== Audio Recording / Input ==