Audio

View source
backend.Audio (Class)
Implements: spec.Audio

Clay backend audio implementation providing comprehensive sound management.

This class handles:

  • Audio resource loading and caching with reference counting
  • Sound playback control (play, pause, stop, loop)
  • Audio properties manipulation (volume, pan, pitch, position)
  • Streaming audio support for large files
  • Real-time audio filters and effects processing
  • Multi-bus audio system for grouping and mixing
  • Web Audio context management for browser compatibility
  • Platform-specific optimizations (native vs web)

The audio system uses Clay's underlying audio engine which supports:

  • On web: Web Audio API with AudioWorklet support
  • On native: Custom audio mixing with SDL audio backend

Audio resources are cached and reference counted to avoid redundant loading and ensure proper memory management.

Instance Members

clay
load(path: String, ?options: Null<LoadAudioOptions>, _done: Function): Void

Loads an audio resource from a file path or URL.

The method handles:

  • Local file loading (relative to assets path)
  • URL loading (http/https)
  • Cached resource reuse with reference counting
  • Asynchronous and synchronous loading modes
  • Streaming mode for large audio files
Name Type Default Description
path String The path to the audio file (relative to assets or absolute/URL)
options Null<LoadAudioOptions> (optional) Optional loading configuration: - loadMethod: SYNC for synchronous loading, ASYNC (default) for asynchronous - stream: true to stream large files instead of loading entirely in memory - immediate: Custom immediate callback queue for synchronization
_done Function Callback invoked with the loaded resource or null on failure
clay
createFromSamplesBuffer(buffer: Float32Array, samples: Int, channels: Int, sampleRate: Float, interleaved: Bool): AudioResource

Creates an audio resource from raw PCM sample data.

This is useful for:

  • Procedurally generated audio
  • Audio synthesis
  • Converting from other audio formats
Name Type Description
buffer Float32Array The raw PCM samples as 32-bit floats
samples Int Number of sample frames (total samples / channels)
channels Int Number of audio channels (1 for mono, 2 for stereo)
sampleRate Float Sample rate in Hz (e.g., 44100, 48000)
interleaved Bool Whether samples are interleaved (LRLRLR) or planar (LLL...RRR...)
Returns Description
AudioResource The created audio resource, or null on failure
clay
getDuration(resource: AudioResource): Float

Gets the duration of an audio resource in seconds.

Name Type Description
resource AudioResource The audio resource to query
Returns Description
Float Duration in seconds, or 0 if unknown
clay
resumeAudioContext(done: Function): Void

No-op on native platforms where audio context is always active.

Name Type Description
done Function Always called with true
clay
supportsHotReloadPath(): Bool

Indicates whether this backend supports hot-reloading audio files.

Returns Description
Bool true (Clay backend supports audio hot-reload)
clay
destroy(audio: AudioResource): Void

Destroys an audio resource and frees associated memory.

Uses reference counting - the resource is only truly destroyed when all references are released.

Name Type Description
audio AudioResource The audio resource to destroy
clay
mute(audio: AudioResource): AudioHandle

Creates a muted audio handle (not implemented in Clay backend).

Name Type Description
audio AudioResource The audio resource
Returns Description
AudioHandle -1 (invalid handle)
clay
play(audio: AudioResource, ?volume: Float = 0.5, ?pan: Float = 0, ?pitch: Float = 1, ?position: Float = 0, ?loop: Bool = false, ?bus: Int = 0): AudioHandle

Plays an audio resource with specified parameters.

Name Type Default Description
audio AudioResource The audio resource to play
volume Float 0.5 Playback volume (0.0 to 1.0, default 0.5)
pan Float 0 Stereo panning (-1.0 left to 1.0 right, 0 center)
pitch Float 1 Playback speed/pitch multiplier (1.0 = normal)
position Float 0 Start position in seconds
loop Bool false Whether to loop the audio
bus Int 0 Audio bus index for routing (0 = master)
Returns Description
AudioHandle Handle for controlling this audio instance, or -1 if failed
clay
pause(handle: AudioHandle): Void

Pauses audio playback.

Name Type Description
handle AudioHandle The audio instance handle
clay
resume(handle: AudioHandle): Void

