Chapter 304: PositionalAudio

Core Idea

Represents a positional audio object.

Key Concepts

• panner : PannerNode (readonly): The panner node represents the location, direction, and behavior of an audio source in 3D space.

Code Examples

// create an AudioListener and add it to the camera
const listener = new THREE.AudioListener();
camera.add( listener );
// create the PositionalAudio object (passing in the listener)
const sound = new THREE.PositionalAudio( listener );
// load a sound and set it as the PositionalAudio object's buffer
const audioLoader = new THREE.AudioLoader();
audioLoader.load( 'sounds/song.ogg', function( buffer ) {
	sound.setBuffer( buffer );
	sound.setRefDistance( 20 );
	sound.play();
});
// create an object for the sound to play from
const sphere = new THREE.SphereGeometry( 20, 32, 16 );
const material = new THREE.MeshPhongMaterial( { color: 0xff2200 } );
const mesh = new THREE.Mesh( sphere, material );
scene.add( mesh );
// finally add the sound to the mesh
mesh.add( sound );

• What it demonstrates: Typical usage of PositionalAudio.

Reference Tables

Constructor

Signature
new PositionalAudio( listener : AudioListener )

Properties

Property	Description
.panner : PannerNode (readonly)	The panner node represents the location, direction, and behavior of an audio source in 3D space.

Methods

Method	Description
`.getDistanceModel() : 'linear'	'inverse'
.getMaxDistance() : number	Returns the current max distance.
.getRefDistance() : number	Returns the current reference distance.
.getRolloffFactor() : number	Returns the current rolloff factor.
.setDirectionalCone( coneInnerAngle : number, coneOuterAngle : number, coneOuterGain : number ) : PositionalAudio	Sets the directional cone in which the audio can be listened.
`.setDistanceModel( value : 'linear'	'inverse'
.setMaxDistance( value : number ) : PositionalAudio	Defines the maximum distance between the audio source and the listener, after which the volume is not reduced any further.
.setRefDistance( value : number ) : PositionalAudio	Defines the reference distance for reducing volume as the audio source moves further from the listener – i.e. the distance at which the volume reduction starts taking effect.
.setRolloffFactor( value : number ) : PositionalAudio	Defines how quickly the volume is reduced as the source moves away from the listener.

Key Takeaways

1. PositionalAudio extends: EventDispatcher → Object3D → Audio
2. Most relevant properties: panner.
3. Key methods: getDistanceModel, getMaxDistance, getRefDistance, getRolloffFactor.

Connects To

• EventDispatcher: parent class
• Object3D: parent class
• Audio: parent class
• Source: src/audio/PositionalAudio.js