Documentation

Unity Engine


User Manual

Script Reference

Unity Engine


AudioSource

A representation of audio sources in 3D.
Read time 11 minutesLast updated 2 days ago

Definition

  • Type: Class
  • Namespace: UnityEngine
  • Assembly: UnityEngine.AudioModule
  • Inherits from: AudioBehaviour
[RequireComponent(typeof(Transform))]public sealed class AudioSource : AudioBehaviour

Remarks

Attach an AudioSource to a GameObject to play back sounds in a 3D environment. To play 3D sounds you also need to have an AudioListener. Usually, you can find the audio listener attached to the camera in your scene. If you set AudioSource.spatialBlend to 0.0f, then Unity will treat the audio clip as a 2D sound. If you set it to 1.0f, the clip is fully 3D. Anything in between is a blend of 2D and 3D.
To play, pause, and stop a single audio clip, use AudioSource.Play, AudioSource.Pause and AudioSource.Stop. To adjust its volume while playing, use the AudioSource.volume property. Use AudioSource.time to seek through the audio track. To play multiple sounds on one AudioSource, use AudioSource.PlayOneShot. To play a clip at a static position in 3D space, use AudioSource.PlayClipAtPoint.

Examples

//This script allows you to toggle music to play and stop.//Assign an AudioSource to a GameObject and attach an Audio Clip in the Audio Source. Attach this script to the GameObject.using UnityEngine;public class Example : MonoBehaviour{ AudioSource m_MyAudioSource; //Play the music bool m_Play; //Detect when you use the toggle, ensures music isn’t played multiple times bool m_ToggleChange; void Start() { //Fetch the AudioSource from the GameObject m_MyAudioSource = GetComponent<AudioSource>(); //Ensure the toggle is set to true for the music to play at start-up m_Play = true; } void Update() { //Check to see if you just set the toggle to positive if (m_Play == true && m_ToggleChange == true) { //Play the audio you attach to the AudioSource component m_MyAudioSource.Play(); //Ensure audio doesn’t play more than once m_ToggleChange = false; } //Check if you just set the toggle to false if (m_Play == false && m_ToggleChange == true) { //Stop the audio m_MyAudioSource.Stop(); //Ensure audio doesn’t play more than once m_ToggleChange = false; } } void OnGUI() { //Switch this toggle to activate and deactivate the parent GameObject m_Play = GUI.Toggle(new Rect(10, 10, 100, 30), m_Play, "Play Music"); //Detect if there is a change with the toggle if (GUI.changed) { //Change to true to show that there was just a change in the toggle state m_ToggleChange = true; } }}

Properties

Property

Description

bypassEffectsBypass effects (Applied from filter components or global listener filters).
bypassListenerEffectsWhen set, global effects on the AudioListener doesn't apply to the audio signal generated by the AudioSource. It also doesn't apply, if the AudioSource is playing into a mixer group.
bypassReverbZonesWhen set, it doesn't route the signal from an AudioSource into the global reverb associated with reverb zones.
clipThe default AudioClip to play.
dopplerLevelSets the Doppler scale for this AudioSource.
gamepadSpeakerOutputTypeGets or sets the gamepad audio output type for this audio source.
ignoreListenerPauseAllows AudioSource to play even though
AudioListener.pause
is set to true. This is useful for the menu element sounds or background music in pause menus.
ignoreListenerVolumeThis makes the audio source not take into account the volume of the audio listener.
isPlayingReturns whether the AudioSource is currently playing an AudioResource(Read Only).
isVirtualTrue if all sounds played by the AudioSource, such as main sound started by Play() or playOnAwake, and one-shots are culled by the audio system.
loopChecks if the audio clip is looping
maxDistanceThe distance where sound either becomes inaudible or stops attenuation, depending on the rolloff mode.
minDistanceWithin the Min distance the AudioSource will cease to grow louder in volume.
muteUn- / Mutes the AudioSource. Mute sets the volume=0, Un-Mute restore the original volume.
outputAudioMixerGroupThe target group to which the AudioSource should route its signal.
panStereoPans a playing sound in a stereo way (left or right). This only applies to sounds that are Mono or Stereo.
pitchThe pitch of the audio source.
playOnAwakeEnable this property to automatically play the audio source when the component or GameObject becomes active.
prioritySets the priority of the AudioSource.
resourceThe default AudioResource to play.
reverbZoneMixThe amount by which the signal from the AudioSource will be mixed into the global reverb associated with the Reverb Zones.
rolloffModeSets/Gets how the AudioSource attenuates over distance.
spatialBlendSets how much this AudioSource is affected by 3D spatialisation calculations (attenuation, doppler etc). 0.0 makes the sound full 2D, 1.0 makes it full 3D.
spatializeEnables or disables spatialization.
spatializePostEffectsDetermines if the spatializer effect is inserted before or after the effect filters.
spreadSets the spread angle (in degrees) of a 3d stereo or multichannel sound in speaker space.
timePlayback position in seconds.
timeSamplesThe current playback position of the AudioSource in PCM samples.
velocityUpdateModeWhether the Audio Source should be updated in the fixed or dynamic update.
volumeThe volume of the audio source (0.0 to 1.0).

Methods

Method

Description

DisableGamepadOutputDisables audio output to a gamepad for this audio source.
GetAmbisonicDecoderFloatReads a user-defined parameter of a custom ambisonic decoder effect that is attached to an AudioSource.
GetCustomCurveGet the current custom curve for the given AudioSourceCurveType.
GetOutputDataProvides a block of the currently playing source's output data.
GetSpatializerFloatReads a user-defined parameter of a custom spatializer effect that is attached to an AudioSource.
GetSpectrumDataProvides the block of audio frequencies (spectrum data) of the AudioSource that is currently playing.
PausePauses playing the AudioSource.clip.
PlayPlays the AudioSource.clip.
PlayDelayedPlays the AudioSource.clip with a delay specified in seconds. Users are advised to use this function instead of the old Play(delay) function that took a delay specified in samples relative to a reference rate of 44.1 kHz as an argument.
PlayOneShotPlays an AudioClip, and scales the AudioSource volume by volumeScale.
PlayOnGamepadEnable the audio source to play through a specific gamepad.
PlayScheduledPlays the AudioSource.clip at a specific time on the absolute time-line that AudioSettings.dspTime reads from.
SetAmbisonicDecoderFloatSets a user-defined parameter of a custom ambisonic decoder effect that is attached to an AudioSource.
SetCustomCurveSet the custom curve for the given AudioSourceCurveType.
SetScheduledEndTimeChanges the time at which a sound that has already been scheduled to play will end. Notice that depending on the timing not all rescheduling requests can be fulfilled.
SetScheduledStartTimeChanges the time at which a sound that has already been scheduled to play will start.
SetSpatializerFloatSets a user-defined parameter of a custom spatializer effect that is attached to an AudioSource.
StopStops playing the AudioSource.clip.
UnPauseUnpause the paused playback of this AudioSource.

Static Methods

Method

Description

GamepadSpeakerSupportsOutputTypeCheck if the platform supports an audio output type on gamepads.
PlayClipAtPointPlays an AudioClip at a given position in world space.

Inheritance

Inherited Members

Operators

Operator

Description

operator ==Compares two object references to see if they refer to the same object.
boolDetermines whether the object exists.
operator !=Compares if two objects refer to a different object.