omni::audio::experimental::CaptureDeviceDesc

Defined in omni/audio/experimental/IAudioCapture.h

struct CaptureDeviceDesc

The parameters to use when opening a capture device.

Public Members

CaptureDeviceFlags flags = 0

Flags to indicate some additional behaviour of the device.

No flags are currently defined. This should be set to 0.

size_t index = 0

The index of the device to be opened.

Index 0 will always be the system’s default capture device. These indices are the same as the ones used in carb::audio::IAudioDevice, so that interface should be used to enumerate the system’s audio devices.

This must be less than the return value of the most recent call to carb::audio::IAudioDevice::getDeviceCount() for capture devices. 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.

Additionally, there is always a possibility that a device will fail to open or the system has no audio capture devices, so code must be able to handle that possibility. In particular, it is common to run into misconfigured devices under ALSA; some distributions automatically configure devices that will not open.

Format format = {}

The format to use for the capture stream.

Leaving this struct at its default values will cause the audio device’s default format to be used (This can be queried later with ICaptureStream_abi::getSoundFormat_abi()). The audio stream will accept any valid PCM format, even if the underlying device does not support that format.

size_t bufferLength = 0

The length of the ring buffer to capture data into, in frames.

The buffer length in combination with bufferFragments determines the minimum possible latency of the audio stream, which the time to record one fragment of audio. The buffer length will be automatically adjusted to ensure that its size is divisible by the fragment count.

This will not determine the buffer size of the underlying audio device, but if it is possible, the underlying audio device will be adjusted to best match this buffer length and fragment combination.

Setting this to 0 will choose the underlying device’s buffer length or a default value if the underlying device has no buffer.

size_t bufferFragments = 0

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

When using callback based recording, one fragment of audio will be sent to each callback. When using polling based recording, data will become available in one fragment increments. One fragment of audio becomes the minimum latency for the audio stream. Setting an excessive number of fragments will reduce the efficiency of the audio stream.

Setting this to 0 will choose the underlying device’s fragment count or a default value if the underlying device doesn’t use a ring buffer system.