Audio

View source
spec.Audio (Interface) → backend.Audio

Backend interface for audio operations.

This interface defines the contract that all backend implementations (Clay, Unity, Headless, Web) must fulfill to provide audio functionality in Ceramic. It handles loading, playback control, real-time effects, and bus management.

The audio system uses a bus-based architecture where sounds can be routed to different buses (0-7) for group control and effects processing.

Instance Members

load(path: String, ?options: Null<backend.LoadAudioOptions>, done: Function): Void

Loads an audio file from the specified path.

Name Type Default Description
path String The path to the audio file (relative to assets directory)
options Null<backend.LoadAudioOptions> (optional) Optional loading configuration (streaming, format hints, etc.)
done Function Callback invoked with the loaded AudioResource or null on failure
createFromSamplesBuffer(buffer: backend.Float32Array, samples: Int, channels: Int, sampleRate: Float, interleaved: Bool): backend.AudioResource

Creates an audio resource from raw PCM sample data.

Name Type Description
buffer backend.Float32Array The raw audio sample data as 32-bit floats (-1.0 to 1.0 range)
samples Int The total number of samples in the buffer
channels Int The number of audio channels (1 for mono, 2 for stereo)
sampleRate Float The sample rate in Hz (e.g., 44100, 48000)
interleaved Bool Whether samples are interleaved (L,R,L,R) or planar (L,L,L...,R,R,R)
Returns Description
backend.AudioResource A new AudioResource containing the audio data
supportsHotReloadPath(): Bool

Checks if the backend supports hot-reloading of audio files. When true, the audio system can detect file changes and reload automatically.

Returns Description
Bool True if hot-reload is supported, false otherwise
getDuration(audio: backend.AudioResource): Float

Gets the duration of an audio resource in seconds.

Name Type Description
audio backend.AudioResource The audio resource to query
Returns Description
Float The duration in seconds, or -1 if unknown (e.g., for streams)
resumeAudioContext(done: Function): Void

Resumes the audio context after user interaction. This is required on web platforms where audio contexts start suspended until user interaction occurs (click, touch, etc.).

Name Type Description
done Function Callback invoked with true on success, false on failure
destroy(audio: backend.AudioResource): Void

Destroys an audio resource and frees its memory. After calling this, the AudioResource should not be used.

Name Type Description
audio backend.AudioResource The audio resource to destroy

Creates a muted audio handle without actually playing the sound. Useful for pre-allocating handles or silent placeholders.

Name Type Description
audio backend.AudioResource The audio resource to create a handle for
Returns Description
backend.AudioHandle A muted AudioHandle that can be controlled like a playing sound
play(audio: backend.AudioResource, ?volume: Float = 0.5, ?pan: Float = 0, ?pitch: Float = 1, ?position: Float = 0, ?loop: Bool = false, ?bus: Int = 0): backend.AudioHandle

Plays an audio resource with the specified parameters.

Name Type Default Description
audio backend.AudioResource The audio resource to play
volume Float 0.5 The playback volume (0.0 to 1.0, default 0.5)
pan Float 0 The stereo panning (-1.0 for left, 0.0 for center, 1.0 for right)
pitch Float 1 The playback pitch/speed multiplier (1.0 is normal speed)
position Float 0 The starting position in seconds
loop Bool false Whether to loop playback when reaching the end
bus Int 0 The audio bus to route this sound through (0-7)
Returns Description
backend.AudioHandle An AudioHandle for controlling the playing sound
pause(handle: backend.AudioHandle): Void

Pauses playback of an audio handle. The sound can be resumed from the same position with resume().

Name Type Description
handle backend.AudioHandle The audio handle to pause
resume(handle: backend.AudioHandle): Void

Resumes playback of a paused audio handle. Playback continues from where it was paused.

Name Type Description
handle backend.AudioHandle The audio handle to resume
stop(handle: backend.AudioHandle): Void

Stops playback of an audio handle. Unlike pause, this cannot be resumed - the handle becomes invalid.

Name Type Description
handle backend.AudioHandle The audio handle to stop
getVolume(handle: backend.AudioHandle): Float

Gets the current volume of an audio handle.

Name Type Description
handle backend.AudioHandle The audio handle to query
Returns Description
Float The current volume (0.0 to 1.0)
setVolume(handle: backend.AudioHandle, volume: Float): Void

Sets the volume of an audio handle.

Name Type Description
handle backend.AudioHandle The audio handle to modify
volume Float The new volume (0.0 to 1.0)
getPan(handle: backend.AudioHandle): Float

Gets the current stereo panning of an audio handle.

Name Type Description
handle backend.AudioHandle The audio handle to query
Returns Description
Float The current pan value (-1.0 for left, 0.0 for center, 1.0 for right)
setPan(handle: backend.AudioHandle, pan: Float): Void

Sets the stereo panning of an audio handle.

Name Type Description
handle backend.AudioHandle The audio handle to modify
pan Float The new pan value (-1.0 for left, 0.0 for center, 1.0 for right)
getPitch(handle: backend.AudioHandle): Float

Gets the current pitch/speed multiplier of an audio handle.

Name Type Description
handle backend.AudioHandle The audio handle to query
Returns Description
Float The current pitch multiplier (1.0 is normal speed)
setPitch(handle: backend.AudioHandle, pitch: Float): Void

Sets the pitch/speed multiplier of an audio handle. This affects both pitch and playback speed proportionally.

Name Type Description
handle backend.AudioHandle The audio handle to modify
pitch Float The new pitch multiplier (0.5 = half speed/octave down, 2.0 = double speed/octave up)
getPosition(handle: backend.AudioHandle): Float

Gets the current playback position of an audio handle.

Name Type Description
handle backend.AudioHandle The audio handle to query
Returns Description
Float The current position in seconds
setPosition(handle: backend.AudioHandle, position: Float): Void

Sets the playback position of an audio handle.

Name Type Description
handle backend.AudioHandle The audio handle to modify
position Float The new position in seconds
addFilter(bus: Int, filter: ceramic.AudioFilter, onReady: Function): Void

Adds an audio filter to a bus for real-time effects processing. Filters are processed in the order they are added.

Name Type Description
bus Int The audio bus number (0-7) to add the filter to
filter ceramic.AudioFilter The AudioFilter instance to add (e.g., LowPassFilter, HighPassFilter)
onReady Function Callback invoked when the filter is ready to process audio
removeFilter(bus: Int, filterId: Int): Void

Removes an audio filter from a bus.

Name Type Description
bus Int The audio bus number (0-7) to remove the filter from
filterId Int The ID of the filter to remove (from AudioFilter.id)
filterParamsChanged(bus: Int, filterId: Int): Void

Notifies the backend that a filter's parameters have changed. This allows the backend to update real-time processing accordingly.

Name Type Description
bus Int The audio bus number (0-7) containing the filter
filterId Int The ID of the filter whose parameters changed