embed blocking RtAudio functions within a multithreaded programming structure of their own design.
RtAudio offers uniform support for 8-bit, 16 -bit, 24-bit, and 32-bit signed integer data formats, as well as 32-bit and 64-bit floating point
formats. When an audio device does not natively support a requested user format, RtAudio
provides automatic format conversion. In addition, internal routines will automatically perform
any byte-swapping, channel number compensation, and channel de-interleaving required by the
underlying audio driver or hardware.
On Linux platforms, both native ALSA and
OSS audio APIs are supported. Portability to
other OSS supported systems, such as Solaris and
HP-UX, is untested but most likely easily achieved.
The ALSA driver model was recently incorporated
into the Linux development kernel and will likely
gain wide acceptance in the near future. The
ALSA API provides a more developed level of support for professional quality audio devices than
OSS. On Windows platforms, only the DirectSound API is currently supported. On SGI platforms, the newer "al" API is supported.
The RtAudio API incorporates many of the
concepts developed in the PortAudio project
(Bencina and Burk, 2001). RtAudio distinguishes
itself from PortAudio in its object-oriented, C++
framework, single-file encapsulation, native blocking support, ALSA support, thread-safe routines,
and slightly less ambitious API (which makes
RtAudio less prone to bugs and easier to maintain
and extend).
All source code for RtAudio is made freely
available, allowing full user extensibility and customization. RtAudio is distributed with a tutorial
and complete API documentation in HTML, PDF,
and RTF formats.
3 The RtAudio API
All uses of RtAudio must begin with object instantiation. The default constructor RtAudio()
scans the underlying audio system to verify that
at least one audio input/output device is available.
RtAudio uses C++ exceptions to handle critical
errors, necessitating try/catch blocks around most
member functions as well as constructors. Likewise, all uses of RtAudio must end with class destruction.
RtAudio uses a C++ exception handler called
RtError, which is declared and defined within the
RtAudio class files. An RtError can be caught by
type, providing a means for error correction or at
a minimum, more detailed error reporting. Almost all RtAudio methods can "throw" an RtError, most typically if an invalid stream identifier
is supplied to a method or a driver error occurs.
There are a number of cases within RtAudio where
warning messages may be displayed but an exception is not thrown.
3.1 Device Capabilities
RtAudio provides the following functions for
use in probing the number and capabilities of available audio devices:
int getDeviceCount (void);
void getDeviceInfo (int device,
RTAUDIO DEVICE *info);
The RTAUDIODEVICE structure contains information commonly required in assessing the capabilities of an audio device, including its name,
minimum and maximum number of input, output,
and duplex channels, supported sample rates, and
native data formats.
3.2 Stream Creation & Parameters
In addition to the default constructor, RtAudio
provides an overloaded constructor which allows a
stream to be immediately opened with a given set
of device parameters. Alternately, a stream can be
opened after instantiation in much the same way.
RtAudio (int *streamId,
int outputDevice,
int outputChannels,
int inputDevice,
int inputChannels,
RTAUDIO_FORMAT format,
int sampleRate,
int *bufferSize,
int numberOfBuffers);
int openStream (int outputDevice,
int outputChannels,
int inputDevice,
int inputChannels,
RTAUDIO_FORMAT format,
int sampleRate,
int *bufferSize,
int numberOfBuffers);
A stream is opened with specified output and
input devices, output and input channels, data format, sample rate, and buffer parameters. When
successful, a stream identifier is returned which
must be used for subsequent function calls on the
stream. Audio devices are identified by integer
values of one and higher, as enumerated by the
getDeviceInfo() function. In addition, the sys
tem default input/output devices are identified by
a zero value. When a device identifier of zero is
197
