al_create_audio_stream(3)

💖 NAME 💖

okay so bestie, this page is from the Library Functions Manual — specifically the Allegro 5 API — and it’s all about al_create_audio_stream, the function that makes an ALLEGRO_AUDIO_STREAM(3) for you. ✨🎀

✨ 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 🌸

It creates an ALLEGRO_AUDIO_STREAM(3). The stream is set to play by default, and it feeds audio data from a buffer that’s split into a number of fragments. 🦋💅

💅 Parameters 💅

• fragment_count — how many fragments to use for the audio stream. Usually only two fragments are required — splitting the audio buffer into two halves. But that means the only time new data can be supplied is whenever one half has finished playing. When using many fragments, you usually will use fewer samples for one, so there will always be (small) fragments available to be filled with new data. 🎀
• frag_samples — the size of a fragment in samples. See the note and explanation below. 👀
• freq — the frequency, in Hertz. 🎵
• depth — must be one of the values listed for ALLEGRO_AUDIO_DEPTH(3). 💎
• chan_conf — must be one of the values listed for ALLEGRO_CHANNEL_CONF(3). 🌈

🧚 Sample layout tea 🧚

A sample that is referred to by the frag_samples parameter refers to a sequence of channel intensities. E.g. if you’re making a stereo stream with frag_samples set to 4, then the layout of the data in the fragment will be:

LRLRLRLR

Where L and R are the intensities for the left and right channels respectively. A single sample, then, refers to the LR pair in this example. periodt. 💅✨

🔥 Delay math 🔥

The choice of fragment_count, frag_samples and freq directly influences the audio delay. The delay in seconds can be expressed as:

delay = fragment_count * frag_samples / freq

This is only the delay due to Allegro’s streaming — there may be additional delay caused by sound drivers and/or hardware. no cap. 😭🔥

Note: If you 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; The size of the complete buffer is: buffer_size = bytes_per_fragment * fragment_count

Note: Unlike many Allegro objects, audio streams are not implicitly destroyed when Allegro is shut down. You must destroy them manually with al_destroy_audio_stream(3) before the audio system is shut down. This is important, bestie — don’t let it leak. 🫶💖

---

source/version: Allegro reference manual · page: al_create_audio_stream(3) · date: none printed on this page — that’s the cute sign-off, mwah 💖🌺