specified during stream creation, RtAudio first attempts to open the default audio device(s) with the
given parameters. If that fails, an attempt is made
to find a device or set of devices which will meet the
given parameters. If all attempts are unsuccessful,
an RtError is thrown. When a positive, non-zero
device value is specified, no additional devices are
probed. Example program code is provided in the
appendix of this paper.
Because RtAudio can be used to simultaneously
control more than a single stream, it is necessary
that the returned stream identifier be provided to
nearly all public methods.
The bufferSize parameter specifies the desired
number of sample frames which will be written to
and/or read from a device per write/read operation. Both the bufferSize and numberOfBuffers
parameters can be used to control stream latency,
though there is no guarantee that the passed values
will be accepted by a device. In general, lower values for both parameters will produce less latency
but perhaps less robust performance. Both parameters can be specified with values of zero, in which
case the smallest allowable values will be used. The
bufferSize parameter is passed as a pointer and the
actual value used by the stream is set during the
device setup procedure.
3.3 Stream Control
An opened stream will not begin to input/output data until it is "started" using the
startStream() function. Several other useful
functions are listed below as well. A stream can be
stopped and "restarted" as many times as necessary. Once the stream is closed, however, it ceases
to exist. The abortStream() function stops a
stream immediately, dropping any remaining audio
samples in its queue. The stopStream() function
plays out any remaining data in its queue before
stopping.
void startStream (int streamId);
void stopStream (int streamId);
void abortStream (int streamId);
void closeStream (int streamId);
In general, the stopStream() and
closeStream() methods should be called after finishing with a stream. However, both
methods will implicitly be called during object
destruction if necessary.
The remaining steps involved in audio playback
or recording vary depending on whether blocking
or callback functionality is used.
3.4 Blocking Input/Output
Blocking read/write functionality provides synchronous control of audio processing. In this mode,
the user must first get a pointer to the stream
buffer, provided by RtAudio, for use in feeding data
to/from the opened stream. Memory management
for the stream buffer is automatically controlled
by RtAudio. The bufferSize value returned during stream creation defines the length, in sample
frames, of the stream buffer. Multichannel data in
the stream buffer must be in interleaved order.
char *const getStreamBuffer (int streamId);
void tickStream (int streamId);
int streamWillBlock (int streamId);
After starting the stream, the sequence of
events then consists of filling or reading from
the stream buffer between calls to tickStream().
The tickStream() function blocks until the
data within the stream buffer can be completely processed by the audio device. The
streamWillBlock() function is provided as a
means for determining, a priori, whether the
tickStream() function will block, returning the
number of sample frames that cannot be processed
without blocking.
3.5 Callback Functionality
Callback functionality provides non-blocking,
asynchronous control of audio processing. In this
mode, the user defines a global C function which is
periodically called when the audio device is ready
to receive/send a new buffer of audio data. The
callback function fills or reads interleaved data
from the stream buffer, interfacing with the user
program in an application-dependent manner. Internally, callback functionality involves the creation of a separate process or thread which provides non-blocking access to an audio device.
void setStreamCallback (int streamId,
RTAUDIO_CALLBACK callback,
void *userData);
void cancelStreamCallback (int streamId);
The cancelStreamCallback() function disassociates a callback function from an open stream.
The user can subsequently set a new callback function for the stream or even use blocking functions.
It should be noted that it is not possible to explicitly synchronize multiple simultaneous callback
streams. When synchronous control is required in
a non-blocking scheme, users should create their
own thread in which they embed RtAudio blocking functions.
4 Summary
RtAudio provides a flexible and easy to
use cross-platform API for realtime audio in
198
