al_play_sample(3alleg5)

✨ al_play_sample ✨

okay bestie, quick vibe check — this one lives in the Allegro 5 API manual, and it's literally the "make a sound happen" button. let's get into it 💖

---

🌸 SYNOPSIS 🌸

#include <allegro5/allegro_audio.h>

bool al_play_sample(ALLEGRO_SAMPLE *spl, float gain, float pan, float speed,
   ALLEGRO_PLAYMODE loop, ALLEGRO_SAMPLE_ID *ret_id)

---

🎀 DESCRIPTION 🎀

so what this does is play a sample on one of the sample instances that al_reserve_samples(3alleg5) already set up for you. returns true if it worked, false if it didn't. and ngl, playback can fail because literally all the reserved sample instances are being used rn 😭 like the pool is full, bestie, no room.

Parameters — the whole squad:

• gain — the relative volume the sample gets played at; 1.0 is normal. that's your baseline, don't overthink it.
• pan — 0.0 is centred, -1.0 is left, 1.0 is right, or you can use ALLEGRO_AUDIO_PAN_NONE. pick your lane 🎧
• speed — the relative speed the sample gets played at; 1.0 is normal. slow it down or speed it up, your call.
• loop — one of ALLEGRO_PLAYMODE_ONCE, ALLEGRO_PLAYMODE_LOOP, or ALLEGRO_PLAYMODE_BIDIR. once, forever, or back-and-forth like it can't decide 🦋
• ret_id — if it's non-NULL, the variable it points to gets assigned an id representing the sample being played. BUT — if al_play_sample(3alleg5) returns false, then whatever's in ret_id is invalid and you must NOT use it as an argument to other functions. fr fr, don't do it, it's giving undefined chaos 💀

lowkey the biggest glow-up move here is remembering that ret_id is only trustworthy when you got a true back. periodt.

---

🫶 SEE ALSO 🫶

• al_load_sample(3alleg5)
• ALLEGRO_PLAYMODE(3alleg5)
• ALLEGRO_AUDIO_PAN_NONE(3alleg5)
• ALLEGRO_SAMPLE_ID(3alleg5)
• al_stop_sample(3alleg5)
• al_stop_samples(3alleg5)
• al_lock_sample_id(3alleg5)

---

and that's the whole page, bestie 💅 this was pulled straight from the Allegro reference manual — al_play_sample(3alleg5), the Allegro 5 API. go make some noise 👑✨