play_audio_stream(3alleg4)

🌸 NAME 🌸

play_audio_stream — bestie, this one creates a new audio stream and starts playing it, like, immediately. 💖

It lives in the Allegro game programming library, and honestly? It's giving main character energy. Periodt.

✨ SYNOPSIS ✨

#include <allegro.h>

AUDIOSTREAM *play_audio_stream(int len, int bits, int stereo, int freq,
int vol, int pan);

🎀 DESCRIPTION 🎀

okay so. This function creates a brand new audio stream and starts playing it right away. No waiting, no "let me think about it", it just goes. 🔥

The len is the size of each transfer buffer — and hear me out, it's measured in sample frames, not bytes. A sample frame is either:

• a single sample value, if you're doing mono data, or
• a pair of interleaved sample values (left one comes first, okay?) if you're doing stereo data.

The length should normally be a power of 2, somewhere around 1k in size — but like, it doesn't have to be. It's not that deep. 🙈

Larger buffers are more efficient and need fewer updates from you, but ngl they also mean more latency between you handing over the data and it actually getting played. So it's a trade-off, bestie. Choose wisely. 💅

Now the parameters:

• bits — must be either 8 or 16. That's it, that's the list.
• freq — the sample rate of the data, in Hertz.
• vol and pan — these use the exact same 0-255 ranges as the regular sample playing functions. Same vibe, same numbers.
• stereo — set it to 1 for stereo streams, or 0 otherwise.

So if you wanna adjust the pitch, volume, or panning of a stream once it's already playing? You can totes use the regular voice_*() functions with stream->voice as the parameter. Iconic. ✨

The format of the sample data is described in the SAMPLE entry of the "Structures and types defined by Allegro" chapter — go read it, it's right there.

And the formula to get the size of the buffers in bytes could be:

bytes = length * (bits / 8) * (stereo ? 2 : 1)

Example time, because we love a demonstration:

/* Create a 22KHz 8bit mono audio stream. */
stream = play_audio_stream(1024, 8, FALSE, 22050, 255, 128);
if (!stream)
   abort_on_error("Error creating audio stream!\n");

Look at her go. 🦋

💜 RETURN VALUE 💜

This function returns a pointer to the audio stream — or NULL if it couldn't be created. So like, check it. Fr fr. 😭

🌈 SEE ALSO 🌈

• install_sound(3alleg4)
• get_audio_stream_buffer(3alleg4)
• stop_audio_stream(3alleg4)
• AUDIOSTREAM(3alleg4)
• exstream(3alleg4)

mwah, that's a wrap bestie 💋 this page came from the Allegro manual, version 4.4.3, and it's all about play_audio_stream(3alleg4) — go make some noise, you've got this. 🫶👑