Sound

View source
Entity → ceramic.Sound (Class)

Represents a loaded sound that can be played multiple times.

Sound instances are typically created by loading audio assets, but can also be created from raw PCM sample data.

Features:

  • Multiple simultaneous playback instances
  • Volume, pan, and pitch control
  • Bus routing for audio processing
  • Group-based mixing
  • Looping support

Each time you call play(), a new SoundPlayer instance is created, allowing the same sound to be played multiple times simultaneously.

// Load and play a sound
var sound = assets.sound('jump');
sound.volume = 0.8;
sound.play();

// Play with custom parameters
var player = sound.play(0, true, 0.5, -0.3, 1.2);

// Create sound from raw samples
var customSound = Sound.fromSamplesBuffer(
    samples, frameCount, 2, 44100, true
);
See: SoundPlayer, SoundAsset, AudioMixer

Static Members

fromSamplesBuffer(buffer: Float32Array, samples: Int, channels: Int, sampleRate: Float, interleaved: Bool): Sound

Create a new sound from raw PCM sample data. Useful for procedural audio generation or custom audio processing.

Name Type Description
buffer Float32Array Float32Array containing the raw PCM samples
samples Int Number of sample frames (total samples divided by channel count)
channels Int Number of audio channels (1 = mono, 2 = stereo, etc.)
sampleRate Float Sample rate in Hz (e.g., 44100, 48000)
interleaved Bool Whether the PCM data is interleaved (LRLRLR...) or planar (LLL...RRR...)
Returns Description
Sound A new Sound instance ready to be played

Instance Members

The backend audio resource containing the actual audio data.

The asset this sound was loaded from, if any. Automatically destroyed when the sound is destroyed.

bus: Int

Default bus to play this sound on. 0 = master bus (default) Higher numbers route through different audio processing chains.

group: Int

The mixer group this sound belongs to. Each group has its own AudioMixer for collective volume/pan/pitch control. Setting this will automatically create the mixer if it doesn't exist.

volume: Float

Default volume when playing this sound. Range: 0.0 (silent) to 1.0 (full volume) This is multiplied with the mixer volume.

pan: Float

Default pan when playing this sound. Range: -1.0 (full left) to 1.0 (full right) 0.0 = center (default)

pitch: Float

Default pitch when playing this sound. 1.0 = normal pitch (default) 0.5 = one octave lower 2.0 = one octave higher

duration: Float

Sound duration in seconds. Read-only property calculated from the audio data.

destroy(): Void
play(?position: Float = 0, ?loop: Bool = false, ?volume: Float, ?pan: Float, ?pitch: Float, ?bus: Int): SoundPlayer

Play the sound with optional parameters. Creates a new SoundPlayer instance for this playback.

If volume/pan/pitch are not provided, the sound's default values are used. The final values are also affected by the mixer group settings.

Name Type Default Description
position Float 0 Start position in seconds (0 = beginning)
loop Bool false Whether to loop the sound continuously
volume Float (optional) Volume override (0-1, null = use default)
pan Float (optional) Pan override (-1 to 1, null = use default)
pitch Float (optional) Pitch override (1 = normal, null = use default)
bus Int (optional) Bus to play on (null = use sound's default bus)
Returns Description
SoundPlayer A SoundPlayer instance to control this specific playback
new(backendItem: backend.AudioResource): Void

Create a new Sound from a backend audio resource. Usually you don't call this directly - use asset loading or fromSamplesBuffer instead.

Name Type Description
backendItem backend.AudioResource The backend audio resource

Private Members

Metadata

Name Parameters
:build ceramic.macros.EntityMacro.buildForCompletion()
:autoBuild ceramic.macros.EntityMacro.buildForCompletion()
:build tracker.macros.EventsMacro.build()
:autoBuild tracker.macros.EventsMacro.build()