audio topic

CategoryAudio

Audio functionality for the SDL library.

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

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

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

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

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

Logical audio devices

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

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

Simplified audio

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

Channel layouts

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

Abbreviations:

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

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

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

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

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

Functions

sdlAudioDevicePaused(int devid) → bool audio
Use this function to query if an audio device is paused.
sdlAudioStreamDevicePaused(Pointer<SdlAudioStream> stream) → bool audio
Use this function to query if an audio device associated with a stream is paused.
sdlBindAudioStream(int devid, Pointer<SdlAudioStream> stream) → bool audio
Bind a single audio stream to an audio device.
sdlBindAudioStreams(int devid, Pointer<Pointer<SdlAudioStream>> streams, int numStreams) → bool audio
Bind a list of audio streams to an audio device.
sdlClearAudioStream(Pointer<SdlAudioStream> stream) → bool audio
Clear any pending data in the stream.
sdlCloseAudioDevice(int devid) → void audio
Close a previously-opened audio device.
sdlConvertAudioSamples(Pointer<SdlAudioSpec> srcSpec, Pointer<Uint8> srcData, int srcLen, Pointer<SdlAudioSpec> dstSpec, Pointer<Pointer<Uint8>> dstData, Pointer<Int32> dstLen) → bool audio
Convert some audio data of one format to another format.
sdlCreateAudioStream(Pointer<SdlAudioSpec> srcSpec, Pointer<SdlAudioSpec> dstSpec) → Pointer<SdlAudioStream> audio
Create a new audio stream.
sdlDestroyAudioStream(Pointer<SdlAudioStream> stream) → void audio
Free an audio stream.
sdlFlushAudioStream(Pointer<SdlAudioStream> stream) → bool audio
Tell the stream that you're done sending data, and anything being buffered should be converted/resampled and made available immediately.
sdlGetAudioDeviceChannelMap(int devid, Pointer<Int32> count) → Pointer<Int32> audio
Get the current channel map of an audio device.
sdlGetAudioDeviceFormat(int devid, Pointer<SdlAudioSpec> spec, Pointer<Int32> sampleFrames) → bool audio
Get the current audio format of a specific audio device.
sdlGetAudioDeviceGain(int devid) → double audio
Get the gain of an audio device.
sdlGetAudioDeviceName(int devid) → String? audio
Get the human-readable name of a specific audio device.
sdlGetAudioDriver(int index) → String? audio
Use this function to get the name of a built in audio driver.
sdlGetAudioFormatName(int format) → String? audio
Get the human readable name of an audio format.
sdlGetAudioPlaybackDevices(Pointer<Int32> count) → Pointer<Uint32> audio
Get a list of currently-connected audio playback devices.
sdlGetAudioRecordingDevices(Pointer<Int32> count) → Pointer<Uint32> audio
Get a list of currently-connected audio recording devices.
sdlGetAudioStreamAvailable(Pointer<SdlAudioStream> stream) → int audio
Get the number of converted/resampled bytes available.
sdlGetAudioStreamData(Pointer<SdlAudioStream> stream, Pointer<NativeType> buf, int len) → int audio
Get converted/resampled data from the stream.
sdlGetAudioStreamDevice(Pointer<SdlAudioStream> stream) → int audio
Query an audio stream for its currently-bound device.
sdlGetAudioStreamFormat(Pointer<SdlAudioStream> stream, Pointer<SdlAudioSpec> srcSpec, Pointer<SdlAudioSpec> dstSpec) → bool audio
Query the current format of an audio stream.
sdlGetAudioStreamFrequencyRatio(Pointer<SdlAudioStream> stream) → double audio
Get the frequency ratio of an audio stream.
sdlGetAudioStreamGain(Pointer<SdlAudioStream> stream) → double audio
Get the gain of an audio stream.
sdlGetAudioStreamInputChannelMap(Pointer<SdlAudioStream> stream, Pointer<Int32> count) → Pointer<Int32> audio
Get the current input channel map of an audio stream.
sdlGetAudioStreamOutputChannelMap(Pointer<SdlAudioStream> stream, Pointer<Int32> count) → Pointer<Int32> audio
Get the current output channel map of an audio stream.
sdlGetAudioStreamProperties(Pointer<SdlAudioStream> stream) → int audio
Get the properties associated with an audio stream.
sdlGetAudioStreamQueued(Pointer<SdlAudioStream> stream) → int audio
Get the number of bytes currently queued.
sdlGetCurrentAudioDriver() → String? audio
Get the name of the current audio driver.
sdlGetNumAudioDrivers() → int audio
Use this function to get the number of built-in audio drivers.
sdlGetSilenceValueForFormat(int format) → int audio
Get the appropriate memset value for silencing an audio format.
sdlIsAudioDevicePhysical(int devid) → bool audio
Determine if an audio device is physical (instead of logical).
sdlIsAudioDevicePlayback(int devid) → bool audio
Determine if an audio device is a playback device (instead of recording).
sdlLoadWav(String? path, Pointer<SdlAudioSpec> spec, Pointer<Pointer<Uint8>> audioBuf, Pointer<Uint32> audioLen) → bool audio
Loads a WAV from a file path.
sdlLoadWavIo(Pointer<SdlIoStream> src, bool closeio, Pointer<SdlAudioSpec> spec, Pointer<Pointer<Uint8>> audioBuf, Pointer<Uint32> audioLen) → bool audio
Load the audio data of a WAVE file into memory.
sdlLockAudioStream(Pointer<SdlAudioStream> stream) → bool audio
Lock an audio stream for serialized access.
sdlMixAudio(Pointer<Uint8> dst, Pointer<Uint8> src, int format, int len, double volume) → bool audio
Mix audio data in a specified format.
sdlOpenAudioDevice(int devid, Pointer<SdlAudioSpec> spec) → int audio
Open a specific audio device.
sdlOpenAudioDeviceStream(int devid, Pointer<SdlAudioSpec> spec, Pointer<NativeFunction<SdlAudioStreamCallback>> callback, Pointer<NativeType> userdata) → Pointer<SdlAudioStream> audio
Convenience function for straightforward audio init for the common case.
sdlPauseAudioDevice(int devid) → bool audio
Use this function to pause audio playback on a specified device.
sdlPauseAudioStreamDevice(Pointer<SdlAudioStream> stream) → bool audio
Use this function to pause audio playback on the audio device associated with an audio stream.
sdlPutAudioStreamData(Pointer<SdlAudioStream> stream, Pointer<NativeType> buf, int len) → bool audio
Add data to the stream.
sdlPutAudioStreamDataNoCopy(Pointer<SdlAudioStream> stream, Pointer<NativeType> buf, int len, Pointer<NativeFunction<SdlAudioStreamDataCompleteCallback>> callback, Pointer<NativeType> userdata) → bool audio
Add external data to an audio stream without copying it.
sdlPutAudioStreamPlanarData(Pointer<SdlAudioStream> stream, Pointer<Pointer<NativeType>> channelBuffers, int numChannels, int numSamples) → bool audio
Add data to the stream with each channel in a separate array.
sdlResumeAudioDevice(int devid) → bool audio
Use this function to unpause audio playback on a specified device.
sdlResumeAudioStreamDevice(Pointer<SdlAudioStream> stream) → bool audio
Use this function to unpause audio playback on the audio device associated with an audio stream.
sdlSetAudioDeviceGain(int devid, double gain) → bool audio
Change the gain of an audio device.
sdlSetAudioPostmixCallback(int devid, Pointer<NativeFunction<SdlAudioPostmixCallback>> callback, Pointer<NativeType> userdata) → bool audio
Set a callback that fires when data is about to be fed to an audio device.
sdlSetAudioStreamFormat(Pointer<SdlAudioStream> stream, Pointer<SdlAudioSpec> srcSpec, Pointer<SdlAudioSpec> dstSpec) → bool audio
Change the input and output formats of an audio stream.
sdlSetAudioStreamFrequencyRatio(Pointer<SdlAudioStream> stream, double ratio) → bool audio
Change the frequency ratio of an audio stream.
sdlSetAudioStreamGain(Pointer<SdlAudioStream> stream, double gain) → bool audio
Change the gain of an audio stream.
sdlSetAudioStreamGetCallback(Pointer<SdlAudioStream> stream, Pointer<NativeFunction<SdlAudioStreamCallback>> callback, Pointer<NativeType> userdata) → bool audio
Set a callback that runs when data is requested from an audio stream.
sdlSetAudioStreamInputChannelMap(Pointer<SdlAudioStream> stream, Pointer<Int32> chmap, int count) → bool audio
Set the current input channel map of an audio stream.
sdlSetAudioStreamOutputChannelMap(Pointer<SdlAudioStream> stream, Pointer<Int32> chmap, int count) → bool audio
Set the current output channel map of an audio stream.
sdlSetAudioStreamPutCallback(Pointer<SdlAudioStream> stream, Pointer<NativeFunction<SdlAudioStreamCallback>> callback, Pointer<NativeType> userdata) → bool audio
Set a callback that runs when data is added to an audio stream.
sdlUnbindAudioStream(Pointer<SdlAudioStream> stream) → void audio
Unbind a single audio stream from its audio device.
sdlUnbindAudioStreams(Pointer<Pointer<SdlAudioStream>> streams, int numStreams) → void audio
Unbind a list of audio streams from their audio devices.
sdlUnlockAudioStream(Pointer<SdlAudioStream> stream) → bool audio
Unlock an audio stream for serialized access.