MIX_SetTrackAudioStream(3)

✨ MIX_SetTrackAudioStream ✨

okay bestie, so this one lives in the SDL_mixer3 functions family (yes, the manual is literally called SDL_mixer3 FUNCTIONS) 💖 and it's genuinely one of the most main-character moves in the whole library. Let's get into it.

---

🌸 NAME 🌸

MIX_SetTrackAudioStream — set a MIX_Track's input to an SDL_AudioStream. that's the whole job. she does one thing and she does it flawlessly 💅

---

🎀 SYNOPSIS 🎀

#include <SDL3_mixer/SDL_mixer.h>

bool MIX_SetTrackAudioStream(MIX_Track *track, SDL_AudioStream *stream);

---

✨ DESCRIPTION ✨

okay so here's the tea 🍓: using an audio stream means your app can generate any type of audio, in any format — maybe procedurally, maybe on-demand, whatever — and mix it in with all the other tracks. it's giving "I make my own sound from scratch and I still sit at the cool table." no cap.

when a track uses an audio stream, it will call SDL_GetAudioStreamData as it needs more audio to mix. so your app has options, bestie:

• buffer data to the stream ahead of time, or
• set a callback on the stream to provide data as needed.

for the deets, please refer to SDL's documentation. iykyk 🫶

🚨 a given audio stream may only be assigned to a single track at a time!! duplicate assignments won't return an error (rude, I know), but assigning a stream to multiple tracks will cause each track to read from the stream arbitrarily — and that causes confusion and incorrect mixing. literally chaos. do not do this. 💀

once a track has a valid input, it can start mixing sound by calling MIX_PlayTrack(), or possibly MIX_PlayTag(). slay ✨

calling this function with a NULL audio stream is legal, and it removes any input from the track. and if the track was currently playing? the next time the mixer runs, it'll notice and mark the track as stopped, calling any assigned MIX_TrackStoppedCallback. so like, she'll catch the vibe check on her own. 💅

it is legal to change the input of a track while it's playing — however, some states, like loop points, may cease to make sense with the new audio. 😭 in such a case, one can call MIX_PlayTrack again to adjust parameters. fixed! iconic.

the provided audio stream must remain valid until the track no longer needs it — either by changing the track's input or destroying the track. no dangling, fr fr. 👑

---

🦋 FUNCTION PARAMETERS 🦋

• track — the track on which to set a new audio input. (the one getting the glow-up ✨)
• stream — the audio stream to use as the track's input. (the glow-up itself 💖)

---

🌈 RETURN VALUE 🌈

returns true on success, false on error — and if it's false, call SDL_GetError() for details. she'll tell you what went wrong, just ask 🥺

---

💜 THREAD SAFETY 💜

it is safe to call this function from any thread. multi-threaded queen behavior, we love to see it 👑

---

⭐ AVAILABILITY ⭐

this function is available since SDL_mixer 3.0.0. ancient. legendary. a classic 🎀

---

and that's the whole page, bestie!! from the SDL_mixer crew, version SDL_mixer 3.2.4 — go forth and stream ur audio responsibly 💖✨🎀🦋