threlte logo
@threlte/extras

<Audio>

webgl <Audio> works with WebGL and is available from the @threlte/extras export. webgpu <Audio> works with WebGPU and is available from the @threlte/extras/webgpu export.

Create a non-positional (global) audio object. This uses the Web Audio API.

You need to have an <AudioListener> component in your scene in order to use <Audio>and <PositionalAudio>components. The <AudioListener> component needs to be mounted before any <Audio> or <PositionalAudio> components:

<T.PerspectiveCamera makeDefault>
  <AudioListener />
</T.PerspectiveCamera>

<PositionalAudio />

Example

<script>
  import { T, Canvas } from '@threlte/core'
  import { AudioListener, Audio } from '@threlte/extras'
</script>

<Canvas>
  <T.PerspectiveCamera
    makeDefault
    position={[3, 3, 3]}
    lookAt={[0, 0, 0]}
  >
    <AudioListener />
  </T.PerspectiveCamera>

  <Audio src={'/audio/track.mp3'} />
</Canvas>

Component Signature

<Audio> extends < T . Audio > and supports all its props, snippets, bindings and events.

Props

name
type
required
default
description

src
AudioSource
yes
The audio to play: a URL (loaded with three's AudioLoader), a decoded AudioBuffer, an <audio> or <video> element, an AudioBufferSourceNode, or a MediaStream such as a microphone.

autoplay
boolean
no
false
Starts playing as soon as src has loaded, resuming the audio context if needed.

detune
number
no
0
Pitch shift in cents, where 100 is one semitone. Only applies once a source is playing.

id
string
no
'default'
The id of the <AudioListener> to play through.

loop
boolean
no
false
Restarts playback when the end is reached.

playbackRate
number
no
1
Playback speed, where 1 is normal speed. Also shifts the pitch.

volume
number
no
1
The gain, where 1 is the original volume and 0 is silent. Values above 1 amplify and can clip.

Events

name
payload
description

onload
AudioBuffer | null
Called when src has loaded, with its buffer when it has one.

onerror
ErrorEvent
Called when src fails to load.

onprogress
ProgressEvent
Called with loading progress while a URL src downloads.

Exports

name
type

play
(delay?: number) => Promise<THREE.Audio>

pause
() => THREE.Audio

stop
() => THREE.Audio