godot-docs/classes/class_audiostreamplayer3d.rst

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

.. _class_AudioStreamPlayer3D:

AudioStreamPlayer3D
===================

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

**Category:** Core

Brief Description
-----------------

Plays 3D sound in 3D space.

Properties
----------

+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+----------+
| :ref:`int<class_int>`                                              | :ref:`area_mask<class_AudioStreamPlayer3D_property_area_mask>`                                                       | 1        |
+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+----------+
| :ref:`float<class_float>`                                          | :ref:`attenuation_filter_cutoff_hz<class_AudioStreamPlayer3D_property_attenuation_filter_cutoff_hz>`                 | 5000.0   |
+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+----------+
| :ref:`float<class_float>`                                          | :ref:`attenuation_filter_db<class_AudioStreamPlayer3D_property_attenuation_filter_db>`                               | -24.0    |
+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+----------+
| :ref:`AttenuationModel<enum_AudioStreamPlayer3D_AttenuationModel>` | :ref:`attenuation_model<class_AudioStreamPlayer3D_property_attenuation_model>`                                       | 0        |
+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+----------+
| :ref:`bool<class_bool>`                                            | :ref:`autoplay<class_AudioStreamPlayer3D_property_autoplay>`                                                         | false    |
+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+----------+
| :ref:`String<class_String>`                                        | :ref:`bus<class_AudioStreamPlayer3D_property_bus>`                                                                   | "Master" |
+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+----------+
| :ref:`DopplerTracking<enum_AudioStreamPlayer3D_DopplerTracking>`   | :ref:`doppler_tracking<class_AudioStreamPlayer3D_property_doppler_tracking>`                                         | 0        |
+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+----------+
| :ref:`float<class_float>`                                          | :ref:`emission_angle_degrees<class_AudioStreamPlayer3D_property_emission_angle_degrees>`                             | 45.0     |
+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+----------+
| :ref:`bool<class_bool>`                                            | :ref:`emission_angle_enabled<class_AudioStreamPlayer3D_property_emission_angle_enabled>`                             | false    |
+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+----------+
| :ref:`float<class_float>`                                          | :ref:`emission_angle_filter_attenuation_db<class_AudioStreamPlayer3D_property_emission_angle_filter_attenuation_db>` | -12.0    |
+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+----------+
| :ref:`float<class_float>`                                          | :ref:`max_db<class_AudioStreamPlayer3D_property_max_db>`                                                             | 3.0      |
+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+----------+
| :ref:`float<class_float>`                                          | :ref:`max_distance<class_AudioStreamPlayer3D_property_max_distance>`                                                 | 0.0      |
+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+----------+
| :ref:`OutOfRangeMode<enum_AudioStreamPlayer3D_OutOfRangeMode>`     | :ref:`out_of_range_mode<class_AudioStreamPlayer3D_property_out_of_range_mode>`                                       | 0        |
+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+----------+
| :ref:`float<class_float>`                                          | :ref:`pitch_scale<class_AudioStreamPlayer3D_property_pitch_scale>`                                                   | 1.0      |
+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+----------+
| :ref:`bool<class_bool>`                                            | :ref:`playing<class_AudioStreamPlayer3D_property_playing>`                                                           | false    |
+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+----------+
| :ref:`AudioStream<class_AudioStream>`                              | :ref:`stream<class_AudioStreamPlayer3D_property_stream>`                                                             |          |
+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+----------+
| :ref:`bool<class_bool>`                                            | :ref:`stream_paused<class_AudioStreamPlayer3D_property_stream_paused>`                                               | false    |
+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+----------+
| :ref:`float<class_float>`                                          | :ref:`unit_db<class_AudioStreamPlayer3D_property_unit_db>`                                                           | 0.0      |
+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+----------+
| :ref:`float<class_float>`                                          | :ref:`unit_size<class_AudioStreamPlayer3D_property_unit_size>`                                                       | 1.0      |
+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+----------+

Methods
-------

+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------+
| :ref:`float<class_float>`                             | :ref:`get_playback_position<class_AudioStreamPlayer3D_method_get_playback_position>` **(** **)**           |
+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------+
| :ref:`AudioStreamPlayback<class_AudioStreamPlayback>` | :ref:`get_stream_playback<class_AudioStreamPlayer3D_method_get_stream_playback>` **(** **)**               |
+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------+
| void                                                  | :ref:`play<class_AudioStreamPlayer3D_method_play>` **(** :ref:`float<class_float>` from_position=0.0 **)** |
+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------+
| void                                                  | :ref:`seek<class_AudioStreamPlayer3D_method_seek>` **(** :ref:`float<class_float>` to_position **)**       |
+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------+
| void                                                  | :ref:`stop<class_AudioStreamPlayer3D_method_stop>` **(** **)**                                             |
+-------------------------------------------------------+------------------------------------------------------------------------------------------------------------+

