The RtAudio Home Page

Home Class/Enum List File List Compound Members C interface

Files | Classes | Typedefs | Enumerations | Enumerator | Functions
C-interface

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

## Files
file | rtaudio_c.h

## Classes
struct | rtaudio_device_info_t
struct | rtaudio_stream_parameters_t
struct | rtaudio_stream_options_t

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

## Enumerations
enum | rtaudio_error { RTAUDIO_ERROR_NONE = 0 , RTAUDIO_ERROR_WARNING , RTAUDIO_ERROR_UNKNOWN , RTAUDIO_ERROR_NO_DEVICES_FOUND , RTAUDIO_ERROR_INVALID_DEVICE , RTAUDIO_ERROR_DEVICE_DISCONNECT , RTAUDIO_ERROR_MEMORY_ERROR , RTAUDIO_ERROR_INVALID_PARAMETER , RTAUDIO_ERROR_INVALID_USE , RTAUDIO_ERROR_DRIVER_ERROR , RTAUDIO_ERROR_SYSTEM_ERROR , RTAUDIO_ERROR_THREAD_ERROR }
| Error codes for RtAudio. More...
enum | rtaudio_api { RTAUDIO_API_UNSPECIFIED , RTAUDIO_API_MACOSX_CORE , RTAUDIO_API_LINUX_ALSA , RTAUDIO_API_UNIX_JACK , RTAUDIO_API_LINUX_PULSE , RTAUDIO_API_LINUX_OSS , RTAUDIO_API_WINDOWS_ASIO , RTAUDIO_API_WINDOWS_WASAPI , RTAUDIO_API_WINDOWS_DS , RTAUDIO_API_DUMMY , RTAUDIO_API_NUM }
| Audio API specifier. See RtAudio::Api. More...

## Functions
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_t * | rtaudio_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 unsigned int | rtaudio_get_device_id (rtaudio_t audio, int i)
RTAUDIOAPI rtaudio_device_info_t | rtaudio_get_device_info (rtaudio_t audio, unsigned int id)
RTAUDIOAPI unsigned int | rtaudio_get_default_output_device (rtaudio_t audio)
RTAUDIOAPI unsigned int | rtaudio_get_default_input_device (rtaudio_t audio)
RTAUDIOAPI rtaudio_error_t | 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 rtaudio_error_t | rtaudio_start_stream (rtaudio_t audio)
| Starts a stream. See RtAudio::startStream().
RTAUDIOAPI rtaudio_error_t | rtaudio_stop_stream (rtaudio_t audio)
RTAUDIOAPI rtaudio_error_t | 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 long | 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

## ◆ rtaudio_device_info_t

struct rtaudio_device_info_t

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

## ◆ rtaudio_stream_parameters_t

struct rtaudio_stream_parameters_t

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

## ◆ rtaudio_stream_options_t

struct rtaudio_stream_options_t

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

## Typedef Documentation

## ◆ rtaudio_format_t

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.

## ◆ rtaudio_stream_flags_t

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.

## ◆ rtaudio_stream_status_t

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.

## ◆ rtaudio_cb_t

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.

## ◆ rtaudio_error_cb_t

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.

## Enumeration Type Documentation

## ◆ rtaudio_error

enum rtaudio_error

Error codes for RtAudio.

See RtAudioError.

Enumerator
RTAUDIO_ERROR_NONE | No error.
RTAUDIO_ERROR_WARNING | A non-critical error.
RTAUDIO_ERROR_UNKNOWN | An unspecified error type.
RTAUDIO_ERROR_NO_DEVICES_FOUND | No devices found on system.
RTAUDIO_ERROR_INVALID_DEVICE | An invalid device ID was specified.
RTAUDIO_ERROR_DEVICE_DISCONNECT | A device in use was disconnected.
RTAUDIO_ERROR_MEMORY_ERROR | An error occurred during memory allocation.
RTAUDIO_ERROR_INVALID_PARAMETER | An invalid parameter was specified to a function.
RTAUDIO_ERROR_INVALID_USE | The function was called incorrectly.
RTAUDIO_ERROR_DRIVER_ERROR | A system driver error occurred.
RTAUDIO_ERROR_SYSTEM_ERROR | A system error occurred.
RTAUDIO_ERROR_THREAD_ERROR | A thread error occurred.

