Audio functionality for the SDL library. More...

Classes
class	SDL::AudioFormat
	Audio format. More...

struct	SDL::AudioDeviceBase
	SDL Audio Device instance IDs. More...

struct	SDL::AudioDeviceRef
	Handle to a non owned audioDevice. More...

struct	SDL::AudioDevice
	Handle to an owned audioDevice. More...

struct	SDL::AudioStreamBase
	The opaque handle that represents an audio stream. More...

struct	SDL::AudioStreamRef
	Handle to a non owned audioStream. More...

struct	SDL::AudioStream
	Handle to an owned audioStream. More...

struct	SDL::AudioStreamLock
	Locks a AudioStream. More...

Macros
#define	SDL_AUDIO_MASK_BITSIZE (0xFFu)
	Mask of bits in an AudioFormat that contains the format bit size.

#define	SDL_AUDIO_MASK_FLOAT (1u << 8)
	Mask of bits in an AudioFormat that contain the floating point flag.

#define	SDL_AUDIO_MASK_BIG_ENDIAN (1u << 12)
	Mask of bits in an AudioFormat that contain the bigendian flag.

#define	SDL_AUDIO_MASK_SIGNED (1u << 15)
	Mask of bits in an AudioFormat that contain the signed data flag.

Typedefs
using	SDL::AudioSpec = SDL_AudioSpec
	Format specifier for audio data.

using	SDL::OptionalAudioStream = OptionalResource< AudioStreamRef, AudioStream >
	A audioStream parameter that might own its value.

using	SDL::AudioPostmixCallback = SDL_AudioPostmixCallback
	A callback that fires when data is about to be fed to an audio device.

using	SDL::AudioPostmixCB = std::function< void(const AudioSpec &spec, std::span< float > buffer)>
	A callback that fires when data is about to be fed to an audio device.

using	SDL::AudioStreamCallback = SDL_AudioStreamCallback
	A callback that fires when data passes through an AudioStreamBase.

using	SDL::AudioStreamCB = std::function< void(AudioStreamRef stream, int additional_amount, int total_amount)>
	A callback that fires when data passes through an AudioStreamBase.

Functions
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.

void	SDL::UnbindAudioStreams (std::span< AudioStreamRef > streams)
	Unbind a list of audio streams from their audio devices.

OwnArray< Uint8 >	SDL::LoadWAV (IOStreamBase &src, AudioSpec *spec)
	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.

void	SDL::AudioDeviceBase::BindAudioStreams (std::span< AudioStreamRef > streams)
	Bind a list of audio streams to an audio device.

void	SDL::AudioDeviceBase::BindAudioStream (AudioStreamBase &stream)
	Bind a single audio stream to an audio device.

AudioStreamLock	SDL::AudioStreamBase::Lock ()
	Lock an audio stream for serialized access.

Variables
constexpr SDL_AudioFormat	SDL::AUDIO_UNKNOWN
	Unspecified audio format.

constexpr SDL_AudioFormat	SDL::AUDIO_U8 = SDL_AUDIO_U8
	Unsigned 8-bit samples.

constexpr SDL_AudioFormat	SDL::AUDIO_S8 = SDL_AUDIO_S8
	Signed 8-bit samples.

constexpr SDL_AudioFormat	SDL::AUDIO_S16LE
	Signed 16-bit samples.

constexpr SDL_AudioFormat	SDL::AUDIO_S16BE
	As above, but big-endian byte order.

constexpr SDL_AudioFormat	SDL::AUDIO_S32LE
	32-bit integer samples

constexpr SDL_AudioFormat	SDL::AUDIO_S32BE
	As above, but big-endian byte order.

constexpr SDL_AudioFormat	SDL::AUDIO_F32LE
	32-bit floating point samples

constexpr SDL_AudioFormat	SDL::AUDIO_F32BE
	As above, but big-endian byte order.

constexpr SDL_AudioFormat	SDL::AUDIO_S16 = SDL_AUDIO_S16
	AUDIO_S16.

constexpr SDL_AudioFormat	SDL::AUDIO_S32 = SDL_AUDIO_S32
	AUDIO_S32.

constexpr SDL_AudioFormat	SDL::AUDIO_F32 = SDL_AUDIO_F32
	AUDIO_F32.

constexpr AudioDeviceRef	SDL::AUDIO_DEVICE_DEFAULT_PLAYBACK
	A value used to request a default playback audio device.

constexpr AudioDeviceRef	SDL::AUDIO_DEVICE_DEFAULT_RECORDING
	A value used to request a default recording audio device.

Detailed Description

All audio in SDL3 revolves around AudioStreamBase. 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 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 AudioStreamBase.AudioStreamBase, 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 AudioStreamBase 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.

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

Macro Definition Documentation

◆ SDL_AUDIO_MASK_BIG_ENDIAN

#define SDL_AUDIO_MASK_BIG_ENDIAN (1u << 12)

Generally one should use AudioFormat.IsBigEndian or AudioFormat.IsLittleEndian instead of this macro directly.

Since: This macro is available since SDL 3.2.0.

