.. _stdlib_audio_component:

=====
Audio
=====

This module provides a description of the Audio component, used for audio processing, playback, and listening.

- `AudioClipSource`: A variant type representing audio sources. It contains information about the audio resource (with a ResourceId) and the data of the audio source (rate, channels, samples).
- `AudioSource`: A component for processing and playing audio sources. It includes functions for playing, stopping, and pausing/resuming the current sound.
- `AudioListener`: A component for listening, with the ability to update its position and direction.

Add these components like any others using the add_component function::

    // create a node at position float3(-2, 0, 0)
    var sourceNode = create_node(NodeData(name="source_node", position=float3(-2, 0, 0)))
    // add a component for 3D sound with the given attenuation
    add_component(sourceNode, new AudioSource(is3d=true, attenuation=inverse_distance_attenuation(5.)))

    // create a node at position float3(2, 0, 0)
    var listenerNode = create_node(NodeData(name="listener_node", position=float3(2, 0, 0)))
    // add a component for audio listening
    add_component(listenerNode, new AudioListener())

+++++++
Classes
+++++++

.. _struct-audio_component-AudioSource:

.. das:attribute:: AudioSource : Component

audio component for processing and playing audio sources

Usage example::

    let node : NodeId = ...
    add_component(node, new AudioSource(isLoop=true, is3d=true))

previous position of sound for updating it if it is 3D

:Fields: * **source** :  :ref:`SoundId <handle-public_resources-SoundId>`  - id of Sound resource (can be generated by request_sound for example)

         * **isLoop** : bool = false - if sound should be looped

         * **is3d** : bool = false - if sound should be played as 3D sound

         * **autoPlay** : bool = false - if sound should be played automatically on start

         * **attenuation** :  :ref:`Attenuation <struct-sound_core-Attenuation>`  = default_attenuation() - attenuation of sound (default: 1 / (d + 1))

         * **currentSound** :  :ref:`SoundHandle <alias-SoundHandle>`  - handle of currently playing sound

         * **pan** : float = 0f - pan of sound (left -1 to right 1)

         * **pitch** : float = 1f - pitch of sound (1 is normal)

         * **volume** : float = 1f - volume of sound (0 is silent, 1 is normal)


.. _function-audio_component_AudioSource_rq_on_initialize_AudioSource:

.. das:function:: AudioSource.on_initialize()

play sound if autoPlay is true

.. _function-audio_component_AudioSource_rq_on_update_AudioSource:

.. das:function:: AudioSource.on_update()

update 3D sound position if it is 3D

.. _function-audio_component_AudioSource_rq_play_AudioSource:

.. das:function:: AudioSource.play()

stop previous sound if any and plays new sound based on the input source
if source is not resource (with SoundId), it is played as data with rate, channels and samples

.. _function-audio_component_AudioSource_rq_playSource_AudioSource_SoundId:

.. das:function:: AudioSource.playSource(src: SoundId)

delete previous source if any and plays new source

:Arguments: * **src** :  :ref:`SoundId <handle-public_resources-SoundId>`  -  source to play



Usage example::

    add_component(node, new AudioSource())
    get_component(node) $(var audio : AudioSource?) {
        audio.playSource(request_sound("my_sound.wav"))
    }

.. _function-audio_component_AudioSource_rq_stop_AudioSource:

.. das:function:: AudioSource.stop()

stop playing current sound and sets it to invalid id

Usage example::

    add_component(node, new AudioSource())
    get_component(node) $(var audio : AudioSource?) {
        audio.stop()
    }

.. _function-audio_component_AudioSource_rq_pause_AudioSource_bool:

.. das:function:: AudioSource.pause(val: bool = true)

pause or resume playing current sound

:Arguments: * **val** : bool -  true to pause, false to resume



Usage example::

    add_component(node, new AudioSource())
    get_component(node) $(var audio : AudioSource?) {
        audio.pause() // pause
        audio.pause(false) // resume
    }

.. _struct-audio_component-AudioListener:

.. das:attribute:: AudioListener : Component

audio listener component

Usage example::

    add_component(node, new AudioListener())


.. _function-audio_component_AudioListener_rq_on_update_AudioListener:

.. das:function:: AudioListener.on_update()

update audio listener position and direction