MIX_LoadAudio_IO(3)

📦
version 3.2.4 · 2 versions
, in fedora 44

💖 MIX_LoadAudio_IO(3) 💖

okay bestie, welcome to the SDL_mixer3 FUNCTIONS section of the manual, and today's main character is MIX_LoadAudio_IO. sit down, get comfy, we're loading audio from an SDL_IOStream and it's gonna be adorable 🎀

✨ NAME ✨

MIX_LoadAudio_IO — load audio for playback from an SDL_IOStream. that's it, that's the whole vibe 🌸

✨ SYNOPSIS ✨

#include <SDL3_mixer/SDL_mixer.h>

MIX_Audio * MIX_LoadAudio_IO(MIX_Mixer *mixer, SDL_IOStream *io, bool predecode, bool closeio);

✨ DESCRIPTION ✨

so like, in normal usage? apps should load audio once, maybe at startup, and then play it a million times. that's the whole point. load once, slay forever 💅

when you load audio, it gets cached fully in RAM in its original data format. then every single time it plays, the data gets decoded. for example — and this is the iconic example — an MP3 will be stored in memory in MP3 format and be decompressed on the fly during playback. it's giving tradeoff between i/o overhead and memory usage, and honestly that's just the deal 🫶

if predecode is true, the data will be decompressed during load and stored as raw PCM data. this might dramatically increase loading time and memory usage, but there will be no need to decompress data during playback. pick your fighter bestie 😭

(one could also use MIX_SetTrackIOStream() to bypass loading the data into RAM upfront at all, but this offers still different tradeoffs. the correct approach depends on the app's needs and employing different approaches in different situations can make sense.) lowkey philosophical, i know 🌈

MIX_Audio objects can be shared between mixers. this function takes a MIX_Mixer, to imply this is the most likely place it will be used and loading should try to match its audio format, but the resulting audio can be used elsewhere. if mixer is NULL, SDL_mixer will set reasonable defaults. no stress, no drama ✨

once a MIX_Audio is created, it can be assigned to a MIX_Track with MIX_SetTrackAudio(), or played without any management with MIX_PlayAudio(). your choice, both are valid, both are cute 💖

when done with a MIX_Audio, it can be freed with MIX_DestroyAudio(). clean up after yourself, we love a responsible queen 👑

this function loads data from an SDL_IOStream. there is also a version that loads from a path on the filesystem (MIX_LoadAudio()), and one that accepts properties for ultimate control (MIX_LoadAudioWithProperties()). pick whichever one matches the moment 🦋

important!! the SDL_IOStream provided must be able to seek, or loading will fail. if the stream can't seek (data is coming from an HTTP connection, etc), consider caching the data to memory or disk first and creating a new stream to read from there. no cap, this one bites people 🫠

✨ FUNCTION PARAMETERS ✨

  • mixer — a mixer this audio is intended to be used with. may be NULL. 💜
  • io — the SDL_IOStream to load data from. 🎀
  • predecode — if true, data will be fully uncompressed before returning. 🌸
  • closeio — true if SDL_mixer should close io before returning (success or failure, both, fr fr). 💅

✨ RETURN VALUE ✨

returns an audio object that can be used to make sound on a mixer, or NULL on failure; call SDL_GetError() for more information. if you get NULL, go check SDL_GetError(), she will tell you what happened 🔍

✨ THREAD SAFETY ✨

it is safe to call this function from any thread. go off, multithreaded icon 🧚

✨ AVAILABILITY ✨

this function is available since SDL_mixer 3.0.0. ancient by internet standards, timeless by Unix standards 👑

✨ SEE ALSO ✨

and that's the whole page bestie!! this one came to you from SDL_mixer 3.2.4 and today's date, brought to you by the SDL_mixer manual itself. go load some audio, predecode responsibly, and remember to MIX_DestroyAudio() when you're done. mwah 💋💖✨

📦 where this page comes from