◆ SDL_AUDIO_MASK_BITSIZE

#define SDL_AUDIO_MASK_BITSIZE (0xFFu)

Generally one should use AudioFormat.GetBitSize instead of this macro directly.

Since: This macro is available since SDL 3.2.0.

◆ SDL_AUDIO_MASK_FLOAT

#define SDL_AUDIO_MASK_FLOAT (1u << 8)

Generally one should use AudioFormat.IsFloat instead of this macro directly.

Since: This macro is available since SDL 3.2.0.

◆ SDL_AUDIO_MASK_SIGNED

#define SDL_AUDIO_MASK_SIGNED (1u << 15)

Generally one should use AudioFormat.IsSigned instead of this macro directly.

Since: This macro is available since SDL 3.2.0.

Typedef Documentation

◆ AudioPostmixCallback

using SDL::AudioPostmixCallback = typedef SDL_AudioPostmixCallback

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 AudioDeviceBase.SetPostmixCallback, 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: AudioDeviceBase.SetPostmixCallback

◆ AudioPostmixCB

using SDL::AudioPostmixCB = typedef std::function<void(const AudioSpec& spec, std::span<float> buffer)>

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: AudioDeviceBase.SetPostmixCallback; AudioPostmixCallback

◆ AudioSpec

using SDL::AudioSpec = typedef SDL_AudioSpec

Since: This struct is available since SDL 3.2.0.

See also: AudioFormat

◆ AudioStreamCallback

using SDL::AudioStreamCallback = typedef SDL_AudioStreamCallback

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

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 AudioStreamLock.AudioStreamLock 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: AudioStreamBase.SetGetCallback; AudioStreamBase.SetPutCallback

◆ AudioStreamCB

using SDL::AudioStreamCB = typedef std::function< void(AudioStreamRef stream, int additional_amount, int total_amount)>

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

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 AudioStreamLock.AudioStreamLock 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: AudioStreamBase.SetGetCallback; AudioStreamBase.SetPutCallback; AudioStreamCallback

◆ OptionalAudioStream

using SDL::OptionalAudioStream = typedef OptionalResource<AudioStreamRef, AudioStream>

This is designed to be used on parameter's type and accepts that accepts a std::nullopt, a non-owned AudioStreamRef or an owned AudioStream

Function Documentation

◆ AudioFrameSize()

constexpr int SDL::AudioFrameSize ( const AudioSpec & x )

constexpr

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.

◆ BindAudioStream()

void SDL::AudioDeviceBase::BindAudioStream ( AudioStreamBase & stream )

inline

This is a convenience function, equivalent to calling AudioDeviceBase.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: AudioDeviceBase.BindAudioStreams; AudioDeviceBase.UnbindAudioStream; AudioStreamBase.GetDevice

◆ BindAudioStreams()

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

inline

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 AudioStreamBase.SetFormat().

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: AudioDeviceBase.BindAudioStreams; AudioDeviceBase.UnbindAudioStream; AudioStreamBase.GetDevice

◆ ConvertAudioSamples()

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

inline

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 AudioStreamBase, which is designed for this situation.

Internally, this function creates and destroys an AudioStreamBase 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.

Returns: the converted audio data 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.

◆ GetAudioDriver()

const char * SDL::GetAudioDriver ( int index )

inline

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

◆ GetAudioPlaybackDevices()

OwnArray< AudioDeviceRef > SDL::GetAudioPlaybackDevices ( )

inline

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 AudioDeviceBase.AudioDeviceBase().

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

Returns: a 0 terminated array of device instance IDs or nullptr on error; call GetError() for more information. This should be freed with free() when it is no longer needed.

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

Since: This function is available since SDL 3.2.0.

See also: AudioDeviceBase.AudioDeviceBase; GetAudioRecordingDevices

◆ GetAudioRecordingDevices()

OwnArray< AudioDeviceRef > SDL::GetAudioRecordingDevices ( )

inline

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 AudioDeviceBase.AudioDeviceBase().

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

Returns: a 0 terminated array of device instance IDs, or nullptr on failure; call GetError() for more information. This should be freed with free() when it is no longer needed.

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

Since: This function is available since SDL 3.2.0.

See also: AudioDeviceBase.AudioDeviceBase; GetAudioPlaybackDevices

◆ GetCurrentAudioDriver()

const char * SDL::GetCurrentAudioDriver ( )

inline

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.

◆ GetNumAudioDrivers()

int SDL::GetNumAudioDrivers ( )

inline

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

◆ LoadWAV() [1/2]

OwnArray< Uint8 > SDL::LoadWAV	(	IOStreamBase &	src,
		AudioSpec *	spec
	)

inline

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(IOStreamBase.IOStreamBase("sample.wav", "rb"), true, &spec, &buf,

&len);

SDL::LoadWAV

OwnArray< Uint8 > LoadWAV(IOStreamBase &src, AudioSpec *spec)

Load the audio data of a WAVE file into memory.

Definition SDL3pp_audio.h:2829

SDL::IOStreamBase

The read/write operation structure.

