create AudioStreamWithEffects

RoyBerardo · RoyBerardo · commit 1f78e1139434 · 2025-11-15T02:37:04.000-08:00
diff --git a/doc/classes/AudioEffect.xml b/doc/classes/AudioEffect.xml
@@ -4,8 +4,8 @@
 		Base class for audio effect resources.
 	</brief_description>
 	<description>
-		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.
+		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 on buses through [method AudioServer.add_bus_effect], [method AudioServer.remove_bus_effect], and [method AudioServer.get_bus_effect]. Audio effects can also be added to an [AudioStreamWithEffects] to manipulate the sound of an individual audio stream.
+		When applied on a bus, an audio effect creates a corresponding [AudioEffectInstance]. When applied on an [AudioStreamWithEffects], an [AudioEffectInstance] is created for each stream effect when the stream begins playback. An [AudioEffectInstance] is directly responsible for manipulating the sound, based on the original audio effect's properties.
 	</description>
 	<tutorials>
 		<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
@@ -15,7 +15,7 @@
 		<method name="_instantiate" qualifiers="virtual required">
 			<return type="AudioEffectInstance" />
 			<description>
-				Override this method to customize the [AudioEffectInstance] created when this effect is applied on a bus in the editor's Audio panel, or through [method AudioServer.add_bus_effect].
+				Override this method to customize the [AudioEffectInstance] created when this effect is applied on a bus in the editor's Audio panel, through [method AudioServer.add_bus_effect], or when the [AudioStreamWithEffects] this effect is placed on instantiates an [AudioStreamPlaybackWithEffects].
 				[codeblock]
 				extends AudioEffect
 
diff --git a/doc/classes/AudioEffectAmplify.xml b/doc/classes/AudioEffectAmplify.xml
@@ -1,10 +1,10 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioEffectAmplify" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Adds an amplifying audio effect to an audio bus.
+		Adds an amplifying audio effect.
 	</brief_description>
 	<description>
-		Increases or decreases the volume being routed through the audio bus.
+		Increases or decreases the volume of the audio being routed through this effect.
 	</description>
 	<tutorials>
 		<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
diff --git a/doc/classes/AudioEffectBandLimitFilter.xml b/doc/classes/AudioEffectBandLimitFilter.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioEffectBandLimitFilter" inherits="AudioEffectFilter" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Adds a band limit filter to the audio bus.
+		Adds a band limit filter.
 	</brief_description>
 	<description>
 		Limits the frequencies in a range around the [member AudioEffectFilter.cutoff_hz] and allows frequencies outside of this range to pass.
diff --git a/doc/classes/AudioEffectBandPassFilter.xml b/doc/classes/AudioEffectBandPassFilter.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioEffectBandPassFilter" inherits="AudioEffectFilter" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Adds a band pass filter to the audio bus.
+		Adds a band pass filter.
 	</brief_description>
 	<description>
 		Attenuates the frequencies inside of a range around the [member AudioEffectFilter.cutoff_hz] and cuts frequencies outside of this band.
diff --git a/doc/classes/AudioEffectCapture.xml b/doc/classes/AudioEffectCapture.xml
@@ -1,10 +1,10 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioEffectCapture" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Captures audio from an audio bus in real-time.
+		Captures audio in real-time.
 	</brief_description>
 	<description>
-		AudioEffectCapture is an AudioEffect which copies all audio frames from the attached audio effect bus into its internal ring buffer.
+		AudioEffectCapture is an AudioEffect which copies all audio frames going into this effect into its internal ring buffer.
 		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].
 	</description>
diff --git a/doc/classes/AudioEffectCompressor.xml b/doc/classes/AudioEffectCompressor.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioEffectCompressor" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Adds a compressor audio effect to an audio bus.
+		Adds a compressor audio effect.
 		Reduces sounds that exceed a certain threshold level, smooths out the dynamics and increases the overall volume.
 	</brief_description>
 	<description>
diff --git a/doc/classes/AudioEffectDelay.xml b/doc/classes/AudioEffectDelay.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioEffectDelay" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Adds a delay audio effect to an audio bus. Plays input signal back after a period of time.
+		Adds a delay audio effect. Plays input signal back after a period of time.
 		Two tap delay and feedback options.
 	</brief_description>
 	<description>
diff --git a/doc/classes/AudioEffectDistortion.xml b/doc/classes/AudioEffectDistortion.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioEffectDistortion" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Adds a distortion audio effect to an Audio bus.
+		Adds a distortion audio effect.
 		Modifies the sound to make it distorted.
 	</brief_description>
 	<description>
diff --git a/doc/classes/AudioEffectEQ10.xml b/doc/classes/AudioEffectEQ10.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioEffectEQ10" inherits="AudioEffectEQ" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Adds a 10-band equalizer audio effect to an Audio bus. Gives you control over frequencies from 31 Hz to 16000 Hz.
+		Adds a 10-band equalizer audio effect. Gives you control over frequencies from 31 Hz to 16000 Hz.
 		Each frequency can be modulated between -60/+24 dB.
 	</brief_description>
 	<description>
