Audio functionality for the SDL library. More...

Namespaces
namespace	SDL::prop
	Constants for Properties keys.
namespace	SDL::prop::AudioStream
	Properties for AudioStream.

Classes
class	SDL::AudioFormat
	Audio format. More...
struct	SDL::AudioDeviceBase
	Base class to AudioDevice. More...
struct	SDL::AudioDevice
	SDL Audio Device instance IDs. More...
struct	SDL::AudioStreamBase
	Base class to AudioStream. More...
struct	SDL::AudioStream
	The opaque handle that represents an audio stream. More...
class	SDL::AudioStreamLock
	Lock an audio stream for serialized access. More...

Typedefs
using	SDL::AudioFormatRaw = SDL_AudioFormat
	Alias to raw representation for AudioFormat.
using	SDL::AudioDeviceID = SDL_AudioDeviceID
	Alias to raw representation for AudioDevice.
using	SDL::AudioDeviceRef = ResourceRefT<AudioDeviceBase>
	Reference for AudioDevice.
using	SDL::AudioStreamRaw = SDL_AudioStream*
	Alias to raw representation for AudioStream.
using	SDL::AudioStreamRef = ResourceRefT<AudioStreamBase>
	Reference for AudioStream.
using	SDL::AudioSpec = SDL_AudioSpec
	Format specifier for audio data.
using	SDL::AudioPostmixCallback
	A callback that fires when data is about to be fed to an audio device.
using	SDL::AudioPostmixCB
	A callback that fires when data is about to be fed to an audio device.
using	SDL::AudioStreamCallback
	A callback that fires when data passes through an AudioStream.
using	SDL::AudioStreamCB
	A callback that fires when data passes through an AudioStream.
using	SDL::AudioStreamDataCompleteCallback
	A callback that fires for completed PutAudioStreamDataNoCopy() data.
using	SDL::AudioStreamDataCompleteCB
	A callback that fires for completed PutAudioStreamDataNoCopy() data.

Functions
constexpr AudioFormat	SDL::DefineAudioFormat (bool sign, bool bigendian, bool flt, Uint16 size)
	Define an AudioFormat value.
constexpr Uint16	SDL::AudioBitSize (AudioFormatRaw x)
	Retrieve the size, in bits, from an AudioFormat.
constexpr Uint16	SDL::AudioByteSize (AudioFormatRaw x)
	Retrieve the size, in bytes, from an AudioFormat.
constexpr bool	SDL::IsAudioFloat (AudioFormatRaw x)
	Determine if an AudioFormat represents floating point data.
constexpr bool	SDL::IsAudioBigENDIAN (AudioFormatRaw x)
	Determine if an AudioFormat represents bigendian data.
constexpr bool	SDL::IsAudioLittleEndian (AudioFormatRaw x)
	Determine if an AudioFormat represents littleendian data.
constexpr bool	SDL::IsAudioSigned (AudioFormatRaw x)
	Determine if an AudioFormat represents signed data.
constexpr bool	SDL::IsAudioInt (AudioFormatRaw x)
	Determine if an AudioFormat represents integer data.
constexpr bool	SDL::IsAudioUnsigned (AudioFormatRaw x)
	Determine if an AudioFormat represents unsigned data.
constexpr int	SDL::AudioFrameSize (const AudioSpec &x)
	Calculate the size of each audio frame (in bytes) from an AudioSpec.
int	SDL::GetNumAudioDrivers ()
	Use this function to get the number of built-in audio drivers.
const char *	SDL::GetAudioDriver (int index)
	Use this function to get the name of a built in audio driver.
const char *	SDL::GetCurrentAudioDriver ()
	Get the name of the current audio driver.
OwnArray< AudioDeviceRef >	SDL::GetAudioPlaybackDevices ()
	Get a list of currently-connected audio playback devices.
OwnArray< AudioDeviceRef >	SDL::GetAudioRecordingDevices ()
	Get a list of currently-connected audio recording devices.
const char *	SDL::GetAudioDeviceName (AudioDeviceRef devid)
	Get the human-readable name of a specific audio device.
AudioSpec	SDL::GetAudioDeviceFormat (AudioDeviceRef devid, int *sample_frames=nullptr)
	Get the current audio format of a specific audio device.
OwnArray< int >	SDL::GetAudioDeviceChannelMap (AudioDeviceRef devid)
	Get the current channel map of an audio device.
AudioDevice	SDL::OpenAudioDevice (AudioDeviceRef devid, OptionalRef< const AudioSpec > spec)
	Open a specific audio device.
bool	SDL::IsAudioDevicePhysical (AudioDeviceRef devid)
	Determine if an audio device is physical (instead of logical).
bool	SDL::IsAudioDevicePlayback (AudioDeviceRef devid)
	Determine if an audio device is a playback device (instead of recording).
void	SDL::PauseAudioDevice (AudioDeviceRef devid)
	Use this function to pause audio playback on a specified device.
void	SDL::ResumeAudioDevice (AudioDeviceRef devid)
	Use this function to unpause audio playback on a specified device.
bool	SDL::AudioDevicePaused (AudioDeviceRef devid)
	Use this function to query if an audio device is paused.
float	SDL::GetAudioDeviceGain (AudioDeviceRef devid)
	Get the gain of an audio device.
void	SDL::SetAudioDeviceGain (AudioDeviceRef devid, float gain)
	Change the gain of an audio device.
void	SDL::CloseAudioDevice (AudioDeviceID devid)
	Close a previously-opened audio device.
void	SDL::BindAudioStreams (AudioDeviceRef devid, std::span< AudioStreamRef > streams)
	Bind a list of audio streams to an audio device.
void	SDL::BindAudioStream (AudioDeviceRef devid, AudioStreamRef stream)
	Bind a single audio stream to an audio device.
void	SDL::UnbindAudioStreams (std::span< AudioStreamRef > streams)
	Unbind a list of audio streams from their audio devices.
void	SDL::UnbindAudioStream (AudioStreamRef stream)
	Unbind a single audio stream from its audio device.
AudioDeviceRef	SDL::GetAudioStreamDevice (AudioStreamRef stream)
	Query an audio stream for its currently-bound device.
AudioStream	SDL::CreateAudioStream (OptionalRef< const AudioSpec > src_spec, OptionalRef< const AudioSpec > dst_spec)
	Create a new audio stream.
PropertiesRef	SDL::GetAudioStreamProperties (AudioStreamRef stream)
	Get the properties associated with an audio stream.
void	SDL::GetAudioStreamFormat (AudioStreamRef stream, AudioSpec src_spec, AudioSpec dst_spec)
	Query the current format of an audio stream.
void	SDL::SetAudioStreamFormat (AudioStreamRef stream, OptionalRef< const AudioSpec > src_spec, OptionalRef< const AudioSpec > dst_spec)
	Change the input and output formats of an audio stream.
float	SDL::GetAudioStreamFrequencyRatio (AudioStreamRef stream)
	Get the frequency ratio of an audio stream.
void	SDL::SetAudioStreamFrequencyRatio (AudioStreamRef stream, float ratio)
	Change the frequency ratio of an audio stream.
float	SDL::GetAudioStreamGain (AudioStreamRef stream)
	Get the gain of an audio stream.
void	SDL::SetAudioStreamGain (AudioStreamRef stream, float gain)
	Change the gain of an audio stream.
OwnArray< int >	SDL::GetAudioStreamInputChannelMap (AudioStreamRef stream)
	Get the current input channel map of an audio stream.
OwnArray< int >	SDL::GetAudioStreamOutputChannelMap (AudioStreamRef stream)
	Get the current output channel map of an audio stream.
void	SDL::SetAudioStreamInputChannelMap (AudioStreamRef stream, std::span< int > chmap)
	Set the current input channel map of an audio stream.
void	SDL::SetAudioStreamOutputChannelMap (AudioStreamRef stream, std::span< int > chmap)
	Set the current output channel map of an audio stream.
void	SDL::PutAudioStreamData (AudioStreamRef stream, SourceBytes buf)
	Add data to the stream.
void	SDL::PutAudioStreamDataNoCopy (AudioStreamRef stream, SourceBytes buf, AudioStreamDataCompleteCallback callback, void *userdata)
	Add external data to an audio stream without copying it.
void	SDL::PutAudioStreamDataNoCopy (AudioStreamRef stream, SourceBytes buf, AudioStreamDataCompleteCB callback)
	Add external data to an audio stream without copying it.
void	SDL::PutAudioStreamPlanarData (AudioStreamRef stream, const void const channel_buffers, int num_channels, int num_samples)
	Add data to the stream with each channel in a separate array.
int	SDL::GetAudioStreamData (AudioStreamRef stream, TargetBytes buf)
	Get converted/resampled data from the stream.
int	SDL::GetAudioStreamAvailable (AudioStreamRef stream)
	Get the number of converted/resampled bytes available.
int	SDL::GetAudioStreamQueued (AudioStreamRef stream)
	Get the number of bytes currently queued.
void	SDL::FlushAudioStream (AudioStreamRef stream)
	Tell the stream that you're done sending data, and anything being buffered should be converted/resampled and made available immediately.
void	SDL::ClearAudioStream (AudioStreamRef stream)
	Clear any pending data in the stream.
void	SDL::PauseAudioStreamDevice (AudioStreamRef stream)
	Use this function to pause audio playback on the audio device associated with an audio stream.
void	SDL::ResumeAudioStreamDevice (AudioStreamRef stream)
	Use this function to unpause audio playback on the audio device associated with an audio stream.
bool	SDL::AudioStreamDevicePaused (AudioStreamRef stream)
	Use this function to query if an audio device associated with a stream is paused.
void	SDL::LockAudioStream (AudioStreamRef stream)
	Lock an audio stream for serialized access.
void	SDL::UnlockAudioStream (AudioStreamRef stream)
	Unlock an audio stream for serialized access.
void	SDL::SetAudioStreamGetCallback (AudioStreamRef stream, AudioStreamCallback callback, void *userdata)
	Set a callback that runs when data is requested from an audio stream.
void	SDL::SetAudioStreamGetCallback (AudioStreamRef stream, AudioStreamCB callback)
	Set a callback that runs when data is requested from an audio stream.
void	SDL::SetAudioStreamPutCallback (AudioStreamRef stream, AudioStreamCallback callback, void *userdata)
	Set a callback that runs when data is added to an audio stream.
void	SDL::SetAudioStreamPutCallback (AudioStreamRef stream, AudioStreamCB callback)
	Set a callback that runs when data is added to an audio stream.
void	SDL::DestroyAudioStream (AudioStreamRaw stream)
	Free an audio stream.