Definition SDL3pp_iostream.h:107

SDL::IOStreamBase::IOStreamBase

IOStreamBase(StringParam file, StringParam mode)

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

Definition SDL3pp_iostream.h:192

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

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

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.

Returns: the audio data on success or nullptr on failure.

This function throws false 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

◆ LoadWAV() [2/2]

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

inline

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

LoadWAV(IOStreamBase.IOStreamBase(path, "rb"), true, spec, audio_buf,

audio_len);

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: the audio data on success or nullptr on failure.

This function throws false 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

◆ Lock()

AudioStreamLock SDL::AudioStreamBase::Lock ( )

inline

Each AudioStreamBase 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 MutexBase.Lock 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: AudioStreamLock.Unlock

◆ MixAudio() [1/2]

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

inline

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

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.

◆ UnbindAudioStreams()

void SDL::UnbindAudioStreams ( std::span< AudioStreamRef > streams )

inline

The streams being unbound do not all have to be on the same device. All streams on the same device will be unbound atomically (data will stop flowing through all unbound streams on the same device at the same time).

Unbinding a stream that isn't bound to a device is a legal no-op.

Parameters

streams an array of audio streams to unbind. Can be nullptr or contain nullptr.

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

Since: This function is available since SDL 3.2.0.

See also: AudioDeviceBase.BindAudioStreams

Variable Documentation

◆ AUDIO_DEVICE_DEFAULT_PLAYBACK

constexpr AudioDeviceRef SDL::AUDIO_DEVICE_DEFAULT_PLAYBACK

constexpr

Initial value:

=

SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK

Several functions that require an AudioDeviceBase will accept this value to signify the app just wants the system to choose a default device instead of the app providing a specific one.

Since: This function is available since SDL 3.2.0.

◆ AUDIO_DEVICE_DEFAULT_RECORDING

constexpr AudioDeviceRef SDL::AUDIO_DEVICE_DEFAULT_RECORDING

constexpr

Initial value:

=

SDL_AUDIO_DEVICE_DEFAULT_RECORDING

Several functions that require an AudioDeviceBase will accept this value to signify the app just wants the system to choose a default device instead of the app providing a specific one.

Since: This function is available since SDL 3.2.0.

◆ AUDIO_F32BE

constexpr SDL_AudioFormat SDL::AUDIO_F32BE

constexpr

Initial value:

=

SDL_AUDIO_F32BE

◆ AUDIO_F32LE

constexpr SDL_AudioFormat SDL::AUDIO_F32LE

constexpr

Initial value:

=

SDL_AUDIO_F32LE

◆ AUDIO_S16BE

constexpr SDL_AudioFormat SDL::AUDIO_S16BE

constexpr

Initial value:

=

SDL_AUDIO_S16BE

◆ AUDIO_S16LE

constexpr SDL_AudioFormat SDL::AUDIO_S16LE

constexpr

Initial value:

=

SDL_AUDIO_S16LE

◆ AUDIO_S32BE

constexpr SDL_AudioFormat SDL::AUDIO_S32BE

constexpr

Initial value:

=

SDL_AUDIO_S32BE

◆ AUDIO_S32LE

constexpr SDL_AudioFormat SDL::AUDIO_S32LE

constexpr

Initial value:

=

SDL_AUDIO_S32LE

◆ AUDIO_UNKNOWN

constexpr SDL_AudioFormat SDL::AUDIO_UNKNOWN

constexpr

Initial value:

=

SDL_AUDIO_UNKNOWN

Classes

Macros

Typedefs

Functions

Variables

Detailed Description

Logical audio devices

Simplified audio

Channel layouts

Macro Definition Documentation

◆ SDL_AUDIO_MASK_BIG_ENDIAN

◆ SDL_AUDIO_MASK_BITSIZE

◆ SDL_AUDIO_MASK_FLOAT

◆ SDL_AUDIO_MASK_SIGNED

Typedef Documentation

◆ AudioPostmixCallback

◆ AudioPostmixCB

◆ AudioSpec

◆ AudioStreamCallback

◆ AudioStreamCB

◆ OptionalAudioStream

Function Documentation

◆ AudioFrameSize()

◆ BindAudioStream()

◆ BindAudioStreams()

◆ ConvertAudioSamples()

◆ GetAudioDriver()

◆ GetAudioPlaybackDevices()

◆ GetAudioRecordingDevices()

◆ GetCurrentAudioDriver()

◆ GetNumAudioDrivers()

◆ LoadWAV() [1/2]

◆ LoadWAV() [2/2]

◆ Lock()

◆ MixAudio() [1/2]

◆ MixAudio() [2/2]

◆ UnbindAudioStreams()

Variable Documentation

◆ AUDIO_DEVICE_DEFAULT_PLAYBACK

◆ AUDIO_DEVICE_DEFAULT_RECORDING

◆ AUDIO_F32BE

◆ AUDIO_F32LE

◆ AUDIO_S16BE

◆ AUDIO_S16LE

◆ AUDIO_S32BE

◆ AUDIO_S32LE

◆ AUDIO_UNKNOWN