Table of Contents

Class AudioStreamPlayer3D

Plays positional sound in 3D space.

Inheritance
AudioStreamPlayer3D

Remarks

Plays audio with positional sound effects, based on the relative position of the audio listener. Positional effects include distance attenuation, directionality, and the Doppler effect. For greater realism, a low-pass filter is applied to distant sounds. This can be disabled by setting attenuation_filter_cutoff_hz to 20500.

By default, audio is heard from the camera position. This can be changed by adding an AudioListener3D node to the scene and enabling it by calling make_current on it.

See also AudioStreamPlayer to play a sound non-positionally.

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

See Also

Audio streams

Properties

area_mask

Determines which Area3D layers affect the sound for reverb and audio bus effects. Areas can be used to redirect AudioStreams 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.

var area_mask : int = 1

Property Value

int

Remarks

  • void set_area_mask(int value)
  • int get_area_mask

attenuation_filter_cutoff_hz

The cutoff frequency of the attenuation low-pass filter, in Hz. A sound above this frequency is attenuated more than a sound below this frequency. To disable this effect, set this to 20500 as this frequency is above the human hearing limit.

var attenuation_filter_cutoff_hz : float = 5000.0

Property Value

float

Remarks

  • void set_attenuation_filter_cutoff_hz(float value)
  • float get_attenuation_filter_cutoff_hz

attenuation_filter_db

Amount how much the filter affects the loudness, in decibels.

var attenuation_filter_db : float = -24.0

Property Value

float

Remarks

  • void set_attenuation_filter_db(float value)
  • float get_attenuation_filter_db

attenuation_model

Decides if audio should get quieter with distance linearly, quadratically, logarithmically, or not be affected by distance, effectively disabling attenuation.

var attenuation_model : int = 0

Property Value

int

Remarks

  • void set_attenuation_model(int value)
  • int get_attenuation_model

autoplay

If true, audio plays when the AudioStreamPlayer3D node is added to scene tree.

var autoplay : bool = false

Property Value

bool

Remarks

  • void set_autoplay(bool value)
  • bool is_autoplay_enabled

bus

The 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".

var bus : StringName = &"Master"

Property Value

StringName

Remarks

doppler_tracking

Decides in which step the Doppler effect should be calculated.

var doppler_tracking : int = 0

Property Value

int

Remarks

  • void set_doppler_tracking(int value)
  • int get_doppler_tracking

emission_angle_degrees

The angle in which the audio reaches a listener unattenuated.

var emission_angle_degrees : float = 45.0

Property Value

float

Remarks

  • void set_emission_angle(float value)
  • float get_emission_angle

emission_angle_enabled

If true, the audio should be attenuated according to the direction of the sound.

var emission_angle_enabled : bool = false

Property Value

bool

Remarks

  • void set_emission_angle_enabled(bool value)
  • bool is_emission_angle_enabled

emission_angle_filter_attenuation_db

Attenuation factor used if listener is outside of emission_angle_degrees and emission_angle_enabled is set, in decibels.

var emission_angle_filter_attenuation_db : float = -12.0

Property Value

float

Remarks

  • void set_emission_angle_filter_attenuation_db(float value)
  • float get_emission_angle_filter_attenuation_db

max_db

Sets the absolute maximum of the sound level, in decibels.

var max_db : float = 3.0

Property Value

float

Remarks

max_distance

The distance past which the sound can no longer be heard at all. Only has an effect if set to a value greater than 0.0. max_distance works in tandem with unit_size. However, unlike unit_size whose behavior depends on the attenuation_model, max_distance always works in a linear fashion. This can be used to prevent the AudioStreamPlayer3D from requiring audio mixing when the listener is far away, which saves CPU resources.

var max_distance : float = 0.0

Property Value

float

Remarks

  • void set_max_distance(float value)
  • float get_max_distance

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.

var max_polyphony : int = 1

Property Value

int

Remarks

  • void set_max_polyphony(int value)
  • int get_max_polyphony

panning_strength

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

var panning_strength : float = 1.0

Property Value

float

Remarks

  • void set_panning_strength(float value)
  • float get_panning_strength

pitch_scale

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

var pitch_scale : float = 1.0

Property Value

float

Remarks

  • void set_pitch_scale(float value)
  • float get_pitch_scale

playback_type

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

var playback_type : int = 0

Property Value

int

Remarks

  • void set_playback_type(int value)
  • int get_playback_type

playing

If true, audio is playing or is queued to be played (see AudioStreamPlayer3D.play).

var playing : bool = false

Property Value

bool

Remarks

  • void set_playing(bool value)
  • bool is_playing

stream

The AudioStream resource to be played.

var stream : AudioStream

Property Value

AudioStream

Remarks

stream_paused

If true, the playback is paused. You can resume it by setting stream_paused to false.

var stream_paused : bool = false

Property Value

bool

Remarks

  • void set_stream_paused(bool value)
  • bool get_stream_paused

unit_size

The factor for the attenuation effect. Higher values make the sound audible over a larger distance.

var unit_size : float = 10.0

Property Value

float

Remarks

  • void set_unit_size(float value)
  • float get_unit_size

volume_db

The base sound level before attenuation, in decibels.

var volume_db : float = 0.0

Property Value

float

Remarks

  • void set_volume_db(float value)
  • float get_volume_db

volume_linear

The base sound level before attenuation, as a linear value.

Note: This member modifies volume_db for convenience. The returned value is equivalent to the result of @GlobalScope.db_to_linear on volume_db. Setting this member is equivalent to setting volume_db to the result of @GlobalScope.linear_to_db on a value.

var volume_linear : float

Property Value

float

Remarks

  • void set_volume_linear(float value)
  • float get_volume_linear

Methods

get_playback_position

Returns the position in the AudioStream.

float get_playback_position

get_stream_playback

Returns the AudioStreamPlayback object associated with this AudioStreamPlayer3D.

AudioStreamPlayback get_stream_playback

has_stream_playback

Returns whether the AudioStreamPlayer can return the AudioStreamPlayback object or not.

bool has_stream_playback

play(float)

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

void play(float from_position)

Parameters

from_position float

seek(float)

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

void seek(float to_position)

Parameters

to_position float

stop

Stops the audio.

void stop

Events

finished

Emitted when the audio stops playing.

signal finished