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

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

## Source

src/audio/Audio.js