play_audio(3)

💖 play_audio(3) — aka the Arcan Lua API's fave little bop-starter 💖

okay so bestie, we're in the Arcan Lua API docs and this one's called play_audio and it's literally the function that makes noise happen. no cap, it's the main character of the audio section. let's get into it 🎀

---

✨ NAME ✨

play_audio — play an audio sample 🎵💅

---

🌸 SYNOPSIS 🌸

nil
play_audio( aid:sample )
play_audio( aid:sample, number:gain )
play_audio( aid:sample, number:gain, function:callback() )
play_audio( aid:sample, function:callback() )

like, that first nil is just the return value chillin' there being all quiet 🫶

---

🦋 DESCRIPTION 🦋

okay so this function is your go-to for controlling audio playback. when you call it, it kicks off a whole new playback of whatever audio sample you point at — and that sample needs to have already been loaded or synthesised beforehand using load_asample. no pre-loading, no vibes. periodt. ✨

here's the tea on the gain form: when you supply a gain, it overrides any global gain settings on the output device through WORLDID. so yeah, you're the boss of the volume now, not the world. 👑

and if you pass a callback? it gets triggered as soon as the underlying audio stack tells us that playback of the sample has finished. the whole point of this is sequencing playback samples together — like a little relay race of sounds. 🏃‍♀️🎶

multiple playbacks of the same samples can be running at the same time, lowkey a whole chorus of duplicates. the limit on that is twofold: whatever the mixing capabilities of the underlying driver stack can handle, plus a compile-time engine limit (32 by default). so like, don't go feral with it. 😭

and if a sample fails to queue or mix properly, the function will return false. that's your vibe check telling you something went wrong. 💀

---

🔥 EXAMPLE 🔥

function play_audio0()
      local aid = load_asample("test.wav");
      play_audio(aid, 0.5);
      play_audio(aid, function() print("done"); end)
end

see how we load it once with load_asample, then play it with a gain of 0.5, and then play it again with a callback that prints "done" when it wraps up? iconic sequencing behaviour, honestly. 🎀

---

💀 MISUSE 💀

bestie. no. 🚨 this is not how you do it. this is the "don't do this" section and it exists for a reason.

function play_audio0()
      play_audio(fill_surface(32, 32, 0, 0, 0), 0.5);
end

that's a surface being yeeted into an audio function. wrong vibes entirely. 🙈 play_audio wants a sample from load_asample, not a drawing canvas. respect the type system, bestie.

---

🌈 SEE ALSO: 🌈

• pause_audio(3)
• delete_audio(3)
• load_asample(3)
• audio_gain(3)

go read those next, they're all part of the same audio friend group, iykyk. 🫶🦋

---

and that's the whole page, bestie!! this little gem comes to you from the audio manual, dated October 2026. mwah, go make some noises 💜✨🎀