godot-docs/classes/class_audiostreamplayer2d.rst

:github_url: hide

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

.. _class_AudioStreamPlayer2D:

AudioStreamPlayer2D
===================

**Inherits:** :ref:`Node2D<class_Node2D>` **<** :ref:`CanvasItem<class_CanvasItem>` **<** :ref:`Node<class_Node>` **<** :ref:`Object<class_Object>`

Plays positional sound in 2D space.

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

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

Plays audio that dampens with distance from a given position.

By default, audio is heard from the screen center. This can be changed by adding a :ref:`Listener2D<class_Listener2D>` node to the scene and enabling it by calling :ref:`Listener2D.make_current<class_Listener2D_method_make_current>` on it.

See also :ref:`AudioStreamPlayer<class_AudioStreamPlayer>` to play a sound non-positionally.

\ **Note:** Hiding an **AudioStreamPlayer2D** node does not disable its audio output. To temporarily disable an **AudioStreamPlayer2D**'s audio output, set :ref:`volume_db<class_AudioStreamPlayer2D_property_volume_db>` to a very low value like ``-100`` (which isn't audible to human hearing).

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

Tutorials
---------

- :doc:`../tutorials/audio/audio_streams`

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

Properties
----------

.. table::
   :widths: auto

   +---------------------------------------+------------------------------------------------------------------------------+--------------+
   | :ref:`int<class_int>`                 | :ref:`area_mask<class_AudioStreamPlayer2D_property_area_mask>`               | ``1``        |
   +---------------------------------------+------------------------------------------------------------------------------+--------------+
   | :ref:`float<class_float>`             | :ref:`attenuation<class_AudioStreamPlayer2D_property_attenuation>`           | ``1.0``      |
   +---------------------------------------+------------------------------------------------------------------------------+--------------+
   | :ref:`bool<class_bool>`               | :ref:`autoplay<class_AudioStreamPlayer2D_property_autoplay>`                 | ``false``    |
   +---------------------------------------+------------------------------------------------------------------------------+--------------+
   | :ref:`String<class_String>`           | :ref:`bus<class_AudioStreamPlayer2D_property_bus>`                           | ``"Master"`` |
   +---------------------------------------+------------------------------------------------------------------------------+--------------+
   | :ref:`float<class_float>`             | :ref:`max_distance<class_AudioStreamPlayer2D_property_max_distance>`         | ``2000.0``   |
   +---------------------------------------+------------------------------------------------------------------------------+--------------+
   | :ref:`float<class_float>`             | :ref:`panning_strength<class_AudioStreamPlayer2D_property_panning_strength>` | ``1.0``      |
   +---------------------------------------+------------------------------------------------------------------------------+--------------+
   | :ref:`float<class_float>`             | :ref:`pitch_scale<class_AudioStreamPlayer2D_property_pitch_scale>`           | ``1.0``      |
   +---------------------------------------+------------------------------------------------------------------------------+--------------+
   | :ref:`bool<class_bool>`               | :ref:`playing<class_AudioStreamPlayer2D_property_playing>`                   | ``false``    |
   +---------------------------------------+------------------------------------------------------------------------------+--------------+
   | :ref:`AudioStream<class_AudioStream>` | :ref:`stream<class_AudioStreamPlayer2D_property_stream>`                     |              |
   +---------------------------------------+------------------------------------------------------------------------------+--------------+
   | :ref:`bool<class_bool>`               | :ref:`stream_paused<class_AudioStreamPlayer2D_property_stream_paused>`       | ``false``    |
   +---------------------------------------+------------------------------------------------------------------------------+--------------+
   | :ref:`float<class_float>`             | :ref:`volume_db<class_AudioStreamPlayer2D_property_volume_db>`               | ``0.0``      |
   +---------------------------------------+------------------------------------------------------------------------------+--------------+

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

Methods
-------

