AudioController Class

ClockStone Audio Toolkit

previous page next page

ClockStone Audio Toolkit for Unity - Documentation

AudioController Class

The audio managing class used to define and play audio items and categories.

Inheritance Hierarchy

SystemObject  Object
    Component
      Behaviour
        MonoBehaviour
          (Default Namespace)SingletonMonoBehaviourAudioController
            (Default Namespace)AudioController

Namespace: (Default Namespace)
Assembly: AudioToolkit (in AudioToolkit.dll) Version: 8.2.0.0 (8.2.0.0)

Syntax

Copy

public class AudioController : SingletonMonoBehaviour<AudioController>, 
	ISerializationCallbackReceiver

The AudioController type exposes the following members.

Constructors

	Name	Description
	AudioController	Initializes a new instance of the AudioController class

Top

Properties

	Name	Description
	ambienceSoundCrossFadeTime_In	Specifies a specific fade-in time for ambience sound cross fading. Only meaningful if specifyCrossFadeInAndOutSeperately is enabled.
	ambienceSoundCrossFadeTime_Out	Specifies a specific fade-out time for ambience sound cross fading. Only meaningful if specifyCrossFadeInAndOutSeperately is enabled.
	ambienceSoundEnabled	Gets or sets the ambienceSoundEnabled.
	DisableAudio	Disables all audio playback.
	isAdditionalAudioController	You may use several AudioControllers in the same scene in parallel. All but one (the main controller) must be marked as 'additional'. You can play audio items of any of those controllers with the normal Play() calls.
	isSingletonObject	returns true if the AudioController is the main controller (not an additional controller) (Overrides SingletonMonoBehaviourTisSingletonObject.)
	musicCrossFadeTime_In	Specifies a specific fade-in time for music cross fading. Only meaningful if specifyCrossFadeInAndOutSeperately is enabled.
	musicCrossFadeTime_Out	Specifies a specific fade-out time for music cross fading. Only meaningful if specifyCrossFadeInAndOutSeperately is enabled.
	musicEnabled	Gets or sets the musicEnabled.
	soundMuted	Gets or sets the soundMuted.
	systemDeltaTime	Returns the high precision audio system delta time since the last frame update.
	systemTime	Returns the high precision audio system time size the application launch.
	Volume	The global volume applied to all categories. You change the volume by script and the change will be apply to all playing audios immediately.

Top

