tiramisu - v7.0.0

tiramisu/audio

Audio playback for sound effects and music.

Tiramisu supports both global (2D) audio that plays at constant volume, and positional (3D) audio that varies based on distance from the camera/listener. Audio is added to the scene graph as scene.audio nodes.

Loading Audio

let load_sfx = audio.load_audio(
  url: "sounds/jump.wav",
  on_success: SoundLoaded,
  on_error: SoundFailed,
)

Playing Global Audio (2D)

scene.audio(
  id: "background-music",
  audio: audio.GlobalAudio(
    buffer: music_buffer,
    config: audio.config()
      |> audio.with_state(audio.Playing)
      |> audio.with_loop(True)
      |> audio.with_volume(0.5)
      |> audio.with_group(audio.Music),
  ),
)

Playing Positional Audio (3D)

scene.audio(
  id: "waterfall",
  audio: audio.PositionalAudio(
    buffer: waterfall_buffer,
    config: audio.playing(),
    ref_distance: 1.0,
    rolloff_factor: 1.0,
    max_distance: 100.0,
  ),
)

Audio Groups

Group audio for volume control (SFX, Music, Voice, Ambient, or Custom).

Types

Audio

</>

Type of audio (global or positional)

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

Constructors 

  • GlobalAudio(buffer: savoiardi.AudioBuffer, config: Config)

    Global audio (2D, same volume everywhere)

  • PositionalAudio(
  buffer: savoiardi.AudioBuffer,
  config: Config,
  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

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)

Buffer

</>

Audio buffer type wrapping the Web Audio API AudioBuffer

pub type Buffer =
  savoiardi.AudioBuffer

Config

</>

Audio playback configuration

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

Constructors 

  • AudioConfig(
  state: AudioState,
  volume: Float,
  loop: Bool,
  playback_rate: Float,
  fade: FadeConfig,
  group: option.Option(Group),
  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)

FadeConfig

</>

Fade configuration for smooth transitions

pub type FadeConfig {
  NoFade
  Fade(duration: duration.Duration)
}

Constructors 

  • NoFade

    No fade (instant transition)

  • Fade(duration: duration.Duration)

    Fade in/out over specified milliseconds

Group

</>

Audio group categories for volume control

pub type Group {
  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

Values

config

</> 
pub fn config() -> Config

Create default audio config (stopped, no fade)

global

</> 
pub fn global(
  buffer: savoiardi.AudioBuffer,
  config: Config,
) -> Audio

Create global audio (2D, same volume everywhere)

load_audio

</> 
pub fn load_audio(
  url url: String,
  on_success on_success: fn(savoiardi.AudioBuffer) -> msg,
  on_error on_error: msg,
) -> effect.Effect(msg)

Load an audio file from URL

playing

</> 
pub fn playing() -> Config

Create audio config that starts playing

positional

</> 
pub fn positional(
  buffer: savoiardi.AudioBuffer,
  config: Config,
) -> Audio

Create a default positional audio configuration

with_fade

</> 
pub fn with_fade(
  config: Config,
  duration: duration.Duration,
) -> Config

Set fade configuration

with_group

</> 
pub fn with_group(config: Config, group: Group) -> Config

Set audio group in config

with_loop

</> 
pub fn with_loop(config: Config, loop: Bool) -> Config

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: Config) -> Config

Set no fade (instant transitions)

with_on_end

</> 
pub fn with_on_end(
  config: Config,
  callback: fn() -> Nil,
) -> Config

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: Config) -> Config

Set audio to paused

with_playback_rate

</> 
pub fn with_playback_rate(config: Config, rate: Float) -> Config

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

with_playing

</> 
pub fn with_playing(config: Config) -> Config

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: Config, state: AudioState) -> Config

Set playback state (Playing, Stopped, Paused)

with_stopped

</> 
pub fn with_stopped(config: Config) -> Config

Set audio to stopped

with_volume

</> 
pub fn with_volume(config: Config, volume: Float) -> Config

Set volume in config (0.0 to 1.0)

✨ Search Document