SDL_OpenAudioDevice(3)

💖 SDL_OpenAudioDevice(3) — the SDL3 FUNCTIONS girlies' edition 💖

okay bestie, sit down, hydrate, because we're opening a specific audio device and it's lowkey iconic. this is SDL_OpenAudioDevice, live from the SDL3 functions lineup. 🎀

---

✨ NAME ✨

SDL_OpenAudioDevice — open a specific audio device. that's it, that's the gig. 🎧

---

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_audio.h>

SDL_AudioDeviceID SDL_OpenAudioDevice(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec);

---

🦋 DESCRIPTION 🦋

so this one function is giving versatility, because you can open both playback and recording devices through it. no cap. 💅

• playback devices will take data from bound audio streams, mix it, and send it to the hardware.
• recording devices will feed any bound audio streams with a copy of any incoming data.

an opened audio device starts out with no audio streams bound. nothing. empty. a fresh face. ✨ to start audio playing, you bind a stream and supply audio data to it. and here's the big glow-up: unlike SDL2, there is no audio callback. you only bind audio streams and make sure they have data flowing into them. periodt. (however — and this is the tea — you can simulate SDL2's semantics fairly closely by using SDL_OpenAudioDeviceStream instead of this function. iykyk. 🫶)

if you don't care about opening a specific device, pass a devid of either SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK or SDL_AUDIO_DEVICE_DEFAULT_RECORDING. in this case, SDL will try to pick the most reasonable default, and may also switch between physical devices seamlessly later, if the most reasonable default changes during the lifetime of this opened device. like what counts as a change?? bestie, so many things:

• user changed the default in the OS's system preferences,
• the default got unplugged so the system jumped to a new default,
• the user plugged in headphones on a mobile device,
• etc.

unless you have a good reason to choose a specific device, this is probably what you want. main character energy, honestly. 👑

you may request a specific format for the audio device, but there is no promise the device will honor that request — for several reasons. as such, it's only meant to be a hint as to what data your app will provide. audio streams will accept data in whatever format you specify and manage conversion for you as appropriate. 💖 SDL_GetAudioDeviceFormat can tell you the preferred format for the device before opening, and the actual format the device is using after opening. glow-up before AND after pics, literally.

it's legal to open the same device ID more than once — each successful open will generate a new logical SDL_AudioDeviceID that is managed separately from others on the same physical device. this allows libraries to open a device separately from the main app and bind its own streams without conflicting. no fighting, no drama, just vibes. 🌈

it is also legal to open a device ID returned by a previous call to this function; doing so just creates another logical device on the same physical device. this may be useful for making logical groupings of audio streams. organized queen behavior. 🎀

this function returns the opened device ID on success. this is a new, unique SDL_AudioDeviceID that represents a logical device. slay. ✨

some backends might offer arbitrary devices (for example, a networked audio protocol that can connect to an arbitrary server). for these — and this is a change from SDL2 — you should open a default device ID and use an SDL hint to specify the target if you care, or otherwise let the backend figure out a reasonable default. most backends don't offer anything like this, and often this would be an end user setting an environment variable for their custom need, and not something an application should specifically manage. not your job, bestie. 🙈

when done with an audio device, possibly at the end of the app's life, one should call SDL_CloseAudioDevice() on the returned device id. do not leave it hanging. ghosting is rude. 💀

---

💜 FUNCTION PARAMETERS 💜

• devid — the device instance id to open, or SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK or SDL_AUDIO_DEVICE_DEFAULT_RECORDING for the most reasonable default device. 🎯
• spec — the requested device configuration. can be NULL to use reasonable defaults. lowkey the chill option. 🍓

---

⭐ RETURN VALUE ⭐

returns the device ID on success, or 0 on failure. and if it fails?? call SDL_GetError() for more information. she will tell you what went wrong, fr fr. 😭

---

🔥 THREAD SAFETY 🔥

it is safe to call this function from any thread. every thread gets a turn, we don't gatekeep. 🫶

---

🌈 AVAILABILITY 🌈

this function is available since SDL 3.2.0. not ancient history, a modern classic. 💅

---

👑 SEE ALSO 👑

• SDL_CloseAudioDevice(3)
• SDL_GetAudioDeviceFormat(3)

go read those too, bestie, they're the supporting cast and they ate. ✨

---

okay that's the whole page!! brought to you by Simple Directmedia Layer, version SDL 3.4.18 — mwah, sending you a big kiss from the SDL 3.4.18 era, hope your streams always have data flowing into them, bye bestie!! 🎀💖🦋🌸💅🫶😭🔥👑🌈⭐💀🙈🍓🧚💜