play_audio_stream(3)

💖 play_audio_stream(3) — Allegro manual, but make it make sense 💖

okay bestie, welcome to play_audio_stream(3) from the Allegro manual, aka the glow-up your game's sound system has been waiting for 🎀

✨ NAME ✨

play_audio_stream — creates a new audio stream and starts playing it. Part of the Allegro game programming library. 💅

---

🌸 SYNOPSIS 🌸

#include <allegro.h>

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

🦋 DESCRIPTION 🦋

So this function does exactly what it says on the tin, no cap: it makes a brand new audio stream and immediately starts playing it. 🔥

len is the size of each transfer buffer, measured in sample frames, NOT bytes (this distinction matters, bestie, do not come for me). And what even is a sample frame? It's one single sample value if you're doing mono, or a pair of interleaved sample values — left first — if you're doing stereo. 📻

Now, len should normally (but literally doesn't have to) be a power of 2, somewhere around 1k in size. And here's the vibe check on buffer size:

• Bigger buffers = more efficient, need fewer updates ✨
• Bigger buffers = more latency between you handing over the data and it actually getting played 😭

so it's giving tradeoff, choose wisely.

• bits — must be 8 or 16. That's it. Those are the options. 🙈
• 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.
• stereo — set it to 1 for stereo streams, or 0 otherwise.

---

🎚️ adjusting it mid-stream (yes you can, icon behavior)

Wanna tweak the pitch, volume, or panning of a stream once it's already playing? You absolutely can — just use the regular voice_*() functions and pass stream->voice as the parameter. 🫶

The format of the sample data is described in the SAMPLE entry of the "Structures and types defined by Allegro" chapter, iykyk.

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

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

🍓 example time

/* 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");

---

⭐ RETURN VALUE ⭐

This function returns a pointer to the audio stream — or NULL if it could not be created. 😭 So like, check it. Always check it.

ngl if you skip the NULL check and it fails, that's on you bestie 💀

---

👑 SEE ALSO 👑

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

---

and that's the whole page, periodt. this was play_audio_stream(3) from the Allegro manual, brought to you by version 4.4.3, same energy as the original dated release. slay, go make some noise 🎀💖✨