SDL 3.0
Data Structures | Macros | Typedefs | Enumerations | Functions
SDL_audio.h File Reference
#include <SDL3/SDL_stdinc.h>
#include <SDL3/SDL_endian.h>
#include <SDL3/SDL_error.h>
#include <SDL3/SDL_mutex.h>
#include <SDL3/SDL_properties.h>
#include <SDL3/SDL_iostream.h>
#include <SDL3/SDL_begin_code.h>
#include <SDL3/SDL_close_code.h>
+ Include dependency graph for SDL_audio.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  SDL_AudioSpec
 

Macros

#define SDL_AUDIO_MASK_BITSIZE   (0xFFu)
 
#define SDL_AUDIO_MASK_FLOAT   (1u<<8)
 
#define SDL_AUDIO_MASK_BIG_ENDIAN   (1u<<12)
 
#define SDL_AUDIO_MASK_SIGNED   (1u<<15)
 
#define SDL_DEFINE_AUDIO_FORMAT(signed, bigendian, flt, size)    (((Uint16)(signed) << 15) | ((Uint16)(bigendian) << 12) | ((Uint16)(flt) << 8) | ((size) & SDL_AUDIO_MASK_BITSIZE))
 
#define SDL_AUDIO_BITSIZE(x)   ((x) & SDL_AUDIO_MASK_BITSIZE)
 
#define SDL_AUDIO_BYTESIZE(x)   (SDL_AUDIO_BITSIZE(x) / 8)
 
#define SDL_AUDIO_ISFLOAT(x)   ((x) & SDL_AUDIO_MASK_FLOAT)
 
#define SDL_AUDIO_ISBIGENDIAN(x)   ((x) & SDL_AUDIO_MASK_BIG_ENDIAN)
 
#define SDL_AUDIO_ISLITTLEENDIAN(x)   (!SDL_AUDIO_ISBIGENDIAN(x))
 
#define SDL_AUDIO_ISSIGNED(x)   ((x) & SDL_AUDIO_MASK_SIGNED)
 
#define SDL_AUDIO_ISINT(x)   (!SDL_AUDIO_ISFLOAT(x))
 
#define SDL_AUDIO_ISUNSIGNED(x)   (!SDL_AUDIO_ISSIGNED(x))
 
#define SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK   ((SDL_AudioDeviceID) 0xFFFFFFFFu)
 
#define SDL_AUDIO_DEVICE_DEFAULT_RECORDING   ((SDL_AudioDeviceID) 0xFFFFFFFEu)
 
#define SDL_AUDIO_FRAMESIZE(x)   (SDL_AUDIO_BYTESIZE((x).format) * (x).channels)
 
#define SDL_PROP_AUDIOSTREAM_AUTO_CLEANUP_BOOLEAN   "SDL.audiostream.auto_cleanup"
 

Typedefs

typedef Uint32 SDL_AudioDeviceID
 
typedef struct SDL_AudioStream SDL_AudioStream
 
typedef void(* SDL_AudioStreamDataCompleteCallback) (void *userdata, const void *buf, int buflen)
 
typedef void(* SDL_AudioStreamCallback) (void *userdata, SDL_AudioStream *stream, int additional_amount, int total_amount)
 
typedef void(* SDL_AudioPostmixCallback) (void *userdata, const SDL_AudioSpec *spec, float *buffer, int buflen)
 

Enumerations

enum  SDL_AudioFormat {
  SDL_AUDIO_UNKNOWN = 0x0000u ,
  SDL_AUDIO_U8 = 0x0008u ,
  SDL_AUDIO_S8 = 0x8008u ,
  SDL_AUDIO_S16LE = 0x8010u ,
  SDL_AUDIO_S16BE = 0x9010u ,
  SDL_AUDIO_S32LE = 0x8020u ,
  SDL_AUDIO_S32BE = 0x9020u ,
  SDL_AUDIO_F32LE = 0x8120u ,
  SDL_AUDIO_F32BE = 0x9120u ,
  SDL_AUDIO_S16 = SDL_AUDIO_S16LE ,
  SDL_AUDIO_S32 = SDL_AUDIO_S32LE ,
  SDL_AUDIO_F32 = SDL_AUDIO_F32LE
}
 

Functions

int SDL_GetNumAudioDrivers (void)
 
const char * SDL_GetAudioDriver (int index)
 
const char * SDL_GetCurrentAudioDriver (void)
 
SDL_AudioDeviceID * SDL_GetAudioPlaybackDevices (int *count)
 
SDL_AudioDeviceID * SDL_GetAudioRecordingDevices (int *count)
 
const char * SDL_GetAudioDeviceName (SDL_AudioDeviceID devid)
 
bool SDL_GetAudioDeviceFormat (SDL_AudioDeviceID devid, SDL_AudioSpec *spec, int *sample_frames)
 
int * SDL_GetAudioDeviceChannelMap (SDL_AudioDeviceID devid, int *count)
 
SDL_AudioDeviceID SDL_OpenAudioDevice (SDL_AudioDeviceID devid, const SDL_AudioSpec *spec)
 
bool SDL_IsAudioDevicePhysical (SDL_AudioDeviceID devid)
 
bool SDL_IsAudioDevicePlayback (SDL_AudioDeviceID devid)
 
bool SDL_PauseAudioDevice (SDL_AudioDeviceID devid)
 
bool SDL_ResumeAudioDevice (SDL_AudioDeviceID devid)
 
bool SDL_AudioDevicePaused (SDL_AudioDeviceID devid)
 
float SDL_GetAudioDeviceGain (SDL_AudioDeviceID devid)
 
bool SDL_SetAudioDeviceGain (SDL_AudioDeviceID devid, float gain)
 
void SDL_CloseAudioDevice (SDL_AudioDeviceID devid)
 
bool SDL_BindAudioStreams (SDL_AudioDeviceID devid, SDL_AudioStream *const *streams, int num_streams)
 
bool SDL_BindAudioStream (SDL_AudioDeviceID devid, SDL_AudioStream *stream)
 
void SDL_UnbindAudioStreams (SDL_AudioStream *const *streams, int num_streams)
 
void SDL_UnbindAudioStream (SDL_AudioStream *stream)
 
SDL_AudioDeviceID SDL_GetAudioStreamDevice (SDL_AudioStream *stream)
 
SDL_AudioStream * SDL_CreateAudioStream (const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec)
 
SDL_PropertiesID SDL_GetAudioStreamProperties (SDL_AudioStream *stream)
 
bool SDL_GetAudioStreamFormat (SDL_AudioStream *stream, SDL_AudioSpec *src_spec, SDL_AudioSpec *dst_spec)
 
bool SDL_SetAudioStreamFormat (SDL_AudioStream *stream, const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec)
 
float SDL_GetAudioStreamFrequencyRatio (SDL_AudioStream *stream)
 
bool SDL_SetAudioStreamFrequencyRatio (SDL_AudioStream *stream, float ratio)
 
float SDL_GetAudioStreamGain (SDL_AudioStream *stream)
 
bool SDL_SetAudioStreamGain (SDL_AudioStream *stream, float gain)
 
int * SDL_GetAudioStreamInputChannelMap (SDL_AudioStream *stream, int *count)
 
int * SDL_GetAudioStreamOutputChannelMap (SDL_AudioStream *stream, int *count)
 
bool SDL_SetAudioStreamInputChannelMap (SDL_AudioStream *stream, const int *chmap, int count)
 
bool SDL_SetAudioStreamOutputChannelMap (SDL_AudioStream *stream, const int *chmap, int count)
 
bool SDL_PutAudioStreamData (SDL_AudioStream *stream, const void *buf, int len)
 
bool SDL_PutAudioStreamDataNoCopy (SDL_AudioStream *stream, const void *buf, int len, SDL_AudioStreamDataCompleteCallback callback, void *userdata)
 
bool SDL_PutAudioStreamPlanarData (SDL_AudioStream *stream, const void *const *channel_buffers, int num_channels, int num_samples)
 
int SDL_GetAudioStreamData (SDL_AudioStream *stream, void *buf, int len)
 
int SDL_GetAudioStreamAvailable (SDL_AudioStream *stream)
 
int SDL_GetAudioStreamQueued (SDL_AudioStream *stream)
 
bool SDL_FlushAudioStream (SDL_AudioStream *stream)
 
bool SDL_ClearAudioStream (SDL_AudioStream *stream)
 
bool SDL_PauseAudioStreamDevice (SDL_AudioStream *stream)
 
bool SDL_ResumeAudioStreamDevice (SDL_AudioStream *stream)
 
bool SDL_AudioStreamDevicePaused (SDL_AudioStream *stream)
 
bool SDL_LockAudioStream (SDL_AudioStream *stream)
 
bool SDL_UnlockAudioStream (SDL_AudioStream *stream)
 
bool SDL_SetAudioStreamGetCallback (SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata)
 
bool SDL_SetAudioStreamPutCallback (SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata)
 
void SDL_DestroyAudioStream (SDL_AudioStream *stream)
 
SDL_AudioStream * SDL_OpenAudioDeviceStream (SDL_AudioDeviceID devid, const SDL_AudioSpec *spec, SDL_AudioStreamCallback callback, void *userdata)
 
bool SDL_SetAudioPostmixCallback (SDL_AudioDeviceID devid, SDL_AudioPostmixCallback callback, void *userdata)
 
bool SDL_LoadWAV_IO (SDL_IOStream *src, bool closeio, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len)
 
bool SDL_LoadWAV (const char *path, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len)
 
bool SDL_MixAudio (Uint8 *dst, const Uint8 *src, SDL_AudioFormat format, Uint32 len, float volume)
 
bool SDL_ConvertAudioSamples (const SDL_AudioSpec *src_spec, const Uint8 *src_data, int src_len, const SDL_AudioSpec *dst_spec, Uint8 **dst_data, int *dst_len)
 
const char * SDL_GetAudioFormatName (SDL_AudioFormat format)
 
int SDL_GetSilenceValueForFormat (SDL_AudioFormat format)
 

Macro Definition Documentation

◆ SDL_AUDIO_BITSIZE

#define SDL_AUDIO_BITSIZE (   x)    ((x) & SDL_AUDIO_MASK_BITSIZE)

Retrieve the size, in bits, from an SDL_AudioFormat.

For example, SDL_AUDIO_BITSIZE(SDL_AUDIO_S16) returns 16.

Parameters
xan SDL_AudioFormat value.
Returns
data size in bits.

\threadsafety It is safe to call this macro from any thread.

Since
This macro is available since SDL 3.2.0.

Definition at line 266 of file SDL_audio.h.

◆ SDL_AUDIO_BYTESIZE

#define SDL_AUDIO_BYTESIZE (   x)    (SDL_AUDIO_BITSIZE(x) / 8)

Retrieve the size, in bytes, from an SDL_AudioFormat.

For example, SDL_AUDIO_BYTESIZE(SDL_AUDIO_S16) returns 2.

Parameters
xan SDL_AudioFormat value.
Returns
data size in bytes.

\threadsafety It is safe to call this macro from any thread.

Since
This macro is available since SDL 3.2.0.

Definition at line 280 of file SDL_audio.h.

◆ SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK

#define SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK   ((SDL_AudioDeviceID) 0xFFFFFFFFu)

A value used to request a default playback audio device.

Several functions that require an SDL_AudioDeviceID 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 macro is available since SDL 3.2.0.

Definition at line 385 of file SDL_audio.h.

◆ SDL_AUDIO_DEVICE_DEFAULT_RECORDING

#define SDL_AUDIO_DEVICE_DEFAULT_RECORDING   ((SDL_AudioDeviceID) 0xFFFFFFFEu)

A value used to request a default recording audio device.

Several functions that require an SDL_AudioDeviceID 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 macro is available since SDL 3.2.0.

Definition at line 396 of file SDL_audio.h.

◆ SDL_AUDIO_FRAMESIZE

#define SDL_AUDIO_FRAMESIZE (   x)    (SDL_AUDIO_BYTESIZE((x).format) * (x).channels)

Calculate the size of each audio frame (in bytes) from an SDL_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
xan SDL_AudioSpec to query.
Returns
the number of bytes used per sample frame.

\threadsafety It is safe to call this macro from any thread.

Since
This macro is available since SDL 3.2.0.

Definition at line 425 of file SDL_audio.h.

◆ SDL_AUDIO_ISBIGENDIAN

#define SDL_AUDIO_ISBIGENDIAN (   x)    ((x) & SDL_AUDIO_MASK_BIG_ENDIAN)

Determine if an SDL_AudioFormat represents bigendian data.

For example, SDL_AUDIO_ISBIGENDIAN(SDL_AUDIO_S16LE) returns 0.

Parameters
xan SDL_AudioFormat value.
Returns
non-zero if format is bigendian, zero otherwise.

\threadsafety It is safe to call this macro from any thread.

Since
This macro is available since SDL 3.2.0.

Definition at line 308 of file SDL_audio.h.

◆ SDL_AUDIO_ISFLOAT

#define SDL_AUDIO_ISFLOAT (   x)    ((x) & SDL_AUDIO_MASK_FLOAT)

Determine if an SDL_AudioFormat represents floating point data.

For example, SDL_AUDIO_ISFLOAT(SDL_AUDIO_S16) returns 0.

Parameters
xan SDL_AudioFormat value.
Returns
non-zero if format is floating point, zero otherwise.

\threadsafety It is safe to call this macro from any thread.

Since
This macro is available since SDL 3.2.0.

Definition at line 294 of file SDL_audio.h.

◆ SDL_AUDIO_ISINT

#define SDL_AUDIO_ISINT (   x)    (!SDL_AUDIO_ISFLOAT(x))

Determine if an SDL_AudioFormat represents integer data.

For example, SDL_AUDIO_ISINT(SDL_AUDIO_F32) returns 0.

Parameters
xan SDL_AudioFormat value.
Returns
non-zero if format is integer, zero otherwise.

\threadsafety It is safe to call this macro from any thread.

Since
This macro is available since SDL 3.2.0.

Definition at line 350 of file SDL_audio.h.

◆ SDL_AUDIO_ISLITTLEENDIAN

#define SDL_AUDIO_ISLITTLEENDIAN (   x)    (!SDL_AUDIO_ISBIGENDIAN(x))

Determine if an SDL_AudioFormat represents littleendian data.

For example, SDL_AUDIO_ISLITTLEENDIAN(SDL_AUDIO_S16BE) returns 0.

Parameters
xan SDL_AudioFormat value.
Returns
non-zero if format is littleendian, zero otherwise.

\threadsafety It is safe to call this macro from any thread.

Since
This macro is available since SDL 3.2.0.

Definition at line 322 of file SDL_audio.h.

◆ SDL_AUDIO_ISSIGNED

#define SDL_AUDIO_ISSIGNED (   x)    ((x) & SDL_AUDIO_MASK_SIGNED)

Determine if an SDL_AudioFormat represents signed data.

For example, SDL_AUDIO_ISSIGNED(SDL_AUDIO_U8) returns 0.

Parameters
xan SDL_AudioFormat value.
Returns
non-zero if format is signed, zero otherwise.

\threadsafety It is safe to call this macro from any thread.

Since
This macro is available since SDL 3.2.0.

Definition at line 336 of file SDL_audio.h.

◆ SDL_AUDIO_ISUNSIGNED

#define SDL_AUDIO_ISUNSIGNED (   x)    (!SDL_AUDIO_ISSIGNED(x))

Determine if an SDL_AudioFormat represents unsigned data.

For example, SDL_AUDIO_ISUNSIGNED(SDL_AUDIO_S16) returns 0.

Parameters
xan SDL_AudioFormat value.
Returns
non-zero if format is unsigned, zero otherwise.

\threadsafety It is safe to call this macro from any thread.

Since
This macro is available since SDL 3.2.0.

Definition at line 364 of file SDL_audio.h.

◆ SDL_AUDIO_MASK_BIG_ENDIAN

#define SDL_AUDIO_MASK_BIG_ENDIAN   (1u<<12)

Mask of bits in an SDL_AudioFormat that contain the bigendian flag.

Generally one should use SDL_AUDIO_ISBIGENDIAN or SDL_AUDIO_ISLITTLEENDIAN instead of this macro directly.

Since
This macro is available since SDL 3.2.0.

Definition at line 170 of file SDL_audio.h.

◆ SDL_AUDIO_MASK_BITSIZE

#define SDL_AUDIO_MASK_BITSIZE   (0xFFu)

CategoryAudio

Audio functionality for the SDL library.

All audio in SDL3 revolves around SDL_AudioStream. Whether you want to play or record audio, convert it, stream it, buffer it, or mix it, you're going to be passing it through an audio stream.

Audio streams are quite flexible; they can accept any amount of data at a time, in any supported format, and output it as needed in any other format, even if the data format changes on either side halfway through.

An app opens an audio device and binds any number of audio streams to it, feeding more data to the streams as available. When the device needs more data, it will pull it from all bound streams and mix them together for playback.

Audio streams can also use an app-provided callback to supply data on-demand, which maps pretty closely to the SDL2 audio model.

SDL also provides a simple .WAV loader in SDL_LoadWAV (and SDL_LoadWAV_IO if you aren't reading from a file) as a basic means to load sound data into your program.

Logical audio devices

In SDL3, opening a physical device (like a SoundBlaster 16 Pro) gives you a logical device ID that you can bind audio streams to. In almost all cases, logical devices can be used anywhere in the API that a physical device is normally used. However, since each device opening generates a new logical device, different parts of the program (say, a VoIP library, or text-to-speech framework, or maybe some other sort of mixer on top of SDL) can have their own device opens that do not interfere with each other; each logical device will mix its separate audio down to a single buffer, fed to the physical device, behind the scenes. As many logical devices as you like can come and go; SDL will only have to open the physical device at the OS level once, and will manage all the logical devices on top of it internally.

One other benefit of logical devices: if you don't open a specific physical device, instead opting for the default, SDL can automatically migrate those logical devices to different hardware as circumstances change: a user plugged in headphones? The system default changed? SDL can transparently migrate the logical devices to the correct physical device seamlessly and keep playing; the app doesn't even have to know it happened if it doesn't want to.

Simplified audio

As a simplified model for when a single source of audio is all that's needed, an app can use SDL_OpenAudioDeviceStream, which is a single function to open an audio device, create an audio stream, bind that stream to the newly-opened device, and (optionally) provide a callback for obtaining audio data. When using this function, the primary interface is the SDL_AudioStream and the device handle is mostly hidden away; destroying a stream created through this function will also close the device, stream bindings cannot be changed, etc. One other quirk of this is that the device is started in a paused state and must be explicitly resumed; this is partially to offer a clean migration for SDL2 apps and partially because the app might have to do more setup before playback begins; in the non-simplified form, nothing will play until a stream is bound to a device, so they start unpaused.

Channel layouts

Audio data passing through SDL is uncompressed PCM data, interleaved. One can provide their own decompression through an MP3, etc, decoder, but SDL does not provide this directly. Each interleaved channel of data is meant to be in a specific order.

Abbreviations:

  • FRONT = single mono speaker
  • FL = front left speaker
  • FR = front right speaker
  • FC = front center speaker
  • BL = back left speaker
  • BR = back right speaker
  • SR = surround right speaker
  • SL = surround left speaker
  • BC = back center speaker
  • LFE = low-frequency speaker

These are listed in the order they are laid out in memory, so "FL, FR" means "the front left speaker is laid out in memory first, then the front right, then it repeats for the next audio frame".

  • 1 channel (mono) layout: FRONT
  • 2 channels (stereo) layout: FL, FR
  • 3 channels (2.1) layout: FL, FR, LFE
  • 4 channels (quad) layout: FL, FR, BL, BR
  • 5 channels (4.1) layout: FL, FR, LFE, BL, BR
  • 6 channels (5.1) layout: FL, FR, FC, LFE, BL, BR (last two can also be SL, SR)
  • 7 channels (6.1) layout: FL, FR, FC, LFE, BC, SL, SR
  • 8 channels (7.1) layout: FL, FR, FC, LFE, BL, BR, SL, SR

This is the same order as DirectSound expects, but applied to all platforms; SDL will swizzle the channels as necessary if a platform expects something different.

SDL_AudioStream can also be provided channel maps to change this ordering to whatever is necessary, in other audio processing scenarios. Mask of bits in an SDL_AudioFormat that contains the format bit size.

Generally one should use SDL_AUDIO_BITSIZE instead of this macro directly.

Since
This macro is available since SDL 3.2.0.

Definition at line 151 of file SDL_audio.h.

◆ SDL_AUDIO_MASK_FLOAT

#define SDL_AUDIO_MASK_FLOAT   (1u<<8)

Mask of bits in an SDL_AudioFormat that contain the floating point flag.

Generally one should use SDL_AUDIO_ISFLOAT instead of this macro directly.

Since
This macro is available since SDL 3.2.0.

Definition at line 160 of file SDL_audio.h.

◆ SDL_AUDIO_MASK_SIGNED

#define SDL_AUDIO_MASK_SIGNED   (1u<<15)

Mask of bits in an SDL_AudioFormat that contain the signed data flag.

Generally one should use SDL_AUDIO_ISSIGNED instead of this macro directly.

Since
This macro is available since SDL 3.2.0.

Definition at line 179 of file SDL_audio.h.

◆ SDL_DEFINE_AUDIO_FORMAT

#define SDL_DEFINE_AUDIO_FORMAT (   signed,
  bigendian,
  flt,
  size 
)     (((Uint16)(signed) << 15) | ((Uint16)(bigendian) << 12) | ((Uint16)(flt) << 8) | ((size) & SDL_AUDIO_MASK_BITSIZE))

