MIX_SetTrackIOStream(3)

💖 MIX_SetTrackIOStream — the manual, but make it cute 💖

okay bestie, this is a page from the SDL_mixer3 function docs (MIX_SetTrackIOStream(3) if you're being formal about it). it's all about wiring up a track's input to an SDL_IOStream. let's get into it 🎀

---

✨ NAME ✨

MIX_SetTrackIOStream — set a MIX_Track's input to an SDL_IOStream.

like. that's the whole vibe. you're giving a track a stream to read its audio from. periodt. 💅

---

🌸 SYNOPSIS 🌸

#include <SDL3_mixer/SDL_mixer.h>

bool MIX_SetTrackIOStream(MIX_Track *track, SDL_IOStream *io, bool closeio);

look at that signature. three little args. so simple. so elegant. she ate. ✨

---

🦋 DESCRIPTION 🦋

okay so first things first, bestie — this is not the recommended way to set a track's input. like, it's valid, it works, but it's not the main character here. 🙈

however, there is one very specific scenario where it's lowkey perfect: you've got a large file, you wanna play it once, and it must be read from disk in small chunks as needed. that's the niche. that's the moment. that's her. 👑

in most cases though? you should create a MIX_Audio ahead of time and use MIX_SetTrackAudio() instead. that's the recommended path. iykyk. 💖

the stream you hand over here should provide an audio file in a supported format. SDL_mixer will parse it during this call to make sure it's valid, and then it'll read file data from the stream as it needs to decode more during mixing. so like, it's doing a lil vibe check on your stream first. 🧚

⚠️ the stream must be able to seek through the complete set of data, or this function will fail. no seeking = no service. 💀

alsoooo, a given IOStream may only be assigned to a single track at a time. duplicate assignments won't return an error — which like, rude, no warning?? 😭 — but assigning a stream to multiple tracks will cause each track to read from the stream arbitrarily, which means confusion, incorrect mixing, or failure to decode. do not do this. please. for me. 🙏

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 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 it's not a jump scare, it's a graceful exit. 🫶

it's also 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. which like... yeah, that's fair honestly. in such a case, one can call MIX_PlayTrack again to adjust parameters. 💜

and the important one: the provided stream must remain valid until the track no longer needs it — either by changing the track's input or destroying the track. don't let it get freed early, bestie, that's how you get undefined behaviour energy. 🌈

---

🎀 FUNCTION PARAMETERS 🎀

• track — the track on which to set a new audio input. she's the one getting the glow-up. 👑
• io — the new i/o stream to use as the track's input. the fresh new supply. 🍓
• closeio — if true, close the stream when done with it. so like, do you want her to clean up after herself? yes = true. 🧹

---

⭐ RETURN VALUE ⭐

returns true on success, false on error. and if it's false, hit up SDL_GetError() for the details — she'll tell you what went wrong. 💅

---

💜 THREAD SAFETY 💜

it is safe to call this function from any thread. no notes. iconic behaviour. 🌸

---

🌈 AVAILABILITY 🌈

this function is available since SDL_mixer 3.0.0. so she's been around. a veteran. a legend. ✨

---

👑 SEE ALSO 👑

• MIX_SetTrackRawIOStream(3)

---

aaaand that's the page bestie!! go forth and stream responsibly 🦋💖

— written up with love from the SDL_mixer docs, SDL_mixer 3.2.4 era. mwah. 💋✨