godot-docs/classes/class_audiostreamplayer.rst

:github_url: hide

.. DO NOT EDIT THIS FILE!!!
.. Generated automatically from Godot engine sources.
.. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py.
.. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/AudioStreamPlayer.xml.

.. _class_AudioStreamPlayer:

AudioStreamPlayer
=================

**Inherits:** :ref:`Node<class_Node>` **<** :ref:`Object<class_Object>`

Plays back audio non-positionally.

.. rst-class:: classref-introduction-group

Description
-----------

Plays an audio stream non-positionally.

To play audio positionally, use :ref:`AudioStreamPlayer2D<class_AudioStreamPlayer2D>` or :ref:`AudioStreamPlayer3D<class_AudioStreamPlayer3D>` instead of **AudioStreamPlayer**.

.. rst-class:: classref-introduction-group

Tutorials
---------

- :doc:`Audio streams <../tutorials/audio/audio_streams>`

- `2D Dodge The Creeps Demo <https://godotengine.org/asset-library/asset/515>`__

- `Audio Device Changer Demo <https://godotengine.org/asset-library/asset/525>`__

- `Audio Generator Demo <https://godotengine.org/asset-library/asset/526>`__

- `Audio Mic Record Demo <https://godotengine.org/asset-library/asset/527>`__

- `Audio Spectrum Demo <https://godotengine.org/asset-library/asset/528>`__

.. rst-class:: classref-reftable-group

Properties
----------

.. table::
   :widths: auto

   +----------------------------------------------------+----------------------------------------------------------------------+---------------+
   | :ref:`bool<class_bool>`                            | :ref:`autoplay<class_AudioStreamPlayer_property_autoplay>`           | ``false``     |
   +----------------------------------------------------+----------------------------------------------------------------------+---------------+
   | :ref:`StringName<class_StringName>`                | :ref:`bus<class_AudioStreamPlayer_property_bus>`                     | ``&"Master"`` |
   +----------------------------------------------------+----------------------------------------------------------------------+---------------+
   | :ref:`int<class_int>`                              | :ref:`max_polyphony<class_AudioStreamPlayer_property_max_polyphony>` | ``1``         |
   +----------------------------------------------------+----------------------------------------------------------------------+---------------+
   | :ref:`MixTarget<enum_AudioStreamPlayer_MixTarget>` | :ref:`mix_target<class_AudioStreamPlayer_property_mix_target>`       | ``0``         |
   +----------------------------------------------------+----------------------------------------------------------------------+---------------+
   | :ref:`float<class_float>`                          | :ref:`pitch_scale<class_AudioStreamPlayer_property_pitch_scale>`     | ``1.0``       |
   +----------------------------------------------------+----------------------------------------------------------------------+---------------+
   | :ref:`bool<class_bool>`                            | :ref:`playing<class_AudioStreamPlayer_property_playing>`             | ``false``     |
   +----------------------------------------------------+----------------------------------------------------------------------+---------------+
   | :ref:`AudioStream<class_AudioStream>`              | :ref:`stream<class_AudioStreamPlayer_property_stream>`               |               |
   +----------------------------------------------------+----------------------------------------------------------------------+---------------+
   | :ref:`bool<class_bool>`                            | :ref:`stream_paused<class_AudioStreamPlayer_property_stream_paused>` | ``false``     |
   +----------------------------------------------------+----------------------------------------------------------------------+---------------+
   | :ref:`float<class_float>`                          | :ref:`volume_db<class_AudioStreamPlayer_property_volume_db>`         | ``0.0``       |
   +----------------------------------------------------+----------------------------------------------------------------------+---------------+

.. rst-class:: classref-reftable-group

Methods
-------

