Audio Device Management, Playing and Recording

Audio output format

class csdl2.SDL_AudioSpec(freq=0, format=0, channels=0, silence=0, samples=0, size=0, callback=None, userdata=None)

Specifies an audio output format. This is used in functions like SDL_OpenAudioDevice(), SDL_OpenAudio() for specifying the audio callback, desired and obtained audio output, and by functions like SDL_LoadWAV() for returning the audio data format of the wave source data.

freq

Specifies the number of sample frames sent to the audio device per second. Common values are 11025, 22050, 44100 and 48000. Larger values produce cleaner audio, in much the same way that larger resolutions produce cleaner graphics.

format

Specifies the size and type of each sample element. One of the Audio data format values. See Audio data format for more info.

channels

Specifies the number of output channels. Supported values are 1 (mono), 2 (stereo), 4 (quad) and 6 (5.1).

silence

Calculated by SDL_OpenAudioDevice(). The audio device silence value.

samples

The audio buffer size in samples. A sample is a chunk of audio data of the size specified in format multiplied by the number of channels. Must be a power of two.

size

Calculated by SDL_OpenAudioDevice(). The audio buffer size in bytes.

callback

When used with SDL_OpenAudioDevice(), it specifies the callable to call when the audio device needs more data. The callable must have the function signature:

callback(userdata, stream, len) -> None

where stream is a pointer to the audio data buffer which must be filled in by the callback. len is the length of that buffer in bytes.

Stereo samples are stored in a LRLR ordering.

userdata

Object that is passed as the userdata argument to the audio callback.

Audio data format

The audio format is a 16-bit integer, with its bits used as follows:

Bits Value
0-7 Sample bit size
8 Sample is float if set
12 Sample is big-endian if set
15 Sample is signed if set

Unspecified bits are always zero, but may be used in later versions of SDL.

csdl2.SDL_AUDIO_MASK_BITSIZE

Bitmask of the bits storing the sample bit size (bits 0-7).

csdl2.SDL_AUDIO_MASK_DATATYPE

Bitmask of the bit storing the sample data type flag (bit 8).

csdl2.SDL_AUDIO_MASK_ENDIAN

Bitmask of the bit storing the sample endianness flag (bit 12).

csdl2.SDL_AUDIO_MASK_SIGNED

Bitmask of the bit storing the sample sign flag (bit 15).

csdl2.SDL_AUDIO_BITSIZE(x) → int

Query the sample bit size of the audio format.

This is equivalent to the value of:

x & SDL_AUDIO_MASK_BITSIZE
Parameters:x (int) – The audio format integer.
Returns:The sample bit size of the audio format.
csdl2.SDL_AUDIO_ISFLOAT(x) → bool

Query whether the audio format is a floating point format.

This is equivalent to the value of:

bool(x & SDL_AUDIO_MASK_DATATYPE)
Parameters:x (int) – The audio format integer.
Returns:True if the audio format is a floating point format, False otherwise.
csdl2.SDL_AUDIO_ISBIGENDIAN(x) → bool

Query whether the audio format is a big endian format.

This is equivalent to the value of:

bool(x & SDL_AUDIO_MASK_ENDIAN)
Parameters:x (int) – The audio format integer.
Returns:True if the audio format is a big endian format, False otherwise.
csdl2.SDL_AUDIO_ISSIGNED(x) → bool

Query whether the audio format is a signed format.

This is equivalent to the value of:

bool(x & SDL_AUDIO_MASK_SIGNED)
Parameters:x (int) – The audio format integer.
Returns:True if the audio format is a signed format, False otherwise.
csdl2.SDL_AUDIO_ISINT(x) → bool

Query whether the audio format is an integer format.

This is equivalent to the value of:

not SDL_AUDIO_ISFLOAT(x)
Parameters:x (int) – The audio format integer.
Returns:True if the audio format is an integer format, False otherwise.
csdl2.SDL_AUDIO_ISLITTLEENDIAN(x) → bool

Query whether the audio format is a little endian fornmat.

This is equivalent to the value of:

not SDL_AUDIO_ISBIGENDIAN(x)
Parameters:x (int) – The audio format integer.
Returns:True if the audio format is a little endian format, False otherwise.
csdl2.SDL_AUDIO_ISUNSIGNED(x) → bool

Query whether the audio format is an unsigned format.