diff --git a/doc/classes/AudioEffectEQ21.xml b/doc/classes/AudioEffectEQ21.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioEffectEQ21" inherits="AudioEffectEQ" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Adds a 21-band equalizer audio effect to an Audio bus. Gives you control over frequencies from 22 Hz to 22000 Hz.
+		Adds a 21-band equalizer audio effect. Gives you control over frequencies from 22 Hz to 22000 Hz.
 		Each frequency can be modulated between -60/+24 dB.
 	</brief_description>
 	<description>
diff --git a/doc/classes/AudioEffectEQ6.xml b/doc/classes/AudioEffectEQ6.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioEffectEQ6" inherits="AudioEffectEQ" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Adds a 6-band equalizer audio effect to an audio bus. Gives you control over frequencies from 32 Hz to 10000 Hz.
+		Adds a 6-band equalizer audio effect. Gives you control over frequencies from 32 Hz to 10000 Hz.
 		Each frequency can be modulated between -60/+24 dB.
 	</brief_description>
 	<description>
diff --git a/doc/classes/AudioEffectFilter.xml b/doc/classes/AudioEffectFilter.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioEffectFilter" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Adds a filter to the audio bus.
+		Adds a filter.
 	</brief_description>
 	<description>
 		Allows frequencies other than the [member cutoff_hz] to pass.
diff --git a/doc/classes/AudioEffectHardLimiter.xml b/doc/classes/AudioEffectHardLimiter.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioEffectHardLimiter" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Adds a hard limiter audio effect to an Audio bus.
+		Adds a hard limiter audio effect.
 	</brief_description>
 	<description>
 		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.
diff --git a/doc/classes/AudioEffectHighPassFilter.xml b/doc/classes/AudioEffectHighPassFilter.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioEffectHighPassFilter" inherits="AudioEffectFilter" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Adds a high-pass filter to the audio bus.
+		Adds a high-pass filter.
 	</brief_description>
 	<description>
 		Cuts frequencies lower than the [member AudioEffectFilter.cutoff_hz] and allows higher frequencies to pass.
diff --git a/doc/classes/AudioEffectHighShelfFilter.xml b/doc/classes/AudioEffectHighShelfFilter.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioEffectHighShelfFilter" inherits="AudioEffectFilter" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Adds a high-shelf filter to the audio bus.
+		Adds a high-shelf filter.
 	</brief_description>
 	<description>
 		Reduces all frequencies above the [member AudioEffectFilter.cutoff_hz].
diff --git a/doc/classes/AudioEffectInstance.xml b/doc/classes/AudioEffectInstance.xml
@@ -4,7 +4,7 @@
 		Manipulates the audio it receives for a given effect.
 	</brief_description>
 	<description>
-		An audio effect instance manipulates the audio it receives for a given effect. This instance is automatically created by an [AudioEffect] when it is added to a bus, and should usually not be created directly. If necessary, it can be fetched at run-time with [method AudioServer.get_bus_effect_instance].
+		An audio effect instance manipulates the audio it receives for a given effect. This instance is automatically created by an [AudioEffect] when it is added to a bus or added to an [AudioStreamWithEffects] with active playbacks, and should usually not be created directly. If necessary, bus effect instances can be fetched at run-time with [method AudioServer.get_bus_effect_instance].
 	</description>
 	<tutorials>
 		<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
diff --git a/doc/classes/AudioEffectLimiter.xml b/doc/classes/AudioEffectLimiter.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioEffectLimiter" inherits="AudioEffect" deprecated="Use [AudioEffectHardLimiter] instead." xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Adds a soft-clip limiter audio effect to an Audio bus.
+		Adds a soft-clip limiter audio effect.
 	</brief_description>
 	<description>
 		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.
diff --git a/doc/classes/AudioEffectLowPassFilter.xml b/doc/classes/AudioEffectLowPassFilter.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioEffectLowPassFilter" inherits="AudioEffectFilter" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Adds a low-pass filter to the audio bus.
+		Adds a low-pass filter.
 	</brief_description>
 	<description>
 		Cuts frequencies higher than the [member AudioEffectFilter.cutoff_hz] and allows lower frequencies to pass.
diff --git a/doc/classes/AudioEffectLowShelfFilter.xml b/doc/classes/AudioEffectLowShelfFilter.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioEffectLowShelfFilter" inherits="AudioEffectFilter" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Adds a low-shelf filter to the audio bus.
+		Adds a low-shelf filter.
 	</brief_description>
 	<description>
 		Reduces all frequencies below the [member AudioEffectFilter.cutoff_hz].
diff --git a/doc/classes/AudioEffectNotchFilter.xml b/doc/classes/AudioEffectNotchFilter.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioEffectNotchFilter" inherits="AudioEffectFilter" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Adds a notch filter to the Audio bus.
+		Adds a notch filter.
 	</brief_description>
 	<description>
 		Attenuates frequencies in a narrow band around the [member AudioEffectFilter.cutoff_hz] and cuts frequencies outside of this range.