Define an SDL_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 SDL_AudioFormat mean.

For example, SDL_AUDIO_S32LE looks like this:

SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 32)
SDL_DEFINE_AUDIO_FORMAT
#define SDL_DEFINE_AUDIO_FORMAT(signed, bigendian, flt, size)
Definition SDL_audio.h:204
Parameters
signed1 for signed data, 0 for unsigned data.
bigendian1 for bigendian data, 0 for littleendian data.
flt1 for floating point data, 0 for integer data.
sizenumber of bits per sample.
Returns
a format value in the style of SDL_AudioFormat.

\threadsafety It is safe to call this macro from any thread.

Since
This macro is available since SDL 3.2.0.

Definition at line 204 of file SDL_audio.h.

221{
222 SDL_AUDIO_UNKNOWN = 0x0000u, /**< Unspecified audio format */
223 SDL_AUDIO_U8 = 0x0008u, /**< Unsigned 8-bit samples */
224 /* SDL_DEFINE_AUDIO_FORMAT(0, 0, 0, 8), */
225 SDL_AUDIO_S8 = 0x8008u, /**< Signed 8-bit samples */
226 /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 8), */
227 SDL_AUDIO_S16LE = 0x8010u, /**< Signed 16-bit samples */
228 /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 16), */
229 SDL_AUDIO_S16BE = 0x9010u, /**< As above, but big-endian byte order */
230 /* SDL_DEFINE_AUDIO_FORMAT(1, 1, 0, 16), */
231 SDL_AUDIO_S32LE = 0x8020u, /**< 32-bit integer samples */
232 /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 32), */
233 SDL_AUDIO_S32BE = 0x9020u, /**< As above, but big-endian byte order */
234 /* SDL_DEFINE_AUDIO_FORMAT(1, 1, 0, 32), */
235 SDL_AUDIO_F32LE = 0x8120u, /**< 32-bit floating point samples */
236 /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 1, 32), */
237 SDL_AUDIO_F32BE = 0x9120u, /**< As above, but big-endian byte order */
238 /* SDL_DEFINE_AUDIO_FORMAT(1, 1, 1, 32), */
239
240 /* These represent the current system's byteorder. */
241 #if SDL_BYTEORDER == SDL_LIL_ENDIAN
242 SDL_AUDIO_S16 = SDL_AUDIO_S16LE,
243 SDL_AUDIO_S32 = SDL_AUDIO_S32LE,
244 SDL_AUDIO_F32 = SDL_AUDIO_F32LE
245 #else
246 SDL_AUDIO_S16 = SDL_AUDIO_S16BE,
247 SDL_AUDIO_S32 = SDL_AUDIO_S32BE,
248 SDL_AUDIO_F32 = SDL_AUDIO_F32BE
249 #endif
250} SDL_AudioFormat;
251
252
253/**
254 * Retrieve the size, in bits, from an SDL_AudioFormat.
255 *
256 * For example, `SDL_AUDIO_BITSIZE(SDL_AUDIO_S16)` returns 16.
257 *
258 * \param x an SDL_AudioFormat value.
259 * \returns data size in bits.
260 *
261 * \threadsafety It is safe to call this macro from any thread.
262 *
263 * \since This macro is available since SDL 3.2.0.
264 */
265#define SDL_AUDIO_BITSIZE(x) ((x) & SDL_AUDIO_MASK_BITSIZE)
266
267/**
268 * Retrieve the size, in bytes, from an SDL_AudioFormat.
269 *
270 * For example, `SDL_AUDIO_BYTESIZE(SDL_AUDIO_S16)` returns 2.
271 *
272 * \param x an SDL_AudioFormat value.
273 * \returns data size in bytes.
274 *
275 * \threadsafety It is safe to call this macro from any thread.
276 *
277 * \since This macro is available since SDL 3.2.0.
278 */
279#define SDL_AUDIO_BYTESIZE(x) (SDL_AUDIO_BITSIZE(x) / 8)
280
281/**
282 * Determine if an SDL_AudioFormat represents floating point data.
283 *
284 * For example, `SDL_AUDIO_ISFLOAT(SDL_AUDIO_S16)` returns 0.
285 *
286 * \param x an SDL_AudioFormat value.
287 * \returns non-zero if format is floating point, zero otherwise.
288 *
289 * \threadsafety It is safe to call this macro from any thread.
290 *
291 * \since This macro is available since SDL 3.2.0.
292 */
293#define SDL_AUDIO_ISFLOAT(x) ((x) & SDL_AUDIO_MASK_FLOAT)
294
295/**
296 * Determine if an SDL_AudioFormat represents bigendian data.
297 *
298 * For example, `SDL_AUDIO_ISBIGENDIAN(SDL_AUDIO_S16LE)` returns 0.
299 *
300 * \param x an SDL_AudioFormat value.
301 * \returns non-zero if format is bigendian, zero otherwise.
302 *
303 * \threadsafety It is safe to call this macro from any thread.
304 *
305 * \since This macro is available since SDL 3.2.0.
306 */
307#define SDL_AUDIO_ISBIGENDIAN(x) ((x) & SDL_AUDIO_MASK_BIG_ENDIAN)
308
309/**
310 * Determine if an SDL_AudioFormat represents littleendian data.
311 *
312 * For example, `SDL_AUDIO_ISLITTLEENDIAN(SDL_AUDIO_S16BE)` returns 0.
313 *
314 * \param x an SDL_AudioFormat value.
315 * \returns non-zero if format is littleendian, zero otherwise.
316 *
317 * \threadsafety It is safe to call this macro from any thread.
318 *
319 * \since This macro is available since SDL 3.2.0.
320 */
321#define SDL_AUDIO_ISLITTLEENDIAN(x) (!SDL_AUDIO_ISBIGENDIAN(x))
322
323/**
324 * Determine if an SDL_AudioFormat represents signed data.
325 *
326 * For example, `SDL_AUDIO_ISSIGNED(SDL_AUDIO_U8)` returns 0.
327 *
328 * \param x an SDL_AudioFormat value.
329 * \returns non-zero if format is signed, zero otherwise.
330 *
331 * \threadsafety It is safe to call this macro from any thread.
332 *
333 * \since This macro is available since SDL 3.2.0.
334 */
335#define SDL_AUDIO_ISSIGNED(x) ((x) & SDL_AUDIO_MASK_SIGNED)
336
337/**
338 * Determine if an SDL_AudioFormat represents integer data.
339 *
340 * For example, `SDL_AUDIO_ISINT(SDL_AUDIO_F32)` returns 0.
341 *
342 * \param x an SDL_AudioFormat value.
343 * \returns non-zero if format is integer, zero otherwise.
344 *
345 * \threadsafety It is safe to call this macro from any thread.
346 *
347 * \since This macro is available since SDL 3.2.0.
348 */
349#define SDL_AUDIO_ISINT(x) (!SDL_AUDIO_ISFLOAT(x))
350
351/**
352 * Determine if an SDL_AudioFormat represents unsigned data.
353 *
354 * For example, `SDL_AUDIO_ISUNSIGNED(SDL_AUDIO_S16)` returns 0.
355 *
356 * \param x an SDL_AudioFormat value.
357 * \returns non-zero if format is unsigned, zero otherwise.
358 *
359 * \threadsafety It is safe to call this macro from any thread.
360 *
361 * \since This macro is available since SDL 3.2.0.
362 */
363#define SDL_AUDIO_ISUNSIGNED(x) (!SDL_AUDIO_ISSIGNED(x))
364
365
366/**
367 * SDL Audio Device instance IDs.
368 *
369 * Zero is used to signify an invalid/null device.
370 *
371 * \since This datatype is available since SDL 3.2.0.
372 */
373typedef Uint32 SDL_AudioDeviceID;
374
375/**
376 * A value used to request a default playback audio device.
377 *
378 * Several functions that require an SDL_AudioDeviceID will accept this value
379 * to signify the app just wants the system to choose a default device instead
380 * of the app providing a specific one.
381 *
382 * \since This macro is available since SDL 3.2.0.
383 */
384#define SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK ((SDL_AudioDeviceID) 0xFFFFFFFFu)
385
386/**
387 * A value used to request a default recording audio device.
388 *
389 * Several functions that require an SDL_AudioDeviceID will accept this value
390 * to signify the app just wants the system to choose a default device instead
391 * of the app providing a specific one.
392 *
393 * \since This macro is available since SDL 3.2.0.
394 */
395#define SDL_AUDIO_DEVICE_DEFAULT_RECORDING ((SDL_AudioDeviceID) 0xFFFFFFFEu)
396
397/**
398 * Format specifier for audio data.
399 *
400 * \since This struct is available since SDL 3.2.0.
401 *
402 * \sa SDL_AudioFormat
403 */
404typedef struct SDL_AudioSpec
405{
406 SDL_AudioFormat format; /**< Audio data format */
407 int channels; /**< Number of channels: 1 mono, 2 stereo, etc */
408 int freq; /**< sample rate: sample frames per second */
409} SDL_AudioSpec;
410
411/**
412 * Calculate the size of each audio frame (in bytes) from an SDL_AudioSpec.
413 *
414 * This reports on the size of an audio sample frame: stereo Sint16 data (2
415 * channels of 2 bytes each) would be 4 bytes per frame, for example.
416 *
417 * \param x an SDL_AudioSpec to query.
418 * \returns the number of bytes used per sample frame.
419 *
420 * \threadsafety It is safe to call this macro from any thread.
421 *
422 * \since This macro is available since SDL 3.2.0.
423 */
424#define SDL_AUDIO_FRAMESIZE(x) (SDL_AUDIO_BYTESIZE((x).format) * (x).channels)
425
426/**
427 * The opaque handle that represents an audio stream.
428 *
429 * SDL_AudioStream is an audio conversion interface.
430 *
431 * - It can handle resampling data in chunks without generating artifacts,
432 * when it doesn't have the complete buffer available.
433 * - It can handle incoming data in any variable size.
434 * - It can handle input/output format changes on the fly.
435 * - It can remap audio channels between inputs and outputs.
436 * - You push data as you have it, and pull it when you need it
437 * - It can also function as a basic audio data queue even if you just have
438 * sound that needs to pass from one place to another.
439 * - You can hook callbacks up to them when more data is added or requested,
440 * to manage data on-the-fly.
441 *
442 * Audio streams are the core of the SDL3 audio interface. You create one or
443 * more of them, bind them to an opened audio device, and feed data to them
444 * (or for recording, consume data from them).
445 *
446 * \since This struct is available since SDL 3.2.0.
447 *
448 * \sa SDL_CreateAudioStream
449 */
450typedef struct SDL_AudioStream SDL_AudioStream;
451
452
453/* Function prototypes */
454
455/**
456 * Use this function to get the number of built-in audio drivers.
457 *
458 * This function returns a hardcoded number. This never returns a negative
459 * value; if there are no drivers compiled into this build of SDL, this
460 * function returns zero. The presence of a driver in this list does not mean
461 * it will function, it just means SDL is capable of interacting with that
462 * interface. For example, a build of SDL might have esound support, but if
463 * there's no esound server available, SDL's esound driver would fail if used.
464 *
465 * By default, SDL tries all drivers, in its preferred order, until one is
466 * found to be usable.
467 *
468 * \returns the number of built-in audio drivers.
469 *
470 * \threadsafety It is safe to call this function from any thread.
471 *
472 * \since This function is available since SDL 3.2.0.
473 *
474 * \sa SDL_GetAudioDriver
475 */
476extern SDL_DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
477
478/**
479 * Use this function to get the name of a built in audio driver.
480 *
481 * The list of audio drivers is given in the order that they are normally
482 * initialized by default; the drivers that seem more reasonable to choose
483 * first (as far as the SDL developers believe) are earlier in the list.
484 *
485 * The names of drivers are all simple, low-ASCII identifiers, like "alsa",
486 * "coreaudio" or "wasapi". These never have Unicode characters, and are not
487 * meant to be proper names.
488 *
489 * \param index the index of the audio driver; the value ranges from 0 to
490 * SDL_GetNumAudioDrivers() - 1.
491 * \returns the name of the audio driver at the requested index, or NULL if an
492 * invalid index was specified.
493 *
494 * \threadsafety It is safe to call this function from any thread.
495 *
496 * \since This function is available since SDL 3.2.0.
497 *
498 * \sa SDL_GetNumAudioDrivers
499 */
500extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDriver(int index);
501
502/**
503 * Get the name of the current audio driver.
504 *
505 * The names of drivers are all simple, low-ASCII identifiers, like "alsa",
506 * "coreaudio" or "wasapi". These never have Unicode characters, and are not
507 * meant to be proper names.
508 *
509 * \returns the name of the current audio driver or NULL if no driver has been
510 * initialized.
511 *
512 * \threadsafety It is safe to call this function from any thread.
513 *
514 * \since This function is available since SDL 3.2.0.
515 */
516extern SDL_DECLSPEC const char * SDLCALL SDL_GetCurrentAudioDriver(void);
517
518/**
519 * Get a list of currently-connected audio playback devices.
520 *
521 * This returns of list of available devices that play sound, perhaps to
522 * speakers or headphones ("playback" devices). If you want devices that
523 * record audio, like a microphone ("recording" devices), use
524 * SDL_GetAudioRecordingDevices() instead.
525 *
526 * This only returns a list of physical devices; it will not have any device
527 * IDs returned by SDL_OpenAudioDevice().
528 *
529 * If this function returns NULL, to signify an error, `*count` will be set to
530 * zero.
531 *
532 * \param count a pointer filled in with the number of devices returned, may
533 * be NULL.
534 * \returns a 0 terminated array of device instance IDs or NULL on error; call
535 * SDL_GetError() for more information. This should be freed with
536 * SDL_free() when it is no longer needed.
537 *
538 * \threadsafety It is safe to call this function from any thread.
539 *
540 * \since This function is available since SDL 3.2.0.
541 *
542 * \sa SDL_OpenAudioDevice
543 * \sa SDL_GetAudioRecordingDevices
544 */
545extern SDL_DECLSPEC SDL_AudioDeviceID * SDLCALL SDL_GetAudioPlaybackDevices(int *count);
546
547/**
548 * Get a list of currently-connected audio recording devices.
549 *
550 * This returns of list of available devices that record audio, like a
551 * microphone ("recording" devices). If you want devices that play sound,
552 * perhaps to speakers or headphones ("playback" devices), use
553 * SDL_GetAudioPlaybackDevices() instead.
554 *
555 * This only returns a list of physical devices; it will not have any device
556 * IDs returned by SDL_OpenAudioDevice().
557 *
558 * If this function returns NULL, to signify an error, `*count` will be set to
559 * zero.
560 *
561 * \param count a pointer filled in with the number of devices returned, may
562 * be NULL.
563 * \returns a 0 terminated array of device instance IDs, or NULL on failure;
564 * call SDL_GetError() for more information. This should be freed
565 * with SDL_free() when it is no longer needed.
566 *
567 * \threadsafety It is safe to call this function from any thread.
568 *
569 * \since This function is available since SDL 3.2.0.
570 *
571 * \sa SDL_OpenAudioDevice
572 * \sa SDL_GetAudioPlaybackDevices
573 */
574extern SDL_DECLSPEC SDL_AudioDeviceID * SDLCALL SDL_GetAudioRecordingDevices(int *count);
575
576/**
577 * Get the human-readable name of a specific audio device.
578 *
579 * **WARNING**: this function will work with SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK
580 * and SDL_AUDIO_DEVICE_DEFAULT_RECORDING, returning the current default
581 * physical devices' names. However, as the default device may change at any
582 * time, it is likely better to show a generic name to the user, like "System
583 * default audio device" or perhaps "default [currently %s]". Do not store
584 * this name to disk to reidentify the device in a later run of the program,
585 * as the default might change in general, and the string will be the name of
586 * a specific device and not the abstract system default.
587 *
588 * \param devid the instance ID of the device to query.
589 * \returns the name of the audio device, or NULL on failure; call
590 * SDL_GetError() for more information.
591 *
592 * \threadsafety It is safe to call this function from any thread.
593 *
594 * \since This function is available since SDL 3.2.0.
595 *
596 * \sa SDL_GetAudioPlaybackDevices
597 * \sa SDL_GetAudioRecordingDevices
598 */
599extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceID devid);
600
601/**
602 * Get the current audio format of a specific audio device.
603 *
604 * For an opened device, this will report the format the device is currently
605 * using. If the device isn't yet opened, this will report the device's
606 * preferred format (or a reasonable default if this can't be determined).
607 *
608 * You may also specify SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK or
609 * SDL_AUDIO_DEVICE_DEFAULT_RECORDING here, which is useful for getting a
610 * reasonable recommendation before opening the system-recommended default
611 * device.
612 *
613 * You can also use this to request the current device buffer size. This is
614 * specified in sample frames and represents the amount of data SDL will feed
615 * to the physical hardware in each chunk. This can be converted to
616 * milliseconds of audio with the following equation:
617 *
618 * `ms = (int) ((((Sint64) frames) * 1000) / spec.freq);`
619 *
620 * Buffer size is only important if you need low-level control over the audio
621 * playback timing. Most apps do not need this.
622 *
623 * \param devid the instance ID of the device to query.
624 * \param spec on return, will be filled with device details.
625 * \param sample_frames pointer to store device buffer size, in sample frames.
626 * Can be NULL.
627 * \returns true on success or false on failure; call SDL_GetError() for more
628 * information.
629 *
630 * \threadsafety It is safe to call this function from any thread.
631 *
632 * \since This function is available since SDL 3.2.0.
633 */
634extern SDL_DECLSPEC bool SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SDL_AudioSpec *spec, int *sample_frames);
635
636/**
637 * Get the current channel map of an audio device.
638 *
639 * Channel maps are optional; most things do not need them, instead passing
640 * data in the [order that SDL expects](CategoryAudio#channel-layouts).
641 *
642 * Audio devices usually have no remapping applied. This is represented by
643 * returning NULL, and does not signify an error.
644 *
645 * \param devid the instance ID of the device to query.
646 * \param count On output, set to number of channels in the map. Can be NULL.
647 * \returns an array of the current channel mapping, with as many elements as
648 * the current output spec's channels, or NULL if default. This
649 * should be freed with SDL_free() when it is no longer needed.
650 *
651 * \threadsafety It is safe to call this function from any thread.
652 *
653 * \since This function is available since SDL 3.2.0.
654 *
655 * \sa SDL_SetAudioStreamInputChannelMap
656 */
657extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioDeviceChannelMap(SDL_AudioDeviceID devid, int *count);
658
659/**
660 * Open a specific audio device.
661 *
662 * You can open both playback and recording devices through this function.
663 * Playback devices will take data from bound audio streams, mix it, and send
664 * it to the hardware. Recording devices will feed any bound audio streams
665 * with a copy of any incoming data.
666 *
667 * An opened audio device starts out with no audio streams bound. To start
668 * audio playing, bind a stream and supply audio data to it. Unlike SDL2,
669 * there is no audio callback; you only bind audio streams and make sure they
670 * have data flowing into them (however, you can simulate SDL2's semantics
671 * fairly closely by using SDL_OpenAudioDeviceStream instead of this
672 * function).
673 *
674 * If you don't care about opening a specific device, pass a `devid` of either
675 * `SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK` or
676 * `SDL_AUDIO_DEVICE_DEFAULT_RECORDING`. In this case, SDL will try to pick
677 * the most reasonable default, and may also switch between physical devices
678 * seamlessly later, if the most reasonable default changes during the
679 * lifetime of this opened device (user changed the default in the OS's system
680 * preferences, the default got unplugged so the system jumped to a new
681 * default, the user plugged in headphones on a mobile device, etc). Unless
682 * you have a good reason to choose a specific device, this is probably what
683 * you want.
684 *
685 * You may request a specific format for the audio device, but there is no
686 * promise the device will honor that request for several reasons. As such,
687 * it's only meant to be a hint as to what data your app will provide. Audio
688 * streams will accept data in whatever format you specify and manage
689 * conversion for you as appropriate. SDL_GetAudioDeviceFormat can tell you
690 * the preferred format for the device before opening and the actual format
691 * the device is using after opening.
692 *
693 * It's legal to open the same device ID more than once; each successful open
694 * will generate a new logical SDL_AudioDeviceID that is managed separately
695 * from others on the same physical device. This allows libraries to open a
696 * device separately from the main app and bind its own streams without
697 * conflicting.
698 *
699 * It is also legal to open a device ID returned by a previous call to this
700 * function; doing so just creates another logical device on the same physical
701 * device. This may be useful for making logical groupings of audio streams.
702 *
703 * This function returns the opened device ID on success. This is a new,
704 * unique SDL_AudioDeviceID that represents a logical device.
705 *
706 * Some backends might offer arbitrary devices (for example, a networked audio
707 * protocol that can connect to an arbitrary server). For these, as a change
708 * from SDL2, you should open a default device ID and use an SDL hint to
709 * specify the target if you care, or otherwise let the backend figure out a
710 * reasonable default. Most backends don't offer anything like this, and often
711 * this would be an end user setting an environment variable for their custom
712 * need, and not something an application should specifically manage.
713 *
714 * When done with an audio device, possibly at the end of the app's life, one
715 * should call SDL_CloseAudioDevice() on the returned device id.
716 *
717 * \param devid the device instance id to open, or
718 * SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK or
719 * SDL_AUDIO_DEVICE_DEFAULT_RECORDING for the most reasonable
720 * default device.
721 * \param spec the requested device configuration. Can be NULL to use
722 * reasonable defaults.
723 * \returns the device ID on success or 0 on failure; call SDL_GetError() for
724 * more information.
725 *
726 * \threadsafety It is safe to call this function from any thread.
727 *
728 * \since This function is available since SDL 3.2.0.
729 *
730 * \sa SDL_CloseAudioDevice
731 * \sa SDL_GetAudioDeviceFormat
732 */
733extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec);
734
735/**
736 * Determine if an audio device is physical (instead of logical).
737 *
738 * An SDL_AudioDeviceID that represents physical hardware is a physical
739 * device; there is one for each piece of hardware that SDL can see. Logical
740 * devices are created by calling SDL_OpenAudioDevice or
741 * SDL_OpenAudioDeviceStream, and while each is associated with a physical
742 * device, there can be any number of logical devices on one physical device.
743 *
744 * For the most part, logical and physical IDs are interchangeable--if you try
745 * to open a logical device, SDL understands to assign that effort to the
746 * underlying physical device, etc. However, it might be useful to know if an
747 * arbitrary device ID is physical or logical. This function reports which.
748 *
749 * This function may return either true or false for invalid device IDs.
750 *
751 * \param devid the device ID to query.
752 * \returns true if devid is a physical device, false if it is logical.
753 *
754 * \threadsafety It is safe to call this function from any thread.
755 *
756 * \since This function is available since SDL 3.2.0.
757 */
758extern SDL_DECLSPEC bool SDLCALL SDL_IsAudioDevicePhysical(SDL_AudioDeviceID devid);
759
760/**
761 * Determine if an audio device is a playback device (instead of recording).
762 *
763 * This function may return either true or false for invalid device IDs.
764 *
765 * \param devid the device ID to query.
766 * \returns true if devid is a playback device, false if it is recording.
767 *
768 * \threadsafety It is safe to call this function from any thread.
769 *
770 * \since This function is available since SDL 3.2.0.
771 */
772extern SDL_DECLSPEC bool SDLCALL SDL_IsAudioDevicePlayback(SDL_AudioDeviceID devid);
773
774/**
775 * Use this function to pause audio playback on a specified device.
776 *
777 * This function pauses audio processing for a given device. Any bound audio
778 * streams will not progress, and no audio will be generated. Pausing one
779 * device does not prevent other unpaused devices from running.
780 *
781 * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app
782 * has to bind a stream before any audio will flow. Pausing a paused device is
783 * a legal no-op.
784 *
785 * Pausing a device can be useful to halt all audio without unbinding all the
786 * audio streams. This might be useful while a game is paused, or a level is
787 * loading, etc.
788 *
789 * Physical devices can not be paused or unpaused, only logical devices
790 * created through SDL_OpenAudioDevice() can be.
791 *
792 * \param devid a device opened by SDL_OpenAudioDevice().
793 * \returns true on success or false on failure; call SDL_GetError() for more
794 * information.
795 *
796 * \threadsafety It is safe to call this function from any thread.
797 *
798 * \since This function is available since SDL 3.2.0.
799 *
800 * \sa SDL_ResumeAudioDevice
801 * \sa SDL_AudioDevicePaused
802 */
803extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID devid);
804
805/**
806 * Use this function to unpause audio playback on a specified device.
807 *
808 * This function unpauses audio processing for a given device that has
809 * previously been paused with SDL_PauseAudioDevice(). Once unpaused, any
810 * bound audio streams will begin to progress again, and audio can be
811 * generated.
812 *
813 * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app
814 * has to bind a stream before any audio will flow. Unpausing an unpaused
815 * device is a legal no-op.
816 *
817 * Physical devices can not be paused or unpaused, only logical devices
818 * created through SDL_OpenAudioDevice() can be.
819 *
820 * \param devid a device opened by SDL_OpenAudioDevice().
821 * \returns true on success or false on failure; call SDL_GetError() for more
822 * information.
823 *
824 * \threadsafety It is safe to call this function from any thread.
825 *
826 * \since This function is available since SDL 3.2.0.
827 *
828 * \sa SDL_AudioDevicePaused
829 * \sa SDL_PauseAudioDevice
830 */
831extern SDL_DECLSPEC bool SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID devid);
832
833/**
834 * Use this function to query if an audio device is paused.
835 *
836 * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app
837 * has to bind a stream before any audio will flow.
838 *
839 * Physical devices can not be paused or unpaused, only logical devices
840 * created through SDL_OpenAudioDevice() can be. Physical and invalid device
841 * IDs will report themselves as unpaused here.
842 *
843 * \param devid a device opened by SDL_OpenAudioDevice().
844 * \returns true if device is valid and paused, false otherwise.
845 *
846 * \threadsafety It is safe to call this function from any thread.
847 *
848 * \since This function is available since SDL 3.2.0.
849 *
850 * \sa SDL_PauseAudioDevice
851 * \sa SDL_ResumeAudioDevice
852 */
853extern SDL_DECLSPEC bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID devid);
854
855/**
856 * Get the gain of an audio device.
857 *
858 * The gain of a device is its volume; a larger gain means a louder output,
859 * with a gain of zero being silence.
860 *
861 * Audio devices default to a gain of 1.0f (no change in output).
862 *
863 * Physical devices may not have their gain changed, only logical devices, and
864 * this function will always return -1.0f when used on physical devices.
865 *
866 * \param devid the audio device to query.
867 * \returns the gain of the device or -1.0f on failure; call SDL_GetError()
868 * for more information.
869 *
870 * \threadsafety It is safe to call this function from any thread.
871 *
872 * \since This function is available since SDL 3.2.0.
873 *
874 * \sa SDL_SetAudioDeviceGain
875 */
876extern SDL_DECLSPEC float SDLCALL SDL_GetAudioDeviceGain(SDL_AudioDeviceID devid);
877
878/**
879 * Change the gain of an audio device.
880 *
881 * The gain of a device is its volume; a larger gain means a louder output,
882 * with a gain of zero being silence.
883 *
884 * Audio devices default to a gain of 1.0f (no change in output).
885 *
886 * Physical devices may not have their gain changed, only logical devices, and
887 * this function will always return false when used on physical devices. While
888 * it might seem attractive to adjust several logical devices at once in this
889 * way, it would allow an app or library to interfere with another portion of
890 * the program's otherwise-isolated devices.
891 *
892 * This is applied, along with any per-audiostream gain, during playback to
893 * the hardware, and can be continuously changed to create various effects. On
894 * recording devices, this will adjust the gain before passing the data into
895 * an audiostream; that recording audiostream can then adjust its gain further
896 * when outputting the data elsewhere, if it likes, but that second gain is
897 * not applied until the data leaves the audiostream again.
898 *
899 * \param devid the audio device on which to change gain.
900 * \param gain the gain. 1.0f is no change, 0.0f is silence.
901 * \returns true on success or false on failure; call SDL_GetError() for more
902 * information.
903 *
904 * \threadsafety It is safe to call this function from any thread, as it holds
905 * a stream-specific mutex while running.
906 *
907 * \since This function is available since SDL 3.2.0.
908 *
909 * \sa SDL_GetAudioDeviceGain
910 */
911extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioDeviceGain(SDL_AudioDeviceID devid, float gain);
912
913/**
914 * Close a previously-opened audio device.
915 *
916 * The application should close open audio devices once they are no longer
917 * needed.
918 *
919 * This function may block briefly while pending audio data is played by the
920 * hardware, so that applications don't drop the last buffer of data they
921 * supplied if terminating immediately afterwards.
922 *
923 * \param devid an audio device id previously returned by
924 * SDL_OpenAudioDevice().
925 *
926 * \threadsafety It is safe to call this function from any thread.
927 *
928 * \since This function is available since SDL 3.2.0.
929 *
930 * \sa SDL_OpenAudioDevice
931 */
932extern SDL_DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid);
933
934/**
935 * Bind a list of audio streams to an audio device.
936 *
937 * Audio data will flow through any bound streams. For a playback device, data
938 * for all bound streams will be mixed together and fed to the device. For a
939 * recording device, a copy of recorded data will be provided to each bound
940 * stream.
941 *
942 * Audio streams can only be bound to an open device. This operation is
943 * atomic--all streams bound in the same call will start processing at the
944 * same time, so they can stay in sync. Also: either all streams will be bound
945 * or none of them will be.
946 *
947 * It is an error to bind an already-bound stream; it must be explicitly
948 * unbound first.
949 *
950 * Binding a stream to a device will set its output format for playback
951 * devices, and its input format for recording devices, so they match the
952 * device's settings. The caller is welcome to change the other end of the
953 * stream's format at any time with SDL_SetAudioStreamFormat(). If the other
954 * end of the stream's format has never been set (the audio stream was created
955 * with a NULL audio spec), this function will set it to match the device
956 * end's format.
957 *
958 * \param devid an audio device to bind a stream to.
959 * \param streams an array of audio streams to bind.
960 * \param num_streams number streams listed in the `streams` array.
961 * \returns true on success or false on failure; call SDL_GetError() for more
962 * information.
963 *
964 * \threadsafety It is safe to call this function from any thread.
965 *
966 * \since This function is available since SDL 3.2.0.
967 *
968 * \sa SDL_BindAudioStreams
969 * \sa SDL_UnbindAudioStream
970 * \sa SDL_GetAudioStreamDevice
971 */
972extern SDL_DECLSPEC bool SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SDL_AudioStream * const *streams, int num_streams);
973
974/**
975 * Bind a single audio stream to an audio device.
976 *
977 * This is a convenience function, equivalent to calling
978 * `SDL_BindAudioStreams(devid, &stream, 1)`.
979 *
980 * \param devid an audio device to bind a stream to.
981 * \param stream an audio stream to bind to a device.
982 * \returns true on success or false on failure; call SDL_GetError() for more
983 * information.
984 *
985 * \threadsafety It is safe to call this function from any thread.
986 *
987 * \since This function is available since SDL 3.2.0.
988 *
989 * \sa SDL_BindAudioStreams
990 * \sa SDL_UnbindAudioStream
991 * \sa SDL_GetAudioStreamDevice
992 */
993extern SDL_DECLSPEC bool SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_AudioStream *stream);
994
995/**
996 * Unbind a list of audio streams from their audio devices.
997 *
998 * The streams being unbound do not all have to be on the same device. All
999 * streams on the same device will be unbound atomically (data will stop
1000 * flowing through all unbound streams on the same device at the same time).
1001 *
1002 * Unbinding a stream that isn't bound to a device is a legal no-op.
1003 *
1004 * \param streams an array of audio streams to unbind. Can be NULL or contain
1005 * NULL.
1006 * \param num_streams number streams listed in the `streams` array.
1007 *
1008 * \threadsafety It is safe to call this function from any thread.
1009 *
1010 * \since This function is available since SDL 3.2.0.
1011 *
1012 * \sa SDL_BindAudioStreams
1013 */
1014extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStreams(SDL_AudioStream * const *streams, int num_streams);
1015
1016/**
1017 * Unbind a single audio stream from its audio device.
1018 *
1019 * This is a convenience function, equivalent to calling
1020 * `SDL_UnbindAudioStreams(&stream, 1)`.
1021 *
1022 * \param stream an audio stream to unbind from a device. Can be NULL.
1023 *
1024 * \threadsafety It is safe to call this function from any thread.
1025 *
1026 * \since This function is available since SDL 3.2.0.
1027 *
1028 * \sa SDL_BindAudioStream
1029 */
1030extern SDL_DECLSPEC void SDLCALL SDL_UnbindAudioStream(SDL_AudioStream *stream);
1031
1032/**
1033 * Query an audio stream for its currently-bound device.
1034 *
1035 * This reports the logical audio device that an audio stream is currently
1036 * bound to.
1037 *
1038 * If not bound, or invalid, this returns zero, which is not a valid device
1039 * ID.
1040 *
1041 * \param stream the audio stream to query.
1042 * \returns the bound audio device, or 0 if not bound or invalid.
1043 *
1044 * \threadsafety It is safe to call this function from any thread.
1045 *
1046 * \since This function is available since SDL 3.2.0.
1047 *
1048 * \sa SDL_BindAudioStream
1049 * \sa SDL_BindAudioStreams
1050 */
1051extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_GetAudioStreamDevice(SDL_AudioStream *stream);
1052
1053/**
1054 * Create a new audio stream.
1055 *
1056 * \param src_spec the format details of the input audio.
1057 * \param dst_spec the format details of the output audio.
1058 * \returns a new audio stream on success or NULL on failure; call
1059 * SDL_GetError() for more information.
1060 *
1061 * \threadsafety It is safe to call this function from any thread.
1062 *
1063 * \since This function is available since SDL 3.2.0.
1064 *
1065 * \sa SDL_PutAudioStreamData
1066 * \sa SDL_GetAudioStreamData
1067 * \sa SDL_GetAudioStreamAvailable
1068 * \sa SDL_FlushAudioStream
1069 * \sa SDL_ClearAudioStream
1070 * \sa SDL_SetAudioStreamFormat
1071 * \sa SDL_DestroyAudioStream
1072 */
1073extern SDL_DECLSPEC SDL_AudioStream * SDLCALL SDL_CreateAudioStream(const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec);
1074
1075/**
1076 * Get the properties associated with an audio stream.
1077 *
1078 * The application can hang any data it wants here, but the following
1079 * properties are understood by SDL:
1080 *
1081 * - `SDL_PROP_AUDIOSTREAM_AUTO_CLEANUP_BOOLEAN`: if true (the default), the
1082 * stream be automatically cleaned up when the audio subsystem quits. If set
1083 * to false, the streams will persist beyond that. This property is ignored
1084 * for streams created through SDL_OpenAudioDeviceStream(), and will always
1085 * be cleaned up. Streams that are not cleaned up will still be unbound from
1086 * devices when the audio subsystem quits. This property was added in SDL
1087 * 3.4.0.
1088 *
1089 * \param stream the SDL_AudioStream to query.
1090 * \returns a valid property ID on success or 0 on failure; call
1091 * SDL_GetError() for more information.
1092 *
1093 * \threadsafety It is safe to call this function from any thread.
1094 *
1095 * \since This function is available since SDL 3.2.0.
1096 */
1097extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetAudioStreamProperties(SDL_AudioStream *stream);
1098
1099#define SDL_PROP_AUDIOSTREAM_AUTO_CLEANUP_BOOLEAN "SDL.audiostream.auto_cleanup"
1100
1101
1102/**
1103 * Query the current format of an audio stream.
1104 *
1105 * \param stream the SDL_AudioStream to query.
1106 * \param src_spec where to store the input audio format; ignored if NULL.
1107 * \param dst_spec where to store the output audio format; ignored if NULL.
1108 * \returns true on success or false on failure; call SDL_GetError() for more
1109 * information.
1110 *
1111 * \threadsafety It is safe to call this function from any thread, as it holds
1112 * a stream-specific mutex while running.
1113 *
1114 * \since This function is available since SDL 3.2.0.
1115 *
1116 * \sa SDL_SetAudioStreamFormat
1117 */
1118extern SDL_DECLSPEC bool SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioSpec *src_spec, SDL_AudioSpec *dst_spec);
1119
1120/**
1121 * Change the input and output formats of an audio stream.
1122 *
1123 * Future calls to and SDL_GetAudioStreamAvailable and SDL_GetAudioStreamData
1124 * will reflect the new format, and future calls to SDL_PutAudioStreamData
1125 * must provide data in the new input formats.
1126 *
1127 * Data that was previously queued in the stream will still be operated on in
1128 * the format that was current when it was added, which is to say you can put
1129 * the end of a sound file in one format to a stream, change formats for the
1130 * next sound file, and start putting that new data while the previous sound
1131 * file is still queued, and everything will still play back correctly.
1132 *
1133 * If a stream is bound to a device, then the format of the side of the stream
1134 * bound to a device cannot be changed (src_spec for recording devices,
1135 * dst_spec for playback devices). Attempts to make a change to this side will
1136 * be ignored, but this will not report an error. The other side's format can
1137 * be changed.
1138 *
1139 * \param stream the stream the format is being changed.
1140 * \param src_spec the new format of the audio input; if NULL, it is not
1141 * changed.
1142 * \param dst_spec the new format of the audio output; if NULL, it is not
1143 * changed.
1144 * \returns true on success or false on failure; call SDL_GetError() for more
1145 * information.
1146 *
1147 * \threadsafety It is safe to call this function from any thread, as it holds
1148 * a stream-specific mutex while running.
1149 *
1150 * \since This function is available since SDL 3.2.0.
1151 *
1152 * \sa SDL_GetAudioStreamFormat
1153 * \sa SDL_SetAudioStreamFrequencyRatio
1154 */
1155extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream, const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec);
1156
1157/**
1158 * Get the frequency ratio of an audio stream.
1159 *
1160 * \param stream the SDL_AudioStream to query.
1161 * \returns the frequency ratio of the stream or 0.0 on failure; call
1162 * SDL_GetError() for more information.
1163 *
1164 * \threadsafety It is safe to call this function from any thread, as it holds
1165 * a stream-specific mutex while running.
1166 *
1167 * \since This function is available since SDL 3.2.0.
1168 *
1169 * \sa SDL_SetAudioStreamFrequencyRatio
1170 */
1171extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamFrequencyRatio(SDL_AudioStream *stream);
1172
1173/**
1174 * Change the frequency ratio of an audio stream.
1175 *
1176 * The frequency ratio is used to adjust the rate at which input data is
1177 * consumed. Changing this effectively modifies the speed and pitch of the
1178 * audio. A value greater than 1.0f will play the audio faster, and at a
1179 * higher pitch. A value less than 1.0f will play the audio slower, and at a
1180 * lower pitch. 1.0f means play at normal speed.
1181 *
1182 * This is applied during SDL_GetAudioStreamData, and can be continuously
1183 * changed to create various effects.
1184 *
1185 * \param stream the stream on which the frequency ratio is being changed.
1186 * \param ratio the frequency ratio. 1.0 is normal speed. Must be between 0.01
1187 * and 100.
1188 * \returns true on success or false on failure; call SDL_GetError() for more
1189 * information.
1190 *
1191 * \threadsafety It is safe to call this function from any thread, as it holds
1192 * a stream-specific mutex while running.
1193 *
1194 * \since This function is available since SDL 3.2.0.
1195 *
1196 * \sa SDL_GetAudioStreamFrequencyRatio
1197 * \sa SDL_SetAudioStreamFormat
1198 */
1199extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream *stream, float ratio);
1200
1201/**
1202 * Get the gain of an audio stream.
1203 *
1204 * The gain of a stream is its volume; a larger gain means a louder output,
1205 * with a gain of zero being silence.
1206 *
1207 * Audio streams default to a gain of 1.0f (no change in output).
1208 *
1209 * \param stream the SDL_AudioStream to query.
1210 * \returns the gain of the stream or -1.0f on failure; call SDL_GetError()
1211 * for more information.
1212 *
1213 * \threadsafety It is safe to call this function from any thread, as it holds
1214 * a stream-specific mutex while running.
1215 *
1216 * \since This function is available since SDL 3.2.0.
1217 *
1218 * \sa SDL_SetAudioStreamGain
1219 */
1220extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamGain(SDL_AudioStream *stream);
1221
1222/**
1223 * Change the gain of an audio stream.
1224 *
1225 * The gain of a stream is its volume; a larger gain means a louder output,
1226 * with a gain of zero being silence.
1227 *
1228 * Audio streams default to a gain of 1.0f (no change in output).
1229 *
1230 * This is applied during SDL_GetAudioStreamData, and can be continuously
1231 * changed to create various effects.
1232 *
1233 * \param stream the stream on which the gain is being changed.
1234 * \param gain the gain. 1.0f is no change, 0.0f is silence.
1235 * \returns true on success or false on failure; call SDL_GetError() for more
1236 * information.
1237 *
1238 * \threadsafety It is safe to call this function from any thread, as it holds
1239 * a stream-specific mutex while running.
1240 *
1241 * \since This function is available since SDL 3.2.0.
1242 *
1243 * \sa SDL_GetAudioStreamGain
1244 */
1245extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamGain(SDL_AudioStream *stream, float gain);
1246
1247/**
1248 * Get the current input channel map of an audio stream.
1249 *
1250 * Channel maps are optional; most things do not need them, instead passing
1251 * data in the [order that SDL expects](CategoryAudio#channel-layouts).
1252 *
1253 * Audio streams default to no remapping applied. This is represented by
1254 * returning NULL, and does not signify an error.
1255 *
1256 * \param stream the SDL_AudioStream to query.
1257 * \param count On output, set to number of channels in the map. Can be NULL.
1258 * \returns an array of the current channel mapping, with as many elements as
1259 * the current output spec's channels, or NULL if default. This
1260 * should be freed with SDL_free() when it is no longer needed.
1261 *
1262 * \threadsafety It is safe to call this function from any thread, as it holds
1263 * a stream-specific mutex while running.
1264 *
1265 * \since This function is available since SDL 3.2.0.
1266 *
1267 * \sa SDL_SetAudioStreamInputChannelMap
1268 */
1269extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamInputChannelMap(SDL_AudioStream *stream, int *count);
1270
1271/**
1272 * Get the current output channel map of an audio stream.
1273 *
1274 * Channel maps are optional; most things do not need them, instead passing
1275 * data in the [order that SDL expects](CategoryAudio#channel-layouts).
1276 *
1277 * Audio streams default to no remapping applied. This is represented by
1278 * returning NULL, and does not signify an error.
1279 *
1280 * \param stream the SDL_AudioStream to query.
1281 * \param count On output, set to number of channels in the map. Can be NULL.
1282 * \returns an array of the current channel mapping, with as many elements as
1283 * the current output spec's channels, or NULL if default. This
1284 * should be freed with SDL_free() when it is no longer needed.
1285 *
1286 * \threadsafety It is safe to call this function from any thread, as it holds
1287 * a stream-specific mutex while running.
1288 *
1289 * \since This function is available since SDL 3.2.0.
1290 *
1291 * \sa SDL_SetAudioStreamInputChannelMap
1292 */
1293extern SDL_DECLSPEC int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_AudioStream *stream, int *count);
1294
1295/**
1296 * Set the current input channel map of an audio stream.
1297 *
1298 * Channel maps are optional; most things do not need them, instead passing
1299 * data in the [order that SDL expects](CategoryAudio#channel-layouts).
1300 *
1301 * The input channel map reorders data that is added to a stream via
1302 * SDL_PutAudioStreamData. Future calls to SDL_PutAudioStreamData must provide
1303 * data in the new channel order.
1304 *
1305 * Each item in the array represents an input channel, and its value is the
1306 * channel that it should be remapped to. To reverse a stereo signal's left
1307 * and right values, you'd have an array of `{ 1, 0 }`. It is legal to remap
1308 * multiple channels to the same thing, so `{ 1, 1 }` would duplicate the
1309 * right channel to both channels of a stereo signal. An element in the
1310 * channel map set to -1 instead of a valid channel will mute that channel,
1311 * setting it to a silence value.
1312 *
1313 * You cannot change the number of channels through a channel map, just
1314 * reorder/mute them.
1315 *
1316 * Data that was previously queued in the stream will still be operated on in
1317 * the order that was current when it was added, which is to say you can put
1318 * the end of a sound file in one order to a stream, change orders for the
1319 * next sound file, and start putting that new data while the previous sound
1320 * file is still queued, and everything will still play back correctly.
1321 *
1322 * Audio streams default to no remapping applied. Passing a NULL channel map
1323 * is legal, and turns off remapping.
1324 *
1325 * SDL will copy the channel map; the caller does not have to save this array
1326 * after this call.
1327 *
1328 * If `count` is not equal to the current number of channels in the audio
1329 * stream's format, this will fail. This is a safety measure to make sure a
1330 * race condition hasn't changed the format while this call is setting the
1331 * channel map.
1332 *
1333 * Unlike attempting to change the stream's format, the input channel map on a
1334 * stream bound to a recording device is permitted to change at any time; any
1335 * data added to the stream from the device after this call will have the new
1336 * mapping, but previously-added data will still have the prior mapping.
1337 *
1338 * \param stream the SDL_AudioStream to change.
1339 * \param chmap the new channel map, NULL to reset to default.
1340 * \param count The number of channels in the map.
1341 * \returns true on success or false on failure; call SDL_GetError() for more
1342 * information.
1343 *
1344 * \threadsafety It is safe to call this function from any thread, as it holds
1345 * a stream-specific mutex while running. Don't change the
1346 * stream's format to have a different number of channels from a
1347 * different thread at the same time, though!
1348 *
1349 * \since This function is available since SDL 3.2.0.
1350 *
1351 * \sa SDL_SetAudioStreamOutputChannelMap
1352 */
1353extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_AudioStream *stream, const int *chmap, int count);
1354
1355/**
1356 * Set the current output channel map of an audio stream.
1357 *
1358 * Channel maps are optional; most things do not need them, instead passing
1359 * data in the [order that SDL expects](CategoryAudio#channel-layouts).
1360 *
1361 * The output channel map reorders data that is leaving a stream via
1362 * SDL_GetAudioStreamData.
1363 *
1364 * Each item in the array represents an input channel, and its value is the
1365 * channel that it should be remapped to. To reverse a stereo signal's left
1366 * and right values, you'd have an array of `{ 1, 0 }`. It is legal to remap
1367 * multiple channels to the same thing, so `{ 1, 1 }` would duplicate the
1368 * right channel to both channels of a stereo signal. An element in the
1369 * channel map set to -1 instead of a valid channel will mute that channel,
1370 * setting it to a silence value.
1371 *
1372 * You cannot change the number of channels through a channel map, just
1373 * reorder/mute them.
1374 *
1375 * The output channel map can be changed at any time, as output remapping is
1376 * applied during SDL_GetAudioStreamData.
1377 *
1378 * Audio streams default to no remapping applied. Passing a NULL channel map
1379 * is legal, and turns off remapping.
1380 *
1381 * SDL will copy the channel map; the caller does not have to save this array
1382 * after this call.
1383 *
1384 * If `count` is not equal to the current number of channels in the audio
1385 * stream's format, this will fail. This is a safety measure to make sure a
1386 * race condition hasn't changed the format while this call is setting the
1387 * channel map.
1388 *
1389 * Unlike attempting to change the stream's format, the output channel map on
1390 * a stream bound to a recording device is permitted to change at any time;
1391 * any data added to the stream after this call will have the new mapping, but
1392 * previously-added data will still have the prior mapping. When the channel
1393 * map doesn't match the hardware's channel layout, SDL will convert the data
1394 * before feeding it to the device for playback.
1395 *
1396 * \param stream the SDL_AudioStream to change.
1397 * \param chmap the new channel map, NULL to reset to default.
1398 * \param count The number of channels in the map.
1399 * \returns true on success or false on failure; call SDL_GetError() for more
1400 * information.
1401 *
1402 * \threadsafety It is safe to call this function from any thread, as it holds
1403 * a stream-specific mutex while running. Don't change the
1404 * stream's format to have a different number of channels from a
1405 * a different thread at the same time, though!
1406 *
1407 * \since This function is available since SDL 3.2.0.
1408 *
1409 * \sa SDL_SetAudioStreamInputChannelMap
1410 */
1411extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamOutputChannelMap(SDL_AudioStream *stream, const int *chmap, int count);
1412
1413/**
1414 * Add data to the stream.
1415 *
1416 * This data must match the format/channels/samplerate specified in the latest
1417 * call to SDL_SetAudioStreamFormat, or the format specified when creating the
1418 * stream if it hasn't been changed.
1419 *
1420 * Note that this call simply copies the unconverted data for later. This is
1421 * different than SDL2, where data was converted during the Put call and the
1422 * Get call would just dequeue the previously-converted data.
1423 *
1424 * \param stream the stream the audio data is being added to.
1425 * \param buf a pointer to the audio data to add.
1426 * \param len the number of bytes to write to the stream.
1427 * \returns true on success or false on failure; call SDL_GetError() for more
1428 * information.
1429 *
1430 * \threadsafety It is safe to call this function from any thread, but if the
1431 * stream has a callback set, the caller might need to manage
1432 * extra locking.
1433 *
1434 * \since This function is available since SDL 3.2.0.
1435 *
1436 * \sa SDL_ClearAudioStream
1437 * \sa SDL_FlushAudioStream
1438 * \sa SDL_GetAudioStreamData
1439 * \sa SDL_GetAudioStreamQueued
1440 */
1441extern SDL_DECLSPEC bool SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream, const void *buf, int len);
1442
1443/**
1444 * A callback that fires for completed SDL_PutAudioStreamDataNoCopy() data.
1445 *
1446 * When using SDL_PutAudioStreamDataNoCopy() to provide data to an
1447 * SDL_AudioStream, it's not safe to dispose of the data until the stream has
1448 * completely consumed it. Often times it's difficult to know exactly when
1449 * this has happened.
1450 *
1451 * This callback fires once when the stream no longer needs the buffer,
1452 * allowing the app to easily free or reuse it.
1453 *
1454 * \param userdata an opaque pointer provided by the app for their personal
1455 * use.
1456 * \param buf the pointer provided to SDL_PutAudioStreamDataNoCopy().
1457 * \param buflen the size of buffer, in bytes, provided to
1458 * SDL_PutAudioStreamDataNoCopy().
1459 *
1460 * \threadsafety This callbacks may run from any thread, so if you need to
1461 * protect shared data, you should use SDL_LockAudioStream to
1462 * serialize access; this lock will be held before your callback
1463 * is called, so your callback does not need to manage the lock
1464 * explicitly.
1465 *
1466 * \since This datatype is available since SDL 3.4.0.
1467 *
1468 * \sa SDL_SetAudioStreamGetCallback
1469 * \sa SDL_SetAudioStreamPutCallback
1470 */
1471typedef void (SDLCALL *SDL_AudioStreamDataCompleteCallback)(void *userdata, const void *buf, int buflen);
1472
1473/**
1474 * Add external data to an audio stream without copying it.
1475 *
1476 * Unlike SDL_PutAudioStreamData(), this function does not make a copy of the
1477 * provided data, instead storing the provided pointer. This means that the
1478 * put operation does not need to allocate and copy the data, but the original
1479 * data must remain available until the stream is done with it, either by
1480 * being read from the stream in its entirety, or a call to
1481 * SDL_ClearAudioStream() or SDL_DestroyAudioStream().
1482 *
1483 * The data must match the format/channels/samplerate specified in the latest
1484 * call to SDL_SetAudioStreamFormat, or the format specified when creating the
1485 * stream if it hasn't been changed.
1486 *
1487 * An optional callback may be provided, which is called when the stream no
1488 * longer needs the data. Once this callback fires, the stream will not access
1489 * the data again. This callback will fire for any reason the data is no
1490 * longer needed, including clearing or destroying the stream.
1491 *
1492 * Note that there is still an allocation to store tracking information, so
1493 * this function is more efficient for larger blocks of data. If you're
1494 * planning to put a few samples at a time, it will be more efficient to use
1495 * SDL_PutAudioStreamData(), which allocates and buffers in blocks.
1496 *
1497 * \param stream the stream the audio data is being added to.
1498 * \param buf a pointer to the audio data to add.
1499 * \param len the number of bytes to add to the stream.
1500 * \param callback the callback function to call when the data is no longer
1501 * needed by the stream. May be NULL.
1502 * \param userdata an opaque pointer provided to the callback for its own
1503 * personal use.
1504 * \returns true on success or false on failure; call SDL_GetError() for more
1505 * information.
1506 *
1507 * \threadsafety It is safe to call this function from any thread, but if the
1508 * stream has a callback set, the caller might need to manage
1509 * extra locking.
1510 *
1511 * \since This function is available since SDL 3.4.0.
1512 *
1513 * \sa SDL_ClearAudioStream
1514 * \sa SDL_FlushAudioStream
1515 * \sa SDL_GetAudioStreamData
1516 * \sa SDL_GetAudioStreamQueued
1517 */
1518extern SDL_DECLSPEC bool SDLCALL SDL_PutAudioStreamDataNoCopy(SDL_AudioStream *stream, const void *buf, int len, SDL_AudioStreamDataCompleteCallback callback, void *userdata);
1519
1520/**
1521 * Add data to the stream with each channel in a separate array.
1522 *
1523 * This data must match the format/channels/samplerate specified in the latest
1524 * call to SDL_SetAudioStreamFormat, or the format specified when creating the
1525 * stream if it hasn't been changed.
1526 *
1527 * The data will be interleaved and queued. Note that SDL_AudioStream only
1528 * operates on interleaved data, so this is simply a convenience function for
1529 * easily queueing data from sources that provide separate arrays. There is no
1530 * equivalent function to retrieve planar data.
1531 *
1532 * The arrays in `channel_buffers` are ordered as they are to be interleaved;
1533 * the first array will be the first sample in the interleaved data. Any
1534 * individual array may be NULL; in this case, silence will be interleaved for
1535 * that channel.
1536 *
1537 * `num_channels` specifies how many arrays are in `channel_buffers`. This can
1538 * be used as a safety to prevent overflow, in case the stream format has
1539 * changed elsewhere. If more channels are specified than the current input
1540 * spec, they are ignored. If less channels are specified, the missing arrays
1541 * are treated as if they are NULL (silence is written to those channels). If
1542 * the count is -1, SDL will assume the array count matches the current input
1543 * spec.
1544 *
1545 * Note that `num_samples` is the number of _samples per array_. This can also
1546 * be thought of as the number of _sample frames_ to be queued. A value of 1
1547 * with stereo arrays will queue two samples to the stream. This is different
1548 * than SDL_PutAudioStreamData, which wants the size of a single array in
1549 * bytes.
1550 *
1551 * \param stream the stream the audio data is being added to.
1552 * \param channel_buffers a pointer to an array of arrays, one array per
1553 * channel.
1554 * \param num_channels the number of arrays in `channel_buffers` or -1.
1555 * \param num_samples the number of _samples_ per array to write to the
1556 * stream.
1557 * \returns true on success or false on failure; call SDL_GetError() for more
1558 * information.
1559 *
1560 * \threadsafety It is safe to call this function from any thread, but if the
1561 * stream has a callback set, the caller might need to manage
1562 * extra locking.
1563 *
1564 * \since This function is available since SDL 3.4.0.
1565 *
1566 * \sa SDL_ClearAudioStream
1567 * \sa SDL_FlushAudioStream
1568 * \sa SDL_GetAudioStreamData
1569 * \sa SDL_GetAudioStreamQueued
1570 */
1571extern SDL_DECLSPEC bool SDLCALL SDL_PutAudioStreamPlanarData(SDL_AudioStream *stream, const void * const *channel_buffers, int num_channels, int num_samples);
1572
1573/**
1574 * Get converted/resampled data from the stream.
1575 *
1576 * The input/output data format/channels/samplerate is specified when creating
1577 * the stream, and can be changed after creation by calling
1578 * SDL_SetAudioStreamFormat.
1579 *
1580 * Note that any conversion and resampling necessary is done during this call,
1581 * and SDL_PutAudioStreamData simply queues unconverted data for later. This
1582 * is different than SDL2, where that work was done while inputting new data
1583 * to the stream and requesting the output just copied the converted data.
1584 *
1585 * \param stream the stream the audio is being requested from.
1586 * \param buf a buffer to fill with audio data.
1587 * \param len the maximum number of bytes to fill.
1588 * \returns the number of bytes read from the stream or -1 on failure; call
1589 * SDL_GetError() for more information.
1590 *
1591 * \threadsafety It is safe to call this function from any thread, but if the
1592 * stream has a callback set, the caller might need to manage
1593 * extra locking.
1594 *
1595 * \since This function is available since SDL 3.2.0.
1596 *
1597 * \sa SDL_ClearAudioStream
1598 * \sa SDL_GetAudioStreamAvailable
1599 * \sa SDL_PutAudioStreamData
1600 */
1601extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamData(SDL_AudioStream *stream, void *buf, int len);
1602
1603/**
1604 * Get the number of converted/resampled bytes available.
1605 *
1606 * The stream may be buffering data behind the scenes until it has enough to
1607 * resample correctly, so this number might be lower than what you expect, or
1608 * even be zero. Add more data or flush the stream if you need the data now.
1609 *
1610 * If the stream has so much data that it would overflow an int, the return
1611 * value is clamped to a maximum value, but no queued data is lost; if there
1612 * are gigabytes of data queued, the app might need to read some of it with
1613 * SDL_GetAudioStreamData before this function's return value is no longer
1614 * clamped.
1615 *
1616 * \param stream the audio stream to query.
1617 * \returns the number of converted/resampled bytes available or -1 on
1618 * failure; call SDL_GetError() for more information.
1619 *
1620 * \threadsafety It is safe to call this function from any thread.
1621 *
1622 * \since This function is available since SDL 3.2.0.
1623 *
1624 * \sa SDL_GetAudioStreamData
1625 * \sa SDL_PutAudioStreamData
1626 */
1627extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *stream);
1628
1629
1630/**
1631 * Get the number of bytes currently queued.
1632 *
1633 * This is the number of bytes put into a stream as input, not the number that
1634 * can be retrieved as output. Because of several details, it's not possible
1635 * to calculate one number directly from the other. If you need to know how
1636 * much usable data can be retrieved right now, you should use
1637 * SDL_GetAudioStreamAvailable() and not this function.
1638 *
1639 * Note that audio streams can change their input format at any time, even if
1640 * there is still data queued in a different format, so the returned byte
1641 * count will not necessarily match the number of _sample frames_ available.
1642 * Users of this API should be aware of format changes they make when feeding
1643 * a stream and plan accordingly.
1644 *
1645 * Queued data is not converted until it is consumed by
1646 * SDL_GetAudioStreamData, so this value should be representative of the exact
1647 * data that was put into the stream.
1648 *
1649 * If the stream has so much data that it would overflow an int, the return
1650 * value is clamped to a maximum value, but no queued data is lost; if there
1651 * are gigabytes of data queued, the app might need to read some of it with
1652 * SDL_GetAudioStreamData before this function's return value is no longer
1653 * clamped.
1654 *
1655 * \param stream the audio stream to query.
1656 * \returns the number of bytes queued or -1 on failure; call SDL_GetError()
1657 * for more information.
1658 *
1659 * \threadsafety It is safe to call this function from any thread.
1660 *
1661 * \since This function is available since SDL 3.2.0.
1662 *
1663 * \sa SDL_PutAudioStreamData
1664 * \sa SDL_ClearAudioStream
1665 */
1666extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamQueued(SDL_AudioStream *stream);
1667
1668
1669/**
1670 * Tell the stream that you're done sending data, and anything being buffered
1671 * should be converted/resampled and made available immediately.
1672 *
1673 * It is legal to add more data to a stream after flushing, but there may be
1674 * audio gaps in the output. Generally this is intended to signal the end of
1675 * input, so the complete output becomes available.
1676 *
1677 * \param stream the audio stream to flush.
1678 * \returns true on success or false on failure; call SDL_GetError() for more
1679 * information.
1680 *
1681 * \threadsafety It is safe to call this function from any thread.
1682 *
1683 * \since This function is available since SDL 3.2.0.
1684 *
1685 * \sa SDL_PutAudioStreamData
1686 */
1687extern SDL_DECLSPEC bool SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream);
1688
1689/**
1690 * Clear any pending data in the stream.
1691 *
1692 * This drops any queued data, so there will be nothing to read from the
1693 * stream until more is added.
1694 *
1695 * \param stream the audio stream to clear.
1696 * \returns true on success or false on failure; call SDL_GetError() for more
1697 * information.
1698 *
1699 * \threadsafety It is safe to call this function from any thread.
1700 *
1701 * \since This function is available since SDL 3.2.0.
1702 *
1703 * \sa SDL_GetAudioStreamAvailable
1704 * \sa SDL_GetAudioStreamData
1705 * \sa SDL_GetAudioStreamQueued
1706 * \sa SDL_PutAudioStreamData
1707 */
1708extern SDL_DECLSPEC bool SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream);
1709
1710/**
1711 * Use this function to pause audio playback on the audio device associated
1712 * with an audio stream.
1713 *
1714 * This function pauses audio processing for a given device. Any bound audio
1715 * streams will not progress, and no audio will be generated. Pausing one
1716 * device does not prevent other unpaused devices from running.
1717 *
1718 * Pausing a device can be useful to halt all audio without unbinding all the
1719 * audio streams. This might be useful while a game is paused, or a level is
1720 * loading, etc.
1721 *
1722 * \param stream the audio stream associated with the audio device to pause.
1723 * \returns true on success or false on failure; call SDL_GetError() for more
1724 * information.
1725 *
1726 * \threadsafety It is safe to call this function from any thread.
1727 *
1728 * \since This function is available since SDL 3.2.0.
1729 *
1730 * \sa SDL_ResumeAudioStreamDevice
1731 */
1732extern SDL_DECLSPEC bool SDLCALL SDL_PauseAudioStreamDevice(SDL_AudioStream *stream);
1733
1734/**
1735 * Use this function to unpause audio playback on the audio device associated
1736 * with an audio stream.
1737 *
1738 * This function unpauses audio processing for a given device that has
1739 * previously been paused. Once unpaused, any bound audio streams will begin
1740 * to progress again, and audio can be generated.
1741 *
1742 * SDL_OpenAudioDeviceStream opens audio devices in a paused state, so this
1743 * function call is required for audio playback to begin on such devices.
1744 *
1745 * \param stream the audio stream associated with the audio device to resume.
1746 * \returns true on success or false on failure; call SDL_GetError() for more
1747 * information.
1748 *
1749 * \threadsafety It is safe to call this function from any thread.
1750 *
1751 * \since This function is available since SDL 3.2.0.
1752 *
1753 * \sa SDL_PauseAudioStreamDevice
1754 */
1755extern SDL_DECLSPEC bool SDLCALL SDL_ResumeAudioStreamDevice(SDL_AudioStream *stream);
1756
1757/**
1758 * Use this function to query if an audio device associated with a stream is
1759 * paused.
1760 *
1761 * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app
1762 * has to bind a stream before any audio will flow.
1763 *
1764 * \param stream the audio stream associated with the audio device to query.
1765 * \returns true if device is valid and paused, false otherwise.
1766 *
1767 * \threadsafety It is safe to call this function from any thread.
1768 *
1769 * \since This function is available since SDL 3.2.0.
1770 *
1771 * \sa SDL_PauseAudioStreamDevice
1772 * \sa SDL_ResumeAudioStreamDevice
1773 */
1774extern SDL_DECLSPEC bool SDLCALL SDL_AudioStreamDevicePaused(SDL_AudioStream *stream);
1775
1776
1777/**
1778 * Lock an audio stream for serialized access.
1779 *
1780 * Each SDL_AudioStream has an internal mutex it uses to protect its data
1781 * structures from threading conflicts. This function allows an app to lock
1782 * that mutex, which could be useful if registering callbacks on this stream.
1783 *
1784 * One does not need to lock a stream to use in it most cases, as the stream
1785 * manages this lock internally. However, this lock is held during callbacks,
1786 * which may run from arbitrary threads at any time, so if an app needs to
1787 * protect shared data during those callbacks, locking the stream guarantees
1788 * that the callback is not running while the lock is held.
1789 *
1790 * As this is just a wrapper over SDL_LockMutex for an internal lock; it has
1791 * all the same attributes (recursive locks are allowed, etc).
1792 *
1793 * \param stream the audio stream to lock.
1794 * \returns true on success or false on failure; call SDL_GetError() for more
1795 * information.
1796 *
1797 * \threadsafety It is safe to call this function from any thread.
1798 *
1799 * \since This function is available since SDL 3.2.0.
1800 *
1801 * \sa SDL_UnlockAudioStream
1802 */
1803extern SDL_DECLSPEC bool SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream);
1804
1805
1806/**
1807 * Unlock an audio stream for serialized access.
1808 *
1809 * This unlocks an audio stream after a call to SDL_LockAudioStream.
1810 *
1811 * \param stream the audio stream to unlock.
1812 * \returns true on success or false on failure; call SDL_GetError() for more
1813 * information.
1814 *
1815 * \threadsafety You should only call this from the same thread that
1816 * previously called SDL_LockAudioStream.
1817 *
1818 * \since This function is available since SDL 3.2.0.
1819 *
1820 * \sa SDL_LockAudioStream
1821 */
1822extern SDL_DECLSPEC bool SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stream);
1823
1824/**
1825 * A callback that fires when data passes through an SDL_AudioStream.
1826 *
1827 * Apps can (optionally) register a callback with an audio stream that is
1828 * called when data is added with SDL_PutAudioStreamData, or requested with
1829 * SDL_GetAudioStreamData.
1830 *
1831 * Two values are offered here: one is the amount of additional data needed to
1832 * satisfy the immediate request (which might be zero if the stream already
1833 * has enough data queued) and the other is the total amount being requested.
1834 * In a Get call triggering a Put callback, these values can be different. In
1835 * a Put call triggering a Get callback, these values are always the same.
1836 *
1837 * Byte counts might be slightly overestimated due to buffering or resampling,
1838 * and may change from call to call.
1839 *
1840 * This callback is not required to do anything. Generally this is useful for
1841 * adding/reading data on demand, and the app will often put/get data as
1842 * appropriate, but the system goes on with the data currently available to it
1843 * if this callback does nothing.
1844 *
1845 * \param stream the SDL audio stream associated with this callback.
1846 * \param additional_amount the amount of data, in bytes, that is needed right
1847 * now.
1848 * \param total_amount the total amount of data requested, in bytes, that is
1849 * requested or available.
1850 * \param userdata an opaque pointer provided by the app for their personal
1851 * use.
1852 *
1853 * \threadsafety This callbacks may run from any thread, so if you need to
1854 * protect shared data, you should use SDL_LockAudioStream to
1855 * serialize access; this lock will be held before your callback
1856 * is called, so your callback does not need to manage the lock
1857 * explicitly.
1858 *
1859 * \since This datatype is available since SDL 3.2.0.
1860 *
1861 * \sa SDL_SetAudioStreamGetCallback
1862 * \sa SDL_SetAudioStreamPutCallback
1863 */
1864typedef void (SDLCALL *SDL_AudioStreamCallback)(void *userdata, SDL_AudioStream *stream, int additional_amount, int total_amount);
1865
1866/**
1867 * Set a callback that runs when data is requested from an audio stream.
1868 *
1869 * This callback is called _before_ data is obtained from the stream, giving
1870 * the callback the chance to add more on-demand.
1871 *
1872 * The callback can (optionally) call SDL_PutAudioStreamData() to add more
1873 * audio to the stream during this call; if needed, the request that triggered
1874 * this callback will obtain the new data immediately.
1875 *
1876 * The callback's `additional_amount` argument is roughly how many bytes of
1877 * _unconverted_ data (in the stream's input format) is needed by the caller,
1878 * although this may overestimate a little for safety. This takes into account
1879 * how much is already in the stream and only asks for any extra necessary to
1880 * resolve the request, which means the callback may be asked for zero bytes,
1881 * and a different amount on each call.
1882 *
1883 * The callback is not required to supply exact amounts; it is allowed to
1884 * supply too much or too little or none at all. The caller will get what's
1885 * available, up to the amount they requested, regardless of this callback's
1886 * outcome.
1887 *
1888 * Clearing or flushing an audio stream does not call this callback.
1889 *
1890 * This function obtains the stream's lock, which means any existing callback
1891 * (get or put) in progress will finish running before setting the new
1892 * callback.
1893 *
1894 * Setting a NULL function turns off the callback.
1895 *
1896 * \param stream the audio stream to set the new callback on.
1897 * \param callback the new callback function to call when data is requested
1898 * from the stream.
1899 * \param userdata an opaque pointer provided to the callback for its own
1900 * personal use.
1901 * \returns true on success or false on failure; call SDL_GetError() for more
1902 * information. This only fails if `stream` is NULL.
1903 *
1904 * \threadsafety It is safe to call this function from any thread.
1905 *
1906 * \since This function is available since SDL 3.2.0.
1907 *
1908 * \sa SDL_SetAudioStreamPutCallback
1909 */
1910extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata);
1911
1912/**
1913 * Set a callback that runs when data is added to an audio stream.
1914 *
1915 * This callback is called _after_ the data is added to the stream, giving the
1916 * callback the chance to obtain it immediately.
1917 *
1918 * The callback can (optionally) call SDL_GetAudioStreamData() to obtain audio
1919 * from the stream during this call.
1920 *
1921 * The callback's `additional_amount` argument is how many bytes of
1922 * _converted_ data (in the stream's output format) was provided by the
1923 * caller, although this may underestimate a little for safety. This value
1924 * might be less than what is currently available in the stream, if data was
1925 * already there, and might be less than the caller provided if the stream
1926 * needs to keep a buffer to aid in resampling. Which means the callback may
1927 * be provided with zero bytes, and a different amount on each call.
1928 *
1929 * The callback may call SDL_GetAudioStreamAvailable to see the total amount
1930 * currently available to read from the stream, instead of the total provided
1931 * by the current call.
1932 *
1933 * The callback is not required to obtain all data. It is allowed to read less
1934 * or none at all. Anything not read now simply remains in the stream for
1935 * later access.
1936 *
1937 * Clearing or flushing an audio stream does not call this callback.
1938 *
1939 * This function obtains the stream's lock, which means any existing callback
1940 * (get or put) in progress will finish running before setting the new
1941 * callback.
1942 *
1943 * Setting a NULL function turns off the callback.
1944 *
1945 * \param stream the audio stream to set the new callback on.
1946 * \param callback the new callback function to call when data is added to the
1947 * stream.
1948 * \param userdata an opaque pointer provided to the callback for its own
1949 * personal use.
1950 * \returns true on success or false on failure; call SDL_GetError() for more
1951 * information. This only fails if `stream` is NULL.
1952 *
1953 * \threadsafety It is safe to call this function from any thread.
1954 *
1955 * \since This function is available since SDL 3.2.0.
1956 *
1957 * \sa SDL_SetAudioStreamGetCallback
1958 */
1959extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata);
1960
1961
1962/**
1963 * Free an audio stream.
1964 *
1965 * This will release all allocated data, including any audio that is still
1966 * queued. You do not need to manually clear the stream first.
1967 *
1968 * If this stream was bound to an audio device, it is unbound during this
1969 * call. If this stream was created with SDL_OpenAudioDeviceStream, the audio
1970 * device that was opened alongside this stream's creation will be closed,
1971 * too.
1972 *
1973 * \param stream the audio stream to destroy.
1974 *
1975 * \threadsafety It is safe to call this function from any thread.
1976 *
1977 * \since This function is available since SDL 3.2.0.
1978 *
1979 * \sa SDL_CreateAudioStream
1980 */
1981extern SDL_DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream);
1982
1983
1984/**
1985 * Convenience function for straightforward audio init for the common case.
1986 *
1987 * If all your app intends to do is provide a single source of PCM audio, this
1988 * function allows you to do all your audio setup in a single call.
1989 *
1990 * This is also intended to be a clean means to migrate apps from SDL2.
1991 *
1992 * This function will open an audio device, create a stream and bind it.
1993 * Unlike other methods of setup, the audio device will be closed when this
1994 * stream is destroyed, so the app can treat the returned SDL_AudioStream as
1995 * the only object needed to manage audio playback.
1996 *
1997 * Also unlike other functions, the audio device begins paused. This is to map
1998 * more closely to SDL2-style behavior, since there is no extra step here to
1999 * bind a stream to begin audio flowing. The audio device should be resumed
2000 * with SDL_ResumeAudioStreamDevice().
2001 *
2002 * This function works with both playback and recording devices.
2003 *
2004 * The `spec` parameter represents the app's side of the audio stream. That
2005 * is, for recording audio, this will be the output format, and for playing
2006 * audio, this will be the input format. If spec is NULL, the system will
2007 * choose the format, and the app can use SDL_GetAudioStreamFormat() to obtain
2008 * this information later.
2009 *
2010 * If you don't care about opening a specific audio device, you can (and
2011 * probably _should_), use SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK for playback and
2012 * SDL_AUDIO_DEVICE_DEFAULT_RECORDING for recording.
2013 *
2014 * One can optionally provide a callback function; if NULL, the app is
2015 * expected to queue audio data for playback (or unqueue audio data if
2016 * capturing). Otherwise, the callback will begin to fire once the device is
2017 * unpaused.
2018 *
2019 * Destroying the returned stream with SDL_DestroyAudioStream will also close
2020 * the audio device associated with this stream.
2021 *
2022 * \param devid an audio device to open, or SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK
2023 * or SDL_AUDIO_DEVICE_DEFAULT_RECORDING.
2024 * \param spec the audio stream's data format. Can be NULL.
2025 * \param callback a callback where the app will provide new data for
2026 * playback, or receive new data for recording. Can be NULL,
2027 * in which case the app will need to call
2028 * SDL_PutAudioStreamData or SDL_GetAudioStreamData as
2029 * necessary.
2030 * \param userdata app-controlled pointer passed to callback. Can be NULL.
2031 * Ignored if callback is NULL.
2032 * \returns an audio stream on success, ready to use, or NULL on failure; call
2033 * SDL_GetError() for more information. When done with this stream,
2034 * call SDL_DestroyAudioStream to free resources and close the
2035 * device.
2036 *
2037 * \threadsafety It is safe to call this function from any thread.
2038 *
2039 * \since This function is available since SDL 3.2.0.
2040 *
2041 * \sa SDL_GetAudioStreamDevice
2042 * \sa SDL_ResumeAudioStreamDevice
2043 */
2044extern SDL_DECLSPEC SDL_AudioStream * SDLCALL SDL_OpenAudioDeviceStream(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec, SDL_AudioStreamCallback callback, void *userdata);
2045
2046/**
2047 * A callback that fires when data is about to be fed to an audio device.
2048 *
2049 * This is useful for accessing the final mix, perhaps for writing a
2050 * visualizer or applying a final effect to the audio data before playback.
2051 *
2052 * This callback should run as quickly as possible and not block for any
2053 * significant time, as this callback delays submission of data to the audio
2054 * device, which can cause audio playback problems.
2055 *
2056 * The postmix callback _must_ be able to handle any audio data format
2057 * specified in `spec`, which can change between callbacks if the audio device
2058 * changed. However, this only covers frequency and channel count; data is
2059 * always provided here in SDL_AUDIO_F32 format.
2060 *
2061 * The postmix callback runs _after_ logical device gain and audiostream gain
2062 * have been applied, which is to say you can make the output data louder at
2063 * this point than the gain settings would suggest.
2064 *
2065 * \param userdata a pointer provided by the app through
2066 * SDL_SetAudioPostmixCallback, for its own use.
2067 * \param spec the current format of audio that is to be submitted to the
2068 * audio device.
2069 * \param buffer the buffer of audio samples to be submitted. The callback can
2070 * inspect and/or modify this data.
2071 * \param buflen the size of `buffer` in bytes.
2072 *
2073 * \threadsafety This will run from a background thread owned by SDL. The
2074 * application is responsible for locking resources the callback
2075 * touches that need to be protected.
2076 *
2077 * \since This datatype is available since SDL 3.2.0.
2078 *
2079 * \sa SDL_SetAudioPostmixCallback
2080 */
2081typedef void (SDLCALL *SDL_AudioPostmixCallback)(void *userdata, const SDL_AudioSpec *spec, float *buffer, int buflen);
2082
2083/**
2084 * Set a callback that fires when data is about to be fed to an audio device.
2085 *
2086 * This is useful for accessing the final mix, perhaps for writing a
2087 * visualizer or applying a final effect to the audio data before playback.
2088 *
2089 * The buffer is the final mix of all bound audio streams on an opened device;
2090 * this callback will fire regularly for any device that is both opened and
2091 * unpaused. If there is no new data to mix, either because no streams are
2092 * bound to the device or all the streams are empty, this callback will still
2093 * fire with the entire buffer set to silence.
2094 *
2095 * This callback is allowed to make changes to the data; the contents of the
2096 * buffer after this call is what is ultimately passed along to the hardware.
2097 *
2098 * The callback is always provided the data in float format (values from -1.0f
2099 * to 1.0f), but the number of channels or sample rate may be different than
2100 * the format the app requested when opening the device; SDL might have had to
2101 * manage a conversion behind the scenes, or the playback might have jumped to
2102 * new physical hardware when a system default changed, etc. These details may
2103 * change between calls. Accordingly, the size of the buffer might change
2104 * between calls as well.
2105 *
2106 * This callback can run at any time, and from any thread; if you need to
2107 * serialize access to your app's data, you should provide and use a mutex or
2108 * other synchronization device.
2109 *
2110 * All of this to say: there are specific needs this callback can fulfill, but
2111 * it is not the simplest interface. Apps should generally provide audio in
2112 * their preferred format through an SDL_AudioStream and let SDL handle the
2113 * difference.
2114 *
2115 * This function is extremely time-sensitive; the callback should do the least
2116 * amount of work possible and return as quickly as it can. The longer the
2117 * callback runs, the higher the risk of audio dropouts or other problems.
2118 *
2119 * This function will block until the audio device is in between iterations,
2120 * so any existing callback that might be running will finish before this
2121 * function sets the new callback and returns.
2122 *
2123 * Setting a NULL callback function disables any previously-set callback.
2124 *
2125 * \param devid the ID of an opened audio device.
2126 * \param callback a callback function to be called. Can be NULL.
2127 * \param userdata app-controlled pointer passed to callback. Can be NULL.
2128 * \returns true on success or false on failure; call SDL_GetError() for more
2129 * information.
2130 *
2131 * \threadsafety It is safe to call this function from any thread.
2132 *
2133 * \since This function is available since SDL 3.2.0.
2134 */
2135extern SDL_DECLSPEC bool SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDeviceID devid, SDL_AudioPostmixCallback callback, void *userdata);
2136
2137
2138/**
2139 * Load the audio data of a WAVE file into memory.
2140 *
2141 * Loading a WAVE file requires `src`, `spec`, `audio_buf` and `audio_len` to
2142 * be valid pointers. The entire data portion of the file is then loaded into
2143 * memory and decoded if necessary.
2144 *
2145 * Supported formats are RIFF WAVE files with the formats PCM (8, 16, 24, and
2146 * 32 bits), IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and
2147 * A-law and mu-law (8 bits). Other formats are currently unsupported and
2148 * cause an error.
2149 *
2150 * If this function succeeds, the return value is zero and the pointer to the
2151 * audio data allocated by the function is written to `audio_buf` and its
2152 * length in bytes to `audio_len`. The SDL_AudioSpec members `freq`,
2153 * `channels`, and `format` are set to the values of the audio data in the
2154 * buffer.
2155 *
2156 * It's necessary to use SDL_free() to free the audio data returned in
2157 * `audio_buf` when it is no longer used.
2158 *
2159 * Because of the underspecification of the .WAV format, there are many
2160 * problematic files in the wild that cause issues with strict decoders. To
2161 * provide compatibility with these files, this decoder is lenient in regards
2162 * to the truncation of the file, the fact chunk, and the size of the RIFF
2163 * chunk. The hints `SDL_HINT_WAVE_RIFF_CHUNK_SIZE`,
2164 * `SDL_HINT_WAVE_TRUNCATION`, and `SDL_HINT_WAVE_FACT_CHUNK` can be used to
2165 * tune the behavior of the loading process.
2166 *
2167 * Any file that is invalid (due to truncation, corruption, or wrong values in
2168 * the headers), too big, or unsupported causes an error. Additionally, any
2169 * critical I/O error from the data source will terminate the loading process
2170 * with an error. The function returns NULL on error and in all cases (with
2171 * the exception of `src` being NULL), an appropriate error message will be
2172 * set.
2173 *
2174 * It is required that the data source supports seeking.
2175 *
2176 * Example:
2177 *
2178 * ```c
2179 * SDL_LoadWAV_IO(SDL_IOFromFile("sample.wav", "rb"), true, &spec, &buf, &len);
2180 * ```
2181 *
2182 * Note that the SDL_LoadWAV function does this same thing for you, but in a
2183 * less messy way:
2184 *
2185 * ```c
2186 * SDL_LoadWAV("sample.wav", &spec, &buf, &len);
2187 * ```
2188 *
2189 * \param src the data source for the WAVE data.
2190 * \param closeio if true, calls SDL_CloseIO() on `src` before returning, even
2191 * in the case of an error.
2192 * \param spec a pointer to an SDL_AudioSpec that will be set to the WAVE
2193 * data's format details on successful return.
2194 * \param audio_buf a pointer filled with the audio data, allocated by the
2195 * function.
2196 * \param audio_len a pointer filled with the length of the audio data buffer
2197 * in bytes.
2198 * \returns true on success. `audio_buf` will be filled with a pointer to an
2199 * allocated buffer containing the audio data, and `audio_len` is
2200 * filled with the length of that audio buffer in bytes.
2201 *
2202 * This function returns false if the .WAV file cannot be opened,
2203 * uses an unknown data format, or is corrupt; call SDL_GetError()
2204 * for more information.
2205 *
2206 * When the application is done with the data returned in
2207 * `audio_buf`, it should call SDL_free() to dispose of it.
2208 *
2209 * \threadsafety It is safe to call this function from any thread.
2210 *
2211 * \since This function is available since SDL 3.2.0.
2212 *
2213 * \sa SDL_free
2214 * \sa SDL_LoadWAV
2215 */
2216extern SDL_DECLSPEC bool SDLCALL SDL_LoadWAV_IO(SDL_IOStream *src, bool closeio, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len);
2217
2218/**
2219 * Loads a WAV from a file path.
2220 *
2221 * This is a convenience function that is effectively the same as:
2222 *
2223 * ```c
2224 * SDL_LoadWAV_IO(SDL_IOFromFile(path, "rb"), true, spec, audio_buf, audio_len);
2225 * ```
2226 *
2227 * \param path the file path of the WAV file to open.
2228 * \param spec a pointer to an SDL_AudioSpec that will be set to the WAVE
2229 * data's format details on successful return.
2230 * \param audio_buf a pointer filled with the audio data, allocated by the
2231 * function.
2232 * \param audio_len a pointer filled with the length of the audio data buffer
2233 * in bytes.
2234 * \returns true on success. `audio_buf` will be filled with a pointer to an
2235 * allocated buffer containing the audio data, and `audio_len` is
2236 * filled with the length of that audio buffer in bytes.
2237 *
2238 * This function returns false if the .WAV file cannot be opened,
2239 * uses an unknown data format, or is corrupt; call SDL_GetError()
2240 * for more information.
2241 *
2242 * When the application is done with the data returned in
2243 * `audio_buf`, it should call SDL_free() to dispose of it.
2244 *
2245 * \threadsafety It is safe to call this function from any thread.
2246 *
2247 * \since This function is available since SDL 3.2.0.
2248 *
2249 * \sa SDL_free
2250 * \sa SDL_LoadWAV_IO
2251 */
2252extern SDL_DECLSPEC bool SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len);
2253
2254/**
2255 * Mix audio data in a specified format.
2256 *
2257 * This takes an audio buffer `src` of `len` bytes of `format` data and mixes
2258 * it into `dst`, performing addition, volume adjustment, and overflow
2259 * clipping. The buffer pointed to by `dst` must also be `len` bytes of
2260 * `format` data.
2261 *
2262 * This is provided for convenience -- you can mix your own audio data.
2263 *
2264 * Do not use this function for mixing together more than two streams of
2265 * sample data. The output from repeated application of this function may be
2266 * distorted by clipping, because there is no accumulator with greater range
2267 * than the input (not to mention this being an inefficient way of doing it).
2268 *
2269 * It is a common misconception that this function is required to write audio
2270 * data to an output stream in an audio callback. While you can do that,
2271 * SDL_MixAudio() is really only needed when you're mixing a single audio
2272 * stream with a volume adjustment.
2273 *
2274 * \param dst the destination for the mixed audio.
2275 * \param src the source audio buffer to be mixed.
2276 * \param format the SDL_AudioFormat structure representing the desired audio
2277 * format.
2278 * \param len the length of the audio buffer in bytes.
2279 * \param volume ranges from 0.0 - 1.0, and should be set to 1.0 for full
2280 * audio volume.
2281 * \returns true on success or false on failure; call SDL_GetError() for more
2282 * information.
2283 *
2284 * \threadsafety It is safe to call this function from any thread.
2285 *
2286 * \since This function is available since SDL 3.2.0.
2287 */
2288extern SDL_DECLSPEC bool SDLCALL SDL_MixAudio(Uint8 *dst, const Uint8 *src, SDL_AudioFormat format, Uint32 len, float volume);
2289
2290/**
2291 * Convert some audio data of one format to another format.
2292 *
2293 * Please note that this function is for convenience, but should not be used
2294 * to resample audio in blocks, as it will introduce audio artifacts on the
2295 * boundaries. You should only use this function if you are converting audio
2296 * data in its entirety in one call. If you want to convert audio in smaller
2297 * chunks, use an SDL_AudioStream, which is designed for this situation.
2298 *
2299 * Internally, this function creates and destroys an SDL_AudioStream on each
2300 * use, so it's also less efficient than using one directly, if you need to
2301 * convert multiple times.
2302 *
2303 * \param src_spec the format details of the input audio.
2304 * \param src_data the audio data to be converted.
2305 * \param src_len the len of src_data.
2306 * \param dst_spec the format details of the output audio.
2307 * \param dst_data will be filled with a pointer to converted audio data,
2308 * which should be freed with SDL_free(). On error, it will be
2309 * NULL.
2310 * \param dst_len will be filled with the len of dst_data.
2311 * \returns true on success or false on failure; call SDL_GetError() for more
2312 * information.
2313 *
2314 * \threadsafety It is safe to call this function from any thread.
2315 *
2316 * \since This function is available since SDL 3.2.0.
2317 */
2318extern SDL_DECLSPEC bool SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec *src_spec, const Uint8 *src_data, int src_len, const SDL_AudioSpec *dst_spec, Uint8 **dst_data, int *dst_len);
2319
2320/**
2321 * Get the human readable name of an audio format.
2322 *
2323 * \param format the audio format to query.
2324 * \returns the human readable name of the specified audio format or
2325 * "SDL_AUDIO_UNKNOWN" if the format isn't recognized.
2326 *
2327 * \threadsafety It is safe to call this function from any thread.
2328 *
2329 * \since This function is available since SDL 3.2.0.
2330 */
2331extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioFormatName(SDL_AudioFormat format);
2332
2333/**
2334 * Get the appropriate memset value for silencing an audio format.
2335 *
2336 * The value returned by this function can be used as the second argument to
2337 * memset (or SDL_memset) to set an audio buffer in a specific format to
2338 * silence.
2339 *
2340 * \param format the audio data format to query.
2341 * \returns a byte value that can be passed to memset.
2342 *
2343 * \threadsafety It is safe to call this function from any thread.
2344 *
2345 * \since This function is available since SDL 3.2.0.
2346 */
2347extern SDL_DECLSPEC int SDLCALL SDL_GetSilenceValueForFormat(SDL_AudioFormat format);
2348
2349
2350/* Ends C function definitions when using C++ */
2351#ifdef __cplusplus
2352}
2353#endif
2354#include <SDL3/SDL_close_code.h>
2355
2356#endif /* SDL_audio_h_ */
SDL_MixAudio
bool SDL_MixAudio(Uint8 *dst, const Uint8 *src, SDL_AudioFormat format, Uint32 len, float volume)
SDL_PutAudioStreamPlanarData
bool SDL_PutAudioStreamPlanarData(SDL_AudioStream *stream, const void *const *channel_buffers, int num_channels, int num_samples)
SDL_GetAudioDeviceName
const char * SDL_GetAudioDeviceName(SDL_AudioDeviceID devid)
SDL_SetAudioStreamFormat
bool SDL_SetAudioStreamFormat(SDL_AudioStream *stream, const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec)
SDL_GetAudioRecordingDevices
SDL_AudioDeviceID * SDL_GetAudioRecordingDevices(int *count)
SDL_UnlockAudioStream
bool SDL_UnlockAudioStream(SDL_AudioStream *stream)
SDL_GetAudioStreamInputChannelMap
int * SDL_GetAudioStreamInputChannelMap(SDL_AudioStream *stream, int *count)
SDL_GetAudioDriver
const char * SDL_GetAudioDriver(int index)
SDL_CreateAudioStream
SDL_AudioStream * SDL_CreateAudioStream(const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec)
SDL_UnbindAudioStream
void SDL_UnbindAudioStream(SDL_AudioStream *stream)
SDL_IsAudioDevicePhysical
bool SDL_IsAudioDevicePhysical(SDL_AudioDeviceID devid)
SDL_UnbindAudioStreams
void SDL_UnbindAudioStreams(SDL_AudioStream *const *streams, int num_streams)
SDL_GetAudioDeviceGain
float SDL_GetAudioDeviceGain(SDL_AudioDeviceID devid)
SDL_SetAudioStreamGain
bool SDL_SetAudioStreamGain(SDL_AudioStream *stream, float gain)
SDL_AudioStream
struct SDL_AudioStream SDL_AudioStream
Definition SDL_audio.h:451
SDL_SetAudioStreamPutCallback
bool SDL_SetAudioStreamPutCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata)
SDL_IsAudioDevicePlayback
bool SDL_IsAudioDevicePlayback(SDL_AudioDeviceID devid)
SDL_GetAudioPlaybackDevices
SDL_AudioDeviceID * SDL_GetAudioPlaybackDevices(int *count)
SDL_SetAudioPostmixCallback
bool SDL_SetAudioPostmixCallback(SDL_AudioDeviceID devid, SDL_AudioPostmixCallback callback, void *userdata)
SDL_AudioStreamCallback
void(* SDL_AudioStreamCallback)(void *userdata, SDL_AudioStream *stream, int additional_amount, int total_amount)
Definition SDL_audio.h:1865
SDL_SetAudioStreamInputChannelMap
bool SDL_SetAudioStreamInputChannelMap(SDL_AudioStream *stream, const int *chmap, int count)
SDL_AudioDevicePaused
bool SDL_AudioDevicePaused(SDL_AudioDeviceID devid)
SDL_SetAudioStreamFrequencyRatio
bool SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream *stream, float ratio)
SDL_GetNumAudioDrivers
int SDL_GetNumAudioDrivers(void)
SDL_LockAudioStream
bool SDL_LockAudioStream(SDL_AudioStream *stream)
SDL_GetAudioStreamGain
float SDL_GetAudioStreamGain(SDL_AudioStream *stream)
SDL_AudioDeviceID
Uint32 SDL_AudioDeviceID
Definition SDL_audio.h:374
SDL_GetAudioStreamQueued
int SDL_GetAudioStreamQueued(SDL_AudioStream *stream)
SDL_SetAudioDeviceGain
bool SDL_SetAudioDeviceGain(SDL_AudioDeviceID devid, float gain)
SDL_GetSilenceValueForFormat
int SDL_GetSilenceValueForFormat(SDL_AudioFormat format)
SDL_GetCurrentAudioDriver
const char * SDL_GetCurrentAudioDriver(void)
SDL_GetAudioStreamProperties
SDL_PropertiesID SDL_GetAudioStreamProperties(SDL_AudioStream *stream)
SDL_OpenAudioDeviceStream
SDL_AudioStream * SDL_OpenAudioDeviceStream(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec, SDL_AudioStreamCallback callback, void *userdata)
SDL_ResumeAudioStreamDevice
bool SDL_ResumeAudioStreamDevice(SDL_AudioStream *stream)
SDL_AudioPostmixCallback
void(* SDL_AudioPostmixCallback)(void *userdata, const SDL_AudioSpec *spec, float *buffer, int buflen)
Definition SDL_audio.h:2082
SDL_GetAudioDeviceFormat
bool SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SDL_AudioSpec *spec, int *sample_frames)
SDL_SetAudioStreamOutputChannelMap
bool SDL_SetAudioStreamOutputChannelMap(SDL_AudioStream *stream, const int *chmap, int count)
SDL_PauseAudioStreamDevice
bool SDL_PauseAudioStreamDevice(SDL_AudioStream *stream)
SDL_GetAudioStreamFrequencyRatio
float SDL_GetAudioStreamFrequencyRatio(SDL_AudioStream *stream)
SDL_GetAudioStreamAvailable
int SDL_GetAudioStreamAvailable(SDL_AudioStream *stream)
SDL_AudioFormat
SDL_AudioFormat
Definition SDL_audio.h:222
SDL_AUDIO_S32LE
@ SDL_AUDIO_S32LE
Definition SDL_audio.h:232
SDL_AUDIO_F32
@ SDL_AUDIO_F32
Definition SDL_audio.h:245
SDL_AUDIO_S16LE
@ SDL_AUDIO_S16LE
Definition SDL_audio.h:228
SDL_AUDIO_S16
@ SDL_AUDIO_S16
Definition SDL_audio.h:243
SDL_AUDIO_U8
@ SDL_AUDIO_U8
Definition SDL_audio.h:224
SDL_AUDIO_S8
@ SDL_AUDIO_S8
Definition SDL_audio.h:226
SDL_AUDIO_S32
@ SDL_AUDIO_S32
Definition SDL_audio.h:244
SDL_AUDIO_F32LE
@ SDL_AUDIO_F32LE
Definition SDL_audio.h:236
SDL_AUDIO_S32BE
@ SDL_AUDIO_S32BE
Definition SDL_audio.h:234
SDL_AUDIO_UNKNOWN
@ SDL_AUDIO_UNKNOWN
Definition SDL_audio.h:223
SDL_AUDIO_S16BE
@ SDL_AUDIO_S16BE
Definition SDL_audio.h:230
SDL_AUDIO_F32BE
@ SDL_AUDIO_F32BE
Definition SDL_audio.h:238
SDL_LoadWAV
bool SDL_LoadWAV(const char *path, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len)
SDL_ConvertAudioSamples
bool SDL_ConvertAudioSamples(const SDL_AudioSpec *src_spec, const Uint8 *src_data, int src_len, const SDL_AudioSpec *dst_spec, Uint8 **dst_data, int *dst_len)
SDL_BindAudioStreams
bool SDL_BindAudioStreams(SDL_AudioDeviceID devid, SDL_AudioStream *const *streams, int num_streams)
SDL_GetAudioStreamOutputChannelMap
int * SDL_GetAudioStreamOutputChannelMap(SDL_AudioStream *stream, int *count)
SDL_ClearAudioStream
bool SDL_ClearAudioStream(SDL_AudioStream *stream)
SDL_DestroyAudioStream
void SDL_DestroyAudioStream(SDL_AudioStream *stream)
SDL_AudioStreamDataCompleteCallback
void(* SDL_AudioStreamDataCompleteCallback)(void *userdata, const void *buf, int buflen)
Definition SDL_audio.h:1472
SDL_CloseAudioDevice
void SDL_CloseAudioDevice(SDL_AudioDeviceID devid)
SDL_GetAudioStreamData
int SDL_GetAudioStreamData(SDL_AudioStream *stream, void *buf, int len)
SDL_AudioStreamDevicePaused
bool SDL_AudioStreamDevicePaused(SDL_AudioStream *stream)
SDL_GetAudioFormatName
const char * SDL_GetAudioFormatName(SDL_AudioFormat format)
SDL_GetAudioStreamFormat
bool SDL_GetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioSpec *src_spec, SDL_AudioSpec *dst_spec)
SDL_OpenAudioDevice
SDL_AudioDeviceID SDL_OpenAudioDevice(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec)
SDL_BindAudioStream
bool SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_AudioStream *stream)
SDL_SetAudioStreamGetCallback
bool SDL_SetAudioStreamGetCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata)
SDL_FlushAudioStream
bool SDL_FlushAudioStream(SDL_AudioStream *stream)
SDL_GetAudioDeviceChannelMap
int * SDL_GetAudioDeviceChannelMap(SDL_AudioDeviceID devid, int *count)
SDL_ResumeAudioDevice
bool SDL_ResumeAudioDevice(SDL_AudioDeviceID devid)
SDL_PutAudioStreamData
bool SDL_PutAudioStreamData(SDL_AudioStream *stream, const void *buf, int len)
SDL_PutAudioStreamDataNoCopy
bool SDL_PutAudioStreamDataNoCopy(SDL_AudioStream *stream, const void *buf, int len, SDL_AudioStreamDataCompleteCallback callback, void *userdata)
SDL_GetAudioStreamDevice
SDL_AudioDeviceID SDL_GetAudioStreamDevice(SDL_AudioStream *stream)
SDL_PauseAudioDevice
bool SDL_PauseAudioDevice(SDL_AudioDeviceID devid)
SDL_LoadWAV_IO
bool SDL_LoadWAV_IO(SDL_IOStream *src, bool closeio, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len)
SDL_close_code.h
SDL_IOStream
struct SDL_IOStream SDL_IOStream
Definition SDL_iostream.h:182
SDL_PropertiesID
Uint32 SDL_PropertiesID
Definition SDL_properties.h:66
Uint8
uint8_t Uint8
Definition SDL_stdinc.h:446
Uint32
uint32_t Uint32
Definition SDL_stdinc.h:482
SDL_AudioSpec
Definition SDL_audio.h:406
SDL_AudioSpec::channels
int channels
Definition SDL_audio.h:408
SDL_AudioSpec::freq
int freq
Definition SDL_audio.h:409
SDL_AudioSpec::format
SDL_AudioFormat format
Definition SDL_audio.h:407

