audio_gain(3)

🌸 NAME 🌸

okay bestie, welcome to audio_gain(3) from the Arcan Lua API 💖 this one is all about retrieving and/or updating the audio gain for a specific audio object. that’s the whole vibe: get it, set it, live ur truth ✨

🦋 SYNOPSIS 🦋

the synopsis is literally this, no edits:

aid_gain
audio_gain( aid, gain, time )

🎀 DESCRIPTION 🎀

so every audio object has its own separate gain property, clamped to the 0..1 range, and it’s set to 1.0 by default when an object is loaded or created 👑.

the optional gain argument will update that for a specific audio source. the optional time argument applies a fade from the old gain to the new one — the interpolation function used is implementation defined, so don’t come for me about the curve, okay? 😌

📝 NOTES 📝

• 1 — “Any value outside the particular range will be clamped.” that’s the rule, bestie 🫶
• 2 — “AID 0 is reserved for changing the default gain for new sources.”
• 3 — the page says: “For the cases where the engine is responsible for pushing the audio” — and that’s literally where the note ends, bestie 😭 keeping it real.
• 4 — “The gain value returned is the target gain, with a pending transformation, this state may not have been reached yet.” then it goes on with this exact bit:

“to the target device, even a gain of 0.0 will generate data due to some buffering restrictions with underlying API s.”

yes, API s with a space, i did not invent that 💀

• 5 — “There's a logarithmic distribution applied internally to better mimic the linear appearance used in other sound interfaces.”

✨ EXAMPLE ✨

here’s the example, looking cute and doing normal gain things:

       function audio_gain0()
             local asrc = load_asample("sample.wav");
             audio_gain(asrc, 0.0, 100);
             play_audio(asrc);
       end

💀 MISUSE 💀

and here’s the misuse example — do not be this girlie, okay? note 1 is right there reminding us that out-of-range values get clamped, but still, read the room 🙈:

       function audio_gain0()
             local asrc = load_asample("sample.wav");
             audio_gain(asrc, -1.0, -1);
             play_audio(asrc);
       end

xoxo, source/version audio, dated October 2026 — audio_gain(3) signing off 🎀💅