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