# Audio Source
In the game scene, you can use the audio source AudioSource to play audio clip audioclip. But AudioSource can only play audio clips with preloadAudioData=true. By default, the sound played by AudioSource is directly received by AudioListener. You can also specify the audio mixer group AudioMixerGroup for AudioSource, so that the sound is mixed in real time through AudioMixer and then flows to AudioListener. AudioSource supports playback in 2D, 3D or spatialBlend mode, and also supports changing the sound attenuation mode to change the impact of distance on the sound.
# Attributes
| Properties | Functions |
|---|---|
| bypassEffects | All sound effects of the node where the AudioSource is located can be bypassed. true: disable sound effects; false: enable sound effects. |
| bypassListenerEffects | Whether the sound played by AudioSource is directly received by AudioListener, or processed by AudioMixer first, and then received by AudioListener, using this option can bypass all sound effects of the node where AudioListener is located. true: disable sound effects; false: enable sound effects. When there is and only one AudioSource on the node, bypassListenerEffects=true is valid. That is, when there are multiple AudioSources on a node, the sounds played by these AudioSources will be processed by all the sound effects of the node where the AudioListener is located. |
| playOnAwake | If this option is enabled, the sound will automatically play when the scene starts. If you disable this option, you need to call the AudioSource.play function through a script to play the sound. |
| audioPriority | Set the priority of the sound played by AudioSource. A value of 0: indicates the highest priority. A value of 255: indicates the lowest priority. When audioPriority=0, the sound played by AudioSource will not be set to virtual audio, that is, the sound played by AudioSource will definitely be heard. For the specific strategy of virtual audio, please refer to here. |
| output | By default, the sound is output directly to AudioListener. Use this property to change the sound output to AudioMixer for real-time mixing, and then output to AudioListener. |
| clip | Audio Clip audioclip to be played by AudioSource. |
| mute | Enable this option to mute. |
| loop | Enable this option to loop playback. |
| volume | Set the original volume of the sound played by AudioSource. Note that this attribute value is unitless. Value 1: means the volume remains unchanged; value 0: means mute. In addition to the effect of this option, the actual sound volume heard when the game is running is also affected by the distance between AudioSource and AudioListener, or various sound effects, AudioMixer, etc. |
| pitch | Sound playback rate. Value 1: Represents normal playback speed. Slow or fast playback will cause the pitch to change. |
| stereoPan | Set the left and right channels of 2D sound. Value -1: Only the left channel; Value 0: Two channels; Value 1: Only the right channel |
| spatialBlend | Set the degree of influence of the 3D space on the audio source. Value 0: Only 2D sound, ignoring the influence of all 3D spatial sound effects; Value 1: Full 3D sound effects. |
| coneInnerAngle | Set the cone angle of the sound in the playback direction, in degrees. Audio systems use cones to describe the direction of sound. In the cone defined by this property, the volume will not be reduced, that is, the sound is not affected by the coneOuterGain property (but the sound will still be affected by distance and other sound effects). A value of 360: indicates that the sound travels in any direction, that is, the sound can be heard in any direction. The cone model can refer to [here](https://developer.mozilla.org/zh-CN/docs/Web/API/Web_Audio_API/Basic_concepts_behind_Web_Audio_API#%E7%A9%BA%E9%97%B4%E4%BD% 8D%E7%BD%AE%E5%8C%96). For more information, please refer to here. |
| coneOuterAngle | Set the cone angle of the sound in the playback direction, in degrees. Outside the cone defined by this attribute, the volume will be reduced to a constant value defined by the coneOuterGain attribute. Value 360: means that the volume of the sound in any direction will not be reduced by the coneOuterGain property (but the sound will still be affected by distance and other sound effects). For more information, please refer to here. |
| coneOuterGain | Set the attenuation value of the sound outside the cone defined by the coneOuterAngle property. Note that this attribute value is unitless. Value 1: means no attenuation; value 0: means mute. For more information, please refer to here. |
| panningModel | Defines the algorithm used to calculate 3D spatial sound effects. For more information, please refer to here. |
| - equalpower | Equal power translation spatialization algorithm, simple and efficient, with less performance overhead. |
| - HRTF | A higher-quality spatialization algorithm that uses a convolution method to measure the impulse response of human subjects, which has a large performance overhead. |
| distanceModel | An algorithm model that defines the volume change with distance. For more information, please refer to here. |
| - inverse | With this option, the volume attenuation is greater at close distances, and the volume attenuation is lower at long distances. It is suitable for the following situations: It can be heard at a long distance, but when the listener is very close to the sound source, the volume will increase significantly. |
| - exponential | This algorithm is similar to inverse. When the rolloffFactor attribute value is greater than 1, the volume attenuation is faster than the inverse attenuation. When the rolloffFactor attribute value is less than 1, the volume attenuation is slower than the inverse attenuation. When the rolloffFactor attribute value is equal to 1, the volume attenuation is exactly the same as inverse. |
| - linear | With this option, the volume will decay linearly, so when the AudioListener approaches and moves away from the AudioSource, the volume change value will remain constant. This option is suitable for fade in and fade out between large background sound effects that do not need to be strictly focused on the 3D space attenuation setting. |
| rolloffFactor | This attribute is a factor in the algorithm defined by distanceModel. Describe the speed at which the volume decays when the AudioSource is far away from the AudioListener. When distanceModel=inverse or distanceModel=exponential, the value range of rolloffFactor is [0,∞). When distanceModel=linear, the value range of rolloffFactor is [0,1]. For more information, please refer to here. |
| minDistance | When the distance between AudioSource and AudioListener is less than this value, the volume is not attenuated due to the distance. If the distance is greater than this value, the sound starts to decay. For more information, please refer to here. Note: The minDistance here represents the refDistance attribute of W3C WebAudio PannerNode. |
| maxDistance | When the distance between AudioSource and AudioListener is greater than this value, the volume remains unchanged and no longer attenuates. For more information, please refer to here. |
# distanceModel distance model
Suppose d = the distance between AudioSource and AudioListener, d1 = minDistance, d2 = maxDistance, f = rolloffFactor, then the algorithm model of the volume change with distance is as follows.
| Type | Algorithm description |
|---|---|
| inverse | d1 / (d1 + f * (max(d, d1)-d1)). When d1=0, the algorithm result is 0. In this algorithm, the value range of f (ie rolloffFactor) is [0,∞). |
| exponential | Power( max(d, d1) / d1, -f), where Power is a power function. When d1=0, the result of this algorithm is 0. In this algorithm, the value range of f (ie rolloffFactor) is [0,∞). |
| linear | 1-f * (max( min(d, d4), d3)-d3) / (d4-d3), where d3 = min(d1, d2), d4 = max(d1, d2). When d3=d4, the result of the algorithm is 1-f. In this algorithm, the value range of f (ie rolloffFactor) is [0,1]. |
- inverse distance model diagram
Set minDistance=1, maxDistance=50, f=1, the line graph of volume changes with distance is as follows:
- exponential distance model diagram
Set minDistance=1, maxDistance=50, f=1, the line graph of volume changes with distance is as follows:
- Linear distance model diagram
Set minDistance=1, maxDistance=50, f=1, the line graph of volume changes with distance is as follows:
# Sound component
You can add sound effect component to the node where the AudioSource is located, so that the sound effect is used for all AudioSources of the node. The order of the sound effect components is important. As shown in the figure below: The sound emitted by AudioSource will be processed by AudioEcho first, then processed by AudioDistortion, and finally output to AudioMixer or AudioListener, depending on the configuration of the output attribute.
# Sound processing flow
When AudioSource is playing, the playback rate is adjusted by pitch, then the volume is adjusted by volume, and then the sound is routed to stereoPan two-channel sound effects and 3D spatial sound effects for processing. Note that stereoPan sound effects and 3D spatial sound effects are processed in parallel, and then mixed after processing. The degree of mixing depends on the value of spatialBlend. The mixed sound will be routed to all the nodes where AudioSource is located in order