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