SDL 3.0
SDL_audio.h
Go to the documentation of this file.
1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2024 Sam Lantinga <slouken@libsdl.org>
4
5 This software is provided 'as-is', without any express or implied
6 warranty. In no event will the authors be held liable for any damages
7 arising from the use of this software.
8
9 Permission is granted to anyone to use this software for any purpose,
10 including commercial applications, and to alter it and redistribute it
11 freely, subject to the following restrictions:
12
13 1. The origin of this software must not be misrepresented; you must not
14 claim that you wrote the original software. If you use this software
15 in a product, an acknowledgment in the product documentation would be
16 appreciated but is not required.
17 2. Altered source versions must be plainly marked as such, and must not be
18 misrepresented as being the original software.
19 3. This notice may not be removed or altered from any source distribution.
20*/
21
22/**
23 * \file SDL_audio.h
24 *
25 * Audio functionality for the SDL library.
26 */
27
28#ifndef SDL_audio_h_
29#define SDL_audio_h_
30
31#include <SDL3/SDL_stdinc.h>
32#include <SDL3/SDL_endian.h>
33#include <SDL3/SDL_error.h>
34#include <SDL3/SDL_mutex.h>
35#include <SDL3/SDL_properties.h>
36#include <SDL3/SDL_iostream.h>
37#include <SDL3/SDL_thread.h>
38
39#include <SDL3/SDL_begin_code.h>
40/* Set up for C function definitions, even when using C++ */
41#ifdef __cplusplus
42extern "C" {
43#endif
44
45/*
46 * For multi-channel audio, the default SDL channel mapping is:
47 * 2: FL FR (stereo)
48 * 3: FL FR LFE (2.1 surround)
49 * 4: FL FR BL BR (quad)
50 * 5: FL FR LFE BL BR (4.1 surround)
51 * 6: FL FR FC LFE SL SR (5.1 surround - last two can also be BL BR)
52 * 7: FL FR FC LFE BC SL SR (6.1 surround)
53 * 8: FL FR FC LFE BL BR SL SR (7.1 surround)
54 */
55
56/**
57 * Audio format flags.
58 *
59 * These are what the 16 bits in SDL_AudioFormat currently mean...
60 * (Unspecified bits are always zero).
61 *
62 * ```
63 * ++-----------------------sample is signed if set
64 * ||
65 * || ++-----------sample is bigendian if set
66 * || ||
67 * || || ++---sample is float if set
68 * || || ||
69 * || || || +=--sample bit size--++
70 * || || || || ||
71 * 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00
72 * ```
73 *
74 * There are macros to query these bits.
75 *
76 * \since This datatype is available since SDL 3.0.0.
77 *
78 * \sa SDL_AUDIO_BITSIZE
79 * \sa SDL_AUDIO_BYTESIZE
80 * \sa SDL_AUDIO_ISINT
81 * \sa SDL_AUDIO_ISFLOAT
82 * \sa SDL_AUDIO_ISBIGENDIAN
83 * \sa SDL_AUDIO_ISLITTLEENDIAN
84 * \sa SDL_AUDIO_ISSIGNED
85 * \sa SDL_AUDIO_ISUNSIGNED
86 */
88
89#define SDL_AUDIO_U8 0x0008 /**< Unsigned 8-bit samples */
90#define SDL_AUDIO_S8 0x8008 /**< Signed 8-bit samples */
91
92#define SDL_AUDIO_S16LE 0x8010 /**< Signed 16-bit samples */
93#define SDL_AUDIO_S16BE 0x9010 /**< As above, but big-endian byte order */
94
95#define SDL_AUDIO_S32LE 0x8020 /**< 32-bit integer samples */
96#define SDL_AUDIO_S32BE 0x9020 /**< As above, but big-endian byte order */
97
98#define SDL_AUDIO_F32LE 0x8120 /**< 32-bit floating point samples */
99#define SDL_AUDIO_F32BE 0x9120 /**< As above, but big-endian byte order */
100
101#if SDL_BYTEORDER == SDL_LIL_ENDIAN
102#define SDL_AUDIO_S16 SDL_AUDIO_S16LE
103#define SDL_AUDIO_S32 SDL_AUDIO_S32LE
104#define SDL_AUDIO_F32 SDL_AUDIO_F32LE
105#else
106#define SDL_AUDIO_S16 SDL_AUDIO_S16BE
107#define SDL_AUDIO_S32 SDL_AUDIO_S32BE
108#define SDL_AUDIO_F32 SDL_AUDIO_F32BE
109#endif
110
111
112/* masks for different parts of SDL_AudioFormat. */
113#define SDL_AUDIO_MASK_BITSIZE (0xFF)
114#define SDL_AUDIO_MASK_FLOAT (1<<8)
115#define SDL_AUDIO_MASK_BIG_ENDIAN (1<<12)
116#define SDL_AUDIO_MASK_SIGNED (1<<15)
117
118
119/**
120 * Retrieve the size, in bits, from an SDL_AudioFormat.
121 *
122 * For example, `SDL_AUDIO_BITSIZE(SDL_AUDIO_S16)` returns 16.
123 *
124 * \param x an SDL_AudioFormat value
125 * \returns data size in bits
126 *
127 * \threadsafety It is safe to call this macro from any thread.
128 *
129 * \since This macro is available since SDL 3.0.0.
130 */
131#define SDL_AUDIO_BITSIZE(x) ((x) & SDL_AUDIO_MASK_BITSIZE)
132
133/**
134 * Retrieve the size, in bytes, from an SDL_AudioFormat.
135 *
136 * For example, `SDL_AUDIO_BYTESIZE(SDL_AUDIO_S16)` returns 2.
137 *
138 * \param x an SDL_AudioFormat value
139 * \returns data size in bytes
140 *
141 * \threadsafety It is safe to call this macro from any thread.
142 *
143 * \since This macro is available since SDL 3.0.0.
144 */
145#define SDL_AUDIO_BYTESIZE(x) (SDL_AUDIO_BITSIZE(x) / 8)
146
147/**
148 * Determine if an SDL_AudioFormat represents floating point data.
149 *
150 * For example, `SDL_AUDIO_ISFLOAT(SDL_AUDIO_S16)` returns 0.
151 *
152 * \param x an SDL_AudioFormat value
153 * \returns non-zero if format is floating point, zero otherwise.
154 *
155 * \threadsafety It is safe to call this macro from any thread.
156 *
157 * \since This macro is available since SDL 3.0.0.
158 */
159#define SDL_AUDIO_ISFLOAT(x) ((x) & SDL_AUDIO_MASK_FLOAT)
160
161/**
162 * Determine if an SDL_AudioFormat represents bigendian data.
163 *
164 * For example, `SDL_AUDIO_ISBIGENDIAN(SDL_AUDIO_S16LE)` returns 0.
165 *
166 * \param x an SDL_AudioFormat value
167 * \returns non-zero if format is bigendian, zero otherwise.
168 *
169 * \threadsafety It is safe to call this macro from any thread.
170 *
171 * \since This macro is available since SDL 3.0.0.
172 */
173#define SDL_AUDIO_ISBIGENDIAN(x) ((x) & SDL_AUDIO_MASK_BIG_ENDIAN)
174
175/**
176 * Determine if an SDL_AudioFormat represents littleendian data.
177 *
178 * For example, `SDL_AUDIO_ISLITTLEENDIAN(SDL_AUDIO_S16BE)` returns 0.
179 *
180 * \param x an SDL_AudioFormat value
181 * \returns non-zero if format is littleendian, zero otherwise.
182 *
183 * \threadsafety It is safe to call this macro from any thread.
184 *
185 * \since This macro is available since SDL 3.0.0.
186 */
187#define SDL_AUDIO_ISLITTLEENDIAN(x) (!SDL_AUDIO_ISBIGENDIAN(x))
188
189/**
190 * Determine if an SDL_AudioFormat represents signed data.
191 *
192 * For example, `SDL_AUDIO_ISSIGNED(SDL_AUDIO_U8)` returns 0.
193 *
194 * \param x an SDL_AudioFormat value
195 * \returns non-zero if format is signed, zero otherwise.
196 *
197 * \threadsafety It is safe to call this macro from any thread.
198 *
199 * \since This macro is available since SDL 3.0.0.
200 */
201#define SDL_AUDIO_ISSIGNED(x) ((x) & SDL_AUDIO_MASK_SIGNED)
202
203/**
204 * Determine if an SDL_AudioFormat represents integer data.
205 *
206 * For example, `SDL_AUDIO_ISINT(SDL_AUDIO_F32)` returns 0.
207 *
208 * \param x an SDL_AudioFormat value
209 * \returns non-zero if format is integer, zero otherwise.
210 *
211 * \threadsafety It is safe to call this macro from any thread.
212 *
213 * \since This macro is available since SDL 3.0.0.
214 */
215#define SDL_AUDIO_ISINT(x) (!SDL_AUDIO_ISFLOAT(x))
216
217/**
218 * Determine if an SDL_AudioFormat represents unsigned data.
219 *
220 * For example, `SDL_AUDIO_ISUNSIGNED(SDL_AUDIO_S16)` returns 0.
221 *
222 * \param x an SDL_AudioFormat value
223 * \returns non-zero if format is unsigned, zero otherwise.
224 *
225 * \threadsafety It is safe to call this macro from any thread.
226 *
227 * \since This macro is available since SDL 3.0.0.
228 */
229#define SDL_AUDIO_ISUNSIGNED(x) (!SDL_AUDIO_ISSIGNED(x))
230
231
232/**
233 * SDL Audio Device instance IDs.
234 *
235 * Zero is used to signify an invalid/null device.
236 *
237 * \since This datatype is available since SDL 3.0.0.
238 */
240
241/**
242 * A value used to request a default output audio device.
243 *
244 * Several functions that require an SDL_AudioDeviceID will accept this value
245 * to signify the app just wants the system to choose a default device instead
246 * of the app providing a specific one.
247 *
248 * \since This macro is available since SDL 3.0.0.
249 */
250#define SDL_AUDIO_DEVICE_DEFAULT_OUTPUT ((SDL_AudioDeviceID) 0xFFFFFFFF)
251
252/**
253 * A value used to request a default capture audio device.
254 *
255 * Several functions that require an SDL_AudioDeviceID will accept this value
256 * to signify the app just wants the system to choose a default device instead
257 * of the app providing a specific one.
258 *
259 * \since This macro is available since SDL 3.0.0.
260 */
261#define SDL_AUDIO_DEVICE_DEFAULT_CAPTURE ((SDL_AudioDeviceID) 0xFFFFFFFE)
262
263/**
264 * Format specifier for audio data.
265 *
266 * \since This struct is available since SDL 3.0.0.
267 *
268 * \sa SDL_AudioFormat
269 */
270typedef struct SDL_AudioSpec
271{
272 SDL_AudioFormat format; /**< Audio data format */
273 int channels; /**< Number of channels: 1 mono, 2 stereo, etc */
274 int freq; /**< sample rate: sample frames per second */
276
277/**
278 * Calculate the size of each audio frame (in bytes) from an SDL_AudioSpec.
279 *
280 * This reports on the size of an audio sample frame: stereo Sint16 data (2
281 * channels of 2 bytes each) would be 4 bytes per frame, for example.
282 *
283 * \param x an SDL_AudioSpec to query.
284 * \returns the number of bytes used per sample frame.
285 *
286 * \threadsafety It is safe to call this macro from any thread.
287 *
288 * \since This macro is available since SDL 3.0.0.
289 */
290#define SDL_AUDIO_FRAMESIZE(x) (SDL_AUDIO_BYTESIZE((x).format) * (x).channels)
291
292/**
293 * The opaque handle that represents an audio stream.
294 *
295 * SDL_AudioStream is an audio conversion interface.
296 *
297 * - It can handle resampling data in chunks without generating artifacts,
298 * when it doesn't have the complete buffer available.
299 * - It can handle incoming data in any variable size.
300 * - It can handle input/output format changes on the fly.
301 * - You push data as you have it, and pull it when you need it
302 * - It can also function as a basic audio data queue even if you just have
303 * sound that needs to pass from one place to another.
304 * - You can hook callbacks up to them when more data is added or requested,
305 * to manage data on-the-fly.
306 *
307 * Audio streams are the core of the SDL3 audio interface. You create one or
308 * more of them, bind them to an opened audio device, and feed data to them
309 * (or for recording, consume data from them).
310 *
311 * \since This struct is available since SDL 3.0.0.
312 *
313 * \sa SDL_CreateAudioStream
314 */
315struct SDL_AudioStream; /**< this is opaque to the outside world. */
317
318
319/* Function prototypes */
320
321/**
322 * \name Driver discovery functions
323 *
324 * These functions return the list of built in audio drivers, in the
325 * order that they are normally initialized by default.
326 */
327/* @{ */
328
329/**
330 * Use this function to get the number of built-in audio drivers.
331 *
332 * This function returns a hardcoded number. This never returns a negative
333 * value; if there are no drivers compiled into this build of SDL, this
334 * function returns zero. The presence of a driver in this list does not mean
335 * it will function, it just means SDL is capable of interacting with that
336 * interface. For example, a build of SDL might have esound support, but if
337 * there's no esound server available, SDL's esound driver would fail if used.
338 *
339 * By default, SDL tries all drivers, in its preferred order, until one is
340 * found to be usable.
341 *
342 * \returns the number of built-in audio drivers.
343 *
344 * \threadsafety It is safe to call this function from any thread.
345 *
346 * \since This function is available since SDL 3.0.0.
347 *
348 * \sa SDL_GetAudioDriver
349 */
350extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
351
352/**
353 * Use this function to get the name of a built in audio driver.
354 *
355 * The list of audio drivers is given in the order that they are normally
356 * initialized by default; the drivers that seem more reasonable to choose
357 * first (as far as the SDL developers believe) are earlier in the list.
358 *
359 * The names of drivers are all simple, low-ASCII identifiers, like "alsa",
360 * "coreaudio" or "xaudio2". These never have Unicode characters, and are not
361 * meant to be proper names.
362 *
363 * \param index the index of the audio driver; the value ranges from 0 to
364 * SDL_GetNumAudioDrivers() - 1
365 * \returns the name of the audio driver at the requested index, or NULL if an
366 * invalid index was specified.
367 *
368 * \threadsafety It is safe to call this function from any thread.
369 *
370 * \since This function is available since SDL 3.0.0.
371 *
372 * \sa SDL_GetNumAudioDrivers
373 */
374extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index);
375/* @} */
376
377/**
378 * Get the name of the current audio driver.
379 *
380 * The returned string points to internal static memory and thus never becomes
381 * invalid, even if you quit the audio subsystem and initialize a new driver
382 * (although such a case would return a different static string from another
383 * call to this function, of course). As such, you should not modify or free
384 * the returned string.
385 *
386 * \returns the name of the current audio driver or NULL if no driver has been
387 * initialized.
388 *
389 * \threadsafety It is safe to call this function from any thread.
390 *
391 * \since This function is available since SDL 3.0.0.
392 */
393extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
394
395/**
396 * Get a list of currently-connected audio output devices.
397 *
398 * This returns of list of available devices that play sound, perhaps to
399 * speakers or headphones ("output" devices). If you want devices that record
400 * audio, like a microphone ("capture" devices), use
401 * SDL_GetAudioCaptureDevices() instead.
402 *
403 * This only returns a list of physical devices; it will not have any device
404 * IDs returned by SDL_OpenAudioDevice().
405 *
406 * \param count a pointer filled in with the number of devices returned
407 * \returns a 0 terminated array of device instance IDs which should be freed
408 * with SDL_free(), or NULL on error; call SDL_GetError() for more
409 * details.
410 *
411 * \threadsafety It is safe to call this function from any thread.
412 *
413 * \since This function is available since SDL 3.0.0.
414 *
415 * \sa SDL_OpenAudioDevice
416 * \sa SDL_GetAudioCaptureDevices
417 */
418extern DECLSPEC SDL_AudioDeviceID *SDLCALL SDL_GetAudioOutputDevices(int *count);
419
420/**
421 * Get a list of currently-connected audio capture devices.
422 *
423 * This returns of list of available devices that record audio, like a
424 * microphone ("capture" devices). If you want devices that play sound,
425 * perhaps to speakers or headphones ("output" devices), use
426 * SDL_GetAudioOutputDevices() instead.
427 *
428 * This only returns a list of physical devices; it will not have any device
429 * IDs returned by SDL_OpenAudioDevice().
430 *
431 * \param count a pointer filled in with the number of devices returned
432 * \returns a 0 terminated array of device instance IDs which should be freed
433 * with SDL_free(), or NULL on error; call SDL_GetError() for more
434 * details.
435 *
436 * \threadsafety It is safe to call this function from any thread.
437 *
438 * \since This function is available since SDL 3.0.0.
439 *
440 * \sa SDL_OpenAudioDevice
441 * \sa SDL_GetAudioOutputDevices
442 */
443extern DECLSPEC SDL_AudioDeviceID *SDLCALL SDL_GetAudioCaptureDevices(int *count);
444
445/**
446 * Get the human-readable name of a specific audio device.
447 *
448 * The string returned by this function is UTF-8 encoded. The caller should
449 * call SDL_free on the return value when done with it.
450 *
451 * \param devid the instance ID of the device to query.
452 * \returns the name of the audio device, or NULL on error.
453 *
454 * \threadsafety It is safe to call this function from any thread.
455 *
456 * \since This function is available since SDL 3.0.0.
457 *
458 * \sa SDL_GetAudioOutputDevices
459 * \sa SDL_GetAudioCaptureDevices
460 * \sa SDL_GetDefaultAudioInfo
461 */
462extern DECLSPEC char *SDLCALL SDL_GetAudioDeviceName(SDL_AudioDeviceID devid);
463
464/**
465 * Get the current audio format of a specific audio device.
466 *
467 * For an opened device, this will report the format the device is currently
468 * using. If the device isn't yet opened, this will report the device's
469 * preferred format (or a reasonable default if this can't be determined).
470 *
471 * You may also specify SDL_AUDIO_DEVICE_DEFAULT_OUTPUT or
472 * SDL_AUDIO_DEVICE_DEFAULT_CAPTURE here, which is useful for getting a
473 * reasonable recommendation before opening the system-recommended default
474 * device.
475 *
476 * You can also use this to request the current device buffer size. This is
477 * specified in sample frames and represents the amount of data SDL will feed
478 * to the physical hardware in each chunk. This can be converted to
479 * milliseconds of audio with the following equation:
480 *
481 * `ms = (int) ((((Sint64) frames) * 1000) / spec.freq);`
482 *
483 * Buffer size is only important if you need low-level control over the audio
484 * playback timing. Most apps do not need this.
485 *
486 * \param devid the instance ID of the device to query.
487 * \param spec On return, will be filled with device details.
488 * \param sample_frames Pointer to store device buffer size, in sample frames.
489 * Can be NULL.
490 * \returns 0 on success or a negative error code on failure; call
491 * SDL_GetError() for more information.
492 *
493 * \threadsafety It is safe to call this function from any thread.
494 *
495 * \since This function is available since SDL 3.0.0.
496 */
497extern DECLSPEC int SDLCALL SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SDL_AudioSpec *spec, int *sample_frames);
498
499
500/**
501 * Open a specific audio device.
502 *
503 * You can open both output and capture devices through this function. Output
504 * devices will take data from bound audio streams, mix it, and send it to the
505 * hardware. Capture devices will feed any bound audio streams with a copy of
506 * any incoming data.
507 *
508 * An opened audio device starts out with no audio streams bound. To start
509 * audio playing, bind a stream and supply audio data to it. Unlike SDL2,
510 * there is no audio callback; you only bind audio streams and make sure they
511 * have data flowing into them (however, you can simulate SDL2's semantics
512 * fairly closely by using SDL_OpenAudioDeviceStream instead of this
513 * function).
514 *
515 * If you don't care about opening a specific device, pass a `devid` of either
516 * `SDL_AUDIO_DEVICE_DEFAULT_OUTPUT` or `SDL_AUDIO_DEVICE_DEFAULT_CAPTURE`. In
517 * this case, SDL will try to pick the most reasonable default, and may also
518 * switch between physical devices seamlessly later, if the most reasonable
519 * default changes during the lifetime of this opened device (user changed the
520 * default in the OS's system preferences, the default got unplugged so the
521 * system jumped to a new default, the user plugged in headphones on a mobile
522 * device, etc). Unless you have a good reason to choose a specific device,
523 * this is probably what you want.
524 *
525 * You may request a specific format for the audio device, but there is no
526 * promise the device will honor that request for several reasons. As such,
527 * it's only meant to be a hint as to what data your app will provide. Audio
528 * streams will accept data in whatever format you specify and manage
529 * conversion for you as appropriate. SDL_GetAudioDeviceFormat can tell you
530 * the preferred format for the device before opening and the actual format
531 * the device is using after opening.
532 *
533 * It's legal to open the same device ID more than once; each successful open
534 * will generate a new logical SDL_AudioDeviceID that is managed separately
535 * from others on the same physical device. This allows libraries to open a
536 * device separately from the main app and bind its own streams without
537 * conflicting.
538 *
539 * It is also legal to open a device ID returned by a previous call to this
540 * function; doing so just creates another logical device on the same physical
541 * device. This may be useful for making logical groupings of audio streams.
542 *
543 * This function returns the opened device ID on success. This is a new,
544 * unique SDL_AudioDeviceID that represents a logical device.
545 *
546 * Some backends might offer arbitrary devices (for example, a networked audio
547 * protocol that can connect to an arbitrary server). For these, as a change
548 * from SDL2, you should open a default device ID and use an SDL hint to
549 * specify the target if you care, or otherwise let the backend figure out a
550 * reasonable default. Most backends don't offer anything like this, and often
551 * this would be an end user setting an environment variable for their custom
552 * need, and not something an application should specifically manage.
553 *
554 * When done with an audio device, possibly at the end of the app's life, one
555 * should call SDL_CloseAudioDevice() on the returned device id.
556 *
557 * \param devid the device instance id to open, or
558 * SDL_AUDIO_DEVICE_DEFAULT_OUTPUT or
559 * SDL_AUDIO_DEVICE_DEFAULT_CAPTURE for the most reasonable
560 * default device.
561 * \param spec the requested device configuration. Can be NULL to use
562 * reasonable defaults.
563 * \returns The device ID on success, 0 on error; call SDL_GetError() for more
564 * information.
565 *
566 * \threadsafety It is safe to call this function from any thread.
567 *
568 * \since This function is available since SDL 3.0.0.
569 *
570 * \sa SDL_CloseAudioDevice
571 * \sa SDL_GetAudioDeviceFormat
572 */
573extern DECLSPEC SDL_AudioDeviceID SDLCALL SDL_OpenAudioDevice(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec);
574
575/**
576 * Use this function to pause audio playback on a specified device.
577 *
578 * This function pauses audio processing for a given device. Any bound audio
579 * streams will not progress, and no audio will be generated. Pausing one
580 * device does not prevent other unpaused devices from running.
581 *
582 * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app
583 * has to bind a stream before any audio will flow. Pausing a paused device is
584 * a legal no-op.
585 *
586 * Pausing a device can be useful to halt all audio without unbinding all the
587 * audio streams. This might be useful while a game is paused, or a level is
588 * loading, etc.
589 *
590 * Physical devices can not be paused or unpaused, only logical devices
591 * created through SDL_OpenAudioDevice() can be.
592 *
593 * \param dev a device opened by SDL_OpenAudioDevice()
594 * \returns 0 on success or a negative error code on failure; call
595 * SDL_GetError() for more information.
596 *
597 * \threadsafety It is safe to call this function from any thread.
598 *
599 * \since This function is available since SDL 3.0.0.
600 *
601 * \sa SDL_ResumeAudioDevice
602 * \sa SDL_AudioDevicePaused
603 */
604extern DECLSPEC int SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev);
605
606/**
607 * Use this function to unpause audio playback on a specified device.
608 *
609 * This function unpauses audio processing for a given device that has
610 * previously been paused with SDL_PauseAudioDevice(). Once unpaused, any
611 * bound audio streams will begin to progress again, and audio can be
612 * generated.
613 *
614 * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app
615 * has to bind a stream before any audio will flow. Unpausing an unpaused
616 * device is a legal no-op.
617 *
618 * Physical devices can not be paused or unpaused, only logical devices
619 * created through SDL_OpenAudioDevice() can be.
620 *
621 * \param dev a device opened by SDL_OpenAudioDevice()
622 * \returns 0 on success or a negative error code on failure; call
623 * SDL_GetError() for more information.
624 *
625 * \threadsafety It is safe to call this function from any thread.
626 *
627 * \since This function is available since SDL 3.0.0.
628 *
629 * \sa SDL_AudioDevicePaused
630 * \sa SDL_PauseAudioDevice
631 */
632extern DECLSPEC int SDLCALL SDL_ResumeAudioDevice(SDL_AudioDeviceID dev);
633
634/**
635 * Use this function to query if an audio device is paused.
636 *
637 * Unlike in SDL2, audio devices start in an _unpaused_ state, since an app
638 * has to bind a stream before any audio will flow.
639 *
640 * Physical devices can not be paused or unpaused, only logical devices
641 * created through SDL_OpenAudioDevice() can be. Physical and invalid device
642 * IDs will report themselves as unpaused here.
643 *
644 * \param dev a device opened by SDL_OpenAudioDevice()
645 * \returns SDL_TRUE if device is valid and paused, SDL_FALSE otherwise.
646 *
647 * \threadsafety It is safe to call this function from any thread.
648 *
649 * \since This function is available since SDL 3.0.0.
650 *
651 * \sa SDL_PauseAudioDevice
652 * \sa SDL_ResumeAudioDevice
653 */
655
656/**
657 * Close a previously-opened audio device.
658 *
659 * The application should close open audio devices once they are no longer
660 * needed.
661 *
662 * This function may block briefly while pending audio data is played by the
663 * hardware, so that applications don't drop the last buffer of data they
664 * supplied if terminating immediately afterwards.
665 *
666 * \param devid an audio device id previously returned by
667 * SDL_OpenAudioDevice()
668 *
669 * \threadsafety It is safe to call this function from any thread.
670 *
671 * \since This function is available since SDL 3.0.0.
672 *
673 * \sa SDL_OpenAudioDevice
674 */
675extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid);
676
677/**
678 * Bind a list of audio streams to an audio device.
679 *
680 * Audio data will flow through any bound streams. For an output device, data
681 * for all bound streams will be mixed together and fed to the device. For a
682 * capture device, a copy of recorded data will be provided to each bound
683 * stream.
684 *
685 * Audio streams can only be bound to an open device. This operation is
686 * atomic--all streams bound in the same call will start processing at the
687 * same time, so they can stay in sync. Also: either all streams will be bound
688 * or none of them will be.
689 *
690 * It is an error to bind an already-bound stream; it must be explicitly
691 * unbound first.
692 *
693 * Binding a stream to a device will set its output format for output devices,
694 * and its input format for capture devices, so they match the device's
695 * settings. The caller is welcome to change the other end of the stream's
696 * format at any time.
697 *
698 * \param devid an audio device to bind a stream to.
699 * \param streams an array of audio streams to unbind.
700 * \param num_streams Number streams listed in the `streams` array.
701 * \returns 0 on success, -1 on error; call SDL_GetError() for more
702 * information.
703 *
704 * \threadsafety It is safe to call this function from any thread.
705 *
706 * \since This function is available since SDL 3.0.0.
707 *
708 * \sa SDL_BindAudioStreams
709 * \sa SDL_UnbindAudioStream
710 * \sa SDL_GetAudioStreamDevice
711 */
712extern DECLSPEC int SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SDL_AudioStream **streams, int num_streams);
713
714/**
715 * Bind a single audio stream to an audio device.
716 *
717 * This is a convenience function, equivalent to calling
718 * `SDL_BindAudioStreams(devid, &stream, 1)`.
719 *
720 * \param devid an audio device to bind a stream to.
721 * \param stream an audio stream to bind to a device.
722 * \returns 0 on success, -1 on error; call SDL_GetError() for more
723 * information.
724 *
725 * \threadsafety It is safe to call this function from any thread.
726 *
727 * \since This function is available since SDL 3.0.0.
728 *
729 * \sa SDL_BindAudioStreams
730 * \sa SDL_UnbindAudioStream
731 * \sa SDL_GetAudioStreamDevice
732 */
733extern DECLSPEC int SDLCALL SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_AudioStream *stream);
734
735/**
736 * Unbind a list of audio streams from their audio devices.
737 *
738 * The streams being unbound do not all have to be on the same device. All
739 * streams on the same device will be unbound atomically (data will stop
740 * flowing through all unbound streams on the same device at the same time).
741 *
742 * Unbinding a stream that isn't bound to a device is a legal no-op.
743 *
744 * \param streams an array of audio streams to unbind.
745 * \param num_streams Number streams listed in the `streams` array.
746 *
747 * \threadsafety It is safe to call this function from any thread.
748 *
749 * \since This function is available since SDL 3.0.0.
750 *
751 * \sa SDL_BindAudioStreams
752 */
753extern DECLSPEC void SDLCALL SDL_UnbindAudioStreams(SDL_AudioStream **streams, int num_streams);
754
755/**
756 * Unbind a single audio stream from its audio device.
757 *
758 * This is a convenience function, equivalent to calling
759 * `SDL_UnbindAudioStreams(&stream, 1)`.
760 *
761 * \param stream an audio stream to unbind from a device.
762 *
763 * \threadsafety It is safe to call this function from any thread.
764 *
765 * \since This function is available since SDL 3.0.0.
766 *
767 * \sa SDL_BindAudioStream
768 */
769extern DECLSPEC void SDLCALL SDL_UnbindAudioStream(SDL_AudioStream *stream);
770
771/**
772 * Query an audio stream for its currently-bound device.
773 *
774 * This reports the audio device that an audio stream is currently bound to.
775 *
776 * If not bound, or invalid, this returns zero, which is not a valid device
777 * ID.
778 *
779 * \param stream the audio stream to query.
780 * \returns The bound audio device, or 0 if not bound or invalid.
781 *
782 * \threadsafety It is safe to call this function from any thread.
783 *
784 * \since This function is available since SDL 3.0.0.
785 *
786 * \sa SDL_BindAudioStream
787 * \sa SDL_BindAudioStreams
788 */
790
791/**
792 * Create a new audio stream.
793 *
794 * \param src_spec The format details of the input audio
795 * \param dst_spec The format details of the output audio
796 * \returns a new audio stream on success, or NULL on failure.
797 *
798 * \threadsafety It is safe to call this function from any thread.
799 *
800 * \since This function is available since SDL 3.0.0.
801 *
802 * \sa SDL_PutAudioStreamData
803 * \sa SDL_GetAudioStreamData
804 * \sa SDL_GetAudioStreamAvailable
805 * \sa SDL_FlushAudioStream
806 * \sa SDL_ClearAudioStream
807 * \sa SDL_ChangeAudioStreamOutput
808 * \sa SDL_DestroyAudioStream
809 */
810extern DECLSPEC SDL_AudioStream *SDLCALL SDL_CreateAudioStream(const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec);
811
812/**
813 * Get the properties associated with an audio stream.
814 *
815 * \param stream the SDL_AudioStream to query
816 * \returns a valid property ID on success or 0 on failure; call
817 * SDL_GetError() for more information.
818 *
819 * \since This function is available since SDL 3.0.0.
820 *
821 * \sa SDL_GetProperty
822 * \sa SDL_SetProperty
823 */
825
826/**
827 * Query the current format of an audio stream.
828 *
829 * \param stream the SDL_AudioStream to query.
830 * \param src_spec Where to store the input audio format; ignored if NULL.
831 * \param dst_spec Where to store the output audio format; ignored if NULL.
832 * \returns 0 on success, or -1 on error.
833 *
834 * \threadsafety It is safe to call this function from any thread, as it holds
835 * a stream-specific mutex while running.
836 *
837 * \since This function is available since SDL 3.0.0.
838 */
839extern DECLSPEC int SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream,
840 SDL_AudioSpec *src_spec,
841 SDL_AudioSpec *dst_spec);
842
843/**
844 * Change the input and output formats of an audio stream.
845 *
846 * Future calls to and SDL_GetAudioStreamAvailable and SDL_GetAudioStreamData
847 * will reflect the new format, and future calls to SDL_PutAudioStreamData
848 * must provide data in the new input formats.
849 *
850 * Data that was previously queued in the stream will still be operated on in
851 * the format that was current when it was added, which is to say you can put
852 * the end of a sound file in one format to a stream, change formats for the
853 * next sound file, and start putting that new data while the previous sound
854 * file is still queued, and everything will still play back correctly.
855 *
856 * \param stream The stream the format is being changed
857 * \param src_spec The new format of the audio input; if NULL, it is not
858 * changed.
859 * \param dst_spec The new format of the audio output; if NULL, it is not
860 * changed.
861 * \returns 0 on success, or -1 on error.
862 *
863 * \threadsafety It is safe to call this function from any thread, as it holds
864 * a stream-specific mutex while running.
865 *
866 * \since This function is available since SDL 3.0.0.
867 *
868 * \sa SDL_GetAudioStreamFormat
869 * \sa SDL_SetAudioStreamFrequencyRatio
870 */
871extern DECLSPEC int SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream,
872 const SDL_AudioSpec *src_spec,
873 const SDL_AudioSpec *dst_spec);
874
875/**
876 * Get the frequency ratio of an audio stream.
877 *
878 * \param stream the SDL_AudioStream to query.
879 * \returns the frequency ratio of the stream, or 0.0 on error
880 *
881 * \threadsafety It is safe to call this function from any thread, as it holds
882 * a stream-specific mutex while running.
883 *
884 * \since This function is available since SDL 3.0.0.
885 *
886 * \sa SDL_SetAudioStreamFrequencyRatio
887 */
888extern DECLSPEC float SDLCALL SDL_GetAudioStreamFrequencyRatio(SDL_AudioStream *stream);
889
890/**
891 * Change the frequency ratio of an audio stream.
892 *
893 * The frequency ratio is used to adjust the rate at which input data is
894 * consumed. Changing this effectively modifies the speed and pitch of the
895 * audio. A value greater than 1.0 will play the audio faster, and at a higher
896 * pitch. A value less than 1.0 will play the audio slower, and at a lower
897 * pitch.
898 *
899 * This is applied during SDL_GetAudioStreamData, and can be continuously
900 * changed to create various effects.
901 *
902 * \param stream The stream the frequency ratio is being changed
903 * \param ratio The frequency ratio. 1.0 is normal speed. Must be between 0.01
904 * and 100.
905 * \returns 0 on success, or -1 on error.
906 *
907 * \threadsafety It is safe to call this function from any thread, as it holds
908 * a stream-specific mutex while running.
909 *
910 * \since This function is available since SDL 3.0.0.
911 *
912 * \sa SDL_GetAudioStreamFrequencyRatio
913 * \sa SDL_SetAudioStreamFormat
914 */
915extern DECLSPEC int SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream *stream, float ratio);
916
917/**
918 * Add data to the stream.
919 *
920 * This data must match the format/channels/samplerate specified in the latest
921 * call to SDL_SetAudioStreamFormat, or the format specified when creating the
922 * stream if it hasn't been changed.
923 *
924 * Note that this call simply copies the unconverted data for later. This is
925 * different than SDL2, where data was converted during the Put call and the
926 * Get call would just dequeue the previously-converted data.
927 *
928 * \param stream The stream the audio data is being added to
929 * \param buf A pointer to the audio data to add
930 * \param len The number of bytes to write to the stream
931 * \returns 0 on success or a negative error code on failure; call
932 * SDL_GetError() for more information.
933 *
934 * \threadsafety It is safe to call this function from any thread, but if the
935 * stream has a callback set, the caller might need to manage
936 * extra locking.
937 *
938 * \since This function is available since SDL 3.0.0.
939 *
940 * \sa SDL_ClearAudioStream
941 * \sa SDL_FlushAudioStream
942 * \sa SDL_GetAudioStreamData
943 * \sa SDL_GetAudioStreamQueued
944 */
945extern DECLSPEC int SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream, const void *buf, int len);
946
947/**
948 * Get converted/resampled data from the stream.
949 *
950 * The input/output data format/channels/samplerate is specified when creating
951 * the stream, and can be changed after creation by calling
952 * SDL_SetAudioStreamFormat.
953 *
954 * Note that any conversion and resampling necessary is done during this call,
955 * and SDL_PutAudioStreamData simply queues unconverted data for later. This
956 * is different than SDL2, where that work was done while inputting new data
957 * to the stream and requesting the output just copied the converted data.
958 *
959 * \param stream The stream the audio is being requested from
960 * \param buf A buffer to fill with audio data
961 * \param len The maximum number of bytes to fill
962 * \returns the number of bytes read from the stream, or -1 on error
963 *
964 * \threadsafety It is safe to call this function from any thread, but if the
965 * stream has a callback set, the caller might need to manage
966 * extra locking.
967 *
968 * \since This function is available since SDL 3.0.0.
969 *
970 * \sa SDL_ClearAudioStream
971 * \sa SDL_GetAudioStreamAvailable
972 * \sa SDL_PutAudioStreamData
973 */
974extern DECLSPEC int SDLCALL SDL_GetAudioStreamData(SDL_AudioStream *stream, void *buf, int len);
975
976/**
977 * Get the number of converted/resampled bytes available.
978 *
979 * The stream may be buffering data behind the scenes until it has enough to
980 * resample correctly, so this number might be lower than what you expect, or
981 * even be zero. Add more data or flush the stream if you need the data now.
982 *
983 * If the stream has so much data that it would overflow an int, the return
984 * value is clamped to a maximum value, but no queued data is lost; if there
985 * are gigabytes of data queued, the app might need to read some of it with
986 * SDL_GetAudioStreamData before this function's return value is no longer
987 * clamped.
988 *
989 * \param stream The audio stream to query
990 * \returns the number of converted/resampled bytes available.
991 *
992 * \threadsafety It is safe to call this function from any thread.
993 *
994 * \since This function is available since SDL 3.0.0.
995 *
996 * \sa SDL_GetAudioStreamData
997 * \sa SDL_PutAudioStreamData
998 */
999extern DECLSPEC int SDLCALL SDL_GetAudioStreamAvailable(SDL_AudioStream *stream);
1000
1001
1002/**
1003 * Get the number of bytes currently queued.
1004 *
1005 * Note that audio streams can change their input format at any time, even if
1006 * there is still data queued in a different format, so the returned byte
1007 * count will not necessarily match the number of _sample frames_ available.
1008 * Users of this API should be aware of format changes they make when feeding
1009 * a stream and plan accordingly.
1010 *
1011 * Queued data is not converted until it is consumed by
1012 * SDL_GetAudioStreamData, so this value should be representative of the exact
1013 * data that was put into the stream.
1014 *
1015 * If the stream has so much data that it would overflow an int, the return
1016 * value is clamped to a maximum value, but no queued data is lost; if there
1017 * are gigabytes of data queued, the app might need to read some of it with
1018 * SDL_GetAudioStreamData before this function's return value is no longer
1019 * clamped.
1020 *
1021 * \param stream The audio stream to query
1022 * \returns the number of bytes queued.
1023 *
1024 * \threadsafety It is safe to call this function from any thread.
1025 *
1026 * \since This function is available since SDL 3.0.0.
1027 *
1028 * \sa SDL_PutAudioStreamData
1029 * \sa SDL_ClearAudioStream
1030 */
1031extern DECLSPEC int SDLCALL SDL_GetAudioStreamQueued(SDL_AudioStream *stream);
1032
1033
1034/**
1035 * Tell the stream that you're done sending data, and anything being buffered
1036 * should be converted/resampled and made available immediately.
1037 *
1038 * It is legal to add more data to a stream after flushing, but there may be
1039 * audio gaps in the output. Generally this is intended to signal the end of
1040 * input, so the complete output becomes available.
1041 *
1042 * \param stream The audio stream to flush
1043 * \returns 0 on success or a negative error code on failure; call
1044 * SDL_GetError() for more information.
1045 *
1046 * \threadsafety It is safe to call this function from any thread.
1047 *
1048 * \since This function is available since SDL 3.0.0.
1049 *
1050 * \sa SDL_PutAudioStreamData
1051 */
1052extern DECLSPEC int SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream);
1053
1054/**
1055 * Clear any pending data in the stream.
1056 *
1057 * This drops any queued data, so there will be nothing to read from the
1058 * stream until more is added.
1059 *
1060 * \param stream The audio stream to clear
1061 * \returns 0 on success or a negative error code on failure; call
1062 * SDL_GetError() for more information.
1063 *
1064 * \threadsafety It is safe to call this function from any thread.
1065 *
1066 * \since This function is available since SDL 3.0.0.
1067 *
1068 * \sa SDL_GetAudioStreamAvailable
1069 * \sa SDL_GetAudioStreamData
1070 * \sa SDL_GetAudioStreamQueued
1071 * \sa SDL_PutAudioStreamData
1072 */
1073extern DECLSPEC int SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream);
1074
1075/**
1076 * Lock an audio stream for serialized access.
1077 *
1078 * Each SDL_AudioStream has an internal mutex it uses to protect its data
1079 * structures from threading conflicts. This function allows an app to lock
1080 * that mutex, which could be useful if registering callbacks on this stream.
1081 *
1082 * One does not need to lock a stream to use in it most cases, as the stream
1083 * manages this lock internally. However, this lock is held during callbacks,
1084 * which may run from arbitrary threads at any time, so if an app needs to
1085 * protect shared data during those callbacks, locking the stream guarantees
1086 * that the callback is not running while the lock is held.
1087 *
1088 * As this is just a wrapper over SDL_LockMutex for an internal lock; it has
1089 * all the same attributes (recursive locks are allowed, etc).
1090 *
1091 * \param stream The audio stream to lock.
1092 * \returns 0 on success or a negative error code on failure; call
1093 * SDL_GetError() for more information.
1094 *
1095 * \threadsafety It is safe to call this function from any thread.
1096 *
1097 * \since This function is available since SDL 3.0.0.
1098 *
1099 * \sa SDL_UnlockAudioStream
1100 */
1101extern DECLSPEC int SDLCALL SDL_LockAudioStream(SDL_AudioStream *stream);
1102
1103
1104/**
1105 * Unlock an audio stream for serialized access.
1106 *
1107 * This unlocks an audio stream after a call to SDL_LockAudioStream.
1108 *
1109 * \param stream The audio stream to unlock.
1110 * \returns 0 on success or a negative error code on failure; call
1111 * SDL_GetError() for more information.
1112 *
1113 * \threadsafety You should only call this from the same thread that
1114 * previously called SDL_LockAudioStream.
1115 *
1116 * \since This function is available since SDL 3.0.0.
1117 *
1118 * \sa SDL_LockAudioStream
1119 */
1120extern DECLSPEC int SDLCALL SDL_UnlockAudioStream(SDL_AudioStream *stream);
1121
1122/**
1123 * A callback that fires when data passes through an SDL_AudioStream.
1124 *
1125 * Apps can (optionally) register a callback with an audio stream that is
1126 * called when data is added with SDL_PutAudioStreamData, or requested with
1127 * SDL_GetAudioStreamData.
1128 *
1129 * Two values are offered here: one is the amount of additional data needed to
1130 * satisfy the immediate request (which might be zero if the stream already
1131 * has enough data queued) and the other is the total amount being requested.
1132 * In a Get call triggering a Put callback, these values can be different. In
1133 * a Put call triggering a Get callback, these values are always the same.
1134 *
1135 * Byte counts might be slightly overestimated due to buffering or resampling,
1136 * and may change from call to call.
1137 *
1138 * This callback is not required to do anything. Generally this is useful for
1139 * adding/reading data on demand, and the app will often put/get data as
1140 * appropriate, but the system goes on with the data currently available to it
1141 * if this callback does nothing.
1142 *
1143 * \param stream The SDL audio stream associated with this callback.
1144 * \param additional_amount The amount of data, in bytes, that is needed right
1145 * now.
1146 * \param total_amount The total amount of data requested, in bytes, that is
1147 * requested or available.
1148 * \param userdata An opaque pointer provided by the app for their personal
1149 * use.
1150 *
1151 * \threadsafety This callbacks may run from any thread, so if you need to
1152 * protect shared data, you should use SDL_LockAudioStream to
1153 * serialize access; this lock will be held before your callback
1154 * is called, so your callback does not need to manage the lock
1155 * explicitly.
1156 *
1157 * \since This datatype is available since SDL 3.0.0.
1158 *
1159 * \sa SDL_SetAudioStreamGetCallback
1160 * \sa SDL_SetAudioStreamPutCallback
1161 */
1162typedef void (SDLCALL *SDL_AudioStreamCallback)(void *userdata, SDL_AudioStream *stream, int additional_amount, int total_amount);
1163
1164/**
1165 * Set a callback that runs when data is requested from an audio stream.
1166 *
1167 * This callback is called _before_ data is obtained from the stream, giving
1168 * the callback the chance to add more on-demand.
1169 *
1170 * The callback can (optionally) call SDL_PutAudioStreamData() to add more
1171 * audio to the stream during this call; if needed, the request that triggered
1172 * this callback will obtain the new data immediately.
1173 *
1174 * The callback's `approx_request` argument is roughly how many bytes of
1175 * _unconverted_ data (in the stream's input format) is needed by the caller,
1176 * although this may overestimate a little for safety. This takes into account
1177 * how much is already in the stream and only asks for any extra necessary to
1178 * resolve the request, which means the callback may be asked for zero bytes,
1179 * and a different amount on each call.
1180 *
1181 * The callback is not required to supply exact amounts; it is allowed to
1182 * supply too much or too little or none at all. The caller will get what's
1183 * available, up to the amount they requested, regardless of this callback's
1184 * outcome.
1185 *
1186 * Clearing or flushing an audio stream does not call this callback.
1187 *
1188 * This function obtains the stream's lock, which means any existing callback
1189 * (get or put) in progress will finish running before setting the new
1190 * callback.
1191 *
1192 * Setting a NULL function turns off the callback.
1193 *
1194 * \param stream the audio stream to set the new callback on.
1195 * \param callback the new callback function to call when data is added to the
1196 * stream.
1197 * \param userdata an opaque pointer provided to the callback for its own
1198 * personal use.
1199 * \returns 0 on success, -1 on error. This only fails if `stream` is NULL.
1200 *
1201 * \threadsafety It is safe to call this function from any thread.
1202 *
1203 * \since This function is available since SDL 3.0.0.
1204 *
1205 * \sa SDL_SetAudioStreamPutCallback
1206 */
1207extern DECLSPEC int SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata);
1208
1209/**
1210 * Set a callback that runs when data is added to an audio stream.
1211 *
1212 * This callback is called _after_ the data is added to the stream, giving the
1213 * callback the chance to obtain it immediately.
1214 *
1215 * The callback can (optionally) call SDL_GetAudioStreamData() to obtain audio
1216 * from the stream during this call.
1217 *
1218 * The callback's `approx_request` argument is how many bytes of _converted_
1219 * data (in the stream's output format) was provided by the caller, although
1220 * this may underestimate a little for safety. This value might be less than
1221 * what is currently available in the stream, if data was already there, and
1222 * might be less than the caller provided if the stream needs to keep a buffer
1223 * to aid in resampling. Which means the callback may be provided with zero
1224 * bytes, and a different amount on each call.
1225 *
1226 * The callback may call SDL_GetAudioStreamAvailable to see the total amount
1227 * currently available to read from the stream, instead of the total provided
1228 * by the current call.
1229 *
1230 * The callback is not required to obtain all data. It is allowed to read less
1231 * or none at all. Anything not read now simply remains in the stream for
1232 * later access.
1233 *
1234 * Clearing or flushing an audio stream does not call this callback.
1235 *
1236 * This function obtains the stream's lock, which means any existing callback
1237 * (get or put) in progress will finish running before setting the new
1238 * callback.
1239 *
1240 * Setting a NULL function turns off the callback.
1241 *
1242 * \param stream the audio stream to set the new callback on.
1243 * \param callback the new callback function to call when data is added to the
1244 * stream.
1245 * \param userdata an opaque pointer provided to the callback for its own
1246 * personal use.
1247 * \returns 0 on success, -1 on error. This only fails if `stream` is NULL.
1248 *
1249 * \threadsafety It is safe to call this function from any thread.
1250 *
1251 * \since This function is available since SDL 3.0.0.
1252 *
1253 * \sa SDL_SetAudioStreamGetCallback
1254 */
1255extern DECLSPEC int SDLCALL SDL_SetAudioStreamPutCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata);
1256
1257
1258/**
1259 * Free an audio stream.
1260 *
1261 * This will release all allocated data, including any audio that is still
1262 * queued. You do not need to manually clear the stream first.
1263 *
1264 * If this stream was bound to an audio device, it is unbound during this
1265 * call. If this stream was created with SDL_OpenAudioDeviceStream, the audio
1266 * device that was opened alongside this stream's creation will be closed,
1267 * too.
1268 *
1269 * \param stream The audio stream to destroy.
1270 *
1271 * \threadsafety It is safe to call this function from any thread.
1272 *
1273 * \since This function is available since SDL 3.0.0.
1274 *
1275 * \sa SDL_CreateAudioStream
1276 */
1277extern DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream);
1278
1279
1280/**
1281 * Convenience function for straightforward audio init for the common case.
1282 *
1283 * If all your app intends to do is provide a single source of PCM audio, this
1284 * function allows you to do all your audio setup in a single call.
1285 *
1286 * This is also intended to be a clean means to migrate apps from SDL2.
1287 *
1288 * This function will open an audio device, create a stream and bind it.
1289 * Unlike other methods of setup, the audio device will be closed when this
1290 * stream is destroyed, so the app can treat the returned SDL_AudioStream as
1291 * the only object needed to manage audio playback.
1292 *
1293 * Also unlike other functions, the audio device begins paused. This is to map
1294 * more closely to SDL2-style behavior, since there is no extra step here to
1295 * bind a stream to begin audio flowing. The audio device should be resumed
1296 * with `SDL_ResumeAudioDevice(SDL_GetAudioStreamDevice(stream));`
1297 *
1298 * This function works with both playback and capture devices.
1299 *
1300 * The `spec` parameter represents the app's side of the audio stream. That
1301 * is, for recording audio, this will be the output format, and for playing
1302 * audio, this will be the input format.
1303 *
1304 * If you don't care about opening a specific audio device, you can (and
1305 * probably _should_), use SDL_AUDIO_DEVICE_DEFAULT_OUTPUT for playback and
1306 * SDL_AUDIO_DEVICE_DEFAULT_CAPTURE for recording.
1307 *
1308 * One can optionally provide a callback function; if NULL, the app is
1309 * expected to queue audio data for playback (or unqueue audio data if
1310 * capturing). Otherwise, the callback will begin to fire once the device is
1311 * unpaused.
1312 *
1313 * \param devid an audio device to open, or SDL_AUDIO_DEVICE_DEFAULT_OUTPUT or
1314 * SDL_AUDIO_DEVICE_DEFAULT_CAPTURE.
1315 * \param spec the audio stream's data format. Required.
1316 * \param callback A callback where the app will provide new data for
1317 * playback, or receive new data for capture. Can be NULL, in
1318 * which case the app will need to call SDL_PutAudioStreamData
1319 * or SDL_GetAudioStreamData as necessary.
1320 * \param userdata App-controlled pointer passed to callback. Can be NULL.
1321 * Ignored if callback is NULL.
1322 * \returns an audio stream on success, ready to use. NULL on error; call
1323 * SDL_GetError() for more information. When done with this stream,
1324 * call SDL_DestroyAudioStream to free resources and close the
1325 * device.
1326 *
1327 * \threadsafety It is safe to call this function from any thread.
1328 *
1329 * \since This function is available since SDL 3.0.0.
1330 *
1331 * \sa SDL_GetAudioStreamDevice
1332 * \sa SDL_ResumeAudioDevice
1333 */
1334extern DECLSPEC SDL_AudioStream *SDLCALL SDL_OpenAudioDeviceStream(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec, SDL_AudioStreamCallback callback, void *userdata);
1335
1336/**
1337 * A callback that fires when data is about to be fed to an audio device.
1338 *
1339 * This is useful for accessing the final mix, perhaps for writing a
1340 * visualizer or applying a final effect to the audio data before playback.
1341 *
1342 * This callback should run as quickly as possible and not block for any
1343 * significant time, as this callback delays submission of data to the audio
1344 * device, which can cause audio playback problems.
1345 *
1346 * The postmix callback _must_ be able to handle any audio data format
1347 * specified in `spec`, which can change between callbacks if the audio device
1348 * changed. However, this only covers frequency and channel count; data is
1349 * always provided here in SDL_AUDIO_F32 format.
1350 *
1351 * \param userdata a pointer provided by the app through
1352 * SDL_SetAudioDevicePostmixCallback, for its own use.
1353 * \param spec the current format of audio that is to be submitted to the
1354 * audio device.
1355 * \param buffer the buffer of audio samples to be submitted. The callback can
1356 * inspect and/or modify this data.
1357 * \param buflen the size of `buffer` in bytes.
1358 *
1359 * \threadsafety This will run from a background thread owned by SDL. The
1360 * application is responsible for locking resources the callback
1361 * touches that need to be protected.
1362 *
1363 * \since This datatype is available since SDL 3.0.0.
1364 *
1365 * \sa SDL_SetAudioDevicePostmixCallback
1366 */
1367typedef void (SDLCALL *SDL_AudioPostmixCallback)(void *userdata, const SDL_AudioSpec *spec, float *buffer, int buflen);
1368
1369/**
1370 * Set a callback that fires when data is about to be fed to an audio device.
1371 *
1372 * This is useful for accessing the final mix, perhaps for writing a
1373 * visualizer or applying a final effect to the audio data before playback.
1374 *
1375 * The buffer is the final mix of all bound audio streams on an opened device;
1376 * this callback will fire regularly for any device that is both opened and
1377 * unpaused. If there is no new data to mix, either because no streams are
1378 * bound to the device or all the streams are empty, this callback will still
1379 * fire with the entire buffer set to silence.
1380 *
1381 * This callback is allowed to make changes to the data; the contents of the
1382 * buffer after this call is what is ultimately passed along to the hardware.
1383 *
1384 * The callback is always provided the data in float format (values from -1.0f
1385 * to 1.0f), but the number of channels or sample rate may be different than
1386 * the format the app requested when opening the device; SDL might have had to
1387 * manage a conversion behind the scenes, or the playback might have jumped to
1388 * new physical hardware when a system default changed, etc. These details may
1389 * change between calls. Accordingly, the size of the buffer might change
1390 * between calls as well.
1391 *
1392 * This callback can run at any time, and from any thread; if you need to
1393 * serialize access to your app's data, you should provide and use a mutex or
1394 * other synchronization device.
1395 *
1396 * All of this to say: there are specific needs this callback can fulfill, but
1397 * it is not the simplest interface. Apps should generally provide audio in
1398 * their preferred format through an SDL_AudioStream and let SDL handle the
1399 * difference.
1400 *
1401 * This function is extremely time-sensitive; the callback should do the least
1402 * amount of work possible and return as quickly as it can. The longer the
1403 * callback runs, the higher the risk of audio dropouts or other problems.
1404 *
1405 * This function will block until the audio device is in between iterations,
1406 * so any existing callback that might be running will finish before this
1407 * function sets the new callback and returns.
1408 *
1409 * Setting a NULL callback function disables any previously-set callback.
1410 *
1411 * \param devid The ID of an opened audio device.
1412 * \param callback A callback function to be called. Can be NULL.
1413 * \param userdata App-controlled pointer passed to callback. Can be NULL.
1414 * \returns zero on success, -1 on error; call SDL_GetError() for more
1415 * information.
1416 *
1417 * \threadsafety It is safe to call this function from any thread.
1418 *
1419 * \since This function is available since SDL 3.0.0.
1420 */
1421extern DECLSPEC int SDLCALL SDL_SetAudioPostmixCallback(SDL_AudioDeviceID devid, SDL_AudioPostmixCallback callback, void *userdata);
1422
1423
1424/**
1425 * Load the audio data of a WAVE file into memory.
1426 *
1427 * Loading a WAVE file requires `src`, `spec`, `audio_buf` and `audio_len` to
1428 * be valid pointers. The entire data portion of the file is then loaded into
1429 * memory and decoded if necessary.
1430 *
1431 * Supported formats are RIFF WAVE files with the formats PCM (8, 16, 24, and
1432 * 32 bits), IEEE Float (32 bits), Microsoft ADPCM and IMA ADPCM (4 bits), and
1433 * A-law and mu-law (8 bits). Other formats are currently unsupported and
1434 * cause an error.
1435 *
1436 * If this function succeeds, the return value is zero and the pointer to the
1437 * audio data allocated by the function is written to `audio_buf` and its
1438 * length in bytes to `audio_len`. The SDL_AudioSpec members `freq`,
1439 * `channels`, and `format` are set to the values of the audio data in the
1440 * buffer.
1441 *
1442 * It's necessary to use SDL_free() to free the audio data returned in
1443 * `audio_buf` when it is no longer used.
1444 *
1445 * Because of the underspecification of the .WAV format, there are many
1446 * problematic files in the wild that cause issues with strict decoders. To
1447 * provide compatibility with these files, this decoder is lenient in regards
1448 * to the truncation of the file, the fact chunk, and the size of the RIFF
1449 * chunk. The hints `SDL_HINT_WAVE_RIFF_CHUNK_SIZE`,
1450 * `SDL_HINT_WAVE_TRUNCATION`, and `SDL_HINT_WAVE_FACT_CHUNK` can be used to
1451 * tune the behavior of the loading process.
1452 *
1453 * Any file that is invalid (due to truncation, corruption, or wrong values in
1454 * the headers), too big, or unsupported causes an error. Additionally, any
1455 * critical I/O error from the data source will terminate the loading process
1456 * with an error. The function returns NULL on error and in all cases (with
1457 * the exception of `src` being NULL), an appropriate error message will be
1458 * set.
1459 *
1460 * It is required that the data source supports seeking.
1461 *
1462 * Example:
1463 *
1464 * ```c
1465 * SDL_LoadWAV_IO(SDL_IOFromFile("sample.wav", "rb"), 1, &spec, &buf, &len);
1466 * ```
1467 *
1468 * Note that the SDL_LoadWAV function does this same thing for you, but in a
1469 * less messy way:
1470 *
1471 * ```c
1472 * SDL_LoadWAV("sample.wav", &spec, &buf, &len);
1473 * ```
1474 *
1475 * \param src The data source for the WAVE data
1476 * \param closeio If SDL_TRUE, calls SDL_CloseIO() on `src` before returning,
1477 * even in the case of an error
1478 * \param spec A pointer to an SDL_AudioSpec that will be set to the WAVE
1479 * data's format details on successful return
1480 * \param audio_buf A pointer filled with the audio data, allocated by the
1481 * function
1482 * \param audio_len A pointer filled with the length of the audio data buffer
1483 * in bytes
1484 * \returns 0 on success. `audio_buf` will be filled with a pointer to an
1485 * allocated buffer containing the audio data, and `audio_len` is
1486 * filled with the length of that audio buffer in bytes.
1487 *
1488 * This function returns -1 if the .WAV file cannot be opened, uses
1489 * an unknown data format, or is corrupt; call SDL_GetError() for
1490 * more information.
1491 *
1492 * When the application is done with the data returned in
1493 * `audio_buf`, it should call SDL_free() to dispose of it.
1494 *
1495 * \threadsafety It is safe to call this function from any thread.
1496 *
1497 * \since This function is available since SDL 3.0.0.
1498 *
1499 * \sa SDL_free
1500 * \sa SDL_LoadWAV
1501 */
1502extern DECLSPEC int SDLCALL SDL_LoadWAV_IO(SDL_IOStream * src, SDL_bool closeio,
1503 SDL_AudioSpec * spec, Uint8 ** audio_buf,
1504 Uint32 * audio_len);
1505
1506/**
1507 * Loads a WAV from a file path.
1508 *
1509 * This is a convenience function that is effectively the same as:
1510 *
1511 * ```c
1512 * SDL_LoadWAV_IO(SDL_IOFromFile(path, "rb"), 1, spec, audio_buf, audio_len);
1513 * ```
1514 *
1515 * \param path The file path of the WAV file to open.
1516 * \param spec A pointer to an SDL_AudioSpec that will be set to the WAVE
1517 * data's format details on successful return.
1518 * \param audio_buf A pointer filled with the audio data, allocated by the
1519 * function.
1520 * \param audio_len A pointer filled with the length of the audio data buffer
1521 * in bytes
1522 * \returns 0 on success. `audio_buf` will be filled with a pointer to an
1523 * allocated buffer containing the audio data, and `audio_len` is
1524 * filled with the length of that audio buffer in bytes.
1525 *
1526 * This function returns -1 if the .WAV file cannot be opened, uses
1527 * an unknown data format, or is corrupt; call SDL_GetError() for
1528 * more information.
1529 *
1530 * When the application is done with the data returned in
1531 * `audio_buf`, it should call SDL_free() to dispose of it.
1532 *
1533 * \threadsafety It is safe to call this function from any thread.
1534 *
1535 * \since This function is available since SDL 3.0.0.
1536 *
1537 * \sa SDL_free
1538 * \sa SDL_LoadWAV_IO
1539 */
1540extern DECLSPEC int SDLCALL SDL_LoadWAV(const char *path, SDL_AudioSpec * spec,
1541 Uint8 ** audio_buf, Uint32 * audio_len);
1542
1543
1544
1545#define SDL_MIX_MAXVOLUME 128
1546
1547/**
1548 * Mix audio data in a specified format.
1549 *
1550 * This takes an audio buffer `src` of `len` bytes of `format` data and mixes
1551 * it into `dst`, performing addition, volume adjustment, and overflow
1552 * clipping. The buffer pointed to by `dst` must also be `len` bytes of
1553 * `format` data.
1554 *
1555 * This is provided for convenience -- you can mix your own audio data.
1556 *
1557 * Do not use this function for mixing together more than two streams of
1558 * sample data. The output from repeated application of this function may be
1559 * distorted by clipping, because there is no accumulator with greater range
1560 * than the input (not to mention this being an inefficient way of doing it).
1561 *
1562 * It is a common misconception that this function is required to write audio
1563 * data to an output stream in an audio callback. While you can do that,
1564 * SDL_MixAudioFormat() is really only needed when you're mixing a single
1565 * audio stream with a volume adjustment.
1566 *
1567 * \param dst the destination for the mixed audio
1568 * \param src the source audio buffer to be mixed
1569 * \param format the SDL_AudioFormat structure representing the desired audio
1570 * format
1571 * \param len the length of the audio buffer in bytes
1572 * \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
1573 * for full audio volume
1574 * \returns 0 on success or a negative error code on failure; call
1575 * SDL_GetError() for more information.
1576 *
1577 * \threadsafety It is safe to call this function from any thread.
1578 *
1579 * \since This function is available since SDL 3.0.0.
1580 */
1581extern DECLSPEC int SDLCALL SDL_MixAudioFormat(Uint8 * dst,
1582 const Uint8 * src,
1583 SDL_AudioFormat format,
1584 Uint32 len, int volume);
1585
1586/**
1587 * Convert some audio data of one format to another format.
1588 *
1589 * Please note that this function is for convenience, but should not be used
1590 * to resample audio in blocks, as it will introduce audio artifacts on the
1591 * boundaries. You should only use this function if you are converting audio
1592 * data in its entirety in one call. If you want to convert audio in smaller
1593 * chunks, use an SDL_AudioStream, which is designed for this situation.
1594 *
1595 * Internally, this function creates and destroys an SDL_AudioStream on each
1596 * use, so it's also less efficient than using one directly, if you need to
1597 * convert multiple times.
1598 *
1599 * \param src_spec The format details of the input audio
1600 * \param src_data The audio data to be converted
1601 * \param src_len The len of src_data
1602 * \param dst_spec The format details of the output audio
1603 * \param dst_data Will be filled with a pointer to converted audio data,
1604 * which should be freed with SDL_free(). On error, it will be
1605 * NULL.
1606 * \param dst_len Will be filled with the len of dst_data
1607 * \returns 0 on success or a negative error code on failure; call
1608 * SDL_GetError() for more information.
1609 *
1610 * \threadsafety It is safe to call this function from any thread.
1611 *
1612 * \since This function is available since SDL 3.0.0.
1613 */
1614extern DECLSPEC int SDLCALL SDL_ConvertAudioSamples(const SDL_AudioSpec *src_spec,
1615 const Uint8 *src_data,
1616 int src_len,
1617 const SDL_AudioSpec *dst_spec,
1618 Uint8 **dst_data,
1619 int *dst_len);
1620
1621
1622/**
1623 * Get the appropriate memset value for silencing an audio format.
1624 *
1625 * The value returned by this function can be used as the second argument to
1626 * memset (or SDL_memset) to set an audio buffer in a specific format to
1627 * silence.
1628 *
1629 * \param format the audio data format to query.
1630 * \returns A byte value that can be passed to memset.
1631 *
1632 * \threadsafety It is safe to call this function from any thread.
1633 *
1634 * \since This function is available since SDL 3.0.0.
1635 */
1636extern DECLSPEC int SDLCALL SDL_GetSilenceValueForFormat(SDL_AudioFormat format);
1637
1638
1639/* Ends C function definitions when using C++ */
1640#ifdef __cplusplus
1641}
1642#endif
1643#include <SDL3/SDL_close_code.h>
1644
1645#endif /* SDL_audio_h_ */
int SDL_UnlockAudioStream(SDL_AudioStream *stream)
const char * SDL_GetAudioDriver(int index)
SDL_AudioStream * SDL_CreateAudioStream(const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec)
void SDL_UnbindAudioStream(SDL_AudioStream *stream)
int SDL_SetAudioPostmixCallback(SDL_AudioDeviceID devid, SDL_AudioPostmixCallback callback, void *userdata)
int SDL_SetAudioStreamPutCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata)
struct SDL_AudioStream SDL_AudioStream
Definition SDL_audio.h:316
int SDL_SetAudioStreamGetCallback(SDL_AudioStream *stream, SDL_AudioStreamCallback callback, void *userdata)
void(* SDL_AudioStreamCallback)(void *userdata, SDL_AudioStream *stream, int additional_amount, int total_amount)
Definition SDL_audio.h:1162
Uint16 SDL_AudioFormat
Definition SDL_audio.h:87
int SDL_FlushAudioStream(SDL_AudioStream *stream)
int SDL_GetNumAudioDrivers(void)
int SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream *stream, float ratio)
char * SDL_GetAudioDeviceName(SDL_AudioDeviceID devid)
Uint32 SDL_AudioDeviceID
Definition SDL_audio.h:239
int SDL_GetAudioStreamQueued(SDL_AudioStream *stream)
int 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)
int SDL_GetSilenceValueForFormat(SDL_AudioFormat format)
const char * SDL_GetCurrentAudioDriver(void)
SDL_PropertiesID SDL_GetAudioStreamProperties(SDL_AudioStream *stream)
int SDL_BindAudioStream(SDL_AudioDeviceID devid, SDL_AudioStream *stream)
SDL_AudioStream * SDL_OpenAudioDeviceStream(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec, SDL_AudioStreamCallback callback, void *userdata)
void(* SDL_AudioPostmixCallback)(void *userdata, const SDL_AudioSpec *spec, float *buffer, int buflen)
Definition SDL_audio.h:1367
int SDL_PauseAudioDevice(SDL_AudioDeviceID dev)
float SDL_GetAudioStreamFrequencyRatio(SDL_AudioStream *stream)
int SDL_GetAudioStreamAvailable(SDL_AudioStream *stream)
SDL_AudioDeviceID * SDL_GetAudioCaptureDevices(int *count)
int SDL_GetAudioDeviceFormat(SDL_AudioDeviceID devid, SDL_AudioSpec *spec, int *sample_frames)
int SDL_LoadWAV(const char *path, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len)
int SDL_PutAudioStreamData(SDL_AudioStream *stream, const void *buf, int len)
int SDL_BindAudioStreams(SDL_AudioDeviceID devid, SDL_AudioStream **streams, int num_streams)
SDL_bool SDL_AudioDevicePaused(SDL_AudioDeviceID dev)
void SDL_UnbindAudioStreams(SDL_AudioStream **streams, int num_streams)
void SDL_DestroyAudioStream(SDL_AudioStream *stream)
int SDL_LockAudioStream(SDL_AudioStream *stream)
int SDL_LoadWAV_IO(SDL_IOStream *src, SDL_bool closeio, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len)
void SDL_CloseAudioDevice(SDL_AudioDeviceID devid)
int SDL_GetAudioStreamData(SDL_AudioStream *stream, void *buf, int len)
int SDL_ResumeAudioDevice(SDL_AudioDeviceID dev)
int SDL_ClearAudioStream(SDL_AudioStream *stream)
SDL_AudioDeviceID * SDL_GetAudioOutputDevices(int *count)
int SDL_MixAudioFormat(Uint8 *dst, const Uint8 *src, SDL_AudioFormat format, Uint32 len, int volume)
SDL_AudioDeviceID SDL_OpenAudioDevice(SDL_AudioDeviceID devid, const SDL_AudioSpec *spec)
int SDL_SetAudioStreamFormat(SDL_AudioStream *stream, const SDL_AudioSpec *src_spec, const SDL_AudioSpec *dst_spec)
int SDL_GetAudioStreamFormat(SDL_AudioStream *stream, SDL_AudioSpec *src_spec, SDL_AudioSpec *dst_spec)
SDL_AudioDeviceID SDL_GetAudioStreamDevice(SDL_AudioStream *stream)
struct SDL_IOStream SDL_IOStream
Uint32 SDL_PropertiesID
uint8_t Uint8
Definition SDL_stdinc.h:188
uint16_t Uint16
Definition SDL_stdinc.h:206
int SDL_bool
Definition SDL_stdinc.h:170
uint32_t Uint32
Definition SDL_stdinc.h:224
SDL_AudioFormat format
Definition SDL_audio.h:272