API reference

Every public class, method, and event in @codexo/exojs. Generated from source.

C

classSound

@codexo/exojs / audio / stable

Pre-decoded short audio clip backed by an `AudioBuffer`. Sound is a **data descriptor** - it holds the decoded audio buffer, sprite definitions, and default playback parameters but does NOT start playback itself, and holds no per-playback spatial state (that lives on the Voice returned by playing it). Playback is driven by `AudioSystem.play(sound, options)` which returns a Voice handle. Multiple concurrent plays of the same Sound are supported up to `poolSize`. When the pool is full the configured SoundPoolStrategy decides which active voice to evict. Use AudioStream for long-form streaming audio (single source, decoded lazily) - `Sound` is best for short, frequently-triggered clips.

14
props
9
methods
0
events
Import
import { Sound } from '@codexo/exojs'

Pre-decoded short audio clip backed by an `AudioBuffer`.

Sound is a **data descriptor** - it holds the decoded audio buffer, sprite definitions, and default playback parameters but does NOT start playback itself, and holds no per-playback spatial state (that lives on the Voice returned by playing it). Playback is driven by `AudioSystem.play(sound, options)` which returns a Voice handle.

Multiple concurrent plays of the same Sound are supported up to `poolSize`. When the pool is full the configured SoundPoolStrategy decides which active voice to evict.

Use AudioStream for long-form streaming audio (single source, decoded lazily) - `Sound` is best for short, frequently-triggered clips.

Constructors1
new(audioBuffer: AudioBuffer | null, options: SoundOptionsConstruction options for Sound.): Sound
Methods9
addSprite(name: string, clip: AudioSpriteClipNamed sub-region of an AudioBuffer used as an audio sprite sheet. `start` / `end` are seconds into the buffer; `loop` makes the clip loop indefinitely when pla…): this
Define (or redefine) a named sub-region of the buffer. Redefining a name discards the sub-Sound Sound.sprite memoized for it, so the next lookup reflects the new window.
clip(offset: number, duration: number): Sound
Return a new Sound that plays only the [offset, offset + duration] sub-range (seconds) of this sound - an audio atlas / sprite-sheet clip. The clip does not copy anything: it reads the decoded AudioBuffer from the sound it was cut from at playback time, so it follows that sound through eviction and reload. It inherits this sound's playback defaults (volume, loop, playbackRate, muted) and pool configuration, and gets its own independent voice pool. Spatialization is not among them: a Sound carries none - it is set per play via PlayOptions and lives on the returned Voice. Available before the sound has loaded, and on a clip of a clip (the nested window is capped by the outer one).
createVoice(system: AudioSystemPer-Application owner of the audio mix: three pre-configured AudioBus instances (`master` ← `music` + `sound`), a single AudioListener for spatial audio, and a…, options: SoundPlayOptionsPer-call overrides for AudioSystem.play.): VoiceA live playback instance in the audio graph with a control surface. A Voice is created by playing a Playable via AudioSystem.play (and, later, by opening an `A…
Implements Playable. Called by AudioSystem.play; do not call directly - use app.audio.play(sound, options) instead. Creates one SoundVoice backed by a single AudioBufferSourceNode. Pool limits are enforced: if the pool is full the configured eviction strategy picks a victim to stop before the new voice starts.
destroy(): void
hasSprite(name: string): boolean
removeSprite(name: string): this
Remove a sprite definition and destroy the sub-Sound Sound.sprite memoized for it, stopping anything it still had playing.
setPoolSize(poolSize: number): this
setSprites(sprites: Readonly<Record<string, AudioSpriteClipNamed sub-region of an AudioBuffer used as an audio sprite sheet. `start` / `end` are seconds into the buffer; `loop` makes the clip loop indefinitely when pla…>>): this
Replace the whole sprite table. Every sub-Sound previously handed out by Sound.sprite is destroyed - the definitions they were derived from are gone, so keeping them alive would keep stale windows (and their voices) playing.
sprite(name: string): Sound
The Sound for a named sprite - the playback side of Sound.addSprite. Same concept as Sound.clip, addressed by name instead of by offset: a sub-Sound over the same decoded buffer, with the clip's own loop flag and its own voice pool. The result is memoized per name, so the pool is shared across every play of that sprite and repeated lookups are free. It stays valid until the name is redefined, removed, or this sound is destroyed.
Properties14
loop: boolean
Default loop flag applied to new voices.
muted: boolean
Default muted flag applied to new voices.
playbackRate: number
Default playback rate applied to new voices.
volume: number
Default volume applied to new voices.
audioBuffer: AudioBuffer | null
The underlying decoded audio data, or null for a deferred handle whose payload hasn't finished loading yet. Useful for sharing a single decoded buffer across multiple Sound instances. A Sound.clip / Sound.sprite reports the buffer its root currently holds, so it turns null while the root is evicted and picks the new one up on reload.
duration: number
Playable duration in seconds - the full buffer, or the clip span for a Sound.clip / Sound.sprite. 0 while no buffer is loaded.
error: Error | null
The error the last load failed with, or null outside 'failed'.
loaded: Promise<this>
Promise that settles with this sound once its payload has loaded - resolved immediately for 'ready' sounds, rejected with the load error for 'failed' ones. Re-materialized when a failed load is retried, so read it fresh from this getter rather than caching it across load cycles.
loadState: LoadStateValueLoad lifecycle of a seamless asset handle. Directly constructed assets are `'ready'`; a catalog leaf awaiting adoption is `'idle'`.
Load lifecycle of this sound. Directly constructed sounds are 'ready'; deferred handles returned by loader.get('theme.ogg') / loader.get(Asset.type('sound', src)) start 'loading' and become 'ready' once the payload fills in, or 'failed' when the load errors. A Sound.clip / Sound.sprite reports its root's lifecycle - it has no payload of its own to load.
poolSize: number
poolStrategy: SoundPoolStrategyEviction strategy used when the pool is full and a new play is requested. At the per-Sound level all pooled instances share the same priority, so `LowestPriori…
The eviction strategy used when the pool is at capacity.
priority: number
Sound priority. Used by the LowestPriority pool strategy. Higher values indicate higher priority (less likely to be evicted).
ready: boolean
true exactly when state is 'ready'.
state: LoadStateValueLoad lifecycle of a seamless asset handle. Directly constructed assets are `'ready'`; a catalog leaf awaiting adoption is `'idle'`.
Load lifecycle: 'idle' | 'loading' | 'ready' | 'failed'.
Source
src/audio/Sound.ts