Home   Class/Enum List   File List   Compound Members   C interface  

Device Settings

The next step in using RtAudio is to open a stream with particular device and parameter settings.

#include "RtAudio.h"
int main()
{
RtAudio dac;
std::vector<unsigned int> deviceIds = dac.getDeviceIds();
if ( deviceIds.size() < 1 ) exit( 0 ); // no devices available
parameters.deviceId = dac.getDefaultOutputDevice();
parameters.nChannels = 2;
unsigned int sampleRate = 44100;
unsigned int bufferFrames = 256; // 256 sample frames
options.flags = RTAUDIO_NONINTERLEAVED;
if ( dac.openStream( &parameters, NULL, RTAUDIO_FLOAT32, sampleRate,
&bufferFrames, &myCallback, NULL, &options ) ) {
std::cout << '\n' << dac.getErrorText() << '\n' << std::endl;
exit( 0 ); // problem with device settings
}
// Normally, you would go on to start / stop a stream
return 0;
}
Realtime audio i/o C++ classes.
Definition RtAudio.h:268
RtAudioStreamFlags flags
Definition RtAudio.h:369
unsigned int getDefaultOutputDevice(void)
A function that returns the ID of the default output device.
Definition RtAudio.h:915
const std::string getErrorText(void)
Retrieve the error message corresponding to the last error or warning condition.
Definition RtAudio.h:920
unsigned int nChannels
Definition RtAudio.h:305
RtAudioErrorType openStream(RtAudio::StreamParameters *outputParameters, RtAudio::StreamParameters *inputParameters, RtAudioFormat format, unsigned int sampleRate, unsigned int *bufferFrames, RtAudioCallback callback, void *userData=NULL, RtAudio::StreamOptions *options=NULL)
A public function for opening a stream with the specified parameters.
std::vector< unsigned int > getDeviceIds(void)
A public function that returns a vector of audio device IDs.
Definition RtAudio.h:912
unsigned int deviceId
Definition RtAudio.h:304
The structure for specifying stream options.
Definition RtAudio.h:368
The structure for specifying input or output stream parameters.
Definition RtAudio.h:302

The RtAudio::openStream() function attempts to open a stream with a specified set of parameter values. In the above example, we attempt to open a two channel playback stream using the default output device, 32-bit floating point data, a sample rate of 44100 Hz, and a frame rate of 256 sample frames per output buffer. If the user specifies an invalid parameter value (such as an unsupported sample rate or an invalid device ID), a non-zero RtAudioErrorType value of RTAUDIO_INVALID_PARAMETER (or perhaps RTAUDIO_INVALID_USE) is returned. If a system error occurs when attempting to open the stream, an RtAudioErrorType of RTAUDIO_SYSTEM_ERROR is returned. In either case, a descriptive error message can be retrieved using the RtAudio::getErrorText() function.

RtAudio provides four signed integer and two floating point data formats that can be specified using the RtAudioFormat parameter values mentioned earlier. If the opened device does not natively support the given format, RtAudio will automatically perform the necessary data format conversion.

The bufferFrames parameter specifies the desired number of sample frames that will be written to and/or read from a device per write/read operation. This parameter can be used to control stream latency though there is no guarantee that the passed value will be that used by a device. In general, a lower bufferFrames value will produce less latency but perhaps less robust performance. A value of zero can be specified, in which case the smallest allowable value will be used. The bufferFrames parameter is passed as a pointer and the actual value used by the stream is set during the device setup procedure. bufferFrames values should be a power of two. Optimal and allowable buffer values tend to vary between systems and devices. Stream latency can also be controlled via the optional RtAudio::StreamOptions member numberOfBuffers (not used in the example above), though this tends to be more system dependent. In particular, the numberOfBuffers parameter is ignored when using the OS-X Core Audio, Jack, and the Windows ASIO APIs.

As noted earlier, the device capabilities reported by a driver or underlying audio API are not always accurate and/or may be dependent on a combination of device settings (for example, higher sample rates may reduce the maximum number of channels). Because of this, RtAudio does not attempt to query a device's capabilities or use previously reported values when opening a device. Instead, RtAudio simply attempts to set the given parameters on a specified device and then checks whether the setup is successful or not.

The RtAudioCallback() parameter above is a pointer to a user-defined function that will be called whenever the audio system is ready for new output data or has new input data to be read. Further details on the use of a callback function are provided in the next section.

Several stream options are available to fine-tune the behavior of an audio stream. In the example above, we specify that data will be written by the user in a non-interleaved format via the RtAudio::StreamOptions member flags. That is, all bufferFrames of the first channel should be written consecutively, followed by all bufferFrames of the second channel. By default (when no option is specified), RtAudio expects data to be written in an interleaved format.


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