Methods

	Name	Description
	AddPlaylist	Adds a new playlist.
	AddToCategory(AudioCategory, AudioItem)	Adds a custom audio item to a category.
	AddToCategory(AudioCategory, AudioClip, String)	Creates an AudioItem with the name audioID containing a single subitem playing the specified custom AudioClip. This AudioItem is then added to the specified category.
	ClearPlaylists	Clears all music playlist.
	DetachAllAudios	Detaches all audio objects possibly parented to the specified game object.
	EnableAmbienceSound	Enables the ambience sound.
	EnableMusic	Enables the music.
	EnqueueMusic	Enqueues an audio ID to the music playlist queue.
	FadeInCategory	Starts a fade-in of an audio category.
	FadeOutCategory	Starts a fade-out of an audio category.
	GetAudioItem	Returns the AudioItem with the given audioID.
	GetAudioItemMaxDistance	Gets the audio item's max distance. (respects all proper default values and overwrites).
	GetCategory	Gets a category.
	GetCategoryVolume	Gets the category volume.
	GetCurrentAmbienceSound	Gets the current ambience sound.
	GetCurrentAudioListener	Gets the currently active Unity audio listener.
	GetCurrentMusic	Gets the current music.
	GetGlobalVolume	Gets the global volume.
	GetMusicPlaylist	If playlistName == null then gets a copy of the current playlist audioID array, otherwise gets a copy of the playlist with the specified name
	GetPlayingAudioObjects(Boolean)	Returns an array of all playing audio objects.
	GetPlayingAudioObjects(String, Boolean)	Returns an array of all playing audio objects with the specified audioID.
	GetPlayingAudioObjectsCount	Returns the number of all playing audio objects with the specified audioID.
	GetPlayingAudioObjectsInCategory	Returns an array of all playing audio objects in the category with name categoryName.
	GetPlaylistByName	Retrieves a playlist by name. If playlists are named identically it will return the first one it finds
	InitializeAudioItems	Updates the internal audioID dictionary and initializes all registered AudioItem objects.
	IsAmbienceSoundEnabled	Determines whether ambience sound is enabled.
	IsAmbienceSoundPaused	Uses to test if ambience sound is paused
	IsMusicEnabled	Determines whether music is enabled.
	IsMusicPaused	Uses to test if music is paused
	IsPlaying	Determines whether the specified audio ID is playing.
	IsPlaylistPlaying	Determines whether the playlist is playing.
	IsSoundMuted	Determines whether sound is muted
	IsValidAudioID	Tests if a given audioID is valid.
	MuteSound	Mutes / Unmutes the sound.
	NewCategory	Creates a new audio category
	OnAfterDeserialize
	OnBeforeSerialize
	PauseAll	Pauses all playing audio items (including the music).
	PauseAmbienceSound	Pauses the currently playing ambience sound.
	PauseCategory	Pauses all playing audio items in the specified category (including the music).
	PauseMusic	Pauses the currently playing music.
	Play(String)	Plays an audio item with the name audioID.
	Play(String, Transform)	Plays an audio item with the name audioID parented to a specified transform.
	Play(String, Vector3, Transform)	Plays an audio item with the name audioID parented to a specified transform with a world offset.
	Play(String, Single, Single, Single)	Plays an audio item with the name audioID.
	Play(String, Transform, Single, Single, Single)	Plays an audio item with the name audioID parented to a specified transform.
	Play(String, Vector3, Transform, Single, Single, Single)	Plays an audio item with the name audioID parented to a specified transform with a world offset.
	PlayAfter	Plays an audio item with the name audioID right after the given AudioObject stops playing. (see the Unity AudioSettings.dspTime documentation)
	PlayAmbienceSound(String, Single, Single, Single)	Plays an audio item with the name audioID as ambience sound.
	PlayAmbienceSound(String, Transform, Single, Single, Single)	Plays an audio item with the name audioID as ambience sound at the specified position.
	PlayAmbienceSound(String, Vector3, Transform, Single, Single, Single)	Plays an audio item with the name audioID as ambience sound at the specified position.
	PlayAudioItem	Plays a specific AudioItem.
	PlayAudioSubItem	Plays a specific AudioSubItem.
	PlayMusic(String, Single, Single, Single)	Plays an audio item with the name audioID as music.
	PlayMusic(String, Transform, Single, Single, Single)	Plays an audio item with the name audioID as music at the specified position.
	PlayMusic(String, Vector3, Transform, Single, Single, Single)	Plays an audio item with the name audioID as music at the specified position.
	PlayMusicPlaylist	Start playing the music playlist.
	PlayNextMusicOnPlaylist	Jumps to the next the music track on the playlist.
	PlayPreviousMusicOnPlaylist	Jumps to the previous music track on the playlist.
	PlayScheduled	Plays an audio item with the name audioID parented to a specified transform with a world offset scheduled at a specified high precision DSP time (see the Unity AudioSettings.dspTime documentation)
	RemoveAudioItem	Removes an AudioItem from the AudioController.
	RemoveCategory	Removes an audio category.
	SetCategoryVolume	Changes the category volume. Also effects currently playing audio items.
	SetCurrentMusicPlaylist	Sets the current playlist to the specified audioID array
	SetGlobalVolume	Changes the global volume. Effects all currently playing audio items.
	Stop(String)	Stops all playing audio items with name audioID.
	Stop(String, Single)	Stops all playing audio items with name audioID with a fade-out.
	StopAll	Immediately stops playing audio items (including the music).
	StopAll(Single)	Fades out all playing audio items (including the music).
	StopAmbienceSound	Stops the currently playing ambience sound.
	StopAmbienceSound(Single)	Stops the currently playing ambience sound with fade-out.
	StopCategory	Stops all playing audio items in the specified category (including the music).
	StopMusic	Stops the currently playing music.
	StopMusic(Single)	Stops the currently playing music with fade-out.
	UnloadAllAudioClips	Unloads all AudioClips specified in this AudioController from memory.
	UnpauseAll	Un-pauses all playing audio items (including the music).
	UnpauseAmbienceSound	Unpauses the current ambience sound.
	UnpauseCategory	Un-pauses all playing audio items in the specified category (including the music).
	UnpauseMusic	Unpauses the current music.