AudioStream	SDL::OpenAudioDeviceStream (AudioDeviceRef devid, OptionalRef< const AudioSpec > spec, AudioStreamCallback callback=nullptr, void *userdata=nullptr)
	Convenience function for straightforward audio init for the common case.
AudioStream	SDL::OpenAudioDeviceStream (AudioDeviceRef devid, OptionalRef< const AudioSpec > spec, AudioStreamCB callback)
	Convenience function for straightforward audio init for the common case.
void	SDL::SetAudioPostmixCallback (AudioDeviceRef devid, AudioPostmixCallback callback, void *userdata)
	Set a callback that fires when data is about to be fed to an audio device.
void	SDL::SetAudioPostmixCallback (AudioDeviceRef devid, AudioPostmixCB callback)
	Set a callback that fires when data is about to be fed to an audio device.
OwnArray< Uint8 >	SDL::LoadWAV_IO (IOStreamRef src, AudioSpec *spec, bool closeio=false)
	Load the audio data of a WAVE file into memory.
OwnArray< Uint8 >	SDL::LoadWAV (StringParam path, AudioSpec *spec)
	Loads a WAV from a file path.
void	SDL::MixAudio (Uint8 *dst, SourceBytes src, AudioFormat format, float volume)
	Mix audio data in a specified format.
void	SDL::MixAudio (TargetBytes dst, SourceBytes src, AudioFormat format, float volume)
	Mix audio data in a specified format.
OwnArray< Uint8 >	SDL::ConvertAudioSamples (const AudioSpec &src_spec, SourceBytes src_data, const AudioSpec &dst_spec)
	Convert some audio data of one format to another format.
const char *	SDL::GetAudioFormatName (AudioFormatRaw format)
	Get the human readable name of an audio format.
int	SDL::GetSilenceValueForFormat (AudioFormatRaw format)
	Get the appropriate memset value for silencing an audio format.
constexpr	SDL::AudioFormat::AudioFormat (bool sign, bool bigendian, bool flt, Uint16 size)
	Define an AudioFormat value.
constexpr Uint16	SDL::AudioFormat::GetBitSize () const
	Retrieve the size, in bits, from an AudioFormat.
constexpr Uint16	SDL::AudioFormat::GetByteSize () const
	Retrieve the size, in bytes, from an AudioFormat.
constexpr bool	SDL::AudioFormat::IsFloat () const
	Determine if an AudioFormat represents floating point data.
constexpr bool	SDL::AudioFormat::IsBigEndian () const
	Determine if an AudioFormat represents bigendian data.
constexpr bool	SDL::AudioFormat::IsLittleEndian () const
	Determine if an AudioFormat represents littleendian data.
constexpr bool	SDL::AudioFormat::IsSigned () const
	Determine if an AudioFormat represents signed data.
constexpr bool	SDL::AudioFormat::IsInt () const
	Determine if an AudioFormat represents integer data.
constexpr bool	SDL::AudioFormat::IsUnsigned () const
	Determine if an AudioFormat represents unsigned data.
const char *	SDL::AudioDeviceBase::GetName () const
	Get the human-readable name of a specific audio device.
AudioSpec	SDL::AudioDeviceBase::GetFormat (int *sample_frames=nullptr) const
	Get the current audio format of a specific audio device.
OwnArray< int >	SDL::AudioDeviceBase::GetChannelMap () const
	Get the current channel map of an audio device.
	SDL::AudioDevice::AudioDevice (AudioDeviceRef devid, OptionalRef< const AudioSpec > spec)
	Open a specific audio device.
bool	SDL::AudioDeviceBase::IsPhysical () const
	Determine if an audio device is physical (instead of logical).
bool	SDL::AudioDeviceBase::IsPlayback () const
	Determine if an audio device is a playback device (instead of recording).
void	SDL::AudioDeviceBase::Pause ()
	Use this function to pause audio playback on a specified device.
void	SDL::AudioDeviceBase::Resume ()
	Use this function to unpause audio playback on a specified device.
bool	SDL::AudioDeviceBase::Paused () const
	Use this function to query if an audio device is paused.
float	SDL::AudioDeviceBase::GetGain () const
	Get the gain of an audio device.
void	SDL::AudioDeviceBase::SetGain (float gain)
	Change the gain of an audio device.
void	SDL::AudioDeviceBase::Close ()
	Close a previously-opened audio device.
void	SDL::AudioDeviceBase::BindAudioStreams (std::span< AudioStreamRef > streams)
	Bind a list of audio streams to an audio device.
void	SDL::AudioDeviceBase::BindAudioStream (AudioStreamRef stream)
	Bind a single audio stream to an audio device.
void	SDL::AudioStreamBase::Unbind ()
	Unbind a single audio stream from its audio device.
AudioDeviceRef	SDL::AudioStreamBase::GetDevice () const
	Query an audio stream for its currently-bound device.
	SDL::AudioStream::AudioStream (OptionalRef< const AudioSpec > src_spec, OptionalRef< const AudioSpec > dst_spec)
	Create a new audio stream.
	SDL::AudioStream::AudioStream (AudioDeviceRef devid, OptionalRef< const AudioSpec > spec=std::nullopt, AudioStreamCallback callback=nullptr, void *userdata=nullptr)
	Convenience function for straightforward audio init for the common case.
	SDL::AudioStream::AudioStream (AudioDeviceRef devid, OptionalRef< const AudioSpec > spec, AudioStreamCB callback)
	Convenience function for straightforward audio init for the common case.
PropertiesRef	SDL::AudioStreamBase::GetProperties () const
	Get the properties associated with an audio stream.
void	SDL::AudioStreamBase::GetFormat (AudioSpec src_spec, AudioSpec dst_spec) const
	Query the current format of an audio stream.
void	SDL::AudioStreamBase::SetFormat (OptionalRef< const AudioSpec > src_spec, OptionalRef< const AudioSpec > dst_spec)
	Change the input and output formats of an audio stream.
float	SDL::AudioStreamBase::GetFrequencyRatio () const
	Get the frequency ratio of an audio stream.
void	SDL::AudioStreamBase::SetFrequencyRatio (float ratio)
	Change the frequency ratio of an audio stream.
float	SDL::AudioStreamBase::GetGain () const
	Get the gain of an audio stream.
void	SDL::AudioStreamBase::SetGain (float gain)
	Change the gain of an audio stream.
OwnArray< int >	SDL::AudioStreamBase::GetInputChannelMap () const
	Get the current input channel map of an audio stream.
OwnArray< int >	SDL::AudioStreamBase::GetOutputChannelMap () const
	Get the current output channel map of an audio stream.
void	SDL::AudioStreamBase::SetInputChannelMap (std::span< int > chmap)
	Set the current input channel map of an audio stream.
void	SDL::AudioStreamBase::SetOutputChannelMap (std::span< int > chmap)
	Set the current output channel map of an audio stream.
void	SDL::AudioStreamBase::PutData (SourceBytes buf)
	Add data to the stream.
void	SDL::AudioStreamBase::PutDataNoCopy (SourceBytes buf, AudioStreamDataCompleteCallback callback, void *userdata)
	Add external data to an audio stream without copying it.
void	SDL::AudioStreamBase::PutDataNoCopy (SourceBytes buf, AudioStreamDataCompleteCB callback)
	Add external data to an audio stream without copying it.
void	SDL::AudioStreamBase::PutPlanarData (const void const channel_buffers, int num_channels, int num_samples)
	Add data to the stream with each channel in a separate array.
int	SDL::AudioStreamBase::GetData (TargetBytes buf)
	Get converted/resampled data from the stream.
int	SDL::AudioStreamBase::GetAvailable () const
	Get the number of converted/resampled bytes available.
int	SDL::AudioStreamBase::GetQueued () const
	Get the number of bytes currently queued.
void	SDL::AudioStreamBase::Flush ()
	Tell the stream that you're done sending data, and anything being buffered should be converted/resampled and made available immediately.
void	SDL::AudioStreamBase::Clear ()
	Clear any pending data in the stream.
void	SDL::AudioStreamBase::PauseDevice ()
	Use this function to pause audio playback on the audio device associated with an audio stream.
void	SDL::AudioStreamBase::ResumeDevice ()
	Use this function to unpause audio playback on the audio device associated with an audio stream.
bool	SDL::AudioStreamBase::DevicePaused () const
	Use this function to query if an audio device associated with a stream is paused.
AudioStreamLock	SDL::AudioStreamBase::Lock ()
	Lock an audio stream for serialized access.
	SDL::AudioStreamLock::AudioStreamLock (AudioStreamRef resource)
	Lock an audio stream for serialized access.
void	SDL::AudioStreamBase::Unlock (AudioStreamLock &&lock)
	Unlock an audio stream for serialized access.
void	SDL::AudioStreamLock::reset ()
	Unlock an audio stream for serialized access.
void	SDL::AudioStreamBase::SetGetCallback (AudioStreamCallback callback, void *userdata)
	Set a callback that runs when data is requested from an audio stream.
void	SDL::AudioStreamBase::SetGetCallback (AudioStreamCB callback)
	Set a callback that runs when data is requested from an audio stream.
void	SDL::AudioStreamBase::SetPutCallback (AudioStreamCallback callback, void *userdata)
	Set a callback that runs when data is added to an audio stream.
void	SDL::AudioStreamBase::SetPutCallback (AudioStreamCB callback)
	Set a callback that runs when data is added to an audio stream.
void	SDL::AudioStreamBase::Destroy ()
	Free an audio stream.
AudioStream	SDL::AudioDeviceBase::OpenStream (OptionalRef< const AudioSpec > spec, AudioStreamCallback callback, void *userdata)
	Convenience function for straightforward audio init for the common case.
AudioStream	SDL::AudioDeviceBase::OpenStream (OptionalRef< const AudioSpec > spec, AudioStreamCB callback)
	Convenience function for straightforward audio init for the common case.
void	SDL::AudioDeviceBase::SetPostmixCallback (AudioPostmixCallback callback, void *userdata)
	Set a callback that fires when data is about to be fed to an audio device.
void	SDL::AudioDeviceBase::SetPostmixCallback (AudioPostmixCB callback)
	Set a callback that fires when data is about to be fed to an audio device.
const char *	SDL::AudioFormat::GetName () const
	Get the human readable name of an audio format.
int	SDL::AudioFormat::GetSilenceValue () const
	Get the appropriate memset value for silencing an audio format.

Variables
constexpr Uint32	SDL::AUDIO_MASK_BITSIZE = SDL_AUDIO_MASK_BITSIZE
	Mask of bits in an AudioFormat that contains the format bit size.
constexpr Uint32	SDL::AUDIO_MASK_FLOAT = SDL_AUDIO_MASK_FLOAT
	Mask of bits in an AudioFormat that contain the floating point flag.