.. table::
   :widths: auto

   +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
   | :ref:`float<class_float>`                             | :ref:`get_playback_position<class_AudioStreamPlayer_method_get_playback_position>` **(** **)**           |
   +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
   | :ref:`AudioStreamPlayback<class_AudioStreamPlayback>` | :ref:`get_stream_playback<class_AudioStreamPlayer_method_get_stream_playback>` **(** **)**               |
   +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
   | :ref:`bool<class_bool>`                               | :ref:`has_stream_playback<class_AudioStreamPlayer_method_has_stream_playback>` **(** **)**               |
   +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
   | void                                                  | :ref:`play<class_AudioStreamPlayer_method_play>` **(** :ref:`float<class_float>` from_position=0.0 **)** |
   +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
   | void                                                  | :ref:`seek<class_AudioStreamPlayer_method_seek>` **(** :ref:`float<class_float>` to_position **)**       |
   +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
   | void                                                  | :ref:`stop<class_AudioStreamPlayer_method_stop>` **(** **)**                                             |
   +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------+

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

Signals
-------

.. _class_AudioStreamPlayer_signal_finished:

.. rst-class:: classref-signal

**finished** **(** **)**

Emitted when the audio stops playing.

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

Enumerations
------------

.. _enum_AudioStreamPlayer_MixTarget:

.. rst-class:: classref-enumeration

enum **MixTarget**:

.. _class_AudioStreamPlayer_constant_MIX_TARGET_STEREO:

.. rst-class:: classref-enumeration-constant

:ref:`MixTarget<enum_AudioStreamPlayer_MixTarget>` **MIX_TARGET_STEREO** = ``0``

The audio will be played only on the first channel.

.. _class_AudioStreamPlayer_constant_MIX_TARGET_SURROUND:

.. rst-class:: classref-enumeration-constant

:ref:`MixTarget<enum_AudioStreamPlayer_MixTarget>` **MIX_TARGET_SURROUND** = ``1``

The audio will be played on all surround channels.

.. _class_AudioStreamPlayer_constant_MIX_TARGET_CENTER:

.. rst-class:: classref-enumeration-constant

:ref:`MixTarget<enum_AudioStreamPlayer_MixTarget>` **MIX_TARGET_CENTER** = ``2``

The audio will be played on the second channel, which is usually the center.

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

Property Descriptions
---------------------

.. _class_AudioStreamPlayer_property_autoplay:

.. rst-class:: classref-property

:ref:`bool<class_bool>` **autoplay** = ``false``

.. rst-class:: classref-property-setget

- void **set_autoplay** **(** :ref:`bool<class_bool>` value **)**
- :ref:`bool<class_bool>` **is_autoplay_enabled** **(** **)**

If ``true``, audio plays when added to scene tree.

.. rst-class:: classref-item-separator

----

.. _class_AudioStreamPlayer_property_bus:

.. rst-class:: classref-property

:ref:`StringName<class_StringName>` **bus** = ``&"Master"``

.. rst-class:: classref-property-setget

- void **set_bus** **(** :ref:`StringName<class_StringName>` value **)**
- :ref:`StringName<class_StringName>` **get_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"``.

.. rst-class:: classref-item-separator

----

.. _class_AudioStreamPlayer_property_max_polyphony:

.. rst-class:: classref-property

:ref:`int<class_int>` **max_polyphony** = ``1``

.. rst-class:: classref-property-setget

- void **set_max_polyphony** **(** :ref:`int<class_int>` value **)**
- :ref:`int<class_int>` **get_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.

.. rst-class:: classref-item-separator

----

.. _class_AudioStreamPlayer_property_mix_target:

.. rst-class:: classref-property

:ref:`MixTarget<enum_AudioStreamPlayer_MixTarget>` **mix_target** = ``0``

.. rst-class:: classref-property-setget

- void **set_mix_target** **(** :ref:`MixTarget<enum_AudioStreamPlayer_MixTarget>` value **)**
- :ref:`MixTarget<enum_AudioStreamPlayer_MixTarget>` **get_mix_target** **(** **)**

If the audio configuration has more than two speakers, this sets the target channels. See :ref:`MixTarget<enum_AudioStreamPlayer_MixTarget>` constants.

.. rst-class:: classref-item-separator

----

.. _class_AudioStreamPlayer_property_pitch_scale:

