@aosengine/audio

Interfaces

AudioBuses

The bus gain nodes, keyed by name.

Properties

master

readonly master: GainNode;

Sums sfx, music and voice; connected to context.destination.

music

readonly music: GainNode;

Music beds.

sfx

readonly sfx: GainNode;

One-shot gameplay sounds.

voice

readonly voice: GainNode;

Dialogue and say lines.

---

AudioEngine

The audio service: everything the host needs to run a frame of sound.

Properties

buses

readonly buses: AudioBuses;

The bus gain nodes. Adjust bus.gain.value for mixer sliders.

context

readonly context: AudioContext;

The context the graph lives on.

ended

readonly ended: number[];

Handles of sounds that ended since the host last cleared this array. AudioEngine.update appends to it; the host turns each entry into a sound-ended event and then clears it with ended.length = 0.

Methods

decode()

decode(id, data): Promise<AudioBuffer>;

Decode encoded audio bytes, memoised by id.

Parameters

Parameter	Type	Description
id	string	Manifest asset id, the cache key.
data	ArrayBuffer	Encoded bytes.

Returns

Promise<AudioBuffer>

The decoded buffer. Repeat calls with the same id share a promise.

dispose()

dispose(): void;

Stop everything, drop the graph, and close a context this engine created.

Returns

void

play()

play(args): void;

Start a voice.

Parameters

Parameter	Type	Description
args	PlayArgs	What to play, where and how loud.

Returns

void

resume()

resume(): Promise<void>;

Resume a context the browser suspended. Safe to call repeatedly.

Returns

Promise<void>

Resolves once the context is running.

setListener()

setListener(pos, rotQuat): void;

Move the listener.

Parameters

Parameter	Type	Description
pos	Vec3	World position.
rotQuat	Quat	Orientation; forward is local -Z, up is local +Y.

Returns

void

setVolume()

setVolume(id, v): void;

Change a playing voice's gain.

Parameters

Parameter	Type	Description
id	number	The sound handle. Unknown ids are ignored.
v	number	Linear gain, 0..1.

Returns

void

stop()

stop(id): void;

Stop a voice now and queue its sound-ended.

Parameters

Parameter	Type	Description
id	number	The handle passed to AudioEngine.play. Unknown ids are ignored.

Returns

void

update()

update(dt): void;

Advance the voice bookkeeping and drain ended voices into ended.

Parameters

Parameter	Type	Description
dt	number	Seconds since the previous call.

Returns

void

---

AudioEngineOptions

Options for createAudioEngine.

Extended by

• AudioModuleOptions

Properties

context?

optional context?: AudioContext;

An existing context to drive. When omitted a new AudioContext is constructed, which requires a DOM environment. Pass one in tests.

masterVolume?

optional masterVolume?: number;

Linear gain on the master bus, 0..1. Defaults to 1.

---

AudioModule

The 'audio' module. Its service is the AudioEngine it owns.

Extends

• EngineModule

Properties

id

readonly id: string;

Unique id. Also the service id when init returns a service.

Inherited from

EngineModule.id

order?

readonly optional order?: number;

Sort key. Lower runs first; equal keys keep registration order.

Rough convention: input -100, physics 0, gameplay 100, rendering helpers 200.

Inherited from

EngineModule.order

service

readonly service: AudioEngine;

The audio engine this module owns.

Also what init returns, so the registry publishes it under 'audio' and engine.get('audio') hands back this same object.

Methods

beginFrame()?

optional beginFrame(): void;

Run before the frame's fixed steps. Input capture lives here.

Returns

void

Inherited from

EngineModule.beginFrame

decodeAsset()

decodeAsset(idOrHandle): Promise<AudioBuffer>;

Decode the bytes behind an asset id or handle, memoised.

This is the bridge from a play-sound command — which carries an asset handle, never a URL — to the AudioBuffer AudioEngine.play wants. The asset must already be loaded; type: 'audio' entries load as an ArrayBuffer.

Parameters

Parameter	Type	Description
idOrHandle	string | number	Manifest asset id, or the handle the guest minted for it.

Returns

Promise<AudioBuffer>

The decoded buffer; rejects when the asset is missing or not audio.

dispose()

dispose(): void;

Release everything this module took.

Returns

void

Inherited from

EngineModule.dispose

endFrame()?

optional endFrame(): void;

Run after rendering. Input's end-of-frame bookkeeping lives here.

Returns

void

Inherited from

EngineModule.endFrame

fixedUpdate()?

