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 <stdint.h> 11 #include <stdlib.h> 12 #include "cubeb_export.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"); 35 int rv; 36 uint32_t rate; 37 uint32_t latency_frames; 38 uint64_t ts; 39 40 rv = cubeb_get_min_latency(app_ctx, &output_params, &latency_frames); 41 if (rv != CUBEB_OK) { 42 fprintf(stderr, "Could not get minimum latency"); 43 return rv; 44 } 45 46 rv = cubeb_get_preferred_sample_rate(app_ctx, output_params, &rate); 47 if (rv != CUBEB_OK) { 48 fprintf(stderr, "Could not get preferred sample-rate"); 49 return rv; 50 } 51 52 cubeb_stream_params output_params; 53 output_params.format = CUBEB_SAMPLE_FLOAT32NE; 54 output_params.rate = rate; 55 output_params.channels = 2; 56 output_params.prefs = CUBEB_STREAM_PREF_NONE; 57 58 cubeb_stream_params input_params; 59 input_params.format = CUBEB_SAMPLE_FLOAT32NE; 60 input_params.rate = rate; 61 input_params.channels = 1; 62 input_params.prefs = CUBEB_STREAM_PREF_NONE; 63 64 cubeb_stream * stm; 65 rv = cubeb_stream_init(app_ctx, &stm, "Example Stream 1", 66 NULL, &input_params, 67 NULL, &output_params, 68 latency_frames, 69 data_cb, state_cb, 70 NULL); 71 if (rv != CUBEB_OK) { 72 fprintf(stderr, "Could not open the stream"); 73 return rv; 74 } 75 76 rv = cubeb_stream_start(stm); 77 if (rv != CUBEB_OK) { 78 fprintf(stderr, "Could not start the stream"); 79 return rv; 80 } 81 for (;;) { 82 cubeb_stream_get_position(stm, &ts); 83 printf("time=%llu\n", ts); 84 sleep(1); 85 } 86 rv = cubeb_stream_stop(stm); 87 if (rv != CUBEB_OK) { 88 fprintf(stderr, "Could not stop the stream"); 89 return rv; 90 } 91 92 cubeb_stream_destroy(stm); 93 cubeb_destroy(app_ctx); 94 @endcode 95 96 @code 97 long data_cb(cubeb_stream * stm, void * user, 98 void * input_buffer, void * output_buffer, long nframes) 99 { 100 float * in = input_buffer; 101 float * out = output_buffer; 102 103 for (i = 0; i < nframes; ++i) { 104 for (c = 0; c < 2; ++c) { 105 buf[i][c] = in[i]; 106 } 107 } 108 return nframes; 109 } 110 @endcode 111 112 @code 113 void state_cb(cubeb_stream * stm, void * user, cubeb_state state) 114 { 115 printf("state=%d\n", state); 116 } 117 @endcode 118 */ 119 120 /** @file 121 The <tt>libcubeb</tt> C API. */ 122 123 typedef struct cubeb cubeb; /**< Opaque handle referencing the application state. */ 124 typedef struct cubeb_stream cubeb_stream; /**< Opaque handle referencing the stream state. */ 125 126 /** Sample format enumeration. */ 127 typedef enum { 128 /**< Little endian 16-bit signed PCM. */ 129 CUBEB_SAMPLE_S16LE, 130 /**< Big endian 16-bit signed PCM. */ 131 CUBEB_SAMPLE_S16BE, 132 /**< Little endian 32-bit IEEE floating point PCM. */ 133 CUBEB_SAMPLE_FLOAT32LE, 134 /**< Big endian 32-bit IEEE floating point PCM. */ 135 CUBEB_SAMPLE_FLOAT32BE, 136 #if defined(WORDS_BIGENDIAN) || defined(__BIG_ENDIAN__) 137 /**< Native endian 16-bit signed PCM. */ 138 CUBEB_SAMPLE_S16NE = CUBEB_SAMPLE_S16BE, 139 /**< Native endian 32-bit IEEE floating point PCM. */ 140 CUBEB_SAMPLE_FLOAT32NE = CUBEB_SAMPLE_FLOAT32BE 141 #else 142 /**< Native endian 16-bit signed PCM. */ 143 CUBEB_SAMPLE_S16NE = CUBEB_SAMPLE_S16LE, 144 /**< Native endian 32-bit IEEE floating point PCM. */ 145 CUBEB_SAMPLE_FLOAT32NE = CUBEB_SAMPLE_FLOAT32LE 146 #endif 147 } cubeb_sample_format; 148 149 /** An opaque handle used to refer a particular input or output device 150 * across calls. */ 151 typedef void const * cubeb_devid; 152 153 /** Level (verbosity) of logging for a particular cubeb context. */ 154 typedef enum { 155 CUBEB_LOG_DISABLED = 0, /** < Logging disabled */ 156 CUBEB_LOG_NORMAL = 1, /**< Logging lifetime operation (creation/destruction). */ 157 CUBEB_LOG_VERBOSE = 2, /**< Verbose logging of callbacks, can have performance implications. */ 158 } cubeb_log_level; 159 160 /** SMPTE channel layout (also known as wave order) 161 * DUAL-MONO L R 162 * DUAL-MONO-LFE L R LFE 163 * MONO M 164 * MONO-LFE M LFE 165 * STEREO L R 166 * STEREO-LFE L R LFE 167 * 3F L R C 168 * 3F-LFE L R C LFE 169 * 2F1 L R RC 170 * 2F1-LFE L R LFE RC 171 * 3F1 L R C RC 172 * 3F1-LFE L R C LFE RC 173 * 2F2 L R LS RS 174 * 2F2-LFE L R LFE LS RS 175 * 3F2 L R C LS RS 176 * 3F2-LFE L R C LFE LS RS 177 * 3F3R-LFE L R C LFE RC LS RS 178 * 3F4-LFE L R C LFE RLS RRS LS RS 179 * 180 * The abbreviation of channel name is defined in following table: 181 * Abbr Channel name 182 * --------------------------- 183 * M Mono 184 * L Left 185 * R Right 186 * C Center 187 * LS Left Surround 188 * RS Right Surround 189 * RLS Rear Left Surround 190 * RC Rear Center 191 * RRS Rear Right Surround 192 * LFE Low Frequency Effects 193 */ 194 195 typedef enum { 196 CUBEB_LAYOUT_UNDEFINED, // Indicate the speaker's layout is undefined. 197 CUBEB_LAYOUT_DUAL_MONO, 198 CUBEB_LAYOUT_DUAL_MONO_LFE, 199 CUBEB_LAYOUT_MONO, 200 CUBEB_LAYOUT_MONO_LFE, 201 CUBEB_LAYOUT_STEREO, 202 CUBEB_LAYOUT_STEREO_LFE, 203 CUBEB_LAYOUT_3F, 204 CUBEB_LAYOUT_3F_LFE, 205 CUBEB_LAYOUT_2F1, 206 CUBEB_LAYOUT_2F1_LFE, 207 CUBEB_LAYOUT_3F1, 208 CUBEB_LAYOUT_3F1_LFE, 209 CUBEB_LAYOUT_2F2, 210 CUBEB_LAYOUT_2F2_LFE, 211 CUBEB_LAYOUT_3F2, 212 CUBEB_LAYOUT_3F2_LFE, 213 CUBEB_LAYOUT_3F3R_LFE, 214 CUBEB_LAYOUT_3F4_LFE, 215 CUBEB_LAYOUT_MAX 216 } cubeb_channel_layout; 217 218 /** Miscellaneous stream preferences. */ 219 typedef enum { 220 CUBEB_STREAM_PREF_NONE = 0x00, /**< No stream preferences are requested. */ 221 CUBEB_STREAM_PREF_LOOPBACK = 0x01 /**< Request a loopback stream. Should be 222 specified on the input params and an 223 output device to loopback from should 224 be passed in place of an input device. */ 225 } cubeb_stream_prefs; 226 227 /** Stream format initialization parameters. */ 228 typedef struct { 229 cubeb_sample_format format; /**< Requested sample format. One of 230 #cubeb_sample_format. */ 231 uint32_t rate; /**< Requested sample rate. Valid range is [1000, 192000]. */ 232 uint32_t channels; /**< Requested channel count. Valid range is [1, 8]. */ 233 cubeb_channel_layout layout; /**< Requested channel layout. This must be consistent with the provided channels. */ 234 cubeb_stream_prefs prefs; /**< Requested preferences. */ 235 } cubeb_stream_params; 236 237 /** Audio device description */ 238 typedef struct { 239 char * output_name; /**< The name of the output device */ 240 char * input_name; /**< The name of the input device */ 241 } cubeb_device; 242 243 /** Stream states signaled via state_callback. */ 244 typedef enum { 245 CUBEB_STATE_STARTED, /**< Stream started. */ 246 CUBEB_STATE_STOPPED, /**< Stream stopped. */ 247 CUBEB_STATE_DRAINED, /**< Stream drained. */ 248 CUBEB_STATE_ERROR /**< Stream disabled due to error. */ 249 } cubeb_state; 250 251 /** Result code enumeration. */ 252 enum { 253 CUBEB_OK = 0, /**< Success. */ 254 CUBEB_ERROR = -1, /**< Unclassified error. */ 255 CUBEB_ERROR_INVALID_FORMAT = -2, /**< Unsupported #cubeb_stream_params requested. */ 256 CUBEB_ERROR_INVALID_PARAMETER = -3, /**< Invalid parameter specified. */ 257 CUBEB_ERROR_NOT_SUPPORTED = -4, /**< Optional function not implemented in current backend. */ 258 CUBEB_ERROR_DEVICE_UNAVAILABLE = -5 /**< Device specified by #cubeb_devid not available. */ 259 }; 260 261 /** 262 * Whether a particular device is an input device (e.g. a microphone), or an 263 * output device (e.g. headphones). */ 264 typedef enum { 265 CUBEB_DEVICE_TYPE_UNKNOWN, 266 CUBEB_DEVICE_TYPE_INPUT, 267 CUBEB_DEVICE_TYPE_OUTPUT 268 } cubeb_device_type; 269 270 /** 271 * The state of a device. 272 */ 273 typedef enum { 274 CUBEB_DEVICE_STATE_DISABLED, /**< The device has been disabled at the system level. */ 275 CUBEB_DEVICE_STATE_UNPLUGGED, /**< The device is enabled, but nothing is plugged into it. */ 276 CUBEB_DEVICE_STATE_ENABLED /**< The device is enabled. */ 277 } cubeb_device_state; 278 279 /** 280 * Architecture specific sample type. 281 */ 282 typedef enum { 283 CUBEB_DEVICE_FMT_S16LE = 0x0010, /**< 16-bit integers, Little Endian. */ 284 CUBEB_DEVICE_FMT_S16BE = 0x0020, /**< 16-bit integers, Big Endian. */ 285 CUBEB_DEVICE_FMT_F32LE = 0x1000, /**< 32-bit floating point, Little Endian. */ 286 CUBEB_DEVICE_FMT_F32BE = 0x2000 /**< 32-bit floating point, Big Endian. */ 287 } cubeb_device_fmt; 288 289 #if defined(WORDS_BIGENDIAN) || defined(__BIG_ENDIAN__) 290 /** 16-bit integers, native endianess, when on a Big Endian environment. */ 291 #define CUBEB_DEVICE_FMT_S16NE CUBEB_DEVICE_FMT_S16BE 292 /** 32-bit floating points, native endianess, when on a Big Endian environment. */ 293 #define CUBEB_DEVICE_FMT_F32NE CUBEB_DEVICE_FMT_F32BE 294 #else 295 /** 16-bit integers, native endianess, when on a Little Endian environment. */ 296 #define CUBEB_DEVICE_FMT_S16NE CUBEB_DEVICE_FMT_S16LE 297 /** 32-bit floating points, native endianess, when on a Little Endian 298 * environment. */ 299 #define CUBEB_DEVICE_FMT_F32NE CUBEB_DEVICE_FMT_F32LE 300 #endif 301 /** All the 16-bit integers types. */ 302 #define CUBEB_DEVICE_FMT_S16_MASK (CUBEB_DEVICE_FMT_S16LE | CUBEB_DEVICE_FMT_S16BE) 303 /** All the 32-bit floating points types. */ 304 #define CUBEB_DEVICE_FMT_F32_MASK (CUBEB_DEVICE_FMT_F32LE | CUBEB_DEVICE_FMT_F32BE) 305 /** All the device formats types. */ 306 #define CUBEB_DEVICE_FMT_ALL (CUBEB_DEVICE_FMT_S16_MASK | CUBEB_DEVICE_FMT_F32_MASK) 307 308 /** Channel type for a `cubeb_stream`. Depending on the backend and platform 309 * used, this can control inter-stream interruption, ducking, and volume 310 * control. 311 */ 312 typedef enum { 313 CUBEB_DEVICE_PREF_NONE = 0x00, 314 CUBEB_DEVICE_PREF_MULTIMEDIA = 0x01, 315 CUBEB_DEVICE_PREF_VOICE = 0x02, 316 CUBEB_DEVICE_PREF_NOTIFICATION = 0x04, 317 CUBEB_DEVICE_PREF_ALL = 0x0F 318 } cubeb_device_pref; 319 320 /** This structure holds the characteristics 321 * of an input or output audio device. It is obtained using 322 * `cubeb_enumerate_devices`, which returns these structures via 323 * `cubeb_device_collection` and must be destroyed via 324 * `cubeb_device_collection_destroy`. */ 325 typedef struct { 326 cubeb_devid devid; /**< Device identifier handle. */ 327 char const * device_id; /**< Device identifier which might be presented in a UI. */ 328 char const * friendly_name; /**< Friendly device name which might be presented in a UI. */ 329 char const * group_id; /**< Two devices have the same group identifier if they belong to the same physical device; for example a headset and microphone. */ 330 char const * vendor_name; /**< Optional vendor name, may be NULL. */ 331 332 cubeb_device_type type; /**< Type of device (Input/Output). */ 333 cubeb_device_state state; /**< State of device disabled/enabled/unplugged. */ 334 cubeb_device_pref preferred;/**< Preferred device. */ 335 336 cubeb_device_fmt format; /**< Sample format supported. */ 337 cubeb_device_fmt default_format; /**< The default sample format for this device. */ 338 uint32_t max_channels; /**< Channels. */ 339 uint32_t default_rate; /**< Default/Preferred sample rate. */ 340 uint32_t max_rate; /**< Maximum sample rate supported. */ 341 uint32_t min_rate; /**< Minimum sample rate supported. */ 342 343 uint32_t latency_lo; /**< Lowest possible latency in frames. */ 344 uint32_t latency_hi; /**< Higest possible latency in frames. */ 345 } cubeb_device_info; 346 347 /** Device collection. 348 * Returned by `cubeb_enumerate_devices` and destroyed by 349 * `cubeb_device_collection_destroy`. */ 350 typedef struct { 351 cubeb_device_info * device; /**< Array of pointers to device info. */ 352 size_t count; /**< Device count in collection. */ 353 } cubeb_device_collection; 354 355 /** User supplied data callback. 356 - Calling other cubeb functions from this callback is unsafe. 357 - The code in the callback should be non-blocking. 358 - Returning less than the number of frames this callback asks for or 359 provides puts the stream in drain mode. This callback will not be called 360 again, and the state callback will be called with CUBEB_STATE_DRAINED when 361 all the frames have been output. 362 @param stream The stream for which this callback fired. 363 @param user_ptr The pointer passed to cubeb_stream_init. 364 @param input_buffer A pointer containing the input data, or nullptr 365 if this is an output-only stream. 366 @param output_buffer A pointer to a buffer to be filled with audio samples, 367 or nullptr if this is an input-only stream. 368 @param nframes The number of frames of the two buffer. 369 @retval Number of frames written to the output buffer. If this number is 370 less than nframes, then the stream will start to drain. 371 @retval CUBEB_ERROR on error, in which case the data callback will stop 372 and the stream will enter a shutdown state. */ 373 typedef long (* cubeb_data_callback)(cubeb_stream * stream, 374 void * user_ptr, 375 void const * input_buffer, 376 void * output_buffer, 377 long nframes); 378 379 /** User supplied state callback. 380 @param stream The stream for this this callback fired. 381 @param user_ptr The pointer passed to cubeb_stream_init. 382 @param state The new state of the stream. */ 383 typedef void (* cubeb_state_callback)(cubeb_stream * stream, 384 void * user_ptr, 385 cubeb_state state); 386 387 /** 388 * User supplied callback called when the underlying device changed. 389 * @param user The pointer passed to cubeb_stream_init. */ 390 typedef void (* cubeb_device_changed_callback)(void * user_ptr); 391 392 /** 393 * User supplied callback called when the underlying device collection changed. 394 * @param context A pointer to the cubeb context. 395 * @param user_ptr The pointer passed to cubeb_register_device_collection_changed. */ 396 typedef void (* cubeb_device_collection_changed_callback)(cubeb * context, 397 void * user_ptr); 398 399 /** User supplied callback called when a message needs logging. */ 400 typedef void (* cubeb_log_callback)(char const * fmt, ...); 401 402 /** Initialize an application context. This will perform any library or 403 application scoped initialization. 404 @param context A out param where an opaque pointer to the application 405 context will be returned. 406 @param context_name A name for the context. Depending on the platform this 407 can appear in different locations. 408 @param backend_name The name of the cubeb backend user desires to select. 409 Accepted values self-documented in cubeb.c: init_oneshot 410 If NULL, a default ordering is used for backend choice. 411 A valid choice overrides all other possible backends, 412 so long as the backend was included at compile time. 413 @retval CUBEB_OK in case of success. 414 @retval CUBEB_ERROR in case of error, for example because the host 415 has no audio hardware. */ 416 CUBEB_EXPORT int cubeb_init(cubeb ** context, char const * context_name, 417 char const * backend_name); 418 419 /** Get a read-only string identifying this context's current backend. 420 @param context A pointer to the cubeb context. 421 @retval Read-only string identifying current backend. */ 422 CUBEB_EXPORT char const * cubeb_get_backend_id(cubeb * context); 423 424 /** Get the maximum possible number of channels. 425 @param context A pointer to the cubeb context. 426 @param max_channels The maximum number of channels. 427 @retval CUBEB_OK 428 @retval CUBEB_ERROR_INVALID_PARAMETER 429 @retval CUBEB_ERROR_NOT_SUPPORTED 430 @retval CUBEB_ERROR */ 431 CUBEB_EXPORT int cubeb_get_max_channel_count(cubeb * context, uint32_t * max_channels); 432 433 /** Get the minimal latency value, in frames, that is guaranteed to work 434 when creating a stream for the specified sample rate. This is platform, 435 hardware and backend dependent. 436 @param context A pointer to the cubeb context. 437 @param params On some backends, the minimum achievable latency depends on 438 the characteristics of the stream. 439 @param latency_frames The latency value, in frames, to pass to 440 cubeb_stream_init. 441 @retval CUBEB_OK 442 @retval CUBEB_ERROR_INVALID_PARAMETER 443 @retval CUBEB_ERROR_NOT_SUPPORTED */ 444 CUBEB_EXPORT int cubeb_get_min_latency(cubeb * context, 445 cubeb_stream_params * params, 446 uint32_t * latency_frames); 447 448 /** Get the preferred sample rate for this backend: this is hardware and 449 platform dependent, and can avoid resampling, and/or trigger fastpaths. 450 @param context A pointer to the cubeb context. 451 @param rate The samplerate (in Hz) the current configuration prefers. 452 @retval CUBEB_OK 453 @retval CUBEB_ERROR_INVALID_PARAMETER 454 @retval CUBEB_ERROR_NOT_SUPPORTED */ 455 CUBEB_EXPORT int cubeb_get_preferred_sample_rate(cubeb * context, uint32_t * rate); 456 457 /** Get the preferred layout for this backend: this is hardware and 458 platform dependent. 459 @param context A pointer to the cubeb context. 460 @param layout The layout of the current speaker configuration. 461 @retval CUBEB_OK 462 @retval CUBEB_ERROR_INVALID_PARAMETER 463 @retval CUBEB_ERROR_NOT_SUPPORTED */ 464 CUBEB_EXPORT int cubeb_get_preferred_channel_layout(cubeb * context, cubeb_channel_layout * layout); 465 466 /** Destroy an application context. This must be called after all stream have 467 * been destroyed. 468 @param context A pointer to the cubeb context.*/ 469 CUBEB_EXPORT void cubeb_destroy(cubeb * context); 470 471 /** Initialize a stream associated with the supplied application context. 472 @param context A pointer to the cubeb context. 473 @param stream An out parameter to be filled with the an opaque pointer to a 474 cubeb stream. 475 @param stream_name A name for this stream. 476 @param input_device Device for the input side of the stream. If NULL the 477 default input device is used. 478 @param input_stream_params Parameters for the input side of the stream, or 479 NULL if this stream is output only. 480 @param output_device Device for the output side of the stream. If NULL the 481 default output device is used. 482 @param output_stream_params Parameters for the output side of the stream, or 483 NULL if this stream is input only. 484 @param latency_frames Stream latency in frames. Valid range 485 is [1, 96000]. 486 @param data_callback Will be called to preroll data before playback is 487 started by cubeb_stream_start. 488 @param state_callback A pointer to a state callback. 489 @param user_ptr A pointer that will be passed to the callbacks. This pointer 490 must outlive the life time of the stream. 491 @retval CUBEB_OK 492 @retval CUBEB_ERROR 493 @retval CUBEB_ERROR_INVALID_FORMAT 494 @retval CUBEB_ERROR_DEVICE_UNAVAILABLE */ 495 CUBEB_EXPORT int cubeb_stream_init(cubeb * context, 496 cubeb_stream ** stream, 497 char const * stream_name, 498 cubeb_devid input_device, 499 cubeb_stream_params * input_stream_params, 500 cubeb_devid output_device, 501 cubeb_stream_params * output_stream_params, 502 uint32_t latency_frames, 503 cubeb_data_callback data_callback, 504 cubeb_state_callback state_callback, 505 void * user_ptr); 506 507 /** Destroy a stream. `cubeb_stream_stop` MUST be called before destroying a 508 stream. 509 @param stream The stream to destroy. */ 510 CUBEB_EXPORT void cubeb_stream_destroy(cubeb_stream * stream); 511 512 /** Start playback. 513 @param stream 514 @retval CUBEB_OK 515 @retval CUBEB_ERROR */ 516 CUBEB_EXPORT int cubeb_stream_start(cubeb_stream * stream); 517 518 /** Stop playback. 519 @param stream 520 @retval CUBEB_OK 521 @retval CUBEB_ERROR */ 522 CUBEB_EXPORT int cubeb_stream_stop(cubeb_stream * stream); 523 524 /** Reset stream to the default device. 525 @param stream 526 @retval CUBEB_OK 527 @retval CUBEB_ERROR_INVALID_PARAMETER 528 @retval CUBEB_ERROR_NOT_SUPPORTED 529 @retval CUBEB_ERROR */ 530 CUBEB_EXPORT int cubeb_stream_reset_default_device(cubeb_stream * stream); 531 532 /** Get the current stream playback position. 533 @param stream 534 @param position Playback position in frames. 535 @retval CUBEB_OK 536 @retval CUBEB_ERROR */ 537 CUBEB_EXPORT int cubeb_stream_get_position(cubeb_stream * stream, uint64_t * position); 538 539 /** Get the latency for this stream, in frames. This is the number of frames 540 between the time cubeb acquires the data in the callback and the listener 541 can hear the sound. 542 @param stream 543 @param latency Current approximate stream latency in frames. 544 @retval CUBEB_OK 545 @retval CUBEB_ERROR_NOT_SUPPORTED 546 @retval CUBEB_ERROR */ 547 CUBEB_EXPORT int cubeb_stream_get_latency(cubeb_stream * stream, uint32_t * latency); 548 549 /** Set the volume for a stream. 550 @param stream the stream for which to adjust the volume. 551 @param volume a float between 0.0 (muted) and 1.0 (maximum volume) 552 @retval CUBEB_OK 553 @retval CUBEB_ERROR_INVALID_PARAMETER volume is outside [0.0, 1.0] or 554 stream is an invalid pointer 555 @retval CUBEB_ERROR_NOT_SUPPORTED */ 556 CUBEB_EXPORT int cubeb_stream_set_volume(cubeb_stream * stream, float volume); 557 558 /** If the stream is stereo, set the left/right panning. If the stream is mono, 559 this has no effect. 560 @param stream the stream for which to change the panning 561 @param panning a number from -1.0 to 1.0. -1.0 means that the stream is 562 fully mixed in the left channel, 1.0 means the stream is fully 563 mixed in the right channel. 0.0 is equal power in the right and 564 left channel (default). 565 @retval CUBEB_OK 566 @retval CUBEB_ERROR_INVALID_PARAMETER if stream is null or if panning is 567 outside the [-1.0, 1.0] range. 568 @retval CUBEB_ERROR_NOT_SUPPORTED 569 @retval CUBEB_ERROR stream is not mono nor stereo */ 570 CUBEB_EXPORT int cubeb_stream_set_panning(cubeb_stream * stream, float panning); 571 572 /** Get the current output device for this stream. 573 @param stm the stream for which to query the current output device 574 @param device a pointer in which the current output device will be stored. 575 @retval CUBEB_OK in case of success 576 @retval CUBEB_ERROR_INVALID_PARAMETER if either stm, device or count are 577 invalid pointers 578 @retval CUBEB_ERROR_NOT_SUPPORTED */ 579 CUBEB_EXPORT int cubeb_stream_get_current_device(cubeb_stream * stm, 580 cubeb_device ** const device); 581 582 /** Destroy a cubeb_device structure. 583 @param stream the stream passed in cubeb_stream_get_current_device 584 @param devices the devices to destroy 585 @retval CUBEB_OK in case of success 586 @retval CUBEB_ERROR_INVALID_PARAMETER if devices is an invalid pointer 587 @retval CUBEB_ERROR_NOT_SUPPORTED */ 588 CUBEB_EXPORT int cubeb_stream_device_destroy(cubeb_stream * stream, 589 cubeb_device * devices); 590 591 /** Set a callback to be notified when the output device changes. 592 @param stream the stream for which to set the callback. 593 @param device_changed_callback a function called whenever the device has 594 changed. Passing NULL allow to unregister a function 595 @retval CUBEB_OK 596 @retval CUBEB_ERROR_INVALID_PARAMETER if either stream or 597 device_changed_callback are invalid pointers. 598 @retval CUBEB_ERROR_NOT_SUPPORTED */ 599 CUBEB_EXPORT int cubeb_stream_register_device_changed_callback(cubeb_stream * stream, 600 cubeb_device_changed_callback device_changed_callback); 601 602 /** Return the user data pointer registered with the stream with cubeb_stream_init. 603 @param stream the stream for which to retrieve user data pointer. 604 @retval user data pointer */ 605 CUBEB_EXPORT void * cubeb_stream_user_ptr(cubeb_stream * stream); 606 607 /** Returns enumerated devices. 608 @param context 609 @param devtype device type to include 610 @param collection output collection. Must be destroyed with cubeb_device_collection_destroy 611 @retval CUBEB_OK in case of success 612 @retval CUBEB_ERROR_INVALID_PARAMETER if collection is an invalid pointer 613 @retval CUBEB_ERROR_NOT_SUPPORTED */ 614 CUBEB_EXPORT int cubeb_enumerate_devices(cubeb * context, 615 cubeb_device_type devtype, 616 cubeb_device_collection * collection); 617 618 /** Destroy a cubeb_device_collection, and its `cubeb_device_info`. 619 @param context 620 @param collection collection to destroy 621 @retval CUBEB_OK 622 @retval CUBEB_ERROR_INVALID_PARAMETER if collection is an invalid pointer */ 623 CUBEB_EXPORT int cubeb_device_collection_destroy(cubeb * context, 624 cubeb_device_collection * collection); 625 626 /** Registers a callback which is called when the system detects 627 a new device or a device is removed. 628 @param context 629 @param devtype device type to include 630 @param callback a function called whenever the system device list changes. 631 Passing NULL allow to unregister a function 632 @param user_ptr pointer to user specified data which will be present in 633 subsequent callbacks. 634 @retval CUBEB_ERROR_NOT_SUPPORTED */ 635 CUBEB_EXPORT int cubeb_register_device_collection_changed(cubeb * context, 636 cubeb_device_type devtype, 637 cubeb_device_collection_changed_callback callback, 638 void * user_ptr); 639 640 /** Set a callback to be called with a message. 641 @param log_level CUBEB_LOG_VERBOSE, CUBEB_LOG_NORMAL. 642 @param log_callback A function called with a message when there is 643 something to log. Pass NULL to unregister. 644 @retval CUBEB_OK in case of success. 645 @retval CUBEB_ERROR_INVALID_PARAMETER if either context or log_callback are 646 invalid pointers, or if level is not 647 in cubeb_log_level. */ 648 CUBEB_EXPORT int cubeb_set_log_callback(cubeb_log_level log_level, 649 cubeb_log_callback log_callback); 650 651 #if defined(__cplusplus) 652 } 653 #endif 654 655 #endif /* CUBEB_c2f983e9_c96f_e71c_72c3_bbf62992a382 */ 656