MIX_LOADAUDIOWITHPROPERTIES(3)

📦
version 3.2.4 · 2 versions
, in fedora 44

💖 MIX_LoadAudioWithProperties 💖 (the NAME bit)

okay bestie, so this page is for MIX_LoadAudioWithProperties, which lives in SDL_mixer3 and hangs out in the FUNCTIONS section 🎀. It's the glow-up version of loading audio — instead of a million args, you hand it a whole collection of properties and it does the thing. Slay.

✨ SYNOPSIS ✨

#include <SDL3_mixer/SDL_mixer.h>

MIX_Audio * MIX_LoadAudioWithProperties(SDL_PropertiesID props);

literally that's the whole signature, no cap 💅

🌸 DESCRIPTION 🌸

first things first, go read MIX_LoadAudio_IO() for the rundown on what all the LoadAudio functions actually do — this one's the sibling that speaks in ✨properties✨. It lets you dictate how it operates and it unlocks functionality the other functions straight-up don't offer. main character energy fr.

SDL_PropertiesID are explained over in SDL's own docs ⟨https://wiki.www:lenstrwww:splitstr:nwww:splitstr:r[char46]libsdl.www:lenstrwww:splitstr:nwww:splitstr:r[char46]org/SDL3/CategoryProperties⟩ 👑

Here are the properties it supports, and yes we're going through all of them:

  • MIX_PROP_AUDIO_LOAD_IOSTREAM_POINTER — a pointer to an SDL_IOStream that gets used to load the audio data. Required bestie, you cannot skip this one. And heads up: this stream must be able to seek! 🫶
  • MIX_PROP_AUDIO_LOAD_CLOSEIO_BOOLEAN — set to true if SDL_mixer should close the SDL_IOStream before returning — and yes, whether it succeeded or failed, the closing still happens.
  • MIX_PROP_AUDIO_LOAD_PREDECODE_BOOLEAN — true if SDL_mixer should fully decode and decompress the data before returning. If you don't, it stays in its original state and gets decompressed on demand instead. lazy-girl decoding, honestly iconic.
  • MIX_PROP_AUDIO_LOAD_PREFERRED_MIXER_POINTER — a pointer to a MIX_Mixer, in case steps can be made to match its format while decoding. Optional 💜
  • MIX_PROP_AUDIO_LOAD_SKIP_METADATA_TAGS_BOOLEAN — true to skip parsing metadata tags, like ID3 and APE tags. This can be used to speed up loading if the data definitely doesn't have these tags. > lowkey a trap though: some decoders will fail if these tags are present when this property is true. read that twice, bestie 😭
  • MIX_PROP_AUDIO_LOAD_IGNORE_LOOPS_BOOLEAN — true to ignore metadata in the audio data that specifies loop points. This will make a file decode from start to finish without looping, even if the file itself said it should loop. And listen — this audio can still be looped at playback time via MIX_Track loop settings, regardless of this setting. Default is false.
  • MIX_PROP_AUDIO_DECODER_STRING — the name of the decoder to use for this data. Optional. If you don't specify one, SDL_mixer will examine the data and choose the best decoder for you (king behaviour honestly). These names are the same ones returned from MIX_GetAudioDecoder().

alsooo, specific decoders might accept additional custom properties, such as where to find soundfonts for MIDI playback, etc. 🎹

🦋 FUNCTION PARAMETERS 🦋

  • props — a set of properties on how to load audio. that's it, that's the whole input ✨

🌈 RETURN VALUE 🌈

Returns an audio object that can be used to make sound on a mixer — 🔥 — or NULL on failure. If you got NULL, call SDL_GetError() for more info, because the universe owes you an explanation.

💅 THREAD SAFETY 💅

It is safe to call this function from any thread. go off, gorl 🧚

⭐ AVAILABILITY ⭐

This function is available since SDL_mixer 3.0.0. so it's been here, serving looks, for a minute.

👑 SEE ALSO 👑

okay that's the whole page, you ate it, periodt 🍓💖

this was brought to you by SDL_mixer 3.2.4 — signed, sealed, delivered by the SDL_mixer girlies themselves 🎀✨ slay and goodnight, bestie 🫶

📦 where this page comes from