◆ SDL_PROP_AUDIOSTREAM_AUTO_CLEANUP_BOOLEAN

#define SDL_PROP_AUDIOSTREAM_AUTO_CLEANUP_BOOLEAN   "SDL.audiostream.auto_cleanup"

Definition at line 1100 of file SDL_audio.h.

Typedef Documentation

◆ SDL_AudioDeviceID

typedef Uint32 SDL_AudioDeviceID

SDL Audio Device instance IDs.

Zero is used to signify an invalid/null device.

Since
This datatype is available since SDL 3.2.0.

Definition at line 374 of file SDL_audio.h.

◆ SDL_AudioPostmixCallback

typedef void(* SDL_AudioPostmixCallback) (void *userdata, const SDL_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 SDL_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
userdataa pointer provided by the app through SDL_SetAudioPostmixCallback, for its own use.
specthe current format of audio that is to be submitted to the audio device.
bufferthe buffer of audio samples to be submitted. The callback can inspect and/or modify this data.
buflenthe size of buffer in bytes.

\threadsafety 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
SDL_SetAudioPostmixCallback

Definition at line 2082 of file SDL_audio.h.

◆ SDL_AudioStream

typedef struct SDL_AudioStream SDL_AudioStream

The opaque handle that represents an audio stream.

SDL_AudioStream is an audio conversion interface.

  • It can handle resampling data in chunks without generating artifacts, when it doesn't have the complete buffer available.
  • It can handle incoming data in any variable size.
  • It can handle input/output format changes on the fly.
  • It can remap audio channels between inputs and outputs.
  • You push data as you have it, and pull it when you need it
  • It can also function as a basic audio data queue even if you just have sound that needs to pass from one place to another.
  • You can hook callbacks up to them when more data is added or requested, to manage data on-the-fly.

Audio streams are the core of the SDL3 audio interface. You create one or more of them, bind them to an opened audio device, and feed data to them (or for recording, consume data from them).

Since
This struct is available since SDL 3.2.0.
See also
SDL_CreateAudioStream

Definition at line 451 of file SDL_audio.h.

◆ SDL_AudioStreamCallback

typedef void(* SDL_AudioStreamCallback) (void *userdata, SDL_AudioStream *stream, int additional_amount, int total_amount)

A callback that fires when data passes through an SDL_AudioStream.

Apps can (optionally) register a callback with an audio stream that is called when data is added with SDL_PutAudioStreamData, or requested with SDL_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
streamthe SDL audio stream associated with this callback.
additional_amountthe amount of data, in bytes, that is needed right now.
total_amountthe total amount of data requested, in bytes, that is requested or available.
userdataan opaque pointer provided by the app for their personal use.

\threadsafety This callbacks may run from any thread, so if you need to protect shared data, you should use SDL_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
SDL_SetAudioStreamGetCallback
SDL_SetAudioStreamPutCallback

Definition at line 1865 of file SDL_audio.h.

◆ SDL_AudioStreamDataCompleteCallback

typedef void(* SDL_AudioStreamDataCompleteCallback) (void *userdata, const void *buf, int buflen)

A callback that fires for completed SDL_PutAudioStreamDataNoCopy() data.

When using SDL_PutAudioStreamDataNoCopy() to provide data to an SDL_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
userdataan opaque pointer provided by the app for their personal use.
bufthe pointer provided to SDL_PutAudioStreamDataNoCopy().
buflenthe size of buffer, in bytes, provided to SDL_PutAudioStreamDataNoCopy().

\threadsafety This callbacks may run from any thread, so if you need to protect shared data, you should use SDL_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
SDL_SetAudioStreamGetCallback
SDL_SetAudioStreamPutCallback

Definition at line 1472 of file SDL_audio.h.

Enumeration Type Documentation

◆ SDL_AudioFormat

enum SDL_AudioFormat

Audio format.

Since
This enum is available since SDL 3.2.0.
See also
SDL_AUDIO_BITSIZE
SDL_AUDIO_BYTESIZE
SDL_AUDIO_ISINT
SDL_AUDIO_ISFLOAT
SDL_AUDIO_ISBIGENDIAN
SDL_AUDIO_ISLITTLEENDIAN
SDL_AUDIO_ISSIGNED
SDL_AUDIO_ISUNSIGNED
Enumerator
SDL_AUDIO_UNKNOWN 

Unspecified audio format

SDL_AUDIO_U8 

Unsigned 8-bit samples

SDL_AUDIO_S8 

Signed 8-bit samples

SDL_AUDIO_S16LE 

Signed 16-bit samples

SDL_AUDIO_S16BE 

As above, but big-endian byte order

SDL_AUDIO_S32LE 

32-bit integer samples

SDL_AUDIO_S32BE 

As above, but big-endian byte order

SDL_AUDIO_F32LE 

32-bit floating point samples

SDL_AUDIO_F32BE 

As above, but big-endian byte order

SDL_AUDIO_S16 
SDL_AUDIO_S32 
SDL_AUDIO_F32 

Definition at line 221 of file SDL_audio.h.

222{
223 SDL_AUDIO_UNKNOWN = 0x0000u, /**< Unspecified audio format */
224 SDL_AUDIO_U8 = 0x0008u, /**< Unsigned 8-bit samples */
225 /* SDL_DEFINE_AUDIO_FORMAT(0, 0, 0, 8), */
226 SDL_AUDIO_S8 = 0x8008u, /**< Signed 8-bit samples */
227 /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 8), */
228 SDL_AUDIO_S16LE = 0x8010u, /**< Signed 16-bit samples */
229 /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 16), */
230 SDL_AUDIO_S16BE = 0x9010u, /**< As above, but big-endian byte order */
231 /* SDL_DEFINE_AUDIO_FORMAT(1, 1, 0, 16), */
232 SDL_AUDIO_S32LE = 0x8020u, /**< 32-bit integer samples */
233 /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 32), */
234 SDL_AUDIO_S32BE = 0x9020u, /**< As above, but big-endian byte order */
235 /* SDL_DEFINE_AUDIO_FORMAT(1, 1, 0, 32), */
236 SDL_AUDIO_F32LE = 0x8120u, /**< 32-bit floating point samples */
237 /* SDL_DEFINE_AUDIO_FORMAT(1, 0, 1, 32), */
238 SDL_AUDIO_F32BE = 0x9120u, /**< As above, but big-endian byte order */
239 /* SDL_DEFINE_AUDIO_FORMAT(1, 1, 1, 32), */
240
241 /* These represent the current system's byteorder. */
242 #if SDL_BYTEORDER == SDL_LIL_ENDIAN
243 SDL_AUDIO_S16 = SDL_AUDIO_S16LE,
244 SDL_AUDIO_S32 = SDL_AUDIO_S32LE,
245 SDL_AUDIO_F32 = SDL_AUDIO_F32LE
246 #else
247 SDL_AUDIO_S16 = SDL_AUDIO_S16BE,
248 SDL_AUDIO_S32 = SDL_AUDIO_S32BE,
249 SDL_AUDIO_F32 = SDL_AUDIO_F32BE
250 #endif
251} SDL_AudioFormat;