constexpr Uint32	SDL::AUDIO_MASK_BIG_ENDIAN = SDL_AUDIO_MASK_BIG_ENDIAN
	Mask of bits in an AudioFormat that contain the bigendian flag.
constexpr Uint32	SDL::AUDIO_MASK_SIGNED = SDL_AUDIO_MASK_SIGNED
	Mask of bits in an AudioFormat that contain the signed data flag.
constexpr AudioFormat	SDL::AUDIO_UNKNOWN
	Unspecified audio format.
constexpr AudioFormat	SDL::AUDIO_U8 = SDL_AUDIO_U8
	Unsigned 8-bit samples.
constexpr AudioFormat	SDL::AUDIO_S8 = SDL_AUDIO_S8
	Signed 8-bit samples.
constexpr AudioFormat	SDL::AUDIO_S16LE = SDL_AUDIO_S16LE
	Signed 16-bit samples.
constexpr AudioFormat	SDL::AUDIO_S16BE
	As above, but big-endian byte order.
constexpr AudioFormat	SDL::AUDIO_S32LE = SDL_AUDIO_S32LE
	32-bit integer samples
constexpr AudioFormat	SDL::AUDIO_S32BE
	As above, but big-endian byte order.
constexpr AudioFormat	SDL::AUDIO_F32LE
	32-bit floating point samples
constexpr AudioFormat	SDL::AUDIO_F32BE
	As above, but big-endian byte order.
constexpr AudioFormat	SDL::AUDIO_S16 = SDL_AUDIO_S16
	AUDIO_S16.
constexpr AudioFormat	SDL::AUDIO_S32 = SDL_AUDIO_S32
	AUDIO_S32.
constexpr AudioFormat	SDL::AUDIO_F32 = SDL_AUDIO_F32
	AUDIO_F32.
constexpr AudioDeviceID	SDL::AUDIO_DEVICE_DEFAULT_PLAYBACK
	A value used to request a default playback audio device.
constexpr AudioDeviceID	SDL::AUDIO_DEVICE_DEFAULT_RECORDING
	A value used to request a default recording audio device.

Detailed Description

Audio functionality for the SDL library.

