tiramisu/audio

Audio module - spatial and global audio playback with Web Audio API.

Provides type-safe audio playback configuration using the Web Audio API. Supports both global (2D) and positional (3D) audio with volume groups, fade transitions, and playback control.

Core Concepts

Global Audio: 2D audio with constant volume regardless of listener position
Positional Audio: 3D audio with distance-based volume falloff
Audio Groups: Categorize sounds (SFX, Music, Voice, Ambient) for group volume control
Builder Pattern: Chainable functions for configuring audio playback
Fade Transitions: Smooth fade in/out when changing playback state
Playback Control: Play, pause, stop, loop, and adjust playback rate

Quick Example

import tiramisu/audio
import tiramisu/scene
import tiramisu/asset

// Global audio (background music)
let music_config =
  audio.playing()
  |> audio.with_loop(True)
  |> audio.with_volume(0.5)
  |> audio.with_group(audio.Music)
  |> audio.with_fade(1000)  // 1 second fade in

scene.Audio(
  id: "bg-music",
  audio: audio.global(music_buffer, music_config),
  transform: transform.identity,
)

// Positional audio (footsteps)
let sfx_config =
  audio.playing()
  |> audio.with_group(audio.SFX)
  |> audio.with_on_end(fn() { io.println("Step complete!") })

scene.Audio(
  id: "footstep",
  audio:
    audio.positional(footstep_buffer, sfx_config)
    |> audio.with_ref_distance(2.0)
    |> audio.with_rolloff_factor(1.5)
    |> audio.with_max_distance(50.0),
  transform: transform.at(position: player_position),
)

Audio Groups

Audio groups allow batch volume control for categories of sounds:

SFX - Sound effects (footsteps, gunshots, UI sounds)
Music - Background music and themes
Voice - Dialogue and voice lines
Ambient - Environmental sounds (wind, rain, crowd noise)
Custom(name) - User-defined groups

Set group volumes using the debug module or custom controls.

Positional Audio

Positional audio uses distance-based volume falloff:

ref_distance: Distance where volume starts decreasing (default: 1.0)
rolloff_factor: How quickly volume decreases with distance (default: 1.0)
max_distance: Maximum distance where audio can be heard (default: 10000.0)

Position is determined by the Audio scene node’s transform.

Types

Audio

</>

Type of audio (global or positional)

pub type Audio {
  GlobalAudio(buffer: AudioBuffer, config: AudioConfig)
  PositionalAudio(
    buffer: AudioBuffer,
    config: AudioConfig,
    ref_distance: Float,
    rolloff_factor: Float,
    max_distance: Float,
  )
}

Constructors

GlobalAudio(buffer: AudioBuffer, config: AudioConfig)

Global audio (2D, same volume everywhere)

```
PositionalAudio(
  buffer: AudioBuffer,
  config: AudioConfig,
  ref_distance: Float,
  rolloff_factor: Float,
  max_distance: Float,
)
```
Positional audio (3D, volume based on distance)

Arguments

ref_distance

Maximum hearing distance

rolloff_factor

How quickly audio fades with distance

max_distance

Maximum distance where audio can be heard

AudioBuffer

</>

Audio buffer type (opaque, wraps Web Audio API AudioBuffer)

pub type AudioBuffer

AudioConfig

</>

Audio playback configuration

pub type AudioConfig {
  AudioConfig(
    state: AudioState,
    volume: Float,
    loop: Bool,
    playback_rate: Float,
    fade: FadeConfig,
    group: option.Option(AudioGroup),
    on_end: option.Option(fn() -> Nil),
  )
}

Constructors

```
AudioConfig(
  state: AudioState,
  volume: Float,
  loop: Bool,
  playback_rate: Float,
  fade: FadeConfig,
  group: option.Option(AudioGroup),
  on_end: option.Option(fn() -> Nil),
)
```
Arguments

state

Playback state (Playing, Stopped, Paused)

volume

Volume (0.0 to 1.0)

loop

Whether to loop the audio

playback_rate

Playback rate (1.0 = normal speed)

fade

Fade configuration for state transitions

group

Audio group for volume control (optional)

