devela::_dep::sdl3::sys

Module audio

Help

Available on crate feature dep_sdl3 only.

Expand description

Audio functionality for the SDL library.

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

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

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

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

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

§Logical audio devices

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

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

§Simplified audio

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

§Channel layouts

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

Abbreviations:

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

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

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

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

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

Structs§

SDL_AudioFormat: Audio format.
SDL_AudioSpec: Format specifier for audio data.
SDL_AudioStream: The opaque handle that represents an audio stream.

Constants§

SDL_AUDIO_DEVICE_DEFAULT_PLAYBACK: A value used to request a default playback audio device.
SDL_AUDIO_DEVICE_DEFAULT_RECORDING: A value used to request a default recording audio device.
SDL_AUDIO_F32
SDL_AUDIO_F32BE: As above, but big-endian byte order
SDL_AUDIO_F32LE: 32-bit floating point samples
SDL_AUDIO_MASK_BIG_ENDIAN: Mask of bits in an SDL_AudioFormat that contain the bigendian flag.
SDL_AUDIO_MASK_BITSIZE: Mask of bits in an SDL_AudioFormat that contains the format bit size.
SDL_AUDIO_MASK_FLOAT: Mask of bits in an SDL_AudioFormat that contain the floating point flag.
SDL_AUDIO_MASK_SIGNED: Mask of bits in an SDL_AudioFormat that contain the signed data flag.
SDL_AUDIO_S8: Signed 8-bit samples
SDL_AUDIO_S16
SDL_AUDIO_S32
SDL_AUDIO_S16BE: As above, but big-endian byte order
SDL_AUDIO_S16LE: Signed 16-bit samples
SDL_AUDIO_S32BE: As above, but big-endian byte order
SDL_AUDIO_S32LE: 32-bit integer samples
SDL_AUDIO_U8: Unsigned 8-bit samples
SDL_AUDIO_UNKNOWN: Unspecified audio format

Functions§

