AAudio.h revision 5fbc2ddb4e340d7af02d146ff2e7c3c4da28d535
1/* 2 * Copyright (C) 2016 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17/** 18 * @addtogroup Audio 19 * @{ 20 */ 21 22/** 23 * @file AAudio.h 24 */ 25 26/** 27 * This is the 'C' API for AAudio. 28 */ 29#ifndef AAUDIO_AAUDIO_H 30#define AAUDIO_AAUDIO_H 31 32#include <time.h> 33 34#ifdef __cplusplus 35extern "C" { 36#endif 37 38/** 39 * This is used to represent a value that has not been specified. 40 * For example, an application could use AAUDIO_UNSPECIFIED to indicate 41 * that is did not not care what the specific value of a parameter was 42 * and would accept whatever it was given. 43 */ 44#define AAUDIO_UNSPECIFIED 0 45#define AAUDIO_DEVICE_UNSPECIFIED 0 46 47enum { 48 AAUDIO_DIRECTION_OUTPUT, 49 AAUDIO_DIRECTION_INPUT 50}; 51typedef int32_t aaudio_direction_t; 52 53enum { 54 AAUDIO_FORMAT_INVALID = -1, 55 AAUDIO_FORMAT_UNSPECIFIED = 0, 56 AAUDIO_FORMAT_PCM_I16, 57 AAUDIO_FORMAT_PCM_FLOAT, 58 AAUDIO_FORMAT_PCM_I8_24, 59 AAUDIO_FORMAT_PCM_I32 60}; 61typedef int32_t aaudio_format_t; 62 63/** 64 * @deprecated use aaudio_format_t instead 65 * TODO remove when tests and examples are updated 66 */ 67typedef int32_t aaudio_audio_format_t; 68 69enum { 70 AAUDIO_OK, 71 AAUDIO_ERROR_BASE = -900, // TODO review 72 AAUDIO_ERROR_DISCONNECTED, 73 AAUDIO_ERROR_ILLEGAL_ARGUMENT, 74 AAUDIO_ERROR_INCOMPATIBLE, 75 AAUDIO_ERROR_INTERNAL, // an underlying API returned an error code 76 AAUDIO_ERROR_INVALID_STATE, 77 AAUDIO_ERROR_UNEXPECTED_STATE, 78 AAUDIO_ERROR_UNEXPECTED_VALUE, 79 AAUDIO_ERROR_INVALID_HANDLE, 80 AAUDIO_ERROR_INVALID_QUERY, 81 AAUDIO_ERROR_UNIMPLEMENTED, 82 AAUDIO_ERROR_UNAVAILABLE, 83 AAUDIO_ERROR_NO_FREE_HANDLES, 84 AAUDIO_ERROR_NO_MEMORY, 85 AAUDIO_ERROR_NULL, 86 AAUDIO_ERROR_TIMEOUT, 87 AAUDIO_ERROR_WOULD_BLOCK, 88 AAUDIO_ERROR_INVALID_FORMAT, 89 AAUDIO_ERROR_OUT_OF_RANGE, 90 AAUDIO_ERROR_NO_SERVICE, 91 AAUDIO_ERROR_INVALID_RATE 92}; 93typedef int32_t aaudio_result_t; 94 95enum 96{ 97 AAUDIO_STREAM_STATE_UNINITIALIZED = 0, 98 AAUDIO_STREAM_STATE_UNKNOWN, 99 AAUDIO_STREAM_STATE_OPEN, 100 AAUDIO_STREAM_STATE_STARTING, 101 AAUDIO_STREAM_STATE_STARTED, 102 AAUDIO_STREAM_STATE_PAUSING, 103 AAUDIO_STREAM_STATE_PAUSED, 104 AAUDIO_STREAM_STATE_FLUSHING, 105 AAUDIO_STREAM_STATE_FLUSHED, 106 AAUDIO_STREAM_STATE_STOPPING, 107 AAUDIO_STREAM_STATE_STOPPED, 108 AAUDIO_STREAM_STATE_CLOSING, 109 AAUDIO_STREAM_STATE_CLOSED, 110 AAUDIO_STREAM_STATE_DISCONNECTED 111}; 112typedef int32_t aaudio_stream_state_t; 113 114 115enum { 116 /** 117 * This will be the only stream using a particular source or sink. 118 * This mode will provide the lowest possible latency. 119 * You should close EXCLUSIVE streams immediately when you are not using them. 120 */ 121 AAUDIO_SHARING_MODE_EXCLUSIVE, 122 /** 123 * Multiple applications will be mixed by the AAudio Server. 124 * This will have higher latency than the EXCLUSIVE mode. 125 */ 126 AAUDIO_SHARING_MODE_SHARED 127}; 128typedef int32_t aaudio_sharing_mode_t; 129 130typedef struct AAudioStreamStruct AAudioStream; 131typedef struct AAudioStreamBuilderStruct AAudioStreamBuilder; 132 133#ifndef AAUDIO_API 134#define AAUDIO_API /* export this symbol */ 135#endif 136 137// ============================================================ 138// Audio System 139// ============================================================ 140 141/** 142 * The text is the ASCII symbol corresponding to the returnCode, 143 * or an English message saying the returnCode is unrecognized. 144 * This is intended for developers to use when debugging. 145 * It is not for display to users. 146 * 147 * @return pointer to a text representation of an AAudio result code. 148 */ 149AAUDIO_API const char * AAudio_convertResultToText(aaudio_result_t returnCode); 150 151/** 152 * The text is the ASCII symbol corresponding to the stream state, 153 * or an English message saying the state is unrecognized. 154 * This is intended for developers to use when debugging. 155 * It is not for display to users. 156 * 157 * @return pointer to a text representation of an AAudio state. 158 */ 159AAUDIO_API const char * AAudio_convertStreamStateToText(aaudio_stream_state_t state); 160 161// ============================================================ 162// StreamBuilder 163// ============================================================ 164 165/** 166 * Create a StreamBuilder that can be used to open a Stream. 167 * 168 * The deviceId is initially unspecified, meaning that the current default device will be used. 169 * 170 * The default direction is AAUDIO_DIRECTION_OUTPUT. 171 * The default sharing mode is AAUDIO_SHARING_MODE_SHARED. 172 * The data format, samplesPerFrames and sampleRate are unspecified and will be 173 * chosen by the device when it is opened. 174 * 175 * AAudioStreamBuilder_delete() must be called when you are done using the builder. 176 */ 177AAUDIO_API aaudio_result_t AAudio_createStreamBuilder(AAudioStreamBuilder** builder); 178 179/** 180 * Request an audio device identified device using an ID. 181 * On Android, for example, the ID could be obtained from the Java AudioManager. 182 * 183 * The default, if you do not call this function, is AAUDIO_DEVICE_UNSPECIFIED, 184 * in which case the primary device will be used. 185 * 186 * @param builder reference provided by AAudio_createStreamBuilder() 187 * @param deviceId device identifier or AAUDIO_DEVICE_UNSPECIFIED 188 */ 189AAUDIO_API void AAudioStreamBuilder_setDeviceId(AAudioStreamBuilder* builder, 190 int32_t deviceId); 191 192/** 193 * Request a sample rate in Hertz. 194 * 195 * The stream may be opened with a different sample rate. 196 * So the application should query for the actual rate after the stream is opened. 197 * 198 * Technically, this should be called the "frame rate" or "frames per second", 199 * because it refers to the number of complete frames transferred per second. 200 * But it is traditionally called "sample rate". So we use that term. 201 * 202 * The default, if you do not call this function, is AAUDIO_UNSPECIFIED. 203 * 204 * @param builder reference provided by AAudio_createStreamBuilder() 205 * @param sampleRate frames per second. Common rates include 44100 and 48000 Hz. 206 */ 207AAUDIO_API void AAudioStreamBuilder_setSampleRate(AAudioStreamBuilder* builder, 208 int32_t sampleRate); 209 210/** 211 * Request a number of samples per frame. 212 * 213 * The stream may be opened with a different value. 214 * So the application should query for the actual value after the stream is opened. 215 * 216 * The default, if you do not call this function, is AAUDIO_UNSPECIFIED. 217 * 218 * Note, this quantity is sometimes referred to as "channel count". 219 * 220 * @param builder reference provided by AAudio_createStreamBuilder() 221 * @param samplesPerFrame Number of samples in one frame, ie. numChannels. 222 */ 223AAUDIO_API void AAudioStreamBuilder_setSamplesPerFrame(AAudioStreamBuilder* builder, 224 int32_t samplesPerFrame); 225 226/** 227 * Request a sample data format, for example AAUDIO_FORMAT_PCM_I16. 228 * 229 * The default, if you do not call this function, is AAUDIO_UNSPECIFIED. 230 * 231 * The stream may be opened with a different value. 232 * So the application should query for the actual value after the stream is opened. 233 * 234 * @param builder reference provided by AAudio_createStreamBuilder() 235 * @param format Most common formats are AAUDIO_FORMAT_PCM_FLOAT and AAUDIO_FORMAT_PCM_I16. 236 */ 237AAUDIO_API void AAudioStreamBuilder_setFormat(AAudioStreamBuilder* builder, 238 aaudio_audio_format_t format); 239 240/** 241 * Request a mode for sharing the device. 242 * 243 * The default, if you do not call this function, is AAUDIO_SHARING_MODE_SHARED. 244 * 245 * The requested sharing mode may not be available. 246 * The application can query for the actual mode after the stream is opened. 247 * 248 * @param builder reference provided by AAudio_createStreamBuilder() 249 * @param sharingMode AAUDIO_SHARING_MODE_SHARED or AAUDIO_SHARING_MODE_EXCLUSIVE 250 */ 251AAUDIO_API void AAudioStreamBuilder_setSharingMode(AAudioStreamBuilder* builder, 252 aaudio_sharing_mode_t sharingMode); 253 254/** 255 * Request the direction for a stream. 256 * 257 * The default, if you do not call this function, is AAUDIO_DIRECTION_OUTPUT. 258 * 259 * @param builder reference provided by AAudio_createStreamBuilder() 260 * @param direction AAUDIO_DIRECTION_OUTPUT or AAUDIO_DIRECTION_INPUT 261 */ 262AAUDIO_API void AAudioStreamBuilder_setDirection(AAudioStreamBuilder* builder, 263 aaudio_direction_t direction); 264 265/** 266 * Set the requested buffer capacity in frames. 267 * The final AAudioStream capacity may differ, but will probably be at least this big. 268 * 269 * The default, if you do not call this function, is AAUDIO_UNSPECIFIED. 270 * 271 * @param builder reference provided by AAudio_createStreamBuilder() 272 * @param numFrames the desired buffer capacity in frames or AAUDIO_UNSPECIFIED 273 */ 274AAUDIO_API void AAudioStreamBuilder_setBufferCapacityInFrames(AAudioStreamBuilder* builder, 275 int32_t numFrames); 276/** 277 * Return one of these values from the data callback function. 278 */ 279enum { 280 281 /** 282 * Continue calling the callback. 283 */ 284 AAUDIO_CALLBACK_RESULT_CONTINUE = 0, 285 286 /** 287 * Stop calling the callback. 288 * 289 * The application will still need to call AAudioStream_requestPause() 290 * or AAudioStream_requestStop(). 291 */ 292 AAUDIO_CALLBACK_RESULT_STOP, 293 294}; 295typedef int32_t aaudio_data_callback_result_t; 296 297/** 298 * Prototype for the data function that is passed to AAudioStreamBuilder_setDataCallback(). 299 * 300 * For an output stream, this function should render and write numFrames of data 301 * in the streams current data format to the audioData buffer. 302 * 303 * For an input stream, this function should read and process numFrames of data 304 * from the audioData buffer. 305 * 306 * Note that this callback function should be considered a "real-time" function. 307 * It must not do anything that could cause an unbounded delay because that can cause the 308 * audio to glitch or pop. 309 * 310 * These are things the function should NOT do: 311 * <ul> 312 * <li>allocate memory using, for example, malloc() or new</li> 313 * <li>any file operations such as opening, closing, reading or writing</li> 314 * <li>any network operations such as streaming</li> 315 * <li>use any mutexes or other synchronization primitives</li> 316 * <li>sleep</li> 317 * </ul> 318 * 319 * If you need to move data, eg. MIDI commands, in or out of the callback function then 320 * we recommend the use of non-blocking techniques such as an atomic FIFO. 321 * 322 * @param stream reference provided by AAudioStreamBuilder_openStream() 323 * @param userData the same address that was passed to AAudioStreamBuilder_setCallback() 324 * @param audioData a pointer to the audio data 325 * @param numFrames the number of frames to be processed 326 * @return AAUDIO_CALLBACK_RESULT_* 327 */ 328typedef aaudio_data_callback_result_t (*AAudioStream_dataCallback)( 329 AAudioStream *stream, 330 void *userData, 331 void *audioData, 332 int32_t numFrames); 333 334/** 335 * Request that AAudio call this functions when the stream is running. 336 * 337 * Note that when using this callback, the audio data will be passed in or out 338 * of the function as an argument. 339 * So you cannot call AAudioStream_write() or AAudioStream_read() on the same stream 340 * that has an active data callback. 341 * 342 * The callback function will start being called after AAudioStream_requestStart() is called. 343 * It will stop being called after AAudioStream_requestPause() or 344 * AAudioStream_requestStop() is called. 345 * 346 * This callback function will be called on a real-time thread owned by AAudio. See 347 * {@link AAudioStream_dataCallback} for more information. 348 * 349 * Note that the AAudio callbacks will never be called simultaneously from multiple threads. 350 * 351 * @param builder reference provided by AAudio_createStreamBuilder() 352 * @param callback pointer to a function that will process audio data. 353 * @param userData pointer to an application data structure that will be passed 354 * to the callback functions. 355 */ 356AAUDIO_API void AAudioStreamBuilder_setDataCallback(AAudioStreamBuilder* builder, 357 AAudioStream_dataCallback callback, 358 void *userData); 359 360/** 361 * Set the requested data callback buffer size in frames. 362 * See {@link AAudioStream_dataCallback}. 363 * 364 * The default, if you do not call this function, is AAUDIO_UNSPECIFIED. 365 * 366 * For the lowest possible latency, do not call this function. AAudio will then 367 * call the dataProc callback function with whatever size is optimal. 368 * That size may vary from one callback to another. 369 * 370 * Only use this function if the application requires a specific number of frames for processing. 371 * The application might, for example, be using an FFT that requires 372 * a specific power-of-two sized buffer. 373 * 374 * AAudio may need to add additional buffering in order to adapt between the internal 375 * buffer size and the requested buffer size. 376 * 377 * If you do call this function then the requested size should be less than 378 * half the buffer capacity, to allow double buffering. 379 * 380 * @param builder reference provided by AAudio_createStreamBuilder() 381 * @param numFrames the desired buffer size in frames or AAUDIO_UNSPECIFIED 382 */ 383AAUDIO_API void AAudioStreamBuilder_setFramesPerDataCallback(AAudioStreamBuilder* builder, 384 int32_t numFrames); 385 386/** 387 * Prototype for the callback function that is passed to 388 * AAudioStreamBuilder_setErrorCallback(). 389 * 390 * @param stream reference provided by AAudioStreamBuilder_openStream() 391 * @param userData the same address that was passed to AAudioStreamBuilder_setErrorCallback() 392 * @param error an AAUDIO_ERROR_* value. 393 */ 394typedef void (*AAudioStream_errorCallback)( 395 AAudioStream *stream, 396 void *userData, 397 aaudio_result_t error); 398 399/** 400 * Request that AAudio call this functions if any error occurs on a callback thread. 401 * 402 * It will be called, for example, if a headset or a USB device is unplugged causing the stream's 403 * device to be unavailable. 404 * In response, this function could signal or launch another thread to reopen a 405 * stream on another device. Do not reopen the stream in this callback. 406 * 407 * This will not be called because of actions by the application, such as stopping 408 * or closing a stream. 409 * 410 * Another possible cause of error would be a timeout or an unanticipated internal error. 411 * 412 * Note that the AAudio callbacks will never be called simultaneously from multiple threads. 413 * 414 * @param builder reference provided by AAudio_createStreamBuilder() 415 * @param callback pointer to a function that will be called if an error occurs. 416 * @param userData pointer to an application data structure that will be passed 417 * to the callback functions. 418 */ 419AAUDIO_API void AAudioStreamBuilder_setErrorCallback(AAudioStreamBuilder* builder, 420 AAudioStream_errorCallback callback, 421 void *userData); 422 423/** 424 * Open a stream based on the options in the StreamBuilder. 425 * 426 * AAudioStream_close must be called when finished with the stream to recover 427 * the memory and to free the associated resources. 428 * 429 * @param builder reference provided by AAudio_createStreamBuilder() 430 * @param stream pointer to a variable to receive the new stream reference 431 * @return AAUDIO_OK or a negative error. 432 */ 433AAUDIO_API aaudio_result_t AAudioStreamBuilder_openStream(AAudioStreamBuilder* builder, 434 AAudioStream** stream); 435 436/** 437 * Delete the resources associated with the StreamBuilder. 438 * 439 * @param builder reference provided by AAudio_createStreamBuilder() 440 * @return AAUDIO_OK or a negative error. 441 */ 442AAUDIO_API aaudio_result_t AAudioStreamBuilder_delete(AAudioStreamBuilder* builder); 443 444// ============================================================ 445// Stream Control 446// ============================================================ 447 448/** 449 * Free the resources associated with a stream created by AAudioStreamBuilder_openStream() 450 * 451 * @param stream reference provided by AAudioStreamBuilder_openStream() 452 * @return AAUDIO_OK or a negative error. 453 */ 454AAUDIO_API aaudio_result_t AAudioStream_close(AAudioStream* stream); 455 456/** 457 * Asynchronously request to start playing the stream. For output streams, one should 458 * write to the stream to fill the buffer before starting. 459 * Otherwise it will underflow. 460 * After this call the state will be in AAUDIO_STREAM_STATE_STARTING or AAUDIO_STREAM_STATE_STARTED. 461 * 462 * @param stream reference provided by AAudioStreamBuilder_openStream() 463 * @return AAUDIO_OK or a negative error. 464 */ 465AAUDIO_API aaudio_result_t AAudioStream_requestStart(AAudioStream* stream); 466 467/** 468 * Asynchronous request for the stream to pause. 469 * Pausing a stream will freeze the data flow but not flush any buffers. 470 * Use AAudioStream_Start() to resume playback after a pause. 471 * After this call the state will be in AAUDIO_STREAM_STATE_PAUSING or AAUDIO_STREAM_STATE_PAUSED. 472 * 473 * @param stream reference provided by AAudioStreamBuilder_openStream() 474 * @return AAUDIO_OK or a negative error. 475 */ 476AAUDIO_API aaudio_result_t AAudioStream_requestPause(AAudioStream* stream); 477 478/** 479 * Asynchronous request for the stream to flush. 480 * Flushing will discard any pending data. 481 * This call only works if the stream is pausing or paused. TODO review 482 * Frame counters are not reset by a flush. They may be advanced. 483 * After this call the state will be in AAUDIO_STREAM_STATE_FLUSHING or AAUDIO_STREAM_STATE_FLUSHED. 484 * 485 * @param stream reference provided by AAudioStreamBuilder_openStream() 486 * @return AAUDIO_OK or a negative error. 487 */ 488AAUDIO_API aaudio_result_t AAudioStream_requestFlush(AAudioStream* stream); 489 490/** 491 * Asynchronous request for the stream to stop. 492 * The stream will stop after all of the data currently buffered has been played. 493 * After this call the state will be in AAUDIO_STREAM_STATE_STOPPING or AAUDIO_STREAM_STATE_STOPPED. 494 * 495 * @param stream reference provided by AAudioStreamBuilder_openStream() 496 * @return AAUDIO_OK or a negative error. 497 */ 498AAUDIO_API aaudio_result_t AAudioStream_requestStop(AAudioStream* stream); 499 500/** 501 * Query the current state of the client, eg. AAUDIO_STREAM_STATE_PAUSING 502 * 503 * This function will immediately return the state without updating the state. 504 * If you want to update the client state based on the server state then 505 * call AAudioStream_waitForStateChange() with currentState 506 * set to AAUDIO_STREAM_STATE_UNKNOWN and a zero timeout. 507 * 508 * @param stream reference provided by AAudioStreamBuilder_openStream() 509 */ 510AAUDIO_API aaudio_stream_state_t AAudioStream_getState(AAudioStream* stream); 511 512/** 513 * Wait until the current state no longer matches the input state. 514 * 515 * This will update the current client state. 516 * 517 * <pre><code> 518 * aaudio_stream_state_t currentState; 519 * aaudio_result_t result = AAudioStream_getState(stream, ¤tState); 520 * while (result == AAUDIO_OK && currentState != AAUDIO_STREAM_STATE_PAUSING) { 521 * result = AAudioStream_waitForStateChange( 522 * stream, currentState, ¤tState, MY_TIMEOUT_NANOS); 523 * } 524 * </code></pre> 525 * 526 * @param stream A reference provided by AAudioStreamBuilder_openStream() 527 * @param inputState The state we want to avoid. 528 * @param nextState Pointer to a variable that will be set to the new state. 529 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. 530 * @return AAUDIO_OK or a negative error. 531 */ 532AAUDIO_API aaudio_result_t AAudioStream_waitForStateChange(AAudioStream* stream, 533 aaudio_stream_state_t inputState, 534 aaudio_stream_state_t *nextState, 535 int64_t timeoutNanoseconds); 536 537// ============================================================ 538// Stream I/O 539// ============================================================ 540 541/** 542 * Read data from the stream. 543 * 544 * The call will wait until the read is complete or until it runs out of time. 545 * If timeoutNanos is zero then this call will not wait. 546 * 547 * Note that timeoutNanoseconds is a relative duration in wall clock time. 548 * Time will not stop if the thread is asleep. 549 * So it will be implemented using CLOCK_BOOTTIME. 550 * 551 * This call is "strong non-blocking" unless it has to wait for data. 552 * 553 * @param stream A stream created using AAudioStreamBuilder_openStream(). 554 * @param buffer The address of the first sample. 555 * @param numFrames Number of frames to read. Only complete frames will be written. 556 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. 557 * @return The number of frames actually read or a negative error. 558 */ 559AAUDIO_API aaudio_result_t AAudioStream_read(AAudioStream* stream, 560 void *buffer, 561 int32_t numFrames, 562 int64_t timeoutNanoseconds); 563 564/** 565 * Write data to the stream. 566 * 567 * The call will wait until the write is complete or until it runs out of time. 568 * If timeoutNanos is zero then this call will not wait. 569 * 570 * Note that timeoutNanoseconds is a relative duration in wall clock time. 571 * Time will not stop if the thread is asleep. 572 * So it will be implemented using CLOCK_BOOTTIME. 573 * 574 * This call is "strong non-blocking" unless it has to wait for room in the buffer. 575 * 576 * @param stream A stream created using AAudioStreamBuilder_openStream(). 577 * @param buffer The address of the first sample. 578 * @param numFrames Number of frames to write. Only complete frames will be written. 579 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. 580 * @return The number of frames actually written or a negative error. 581 */ 582AAUDIO_API aaudio_result_t AAudioStream_write(AAudioStream* stream, 583 const void *buffer, 584 int32_t numFrames, 585 int64_t timeoutNanoseconds); 586 587// ============================================================ 588// Stream - queries 589// ============================================================ 590 591/** 592 * This can be used to adjust the latency of the buffer by changing 593 * the threshold where blocking will occur. 594 * By combining this with AAudioStream_getXRunCount(), the latency can be tuned 595 * at run-time for each device. 596 * 597 * This cannot be set higher than AAudioStream_getBufferCapacityInFrames(). 598 * 599 * Note that you will probably not get the exact size you request. 600 * Call AAudioStream_getBufferSizeInFrames() to see what the actual final size is. 601 * 602 * @param stream reference provided by AAudioStreamBuilder_openStream() 603 * @param numFrames requested number of frames that can be filled without blocking 604 * @return actual buffer size in frames or a negative error 605 */ 606AAUDIO_API aaudio_result_t AAudioStream_setBufferSizeInFrames(AAudioStream* stream, 607 int32_t numFrames); 608 609/** 610 * Query the maximum number of frames that can be filled without blocking. 611 * 612 * @param stream reference provided by AAudioStreamBuilder_openStream() 613 * @return buffer size in frames. 614 */ 615AAUDIO_API int32_t AAudioStream_getBufferSizeInFrames(AAudioStream* stream); 616 617/** 618 * Query the number of frames that the application should read or write at 619 * one time for optimal performance. It is OK if an application writes 620 * a different number of frames. But the buffer size may need to be larger 621 * in order to avoid underruns or overruns. 622 * 623 * Note that this may or may not match the actual device burst size. 624 * For some endpoints, the burst size can vary dynamically. 625 * But these tend to be devices with high latency. 626 * 627 * @param stream reference provided by AAudioStreamBuilder_openStream() 628 * @return burst size 629 */ 630AAUDIO_API int32_t AAudioStream_getFramesPerBurst(AAudioStream* stream); 631 632/** 633 * Query maximum buffer capacity in frames. 634 * 635 * @param stream reference provided by AAudioStreamBuilder_openStream() 636 * @return buffer capacity in frames 637 */ 638AAUDIO_API int32_t AAudioStream_getBufferCapacityInFrames(AAudioStream* stream); 639 640/** 641 * Query the size of the buffer that will be passed to the dataProc callback 642 * in the numFrames parameter. 643 * 644 * This call can be used if the application needs to know the value of numFrames before 645 * the stream is started. This is not normally necessary. 646 * 647 * If a specific size was requested by calling AAudioStreamBuilder_setCallbackSizeInFrames() 648 * then this will be the same size. 649 * 650 * If AAudioStreamBuilder_setCallbackSizeInFrames() was not called then this will 651 * return the size chosen by AAudio, or AAUDIO_UNSPECIFIED. 652 * 653 * AAUDIO_UNSPECIFIED indicates that the callback buffer size for this stream 654 * may vary from one dataProc callback to the next. 655 * 656 * @param stream reference provided by AAudioStreamBuilder_openStream() 657 * @return callback buffer size in frames or AAUDIO_UNSPECIFIED 658 */ 659AAUDIO_API int32_t AAudioStream_getFramesPerDataCallback(AAudioStream* stream); 660 661/** 662 * An XRun is an Underrun or an Overrun. 663 * During playing, an underrun will occur if the stream is not written in time 664 * and the system runs out of valid data. 665 * During recording, an overrun will occur if the stream is not read in time 666 * and there is no place to put the incoming data so it is discarded. 667 * 668 * An underrun or overrun can cause an audible "pop" or "glitch". 669 * 670 * @param stream reference provided by AAudioStreamBuilder_openStream() 671 * @return the underrun or overrun count 672 */ 673AAUDIO_API int32_t AAudioStream_getXRunCount(AAudioStream* stream); 674 675/** 676 * @param stream reference provided by AAudioStreamBuilder_openStream() 677 * @return actual sample rate 678 */ 679AAUDIO_API int32_t AAudioStream_getSampleRate(AAudioStream* stream); 680 681/** 682 * The samplesPerFrame is also known as channelCount. 683 * 684 * @param stream reference provided by AAudioStreamBuilder_openStream() 685 * @return actual samples per frame 686 */ 687AAUDIO_API int32_t AAudioStream_getSamplesPerFrame(AAudioStream* stream); 688 689/** 690 * @param stream reference provided by AAudioStreamBuilder_openStream() 691 * @return actual device ID 692 */ 693AAUDIO_API int32_t AAudioStream_getDeviceId(AAudioStream* stream); 694 695/** 696 * @param stream reference provided by AAudioStreamBuilder_openStream() 697 * @return actual data format 698 */ 699AAUDIO_API aaudio_audio_format_t AAudioStream_getFormat(AAudioStream* stream); 700 701/** 702 * Provide actual sharing mode. 703 * @param stream reference provided by AAudioStreamBuilder_openStream() 704 * @return actual sharing mode 705 */ 706AAUDIO_API aaudio_sharing_mode_t AAudioStream_getSharingMode(AAudioStream* stream); 707 708/** 709 * @param stream reference provided by AAudioStreamBuilder_openStream() 710 * @return direction 711 */ 712AAUDIO_API aaudio_direction_t AAudioStream_getDirection(AAudioStream* stream); 713 714/** 715 * Passes back the number of frames that have been written since the stream was created. 716 * For an output stream, this will be advanced by the application calling write(). 717 * For an input stream, this will be advanced by the endpoint. 718 * 719 * The frame position is monotonically increasing. 720 * 721 * @param stream reference provided by AAudioStreamBuilder_openStream() 722 * @return frames written 723 */ 724AAUDIO_API int64_t AAudioStream_getFramesWritten(AAudioStream* stream); 725 726/** 727 * Passes back the number of frames that have been read since the stream was created. 728 * For an output stream, this will be advanced by the endpoint. 729 * For an input stream, this will be advanced by the application calling read(). 730 * 731 * The frame position is monotonically increasing. 732 * 733 * @param stream reference provided by AAudioStreamBuilder_openStream() 734 * @return frames read 735 */ 736AAUDIO_API int64_t AAudioStream_getFramesRead(AAudioStream* stream); 737 738/** 739 * Passes back the time at which a particular frame was presented. 740 * This can be used to synchronize audio with video or MIDI. 741 * It can also be used to align a recorded stream with a playback stream. 742 * 743 * Timestamps are only valid when the stream is in AAUDIO_STREAM_STATE_STARTED. 744 * AAUDIO_ERROR_INVALID_STATE will be returned if the stream is not started. 745 * Note that because requestStart() is asynchronous, timestamps will not be valid until 746 * a short time after calling requestStart(). 747 * So AAUDIO_ERROR_INVALID_STATE should not be considered a fatal error. 748 * Just try calling again later. 749 * 750 * If an error occurs, then the position and time will not be modified. 751 * 752 * The position and time passed back are monotonically increasing. 753 * 754 * @param stream reference provided by AAudioStreamBuilder_openStream() 755 * @param clockid AAUDIO_CLOCK_MONOTONIC or AAUDIO_CLOCK_BOOTTIME 756 * @param framePosition pointer to a variable to receive the position 757 * @param timeNanoseconds pointer to a variable to receive the time 758 * @return AAUDIO_OK or a negative error 759 */ 760AAUDIO_API aaudio_result_t AAudioStream_getTimestamp(AAudioStream* stream, 761 clockid_t clockid, 762 int64_t *framePosition, 763 int64_t *timeNanoseconds); 764 765#ifdef __cplusplus 766} 767#endif 768 769#endif //AAUDIO_AAUDIO_H 770 771/** @} */ 772