Beginning Audio Programming in AS3

Flash Player 10 introduced new low-level APIs for manipulating audio with AS3. In this tutorial, you’ll learn about these APIs and how they work, and use them to create a simple app that can play MP3s in reverse.

Click here to view a preview of the SWF we’ll be building in this tutorial. Click on the “Play” button to play the sound. You can’t really tell by looking at or listening to it, but this isn’t just an MP3 loaded and then played normally; the MP3 is being used as a sound source and samples are fed dynamically to the Sound engine. To help prove it, the “Reverse” button will play the same sound, just in reverse. There is no sleight of hand here: there is only one MP3 loaded and the reversal effect is computed on the fly.

Step 1: Playing Sound: The Olde Way

First, let’s make sure we’re up to speed on the pre-Flash 10 method of loading and playing an MP3. That is to say, this method still works in Flash 10 and up, but we’ll be exploring a more advanced and more powerful method in the remainder of the tutorial. If you are reading this tutorial for the specifics of the more advanced method, and feel you have a solid understanding of the traditional method, feel free to skip ahead to the step “Playing Sound: The Neue Way.”

The general method for this process is as follows:

Create a Sound object.
Load an MP3 file using the load method of the Sound object.
Once the MP3 loads, start playback by calling the play method.
When you call play, be sure to store the SoundChannel object you’ll get returned.
When/If you need to stop the sound, or adjust the volume or panning, call the appropriate methods on the SoundChannel object.

To start, let’s create a basic project.

Create a new ActionScript 3 FLA and save it to a project folder.
Create a document class to go along with the FLA. That is, create a new ActionScript 3.0 file, and save it as “TraditionalSound.as” in the same folder as your FLA.

If you need some class boilerplate, enter this into your new class file:

package {
    import flash.display.*;
    import flash.events.*;
    import flash.net.*;
    import flash.media.*;
    public class TraditionalSound extends Sprite {
        public function TraditionalSound() {
        }
    }
}

Next, we’ll walk through the five steps (outlined above) involved in loading and playing a sound.

Step 2: Creating a `Sound` Object

Create an instance property of type Sound in the class file:

package {

    import flash.display.*;
    import flash.events.*;
    import flash.net.*;
    import flash.media.*;

    public class TraditionalSound extends Sprite {

        private var _sound:Sound;

        public function TraditionalSound() {
        }
    }
}

And then instantiate it in the constructor.

public function TraditionalSound() {
    _sound = new Sound();
}

Step 3: Load an MP3 File

To load a file, call the load method of the Sound object and pass in a URLRequest that indicates the MP3 file to load.

public function TraditionalSound() {
    _sound = new Sound();
    _sound.load(new URLRequest("clip.mp3"));
    _sound.addEventListener(Event.COMPLETE, onSoundLoad);
}

private function onSoundLoad(e:Event):void {
    trace("sound loaded");
}

While we’re loading the sound, we may as well add the “complete” event listener. You can test the movie now, and assuming you’re pointing the load method at a valid MP3 file, you should see the trace as soon as it loads:

The Output panel displaying the trace once the sound loads

Also note that ideally you’ll hook up an IOErrorEvent.IO_ERROR event listener, as well, for the situation where the MP3 file fails to load.

Step 4: Start Playback

It is possible to start the playback of a Sound before it has fully loaded, but for our purposes we’ll stick with waiting until it has. So, in the onSoundLoad method, tell the Sound to play.

private function onSoundLoad(e:Event):void {
    _sound.play();
}

Test the movie now, and you should hear your sound.

Step 5: The `SoundChannel` Object

Now that you have sound playing, presumably you would like to further control it: stop it, adjust the volume, etc. If this is the first time you’ve worked with audio in flash, you may be surprised to learn that there is no stop method on the Sound object, nor is there any way to control the volume or pan once the Sound has started playing. Instead, there is a SoundChannel object that takes care of these functions. You create a SoundChannel object by calling Sound.play, which not only starts the playback of the audio but also returns the SoundChannel object that is the playing audio. So, first, we need a property in which to store the SoundChannel object:

public class TraditionalSound extends Sprite {

