Sound Groups

Introduction
SoundGroup is an optional utility class in Gaia. It is not compiled as part of the framework, so you need to import it when you want to use it.

com.gaiaframework.utils.SoundGroup



Overview
Inside the utils package is a class called SoundGroup. A Sound Group enables you to group sound assets together for group control, similar to bussing on a mixing board combined with group playback functionality including random, sequential and simultaneous. For example, if you want to have a few sound assets and want to control them as one entity, you use a Sound Group and control them together. Or, if you want to have one of a group of random sounds play on rollovers, you can use a Sound Group for that, as well.

SoundGroup treats SoundAssets and SoundClipAssets exactly the same. For the purpose of this document, anywhere you see SoundAsset can be interchanged with SoundClipAsset.



Adding Sound Assets to Sound Groups
When you instantiate a new SoundGroup, you pass the sound assets you want to be in that group.

import com.gaiaframework.utils.SoundGroup; mySoundGroup:SoundGroup = new SoundGroup(assets.music1, assets.music2, assets.music3);

You can optionally pass an assets object and it will filter only the SoundAssets:

import com.gaiaframework.utils.SoundGroup; mySoundGroup:SoundGroup = new SoundGroup(assets);

Finally, you can pass SoundAssets and asset objects in any order, as well. You can pass assets from different pages this way into the same Sound Group. Just make sure that every asset id is unique in a Sound Group.

You can add or remove individual Sound Assets to an existing group using addSound(sound:SoundAsset) and removeSound(sound:SoundAsset). SoundGroup prevents duplication by ignoring attempts to add sound assets which are already in the group (it also ignores attempts to remove sounds that are not in the group).



Baseline Volumes and Pans
When you add a SoundAsset to a SoundGroup, either at instantiation or after, its current volume is used as a baseline for its volume relative to the group. For instance, if you have three SoundAssets in a group with volumes of 100, 60, and 40 and you set the volume of the SoundGroup to 50, those SoundAssets would have their volumes set to 50, 30, and 20, respectively.

Similarly, each SoundAsset's pan is used as a baseline, as well, and the group's pan is used as an offset relative to its sounds' pans. For instance, if you have three SoundAssets in a group with pans of -50, 0, 50 and you set the pan of the SoundGroup to 25, those SoundAssets would have their pans set to -25, 25, and 75. SoundGroup makes sure that pans on individual sound assets will never be set above 100 or below -100.



Calibrate
The calibrate method is used to set the SoundGroup's volume back to 100 and pan back to 0 while leaving the current volumes and pans of its sound assets untouched. For instance, if you have 3 sounds with volumes 100, 60, and 40 and set the group volume to 50, those sounds will be 50, 30, and 20. If you call calibrate and then set the group's volume to 50 again, those sounds will be 25, 15, and 10.

One use for calibrate is if you want to directly set individual sound asset volumes after you've added them to a group. Set the individual asset volumes and call calibrate on the group and the group will use the current sound asset volumes as its baseline.

It is possible to assign sound assets to more than one sound group. Just keep in mind the above rules for baselines, volumes and pans as sound groups have no knowledge of eachother (unless you code one yourself).

For instance, if you put a sound asset with a volume of 80 in two groups and set the first group's volume to 50 and then set the second group's volume to 75, the sound asset will have a volume of 60 (75% of 80) because the baseline is what the sound was at when you put it in the second group.

If you set the volume of the first group to 50 and then call calibrate on the second sound group and set the volume of it to 75, the sound asset will have a volume of 30 (50% of 80 = 40, 75% of 40 = 30).



Setting and Fading Volumes and Pans
You can use setVolume(volume) and setPan(pan) to set the relative volumes and pans of all your SoundAssets in the group. Similarly, you can use fadeTo(target, time, [onComplete]) and panTo(target, time, [onComplete]) to fade or pan to the target value over time in seconds. You can optionally pass a callback function to be called when the fade or pan is complete. In AS2, it is recommended you pass a Delegate function as a callback.

The following example fades the volume of a sound group to 0 over 2 seconds and calls a function when it's completed.

AS2 import mx.utils.Delegate; mySoundGroup.fadeTo(0, 2, Delegate.create(this, onFadeOutComplete)); function onFadeOutComplete:Void {    trace("sound group has finished fading out"); }

AS3 mySoundGroup.fadeTo(0, 2, onFadeOutComplete); function onFadeOutComplete:void {    trace("sound group has finished fading out"); }



Playback Methods
There are a variety of ways to control playback of sounds in a SoundGroup.

play              Play all sounds at once. playNext          Play the next sound in sequential order playPrevious      Play the previous sound playRandom        Play the sounds randomly without repeating the same sound twice stop              Stops all Sounds in the SoundGroup pause(flag:Boolean) Pauses/unpauses all Sounds in the SoundGroup

playNext, playPrevious and playRandom all return the SoundAsset that the SoundGroup is playing. This is useful for displaying the asset title, for example.

Calling one of these playback methods will not stop a sound in the group that is already playing from continuing to play, resulting in the sounds layering on top of each other and themselves. You need to call stop on the SoundAsset or on the SoundGroup if you only want to play one sound at a time.

