rtaudio_c.h

   1 /************************************************************************/
   2 /*! \defgroup C-interface
   3     @{
   4
   5     \brief C interface to realtime audio i/o C++ classes.
   6
   7     RtAudio offers a C-style interface, principally for use in binding
   8     RtAudio to other programming languages.  All structs, enums, and
   9     functions listed here have direct analogs (and simply call to)
  10     items in the C++ RtAudio class and its supporting classes and
  11     types
  12 */
  13 /************************************************************************/
  14
  15 /*!
  16   \file rtaudio_c.h
  17  */
  18
  19 #ifndef RTAUDIO_C_H
  20 #define RTAUDIO_C_H
  21
  22 #if defined(RTAUDIO_EXPORT)
  23 #if defined _WIN32 || defined __CYGWIN__
  24 #define RTAUDIOAPI __declspec(dllexport)
  25 #else
  26 #define RTAUDIOAPI __attribute__((visibility("default")))
  27 #endif
  28 #else
  29 #define RTAUDIOAPI //__declspec(dllimport)
  30 #endif
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 /*! \typedef typedef unsigned long rtaudio_format_t;
  37     \brief RtAudio data format type.
  38
  39     - \e RTAUDIO_FORMAT_SINT8:   8-bit signed integer.
  40     - \e RTAUDIO_FORMAT_SINT16:  16-bit signed integer.
  41     - \e RTAUDIO_FORMAT_SINT24:  24-bit signed integer.
  42     - \e RTAUDIO_FORMAT_SINT32:  32-bit signed integer.
  43     - \e RTAUDIO_FORMAT_FLOAT32: Normalized between plus/minus 1.0.
  44     - \e RTAUDIO_FORMAT_FLOAT64: Normalized between plus/minus 1.0.
  45
  46     See \ref RtAudioFormat.
  47 */
  48 typedef unsigned long rtaudio_format_t;
  49
  50 #define RTAUDIO_FORMAT_SINT8 0x01
  51 #define RTAUDIO_FORMAT_SINT16 0x02
  52 #define RTAUDIO_FORMAT_SINT24 0x04
  53 #define RTAUDIO_FORMAT_SINT32 0x08
  54 #define RTAUDIO_FORMAT_FLOAT32 0x10
  55 #define RTAUDIO_FORMAT_FLOAT64 0x20
  56
  57 /*! \typedef typedef unsigned long rtaudio_stream_flags_t;
  58     \brief RtAudio stream option flags.
  59
  60     The following flags can be OR'ed together to allow a client to
  61     make changes to the default stream behavior:
  62
  63     - \e RTAUDIO_FLAGS_NONINTERLEAVED:   Use non-interleaved buffers (default = interleaved).
  64     - \e RTAUDIO_FLAGS_MINIMIZE_LATENCY: Attempt to set stream parameters for lowest possible latency.
  65     - \e RTAUDIO_FLAGS_HOG_DEVICE:       Attempt grab device for exclusive use.
  66     - \e RTAUDIO_FLAGS_ALSA_USE_DEFAULT: Use the "default" PCM device (ALSA only).
  67     - \e RTAUDIO_FLAGS_JACK_DONT_CONNECT: Do not automatically connect ports (JACK only).
  68
  69     See \ref RtAudioStreamFlags.
  70 */
  71 typedef unsigned int rtaudio_stream_flags_t;
  72
  73 #define RTAUDIO_FLAGS_NONINTERLEAVED 0x1
  74 #define RTAUDIO_FLAGS_MINIMIZE_LATENCY 0x2
  75 #define RTAUDIO_FLAGS_HOG_DEVICE 0x4
  76 #define RTAUDIO_FLAGS_SCHEDULE_REALTIME 0x8
  77 #define RTAUDIO_FLAGS_ALSA_USE_DEFAULT 0x10
  78 #define RTAUDIO_FLAGS_JACK_DONT_CONNECT = 0x20
  79
  80 /*! \typedef typedef unsigned long rtaudio_stream_status_t;
  81     \brief RtAudio stream status (over- or underflow) flags.
  82
  83     Notification of a stream over- or underflow is indicated by a
  84     non-zero stream \c status argument in the RtAudioCallback function.
  85     The stream status can be one of the following two options,
  86     depending on whether the stream is open for output and/or input:
  87
  88     - \e RTAUDIO_STATUS_INPUT_OVERFLOW:   Input data was discarded because of an overflow condition at the driver.
  89     - \e RTAUDIO_STATUS_OUTPUT_UNDERFLOW: The output buffer ran low, likely producing a break in the output sound.
  90
  91     See \ref RtAudioStreamStatus.
  92 */
  93 typedef unsigned int rtaudio_stream_status_t;
  94
  95 #define RTAUDIO_STATUS_INPUT_OVERFLOW 0x1
  96 #define RTAUDIO_STATUS_OUTPUT_UNDERFLOW 0x2
  97
  98 //! RtAudio callback function prototype.
  99 /*!
 100    All RtAudio clients must create a function of this type to read
 101    and/or write data from/to the audio stream.  When the underlying
 102    audio system is ready for new input or output data, this function
 103    will be invoked.
 104
 105    See \ref RtAudioCallback.
 106  */
 107 typedef int (*rtaudio_cb_t)(void *out, void *in, unsigned int nFrames,
 108                             double stream_time, rtaudio_stream_status_t status,
 109                             void *userdata);
 110
 111 /*! \brief Error codes for RtAudio.
 112
 113     See \ref RtAudioError.
 114 */
 115 typedef enum rtaudio_error {
 116   RTAUDIO_ERROR_WARNING,           /*!< A non-critical error. */
 117   RTAUDIO_ERROR_DEBUG_WARNING,     /*!< A non-critical error which might be useful for debugging. */
 118   RTAUDIO_ERROR_UNSPECIFIED,       /*!< The default, unspecified error type. */
 119   RTAUDIO_ERROR_NO_DEVICES_FOUND,  /*!< No devices found on system. */
 120   RTAUDIO_ERROR_INVALID_DEVICE,    /*!< An invalid device ID was specified. */
 121   RTAUDIO_ERROR_MEMORY_ERROR,      /*!< An error occured during memory allocation. */
 122   RTAUDIO_ERROR_INVALID_PARAMETER, /*!< An invalid parameter was specified to a function. */
 123   RTAUDIO_ERROR_INVALID_USE,       /*!< The function was called incorrectly. */
 124   RTAUDIO_ERROR_DRIVER_ERROR,      /*!< A system driver error occured. */
 125   RTAUDIO_ERROR_SYSTEM_ERROR,      /*!< A system error occured. */
 126   RTAUDIO_ERROR_THREAD_ERROR,      /*!< A thread error occured. */
 127 } rtaudio_error_t;
 128
 129 //! RtAudio error callback function prototype.
 130 /*!
 131     \param err Type of error.
 132     \param msg Error description.
 133
 134     See \ref RtAudioErrorCallback.
 135  */
 136 typedef void (*rtaudio_error_cb_t)(rtaudio_error_t err, const char *msg);
 137
 138 //! Audio API specifier.  See \ref RtAudio::Api.
 139 typedef enum rtaudio_api {
 140   RTAUDIO_API_UNSPECIFIED,    /*!< Search for a working compiled API. */
 141   RTAUDIO_API_LINUX_ALSA,     /*!< The Advanced Linux Sound Architecture API. */
 142   RTAUDIO_API_LINUX_PULSE,    /*!< The Linux PulseAudio API. */
 143   RTAUDIO_API_LINUX_OSS,      /*!< The Linux Open Sound System API. */
 144   RTAUDIO_API_UNIX_JACK,      /*!< The Jack Low-Latency Audio Server API. */
 145   RTAUDIO_API_MACOSX_CORE,    /*!< Macintosh OS-X Core Audio API. */
 146   RTAUDIO_API_WINDOWS_WASAPI, /*!< The Microsoft WASAPI API. */
 147   RTAUDIO_API_WINDOWS_ASIO,   /*!< The Steinberg Audio Stream I/O API. */
 148   RTAUDIO_API_WINDOWS_DS,     /*!< The Microsoft DirectSound API. */
 149   RTAUDIO_API_DUMMY,          /*!< A compilable but non-functional API. */
 150   RTAUDIO_API_NUM,            /*!< Number of values in this enum. */
 151 } rtaudio_api_t;
 152
 153 #define NUM_SAMPLE_RATES 16
 154 #define MAX_NAME_LENGTH 512
 155
 156 //! The public device information structure for returning queried values.
 157 //! See \ref RtAudio::DeviceInfo.
 158 typedef struct rtaudio_device_info {
 159   int probed;
 160   unsigned int output_channels;
 161   unsigned int input_channels;
 162   unsigned int duplex_channels;
 163
 164   int is_default_output;
 165   int is_default_input;
 166
 167   rtaudio_format_t native_formats;
 168
 169   unsigned int preferred_sample_rate;
 170   int sample_rates[NUM_SAMPLE_RATES];
 171
 172   char name[MAX_NAME_LENGTH];
 173 } rtaudio_device_info_t;
 174
 175 //! The structure for specifying input or ouput stream parameters.
 176 //! See \ref RtAudio::StreamParameters.
 177 typedef struct rtaudio_stream_parameters {
 178   unsigned int device_id;
 179   unsigned int num_channels;
 180   unsigned int first_channel;
 181 } rtaudio_stream_parameters_t;
 182
 183 //! The structure for specifying stream options.
 184 //! See \ref RtAudio::StreamOptions.
 185 typedef struct rtaudio_stream_options {
 186   rtaudio_stream_flags_t flags;
 187   unsigned int num_buffers;
 188   int priority;
 189   char name[MAX_NAME_LENGTH];
 190 } rtaudio_stream_options_t;
 191
 192 typedef struct rtaudio *rtaudio_t;
 193
 194 //! Determine the current RtAudio version.  See \ref RtAudio::getVersion().
 195 RTAUDIOAPI const char *rtaudio_version(void);
 196
 197 //! Determine the number of available compiled audio APIs, the length
 198 //! of the array returned by rtaudio_compiled_api().  See \ref
 199 //! RtAudio::getCompiledApi().
 200 RTAUDIOAPI unsigned int rtaudio_get_num_compiled_apis(void);
 201
 202 //! Return an array of rtaudio_api_t compiled into this instance of
 203 //! RtAudio.  This array is static (do not free it) and has the length
 204 //! returned by rtaudio_get_num_compiled_apis().  See \ref
 205 //! RtAudio::getCompiledApi().
 206 RTAUDIOAPI const rtaudio_api_t *rtaudio_compiled_api(void);
 207
 208 //! Return the name of a specified rtaudio_api_t.  This string can be
 209 //! used to look up an API by rtaudio_compiled_api_by_name().  See
 210 //! \ref RtAudio::getApiName().
 211 RTAUDIOAPI const char *rtaudio_api_name(rtaudio_api_t api);
 212
 213 //! Return the display name of a specified rtaudio_api_t.  See \ref
 214 //! RtAudio::getApiDisplayName().
 215 RTAUDIOAPI const char *rtaudio_api_display_name(rtaudio_api_t api);
 216
 217 //! Return the rtaudio_api_t having the given name.  See \ref
 218 //! RtAudio::getCompiledApiByName().
 219 RTAUDIOAPI rtaudio_api_t rtaudio_compiled_api_by_name(const char *name);
 220
 221 RTAUDIOAPI const char *rtaudio_error(rtaudio_t audio);
 222
 223 //! Create an instance of struct rtaudio.
 224 RTAUDIOAPI rtaudio_t rtaudio_create(rtaudio_api_t api);
 225
 226 //! Free an instance of struct rtaudio.
 227 RTAUDIOAPI void rtaudio_destroy(rtaudio_t audio);
 228
 229 //! Returns the audio API specifier for the current instance of
 230 //! RtAudio.  See RtAudio::getCurrentApi().
 231 RTAUDIOAPI rtaudio_api_t rtaudio_current_api(rtaudio_t audio);
 232
 233 //! Queries for the number of audio devices available.  See \ref
 234 //! RtAudio::getDeviceCount().
 235 RTAUDIOAPI int rtaudio_device_count(rtaudio_t audio);
 236
 237 //! Return a struct rtaudio_device_info for a specified device number.
 238 //! See \ref RtAudio::getDeviceInfo().
 239 RTAUDIOAPI rtaudio_device_info_t rtaudio_get_device_info(rtaudio_t audio,
 240                                                          int i);
 241
 242 //! Returns the index of the default output device.  See \ref
 243 //! RtAudio::getDefaultOutputDevice().
 244 RTAUDIOAPI unsigned int rtaudio_get_default_output_device(rtaudio_t audio);
 245
 246 //! Returns the index of the default input device.  See \ref
 247 //! RtAudio::getDefaultInputDevice().
 248 RTAUDIOAPI unsigned int rtaudio_get_default_input_device(rtaudio_t audio);
 249
 250 //! Opens a stream with the specified parameters.  See \ref RtAudio::openStream().
 251 //! \return an \ref rtaudio_error.
 252 RTAUDIOAPI int
 253 rtaudio_open_stream(rtaudio_t audio, rtaudio_stream_parameters_t *output_params,
 254                     rtaudio_stream_parameters_t *input_params,
 255                     rtaudio_format_t format, unsigned int sample_rate,
 256                     unsigned int *buffer_frames, rtaudio_cb_t cb,
 257                     void *userdata, rtaudio_stream_options_t *options,
 258                     rtaudio_error_cb_t errcb);
 259
 260 //! Closes a stream and frees any associated stream memory.  See \ref RtAudio::closeStream().
 261 RTAUDIOAPI void rtaudio_close_stream(rtaudio_t audio);
 262
 263 //! Starts a stream.  See \ref RtAudio::startStream().
 264 RTAUDIOAPI int rtaudio_start_stream(rtaudio_t audio);
 265
 266 //! Stop a stream, allowing any samples remaining in the output queue
 267 //! to be played.  See \ref RtAudio::stopStream().
 268 RTAUDIOAPI int rtaudio_stop_stream(rtaudio_t audio);
 269
 270 //! Stop a stream, discarding any samples remaining in the
 271 //! input/output queue.  See \ref RtAudio::abortStream().
 272 RTAUDIOAPI int rtaudio_abort_stream(rtaudio_t audio);
 273
 274 //! Returns 1 if a stream is open and false if not.  See \ref RtAudio::isStreamOpen().
 275 RTAUDIOAPI int rtaudio_is_stream_open(rtaudio_t audio);
 276
 277 //! Returns 1 if a stream is running and false if it is stopped or not
 278 //! open.  See \ref RtAudio::isStreamRunning().
 279 RTAUDIOAPI int rtaudio_is_stream_running(rtaudio_t audio);
 280
 281 //! Returns the number of elapsed seconds since the stream was
 282 //! started.  See \ref RtAudio::getStreamTime().
 283 RTAUDIOAPI double rtaudio_get_stream_time(rtaudio_t audio);
 284
 285 //! Set the stream time to a time in seconds greater than or equal to
 286 //! 0.0.  See \ref RtAudio::setStreamTime().
 287 RTAUDIOAPI void rtaudio_set_stream_time(rtaudio_t audio, double time);
 288
 289 //! Returns the internal stream latency in sample frames.  See \ref
 290 //! RtAudio::getStreamLatency().
 291 RTAUDIOAPI int rtaudio_get_stream_latency(rtaudio_t audio);
 292
 293 //! Returns actual sample rate in use by the stream.  See \ref
 294 //! RtAudio::getStreamSampleRate().
 295 RTAUDIOAPI unsigned int rtaudio_get_stream_sample_rate(rtaudio_t audio);
 296
 297 //! Specify whether warning messages should be printed to stderr.  See
 298 //! \ref RtAudio::showWarnings().
 299 RTAUDIOAPI void rtaudio_show_warnings(rtaudio_t audio, int show);
 300
 301 #ifdef __cplusplus
 302 }
 303 #endif
 304 #endif /* RTAUDIO_C_H */
 305
 306 /*! }@ */