ALLEGRO_AUDIO_STREAM(3alleg5)

👑 NAME 👑

ALLEGRO_AUDIO_STREAM — the Allegro 5 API's very own real-time audio streaming era 💖 (this page lives in the allegro5 manual, bestie, and it's giving "make ur own sound, live, as u go").

---

✨ SYNOPSIS ✨

#include <allegro5/allegro_audio.h>

typedef struct ALLEGRO_AUDIO_STREAM ALLEGRO_AUDIO_STREAM;

---

🎀 DESCRIPTION 🎀

Okay so an ALLEGRO_AUDIO_STREAM object is literally the main character of generated audio, streamed to the sound device, in real-time. How? By reading from a buffer, and that buffer is split into a bunch of fragments. Whenever one fragment finishes playing, you — yes you — get to refill it with new data. It's a lil conveyor belt of sound 🍓

Same energy as ALLEGRO_SAMPLE_INSTANCE(3alleg5) objects: streams store the info they need for playback, which means you may not play the same stream multiple times simultaneously. One stream, one playthrough. No sharing. Streams also gotta be attached to an ALLEGRO_MIXER(3alleg5), which eventually reaches an ALLEGRO_VOICE(3alleg5) object. It's a whole chain, iykyk 🌈

While it's playing, you must periodically fill fragments with new audio data. To know when a fresh fragment is ready to be filled, you've got two options: check directly with al_get_available_audio_stream_fragments(3alleg5), or listen to events from the stream.

You can register an audio stream event source to an event queue — see al_get_audio_stream_event_source(3alleg5). An ALLEGRO_EVENT_AUDIO_STREAM_FRAGMENT(3alleg5) event gets generated whenever a new fragment is ready. When you receive an event, use al_get_audio_stream_fragment(3alleg5) to grab a pointer to the fragment you're gonna fill. The size and the format? Determined by the parameters you passed to al_create_audio_stream(3alleg5). ✨

If you're late supplying new data, no cap, the stream will just be silent until new data shows up. 😭 And you must call al_drain_audio_stream(3alleg5) when you're finished supplying data to the stream. Don't skip it. Periodt.

💡 Pro bestie tip from the manpage itself: it is often a good idea to prefill the audio stream with data before ALLEGRO_EVENT_AUDIO_STREAM_FRAGMENT(3alleg5) events arrive. Here's a snippet that fills the stream buffers with silence:

ALLEGRO_AUDIO_STREAM *stream = al_create_audio_stream(num_buffers,
   samples_per_buffer, freq, depth, channel_conf);
void *buf;
while ((buf = al_get_audio_stream_fragment(stream))) {
   al_fill_silence(buf, samples_per_buffer, depth, channel_conf);
   al_set_audio_stream_fragment(stream, buf);
}

And one more thing 🌸 — if the stream was created by al_load_audio_stream(3alleg5) or al_play_audio_stream(3alleg5), then it will also generate an ALLEGRO_EVENT_AUDIO_STREAM_FINISHED(3alleg5) event if it reaches the end of the file and is not set to loop. Chef's kiss. 💅

---

Mwah, that's the whole page, bestie 💜 This was the Allegro reference manual, ALLEGRO_AUDIO_STREAM(3alleg5). Go stream something iconic. 🦋🎀