ThreeJS Audio

It is used to create a non-positional (global ) audio object.

Code Example:

// create an AudioListener and add it to the camera
const listener = new THREE.AudioListener();
camera.add( listener );


// create a global audio source
const sound = new THREE.Audio( listener );


// load a sound and set it as the Audio object's buffer
const audioLoader = new THREE.AudioLoader();
audioLoader.load( 'sounds/ambient.ogg', function( buffer ) {
	sound.setBuffer( buffer );
	sound.setLoop( true );
	sound.setVolume( 0.5 );
	sound.play();
});

Constructor

Audio( listener : AudioListener )

listener — (required) AudioListener instance.

Properties

.autoplay : Boolean

Whether to start playback automatically. Default is false.

.context : AudioContext

The AudioContext of the listener given in the constructor.

.detune : Number

Modify pitch, measured in cents. +/- 100 is a semitone. +/- 1200 is an octave. Default is 0.

.filters : Array

An array of AudioNodes is represented by this class. To generate more sophisticated sound effects, it can be used to apply a variety of low-order filters. In most cases, the array contains BiquadFilterNodes instances. Audio.setFilter or Audio.setFilters are used to set filters.

.gain : GainNode

A GainNode created using AudioContext.createGain().

.hasPlaybackControl : Boolean

Whether playback can be controlled using the play(), pause() etc. methods. Default is true.

.isPlaying : Boolean

Whether the audio is currently playing.

.listener : AudioListener

A reference to the listener object of this audio.

.playbackRate : Number

Speed of playback. Default is 1.

.offset : Number

An offset for when playback should start within the audio buffer. The offset parameter of AudioBufferSourceNode is the same. start(). The default value is 0.

.duration : Number

Overrides the audio's duration. The duration parameter of AudioBufferSourceNode.start is the same as the duration parameter of AudioBufferSourceNode.start (). The default is undefined, which means it will play the entire buffer.

.source : String

An AudioBufferSourceNode created using AudioContext.createBufferSource().

.sourceType : String

Type of the audio source. Default is string 'empty'.

.type : String

String denoting the type, set to 'Audio'.

Methods

.connect () :this

Connect to the Audio.source. This is used internally on initialisation and when setting / removing filters.

.disconnect () : this

Disconnect from the Audio.source. This is used internally when setting / removing filters.

.getFilter () : BiquadFilterNode

Returns the first element of the filters array.

.getFilters () : Array

Returns the filters array.

.getLoop () : Boolean

Return the value of source.loop (whether playback should loop).

.getOutput () : GainNode

Return the gainNode.

.getPlaybackRate () : Float

Return the value of playbackRate.

.getVolume ( value ) : Float

Return the current volume.

.play ( delay ) : this

If hasPlaybackControl is true, starts playback.

.pause () : this

If hasPlaybackControl is true, pauses playback.

.onEnded () : undefined

Called automatically when playback finished.

.setBuffer ( audioBuffer ) : this

Setup the source to the audioBuffer, and sets sourceType to 'buffer'.

If autoplay, also starts playback.

.setFilter ( filter ) : this

Applies a single filter node to the audio.

.setFilters ( value : Array ) : this

value - arrays of filters.

Applies an array of filter nodes to the audio.

.setLoop ( value : Boolean ) : this

Set source.loop to value (whether playback should loop).

.setLoopStart ( value : Float ) : this

Set source.loopStart to value.

.setLoopEnd ( value : Float ) : this

Set source.loopEnd to value.

.setMediaElementSource ( mediaElement ) : this

Applies the given object of type HTMLMediaElement as the source of this audio.

Also sets hasPlaybackControl to false.

.setMediaStreamSource ( mediaStream ) : this

Applies the given object of type MediaStream as the source of this audio.

Also sets hasPlaybackControl to false.

.setNodeSource ( audioNode ) : this

Setup the source to the audioBuffer, and sets sourceType to 'audioNode'.

Also sets hasPlaybackControl to false.

.setPlaybackRate ( value : Float ) : this

If hasPlaybackControl is enabled, set the playbackRate to value.

.setVolume ( value : Float ) : this

Set the volume.

.stop () : this

If hasPlaybackControl is enabled, stops playback.

AudioAnalyser

Create an AudioAnalyser object that analyses audio data using an AnalyserNode.

Code Example:

// create an AudioListener and add it to the camera
const listener = new THREE.AudioListener();
camera.add( listener );


