Skip to content

Audio

The Audio class enables loading and playing sound effects (SE) or background music (BGM) tracks.

Synopsis

Constructor

Static Methods

Instance Methods

Constructor

Audio(path, [streaming])

Loads an audio resource from the specified path as a sound effect.

Parameters:

Parameter Type Required Description
path string Yes The path to the audio asset.
streaming bool No If true, the file is streamed from disk rather than fully loaded into memory. Default is false.

Static Methods

Audio.bgm_pause()

Pauses the currently playing background music.

Audio.bgm_play(path[, options])

Loads and plays an audio file as background music. BGM tracks are automatically streamed.

Parameters:

Parameter Type Required Description
path string Yes Path to the music file.
options table No Advanced playback modifiers (see Play Options).

Audio.bgm_playing()

Checks whether background music is currently active.

  • Returns: bool: true if background music is playing, false otherwise.

Audio.bgm_set_options(options)

Dynamically updates the playback parameters of the currently active background music track. Properties omitted from the options table remain unchanged. Options specified here are remembered if the current track is later restarted.

Parameters:

Parameter Type Required Description
options table Yes A table containing properties to update (see Play Options).

Audio.bgm_stop()

Stops the currently playing background music.

Audio.bgm_restart()

Restart a stopped background music.

Audio.bgm_resume()

Resumes the currently paused background music.

Instance Methods

audio.play([options])

Plays a previously loaded sound effect.

Play Options Table

Field Type Default Description
loops int 0 Additional loops to play (-1 for infinite).
pan float 0.0 Stereo panning (-1.0 Left, 0.0 Center, 1.0 Right).
pitch float 1.0 Playback pitch modifier.
position int 0 Starting position in milliseconds.
volume float 1.0 Playback volume multiplier.

Examples

// Load a sound effect
local clickSound = Audio("assets/audio/click.wav")

// Play sound effect
clickSound.play()

// Play sound effect with lowered volume
clickSound.play({ volume = 0.75})

// Start to play a background music track
Audio.bgm_play("assets/audio/music.ogg", { volume = 0.8, loops = -1 })

// Change BGM properties dynamically while it's playing
Audio.bgm_set_options({ volume = 0.3, pitch = 1.2, pan = -0.5 })

// Stop the track completely
Audio.bgm_stop()

// Restart it using the modified options
Audio.bgm_restart()

Additional example code available here.