Intel Spatial Audio for Java* Package Tutorial

Lesson 2: Setting Up

Goal: This lesson is designed to help you get Intel Spatial Audio for Java* up and running in a Java applet or application. Although applets are used throughout this Tutorial, use of the package in an application is identical.

Making Sound

There's an applet on this page. (It was on the last page, too, playing a pretty cool song from a MIDI file.) You should hear the looping sound of a guitar. This applet demonstrates the minimum code required to make sound using the Intel Spatial Audio for Java package. Essentially, it does four things:

• Create an Environment
  To create an Environment, you use a static member function of the class SpatialAudio. It looks like this:

Environment env;
try { 
	env = SpatialAudio.createEnvironment();
} catch (SpatialAudioException e) {
	/* handle the exception */
}

• Create a Listener
  You create the Listener by using one of the Environment interface methods. Since we want the simplest possible example with the audio output going right to the audio device, we create a direct listener. It looks like this:

Listener listener;
try {
	listener = env.createDirectListener(); 
} catch (SpatialAudioException e) {
	/* handle the exception */
}

• Create a SoundSource
  Again, we want the simplest example, so we create a cached sound source from a string that represents an URL. The code looks like this:

CachedSoundSource soundSource;
try {
	soundSource = env.createCachedSoundSource(docBase + soundName);
} catch (Exception e) {
	/* handle the exception */
}

• Here docBase is the name of the directory where the HTML file is located, and soundName is the name of the sound file.
• Tell the Sound to Play
  This call causes the sound to loop forever. Later, we'll look at how to control how the sound plays.

soundSource.setPlayState(MediaState.AUDIO_PLAY);  

There are a couple of other important things going on in this applet. They have to do with handling the audio device and cleaning up when the applet terminates.

Handling the Audio Device

Because of how the PC handles sharing of the audio device, you need to be very careful about how you handle it. When you create a direct listener, it automatically connects itself to the audio device. At all other times, however, you must explicitly connect and disconnect a direct listener to and from the audio device. (The streaming listener does not utilize the audio device resource and does not have these methods.) It is important that you disconnect your listener from the audio device when your applet is not running so that other applets and applications can use it.

You can normally handle this situation easily by calling connect() and disconnect() in your applet's start() and stop() methods, respectively. This way, you release the audio device whenever the user leaves your page, and regain control of it whenever the applet becomes active again. As an added benefit, disconnecting the listener automatically cuts off any sound your applet might be playing when the user leaves the page.

The code looks like this:

public void start() {
	...
	listener.connect();
	...
}

public void stop() {
	...
	listener.disconnect();
	...
}

Cleaning Up

When you are all finished with an audio object (an Environment, a Listener, or a SoundSource), you should release it. Calling release() is not required, but helps you control the resources used by your applet. After you have called an object's release() method, you can no longer use the object; all calls on it will fail.

Normally, you can place your clean-up code in your applet's destroy() method. There are certain other times when you might want to release an object. For example, only one listener at a time is currently supported per environment. If you want to replace your current listener, you need release the first one.

The code looks like this:

if (soundSource != null) {
	soundSource.release();
	 soundSource = null;
}
if (listener != null) {
	listener.release();
	listener = null;
}
if (env != null) {
	env.release();
	env = null;
}

This page was last updated on Feb 11th, 1997.

Legal Stuff