Audio

Global audio state (listener) and creation/control of Source objects. Sources are created from mounted audio paths (WAV, MP3, OGG, FLAC depending on build). All Audio methods are static.

Creating sources

Audio.newSource(path)

Returns: Source or null — A new source, or null if the file could not be loaded.

Parameters:

• path (String) — Path to the audio file relative to the mounted project (e.g. "sounds/click.wav").

_clickSource = Audio.newSource("sounds/click.wav")
if (_clickSource != null) {
  Audio.play(_clickSource)
}

Streaming audio

Where Audio.newSource plays a one-shot clip decoded from a file, a streaming source plays float PCM you feed over time — procedural or synthesized audio (a sine tone, a SoundFont/MIDI synth) with no backing file. You create the source, then top up its buffer queue each frame; the engine recycles finished buffers and (re)starts playback automatically as buffers are queued, so a fed stream plays continuously.

It uses the AL_EXT_FLOAT32 OpenAL extension when present, with an int16 fallback so it works everywhere. The queue is fed from the main thread (from your update), so keep a few buffers queued to absorb a stalled frame. The one-shot Audio.newSource(path) API is unchanged.

Audio.newStreamingSource(sampleRate, channels)

Returns: Source or null — A streaming source you feed over time, or null if one could not be created.

Parameters:

• sampleRate (Num) — Samples per second per channel (e.g. 48000).
• channels (Num) — 1 (mono) or 2 (stereo).

source.queueSamples(list)

Returns: Bool — true if the samples were queued.

Parameters:

• list (List) — Interleaved float samples in [-1, 1]. For stereo, samples are interleaved left/right: L, R, L, R, …. Bounded to 1M samples per call.

Queues a chunk of PCM and (re)starts playback if the source was idle (the initial queue, or after an underrun). The engine recycles buffers that have finished playing, so calling this every frame keeps allocation flat. It is a no-op on a non-streaming (file-backed) source.

source.queuedBuffers

Returns: Num — The number of buffers currently queued (still to play). Poll it to pace refills — top the queue up to a few buffers each frame.

Feed-each-frame pattern

Create the source on init, then top the queue up each frame in update. A handful of buffers of headroom keeps playback gapless:

import "engine" for Audio, Logger

class Game {
  construct new() {
    _rate = 48000
    _freq = 220.0
    _phase = 0.0
    _src = null
  }

  init() {
    _src = Audio.newStreamingSource(_rate, 1)   // mono
    if (_src == null) Logger.error("could not create a streaming source")
  }

  update(dt) {
    if (_src == null) return
    // Keep ~4 buffers queued so playback never underruns.
    while (_src.queuedBuffers < 4) {
      var samples = []
      for (i in 0...800) {                        // ~1/60 s of audio at 48 kHz
        _phase = _phase + 2.0 * Num.pi * _freq / _rate
        if (_phase > 2.0 * Num.pi) _phase = _phase - 2.0 * Num.pi
        samples.add(0.2 * _phase.sin)             // float in [-1, 1]
      }
      _src.queueSamples(samples)                  // interleaved for stereo: L,R,L,R…
    }
  }

  draw() {}
  quit() {}
}

See the Audio Streaming Demo example.

Global playback

Audio.play(source) / Audio.stop(source) / Audio.stop()

Parameters:

• source (Source, optional) — Source to play or stop. Audio.stop() with no arguments stops all playback.

Play a source, or stop a specific source or all playback.

Audio.play(_musicSource)
Audio.stop(_musicSource)
Audio.stop()  // stop all

Audio.isPlaying(source)

Returns: Bool — true if the given source is currently playing.

Parameters:

• source (Source) — Source to check.

Audio.pause()

Pause global playback.

Listener (volume & 3D)

Audio.getVolume() / Audio.setVolume(vol)

Returns: (getter) Num — Global volume (0–1 or engine-defined range).

Parameters:

• vol (Num) — Volume (0–1 typical).

Audio.getPosition() / Audio.setPosition(x, y, z)

Returns: (getter) List of three numbers [x, y, z] — Listener position in world space.

Parameters:

• x, y, z (Num) — Listener position.

Audio.getOrientation() / Audio.setOrientation(atX, atY, atZ, upX, upY, upZ)

Returns: (getter) Orientation (at and up vectors).

Parameters:

• atX, atY, atZ (Num) — “At” (forward) direction.
• upX, upY, upZ (Num) — “Up” direction.

Audio.getVelocity() / Audio.setVelocity(x, y, z)

Returns: (getter) List [x, y, z] — Listener velocity (for Doppler).

Parameters:

• x, y, z (Num) — Velocity.

Audio.getDistanceModel() / Audio.setDistanceModel(model)

Returns: (getter) Current distance model.

Parameters:

• model — Distance attenuation model (implementation-dependent).

Audio.getDopplerScale() / Audio.setDopplerScale(scale)

Returns: (getter) Num — Doppler scale.

Parameters:

• scale (Num) — Doppler effect scale.

Audio.getActiveSourceCount()

Returns: Num — Number of sources currently playing.

---

Source

A single sound source. Create with Audio.newSource or Resource.loadSound.

Playback

Method	Returns	Parameters	Description
play()	—	—	Start playback
stop()	—	—	Stop playback
pause()	—	—	Pause playback
getVolume()	Num	—	Current volume
setVolume(vol)	—	vol (Num)	Set volume
getPitch()	Num	—	Current pitch
setPitch(p)	—	p (Num)	Set pitch
isLooping()	Bool	—	Whether looping
setLooping(loop)	—	loop (Bool)	Set looping
getDuration()	Num	—	Length in seconds
tell()	Num	—	Current position in seconds
seek(offsetSeconds)	—	offsetSeconds (Num)	Seek to position
clone()	Source	—	New source with same buffer

3D sound

Method	Returns / Parameters	Description
getPosition()	[x, y, z]	Source position
setPosition(x, y, z)	x, y, z (Num)	Set position
getVelocity() / setVelocity(x, y, z)	—	Velocity for Doppler
getDirection() / setDirection(x, y, z)	—	Direction vector
getCone() / setCone(innerAngle, outerAngle, outerGain)	—	Directional cone (angles in radians)
getAttenuationDistances() / setAttenuationDistances(refDist, maxDist)	—	Distance attenuation
getRolloff() / setRolloff(rolloff)	—	Rolloff factor
isRelative() / setRelative(rel)	Bool	Relative to listener

var src = Audio.newSource("sounds/music.wav")
src.setLooping(true)
src.setVolume(0.8)
src.setPosition(5, 0, 0)
Audio.play(src)