godot-docs/classes/class_audiostreamplayer.rst

:github_url: hide

.. Generated automatically by doc/tools/make_rst.py in Godot's source tree.
.. DO NOT EDIT THIS FILE, but the AudioStreamPlayer.xml source instead.
.. The source is found in doc/classes or modules/<name>/doc_classes.

.. _class_AudioStreamPlayer:

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

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

Plays back audio non-positionally.

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

Plays an audio stream non-positionally.

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

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>`__

Properties
----------

+----------------------------------------------------+----------------------------------------------------------------------+---------------+
| :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``       |
+----------------------------------------------------+----------------------------------------------------------------------+---------------+

Methods
-------

+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
| :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>` **(** **)**               |
+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------+
| 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>` **(** **)**                                             |
+-------------------------------------------------------+----------------------------------------------------------------------------------------------------------+

Signals
-------

.. _class_AudioStreamPlayer_signal_finished:

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

Emitted when the audio stops playing.

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

.. _enum_AudioStreamPlayer_MixTarget:

.. _class_AudioStreamPlayer_constant_MIX_TARGET_STEREO:

.. _class_AudioStreamPlayer_constant_MIX_TARGET_SURROUND:

.. _class_AudioStreamPlayer_constant_MIX_TARGET_CENTER:

enum **MixTarget**:

- **MIX_TARGET_STEREO** = **0** --- The audio will be played only on the first channel.

- **MIX_TARGET_SURROUND** = **1** --- The audio will be played on all surround channels.

- **MIX_TARGET_CENTER** = **2** --- The audio will be played on the second channel, which is usually the center.

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

.. _class_AudioStreamPlayer_property_autoplay:

- :ref:`bool<class_bool>` **autoplay**

+-----------+-----------------------+
| *Default* | ``false``             |
+-----------+-----------------------+
| *Setter*  | set_autoplay(value)   |
+-----------+-----------------------+
| *Getter*  | is_autoplay_enabled() |
+-----------+-----------------------+

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

----

.. _class_AudioStreamPlayer_property_bus:

- :ref:`StringName<class_StringName>` **bus**

+-----------+----------------+
| *Default* | ``&"Master"``  |
+-----------+----------------+
| *Setter*  | set_bus(value) |
+-----------+----------------+
| *Getter*  | get_bus()      |
+-----------+----------------+

Bus on which this audio is playing.

----

.. _class_AudioStreamPlayer_property_max_polyphony:

- :ref:`int<class_int>` **max_polyphony**

+-----------+--------------------------+
| *Default* | ``1``                    |
+-----------+--------------------------+
| *Setter*  | set_max_polyphony(value) |
+-----------+--------------------------+
| *Getter*  | 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.

----

.. _class_AudioStreamPlayer_property_mix_target:

- :ref:`MixTarget<enum_AudioStreamPlayer_MixTarget>` **mix_target**

+-----------+-----------------------+
| *Default* | ``0``                 |
+-----------+-----------------------+
| *Setter*  | set_mix_target(value) |
+-----------+-----------------------+
| *Getter*  | get_mix_target()      |
+-----------+-----------------------+

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

----

.. _class_AudioStreamPlayer_property_pitch_scale:

- :ref:`float<class_float>` **pitch_scale**

+-----------+------------------------+
| *Default* | ``1.0``                |
+-----------+------------------------+
| *Setter*  | set_pitch_scale(value) |
+-----------+------------------------+
| *Getter*  | get_pitch_scale()      |
+-----------+------------------------+

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

----

.. _class_AudioStreamPlayer_property_playing:

- :ref:`bool<class_bool>` **playing**

+-----------+--------------+
| *Default* | ``false``    |
+-----------+--------------+
| *Getter*  | is_playing() |
+-----------+--------------+

If ``true``, audio is playing.

----

.. _class_AudioStreamPlayer_property_stream:

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

+----------+-------------------+
| *Setter* | set_stream(value) |
+----------+-------------------+
| *Getter* | get_stream()      |
+----------+-------------------+

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

----

.. _class_AudioStreamPlayer_property_stream_paused:

- :ref:`bool<class_bool>` **stream_paused**

+-----------+--------------------------+
| *Default* | ``false``                |
+-----------+--------------------------+
| *Setter*  | set_stream_paused(value) |
+-----------+--------------------------+
| *Getter*  | get_stream_paused()      |
+-----------+--------------------------+

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

----

.. _class_AudioStreamPlayer_property_volume_db:

- :ref:`float<class_float>` **volume_db**

+-----------+----------------------+
| *Default* | ``0.0``              |
+-----------+----------------------+
| *Setter*  | set_volume_db(value) |
+-----------+----------------------+
| *Getter*  | get_volume_db()      |
+-----------+----------------------+

Volume of sound, in dB.

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

.. _class_AudioStreamPlayer_method_get_playback_position:

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

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

----

.. _class_AudioStreamPlayer_method_get_stream_playback:

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

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

----

.. _class_AudioStreamPlayer_method_play:

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

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

----

.. _class_AudioStreamPlayer_method_seek:

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

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

----

.. _class_AudioStreamPlayer_method_stop:

- 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.)`