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

## Enumerations
enum | rtaudio_error_t { RTAUDIO_ERROR_WARNING, RTAUDIO_ERROR_DEBUG_WARNING, RTAUDIO_ERROR_UNSPECIFIED, RTAUDIO_ERROR_NO_DEVICES_FOUND, RTAUDIO_ERROR_INVALID_DEVICE, 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_t { RTAUDIO_API_UNSPECIFIED, RTAUDIO_API_LINUX_ALSA, RTAUDIO_API_LINUX_PULSE, RTAUDIO_API_LINUX_OSS, RTAUDIO_API_UNIX_JACK, RTAUDIO_API_MACOSX_CORE, RTAUDIO_API_WINDOWS_WASAPI, RTAUDIO_API_WINDOWS_ASIO, 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 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

## ◆ 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 ouput 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_t

enum rtaudio_error_t

Error codes for RtAudio.

See RtAudioError.

Enumerator
RTAUDIO_ERROR_WARNING | A non-critical error.
RTAUDIO_ERROR_DEBUG_WARNING | A non-critical error which might be useful for debugging.
RTAUDIO_ERROR_UNSPECIFIED | The default, 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_MEMORY_ERROR | An error occured 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 occured.
RTAUDIO_ERROR_SYSTEM_ERROR | A system error occured.
RTAUDIO_ERROR_THREAD_ERROR | A thread error occured.

## ◆ rtaudio_api_t

enum rtaudio_api_t

Audio API specifier. See RtAudio::Api.

Enumerator
RTAUDIO_API_UNSPECIFIED | Search for a working compiled API.
RTAUDIO_API_LINUX_ALSA | The Advanced Linux Sound Architecture API.
RTAUDIO_API_LINUX_PULSE | The Linux PulseAudio API.
RTAUDIO_API_LINUX_OSS | The Linux Open Sound System API.
RTAUDIO_API_UNIX_JACK | The Jack Low-Latency Audio Server API.
RTAUDIO_API_MACOSX_CORE | Macintosh OS-X Core Audio API.
RTAUDIO_API_WINDOWS_WASAPI | The Microsoft WASAPI API.
RTAUDIO_API_WINDOWS_ASIO | The Steinberg Audio Stream I/O 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_info()

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

## ◆ rtaudio_get_default_output_device()

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

Returns the index 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 index of the default input device. See RtAudio::getDefaultInputDevice().

## ◆ rtaudio_open_stream()

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

Returns
  an rtaudio_error.

## ◆ rtaudio_stop_stream()

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

## ◆ rtaudio_abort_stream()

RTAUDIOAPI int 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 int 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-2019 Gary P. Scavone, McGill University. All Rights Reserved. Maintained by Gary P. Scavone.