Difference between revisions of "love.audio.setEffect"

(document disabling effects)
(→‎Examples: Added example.)
 
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{newin|[[11.0]]|110|type=function}}
 
{{newin|[[11.0]]|110|type=function}}
−
Defines an effect that can be applied to a [[Source]].
+
Defines an effect that can be [[Source:setEffect|applied]] to a [[Source]].
 +
 
 +
Not all systems support audio effects. Use [[love.audio.isEffectsSupported]] to check.
  
 
== Function ==
 
== Function ==
−
 
 
=== Synopsis ===
 
=== Synopsis ===
 
<source lang="lua">
 
<source lang="lua">
−
love.audio.setEffect(name, settings)
+
love.audio.setEffect( name, settings )
 
</source>
 
</source>
−
 
 
=== Arguments ===
 
=== Arguments ===
 
{{param|string|name|The name of the effect.}}
 
{{param|string|name|The name of the effect.}}
 
{{param|table|settings|The settings to use for this effect, with the following fields:}}
 
{{param|table|settings|The settings to use for this effect, with the following fields:}}
−
{{subparam|string|type|The type of effect to use.}}
+
{{subparam|EffectType|type|The type of effect to use.}}
 
{{subparam|number|volume|The volume of the effect.}}
 
{{subparam|number|volume|The volume of the effect.}}
−
{{subparam|number|...|Effect-specific settings (listed below).}}
+
{{subparam|number|...|Effect-specific settings. See [[EffectType]] for available effects and their corresponding settings.}}
−
 
 
 
=== Returns ===
 
=== Returns ===
 
{{param|boolean|success|Whether the effect was successfully created.}}
 
{{param|boolean|success|Whether the effect was successfully created.}}
  
 
== Function ==
 
== Function ==
−
 
 
=== Synopsis ===
 
=== Synopsis ===
 
<source lang="lua">
 
<source lang="lua">
−
love.audio.setEffect(name, enabled)
+
love.audio.setEffect( name, enabled )
 
</source>
 
</source>
−
 
 
=== Arguments ===
 
=== Arguments ===
 
{{param|string|name|The name of the effect.}}
 
{{param|string|name|The name of the effect.}}
 
{{param|boolean|enabled (true)|If false and the given effect name was previously set, disables the effect.}}
 
{{param|boolean|enabled (true)|If false and the given effect name was previously set, disables the effect.}}
−
 
 
=== Returns ===
 
=== Returns ===
 
{{param|boolean|success|Whether the effect was successfully disabled.}}
 
{{param|boolean|success|Whether the effect was successfully disabled.}}
  
−
== Available effects and corresponding settings ==
+
== Notes ==
−
 
+
Audio produced by effects are added on top of the normal dry sound from Sources.
−
=== reverb ===
 
−
{{param|number|gain|}}
 
−
{{param|number|highgain|}}
 
−
{{param|number|density|}}
 
−
{{param|number|diffusion|}}
 
−
{{param|number|decaytime|}}
 
−
{{param|number|decayhighratio|}}
 
−
{{param|number|earlygain|}}
 
−
{{param|number|earlydelay|}}
 
−
{{param|number|lategain|}}
 
−
{{param|number|latedelay|}}
 
−
{{param|number|roomrolloff|}}
 
−
{{param|number|airabsorption|}}
 
−
{{param|number|highlimit|}}
 
−
 
 
−
=== chorus ===
 
−
{{param|string|waveform|}}
 
−
{{param|number|phase|}}
 
−
{{param|number|rate|}}
 
−
{{param|number|depth|}}
 
−
{{param|number|feedback|}}
 
−
{{param|number|delay|}}
 
−
 
 
−
=== distortion ===
 
−
{{param|number|gain|}}
 
−
{{param|number|edge|}}
 
−
{{param|number|lowcut|}}
 
−
{{param|number|center|}}
 
−
{{param|number|bandwidth|}}
 
−
 
 
−
=== echo ===
 
−
{{param|number|delay|}}
 
−
{{param|number|tapdelay|}}
 
−
{{param|number|damping|}}
 
−
{{param|number|feedback|}}
 
−
{{param|number|spread|}}
 
−
 
 
−
=== flanger ===
 
−
{{param|string|waveform|}}
 
−
{{param|number|phase|}}
 
−
{{param|number|rate|}}
 
−
{{param|number|depth|}}
 
−
{{param|number|feedback|}}
 
−
{{param|number|delay|}}
 
−
 
 
−
=== ringmodulator ===
 
−
{{param|string|waveform|}}
 
−
{{param|number|frequency|}}
 
−
{{param|number|highcut|}}
 
−
 
 
−
=== compressor ===
 
−
{{param|boolean|enable|}}
 
−
 
 
−
=== equalizer ===
 
−
{{param|number|lowgain|}}
 
−
{{param|number|lowcut|}}
 
−
{{param|number|lowmidgain|}}
 