Function Documentation

◆ SDL_AudioDevicePaused()

bool SDL_AudioDevicePaused ( SDL_AudioDeviceID  devid)
extern

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 SDL_OpenAudioDevice() can be. Physical and invalid device IDs will report themselves as unpaused here.

Parameters
devida device opened by SDL_OpenAudioDevice().
Returns
true if device is valid and paused, false otherwise.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_PauseAudioDevice
SDL_ResumeAudioDevice

◆ SDL_AudioStreamDevicePaused()

bool SDL_AudioStreamDevicePaused ( SDL_AudioStream *  stream)
extern

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
streamthe audio stream associated with the audio device to query.
Returns
true if device is valid and paused, false otherwise.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_PauseAudioStreamDevice
SDL_ResumeAudioStreamDevice

◆ SDL_BindAudioStream()

bool SDL_BindAudioStream ( SDL_AudioDeviceID  devid,
SDL_AudioStream *  stream 
)
extern

Bind a single audio stream to an audio device.

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

Parameters
devidan audio device to bind a stream to.
streaman audio stream to bind to a device.
Returns
true on success or false on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_BindAudioStreams
SDL_UnbindAudioStream
SDL_GetAudioStreamDevice

◆ SDL_BindAudioStreams()

bool SDL_BindAudioStreams ( SDL_AudioDeviceID  devid,
SDL_AudioStream *const *  streams,
int  num_streams 
)
extern

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 SDL_SetAudioStreamFormat(). If the other end of the stream's format has never been set (the audio stream was created with a NULL audio spec), this function will set it to match the device end's format.