## ◆ rtaudio_api

enum rtaudio_api

Audio API specifier. See RtAudio::Api.

Enumerator
RTAUDIO_API_UNSPECIFIED | Search for a working compiled API.
RTAUDIO_API_MACOSX_CORE | Macintosh OS-X Core Audio API.
RTAUDIO_API_LINUX_ALSA | The Advanced Linux Sound Architecture API.
RTAUDIO_API_UNIX_JACK | The Jack Low-Latency Audio Server API.
RTAUDIO_API_LINUX_PULSE | The Linux PulseAudio API.
RTAUDIO_API_LINUX_OSS | The Linux Open Sound System API.
RTAUDIO_API_WINDOWS_ASIO | The Steinberg Audio Stream I/O API.
RTAUDIO_API_WINDOWS_WASAPI | The Microsoft WASAPI API.
RTAUDIO_API_WINDOWS_DS | The Microsoft DirectSound API.
RTAUDIO_API_DUMMY | A compilable but non-functional API.
RTAUDIO_API_NUM | Number of values in this enum.

## Function Documentation

## ◆ rtaudio_get_num_compiled_apis()

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().

## ◆ rtaudio_compiled_api()

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().

## ◆ rtaudio_api_name()

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().

## ◆ rtaudio_api_display_name()

RTAUDIOAPI const char * rtaudio_api_display_name | ( | rtaudio_api_t | api | ) |

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

## ◆ rtaudio_compiled_api_by_name()

RTAUDIOAPI rtaudio_api_t rtaudio_compiled_api_by_name | ( | const char * | name | ) |

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

## ◆ rtaudio_current_api()

RTAUDIOAPI rtaudio_api_t rtaudio_current_api | ( | rtaudio_t | audio | ) |

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

## ◆ rtaudio_device_count()

RTAUDIOAPI int rtaudio_device_count | ( | rtaudio_t | audio | ) |

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

## ◆ rtaudio_get_device_id()

RTAUDIOAPI unsigned int rtaudio_get_device_id | ( | rtaudio_t | audio,
|  | int | i
| ) |  |

Returns the audio device ID corresponding to a given index value (valid index values are between 0 and rtaudio_device_count()-1). Note that a return value of 0 is invalid, which will occur if the index value is out of bounds or no devices are found. See RtAudio::getDeviceIds().

## ◆ rtaudio_get_device_info()

RTAUDIOAPI rtaudio_device_info_t rtaudio_get_device_info | ( | rtaudio_t | audio,
|  | unsigned int | id
| ) |  |

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

## ◆ rtaudio_get_default_output_device()

RTAUDIOAPI unsigned int rtaudio_get_default_output_device | ( | rtaudio_t | audio | ) |

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

## ◆ rtaudio_get_default_input_device()

RTAUDIOAPI unsigned int rtaudio_get_default_input_device | ( | rtaudio_t | audio | ) |

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

## ◆ rtaudio_open_stream()

RTAUDIOAPI rtaudio_error_t 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().

Returns
  an rtaudio_error.

## ◆ rtaudio_stop_stream()

RTAUDIOAPI rtaudio_error_t rtaudio_stop_stream | ( | rtaudio_t | audio | ) |

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

## ◆ rtaudio_abort_stream()

RTAUDIOAPI rtaudio_error_t rtaudio_abort_stream | ( | rtaudio_t | audio | ) |

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

## ◆ rtaudio_is_stream_running()

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().

## ◆ rtaudio_get_stream_time()

RTAUDIOAPI double rtaudio_get_stream_time | ( | rtaudio_t | audio | ) |

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

## ◆ rtaudio_set_stream_time()

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().

## ◆ rtaudio_get_stream_latency()

RTAUDIOAPI long rtaudio_get_stream_latency | ( | rtaudio_t | audio | ) |

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

## ◆ rtaudio_get_stream_sample_rate()

RTAUDIOAPI unsigned int rtaudio_get_stream_sample_rate | ( | rtaudio_t | audio | ) |

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

## ◆ rtaudio_show_warnings()

RTAUDIOAPI void rtaudio_show_warnings | ( | rtaudio_t | audio,
|  | int | show
| ) |  |

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

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