# 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_PutAudioStreamDataNoCopy](SDL_PutAudioStreamDataNoCopy)
- [SDL_PutAudioStreamPlanarData](SDL_PutAudioStreamPlanarData)
- [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)
- [SDL_AudioStreamDataCompleteCallback](SDL_AudioStreamDataCompleteCallback)
<!-- 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)

