Table of Contents

Class AudioStreamPlayer

A node for audio playback.

Inheritance
AudioStreamPlayer

Remarks

The AudioStreamPlayer node plays an audio stream non-positionally. It is ideal for user interfaces, menus, or background music.

To use this node, stream needs to be set to a valid AudioStream resource. Playing more than one sound at the same time is also supported, see max_polyphony.

If you need to play audio at a specific position, use AudioStreamPlayer2D or AudioStreamPlayer3D instead.

See Also

Audio streams
2D Dodge The Creeps Demo
Audio Device Changer Demo
Audio Generator Demo
Audio Microphone Record Demo
Audio Spectrum Visualizer Demo

Properties

autoplay

If true, this node calls AudioStreamPlayer.play when entering the tree.

var autoplay : bool = false

Property Value

bool

Remarks

  • void set_autoplay(bool value)
  • bool is_autoplay_enabled

bus

The target bus name. All sounds from this node will be playing on this bus.

Note: At runtime, if no bus with the given name exists, all sounds will fall back on "Master". See also AudioServer.get_bus_name.

var bus : StringName = &"Master"

Property Value

StringName

Remarks

max_polyphony

The maximum number of sounds this node can play at the same time. Calling AudioStreamPlayer.play 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

mix_target

The mix target channels, as one of the MixTarget constants. Has no effect when two speakers or less are detected (see SpeakerMode).

var mix_target : int = 0

Property Value

int

Remarks

  • void set_mix_target(int value)
  • int get_mix_target

pitch_scale

The audio's pitch and tempo, as a multiplier of the stream's sample rate. A value of 2.0 doubles the audio's pitch, while a value of 0.5 halves the pitch.

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, this node is playing sounds. Setting this property has the same effect as AudioStreamPlayer.play and stop.

var playing : bool = false

Property Value

bool

Remarks

  • void set_playing(bool value)
  • bool is_playing

stream

The AudioStream resource to be played. Setting this property stops all currently playing sounds. If left empty, the AudioStreamPlayer does not work.

var stream : AudioStream

Property Value

AudioStream

Remarks

stream_paused

If true, the sounds are paused. Setting stream_paused to false resumes all sounds.

Note: This property is automatically changed when exiting or entering the tree, or this node is paused (see process_mode).

var stream_paused : bool = false

Property Value

bool

Remarks

  • void set_stream_paused(bool value)
  • bool get_stream_paused

volume_db

Volume of sound, in decibels. This is an offset of the stream's volume.

Note: To convert between decibel and linear energy (like most volume sliders do), use volume_linear, or @GlobalScope.db_to_linear and @GlobalScope.linear_to_db.

var volume_db : float = 0.0

Property Value

float

Remarks

  • void set_volume_db(float value)
  • float get_volume_db

volume_linear

Volume of sound, 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 of the latest sound, in seconds. Returns 0.0 if no sounds are playing.

Note: The position is not always accurate, as the AudioServer does not mix audio every processed frame. To get more accurate results, add get_time_since_last_mix to the returned position.

Note: This method always returns 0.0 if the stream is an AudioStreamInteractive, since it can have multiple clips playing at once.

float get_playback_position

get_stream_playback

Returns the latest AudioStreamPlayback of this node, usually the most recently created by AudioStreamPlayer.play. If no sounds are playing, this method fails and returns an empty playback.

AudioStreamPlayback get_stream_playback

has_stream_playback

Returns true if any sound is active, even if stream_paused is set to true. See also playing and get_stream_playback.

bool has_stream_playback

play(float)

Plays a sound from the beginning, or the given from_position in seconds.

void play(float from_position)

Parameters

from_position float

seek(float)

Restarts all sounds to be played from the given to_position, in seconds. Does nothing if no sounds are playing.

void seek(float to_position)

Parameters

to_position float

stop

Stops all sounds from this node.

void stop

Events

finished

Emitted when a sound finishes playing without interruptions. This signal is not emitted when calling stop, or when exiting the tree while sounds are playing.

signal finished