This is equivalent to the value of:

not SDL_AUDIO_ISSIGNED(x)
Parameters:x (int) – The audio format integer.
Returns:True if the audio format is an unsigned format, False otherwise.

Audio data format values

The following are thus the possible audio data format values:

csdl2.AUDIO_U8

Unsigned 8-bit samples.

csdl2.AUDIO_S8

Signed 8-bit samples.

csdl2.AUDIO_S16LSB

Signed 16-bit samples in little-endian byte order.

csdl2.AUDIO_S16MSB

Signed 16-bit samples in big-endian byte order.

csdl2.AUDIO_S16SYS

Signed 16-bit samples in native byte order.

csdl2.AUDIO_S16

Aliased to AUDIO_S16LSB.

csdl2.AUDIO_U16LSB

Unsigned 16-bit samples in little-endian byte order.

csdl2.AUDIO_U16MSB

Unsigned 16-bit samples in big-endian byte order.

csdl2.AUDIO_U16SYS

Unsigned 16-bit samples in native byte order.

csdl2.AUDIO_U16

Aliased to AUDIO_U16LSB.

csdl2.AUDIO_S32LSB

32-bit integer samples in little-endian byte order.

csdl2.AUDIO_S32MSB

32-bit integer samples in big-endian byte order.

csdl2.AUDIO_S32SYS

32-bit integer samples in native byte order.

csdl2.AUDIO_S32

Aliased to AUDIO_S32LSB.

csdl2.AUDIO_F32LSB

32-bit floating point samples in little-endian byte order.

csdl2.AUDIO_F32MSB

32-bit floating point samples in big-endian byte order.

csdl2.AUDIO_F32SYS

32-bit floating point samples in native byte order.

csdl2.AUDIO_F32

Aliased to AUDIO_F32LSB.

Audio Driver Discovery

csdl2.SDL_GetNumAudioDrivers() → int

Returns the number of audio drivers that SDL supports.

Returns:The number of builtin audio drivers.
Return type:int
csdl2.SDL_GetAudioDriver(index: int) → str

Use this function to get the name of a builtin audio driver. The presence of a driver in this list does not mean that it will function, it just means SDL is capable of interacting with that interface.

Parameters:index (int) – Index of the audio driver. The value ranges from 0 to SDL_GetNumAudioDrivers() - 1.
Returns:The name of the audio driver at the requested index.
Return type:str
csdl2.SDL_GetCurrentAudioDriver()

Returns the name of the current audio driver.

Returns:The name of the current audio driver, or None if no driver has been initialized.
Return type:str or None

Initialization and Cleanup

These functions are used internally, and should not be used unless you have a specific need to specify the audio driver.

csdl2.SDL_AudioInit(driver_name)

Initializes a particular audio driver.

Parameters:driver_name (str or None) – The name of the desired audio driver.
csdl2.SDL_AudioQuit()

Use this function to shut down audio if you initialized it with SDL_AudioInit().

Audio Device Discovery

csdl2.SDL_GetNumAudioDevices(iscapture) → int

Query the number of audio devices.

This function may trigger a complete redetection of available hardware, which is an expensive operation.

Parameters:iscapture (bool) – False to request playback devices, True to request recording devices.
Returns:The number of available devices exposed by the current driver, or -1 if an explicit list of devices can’t be determined.

Note

The iscapture parameter is for future expansion and should always be False for now.

csdl2.SDL_GetAudioDeviceName(index, iscapture) → str

Query the name of an audio device.

Parameters:
  • index (int) – The index of the audio device. The value ranges from 0 to SDL_GetNumAudioDevices() - 1
  • iscapture (bool) – True to specify a device that has recording capability.
Returns:

The name of the audio device at the requested index.

Note

This function is only valid after successfully initializing the audio subsystem. The values returned by this function reflect the latest call to SDL_GetNumAudioDevices(). Re-call that function to re-detect available hardware.

Opening and Closing an Audio Device

SDL provides 2 methods for accessing audio devices. The recommended way is to open the audio device with SDL_OpenAudioDevice() and then control it with SDL_PauseAudioDevice(), SDL_LockAudioDevice() etc. The legacy way is to open the audio device with SDL_OpenAudio(), and then control it with SDL_PauseAudio(), SDL_LockAudio() etc.

