SDL_SETAUDIOSTREAMOUTPUTCHANNELMAP(3)

💖 SDL_SetAudioStreamOutputChannelMap(3) 💖

okay bestie, welcome to the SDL3 FUNCTIONS corner of the manual, this one's all about telling an audio stream how to shuffle its channels around on the way out. no cap, it's giving mixer-board energy. 🎚️✨

---

🌸 NAME 🌸

SDL_SetAudioStreamOutputChannelMap — set the current output channel map of an audio stream. literally just "hey stream, remap ur outs like this." 💅

---

✨ SYNOPSIS ✨

#include <SDL3/SDL_audio.h>

bool SDL_SetAudioStreamOutputChannelMap(SDL_AudioStream *stream, const int *chmap, int count);

---

🦋 DESCRIPTION 🦋

so, channel maps are optional. like, genuinely optional optional. most things don't need them at all — instead you just pass data in the [order that SDL expects](CategoryAudio#channel-layouts) and everyone's happy. 🫶

the output channel map reorders data that is leaving a stream via SDL_GetAudioStreamData. so it's the exit-door bouncer, not the entrance one. 🚪

each item in the array represents an input channel, and its value is the channel that it should be remapped to. wanna reverse a stereo signal's left and right? you'd have an array of { 1, 0 }. iconic. it is legal to remap multiple channels to the same thing, so { 1, 1 } would duplicate the right channel to both channels of a stereo signal. and if an element in the channel map is set to -1 instead of a valid channel, that channel gets muted — it's set to a silence value. shhh. 🤫

⚠️ you cannot change the number of channels through a channel map. you can only reorder/mute them. that's the whole gig, bestie, don't push it.

the output channel map can be changed at any time, because output remapping is applied during SDL_GetAudioStreamData. so whenever, wherever. 🌈

audio streams default to no remapping applied. passing a NULL channel map is legal, and turns off remapping. reset era. 💫

SDL will copy the channel map, so the caller does not have to save this array after this call. you can let it go, it's safe. 🕊️

if count is not equal to the current number of channels in the audio stream's format, this will fail. it's a safety measure to make sure a race condition hasn't changed the format while this call is setting the channel map. basically SDL double-checking that nobody snuck in and redecorated mid-call. 😭

unlike attempting to change the stream's format, the output channel map on a stream bound to a recording device is permitted to change at any time. any data added to the stream after this call will have the new mapping, but previously-added data will still have the prior mapping. the past stays the past, periodt. when the channel map doesn't match the hardware's channel layout, SDL will convert the data before feeding it to the device for playback. 🔥

---

🎀 FUNCTION PARAMETERS 🎀

• stream — the SDL_AudioStream to change. the main character we're editing. 👑
• chmap — the new channel map, NULL to reset to default. yes, NULL is a valid vibe here.
• count — the number of channels in the map.

---

💜 RETURN VALUE 💜

returns true on success or false on failure; call SDL_GetError() for more information. so if it flops, ask SDL_GetError() what happened, she'll tell you. 💀

---

🔒 THREAD SAFETY 🔒

it is safe to call this function from any thread, as it holds a stream-specific mutex while running. multitask slay. ✨

🛑 BUT — don't change the stream's format to have a different number of channels from a a different thread at the same time, though! that's the one thing that'll ruin the whole vibe. fr fr.

---

⭐ AVAILABILITY ⭐

this function is available since SDL 3.2.0. vintage-ish, but fresh. 🍓

---

🌈 SEE ALSO 🌈

• SDL_SetAudioStreamInputChannelMap(3) — the input-side twin, go say hi 🧚

---

and that's the tea, bestie 💖 this page came to you from <strong>Simple Directmedia Layer</strong>, living in <strong>SDL 3.4.18</strong> — so if you see SDL_SetAudioS...putChannelMap(3) floating around, that's just her short name. mwah, go remap something responsibly 💅✨🦋