Public API

C-interface

C interface to realtime audio i/o C++ classes.

RtAudio offers a C-style interface, principally for use in binding RtAudio to other programming languages. All structs, enums, and functions listed here have direct analogs (and simply call to) items in the C++ RtAudio class and its supporting classes and types

rtaudio_device_info_tThe public device information structure for returning queried values
rtaudio_stream_options_tThe structure for specifying stream options
rtaudio_stream_parameters_tThe structure for specifying input or ouput stream parameters
rtaudio_abort_streamStop a stream, discarding any samples remaining in the input/output queue
rtaudio_api_display_nameReturn the display name of a specified rtaudio_api_t
rtaudio_api_nameReturn the name of a specified rtaudio_api_t
rtaudio_close_streamCloses a stream and frees any associated stream memory. See RtAudio::closeStream().
rtaudio_compiled_apiReturn an array of rtaudio_api_t compiled into this instance of RtAudio
rtaudio_compiled_api_by_nameReturn the rtaudio_api_t having the given name
rtaudio_createCreate an instance of struct rtaudio.
rtaudio_current_apiReturns the audio API specifier for the current instance of RtAudio
rtaudio_destroyFree an instance of struct rtaudio.
rtaudio_device_countQueries for the number of audio devices available
rtaudio_error
rtaudio_error_type
rtaudio_get_default_input_deviceReturns the index of the default input device
rtaudio_get_default_output_deviceReturns the index of the default output device
rtaudio_get_device_infoReturn a struct rtaudio_device_info for a specified device number
rtaudio_get_num_compiled_apisDetermine the number of available compiled audio APIs, the length of the array returned by rtaudio_compiled_api()
rtaudio_get_stream_latencyReturns the internal stream latency in sample frames
rtaudio_get_stream_sample_rateReturns actual sample rate in use by the stream
rtaudio_get_stream_timeReturns the number of elapsed seconds since the stream was started
rtaudio_is_stream_openReturns 1 if a stream is open and false if not. See RtAudio::isStreamOpen().
rtaudio_is_stream_runningReturns 1 if a stream is running and false if it is stopped or not open
rtaudio_open_streamOpens a stream with the specified parameters
rtaudio_set_stream_timeSet the stream time to a time in seconds greater than or equal to 0.0
rtaudio_show_warningsSpecify whether warning messages should be printed to stderr
rtaudio_start_streamStarts a stream. See RtAudio::startStream().
rtaudio_stop_streamStop a stream, allowing any samples remaining in the output queue to be played
rtaudio_versionDetermine the current RtAudio version. See RtAudio::getVersion().
rtaudio_error_tError codes for RtAudio.
rtaudio_api_tAudio API specifier. See RtAudio::Api.

typedef unsigned long rtaudio_format_t

RtAudio data format type.

  • RTAUDIO_FORMAT_SINT8: 8-bit signed integer.
  • RTAUDIO_FORMAT_SINT16: 16-bit signed integer.
  • RTAUDIO_FORMAT_SINT24: 24-bit signed integer.
  • RTAUDIO_FORMAT_SINT32: 32-bit signed integer.
  • RTAUDIO_FORMAT_FLOAT32: Normalized between plus/minus 1.0.
  • RTAUDIO_FORMAT_FLOAT64: Normalized between plus/minus 1.0.

See RtAudioFormat.

typedef unsigned int rtaudio_stream_flags_t

RtAudio stream option flags.

The following flags can be OR'ed together to allow a client to make changes to the default stream behavior:

  • RTAUDIO_FLAGS_NONINTERLEAVED: Use non-interleaved buffers (default = interleaved).
  • RTAUDIO_FLAGS_MINIMIZE_LATENCY: Attempt to set stream parameters for lowest possible latency.
  • RTAUDIO_FLAGS_HOG_DEVICE: Attempt grab device for exclusive use.
  • RTAUDIO_FLAGS_ALSA_USE_DEFAULT: Use the "default" PCM device (ALSA only).
  • RTAUDIO_FLAGS_JACK_DONT_CONNECT: Do not automatically connect ports (JACK only).

