MIX_SetTrackRawIOStream(3)

📦
version 3.2.4 · 2 versions
, in fedora 44

💖 MIX_SetTrackRawIOStream(3) 💖

okay bestie, welcome to the SDL_mixer3 FUNCTIONS section of the manual, and today's main character is MIX_SetTrackRawIOStream 🎀

✨ NAME ✨

MIX_SetTrackRawIOStream — set a MIX_Track's input to an SDL_IOStream that's feeding you raw PCM data 💅

🌸 SYNOPSIS 🌸

#include <SDL3_mixer/SDL_mixer.h>

bool MIX_SetTrackRawIOStream(MIX_Track *track, SDL_IOStream *io, const SDL_AudioSpec *spec, bool closeio);

🦋 DESCRIPTION 🦋

Okay so first things first, bestie: this is not the recommended way to set a track's input. Like, at all. 🙈 But it does have one very specific little slay of a use case: a large file, played once, that has to be read from disk in small chunks as needed. That's the vibe. That's the scenario.

In most cases though? You're way better off creating a MIX_Audio ahead of time and calling MIX_SetTrackAudio() instead. fr fr.

Also worth knowing: MIX_SetTrackAudioStream() can _also_ hand raw PCM audio to a track, but via an SDL_AudioStream. That one might be preferable, unless your data is already coming directly from an SDL_IOStream. iykyk.

The stream you hand over here should provide audio in raw PCM format. no cap.

⚠️ A given IOStream may only be assigned to a single track at a time. Duplicate assignments won't return an error — but if you assign one stream to multiple tracks, each track will read from that stream arbitrarily, which causes confusion and incorrect mixing. it's giving chaos 💀

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

Calling this function with a NULL stream is legal, and it removes any input from the track. If the track was currently playing, the next time the mixer runs it'll notice this and mark the track as stopped, calling any assigned MIX_TrackStoppedCallback. bye bestie 👋

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. glow-up moment ✨

🫶 The provided stream must remain valid until the track no longer needs it — either by changing the track's input or by destroying the track.

💅 FUNCTION PARAMETERS 💅

  • track — the track on which to set a new audio input 👑
  • io — the new i/o stream to use as the track's input 🌊
  • spec — the format of the PCM data that the SDL_IOStream will provide 🎚️
  • closeio — if true, close the stream when done with it 🔒

⭐ RETURN VALUE ⭐

Returns true on success, false on error. If it's giving error, call SDL_GetError() for details 😭

🧚 THREAD SAFETY 🧚

It is safe to call this function from any thread. multitasking queen 🐝

🌈 AVAILABILITY 🌈

This function is available since SDL_mixer 3.0.0. vintage but iconic ✨

🍓 SEE ALSO 🍓

and that's the whole page, bestie!! 💜 this was SDL_mixer — specifically SDL_mixer 3.2.4, dated with the MIX_SetTrackRawIOStream(3) page, so go forth and stream that raw PCM responsibly. mwah 🎀💖

📦 where this page comes from