diff --git a/doc/classes/AudioEffect.xml b/doc/classes/AudioEffect.xml index 626bb1370c..eb02bf8515 100644 --- a/doc/classes/AudioEffect.xml +++ b/doc/classes/AudioEffect.xml @@ -5,10 +5,11 @@ The base [Resource] for every audio effect. In the editor, an audio effect can be added to the current bus layout through the Audio panel. At run-time, it is also possible to manipulate audio effects through [method AudioServer.add_bus_effect], [method AudioServer.remove_bus_effect], and [method AudioServer.get_bus_effect]. - When applied on a bus, an audio effect creates a corresponding [AudioEffectInstance]. The instance is directly responsible for manipulating the sound, based on the original audio effect's properties. + When applied on a bus, an audio effect creates a corresponding [AudioEffectInstance]. The instance is directly responsible for manipulating sound, based on the original audio effect's properties. $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html https://godotengine.org/asset-library/asset/2760 diff --git a/doc/classes/AudioEffectAmplify.xml b/doc/classes/AudioEffectAmplify.xml index ae12b6c193..27603c7a2d 100644 --- a/doc/classes/AudioEffectAmplify.xml +++ b/doc/classes/AudioEffectAmplify.xml @@ -1,17 +1,18 @@ - Adds an amplifying audio effect to an audio bus. + Adds a volume manipulation audio effect to an audio bus. Increases or decreases the volume being routed through the audio bus. $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html - Amount of amplification in decibels. Positive values make the sound louder, negative values make it quieter. Value can range from -80 to 24. + Amount of amplification in dB. Positive values make the sound louder, negative values make it quieter. Value can range from -80 to 24. Amount of amplification as a linear value. diff --git a/doc/classes/AudioEffectBandLimitFilter.xml b/doc/classes/AudioEffectBandLimitFilter.xml index c8667818ba..daa294dbb6 100644 --- a/doc/classes/AudioEffectBandLimitFilter.xml +++ b/doc/classes/AudioEffectBandLimitFilter.xml @@ -1,12 +1,14 @@ - Adds a band limit filter to the audio bus. + Adds a band-limit filter to an audio bus. - Limits the frequencies in a range around the [member AudioEffectFilter.cutoff_hz] and allows frequencies outside of this range to pass. + A "band-limit" filter attenuates the frequencies at [member AudioEffectFilter.cutoff_hz], and allows frequencies outside the frequency threshold to pass unchanged. It is a wider and weaker version of [AudioEffectNotchFilter], and is the opposite of [AudioEffectBandPassFilter]. + This filter can be used to give more room for other sounds to play at that frequency. $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html diff --git a/doc/classes/AudioEffectBandPassFilter.xml b/doc/classes/AudioEffectBandPassFilter.xml index 64bff53467..60644dde51 100644 --- a/doc/classes/AudioEffectBandPassFilter.xml +++ b/doc/classes/AudioEffectBandPassFilter.xml @@ -1,12 +1,14 @@ - Adds a band pass filter to the audio bus. + Adds a band-pass filter to an audio bus. - Attenuates the frequencies inside of a range around the [member AudioEffectFilter.cutoff_hz] and cuts frequencies outside of this band. + A "band-pass" filter allows the frequencies at [member AudioEffectFilter.cutoff_hz] to pass unchanged, and attenuates frequencies outside the frequency threshold. It is the opposite of [AudioEffectBandLimitFilter] and [AudioEffectNotchFilter]. + This filter can be used to emulate sounds coming from weak speakers. $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html diff --git a/doc/classes/AudioEffectCapture.xml b/doc/classes/AudioEffectCapture.xml index ce516be5fc..5c8eb7987e 100644 --- a/doc/classes/AudioEffectCapture.xml +++ b/doc/classes/AudioEffectCapture.xml @@ -1,10 +1,10 @@ - Captures audio from an audio bus in real-time. + Exposes audio samples from an audio bus in real-time, such that it can be accessed as data. - AudioEffectCapture is an AudioEffect which copies all audio frames from the attached audio effect bus into its internal ring buffer. + Copies all audio frames, also known as "samples" or "audio samples", from the attached audio bus into its internal ring buffer. This effect does not alter the audio. Can be used for storing real-time audio data for playback, and for creating real-time audio visualizations, like an oscilloscope. Application code should consume these audio frames from this ring buffer using [method get_buffer] and process it as needed, for example to capture data from an [AudioStreamMicrophone], implement application-defined effects, or to transmit audio over the network. When capturing audio data from a microphone, the format of the samples will be stereo 32-bit floating-point PCM. Unlike [AudioEffectRecord], this effect only returns the raw audio samples instead of encoding them into an [AudioStream]. @@ -16,7 +16,7 @@ - Returns [code]true[/code] if at least [param frames] audio frames are available to read in the internal ring buffer. + Returns [code]true[/code] if at least [param frames] samples are available to read in the internal ring buffer. @@ -30,39 +30,40 @@ - Gets the next [param frames] audio samples from the internal ring buffer. - Returns a [PackedVector2Array] containing exactly [param frames] audio samples if available, or an empty [PackedVector2Array] if insufficient data was available. + Gets the next [param frames] samples from the internal ring buffer. + Returns a [PackedVector2Array] containing exactly [param frames] samples if available, or an empty [PackedVector2Array] if insufficient data was available. The samples are signed floating-point PCM between [code]-1[/code] and [code]1[/code]. You will have to scale them if you want to use them as 8 or 16-bit integer samples. ([code]v = 0x7fff * samples[0].x[/code]) - Returns the total size of the internal ring buffer in frames. + Returns the total size of the internal ring buffer in number of samples. - Returns the number of audio frames discarded from the audio bus due to full buffer. + Returns the number of samples discarded from the audio bus due to full buffer. - Returns the number of frames available to read using [method get_buffer]. + Returns the number of samples available to read using [method get_buffer]. - Returns the number of audio frames inserted from the audio bus. + Returns the number of samples inserted from the audio bus. - Length of the internal ring buffer, in seconds. Setting the buffer length will have no effect if already initialized. + Length of the internal ring buffer, in seconds. Higher values keep data around for longer, but require more memory. Value can range from 0.01 to 10. + [b]Note:[/b] Setting the buffer length will have no effect if already initialized. diff --git a/doc/classes/AudioEffectChorus.xml b/doc/classes/AudioEffectChorus.xml index f0c1d7c111..6ae02cd549 100644 --- a/doc/classes/AudioEffectChorus.xml +++ b/doc/classes/AudioEffectChorus.xml @@ -1,49 +1,60 @@ - Adds a chorus audio effect. + Adds a chorus audio effect to an audio bus. + Gives the impression of multiple audio sources. - Adds a chorus audio effect. The effect applies a filter with voices to duplicate the audio source and manipulate it through the filter. + A "chorus" effect creates multiple copies of the original audio (called "voices") with variations in pitch, and layers on top of the original, giving the impression that the sound comes from multiple sources. This creates spectral and spatial movement. + Each voice is played a short period of time after the original audio, controlled by [code]delay[/code]. An internal low-frequency oscillator (LFO) controls their pitch, and [code]depth[/code] controls the LFO's maximum amount. + In the real world, this kind of effect is found in pianos, choirs, and instrument ensembles. + This effect can also be used to widen mono audio and make digital sounds have a more natural or analog quality. $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html + Returns the frequency threshold of a given [param voice_idx]'s low-pass filter in Hz. Frequencies above this value are removed from the voice. + Returns the delay of a given [param voice_idx] in milliseconds, compared to the original audio. + Returns the depth of a given [param voice_idx]'s low-frequency oscillator in milliseconds. + Returns the gain of a given [param voice_idx] in dB. + Returns the pan position of a given [param voice_idx]. Negative values mean the left channel, positive mean the right. + Returns the rate of a given [param voice_idx]'s low-frequency oscillator in Hz. @@ -51,6 +62,7 @@ + Sets the frequency threshold of a given [param voice_idx]'s low-pass filter in Hz. Frequencies above [param cutoff_hz] are removed from [param voice_idx]. Value can range from 1 to 20500. @@ -58,6 +70,7 @@ + Sets the delay of a given [param voice_idx] in milliseconds, compared to the original audio. Value can range from 0 to 50. @@ -65,6 +78,7 @@ + Sets the depth of a given [param voice_idx]'s low-frequency oscillator in milliseconds. Value can range from 0 to 20. @@ -72,6 +86,7 @@ + Sets the gain of a given [param voice_idx] in dB. Value can range from -60 to 24. @@ -79,6 +94,7 @@ + Sets the pan position of a given [param voice_idx]. Negative values pan the sound to the left, positive pan to the right. Value can range from -1 to 1. @@ -86,90 +102,91 @@ + Sets the rate of a given [param voice_idx]'s low-frequency oscillator in Hz. Value can range from 0.1 to 20. - The effect's raw signal. + The volume ratio of the original audio. Value can range from 0 to 1. - The voice's cutoff frequency. + The frequency threshold of the voice's low-pass filter in Hz. - The voice's signal delay. + The delay of the voice in milliseconds, compared to the original audio. - The voice filter's depth. + The depth of the voice's low-frequency oscillator in milliseconds. - The voice's volume. + The gain of the voice in dB. - The voice's pan level. + The pan position of the voice. - The voice's filter rate. + The rate of the voice's low-frequency oscillator in Hz. - The voice's cutoff frequency. + The frequency threshold of the voice's low-pass filter in Hz. - The voice's signal delay. + The delay of the voice in milliseconds, compared to the original audio. - The voice filter's depth. + The depth of the voice's low-frequency oscillator in milliseconds. - The voice's volume. + The gain of the voice in dB. - The voice's pan level. + The pan position of the voice. - The voice's filter rate. + The rate of the voice's low-frequency oscillator in Hz. - The voice's cutoff frequency. + The frequency threshold of the voice's low-pass filter in Hz. - The voice's signal delay. + The delay of the voice in milliseconds, compared to the original audio. - The voice filter's depth. + The depth of the voice's low-frequency oscillator in milliseconds. - The voice's volume. + The gain of the voice in dB. - The voice's pan level. + The pan position of the voice. - The voice's filter rate. + The rate of the voice's low-frequency oscillator in Hz. - The voice's cutoff frequency. + The frequency threshold of the voice's low-pass filter in Hz. - The voice's signal delay. + The delay of the voice in milliseconds, compared to the original audio. - The voice filter's depth. + The depth of the voice's low-frequency oscillator in milliseconds. - The voice's volume. + The gain of the voice in dB. - The voice's pan level. + The pan position of the voice. - The voice's filter rate. + The rate of the voice's low-frequency oscillator in Hz. - The number of voices in the effect. + The number of voices in the effect. Value can range from 1 to 4. - The effect's processed signal. + The volume ratio of all voices. Value can range from 0 to 1. diff --git a/doc/classes/AudioEffectCompressor.xml b/doc/classes/AudioEffectCompressor.xml index f6d94e0ccc..8720db3f3e 100644 --- a/doc/classes/AudioEffectCompressor.xml +++ b/doc/classes/AudioEffectCompressor.xml @@ -1,41 +1,42 @@ - Adds a compressor audio effect to an audio bus. - Reduces sounds that exceed a certain threshold level, smooths out the dynamics and increases the overall volume. + Adds a downward compressor audio effect to an audio bus. + Allows control of the dynamic range via a volume threshold and timing controls. - Dynamic range compressor reduces the level of the sound when the amplitude goes over a certain threshold in Decibels. One of the main uses of a compressor is to increase the dynamic range by clipping as little as possible (when sound goes over 0dB). - Compressor has many uses in the mix: - - In the Master bus to compress the whole output (although an [AudioEffectHardLimiter] is probably better). - - In voice channels to ensure they sound as balanced as possible. - - Sidechained. This can reduce the sound level sidechained with another audio bus for threshold detection. This technique is common in video game mixing to the level of music and SFX while voices are being heard. - - Accentuates transients by using a wider attack, making effects sound more punchy. + A "compressor" decreases the volume of sounds when it exceeds a certain volume threshold level. + A compressor can have many uses in a mix: + - To compress the whole volume in the Master bus (although an [AudioEffectHardLimiter] is probably better). + - To ensure balance of voice audio clips. + - To sidechain, using another bus as a trigger. This decreases the volume of the bus it is attached to, by using the volume from another audio bus for threshold detection. This technique is common in video game mixing to decrease the volume of music and SFX while voices are being heard. This effect is also known as "ducking". + - To accentuate transients by using a long attack, letting sounds exceed the volume threshold level for a short period before compressing them. This can be used to make SFX more punchy. $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html - Compressor's reaction time when the signal exceeds the threshold, in microseconds. Value can range from 20 to 2000. + Compressor's reaction time when the audio exceeds the volume threshold level, in microseconds. Value can range from 20 to 2000. - Gain applied to the output signal. + Gain of the audio signal, in dB. Value can range from -20 to 20. - Balance between original signal and effect signal. Value can range from 0 (totally dry) to 1 (totally wet). + Balance between the original audio and the compressed audio. Value can range from 0 (totally dry) to 1 (totally wet). - Amount of compression applied to the audio once it passes the threshold level. The higher the ratio, the more the loud parts of the audio will be compressed. Value can range from 1 to 48. + Amount of compression applied to the audio once it passes the volume threshold level. The higher the ratio, the stronger the compression applied to audio signals that pass the volume threshold level. Value can range from 1 to 48. - Compressor's delay time to stop reducing the signal after the signal level falls below the threshold, in milliseconds. Value can range from 20 to 2000. + Compressor's delay time to stop decreasing the volume after the it falls below the volume threshold level, in milliseconds. Value can range from 20 to 2000. - Reduce the sound level using another audio bus for threshold detection. + Audio bus to use for the volume threshold detection. - The level above which compression is applied to the audio. Value can range from -60 to 0. + The volume level above which compression is applied to the audio, in dB. Value can range from -60 to 0. diff --git a/doc/classes/AudioEffectDelay.xml b/doc/classes/AudioEffectDelay.xml index eae49f6a98..525be7bb02 100644 --- a/doc/classes/AudioEffectDelay.xml +++ b/doc/classes/AudioEffectDelay.xml @@ -1,54 +1,56 @@ - Adds a delay audio effect to an audio bus. Plays input signal back after a period of time. - Two tap delay and feedback options. + Adds a delay audio effect to an audio bus. + Emulates an echo by playing the input audio back after a period of time. - Plays input signal back after a period of time. The delayed signal may be played back multiple times to create the sound of a repeating, decaying echo. Delay effects range from a subtle echo effect to a pronounced blending of previous sounds with new sounds. + A "delay" effect plays the input audio signal back after a period of time. Each repetition is called a "delay tap" or simply "tap". Delay taps may be played back multiple times to create the sound of a repeating, decaying echo. Delay effects range from a subtle echo to a pronounced blending of previous sounds with new sounds. + See also [AudioEffectReverb] for a blurry, continuous echo. $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html - Output percent of original sound. At 0, only delayed sounds are output. Value can range from 0 to 1. + The volume ratio of the original audio. Value can range from 0 to 1. - If [code]true[/code], feedback is enabled. + If [code]true[/code], feedback is enabled, repeating taps after they are played. - Feedback delay time in milliseconds. + Feedback delay time in milliseconds. Value can range from 0 to 1500. - Sound level for feedback. + Gain for feedback, in dB. Value can range from -60 to 0. - Low-pass filter for feedback, in Hz. Frequencies below this value are filtered out of the source signal. + Low-pass filter for feedback, in Hz. Frequencies above this value are filtered out. Value can range from 1 to 16000. If [code]true[/code], the first tap will be enabled. - First tap delay time in milliseconds. + First tap delay time in milliseconds, compared to the original audio. Value can range from 0 to 1500. - Sound level for the first tap. + Gain for the first tap, in dB. Value can range from -60 to 0. - Pan position for the first tap. Value can range from -1 (fully left) to 1 (fully right). + Pan position for the first tap. Negative values pan the sound to the left, positive pan to the right. Value can range from -1 to 1. If [code]true[/code], the second tap will be enabled. - Second tap delay time in milliseconds. + Second tap delay time in milliseconds, compared to the original audio. Value can range from 0 to 1500. - Sound level for the second tap. + Gain for the second tap, in dB. Value can range from -60 to 0. - Pan position for the second tap. Value can range from -1 (fully left) to 1 (fully right). + Pan position for the second tap. Negative values pan the sound to the left, positive pan to the right. Value can range from -1 to 1. diff --git a/doc/classes/AudioEffectDistortion.xml b/doc/classes/AudioEffectDistortion.xml index f8c6804772..8b9115ebab 100644 --- a/doc/classes/AudioEffectDistortion.xml +++ b/doc/classes/AudioEffectDistortion.xml @@ -1,47 +1,53 @@ - Adds a distortion audio effect to an Audio bus. - Modifies the sound to make it distorted. + Adds a distortion audio effect to an audio bus. + Remaps audio samples using a nonlinear function to achieve a distorted sound. - Different types are available: clip, tan, lo-fi (bit crushing), overdrive, or waveshape. - By distorting the waveform the frequency content changes, which will often make the sound "crunchy" or "abrasive". For games, it can simulate sound coming from some saturated device or speaker very efficiently. + A "distortion" effect modifies the waveform via a nonlinear mathematical function (see available ones in [enum Mode]), based on the amplitude of the waveform's samples. + [b]Note:[/b] In a nonlinear function, an input sample at [i]x[/i] amplitude value, will either have its amplitude increased or decreased to a [i]y[/i] value, based on the function value at [i]x[/i], which is why even at the same [member drive], the output sound will vary depending on the input's volume. To change the volume while maintaining the output waveform, use [member post_gain]. + In this effect, each type is a different nonlinear function. The different types available are: clip, atan, lofi (bitcrush), overdrive, and waveshape. Every distortion type available here is symmetric: negative amplitude values are affected the same way as positive ones. + Although distortion will always change frequency content, usually by introducing high harmonics, different distortion types offer a range of sound qualities; from "soft" and "warm", to "crunchy" and "abrasive". + For games, it can help simulate sound coming from some saturated device or speaker very efficiently. It can also help the audio stand out in a mix, by introducing higher frequencies and increasing the volume. + [b]Note:[/b] Although usually imperceptible, an enabled distortion effect still changes the sound even when [member drive] is set to 0. This is not a bug. If this behavior is undesirable, consider disabling the effect using [method AudioServer.set_bus_effect_enabled]. $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html - Distortion power. Value can range from 0 to 1. + Distortion intensity. Controls how much of the input audio is affected by the distortion curve by moving from a linear function to a nonlinear one. Value can range from 0 to 1. High-pass filter, in Hz. Frequencies higher than this value will not be affected by the distortion. Value can range from 1 to 20000. - Distortion type. + Distortion type. Changes the nonlinear function used to distort the waveform. See [enum Mode]. - Increases or decreases the volume after the effect, in decibels. Value can range from -80 to 24. + Gain after the effect, in dB. Value can range from -80 to 24. - Increases or decreases the volume before the effect, in decibels. Value can range from -60 to 60. + Gain before the effect, in dB. Value can range from -60 to 60. - Digital distortion effect which cuts off peaks at the top and bottom of the waveform. + Flattens the waveform at 0 dB in a sharp manner. [member drive] increases amplitude of samples exponentially. This mode functions as a hard clipper if [member drive] is set to 0, and is the only mode that clips audio signals at 0 dB. + Flattens the waveform in a smooth manner, following an arctangent curve. The audio decreases in volume, before flattening peaks to [code]PI * 4.0[/code] (linear value), if it was normalized beforehand. - Low-resolution digital distortion effect (bit depth reduction). You can use it to emulate the sound of early digital audio devices. + Decreases audio bit depth to achieve a low-resolution audio signal, going from 16-bit to 2-bit. Can be used to emulate the sound of early digital audio devices. - Emulates the warm distortion produced by a field effect transistor, which is commonly used in solid-state musical instrument amplifiers. The [member drive] property has no effect in this mode. + Emulates the warm distortion produced by a field effect transistor, which is commonly used in solid-state musical instrument amplifiers. [member drive] has no effect in this mode. - Waveshaper distortions are used mainly by electronic musicians to achieve an extra-abrasive sound. + Flattens the waveform in a smooth manner, until it reaches a sharp peak at [code]drive = 1[/code], following a generic absolute sigmoid function. diff --git a/doc/classes/AudioEffectEQ.xml b/doc/classes/AudioEffectEQ.xml index fb06ee2a54..67103f961d 100644 --- a/doc/classes/AudioEffectEQ.xml +++ b/doc/classes/AudioEffectEQ.xml @@ -1,14 +1,16 @@ - Base class for audio equalizers. Gives you control over frequencies. - Use it to create a custom equalizer if [AudioEffectEQ6], [AudioEffectEQ10] or [AudioEffectEQ21] don't fit your needs. + Base class for audio equalizers (EQ). Gives you control over frequencies. + Use it to create a custom equalizer if [AudioEffectEQ6], [AudioEffectEQ10], or [AudioEffectEQ21] don't fit your needs. - AudioEffectEQ gives you control over frequencies. Use it to compensate for existing deficiencies in audio. AudioEffectEQs are useful on the Master bus to completely master a mix and give it more character. They are also useful when a game is run on a mobile device, to adjust the mix to that kind of speakers (it can be added but disabled when headphones are plugged). + An "equalizer" gives you control over the gain of frequencies in the entire spectrum, by allowing their adjustment through bands. A band is a point in the frequency spectrum, and each band means a division of the spectrum that can be adjusted. + Use equalizers to compensate for existing deficiencies in the audio, make room for other elements, or remove undesirable frequencies. AudioEffectEQs are useful on the Master bus to balance the entire mix or give it more character. They are also useful when a game is run on a mobile device, to adjust the mix to that kind of speakers (it can be disabled when headphones are plugged in). $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html diff --git a/doc/classes/AudioEffectEQ10.xml b/doc/classes/AudioEffectEQ10.xml index b236ba7b02..a9fea213bb 100644 --- a/doc/classes/AudioEffectEQ10.xml +++ b/doc/classes/AudioEffectEQ10.xml @@ -1,8 +1,8 @@ - Adds a 10-band equalizer audio effect to an Audio bus. Gives you control over frequencies from 31 Hz to 16000 Hz. - Each frequency can be modulated between -60/+24 dB. + Adds a 10-band equalizer audio effect to an audio bus. + Gives you control over frequencies from 31 Hz to 16000 Hz. Each frequency can be modulated between -60/+24 dB. Frequency bands: @@ -20,5 +20,6 @@ $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html diff --git a/doc/classes/AudioEffectEQ21.xml b/doc/classes/AudioEffectEQ21.xml index 41ceed1707..630ba08613 100644 --- a/doc/classes/AudioEffectEQ21.xml +++ b/doc/classes/AudioEffectEQ21.xml @@ -1,8 +1,8 @@ - Adds a 21-band equalizer audio effect to an Audio bus. Gives you control over frequencies from 22 Hz to 22000 Hz. - Each frequency can be modulated between -60/+24 dB. + Adds a 21-band equalizer audio effect to an audio bus. + Gives you control over frequencies from 22 Hz to 22000 Hz. Each frequency can be modulated between -60/+24 dB. Frequency bands: @@ -31,5 +31,6 @@ $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html diff --git a/doc/classes/AudioEffectEQ6.xml b/doc/classes/AudioEffectEQ6.xml index 6e4a16ddf2..135954a00a 100644 --- a/doc/classes/AudioEffectEQ6.xml +++ b/doc/classes/AudioEffectEQ6.xml @@ -1,8 +1,8 @@ - Adds a 6-band equalizer audio effect to an audio bus. Gives you control over frequencies from 32 Hz to 10000 Hz. - Each frequency can be modulated between -60/+24 dB. + Adds a 6-band equalizer audio effect to an audio bus. + Gives you control over frequencies from 32 Hz to 10000 Hz. Each frequency can be modulated between -60/+24 dB. Frequency bands: @@ -16,5 +16,6 @@ $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html diff --git a/doc/classes/AudioEffectFilter.xml b/doc/classes/AudioEffectFilter.xml index 18540de736..f47541a05a 100644 --- a/doc/classes/AudioEffectFilter.xml +++ b/doc/classes/AudioEffectFilter.xml @@ -1,40 +1,49 @@ - Adds a filter to the audio bus. + Base class for filters. Use effects that inherit this class instead of using it directly. - Allows frequencies other than the [member cutoff_hz] to pass. + A "filter" controls the gain of frequencies, using [member cutoff_hz] as a frequency threshold. Filters can help to give room for each sound, and create interesting effects. + There are different types of filter that inherit this class: + Shelf filters: [AudioEffectLowShelfFilter] and [AudioEffectHighShelfFilter] + Band-pass and notch filters: [AudioEffectBandPassFilter], [AudioEffectBandLimitFilter], and [AudioEffectNotchFilter] + Low/high-pass filters: [AudioEffectLowPassFilter] and [AudioEffectHighPassFilter] $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html - Threshold frequency for the filter, in Hz. + Frequency threshold for the filter, in Hz. Value can range from 1 to 20500. - Steepness of the cutoff curve in dB per octave, also known as the order of the filter. Higher orders have a more aggressive cutoff. + Steepness of the cutoff curve in dB per octave (twice the frequency above [member cutoff_hz], or half the frequency below [member cutoff_hz]), also known as the "order" of the filter. Higher orders have a more aggressive cutoff. - Gain amount of the frequencies after the filter. + Gain of the frequencies affected by the filter. This property is only available for [AudioEffectLowShelfFilter] and [AudioEffectHighShelfFilter]. Value can range from 0 to 4. - Amount of boost in the frequency range near the cutoff frequency. + Gain at or directly next to the [member cutoff_hz] frequency threshold. Value can range from 0 to 1. + Its exact behavior depends on the selected filter type: + - For shelf filters, it accentuates or masks the order by increasing frequencies right next to the [member cutoff_hz] frequency and decreasing frequencies on the opposite side. + - For the band-pass and notch filters, it widens or narrows the filter at the [member cutoff_hz] frequency threshold. + - For low/high-pass filters, it increases or decreases frequencies at the [member cutoff_hz] frequency threshold. - Cutting off at 6dB per octave. + Cutting off at 6 dB per octave. One octave is twice the frequency above [member cutoff_hz], or half the frequency below [member cutoff_hz]. - Cutting off at 12dB per octave. + Cutting off at 12 dB per octave. One octave is twice the frequency above [member cutoff_hz], or half the frequency below [member cutoff_hz]. - Cutting off at 18dB per octave. + Cutting off at 18 dB per octave. One octave is twice the frequency above [member cutoff_hz], or half the frequency below [member cutoff_hz]. - Cutting off at 24dB per octave. + Cutting off at 24 dB per octave. One octave is twice the frequency above [member cutoff_hz], or half the frequency below [member cutoff_hz]. diff --git a/doc/classes/AudioEffectHardLimiter.xml b/doc/classes/AudioEffectHardLimiter.xml index 7616b91f97..eb8747dd0b 100644 --- a/doc/classes/AudioEffectHardLimiter.xml +++ b/doc/classes/AudioEffectHardLimiter.xml @@ -1,24 +1,27 @@ - Adds a hard limiter audio effect to an Audio bus. + Adds a limiter audio effect to an audio bus. + Prevents audio signals from exceeding a specified volume level. - A limiter is an effect designed to disallow sound from going over a given dB threshold. Hard limiters predict volume peaks, and will smoothly apply gain reduction when a peak crosses the ceiling threshold to prevent clipping and distortion. It preserves the waveform and prevents it from crossing the ceiling threshold. Adding one in the Master bus is recommended as a safety measure to prevent sudden volume peaks from occurring, and to prevent distortion caused by clipping. + A "limiter" disallows audio signals from exceeding a given volume threshold level in dB. Hard limiters predict volume peaks, and will smoothly apply gain reduction when a peak crosses the ceiling threshold level to prevent clipping. It preserves the waveform and prevents it from crossing the ceiling threshold level. Adding one in the Master bus is recommended as a safety measure to prevent sudden volume peaks from occurring, and to prevent distortion caused by clipping, when the volume exceeds 0 dB. + If clipping is desired, consider [constant AudioEffectDistortion.MODE_CLIP]. $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html - The waveform's maximum allowed value, in decibels. This value can range from [code]-24.0[/code] to [code]0.0[/code]. - The default value of [code]-0.3[/code] prevents potential inter-sample peaks (ISP) from crossing over 0 dB, which can cause slight distortion on some older hardware. + The waveform's maximum allowed value, in dB. This value can range from -24 to 0. + The default value of -0.3 prevents potential inter-sample peaks (ISP) from crossing over 0 dB, which can cause slight distortion on some older hardware. - Gain to apply before limiting, in decibels. + Gain before limiting, in dB. Value can range from -24 to 24. - Time it takes in seconds for the gain reduction to fully release. + Time it takes in seconds for the gain reduction to fully release. Value can range from 0.01 to 3. diff --git a/doc/classes/AudioEffectHighPassFilter.xml b/doc/classes/AudioEffectHighPassFilter.xml index 285b4c74a3..8eb98335d8 100644 --- a/doc/classes/AudioEffectHighPassFilter.xml +++ b/doc/classes/AudioEffectHighPassFilter.xml @@ -1,12 +1,14 @@ - Adds a high-pass filter to the audio bus. + Adds a high-pass filter to an audio bus. - Cuts frequencies lower than the [member AudioEffectFilter.cutoff_hz] and allows higher frequencies to pass. + A "high-pass" filter attenuates frequencies lower than [member AudioEffectFilter.cutoff_hz] and allows higher frequencies to pass unchanged. + This filter can be used to remove "strength" from a sound, and give low-end space for basses and impact sounds. $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html diff --git a/doc/classes/AudioEffectHighShelfFilter.xml b/doc/classes/AudioEffectHighShelfFilter.xml index 4645bf953c..6dd71e8ea9 100644 --- a/doc/classes/AudioEffectHighShelfFilter.xml +++ b/doc/classes/AudioEffectHighShelfFilter.xml @@ -1,12 +1,14 @@ - Adds a high-shelf filter to the audio bus. + Adds a high-shelf filter to an audio bus. - Reduces all frequencies above the [member AudioEffectFilter.cutoff_hz]. + A "high-shelf" filter controls the gain of all frequencies above [member AudioEffectFilter.cutoff_hz]. + This filter can be used to increase or decrease clarity of a sound. $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html diff --git a/doc/classes/AudioEffectInstance.xml b/doc/classes/AudioEffectInstance.xml index 058a4510ae..8f2a1c8913 100644 --- a/doc/classes/AudioEffectInstance.xml +++ b/doc/classes/AudioEffectInstance.xml @@ -8,6 +8,7 @@ $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html diff --git a/doc/classes/AudioEffectLimiter.xml b/doc/classes/AudioEffectLimiter.xml index b1a80cd9ef..ebe4995b14 100644 --- a/doc/classes/AudioEffectLimiter.xml +++ b/doc/classes/AudioEffectLimiter.xml @@ -1,26 +1,29 @@ - Adds a soft-clip limiter audio effect to an Audio bus. + Adds a soft-clip limiter audio effect to an audio bus. - A limiter is similar to a compressor, but it's less flexible and designed to disallow sound going over a given dB threshold. Adding one in the Master bus is always recommended to reduce the effects of clipping. - Soft clipping starts to reduce the peaks a little below the threshold level and progressively increases its effect as the input level increases such that the threshold is never exceeded. + A "limiter" is an audio effect designed to stop audio signals from exceeding a specified volume threshold level, and usually works by decreasing the volume or soft-clipping the audio. Adding one in the Master bus is always recommended to prevent clipping when the volume goes above 0 dB. + Soft clipping starts to decrease the peaks a little below the volume threshold level and progressively increases its effect as the input volume increases such that the threshold level is never exceeded. + If hard clipping is desired, consider [constant AudioEffectDistortion.MODE_CLIP]. $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html - The waveform's maximum allowed value, in decibels. Value can range from -20 to -0.1. + The waveform's maximum allowed value, in dB. Value can range from -20 to -0.1. - Applies a gain to the limited waves, in decibels. Value can range from 0 to 6. + Modifies the volume of the limited waves, in dB. Value can range from 0 to 6. + This property has no effect on the audio. Use [AudioEffectHardLimiter] instead, as this Limiter effect is deprecated. - Threshold from which the limiter begins to be active, in decibels. Value can range from -30 to 0. + The volume threshold level from which the limiter begins to be active, in dB. Value can range from -30 to 0. diff --git a/doc/classes/AudioEffectLowPassFilter.xml b/doc/classes/AudioEffectLowPassFilter.xml index eab5a04c15..f59e15ab90 100644 --- a/doc/classes/AudioEffectLowPassFilter.xml +++ b/doc/classes/AudioEffectLowPassFilter.xml @@ -1,12 +1,14 @@ - Adds a low-pass filter to the audio bus. + Adds a low-pass filter to an audio bus. - Cuts frequencies higher than the [member AudioEffectFilter.cutoff_hz] and allows lower frequencies to pass. + A "low-pass" filter attenuates frequencies higher than [member AudioEffectFilter.cutoff_hz] and allows lower frequencies to pass unchanged. + This filter can be used to muffle sounds. $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html diff --git a/doc/classes/AudioEffectLowShelfFilter.xml b/doc/classes/AudioEffectLowShelfFilter.xml index 1afc9ce310..de026b5036 100644 --- a/doc/classes/AudioEffectLowShelfFilter.xml +++ b/doc/classes/AudioEffectLowShelfFilter.xml @@ -1,12 +1,14 @@ - Adds a low-shelf filter to the audio bus. + Adds a low-shelf filter to an audio bus. - Reduces all frequencies below the [member AudioEffectFilter.cutoff_hz]. + A "low-shelf" filter controls the gain of all frequencies below [member AudioEffectFilter.cutoff_hz]. + This filter can be used to adjust the "strength" of a sound, by increasing or decreasing its low-end. $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html diff --git a/doc/classes/AudioEffectNotchFilter.xml b/doc/classes/AudioEffectNotchFilter.xml index de8edb34f2..d8980e358c 100644 --- a/doc/classes/AudioEffectNotchFilter.xml +++ b/doc/classes/AudioEffectNotchFilter.xml @@ -1,12 +1,14 @@ - Adds a notch filter to the Audio bus. + Adds a notch filter to an audio bus. - Attenuates frequencies in a narrow band around the [member AudioEffectFilter.cutoff_hz] and cuts frequencies outside of this range. + A "notch" filter attenuates frequencies at [member AudioEffectFilter.cutoff_hz] and allows frequencies outside the frequency threshold to pass unchanged. It is a narrower and stronger version of [AudioEffectBandLimitFilter], and is the opposite of [AudioEffectBandPassFilter]. + This filter can be used to give more room for other sounds to play at that frequency. Because of how much it attenuates frequencies, it can also be used to completely remove undesired frequencies. $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html diff --git a/doc/classes/AudioEffectPanner.xml b/doc/classes/AudioEffectPanner.xml index 22286dbfb1..3502e2711b 100644 --- a/doc/classes/AudioEffectPanner.xml +++ b/doc/classes/AudioEffectPanner.xml @@ -1,17 +1,20 @@ - Adds a panner audio effect to an audio bus. Pans sound left or right. + Adds a panner audio effect to an audio bus. + Pans the sound left or right. - Determines how much of an audio signal is sent to the left and right buses. + Determines how much of the audio signal is sent to the left and right channels. This helps with audio spatialization, giving sounds distinct places in a mix. + [AudioStreamPlayer2D] and [AudioStreamPlayer3D] handle panning automatically, following where the source of the sound is on the screen. $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html - Pan position. Value can range from -1 (fully left) to 1 (fully right). + Pan position. Negative values pan the sound to the left, positive pan to the right. Value can range from -1 to 1. diff --git a/doc/classes/AudioEffectPhaser.xml b/doc/classes/AudioEffectPhaser.xml index 6e845ff3fc..0f50bf5034 100644 --- a/doc/classes/AudioEffectPhaser.xml +++ b/doc/classes/AudioEffectPhaser.xml @@ -2,29 +2,31 @@ Adds a phaser audio effect to an audio bus. - Combines the original signal with a copy that is slightly out of phase with the original. + Creates several notch and peak filters that sweep across the spectrum. - Combines phase-shifted signals with the original signal. The movement of the phase-shifted signals is controlled using a low-frequency oscillator. + A "phaser" effect creates a copy of the original audio that phase-rotates differently across the entire frequency spectrum, with the use of a series of all-pass filter stages (6 in this effect). This copy modulates with a low-frequency oscillator and combines with the original audio, resulting in peaks and troughs that sweep across the spectrum. + This effect can be used to create a "glassy" or "bubbly" sound. $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html - Determines how high the filter frequencies sweep. Low value will primarily affect bass frequencies. High value can sweep high into the treble. Value can range from [code]0.1[/code] to [code]4.0[/code]. + Intensity of the effect. Value can range from 0.1 to 4.0. - Output percent of modified sound. Value can range from 0.1 to 0.9. + The volume ratio of the filtered audio that is fed back to the all-pass filters. The higher the value, the sharper and louder the peak filters created by the effect. Value can range from 0.1 to 0.9. - Determines the maximum frequency affected by the LFO modulations, in Hz. Value can range from 10 to 10000. + Determines the maximum frequency affected by the low-frequency oscillator modulations, in Hz. Value can range from 10 to 10000. - Determines the minimum frequency affected by the LFO modulations, in Hz. Value can range from 10 to 10000. + Determines the minimum frequency affected by the low-frequency oscillator modulations, in Hz. Value can range from 10 to 10000. - Adjusts the rate in Hz at which the effect sweeps up and down across the frequency range. + Adjusts the rate in Hz at which the effect sweeps up and down across the frequency range. Value can range from 0.01 to 20. diff --git a/doc/classes/AudioEffectPitchShift.xml b/doc/classes/AudioEffectPitchShift.xml index 4d4baa34ab..0c97214d90 100644 --- a/doc/classes/AudioEffectPitchShift.xml +++ b/doc/classes/AudioEffectPitchShift.xml @@ -2,23 +2,24 @@ Adds a pitch-shifting audio effect to an audio bus. - Raises or lowers the pitch of original sound. + Raises or lowers the pitch of the input audio. - Allows modulation of pitch independently of tempo. All frequencies can be increased/decreased with minimal effect on transients. + Allows modulation of pitch without modifying speed. All frequencies can be raised or lowered with minimal effect on transients. $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html - The size of the [url=https://en.wikipedia.org/wiki/Fast_Fourier_transform]Fast Fourier transform[/url] buffer. Higher values smooth out the effect over time, but have greater latency. The effects of this higher latency are especially noticeable on sounds that have sudden amplitude changes. + The size of the [url=https://en.wikipedia.org/wiki/Fast_Fourier_transform]Fast Fourier transform[/url] buffer. Higher values smooth out the effect over time, but have greater latency. The effects of this higher latency are especially noticeable on audio signals that have sudden amplitude changes. The oversampling factor to use. Higher values result in better quality, but are more demanding on the CPU and may cause audio cracking if the CPU can't keep up. - The pitch scale to use. [code]1.0[/code] is the default pitch and plays sounds unaffected. [member pitch_scale] can range from [code]0.0[/code] (infinitely low pitch, inaudible) to [code]16[/code] (16 times higher than the initial pitch). + The pitch scale to use. [code]1.0[/code] is the default pitch and plays sounds unaffected. [member pitch_scale] can range from 0 (infinitely low pitch, inaudible) to 16 (16 times higher than the initial pitch). diff --git a/doc/classes/AudioEffectRecord.xml b/doc/classes/AudioEffectRecord.xml index 6db9fac25e..8a02444fec 100644 --- a/doc/classes/AudioEffectRecord.xml +++ b/doc/classes/AudioEffectRecord.xml @@ -4,7 +4,7 @@ Audio effect used for recording the sound from an audio bus. - Allows the user to record the sound from an audio bus into an [AudioStreamWAV]. When used on the "Master" audio bus, this includes all audio output by Godot. + Allows the user to record the sound from an audio bus into an [AudioStreamWAV]. When used on the Master audio bus, this includes all audio output by Godot. Unlike [AudioEffectCapture], this effect encodes the recording with the given format (8-bit, 16-bit, or compressed) instead of giving access to the raw audio samples. Can be used (with an [AudioStreamMicrophone]) to record from a microphone. [b]Note:[/b] [member ProjectSettings.audio/driver/enable_input] must be [code]true[/code] for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings. diff --git a/doc/classes/AudioEffectReverb.xml b/doc/classes/AudioEffectReverb.xml index 4ac9672a8f..80f63d435c 100644 --- a/doc/classes/AudioEffectReverb.xml +++ b/doc/classes/AudioEffectReverb.xml @@ -1,39 +1,42 @@ - Adds a reverberation audio effect to an Audio bus. + Adds a reverberation audio effect to an audio bus. + Emulates an echo by playing a blurred version of the input audio. - Simulates the sound of acoustic environments such as rooms, concert halls, caverns, or an open spaces. + A "reverb" effect plays the input audio back continuously, decaying over a period of time. It simulates sounds in different kinds of spaces, ranging from small rooms, to big caverns. + See also [AudioEffectDelay] for a non-blurry type of echo. $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html https://godotengine.org/asset-library/asset/2710 - Defines how reflective the imaginary room's walls are. Value can range from 0 to 1. + Defines how reflective the imaginary room's walls are. The more reflective, the more high frequency content the reverb has. Value can range from 0 to 1. - Output percent of original sound. At 0, only modified sound is outputted. Value can range from 0 to 1. + The volume ratio of the original audio. At 0, only the modified audio is outputted. Value can range from 0 to 1. - High-pass filter passes signals with a frequency higher than a certain cutoff frequency and attenuates signals with frequencies lower than the cutoff frequency. Value can range from 0 to 1. + High-pass filter allows frequencies higher than a certain cutoff threshold and attenuates frequencies lower than the cutoff threshold. Value can range from 0 to 1. - Output percent of predelay. Value can range from 0 to 1. + Gain of early reflection copies. At higher values, early reflection copies are louder and ring out for longer. Value can range from 0 to 1. - Time between the original signal and the early reflections of the reverb signal, in milliseconds. + Time between the original audio and the early reflections of the reverb signal, in milliseconds. Value can range from 20 to 500. Dimensions of simulated room. Bigger means more echoes. Value can range from 0 to 1. - Widens or narrows the stereo image of the reverb tail. 1 means fully widens. Value can range from 0 to 1. + Widens or narrows the stereo image of the reverb tail. At 1, it fully widens. Value can range from 0 to 1. - Output percent of modified sound. At 0, only original sound is outputted. Value can range from 0 to 1. + The volume ratio of the modified audio. At 0, only the original audio is outputted. Value can range from 0 to 1. diff --git a/doc/classes/AudioEffectSpectrumAnalyzer.xml b/doc/classes/AudioEffectSpectrumAnalyzer.xml index 3122c1a18e..07f8eb2562 100644 --- a/doc/classes/AudioEffectSpectrumAnalyzer.xml +++ b/doc/classes/AudioEffectSpectrumAnalyzer.xml @@ -1,19 +1,20 @@ - Audio effect that can be used for real-time audio visualizations. + Creates an [AudioEffectInstance] which performs frequency analysis and exposes results to be accessed in real-time. - This audio effect does not affect sound output, but can be used for real-time audio visualizations. - This resource configures an [AudioEffectSpectrumAnalyzerInstance], which performs the actual analysis at runtime. An instance can be obtained with [method AudioServer.get_bus_effect_instance]. - See also [AudioStreamGenerator] for procedurally generating sounds. + Calculates a Fourier Transform of the audio signal. This effect does not alter the audio. Can be used for creating real-time audio visualizations, like a spectrogram. + This resource configures an [AudioEffectSpectrumAnalyzerInstance], which performs the actual analysis at runtime. An instance should be obtained with [method AudioServer.get_bus_effect_instance] to make use of this effect. + $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html https://godotengine.org/asset-library/asset/2762 - The length of the buffer to keep (in seconds). Higher values keep data around for longer, but require more memory. + The length of the buffer to keep, in seconds. Higher values keep data around for longer, but require more memory. Value can range from 0.1 to 4. The size of the [url=https://en.wikipedia.org/wiki/Fast_Fourier_transform]Fast Fourier transform[/url] buffer. Higher values smooth out the spectrum analysis over time, but have greater latency. The effects of this higher latency are especially noticeable with sudden amplitude changes. diff --git a/doc/classes/AudioEffectSpectrumAnalyzerInstance.xml b/doc/classes/AudioEffectSpectrumAnalyzerInstance.xml index ab9106f53d..a0fe6f2634 100644 --- a/doc/classes/AudioEffectSpectrumAnalyzerInstance.xml +++ b/doc/classes/AudioEffectSpectrumAnalyzerInstance.xml @@ -8,6 +8,8 @@ An instance of this class can be obtained with [method AudioServer.get_bus_effect_instance]. + $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html https://godotengine.org/asset-library/asset/2762 diff --git a/doc/classes/AudioEffectStereoEnhance.xml b/doc/classes/AudioEffectStereoEnhance.xml index 459ae3ebc6..00d4621ed3 100644 --- a/doc/classes/AudioEffectStereoEnhance.xml +++ b/doc/classes/AudioEffectStereoEnhance.xml @@ -1,23 +1,25 @@ - An audio effect that can be used to adjust the intensity of stereo panning. + Adds a stereo manipulation audio effect to an audio bus. + Controls gain of the side channels, and widens the stereo image. - An audio effect that can be used to adjust the intensity of stereo panning. + Adjusts gain of the left and right channels, and makes mono sounds stereo through phase shifting. $DOCS_URL/tutorials/audio/audio_buses.html + $DOCS_URL/tutorials/audio/audio_effects.html - Amplifies the difference between stereo channels, increasing or decreasing existing panning. A value of 0.0 will downmix stereo to mono. Does not affect a mono signal. + Gain of the side channels, if they exist. A value of 0 will downmix stereo to mono. Value can range from 0 to 4. - Widens sound stage through phase shifting in conjunction with [member time_pullout_ms]. Just pans sound to the left channel if [member time_pullout_ms] is 0. + Widens the stereo image through phase shifting in conjunction with [member time_pullout_ms]. Just pans sound to the left channel if [member time_pullout_ms] is 0. Value can range from 0 to 1. - Widens sound stage through phase shifting in conjunction with [member surround]. Just delays the right channel if [member surround] is 0. + Widens the stereo image through phase shifting in conjunction with [member surround]. Just delays the right channel if [member surround] is 0. Value is in milliseconds, and can range from 0 to 50.