SDL_SETAUDIOSTREAMPUTCALLBACK(3)

✨ SDL_SetAudioStreamPutCallback(3) ✨

okay bestie, welcome to the SDL3 FUNCTIONS corner of the manual 💅 this one's all about the put callback — the lil function that fires the second somebody drops data into your audio stream. buckle up, it's giving audio nerd but make it cute 🎀

---

🦋 NAME 🦋

SDL_SetAudioStreamPutCallback — set a callback that runs when data is added to an audio stream.

---

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_audio.h>

bool SDL_SetAudioStreamPutCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata);

---

💖 DESCRIPTION 💖

So here's the tea, bestie: this callback gets called _after_ the data is added to the stream. After, not before. Which means your callback gets the chance to grab that data immediately — like, right off the counter, still warm 🔥

Your callback can (optionally!) call SDL_GetAudioStreamData() to snag audio from the stream during this very call. Optional though, no pressure, she's not obligated ✨

Now the callback's additional_amount argument — this is how many bytes of _converted_ data (in the stream's output format, iykyk) was provided by the caller. Lowkey it might underestimate a little bit, but that's on purpose, for safety 🫶

And here's the messy part that you need to know: that value might be less than what's currently available in the stream, if data was already chillin' there from before. And it might be less than what the caller provided if the stream needs to keep a buffer to aid in resampling. Which means… yeah, the callback may be handed zero bytes, and a different amount on each call. Not a bug, just the vibe check failing sometimes 💀

If you want the real numbers, the callback may call SDL_GetAudioStreamAvailable to see the total amount currently available to read from the stream — instead of just the total provided by the current call. That's your actual main character move 👑

Oh and — the callback is not required to obtain all the data. She can read less, or none at all. Whatever. Anything not read right now simply remains in the stream for later access. No data is wasted, periodt 💅

heads up: clearing or flushing an audio stream does NOT call this callback. so don't be waiting on it, bestie 😭

One more thing: this function obtains the stream's lock. Which means any existing callback (get or put) that's in progress will finish running before the new callback gets set. So no chaotic overlapping, it's very orderly, very demure 🌸

And if you set a NULL function? That turns off the callback. bye bestie 👋

---

🎀 FUNCTION PARAMETERS 🎀

• stream — the audio stream to set the new callback on. the canvas, the moment, the whole point 🎨
• callback — the new callback function to call when data is added to the stream. your lil star of the show ⭐
• userdata — an opaque pointer provided to the callback for its own personal use. it's giving private diary, only the callback reads it 🙈

---

⭐ RETURN VALUE ⭐

Returns true on success or false on failure — and if it fails, call SDL_GetError() for more info, she'll tell you everything 💜

Fun fact: this only fails if stream is NULL. That's it. That's the only way to fumble this one, no cap.

---

🌈 THREAD SAFETY 🌈

It is safe to call this function from any thread. go off, multithreaded queen 👑✨

---

💜 AVAILABILITY 💜

This function is available since SDL 3.2.0. brand new, freshly dropped, iconic behavior 🎀

---

🫶 SEE ALSO 🫶

• SDL_SetAudioStreamGetCallback(3) — her sister, the get side of the story 🦋

---

and that's the whole page bestie!! 💖 this manual page came to you courtesy of Simple Directmedia Layer, straight outta SDL 3.4.18, and yeah it's literally titled SDL_SetAudioStreamPutCallback(3) because of course it is 🎀 mwah, go set some callbacks, slay ✨🌸