.. rst-class:: classref-property

:ref:`float<class_float>` **pitch_scale** = ``1.0``

.. rst-class:: classref-property-setget

- void **set_pitch_scale** **(** :ref:`float<class_float>` value **)**
- :ref:`float<class_float>` **get_pitch_scale** **(** **)**

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

.. rst-class:: classref-item-separator

----

.. _class_AudioStreamPlayer_property_playing:

.. rst-class:: classref-property

:ref:`bool<class_bool>` **playing** = ``false``

.. rst-class:: classref-property-setget

- :ref:`bool<class_bool>` **is_playing** **(** **)**

If ``true``, audio is playing.

.. rst-class:: classref-item-separator

----

.. _class_AudioStreamPlayer_property_stream:

.. rst-class:: classref-property

:ref:`AudioStream<class_AudioStream>` **stream**

.. rst-class:: classref-property-setget

- void **set_stream** **(** :ref:`AudioStream<class_AudioStream>` value **)**
- :ref:`AudioStream<class_AudioStream>` **get_stream** **(** **)**

The :ref:`AudioStream<class_AudioStream>` object to be played.

.. rst-class:: classref-item-separator

----

.. _class_AudioStreamPlayer_property_stream_paused:

.. rst-class:: classref-property

:ref:`bool<class_bool>` **stream_paused** = ``false``

.. rst-class:: classref-property-setget

- void **set_stream_paused** **(** :ref:`bool<class_bool>` value **)**
- :ref:`bool<class_bool>` **get_stream_paused** **(** **)**

If ``true``, the playback is paused. You can resume it by setting :ref:`stream_paused<class_AudioStreamPlayer_property_stream_paused>` to ``false``.

.. rst-class:: classref-item-separator

----

.. _class_AudioStreamPlayer_property_volume_db:

.. rst-class:: classref-property

:ref:`float<class_float>` **volume_db** = ``0.0``

.. rst-class:: classref-property-setget

- void **set_volume_db** **(** :ref:`float<class_float>` value **)**
- :ref:`float<class_float>` **get_volume_db** **(** **)**

Volume of sound, in dB.

.. rst-class:: classref-section-separator

----

.. rst-class:: classref-descriptions-group

Method Descriptions
-------------------

.. _class_AudioStreamPlayer_method_get_playback_position:

.. rst-class:: classref-method

:ref:`float<class_float>` **get_playback_position** **(** **)**

Returns the position in the :ref:`AudioStream<class_AudioStream>` in seconds.

.. rst-class:: classref-item-separator

----

.. _class_AudioStreamPlayer_method_get_stream_playback:

.. rst-class:: classref-method

:ref:`AudioStreamPlayback<class_AudioStreamPlayback>` **get_stream_playback** **(** **)**

Returns the :ref:`AudioStreamPlayback<class_AudioStreamPlayback>` object associated with this **AudioStreamPlayer**.

.. rst-class:: classref-item-separator

----

.. _class_AudioStreamPlayer_method_has_stream_playback:

.. rst-class:: classref-method

:ref:`bool<class_bool>` **has_stream_playback** **(** **)**

Returns whether the **AudioStreamPlayer** can return the :ref:`AudioStreamPlayback<class_AudioStreamPlayback>` object or not.

.. rst-class:: classref-item-separator

----

.. _class_AudioStreamPlayer_method_play:

.. rst-class:: classref-method

void **play** **(** :ref:`float<class_float>` from_position=0.0 **)**

Plays the audio from the given ``from_position``, in seconds.

.. rst-class:: classref-item-separator

----

.. _class_AudioStreamPlayer_method_seek:

.. rst-class:: classref-method

void **seek** **(** :ref:`float<class_float>` to_position **)**

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

.. rst-class:: classref-item-separator

----

.. _class_AudioStreamPlayer_method_stop:

.. rst-class:: classref-method

void **stop** **(** **)**

Stops the audio.

.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`
.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)`
.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`
.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)`
.. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)`