.. table::
   :widths: auto

   +-------------------------------------------------------+------------------------------------------------------------------------------------------------------------+
   | :ref:`float<class_float>`                             | :ref:`get_playback_position<class_AudioStreamPlayer2D_method_get_playback_position>` **(** **)**           |
   +-------------------------------------------------------+------------------------------------------------------------------------------------------------------------+
   | :ref:`AudioStreamPlayback<class_AudioStreamPlayback>` | :ref:`get_stream_playback<class_AudioStreamPlayer2D_method_get_stream_playback>` **(** **)**               |
   +-------------------------------------------------------+------------------------------------------------------------------------------------------------------------+
   | void                                                  | :ref:`play<class_AudioStreamPlayer2D_method_play>` **(** :ref:`float<class_float>` from_position=0.0 **)** |
   +-------------------------------------------------------+------------------------------------------------------------------------------------------------------------+
   | void                                                  | :ref:`seek<class_AudioStreamPlayer2D_method_seek>` **(** :ref:`float<class_float>` to_position **)**       |
   +-------------------------------------------------------+------------------------------------------------------------------------------------------------------------+
   | void                                                  | :ref:`stop<class_AudioStreamPlayer2D_method_stop>` **(** **)**                                             |
   +-------------------------------------------------------+------------------------------------------------------------------------------------------------------------+

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

----

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

Signals
-------

.. _class_AudioStreamPlayer2D_signal_finished:

.. rst-class:: classref-signal

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

Emitted when the audio stops playing.

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

----

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

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

.. _class_AudioStreamPlayer2D_property_area_mask:

.. rst-class:: classref-property

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

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

- void **set_area_mask** **(** :ref:`int<class_int>` value **)**
- :ref:`int<class_int>` **get_area_mask** **(** **)**

Determines which :ref:`Area2D<class_Area2D>` layers affect the sound for reverb and audio bus effects. Areas can be used to redirect :ref:`AudioStream<class_AudioStream>`\ s 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.

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

----

.. _class_AudioStreamPlayer2D_property_attenuation:

.. rst-class:: classref-property

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

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

- void **set_attenuation** **(** :ref:`float<class_float>` value **)**
- :ref:`float<class_float>` **get_attenuation** **(** **)**

Dampens audio over distance with this as an exponent.

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

----

.. _class_AudioStreamPlayer2D_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_AudioStreamPlayer2D_property_bus:

.. rst-class:: classref-property

:ref:`String<class_String>` **bus** = ``"Master"``

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

- void **set_bus** **(** :ref:`String<class_String>` value **)**
- :ref:`String<class_String>` **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_AudioStreamPlayer2D_property_max_distance:

.. rst-class:: classref-property

:ref:`float<class_float>` **max_distance** = ``2000.0``

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

- void **set_max_distance** **(** :ref:`float<class_float>` value **)**
- :ref:`float<class_float>` **get_max_distance** **(** **)**

Maximum distance from which audio is still hearable.

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

----

.. _class_AudioStreamPlayer2D_property_panning_strength:

.. rst-class:: classref-property

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

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

- void **set_panning_strength** **(** :ref:`float<class_float>` value **)**
- :ref:`float<class_float>` **get_panning_strength** **(** **)**

Scales the panning strength for this node by multiplying the base :ref:`ProjectSettings.audio/2d_panning_strength<class_ProjectSettings_property_audio/2d_panning_strength>` with this factor. Higher values will pan audio from left to right more dramatically than lower values.

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

----

.. _class_AudioStreamPlayer2D_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_AudioStreamPlayer2D_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_AudioStreamPlayer2D_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_AudioStreamPlayer2D_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 ``stream_paused`` to ``false``.

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

----

.. _class_AudioStreamPlayer2D_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** **(** **)**

Base volume without dampening.

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

----

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

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

.. _class_AudioStreamPlayer2D_method_get_playback_position:

.. rst-class:: classref-method

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

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

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

----

.. _class_AudioStreamPlayer2D_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 **AudioStreamPlayer2D**.

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

----

.. _class_AudioStreamPlayer2D_method_play:

.. rst-class:: classref-method

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

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

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

----

.. _class_AudioStreamPlayer2D_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_AudioStreamPlayer2D_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.)`
.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`