Parameters
devidan audio device to bind a stream to.
streamsan array of audio streams to bind.
num_streamsnumber streams listed in the streams array.
Returns
true on success or false on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_BindAudioStreams
SDL_UnbindAudioStream
SDL_GetAudioStreamDevice

◆ SDL_ClearAudioStream()

bool SDL_ClearAudioStream ( SDL_AudioStream *  stream)
extern

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
streamthe audio stream to clear.
Returns
true on success or false on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_GetAudioStreamAvailable
SDL_GetAudioStreamData
SDL_GetAudioStreamQueued
SDL_PutAudioStreamData

◆ SDL_CloseAudioDevice()

void SDL_CloseAudioDevice ( SDL_AudioDeviceID  devid)
extern

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
devidan audio device id previously returned by SDL_OpenAudioDevice().

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_OpenAudioDevice

◆ SDL_ConvertAudioSamples()

bool SDL_ConvertAudioSamples ( const SDL_AudioSpec *  src_spec,
const Uint8 *  src_data,
int  src_len,
const SDL_AudioSpec *  dst_spec,
Uint8 **  dst_data,
int *  dst_len 
)
extern

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

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

Parameters
src_specthe format details of the input audio.
src_datathe audio data to be converted.
src_lenthe len of src_data.
dst_specthe format details of the output audio.
dst_datawill be filled with a pointer to converted audio data, which should be freed with SDL_free(). On error, it will be NULL.
dst_lenwill be filled with the len of dst_data.
Returns
true on success or false on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.