optional fixedUpdate(dt): void;

Run once per fixed step.

Parameters

Parameter	Type	Description
dt	number	Always ctx.config.fixedDt.

Returns

void

Inherited from

EngineModule.fixedUpdate

init()

init(ctx): AudioEngine;

Acquire resources and publish the engine as the 'audio' service.

Parameters

Parameter	Type	Description
ctx	EngineContext	The host surface; only ctx.assets is read.

Returns

AudioEngine

The audio engine.

Overrides

EngineModule.init

update()

update(dt, alpha): void;

Pump the engine: advance voices and drain service.ended.

Always present on this module, so callers need no optional call.

Parameters

Parameter	Type	Description
dt	number	Wall-clock seconds since the previous frame.
alpha	number	Interpolation factor; unused by audio.

Returns

void

Overrides

EngineModule.update

---

AudioModuleOptions

Options for audio.

Extends

• AudioEngineOptions

Properties

context?

optional context?: AudioContext;

An existing context to drive. When omitted a new AudioContext is constructed, which requires a DOM environment. Pass one in tests.

Inherited from

AudioEngineOptions.context

masterVolume?

optional masterVolume?: number;

Linear gain on the master bus, 0..1. Defaults to 1.

Inherited from

AudioEngineOptions.masterVolume

order?

optional order?: number;

Position in the module order. Lower runs first. Defaults to 30.

unlockTarget?

optional unlockTarget?: EventTarget;

Where the one-time unlock listener is installed. Defaults to the global object; pass the canvas to scope it, or a stub in tests.

---

PlayArgs

One call to AudioEngine.play.

Properties

buffer

buffer: AudioBuffer;

The decoded buffer to play, normally from AudioEngine.decode.

bus?

optional bus?: BusName;

Bus to route through. Defaults to 'sfx'.

id

id: number;

Guest-minted sound handle. Replaces any sound already using this handle.

loop?

optional loop?: boolean;

Loop until stopped. Looping voices never end on their own. Defaults to false.

pos?

optional pos?: Vec3;

World position. When given the voice gets an HRTF PannerNode.

volume?

optional volume?: number;

Linear gain, 0..1. Defaults to 1.

Type Aliases

BusName

type BusName = "master" | "sfx" | "music" | "voice";

The buses a voice can be routed to. master is the sum of the other three.

---

Quat

type Quat = readonly [number, number, number, number];

A rotation, as a plain [x, y, z, w] quaternion (three.js / Jolt order).

---

Vec3

type Vec3 = readonly [number, number, number];

A world-space position, as a plain [x, y, z] array.

Variables

PACKAGE

const PACKAGE: "@aosengine/audio";

Package identity marker.

Example

import { PACKAGE } from '@aosengine/audio';

console.log(PACKAGE); // '@aosengine/audio'

Functions

audio()

function audio(options?): AudioModule;

Create the audio module.

Register it in the engine's module list. init returns the AudioEngine, so it becomes the 'audio' service: the host maps play-sound / stop-sound / set-listener straight onto its methods and drains ended into sound-ended events each frame.

Browsers keep an AudioContext suspended until the page sees a user gesture, so init installs a single pointerdown + keydown listener that calls resume() once and then removes itself.

Parameters

Parameter	Type	Description
options	AudioModuleOptions	Engine options, plus the unlock target and module order.

Returns

AudioModule

The module, ready to register.

Example

import { audio } from '@aosengine/audio';

const mod = audio({ masterVolume: 0.8 });
const engine = mod.init(ctx);

const buffer = await mod.decodeAsset('pistol');
engine.play({ id: 1, buffer, pos: [0, 1, -3] });
mod.update(1 / 60, 0);

---

createAudioEngine()

function createAudioEngine(options?): AudioEngine;

Create the audio engine.

The graph is voice -> [panner] -> bus -> master -> destination. Nothing is allocated per frame: voices are pooled, the listener basis is written into scratch arrays, and ended is reused.

Parameters

Parameter	Type	Description
options	AudioEngineOptions	Context to adopt and initial master gain.

Returns

AudioEngine

The engine, which is also the 'audio' module's service.

Example

import { createAudioEngine } from '@aosengine/audio';

const engine = createAudioEngine({ masterVolume: 0.8 });
const buffer = await engine.decode('pistol', bytes);

engine.play({ id: 1, buffer, pos: [3, 0, -4], bus: 'sfx' });
engine.update(1 / 60);
for (const id of engine.ended) console.log('ended', id);
engine.ended.length = 0;