Getting Started

Requirements

Three Steam Audio runs in modern browsers that support:

WebAssembly — required to load the Steam Audio DSP runtime.
AudioWorklet — required for low-latency audio processing.
crossOriginIsolated and SharedArrayBuffer — optional but recommended. When available, control updates are sent to the AudioWorklet using shared memory with atomics. Otherwise, the library falls back to postMessage.

You can check the current environment with detectCapabilities().

Installation

Install three-steam-audio from your package manager. It is ESM-only with peer dependencies on three, and optional react, @react-three/fiber.

Three.js
React Three Fiber

pnpm add three-steam-audio three

npm install three-steam-audio three

yarn add three-steam-audio three

bun add three-steam-audio three

pnpm add -D @types/three

npm install -D @types/three

yarn add -D @types/three

bun add -D @types/three

pnpm add three-steam-audio three @react-three/fiber react react-dom

npm install three-steam-audio three @react-three/fiber react react-dom

yarn add three-steam-audio three @react-three/fiber react react-dom

bun add three-steam-audio three @react-three/fiber react react-dom

pnpm add -D @types/three @types/react @types/react-dom

npm install -D @types/three @types/react @types/react-dom

yarn add -D @types/three @types/react @types/react-dom

bun add -D @types/three @types/react @types/react-dom

Example: Spatializing an audio clip

This example creates a World, adds a simple source, and connects the resulting SteamAudioNode to the audio output. Before any audio is heard, you must resume the AudioContext from a user gesture to satisfy browser autoplay policy.

Three.js
React Three Fiber

import { 
const createWorld: (options: WorldOptions) => Promise<World>
createWorld } from 'three-steam-audio'

const 
const audioContext: AudioContext
audioContext = new 
var AudioContext: new (contextOptions?: AudioContextOptions) => AudioContext
The AudioContext interface represents an audio-processing graph built from audio modules linked together, each represented by an AudioNode.
MDN Reference
AudioContext()

// Resume from a user gesture, e.g. a button click.
await 
const audioContext: AudioContext
audioContext.
AudioContext.resume(): Promise<void>
The resume() method of the AudioContext interface resumes the progression of time in an audio context that has previously been suspended.
MDN Reference
resume()

const 
const world: World
world = await 
function createWorld(options: WorldOptions): Promise<World>
createWorld({ 
WorldOptions.audioContext: AudioContext
audioContext })

const 
const source: Source
source = 
const world: World
world.
function createSource(settings?: SourceSettings): Source
createSource({
  
SourceSettings.hrtf?: boolean | undefined
hrtf: true,
  
SourceSettings.directSimulation?: boolean | DirectSimulationSettings | undefined
directSimulation: { 
DirectSimulationSettings.occlusion?: false | "raycast" | "volumetric" | undefined
occlusion: 'raycast' },
})

const 
const node: SteamAudioNode
node = 
const world: World
world.
function createNode(sourceValue: Source): SteamAudioNode
createNode(
const source: Source
source)

// Connect an existing AudioNode as the mono input.
const 
const oscillator: OscillatorNode
oscillator = new 
var OscillatorNode: new (context: BaseAudioContext, options?: OscillatorOptions) => OscillatorNode
The OscillatorNode interface represents a periodic waveform, such as a sine wave. It is an AudioScheduledSourceNode audio-processing module that causes a specified frequency of a given wave to be created—in effect, a constant tone.
MDN Reference
OscillatorNode(
const audioContext: AudioContext
audioContext, { 
OscillatorOptions.frequency?: number | undefined
frequency: 440 })
const oscillator: OscillatorNode
oscillator.
AudioNode.connect(destinationNode: AudioNode, output?: number, input?: number): AudioNode (+1 overload)
The connect() method of the AudioNode interface lets you connect one of the node's outputs to a target, which may be either another AudioNode (thereby directing the sound data to the specified node) or an AudioParam, so that the node's output data is automatically used to change the value of that parameter over time.
MDN Reference
connect(
const node: SteamAudioNode
node)
const node: SteamAudioNode
node.
AudioNode.connect(destinationNode: AudioNode, output?: number, input?: number): AudioNode (+1 overload)
The connect() method of the AudioNode interface lets you connect one of the node's outputs to a target, which may be either another AudioNode (thereby directing the sound data to the specified node) or an AudioParam, so that the node's output data is automatically used to change the value of that parameter over time.
MDN Reference
connect(
const audioContext: AudioContext
audioContext.
BaseAudioContext.destination: AudioDestinationNode
The destination property of the BaseAudioContext interface returns an AudioDestinationNode representing the final destination of all audio in the context. It often represents an actual audio-rendering device such as your device's speakers.
MDN Reference
destination)
const oscillator: OscillatorNode
oscillator.
AudioScheduledSourceNode.start(when?: number): void
The start() method on AudioScheduledSourceNode schedules a sound to begin playback at the specified time. If no time is specified, then the sound begins playing immediately.
MDN Reference
start()

