Recipe 13.14 Fading In a Sound

13.14.1 Problem

You want to fade in a sound from the beginning of playback over a span of a number of milliseconds.

13.14.2 Solution

Create and invoke a custom fadeIn( ) method.

13.14.3 Discussion

Although there is no built-in method for fading in sounds, you can create a custom method for the Sound class to handle this task. Our custom fadeIn( ) method, shown in the following code, accomplishes this by using an onEnterFrame( ) event handler method to monitor the position of the sound's playback and to set the volume accordingly. The fadeIn( ) method requires that the Sound object is created using our custom createNewSound( ) method from Recipe 13.1 because it uses the sound holder movie clip.

The fadeIn( ) method accepts up to six parameters:

millis

The number of milliseconds over which the sound should fade in

minVol

The volume percentage from which the sound should start to fade (defaults to the current volume or 0 if the current volume is 100)

maxVol

The volume percentage at which the sound fade should end (defaults to 100)

startFadeTime

The number of milliseconds from the beginning of the sound at which to begin the fade (defaults to 0)

startSound

A Boolean value that indicates whether to start the playback of the sound automatically

startPlayOffset

The number of milliseconds from the beginning of the sound at which to begin playback

Add the following custom fadeIn( ) method to an external Sound.as file for easy inclusion in other projects:

Sound.prototype.fadeIn = function (millis, minVol, maxVol, startFadeTime, 
                                   startSound, startPlayOffset) {

  // If the sound is already at 100% volume, set the volume to 0. That is, because
  // sounds default to 100% volume, we want to fade from 0 (unless minVol specifies
  // otherwise). By default, if the volume is not already 100%, fade up from the
  // current volume.
  if (this.getVolume(  ) == 100) {
    this.setVolume(0);
  }

  minVol = (minVol == undefined) ? this.getVolume(  ) : minVol;
  maxVol = (maxVol == undefined) ? 100 : maxVol;
  startFadeTime = (startFadeTime == undefined) ? 0 : startFadeTime;

  // If startSound is true, start the playback of the sound.
  if (startSound) {
    this.start(startPlayOffset/1000);
  }

  // Invoke the custom monitorFadeIn(  ) method every 100 ms. Pass it the parameters
  // needed to make the sound fade calculations.
  this.monitorFadeInInterval = setInterval(this, "monitorFadeIn", 
                       100, millis, minVol, maxVol, startFadeTime);
};

// Invoke this function periodically to monitor the sound fade.
Sound.prototype.monitorFadeIn = function (fadeInMillis, minVol, maxVol, 
                                          startFadeTime) {
  // Once the fade-in time is exceeded, make sure the maximum volume is reached and
  // clear the interval to end the fade.
  var pos = this.position;
  if (pos > fadeInMillis + startFadeTime) {

    // Make sure the volume is set to maximum before terminating the fade.
    this.setVolume(maxVol);
    clearInterval(this.monitorFadeInInterval);

    // Call the onFadeInStop(  ) callback function if one is defined.
    this.onFadeInStopPath[this.onFadeInStopCB](  );  
  }

  // Set the volume based on the current sound position, fading from minVol to maxVol 
  // over the specified time duration. Make sure the volume doesn't exceed maxVol 
  // accidentally.
  var volumePercent = Math.min(minVol + (pos - startFadeTime) / fadeInMillis *
                                (maxVol - minVol), maxVol);
  volumePercent = (volumePercent < 0) ? 0 : volumePercent;

  // Set the volume of the sound repeatedly to simulate a sound fade.
  this.setVolume(volumePercent);
};

// The setOnFadeInStop(  ) method allows you to define a callback function to invoke
// when the sound finishing fading in. The parameters are a string specifying the
// function name and an optional path to the function. If path is undefined, the
// Sound object's parent property is used instead. The parent property is defined
// only if you use the custom createNewSound(  ) method to create the sound.
Sound.prototype.setOnFadeInStop = function (functionName, path) {
  this.onFadeInStopPath = (path == undefined) ? this.parent : path;
  this.onFadeInStopCB = functionName;
};

Once defined, the fadeIn( ) method can be used to fade in any sound created using our custom createNewSound( ) method. You can use the fadeIn( ) method with sounds that were not created using the createNewSound( ) method, as long as you add a property named mc that is a reference to an empty movie clip. Also, notice that we've created a way to define a callback function for when the fade in stops (reaches the maximum volume).

Here is an example of how to use the fadeIn( ) method. Notice that the sound begins playback only if you start the sound with the start( ) method or pass the fadeIn( ) method a value of true for the startSound parameter.

#include "Sound.as"

mySound_sound = Sound.createNewSound(  );

// Attach a sound from the Library.
mySound_sound.attachSound("MySoundSymbol");

// Tell the sound to fade in over 5,000 milliseconds (5 seconds), starting from zero
// volume and going to 100%. Also, start the playback of the sound at three seconds
// into the sound and begin the fade at six seconds in.
mySound_sound.fadeIn(10000, 0, 100, 6000, true, 3000);

Optionally, you can also define a callback function for the fade in:

function onFadeInStop (  ) {
  trace("Sounded has faded in.");
}

mySound_sound.setOnFadeInStop("onFadeInStop");

13.14.4 See Also

Recipe 13.15