Audio

In Three.js, audio functionality allows you to integrate sound effects and music into your 3D scenes. This can enhance the immersive experience of your application or game. The Three.js library provides several classes to handle different aspects of audio, including loading audio files, creating audio sources, and controlling audio playback.

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

Represents an array of AudioNodes. Can be used to apply a variety of low-order filters to create more complex sound effects. In most cases, the array contains instances of BiquadFilterNodes. Filters are set via Audio.setFilter or Audio.setFilters.

.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 to the time within the audio buffer that playback should begin. Same as the offset parameter of AudioBufferSourceNode.start(). Default is 0.

.duration : Number

Overrides the duration of the audio. Same as the duration parameter of AudioBufferSourceNode.start(). Default is undefined to play the whole buffer.

.source : AudioNode

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.

.getDetune () : Float

Returns the detuning of oscillation in cents.

.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 () : 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.

.setDetune ( value : Float ) : this

Defines the detuning of oscillation in cents.

.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.

Important Notes

• Audio Format Compatibility: Ensure that your audio files are in a format compatible with the browsers you’re targeting. Common formats like .mp3 and .ogg are widely supported.
• Autoplay Restrictions: Many modern browsers have restrictions on autoplaying audio. You may need to start the audio in response to a user interaction (like a button click) to ensure it plays correctly.