Skip to content

Courage.Audio#

Courage.Audio plays audio files from disk. Sounds run on a background audio thread and do not block the game loop.

Supported formats: MP3, WAV, FLAC, OGG/Vorbis.

Loading#

local Audio = require("Courage.Audio")

import * as Audio from "Courage.Audio"

API#

Audio.play(path, loop?, volume?) -> handle | nil, err?#

Loads and plays an audio file. Returns a handle on success. On failure, returns nil and an error string.

Parameter Type Description
path string Absolute path to the audio file
loop boolean? Loop until stopped. Defaults to false
volume number? Linear playback volume. 1.0 is full volume, 0.0 is silent. Defaults to 1.0

Use Storage.asset_path to get the correct absolute path for a bundled asset file:

local Storage = require("Petrichor.Storage")
local Audio   = require("Courage.Audio")
local Log     = require("Petrichor.Log")

local handle, err = Audio.play(Storage.asset_path("sound.mp3"))
if not handle then
    Log.err("my-mod", err or "Audio.play failed")
end

import * as Storage from "Petrichor.Storage"
import * as Audio   from "Courage.Audio"

const handle = Audio.play(Storage.asset_path("sound.mp3"))
if (handle === undefined) {
    // play failed; Luau also returns an error string as a second value
}

Audio.stop(handle)#

Stops and unloads a playing sound.

Parameter Type Description
handle number Handle returned by Audio.play 
Audio.stop(handle)

Audio.stop(handle)

Audio.set_volume(handle, volume)#

Sets the volume of a playing sound.

Parameter Type Description
handle number Handle returned by Audio.play
volume number Linear volume. 1.0 is full volume, 0.0 is silent 
Audio.set_volume(handle, 0.5)

Audio.set_volume(handle, 0.5)

Audio.is_playing(handle) -> boolean#

Returns true if the sound is still playing.

Parameter Type Description
handle number Handle returned by Audio.play 
if Audio.is_playing(handle) then
    Audio.stop(handle)
end

if (Audio.is_playing(handle)) {
    Audio.stop(handle)
}

Audio.stop_all()#

Stops and unloads every sound currently playing.

Audio.stop_all()

Audio.stop_all()

Example: play a sound on a game event#

local Hook    = require("Augment.Hook")
local Storage = require("Petrichor.Storage")
local Audio   = require("Courage.Audio")

local soundPath = Storage.asset_path("void.mp3")

Hook.dStage_restartRoom:before(function()
    Audio.play(soundPath)
end)

local Mod = {}
Mod.__index = Mod
function Mod.new() return setmetatable({}, Mod) end
function Mod:tick() end
function Mod:shutdown() Audio.stop_all() end
return Mod

import * as Hook    from "Augment.Hook"
import * as Storage from "Petrichor.Storage"
import * as Audio   from "Courage.Audio"

const soundPath = Storage.asset_path("void.mp3")

Hook.dStage_restartRoom.before(() => {
    Audio.play(soundPath)
})

Notes#

  • Each call to play allocates a new sound instance. Call stop or stop_all to free them.
  • Always call Audio.stop_all() in your mod's shutdown to avoid leaving sounds running after the mod is unloaded.

See also#