See RtAudioStreamFlags.

typedef unsigned int rtaudio_stream_status_t

RtAudio stream status (over- or underflow) flags.

Notification of a stream over- or underflow is indicated by a non-zero stream status argument in the RtAudioCallback function. The stream status can be one of the following two options, depending on whether the stream is open for output and/or input:

  • RTAUDIO_STATUS_INPUT_OVERFLOW: Input data was discarded because of an overflow condition at the driver.
  • RTAUDIO_STATUS_OUTPUT_UNDERFLOW: The output buffer ran low, likely producing a break in the output sound.

See RtAudioStreamStatus.

typedef int(* rtaudio_cb_t)(void *out, void *in, unsigned int nFrames, double stream_time, rtaudio_stream_status_t status, void *userdata)

RtAudio callback function prototype.

All RtAudio clients must create a function of this type to read and/or write data from/to the audio stream. When the underlying audio system is ready for new input or output data, this function will be invoked.

See RtAudioCallback.

typedef void(* rtaudio_error_cb_t)(rtaudio_error_t err, const char *msg)

RtAudio error callback function prototype.

Parameters

err - Type of error.

msg - Error description.

See RtAudioErrorCallback.

typedef struct rtaudio * rtaudio_t

Classes

CallbackInfoThis global structure type is used to pass callback information between the private RtAudio stream structure and global callback handling functions.
RtApi

Mentioned in

  • Advanced Tutorial / Multi
RtApiAlsa
RtApiAsio

Mentioned in

  • Advanced Tutorial / Multi
RtApiCoreRtApi Subclass prototypes.
RtApiDs

Mentioned in

  • Advanced Tutorial / Multi
RtApiDummy
RtApiJack
RtApiOss
RtApiPulse
RtApiWasapi
RtAudioRealtime audio i/o C++ classes.
RtAudioErrorException handling class for RtAudio.
S24**************** //

Typedefs

Typedefs (RtAudio.h)

typedef unsigned long RtAudioFormat

RtAudio data format type.

Support for signed integers and floats. Audio data fed to/from an RtAudio stream is assumed to ALWAYS be in host byte order. The internal routines will automatically take care of any necessary byte-swapping between the host format and the soundcard. Thus, endian-ness is not a concern in the following format definitions.

Mentioned in:

Advanced Tutorial / Probe

Advanced Tutorial / Settings

typedef unsigned int RtAudioStreamFlags

RtAudio stream option flags.

The following flags can be OR'ed together to allow a client to make changes to the default stream behavior:

By default, RtAudio streams pass and receive audio data from the client in an interleaved format. By passing the RTAUDIO_NONINTERLEAVED flag to the openStream() function, audio data will instead be presented in non-interleaved buffers. In this case, each buffer argument in the RtAudioCallback function will point to a single array of data, with nFrames samples for each channel concatenated back-to-back. For example, the first sample of data for the second channel would be located at index nFrames (assuming the buffer pointer was recast to the correct data type for the stream).

Certain audio APIs offer a number of parameters that influence the I/O latency of a stream. By default, RtAudio will attempt to set these parameters internally for robust (glitch-free) performance (though some APIs, like Windows DirectSound, make this difficult). By passing the RTAUDIO_MINIMIZE_LATENCY flag to the openStream() function, internal stream settings will be influenced in an attempt to minimize stream latency, though possibly at the expense of stream performance.

If the RTAUDIO_HOG_DEVICE flag is set, RtAudio will attempt to open the input and/or output stream device(s) for exclusive use. Note that this is not possible with all supported audio APIs.

If the RTAUDIO_SCHEDULE_REALTIME flag is set, RtAudio will attempt to select realtime scheduling (round-robin) for the callback thread.

