Difference between revisions of "Effect Constants Name Candidates"

m (Constants: ringmod suggestion)
m (0.11.0 -> 11.0)
 
(41 intermediate revisions by 4 users not shown)
Line 1: Line 1:
Effects and Filters are coming in version 0.11 but their names are not finalized and are subject to discussion, since many of them are picked poorly.  
+
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.
  
'''Alternative suggested names go underneath the basic name.'''
+
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 passed in as a table with named parameters, e.g.:
+
'''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.
  
{ type = "lowpass", volume = 1, lowgain = 0.3 }
+
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.
  
Refer to OpenAL EFX handbook for underlying system details: http://kcat.strangesoft.net/misc-downloads/Effects%20Extension%20Guide.pdf
+
== 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]}}
  
==Filters==
+
{{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]}}
Filters are basic low-pass, high-pass and "combo"-pass (band-pass) frequency filters. They can be applied to each sound Source individually, but only one Filter per Source at a time.
+
{{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 ===
  
===Functions===
+
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)
Apply Filter to Source:
 
* Source:setFilter
 
** Source:applyFilter
 
  
Get current Source filter:
+
== Chorus Arguments ==
* Source:getFilter
+
{{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)
  
===Constants===
+
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)
Filter types:
 
* lowpass -removes upper part of the spectrum, making the sound muffled as if it passed through a thick barrier
 
* highpass -removes lower part of the spectrum, eliminating the bass
 
* bandpass -removes both upper and lower part of the spectrum, leaving alone the area between lowgain and highgain.
 
  
Parameters:
+
== Distortion Arguments ==
* type - the above three.
+
{{param|number|gain (distortiongain)|This property allows you to attenuate the distorted sound. Range: [0.01,1]}}
* volume -(define whether this affects the attenuation for the affected areas, or for the whole)
+
{{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]}}
* lowgain -lower part of the spectrum multiplier.
+
{{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]}}
* highgain -upper part of the spectrum multiplier.
+
{{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 ===
  
==Effects==
+
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)
Effects are advanced audio filters that can be used to recreate realistic acoustic properties of the level as well as creating cool effects. 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, it will filter the sound on the path between Source and Effect. Effects work continuously, even when no sound is fed, e.g. reverberation Effect can still output decaying reverb long after all input is cut.
+
: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)
  
===Functions===
+
== Echo ("Delay") Arguments ==
Apply Effect to scene:
+
{{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]}}
* love.audio.setSceneEffect
+
{{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]}}
** love.audio.applySceneEffect
+
{{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]}}
** love.audio.setEffect -- 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.
+
{{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 ===
  
Get current scene Effect:
+
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)
* love.audio.getSceneEffect
+
: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)
** love.audio.getEffect
+
::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)
  
Use scene Effect with Source:
+
== Flanger Arguments ==
* Source:setSceneEffect
+
{{param|EffectWaveform|waveform|Selects the shape of the LFO waveform that controls the amount of the delay of the sampled signal.}}
** Source:useSceneEffect
+
{{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]}}
** Source:setEffect -- with a disclaimer on the wiki page that modifying an effect's parameter won't apply it here until you call this again.
+
{{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 ===
  
Get Source's currently used scene Effect:
+
== Ring modulator Arguments ==
* Source:getSceneEffect
+
{{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. }}
** Source:getEffect
+
{{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 ===
  
===Constants===
 
Effect types:
 
* reverb -adds decaying continuous sound repetition
 
* chorus -lays sound over itself with pitch and delay variation
 
* distortion -produces artificial sound clipping
 
* echo
 
* flanger -lays sound over itself with phase shift
 
* ringmodulator -rapidly increases and decreases volume cyclically
 
** modulator -imprecise; people will assume this allows AM/FM modulation instead of ringmod.
 
* compressor -increases loudness in entire frequency range to the maximum
 
* equalizer
 
  
Effect waveforms:
 
* sine
 
* triangle
 
* sawtooth
 
* square
 
  
Effect parameters:
+
== Compressor Arguments ==
* type
+
None.
* volume
+
=== 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)
  
Reverb:
 
* gain
 
** reverbgain
 
* hfgain
 
* density
 
* diffusion
 
* decay
 
* hfdecay
 
* earlygain
 
* lategain
 
* earlydelay
 
* latedelay
 
* rolloff
 
** roomrolloff
 
* airhfgain
 
** airabsorptionhfgain
 
* hflimiter
 
  
Chorus:
 
* waveform
 
* phase
 
* rate
 
* depth
 
* delay
 
* feedback
 
  
Distortion:
+
== Equalizer Arguments ==
* gain
+
{{param|number|lowgain|This property controls amount of cut or boost on the low frequency range.}}
* edge -effect strength
+
{{param|number|lowcut|This property controls the low frequency below which signal will be cut off.}}
* lowcut
+
{{param|number|mid1gain (lowmidgain)|This property allows you to cut / boost signal on the “mid1” range.}}
* eqcenter
+
{{param|number|mid1frequency (lowmidfrequency)|This property sets the center frequency for the “mid1” range.}}
* eqbandwidth
+
{{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 ===
  
Echo:
+
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)
* delay -delay between input and first main echo
+
: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)
* lrdelay -delay between first main echo and second trailing echo
+
::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)
* damping
 
* spread -stereo separation between first and second echo
 
* feedback
 
  
Flanger:
+
:::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)
* waveform
 
* phase
 
* rate
 
* depth
 
* delay
 
* feedback
 
  
Ring modulator:
+
::::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)
* waveform
 
* frequency
 
* highcut
 
  
Equalizer:
+
:::::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)
* lowgain
 
* lowcut
 
* mid1gain
 
* mid1frequency
 
* mid1bandwidth
 
* mid2gain
 
* mid2frequency
 
* mid2bandwidth
 
* highgain
 
* highcut
 
  
===Unsupported===
+
== 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.
 
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:
 
Effect types:
 
* frequencyshifter
 
* frequencyshifter
** freqshifter
+
* freqshifter
 
* vocalmorpher
 
* vocalmorpher
** morpher
+
* morpher
 
* pitchshifter
 
* pitchshifter
 
* autowah
 
* autowah
Line 156: Line 222:
 
* leftdirection
 
* leftdirection
 
* rightdirection
 
* rightdirection
 
+
* Frequency shifting directions:
Frequency shifting directions:
+
** up
* up
+
** down
* down
+
** none
* none
 
  
 
Vocal morpher:
 
Vocal morpher:
 
* waveform
 
* waveform
 
* rate
 
* rate
* phonemea
+
* phonemea (formant1)
* phonemeb
+
* phonemeb (formant2)
 
* tunea
 
* tunea
 
* tuneb
 
* 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.
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.
 
  
 
Pitch shifter:
 
Pitch shifter:
* pitch  
+
* pitch
  
 
Autowah:
 
Autowah:
Line 180: Line 244:
 
* resonance
 
* resonance
 
* peakgain
 
* peakgain
 +
 +
== Queuable Sources ==
 +
 +
== Audio Recording / Input ==

Latest revision as of 18:18, 7 May 2019

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.:

{ 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)

i dont think the argument name volume is smart as it might make people use the filter section in a wrong manner. a more suitable name would be outgain or output--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

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

Banter

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]

Banter

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.--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 mid1bandwidth would become mid1Q or if you use the suggestion in my previous comment lowmidQ.--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." ~ 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. --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