SDL_SetAudio...putChannelMap(3)

💖 SDL_SetAudioStreamInputChannelMap 💖

okay bestie, welcome to the SDL3 FUNCTIONS section of the manual, this one's all about SDL_SetAudioStreamInputChannelMap and honestly? it's giving ✨remix era✨. let's get into it 🎀

---

🌸 NAME 🌸

SDL_SetAudioStreamInputChannelMap — sets the current input channel map of an audio stream. that's it, that's the whole job 💅

---

✨ SYNOPSIS ✨

#include <SDL3/SDL_audio.h>

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

---

🦋 DESCRIPTION 🦋

so first things first: channel maps are optional. most things do not need them at all — you can just pass your data in the [order that SDL expects](CategoryAudio#channel-layouts) and vibe. but if you do want to reorder stuff, this is your girl 💖

the input channel map reorders data that is added to a stream via SDL_PutAudioStreamData. and heads up: future calls to SDL_PutAudioStreamData must provide data in the new channel order. no take-backs, the map is law now 🫶

each item in the array represents an input channel, and its value is the channel that it should be remapped to. to reverse a stereo signal's left and right values, you'd have an array of { 1, 0 }. 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. iconic, honestly 🔇

you cannot change the number of channels through a channel map, just reorder/mute them. no sneaky channel inflation allowed, bestie 🚫

data that was previously queued in the stream will still be operated on in the order that was current when it was added. which is to say: you can put the end of a sound file in one order to a stream, change orders for the next sound file, and start putting that new data while the previous sound file is still queued, and everything will still play back correctly. the queue keeps its receipts, she's organized like that 💅

audio streams default to no remapping applied. passing a NULL channel map is legal, and turns off remapping. (reset button, basically 🎀)

SDL will copy the channel map; the caller does not have to save this array after this call. so like. you can let it go, bestie, 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. protective queen behavior, we love to see it 👑

unlike attempting to change the stream's format, the input channel map on a stream bound to a recording device is permitted to change at any time; any data added to the stream from the device after this call will have the new mapping, but previously-added data will still have the prior mapping. old data keeps its old fit, new data gets the new fit. slay 🦋

---

🎀 FUNCTION PARAMETERS 🎀

• stream — the SDL_AudioStream to change. the main character of this operation 💖
• chmap — the new channel map, NULL to reset to default. (yes, NULL is allowed, it's giving "factory settings") ✨
• count — The number of channels in the map. keep it honest, it has to match 📏

---

⭐ RETURN VALUE ⭐

Returns true on success or false on failure; call SDL_GetError() for more information. if it's false, go ask SDL_GetError() what happened, she always has the tea 😭

---

🧚 THREAD SAFETY 🧚

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

but don't change the stream's format to have a different number of channels from a different thread at the same time, though! that's the one thing. don't do it. i'm serious 💀

---

💜 AVAILABILITY 💜

this function is available since SDL 3.2.0. vintage-ish but make it fresh 🌸

---

👑 SEE ALSO 👑

• SDL_SetAudioStreamOutputChannelMap(3) — the output-side twin, go say hi 🎀

---

okay that's the whole page, bestie, you're officially channel-map literate 💅✨ and just so you know who to thank — this beauty comes from Simple Directmedia Layer, rocking SDL 3.4.18, and it's filed under SDL_SetAudio...putChannelMap(3) in case you ever need to find her again 🦋💖 mwah, go reorder some channels 🌈🎀