◆ SDL_CreateAudioStream()

SDL_AudioStream * SDL_CreateAudioStream ( const SDL_AudioSpec *  src_spec,
const SDL_AudioSpec *  dst_spec 
)
extern

Create a new audio stream.

Parameters
src_specthe format details of the input audio.
dst_specthe format details of the output audio.
Returns
a new audio stream on success or NULL on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_PutAudioStreamData
SDL_GetAudioStreamData
SDL_GetAudioStreamAvailable
SDL_FlushAudioStream
SDL_ClearAudioStream
SDL_SetAudioStreamFormat
SDL_DestroyAudioStream

◆ SDL_DestroyAudioStream()

void SDL_DestroyAudioStream ( SDL_AudioStream *  stream)
extern

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 SDL_OpenAudioDeviceStream, the audio device that was opened alongside this stream's creation will be closed, too.

Parameters
streamthe audio stream to destroy.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_CreateAudioStream

◆ SDL_FlushAudioStream()

bool SDL_FlushAudioStream ( SDL_AudioStream *  stream)
extern

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
streamthe audio stream to flush.
Returns
true on success or false on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_PutAudioStreamData

◆ SDL_GetAudioDeviceChannelMap()

int * SDL_GetAudioDeviceChannelMap ( SDL_AudioDeviceID  devid,
int *  count 
)
extern

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

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

