Intel Spatial Audio for Java* Package Tutorial

Lesson 3: Controlling Audio Objects

Goal: This lesson shows you the basics you'll need to use audio objects effectively. This includes:

• Controlling the position and orientation of audio objects
• Correlating graphics and sound
• Basics of the sound model
• Adjusting the media state
• Notes on the coordinate system

Controlling the Position and Orientation of Audio Objects

Listeners and SoundSources both support the setPosition() and setOrientation() methods for controlling position and orientation. To control the position of an audio object, you need to specify its x, y, and z axis coordinates, either directly or using an instance of the Vector3D class. Note that many of the methods in the package can be called with several sets of arguments.

Vector3D v3d = new Vector3D(5.0f, 10.2f, 3.0f);
listener.setPosition(v3d);
soundSource.setPosition(v3d);
-- or --
listener.setPosition(v3d.x, v3d.y, v3d.z);
soundSource.setPosition(v3d.x, v3d.y, v3d.z);

A sound source may be directional, or audible further in front than behind it; the direction in which its audible region extends the furthest is its "forward" direction. (This is discussed further in the section on Understanding the Sound Model.) Controlling the orientation of a sound source is just like controlling its position:

Vector3D v3d = new Vector3D(5.0f, 10.2f, 3.0f);
soundSource.setOrientation(v3d);
-- or --
soundSource.setOrientation(v3d.x, v3d.y, v3d.z);

Two vectors are required to specify the orientation of a listener. As you face a computer monitor (one directional vector), you will perceive sounds differently depending on whether your feet are on the floor, on the ceiling, or somewhere in between (the second vector). To determine the orientation of a listener, then, you must specify both the "forward" direction and the "up" direction. You may do this using two three-dimensional vectors, six floating point values, or an instance of the Orientation6D class, which contains two three-dimensional vectors.

Vector3D forward = new Vector3D(0.0f, 0.0f, 1.0f);
Vector3D up = new Vector3D(0.0f, 1.0f, 0.0f);
listener.setOrientation(forward, up);

You can retrieve the current position and orientation of a sound source or listener at any time. A SpatialAudioException is thrown if the retrieval fails.

try {
	Vector3D v3d1 = listener.getPosition();
	Vector3D v3d2 = soundSource.getPosition();

	Orientation6d v6d = listener.getOrientation();
	Vector3D v3d3 = soundSource.getOrientation;
} catch (SpatialAudioException e) {
	/* handle the exception */
}

Correlating Graphics and Sound

It is very common to use graphics and sound together in an applet or application. Normally, sound sources correlate to graphical objects and the listener correlates to the camera. To attach an audio object to a graphical element, simply keep their positions and orientations synchronized. The code might look something like this:

public void updatePosition(Vector3D newPosition) {
	GraphicalObject.setPosition(newPosition);
	soundSource.setPosition(newPosition);
}

public void updateCamera(Vector3D newPosition) {
	GraphicalCamera.setPosition(newPosition);
	listener.setPosition(newPosition);
}

In the applet on this page, different icons represent the listener and the sound source. When the user changes the position of an object, the updated position is stored in a Vector3D object. setPosition() is called on the audio object, and a call to repaint() is made. When the applet repaints, it uses the updated position information to draw the icons.

public boolean action(Event evt, Object arg) {
	....
	....
	/*
	* change the position of the sound source
	*/
	if (evt.target == soundSource_right) {
		try { soundSourcePos = soundSource.getPosition(); } catch (SpatialAudioException e) {  }
		soundSourcePos.x += 10.0f;
		soundSource.setPosition(soundSourcePos);
		repaint();
		return true;

	}
	....
	....
}

public void paint(Graphic g) {
			....
			....
			h.drawImage(soundSourceImage, (int)soundSourcePos.x, (int)soundSourcePos.y, top);
			soundSource.setPosition(newPosition);
			....
			....
}

Basics of the Sound Model

By adjusting the sound model, you can control the directionality and extent of a sound source. The black circle in the applet on this page represents the limits of audibility of the sound source. When you make the circle bigger, you can hear the sound source further away. (Your position is represented by the smiley-face icon.)

You can learn more about the sound model in the next lesson.

Adjusting the Media State

You can control the play state of a cached sound source using the setPlayState() method. This method allows you to apply VCR-type controls to a cached sound source using constants defined in the MediaState class.  

AUDIO_PLAY causes the sound to begin playing from the beginning and loop continuously.
AUDIO_PAUSE causes the sound to pause at its current play position.
AUDIO_RESUME causes the sound to start playing at its current play position, if it is paused, or from the beginning if it is stopped.
AUDIO_STOP stops playback of the sound and resets the play position to the beginning.

In the applet on this page, playback is controlled by four buttons. The code for handling input looks like this:

public boolean action(Event evt, Object arg) {
	....
	....
	/*
	* change the play state of the sound source
	*/
	if (evt.target == playSound) {
		soundSource.setPlayState(MediaState.AUDIO_PLAY);
		return true;
	}
	if (evt.target == pauseSound) {
		soundSource.setPlayState(MediaState.AUDIO_PAUSE);
		return true;
	}
	if (evt.target == resumeSound) {
		soundSource.setPlayState(MediaState.AUDIO_RESUME);
		return true;
	}
	if (evt.target == stopSound) {
		soundSource.setPlayState(MediaState.AUDIO_STOP);
		return true;
	}
	....
	....
}

Notes on the Coordinate System

A three-dimensional coordinate system may be either right- or left-handed. By default, the package uses a left-handed coordinate system in which x increases to the right, y increases upward, and z increases into the screen. In a right-handed coordinate system, the x and y axes would remain the same and z would increase in the opposite direction.

Both coordinate systems are commonly used by graphics libraries. If you are correlating graphics and sound, it is very useful to use the same coordinate system. Intel Spatial Audio for Java* allows you to specify the handedness of the coordinate system you would like to use in the Environment.setEnvironment() method. This and other advanced features are discussed later in the Tutorial.

Remember that in a standard left-handed coordinate system, x increases to the right and y increases upward. However, your window coordinates increase downward.

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

Legal Stuff