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