carb::audio::CaptureDeviceDesc

struct CaptureDeviceDesc

describes the parameters to use when selecting a capture device.

This includes the sound format, buffer length, and device index. This is used when selecting an audio capture device with IAudioCapture::setSource().

Public Members

CaptureDeviceFlags flags = 0

flags to control the behavior of selecting a capture device.

No flags are currently defined. These may be used to control how the values in ext are interpreted.

size_t deviceIndex = 0

the index of the device to be opened.

This must be less than the return value of the most recent call to getDeviceCount(). Note that since the capture device list can change at any time asynchronously due to external user action, setting any particular value here is never guaranteed to be valid. There is always the possibility the user could remove the device after its information is collected but before it is opened. Using this index may either fail to open or open a different device if the system’s set of connected capture devices changes. The only value that guarantees a device will be opened (at least with default settings) is device 0 - the system’s default capture device, as long as at least one is connected.

size_t frameRate = 0

the frame rate to capture audio at.

Note that if this is different from the device’s preferred frame rate (retrieved from a call to getDeviceCaps()), a resampler will have to be added to convert the recorded sound to the requested frame rate. This will incur an extra processing cost. This may be 0 to use the device’s preferred frame rate. The actual frame rate may be retrieved with getSoundFormat().

size_t channels = 0

the number of channels to capture audio into.

This should match the device’s preferred channel count (retrieved from a recent call to getDeviceCaps()). If the channel count is different, the captured audio may not appear in the expected channels of the buffer. For example, if a mono source is used, the captured audio may only be present in the front left channel of the buffer. This may be 0 to use the device’s preferred channel count. The actual channel count may be retrieved with getSoundFormat().

SampleFormat sampleFormat = SampleFormat::eDefault 

the format of each audio sample that is captured.

If this does not match the device’s preferred sample format, a conversion will be performed internally as needed. This will incur an extra processing cost however. This may be SampleFormat::eDefault to indicate that the device’s preferred format should be used instead. In this case, the actual sample format may be retrieved with getSoundFormat(). Only PCM sample formats and SampleFormat::eDefault are allowed.

size_t bufferLength = 0

the requested length of the capture buffer.

The interpretation of this size value depends on the lengthType value. This may be given as a byte count, a frame count, or a time in milliseconds or microseconds. This may be set to 0 to allow a default buffer length to be chosen. If a zero buffer size is used, the buffer’s real size can be discovered later with a call to getBufferSize(). Note that if a buffer size is given in bytes, it may be adjusted slightly to ensure it is frame aligned.

UnitType lengthType = UnitType::eFrames 

describes how the buffer length value should be interpreted.

This value is ignored if bufferLength is 0. Note that the buffer size will always be rounded up to the next frame boundary even if the size is specified in bytes.

size_t bufferFragments = 8

The number of fragments that the recording buffer is divided into.

The buffer is divided into this number of fragments; each fragment must be filled before the data will be returned by IAudioCapture::lock() or IAudioCapture::read(). If all of the fragments are filled during a looping capture, then this is considered an overrun. This is important to configure for low latency capture; dividing the buffer into smaller fragments will reduce additional capture latency. The minimum possible capture latency is decided by the underlying audio device (typically 10-20ms). This will be clamped to the range [2, 64]

void *ext = nullptr

extended information for this object.

This is reserved for future expansion and must be set to nullptr. The values in flags will affect how this is interpreted.