Audio · interface

SpatialOptions

A sound placed in the world, heard from where the listener is standing.

interface SpatialOptions

import type { SpatialOptions } from '@driftengine/audio';

In depth

  buffer source ─ detune ─→ occlusion lowpass ─→ occlusion gain ─→ panner (HRTF) ─→ a bus

A function rather than a method on the console, and that is a size decision rather than a style one. A method would be a static reference from the mix to the panner, which no bundler can shake out, so every consumer that imports the mix would carry the HRTF machinery whether or not it ever places a sound. scripts/size-gate.test.mjs publishes what each package costs and promises you pay only for what you import; this is what keeps that true.

This is the expensive path and it is meant to be. distanceGain and stereoPan still exist and are still right for a fire, a shoreline or a storm column — diffuse things where what a player reads is "how close" and "which way". Reach for a panner when the direction is information: a footstep behind you, a voice through a doorway, something you are meant to turn towards.

Properties

Name	Type	Description
`bus`readonlyoptional	`MixBus`	Where this lands in the mix. The console's `effects` bus when omitted.
`loop`readonlyoptional	`boolean`
`doppler`readonlyoptional	`boolean`	Shift the pitch with relative motion. More Off by default, deliberately. On a looping bed — a fire, a waterfall — a listener walking past makes the bed's pitch wander, which reads as the sound being broken rather than as motion. Turn it on for something that genuinely passes: a vehicle, a projectile, a siren.
`speedOfSound`readonlyoptional	`number`	Metres per second. 343 in air; a game whose world is not in metres will want its own.
`maxDopplerCents`readonlyoptional	`number`	How far the pitch is allowed to move, in cents. A whole tone each way by default.
`refDistance`readonlyoptional	`number`	Distance-model parameters, passed to the panner unchanged.
`maxDistance`readonlyoptional	`number`
`rolloff`readonlyoptional	`number`
`occlusionRate`readonlyoptional	`number`	How fast occlusion follows the world, per second. More Slow enough that a probe landing on a different answer does not click, fast enough that walking through a doorway is heard as walking through a doorway.