SDL_AUDIO_BITSIZE: Retrieve the size, in bits, from an SDL_AudioFormat.
SDL_AUDIO_BYTESIZE: Retrieve the size, in bytes, from an SDL_AudioFormat.
SDL_AUDIO_FRAMESIZE: Calculate the size of each audio frame (in bytes) from an SDL_AudioSpec.
SDL_AUDIO_ISBIGENDIAN: Determine if an SDL_AudioFormat represents bigendian data.
SDL_AUDIO_ISFLOAT: Determine if an SDL_AudioFormat represents floating point data.
SDL_AUDIO_ISINT: Determine if an SDL_AudioFormat represents integer data.
SDL_AUDIO_ISLITTLEENDIAN: Determine if an SDL_AudioFormat represents littleendian data.
SDL_AUDIO_ISSIGNED: Determine if an SDL_AudioFormat represents signed data.
SDL_AUDIO_ISUNSIGNED: Determine if an SDL_AudioFormat represents unsigned data.
SDL_AudioDevicePaused^⚠: Use this function to query if an audio device is paused.
SDL_AudioStreamDevicePaused^⚠: Use this function to query if an audio device associated with a stream is paused.
SDL_BindAudioStream^⚠: Bind a single audio stream to an audio device.
SDL_BindAudioStreams^⚠: Bind a list of audio streams to an audio device.
SDL_ClearAudioStream^⚠: Clear any pending data in the stream.
SDL_CloseAudioDevice^⚠: Close a previously-opened audio device.
SDL_ConvertAudioSamples^⚠: Convert some audio data of one format to another format.
SDL_CreateAudioStream^⚠: Create a new audio stream.
SDL_DEFINE_AUDIO_FORMAT: Define an SDL_AudioFormat value.
SDL_DestroyAudioStream^⚠: Free an audio stream.
SDL_FlushAudioStream^⚠: Tell the stream that you’re done sending data, and anything being buffered should be converted/resampled and made available immediately.
SDL_GetAudioDeviceChannelMap^⚠: Get the current channel map of an audio device.
SDL_GetAudioDeviceFormat^⚠: Get the current audio format of a specific audio device.
SDL_GetAudioDeviceGain^⚠: Get the gain of an audio device.
SDL_GetAudioDeviceName^⚠: Get the human-readable name of a specific audio device.
SDL_GetAudioDriver^⚠: Use this function to get the name of a built in audio driver.
SDL_GetAudioFormatName^⚠: Get the human readable name of an audio format.
SDL_GetAudioPlaybackDevices^⚠: Get a list of currently-connected audio playback devices.
SDL_GetAudioRecordingDevices^⚠: Get a list of currently-connected audio recording devices.
SDL_GetAudioStreamAvailable^⚠: Get the number of converted/resampled bytes available.
SDL_GetAudioStreamData^⚠: Get converted/resampled data from the stream.
SDL_GetAudioStreamDevice^⚠: Query an audio stream for its currently-bound device.
SDL_GetAudioStreamFormat^⚠: Query the current format of an audio stream.
SDL_GetAudioStreamFrequencyRatio^⚠: Get the frequency ratio of an audio stream.
SDL_GetAudioStreamGain^⚠: Get the gain of an audio stream.
SDL_GetAudioStreamInputChannelMap^⚠: Get the current input channel map of an audio stream.
SDL_GetAudioStreamOutputChannelMap^⚠: Get the current output channel map of an audio stream.
SDL_GetAudioStreamProperties^⚠: Get the properties associated with an audio stream.
SDL_GetAudioStreamQueued^⚠: Get the number of bytes currently queued.
SDL_GetCurrentAudioDriver^⚠: Get the name of the current audio driver.
SDL_GetNumAudioDrivers^⚠: Use this function to get the number of built-in audio drivers.
SDL_GetSilenceValueForFormat^⚠: Get the appropriate memset value for silencing an audio format.
SDL_IsAudioDevicePhysical^⚠: Determine if an audio device is physical (instead of logical).
SDL_IsAudioDevicePlayback^⚠: Determine if an audio device is a playback device (instead of recording).
SDL_LoadWAV^⚠: Loads a WAV from a file path.
SDL_LoadWAV_IO^⚠: Load the audio data of a WAVE file into memory.
SDL_LockAudioStream^⚠: Lock an audio stream for serialized access.
SDL_MixAudio^⚠: Mix audio data in a specified format.
SDL_OpenAudioDevice^⚠: Open a specific audio device.
SDL_OpenAudioDeviceStream^⚠: Convenience function for straightforward audio init for the common case.
SDL_PauseAudioDevice^⚠: Use this function to pause audio playback on a specified device.
SDL_PauseAudioStreamDevice^⚠: Use this function to pause audio playback on the audio device associated with an audio stream.
SDL_PutAudioStreamData^⚠: Add data to the stream.
SDL_ResumeAudioDevice^⚠: Use this function to unpause audio playback on a specified device.
SDL_ResumeAudioStreamDevice^⚠: Use this function to unpause audio playback on the audio device associated with an audio stream.
SDL_SetAudioDeviceGain^⚠: Change the gain of an audio device.
SDL_SetAudioPostmixCallback^⚠: Set a callback that fires when data is about to be fed to an audio device.
SDL_SetAudioStreamFormat^⚠: Change the input and output formats of an audio stream.
SDL_SetAudioStreamFrequencyRatio^⚠: Change the frequency ratio of an audio stream.
SDL_SetAudioStreamGain^⚠: Change the gain of an audio stream.
SDL_SetAudioStreamGetCallback^⚠: Set a callback that runs when data is requested from an audio stream.
SDL_SetAudioStreamInputChannelMap^⚠: Set the current input channel map of an audio stream.
SDL_SetAudioStreamOutputChannelMap^⚠: Set the current output channel map of an audio stream.
SDL_SetAudioStreamPutCallback^⚠: Set a callback that runs when data is added to an audio stream.
SDL_UnbindAudioStream^⚠: Unbind a single audio stream from its audio device.
SDL_UnbindAudioStreams^⚠: Unbind a list of audio streams from their audio devices.
SDL_UnlockAudioStream^⚠: Unlock an audio stream for serialized access.

Type Aliases§

SDL_AudioDeviceID: SDL Audio Device instance IDs.
SDL_AudioPostmixCallback: A callback that fires when data is about to be fed to an audio device.
SDL_AudioStreamCallback: A callback that fires when data passes through an SDL_AudioStream.

Module audioCopy item path