−
{{param|number|lowmidfrequency|}}
 
−
{{param|number|lowmidbandwidth|}}
 
−
{{param|number|highmidgain|}}
 
−
{{param|number|highmidfrequency|}}
 
−
{{param|number|highmidbandwidth|}}
 
−
{{param|number|highgain|}}
 
−
{{param|number|highcut|}}
 
  
 
== Examples ==
 
== Examples ==
 +
=== Play music with added reverb ===
 +
<source lang="lua">
 +
love.audio.setEffect("myEffect", {type="reverb"})
  
−
=== Playing music with added reverb ===
+
local source = love.audio.newSource("music.ogg", "stream")
−
<source lang="lua">
+
source:setEffect("myEffect")
−
love.audio.setEffect('myEffect', {type = 'reverb'})
 
−
local source = love.audio.newSource('music.ogg', 'stream')
 
−
source:setEffect('myEffect')
 
 
source:play()
 
source:play()
 
</source>
 
</source>
  
−
=== Playing music with distortion ===
+
=== Play music with distortion ===
 
<source lang="lua">
 
<source lang="lua">
−
love.audio.setEffect('myEffect', {
+
love.audio.setEffect("myEffect", {
−
type = 'distortion',
+
type = "distortion",
 
gain = .5,
 
gain = .5,
 
edge = .25,
 
edge = .25,
 
})
 
})
−
local source = love.audio.newSource('music.ogg', 'stream')
+
local source = love.audio.newSource("music.ogg", "stream")
−
source:setEffect('myEffect')
+
source:setEffect("myEffect")
 +
source:play()
 +
</source>
 +
 
 +
=== Play effect while muting the dry sound ===
 +
<source lang="lua">
 +
love.audio.setEffect("myEffect", {type="chorus", waveform="sine", rate=5, depth=.5})
 +
 
 +
local source = love.audio.newSource("music.ogg", "stream")
 +
source:setEffect("myEffect")
 +
source:setFilter{ volume=0, type="lowpass" } -- This volume only affects the dry sound.
 
source:play()
 
source:play()
 
</source>
 
</source>
Line 124: Line 66:
 
== See Also ==
 
== See Also ==
 
* [[parent::love.audio]]
 
* [[parent::love.audio]]
 +
* [[love.audio.isEffectsSupported]]
 
* [[Source:setEffect]]
 
* [[Source:setEffect]]
  
 
[[Category:Functions]]
 
[[Category:Functions]]
 
{{#set:Description=Defines an effect that can be applied to a Source.}}
 
{{#set:Description=Defines an effect that can be applied to a Source.}}
 +
 +
== Other Languages ==
 +
{{i18n|love.audio.setEffect}}

Latest revision as of 12:17, 21 August 2022

Available since LÖVE 11.0
This function is not supported in earlier versions.

Defines an effect that can be applied to a Source.

Not all systems support audio effects. Use love.audio.isEffectsSupported to check.

Function

Synopsis

love.audio.setEffect( name, settings )

Arguments

string name
The name of the effect.
table settings
The settings to use for this effect, with the following fields:
EffectType type
The type of effect to use.
number volume
The volume of the effect.
number ...
Effect-specific settings. See EffectType for available effects and their corresponding settings.

Returns

boolean success
Whether the effect was successfully created.

Function

Synopsis

love.audio.setEffect( name, enabled )

Arguments

string name
The name of the effect.
boolean enabled (true)
If false and the given effect name was previously set, disables the effect.

Returns

boolean success
Whether the effect was successfully disabled.

Notes

Audio produced by effects are added on top of the normal dry sound from Sources.

Examples

Play music with added reverb

love.audio.setEffect("myEffect", {type="reverb"})

local source = love.audio.newSource("music.ogg", "stream")
source:setEffect("myEffect")
source:play()

Play music with distortion

love.audio.setEffect("myEffect", {
	type = "distortion",
	gain = .5,
	edge = .25,
})
local source = love.audio.newSource("music.ogg", "stream")
source:setEffect("myEffect")
source:play()

Play effect while muting the dry sound

love.audio.setEffect("myEffect", {type="chorus", waveform="sine", rate=5, depth=.5})

local source = love.audio.newSource("music.ogg", "stream")
source:setEffect("myEffect")
source:setFilter{ volume=0, type="lowpass" } -- This volume only affects the dry sound.
source:play()

See Also


Other Languages

Dansk – Deutsch – English – Español – Français – Indonesia – Italiano – Lietuviškai – Magyar – Nederlands – Polski – Português – Română – Slovenský – Suomi – Svenska – Türkçe – Česky – Ελληνικά – Български – Русский – Српски – Українська – עברית – ไทย – 日本語 – 正體中文 – 简体中文 – Tiếng Việt – 한국어
More info

Retrieved from "https://love2d.org./w/index.php?title=love.audio.setEffect&oldid=27987"