World

A World is created by createWorld() and is the factory for point sources, Ambisonic sources, audio nodes, reflection buses, and reverb buses. It also owns the acoustic scene and the listener.

createWorld(options)

async function createWorld(options: WorldOptions): Promise<World>

Creates and initializes a world. This function loads the Steam Audio WASM module, fetches the AudioWorklet processor, and adds it to the provided AudioContext.

WorldOptions

audioContext : Required. The AudioContext that all audio nodes created from this world will use.

maxSources : Maximum number of sources that can exist simultaneously. Default: 32.

frameSize : Number of samples processed per audio frame. Default: 1024.

hrtf : World-level HRTF settings, applied when each audio worklet is initialized:

• type — 'default' (the built-in HRTF, default) or 'sofa'.
• volume — linear HRTF correction gain. Must be finite and at least 0. Default: 1.
• normalization — 'none' or 'rms'. RMS normalization keeps HRTF loudness more consistent between directions. Default: 'none'.
• data — required when type is 'sofa': an ArrayBuffer containing a SimpleFreeFieldHRIR SOFA file. The same data is reused by all nodes in the World.

direct : Direct sound world settings:

• updateRate — how often direct simulation runs, in Hz. Default: 60
• maxOcclusionSamples — maximum volumetric occlusion samples for any source. Default depends on occlusionQuality

occlusionQuality : Preset that affects direct.maxOcclusionSamples. One of 'low', 'medium', 'high'. Default: 'medium'.

perspectiveCorrection : Optional desktop-screen spatialization settings. This follows Steam Audio’s Unity integration: it changes only the rendered direction of sources that opt in; direct simulation, distance attenuation, occlusion, and reflections continue to use world-space coordinates.

• enabled — enables correction globally. Default: false.
• factor — screen-size calibration factor. Must be finite and at least 0. Default: 1.
• applyInXR — enables correction for an XR array camera. Default: false; desktop correction is normally disabled in XR.

reflections : false to disable reflections, or an object with upper bounds:

• maxRays — default 4096
• maxDuration — default 1
• maxOrder — default 1
• diffuseSamples — default 32
• maxSources — maximum real-time reflection sources
• updateRate — how often reflection simulation runs, in Hz. Default: 10
• initial — initial runtime reflection settings

moduleFactory : Optional custom factory used to instantiate the Emscripten module.

Properties

world.audioContext : The AudioContext passed to createWorld.

world.listener : The world’s Listener.

world.scene : The world’s AcousticScene.

Methods

createSource(settings?)

world.createSource(settings?: SourceSettings): Source

Creates a new source. Throws if maxSources would be exceeded. See SourceSettings.

createNode(source)

world.createNode(source: Source): SteamAudioNode

Creates an AudioWorklet node for the given source. The source must have been created by this world.

createAmbisonicSource(settings?)

world.createAmbisonicSource(settings?: AmbisonicSourceSettings): AmbisonicSource

Creates an independent Unity-compatible Ambisonic source. It does not consume maxSources. See AmbisonicSource.

createAmbisonicNode(source)

world.createAmbisonicNode(source: AmbisonicSource): SteamAudioAmbisonicNode

Creates the stereo AudioWorklet decoder for an Ambisonic source.

createReflectionBus(settings?)

world.createReflectionBus(settings?: ReflectionBusSettings): ReflectionBusNode

Creates a bus for rendering per-source reflections. Requires reflections to be enabled for the world.

createReverbBus(settings?)

world.createReverbBus(settings?: ReverbBusSettings): ReverbBusNode

Creates a bus for rendering listener reverb. Requires reflections to be enabled for the world.

setPerspectiveCorrection(settings)

world.setPerspectiveCorrection(settings: false | PerspectiveCorrectionSettings): void

Enables, disables, or replaces the runtime perspective-correction settings. It republishes rendering controls only; it does not change acoustic simulation.

setReflectionSettings(settings)

world.setReflectionSettings(settings: ReflectionSimulationSettings): void

Tunes reflection simulation at runtime. All values are clamped to the maximums declared in WorldOptions.

settings.rays : Number of reflection rays to trace. Must not exceed maxRays.

settings.bounces : Maximum number of bounces per ray.

settings.duration : Simulation duration in seconds. Must not exceed maxDuration.

settings.ambisonicOrder : Ambisonic order. Must not exceed maxOrder.

settings.irradianceMinDistance : Minimum distance for irradiance sampling.

step(delta)

world.step(delta: number): void

Advances simulation by delta seconds. Runs direct simulation and, if enabled, reflection simulation according to their configured rates. Returns early if the AudioContext is not running.

dispose()

world.dispose(): void

Releases all native resources, audio nodes, buses, sources, and scene geometry.

SteamAudioError

class SteamAudioError extends Error {
  operation: string
  status: string
}

Thrown when a world, source, or audio node operation fails. operation identifies the function that failed, and status contains a short description of the failure.