godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-03 05:48:42 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
b2579e9cef1f422659aaa64d11568a5cb7900a13
godot-docs/classes/class_audiostreamplayer3d.rst
Rémi Verschelde f4d0513091 Resync classref with 3.2.3-stable, next release is 3.3
2021-03-16 12:29:34 +01:00

495 lines
23 KiB
ReStructuredText
Raw Blame History

:github_url: hide
.. 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>`
Plays 3D sound in 3D space.
Description
-----------
Plays a sound effect with directed sound effects, dampens with distance if needed, generates effect of hearable position in space.
By default, audio is heard from the camera position. This can be changed by adding a :ref:`Listener<class_Listener>` node to the scene and enabling it by calling :ref:`Listener.make_current<class_Listener_method_make_current>` on it.
Tutorials
---------
- :doc:`../tutorials/audio/audio_streams`
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.
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() |
+-----------+------------------------+
The pitch and the tempo of the audio, as a multiplier of the audio sample's sample rate.
----
.. _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() |
+-----------+--------------------------+
If ``true``, the playback is paused. You can resume it by setting ``stream_paused`` to ``false``.
----
.. _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** **(** **)**
Returns the :ref:`AudioStreamPlayback<class_AudioStreamPlayback>` object associated with this ``AudioStreamPlayer3D``.
----
.. _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.
.. |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.)`
Reference in New Issue View Git Blame Copy Permalink