Signals
-------

.. _class_AudioStreamPlayer3D_signal_finished:

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

Emitted when the audio stops playing.

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

.. _enum_AudioStreamPlayer3D_AttenuationModel:

.. _class_AudioStreamPlayer3D_constant_ATTENUATION_INVERSE_DISTANCE:

.. _class_AudioStreamPlayer3D_constant_ATTENUATION_INVERSE_SQUARE_DISTANCE:

.. _class_AudioStreamPlayer3D_constant_ATTENUATION_LOGARITHMIC:

.. _class_AudioStreamPlayer3D_constant_ATTENUATION_DISABLED:

enum **AttenuationModel**:

- **ATTENUATION_INVERSE_DISTANCE** = **0** --- Linear dampening of loudness according to distance.

- **ATTENUATION_INVERSE_SQUARE_DISTANCE** = **1** --- Squared dampening of loudness according to distance.

- **ATTENUATION_LOGARITHMIC** = **2** --- Logarithmic dampening of loudness according to distance.

- **ATTENUATION_DISABLED** = **3** --- No dampening of loudness according to distance.

.. _enum_AudioStreamPlayer3D_OutOfRangeMode:

.. _class_AudioStreamPlayer3D_constant_OUT_OF_RANGE_MIX:

.. _class_AudioStreamPlayer3D_constant_OUT_OF_RANGE_PAUSE:

enum **OutOfRangeMode**:

- **OUT_OF_RANGE_MIX** = **0** --- Mix this audio in, even when it's out of range.

- **OUT_OF_RANGE_PAUSE** = **1** --- Pause this audio when it gets out of range.

.. _enum_AudioStreamPlayer3D_DopplerTracking:

.. _class_AudioStreamPlayer3D_constant_DOPPLER_TRACKING_DISABLED:

.. _class_AudioStreamPlayer3D_constant_DOPPLER_TRACKING_IDLE_STEP:

.. _class_AudioStreamPlayer3D_constant_DOPPLER_TRACKING_PHYSICS_STEP:

enum **DopplerTracking**:

- **DOPPLER_TRACKING_DISABLED** = **0** --- Disables doppler tracking.

- **DOPPLER_TRACKING_IDLE_STEP** = **1** --- Executes doppler tracking in idle step.

- **DOPPLER_TRACKING_PHYSICS_STEP** = **2** --- Executes doppler tracking in physics step.

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

Plays a sound effect with directed sound effects, dampens with distance if needed, generates effect of hearable position in space.

Tutorials
---------

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

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

.. _class_AudioStreamPlayer3D_property_area_mask:

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

+-----------+----------------------+
| *Default* | 1                    |
+-----------+----------------------+
| *Setter*  | set_area_mask(value) |
+-----------+----------------------+
| *Getter*  | get_area_mask()      |
+-----------+----------------------+

Areas in which this sound plays.

.. _class_AudioStreamPlayer3D_property_attenuation_filter_cutoff_hz:

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

+-----------+-----------------------------------------+
| *Default* | 5000.0                                  |
+-----------+-----------------------------------------+
| *Setter*  | set_attenuation_filter_cutoff_hz(value) |
+-----------+-----------------------------------------+
| *Getter*  | get_attenuation_filter_cutoff_hz()      |
+-----------+-----------------------------------------+

Dampens audio above this frequency, in Hz.

.. _class_AudioStreamPlayer3D_property_attenuation_filter_db:

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

+-----------+----------------------------------+
| *Default* | -24.0                            |
+-----------+----------------------------------+
| *Setter*  | set_attenuation_filter_db(value) |
+-----------+----------------------------------+
| *Getter*  | get_attenuation_filter_db()      |
+-----------+----------------------------------+

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

.. _class_AudioStreamPlayer3D_property_attenuation_model:

- :ref:`AttenuationModel<enum_AudioStreamPlayer3D_AttenuationModel>` **attenuation_model**

+-----------+------------------------------+
| *Default* | 0                            |
+-----------+------------------------------+
| *Setter*  | set_attenuation_model(value) |
+-----------+------------------------------+
| *Getter*  | get_attenuation_model()      |
+-----------+------------------------------+

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

.. _class_AudioStreamPlayer3D_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_AudioStreamPlayer3D_property_bus:

- :ref:`String<class_String>` **bus**

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

Bus on which this audio is playing.

.. _class_AudioStreamPlayer3D_property_doppler_tracking:

- :ref:`DopplerTracking<enum_AudioStreamPlayer3D_DopplerTracking>` **doppler_tracking**