// Move the listener and source each frame, then step simulation.
const 
const animate: () => void
animate = () => {
  
function requestAnimationFrame(callback: FrameRequestCallback): number
MDN Reference
requestAnimationFrame(
const animate: () => void
animate)

  const 
const time: number
time = 
var performance: Performance
MDN Reference
performance.
Performance.now(): DOMHighResTimeStamp
The performance.now() method returns a high resolution timestamp in milliseconds. It represents the time elapsed since Performance.timeOrigin (the time when navigation has started in window contexts, or the time when the worker is run in Worker and ServiceWorker contexts).
MDN Reference
now() / 1000

  
const world: World
world.
listener: Listener
listener.
Listener.setPosition: (position: Vector3Like) => void
setPosition({ 
Vector3Like.x: number
x: 0, 
Vector3Like.y: number
y: 1.7, 
Vector3Like.z: number
z: 0 })
  
const world: World
world.
listener: Listener
listener.
Listener.setOrientation: (orientation: QuaternionLike) => void
setOrientation({ 
QuaternionLike.x: number
x: 0, 
QuaternionLike.y: number
y: 0, 
QuaternionLike.z: number
z: 0, 
QuaternionLike.w: number
w: 1 })

  
const source: Source
source.
Source.setPosition: (position: Vector3Like) => void
setPosition({
    
Vector3Like.x: number
x: 
var Math: Math
An intrinsic object that provides basic mathematics functionality and constants.
Math.
Math.sin(x: number): number
Returns the sine of a number.
@param ― x A numeric expression that contains an angle measured in radians.
sin(
const time: number
time) * 2,
    
Vector3Like.y: number
y: 1,
    
Vector3Like.z: number
z: 
var Math: Math
An intrinsic object that provides basic mathematics functionality and constants.
Math.
Math.cos(x: number): number
Returns the cosine of a number.
@param ― x A numeric expression that contains an angle measured in radians.
cos(
const time: number
time) * 2,
  })

  
const world: World
world.
function step(delta: number): void
step(1 / 60)
}
const animate: () => void
animate()

// Later, when shutting down:
// oscillator.stop()
// node.dispose()
// source.dispose()
// world.dispose()

import { 
const Suspense: ExoticComponent<SuspenseProps>
Lets you display a fallback until its children have finished loading.
@see ― https://react.dev/reference/react/Suspense React Docs
@example 
import { Suspense } from 'react';

<Suspense fallback={<Loading />}>
  <ProfileDetails />
</Suspense>
Suspense, 
function useEffect(effect: EffectCallback, deps?: DependencyList): void
Accepts a function that contains imperative, possibly effectful code.
@param ― effect Imperative function that can return a cleanup function
@param ― deps If present, effect will only activate if the values in the list change.
@version ― 16.8.0
@see ― https://react.dev/reference/react/useEffect
useEffect, 
function useState<S>(initialState: S | (() => S)): [S, Dispatch<SetStateAction<S>>] (+1 overload)
Returns a stateful value, and a function to update it.
@version ― 16.8.0
@see ― https://react.dev/reference/react/useState
useState } from 'react'
import { 
function Canvas(props: CanvasProps): import("react").JSX.Element
A DOM canvas which accepts threejs elements as children.
@see ― https://docs.pmnd.rs/react-three-fiber/api/canvas
Canvas } from '@react-three/fiber'
import {
  
const SteamAudio: (props: SteamAudioProps) => import("react").JSX.Element
SteamAudio,
  
const SteamAudioListener: ({ object }: SteamAudioListenerProps) => null
SteamAudioListener,
  
const SteamAudioSource: {
    ({ airAbsorption, destination, directivity, hrtf, input, occlusion, onReady, ref, reflections, reflectionSend, reverbSend, settings, spatialBlend, transmission, ...groupProps }: SteamAudioSourceProps): import("react").JSX.Element;
    displayName: string;
}
SteamAudioSource,
} from 'three-steam-audio/react'

