Home   Class/Enum List   File List   Compound Members   C interface  

Files | Classes | Typedefs | Enumerations | Enumerator | Functions

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


file  rtaudio_c.h


struct  rtaudio_device_info_t
struct  rtaudio_stream_parameters_t
struct  rtaudio_stream_options_t


typedef unsigned long rtaudio_format_t
 RtAudio data format type. More...
typedef unsigned int rtaudio_stream_flags_t
 RtAudio stream option flags. More...
typedef unsigned int rtaudio_stream_status_t
 RtAudio stream status (over- or underflow) flags. More...
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. More...
typedef void(* rtaudio_error_cb_t )(rtaudio_error_t err, const char *msg)
 RtAudio error callback function prototype. More...


enum  rtaudio_error_t {
 Error codes for RtAudio. More...
enum  rtaudio_api_t {
 Audio API specifier. See RtAudio::Api. More...


RTAUDIOAPI const char * rtaudio_version (void)
 Determine the current RtAudio version. See RtAudio::getVersion().
RTAUDIOAPI unsigned int rtaudio_get_num_compiled_apis (void)
RTAUDIOAPI const rtaudio_api_trtaudio_compiled_api (void)
RTAUDIOAPI const char * rtaudio_api_name (rtaudio_api_t api)
RTAUDIOAPI const char * rtaudio_api_display_name (rtaudio_api_t api)
RTAUDIOAPI rtaudio_api_t rtaudio_compiled_api_by_name (const char *name)
RTAUDIOAPI rtaudio_t rtaudio_create (rtaudio_api_t api)
 Create an instance of struct rtaudio.
RTAUDIOAPI void rtaudio_destroy (rtaudio_t audio)
 Free an instance of struct rtaudio.
RTAUDIOAPI rtaudio_api_t rtaudio_current_api (rtaudio_t audio)
RTAUDIOAPI int rtaudio_device_count (rtaudio_t audio)
RTAUDIOAPI rtaudio_device_info_t rtaudio_get_device_info (rtaudio_t audio, int i)
RTAUDIOAPI unsigned int rtaudio_get_default_output_device (rtaudio_t audio)
RTAUDIOAPI unsigned int rtaudio_get_default_input_device (rtaudio_t audio)
RTAUDIOAPI int rtaudio_open_stream (rtaudio_t audio, rtaudio_stream_parameters_t *output_params, rtaudio_stream_parameters_t *input_params, rtaudio_format_t format, unsigned int sample_rate, unsigned int *buffer_frames, rtaudio_cb_t cb, void *userdata, rtaudio_stream_options_t *options, rtaudio_error_cb_t errcb)
RTAUDIOAPI void rtaudio_close_stream (rtaudio_t audio)
 Closes a stream and frees any associated stream memory. See RtAudio::closeStream().
RTAUDIOAPI int rtaudio_start_stream (rtaudio_t audio)
 Starts a stream. See RtAudio::startStream().
RTAUDIOAPI int rtaudio_stop_stream (rtaudio_t audio)
RTAUDIOAPI int rtaudio_abort_stream (rtaudio_t audio)
RTAUDIOAPI int rtaudio_is_stream_open (rtaudio_t audio)
 Returns 1 if a stream is open and false if not. See RtAudio::isStreamOpen().
RTAUDIOAPI int rtaudio_is_stream_running (rtaudio_t audio)
RTAUDIOAPI double rtaudio_get_stream_time (rtaudio_t audio)
RTAUDIOAPI void rtaudio_set_stream_time (rtaudio_t audio, double time)
RTAUDIOAPI int rtaudio_get_stream_latency (rtaudio_t audio)
RTAUDIOAPI unsigned int rtaudio_get_stream_sample_rate (rtaudio_t audio)
RTAUDIOAPI void rtaudio_show_warnings (rtaudio_t audio, int show)

Detailed Description

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

Class Documentation

struct rtaudio_device_info_t

The public device information structure for returning queried values. See RtAudio::DeviceInfo.

struct rtaudio_stream_parameters_t

The structure for specifying input or ouput stream parameters. See RtAudio::StreamParameters.

struct rtaudio_stream_options_t

The structure for specifying stream options. See RtAudio::StreamOptions.

Typedef Documentation

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 long 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 long 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.

errType of error.
msgError description.

See RtAudioErrorCallback.

Enumeration Type Documentation

Error codes for RtAudio.

See RtAudioError.


A non-critical error.


A non-critical error which might be useful for debugging.


The default, unspecified error type.


No devices found on system.


An invalid device ID was specified.


An error occured during memory allocation.


An invalid parameter was specified to a function.


The function was called incorrectly.


A system driver error occured.


A system error occured.


A thread error occured.

Audio API specifier. See RtAudio::Api.


Search for a working compiled API.


The Advanced Linux Sound Architecture API.


The Linux PulseAudio API.


The Linux Open Sound System API.


The Jack Low-Latency Audio Server API.


Macintosh OS-X Core Audio API.


The Microsoft WASAPI API.


The Steinberg Audio Stream I/O API.


The Microsoft DirectSound API.


A compilable but non-functional API.


Number of values in this enum.

Function Documentation

RTAUDIOAPI unsigned int rtaudio_get_num_compiled_apis ( void  )

Determine the number of available compiled audio APIs, the length of the array returned by rtaudio_compiled_api(). See RtAudio::getCompiledApi().

RTAUDIOAPI const rtaudio_api_t* rtaudio_compiled_api ( void  )

Return an array of rtaudio_api_t compiled into this instance of RtAudio. This array is static (do not free it) and has the length returned by rtaudio_get_num_compiled_apis(). See RtAudio::getCompiledApi().

RTAUDIOAPI const char* rtaudio_api_name ( rtaudio_api_t  api)

Return the name of a specified rtaudio_api_t. This string can be used to look up an API by rtaudio_compiled_api_by_name(). See RtAudio::getApiName().

RTAUDIOAPI const char* rtaudio_api_display_name ( rtaudio_api_t  api)

Return the display name of a specified rtaudio_api_t. See RtAudio::getApiDisplayName().

RTAUDIOAPI rtaudio_api_t rtaudio_compiled_api_by_name ( const char *  name)

Return the rtaudio_api_t having the given name. See RtAudio::getCompiledApiByName().

RTAUDIOAPI rtaudio_api_t rtaudio_current_api ( rtaudio_t  audio)

Returns the audio API specifier for the current instance of RtAudio. See RtAudio::getCurrentApi().

RTAUDIOAPI int rtaudio_device_count ( rtaudio_t  audio)

Queries for the number of audio devices available. See RtAudio::getDeviceCount().

RTAUDIOAPI rtaudio_device_info_t rtaudio_get_device_info ( rtaudio_t  audio,
int  i 

Return a struct rtaudio_device_info for a specified device number. See RtAudio::getDeviceInfo().

RTAUDIOAPI unsigned int rtaudio_get_default_output_device ( rtaudio_t  audio)

Returns the index of the default output device. See RtAudio::getDefaultOutputDevice().

RTAUDIOAPI unsigned int rtaudio_get_default_input_device ( rtaudio_t  audio)

Returns the index of the default input device. See RtAudio::getDefaultInputDevice().

RTAUDIOAPI int rtaudio_open_stream ( rtaudio_t  audio,
rtaudio_stream_parameters_t output_params,
rtaudio_stream_parameters_t input_params,
rtaudio_format_t  format,
unsigned int  sample_rate,
unsigned int *  buffer_frames,
rtaudio_cb_t  cb,
void *  userdata,
rtaudio_stream_options_t options,
rtaudio_error_cb_t  errcb 

Opens a stream with the specified parameters. See RtAudio::openStream().

an rtaudio_error.
RTAUDIOAPI int rtaudio_stop_stream ( rtaudio_t  audio)

Stop a stream, allowing any samples remaining in the output queue to be played. See RtAudio::stopStream().

RTAUDIOAPI int rtaudio_abort_stream ( rtaudio_t  audio)

Stop a stream, discarding any samples remaining in the input/output queue. See RtAudio::abortStream().

RTAUDIOAPI int rtaudio_is_stream_running ( rtaudio_t  audio)

Returns 1 if a stream is running and false if it is stopped or not open. See RtAudio::isStreamRunning().

RTAUDIOAPI double rtaudio_get_stream_time ( rtaudio_t  audio)

Returns the number of elapsed seconds since the stream was started. See RtAudio::getStreamTime().

RTAUDIOAPI void rtaudio_set_stream_time ( rtaudio_t  audio,
double  time 

Set the stream time to a time in seconds greater than or equal to 0.0. See RtAudio::setStreamTime().

RTAUDIOAPI int rtaudio_get_stream_latency ( rtaudio_t  audio)

Returns the internal stream latency in sample frames. See RtAudio::getStreamLatency().

RTAUDIOAPI unsigned int rtaudio_get_stream_sample_rate ( rtaudio_t  audio)

Returns actual sample rate in use by the stream. See RtAudio::getStreamSampleRate().

RTAUDIOAPI void rtaudio_show_warnings ( rtaudio_t  audio,
int  show 

Specify whether warning messages should be printed to stderr. See RtAudio::showWarnings().

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