React Components

The three-steam-audio/react entry point provides declarative components for React Three Fiber.

`<SteamAudio>`

Provider that owns or receives a World. It runs world.step(delta) automatically each frame.

import { 
const SteamAudio: (props: SteamAudioProps) => import("react").JSX.Element
SteamAudio } from 'three-steam-audio/react'

Props

audioContext : Required when creating an owned world. The AudioContext to use.

options : Omit<WorldOptions, 'audioContext'> — options passed to createWorld.

world : An existing World to use instead of creating one.

paused : boolean — when true, world.step is not called. Default: false.

updatePriority : number — R3F useFrame priority. Default: -100.

children : React nodes rendered inside the provider.

`useSteamAudio()`

import { 
const useSteamAudio: () => SteamAudioContextValue
useSteamAudio } from 'three-steam-audio/react'

const { 
const listener: Listener
listener, 
const scene: AcousticSceneImpl
scene, 
const world: World
world } = 
function useSteamAudio(): SteamAudioContextValue
useSteamAudio()

Returns the current world, listener, and scene. Must be called inside <SteamAudio>.

`<SteamAudioListener>`

Synchronizes the R3F camera (or a custom object) to world.listener.

Props

object : Optional ref to an Object3D to use as the listener transform. Defaults to the R3F camera.

`<SteamAudioEnvironment>`

Creates optional reflection and reverb buses and wires them to a destination.

Props

destination : AudioNode | null — where buses are connected. Defaults to world.audioContext.destination.

reflections : boolean | ReflectionBusSettings — enables and configures a reflection bus.

reverb : false | (ReverbBusSettings & ReverbSettings) — enables and configures a reverb bus, and configures listener reverb.

children : React nodes rendered inside the environment context.

`useSteamAudioEnvironment()`

import { 
const useSteamAudioEnvironment: () => EnvironmentValue
useSteamAudioEnvironment } from 'three-steam-audio/react'

const { 
const reflectionBus: ReflectionBusNode | undefined
reflectionBus, 
const reverbBus: ReverbBusNode | undefined
reverbBus } = 
function useSteamAudioEnvironment(): EnvironmentValue
useSteamAudioEnvironment()

Returns the buses created by the nearest <SteamAudioEnvironment>, if any.

`<AcousticMesh>`

Wraps children meshes and registers them as acoustic geometry.

Props

material : AcousticMaterial | readonly AcousticMaterial[] | ((mesh: Mesh) => AcousticMaterial | readonly AcousticMaterial[]) — material or materials to apply.

dynamic : boolean — registers meshes as dynamic geometry. Default: false.

All other props are forwarded to the inner <group>.

Does not support SkinnedMesh or morph targets.

`<SteamAudioSource>`

Declarative source component.

Props

input : AudioNode | null — the mono audio input.

destination : AudioNode | null — where to connect the node’s main output.

hrtf : boolean.

airAbsorption : boolean.

occlusion : 'raycast' | 'volumetric' | false.

transmission : 'frequency-dependent' | 'frequency-independent' | boolean.

directivity : { dipoleWeight?: number, dipolePower?: number }.

spatialBlend : number.

reflections : SourceSettings['reflections'].

reflectionSend : number — gain to the environment reflection bus.

reverbSend : number — gain to the environment reverb bus.

settings : SourceSettings — full source settings object. Other props are merged into this object.

onReady : (api: SteamAudioSourceApi) => void — called when the source group is mounted.

All other props are forwarded to the inner <group>.

`useSteamAudioSource(object, settings?)`

Lower-level hook that creates a source and node tied to an Object3D ref.

import { 
function useRef<T>(initialValue: T): RefObject<T> (+2 overloads)
useRef returns a mutable ref object whose .current property is initialized to the passed argument
(initialValue). The returned object will persist for the full lifetime of the component.
Note that useRef() is useful for more than the ref attribute. It’s handy for keeping any mutable
value around similar to how you’d use instance fields in classes.
@version ― 16.8.0
@see ― https://react.dev/reference/react/useRef
useRef } from 'react'
import { 
const useSteamAudioSource: (object: RefObject<null | Object3D>, settings?: SourceSettings) => {
    node: SteamAudioNode;
    source: Source;
}
useSteamAudioSource } from 'three-steam-audio/react'
import type { 
class Object3D<TEventMap extends Object3DEventMap = Object3DEventMap>
interface Object3D<TEventMap extends Object3DEventMap = Object3DEventMap>
This is the base class for most objects in three.js and provides a set of properties and methods for manipulating objects in 3D space.
@remarks ― Note that this can be used for grouping objects via the THREE.Object3D.add .add() method which adds the object as a child,
however it is better to use THREE.Group Group for this.
@see ― https://threejs.org/docs/index.html#api/en/core/Object3D Official Documentation
@see ― https://github.com/mrdoob/three.js/blob/master/src/core/Object3D.js Source
Object3D } from 'three'