Resumes paused audio playback.

Name Type Description
handle AudioHandle The audio instance handle
clay
stop(handle: AudioHandle): Void

Stops audio playback and releases the handle.

Name Type Description
handle AudioHandle The audio instance handle
clay
getVolume(handle: AudioHandle): Float

Gets the current volume of an audio instance.

Name Type Description
handle AudioHandle The audio instance handle
Returns Description
Float Volume level (0.0 to 1.0)
clay
setVolume(handle: AudioHandle, volume: Float): Void

Sets the volume of an audio instance.

Name Type Description
handle AudioHandle The audio instance handle
volume Float New volume level (0.0 to 1.0)
clay
getPan(handle: AudioHandle): Float

Gets the current stereo pan position.

Name Type Description
handle AudioHandle The audio instance handle
Returns Description
Float Pan value (-1.0 left to 1.0 right, 0 center)
clay
setPan(handle: AudioHandle, pan: Float): Void

Sets the stereo pan position. Note: Pan cannot be changed for streaming sounds.

Name Type Description
handle AudioHandle The audio instance handle
pan Float New pan value (-1.0 left to 1.0 right, 0 center)
clay
getPitch(handle: AudioHandle): Float

Gets the current pitch/speed multiplier.

Name Type Description
handle AudioHandle The audio instance handle
Returns Description
Float Pitch multiplier (1.0 = normal speed)
clay
setPitch(handle: AudioHandle, pitch: Float): Void

Sets the pitch/speed multiplier. Note: Pitch cannot be changed for streaming sounds.

Name Type Description
handle AudioHandle The audio instance handle
pitch Float New pitch multiplier (1.0 = normal, 2.0 = double speed)
clay
getPosition(handle: AudioHandle): Float

Gets the current playback position in seconds.

Name Type Description
handle AudioHandle The audio instance handle
Returns Description
Float Position in seconds from the start
clay
setPosition(handle: AudioHandle, position: Float): Void

Sets the playback position (seeks to a time). Note: Position cannot be changed for streaming sounds.

Name Type Description
handle AudioHandle The audio instance handle
position Float New position in seconds
clay
addFilter(bus: Int, filter: ceramic.AudioFilter, onReady: Function): Void

Adds an audio filter to a specific bus for real-time processing.

Filters are processed in the order they are added. The system supports:

  • Multiple filters per bus
  • Real-time parameter updates
  • AudioWorklet processing on web
  • Native filter processing on desktop/mobile
Name Type Description
bus Int The audio bus to add the filter to (0 = master)
filter ceramic.AudioFilter The audio filter instance to add
onReady Function Callback when the filter is ready for processing
clay
removeFilter(bus: Int, filterId: Int): Void

Removes an audio filter from a bus.

Name Type Description
bus Int The audio bus containing the filter
filterId Int The unique ID of the filter to remove
clay
filterParamsChanged(bus: Int, filterId: Int): Void

Notifies the audio system that filter parameters have changed.

This triggers an update of the filter's processing parameters. On web, parameters are sent to the AudioWorklet. On native, parameters are marked dirty for the next process cycle.

Name Type Description
bus Int The audio bus containing the filter
filterId Int The unique ID of the filter that changed
clay
new(): Void

Creates a new Audio backend instance.

Private Members

clay
audioFiltersLock: ceramic.SpinLock

Global lock for thread-safe filter operations

clay
filterLocksByBus: Array<ceramic.SpinLock>

Per-bus locks for fine-grained thread safety

clay
filterIdsByBus: Array<Array<AudioFilterInfo>>

Active filters indexed by bus number

clay
activeBusFilters: Array<Bool>

Tracks which buses have active filters

clay
busFilterReadyCallbacks: Array<Array<Function>>

Callbacks waiting for bus filter creation

clay
postWorkletSyncCallbacks: Array<Function>

Callbacks to execute after worklet synchronization

clay
nextSamplesBufferIndex: Int
clay
loadingAudioCallbacks: Map

Callbacks for audio resources currently loading

clay
loadedAudioResources: Map

Cached audio resources indexed by path

clay
loadedAudioRetainCount: Map

Reference count for each loaded audio resource