# CategoryAudio Audio functionality for the SDL library. All audio in SDL3 revolves around [SDL_AudioStream](SDL_AudioStream). Whether you want to play or record audio, convert it, stream it, buffer it, or mix it, you're going to be passing it through an audio stream. Audio streams are quite flexible; they can accept any amount of data at a time, in any supported format, and output it as needed in any other format, even if the data format changes on either side halfway through. An app opens an audio device and binds any number of audio streams to it, feeding more data to the streams as available. When the device needs more data, it will pull it from all bound streams and mix them together for playback. Audio streams can also use an app-provided callback to supply data on-demand, which maps pretty closely to the SDL2 audio model. SDL also provides a simple .WAV loader in [SDL_LoadWAV](SDL_LoadWAV) (and [SDL_LoadWAV_IO](SDL_LoadWAV_IO) if you aren't reading from a file) as a basic means to load sound data into your program. ## Logical audio devices In SDL3, opening a physical device (like a SoundBlaster 16 Pro) gives you a logical device ID that you can bind audio streams to. In almost all cases, logical devices can be used anywhere in the API that a physical device is normally used. However, since each device opening generates a new logical device, different parts of the program (say, a VoIP library, or text-to-speech framework, or maybe some other sort of mixer on top of SDL) can have their own device opens that do not interfere with each other; each logical device will mix its separate audio down to a single buffer, fed to the physical device, behind the scenes. As many logical devices as you like can come and go; SDL will only have to open the physical device at the OS level once, and will manage all the logical devices on top of it internally. One other benefit of logical devices: if you don't open a specific physical device, instead opting for the default, SDL can automatically migrate those logical devices to different hardware as circumstances change: a user plugged in headphones? The system default changed? SDL can transparently migrate the logical devices to the correct physical device seamlessly and keep playing; the app doesn't even have to know it happened if it doesn't want to. ## Simplified audio As a simplified model for when a single source of audio is all that's needed, an app can use [SDL_OpenAudioDeviceStream](SDL_OpenAudioDeviceStream), which is a single function to open an audio device, create an audio stream, bind that stream to the newly-opened device, and (optionally) provide a callback for obtaining audio data. When using this function, the primary interface is the [SDL_AudioStream](SDL_AudioStream) and the device handle is mostly hidden away; destroying a stream created through this function will also close the device, stream bindings cannot be changed, etc. One other quirk of this is that the device is started in a _paused_ state and must be explicitly resumed; this is partially to offer a clean migration for SDL2 apps and partially because the app might have to do more setup before playback begins; in the non-simplified form, nothing will play until a stream is bound to a device, so they start _unpaused_. ## Channel layouts Audio data passing through SDL is uncompressed PCM data, interleaved. One can provide their own decompression through an MP3, etc, decoder, but SDL does not provide this directly. Each interleaved channel of data is meant to be in a specific order. Abbreviations: - FRONT = single mono speaker - FL = front left speaker - FR = front right speaker - FC = front center speaker - BL = back left speaker - BR = back right speaker - SR = surround right speaker - SL = surround left speaker - BC = back center speaker - LFE = low-frequency speaker These are listed in the order they are laid out in memory, so "FL, FR" means "the front left speaker is laid out in memory first, then the front right, then it repeats for the next audio frame". - 1 channel (mono) layout: FRONT - 2 channels (stereo) layout: FL, FR - 3 channels (2.1) layout: FL, FR, LFE - 4 channels (quad) layout: FL, FR, BL, BR - 5 channels (4.1) layout: FL, FR, LFE, BL, BR - 6 channels (5.1) layout: FL, FR, FC, LFE, BL, BR (last two can also be SL, SR) - 7 channels (6.1) layout: FL, FR, FC, LFE, BC, SL, SR - 8 channels (7.1) layout: FL, FR, FC, LFE, BL, BR, SL, SR This is the same order as DirectSound expects, but applied to all platforms; SDL will swizzle the channels as necessary if a platform expects something different. [SDL_AudioStream](SDL_AudioStream) can also be provided channel maps to change this ordering to whatever is necessary, in other audio processing scenarios. <!-- END CATEGORY DOCUMENTATION --> ## Functions <!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. --> <!-- BEGIN CATEGORY LIST: CategoryAudio, CategoryAPIFunction --> - [SDL_AudioDevicePaused](SDL_AudioDevicePaused) - [SDL_AudioStreamDevicePaused](SDL_AudioStreamDevicePaused) - [SDL_BindAudioStream](SDL_BindAudioStream) - [SDL_BindAudioStreams](SDL_BindAudioStreams) - [SDL_ClearAudioStream](SDL_ClearAudioStream) - [SDL_CloseAudioDevice](SDL_CloseAudioDevice) - [SDL_ConvertAudioSamples](SDL_ConvertAudioSamples) - [SDL_CreateAudioStream](SDL_CreateAudioStream) - [SDL_DestroyAudioStream](SDL_DestroyAudioStream) - [SDL_FlushAudioStream](SDL_FlushAudioStream) - [SDL_GetAudioDeviceChannelMap](SDL_GetAudioDeviceChannelMap) - [SDL_GetAudioDeviceFormat](SDL_GetAudioDeviceFormat) - [SDL_GetAudioDeviceGain](SDL_GetAudioDeviceGain) - [SDL_GetAudioDeviceName](SDL_GetAudioDeviceName) - [SDL_GetAudioDriver](SDL_GetAudioDriver) - [SDL_GetAudioFormatName](SDL_GetAudioFormatName) - [SDL_GetAudioPlaybackDevices](SDL_GetAudioPlaybackDevices) - [SDL_GetAudioRecordingDevices](SDL_GetAudioRecordingDevices) - [SDL_GetAudioStreamAvailable](SDL_GetAudioStreamAvailable) - [SDL_GetAudioStreamData](SDL_GetAudioStreamData) - [SDL_GetAudioStreamDevice](SDL_GetAudioStreamDevice) - [SDL_GetAudioStreamFormat](SDL_GetAudioStreamFormat) - [SDL_GetAudioStreamFrequencyRatio](SDL_GetAudioStreamFrequencyRatio) - [SDL_GetAudioStreamGain](SDL_GetAudioStreamGain) - [SDL_GetAudioStreamInputChannelMap](SDL_GetAudioStreamInputChannelMap) - [SDL_GetAudioStreamOutputChannelMap](SDL_GetAudioStreamOutputChannelMap) - [SDL_GetAudioStreamProperties](SDL_GetAudioStreamProperties) - [SDL_GetAudioStreamQueued](SDL_GetAudioStreamQueued) - [SDL_GetCurrentAudioDriver](SDL_GetCurrentAudioDriver) - [SDL_GetNumAudioDrivers](SDL_GetNumAudioDrivers) - [SDL_GetSilenceValueForFormat](SDL_GetSilenceValueForFormat) - [SDL_IsAudioDevicePhysical](SDL_IsAudioDevicePhysical) - [SDL_IsAudioDevicePlayback](SDL_IsAudioDevicePlayback) - [SDL_LoadWAV](SDL_LoadWAV) - [SDL_LoadWAV_IO](SDL_LoadWAV_IO) - [SDL_LockAudioStream](SDL_LockAudioStream) - [SDL_MixAudio](SDL_MixAudio) - [SDL_OpenAudioDevice](SDL_OpenAudioDevice) - [SDL_OpenAudioDeviceStream](SDL_OpenAudioDeviceStream) - [SDL_PauseAudioDevice](SDL_PauseAudioDevice) - [SDL_PauseAudioStreamDevice](SDL_PauseAudioStreamDevice) - [SDL_PutAudioStreamData](SDL_PutAudioStreamData) - [SDL_ResumeAudioDevice](SDL_ResumeAudioDevice) - [SDL_ResumeAudioStreamDevice](SDL_ResumeAudioStreamDevice) - [SDL_SetAudioDeviceGain](SDL_SetAudioDeviceGain) - [SDL_SetAudioPostmixCallback](SDL_SetAudioPostmixCallback) - [SDL_SetAudioStreamFormat](SDL_SetAudioStreamFormat) - [SDL_SetAudioStreamFrequencyRatio](SDL_SetAudioStreamFrequencyRatio) - [SDL_SetAudioStreamGain](SDL_SetAudioStreamGain) - [SDL_SetAudioStreamGetCallback](SDL_SetAudioStreamGetCallback) - [SDL_SetAudioStreamInputChannelMap](SDL_SetAudioStreamInputChannelMap) - [SDL_SetAudioStreamOutputChannelMap](SDL_SetAudioStreamOutputChannelMap) - [SDL_SetAudioStreamPutCallback](SDL_SetAudioStreamPutCallback) - [SDL_UnbindAudioStream](SDL_UnbindAudioStream) - [SDL_UnbindAudioStreams](SDL_UnbindAudioStreams) - [SDL_UnlockAudioStream](SDL_UnlockAudioStream) <!-- END CATEGORY LIST --> ## Datatypes <!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. --> <!-- BEGIN CATEGORY LIST: CategoryAudio, CategoryAPIDatatype --> - [SDL_AudioDeviceID](SDL_AudioDeviceID) - [SDL_AudioPostmixCallback](SDL_AudioPostmixCallback) - [SDL_AudioStream](SDL_AudioStream) - [SDL_AudioStreamCallback](SDL_AudioStreamCallback) <!-- END CATEGORY LIST --> ## Structs <!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. --> <!-- BEGIN CATEGORY LIST: CategoryAudio, CategoryAPIStruct --> - [SDL_AudioSpec](SDL_AudioSpec) <!-- END CATEGORY LIST --> ## Enums <!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. --> <!-- BEGIN CATEGORY LIST: CategoryAudio, CategoryAPIEnum --> - [SDL_AudioFormat](SDL_AudioFormat) <!-- END CATEGORY LIST --> ## Macros <!-- DO NOT HAND-EDIT CATEGORY LISTS, THEY ARE AUTOGENERATED AND WILL BE OVERWRITTEN, BASED ON TAGS IN INDIVIDUAL PAGE FOOTERS. EDIT THOSE INSTEAD. --> <!-- BEGIN CATEGORY LIST: CategoryAudio, CategoryAPIMacro --> - [SDL_AUDIO_BITSIZE](SDL_AUDIO_BITSIZE) - [SDL_AUDIO_BYTESIZE](SDL_AUDIO_BYTESIZE) - [SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK](SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK) - [SDL_AUDIO_DEVICE_DEFAULT_RECORDING](SDL_AUDIO_DEVICE_DEFAULT_RECORDING) - [SDL_AUDIO_FRAMESIZE](SDL_AUDIO_FRAMESIZE) - [SDL_AUDIO_ISBIGENDIAN](SDL_AUDIO_ISBIGENDIAN) - [SDL_AUDIO_ISFLOAT](SDL_AUDIO_ISFLOAT) - [SDL_AUDIO_ISINT](SDL_AUDIO_ISINT) - [SDL_AUDIO_ISLITTLEENDIAN](SDL_AUDIO_ISLITTLEENDIAN) - [SDL_AUDIO_ISSIGNED](SDL_AUDIO_ISSIGNED) - [SDL_AUDIO_ISUNSIGNED](SDL_AUDIO_ISUNSIGNED) - [SDL_AUDIO_MASK_BIG_ENDIAN](SDL_AUDIO_MASK_BIG_ENDIAN) - [SDL_AUDIO_MASK_BITSIZE](SDL_AUDIO_MASK_BITSIZE) - [SDL_AUDIO_MASK_FLOAT](SDL_AUDIO_MASK_FLOAT) - [SDL_AUDIO_MASK_SIGNED](SDL_AUDIO_MASK_SIGNED) - [SDL_DEFINE_AUDIO_FORMAT](SDL_DEFINE_AUDIO_FORMAT) <!-- END CATEGORY LIST --> ---- [CategoryAPICategory](CategoryAPICategory)