# Chapter 18

# Shockwave for Audio

CONTENTS

- What Is Streaming?
- Compressing Audio for Shockwave
  - Compressing Sounds Embedded in Director
  - Creating Streamable Audio Files
- Controlling the Streaming Files in Director
  - Set the URL of the SWA Cast Member
  - Playing, Stopping, and Pausing the Streaming Audio
  - Preloading
  - The State of the Streaming File
  - Checking the Duration and Percentages of an SWA File
  - Checking the Bit Rate of an SWA File
  - Checking Errors with the SWA File
- A Streaming Audio Example
  - Collecting the Pieces
  - Assembling in Director
  - Afterburner and Embedding the Movie
- From Here…

Two weeks after the first draft of this book was finished, Macromedia made public a new Shockwave development: audio compression and streaming. Very typical of the newfangled computer world, it's hard to keep up, but we have done our best to include the absolute latest possible information for you. This chapter presents the processes of including compressed audio and streaming audio in your Shockwave Web pages. This is a powerful addition to Shockwave in an area that previously was quite limited. Here's what you can expect from this chapter:

- Defines new terms and describes the process of streaming over the Internet.
- Shows you how to compress the audio files embedded within your Director movie.
- Shows how to create your own compressed audio files using Macromedia's Sound Edit 16 software.
- Describes the new Lingo used to control the streamed audio.
- Includes an example of a Shockwave "Music Stereo" to show you exactly how this process works.

## What Is Streaming?

Ever tried to build a brick wall? Me neither, but it works well for an analogy. You can't build the whole thing at once; instead, you put one brick on at a time. Going bit by bit, the whole wall is eventually built. This is the principle of streaming.

You may remember this concept if you read the chapter about Shockwave for Authorware, because it uses the process of streaming. The way a normal Shockwave for Director movie works is to download the entire movie across the Internet, then play it within your browser. In earlier versions of Shockwave, all sound files needed to be included within the movie. So if the movie contained a 60K audio clip, the whole thing would need to be loaded before it could be played.

What streaming does is separate the sound file from the rest of the Shockwave movie. Then it breaks the sound file into little pieces that can be loaded a little bit at a time as needed. You obviously can't listen to an entire three-minute song at once, so streaming allows Shockwave to load only a few seconds at a time for seemingly real-time audio. It starts by loading a few seconds as a buffer, then immediately plays those few seconds while more data is loaded.

Previously, a three-minute song was out of the question for Shockwave because few people would be willing to wait that long to hear it. But with the process of streaming, the user is occupied listening to the music (and possibly interacting with the rest of the movie or Web page) as the audio information is slowly loading in the background. You could potentially have megabytes of audio data, but if the user is enjoying the music, he or she will hardly notice that it's downloading.

## Compressing Audio for Shockwave

There are really two enhancements that Shockwave can offer to audio. We have mentioned streaming already, which is a separate compressed audio file that is loaded by the Shockwave movie. The other feature is compressed sound within the Director movie. Where Afterburner previously compressed only graphics and other elements, it will now compress the audio cast members embedded within the movie. For shorter sound clips, this is very beneficial because you may want immediate access to the sounds instead of a delay that results from streaming.

Note
Be sure you have the latest version of the Shockwave plug-in and Afterburner installed. If you don't, you will soon be lost because you won't have certain extras this chapter refers to that are installed in Director, SoundEdit 16, or your browser.

### Compressing Sounds Embedded in Director

This audio compression feature only works with version 5 of Director. The SWA Compression Xtra is included with Afterburner to offer controls for the compression of audio cast members (it will automatically be added to your Xtras menu when you install Afterburner for Director 5). Figure 18.1 shows the available features when you select "Shockwave for Audio Settings" from the Xtras menu.

Figure 18.1 : Options using the Shockwave for Audio Xtra.

Of course, if you have no audio imported as cast members, this doesn't make any difference to your movie. But with audio cast members you have several options from the Xtra menu.

First, you can choose to disable the audio compression. Why you would want to disable it I don't know, but you may have your reasons-troubleshooting, perhaps.