Audio data is passed to the audio device through an audio callback, which is specified through the SDL_AudioSpec.callback attribute. Once the audio device has been opened, and the audio device unpaused, SDL will call the audio callback to fill the audio buffer with audio data as needed.

class csdl2.SDL_AudioDevice

An opaque handle returned by SDL_OpenAudioDevice() representing an opened audio device. It’s destructor will call SDL_CloseAudioDevice().

csdl2.SDL_OpenAudioDevice(device, iscapture, desired, obtained, allowed_changes) → SDL_AudioDevice

Opens a specific audio device.

An opened audio device starts out paused, and should be enabled for playing by calling SDL_PauseAudioDevice() when the audio callback function is ready to be called.

The audio callback runs in a separate thread in most cases. You can prevent race conditions between your callback and other threads without fully pausing playback with SDL_LockAudioDevice().

Parameters:
Returns:

An SDL_AudioDevice object representing the opened audio device.
csdl2.SDL_AUDIO_ALLOW_FREQUENCY_CHANGE

Allow the actual audio output frequency to differ from the desired frequency.

csdl2.SDL_AUDIO_ALLOW_FORMAT_CHANGE

Allow the actual audio output format to differ from the desired format.

csdl2.SDL_AUDIO_ALLOW_CHANNELS_CHANGE

Allow the actual number of channels to differ from the desired number of channels.

csdl2.SDL_AUDIO_ALLOW_ANY_CHANGE

Allow all of the above changes.

csdl2.SDL_CloseAudioDevice(dev) → None

Shuts down audio processing and closes the specified device.

There is no need to explictly call this function. SDL_AudioDevice will automatically call this function as part of its destructor.

Parameters:dev (SDL_AudioDevice) – Audio device to close
csdl2.SDL_OpenAudio(desired, obtained)

Opens the audio device with the desired output format.

This function is a legacy means of opening the audio device. Use SDL_OpenAudioDevice() instead.

Parameters:
  • desired (SDL_AudioSpec) – Specifies the desired output format and audio callback
  • obtained (SDL_AudioSpec or None) – A SDL_AudioSpec that will be filled in with the hardware parameters. If None, the the output format of the audio device is guaranteed to match the desired output format. SDL will convert the audio data to the actual hardware audio format if necessary. The desired SDL_AudioSpec will have its fields modified as well.
csdl2.SDL_CloseAudio()

Shuts down audio processing and closes the audio device.

Querying Playback Status

An audio device can be in any one of these 3 states:

csdl2.SDL_AUDIO_STOPPED

Audio device is stopped.

csdl2.SDL_AUDIO_PLAYING

Audio device is playing.

csdl2.SDL_AUDIO_PAUSED

Audio device is paused.

SDL_GetAudioStatus() and SDL_GetAudioDeviceStatus() can be used to query the playback status of an audio device.

csdl2.SDL_GetAudioDeviceStatus(dev) → int

Query the playback status of the specified audio device.

Parameters:dev (SDL_AudioDevice) – Audio device to query.
Returns:The playback status of the specified audio device, which is one of SDL_AUDIO_STOPPED, SDL_AUDIO_PLAYING or SDL_AUDIO_PAUSED.
csdl2.SDL_GetAudioStatus() → int

Query the playback status of the audio device.

This function is a legacy means of querying the audio device. Use SDL_GetAudioDeviceStatus() instead.

Returns:The playback status of the audio device, which is one of SDL_AUDIO_STOPPED, SDL_AUDIO_PLAYING or SDL_AUDIO_PAUSED.

Controlling Playback

csdl2.SDL_PauseAudioDevice(dev, pause_on) → None

Pause or unpause audio playback on the specified device. When the device is paused, silence will be written to the audio device and the audio callback is guaranteed to not be called.

Pausing state does not stack. Even if the device is paused several times, a single unpause will start the device playing again, and vice versa.

If you need to protect a few variables from race conditions with the audio callback, you should not pause the audio device as it will lead to dropouts in audio playback. Instead, use SDL_LockAudioDevice().

Parameters:
  • dev (SDL_AudioDevice) – Audio device to pause or unpause
  • pause_on (bool) – If True, the audio device will be paused, otherwise the audio device will be unpaused.
csdl2.SDL_PauseAudio(pause_on)

Pause or unpause audio playback on the audio device. When the device is paused, silence will be written to the audio device and the audio callback is guaranteed to not be called.