const 
const objectRef: RefObject<Object3D<Object3DEventMap> | null>
objectRef = 
useRef<Object3D<Object3DEventMap>>(initialValue: Object3D<Object3DEventMap> | null): RefObject<Object3D<Object3DEventMap> | null> (+2 overloads)
useRef returns a mutable ref object whose .current property is initialized to the passed argument
(initialValue). The returned object will persist for the full lifetime of the component.
Note that useRef() is useful for more than the ref attribute. It’s handy for keeping any mutable
value around similar to how you’d use instance fields in classes.
@version ― 16.8.0
@see ― https://react.dev/reference/react/useRef
useRef<
class Object3D<TEventMap extends Object3DEventMap = Object3DEventMap>
interface Object3D<TEventMap extends Object3DEventMap = Object3DEventMap>
This is the base class for most objects in three.js and provides a set of properties and methods for manipulating objects in 3D space.
@remarks ― Note that this can be used for grouping objects via the THREE.Object3D.add .add() method which adds the object as a child,
however it is better to use THREE.Group Group for this.
@see ― https://threejs.org/docs/index.html#api/en/core/Object3D Official Documentation
@see ― https://github.com/mrdoob/three.js/blob/master/src/core/Object3D.js Source
Object3D>(null)
const { 
const node: SteamAudioNode
node, 
const source: Source
source } = 
function useSteamAudioSource(object: RefObject<null | Object3D>, settings?: SourceSettings): {
    node: SteamAudioNode;
    source: Source;
}
useSteamAudioSource(
const objectRef: RefObject<Object3D<Object3DEventMap> | null>
objectRef)

`SteamAudioSourceApi`

import type { 
class Group<TEventMap extends Object3DEventMap = Object3DEventMap>
Its purpose is to make working with groups of objects syntactically clearer.
@remarks ― This is almost identical to an Object3DObject3D
@example 
const geometry = new THREE.BoxGeometry(1, 1, 1);
const material = new THREE.MeshBasicMaterial({
    color: 0x00ff00
});
const cubeA = new THREE.Mesh(geometry, material);
cubeA.position.set(100, 100, 0);
const cubeB = new THREE.Mesh(geometry, material);
cubeB.position.set(-100, -100, 0);
//create a Group and add the two cubes
//These cubes can now be rotated / scaled etc as a Group  * const Group = new THREE.Group();
group.add(cubeA);
group.add(cubeB);
scene.add(group);
@see ― https://threejs.org/docs/index.html#api/en/objects/Group Official Documentation
@see ― https://github.com/mrdoob/three.js/blob/master/src/objects/Group.js Source
Group } from 'three'
import type { 
class SteamAudioNode
SteamAudioNode } from 'three-steam-audio'
import type { 
(alias) interface Source
import Source
Source } from 'three-steam-audio'

interface 
interface SteamAudioSourceApi
SteamAudioSourceApi {
  
SteamAudioSourceApi.group: Group<Object3DEventMap>
group: 
class Group<TEventMap extends Object3DEventMap = Object3DEventMap>
Its purpose is to make working with groups of objects syntactically clearer.
@remarks ― This is almost identical to an Object3DObject3D
@example 
const geometry = new THREE.BoxGeometry(1, 1, 1);
const material = new THREE.MeshBasicMaterial({
    color: 0x00ff00
});
const cubeA = new THREE.Mesh(geometry, material);
cubeA.position.set(100, 100, 0);
const cubeB = new THREE.Mesh(geometry, material);
cubeB.position.set(-100, -100, 0);
//create a Group and add the two cubes
//These cubes can now be rotated / scaled etc as a Group  * const Group = new THREE.Group();
group.add(cubeA);
group.add(cubeB);
scene.add(group);
@see ― https://threejs.org/docs/index.html#api/en/objects/Group Official Documentation
@see ― https://github.com/mrdoob/three.js/blob/master/src/objects/Group.js Source
Group
  
SteamAudioSourceApi.node: SteamAudioNode
node: 
class SteamAudioNode
SteamAudioNode
  
SteamAudioSourceApi.source: Source
source: 
(alias) interface Source
import Source
Source
}