Another option is bit rate. This determines the quality and final size of the compressed audio. A higher setting produces larger files that are higher in quality. Lower settings compress the audio more, but may lose some quality. For most sound effects, you may find that you can't tell much difference in quality, but the choice is up to you. I did a small test on compression rates and found the following. An original Director movie of 164K contained a sound clip recorded at 22.050 kHz and 16 bits that was 156K within the cast. Choosing 160 as the bit rate resulted in a compressed .DCR file of 79.3K, and choosing a bit rate of 32 compressed the file to a final .DCR size of 18.5K. The higher rate did sound better, but the low-bit rate did not sound too bad considering the incredible reduction in file size.

The menu gives the option of normal or high accuracy in the audio compression. While the higher accuracy is claimed to take longer processing time, I have found Afterburner to be a very fast conversion anyway.

Finally, you may choose to automatically convert stereo sounds to mono. Stereo sounds are twice as large as mono sounds, so this is usually a good practice if your imported audio is not already mono. Setting the bit rate to 32 will automatically convert stereo sounds to mono.

That's all there is to the SWA Compression Xtra. Once you have the settings the way you like them, the Afterburner Xtra will automatically compress all embedded audio to your specifications. You don't need to input these settings every time; your choices will remain as defaults.

### Creating Streamable Audio Files

We are about to deliver some bad news to Windows users. To create the compressed files to be streamed you must use SoundEdit 16, a software package developed by Macromedia only for the Macintosh (figure 18.2). I'm sure many Macintosh users are leaping with glee at the chance to be one up on Windows (something that isn't too common lately due to the vast number of Windows users) but I wouldn't be surprised to see the arrival of either SoundEdit 16 for Windows or a similar program developed to allow Windows users to create streamable audio files.

Figure 18.2 : SoundEdit 16 for Macintosh.

There are two Xtras for SoundEdit 16 that are also included with Afterburner. The SWA Export Xtra actually does the compressing and exporting, and the SWA Settings Xtra gives you control of the compression settings. Both are put into SoundEdit 16's Xtras folder. The plug-ins allow you to take a standard audio file from SoundEdit 16 and export it in a new format with the extension .SWA which is compressed to reduce download time for streaming over the Web.

In SoundEdit 16, begin by opening the audio file that you wish to export. Macromedia recommends you work with 22.050 kHz files, though you may use 44.100 kHz files also. If they are already 8-bit or 11.025 kHz files, they should be upsampled to 16-bit and 22.050 kHz for exporting. Note that an 11 kHz stereo file will automatically be converted to mono when exported.

From the Xtras menu, choose "Shockwave for Audio Settings" to control the options for the SWA file (figure 18.3). The settings are similar to those in the Director Xtra. You will need to select a bit rate for the streamable file. Keep your target audience in mind when selecting a bit rate. Lower rates should be used for modem users over the Internet, while higher bit rates can be used for T1 lines or Intranet projects.

Figure 18.3 : Using the Shockwave for Audio Xtra in SoundEdit 16.

Macromedia offers the following suggestions for bit rates (see table 18.1):

Table 18.1 Bit Rates for Streamable Audio Files

Bit Rate | Intended Audience
64 Kbps-128 Kbps | T1 connection
32 Kbps-56 Kbps | ISDN line
16 Kbps | 28.8 modem
8 Kbps | 14.4 modem

You have the option of converting stereo audio files to mono when exporting. Like the Director Xtra, a bit rate of 32 or less automatically converts to mono. When the settings are chosen, press "OK" to close the settings box. Before exporting, you should close the Levels palette if it is open.

From the file menu, choose Export and select .SWA File from the "export type" menu. Enter a file name and choose Save to export the file. The settings you chose earlier will be used as the new SWA file is created. Pretty simple. The file is now ready to be uploaded to the server and streamed by the Shockwave movie.

## Controlling the Streaming Files in Director

