Appearance
@bendyline/molen-client/audio
Molen rendering client: three.js wrapper, snapshot sync, interpolation.
ts
import { /* … */ } from '@bendyline/molen-client/audio';Classes
AudioDirector
Constructors
Constructor
ts
new AudioDirector(opts): AudioDirector;Parameters
opts
Returns
Methods
handleEvent()
ts
handleEvent(event, tick?): void;Queue an engine event (audio.play|stop|music or a type mapped under events).
Parameters
event
EngineEvent
tick?
number
Returns
void
music()
ts
music(playlist, opts?): void;Parameters
playlist
string | string[] | null
opts?
crossfadeS?
number
Returns
void
play()
ts
play(sound, opts?): string;Host-side one-shot or loop (UI clicks, host-owned engines). Returns a handle for stop.
Parameters
sound
string
opts?
bus?
string
entity?
string
gain?
number
loop?
boolean
pitch?
number
position?
Returns
string
reset()
ts
reset(fadeS?): VoiceCommand[];Stop everything (fading) and forget all state except warnings.
Parameters
fadeS?
number
Returns
setBank()
ts
setBank(bank): void;Parameters
bank
Returns
void
setEnvironment()
ts
setEnvironment(environment): void;Parameters
environment
AudioEnvironmentData | undefined
Returns
void
stop()
ts
stop(target, fadeS?): void;Parameters
target
| string | { entity?: string; sound?: string; }
fadeS?
number
Returns
void
update()
ts
update(input): VoiceCommand[];Parameters
input
Returns
voices()
ts
voices(): VoiceSnapshot[];Persistent voices currently alive (loops, ambience, zones, music).
Returns
warnings()
ts
warnings(): readonly string[];Returns
readonly string[]
Gate
Rising/falling edge gate: a rule turns on after enterMs true and off after exitMs false.
Constructors
Constructor
ts
new Gate(enterMs?, exitMs?): Gate;Parameters
enterMs?
number
exitMs?
number
Returns
Properties
active
ts
active: boolean;Methods
update()
ts
update(raw, nowMs): boolean;Parameters
raw
boolean
nowMs
number
Returns
boolean
WebAudioBackend
Plays director commands through Web Audio: buses, panners, looped buffers, fades.
Implements
Constructors
Constructor
ts
new WebAudioBackend(opts): WebAudioBackend;Parameters
opts
Returns
Properties
context
ts
readonly context: AudioContext;Accessors
unlocked
Get Signature
ts
get unlocked(): boolean;Returns
boolean
Implementation of
Methods
apply()
ts
apply(commands): void;Parameters
commands
readonly VoiceCommand[]
Returns
void
Implementation of
dispose()
ts
dispose(): void;Returns
void
Implementation of
preload()
ts
preload(refs): Promise<void>;Decode clips ahead of first use.
Parameters
refs
readonly string[]
Returns
Promise<void>
Implementation of
setSuspended()
ts
setSuspended(suspended): void;Pause/resume output without losing voices (page hidden, game paused).
Parameters
suspended
boolean
Returns
void
Implementation of
stats()
ts
stats(): AudioBackendStats;Returns
Implementation of
unlock()
ts
unlock(): Promise<void>;Resume audio output; browsers require a user gesture first.
Returns
Promise<void>
Implementation of
Interfaces
AudioBackend
Realizes voice commands. WebAudioBackend plays them; createRecordingBackend logs them.
Extended by
Properties
unlocked
ts
readonly unlocked: boolean;Methods
apply()
ts
apply(commands): void;Parameters
commands
readonly VoiceCommand[]
Returns
void
dispose()
ts
dispose(): void;Returns
void
preload()?
ts
optional preload(refs): Promise<void>;Decode clips ahead of first use.
Parameters
refs
readonly string[]
Returns
Promise<void>
setSuspended()?
ts
optional setSuspended(suspended): void;Pause/resume output without losing voices (page hidden, game paused).
Parameters
suspended
boolean
Returns
void
stats()
ts
stats(): AudioBackendStats;Returns
unlock()
ts
unlock(): Promise<void>;Resume audio output; browsers require a user gesture first.
Returns
Promise<void>
AudioBackendStats
Properties
decoded
ts
decoded: number;pending
ts
pending: number;state
ts
state: "running" | "suspended" | "closed" | "headless";voices
ts
voices: number;AudioCameraLike
Anything with a three.js-style world matrix (column-major 4×4 elements).
Properties
matrixWorld
ts
readonly matrixWorld: object;elements
ts
readonly elements: ArrayLike<number>;AudioClientLike
The slice of a Worker-linked MolenClient the audio layer reads.
Properties
tick
ts
readonly tick: number | undefined;Methods
entities()
ts
entities(): string[];Returns
string[]
get()
ts
get(id, component): JsonObject | undefined;Parameters
id
string
component
string
Returns
JsonObject | undefined
onEvent()
ts
onEvent(type, cb): () => void;Parameters
type
string
cb
(event, tick) => void
Returns
() => void
AudioDirectorOptions
Properties
bank
ts
bank: SoundBank;environment?
ts
optional environment?: AudioEnvironmentData;Host soundscape rules; a scene's audioEnvironment entity overrides these key by key.
maxOneShots?
ts
optional maxOneShots?: number;Concurrent one-shot budget; the oldest is cut when exceeded. Default 16.
onWarning?
ts
optional onWarning?: (message) => void;Called once per distinct warning (unknown sound ids, unknown signals).
Parameters
message
string
Returns
void
seed?
ts
optional seed?: string | number;Seed mixed into clip/pitch variation.
AudioEntitySource
The structural slice of an entity store the director reads. Implemented over a Worker-linked MolenClient (entitySourceFromClient) and over a main-thread kernel World (entitySourceFromWorld); a kernel-less viewer passes none.
Properties
tick
ts
readonly tick: number | undefined;tickRate?
ts
readonly optional tickRate?: number;Methods
each()
ts
each(component): Iterable<[string, JsonObject]>;Every entity carrying component, with that component's (read-only) data.
Parameters
component
string
Returns
Iterable<[string, JsonObject]>
get()
ts
get(id, component): JsonObject | undefined;Parameters
id
string
component
string
Returns
JsonObject | undefined
onEvent()?
ts
optional onEvent(cb): () => void;Subscribe to every engine event; returns an unsubscribe.
Parameters
cb
(event, tick) => void
Returns
() => void
AudioEnvironmentSignals
World-level signals: weather, sky and anything else the host wants to expose as host.*.
Properties
host?
ts
optional host?: Record<string, AudioScalar | undefined>;sky?
ts
optional sky?: AudioSkySignals;weather?
ts
optional weather?: WeatherData;AudioLayer
Properties
backend
ts
readonly backend: AudioBackend;director
ts
readonly director: AudioDirector;muted
ts
readonly muted: boolean;unlocked
ts
readonly unlocked: boolean;volume
ts
readonly volume: number;Methods
attachClient()
ts
attachClient(client, opts?): () => void;Read entities and events from a Worker-linked client (game samples).
Parameters
client
opts?
tickRate?
number
Returns
() => void
attachWorld()
ts
attachWorld(world): () => void;Read entities and events from a main-thread kernel World (vehicles, aircraft).
Parameters
world
Returns
() => void
dispose()
ts
dispose(): void;Returns
void
music()
ts
music(playlist, opts?): void;Parameters
playlist
string | string[] | null
opts?
crossfadeS?
number
Returns
void
play()
ts
play(sound, opts?): string;Parameters
sound
string
opts?
bus?
string
entity?
string
gain?
number
loop?
boolean
pitch?
number
position?
Returns
string
setBanks()
ts
setBanks(banks): void;Parameters
banks
readonly (SoundbankDoc | SoundbankInput)[]
Returns
void
setBusGain()
ts
setBusGain(bus, gain): void;Host-side bus trim, multiplied with the environment's bus gain.
Parameters
bus
string
gain
number
Returns
void
setEnvironment()
ts
setEnvironment(environment): void;Parameters
environment
AudioEnvironmentData | undefined
Returns
void
setMuted()
ts
setMuted(muted): void;Parameters
muted
boolean
Returns
void
setSource()
ts
setSource(source): void;Plug in any entity source; undefined detaches.
Parameters
source
AudioEntitySource | undefined
Returns
void
setSuspended()
ts
setSuspended(suspended): void;Parameters
suspended
boolean
Returns
void
setVolume()
ts
setVolume(volume): void;Parameters
volume
number
Returns
void
stats()
ts
stats(): AudioLayerStats;Returns
stop()
ts
stop(target, fadeS?): void;Parameters
target
| string | { entity?: string; sound?: string; }
fadeS?
number
Returns
void
unlock()
ts
unlock(): Promise<void>;Returns
Promise<void>
update()
ts
update(
nowMs,
listener?,
signals?
): void;Advance one frame: resolve rules against the listener and signals, then play the diff.
Parameters
nowMs
number
listener?
Partial<AudioListenerState>
signals?
Returns
void
AudioLayerOptions
Properties
backend?
ts
optional backend?: AudioBackend;Default: Web Audio when available (and a provider is given), else a silent recorder.
banks
ts
banks: readonly (SoundbankDoc | SoundbankInput)[];Sound banks, earliest first; later banks override sounds with the same id.
environment?
ts
optional environment?: AudioEnvironmentData;Host soundscape rules; a scene's audioEnvironment entity overrides them key by key.
maxOneShots?
ts
optional maxOneShots?: number;muted?
ts
optional muted?: boolean;onWarning?
ts
optional onWarning?: (message) => void;Parameters
message
string
Returns
void
provider?
ts
optional provider?: AssetProvider;Loads clip bytes; required for the default Web Audio backend.
renderer?
ts
optional renderer?: AudioRendererLike;Listener from this camera and sky/weather signals from this renderer, when given.
seed?
ts
optional seed?: string | number;signals?
ts
optional signals?: () => AudioEnvironmentSignals | undefined;Extra signals merged over the renderer's each update (e.g. host.landcover).
Returns
AudioEnvironmentSignals | undefined
suspendWhenHidden?
ts
optional suspendWhenHidden?: boolean;Suspend output while the page is hidden; default true.
volume?
ts
optional volume?: number;Master volume 0–1 (default 1) and mute.
AudioLayerStats
Properties
backend
ts
backend: AudioBackendStats;voices
ts
voices: number;warnings
ts
warnings: number;AudioListenerState
Where the ears are, in world space (render origin already added back).
Properties
forward
ts
forward: AudioVec3;Unit look direction.
grounded?
ts
optional grounded?: boolean;false suppresses footsteps; undefined counts as grounded.
heightAboveGround?
ts
optional heightAboveGround?: number;Height above the ground under the listener (m); the listener.heightAboveGround signal. Hosts with terrain report it so ground-level ambience (birds, traffic) fades as the listener rises.
indoors?
ts
optional indoors?: boolean;true when the listener is inside a building.
mode?
ts
optional mode?: string;Host navigation mode: walk, drive, fly, orbit, pilot… (the listener.mode signal).
position
ts
position: AudioVec3;speed?
ts
optional speed?: number;Speed (m/s); overrides the measured value.
surface?
ts
optional surface?: string;Surface under the listener (grass, concrete, wood…), selects footstep sounds.
up
ts
up: AudioVec3;Unit up direction.
velocity?
ts
optional velocity?: AudioVec3;World velocity (m/s); when absent the director measures it between updates.
AudioPackSetLike
The slice of a @bendyline/molen-pack PackSet this needs (structural: no pack dependency).
Methods
provided()
ts
provided(role): object[];Parameters
role
string
Returns
object[]
readJson()
ts
readJson<T>(ref): Promise<T>;Type Parameters
T
T = unknown
Parameters
ref
string
Returns
Promise<T>
AudioRendererLike
The renderer slice the layer reads: camera pose, world origin, sky and weather state.
Properties
camera
ts
readonly camera: AudioCameraLike;sky?
ts
readonly optional sky?: object;frame?
ts
readonly optional frame?: AudioSkySignals;weather?
ts
readonly optional weather?: object;data?
ts
readonly optional data?: WeatherData;Methods
getWorldOrigin()
ts
getWorldOrigin(): ArrayLike<number>;Returns
ArrayLike<number>
AudioSkySignals
Sky state the director reads (a subset of the client's SkyFrame).
Properties
daylight
ts
daylight: number;starVisibility?
ts
optional starVisibility?: number;sunDirection?
ts
optional sunDirection?: AudioVec3;AudioWorldLike
The slice of a main-thread kernel World the audio layer reads (structural, no import).
Properties
tick
ts
readonly tick: number;tickRate
ts
readonly tickRate: number;Methods
get()
ts
get(id, component): unknown;Parameters
id
string
component
name
string
Returns
unknown
on()
ts
on(type, handler): () => void;Parameters
type
string
handler
(event, ctx) => void
Returns
() => void
query()
ts
query(component): Iterable<[string, ...JsonObject[]]>;Parameters
component
name
string
Returns
Iterable<[string, ...JsonObject[]]>
DirectorInput
Properties
listener?
ts
optional listener?: Partial<AudioListenerState>;nowMs
ts
nowMs: number;Wall-clock milliseconds (performance.now in browsers; simulated time headlessly).
signals?
ts
optional signals?: AudioEnvironmentSignals;source?
ts
optional source?: AudioEntitySource;EntityMotion
Per-entity motion the director measures from transforms (the self.* signals).
Properties
distance
ts
distance: number;pos
ts
pos: [number, number, number];speed
ts
speed: number;RecordingBackend
Realizes voice commands. WebAudioBackend plays them; createRecordingBackend logs them.
Extends
Properties
active
ts
readonly active: ReadonlyMap<string, {
bus: string;
fadeInS?: number;
gain: number;
loop: boolean;
loopEnd?: number;
loopStart?: number;
op: "start";
pitch: number;
ref: string;
sound: string;
spatial?: VoiceSpatial;
voice: string;
}>;Looping voices currently started and not stopped.
log
ts
readonly log: VoiceCommand[];Every command applied, in order.
unlocked
ts
readonly unlocked: boolean;Inherited from
Methods
apply()
ts
apply(commands): void;Parameters
commands
readonly VoiceCommand[]
Returns
void
Inherited from
clear()
ts
clear(): void;Returns
void
dispose()
ts
dispose(): void;Returns
void
Inherited from
preload()?
ts
optional preload(refs): Promise<void>;Decode clips ahead of first use.
Parameters
refs
readonly string[]
Returns
Promise<void>
Inherited from
setSuspended()?
ts
optional setSuspended(suspended): void;Pause/resume output without losing voices (page hidden, game paused).
Parameters
suspended
boolean
Returns
void
Inherited from
stats()
ts
stats(): AudioBackendStats;Returns
Inherited from
unlock()
ts
unlock(): Promise<void>;Resume audio output; browsers require a user gesture first.
Returns
Promise<void>
Inherited from
ResolvedSound
Properties
bank
ts
bank: string;Id of the bank that supplied this sound (later banks override earlier ones).
entry
ts
entry: SoundEntry;id
ts
id: string;refs
ts
refs: readonly string[];Clip refs ready for AssetProvider.load.
SignalContext
Properties
entity
ts
entity: string | undefined;The entity <component>.<field> and self.* paths resolve on.
listener
ts
listener: AudioListenerState & object;Type Declaration
distance
ts
distance: number;speed
ts
speed: number;motion
ts
motion: ReadonlyMap<string, EntityMotion>;occupied
ts
occupied: ReadonlySet<string>;Entities someone is mounted in (a mounted component names them): self.occupied.
seconds
ts
seconds: number;signals
ts
signals: AudioEnvironmentSignals;source
ts
source: AudioEntitySource | undefined;SoundBank
Methods
ids()
ts
ids(): readonly string[];Returns
readonly string[]
resolve()
ts
resolve(id): ResolvedSound | undefined;Parameters
id
string
Returns
ResolvedSound | undefined
SoundbankInput
A bank document plus where its clip paths resolve (e.g. pack:molen.sounds/, sounds/).
Properties
base?
ts
optional base?: string;Prefix joined to every clip path; default none (clips are provider refs as written).
doc
ts
doc: SoundbankDoc;Unlockable
Something that needs a user gesture before it can make sound.
Properties
unlocked
ts
readonly unlocked: boolean;Methods
unlock()
ts
unlock(): Promise<void>;Returns
Promise<void>
VoiceSnapshot
A persistent voice the director is keeping alive.
Properties
bus
ts
bus: string;entity?
ts
optional entity?: string;gain
ts
gain: number;key
ts
key: string;loop
ts
loop: boolean;pitch
ts
pitch: number;position?
ts
optional position?: AudioVec3;sound
ts
sound: string;voice
ts
voice: string;VoiceSpatial
Properties
maxDistance
ts
maxDistance: number;model
ts
model: "linear" | "inverse" | "exponential";position
ts
position: AudioVec3;refDistance
ts
refDistance: number;rolloff
ts
rolloff: number;WebAudioBackendOptions
Properties
context?
ts
optional context?: AudioContext;Supply a context (tests, shared graphs); default a new interactive AudioContext.
onError?
ts
optional onError?: (message) => void;Parameters
message
string
Returns
void
provider
ts
provider: AssetProvider;Loads clip bytes by ref (a pack set's assetProvider(), or createUrlAssetProvider).
staleOneShotS?
ts
optional staleOneShotS?: number;Drop a one-shot whose clip is still decoding this many seconds after it was requested.
Type Aliases
AudioVec3
ts
type AudioVec3 = [number, number, number];SignalValue
ts
type SignalValue = AudioScalar | undefined;VoiceCommand
ts
type VoiceCommand =
| {
bus: string;
fadeInS?: number;
gain: number;
loop: boolean;
loopEnd?: number;
loopStart?: number;
op: "start";
pitch: number;
ref: string;
sound: string;
spatial?: VoiceSpatial;
voice: string;
}
| {
gain?: number;
op: "set";
pitch?: number;
position?: AudioVec3;
rampS?: number;
voice: string;
}
| {
fadeS?: number;
op: "stop";
voice: string;
}
| {
forward: AudioVec3;
op: "listener";
position: AudioVec3;
up: AudioVec3;
}
| {
bus: string;
gain: number;
op: "bus";
};The director's output: a diff the backend applies.
Functions
attachAutoplayUnlock()
ts
function attachAutoplayUnlock(audio, target?): () => void;Browsers start audio suspended until the page gets a gesture. Resume on the first pointer, key or touch on target (default the window); returns a detach function.
Parameters
audio
target?
EventTarget
Returns
() => void
createAudioLayer()
ts
function createAudioLayer(opts): AudioLayer;The audio layer a host creates once and updates each frame. It owns the director (rules) and the backend (playback). Kernel-less viewers call update with listener state only; kernel hosts also attachClient or attachWorld so entity components and events reach the director.
Parameters
opts
Returns
createRecordingBackend()
ts
function createRecordingBackend(opts?): RecordingBackend;A silent backend that records commands: tests, headless planning, and hosts without audio.
Parameters
opts?
unlocked?
boolean
Returns
curve()
ts
function curve(points, x): number;Piecewise-linear lookup over [input, output] points, clamped at both ends.
Parameters
points
readonly readonly [number, number][]
x
number
Returns
number
entitySourceFromClient()
ts
function entitySourceFromClient(client, opts?): AudioEntitySource;Entity source over a kernel-linked client. Reads are memoized per mirrored tick, because client.get returns a detached copy and the mirror only changes when a new tick arrives.
Parameters
client
opts?
tickRate?
number
Returns
entitySourceFromWorld()
ts
function entitySourceFromWorld(world): AudioEntitySource;Entity source over a main-thread World (EarthVehicles, headless tooling).
Parameters
world
Returns
evalWhen()
ts
function evalWhen(
when,
ctx,
active?
): boolean;Every condition must hold (AND). active widens numeric ranges (hysteresis).
Parameters
when
AudioWhen | undefined
ctx
active?
boolean
Returns
boolean
hash32()
ts
function hash32(...parts): number;32-bit string/number hash (FNV-1a + fmix32); deterministic across hosts.
Parameters
parts
...(string | number)[]
Returns
number
listenerFromCamera()
ts
function listenerFromCamera(camera, worldOrigin?): Pick<AudioListenerState, "position" | "forward" | "up">;Listener pose from a render camera. The renderer keeps the camera near the origin (floating origin); pass renderer.getWorldOrigin() so the listener sits in the same world space as entity transforms. Reads the matrix only, so it needs no three.js import.
Parameters
camera
worldOrigin?
ArrayLike<number>
Returns
Pick<AudioListenerState, "position" | "forward" | "up">
loadPackSoundbanks()
ts
function loadPackSoundbanks(set, onWarning?): Promise<SoundbankInput[]>;Every provides.soundbank document in a pack set, validated, with clip refs rooted in its pack (pack:<id>/<dir>/), ready for createAudioLayer({ banks, provider: set.assetProvider() }). Invalid banks are reported through onWarning and skipped.
Parameters
set
onWarning?
(message) => void
Returns
Promise<SoundbankInput[]>
mergeSoundbanks()
ts
function mergeSoundbanks(inputs): SoundBank;Merge banks; a later bank's sound replaces an earlier one with the same id (reskinning).
Parameters
inputs
readonly (SoundbankDoc | SoundbankInput)[]
Returns
resolveSignal()
ts
function resolveSignal(path, ctx): SignalValue;Resolve a signal path to a scalar, or undefined when it has no value here.
Parameters
path
string
ctx
Returns
unitRandom()
ts
function unitRandom(...parts): number;Deterministic [0, 1) from any key parts.
Parameters
parts
...(string | number)[]
Returns
number