Sound Groups

From Gaia Framework Wiki

Contents 1 Introduction 2 Overview 3 Adding Sound Assets to Sound Groups 4 Baseline Volumes and Pans 5 Calibrate 6 Setting and Fading Volumes and Pans 7 Playback Methods 8 Synchronous Playback 9 Group Transforms 10 API 10.1 new SoundGroup 10.2 addSound 10.3 removeSound 10.4 calibrate 10.5 preload 10.6 playRandom 10.7 playNext 10.8 playPrevious 10.9 play 10.10 stop 10.11 pause 10.12 fadeTo 10.13 panTo 10.14 volume (AS3) 10.15 setVolume / getVolume (AS2) 10.16 pan (AS3) 10.17 setPan / getPan (AS2) 10.18 setTransform 10.19 getTransform 10.20 index

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.

---

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.

---

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.

---

stop

stop()

Stop all sounds in the group.

---

pause

pause(flag:Boolean)

Pass true to pause and false to play all sounds in the group.

---

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.

---

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.

---

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.

---

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.

---

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.

---

index

index:Number // AS2
index:int // AS3

Getter only: Returns the current index of the SoundGroup.