The RtAudio Home Page

Home Class/Enum List File List Compound Members C interface

Probing Device Capabilities

A programmer may wish to query the available audio device capabilities before deciding which to use. The following example outlines how this can be done.

// audioprobe.cpp
#include <iostream>
#include "RtAudio.h"
int main()
{
RtAudio audio;
// Determine the number of devices available
unsigned int devices = audio.getDeviceCount();
// Scan through devices for various capabilities
RtAudio::DeviceInfo info;
for ( unsigned int i=0; i<devices; i++ ) {
info = audio.getDeviceInfo( i );
if ( info.probed == true ) {
// Print, for example, the maximum number of output channels for each device
std::cout << "device = " << i;
std::cout << ": maximum output channels = " << info.outputChannels << "\n";
}
}
return 0;
}
RtAudio.h
RtAudio
Realtime audio i/o C++ classes.
Definition: RtAudio.h:280
RtAudio::getDeviceInfo
RtAudio::DeviceInfo getDeviceInfo(unsigned int device)
Return an RtAudio::DeviceInfo structure for a specified device number.
Definition: RtAudio.h:858
RtAudio::getDeviceCount
unsigned int getDeviceCount(void)
A public function that queries for the number of audio devices available.
Definition: RtAudio.h:857
RtAudio::DeviceInfo::outputChannels
unsigned int outputChannels
Definition: RtAudio.h:302
RtAudio::DeviceInfo::probed
bool probed
Definition: RtAudio.h:300
RtAudio::DeviceInfo
The public device information structure for returning queried values.
Definition: RtAudio.h:299

The RtAudio::DeviceInfo structure is defined in RtAudio.h and provides a variety of information useful in assessing the capabilities of a device:

typedef struct RtAudio::DeviceInfo {
bool probed; // true if the device capabilities were successfully probed.
std::string name; // Character string device identifier.
unsigned int outputChannels; // Maximum output channels supported by device.
unsigned int inputChannels; // Maximum input channels supported by device.
unsigned int duplexChannels; // Maximum simultaneous input/output channels supported by device.
bool isDefaultOutput; // true if this is the default output device.
bool isDefaultInput; // true if this is the default input device.
std::vector<unsigned int> sampleRates; // Supported sample rates.
unsigned int preferredSampleRate; // Preferred sample rate, e.g. for WASAPI the system sample rate.
RtAudioFormat nativeFormats; // Bit mask of supported data formats.
};
RtAudioFormat
unsigned long RtAudioFormat
RtAudio data format type.
Definition: RtAudio.h:86
RtAudio::DeviceInfo::nativeFormats
RtAudioFormat nativeFormats
Definition: RtAudio.h:309
RtAudio::DeviceInfo::name
std::string name
Definition: RtAudio.h:301
RtAudio::DeviceInfo::duplexChannels
unsigned int duplexChannels
Definition: RtAudio.h:304
RtAudio::DeviceInfo::isDefaultOutput
bool isDefaultOutput
Definition: RtAudio.h:305
RtAudio::DeviceInfo::inputChannels
unsigned int inputChannels
Definition: RtAudio.h:303
RtAudio::DeviceInfo::isDefaultInput
bool isDefaultInput
Definition: RtAudio.h:306
RtAudio::DeviceInfo::preferredSampleRate
unsigned int preferredSampleRate
Definition: RtAudio.h:308
RtAudio::DeviceInfo::sampleRates
std::vector< unsigned int > sampleRates
Definition: RtAudio.h:307

The following data formats are defined and fully supported by RtAudio:

typedef unsigned long RtAudioFormat;
static const RtAudioFormat RTAUDIO_SINT8 = 0x1; // 8-bit signed integer.
static const RtAudioFormat RTAUDIO_SINT16 = 0x2; // 16-bit signed integer.
static const RtAudioFormat RTAUDIO_SINT24 = 0x4; // 24-bit signed integer.
static const RtAudioFormat RTAUDIO_SINT32 = 0x8; // 32-bit signed integer.
static const RtAudioFormat RTAUDIO_FLOAT32 = 0x10; // Normalized between plus/minus 1.0.
static const RtAudioFormat RTAUDIO_FLOAT64 = 0x20; // Normalized between plus/minus 1.0.

The `nativeFormats` member of the RtAudio::DeviceInfo structure is a bit mask of the above formats which are natively supported by the device. However, RtAudio will automatically provide format conversion if a particular format is not natively supported. When the `probed` member of the RtAudio::DeviceInfo structure is false, the remaining structure members are undefined and the device is probably unusable.

Some audio devices may require a minimum channel value greater than one. RtAudio will provide automatic channel number compensation when the number of channels set by the user is less than that required by the device. Channel compensation is NOT possible when the number of channels set by the user is greater than that supported by the device.

Note that the device enumeration is system specific and will change if any devices are plugged or unplugged by the user. Thus, the device numbers should be verified immediately before opening a stream. As well, if a user unplugs a device while an open stream is using that device, the resulting stream behaviour will be undefined (a system error will likely be generated).

Also, the capabilities reported by a device driver or underlying audio API are not always accurate and/or may be dependent on a combination of device settings. For this reason, RtAudio does not rely on the queried values when attempting to open a stream.

| ©2001-2021 Gary P. Scavone, McGill University. All Rights Reserved. Maintained by Gary P. Scavone.