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