diff --git a/doc/classes/AudioEffectPanner.xml b/doc/classes/AudioEffectPanner.xml
@@ -1,10 +1,10 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioEffectPanner" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Adds a panner audio effect to an audio bus. Pans sound left or right.
+		Adds a panner audio effect. Pans sound left or right.
 	</brief_description>
 	<description>
-		Determines how much of an audio signal is sent to the left and right buses.
+		Determines how much of an audio signal is sent to the left and right channels.
 	</description>
 	<tutorials>
 		<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
diff --git a/doc/classes/AudioEffectPhaser.xml b/doc/classes/AudioEffectPhaser.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioEffectPhaser" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Adds a phaser audio effect to an audio bus.
+		Adds a phaser audio effect.
 		Combines the original signal with a copy that is slightly out of phase with the original.
 	</brief_description>
 	<description>
diff --git a/doc/classes/AudioEffectPitchShift.xml b/doc/classes/AudioEffectPitchShift.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioEffectPitchShift" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Adds a pitch-shifting audio effect to an audio bus.
+		Adds a pitch-shifting audio effect.
 		Raises or lowers the pitch of original sound.
 	</brief_description>
 	<description>
diff --git a/doc/classes/AudioEffectRecord.xml b/doc/classes/AudioEffectRecord.xml
@@ -1,10 +1,10 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioEffectRecord" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Audio effect used for recording the sound from an audio bus.
+		Audio effect used for recording the audio that passes through it.
 	</brief_description>
 	<description>
-		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 passing through the effect 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
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8" ?>
 <class name="AudioEffectReverb" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
 	<brief_description>
-		Adds a reverberation audio effect to an Audio bus.
+		Adds a reverberation audio effect.
 	</brief_description>
 	<description>
 		Simulates the sound of acoustic environments such as rooms, concert halls, caverns, or an open spaces.
diff --git a/doc/classes/AudioEffectSpectrumAnalyzer.xml b/doc/classes/AudioEffectSpectrumAnalyzer.xml
@@ -5,7 +5,7 @@
 	</brief_description>
 	<description>
 		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].
+		This resource configures an [AudioEffectSpectrumAnalyzerInstance], which performs the actual analysis at runtime. When added to a bus, an instance can be obtained with [method AudioServer.get_bus_effect_instance].
 		See also [AudioStreamGenerator] for procedurally generating sounds.
 	</description>
 	<tutorials>
diff --git a/doc/classes/AudioEffectSpectrumAnalyzerInstance.xml b/doc/classes/AudioEffectSpectrumAnalyzerInstance.xml
@@ -5,7 +5,7 @@
 	</brief_description>
 	<description>
 		The runtime part of an [AudioEffectSpectrumAnalyzer], which can be used to query the magnitude of a frequency range on its host bus.
-		An instance of this class can be obtained with [method AudioServer.get_bus_effect_instance].
+		A bus instance of this class can be obtained with [method AudioServer.get_bus_effect_instance].
 	</description>
 	<tutorials>
 		<link title="Audio Spectrum Visualizer Demo">https://godotengine.org/asset-library/asset/2762</link>
diff --git a/doc/classes/AudioStreamPlaybackWithEffects.xml b/doc/classes/AudioStreamPlaybackWithEffects.xml
@@ -0,0 +1,27 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<class name="AudioStreamPlaybackWithEffects" inherits="AudioStreamPlayback" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
+	<brief_description>
+		Playback instance of [AudioStreamWithEffects].
+	</brief_description>
+	<description>
+		Playback instance created when [AudioStreamWithEffects] instantiates playback.
+	</description>
+	<tutorials>
+	</tutorials>
+	<methods>
+		<method name="get_effect_instance">
+			<return type="AudioEffectInstance" />
+			<param index="0" name="index" type="int" />
+			<description>
+				Returns the [AudioEffectInstance] created from the [AudioEffect] at the specified index on the instantiating [AudioStreamWithEffects] effect list. Negative values access indices from the end.
+			</description>
+		</method>
+		<method name="get_effect_instance_count">
+			<return type="AudioEffectInstance" />
+			<param index="0" name="index" type="int" />
+			<description>
+				Returns the number of [AudioEffectInstance]s in this playback. Will return the same value as [member AudioStreamWithEffects.effect_count] on the instantiating [AudioStreamWithEffects] effects list.
+			</description>
+		</method>
+	</methods>
+</class>
diff --git a/doc/classes/AudioStreamWithEffects.xml b/doc/classes/AudioStreamWithEffects.xml
diff --git a/editor/icons/AudioStreamWithEffects.svg b/editor/icons/AudioStreamWithEffects.svg
diff --git a/scene/register_scene_types.cpp b/scene/register_scene_types.cpp
diff --git a/scene/resources/audio_stream_with_effects.cpp b/scene/resources/audio_stream_with_effects.cpp
diff --git a/scene/resources/audio_stream_with_effects.h b/scene/resources/audio_stream_with_effects.h