Pausing state does not stack. Even if the device is paused several times, a single unpause will start the device playing again, and vice versa.

If you need to protect a few variables from race conditions with the audio callback, you should not pause the audio device as it will lead to dropouts in audio playback. Instead, use SDL_LockAudio().

This function is a legacy means of pausing the audio device. Use SDL_PauseAudioDevice() instead.

Parameters:pause_on (bool) – If True, the audio device will be paused, otherwise audio device will be unpaused.

WAVE file format support

SDL supports loading a Waveform Audio File Format (WAVE) file from a data stream.

csdl2.SDL_LoadWAV_RW(src: SDL_RWops, freesrc: bool)

Loads a WAVE from the data source.

Parameters:
  • src (SDL_RWops) – Data source for the wave file.
  • freesrc (bool) – If True, the data source will be freed with SDL_RWclose().
Returns:

A 3-tuple (SDL_AudioSpec, buffer, int):

  • A SDL_AudioSpec specifying the audio format of the wave file.
  • A byte buffer containing the audio data.
  • An int specifying the size of the audio data buffer in bytes.
csdl2.SDL_LoadWAV(file: str)

Loads a WAVE from a file.

Parameters:file (str) – Name of the file to load
Returns:A 3-tuple (SDL_AudioSpec, buffer, int):
  • A SDL_AudioSpec specifying the audio format of the wave file.
  • A byte buffer containing the audio data.
  • An int specifying the size of the audio data buffer in bytes.
csdl2.SDL_FreeWAV(audio_buf) → None

Frees the buffer previously allocated with SDL_LoadWAV() or SDL_LoadWAV_RW().

There is no need to explictly call this function. The buffer returned by SDL_LoadWAV() or SDL_LoadWAV_RW() will automatically call this function as part of its destructor.

Parameters:audio_buf (buffer) – Buffer created by SDL_LoadWAV() or SDL_LoadWAV_RW().

Audio Data Conversion

Audio data conversion is done in 3 steps:

  1. An SDL_AudioCVT structure is initialized with SDL_BuildAudioCVT().
  2. The application sets up an appropriately-sized buffer containing the source data, assigning it to SDL_AudioCVT.buf. The application must also set SDL_AudioCVT.len to the source data size in bytes. The actual size of the buffer must be at least len * len_mult bytes large, as the conversion will be done using this buffer.
  3. The actual audio data conversion is done by calling SDL_ConvertAudio() with the SDL_AudioCVT struct. The converted audio data will be written to the provided audio buffer.
class csdl2.SDL_AudioCVT

A structure that contains audio data conversion information.

It is initialized with SDL_BuildAudioCVT(), and passed to SDL_ConvertAudio() to do the actual conversion once the application has set up appropriately-sized buffers between these two function calls.

conversion is done by SDL_ConvertAudio()

needed

(readonly) True if conversion is needed.

src_format

(readonly) Source audio format.

dst_format

(readonly) Target audio format

rate_incr

(readonly) Rate conversion increment.

buf

This attribute should point to the audio data that will be used in the conversion.

The buffer is both the source and the destination, which means the converted audio data overwrites the original data. It also means that converted data may be larger than the original data (if you were converting from 8-bit to 16-bit, for instance), so you must ensure SDL_AudioCVT.buf is larger enough for any stage of the conversion, regardless of the final converted data’s size.

The buffer must have a size of at least len * len_mult.

len

Length of original audio buffer in bytes.

len_cvt

(readonly) Length of converted audio buffer.

len_mult

(readonly) The length multiplier for determining the size of the converted data.

The audio buffer may need to be larger than either the original data or the converted data. The allocated size of SDL_AudioCVT.buf must have a size of at least len * len_mult bytes.

len_ratio

(readonly) The length ratio of the converted data to the original data.

When you have finished converting your audio data, you need to know how much of your audio buffer is valid. len * len_ratio is the size of the converted audio data in bytes.

This is similar to SDL_AudioCVT.len_mult. However, when the converted audio data is shorter than the original, SDL_AudioCVT.len_mult will be 1. SDL_AudioCVT.len_ratio on the other hand will be a fractional number between 0 and 1.

csdl2.SDL_BuildAudioCVT(cvt, src_format, src_channels, src_rate, dst_format, dst_channels, dst_rate) → bool

Initialize a SDL_AudioCVT structure for conversion.

