cubeb  0.0.0
cubeb.h
Go to the documentation of this file.
1 /*
2  * Copyright © 2011 Mozilla Foundation
3  *
4  * This program is made available under an ISC-style license. See the
5  * accompanying file LICENSE for details.
6  */
7 #if !defined(CUBEB_c2f983e9_c96f_e71c_72c3_bbf62992a382)
8 #define CUBEB_c2f983e9_c96f_e71c_72c3_bbf62992a382
9 
10 #include "cubeb_export.h"
11 #include <stdint.h>
12 #include <stdlib.h>
13 
14 #if defined(__cplusplus)
15 extern "C" {
16 #endif
17 
125 typedef struct cubeb
126  cubeb;
127 typedef struct cubeb_stream
128  cubeb_stream;
131 typedef enum {
140 #if defined(WORDS_BIGENDIAN) || defined(__BIG_ENDIAN__)
144  CUBEB_SAMPLE_FLOAT32NE = CUBEB_SAMPLE_FLOAT32BE
145 #else
149  CUBEB_SAMPLE_FLOAT32NE = CUBEB_SAMPLE_FLOAT32LE
150 #endif
152 
155 typedef void const * cubeb_devid;
156 
158 typedef enum {
159  CUBEB_LOG_DISABLED = 0,
161  1,
162  CUBEB_LOG_VERBOSE = 2,
165 
166 typedef enum {
167  CHANNEL_UNKNOWN = 0,
168  CHANNEL_FRONT_LEFT = 1 << 0,
169  CHANNEL_FRONT_RIGHT = 1 << 1,
170  CHANNEL_FRONT_CENTER = 1 << 2,
171  CHANNEL_LOW_FREQUENCY = 1 << 3,
172  CHANNEL_BACK_LEFT = 1 << 4,
173  CHANNEL_BACK_RIGHT = 1 << 5,
174  CHANNEL_FRONT_LEFT_OF_CENTER = 1 << 6,
175  CHANNEL_FRONT_RIGHT_OF_CENTER = 1 << 7,
176  CHANNEL_BACK_CENTER = 1 << 8,
177  CHANNEL_SIDE_LEFT = 1 << 9,
178  CHANNEL_SIDE_RIGHT = 1 << 10,
179  CHANNEL_TOP_CENTER = 1 << 11,
180  CHANNEL_TOP_FRONT_LEFT = 1 << 12,
181  CHANNEL_TOP_FRONT_CENTER = 1 << 13,
182  CHANNEL_TOP_FRONT_RIGHT = 1 << 14,
183  CHANNEL_TOP_BACK_LEFT = 1 << 15,
184  CHANNEL_TOP_BACK_CENTER = 1 << 16,
185  CHANNEL_TOP_BACK_RIGHT = 1 << 17
186 } cubeb_channel;
187 
188 typedef uint32_t cubeb_channel_layout;
189 // Some common layout definitions.
190 enum {
191  CUBEB_LAYOUT_UNDEFINED = 0, // Indicate the speaker's layout is undefined.
192  CUBEB_LAYOUT_MONO = CHANNEL_FRONT_CENTER,
193  CUBEB_LAYOUT_MONO_LFE = CUBEB_LAYOUT_MONO | CHANNEL_LOW_FREQUENCY,
194  CUBEB_LAYOUT_STEREO = CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT,
195  CUBEB_LAYOUT_STEREO_LFE = CUBEB_LAYOUT_STEREO | CHANNEL_LOW_FREQUENCY,
196  CUBEB_LAYOUT_3F =
197  CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT | CHANNEL_FRONT_CENTER,
198  CUBEB_LAYOUT_3F_LFE = CUBEB_LAYOUT_3F | CHANNEL_LOW_FREQUENCY,
199  CUBEB_LAYOUT_2F1 =
200  CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT | CHANNEL_BACK_CENTER,
201  CUBEB_LAYOUT_2F1_LFE = CUBEB_LAYOUT_2F1 | CHANNEL_LOW_FREQUENCY,
202  CUBEB_LAYOUT_3F1 = CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT |
203  CHANNEL_FRONT_CENTER | CHANNEL_BACK_CENTER,
204  CUBEB_LAYOUT_3F1_LFE = CUBEB_LAYOUT_3F1 | CHANNEL_LOW_FREQUENCY,
205  CUBEB_LAYOUT_2F2 = CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT |
206  CHANNEL_SIDE_LEFT | CHANNEL_SIDE_RIGHT,
207  CUBEB_LAYOUT_2F2_LFE = CUBEB_LAYOUT_2F2 | CHANNEL_LOW_FREQUENCY,
208  CUBEB_LAYOUT_QUAD = CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT |
209  CHANNEL_BACK_LEFT | CHANNEL_BACK_RIGHT,
210  CUBEB_LAYOUT_QUAD_LFE = CUBEB_LAYOUT_QUAD | CHANNEL_LOW_FREQUENCY,
211  CUBEB_LAYOUT_3F2 = CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT |
212  CHANNEL_FRONT_CENTER | CHANNEL_SIDE_LEFT |
213  CHANNEL_SIDE_RIGHT,
214  CUBEB_LAYOUT_3F2_LFE = CUBEB_LAYOUT_3F2 | CHANNEL_LOW_FREQUENCY,
215  CUBEB_LAYOUT_3F2_BACK = CUBEB_LAYOUT_QUAD | CHANNEL_FRONT_CENTER,
216  CUBEB_LAYOUT_3F2_LFE_BACK = CUBEB_LAYOUT_3F2_BACK | CHANNEL_LOW_FREQUENCY,
217  CUBEB_LAYOUT_3F3R_LFE = CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT |
218  CHANNEL_FRONT_CENTER | CHANNEL_LOW_FREQUENCY |
219  CHANNEL_BACK_CENTER | CHANNEL_SIDE_LEFT |
220  CHANNEL_SIDE_RIGHT,
221  CUBEB_LAYOUT_3F4_LFE = CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT |
222  CHANNEL_FRONT_CENTER | CHANNEL_LOW_FREQUENCY |
223  CHANNEL_BACK_LEFT | CHANNEL_BACK_RIGHT |
224  CHANNEL_SIDE_LEFT | CHANNEL_SIDE_RIGHT,
225 };
226 
228 typedef enum {
231  0x01,
239  0x04,
246  0x08,
256 
258 typedef struct {
261  uint32_t rate;
262  uint32_t channels;
263  cubeb_channel_layout
268 
270 typedef struct {
271  char * output_name;
272  char * input_name;
273 } cubeb_device;
274 
276 typedef enum {
282 
284 enum {
285  CUBEB_OK = 0,
286  CUBEB_ERROR = -1,
288  -2,
291  -4,
293  -5
294 };
295 
299 typedef enum {
300  CUBEB_DEVICE_TYPE_UNKNOWN,
301  CUBEB_DEVICE_TYPE_INPUT,
302  CUBEB_DEVICE_TYPE_OUTPUT
304 
308 typedef enum {
315 
319 typedef enum {
323  CUBEB_DEVICE_FMT_F32BE = 0x2000
325 
326 #if defined(WORDS_BIGENDIAN) || defined(__BIG_ENDIAN__)
328 #define CUBEB_DEVICE_FMT_S16NE CUBEB_DEVICE_FMT_S16BE
331 #define CUBEB_DEVICE_FMT_F32NE CUBEB_DEVICE_FMT_F32BE
332 #else
334 #define CUBEB_DEVICE_FMT_S16NE CUBEB_DEVICE_FMT_S16LE
337 #define CUBEB_DEVICE_FMT_F32NE CUBEB_DEVICE_FMT_F32LE
338 #endif
340 #define CUBEB_DEVICE_FMT_S16_MASK \
341  (CUBEB_DEVICE_FMT_S16LE | CUBEB_DEVICE_FMT_S16BE)
343 #define CUBEB_DEVICE_FMT_F32_MASK \
344  (CUBEB_DEVICE_FMT_F32LE | CUBEB_DEVICE_FMT_F32BE)
346 #define CUBEB_DEVICE_FMT_ALL \
347  (CUBEB_DEVICE_FMT_S16_MASK | CUBEB_DEVICE_FMT_F32_MASK)
348 
353 typedef enum {
354  CUBEB_DEVICE_PREF_NONE = 0x00,
355  CUBEB_DEVICE_PREF_MULTIMEDIA = 0x01,
356  CUBEB_DEVICE_PREF_VOICE = 0x02,
357  CUBEB_DEVICE_PREF_NOTIFICATION = 0x04,
358  CUBEB_DEVICE_PREF_ALL = 0x0F
360 
366 typedef struct {
368  char const *
370  char const * friendly_name;
372  char const * group_id;
375  char const * vendor_name;
384  uint32_t max_channels;
385  uint32_t default_rate;
386  uint32_t max_rate;
387  uint32_t min_rate;
389  uint32_t latency_lo;
390  uint32_t latency_hi;
392 
396 typedef struct {
398  size_t count;
400 
423 typedef long (*cubeb_data_callback)(cubeb_stream * stream, void * user_ptr,
424  void const * input_buffer,
425  void * output_buffer, long nframes);
426 
431 typedef void (*cubeb_state_callback)(cubeb_stream * stream, void * user_ptr,
432  cubeb_state state);
433 
437 typedef void (*cubeb_device_changed_callback)(void * user_ptr);
438 
445  void * user_ptr);
446 
448 typedef void (*cubeb_log_callback)(char const * fmt, ...);
449 
468 CUBEB_EXPORT int
469 cubeb_init(cubeb ** context, char const * context_name,
470  char const * backend_name);
471 
475 CUBEB_EXPORT char const *
477 
485 CUBEB_EXPORT int
486 cubeb_get_max_channel_count(cubeb * context, uint32_t * max_channels);
487 
499 CUBEB_EXPORT int
501  uint32_t * latency_frames);
502 
510 CUBEB_EXPORT int
511 cubeb_get_preferred_sample_rate(cubeb * context, uint32_t * rate);
512 
516 CUBEB_EXPORT void
517 cubeb_destroy(cubeb * context);
518 
551 CUBEB_EXPORT int
552 cubeb_stream_init(cubeb * context, cubeb_stream ** stream,
553  char const * stream_name, cubeb_devid input_device,
554  cubeb_stream_params * input_stream_params,
555  cubeb_devid output_device,
556  cubeb_stream_params * output_stream_params,
557  uint32_t latency_frames, cubeb_data_callback data_callback,
558  cubeb_state_callback state_callback, void * user_ptr);
559 
563 CUBEB_EXPORT void
565 
570 CUBEB_EXPORT int
572 
577 CUBEB_EXPORT int
579 
585 CUBEB_EXPORT int
586 cubeb_stream_get_position(cubeb_stream * stream, uint64_t * position);
587 
596 CUBEB_EXPORT int
597 cubeb_stream_get_latency(cubeb_stream * stream, uint32_t * latency);
598 
608 CUBEB_EXPORT int
609 cubeb_stream_get_input_latency(cubeb_stream * stream, uint32_t * latency);
617 CUBEB_EXPORT int
618 cubeb_stream_set_volume(cubeb_stream * stream, float volume);
619 
626 CUBEB_EXPORT int
627 cubeb_stream_set_name(cubeb_stream * stream, char const * stream_name);
628 
636 CUBEB_EXPORT int
638  cubeb_device ** const device);
639 
646 CUBEB_EXPORT int
648 
657 CUBEB_EXPORT int
659  cubeb_stream * stream,
660  cubeb_device_changed_callback device_changed_callback);
661 
666 CUBEB_EXPORT void *
668 
677 CUBEB_EXPORT int
679  cubeb_device_collection * collection);
680 
686 CUBEB_EXPORT int
688  cubeb_device_collection * collection);
689 
704 CUBEB_EXPORT int
706  cubeb * context, cubeb_device_type devtype,
707  cubeb_device_collection_changed_callback callback, void * user_ptr);
708 
717 CUBEB_EXPORT int
719  cubeb_log_callback log_callback);
720 
721 #if defined(__cplusplus)
722 }
723 #endif
724 
725 #endif /* CUBEB_c2f983e9_c96f_e71c_72c3_bbf62992a382 */
CUBEB_EXPORT int cubeb_get_preferred_sample_rate(cubeb *context, uint32_t *rate)
Get the preferred sample rate for this backend: this is hardware and platform dependent,...
void const * cubeb_devid
An opaque handle used to refer a particular input or output device across calls.
Definition: cubeb.h:155
CUBEB_EXPORT int cubeb_stream_get_current_device(cubeb_stream *stm, cubeb_device **const device)
Get the current output device for this stream.
void(* cubeb_device_collection_changed_callback)(cubeb *context, void *user_ptr)
User supplied callback called when the underlying device collection changed.
Definition: cubeb.h:444
cubeb_device_type
Whether a particular device is an input device (e.g.
Definition: cubeb.h:299
CUBEB_EXPORT int cubeb_register_device_collection_changed(cubeb *context, cubeb_device_type devtype, cubeb_device_collection_changed_callback callback, void *user_ptr)
Registers a callback which is called when the system detects a new device or a device is removed.
CUBEB_EXPORT int cubeb_enumerate_devices(cubeb *context, cubeb_device_type devtype, cubeb_device_collection *collection)
Returns enumerated devices.
CUBEB_EXPORT int cubeb_stream_device_destroy(cubeb_stream *stream, cubeb_device *devices)
Destroy a cubeb_device structure.
CUBEB_EXPORT int cubeb_stream_get_input_latency(cubeb_stream *stream, uint32_t *latency)
Get the input latency for this stream, in frames.
cubeb_device_pref
Channel type for a cubeb_stream.
Definition: cubeb.h:353
CUBEB_EXPORT char const * cubeb_get_backend_id(cubeb *context)
Get a read-only string identifying this context's current backend.
CUBEB_EXPORT int cubeb_stream_set_volume(cubeb_stream *stream, float volume)
Set the volume for a stream.
void(* cubeb_log_callback)(char const *fmt,...)
User supplied callback called when a message needs logging.
Definition: cubeb.h:448
CUBEB_EXPORT int cubeb_set_log_callback(cubeb_log_level log_level, cubeb_log_callback log_callback)
Set a callback to be called with a message.
void(* cubeb_device_changed_callback)(void *user_ptr)
User supplied callback called when the underlying device changed.
Definition: cubeb.h:437
struct cubeb cubeb
Opaque handle referencing the application state.
Definition: cubeb.h:125
CUBEB_EXPORT int cubeb_stream_register_device_changed_callback(cubeb_stream *stream, cubeb_device_changed_callback device_changed_callback)
Set a callback to be notified when the output device changes.
CUBEB_EXPORT int cubeb_stream_start(cubeb_stream *stream)
Start playback.
CUBEB_EXPORT int cubeb_stream_init(cubeb *context, cubeb_stream **stream, char const *stream_name, cubeb_devid input_device, cubeb_stream_params *input_stream_params, cubeb_devid output_device, cubeb_stream_params *output_stream_params, uint32_t latency_frames, cubeb_data_callback data_callback, cubeb_state_callback state_callback, void *user_ptr)
Initialize a stream associated with the supplied application context.
long(* cubeb_data_callback)(cubeb_stream *stream, void *user_ptr, void const *input_buffer, void *output_buffer, long nframes)
User supplied data callback.
Definition: cubeb.h:423
cubeb_sample_format
Sample format enumeration.
Definition: cubeb.h:131
@ CUBEB_SAMPLE_FLOAT32LE
Big endian 32-bit IEEE floating point PCM.
Definition: cubeb.h:137
@ CUBEB_SAMPLE_FLOAT32BE
Native endian 16-bit signed PCM.
Definition: cubeb.h:139
@ CUBEB_SAMPLE_S16BE
Little endian 32-bit IEEE floating point PCM.
Definition: cubeb.h:135
@ CUBEB_SAMPLE_S16LE
Little endian 16-bit signed PCM.
Definition: cubeb.h:133
@ CUBEB_SAMPLE_S16NE
Native endian 32-bit IEEE floating point PCM.
Definition: cubeb.h:147
cubeb_device_state
The state of a device.
Definition: cubeb.h:308
@ CUBEB_DEVICE_STATE_DISABLED
The device has been disabled at the system level.
Definition: cubeb.h:309
@ CUBEB_DEVICE_STATE_ENABLED
The device is enabled.
Definition: cubeb.h:313
@ CUBEB_DEVICE_STATE_UNPLUGGED
The device is enabled, but nothing is plugged into it.
Definition: cubeb.h:311
CUBEB_EXPORT int cubeb_get_max_channel_count(cubeb *context, uint32_t *max_channels)
Get the maximum possible number of channels.
cubeb_stream_prefs
Miscellaneous stream preferences.
Definition: cubeb.h:228
@ CUBEB_STREAM_PREF_JACK_NO_AUTO_CONNECT
Don't automatically try to connect ports.
Definition: cubeb.h:252
@ CUBEB_STREAM_PREF_NONE
No stream preferences are requested.
Definition: cubeb.h:229
@ CUBEB_STREAM_PREF_DISABLE_DEVICE_SWITCHING
Disable switching default device on OS changes.
Definition: cubeb.h:235
@ CUBEB_STREAM_PREF_PERSIST
Request that the volume and mute settings should persist across restarts of the stream and/or applica...
Definition: cubeb.h:248
@ CUBEB_STREAM_PREF_RAW
Windows only.
Definition: cubeb.h:245
@ CUBEB_STREAM_PREF_VOICE
This stream is going to transport voice data.
Definition: cubeb.h:238
@ CUBEB_STREAM_PREF_LOOPBACK
Request a loopback stream.
Definition: cubeb.h:230
CUBEB_EXPORT int cubeb_stream_get_latency(cubeb_stream *stream, uint32_t *latency)
Get the latency for this stream, in frames.
CUBEB_EXPORT int cubeb_init(cubeb **context, char const *context_name, char const *backend_name)
Initialize an application context.
struct cubeb_stream cubeb_stream
Opaque handle referencing the stream state.
Definition: cubeb.h:127
CUBEB_EXPORT int cubeb_stream_stop(cubeb_stream *stream)
Stop playback.
CUBEB_EXPORT void * cubeb_stream_user_ptr(cubeb_stream *stream)
Return the user data pointer registered with the stream with cubeb_stream_init.
CUBEB_EXPORT int cubeb_device_collection_destroy(cubeb *context, cubeb_device_collection *collection)
Destroy a cubeb_device_collection, and its cubeb_device_info.
CUBEB_EXPORT int cubeb_stream_get_position(cubeb_stream *stream, uint64_t *position)
Get the current stream playback position.
void(* cubeb_state_callback)(cubeb_stream *stream, void *user_ptr, cubeb_state state)
User supplied state callback.
Definition: cubeb.h:431
CUBEB_EXPORT void cubeb_stream_destroy(cubeb_stream *stream)
Destroy a stream.
CUBEB_EXPORT int cubeb_stream_set_name(cubeb_stream *stream, char const *stream_name)
Change a stream's name.
cubeb_device_fmt
Architecture specific sample type.
Definition: cubeb.h:319
@ CUBEB_DEVICE_FMT_S16BE
16-bit integers, Big Endian.
Definition: cubeb.h:321
@ CUBEB_DEVICE_FMT_F32BE
32-bit floating point, Big Endian.
Definition: cubeb.h:323
@ CUBEB_DEVICE_FMT_S16LE
16-bit integers, Little Endian.
Definition: cubeb.h:320
@ CUBEB_DEVICE_FMT_F32LE
32-bit floating point, Little Endian.
Definition: cubeb.h:322
@ CUBEB_ERROR
Unclassified error.
Definition: cubeb.h:286
@ CUBEB_ERROR_INVALID_FORMAT
Unsupported cubeb_stream_params requested.
Definition: cubeb.h:287
@ CUBEB_ERROR_NOT_SUPPORTED
Optional function not implemented in current backend.
Definition: cubeb.h:290
@ CUBEB_ERROR_DEVICE_UNAVAILABLE
Device specified by cubeb_devid not available.
Definition: cubeb.h:292
@ CUBEB_OK
Success.
Definition: cubeb.h:285
@ CUBEB_ERROR_INVALID_PARAMETER
Invalid parameter specified.
Definition: cubeb.h:289
CUBEB_EXPORT void cubeb_destroy(cubeb *context)
Destroy an application context.
cubeb_log_level
Level (verbosity) of logging for a particular cubeb context.
Definition: cubeb.h:158
@ CUBEB_LOG_NORMAL
< Logging disabled
Definition: cubeb.h:160
@ CUBEB_LOG_VERBOSE
Verbose logging of callbacks, can have performance implications.
Definition: cubeb.h:162
CUBEB_EXPORT int cubeb_get_min_latency(cubeb *context, cubeb_stream_params *params, uint32_t *latency_frames)
Get the minimal latency value, in frames, that is guaranteed to work when creating a stream for the s...
cubeb_state
Stream states signaled via state_callback.
Definition: cubeb.h:276
@ CUBEB_STATE_STARTED
Stream started.
Definition: cubeb.h:277
@ CUBEB_STATE_ERROR
Stream disabled due to error.
Definition: cubeb.h:280
@ CUBEB_STATE_DRAINED
Stream drained.
Definition: cubeb.h:279
@ CUBEB_STATE_STOPPED
Stream stopped.
Definition: cubeb.h:278
Device collection.
Definition: cubeb.h:396
size_t count
Device count in collection.
Definition: cubeb.h:398
cubeb_device_info * device
Array of pointers to device info.
Definition: cubeb.h:397
This structure holds the characteristics of an input or output audio device.
Definition: cubeb.h:366
cubeb_device_state state
State of device disabled/enabled/unplugged.
Definition: cubeb.h:378
uint32_t max_rate
Maximum sample rate supported.
Definition: cubeb.h:386
uint32_t min_rate
Minimum sample rate supported.
Definition: cubeb.h:387
cubeb_device_type type
Type of device (Input/Output).
Definition: cubeb.h:377
cubeb_device_pref preferred
Preferred device.
Definition: cubeb.h:379
cubeb_device_fmt default_format
The default sample format for this device.
Definition: cubeb.h:383
char const * group_id
Two devices have the same group identifier if they belong to the same physical device; for example a ...
Definition: cubeb.h:372
uint32_t max_channels
Channels.
Definition: cubeb.h:384
uint32_t default_rate
Default/Preferred sample rate.
Definition: cubeb.h:385
uint32_t latency_lo
Lowest possible latency in frames.
Definition: cubeb.h:389
char const * vendor_name
Optional vendor name, may be NULL.
Definition: cubeb.h:375
uint32_t latency_hi
Higest possible latency in frames.
Definition: cubeb.h:390
char const * device_id
Device identifier which might be presented in a UI.
Definition: cubeb.h:369
cubeb_devid devid
Device identifier handle.
Definition: cubeb.h:367
char const * friendly_name
Friendly device name which might be presented in a UI.
Definition: cubeb.h:370
cubeb_device_fmt format
Sample format supported.
Definition: cubeb.h:381
Audio device description.
Definition: cubeb.h:270
char * input_name
The name of the input device.
Definition: cubeb.h:272
char * output_name
The name of the output device.
Definition: cubeb.h:271
Stream format initialization parameters.
Definition: cubeb.h:258
cubeb_sample_format format
Requested sample format.
Definition: cubeb.h:259
cubeb_channel_layout layout
Requested channel layout.
Definition: cubeb.h:264
cubeb_stream_prefs prefs
Requested preferences.
Definition: cubeb.h:266
uint32_t rate
Requested sample rate.
Definition: cubeb.h:261
uint32_t channels
Requested channel count.
Definition: cubeb.h:262