If the RTAUDIO_ALSA_USE_DEFAULT flag is set, RtAudio will attempt to open the "default" PCM device when using the ALSA API. Note that this will override any specified input or output device id.

If the RTAUDIO_JACK_DONT_CONNECT flag is set, RtAudio will not attempt to automatically connect the ports of the client to the audio device.

typedef unsigned int RtAudioStreamStatus

RtAudio stream status (over- or underflow) flags.

Notification of a stream over- or underflow is indicated by a non-zero stream status argument in the RtAudioCallback function. The stream status can be one of the following two options, depending on whether the stream is open for output and/or input:

Mentioned in:

Advanced Tutorial / Duplex

Advanced Tutorial / Playback

Advanced Tutorial / Recording

typedef int(* RtAudioCallback)(void *outputBuffer, void *inputBuffer, unsigned int nFrames, double streamTime, RtAudioStreamStatus status, void *userData)

RtAudio callback function prototype.

All RtAudio clients must create a function of type RtAudioCallback to read and/or write data from/to the audio stream. When the underlying audio system is ready for new input or output data, this function will be invoked.

Parameters

outputBuffer - For output (or duplex) streams, the client should write nFrames of audio sample frames into this buffer. This argument should be recast to the datatype specified when the stream was opened. For input-only streams, this argument will be NULL.

inputBuffer - For input (or duplex) streams, this buffer will hold nFrames of input audio sample frames. This argument should be recast to the datatype specified when the stream was opened. For output-only streams, this argument will be NULL.

nFrames - The number of sample frames of input or output data in the buffers. The actual buffer size in bytes is dependent on the data type and number of channels in use.

streamTime - The number of seconds that have elapsed since the stream was started.

status - If non-zero, this argument indicates a data overflow or underflow condition for the stream. The particular condition can be determined by comparison with the RtAudioStreamStatus flags.

userData - A pointer to optional data provided by the client when opening the stream (default = NULL).

Returns
To continue normal stream operation, the RtAudioCallback function should return a value of zero. To stop the stream and drain the output buffer, the function should return a value of one. To abort the stream immediately, the client should return a value of two.
Mentioned in:

Advanced Tutorial / Settings

typedef void(* RtAudioErrorCallback)(RtAudioError::Type type, const std::string &errorText)

RtAudio error callback function prototype.

Parameters

type - Type of error.

errorText - Error description.

typedef uintptr_t ThreadHandle

Using pthread library for various flavors of unix.

typedef CRITICAL_SECTION StreamMutex

Variables

Variables (RtAudio.h)

const RtAudioFormat RTAUDIO_SINT8 = 0x1

Mentioned in:

  • Advanced Tutorial / Probe

const RtAudioFormat RTAUDIO_SINT16 = 0x2

Mentioned in:

const RtAudioFormat RTAUDIO_SINT24 = 0x4

Mentioned in:

  • Advanced Tutorial / Probe

const RtAudioFormat RTAUDIO_SINT32 = 0x8

Mentioned in:

const RtAudioFormat RTAUDIO_FLOAT32 = 0x10

Mentioned in:

const RtAudioFormat RTAUDIO_FLOAT64 = 0x20

Mentioned in:

const RtAudioStreamFlags RTAUDIO_NONINTERLEAVED = 0x1

Mentioned in:

const RtAudioStreamFlags RTAUDIO_MINIMIZE_LATENCY = 0x2

const RtAudioStreamFlags RTAUDIO_HOG_DEVICE = 0x4

const RtAudioStreamFlags RTAUDIO_SCHEDULE_REALTIME = 0x8

const RtAudioStreamFlags RTAUDIO_ALSA_USE_DEFAULT = 0x10

const RtAudioStreamFlags RTAUDIO_JACK_DONT_CONNECT = 0x20

const RtAudioStreamStatus RTAUDIO_INPUT_OVERFLOW = 0x1

const RtAudioStreamStatus RTAUDIO_OUTPUT_UNDERFLOW = 0x2






Add Discussion as Guest

Log in