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