Parameters
devidthe instance ID of the device to query.
countOn output, set to number of channels in the map. Can be NULL.
Returns
an array of the current channel mapping, with as many elements as the current output spec's channels, or NULL if default. This should be freed with SDL_free() when it is no longer needed.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_SetAudioStreamInputChannelMap

◆ SDL_GetAudioDeviceFormat()

bool SDL_GetAudioDeviceFormat ( SDL_AudioDeviceID  devid,
SDL_AudioSpec *  spec,
int *  sample_frames 
)
extern

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 SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK or SDL_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
devidthe instance ID of the device to query.
specon return, will be filled with device details.
sample_framespointer to store device buffer size, in sample frames. Can be NULL.
Returns
true on success or false on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.

◆ SDL_GetAudioDeviceGain()

float SDL_GetAudioDeviceGain ( SDL_AudioDeviceID  devid)
extern

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
devidthe audio device to query.
Returns
the gain of the device or -1.0f on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_SetAudioDeviceGain

◆ SDL_GetAudioDeviceName()

const char * SDL_GetAudioDeviceName ( SDL_AudioDeviceID  devid)
extern

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

WARNING: this function will work with SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK and SDL_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
devidthe instance ID of the device to query.
Returns
the name of the audio device, or NULL on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_GetAudioPlaybackDevices
SDL_GetAudioRecordingDevices

◆ SDL_GetAudioDriver()

const char * SDL_GetAudioDriver ( int  index)
extern

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
indexthe index of the audio driver; the value ranges from 0 to SDL_GetNumAudioDrivers() - 1.
Returns
the name of the audio driver at the requested index, or NULL if an invalid index was specified.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_GetNumAudioDrivers

◆ SDL_GetAudioFormatName()

const char * SDL_GetAudioFormatName ( SDL_AudioFormat  format)
extern

Get the human readable name of an audio format.

Parameters
formatthe audio format to query.
Returns
the human readable name of the specified audio format or "SDL_AUDIO_UNKNOWN" if the format isn't recognized.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.

◆ SDL_GetAudioPlaybackDevices()

SDL_AudioDeviceID * SDL_GetAudioPlaybackDevices ( int *  count)
extern

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 SDL_GetAudioRecordingDevices() instead.

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

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

Parameters
counta pointer filled in with the number of devices returned, may be NULL.
Returns
a 0 terminated array of device instance IDs or NULL on error; call SDL_GetError() for more information. This should be freed with SDL_free() when it is no longer needed.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_OpenAudioDevice
SDL_GetAudioRecordingDevices

◆ SDL_GetAudioRecordingDevices()

SDL_AudioDeviceID * SDL_GetAudioRecordingDevices ( int *  count)
extern

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 SDL_GetAudioPlaybackDevices() instead.

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

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

Parameters
counta pointer filled in with the number of devices returned, may be NULL.
Returns
a 0 terminated array of device instance IDs, or NULL on failure; call SDL_GetError() for more information. This should be freed with SDL_free() when it is no longer needed.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_OpenAudioDevice
SDL_GetAudioPlaybackDevices

◆ SDL_GetAudioStreamAvailable()

int SDL_GetAudioStreamAvailable ( SDL_AudioStream *  stream)
extern

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 SDL_GetAudioStreamData before this function's return value is no longer clamped.

Parameters
streamthe audio stream to query.
Returns
the number of converted/resampled bytes available or -1 on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_GetAudioStreamData
SDL_PutAudioStreamData

◆ SDL_GetAudioStreamData()

int SDL_GetAudioStreamData ( SDL_AudioStream *  stream,
void *  buf,
int  len 
)
extern

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

Note that any conversion and resampling necessary is done during this call, and SDL_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
streamthe stream the audio is being requested from.
bufa buffer to fill with audio data.
lenthe maximum number of bytes to fill.
Returns
the number of bytes read from the stream or -1 on failure; call SDL_GetError() for more information.

\threadsafety 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
SDL_ClearAudioStream
SDL_GetAudioStreamAvailable
SDL_PutAudioStreamData

◆ SDL_GetAudioStreamDevice()

SDL_AudioDeviceID SDL_GetAudioStreamDevice ( SDL_AudioStream *  stream)
extern

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
streamthe audio stream to query.
Returns
the bound audio device, or 0 if not bound or invalid.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_BindAudioStream
SDL_BindAudioStreams

◆ SDL_GetAudioStreamFormat()

bool SDL_GetAudioStreamFormat ( SDL_AudioStream *  stream,
SDL_AudioSpec *  src_spec,
SDL_AudioSpec *  dst_spec 
)
extern

Query the current format of an audio stream.

Parameters
streamthe SDL_AudioStream to query.
src_specwhere to store the input audio format; ignored if NULL.
dst_specwhere to store the output audio format; ignored if NULL.
Returns
true on success or false on failure; call SDL_GetError() for more information.

\threadsafety 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
SDL_SetAudioStreamFormat

◆ SDL_GetAudioStreamFrequencyRatio()

float SDL_GetAudioStreamFrequencyRatio ( SDL_AudioStream *  stream)
extern

Get the frequency ratio of an audio stream.

Parameters
streamthe SDL_AudioStream to query.
Returns
the frequency ratio of the stream or 0.0 on failure; call SDL_GetError() for more information.

\threadsafety 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
SDL_SetAudioStreamFrequencyRatio

◆ SDL_GetAudioStreamGain()

float SDL_GetAudioStreamGain ( SDL_AudioStream *  stream)
extern

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
streamthe SDL_AudioStream to query.
Returns
the gain of the stream or -1.0f on failure; call SDL_GetError() for more information.

\threadsafety 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
SDL_SetAudioStreamGain

◆ SDL_GetAudioStreamInputChannelMap()

int * SDL_GetAudioStreamInputChannelMap ( SDL_AudioStream *  stream,
int *  count 
)
extern

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

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

Parameters
streamthe SDL_AudioStream to query.
countOn output, set to number of channels in the map. Can be NULL.
Returns
an array of the current channel mapping, with as many elements as the current output spec's channels, or NULL if default. This should be freed with SDL_free() when it is no longer needed.

\threadsafety 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
SDL_SetAudioStreamInputChannelMap

◆ SDL_GetAudioStreamOutputChannelMap()

int * SDL_GetAudioStreamOutputChannelMap ( SDL_AudioStream *  stream,
int *  count 
)
extern

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

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

Parameters
streamthe SDL_AudioStream to query.
countOn output, set to number of channels in the map. Can be NULL.
Returns
an array of the current channel mapping, with as many elements as the current output spec's channels, or NULL if default. This should be freed with SDL_free() when it is no longer needed.

\threadsafety 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
SDL_SetAudioStreamInputChannelMap

◆ SDL_GetAudioStreamProperties()

SDL_PropertiesID SDL_GetAudioStreamProperties ( SDL_AudioStream *  stream)
extern

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:

  • 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 SDL_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
streamthe SDL_AudioStream to query.
Returns
a valid property ID on success or 0 on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.

◆ SDL_GetAudioStreamQueued()

int SDL_GetAudioStreamQueued ( SDL_AudioStream *  stream)
extern

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 SDL_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 SDL_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 SDL_GetAudioStreamData before this function's return value is no longer clamped.

Parameters
streamthe audio stream to query.
Returns
the number of bytes queued or -1 on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_PutAudioStreamData
SDL_ClearAudioStream

◆ SDL_GetCurrentAudioDriver()

const char * SDL_GetCurrentAudioDriver ( void  )
extern

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 NULL if no driver has been initialized.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.

◆ SDL_GetNumAudioDrivers()

int SDL_GetNumAudioDrivers ( void  )
extern

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.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_GetAudioDriver

◆ SDL_GetSilenceValueForFormat()

int SDL_GetSilenceValueForFormat ( SDL_AudioFormat  format)
extern

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 SDL_memset) to set an audio buffer in a specific format to silence.

Parameters
formatthe audio data format to query.
Returns
a byte value that can be passed to memset.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.

◆ SDL_IsAudioDevicePhysical()

bool SDL_IsAudioDevicePhysical ( SDL_AudioDeviceID  devid)
extern

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

An SDL_AudioDeviceID 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 SDL_OpenAudioDevice or SDL_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
devidthe device ID to query.
Returns
true if devid is a physical device, false if it is logical.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.

◆ SDL_IsAudioDevicePlayback()

bool SDL_IsAudioDevicePlayback ( SDL_AudioDeviceID  devid)
extern

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
devidthe device ID to query.
Returns
true if devid is a playback device, false if it is recording.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.

◆ SDL_LoadWAV()

bool SDL_LoadWAV ( const char *  path,
SDL_AudioSpec *  spec,
Uint8 **  audio_buf,
Uint32 *  audio_len 
)
extern

Loads a WAV from a file path.

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

SDL_LoadWAV_IO(SDL_IOFromFile(path, "rb"), true, spec, audio_buf, audio_len);
SDL_IOFromFile
SDL_IOStream * SDL_IOFromFile(const char *file, const char *mode)
Parameters
paththe file path of the WAV file to open.
speca pointer to an SDL_AudioSpec that will be set to the WAVE data's format details on successful return.
audio_bufa pointer filled with the audio data, allocated by the function.
audio_lena pointer filled with the length of the audio data buffer in bytes.
Returns
true on success. audio_buf will be filled with a pointer to an allocated buffer containing the audio data, and audio_len is filled with the length of that audio buffer in bytes.

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

When the application is done with the data returned in audio_buf, it should call SDL_free() to dispose of it.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_free
SDL_LoadWAV_IO

◆ SDL_LoadWAV_IO()

bool SDL_LoadWAV_IO ( SDL_IOStream *  src,
bool  closeio,
SDL_AudioSpec *  spec,
Uint8 **  audio_buf,
Uint32 *  audio_len 
)
extern

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 SDL_AudioSpec members freq, channels, and format are set to the values of the audio data in the buffer.

It's necessary to use SDL_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 NULL on error and in all cases (with the exception of src being NULL), an appropriate error message will be set.

It is required that the data source supports seeking.

Example:

SDL_LoadWAV_IO(SDL_IOFromFile("sample.wav", "rb"), true, &spec, &buf, &len);

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

SDL_LoadWAV("sample.wav", &spec, &buf, &len);
Parameters
srcthe data source for the WAVE data.
closeioif true, calls SDL_CloseIO() on src before returning, even in the case of an error.
speca pointer to an SDL_AudioSpec that will be set to the WAVE data's format details on successful return.
audio_bufa pointer filled with the audio data, allocated by the function.
audio_lena pointer filled with the length of the audio data buffer in bytes.
Returns
true on success. audio_buf will be filled with a pointer to an allocated buffer containing the audio data, and audio_len is filled with the length of that audio buffer in bytes.

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

When the application is done with the data returned in audio_buf, it should call SDL_free() to dispose of it.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_free
SDL_LoadWAV

◆ SDL_LockAudioStream()

bool SDL_LockAudioStream ( SDL_AudioStream *  stream)
extern

Lock an audio stream for serialized access.

Each SDL_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 SDL_LockMutex for an internal lock; it has all the same attributes (recursive locks are allowed, etc).

Parameters
streamthe audio stream to lock.
Returns
true on success or false on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_UnlockAudioStream

◆ SDL_MixAudio()

bool SDL_MixAudio ( Uint8 *  dst,
const Uint8 *  src,
SDL_AudioFormat  format,
Uint32  len,
float  volume 
)
extern

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, SDL_MixAudio() is really only needed when you're mixing a single audio stream with a volume adjustment.

Parameters
dstthe destination for the mixed audio.
srcthe source audio buffer to be mixed.
formatthe SDL_AudioFormat structure representing the desired audio format.
lenthe length of the audio buffer in bytes.
volumeranges from 0.0 - 1.0, and should be set to 1.0 for full audio volume.
Returns
true on success or false on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.

◆ SDL_OpenAudioDevice()

SDL_AudioDeviceID SDL_OpenAudioDevice ( SDL_AudioDeviceID  devid,
const SDL_AudioSpec *  spec 
)
extern

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 SDL_OpenAudioDeviceStream instead of this function).

If you don't care about opening a specific device, pass a devid of either SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK or SDL_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. SDL_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 SDL_AudioDeviceID 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 SDL_AudioDeviceID 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 SDL_CloseAudioDevice() on the returned device id.

Parameters
devidthe device instance id to open, or SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK or SDL_AUDIO_DEVICE_DEFAULT_RECORDING for the most reasonable default device.
specthe requested device configuration. Can be NULL to use reasonable defaults.
Returns
the device ID on success or 0 on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_CloseAudioDevice
SDL_GetAudioDeviceFormat

◆ SDL_OpenAudioDeviceStream()

