godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-04 14:11:02 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
19fca2678c1ca063601f0a14e005a846aea3e765
godot-docs/classes/class_audiostreamplayer3d.rst
Rémi Verschelde 19fca2678c classref: Sync with latest 4.0-alpha
2022-02-22 10:06:27 +01:00

488 lines
25 KiB
ReStructuredText
Raw Blame History

:github_url: hide
.. Generated automatically by doc/tools/make_rst.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:`Node3D<class_Node3D>` **<** :ref:`Node<class_Node>` **<** :ref:`Object<class_Object>`
Plays positional 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. For greater realism, a low-pass filter is automatically applied to distant sounds. This can be disabled by setting :ref:`attenuation_filter_cutoff_hz<class_AudioStreamPlayer3D_property_attenuation_filter_cutoff_hz>` to ``20500``.
By default, audio is heard from the camera position. This can be changed by adding a :ref:`AudioListener3D<class_AudioListener3D>` node to the scene and enabling it by calling :ref:`AudioListener3D.make_current<class_AudioListener3D_method_make_current>` on it.
See also :ref:`AudioStreamPlayer<class_AudioStreamPlayer>` to play a sound non-positionally.
\ **Note:** Hiding an ``AudioStreamPlayer3D`` node does not disable its audio output. To temporarily disable an ``AudioStreamPlayer3D``'s audio output, set :ref:`unit_db<class_AudioStreamPlayer3D_property_unit_db>` to a very low value like ``-100`` (which isn't audible to human hearing).
Tutorials
---------
- :doc:`Audio streams <../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:`StringName<class_StringName>` | :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:`int<class_int>` | :ref:`max_polyphony<class_AudioStreamPlayer3D_property_max_polyphony>` | ``1`` |
+--------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+---------------+
| :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>` | ``10.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. The sound will still be heard positionally, unlike an :ref:`AudioStreamPlayer<class_AudioStreamPlayer>`. :ref:`ATTENUATION_DISABLED<class_AudioStreamPlayer3D_constant_ATTENUATION_DISABLED>` can be combined with a :ref:`max_distance<class_AudioStreamPlayer3D_property_max_distance>` value greater than ``0.0`` to achieve linear attenuation clamped to a sphere of a defined size.
----
.. _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() |
+-----------+----------------------+
Determines which :ref:`Area3D<class_Area3D>` 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.
----
.. _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 using a low-pass filter above this frequency, in Hz. To disable the dampening effect entirely, set this to ``20500`` as this frequency is above the human hearing limit.
----
.. _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 decibels.
----
.. _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 the AudioStreamPlayer3D node is added to scene tree.
----
.. _class_AudioStreamPlayer3D_property_bus:
- :ref:`StringName<class_StringName>` **bus**
+-----------+----------------+
| *Default* | ``&"Master"`` |
+-----------+----------------+
| *Setter* | set_bus(value) |
+-----------+----------------+
| *Getter* | get_bus() |
+-----------+----------------+
The 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 decibels.
----
.. _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 decibels.
----
.. _class_AudioStreamPlayer3D_property_max_distance:
- :ref:`float<class_float>` **max_distance**
+-----------+-------------------------+
| *Default* | ``0.0`` |
+-----------+-------------------------+
| *Setter* | set_max_distance(value) |
+-----------+-------------------------+
| *Getter* | get_max_distance() |
+-----------+-------------------------+
The distance past which the sound can no longer be heard at all. Only has an effect if set to a value greater than ``0.0``. :ref:`max_distance<class_AudioStreamPlayer3D_property_max_distance>` works in tandem with :ref:`unit_size<class_AudioStreamPlayer3D_property_unit_size>`. However, unlike :ref:`unit_size<class_AudioStreamPlayer3D_property_unit_size>` whose behavior depends on the :ref:`attenuation_model<class_AudioStreamPlayer3D_property_attenuation_model>`, :ref:`max_distance<class_AudioStreamPlayer3D_property_max_distance>` always works in a linear fashion. This can be used to prevent the ``AudioStreamPlayer3D`` from requiring audio mixing when the listener is far away, which saves CPU resources.
----
.. _class_AudioStreamPlayer3D_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_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>` resource 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 :ref:`stream_paused<class_AudioStreamPlayer3D_property_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() |
+-----------+--------------------+
The base sound level unaffected by dampening, in decibels.
----
.. _class_AudioStreamPlayer3D_property_unit_size:
- :ref:`float<class_float>` **unit_size**
+-----------+----------------------+
| *Default* | ``10.0`` |
+-----------+----------------------+
| *Setter* | set_unit_size(value) |
+-----------+----------------------+
| *Getter* | get_unit_size() |
+-----------+----------------------+
The factor for the attenuation effect. Higher values make the sound audible over a larger distance.
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.)`
.. |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.)`
Reference in New Issue View Git Blame Copy Permalink