You can use stop to stop all sounds in a group, pause(true) to pause all sounds in the group, and pause(false) to unpause all sounds in the group (play from their last positions).



Synchronous Playback
If your SoundAssets are load on - demand assets, and you call play, it will preload all of the SoundAssets first. If they are all streaming assets, you can use the preload method to get them started, but keep in mind that the default limit of simultaneous HTTP requests is Windows is two, so depending on the size of the sounds, it might take a bit.

You can listen to the SoundGroup for the SoundGroupEvent.ALL_SOUNDS_LOADED event to know when all sounds have been preloaded.



Group Transforms
You can apply a single Sound Transform object to all sounds in a SoundGroup by using

AS2 setTransform(transformObject);

AS3 setTransform(transform:SoundTransform);



API
The following is an explanation of the API for Gaia's SoundGroup class.



new SoundGroup
new SoundGroup(sound1:SoundAsset, [sound2:SoundAsset], ...) When you instantiate a new SoundGroup, pass the assets you want to be in that group. Any number of SoundAssets can be added to a SoundGroup. You can also pass an assets object. You can pass in any combination of these, as well. Example: new SoundGroup(someAssetsObject, someSoundAsset, anotherSoundAsset, anotherAssetsObject);



addSound
addSound(sound:SoundAsset) Adds a SoundAsset to an existing SoundGroup.



removeSound
removeSound(sound:SoundAsset) Removes a SoundAsset from the SoundGroup.



calibrate
calibrate If you change the volumes or pans on individual SoundAssets after you instantiate a SoundGroup and you want their current volumes and pans to be the group's 100 volume and 0 pan, use this method, which will calibrate the SoundGroup to all of its SoundAssets.



preload
preload If your assets are set to not preload (such as streaming sounds or event sounds you want to wait to load), use this method to preload them all. This will get them ready for syncronized playback.



playRandom
playRandom(startTime:Number, loops:Number, repeat:Boolean):SoundAsset Plays a single SoundAsset from the SoundGroup at random, and will not repeat the same SoundAsset twice in a row unless you pass true as the third argument. If the SoundAsset is not loaded yet, it will load it and then play it immediately. This method returns the SoundAsset.



playNext
playNext(startTime:Number, loops:Number):SoundAsset Plays the next SoundAsset in the order they were added. If it's at the last asset, it plays the first one. If the SoundAsset is not loaded yet, it will load it and then play it immediately. This method returns the SoundAsset.

<br style="clear:both" />

playPrevious
playPrevious(startTime:Number, loops:Number):SoundAsset Plays the previous SoundAsset in the order they were added. If it's at the first asset, it plays the last one. If the SoundAsset is not loaded yet, it will load it and then play it immediately. This method returns the SoundAsset.

<br style="clear:both" />

play
play(startTime:Number, loops:Number) Play all sounds in the group at once. If the SoundAssets in the group are not loaded yet, it will load them all and then play them immediately.

<br style="clear:both" />

stop
stop Stop all sounds in the group.

<br style="clear:both" />

pause
pause(flag:Boolean) Pass true to pause and false to play all sounds in the group.

<br style="clear:both" />

fadeTo
fadeTo(value:Number, duration:Number, [onComplete:Function]) Fade the entire group to the value volume over duration in seconds. Pass a callback function if you want to be notified when the fade is complete. Volumes are relative to their individual volumes as a ratio of the group volume.

<br style="clear:both" />

panTo
panTo(value:Number, duration:Number, [onComplete:Function]) Pan the entire group to the value over duration in seconds. Pass a callback function if you want to be notified when the pan is complete. Pans are relative to their individual pans as an offset of the group pan.

<br style="clear:both" />

volume (AS3)
volume = value

In AS3, volume is a Number between 0 and 1.

setVolume / getVolume (AS2)
setVolume(value:Number) getVolume:Number

In AS2, value is a Number between 0 and 100.

volume and setVolume set the relative volume of all assets in the group to the group volume. For instance, if you have 3 assets with volumes of 100, 60, and 40 and you set the SoundGroup volume to 50, your assets will have volumes of 50, 30, and 20.

<br style="clear:both" />

pan (AS3)
pan = value

In AS3, value is a Number between -1 and 1.

setPan / getPan (AS2)
setPan(value:Number) getPan:Number

In AS2, value is a Number between -100 and 100.

pan and setPan offset the pan of all the assets in the group to the group pan. For instance, if you have 3 assets with pans of -50, 0, and 50 and you set the SoundGroup pan to 50, your assets will have pans of 0, 50, and 100. Pans will never go above 100 or below -100.

<br style="clear:both" />

setTransform
setTransform(transformObject:Object):Void   // AS2 setTransform(transform:SoundTransform):Void // AS3 Apply a single Sound Transform to all sounds in the group.

getTransform
getTransform:Object         // AS2 getTransform:SoundTransform // AS3 Get the current Sound Transform being applied to the group.

<br style="clear:both" />

index
index:Number // AS2 index:int // AS3 Getter only: Returns the current index of the SoundGroup.