export const 
const App: () => JSX.Element | null
App = () => {
  const [
const audioContext: AudioContext
audioContext] = 
useState<AudioContext>(initialState: AudioContext | (() => AudioContext)): [AudioContext, Dispatch<SetStateAction<AudioContext>>] (+1 overload)
Returns a stateful value, and a function to update it.
@version ― 16.8.0
@see ― https://react.dev/reference/react/useState
useState(() => new 
var AudioContext: new (contextOptions?: AudioContextOptions) => AudioContext
The AudioContext interface represents an audio-processing graph built from audio modules linked together, each represented by an AudioNode.
MDN Reference
AudioContext())
  const [
const input: AudioNode | null
input, 
const setInput: Dispatch<SetStateAction<AudioNode | null>>
setInput] = 
useState<AudioNode | null>(initialState: AudioNode | (() => AudioNode | null) | null): [AudioNode | null, Dispatch<SetStateAction<AudioNode | null>>] (+1 overload)
Returns a stateful value, and a function to update it.
@version ― 16.8.0
@see ― https://react.dev/reference/react/useState
useState<
interface AudioNode
The AudioNode interface is a generic interface for representing an audio processing module.
MDN Reference
AudioNode | null>(null)

  
function useEffect(effect: EffectCallback, deps?: DependencyList): void
Accepts a function that contains imperative, possibly effectful code.
@param ― effect Imperative function that can return a cleanup function
@param ― deps If present, effect will only activate if the values in the list change.
@version ― 16.8.0
@see ― https://react.dev/reference/react/useEffect
useEffect(() => {
    const 
const resume: () => Promise<void>
resume = () => 
const audioContext: AudioContext
audioContext.
AudioContext.resume(): Promise<void>
The resume() method of the AudioContext interface resumes the progression of time in an audio context that has previously been suspended.
MDN Reference
resume()
    
var window: Window & typeof globalThis
The window property of a Window object points to the window object itself.
MDN Reference
window.
addEventListener<"click">(type: "click", listener: (this: Window, ev: PointerEvent) => any, options?: boolean | AddEventListenerOptions): void (+1 overload)
The addEventListener() method of the EventTarget interface sets up a function that will be called whenever the specified event is delivered to the target.
MDN Reference
addEventListener('click', 
const resume: () => Promise<void>
resume, { 
AddEventListenerOptions.once?: boolean | undefined
once: true })
    return () => 
var window: Window & typeof globalThis
The window property of a Window object points to the window object itself.
MDN Reference
window.
removeEventListener<"click">(type: "click", listener: (this: Window, ev: PointerEvent) => any, options?: boolean | EventListenerOptions): void (+1 overload)
The removeEventListener() method of the EventTarget interface removes an event listener previously registered with EventTarget.addEventListener() from the target. The event listener to be removed is identified using a combination of the event type, the event listener function itself, and various optional options that may affect the matching process; see Matching event listeners for removal.
MDN Reference
removeEventListener('click', 
const resume: () => Promise<void>
resume)
  }, [
const audioContext: AudioContext
audioContext])

  
function useEffect(effect: EffectCallback, deps?: DependencyList): void
Accepts a function that contains imperative, possibly effectful code.
@param ― effect Imperative function that can return a cleanup function
@param ― deps If present, effect will only activate if the values in the list change.
@version ― 16.8.0
@see ― https://react.dev/reference/react/useEffect
useEffect(() => {
    const 
const oscillator: OscillatorNode
oscillator = new 
var OscillatorNode: new (context: BaseAudioContext, options?: OscillatorOptions) => OscillatorNode
The OscillatorNode interface represents a periodic waveform, such as a sine wave. It is an AudioScheduledSourceNode audio-processing module that causes a specified frequency of a given wave to be created—in effect, a constant tone.
MDN Reference
OscillatorNode(
const audioContext: AudioContext
audioContext, { 
OscillatorOptions.frequency?: number | undefined
frequency: 440 })
    
const oscillator: OscillatorNode
oscillator.
AudioScheduledSourceNode.start(when?: number): void
The start() method on AudioScheduledSourceNode schedules a sound to begin playback at the specified time. If no time is specified, then the sound begins playing immediately.
MDN Reference
start()
    
const setInput: (value: SetStateAction<AudioNode | null>) => void
setInput(
const oscillator: OscillatorNode
oscillator)
    return () => 
const oscillator: OscillatorNode
oscillator.
AudioScheduledSourceNode.stop(when?: number): void
The stop() method on AudioScheduledSourceNode schedules a sound to cease playback at the specified time. If no time is specified, then the sound stops playing immediately.
MDN Reference
stop()
  }, [
const audioContext: AudioContext
audioContext])

  if (!
const input: AudioNode | null
input) return null

  return (
    <
function Canvas(props: CanvasProps): import("react").JSX.Element
A DOM canvas which accepts threejs elements as children.
@see ― https://docs.pmnd.rs/react-three-fiber/api/canvas
Canvas>
      <
const Suspense: ExoticComponent<SuspenseProps>
Lets you display a fallback until its children have finished loading.
@see ― https://react.dev/reference/react/Suspense React Docs
@example 
import { Suspense } from 'react';

<Suspense fallback={<Loading />}>
  <ProfileDetails />
</Suspense>
Suspense 
SuspenseProps.fallback?: ReactNode
A fallback react tree to show when a Suspense child (like React.lazy) suspends
fallback={null}>
        <
const SteamAudio: (props: SteamAudioProps) => import("react").JSX.Element
SteamAudio 
audioContext: AudioContext
audioContext={
const audioContext: AudioContext
audioContext}>
          <
const SteamAudioListener: ({ object }: SteamAudioListenerProps) => null
SteamAudioListener />
          <
const SteamAudioSource: {
    ({ airAbsorption, destination, directivity, hrtf, input, occlusion, onReady, ref, reflections, reflectionSend, reverbSend, settings, spatialBlend, transmission, ...groupProps }: SteamAudioSourceProps): import("react").JSX.Element;
    displayName: string;
}
SteamAudioSource
            
SteamAudioSourceProps.input?: AudioNode | null | undefined
input={
const input: AudioNode
input}
            
SteamAudioSourceProps.hrtf?: boolean | undefined
hrtf
            
SteamAudioSourceProps.occlusion?: false | "raycast" | "volumetric" | undefined
occlusion="raycast"
            
position?: number | Vector3 | [x: number, y: number, z: number] | readonly [x: number, y: number, z: number] | Readonly<Vector3> | undefined
Object's local position.
@defaultValue ― new THREE.Vector3() - that is (0, 0, 0).
position={[0, 1, -2]}
          />
        </
const SteamAudio: (props: SteamAudioProps) => import("react").JSX.Element
SteamAudio>
      </
const Suspense: ExoticComponent<SuspenseProps>
Lets you display a fallback until its children have finished loading.
@see ― https://react.dev/reference/react/Suspense React Docs
@example 
import { Suspense } from 'react';

<Suspense fallback={<Loading />}>
  <ProfileDetails />
</Suspense>
Suspense>
    </
function Canvas(props: CanvasProps): import("react").JSX.Element
A DOM canvas which accepts threejs elements as children.
@see ― https://docs.pmnd.rs/react-three-fiber/api/canvas
Canvas>
  )
}

<SteamAudio> owns the world and runs world.step(delta) automatically each frame inside a useFrame callback. You can also pass an existing world with <SteamAudio world={world}>.

SteamAudioNode initialization is asynchronous. Use await node.ready when playback must not begin until the AudioWorklet DSP runtime is ready. If initialization fails, ready rejects and node.state becomes "failed"; the node outputs silence instead of bypassing the unprocessed input.

Next steps

Read the Programmer’s Guide to learn how the world, sources, listener, and scene fit together.
Browse the Reference for a complete list of options, methods, and React component props.
Look at the React example for a full interactive scene with reflections.