SDL_LoadWAV_IO(3)

SDL_LoadWAV_IO(3) 💖

okay bestie, this one lives in the SDL3 FUNCTIONS section of the SDL3 manual, and it's literally the "pls just give me the audio out of this .WAV file" function. Let's get into it 🎀

---

✨ NAME ✨

SDL_LoadWAV_IO — load the audio data of a WAVE file into memory. 🦋

---

✨ SYNOPSIS ✨

#include <SDL3/SDL_audio.h>

bool SDL_LoadWAV_IO(SDL_IOStream *src, bool closeio, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len);

---

✨ DESCRIPTION ✨

so like, to load a WAVE file you need src, spec, audio_buf and audio_len to all be valid pointers, no cap. Once they are, the entire data portion of the file gets loaded into memory and decoded if it needs to be. 💅

the formats it fucks with are RIFF WAVE files with:

• PCM — 8, 16, 24, and 32 bits
• IEEE Float — 32 bits
• Microsoft ADPCM and IMA ADPCM — 4 bits
• A-law and mu-law — 8 bits

anything else? not supported rn, it's giving error. 💀

if this function slays (i.e. succeeds), the return value is zero and the pointer to the audio data that the function allocated gets written to audio_buf, and its length in bytes goes into audio_len. the SDL_AudioSpec members freq, channels, and format get set to the values of the audio data in the buffer. obsessed. 🌸

🚨 you MUST call SDL_free() on the audio data you get back in audio_buf once you're done with it. no leaking bestie, i will know.

ngl the .WAV format is underspecified — like the spec said "figure it out" — so there are SO many problematic files in the wild that make strict decoders have a whole meltdown. to stay compatible with those chaotic files, this decoder is lenient about the truncation of the file, the fact chunk, and the size of the RIFF chunk. and if you want to tune how all that loading goes down, there are hints for that:

• SDL_HINT_WAVE_RIFF_CHUNK_SIZE
• SDL_HINT_WAVE_TRUNCATION
• SDL_HINT_WAVE_FACT_CHUNK

any file that's invalid (truncation, corruption, or wrong values in the headers), too big, or unsupported → error. and on top of that, any critical I/O error from the data source will straight up terminate the loading process with an error. the function returns NULL on error and in all cases (except when src is NULL) an appropriate error message will be set. periodt. 💅

also it is required that the data source supports seeking. iykyk.

example time bestie ✨

SDL_LoadWAV_IO(SDL_IOFromFile("sample.wav", "rb"), true, &spec, &buf, &len);

and btw, the SDL_LoadWAV function does this exact same thing for you, but in a less messy way: 🫶

SDL_LoadWAV("sample.wav", &spec, &buf, &len);

---

✨ FUNCTION PARAMETERS ✨

• src — the data source for the WAVE data. 🎧
• closeio — if true, calls SDL_CloseIO() on src before returning, even in the case of an error. so it's closing the door behind you no matter what 🙈
• spec — a pointer to an SDL_AudioSpec that will be set to the WAVE data's format details on successful return. the whole vibe of the file, basically 💖
• audio_buf — a pointer filled with the audio data, allocated by the function. you don't make it, it makes it for you ✨
• audio_len — a pointer filled with the length of the audio data buffer in bytes. 📏

---

✨ RETURN VALUE ✨

returns true on success. audio_buf gets filled with a pointer to an allocated buffer containing the audio data, and audio_len gets filled with the length of that audio buffer in bytes. slay. 👑

it returns false if the .WAV file can't be opened, uses an unknown data format, or is corrupt — call SDL_GetError() for more info bestie, it'll spill the tea. ☕

and when your app is done with the data in audio_buf, it should call SDL_free() to dispose of it. (yes i'm saying it again, it's THAT important 💀)

---

✨ THREAD SAFETY ✨

it is safe to call this function from any thread. main character energy in every single one 🌈

---

✨ AVAILABILITY ✨

this function is available since SDL 3.2.0. so if you're on anything older, it's not here yet, sorry bestie 😭

---

✨ SEE ALSO ✨

• SDL_free(3)
• SDL_LoadWAV(3)

---

and that's the whole page, bestie!! this gorgeousness comes to you courtesy of Simple Directmedia Layer, version SDL 3.4.18 💅✨ go load some WAVs, free your buffers, and stay iconic 🎀🦋💖