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.