The audio.engine manages playback of prerendered and streaming audio clips. It uses OpenAL as the underlying interface to audio hardware. As clips play, their 3D location, volume, and other attributes can be updated on the fly.

An audio-engine object manages the connection to the OpenAL implementation and any playing clips:

audio-engine

<audio-engine> ( device-name voice-count -- engine )

<standard-audio-engine> ( -- engine )

The audio engine can be started and stopped. While it is running, it must be regularly updated to keep audio buffers full and clip attributes up to date.

start-audio ( audio-engine -- )

start-audio* ( audio-engine -- )

stop-audio ( audio-engine -- )

update-audio ( audio-engine -- )

Audio clips are represented by audio-clip objects while they are playing. Words are provided to control the playback of clips:

audio-clip

play-clip ( audio-clip -- )

pause-clip ( audio-clip -- )

stop-clip ( audio-clip -- )

play-clips ( audio-clips -- )

pause-clips ( audio-clips -- )

stop-clips ( audio-clips -- )

Two types of audio clip objects can be played by the engine. A static-audio-clip plays back a static, prerendered, fixed-size block of PCM data from an audio object.

static-audio-clip

<static-audio-clip> ( audio-engine source audio loop? -- audio-clip/f )

play-static-audio-clip ( audio-engine source audio loop? -- audio-clip/f )

A streaming-audio-clip generates PCM data on the fly from a generator object.
Audio generator protocol

streaming-audio-clip

<streaming-audio-clip> ( audio-engine source generator buffer-count -- audio-clip/f )

play-streaming-audio-clip ( audio-engine source generator buffer-count -- audio-clip/f )

Every audio clip has an associated source object that determines the clip's 3D position, velocity, volume, and other attributes. The engine itself has a listener that describes the position, orientation, velocity, and volume that make up the frame of reference for audio playback.
Audio source protocol
Audio listener protocol