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