SDL_AudioStream * SDL_OpenAudioDeviceStream ( SDL_AudioDeviceID  devid,
const SDL_AudioSpec *  spec,
SDL_AudioStreamCallback  callback,
void *  userdata 
)
extern

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 SDL_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 SDL_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 NULL, the system will choose the format, and the app can use SDL_GetAudioStreamFormat() to obtain this information later.

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

One can optionally provide a callback function; if NULL, 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 SDL_DestroyAudioStream will also close the audio device associated with this stream.

Parameters
devidan audio device to open, or SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK or SDL_AUDIO_DEVICE_DEFAULT_RECORDING.
specthe audio stream's data format. Can be NULL.
callbacka callback where the app will provide new data for playback, or receive new data for recording. Can be NULL, in which case the app will need to call SDL_PutAudioStreamData or SDL_GetAudioStreamData as necessary.
userdataapp-controlled pointer passed to callback. Can be NULL. Ignored if callback is NULL.
Returns
an audio stream on success, ready to use, or NULL on failure; call SDL_GetError() for more information. When done with this stream, call SDL_DestroyAudioStream to free resources and close the device.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_GetAudioStreamDevice
SDL_ResumeAudioStreamDevice

◆ SDL_PauseAudioDevice()

bool SDL_PauseAudioDevice ( SDL_AudioDeviceID  devid)
extern

Use this function to pause audio playback on a specified device.

This function pauses audio processing for a given device. Any bound audio streams will not progress, and no audio will be generated. Pausing one device does not prevent other unpaused devices from running.

Unlike in SDL2, audio devices start in an unpaused state, since an app has to bind a stream before any audio will flow. Pausing a paused device is a legal no-op.

Pausing a device can be useful to halt all audio without unbinding all the audio streams. This might be useful while a game is paused, or a level is loading, etc.

Physical devices can not be paused or unpaused, only logical devices created through SDL_OpenAudioDevice() can be.

Parameters
devida device opened by SDL_OpenAudioDevice().
Returns
true on success or false on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_ResumeAudioDevice
SDL_AudioDevicePaused

◆ SDL_PauseAudioStreamDevice()

bool SDL_PauseAudioStreamDevice ( SDL_AudioStream *  stream)
extern

Use this function to pause audio playback on the audio device associated with an audio stream.

This function pauses audio processing for a given device. Any bound audio streams will not progress, and no audio will be generated. Pausing one device does not prevent other unpaused devices from running.

Pausing a device can be useful to halt all audio without unbinding all the audio streams. This might be useful while a game is paused, or a level is loading, etc.

Parameters
streamthe audio stream associated with the audio device to pause.
Returns
true on success or false on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_ResumeAudioStreamDevice

◆ SDL_PutAudioStreamData()

bool SDL_PutAudioStreamData ( SDL_AudioStream *  stream,
const void *  buf,
int  len 
)
extern

Add data to the stream.

This data must match the format/channels/samplerate specified in the latest call to SDL_SetAudioStreamFormat, or the format specified when creating the stream if it hasn't been changed.

Note that this call simply copies the unconverted data for later. This is different than SDL2, where data was converted during the Put call and the Get call would just dequeue the previously-converted data.

Parameters
streamthe stream the audio data is being added to.
bufa pointer to the audio data to add.
lenthe number of bytes to write to the stream.
Returns
true on success or false on failure; call SDL_GetError() for more information.

\threadsafety 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
SDL_ClearAudioStream
SDL_FlushAudioStream
SDL_GetAudioStreamData
SDL_GetAudioStreamQueued

◆ SDL_PutAudioStreamDataNoCopy()

bool SDL_PutAudioStreamDataNoCopy ( SDL_AudioStream *  stream,
const void *  buf,
int  len,
SDL_AudioStreamDataCompleteCallback  callback,
void *  userdata 
)
extern

Add external data to an audio stream without copying it.

Unlike SDL_PutAudioStreamData(), this function does not make a copy of the provided data, instead storing the provided pointer. This means that the put operation does not need to allocate and copy the data, but the original data must remain available until the stream is done with it, either by being read from the stream in its entirety, or a call to SDL_ClearAudioStream() or SDL_DestroyAudioStream().

The data must match the format/channels/samplerate specified in the latest call to SDL_SetAudioStreamFormat, or the format specified when creating the stream if it hasn't been changed.

An optional callback may be provided, which is called when the stream no longer needs the data. Once this callback fires, the stream will not access the data again. This callback will fire for any reason the data is no longer needed, including clearing or destroying the stream.

Note that there is still an allocation to store tracking information, so this function is more efficient for larger blocks of data. If you're planning to put a few samples at a time, it will be more efficient to use SDL_PutAudioStreamData(), which allocates and buffers in blocks.

Parameters
streamthe stream the audio data is being added to.
bufa pointer to the audio data to add.
lenthe number of bytes to add to the stream.
callbackthe callback function to call when the data is no longer needed by the stream. May be NULL.
userdataan opaque pointer provided to the callback for its own personal use.
Returns
true on success or false on failure; call SDL_GetError() for more information.

\threadsafety 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.4.0.
See also
SDL_ClearAudioStream
SDL_FlushAudioStream
SDL_GetAudioStreamData
SDL_GetAudioStreamQueued

◆ SDL_PutAudioStreamPlanarData()

bool SDL_PutAudioStreamPlanarData ( SDL_AudioStream *  stream,
const void *const *  channel_buffers,
int  num_channels,
int  num_samples 
)
extern

Add data to the stream with each channel in a separate array.

This data must match the format/channels/samplerate specified in the latest call to SDL_SetAudioStreamFormat, or the format specified when creating the stream if it hasn't been changed.

The data will be interleaved and queued. Note that SDL_AudioStream only operates on interleaved data, so this is simply a convenience function for easily queueing data from sources that provide separate arrays. There is no equivalent function to retrieve planar data.

The arrays in channel_buffers are ordered as they are to be interleaved; the first array will be the first sample in the interleaved data. Any individual array may be NULL; in this case, silence will be interleaved for that channel.

num_channels specifies how many arrays are in channel_buffers. This can be used as a safety to prevent overflow, in case the stream format has changed elsewhere. If more channels are specified than the current input spec, they are ignored. If less channels are specified, the missing arrays are treated as if they are NULL (silence is written to those channels). If the count is -1, SDL will assume the array count matches the current input spec.

Note that num_samples is the number of samples per array. This can also be thought of as the number of sample frames to be queued. A value of 1 with stereo arrays will queue two samples to the stream. This is different than SDL_PutAudioStreamData, which wants the size of a single array in bytes.

Parameters
streamthe stream the audio data is being added to.
channel_buffersa pointer to an array of arrays, one array per channel.
num_channelsthe number of arrays in channel_buffers or -1.
num_samplesthe number of samples per array to write to the stream.
Returns
true on success or false on failure; call SDL_GetError() for more information.

\threadsafety 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.4.0.
See also
SDL_ClearAudioStream
SDL_FlushAudioStream
SDL_GetAudioStreamData
SDL_GetAudioStreamQueued

◆ SDL_ResumeAudioDevice()

bool SDL_ResumeAudioDevice ( SDL_AudioDeviceID  devid)
extern

Use this function to unpause audio playback on a specified device.

This function unpauses audio processing for a given device that has previously been paused with SDL_PauseAudioDevice(). Once unpaused, any bound audio streams will begin to progress again, and audio can be generated.

Unlike in SDL2, audio devices start in an unpaused state, since an app has to bind a stream before any audio will flow. Unpausing an unpaused device is a legal no-op.

Physical devices can not be paused or unpaused, only logical devices created through SDL_OpenAudioDevice() can be.

Parameters
devida device opened by SDL_OpenAudioDevice().
Returns
true on success or false on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_AudioDevicePaused
SDL_PauseAudioDevice

◆ SDL_ResumeAudioStreamDevice()

bool SDL_ResumeAudioStreamDevice ( SDL_AudioStream *  stream)
extern

Use this function to unpause audio playback on the audio device associated with an audio stream.

This function unpauses audio processing for a given device that has previously been paused. Once unpaused, any bound audio streams will begin to progress again, and audio can be generated.

SDL_OpenAudioDeviceStream opens audio devices in a paused state, so this function call is required for audio playback to begin on such devices.

Parameters
streamthe audio stream associated with the audio device to resume.
Returns
true on success or false on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_PauseAudioStreamDevice

◆ SDL_SetAudioDeviceGain()

bool SDL_SetAudioDeviceGain ( SDL_AudioDeviceID  devid,
float  gain 
)
extern

Change 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 false when used on physical devices. While it might seem attractive to adjust several logical devices at once in this way, it would allow an app or library to interfere with another portion of the program's otherwise-isolated devices.

This is applied, along with any per-audiostream gain, during playback to the hardware, and can be continuously changed to create various effects. On recording devices, this will adjust the gain before passing the data into an audiostream; that recording audiostream can then adjust its gain further when outputting the data elsewhere, if it likes, but that second gain is not applied until the data leaves the audiostream again.

Parameters
devidthe audio device on which to change gain.
gainthe gain. 1.0f is no change, 0.0f is silence.
Returns
true on success or false on failure; call SDL_GetError() for more information.

\threadsafety 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
SDL_GetAudioDeviceGain

◆ SDL_SetAudioPostmixCallback()

bool SDL_SetAudioPostmixCallback ( SDL_AudioDeviceID  devid,
SDL_AudioPostmixCallback  callback,
void *  userdata 
)
extern

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

The buffer is the final mix of all bound audio streams on an opened device; this callback will fire regularly for any device that is both opened and unpaused. If there is no new data to mix, either because no streams are bound to the device or all the streams are empty, this callback will still fire with the entire buffer set to silence.

This callback is allowed to make changes to the data; the contents of the buffer after this call is what is ultimately passed along to the hardware.

The callback is always provided the data in float format (values from -1.0f to 1.0f), but the number of channels or sample rate may be different than the format the app requested when opening the device; SDL might have had to manage a conversion behind the scenes, or the playback might have jumped to new physical hardware when a system default changed, etc. These details may change between calls. Accordingly, the size of the buffer might change between calls as well.

This callback can run at any time, and from any thread; if you need to serialize access to your app's data, you should provide and use a mutex or other synchronization device.

All of this to say: there are specific needs this callback can fulfill, but it is not the simplest interface. Apps should generally provide audio in their preferred format through an SDL_AudioStream and let SDL handle the difference.

This function is extremely time-sensitive; the callback should do the least amount of work possible and return as quickly as it can. The longer the callback runs, the higher the risk of audio dropouts or other problems.

This function will block until the audio device is in between iterations, so any existing callback that might be running will finish before this function sets the new callback and returns.

Setting a NULL callback function disables any previously-set callback.

Parameters
devidthe ID of an opened audio device.
callbacka callback function to be called. Can be NULL.
userdataapp-controlled pointer passed to callback. Can be NULL.
Returns
true on success or false on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.

◆ SDL_SetAudioStreamFormat()

bool SDL_SetAudioStreamFormat ( SDL_AudioStream *  stream,
const SDL_AudioSpec *  src_spec,
const SDL_AudioSpec *  dst_spec 
)
extern

Change the input and output formats of an audio stream.

Future calls to and SDL_GetAudioStreamAvailable and SDL_GetAudioStreamData will reflect the new format, and future calls to SDL_PutAudioStreamData must provide data in the new input formats.

Data that was previously queued in the stream will still be operated on in the format that was current when it was added, which is to say you can put the end of a sound file in one format to a stream, change formats for the next sound file, and start putting that new data while the previous sound file is still queued, and everything will still play back correctly.

If a stream is bound to a device, then the format of the side of the stream bound to a device cannot be changed (src_spec for recording devices, dst_spec for playback devices). Attempts to make a change to this side will be ignored, but this will not report an error. The other side's format can be changed.

Parameters
streamthe stream the format is being changed.
src_specthe new format of the audio input; if NULL, it is not changed.
dst_specthe new format of the audio output; if NULL, it is not changed.
Returns
true on success or false on failure; call SDL_GetError() for more information.

\threadsafety 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
SDL_GetAudioStreamFormat
SDL_SetAudioStreamFrequencyRatio

◆ SDL_SetAudioStreamFrequencyRatio()

bool SDL_SetAudioStreamFrequencyRatio ( SDL_AudioStream *  stream,
float  ratio 
)
extern

Change the frequency ratio of an audio stream.

The frequency ratio is used to adjust the rate at which input data is consumed. Changing this effectively modifies the speed and pitch of the audio. A value greater than 1.0f will play the audio faster, and at a higher pitch. A value less than 1.0f will play the audio slower, and at a lower pitch. 1.0f means play at normal speed.

This is applied during SDL_GetAudioStreamData, and can be continuously changed to create various effects.

Parameters
streamthe stream on which the frequency ratio is being changed.
ratiothe frequency ratio. 1.0 is normal speed. Must be between 0.01 and 100.
Returns
true on success or false on failure; call SDL_GetError() for more information.

\threadsafety 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
SDL_GetAudioStreamFrequencyRatio
SDL_SetAudioStreamFormat

◆ SDL_SetAudioStreamGain()

bool SDL_SetAudioStreamGain ( SDL_AudioStream *  stream,
float  gain 
)
extern

Change 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).

This is applied during SDL_GetAudioStreamData, and can be continuously changed to create various effects.

Parameters
streamthe stream on which the gain is being changed.
gainthe gain. 1.0f is no change, 0.0f is silence.
Returns
true on success or false on failure; call SDL_GetError() for more information.

\threadsafety 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
SDL_GetAudioStreamGain

◆ SDL_SetAudioStreamGetCallback()

bool SDL_SetAudioStreamGetCallback ( SDL_AudioStream *  stream,
SDL_AudioStreamCallback  callback,
void *  userdata 
)
extern

Set a callback that runs when data is requested from an audio stream.

This callback is called before data is obtained from the stream, giving the callback the chance to add more on-demand.

The callback can (optionally) call SDL_PutAudioStreamData() to add more audio to the stream during this call; if needed, the request that triggered this callback will obtain the new data immediately.

The callback's additional_amount argument is roughly how many bytes of unconverted data (in the stream's input format) is needed by the caller, although this may overestimate a little for safety. This takes into account how much is already in the stream and only asks for any extra necessary to resolve the request, which means the callback may be asked for zero bytes, and a different amount on each call.

The callback is not required to supply exact amounts; it is allowed to supply too much or too little or none at all. The caller will get what's available, up to the amount they requested, regardless of this callback's outcome.

Clearing or flushing an audio stream does not call this callback.

This function obtains the stream's lock, which means any existing callback (get or put) in progress will finish running before setting the new callback.

Setting a NULL function turns off the callback.

Parameters
streamthe audio stream to set the new callback on.
callbackthe new callback function to call when data is requested from the stream.
userdataan opaque pointer provided to the callback for its own personal use.
Returns
true on success or false on failure; call SDL_GetError() for more information. This only fails if stream is NULL.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_SetAudioStreamPutCallback

◆ SDL_SetAudioStreamInputChannelMap()

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

Set 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 expects.

The input channel map reorders data that is added to a stream via SDL_PutAudioStreamData. Future calls to SDL_PutAudioStreamData must provide data in the new channel order.

Each item in the array represents an input channel, and its value is the channel that it should be remapped to. To reverse a stereo signal's left and right values, you'd have an array of { 1, 0 }. It is legal to remap multiple channels to the same thing, so { 1, 1 } would duplicate the right channel to both channels of a stereo signal. An element in the channel map set to -1 instead of a valid channel will mute that channel, setting it to a silence value.

You cannot change the number of channels through a channel map, just reorder/mute them.

Data that was previously queued in the stream will still be operated on in the order that was current when it was added, which is to say you can put the end of a sound file in one order to a stream, change orders for the next sound file, and start putting that new data while the previous sound file is still queued, and everything will still play back correctly.

Audio streams default to no remapping applied. Passing a NULL channel map is legal, and turns off remapping.

SDL will copy the channel map; the caller does not have to save this array after this call.

If count is not equal to the current number of channels in the audio stream's format, this will fail. This is a safety measure to make sure a race condition hasn't changed the format while this call is setting the channel map.

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

Parameters
streamthe SDL_AudioStream to change.
chmapthe new channel map, NULL to reset to default.
countThe number of channels in the map.
Returns
true on success or false on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread, as it holds a stream-specific mutex while running. Don't change the stream's format to have a different number of channels from a different thread at the same time, though!

Since
This function is available since SDL 3.2.0.
See also
SDL_SetAudioStreamOutputChannelMap

◆ SDL_SetAudioStreamOutputChannelMap()

bool SDL_SetAudioStreamOutputChannelMap ( SDL_AudioStream *  stream,
const int *  chmap,
int  count 
)
extern

Set 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 expects.

The output channel map reorders data that is leaving a stream via SDL_GetAudioStreamData.

Each item in the array represents an input channel, and its value is the channel that it should be remapped to. To reverse a stereo signal's left and right values, you'd have an array of { 1, 0 }. It is legal to remap multiple channels to the same thing, so { 1, 1 } would duplicate the right channel to both channels of a stereo signal. An element in the channel map set to -1 instead of a valid channel will mute that channel, setting it to a silence value.

You cannot change the number of channels through a channel map, just reorder/mute them.

The output channel map can be changed at any time, as output remapping is applied during SDL_GetAudioStreamData.

Audio streams default to no remapping applied. Passing a NULL channel map is legal, and turns off remapping.

SDL will copy the channel map; the caller does not have to save this array after this call.

If count is not equal to the current number of channels in the audio stream's format, this will fail. This is a safety measure to make sure a race condition hasn't changed the format while this call is setting the channel map.

Unlike attempting to change the stream's format, the output channel map on a stream bound to a recording device is permitted to change at any time; any data added to the stream after this call will have the new mapping, but previously-added data will still have the prior mapping. When the channel map doesn't match the hardware's channel layout, SDL will convert the data before feeding it to the device for playback.

Parameters
streamthe SDL_AudioStream to change.
chmapthe new channel map, NULL to reset to default.
countThe number of channels in the map.
Returns
true on success or false on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread, as it holds a stream-specific mutex while running. Don't change the stream's format to have a different number of channels from a a different thread at the same time, though!

Since
This function is available since SDL 3.2.0.
See also
SDL_SetAudioStreamInputChannelMap

◆ SDL_SetAudioStreamPutCallback()

bool SDL_SetAudioStreamPutCallback ( SDL_AudioStream *  stream,
SDL_AudioStreamCallback  callback,
void *  userdata 
)
extern

Set a callback that runs when data is added to an audio stream.

This callback is called after the data is added to the stream, giving the callback the chance to obtain it immediately.

The callback can (optionally) call SDL_GetAudioStreamData() to obtain audio from the stream during this call.

The callback's additional_amount argument is how many bytes of converted data (in the stream's output format) was provided by the caller, although this may underestimate a little for safety. This value might be less than what is currently available in the stream, if data was already there, and might be less than the caller provided if the stream needs to keep a buffer to aid in resampling. Which means the callback may be provided with zero bytes, and a different amount on each call.

The callback may call SDL_GetAudioStreamAvailable to see the total amount currently available to read from the stream, instead of the total provided by the current call.

The callback is not required to obtain all data. It is allowed to read less or none at all. Anything not read now simply remains in the stream for later access.

Clearing or flushing an audio stream does not call this callback.

This function obtains the stream's lock, which means any existing callback (get or put) in progress will finish running before setting the new callback.

Setting a NULL function turns off the callback.

Parameters
streamthe audio stream to set the new callback on.
callbackthe new callback function to call when data is added to the stream.
userdataan opaque pointer provided to the callback for its own personal use.
Returns
true on success or false on failure; call SDL_GetError() for more information. This only fails if stream is NULL.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_SetAudioStreamGetCallback

◆ SDL_UnbindAudioStream()

void SDL_UnbindAudioStream ( SDL_AudioStream *  stream)
extern

Unbind a single audio stream from its audio device.

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

Parameters
streaman audio stream to unbind from a device. Can be NULL.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_BindAudioStream

◆ SDL_UnbindAudioStreams()

void SDL_UnbindAudioStreams ( SDL_AudioStream *const *  streams,
int  num_streams 
)
extern

Unbind a list of audio streams from their audio devices.

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
streamsan array of audio streams to unbind. Can be NULL or contain NULL.
num_streamsnumber streams listed in the streams array.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.2.0.
See also
SDL_BindAudioStreams

◆ SDL_UnlockAudioStream()

bool SDL_UnlockAudioStream ( SDL_AudioStream *  stream)
extern

Unlock an audio stream for serialized access.

This unlocks an audio stream after a call to SDL_LockAudioStream.

Parameters
streamthe audio stream to unlock.
Returns
true on success or false on failure; call SDL_GetError() for more information.

\threadsafety You should only call this from the same thread that previously called SDL_LockAudioStream.

Since
This function is available since SDL 3.2.0.
See also
SDL_LockAudioStream