Parameters:
  • cvt (SDL_AudioCVT) – An SDL_AudioCVT structure to be filled in with audio conversion information.
  • src_format (int) – The source format of the audio data. One of the Audio data format values.
  • src_channels (int) – The number of channels in the source.
  • src_rate (int) – The frequency (sample-frames-per-second) of the source.
  • dst_format (int) – The destination format of the audio data. One of the Audio data format values.
  • dst_channels (int) – The number of channels in the destination.
  • dst_rate (int) – The frequency (sample-frames-per-second) of the destination.
Returns:

True if conversion is needed, False otherwise.

Note

This function will zero out every field of the SDL_AudioCVT, so it must be called before the application fills in the final buffer information.

csdl2.SDL_ConvertAudio(cvt)

Convert the audio data as specified by the SDL_AudioCVT structure.

Parameters:cvt – An SDL_AudioCVT structure with the information required for audio conversion.

Note

The SDL_AudioCVT structure must first be initialized with SDL_BuildAudioCVT().

The application then needs to set the SDL_AudioCVT structure’s SDL_AudioCVT.buf attribute to the audio buffer containing the source audio data, and SDL_AudioCVT.len attribute to the size, in bytes, of the source data.

This same buffer is used for data conversion, and will contain the converted audio data after calling this function. The converted audio data, or any of the intermediate conversion data, may be larger than the source data, and thus the actual size of the buffer must be at least len * len_mult bytes long.

This function will write the converted audio data to the buffer, and will set SDL_AudioCVT.len_cvt to the size in bytes of the converted audio data.

Audio Mixing

csdl2.SDL_MixAudioFormat(dst, src, len, volume)

Mix audio data in a specified format.

This takes a source audio buffer, and mixes it into the destination audio buffer, performing addition, volume adjustment, and overflow clipping.

This is provided for convenience – you can mix your own audio data.

Parameters:
  • dst (buffer) – The destination for the mixed audio.
  • src (buffer) – The source audio data to be mixed in.
  • format (int) – The audio format. One of the Audio data format values.
  • len (int) – The length of the source and destination buffers in bytes.
  • volume (int) – Ranges from 0 to 128, and should be set to SDL_MIX_MAXVOLUME for full audio volume.

Note

Do not use this function for mixing together more than two streams of sample data. The output from repeated application of this function may be distorted by clipping, because there is no accumulator with greater range than the input. Use mixing functions from SDL_mixer, OpenAL or write your own mixer instead.

csdl2.SDL_MixAudio(dst, src, len, volume)

This function is a legacy means of mixing audio, and is equivalent to calling:

SDL_MixAudioFormat(dst, src, format, len, volume)

where format is the obtained format of the audio device from the legacy SDL_OpenAudio() function.

Parameters:
  • dst (buffer) – The destination buffer for the mixed audio.
  • src (buffer) – The source audio buffer to be mixed in.
  • len (int) – The length of the source and destination buffers in bytes.
  • volume (int) – Ranges from 0 to 128, and should be set to SDL_MIX_MAXVOLUME for full audio volume.

Note

This function requires the audio device to be open with SDL_OpenAudio(), and will silently fail if the audio device is not open.

csdl2.SDL_MIX_MAXVOLUME

The maximum volume for mixing.

Audio Locking

The lock manipulated by these functions protects the callback function. During a SDL_LockAudio()/SDL_UnlockAudio() or SDL_LockAudioDevice()/SDL_UnlockAudioDevice() pair, you can be guaranteed the callback function is not running. Do not call these from the callback function or you will cause deadlock.

It is safe to lock the audio device multiple times, as long as you unlock it an equivalent number of times. The audio callback will not run until the device has been unlocked completely.

csdl2.SDL_LockAudioDevice(dev)

Lock out the audio callback function for a specified audio device.

Parameters:dev (SDL_AudioDevice) – The audio device to be locked.
csdl2.SDL_UnlockAudioDevice(dev)

Unlock the audio callback function for a specified audio device.

Parameters:dev (SDL_AudioDevice) – The audio device to be unlocked.
csdl2.SDL_LockAudio()

This function is a legacy means of locking the audio device. Use SDL_LockAudioDevice() instead.

csdl2.SDL_UnlockAudio()

This function is a legacy means of unlocking the audio device. Use SDL_UnlockAudioDevice() instead.