cubeb.h (34058B)
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 18 /** @mainpage 19 20 @section intro Introduction 21 22 This is the documentation for the <tt>libcubeb</tt> C API. 23 <tt>libcubeb</tt> is a callback-based audio API library allowing the 24 authoring of portable multiplatform audio playback and recording. 25 26 @section example Example code 27 28 This example shows how to create a duplex stream that pipes the microphone 29 to the speakers, with minimal latency and the proper sample-rate for the 30 platform. 31 32 @code 33 cubeb * app_ctx; 34 cubeb_init(&app_ctx, "Example Application", NULL); 35 int rv; 36 uint32_t rate; 37 uint32_t latency_frames; 38 uint64_t ts; 39 40 rv = cubeb_get_preferred_sample_rate(app_ctx, &rate); 41 if (rv != CUBEB_OK) { 42 fprintf(stderr, "Could not get preferred sample-rate"); 43 return rv; 44 } 45 46 cubeb_stream_params output_params; 47 output_params.format = CUBEB_SAMPLE_FLOAT32NE; 48 output_params.rate = rate; 49 output_params.channels = 2; 50 output_params.layout = CUBEB_LAYOUT_UNDEFINED; 51 output_params.prefs = CUBEB_STREAM_PREF_NONE; 52 output_params.input_params = CUBEB_INPUT_PROCESSING_PARAM_NONE; 53 54 rv = cubeb_get_min_latency(app_ctx, &output_params, &latency_frames); 55 if (rv != CUBEB_OK) { 56 fprintf(stderr, "Could not get minimum latency"); 57 return rv; 58 } 59 60 cubeb_stream_params input_params; 61 input_params.format = CUBEB_SAMPLE_FLOAT32NE; 62 input_params.rate = rate; 63 input_params.channels = 1; 64 input_params.layout = CUBEB_LAYOUT_UNDEFINED; 65 input_params.prefs = CUBEB_STREAM_PREF_NONE; 66 input_params.input_params = CUBEB_INPUT_PROCESSING_PARAM_NONE; 67 68 cubeb_stream * stm; 69 rv = cubeb_stream_init(app_ctx, &stm, "Example Stream 1", 70 NULL, &input_params, 71 NULL, &output_params, 72 latency_frames, 73 data_cb, state_cb, 74 NULL); 75 if (rv != CUBEB_OK) { 76 fprintf(stderr, "Could not open the stream"); 77 return rv; 78 } 79 80 rv = cubeb_stream_start(stm); 81 if (rv != CUBEB_OK) { 82 fprintf(stderr, "Could not start the stream"); 83 return rv; 84 } 85 for (;;) { 86 cubeb_stream_get_position(stm, &ts); 87 printf("time=%llu\n", ts); 88 sleep(1); 89 } 90 rv = cubeb_stream_stop(stm); 91 if (rv != CUBEB_OK) { 92 fprintf(stderr, "Could not stop the stream"); 93 return rv; 94 } 95 96 cubeb_stream_destroy(stm); 97 cubeb_destroy(app_ctx); 98 @endcode 99 100 @code 101 long data_cb(cubeb_stream * stm, void * user, 102 const void * input_buffer, void * output_buffer, long nframes) 103 { 104 const float * in = input_buffer; 105 float * out = output_buffer; 106 107 for (int i = 0; i < nframes; ++i) { 108 for (int c = 0; c < 2; ++c) { 109 out[2 * i + c] = in[i]; 110 } 111 } 112 return nframes; 113 } 114 @endcode 115 116 @code 117 void state_cb(cubeb_stream * stm, void * user, cubeb_state state) 118 { 119 printf("state=%d\n", state); 120 } 121 @endcode 122 */ 123 124 /** @file 125 The <tt>libcubeb</tt> C API. */ 126 127 typedef struct cubeb 128 cubeb; /**< Opaque handle referencing the application state. */ 129 typedef struct cubeb_stream 130 cubeb_stream; /**< Opaque handle referencing the stream state. */ 131 132 /** Sample format enumeration. */ 133 typedef enum { 134 /**< Little endian 16-bit signed PCM. */ 135 CUBEB_SAMPLE_S16LE, 136 /**< Big endian 16-bit signed PCM. */ 137 CUBEB_SAMPLE_S16BE, 138 /**< Little endian 32-bit IEEE floating point PCM. */ 139 CUBEB_SAMPLE_FLOAT32LE, 140 /**< Big endian 32-bit IEEE floating point PCM. */ 141 CUBEB_SAMPLE_FLOAT32BE, 142 #if defined(WORDS_BIGENDIAN) || defined(__BIG_ENDIAN__) 143 /**< Native endian 16-bit signed PCM. */ 144 CUBEB_SAMPLE_S16NE = CUBEB_SAMPLE_S16BE, 145 /**< Native endian 32-bit IEEE floating point PCM. */ 146 CUBEB_SAMPLE_FLOAT32NE = CUBEB_SAMPLE_FLOAT32BE 147 #else 148 /**< Native endian 16-bit signed PCM. */ 149 CUBEB_SAMPLE_S16NE = CUBEB_SAMPLE_S16LE, 150 /**< Native endian 32-bit IEEE floating point PCM. */ 151 CUBEB_SAMPLE_FLOAT32NE = CUBEB_SAMPLE_FLOAT32LE 152 #endif 153 } cubeb_sample_format; 154 155 /** An opaque handle used to refer a particular input or output device 156 * across calls. */ 157 typedef void const * cubeb_devid; 158 159 /** Level (verbosity) of logging for a particular cubeb context. */ 160 typedef enum { 161 CUBEB_LOG_DISABLED = 0, /** < Logging disabled */ 162 CUBEB_LOG_NORMAL = 163 1, /**< Logging lifetime operation (creation/destruction). */ 164 CUBEB_LOG_VERBOSE = 2, /**< Verbose logging of callbacks, can have performance 165 implications. */ 166 } cubeb_log_level; 167 168 /// A single channel position, to be used in a bitmask. 169 typedef enum { 170 CHANNEL_UNKNOWN = 0, 171 CHANNEL_FRONT_LEFT = 1 << 0, 172 CHANNEL_FRONT_RIGHT = 1 << 1, 173 CHANNEL_FRONT_CENTER = 1 << 2, 174 CHANNEL_LOW_FREQUENCY = 1 << 3, 175 CHANNEL_BACK_LEFT = 1 << 4, 176 CHANNEL_BACK_RIGHT = 1 << 5, 177 CHANNEL_FRONT_LEFT_OF_CENTER = 1 << 6, 178 CHANNEL_FRONT_RIGHT_OF_CENTER = 1 << 7, 179 CHANNEL_BACK_CENTER = 1 << 8, 180 CHANNEL_SIDE_LEFT = 1 << 9, 181 CHANNEL_SIDE_RIGHT = 1 << 10, 182 CHANNEL_TOP_CENTER = 1 << 11, 183 CHANNEL_TOP_FRONT_LEFT = 1 << 12, 184 CHANNEL_TOP_FRONT_CENTER = 1 << 13, 185 CHANNEL_TOP_FRONT_RIGHT = 1 << 14, 186 CHANNEL_TOP_BACK_LEFT = 1 << 15, 187 CHANNEL_TOP_BACK_CENTER = 1 << 16, 188 CHANNEL_TOP_BACK_RIGHT = 1 << 17 189 } cubeb_channel; 190 191 /// A bitmask representing the channel layout of a cubeb stream. This is 192 /// bit-compatible with WAVEFORMATEXENSIBLE and in the same order as the SMPTE 193 /// ordering. 194 typedef uint32_t cubeb_channel_layout; 195 // Some common layout definitions. 196 enum { 197 CUBEB_LAYOUT_UNDEFINED = 0, // Indicate the speaker's layout is undefined. 198 CUBEB_LAYOUT_MONO = CHANNEL_FRONT_CENTER, 199 CUBEB_LAYOUT_MONO_LFE = CUBEB_LAYOUT_MONO | CHANNEL_LOW_FREQUENCY, 200 CUBEB_LAYOUT_STEREO = CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT, 201 CUBEB_LAYOUT_STEREO_LFE = CUBEB_LAYOUT_STEREO | CHANNEL_LOW_FREQUENCY, 202 CUBEB_LAYOUT_3F = 203 CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT | CHANNEL_FRONT_CENTER, 204 CUBEB_LAYOUT_3F_LFE = CUBEB_LAYOUT_3F | CHANNEL_LOW_FREQUENCY, 205 CUBEB_LAYOUT_2F1 = 206 CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT | CHANNEL_BACK_CENTER, 207 CUBEB_LAYOUT_2F1_LFE = CUBEB_LAYOUT_2F1 | CHANNEL_LOW_FREQUENCY, 208 CUBEB_LAYOUT_3F1 = CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT | 209 CHANNEL_FRONT_CENTER | CHANNEL_BACK_CENTER, 210 CUBEB_LAYOUT_3F1_LFE = CUBEB_LAYOUT_3F1 | CHANNEL_LOW_FREQUENCY, 211 CUBEB_LAYOUT_2F2 = CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT | 212 CHANNEL_SIDE_LEFT | CHANNEL_SIDE_RIGHT, 213 CUBEB_LAYOUT_2F2_LFE = CUBEB_LAYOUT_2F2 | CHANNEL_LOW_FREQUENCY, 214 CUBEB_LAYOUT_QUAD = CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT | 215 CHANNEL_BACK_LEFT | CHANNEL_BACK_RIGHT, 216 CUBEB_LAYOUT_QUAD_LFE = CUBEB_LAYOUT_QUAD | CHANNEL_LOW_FREQUENCY, 217 CUBEB_LAYOUT_3F2 = CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT | 218 CHANNEL_FRONT_CENTER | CHANNEL_SIDE_LEFT | 219 CHANNEL_SIDE_RIGHT, 220 CUBEB_LAYOUT_3F2_LFE = CUBEB_LAYOUT_3F2 | CHANNEL_LOW_FREQUENCY, 221 CUBEB_LAYOUT_3F2_BACK = CUBEB_LAYOUT_QUAD | CHANNEL_FRONT_CENTER, 222 CUBEB_LAYOUT_3F2_LFE_BACK = CUBEB_LAYOUT_3F2_BACK | CHANNEL_LOW_FREQUENCY, 223 CUBEB_LAYOUT_3F3R_LFE = CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT | 224 CHANNEL_FRONT_CENTER | CHANNEL_LOW_FREQUENCY | 225 CHANNEL_BACK_CENTER | CHANNEL_SIDE_LEFT | 226 CHANNEL_SIDE_RIGHT, 227 CUBEB_LAYOUT_3F4_LFE = CHANNEL_FRONT_LEFT | CHANNEL_FRONT_RIGHT | 228 CHANNEL_FRONT_CENTER | CHANNEL_LOW_FREQUENCY | 229 CHANNEL_BACK_LEFT | CHANNEL_BACK_RIGHT | 230 CHANNEL_SIDE_LEFT | CHANNEL_SIDE_RIGHT, 231 }; 232 233 /** Miscellaneous stream preferences. */ 234 typedef enum { 235 CUBEB_STREAM_PREF_NONE = 0x00, /**< No stream preferences are requested. */ 236 CUBEB_STREAM_PREF_LOOPBACK = 237 0x01, /**< Request a loopback stream. Should be 238 specified on the input params and an 239 output device to loopback from should 240 be passed in place of an input device. */ 241 CUBEB_STREAM_PREF_DISABLE_DEVICE_SWITCHING = 0x02, /**< Disable switching 242 default device on OS 243 changes. */ 244 CUBEB_STREAM_PREF_VOICE = 245 0x04, /**< This stream is going to transport voice data. 246 Depending on the backend and platform, this can 247 change the audio input or output devices 248 selected, as well as the quality of the stream, 249 for example to accomodate bluetooth SCO modes on 250 bluetooth devices. */ 251 CUBEB_STREAM_PREF_RAW = 252 0x08, /**< Windows only. Bypass all signal processing 253 except for always on APO, driver and hardware. */ 254 CUBEB_STREAM_PREF_PERSIST = 0x10, /**< Request that the volume and mute 255 settings should persist across restarts 256 of the stream and/or application. This is 257 obsolete and ignored by all backends. */ 258 CUBEB_STREAM_PREF_JACK_NO_AUTO_CONNECT = 0x20 /**< Don't automatically try to 259 connect ports. Only affects 260 the jack backend. */ 261 } cubeb_stream_prefs; 262 263 /** 264 * Input stream audio processing parameters. Only applicable with 265 * CUBEB_STREAM_PREF_VOICE. 266 */ 267 typedef enum { 268 CUBEB_INPUT_PROCESSING_PARAM_NONE = 0x00, 269 CUBEB_INPUT_PROCESSING_PARAM_ECHO_CANCELLATION = 0x01, 270 CUBEB_INPUT_PROCESSING_PARAM_NOISE_SUPPRESSION = 0x02, 271 CUBEB_INPUT_PROCESSING_PARAM_AUTOMATIC_GAIN_CONTROL = 0x04, 272 CUBEB_INPUT_PROCESSING_PARAM_VOICE_ISOLATION = 0x08, 273 } cubeb_input_processing_params; 274 275 /** Stream format initialization parameters. */ 276 typedef struct { 277 cubeb_sample_format format; /**< Requested sample format. One of 278 #cubeb_sample_format. */ 279 uint32_t rate; /**< Requested sample rate. Valid range is [1000, 384000]. */ 280 uint32_t channels; /**< Requested channel count. Valid range is [1, 8]. */ 281 cubeb_channel_layout 282 layout; /**< Requested channel layout. This must be consistent with the 283 provided channels. CUBEB_LAYOUT_UNDEFINED if unknown */ 284 cubeb_stream_prefs prefs; /**< Requested preferences. */ 285 cubeb_input_processing_params input_params; /**< Requested input processing 286 params. Ignored for output streams. At present, only supported on the 287 WASAPI backend; others should use cubeb_set_input_processing_params. */ 288 } cubeb_stream_params; 289 290 /** Audio device description */ 291 typedef struct { 292 char * output_name; /**< The name of the output device */ 293 char * input_name; /**< The name of the input device */ 294 } cubeb_device; 295 296 /** Stream states signaled via state_callback. */ 297 typedef enum { 298 CUBEB_STATE_STARTED, /**< Stream started. */ 299 CUBEB_STATE_STOPPED, /**< Stream stopped. */ 300 CUBEB_STATE_DRAINED, /**< Stream drained. */ 301 CUBEB_STATE_ERROR /**< Stream disabled due to error. */ 302 } cubeb_state; 303 304 /** Result code enumeration. */ 305 enum { 306 CUBEB_OK = 0, /**< Success. */ 307 CUBEB_ERROR = -1, /**< Unclassified error. */ 308 CUBEB_ERROR_INVALID_FORMAT = 309 -2, /**< Unsupported #cubeb_stream_params requested. */ 310 CUBEB_ERROR_INVALID_PARAMETER = -3, /**< Invalid parameter specified. */ 311 CUBEB_ERROR_NOT_SUPPORTED = 312 -4, /**< Optional function not implemented in current backend. */ 313 CUBEB_ERROR_DEVICE_UNAVAILABLE = 314 -5 /**< Device specified by #cubeb_devid not available. */ 315 }; 316 317 /** 318 * Whether a particular device is an input device (e.g. a microphone), or an 319 * output device (e.g. headphones). */ 320 typedef enum { 321 CUBEB_DEVICE_TYPE_UNKNOWN, 322 CUBEB_DEVICE_TYPE_INPUT, 323 CUBEB_DEVICE_TYPE_OUTPUT 324 } cubeb_device_type; 325 326 /** 327 * The state of a device. 328 */ 329 typedef enum { 330 CUBEB_DEVICE_STATE_DISABLED, /**< The device has been disabled at the system 331 level. */ 332 CUBEB_DEVICE_STATE_UNPLUGGED, /**< The device is enabled, but nothing is 333 plugged into it. */ 334 CUBEB_DEVICE_STATE_ENABLED /**< The device is enabled. */ 335 } cubeb_device_state; 336 337 /** 338 * Architecture specific sample type. 339 */ 340 typedef enum { 341 CUBEB_DEVICE_FMT_S16LE = 0x0010, /**< 16-bit integers, Little Endian. */ 342 CUBEB_DEVICE_FMT_S16BE = 0x0020, /**< 16-bit integers, Big Endian. */ 343 CUBEB_DEVICE_FMT_F32LE = 0x1000, /**< 32-bit floating point, Little Endian. */ 344 CUBEB_DEVICE_FMT_F32BE = 0x2000 /**< 32-bit floating point, Big Endian. */ 345 } cubeb_device_fmt; 346 347 #if defined(WORDS_BIGENDIAN) || defined(__BIG_ENDIAN__) 348 /** 16-bit integers, native endianess, when on a Big Endian environment. */ 349 #define CUBEB_DEVICE_FMT_S16NE CUBEB_DEVICE_FMT_S16BE 350 /** 32-bit floating points, native endianess, when on a Big Endian environment. 351 */ 352 #define CUBEB_DEVICE_FMT_F32NE CUBEB_DEVICE_FMT_F32BE 353 #else 354 /** 16-bit integers, native endianess, when on a Little Endian environment. */ 355 #define CUBEB_DEVICE_FMT_S16NE CUBEB_DEVICE_FMT_S16LE 356 /** 32-bit floating points, native endianess, when on a Little Endian 357 * environment. */ 358 #define CUBEB_DEVICE_FMT_F32NE CUBEB_DEVICE_FMT_F32LE 359 #endif 360 /** All the 16-bit integers types. */ 361 #define CUBEB_DEVICE_FMT_S16_MASK \ 362 (CUBEB_DEVICE_FMT_S16LE | CUBEB_DEVICE_FMT_S16BE) 363 /** All the 32-bit floating points types. */ 364 #define CUBEB_DEVICE_FMT_F32_MASK \ 365 (CUBEB_DEVICE_FMT_F32LE | CUBEB_DEVICE_FMT_F32BE) 366 /** All the device formats types. */ 367 #define CUBEB_DEVICE_FMT_ALL \ 368 (CUBEB_DEVICE_FMT_S16_MASK | CUBEB_DEVICE_FMT_F32_MASK) 369 370 /** Channel type for a `cubeb_stream`. Depending on the backend and platform 371 * used, this can control inter-stream interruption, ducking, and volume 372 * control. 373 */ 374 typedef enum { 375 CUBEB_DEVICE_PREF_NONE = 0x00, 376 CUBEB_DEVICE_PREF_MULTIMEDIA = 0x01, 377 CUBEB_DEVICE_PREF_VOICE = 0x02, 378 CUBEB_DEVICE_PREF_NOTIFICATION = 0x04, 379 CUBEB_DEVICE_PREF_ALL = 0x0F 380 } cubeb_device_pref; 381 382 /** This structure holds the characteristics 383 * of an input or output audio device. It is obtained using 384 * `cubeb_enumerate_devices`, which returns these structures via 385 * `cubeb_device_collection` and must be destroyed via 386 * `cubeb_device_collection_destroy`. */ 387 typedef struct { 388 cubeb_devid devid; /**< Device identifier handle. */ 389 char const * 390 device_id; /**< Device identifier which might be presented in a UI. */ 391 char const * friendly_name; /**< Friendly device name which might be presented 392 in a UI. */ 393 char const * group_id; /**< Two devices have the same group identifier if they 394 belong to the same physical device; for example a 395 headset and microphone. */ 396 char const * vendor_name; /**< Optional vendor name, may be NULL. */ 397 398 cubeb_device_type type; /**< Type of device (Input/Output). */ 399 cubeb_device_state state; /**< State of device disabled/enabled/unplugged. */ 400 cubeb_device_pref preferred; /**< Preferred device. */ 401 402 cubeb_device_fmt format; /**< Sample format supported. */ 403 cubeb_device_fmt 404 default_format; /**< The default sample format for this device. */ 405 uint32_t max_channels; /**< Channels. */ 406 uint32_t default_rate; /**< Default/Preferred sample rate. */ 407 uint32_t max_rate; /**< Maximum sample rate supported. */ 408 uint32_t min_rate; /**< Minimum sample rate supported. */ 409 410 uint32_t latency_lo; /**< Lowest possible latency in frames. */ 411 uint32_t latency_hi; /**< Higest possible latency in frames. */ 412 } cubeb_device_info; 413 414 /** Device collection. 415 * Returned by `cubeb_enumerate_devices` and destroyed by 416 * `cubeb_device_collection_destroy`. */ 417 typedef struct { 418 cubeb_device_info * device; /**< Array of pointers to device info. */ 419 size_t count; /**< Device count in collection. */ 420 } cubeb_device_collection; 421 422 /** Array of compiled backends returned by `cubeb_get_backend_names`. */ 423 typedef struct { 424 const char * const * 425 names; /**< Array of strings representing backend names. */ 426 size_t count; /**< Length of the array. */ 427 } cubeb_backend_names; 428 429 /** User supplied data callback. 430 - Calling other cubeb functions from this callback is unsafe. 431 - The code in the callback should be non-blocking. 432 - Returning less than the number of frames this callback asks for or 433 provides puts the stream in drain mode. This callback will not be called 434 again, and the state callback will be called with CUBEB_STATE_DRAINED when 435 all the frames have been output. 436 @param stream The stream for which this callback fired. 437 @param user_ptr The pointer passed to cubeb_stream_init. 438 @param input_buffer A pointer containing the input data, or nullptr 439 if this is an output-only stream. 440 @param output_buffer A pointer to a buffer to be filled with audio samples, 441 or nullptr if this is an input-only stream. 442 @param nframes The number of frames of the two buffer. 443 @retval If the stream has output, this is the number of frames written to 444 the output buffer. In this case, if this number is less than 445 nframes then the stream will start to drain. If the stream is 446 input only, then returning nframes indicates data has been read. 447 In this case, a value less than nframes will result in the stream 448 being stopped. 449 @retval CUBEB_ERROR on error, in which case the data callback will stop 450 and the stream will enter a shutdown state. */ 451 typedef long (*cubeb_data_callback)(cubeb_stream * stream, void * user_ptr, 452 void const * input_buffer, 453 void * output_buffer, long nframes); 454 455 /** User supplied state callback. 456 @param stream The stream for this this callback fired. 457 @param user_ptr The pointer passed to cubeb_stream_init. 458 @param state The new state of the stream. */ 459 typedef void (*cubeb_state_callback)(cubeb_stream * stream, void * user_ptr, 460 cubeb_state state); 461 462 /** 463 * User supplied callback called when the underlying device changed. 464 * @param user_ptr The pointer passed to cubeb_stream_init. */ 465 typedef void (*cubeb_device_changed_callback)(void * user_ptr); 466 467 /** 468 * User supplied callback called when the underlying device collection changed. 469 * This callback will be called when devices are added or removed from the 470 * system, or when the default device changes for the specified device type. 471 * @param context A pointer to the cubeb context. 472 * @param user_ptr The pointer passed to 473 * cubeb_register_device_collection_changed. */ 474 typedef void (*cubeb_device_collection_changed_callback)(cubeb * context, 475 void * user_ptr); 476 477 /** User supplied callback called when a message needs logging. */ 478 typedef void (*cubeb_log_callback)(char const * fmt, ...); 479 480 /** Initialize an application context. This will perform any library or 481 application scoped initialization. 482 483 Note: On Windows platforms, COM must be initialized in MTA mode on 484 any thread that will call the cubeb API. 485 486 @param context A out param where an opaque pointer to the application 487 context will be returned. 488 @param context_name A name for the context. Depending on the platform this 489 can appear in different locations. 490 @param backend_name The name of the cubeb backend user desires to select. 491 Accepted values self-documented in cubeb.c: init_oneshot 492 If NULL, a default ordering is used for backend choice. 493 A valid choice overrides all other possible backends, 494 so long as the backend was included at compile time. 495 @retval CUBEB_OK in case of success. 496 @retval CUBEB_ERROR in case of error, for example because the host 497 has no audio hardware. */ 498 CUBEB_EXPORT int 499 cubeb_init(cubeb ** context, char const * context_name, 500 char const * backend_name); 501 502 /** Get a read-only string identifying this context's current backend. 503 @param context A pointer to the cubeb context. 504 @retval Read-only string identifying current backend. */ 505 CUBEB_EXPORT char const * 506 cubeb_get_backend_id(cubeb * context); 507 508 /** Get a read-only array of strings identifying available backends. 509 These can be passed as `backend_name` parameter to `cubeb_init`. 510 @retval Struct containing the array with backend names. */ 511 CUBEB_EXPORT cubeb_backend_names 512 cubeb_get_backend_names(); 513 514 /** Get the maximum possible number of channels. 515 @param context A pointer to the cubeb context. 516 @param max_channels The maximum number of channels. 517 @retval CUBEB_OK 518 @retval CUBEB_ERROR_INVALID_PARAMETER 519 @retval CUBEB_ERROR_NOT_SUPPORTED 520 @retval CUBEB_ERROR */ 521 CUBEB_EXPORT int 522 cubeb_get_max_channel_count(cubeb * context, uint32_t * max_channels); 523 524 /** Get the minimal latency value, in frames, that is guaranteed to work 525 when creating a stream for the specified sample rate. This is platform, 526 hardware and backend dependent. 527 @param context A pointer to the cubeb context. 528 @param params On some backends, the minimum achievable latency depends on 529 the characteristics of the stream. 530 @param latency_frames The latency value, in frames, to pass to 531 cubeb_stream_init. 532 @retval CUBEB_OK 533 @retval CUBEB_ERROR_INVALID_PARAMETER 534 @retval CUBEB_ERROR_NOT_SUPPORTED */ 535 CUBEB_EXPORT int 536 cubeb_get_min_latency(cubeb * context, cubeb_stream_params * params, 537 uint32_t * latency_frames); 538 539 /** Get the preferred sample rate for this backend: this is hardware and 540 platform dependent, and can avoid resampling, and/or trigger fastpaths. 541 @param context A pointer to the cubeb context. 542 @param rate The samplerate (in Hz) the current configuration prefers. 543 @retval CUBEB_OK 544 @retval CUBEB_ERROR_INVALID_PARAMETER 545 @retval CUBEB_ERROR_NOT_SUPPORTED */ 546 CUBEB_EXPORT int 547 cubeb_get_preferred_sample_rate(cubeb * context, uint32_t * rate); 548 549 /** Get the supported input processing features for this backend. See 550 cubeb_stream_set_input_processing for how to set them for a particular input 551 stream. 552 @param context A pointer to the cubeb context. 553 @param params Out parameter for the input processing params supported by 554 this backend. 555 @retval CUBEB_OK 556 @retval CUBEB_ERROR_NOT_SUPPORTED */ 557 CUBEB_EXPORT int 558 cubeb_get_supported_input_processing_params( 559 cubeb * context, cubeb_input_processing_params * params); 560 561 /** Destroy an application context. This must be called after all stream have 562 * been destroyed. 563 @param context A pointer to the cubeb context.*/ 564 CUBEB_EXPORT void 565 cubeb_destroy(cubeb * context); 566 567 /** Initialize a stream associated with the supplied application context. 568 @param context A pointer to the cubeb context. 569 @param stream An out parameter to be filled with the an opaque pointer to a 570 cubeb stream. 571 @param stream_name A name for this stream. 572 @param input_device Device for the input side of the stream. If NULL the 573 default input device is used. Passing a valid 574 cubeb_devid means the stream only ever uses that device. Passing a NULL 575 cubeb_devid allows the stream to follow that device 576 type's OS default. 577 @param input_stream_params Parameters for the input side of the stream, or 578 NULL if this stream is output only. 579 @param output_device Device for the output side of the stream. If NULL the 580 default output device is used. Passing a valid 581 cubeb_devid means the stream only ever uses that device. Passing a NULL 582 cubeb_devid allows the stream to follow that device 583 type's OS default. 584 @param output_stream_params Parameters for the output side of the stream, or 585 NULL if this stream is input only. When input 586 and output stream parameters are supplied, their 587 rate has to be the same. 588 @param latency_frames Stream latency in frames. Valid range 589 is [1, 96000]. 590 @param data_callback Will be called to preroll data before playback is 591 started by cubeb_stream_start. 592 @param state_callback A pointer to a state callback. 593 @param user_ptr A pointer that will be passed to the callbacks. This pointer 594 must outlive the life time of the stream. 595 @retval CUBEB_OK 596 @retval CUBEB_ERROR 597 @retval CUBEB_ERROR_INVALID_FORMAT 598 @retval CUBEB_ERROR_DEVICE_UNAVAILABLE */ 599 CUBEB_EXPORT int 600 cubeb_stream_init(cubeb * context, cubeb_stream ** stream, 601 char const * stream_name, cubeb_devid input_device, 602 cubeb_stream_params * input_stream_params, 603 cubeb_devid output_device, 604 cubeb_stream_params * output_stream_params, 605 uint32_t latency_frames, cubeb_data_callback data_callback, 606 cubeb_state_callback state_callback, void * user_ptr); 607 608 /** Destroy a stream. `cubeb_stream_stop` MUST be called before destroying a 609 stream. 610 @param stream The stream to destroy. */ 611 CUBEB_EXPORT void 612 cubeb_stream_destroy(cubeb_stream * stream); 613 614 /** Start playback. 615 @param stream 616 @retval CUBEB_OK 617 @retval CUBEB_ERROR */ 618 CUBEB_EXPORT int 619 cubeb_stream_start(cubeb_stream * stream); 620 621 /** Stop playback. 622 @param stream 623 @retval CUBEB_OK 624 @retval CUBEB_ERROR */ 625 CUBEB_EXPORT int 626 cubeb_stream_stop(cubeb_stream * stream); 627 628 /** Get the current stream playback position. 629 @param stream 630 @param position Playback position in frames. 631 @retval CUBEB_OK 632 @retval CUBEB_ERROR */ 633 CUBEB_EXPORT int 634 cubeb_stream_get_position(cubeb_stream * stream, uint64_t * position); 635 636 /** Get the latency for this stream, in frames. This is the number of frames 637 between the time cubeb acquires the data in the callback and the listener 638 can hear the sound. 639 @param stream 640 @param latency Current approximate stream latency in frames. 641 @retval CUBEB_OK 642 @retval CUBEB_ERROR_NOT_SUPPORTED 643 @retval CUBEB_ERROR */ 644 CUBEB_EXPORT int 645 cubeb_stream_get_latency(cubeb_stream * stream, uint32_t * latency); 646 647 /** Get the input latency for this stream, in frames. This is the number of 648 frames between the time the audio input devices records the data, and they 649 are available in the data callback. 650 This returns CUBEB_ERROR when the stream is output-only. 651 @param stream 652 @param latency Current approximate stream latency in frames. 653 @retval CUBEB_OK 654 @retval CUBEB_ERROR_NOT_SUPPORTED 655 @retval CUBEB_ERROR */ 656 CUBEB_EXPORT int 657 cubeb_stream_get_input_latency(cubeb_stream * stream, uint32_t * latency); 658 /** Set the volume for a stream. 659 @param stream the stream for which to adjust the volume. 660 @param volume a float between 0.0 (muted) and 1.0 (maximum volume) 661 @retval CUBEB_OK 662 @retval CUBEB_ERROR_INVALID_PARAMETER volume is outside [0.0, 1.0] or 663 stream is an invalid pointer 664 @retval CUBEB_ERROR_NOT_SUPPORTED */ 665 CUBEB_EXPORT int 666 cubeb_stream_set_volume(cubeb_stream * stream, float volume); 667 668 /** Change a stream's name. 669 @param stream the stream for which to set the name. 670 @param stream_name the new name for the stream 671 @retval CUBEB_OK 672 @retval CUBEB_ERROR_INVALID_PARAMETER if any pointer is invalid 673 @retval CUBEB_ERROR_NOT_SUPPORTED */ 674 CUBEB_EXPORT int 675 cubeb_stream_set_name(cubeb_stream * stream, char const * stream_name); 676 677 /** Get the current output device for this stream. 678 @param stm the stream for which to query the current output device 679 @param device a pointer in which the current output device will be stored. 680 @retval CUBEB_OK in case of success 681 @retval CUBEB_ERROR_INVALID_PARAMETER if either stm, device or count are 682 invalid pointers 683 @retval CUBEB_ERROR_NOT_SUPPORTED */ 684 CUBEB_EXPORT int 685 cubeb_stream_get_current_device(cubeb_stream * stm, 686 cubeb_device ** const device); 687 688 /** Set input mute state for this stream. Some platforms notify the user when an 689 application is accessing audio input. When all inputs are muted they can 690 prove to the user that the application is not actively capturing any input. 691 @param stream the stream for which to set input mute state 692 @param mute whether the input should mute or not 693 @retval CUBEB_OK 694 @retval CUBEB_ERROR_INVALID_PARAMETER if this stream does not have an input 695 device 696 @retval CUBEB_ERROR_NOT_SUPPORTED */ 697 CUBEB_EXPORT int 698 cubeb_stream_set_input_mute(cubeb_stream * stream, int mute); 699 700 /** Set what input processing features to enable for this stream. 701 @param stream the stream for which to set input processing features. 702 @param params what input processing features to use 703 @retval CUBEB_OK 704 @retval CUBEB_ERROR if params could not be applied 705 @retval CUBEB_ERROR_INVALID_PARAMETER if a given param is not supported by 706 this backend, or if this stream does not have an input device 707 @retval CUBEB_ERROR_NOT_SUPPORTED */ 708 CUBEB_EXPORT int 709 cubeb_stream_set_input_processing_params(cubeb_stream * stream, 710 cubeb_input_processing_params params); 711 712 /** Destroy a cubeb_device structure. 713 @param stream the stream passed in cubeb_stream_get_current_device 714 @param devices the devices to destroy 715 @retval CUBEB_OK in case of success 716 @retval CUBEB_ERROR_INVALID_PARAMETER if devices is an invalid pointer 717 @retval CUBEB_ERROR_NOT_SUPPORTED */ 718 CUBEB_EXPORT int 719 cubeb_stream_device_destroy(cubeb_stream * stream, cubeb_device * devices); 720 721 /** Set a callback to be notified when the output device changes. 722 @param stream the stream for which to set the callback. 723 @param device_changed_callback a function called whenever the device has 724 changed. Passing NULL allow to unregister a function 725 @retval CUBEB_OK 726 @retval CUBEB_ERROR_INVALID_PARAMETER if either stream or 727 device_changed_callback are invalid pointers. 728 @retval CUBEB_ERROR_NOT_SUPPORTED */ 729 CUBEB_EXPORT int 730 cubeb_stream_register_device_changed_callback( 731 cubeb_stream * stream, 732 cubeb_device_changed_callback device_changed_callback); 733 734 /** Return the user data pointer registered with the stream with 735 cubeb_stream_init. 736 @param stream the stream for which to retrieve user data pointer. 737 @retval user data pointer */ 738 CUBEB_EXPORT void * 739 cubeb_stream_user_ptr(cubeb_stream * stream); 740 741 /** Returns enumerated devices. 742 @param context 743 @param devtype device type to include 744 @param collection output collection. Must be destroyed with 745 cubeb_device_collection_destroy 746 @retval CUBEB_OK in case of success 747 @retval CUBEB_ERROR_INVALID_PARAMETER if collection is an invalid pointer 748 @retval CUBEB_ERROR_NOT_SUPPORTED */ 749 CUBEB_EXPORT int 750 cubeb_enumerate_devices(cubeb * context, cubeb_device_type devtype, 751 cubeb_device_collection * collection); 752 753 /** Destroy a cubeb_device_collection, and its `cubeb_device_info`. 754 @param context 755 @param collection collection to destroy 756 @retval CUBEB_OK 757 @retval CUBEB_ERROR_INVALID_PARAMETER if collection is an invalid pointer */ 758 CUBEB_EXPORT int 759 cubeb_device_collection_destroy(cubeb * context, 760 cubeb_device_collection * collection); 761 762 /** Registers a callback which is called when the system detects 763 a new device or a device is removed, or when the default device 764 changes for the specified device type. 765 @param context 766 @param devtype device type to include. Different callbacks and user pointers 767 can be registered for each devtype. The hybrid devtype 768 `CUBEB_DEVICE_TYPE_INPUT | CUBEB_DEVICE_TYPE_OUTPUT` is also valid 769 and will register the provided callback and user pointer in both 770 sides. 771 @param callback a function called whenever the system device list changes, 772 including when default devices change. 773 Passing NULL allow to unregister a function. You have to unregister 774 first before you register a new callback. 775 @param user_ptr pointer to user specified data which will be present in 776 subsequent callbacks. 777 @retval CUBEB_ERROR_NOT_SUPPORTED */ 778 CUBEB_EXPORT int 779 cubeb_register_device_collection_changed( 780 cubeb * context, cubeb_device_type devtype, 781 cubeb_device_collection_changed_callback callback, void * user_ptr); 782 783 /** Set a callback to be called with a message. 784 @param log_level CUBEB_LOG_VERBOSE, CUBEB_LOG_NORMAL. 785 @param log_callback A function called with a message when there is 786 something to log. Pass NULL to unregister. 787 @retval CUBEB_OK in case of success. 788 @retval CUBEB_ERROR_INVALID_PARAMETER if either context or log_callback are 789 invalid pointers, or if level is not 790 in cubeb_log_level. */ 791 CUBEB_EXPORT int 792 cubeb_set_log_callback(cubeb_log_level log_level, 793 cubeb_log_callback log_callback); 794 795 #if defined(__cplusplus) 796 } 797 #endif 798 799 #endif /* CUBEB_c2f983e9_c96f_e71c_72c3_bbf62992a382 */