Audio.html.md 8.3 KB
Inheritance: EventDispatcher → Object3D →
Audio
Represents a non-positional ( global ) audio object.
This and related audio modules make use of the Web Audio API.
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
new Audio( listener : AudioListener )
Constructs a new audio.
listener
The global audio listener.
Properties
.autoplay : boolean
Whether to start playback automatically or not.
Default is false.
.buffer : AudioBuffer (readonly)
A reference to an audio buffer.
Defined via Audio#setBuffer.
Default is null.
.context : AudioContext (readonly)
The audio context.
.detune : number (readonly)
Modify pitch, measured in cents. +/- 100 is a semitone. +/- 1200 is an octave.
Defined via Audio#setDetune.
Default is 0.
.duration : undefined | number
Overrides the default duration of the audio.
Default is undefined.
.filters : Array. (readonly)
Can be used to apply a variety of low-order filters to create more complex sound effects e.g. via BiquadFilterNode.
The property is automatically set by Audio#setFilters.
.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.
This flag will be automatically set when audio sources are defined.
Default is true.
.isPlaying : boolean (readonly)
Indicates whether the audio is playing or not.
This flag will be automatically set when using Audio#play, Audio#pause, Audio#stop.
Default is false.
.listener : AudioListener (readonly)
The global audio listener.
.loop : boolean (readonly)
Whether the audio should loop or not.
Defined via Audio#setLoop.
Default is false.
.loopEnd : number
Defines where in the audio buffer the replay should stop, in seconds.
Default is 0.
.loopStart : number
Defines where in the audio buffer the replay should start, in seconds.
Default is 0.
.offset : number
An offset to the time within the audio buffer the playback should begin, in seconds.
Default is 0.
.playbackRate : number (readonly)
The playback speed.
Defined via Audio#setPlaybackRate.
Default is 1.
.source : AudioNode (readonly)
Holds a reference to the current audio source.
The property is automatically by one of the set*() methods.
Default is null.
.sourceType : 'empty' | 'audioNode' | 'mediaNode' | 'mediaStreamNode' | 'buffer' (readonly)
Defines the source type.
The property is automatically set by one of the set*() methods.
Default is 'empty'.
Methods
.connect() : Audio
Connects to the audio source. This is used internally on initialisation and when setting / removing filters.
Returns: A reference to this instance.
.disconnect() : Audio | undefined
Disconnects to the audio source. This is used internally on initialisation and when setting / removing filters.
Returns: A reference to this instance.
.getDetune() : number
Returns the detuning of oscillation in cents.
Returns: The detuning of oscillation in cents.
.getFilter() : AudioNode | undefined
Returns the first filter in the list of filters.
Returns: The first filter in the list of filters.
.getFilters() : Array.
Returns the current set filters.
Returns: The list of filters.
.getLoop() : boolean
Returns the loop flag.
Can only be used with compatible audio sources that allow playback control.
Returns: Whether the audio should loop or not.
.getOutput() : GainNode
Returns the output audio node.
Returns: The output node.
.getPlaybackRate() : number
Returns the current playback rate.
Returns: The playback rate.
.getVolume() : number
Returns the volume.
Returns: The volume.
.onEnded()
Automatically called when playback finished.
.pause() : Audio | undefined
Pauses the playback of the audio.
Can only be used with compatible audio sources that allow playback control.
Returns: A reference to this instance.
.play( delay : number ) : Audio | undefined
Starts the playback of the audio.
Can only be used with compatible audio sources that allow playback control.
delay
The delay, in seconds, at which the audio should start playing.
Default is 0.
Returns: A reference to this instance.
.setBuffer( audioBuffer : AudioBuffer ) : Audio
Sets the given audio buffer as the source of this instance.
Audio#sourceType is set to buffer and Audio#hasPlaybackControl to true.
audioBuffer
The audio buffer.
Returns: A reference to this instance.
.setDetune( value : number ) : Audio
Defines the detuning of oscillation in cents.
value
The detuning of oscillation in cents.
Returns: A reference to this instance.
.setFilter( filter : AudioNode ) : Audio
Applies a single filter node to the audio.
filter
The filter to set.
Returns: A reference to this instance.
.setFilters( value : Array. ) : Audio
Sets an array of filters and connects them with the audio source.
value
A list of filters.
Returns: A reference to this instance.
.setLoop( value : boolean ) : Audio | undefined
Sets the loop flag.
Can only be used with compatible audio sources that allow playback control.
value
Whether the audio should loop or not.
Returns: A reference to this instance.
.setLoopEnd( value : number ) : Audio
Sets the loop end value which defines where in the audio buffer the replay should stop, in seconds.
value
The loop end value.
Returns: A reference to this instance.
.setLoopStart( value : number ) : Audio
Sets the loop start value which defines where in the audio buffer the replay should start, in seconds.
value
The loop start value.
Returns: A reference to this instance.
.setMediaElementSource( mediaElement : HTMLMediaElement ) : Audio
Sets the given media element as the source of this instance.
Audio#sourceType is set to mediaNode and Audio#hasPlaybackControl to false.
mediaElement
The media element.
Returns: A reference to this instance.
.setMediaStreamSource( mediaStream : MediaStream ) : Audio
Sets the given media stream as the source of this instance.
Audio#sourceType is set to mediaStreamNode and Audio#hasPlaybackControl to false.
mediaStream
The media stream.
Returns: A reference to this instance.
.setNodeSource( audioNode : AudioNode ) : Audio
Sets the given audio node as the source of this instance.
Audio#sourceType is set to audioNode and Audio#hasPlaybackControl to false.
audioNode
The audio node like an instance of OscillatorNode.
Returns: A reference to this instance.
.setPlaybackRate( value : number ) : Audio | undefined
Sets the playback rate.
Can only be used with compatible audio sources that allow playback control.
value
The playback rate to set.
Returns: A reference to this instance.
.setVolume( value : number ) : Audio
Sets the volume.
value
The volume to set.
Returns: A reference to this instance.
.stop( delay : number ) : Audio | undefined
Stops the playback of the audio.
Can only be used with compatible audio sources that allow playback control.
delay
The delay, in seconds, at which the audio should stop playing.
Default is 0.
Returns: A reference to this instance.