Loading external sound files

If you are loading a small sound file, such as a click sound to be attached to a button, your application can create a Sound and have it automatically load the sound file, as the following example shows:

var req = new air.URLRequest("click.mp3"); 
var s = new air.Sound(req);

The Sound() constructor accepts a URLRequest object as its first parameter. When a value for the URLRequest parameter is supplied, the new Sound object starts loading the specified sound resource automatically.

In all but the simplest cases, your application should pay attention to the sound’s loading progress and watch for errors during loading. For example, if the click sound is fairly large, the application may not completely load it by the time the user clicks the button that triggers the sound. Trying to play an unloaded sound could cause a run-time error. It’s safer to wait for the sound to load completely before letting users take actions that can start sounds playing.

A Sound object dispatches a number of different events during the sound loading process. Your application can listen for these events to track loading progress and make sure that the sound loads completely before playing. The following table lists the events that the Sound object is able to dispatch:

The following code illustrates how to play a sound after it has finished loading:

var s = new air.Sound(); 
s.addEventListener(air.Event.COMPLETE, onSoundLoaded); 
var req = new air.URLRequest("bigSound.mp3"); 
s.load(req); 
 
function onSoundLoaded(event) 
{ 
    var localSound = event.target; 
    localSound.play(); 
}

First, the code sample creates a new Sound object without giving it an initial value for the URLRequest parameter. Then, it listens for the complete event from the Sound object, which causes the onSoundLoaded() method to execute when all the sound data is loaded. Next, it calls the Sound.load() method with a new URLRequest value for the sound file.

The onSoundLoaded() method executes when the sound loading is complete. The target property of the Event object is a reference to the Sound object. Calling the play() method of the Sound object then starts the sound playback.

Sound files can be large and take a long time to load, especially if they are loaded from the Internet. An application can play sounds before they are fully loaded. You might want to give the user an indication of how much of the sound data has been loaded and how much of the sound has already been played.

The Sound class dispatches two events that make it relatively easy to display the loading progress of a sound: progress and complete . The following example shows how to use these events to display progress information about the sound being loaded:

var s = new Sound(); 
s.addEventListener(air.ProgressEvent.PROGRESS, 
    onLoadProgress); 
s.addEventListener(air.Event.COMPLETE,  
    onLoadComplete); 
s.addEventListener(air.IOErrorEvent.IO_ERROR,  
    onIOError); 
 
var req = new air.URLRequest("bigSound.mp3"); 
s.load(req); 
 
function onLoadProgress(event) 
{ 
    var loadedPct = Math.round(100 * (event.bytesLoaded / event.bytesTotal)); 
    air.trace("The sound is " + loadedPct + "% loaded."); 
} 
 
function onLoadComplete(event) 
{ 
    var localSound = event.target; 
    localSound.play(); 
} 
function onIOError(event) 
{ 
    air.trace("The sound could not be loaded: " + event.text); 
}

This code first creates a Sound object and then adds listeners to that object for the progress and complete events. After the Sound.load() method has been called and the first data is received from the sound file, a progress event occurs, and triggers the onSoundLoadProgress() method.

The fraction of the sound data that has been loaded is equal to the value of the bytesLoaded property of the ProgressEvent object divided by the value of the bytesTotal property. The same bytesLoaded and bytesTotal properties are available on the Sound object as well.

This example also shows how an application can recognize and respond to an error when loading sound files. For example, if a sound file with the given filename cannot be located, the Sound object dispatches an ioError event. In the previous code, the onIOError() method executes and displays a brief error message when an error occurs.