So, you have an SWA file all ready to stream across the Web. This section describes how to import and control the SWA file in your Shockwave movie. Director 5 uses yet another Xtra for this purpose. (Don't worry, all of these Xtras are automatically put where they should be.) This one is called the SWA Streaming Xtra.F file in the cast.

Before you are confused, we are not embedding the actual SWA file, we are simply inserting a cast member that is the SWA type. It is sort of like a linked media element, though we control the reference through Lingo.

From the Insert menu in Director, choose "Other," then "SWA Streaming Xtra." This will place a new type of cast member in an available position. This is somewhat abstract because the cast member is not really referencing the actual SWA file, it is just a generic cast member type. You will want to name this cast member to refer to it easily through Lingo. Editing the cast member properties (the "i" button) brings up an options box that really has no options except for the member name (figure 18.4). You may also enter the name directly in the cast member window in the name space.

Figure 18.4 : Naming the SWA Streaming cast member.

You will soon see how easy it is to control the SWA cast member through Lingo. We begin with the basic commands, then cover some additional available features.

### Set the URL of the SWA Cast Member

When you insert an SWA Streaming cast member, it has no reference to tell it what SWA file to play. By setting the URL, you give a specific location and file name for the SWA file. You may include an entire HTTP address, or just the file name if the SWA file will be located in the same directory as the Shockwave movie. To do this, you use the Lingo term: `URL of member` "`name`." For example:

>     set the URL of member "mysong" = "http://www.pdgroup.com/shock/
>     music.swa"

The above Lingo statement would set the URL of the SWA cast member named "mysong" to the HTTP address of the actual SWA file, called music.swa.

Caution
It is important that you type the exact URL address correctly. Many servers may not allow file names longer than eight characters plus the extension and the names may be case-sensitive.

You only need to have one SWA cast member because you can't stream more than one sound at a time. By controlling the URL through Lingo, you may have more than one possible SWA file that can be referenced by the SWA cast member. The user may press different buttons in the Shockwave movie that set the SWA cast member's URL to play different sound files over the Web.

### Playing, Stopping, and Pausing the Streaming Audio

The commands for playing, stopping, and pausing could not be simpler than they are. The syntax is as follows:

>     play (member "name")
>     pause (member "name")
>     stop (member "name")

Let's say I have an SWA cast member that I have named "long music" and I have already set the URL of the member. I may have a play button with the following script attached:

>     on mouseup
>        play (member "long music")
>     end

Other buttons could be scripted to pause or stop the music in the same way using the other two commands. When an SWA file is paused, it freezes the song until the `play` command is again initiated. The `stop` command ends the streaming, and a subsequent `play` command will restart the audio file from the beginning.

### Preloading

Preloading is a way of protecting the streaming file from breaking up. Preloading for five seconds, for example, loads five seconds of the sound before the Shockwave movie begins playing it. By giving it a head start, you have a buffer so that if the network connection slows down, there's still audio information to play and the sound doesn't stop. Playing a streaming SWA file automatically preloads a small amount without specifying, but you can choose to determine when and how much is preloaded using Lingo commands.

The following Lingo sets the amount of time that is preloaded in seconds:

>     set the preloadtime of member "name" = number of seconds

Then, I may even begin preloading before the play command is given. This way, a few seconds could be loaded when the movie starts so that the sound begins immediately when the user clicks a button to play it. To start preloading without playing, use the `preloadbuffer` command. The syntax is as follows:

>     Preloadbuffer (member "name")

So a specific example might look like this, where "songfile" is the name of the SWA cast member I want to preload for 8 seconds:

>     on exitframe
>        set the preloadtime of member "songfile" = 8
>        preloadbuffer (member "songfile")
>     end

### The State of the Streaming File

At any time, you may check the state of a streaming SWA file. This will tell you if the file is playing, preloading, stopped, and so on. To check this state, use the Lingo: state of member "name." The result is returned as an integer that is translated in table 18.2. If the value is 3, for example, the file is playing. The following handler puts a message in a field if the sound is playing.

>     on ckeckplay
>        if the state of member "mysong" = 3 then put "Now playing the
>     song." into field "songstatus"
>     end

Table 18.2 contains the possible results of the state function.

Table 18.2 Possible Code Results of the State of a Streaming File

Value | Returned Meaning
0 | stopped
1 | preloading
2 | preloading finished
3 | playing
4 | paused
5 | done
9 | error

### Checking the Duration and Percentages of an SWA File

Lingo commands are provided to check the duration of a streaming file (in seconds), the percentage of the file streamed from the server, and the percentage of the file that has been played. The three Lingo terms are duration of member "name," percentstreamed of member "name," and percentplayed of member "name." These values may only be checked after the command has been initiated to play or preload the SWA file, otherwise they return zero (0).

The following example handler could be used to check the progress of a streaming file and put the results in three text fields:

>     on checktime
>        if the state of member "mysong"=2 then
>           put the duration of member "mysong" into field "howlong"
>           put the percentstreamed of member "mysong" into field
>     "pstreamed"
>           put the percentplayed of member "mysong" into field
>     "pplayed"
>        end if
>     end

### Checking the Bit Rate of an SWA File

Similar to checking state, duration, and other characteristics, you may check the bit rate of an SWA streaming file using the bitrate of member "name." If the file was created with a bit rate of 16 Kbps for example, this function would return the value 16000. This handler puts the bit rate of the current streaming file into a variable called "gbrate."

>     On checkrate
>        global gbrate
>        if the state of member "mysong"=2 then set gbrate=the
>        bitrate of
>     member "mysong"
>     end

### Checking Errors with the SWA File

If you have problems streaming a file, you may wish to check what the particular error is. Two functions are provided to check and return error messages: "geterror" (member "name") and `geterrorstring` (member "name"). If you only want an integer representing the error, use "geterror". `"Geterrorstring"` results in a text string describing the error. For example, the following handler checks for an error and puts the results into a field named "whaterror."

>     on checkerrors
>        if geterror (member "mysong") <> 0 then
>           put geterrorstring (member "mysong") into field
>     "whaterror"
>        end if
>     end

If `geterror` returns zero (0), there is no error. Table 18.3 lists the possible
results for both "geterror" and `"geterrorstring"`.

Table 18.3 Error Code Results for geterror and geterrorstring

geterror() | geterrorstring()
0 | OK
1 | memory
2 | network
3 | playback device
99 | other

## A Streaming Audio Example

We created an example for you to look at and take apart (or possibly use in your own Web page). This is a Shockwave "Stereo" to play streaming SWA files. It is designed to be useful in more than one situation because values for the SWA URL are passed to the movie through the embed tag in the HTML document. Open the movie stereo.dir on the CD-ROM to see how it's made. Audio.html loads the .DCR version and uses two .SWA files also located on the CD-ROM in the chapter 18 directory.

### Collecting the Pieces

The graphics created include the main music control panel with buttons to play, to pause and stop the sound, as well as controls for volume and song selection. Buttons with highlighted symbols also show when the song is playing, paused, or stopped. Figure 18.5 shows the graphics used.

Figure 18.5 : Graphics used in the Shockwave Music Player.

The SWA audio files in this example were taken from Macromedia's demonstration sites. You may run this from the CD-ROM using the audio.html file, but the concept works the same over the Internet.

### Assembling in Director

The creation of the movie is fairly straightforward, though you should think ahead about how you want to construct the embed tag in the HTML document. It's also tricky using network Lingo scripts because they cause errors in Director; they are only understood through Shockwave. If you are careful, you will be able to create the movie without running the completed version until it is embedded for Shockwave.

#### Basic Functionality

Set up the buttons first, leaving out the network Lingo until the buttons work properly with the changing graphics. The play button remains lit when pressed, the pause button only lights when the play button is on, and the stop button turns off both the play and pause buttons. You can control these using the "visible" property of the three sprites. Once these buttons work properly, you're ready to start working with the SWA cast member, though you can't test the movie until it's embedded.

Choosing the SWA Streaming Xtra from the Insert/other menu, I added the SWA member to my cast then named it "song." In a beginning frame script, I put the following:

>     on exitFrame
>       set the url of member "song" = externalparamvalue("sw1")
>       set the preloadtime of member "song" = 5
>       put externalparamvalue("sw2") into field "title"
>       set the visible of sprite 2 to false
>       set the visible of sprite 3 to false
>       set the visible of sprite 4 to false
>       updatestage
>     end

The "set the visible…" statements simply hide the highlighted buttons that become visible when clicked. I planned ahead to use four external parameters:

> "sw1"-the URL of the first song
> "sw2"-the title of the first song
> "sw3"-the URL of the second song
> "sw4"-the title of the second song

The above script sets the URL of my SWA cast member equal to the external parameter "sw1," which will be entered later in the HTML embed tag. I could have used the external parameter named "swURL" but this may confuse me when I want to pass a second URL value in the embed tag, so I decided just to use all custom parameters. My script sets the preload time of the SWA cast member to be five seconds. It also puts the song title into a field named "title" by retrieving the external parameter "sw2."

The next frame script loops while waiting for the user to choose to play, pause, stop, and so on. While it loops it updates the status of the current song using a case statement:

>     on exitFrame
>       case (the state of member "song") of
>         0: set status="Stopped"
>         1: set status="Preloading"
>         2: set status="Preload done"
>         3: set status="Playing"
>         4: set status="Paused"
>         5: set status="Done"
>         9: set status="Error"
>       end case
>       put status into field "song status"
>       go to the frame
>     end

I created another text field named "song status" that displays the results of the `state of member "song"` command. Because I don't want just a number displayed in the text field, I had to use a case statement to translate the numbers into text strings.

The rest of the scripts are all attached to buttons. Because I already set the buttons to appear and disappear depending on how they are clicked, I just need to add the network Lingo to start or stop the audio streaming. The play button, for example, looks like this:

>     on mousedown
>       set the visible of sprite 2 to true
>       set the visible of sprite 3 to false
>       updatestage
>       play (member "song")
>     end

It first turns the highlighted play button visible in sprite 2 and turns the pause button invisible in sprite 3 (whether it was invisible already or not). Then it begins the SWA streaming using the play (member "song") Lingo. The stop and pause buttons look similar, but turn different sprites visible and use their respective Lingo commands to control the audio.

#### Adding Extra Features

For more features, I added two other options for the user to control. Up and down arrows control which song to play and the volume of the music.

Note
I only have two songs available to play, though you could use more. There are quite a few external parameters that can be used to pass values from the HTML tag to the movie (in this case, URLs and song titles) but if you had a very long list, you might decide to load the information from a text file using the `getnettext` command.

For the song control buttons, I added another text field to display the song number, then scripted the up and down buttons. The up button script, for example, looks like this:

>     on mouseUp
>       global gsongnum
>       if gsongnum<>2 then
>         stop (member "song")
>         set the visible of sprite 2 to false
>         set the visible of sprite 3 to false
>         updatestage
>         set gsongnum=2
>         set the url of member "song"=externalparamvalue("sw3")
>         put externalparamvalue("sw4") into field "title"
>         put gsongnum into field "songnum"
>       end if
>     end

The above script first checks if the current song is already the highest number (2) by checking a global variable. If it's not, then the up arrow switches to song 2. It stops the current song if it's playing, turning off the play or pause buttons also. Then it sets the URL of the SWA cast member to the external parameter "sw3" and the song title to the external parameter "sw4." The down arrow button looks similar, but switches back to song number one.

The volume buttons use the Lingo soundlevel to control how loud the song plays. Another text field displays the sound level (an integer from 0 to 7). The script for the volume down button is as follows:

>     on mouseUp
>       set the soundlevel=the soundlevel -1
>       put the soundlevel into field "vol level"
>     end

Of course, the volume up script is identical, but increments the sound level instead of subtracting from it.

### Afterburner and Embedding the Movie

After saving and compressing the movie into a .DCR format, you're ready to write the embed tag in the HTML document. It looks like this:

>     <embed src="stereo.dcr" height=300 width=400 sw1="song1.swa"
>     sw2="An unknown song" sw3="song2.swa" sw4="Some Orchestra Music">

After the standard height and width parameters, I put the four external parameters that will be read by Lingo for the URLs and song titles of the SWA files. Because the SWA files are in the same directory as the Shockwave movie, they need only the file name. I could have specified the entire HTTP address.

Figure 18.6 shows the final movie as seen in the browser. Run it from the CD-ROM to hear the music streaming.

Figure 18.6 : The Shockwave Audio Player.

## From Here…

The addition of compressed audio is a significant accomplishment in multimedia on the Web. As with any new development, it's exciting to think of the possibilities made available through this technology. You will surprise your Web visitors and invite their return by continuing to update your Shockwave Web site with the latest enhancements.

The speed that multimedia springs up on the Web suggests that it is not ready to stabilize. It shouldn't at all surprise you if, by the time you hold this book in your hands, there is a new development called "Shockwave for Video" that allows streaming video clips. Perhaps it's not yet available or practical for the public, but it is there somewhere along with dozens of other ideas waiting for their chance to be developed.

- Chapter 19, "Shockwave for Authorware": Covers the basics of using Shockwave for Authorware for large multimedia projects over Intranets.
- Chapter 20, "Shockwave for Freehand": Describes Shockwave for Freehand, using scalable vector graphics on the Web.
- Appendixes at the back of the book give further information, including a gallery of Shockwave examples.