+-----------+-----------------------------+
| *Default* | 0                           |
+-----------+-----------------------------+
| *Setter*  | set_doppler_tracking(value) |
+-----------+-----------------------------+
| *Getter*  | get_doppler_tracking()      |
+-----------+-----------------------------+

Decides in which step the Doppler effect should be calculated.

.. _class_AudioStreamPlayer3D_property_emission_angle_degrees:

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

+-----------+---------------------------+
| *Default* | 45.0                      |
+-----------+---------------------------+
| *Setter*  | set_emission_angle(value) |
+-----------+---------------------------+
| *Getter*  | get_emission_angle()      |
+-----------+---------------------------+

The angle in which the audio reaches cameras undampened.

.. _class_AudioStreamPlayer3D_property_emission_angle_enabled:

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

+-----------+-----------------------------------+
| *Default* | false                             |
+-----------+-----------------------------------+
| *Setter*  | set_emission_angle_enabled(value) |
+-----------+-----------------------------------+
| *Getter*  | is_emission_angle_enabled()       |
+-----------+-----------------------------------+

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

.. _class_AudioStreamPlayer3D_property_emission_angle_filter_attenuation_db:

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

+-----------+-------------------------------------------------+
| *Default* | -12.0                                           |
+-----------+-------------------------------------------------+
| *Setter*  | set_emission_angle_filter_attenuation_db(value) |
+-----------+-------------------------------------------------+
| *Getter*  | get_emission_angle_filter_attenuation_db()      |
+-----------+-------------------------------------------------+

Dampens audio if camera is outside of :ref:`emission_angle_degrees<class_AudioStreamPlayer3D_property_emission_angle_degrees>` and :ref:`emission_angle_enabled<class_AudioStreamPlayer3D_property_emission_angle_enabled>` is set by this factor, in dB.

.. _class_AudioStreamPlayer3D_property_max_db:

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

+-----------+-------------------+
| *Default* | 3.0               |
+-----------+-------------------+
| *Setter*  | set_max_db(value) |
+-----------+-------------------+
| *Getter*  | get_max_db()      |
+-----------+-------------------+

Sets the absolute maximum of the soundlevel, in dB.

.. _class_AudioStreamPlayer3D_property_max_distance:

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

+-----------+-------------------------+
| *Default* | 0.0                     |
+-----------+-------------------------+
| *Setter*  | set_max_distance(value) |
+-----------+-------------------------+
| *Getter*  | get_max_distance()      |
+-----------+-------------------------+

Sets the distance from which the :ref:`out_of_range_mode<class_AudioStreamPlayer3D_property_out_of_range_mode>` takes effect. Has no effect if set to 0.

.. _class_AudioStreamPlayer3D_property_out_of_range_mode:

- :ref:`OutOfRangeMode<enum_AudioStreamPlayer3D_OutOfRangeMode>` **out_of_range_mode**

+-----------+------------------------------+
| *Default* | 0                            |
+-----------+------------------------------+
| *Setter*  | set_out_of_range_mode(value) |
+-----------+------------------------------+
| *Getter*  | get_out_of_range_mode()      |
+-----------+------------------------------+

Decides if audio should pause when source is outside of :ref:`max_distance<class_AudioStreamPlayer3D_property_max_distance>` range.

.. _class_AudioStreamPlayer3D_property_pitch_scale:

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

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

Changes the pitch and the tempo of the audio.

.. _class_AudioStreamPlayer3D_property_playing:

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

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

If ``true``, audio is playing.

.. _class_AudioStreamPlayer3D_property_stream:

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

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

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

.. _class_AudioStreamPlayer3D_property_stream_paused:

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

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

.. _class_AudioStreamPlayer3D_property_unit_db:

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

+-----------+--------------------+
| *Default* | 0.0                |
+-----------+--------------------+
| *Setter*  | set_unit_db(value) |
+-----------+--------------------+
| *Getter*  | get_unit_db()      |
+-----------+--------------------+

Base sound level unaffected by dampening, in dB.

.. _class_AudioStreamPlayer3D_property_unit_size:

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

+-----------+----------------------+
| *Default* | 1.0                  |
+-----------+----------------------+
| *Setter*  | set_unit_size(value) |
+-----------+----------------------+
| *Getter*  | get_unit_size()      |
+-----------+----------------------+

Factor for the attenuation effect.

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

.. _class_AudioStreamPlayer3D_method_get_playback_position:

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

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

.. _class_AudioStreamPlayer3D_method_get_stream_playback:

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

.. _class_AudioStreamPlayer3D_method_play:

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

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

.. _class_AudioStreamPlayer3D_method_seek:

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

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

.. _class_AudioStreamPlayer3D_method_stop:

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

Stops the audio.