Listener

The listener represents the position and orientation of the player. Three Steam Audio uses the listener transform when spatializing sources, running occlusion rays, and simulating reflections.

Updating the listener

The world exposes a single listener through world.listener. Update it each frame before calling world.step(delta).

Three.js
React Three Fiber

import { 
const createWorld: (options: WorldOptions) => Promise<World>
createWorld } from 'three-steam-audio'
import { 
class Camera
Abstract base class for cameras. This class should always be inherited
when you build a new camera.
Camera } from 'three'

const 
const world: World
world = await 
function createWorld(options: WorldOptions): Promise<World>
createWorld({ 
WorldOptions.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() })

const 
const animate: () => void
animate = () => {
  
function requestAnimationFrame(callback: FrameRequestCallback): number
MDN Reference
requestAnimationFrame(
const animate: () => void
animate)

  
const world: World
world.
listener: ListenerImpl
listener.
ListenerImpl.setPosition(position: Vector3Like): void
setPosition(
const camera: Camera
camera.
Object3D<Object3DEventMap>.position: Vector3
Object's local position.
@defaultValue ― new THREE.Vector3() - that is (0, 0, 0).
position)
  
const world: World
world.
listener: ListenerImpl
listener.
ListenerImpl.setOrientation(orientation: QuaternionLike): void
setOrientation(
const camera: Camera
camera.
Object3D<Object3DEventMap>.quaternion: Quaternion
Object's local rotation as a
THREE.Quaternion Quaternion
.
@defaultValue ― new THREE.Quaternion() - that is (0,  0, 0, 1).
quaternion)
  
const world: World
world.
listener: ListenerImpl
listener.
ListenerImpl.setCamera(camera: Camera | null): void
Sets the render camera used for perspective-corrected spatialization.
Call this after updating the camera projection or world matrix.
setCamera(
const camera: Camera
camera)

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

const animate: () => void
animate()

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 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, perspectiveCorrection }: SteamAudioListenerProps) => null
SteamAudioListener,
} from 'three-steam-audio/react'

export const 
const App: () => JSX.Element
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())

  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, perspectiveCorrection }: SteamAudioListenerProps) => null
SteamAudioListener 
SteamAudioListenerProps.perspectiveCorrection?: boolean | Omit<PerspectiveCorrectionSettings, "enabled"> | undefined
perspectiveCorrection />
          {/* scene contents */}
        </
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>
  )
}

<SteamAudioListener> automatically synchronizes the R3F camera (or a custom object provided via the object prop) to world.listener each frame. When the object is a camera, it also provides its current projection and view matrices for perspective correction. Only one listener may be mounted per <SteamAudio> context.

Listener reverb

When reflections are enabled, you can ask the simulator to compute listener-centric reverb. This is useful for applying ambient reverberation to parts of your mix.

Three.js
React Three Fiber

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

const world: World
world.
listener: ListenerImpl
listener.
ListenerImpl.setReverb(settings: false | ReverbSettings): void
setReverb({
  
ReverbSettings.reverbScale?: ThreeBand | undefined
reverbScale: [1.8, 1.6, 1.3],
})

// Disable reverb later:
const world: World
world.
listener: ListenerImpl
listener.
ListenerImpl.setReverb(settings: false | ReverbSettings): void
setReverb(false)

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 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 SteamAudioEnvironment: ({ children, destination, reflections, reverb }: SteamAudioEnvironmentProps) => import("react").JSX.Element
SteamAudioEnvironment,
  
const SteamAudioListener: ({ object, perspectiveCorrection }: SteamAudioListenerProps) => null
SteamAudioListener,
} from 'three-steam-audio/react'

export const 
const App: () => JSX.Element
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())

  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}
          
options?: Omit<WorldOptions, "audioContext"> | undefined
options={{ 
reflections?: false | {
    diffuseSamples?: number;
    initial?: ReflectionSimulationSettings;
    maxDuration?: number;
    maxOrder?: number;
    maxRays?: number;
    maxSources?: number;
    updateRate?: number;
} | undefined
reflections: { 
maxRays?: number | undefined
maxRays: 4096 } }}
        >
          <
const SteamAudioListener: ({ object, perspectiveCorrection }: SteamAudioListenerProps) => null
SteamAudioListener />
          <
const SteamAudioEnvironment: ({ children, destination, reflections, reverb }: SteamAudioEnvironmentProps) => import("react").JSX.Element
SteamAudioEnvironment
            
SteamAudioEnvironmentProps.reverb?: false | (ReverbBusSettings & ReverbSettings) | undefined
reverb={{ 
ReverbSettings.reverbScale?: ThreeBand | undefined
reverbScale: [1.8, 1.6, 1.3], 
ReverbBusSettings.wet?: number | undefined
wet: 1 }}
          >
            {/* scene contents */}
          </
const SteamAudioEnvironment: ({ children, destination, reflections, reverb }: SteamAudioEnvironmentProps) => import("react").JSX.Element
SteamAudioEnvironment>
        </
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>
  )
}

See Reflections and Reverb for how to render reverb through a ReverbBusNode.