Top

Fields

	Name	Description
	_currentInspectorSelection
	ambienceSoundCrossFadeTime	If set to a value > 0 (in seconds) music will automatically be cross-faded with this fading time.
	AUDIO_TOOLKIT_VERSION	A string containing the version number of the Audio Toolkit
	AudioCategories	Specify your audio categories here using the Unity inspector.
	AudioObjectPrefab	You must specify your AudioObject prefab here using the Unity inspector. AudioObjectAudioSource (Unity built-in)PoolableObject - only required if pooling is uses
	crossfadePlaylist	if enabled, the tracks on the playlist will get cross-faded as specified by musicCrossFadeTime
	delayBetweenPlaylistTracks	Mute time in between two tracks on the playlist.
	EqualPowerCrossfade	If enabled fading is adjusted in a way so that cross-fades should result in the same power during the time of fadeing
	loopPlaylist	specifies if the music playlist will get looped
	musicCrossFadeTime	If set to a value > 0 (in seconds) music will automatically be cross-faded with this fading time.
	musicPlaylist	Obsolete. For backwards compatibility we still keep the old playlist system, its items will be copied over to the Default Playlist and then cleared
	musicPlaylists	allows to specify a list of named playlist that can be played as music
	Persistent	If enabled, the audio controller will survive scene changes
	PlayWithZeroVolume	If disabled, audios are not played if they have a resulting volume of zero.
	shufflePlaylist	enables / disables shuffling for the music playlist
	specifyCrossFadeInAndOutSeperately	If enabled specific music and ambience sound cross-fading in and out times can be specified with musicCrossFadeTime_In and musicCrossFadeTime_Out respectively ambienceSoundCrossFadeTime_In and ambienceSoundCrossFadeTime_Out
	UnloadAudioClipsOnDestroy	If enabled all audio resources (AudioClips) specified in this AudioController are unloaded from memory when the AudioController gets destroyed (e.g. when loading a new scene and Persistent is not enabled)
	UsePooledAudioObjects	Enables / Disables AudioObject pooling

Top

Remarks

At least one instance of an AudioController must exist in each scene using the Audio Toolkit. Usually there is exactly one controller, but you can have additional controllers if they are marked as such (in the Unity insepector, see isAdditionalAudioController) There a two options when setting up an AudioController. Either you can specify all audio files that are used in your entire project in one single AudioController. Then add this AudioController to your initial scene and set it persistent from within the inspector, so it will survive when a new scene is loaded. This way all audios are accessible from within your entire application. If you have a lot of audio files though, this may lead to a lengthy loading time and will have a rather large memory footprint. To avoid this, you can alternatively set up a specific AudioController for each scene which only contains those audio files needed in the particular scene.

Examples

Once you have defined your audio categories and items in the Unity inspector you can play music and sound effects very easily:

Copy

AudioController.Play( "MySoundEffect1" );
AudioController.Play( "MySoundEffect2", new Vector3( posX, posY, posZ ) );
AudioController.PlayMusic( "MusicTrack1" );
AudioController.SetCategoryVolume( "Music", 0.5f );
AudioController.PauseMusic();

Reference

(Default Namespace) Namespace

Send comments on this topic to ClockStone Support Email

previous page start next page