// create an Audio source
const sound = new THREE.Audio( listener );


// load a sound and set it as the Audio object's buffer
const audioLoader = new THREE.AudioLoader();
audioLoader.load( 'sounds/ambient.ogg', function( buffer ) {
	sound.setBuffer( buffer );
	sound.setLoop(true);
	sound.setVolume(0.5);
	sound.play();
});


// create an AudioAnalyser, passing in the sound and desired fftSize
const analyser = new THREE.AudioAnalyser( sound, 32 );


// get the average frequency of the sound
const data = analyser.getAverageFrequency();

Constructor

AudioAnalyser( audio, fftSize )

Create a new AudioAnalyser.

Properties

.analyser : AnalyserNode

An AnalyserNode used to analyze audio.

.fftSize : Integer

A non-zero power of two up to 2048, representing the size of the FFT (Fast Fourier Transform) to be used to determine the frequency domain. See this page for details.

.data : Uint8Array

A Uint8Array with size determined by analyser.frequencyBinCount used to hold analysis data.

Methods

.getFrequencyData () : Uint8Array

Uses the Web Audio's getByteFrequencyData method. See that page.

.getAverageFrequency () : Number

Get the average of the frequencies returned by the getFrequencyData method.

AudioContext

This section includes the techniques for creating an AudioContext.

The AudioListener and AudioLoader classes use this internally.

The Web Audio API is used here.

Methods

.getContext () : AudioContext

Return the value of the variable context in the outer scope, if defined, otherwise set it to a new AudioContext.

.setContext ( value : AudioContext ) : AudioContext

Set the variable context in the outer scope to value.

AudioListener

The AudioListener is a virtual listener for all of the scene's positional and non-positional audio effects.

A single instance of AudioListener is normally created in a three.js application. For audio entities like as Audio and PositionalAudio, it is a required function Object() { [native code] } parameter.

The listener object is almost always a camera's kid. As a result, the camera's 3D transformation replicates the listener's 3D transformation.

Code Example:

// create an AudioListener and add it to the camera
const listener = new THREE.AudioListener();
camera.add( listener );


// create a global audio source
const sound = new THREE.Audio( listener );


// load a sound and set it as the Audio object's buffer
const audioLoader = new THREE.AudioLoader();
audioLoader.load( 'sounds/ambient.ogg', function( buffer ) {
	sound.setBuffer( buffer );
	sound.setLoop(true);
	sound.setVolume(0.5);
	sound.play();
});

Constructor

AudioListener( )

Create a new AudioListener.

Properties

.context : AudioContext

The AudioContext of the listener given in the constructor.

.gain : GainNode

A GainNode created using AudioContext.createGain().

.filter : AudioNode

Default is null.

.timeDelta : Number

Time delta value for audio entities. Use in context of AudioParam.linearRampToValueAtTimeDefault(). Default is 0.

Methods

.getInput () : GainNode

Return the gainNode.

.removeFilter () : this

Set the filter property to null.

.getFilter () : AudioNode

Returns the value of the filter property.

.setFilter ( value : AudioNode ) : this

Set the filter property to value.

.getMasterVolume () : Float

Return the volume.

.setMasterVolume ( value : Number ) : this

Set the volume.

PositionalAudio

It is used to create a positional audio object.

Code Example:

// 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 );

Constructor

PositionalAudio( listener : AudioListener )

listener — (required) AudioListener instance.

Properties and Methods

The properties and methods are inherited from the Audio package. The unique properties and methods are as follows:

.panner : PannerNode

The PositionalAudio's PannerNode.

.getOutput () : PannerNode

Returns the panner.

.getRefDistance () : Float

Returns the value of panner.refDistance.

.setRefDistance ( value : Float ) : this

Sets the value of panner.refDistance.

.getRolloffFactor () : Float

Returns the value of panner.rolloffFactor.

.setRolloffFactor ( value : Float ) : this

Sets the value of panner.rolloffFactor.

.getDistanceModel () : String

Returns the value of panner.distanceModel.

.setDistanceModel ( value : String ) : this

Sets the value of panner.distanceModel.

.getMaxDistance () : Float

Returns the value of panner.maxDistance.

.setMaxDistance ( value : Float ) : this

Sets the value of panner.maxDistance.

.setDirectionalCone ( coneInnerAngle : Float, coneOuterAngle : Float, coneOuterGain : Float ) : this

This method can be used in order to transform an omnidirectional sound into a directional sound.