ALLEGRO_AUDIO_STREAM(3)

✨ NAME ✨

ALLEGRO_AUDIO_STREAM — Allegro 5 API. This is the Library Functions Manual entry, and yes bestie, we’re about to make audio streaming make sense. 💖

🎧 SYNOPSIS 🎧

#include <allegro5/allegro_audio.h>

typedef struct ALLEGRO_AUDIO_STREAM ALLEGRO_AUDIO_STREAM;

💅 DESCRIPTION 💅

Okay so an ALLEGRO_AUDIO_STREAM object is literally how you stream generated audio to the sound device, in real-time. It does this by reading from a buffer that’s split into a bunch of fragments. Whenever a fragment has finished playing, you can refill it with new data. iconic. ✨

Just like ALLEGRO_SAMPLE_INSTANCE(3) objects, streams store the info needed for playback, so you may not play the same stream multiple times simultaneously. Not optional, bestie. Streams also need to be attached to an ALLEGRO_MIXER(3), which eventually reaches an ALLEGRO_VOICE(3) object.

While playing, you must periodically fill fragments with new audio data. To know when a new fragment is ready to be filled, you can either directly check with al_get_available_audio_stream_fragments(3), 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(3). An ALLEGRO_EVENT_AUDIO_STREAM_FRAGMENT(3) event is generated whenever a new fragment is ready. When you receive an event, use al_get_audio_stream_fragment(3) to obtain a pointer to the fragment to be filled. The size and format are determined by the parameters passed to al_create_audio_stream(3).

If you’re late with supplying new data, the stream will be silent until new data is provided. No pressure, but also pressure. 😭 You must call al_drain_audio_stream(3) when you’re finished with supplying data to the stream.

It is often a good idea to prefill the audio stream with data before ALLEGRO_EVENT_AUDIO_STREAM_FRAGMENT(3) events arrive. Here’s a snippet that will fill 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);
              }

If the stream is created by al_load_audio_stream(3) or al_play_audio_stream(3) then it will also generate an ALLEGRO_EVENT_AUDIO_STREAM_FINISHED(3) event if it reaches the end of the file and is not set to loop.

---

that’s the tea: from the Allegro reference manual, page ALLEGRO_AUDIO_STREAM(3). 🫶💜✨