Audio

:= []

Audio module - short sound effects, streamed music, and procedural tones.

Load or generate resources during initialization and keep the opaque values in your model. Sound and music are distinct types, so they cannot be mixed by accident. Their final Roc reference automatically unloads the host resource.

load_sound! : Str => Try(Sound, [SoundLoadFailed, ResourceLimit, ..])

Load a short sound effect from disk.

load_music! : Str => Try(Music, [MusicLoadFailed, ResourceLimit, ..])

Load a streamed music file. Keep the returned value in the app model.

gen_sound! : GenSound => Try(Sound, [SoundGenerationFailed, ResourceLimit, ..])

Generate a reusable procedural sound. Generation can fail if the fixed host resource heap is exhausted, so initialization should propagate the returned error.

gen_tone! : { freq : F32, ms : I32 } => Try(Sound, [SoundGenerationFailed, ResourceLimit, ..])

Generate a reusable sine tone. freq is Hz and ms is milliseconds.

set_master_volume! : F32 => {  }

Set global output volume for all sounds and music, clamped to 0 through 1.

Sound

Audio.Sound :: # (opaque)

Host-owned short sound effect. Use receiver methods such as sound.play!().

play! : Sound => {  }

Start playback from the beginning.

stop! : Sound => {  }

Stop playback and rewind to the beginning.

pause! : Sound => {  }

Pause playback at the current position.

resume! : Sound => {  }

Resume a paused sound.

is_playing! : Sound => Bool

Whether this sound is currently playing.

set_volume! : Sound, F32 => {  }

Set volume, clamped by the host to 0 through 1.

set_pitch! : Sound, F32 => {  }

Set pitch multiplier. Non-positive values are clamped by the host.

set_pan! : Sound, F32 => {  }

Set stereo pan, clamped by the host to -1 through 1.

Music

Audio.Music :: # (opaque)

Host-owned streamed music. The platform updates active streams each frame.

play! : Music => {  }

Start or restart playback.

stop! : Music => {  }

Stop playback and rewind.

pause! : Music => {  }

Pause at the current position.

resume! : Music => {  }

Resume paused playback.

set_volume! : Music, F32 => {  }

Set stream volume, clamped to 0 through 1.

set_pitch! : Music, F32 => {  }

Set stream pitch multiplier.

set_pan! : Music, F32 => {  }

Set stereo pan, clamped to -1 through 1.

set_looping! : Music, Bool => {  }

Enable or disable automatic looping.

is_playing! : Music => Bool

Whether this stream is currently playing.

seek! : Music, F32 => {  }

Seek to seconds from the start. Negative values are clamped to zero.

length! : Music => F32

Total stream length in seconds, or zero for an invalid resource.

time_played! : Music => F32

Current playback position in seconds.

Waveform

:= [Sine, Square, Triangle, Saw, Noise]

Procedural waveform used by gen_sound!.

GenSound : {
    waveform : Waveform,
    freq_start : F32,
    freq_end : F32,
    ms : I32,
    attack_ms : I32,
    decay_ms : I32,
    sustain : F32,
    release_ms : I32,
    volume : F32,
}

Envelope and pitch configuration for a generated sound.