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