1 /************************************************************************/
2 /*! \defgroup C-interface
5 \brief C interface to realtime audio i/o C++ classes.
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
13 /************************************************************************/
22 #if defined(RTAUDIO_EXPORT)
23 #if defined _WIN32 || defined __CYGWIN__
24 #define RTAUDIOAPI __declspec(dllexport)
26 #define RTAUDIOAPI __attribute__((visibility("default")))
29 #define RTAUDIOAPI //__declspec(dllimport)
36 /*! \typedef typedef unsigned long rtaudio_format_t;
37 \brief RtAudio data format type.
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.
46 See \ref RtAudioFormat.
48 typedef unsigned long rtaudio_format_t;
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
57 /*! \typedef typedef unsigned long rtaudio_stream_flags_t;
58 \brief RtAudio stream option flags.
60 The following flags can be OR'ed together to allow a client to
61 make changes to the default stream behavior:
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).
69 See \ref RtAudioStreamFlags.
71 typedef unsigned int rtaudio_stream_flags_t;
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
80 /*! \typedef typedef unsigned long rtaudio_stream_status_t;
81 \brief RtAudio stream status (over- or underflow) flags.
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:
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.
91 See \ref RtAudioStreamStatus.
93 typedef unsigned int rtaudio_stream_status_t;
95 #define RTAUDIO_STATUS_INPUT_OVERFLOW 0x1
96 #define RTAUDIO_STATUS_OUTPUT_UNDERFLOW 0x2
98 //! RtAudio callback function prototype.
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
105 See \ref RtAudioCallback.
107 typedef int (*rtaudio_cb_t)(void *out, void *in, unsigned int nFrames,
108 double stream_time, rtaudio_stream_status_t status,
111 /*! \brief Error codes for RtAudio.
113 See \ref RtAudioError.
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. */
129 //! RtAudio error callback function prototype.
131 \param err Type of error.
132 \param msg Error description.
134 See \ref RtAudioErrorCallback.
136 typedef void (*rtaudio_error_cb_t)(rtaudio_error_t err, const char *msg);
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. */
153 #define NUM_SAMPLE_RATES 16
154 #define MAX_NAME_LENGTH 512
156 //! The public device information structure for returning queried values.
157 //! See \ref RtAudio::DeviceInfo.
158 typedef struct rtaudio_device_info {
160 unsigned int output_channels;
161 unsigned int input_channels;
162 unsigned int duplex_channels;
164 int is_default_output;
165 int is_default_input;
167 rtaudio_format_t native_formats;
169 unsigned int preferred_sample_rate;
170 int sample_rates[NUM_SAMPLE_RATES];
172 char name[MAX_NAME_LENGTH];
173 } rtaudio_device_info_t;
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;
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;
189 char name[MAX_NAME_LENGTH];
190 } rtaudio_stream_options_t;
192 typedef struct rtaudio *rtaudio_t;
194 //! Determine the current RtAudio version. See \ref RtAudio::getVersion().
195 RTAUDIOAPI const char *rtaudio_version(void);
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);
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);
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);
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);
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);
221 RTAUDIOAPI const char *rtaudio_error(rtaudio_t audio);
223 //! Create an instance of struct rtaudio.
224 RTAUDIOAPI rtaudio_t rtaudio_create(rtaudio_api_t api);
226 //! Free an instance of struct rtaudio.
227 RTAUDIOAPI void rtaudio_destroy(rtaudio_t audio);
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);
233 //! Queries for the number of audio devices available. See \ref
234 //! RtAudio::getDeviceCount().
235 RTAUDIOAPI int rtaudio_device_count(rtaudio_t audio);
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,
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);
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);
250 //! Opens a stream with the specified parameters. See \ref RtAudio::openStream().
251 //! \return an \ref rtaudio_error.
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);
260 //! Closes a stream and frees any associated stream memory. See \ref RtAudio::closeStream().
261 RTAUDIOAPI void rtaudio_close_stream(rtaudio_t audio);
263 //! Starts a stream. See \ref RtAudio::startStream().
264 RTAUDIOAPI int rtaudio_start_stream(rtaudio_t audio);
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);
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);
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);
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);
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);
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);
289 //! Returns the internal stream latency in sample frames. See \ref
290 //! RtAudio::getStreamLatency().
291 RTAUDIOAPI int rtaudio_get_stream_latency(rtaudio_t audio);
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);
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);
304 #endif /* RTAUDIO_C_H */