al_create_audio_stream(3alleg5)

💖 al_create_audio_stream — the Allegro 5 API glow-up 💖

okay bestie, this is a page from the Allegro 5 API — the Allegro reference manual, to be exact — and today we're building an audio stream from scratch. let's go 🎀

---

✨ SYNOPSIS ✨

#include <allegro5/allegro_audio.h>

ALLEGRO_AUDIO_STREAM *al_create_audio_stream(size_t fragment_count,
   unsigned int frag_samples, unsigned int freq, ALLEGRO_AUDIO_DEPTH depth,
   ALLEGRO_CHANNEL_CONF chan_conf)

---

🌸 DESCRIPTION 🌸

She makes you an ALLEGRO_AUDIO_STREAM(3alleg5) ✨ and by default that stream is already set to play — like, it comes out the box ready, no extra steps. It feeds audio data out of a buffer, and that buffer gets chopped up into a bunch of fragments. it's giving "pizza sliced for the group chat" 🍕

The parameters, bestie, one by one:

• fragment_count — how many fragments you want your audio stream to use. Usually you only need two — just split the audio buffer in half. But lowkey that means the only moment you're allowed to hand over new data is when one of the halves is done playing. So when you're out here using a lot of fragments, you'll usually make each one hold fewer samples, so there's always a (tiny) fragment sitting free and ready to be filled with fresh data. 🌈
• frag_samples — the size of a fragment, measured in samples. there's a whole note and explanation for this below, don't worry 💅
• freq — the frequency, in Hertz. yes queen, actual Hz.
• depth — has to be one of the values listed over at ALLEGRO_AUDIO_DEPTH(3alleg5). no off-menu orders 🙈
• chan_conf — has to be one of the values listed over at ALLEGRO_CHANNEL_CONF(3alleg5). same rules, bestie.

---

🦋 so what even IS a "sample" here

when frag_samples says "sample", it means a sequence of channel intensities. like, picture a stereo stream where frag_samples is set to 4 — then the data inside that fragment lays out like this:

LRLRLRLR

where L and R are the intensities for the left and right channels respectively. so a single sample is the LR pair in this example. iconic, honestly. 💜

---

👑 the delay math (iykyk)

the way fragment_count, frag_samples and freq are chosen directly influences the audio delay. the delay in seconds goes like:

delay = fragment_count * frag_samples / freq

and this is only the delay coming from Allegro's streaming, okay? there may be additional delay caused by sound drivers and/or hardware. not our fault, not our problem, but definitely our vibe check. 💀

Note: if you already know the fragment size in bytes, you can get the size in samples like this:

sample_size = al_get_channel_count(chan_conf) * al_get_audio_depth_size(depth);
samples = bytes_per_fragment / sample_size;

and the size of the complete buffer is:

buffer_size = bytes_per_fragment * fragment_count

Note: unlike a lot of Allegro objects, audio streams are not implicitly destroyed when Allegro shuts down. 😭 not a drill. you must destroy them manually with al_destroy_audio_stream(3alleg5) before the audio system is shut down. do not skip this step, bestie, fr fr.

---

and that's the whole page, mwah 💋 — this was al_create_audio_stream(3alleg5) straight out of the Allegro reference manual. no date on this one, just the manual name and the page name riding along the bottom, so consider this your sign-off: go make something that slays, and destroy your streams manually. periodt. 🫶✨