All audio in SDL3 revolves around 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 LoadWAV (and 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 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 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.

AudioStream can also be provided channel maps to change this ordering to whatever is necessary, in other audio processing scenarios.

Typedef Documentation

◆ AudioDeviceRef

using SDL::AudioDeviceRef = ResourceRefT<AudioDeviceBase>

Reference for AudioDevice.

This does not take ownership!

◆ AudioPostmixCallback

using SDL::AudioPostmixCallback

Initial value:

void(SDLCALL*)(void* userdata,
                                           const AudioSpec* spec,
                                           float* buffer,
                                           int buflen)

A callback that fires when data is about to be fed to an audio device.

This is useful for accessing the final mix, perhaps for writing a visualizer or applying a final effect to the audio data before playback.

This callback should run as quickly as possible and not block for any significant time, as this callback delays submission of data to the audio device, which can cause audio playback problems.

The postmix callback must be able to handle any audio data format specified in spec, which can change between callbacks if the audio device changed. However, this only covers frequency and channel count; data is always provided here in AUDIO_F32 format.

The postmix callback runs after logical device gain and audiostream gain have been applied, which is to say you can make the output data louder at this point than the gain settings would suggest.

Parameters

userdata	a pointer provided by the app through SetAudioPostmixCallback, for its own use.
spec	the current format of audio that is to be submitted to the audio device.
buffer	the buffer of audio samples to be submitted. The callback can inspect and/or modify this data.
buflen	the size of buffer in bytes.

Thread safety:: This will run from a background thread owned by SDL. The application is responsible for locking resources the callback touches that need to be protected.

Since: This datatype is available since SDL 3.2.0.

See also: SetAudioPostmixCallback

◆ AudioPostmixCB

using SDL::AudioPostmixCB

Initial value:

MakeFrontCallback<void(const AudioSpec* spec, float* buffer, int buflen)>

SDL::MakeFrontCallback

Definition SDL3pp_callbackWrapper.h:169

A callback that fires when data is about to be fed to an audio device.

This is useful for accessing the final mix, perhaps for writing a visualizer or applying a final effect to the audio data before playback.

This callback should run as quickly as possible and not block for any significant time, as this callback delays submission of data to the audio device, which can cause audio playback problems.

The postmix callback must be able to handle any audio data format specified in spec, which can change between callbacks if the audio device changed. However, this only covers frequency and channel count; data is always provided here in AUDIO_F32 format.

The postmix callback runs after logical device gain and audiostream gain have been applied, which is to say you can make the output data louder at this point than the gain settings would suggest.

Parameters

spec	the current format of audio that is to be submitted to the audio device.
buffer	the buffer of audio samples to be submitted. The callback can inspect and/or modify this data.

Thread safety:: This will run from a background thread owned by SDL. The application is responsible for locking resources the callback touches that need to be protected.

Since: This datatype is available since SDL 3.2.0.

See also: SetAudioPostmixCallback; AudioPostmixCallback

◆ AudioSpec

using SDL::AudioSpec = SDL_AudioSpec

Format specifier for audio data.

Since: This struct is available since SDL 3.2.0.

See also: AudioFormat

◆ AudioStreamCallback

using SDL::AudioStreamCallback

Initial value:

void(SDLCALL*)(void* userdata,
                                          AudioStreamRaw stream,
                                          int additional_amount,
                                          int total_amount)

A callback that fires when data passes through an AudioStream.

Apps can (optionally) register a callback with an audio stream that is called when data is added with PutAudioStreamData, or requested with GetAudioStreamData.

Two values are offered here: one is the amount of additional data needed to satisfy the immediate request (which might be zero if the stream already has enough data queued) and the other is the total amount being requested. In a Get call triggering a Put callback, these values can be different. In a Put call triggering a Get callback, these values are always the same.

Byte counts might be slightly overestimated due to buffering or resampling, and may change from call to call.

This callback is not required to do anything. Generally this is useful for adding/reading data on demand, and the app will often put/get data as appropriate, but the system goes on with the data currently available to it if this callback does nothing.

Parameters

stream	the SDL audio stream associated with this callback.
additional_amount	the amount of data, in bytes, that is needed right now.
total_amount	the total amount of data requested, in bytes, that is requested or available.
userdata	an opaque pointer provided by the app for their personal use.

Thread safety:: This callbacks may run from any thread, so if you need to protect shared data, you should use LockAudioStream to serialize access; this lock will be held before your callback is called, so your callback does not need to manage the lock explicitly.

Since: This datatype is available since SDL 3.2.0.

See also: SetAudioStreamGetCallback; SetAudioStreamPutCallback

◆ AudioStreamCB

using SDL::AudioStreamCB

Initial value:

MakeFrontCallback<

void(AudioStreamRaw stream, int additional_amount, int total_amount)>

A callback that fires when data passes through an AudioStream.

Apps can (optionally) register a callback with an audio stream that is called when data is added with PutAudioStreamData, or requested with GetAudioStreamData.

Two values are offered here: one is the amount of additional data needed to satisfy the immediate request (which might be zero if the stream already has enough data queued) and the other is the total amount being requested. In a Get call triggering a Put callback, these values can be different. In a Put call triggering a Get callback, these values are always the same.

Byte counts might be slightly overestimated due to buffering or resampling, and may change from call to call.

This callback is not required to do anything. Generally this is useful for adding/reading data on demand, and the app will often put/get data as appropriate, but the system goes on with the data currently available to it if this callback does nothing.

Parameters

stream	the SDL audio stream associated with this callback.
additional_amount	the amount of data, in bytes, that is needed right now.
total_amount	the total amount of data requested, in bytes, that is requested or available.

Thread safety:: This callbacks may run from any thread, so if you need to protect shared data, you should use LockAudioStream to serialize access; this lock will be held before your callback is called, so your callback does not need to manage the lock explicitly.

Since: This datatype is available since SDL 3.2.0.

See also: SetAudioStreamGetCallback; SetAudioStreamPutCallback; AudioStreamCallback

◆ AudioStreamDataCompleteCallback

using SDL::AudioStreamDataCompleteCallback

Initial value:

void(SDLCALL*)(void* userdata,
                                                      const void* buf,
                                                      int buflen)

A callback that fires for completed PutAudioStreamDataNoCopy() data.

When using PutAudioStreamDataNoCopy() to provide data to an AudioStream, it's not safe to dispose of the data until the stream has completely consumed it. Often times it's difficult to know exactly when this has happened.

This callback fires once when the stream no longer needs the buffer, allowing the app to easily free or reuse it.

Parameters

userdata	an opaque pointer provided by the app for their personal use.
buf	the pointer provided to PutAudioStreamDataNoCopy().
buflen	the size of buffer, in bytes, provided to PutAudioStreamDataNoCopy().

Thread safety:: This callbacks may run from any thread, so if you need to protect shared data, you should use LockAudioStream to serialize access; this lock will be held before your callback is called, so your callback does not need to manage the lock explicitly.

Since: This datatype is available since SDL 3.4.0.

See also: SetAudioStreamGetCallback; SetAudioStreamPutCallback

◆ AudioStreamDataCompleteCB

using SDL::AudioStreamDataCompleteCB

Initial value:

std::function<void(const void* buf, int buflen)>

A callback that fires for completed PutAudioStreamDataNoCopy() data.

When using PutAudioStreamDataNoCopy() to provide data to an AudioStream, it's not safe to dispose of the data until the stream has completely consumed it. Often times it's difficult to know exactly when this has happened.

This callback fires once when the stream no longer needs the buffer, allowing the app to easily free or reuse it.

Parameters

buf	the pointer provided to PutAudioStreamDataNoCopy().
buflen	the size of buffer, in bytes, provided to PutAudioStreamDataNoCopy().

Thread safety:: This callbacks may run from any thread, so if you need to protect shared data, you should use LockAudioStream to serialize access; this lock will be held before your callback is called, so your callback does not need to manage the lock explicitly.

Since: This datatype is available since SDL 3.4.0.

See also: SetAudioStreamGetCallback; SetAudioStreamPutCallback; AudioStreamDataCompleteCallback

◆ AudioStreamRef

using SDL::AudioStreamRef = ResourceRefT<AudioStreamBase>

Reference for AudioStream.

This does not take ownership!

Function Documentation

◆ AudioBitSize()

Uint16 SDL::AudioBitSize ( AudioFormatRaw x )

constexpr

Retrieve the size, in bits, from an AudioFormat.

For example, AudioBitSize(AUDIO_S16) returns 16.

Parameters

x	an AudioFormat value.

Returns: data size in bits.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ AudioByteSize()

Uint16 SDL::AudioByteSize ( AudioFormatRaw x )

constexpr

Retrieve the size, in bytes, from an AudioFormat.

For example, AudioByteSize(AUDIO_S16) returns 2.

Parameters

x	an AudioFormat value.

Returns: data size in bytes.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ AudioDevice()

SDL::AudioDevice::AudioDevice	(	AudioDeviceRef	devid,
		OptionalRef< const AudioSpec >	spec )

inline

Open a specific audio device.

You can open both playback and recording devices through this function. 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. To start audio playing, bind a stream and supply audio data to it. Unlike SDL2, there is no audio callback; you only bind audio streams and make sure they have data flowing into them (however, you can simulate SDL2's semantics fairly closely by using OpenAudioDeviceStream instead of this function).

If you don't care about opening a specific device, pass a devid of either AUDIO_DEVICE_DEFAULT_PLAYBACK or 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 (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.

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. GetAudioDeviceFormat can tell you the preferred format for the device before opening and the actual format the device is using after opening.

It's legal to open the same device ID more than once; each successful open will generate a new logical AudioDevice 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.

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.

This function returns the opened device ID on success. This is a new, unique AudioDevice that represents a logical device.

Some backends might offer arbitrary devices (for example, a networked audio protocol that can connect to an arbitrary server). For these, as 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.

When done with an audio device, possibly at the end of the app's life, one should call CloseAudioDevice() on the returned device id.

Parameters

devid	the device instance id to open, or AUDIO_DEVICE_DEFAULT_PLAYBACK or AUDIO_DEVICE_DEFAULT_RECORDING for the most reasonable default device.
spec	the requested device configuration. Can be nullptr to use reasonable defaults.

Postcondition: the device ID on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: CloseAudioDevice; GetAudioDeviceFormat

◆ AudioDevicePaused()

bool SDL::AudioDevicePaused ( AudioDeviceRef devid )

inline

Use this function to query if an audio device is paused.

Unlike in SDL2, audio devices start in an unpaused state, since an app has to bind a stream before any audio will flow.

Physical devices can not be paused or unpaused, only logical devices created through OpenAudioDevice() can be. Physical and invalid device IDs will report themselves as unpaused here.

Parameters

devid a device opened by OpenAudioDevice().

Returns: true if device is valid and paused, false otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PauseAudioDevice; ResumeAudioDevice

◆ AudioFormat()

SDL::AudioFormat::AudioFormat	(	bool	sign,
		bool	bigendian,
		bool	flt,
		Uint16	size )

constexpr

Define an AudioFormat value.

SDL does not support custom audio formats, so this macro is not of much use externally, but it can be illustrative as to what the various bits of an AudioFormat mean.

For example, AUDIO_S32LE looks like this:

AudioFormat format(1, 0, 0, 32)

SDL::AudioFormat::AudioFormat

constexpr AudioFormat(AudioFormatRaw audioFormat={}) noexcept

Wraps AudioFormat.

Definition SDL3pp_audio.h:227

Parameters

sign	1 for signed data, 0 for unsigned data.
bigendian	1 for bigendian data, 0 for littleendian data.
flt	1 for floating point data, 0 for integer data.
size	number of bits per sample.

Postcondition: a format value in the style of AudioFormat.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ AudioFrameSize()

int SDL::AudioFrameSize ( const AudioSpec & x )

constexpr

Calculate the size of each audio frame (in bytes) from an AudioSpec.

This reports on the size of an audio sample frame: stereo Sint16 data (2 channels of 2 bytes each) would be 4 bytes per frame, for example.

Parameters

x	an AudioSpec to query.

Returns: the number of bytes used per sample frame.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ AudioStream() [1/3]

SDL::AudioStream::AudioStream	(	AudioDeviceRef	devid,
		OptionalRef< const AudioSpec >	spec,
		AudioStreamCB	callback )

inline

Convenience function for straightforward audio init for the common case.

If all your app intends to do is provide a single source of PCM audio, this function allows you to do all your audio setup in a single call.

This is also intended to be a clean means to migrate apps from SDL2.

This function will open an audio device, create a stream and bind it. Unlike other methods of setup, the audio device will be closed when this stream is destroyed, so the app can treat the returned AudioStream as the only object needed to manage audio playback.

Also unlike other functions, the audio device begins paused. This is to map more closely to SDL2-style behavior, since there is no extra step here to bind a stream to begin audio flowing. The audio device should be resumed with AudioStream.ResumeDevice();

This function works with both playback and recording devices.

The spec parameter represents the app's side of the audio stream. That is, for recording audio, this will be the output format, and for playing audio, this will be the input format. If spec is nullptr, the system will choose the format, and the app can use AudioStream.GetFormat() to obtain this information later.

If you don't care about opening a specific audio device, you can (and probably should), use AUDIO_DEVICE_DEFAULT_PLAYBACK for playback and AUDIO_DEVICE_DEFAULT_RECORDING for recording.

One can optionally provide a callback function; if nullptr, the app is expected to queue audio data for playback (or unqueue audio data if capturing). Otherwise, the callback will begin to fire once the device is unpaused.

Destroying the returned stream with AudioStream.Destroy will also close the audio device associated with this stream.

Parameters

devid	an audio device to open, or AUDIO_DEVICE_DEFAULT_PLAYBACK or AUDIO_DEVICE_DEFAULT_RECORDING.
spec	the audio stream's data format. Can be nullptr.
callback	a callback where the app will provide new data for playback, or receive new data for recording.

Postcondition: an audio stream on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetAudioStreamDevice; ResumeAudioStreamDevice

◆ AudioStream() [2/3]

SDL::AudioStream::AudioStream	(	AudioDeviceRef	devid,
		OptionalRef< const AudioSpec >	spec = std::nullopt,
		AudioStreamCallback	callback = nullptr,
		void *	userdata = nullptr )

inline

Convenience function for straightforward audio init for the common case.

If all your app intends to do is provide a single source of PCM audio, this function allows you to do all your audio setup in a single call.

This is also intended to be a clean means to migrate apps from SDL2.

This function will open an audio device, create a stream and bind it. Unlike other methods of setup, the audio device will be closed when this stream is destroyed, so the app can treat the returned AudioStream as the only object needed to manage audio playback.

Also unlike other functions, the audio device begins paused. This is to map more closely to SDL2-style behavior, since there is no extra step here to bind a stream to begin audio flowing. The audio device should be resumed with ResumeAudioStreamDevice().

This function works with both playback and recording devices.

The spec parameter represents the app's side of the audio stream. That is, for recording audio, this will be the output format, and for playing audio, this will be the input format. If spec is nullptr, the system will choose the format, and the app can use GetAudioStreamFormat() to obtain this information later.

If you don't care about opening a specific audio device, you can (and probably should), use AUDIO_DEVICE_DEFAULT_PLAYBACK for playback and AUDIO_DEVICE_DEFAULT_RECORDING for recording.

One can optionally provide a callback function; if nullptr, the app is expected to queue audio data for playback (or unqueue audio data if capturing). Otherwise, the callback will begin to fire once the device is unpaused.

Destroying the returned stream with DestroyAudioStream will also close the audio device associated with this stream.

Parameters

devid	an audio device to open, or AUDIO_DEVICE_DEFAULT_PLAYBACK or AUDIO_DEVICE_DEFAULT_RECORDING.
spec	the audio stream's data format. Can be nullptr.
callback	a callback where the app will provide new data for playback, or receive new data for recording. Can be nullptr, in which case the app will need to call PutAudioStreamData or GetAudioStreamData as necessary.
userdata	app-controlled pointer passed to callback. Can be nullptr. Ignored if callback is nullptr.

Postcondition: an audio stream on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetAudioStreamDevice; ResumeAudioStreamDevice

◆ AudioStream() [3/3]

SDL::AudioStream::AudioStream	(	OptionalRef< const AudioSpec >	src_spec,
		OptionalRef< const AudioSpec >	dst_spec )

inline

Create a new audio stream.

Parameters

src_spec	the format details of the input audio.
dst_spec	the format details of the output audio.

Postcondition: a new audio stream on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PutAudioStreamData; GetAudioStreamData; GetAudioStreamAvailable; FlushAudioStream; ClearAudioStream; SetAudioStreamFormat; DestroyAudioStream

◆ AudioStreamDevicePaused()

bool SDL::AudioStreamDevicePaused ( AudioStreamRef stream )

inline

Use this function to query if an audio device associated with a stream is paused.

Unlike in SDL2, audio devices start in an unpaused state, since an app has to bind a stream before any audio will flow.

Parameters

stream the audio stream associated with the audio device to query.

Returns: true if device is valid and paused, false otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PauseAudioStreamDevice; ResumeAudioStreamDevice

◆ AudioStreamLock()

SDL::AudioStreamLock::AudioStreamLock ( AudioStreamRef resource )

inline

Lock an audio stream for serialized access.

Each AudioStream has an internal mutex it uses to protect its data structures from threading conflicts. This function allows an app to lock that mutex, which could be useful if registering callbacks on this stream.

One does not need to lock a stream to use in it most cases, as the stream manages this lock internally. However, this lock is held during callbacks, which may run from arbitrary threads at any time, so if an app needs to protect shared data during those callbacks, locking the stream guarantees that the callback is not running while the lock is held.

As this is just a wrapper over LockMutex for an internal lock; it has all the same attributes (recursive locks are allowed, etc).

Parameters

resource the audio stream to lock.

Postcondition: true on success or false on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: UnlockAudioStream

◆ BindAudioStream() [1/2]

void SDL::AudioDeviceBase::BindAudioStream ( AudioStreamRef stream )

inline

Bind a single audio stream to an audio device.

This is a convenience function, equivalent to calling BindAudioStreams(devid, &stream, 1).

Parameters

stream an audio stream to bind to a device.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: BindAudioStreams; UnbindAudioStream; GetAudioStreamDevice

◆ BindAudioStream() [2/2]

void SDL::BindAudioStream	(	AudioDeviceRef	devid,
		AudioStreamRef	stream )

inline

Bind a single audio stream to an audio device.

This is a convenience function, equivalent to calling BindAudioStreams(devid, &stream, 1).

Parameters

devid	an audio device to bind a stream to.
stream	an audio stream to bind to a device.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: BindAudioStreams; UnbindAudioStream; GetAudioStreamDevice

◆ BindAudioStreams() [1/2]

void SDL::AudioDeviceBase::BindAudioStreams ( std::span< AudioStreamRef > streams )

inline

Bind a list of audio streams to an audio device.

Audio data will flow through any bound streams. For a playback device, data for all bound streams will be mixed together and fed to the device. For a recording device, a copy of recorded data will be provided to each bound stream.

Audio streams can only be bound to an open device. This operation is atomic–all streams bound in the same call will start processing at the same time, so they can stay in sync. Also: either all streams will be bound or none of them will be.

It is an error to bind an already-bound stream; it must be explicitly unbound first.

Binding a stream to a device will set its output format for playback devices, and its input format for recording devices, so they match the device's settings. The caller is welcome to change the other end of the stream's format at any time with SetAudioStreamFormat(). If the other end of the stream's format has never been set (the audio stream was created with a nullptr audio spec), this function will set it to match the device end's format.

Parameters

streams an array of audio streams to bind.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: BindAudioStreams; UnbindAudioStream; GetAudioStreamDevice

◆ BindAudioStreams() [2/2]

void SDL::BindAudioStreams	(	AudioDeviceRef	devid,
		std::span< AudioStreamRef >	streams )

inline

Bind a list of audio streams to an audio device.

Audio data will flow through any bound streams. For a playback device, data for all bound streams will be mixed together and fed to the device. For a recording device, a copy of recorded data will be provided to each bound stream.

Audio streams can only be bound to an open device. This operation is atomic–all streams bound in the same call will start processing at the same time, so they can stay in sync. Also: either all streams will be bound or none of them will be.

It is an error to bind an already-bound stream; it must be explicitly unbound first.

Binding a stream to a device will set its output format for playback devices, and its input format for recording devices, so they match the device's settings. The caller is welcome to change the other end of the stream's format at any time with SetAudioStreamFormat(). If the other end of the stream's format has never been set (the audio stream was created with a nullptr audio spec), this function will set it to match the device end's format.

Parameters

devid	an audio device to bind a stream to.
streams	an array of audio streams to bind.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: BindAudioStreams; UnbindAudioStream; GetAudioStreamDevice

◆ Clear()

void SDL::AudioStreamBase::Clear ( )

inline

Clear any pending data in the stream.

This drops any queued data, so there will be nothing to read from the stream until more is added.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetAudioStreamAvailable; GetAudioStreamData; GetAudioStreamQueued; PutAudioStreamData

◆ ClearAudioStream()

void SDL::ClearAudioStream ( AudioStreamRef stream )

inline

Clear any pending data in the stream.

This drops any queued data, so there will be nothing to read from the stream until more is added.

Parameters

stream the audio stream to clear.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetAudioStreamAvailable; GetAudioStreamData; GetAudioStreamQueued; PutAudioStreamData

◆ Close()

void SDL::AudioDeviceBase::Close ( )

inline

Close a previously-opened audio device.

The application should close open audio devices once they are no longer needed.

This function may block briefly while pending audio data is played by the hardware, so that applications don't drop the last buffer of data they supplied if terminating immediately afterwards.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: OpenAudioDevice

◆ CloseAudioDevice()

void SDL::CloseAudioDevice ( AudioDeviceID devid )

inline

Close a previously-opened audio device.

The application should close open audio devices once they are no longer needed.

This function may block briefly while pending audio data is played by the hardware, so that applications don't drop the last buffer of data they supplied if terminating immediately afterwards.

Parameters

devid an audio device id previously returned by OpenAudioDevice().

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: OpenAudioDevice

◆ ConvertAudioSamples()

OwnArray< Uint8 > SDL::ConvertAudioSamples	(	const AudioSpec &	src_spec,
		SourceBytes	src_data,
		const AudioSpec &	dst_spec )

inline

Convert some audio data of one format to another format.

Please note that this function is for convenience, but should not be used to resample audio in blocks, as it will introduce audio artifacts on the boundaries. You should only use this function if you are converting audio data in its entirety in one call. If you want to convert audio in smaller chunks, use an AudioStream, which is designed for this situation.

Internally, this function creates and destroys an AudioStream on each use, so it's also less efficient than using one directly, if you need to convert multiple times.

Parameters

src_spec	the format details of the input audio.
src_data	the audio data to be converted.
dst_spec	the format details of the output audio.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ CreateAudioStream()

AudioStream SDL::CreateAudioStream	(	OptionalRef< const AudioSpec >	src_spec,
		OptionalRef< const AudioSpec >	dst_spec )

inline

Create a new audio stream.

Parameters

src_spec	the format details of the input audio.
dst_spec	the format details of the output audio.

Returns: a new audio stream on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PutAudioStreamData; GetAudioStreamData; GetAudioStreamAvailable; FlushAudioStream; ClearAudioStream; SetAudioStreamFormat; DestroyAudioStream

◆ DefineAudioFormat()

AudioFormat SDL::DefineAudioFormat	(	bool	sign,
		bool	bigendian,
		bool	flt,
		Uint16	size )

constexpr

Define an AudioFormat value.

SDL does not support custom audio formats, so this macro is not of much use externally, but it can be illustrative as to what the various bits of an AudioFormat mean.

For example, AUDIO_S32LE looks like this:

DefineAudioFormat(1, 0, 0, 32)

SDL::DefineAudioFormat

constexpr AudioFormat DefineAudioFormat(bool sign, bool bigendian, bool flt, Uint16 size)

Define an AudioFormat value.

Definition SDL3pp_audio.h:454

Parameters

sign	1 for signed data, 0 for unsigned data.
bigendian	1 for bigendian data, 0 for littleendian data.
flt	1 for floating point data, 0 for integer data.
size	number of bits per sample.

Returns: a format value in the style of AudioFormat.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ Destroy()

void SDL::AudioStreamBase::Destroy ( )

inline

Free an audio stream.

This will release all allocated data, including any audio that is still queued. You do not need to manually clear the stream first.

If this stream was bound to an audio device, it is unbound during this call. If this stream was created with OpenAudioDeviceStream, the audio device that was opened alongside this stream's creation will be closed, too.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: CreateAudioStream

◆ DestroyAudioStream()

void SDL::DestroyAudioStream ( AudioStreamRaw stream )

inline

Free an audio stream.

This will release all allocated data, including any audio that is still queued. You do not need to manually clear the stream first.

If this stream was bound to an audio device, it is unbound during this call. If this stream was created with OpenAudioDeviceStream, the audio device that was opened alongside this stream's creation will be closed, too.

Parameters

stream the audio stream to destroy.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: CreateAudioStream

◆ DevicePaused()

bool SDL::AudioStreamBase::DevicePaused ( ) const

inline

Use this function to query if an audio device associated with a stream is paused.

Unlike in SDL2, audio devices start in an unpaused state, since an app has to bind a stream before any audio will flow.

Returns: true if device is valid and paused, false otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PauseAudioStreamDevice; ResumeAudioStreamDevice

◆ Flush()

void SDL::AudioStreamBase::Flush ( )

inline

Tell the stream that you're done sending data, and anything being buffered should be converted/resampled and made available immediately.

It is legal to add more data to a stream after flushing, but there may be audio gaps in the output. Generally this is intended to signal the end of input, so the complete output becomes available.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PutAudioStreamData

◆ FlushAudioStream()

void SDL::FlushAudioStream ( AudioStreamRef stream )

inline

Tell the stream that you're done sending data, and anything being buffered should be converted/resampled and made available immediately.

It is legal to add more data to a stream after flushing, but there may be audio gaps in the output. Generally this is intended to signal the end of input, so the complete output becomes available.

Parameters

stream the audio stream to flush.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PutAudioStreamData

◆ GetAudioDeviceChannelMap()

OwnArray< int > SDL::GetAudioDeviceChannelMap ( AudioDeviceRef devid )

inline

Get the current channel map of an audio device.

Channel maps are optional; most things do not need them, instead passing data in the order that SDL expectsorder that SDL expects.

Audio devices usually have no remapping applied. This is represented by returning nullptr, and does not signify an error.

Parameters

devid the instance ID of the device to query.

Returns: an array of the current channel mapping, with as many elements as the current output spec's channels, or nullptr if default

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: SetAudioStreamInputChannelMap

◆ GetAudioDeviceFormat()

AudioSpec SDL::GetAudioDeviceFormat	(	AudioDeviceRef	devid,
		int *	sample_frames = nullptr )

inline

Get the current audio format of a specific audio device.

For an opened device, this will report the format the device is currently using. If the device isn't yet opened, this will report the device's preferred format (or a reasonable default if this can't be determined).

You may also specify AUDIO_DEVICE_DEFAULT_PLAYBACK or AUDIO_DEVICE_DEFAULT_RECORDING here, which is useful for getting a reasonable recommendation before opening the system-recommended default device.

You can also use this to request the current device buffer size. This is specified in sample frames and represents the amount of data SDL will feed to the physical hardware in each chunk. This can be converted to milliseconds of audio with the following equation:

ms = (int) ((((Sint64) frames) * 1000) / spec.freq);

Buffer size is only important if you need low-level control over the audio playback timing. Most apps do not need this.

Parameters

devid	the instance ID of the device to query.
sample_frames	pointer to store device buffer size, in sample frames. Can be nullptr.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetAudioDeviceGain()

float SDL::GetAudioDeviceGain ( AudioDeviceRef devid )

inline

Get the gain of an audio device.

The gain of a device is its volume; a larger gain means a louder output, with a gain of zero being silence.

Audio devices default to a gain of 1.0f (no change in output).

Physical devices may not have their gain changed, only logical devices, and this function will always return -1.0f when used on physical devices.

Parameters

devid the audio device to query.

Returns: the gain of the device or -1.0f on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: SetAudioDeviceGain

◆ GetAudioDeviceName()

const char * SDL::GetAudioDeviceName ( AudioDeviceRef devid )

inline

Get the human-readable name of a specific audio device.

WARNING: this function will work with AUDIO_DEVICE_DEFAULT_PLAYBACK and AUDIO_DEVICE_DEFAULT_RECORDING, returning the current default physical devices' names. However, as the default device may change at any time, it is likely better to show a generic name to the user, like "System default audio device" or perhaps "default [currently %s]". Do not store this name to disk to reidentify the device in a later run of the program, as the default might change in general, and the string will be the name of a specific device and not the abstract system default.

Parameters

devid the instance ID of the device to query.

Returns: the name of the audio device on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetAudioPlaybackDevices; GetAudioRecordingDevices

◆ GetAudioDriver()

const char * SDL::GetAudioDriver ( int index )

inline

Use this function to get the name of a built in audio driver.

The list of audio drivers is given in the order that they are normally initialized by default; the drivers that seem more reasonable to choose first (as far as the SDL developers believe) are earlier in the list.

The names of drivers are all simple, low-ASCII identifiers, like "alsa", "coreaudio" or "wasapi". These never have Unicode characters, and are not meant to be proper names.

Parameters

index the index of the audio driver; the value ranges from 0 to GetNumAudioDrivers() - 1.

Returns: the name of the audio driver at the requested index, or nullptr if an invalid index was specified.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetNumAudioDrivers

◆ GetAudioFormatName()

const char * SDL::GetAudioFormatName ( AudioFormatRaw format )

inline

Get the human readable name of an audio format.

Parameters

format the audio format to query.

Returns: the human readable name of the specified audio format or "AUDIO_UNKNOWN" if the format isn't recognized.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetAudioPlaybackDevices()

OwnArray< AudioDeviceRef > SDL::GetAudioPlaybackDevices ( )

inline

Get a list of currently-connected audio playback devices.

This returns of list of available devices that play sound, perhaps to speakers or headphones ("playback" devices). If you want devices that record audio, like a microphone ("recording" devices), use GetAudioRecordingDevices() instead.

This only returns a list of physical devices; it will not have any device IDs returned by OpenAudioDevice().

If this function returns nullptr, to signify an error, *count will be set to zero.

Returns: a 0 terminated array of device instance IDs on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: OpenAudioDevice; GetAudioRecordingDevices

◆ GetAudioRecordingDevices()

OwnArray< AudioDeviceRef > SDL::GetAudioRecordingDevices ( )

inline

Get a list of currently-connected audio recording devices.

This returns of list of available devices that record audio, like a microphone ("recording" devices). If you want devices that play sound, perhaps to speakers or headphones ("playback" devices), use GetAudioPlaybackDevices() instead.

This only returns a list of physical devices; it will not have any device IDs returned by OpenAudioDevice().

If this function returns nullptr, to signify an error, *count will be set to zero.

Returns: a 0 terminated array of device instance IDs on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: OpenAudioDevice; GetAudioPlaybackDevices

◆ GetAudioStreamAvailable()

int SDL::GetAudioStreamAvailable ( AudioStreamRef stream )

inline

Get the number of converted/resampled bytes available.

The stream may be buffering data behind the scenes until it has enough to resample correctly, so this number might be lower than what you expect, or even be zero. Add more data or flush the stream if you need the data now.

If the stream has so much data that it would overflow an int, the return value is clamped to a maximum value, but no queued data is lost; if there are gigabytes of data queued, the app might need to read some of it with GetAudioStreamData before this function's return value is no longer clamped.

Parameters

stream the audio stream to query.

Returns: the number of converted/resampled bytes available or -1 on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetAudioStreamData; PutAudioStreamData

◆ GetAudioStreamData()

int SDL::GetAudioStreamData	(	AudioStreamRef	stream,
		TargetBytes	buf )

inline

Get converted/resampled data from the stream.

The input/output data format/channels/samplerate is specified when creating the stream, and can be changed after creation by calling SetAudioStreamFormat.

Note that any conversion and resampling necessary is done during this call, and PutAudioStreamData simply queues unconverted data for later. This is different than SDL2, where that work was done while inputting new data to the stream and requesting the output just copied the converted data.

Parameters

stream	the stream the audio is being requested from.
buf	a buffer to fill with audio data.

Returns: the number of bytes read from the stream or -1 on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread, but if the stream has a callback set, the caller might need to manage extra locking.

Since: This function is available since SDL 3.2.0.

See also: ClearAudioStream; GetAudioStreamAvailable; PutAudioStreamData

◆ GetAudioStreamDevice()

AudioDeviceRef SDL::GetAudioStreamDevice ( AudioStreamRef stream )

inline

Query an audio stream for its currently-bound device.

This reports the logical audio device that an audio stream is currently bound to.

If not bound, or invalid, this returns zero, which is not a valid device ID.

Parameters

stream the audio stream to query.

Returns: the bound audio device, or 0 if not bound or invalid.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: BindAudioStream; BindAudioStreams

◆ GetAudioStreamFormat()

void SDL::GetAudioStreamFormat	(	AudioStreamRef	stream,
		AudioSpec *	src_spec,
		AudioSpec *	dst_spec )

inline

Query the current format of an audio stream.

Parameters

stream	the AudioStream to query.
src_spec	where to store the input audio format; ignored if nullptr.
dst_spec	where to store the output audio format; ignored if nullptr.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

See also: SetAudioStreamFormat

◆ GetAudioStreamFrequencyRatio()

float SDL::GetAudioStreamFrequencyRatio ( AudioStreamRef stream )

inline

Get the frequency ratio of an audio stream.

Parameters

stream the AudioStream to query.

Returns: the frequency ratio of the stream or 0.0 on failure; call GetError() for more information.

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

Since: This function is available since SDL 3.2.0.

See also: SetAudioStreamFrequencyRatio

◆ GetAudioStreamGain()

float SDL::GetAudioStreamGain ( AudioStreamRef stream )

inline

Get the gain of an audio stream.

The gain of a stream is its volume; a larger gain means a louder output, with a gain of zero being silence.

Audio streams default to a gain of 1.0f (no change in output).

Parameters

stream the AudioStream to query.

Returns: the gain of the stream or -1.0f on failure; call GetError() for more information.

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

Since: This function is available since SDL 3.2.0.

See also: SetAudioStreamGain

◆ GetAudioStreamInputChannelMap()

OwnArray< int > SDL::GetAudioStreamInputChannelMap ( AudioStreamRef stream )

inline

Get the current input channel map of an audio stream.

Channel maps are optional; most things do not need them, instead passing data in the order that SDL expectsorder that SDL expects.

Audio streams default to no remapping applied. This is represented by returning nullptr, and does not signify an error.

Parameters

stream the AudioStream to query.

Returns: an array of the current channel mapping, with as many elements as the current output spec's channels, or nullptr if default.

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

Since: This function is available since SDL 3.2.0.

See also: SetAudioStreamInputChannelMap

◆ GetAudioStreamOutputChannelMap()

OwnArray< int > SDL::GetAudioStreamOutputChannelMap ( AudioStreamRef stream )

inline

Get the current output channel map of an audio stream.

Channel maps are optional; most things do not need them, instead passing data in the order that SDL expectsorder that SDL expects.

Audio streams default to no remapping applied. This is represented by returning nullptr, and does not signify an error.

Parameters

stream the AudioStream to query.

Returns: an array of the current channel mapping, with as many elements as the current output spec's channels, or nullptr if default.

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

Since: This function is available since SDL 3.2.0.

See also: SetAudioStreamInputChannelMap

◆ GetAudioStreamProperties()

PropertiesRef SDL::GetAudioStreamProperties ( AudioStreamRef stream )

inline

Get the properties associated with an audio stream.

The application can hang any data it wants here, but the following properties are understood by SDL:

prop.AudioStream.AUTO_CLEANUP_BOOLEAN: if true (the default), the stream be automatically cleaned up when the audio subsystem quits. If set to false, the streams will persist beyond that. This property is ignored for streams created through OpenAudioDeviceStream(), and will always be cleaned up. Streams that are not cleaned up will still be unbound from devices when the audio subsystem quits. This property was added in SDL 3.4.0.

Parameters

stream the AudioStream to query.

Returns: a valid property ID on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetAudioStreamQueued()

int SDL::GetAudioStreamQueued ( AudioStreamRef stream )

inline

Get the number of bytes currently queued.

This is the number of bytes put into a stream as input, not the number that can be retrieved as output. Because of several details, it's not possible to calculate one number directly from the other. If you need to know how much usable data can be retrieved right now, you should use GetAudioStreamAvailable() and not this function.

Note that audio streams can change their input format at any time, even if there is still data queued in a different format, so the returned byte count will not necessarily match the number of sample frames available. Users of this API should be aware of format changes they make when feeding a stream and plan accordingly.

Queued data is not converted until it is consumed by GetAudioStreamData, so this value should be representative of the exact data that was put into the stream.

If the stream has so much data that it would overflow an int, the return value is clamped to a maximum value, but no queued data is lost; if there are gigabytes of data queued, the app might need to read some of it with GetAudioStreamData before this function's return value is no longer clamped.

Parameters

stream the audio stream to query.

Returns: the number of bytes queued or -1 on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PutAudioStreamData; ClearAudioStream

◆ GetAvailable()

int SDL::AudioStreamBase::GetAvailable ( ) const

inline

Get the number of converted/resampled bytes available.

The stream may be buffering data behind the scenes until it has enough to resample correctly, so this number might be lower than what you expect, or even be zero. Add more data or flush the stream if you need the data now.

If the stream has so much data that it would overflow an int, the return value is clamped to a maximum value, but no queued data is lost; if there are gigabytes of data queued, the app might need to read some of it with GetAudioStreamData before this function's return value is no longer clamped.

Returns: the number of converted/resampled bytes available or -1 on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetAudioStreamData; PutAudioStreamData

◆ GetBitSize()

Uint16 SDL::AudioFormat::GetBitSize ( ) const

constexpr

Retrieve the size, in bits, from an AudioFormat.

For example, AudioBitSize(AUDIO_S16) returns 16.

Returns: data size in bits.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetByteSize()

Uint16 SDL::AudioFormat::GetByteSize ( ) const

constexpr

Retrieve the size, in bytes, from an AudioFormat.

For example, AudioByteSize(AUDIO_S16) returns 2.

Returns: data size in bytes.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetChannelMap()

OwnArray< int > SDL::AudioDeviceBase::GetChannelMap ( ) const

inline

Get the current channel map of an audio device.

Channel maps are optional; most things do not need them, instead passing data in the order that SDL expectsorder that SDL expects.

Audio devices usually have no remapping applied. This is represented by returning nullptr, and does not signify an error.

Returns: an array of the current channel mapping, with as many elements as the current output spec's channels, or nullptr if default

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: SetAudioStreamInputChannelMap

◆ GetCurrentAudioDriver()

const char * SDL::GetCurrentAudioDriver ( )

inline

Get the name of the current audio driver.

The names of drivers are all simple, low-ASCII identifiers, like "alsa", "coreaudio" or "wasapi". These never have Unicode characters, and are not meant to be proper names.

Returns: the name of the current audio driver or nullptr if no driver has been initialized.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetData()

int SDL::AudioStreamBase::GetData ( TargetBytes buf )

inline

Get converted/resampled data from the stream.

The input/output data format/channels/samplerate is specified when creating the stream, and can be changed after creation by calling SetAudioStreamFormat.

Note that any conversion and resampling necessary is done during this call, and PutAudioStreamData simply queues unconverted data for later. This is different than SDL2, where that work was done while inputting new data to the stream and requesting the output just copied the converted data.

Parameters

buf	a buffer to fill with audio data.

Returns: the number of bytes read from the stream or -1 on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread, but if the stream has a callback set, the caller might need to manage extra locking.

Since: This function is available since SDL 3.2.0.

See also: ClearAudioStream; GetAudioStreamAvailable; PutAudioStreamData

◆ GetDevice()

AudioDeviceRef SDL::AudioStreamBase::GetDevice ( ) const

inline

Query an audio stream for its currently-bound device.

This reports the logical audio device that an audio stream is currently bound to.

If not bound, or invalid, this returns zero, which is not a valid device ID.

Returns: the bound audio device, or 0 if not bound or invalid.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: BindAudioStream; BindAudioStreams

◆ GetFormat() [1/2]

AudioSpec SDL::AudioDeviceBase::GetFormat ( int * sample_frames = nullptr ) const

inline

Get the current audio format of a specific audio device.

For an opened device, this will report the format the device is currently using. If the device isn't yet opened, this will report the device's preferred format (or a reasonable default if this can't be determined).

You may also specify AUDIO_DEVICE_DEFAULT_PLAYBACK or AUDIO_DEVICE_DEFAULT_RECORDING here, which is useful for getting a reasonable recommendation before opening the system-recommended default device.

You can also use this to request the current device buffer size. This is specified in sample frames and represents the amount of data SDL will feed to the physical hardware in each chunk. This can be converted to milliseconds of audio with the following equation:

ms = (int) ((((Sint64) frames) * 1000) / spec.freq);

Buffer size is only important if you need low-level control over the audio playback timing. Most apps do not need this.

Parameters

sample_frames pointer to store device buffer size, in sample frames. Can be nullptr.

Returns: the device format details on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetFormat() [2/2]

void SDL::AudioStreamBase::GetFormat	(	AudioSpec *	src_spec,
		AudioSpec *	dst_spec ) const

inline

Query the current format of an audio stream.

Parameters

src_spec	where to store the input audio format; ignored if nullptr.
dst_spec	where to store the output audio format; ignored if nullptr.

Exceptions

Error on failure.

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

Since: This function is available since SDL 3.2.0.

See also: SetAudioStreamFormat

◆ GetFrequencyRatio()

float SDL::AudioStreamBase::GetFrequencyRatio ( ) const

inline

Get the frequency ratio of an audio stream.

Returns: the frequency ratio of the stream or 0.0 on failure; call GetError() for more information.

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

Since: This function is available since SDL 3.2.0.

See also: SetAudioStreamFrequencyRatio

◆ GetGain() [1/2]

float SDL::AudioDeviceBase::GetGain ( ) const

inline

Get the gain of an audio device.

The gain of a device is its volume; a larger gain means a louder output, with a gain of zero being silence.

Audio devices default to a gain of 1.0f (no change in output).

Physical devices may not have their gain changed, only logical devices, and this function will always return -1.0f when used on physical devices.

Returns: the gain of the device or -1.0f on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: SetAudioDeviceGain

◆ GetGain() [2/2]

float SDL::AudioStreamBase::GetGain ( ) const

inline

Get the gain of an audio stream.

The gain of a stream is its volume; a larger gain means a louder output, with a gain of zero being silence.

Audio streams default to a gain of 1.0f (no change in output).

Returns: the gain of the stream or -1.0f on failure; call GetError() for more information.

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

Since: This function is available since SDL 3.2.0.

See also: SetAudioStreamGain

◆ GetInputChannelMap()

OwnArray< int > SDL::AudioStreamBase::GetInputChannelMap ( ) const

inline

Get the current input channel map of an audio stream.

Channel maps are optional; most things do not need them, instead passing data in the order that SDL expectsorder that SDL expects.

Audio streams default to no remapping applied. This is represented by returning nullptr, and does not signify an error.

Returns: an array of the current channel mapping, with as many elements as the current output spec's channels, or nullptr if default.

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

Since: This function is available since SDL 3.2.0.

See also: SetAudioStreamInputChannelMap

◆ GetName() [1/2]

const char * SDL::AudioDeviceBase::GetName ( ) const

inline

Get the human-readable name of a specific audio device.

WARNING: this function will work with AUDIO_DEVICE_DEFAULT_PLAYBACK and AUDIO_DEVICE_DEFAULT_RECORDING, returning the current default physical devices' names. However, as the default device may change at any time, it is likely better to show a generic name to the user, like "System default audio device" or perhaps "default [currently %s]". Do not store this name to disk to reidentify the device in a later run of the program, as the default might change in general, and the string will be the name of a specific device and not the abstract system default.

Returns: the name of the audio device on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetAudioPlaybackDevices; GetAudioRecordingDevices

◆ GetName() [2/2]

const char * SDL::AudioFormat::GetName ( ) const

inline

Get the human readable name of an audio format.

Returns: the human readable name of the specified audio format or "AUDIO_UNKNOWN" if the format isn't recognized.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetNumAudioDrivers()

int SDL::GetNumAudioDrivers ( )

inline

Use this function to get the number of built-in audio drivers.

This function returns a hardcoded number. This never returns a negative value; if there are no drivers compiled into this build of SDL, this function returns zero. The presence of a driver in this list does not mean it will function, it just means SDL is capable of interacting with that interface. For example, a build of SDL might have esound support, but if there's no esound server available, SDL's esound driver would fail if used.

By default, SDL tries all drivers, in its preferred order, until one is found to be usable.

Returns: the number of built-in audio drivers.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: GetAudioDriver

◆ GetOutputChannelMap()

OwnArray< int > SDL::AudioStreamBase::GetOutputChannelMap ( ) const

inline

Get the current output channel map of an audio stream.

Channel maps are optional; most things do not need them, instead passing data in the order that SDL expectsorder that SDL expects.

Audio streams default to no remapping applied. This is represented by returning nullptr, and does not signify an error.

Returns: an array of the current channel mapping, with as many elements as the current output spec's channels, or nullptr if default.

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

Since: This function is available since SDL 3.2.0.

See also: SetAudioStreamInputChannelMap

◆ GetProperties()

PropertiesRef SDL::AudioStreamBase::GetProperties ( ) const

inline

Get the properties associated with an audio stream.

The application can hang any data it wants here, but the following properties are understood by SDL:

prop.AudioStream.AUTO_CLEANUP_BOOLEAN: if true (the default), the stream be automatically cleaned up when the audio subsystem quits. If set to false, the streams will persist beyond that. This property is ignored for streams created through OpenAudioDeviceStream(), and will always be cleaned up. Streams that are not cleaned up will still be unbound from devices when the audio subsystem quits. This property was added in SDL 3.4.0.

Returns: a valid property ID on success.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetQueued()

int SDL::AudioStreamBase::GetQueued ( ) const

inline

Get the number of bytes currently queued.

This is the number of bytes put into a stream as input, not the number that can be retrieved as output. Because of several details, it's not possible to calculate one number directly from the other. If you need to know how much usable data can be retrieved right now, you should use GetAudioStreamAvailable() and not this function.

Note that audio streams can change their input format at any time, even if there is still data queued in a different format, so the returned byte count will not necessarily match the number of sample frames available. Users of this API should be aware of format changes they make when feeding a stream and plan accordingly.

Queued data is not converted until it is consumed by GetAudioStreamData, so this value should be representative of the exact data that was put into the stream.

If the stream has so much data that it would overflow an int, the return value is clamped to a maximum value, but no queued data is lost; if there are gigabytes of data queued, the app might need to read some of it with GetAudioStreamData before this function's return value is no longer clamped.

Returns: the number of bytes queued or -1 on failure; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: PutAudioStreamData; ClearAudioStream

◆ GetSilenceValue()

int SDL::AudioFormat::GetSilenceValue ( ) const

inline

Get the appropriate memset value for silencing an audio format.

The value returned by this function can be used as the second argument to memset (or memset) to set an audio buffer in a specific format to silence.

Returns: a byte value that can be passed to memset.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ GetSilenceValueForFormat()

int SDL::GetSilenceValueForFormat ( AudioFormatRaw format )

inline

Get the appropriate memset value for silencing an audio format.

The value returned by this function can be used as the second argument to memset (or memset) to set an audio buffer in a specific format to silence.

Parameters

format the audio data format to query.

Returns: a byte value that can be passed to memset.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ IsAudioBigENDIAN()

bool SDL::IsAudioBigENDIAN ( AudioFormatRaw x )

constexpr

Determine if an AudioFormat represents bigendian data.

For example, IsAudioBigENDIAN(AUDIO_S16LE) returns 0.

Parameters

x	an AudioFormat value.

Returns: non-zero if format is bigendian, zero otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ IsAudioDevicePhysical()

bool SDL::IsAudioDevicePhysical ( AudioDeviceRef devid )

inline

Determine if an audio device is physical (instead of logical).

An AudioDevice that represents physical hardware is a physical device; there is one for each piece of hardware that SDL can see. Logical devices are created by calling OpenAudioDevice or OpenAudioDeviceStream, and while each is associated with a physical device, there can be any number of logical devices on one physical device.

For the most part, logical and physical IDs are interchangeable–if you try to open a logical device, SDL understands to assign that effort to the underlying physical device, etc. However, it might be useful to know if an arbitrary device ID is physical or logical. This function reports which.

This function may return either true or false for invalid device IDs.

Parameters

devid the device ID to query.

Returns: true if devid is a physical device, false if it is logical.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ IsAudioDevicePlayback()

bool SDL::IsAudioDevicePlayback ( AudioDeviceRef devid )

inline

Determine if an audio device is a playback device (instead of recording).

This function may return either true or false for invalid device IDs.

Parameters

devid the device ID to query.

Returns: true if devid is a playback device, false if it is recording.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ IsAudioFloat()

bool SDL::IsAudioFloat ( AudioFormatRaw x )

constexpr

Determine if an AudioFormat represents floating point data.

For example, IsAudioFloat(AUDIO_S16) returns 0.

Parameters

x	an AudioFormat value.

Returns: non-zero if format is floating point, zero otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ IsAudioInt()

bool SDL::IsAudioInt ( AudioFormatRaw x )

constexpr

Determine if an AudioFormat represents integer data.

For example, IsAudioInt(AUDIO_F32) returns 0.

Parameters

x	an AudioFormat value.

Returns: non-zero if format is integer, zero otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ IsAudioLittleEndian()

bool SDL::IsAudioLittleEndian ( AudioFormatRaw x )

constexpr

Determine if an AudioFormat represents littleendian data.

For example, IsAudioLittleEndian(AUDIO_S16BE) returns 0.

Parameters

x	an AudioFormat value.

Returns: non-zero if format is littleendian, zero otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ IsAudioSigned()

bool SDL::IsAudioSigned ( AudioFormatRaw x )

constexpr

Determine if an AudioFormat represents signed data.

For example, IsAudioSigned(AUDIO_U8) returns 0.

Parameters

x	an AudioFormat value.

Returns: non-zero if format is signed, zero otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ IsAudioUnsigned()

bool SDL::IsAudioUnsigned ( AudioFormatRaw x )

constexpr

Determine if an AudioFormat represents unsigned data.

For example, IsAudioUnsigned(AUDIO_S16) returns 0.

Parameters

x	an AudioFormat value.

Returns: non-zero if format is unsigned, zero otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ IsBigEndian()

bool SDL::AudioFormat::IsBigEndian ( ) const

constexpr

Determine if an AudioFormat represents bigendian data.

For example, IsAudioBigENDIAN(AUDIO_S16LE) returns 0.

Returns: non-zero if format is bigendian, zero otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ IsFloat()

bool SDL::AudioFormat::IsFloat ( ) const

constexpr

Determine if an AudioFormat represents floating point data.

For example, IsAudioFloat(AUDIO_S16) returns 0.

Returns: non-zero if format is floating point, zero otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ IsInt()

bool SDL::AudioFormat::IsInt ( ) const

constexpr

Determine if an AudioFormat represents integer data.

For example, IsAudioInt(AUDIO_F32) returns 0.

Returns: non-zero if format is integer, zero otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ IsLittleEndian()

bool SDL::AudioFormat::IsLittleEndian ( ) const

constexpr

Determine if an AudioFormat represents littleendian data.

For example, IsAudioLittleEndian(AUDIO_S16BE) returns 0.

Returns: non-zero if format is littleendian, zero otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ IsPhysical()

bool SDL::AudioDeviceBase::IsPhysical ( ) const

inline

Determine if an audio device is physical (instead of logical).

An AudioDevice that represents physical hardware is a physical device; there is one for each piece of hardware that SDL can see. Logical devices are created by calling OpenAudioDevice or OpenAudioDeviceStream, and while each is associated with a physical device, there can be any number of logical devices on one physical device.

For the most part, logical and physical IDs are interchangeable–if you try to open a logical device, SDL understands to assign that effort to the underlying physical device, etc. However, it might be useful to know if an arbitrary device ID is physical or logical. This function reports which.

This function may return either true or false for invalid device IDs.

Returns: true if devid is a physical device, false if it is logical.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ IsPlayback()

bool SDL::AudioDeviceBase::IsPlayback ( ) const

inline

Determine if an audio device is a playback device (instead of recording).

This function may return either true or false for invalid device IDs.

Returns: true if devid is a playback device, false if it is recording.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ IsSigned()

bool SDL::AudioFormat::IsSigned ( ) const

constexpr

Determine if an AudioFormat represents signed data.

For example, IsAudioSigned(AUDIO_U8) returns 0.

Returns: non-zero if format is signed, zero otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ IsUnsigned()

bool SDL::AudioFormat::IsUnsigned ( ) const

constexpr

Determine if an AudioFormat represents unsigned data.

For example, IsAudioUnsigned(AUDIO_S16) returns 0.

Returns: non-zero if format is unsigned, zero otherwise.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ LoadWAV()

OwnArray< Uint8 > SDL::LoadWAV	(	StringParam	path,
		AudioSpec *	spec )

inline

Loads a WAV from a file path.

This is a convenience function that is effectively the same as:

LoadWAV_IO(IOFromFile(path, "rb"), true, spec);

SDL::LoadWAV_IO

OwnArray< Uint8 > LoadWAV_IO(IOStreamRef src, AudioSpec *spec, bool closeio=false)

Load the audio data of a WAVE file into memory.

Definition SDL3pp_audio.h:5288

SDL::IOFromFile

IOStream IOFromFile(StringParam file, StringParam mode)

Use this function to create a new IOStream structure for reading from and/or writing to a named file.

Definition SDL3pp_iostream.h:1683

Parameters

path	the file path of the WAV file to open.
spec	a pointer to an AudioSpec that will be set to the WAVE data's format details on successful return.

Returns: an allocated buffer containing the audio data on success, or nullptr on failure.

This function throws if the .WAV file cannot be opened, uses an unknown data format, or is corrupt,

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: LoadWAV_IO

◆ LoadWAV_IO()

OwnArray< Uint8 > SDL::LoadWAV_IO	(	IOStreamRef	src,
		AudioSpec *	spec,
		bool	closeio = false )

inline

Load the audio data of a WAVE file into memory.

Loading a WAVE file requires src, spec, audio_buf and audio_len to be valid pointers. The entire data portion of the file is then loaded into memory and decoded if necessary.

Supported formats are RIFF WAVE files with the formats PCM (8, 16, 24, and 32 bits), IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and A-law and mu-law (8 bits). Other formats are currently unsupported and cause an error.

If this function succeeds, the return value is zero and the pointer to the audio data allocated by the function is written to audio_buf and its length in bytes to audio_len. The AudioSpec members freq, channels, and format are set to the values of the audio data in the buffer.

It's necessary to use free() to free the audio data returned in audio_buf when it is no longer used.

Because of the underspecification of the .WAV format, there are many problematic files in the wild that cause issues with strict decoders. To provide compatibility with these files, this decoder is lenient in regards to the truncation of the file, the fact chunk, and the size of the RIFF chunk. The hints SDL_HINT_WAVE_RIFF_CHUNK_SIZE, SDL_HINT_WAVE_TRUNCATION, and SDL_HINT_WAVE_FACT_CHUNK can be used to tune the behavior of the loading process.

Any file that is invalid (due to truncation, corruption, or wrong values in the headers), too big, or unsupported causes an error. Additionally, any critical I/O error from the data source will terminate the loading process with an error. The function returns nullptr on error and in all cases (with the exception of src being nullptr), an appropriate error message will be set.

It is required that the data source supports seeking.

Example:

LoadWAV_IO(IOStream.FromFile("sample.wav", "rb"), spec);

SDL::IOStream::FromFile

static IOStream FromFile(StringParam file, StringParam mode)

Use this function to create a new IOStream structure for reading from and/or writing to a named file.

Definition SDL3pp_iostream.h:1688

SDL::IOStream

The read/write operation structure.

Definition SDL3pp_iostream.h:1332

Note that the LoadWAV function does this same thing for you, but in a less messy way:

LoadWAV("sample.wav", &spec);

SDL::LoadWAV

OwnArray< Uint8 > LoadWAV(StringParam path, AudioSpec *spec)

Loads a WAV from a file path.

Definition SDL3pp_audio.h:5322

Parameters

src	the data source for the WAVE data.
spec	a pointer to an AudioSpec that will be set to the WAVE data's format details on successful return.
closeio	if true, calls CloseIO() on src before returning, even in the case of an error.

Returns: an allocated buffer containing the audio data on success, or nullptr on failure.

This function throws if the .WAV file cannot be opened, uses an unknown data format, or is corrupt; call GetError() for more information.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: LoadWAV

◆ Lock()

AudioStreamLock SDL::AudioStreamBase::Lock ( )

inline

Lock an audio stream for serialized access.

Each AudioStream has an internal mutex it uses to protect its data structures from threading conflicts. This function allows an app to lock that mutex, which could be useful if registering callbacks on this stream.

One does not need to lock a stream to use in it most cases, as the stream manages this lock internally. However, this lock is held during callbacks, which may run from arbitrary threads at any time, so if an app needs to protect shared data during those callbacks, locking the stream guarantees that the callback is not running while the lock is held.

As this is just a wrapper over LockMutex for an internal lock; it has all the same attributes (recursive locks are allowed, etc).

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: UnlockAudioStream

◆ LockAudioStream()

void SDL::LockAudioStream ( AudioStreamRef stream )

inline

Lock an audio stream for serialized access.

Each AudioStream has an internal mutex it uses to protect its data structures from threading conflicts. This function allows an app to lock that mutex, which could be useful if registering callbacks on this stream.

One does not need to lock a stream to use in it most cases, as the stream manages this lock internally. However, this lock is held during callbacks, which may run from arbitrary threads at any time, so if an app needs to protect shared data during those callbacks, locking the stream guarantees that the callback is not running while the lock is held.

As this is just a wrapper over LockMutex for an internal lock; it has all the same attributes (recursive locks are allowed, etc).

Parameters

stream the audio stream to lock.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

See also: UnlockAudioStream

◆ MixAudio() [1/2]

void SDL::MixAudio	(	TargetBytes	dst,
		SourceBytes	src,
		AudioFormat	format,
		float	volume )

inline

Mix audio data in a specified format.

This takes an audio buffer src of len bytes of format data and mixes it into dst, performing addition, volume adjustment, and overflow clipping. The buffer pointed to by dst must also be len bytes of format data.

This is provided for convenience – you can mix your own audio data.

Do not use this function for mixing together more than two streams of sample data. The output from repeated application of this function may be distorted by clipping, because there is no accumulator with greater range than the input (not to mention this being an inefficient way of doing it).

It is a common misconception that this function is required to write audio data to an output stream in an audio callback. While you can do that, MixAudio() is really only needed when you're mixing a single audio stream with a volume adjustment.

Parameters

dst	the destination for the mixed audio.
src	the source audio buffer to be mixed.
format	the AudioFormat structure representing the desired audio format.
volume	ranges from 0.0 - 1.0, and should be set to 1.0 for full audio volume.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ MixAudio() [2/2]

void SDL::MixAudio	(	Uint8 *	dst,
		SourceBytes	src,
		AudioFormat	format,
		float	volume )

inline

Mix audio data in a specified format.

This takes an audio buffer src of len bytes of format data and mixes it into dst, performing addition, volume adjustment, and overflow clipping. The buffer pointed to by dst must also be len bytes of format data.

This is provided for convenience – you can mix your own audio data.

Do not use this function for mixing together more than two streams of sample data. The output from repeated application of this function may be distorted by clipping, because there is no accumulator with greater range than the input (not to mention this being an inefficient way of doing it).

It is a common misconception that this function is required to write audio data to an output stream in an audio callback. While you can do that, MixAudio() is really only needed when you're mixing a single audio stream with a volume adjustment.

Parameters

dst	the destination for the mixed audio.
src	the source audio buffer to be mixed.
format	the AudioFormat structure representing the desired audio format.
volume	ranges from 0.0 - 1.0, and should be set to 1.0 for full audio volume.

Exceptions

Error on failure.

Thread safety:: It is safe to call this function from any thread.

Since: This function is available since SDL 3.2.0.

◆ OpenAudioDevice()

AudioDevice SDL::OpenAudioDevice	(	AudioDeviceRef	devid,
		OptionalRef< const AudioSpec >	spec )