on_end

Callback when audio ends (for non-looping audio)

AudioGroup

</>

Audio group categories for volume control

pub type AudioGroup {
  SFX
  Music
  Voice
  Ambient
  Custom(String)
}

Constructors

```
SFX
```
Sound effects (footsteps, gunshots, etc.)
```
Music
```
Background music
```
Voice
```
Voice lines and dialogue
```
Ambient
```
Ambient sounds (wind, rain, etc.)
```
Custom(String)
```
Custom group with a name

AudioSource

</>

Opaque handle to a THREE.Audio or THREE.PositionalAudio object

pub type AudioSource

AudioState

</>

Audio playback state

pub type AudioState {
  Playing
  Stopped
  Paused
}

Constructors

```
Playing
```
Audio is playing
```
Stopped
```
Audio is stopped (reset to beginning)
```
Paused
```
Audio is paused (can be resumed)

FadeConfig

</>

Fade configuration for smooth transitions

pub type FadeConfig {
  NoFade
  Fade(duration_ms: Int)
}

Constructors

```
NoFade
```
No fade (instant transition)
```
Fade(duration_ms: Int)
```
Fade in/out over specified milliseconds

Values

config

</>

pub fn config() -> AudioConfig

Create default audio config (stopped, no fade)

global

</>

pub fn global(buffer: AudioBuffer, config: AudioConfig) -> Audio

Create global audio (2D, same volume everywhere)

playing

</>

pub fn playing() -> AudioConfig

Create audio config that starts playing

positional

</>

pub fn positional(
  buffer: AudioBuffer,
  config: AudioConfig,
) -> Audio

Create a default positional audio configuration

with_fade

</>

pub fn with_fade(
  config: AudioConfig,
  duration_ms: Int,
) -> AudioConfig

Set fade configuration

with_group

</>

pub fn with_group(
  config: AudioConfig,
  group: AudioGroup,
) -> AudioConfig

Set audio group in config

with_loop

</>

pub fn with_loop(config: AudioConfig, loop: Bool) -> AudioConfig

Set looping in config

with_max_distance

</>

pub fn with_max_distance(audio: Audio, distance: Float) -> Audio

Set maximum distance for positional audio

with_no_fade

</>

pub fn with_no_fade(config: AudioConfig) -> AudioConfig

Set no fade (instant transitions)

with_on_end

</>

pub fn with_on_end(
  config: AudioConfig,
  callback: fn() -> Nil,
) -> AudioConfig

Set callback to be called when audio ends (for non-looping audio)

This is useful for one-shot sounds like SFX where you need to know when the sound has finished playing.

Example

audio.config()
|> audio.with_state(audio.Playing)
|> audio.with_on_end(fn() {
  // Audio finished playing
  io.println("SFX finished!")
})

with_paused

</>

pub fn with_paused(config: AudioConfig) -> AudioConfig

Set audio to paused

with_playback_rate

</>

pub fn with_playback_rate(
  config: AudioConfig,
  rate: Float,
) -> AudioConfig

Set playback rate in config (1.0 = normal, 2.0 = double speed, etc.)

with_playing

</>

pub fn with_playing(config: AudioConfig) -> AudioConfig

Set audio to playing

with_ref_distance

</>

pub fn with_ref_distance(audio: Audio, distance: Float) -> Audio

Set reference distance for positional audio

with_rolloff_factor

</>

pub fn with_rolloff_factor(audio: Audio, factor: Float) -> Audio

Set rolloff factor for positional audio

with_state

</>

pub fn with_state(
  config: AudioConfig,
  state: AudioState,
) -> AudioConfig

Set playback state (Playing, Stopped, Paused)

with_stopped

</>

pub fn with_stopped(config: AudioConfig) -> AudioConfig

Set audio to stopped

with_volume

</>

pub fn with_volume(
  config: AudioConfig,
  volume: Float,
) -> AudioConfig

Set volume in config (0.0 to 1.0)

Core Concepts

Quick Example

Audio Groups

Positional Audio

Constructors

Arguments

Constructors

Arguments

Constructors

Constructors

Constructors

Example