    private var _sound:Sound;
    private var _channel:SoundChannel;

Then we need to alter our playback code to store the SoundChannel object:

private function onSoundLoad(e:Event):void {
    _channel = _sound.play();
}

Now we can control the playing sound. For example, let’s make a click on the stage stop the audio (most of the class code is listed below for reference; the new code is highlighted).

public class TraditionalSound extends Sprite {

    private var _sound:Sound;
    private var _channel:SoundChannel;

    public function TraditionalSound() {
        _sound = new Sound();
        _sound.load(new URLRequest("clip.mp3"));
        _sound.addEventListener(Event.COMPLETE, onSoundLoad);
        stage.addEventListener(MouseEvent.CLICK, onClick);
    }

    private function onSoundLoad(e:Event):void {
        _channel = _sound.play();
    }

    private function onClick(e:MouseEvent):void {
        _channel.stop();
    }
}

As another example, we’ll make moving the mouse around control the volume and pan. The pan will be adjusted depending where the mouse is on the horizontal axis, and the volume will be on the vertical axis, with the bottom being muted. We just need to add a mouse move listener. In the constructor:

public function TraditionalSound() {
    _sound = new Sound();
    _sound.load(new URLRequest("clip.mp3"));
    _sound.addEventListener(Event.COMPLETE, onSoundLoad);
    stage.addEventListener(MouseEvent.CLICK, onClick);
    stage.addEventListener(MouseEvent.MOUSE_MOVE, onMove);
}

And the listener itself:

private function onMove(e:MouseEvent):void {
    var volume:Number = 1 - (e.stageY / stage.stageHeight);
    var pan:Number = (e.stageX / (stage.stageWidth/2)) - 1;
    _channel.soundTransform = new SoundTransform(volume, pan);
}

The math is a little wild, but it just turns the mouse position into numbers that can be used for volume and pan. Volume can be from 0 to 1, and pan from -1 to 1. Those get fed into a SoundTransform object, which can then be set in the SoundChannel.

Now, you may be wondering why you need one object to play the sound and another to control the sound. It is a little confusing at first, but the setup allows you to have a single Sound object, that is, an audio source, and play it multiple times in multiple ways. For simply playing back a song, that’s not overly useful, but imagine providing sounds for a game. If you had a sound for hitting an enemy, this sound might need to be played back many times, perhaps overlapping itself, and with separate volume and pan depending on where on the screen the hit happened. By playing back a single Sound into multiple SoundChannels, you have this kind of control, but without the need to re-create the audio source every time.

For our purposes, we won’t be getting that involved, but you do need to understand the relationship between Sound and SoundChannel objects.

Step 6: Playing Sound: The Neue Way

Now that we’ve had a crash course in how to load and play a sound the standard way, we’ll start looking at how to play a sound with the new method introduced in Flash Player 10. Our approach will first include a bit of Flash folklore, and then involve some general digital audio theory. Next we’ll create the skeleton of the project for us to work in, and then spend the rest of our time on an incremental approach to writing the code, with generous explanation woven in.

A bit of history. The geniuses behind the hobnox audiotool*, namely André Michelle and Joa Ebert, were going where no Flash-based audio application had gone before, and required a more dynamic method of creating audio on the fly. While they managed to make happen in Flash Player 9, they were fed up with the less-than-powerful audio implementation in Flash. They founded a site called make-some-noise.info that was a community-powered plea to get Adobe to add audio features to Flash.

Amazingly, not only did Adobe listen, but they delivered in a matter of months, and released some previously-unexpected features with Flash Player 10. The good news is that we now have some fairly advanced tools available to us for audio manipulation. The bad news is that it really is just a small set of fairly low-level APIs that, while powerful, are just the building blocks upon which you’ll need to add your own ingenuity and elbow grease. But that’s what this tutorial is about, so you’re covered.

(The Adobe Make Some Noise campaign is no longer around, but you can still read the posts on make-some-noise.info, as well as a series of blog posts by Tinic Uro, who is a developer at Adobe working on the Flash Player. In these posts he responds to Adobe Make Some Noise on behalf of Adobe, and provides some interesting insight to the situation as well as a look some of the first code samples. There are three posts, adding up to a good dose of information, but not too lengthy of a read. Part 1, Part 2, and Part 3.)

* Just a personal aside: The audiotool is by far the most impressive Flash piece I have ever seen.