Chapter 299: Audio

Core Idea

Represents a non-positional ( global ) audio object.

This and related audio modules make use of the Web Audio API.

Key Concepts

autoplay : boolean: Whether to start playback automatically or not.
buffer : AudioBuffer (readonly): A reference to an audio buffer.
context : AudioContext (readonly): The audio context.
detune : number (readonly): Modify pitch, measured in cents. +/- 100 is a semitone. +/- 1200 is an octave.
duration : undefined | number: Overrides the default duration of the audio.
filters : Array.<AudioNode> (readonly): Can be used to apply a variety of low-order filters to create more complex sound effects e.g. via BiquadFilterNode.
gain : GainNode (readonly): The gain node used for volume control.
hasPlaybackControl : boolean (readonly): Indicates whether the audio playback can be controlled with method like Audio#play or Audio#pause.
isPlaying : boolean (readonly): Indicates whether the audio is playing or not.
listener : AudioListener (readonly): The global audio listener.

Code Examples

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

What it demonstrates: Typical usage of Audio.

Reference Tables

Constructor

Signature
`new Audio( listener : AudioListener )`

Properties

Property	Description
`.autoplay : boolean`	Whether to start playback automatically or not.
`.buffer : AudioBuffer (readonly)`	A reference to an audio buffer.
`.context : AudioContext (readonly)`	The audio context.
`.detune : number (readonly)`	Modify pitch, measured in cents. +/- 100 is a semitone. +/- 1200 is an octave.
`.duration : undefined	number`
`.filters : Array.<AudioNode> (readonly)`	Can be used to apply a variety of low-order filters to create more complex sound effects e.g. via `BiquadFilterNode`.
`.gain : GainNode (readonly)`	The gain node used for volume control.
`.hasPlaybackControl : boolean (readonly)`	Indicates whether the audio playback can be controlled with method like Audio#play or Audio#pause.
`.isPlaying : boolean (readonly)`	Indicates whether the audio is playing or not.
`.listener : AudioListener (readonly)`	The global audio listener.
`.loop : boolean (readonly)`	Whether the audio should loop or not.
`.loopEnd : number`	Defines where in the audio buffer the replay should stop, in seconds.
`.loopStart : number`	Defines where in the audio buffer the replay should start, in seconds.
`.offset : number`	An offset to the time within the audio buffer the playback should begin, in seconds.
`.playbackRate : number (readonly)`	The playback speed.
`.source : AudioNode (readonly)`	Holds a reference to the current audio source.
`.sourceType : 'empty'	'audioNode'

Methods

Method	Description
`.connect() : Audio`	Connects to the audio source. This is used internally on initialisation and when setting / removing filters.
`.disconnect() : Audio	undefined`
`.getDetune() : number`	Returns the detuning of oscillation in cents.
`.getFilter() : AudioNode	undefined`
`.getFilters() : Array.<AudioNode>`	Returns the current set filters.
`.getLoop() : boolean`	Returns the loop flag.
`.getOutput() : GainNode`	Returns the output audio node.
`.getPlaybackRate() : number`	Returns the current playback rate.
`.getVolume() : number`	Returns the volume.
`.onEnded()`	Automatically called when playback finished.
`.pause() : Audio	undefined`
`.play( delay : number ) : Audio	undefined`
`.setBuffer( audioBuffer : AudioBuffer ) : Audio`	Sets the given audio buffer as the source of this instance.
`.setDetune( value : number ) : Audio`	Defines the detuning of oscillation in cents.
`.setFilter( filter : AudioNode ) : Audio`	Applies a single filter node to the audio.
`.setFilters( value : Array.<AudioNode> ) : Audio`	Sets an array of filters and connects them with the audio source.
`.setLoop( value : boolean ) : Audio	undefined`
`.setLoopEnd( value : number ) : Audio`	Sets the loop end value which defines where in the audio buffer the replay should stop, in seconds.
`.setLoopStart( value : number ) : Audio`	Sets the loop start value which defines where in the audio buffer the replay should start, in seconds.
`.setMediaElementSource( mediaElement : HTMLMediaElement ) : Audio`	Sets the given media element as the source of this instance.
`.setMediaStreamSource( mediaStream : MediaStream ) : Audio`	Sets the given media stream as the source of this instance.
`.setNodeSource( audioNode : AudioNode ) : Audio`	Sets the given audio node as the source of this instance.
`.setPlaybackRate( value : number ) : Audio	undefined`
`.setVolume( value : number ) : Audio`	Sets the volume.
`.stop( delay : number ) : Audio	undefined`

Key Takeaways

Audio extends: EventDispatcher → Object3D
Most relevant properties: autoplay, buffer, context, detune.
Key methods: connect, disconnect, getDetune, getFilter.

Connects To

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