Description

Plays audio that is attenuated with distance to the listener.

By default, audio is heard from the screen center. This can be changed by adding anAudioListener2D node to the scene and enabling it by callingAudioListener2D.make_current() on it.

See alsoAudioStreamPlayer to play a sound non-positionally.

Note: Hiding anAudioStreamPlayer2D node does not disable its audio output. To temporarily disable anAudioStreamPlayer2D's audio output, setvolume_db to a very low value like-100 (which isn't audible to human hearing).

Tutorials

• Audio streams

Properties

Methods

Signals

finished()🔗

Emitted when the audio stops playing.

Property Descriptions

intarea_mask =1🔗

• voidset_area_mask(value:int)

• intget_area_mask()

Determines whichArea2D layers affect the sound for reverb and audio bus effects. Areas can be used to redirectAudioStreams so that they play in a certain audio bus. An example of how you might use this is making a "water" area so that sounds played in the water are redirected through an audio bus to make them sound like they are being played underwater.

floatattenuation =1.0🔗

• voidset_attenuation(value:float)

• floatget_attenuation()

The volume is attenuated over distance with this as an exponent.

boolautoplay =false🔗

• voidset_autoplay(value:bool)

• boolis_autoplay_enabled()

Iftrue, audio plays when added to scene tree.

StringNamebus =&"Master"🔗

• voidset_bus(value:StringName)

• StringNameget_bus()

Bus on which this audio is playing.

Note: When setting this property, keep in mind that no validation is performed to see if the given name matches an existing bus. This is because audio bus layouts might be loaded after this property is set. If this given name can't be resolved at runtime, it will fall back to"Master".

floatmax_distance =2000.0🔗

• voidset_max_distance(value:float)

• floatget_max_distance()

Maximum distance from which audio is still hearable.

intmax_polyphony =1🔗

• voidset_max_polyphony(value:int)

• intget_max_polyphony()

The maximum number of sounds this node can play at the same time. Playing additional sounds after this value is reached will cut off the oldest sounds.

floatpanning_strength =1.0🔗

• voidset_panning_strength(value:float)

• floatget_panning_strength()

Scales the panning strength for this node by multiplying the baseProjectSettings.audio/general/2d_panning_strength with this factor. Higher values will pan audio from left to right more dramatically than lower values.

floatpitch_scale =1.0🔗

• voidset_pitch_scale(value:float)

• floatget_pitch_scale()

The pitch and the tempo of the audio, as a multiplier of the audio sample's sample rate.

PlaybackTypeplayback_type =0🔗

• voidset_playback_type(value:PlaybackType)

• PlaybackTypeget_playback_type()

Experimental: This property may be changed or removed in future versions.

The playback type of the stream player. If set other than to the default value, it will force that playback type.

boolplaying =false🔗

• voidset_playing(value:bool)

• boolis_playing()

Iftrue, audio is playing or is queued to be played (seeplay()).

AudioStreamstream🔗

• voidset_stream(value:AudioStream)

• AudioStreamget_stream()

TheAudioStream object to be played.

boolstream_paused =false🔗

• voidset_stream_paused(value:bool)

• boolget_stream_paused()

Iftrue, the playback is paused. You can resume it by settingstream_paused tofalse.

floatvolume_db =0.0🔗

• voidset_volume_db(value:float)

• floatget_volume_db()

Base volume before attenuation, in decibels.

floatvolume_linear🔗

• voidset_volume_linear(value:float)

• floatget_volume_linear()

Base volume before attenuation, as a linear value.

Note: This member modifiesvolume_db for convenience. The returned value is equivalent to the result of@GlobalScope.db_to_linear() onvolume_db. Setting this member is equivalent to settingvolume_db to the result of@GlobalScope.linear_to_db() on a value.

Method Descriptions

floatget_playback_position()🔗

Returns the position in theAudioStream.

AudioStreamPlaybackget_stream_playback()🔗

Returns theAudioStreamPlayback object associated with thisAudioStreamPlayer2D.

boolhas_stream_playback()🔗

Returns whether theAudioStreamPlayer can return theAudioStreamPlayback object or not.

voidplay(from_position:float = 0.0)🔗

Queues the audio to play on the next physics frame, from the given positionfrom_position, in seconds.

voidseek(to_position:float)🔗

Sets the position from which audio will be played, in seconds.

voidstop()🔗

Stops the audio.