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 35 extern "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 46 enum { 47 /** 48 * Audio data will travel out of the device, for example through a speaker. 49 */ 50 AAUDIO_DIRECTION_OUTPUT, 51 52 53 /** 54 * Audio data will travel into the device, for example from a microphone. 55 */ 56 AAUDIO_DIRECTION_INPUT 57 }; 58 typedef int32_t aaudio_direction_t; 59 60 enum { 61 AAUDIO_FORMAT_INVALID = -1, 62 AAUDIO_FORMAT_UNSPECIFIED = 0, 63 64 /** 65 * This format uses the int16_t data type. 66 * The maximum range of the data is -32768 to 32767. 67 */ 68 AAUDIO_FORMAT_PCM_I16, 69 70 /** 71 * This format uses the float data type. 72 * The nominal range of the data is [-1.0f, 1.0f). 73 * Values outside that range may be clipped. 74 * 75 * See also 'floatData' at 76 * https://developer.android.com/reference/android/media/AudioTrack#write(float[],%20int,%20int,%20int) 77 */ 78 AAUDIO_FORMAT_PCM_FLOAT 79 }; 80 typedef int32_t aaudio_format_t; 81 82 /** 83 * These result codes are returned from AAudio functions to indicate success or failure. 84 * Note that error return codes may change in the future so applications should generally 85 * not rely on specific return codes. 86 */ 87 enum { 88 /** 89 * The call was successful. 90 */ 91 AAUDIO_OK, 92 AAUDIO_ERROR_BASE = -900, // TODO review 93 94 /** 95 * The audio device was disconnected. This could occur, for example, when headphones 96 * are plugged in or unplugged. The stream cannot be used after the device is disconnected. 97 * Applications should stop and close the stream. 98 * If this error is received in an error callback then another thread should be 99 * used to stop and close the stream. 100 */ 101 AAUDIO_ERROR_DISCONNECTED, 102 103 /** 104 * An invalid parameter was passed to AAudio. 105 */ 106 AAUDIO_ERROR_ILLEGAL_ARGUMENT, 107 // reserved 108 AAUDIO_ERROR_INTERNAL = AAUDIO_ERROR_ILLEGAL_ARGUMENT + 2, 109 110 /** 111 * The requested operation is not appropriate for the current state of AAudio. 112 */ 113 AAUDIO_ERROR_INVALID_STATE, 114 // reserved 115 // reserved 116 /* The server rejected the handle used to identify the stream. 117 */ 118 AAUDIO_ERROR_INVALID_HANDLE = AAUDIO_ERROR_INVALID_STATE + 3, 119 // reserved 120 121 /** 122 * The function is not implemented for this stream. 123 */ 124 AAUDIO_ERROR_UNIMPLEMENTED = AAUDIO_ERROR_INVALID_HANDLE + 2, 125 126 /** 127 * A resource or information is unavailable. 128 * This could occur when an application tries to open too many streams, 129 * or a timestamp is not available. 130 */ 131 AAUDIO_ERROR_UNAVAILABLE, 132 AAUDIO_ERROR_NO_FREE_HANDLES, 133 134 /** 135 * Memory could not be allocated. 136 */ 137 AAUDIO_ERROR_NO_MEMORY, 138 139 /** 140 * A NULL pointer was passed to AAudio. 141 * Or a NULL pointer was detected internally. 142 */ 143 AAUDIO_ERROR_NULL, 144 145 /** 146 * An operation took longer than expected. 147 */ 148 AAUDIO_ERROR_TIMEOUT, 149 AAUDIO_ERROR_WOULD_BLOCK, 150 151 /** 152 * The requested data format is not supported. 153 */ 154 AAUDIO_ERROR_INVALID_FORMAT, 155 156 /** 157 * A requested was out of range. 158 */ 159 AAUDIO_ERROR_OUT_OF_RANGE, 160 161 /** 162 * The audio service was not available. 163 */ 164 AAUDIO_ERROR_NO_SERVICE, 165 166 /** 167 * The requested sample rate was not supported. 168 */ 169 AAUDIO_ERROR_INVALID_RATE 170 }; 171 typedef int32_t aaudio_result_t; 172 173 enum 174 { 175 AAUDIO_STREAM_STATE_UNINITIALIZED = 0, 176 AAUDIO_STREAM_STATE_UNKNOWN, 177 AAUDIO_STREAM_STATE_OPEN, 178 AAUDIO_STREAM_STATE_STARTING, 179 AAUDIO_STREAM_STATE_STARTED, 180 AAUDIO_STREAM_STATE_PAUSING, 181 AAUDIO_STREAM_STATE_PAUSED, 182 AAUDIO_STREAM_STATE_FLUSHING, 183 AAUDIO_STREAM_STATE_FLUSHED, 184 AAUDIO_STREAM_STATE_STOPPING, 185 AAUDIO_STREAM_STATE_STOPPED, 186 AAUDIO_STREAM_STATE_CLOSING, 187 AAUDIO_STREAM_STATE_CLOSED, 188 AAUDIO_STREAM_STATE_DISCONNECTED 189 }; 190 typedef int32_t aaudio_stream_state_t; 191 192 193 enum { 194 /** 195 * This will be the only stream using a particular source or sink. 196 * This mode will provide the lowest possible latency. 197 * You should close EXCLUSIVE streams immediately when you are not using them. 198 */ 199 AAUDIO_SHARING_MODE_EXCLUSIVE, 200 /** 201 * Multiple applications will be mixed by the AAudio Server. 202 * This will have higher latency than the EXCLUSIVE mode. 203 */ 204 AAUDIO_SHARING_MODE_SHARED 205 }; 206 typedef int32_t aaudio_sharing_mode_t; 207 208 209 enum { 210 /** 211 * No particular performance needs. Default. 212 */ 213 AAUDIO_PERFORMANCE_MODE_NONE = 10, 214 215 /** 216 * Extending battery life is more important than low latency. 217 * 218 * This mode is not supported in input streams. 219 * For input, mode NONE will be used if this is requested. 220 */ 221 AAUDIO_PERFORMANCE_MODE_POWER_SAVING, 222 223 /** 224 * Reducing latency is more important than battery life. 225 */ 226 AAUDIO_PERFORMANCE_MODE_LOW_LATENCY 227 }; 228 typedef int32_t aaudio_performance_mode_t; 229 230 /** 231 * The USAGE attribute expresses "why" you are playing a sound, what is this sound used for. 232 * This information is used by certain platforms or routing policies 233 * to make more refined volume or routing decisions. 234 * 235 * Note that these match the equivalent values in AudioAttributes in the Android Java API. 236 * 237 * Added in API level 28. 238 */ 239 enum { 240 /** 241 * Use this for streaming media, music performance, video, podcasts, etcetera. 242 */ 243 AAUDIO_USAGE_MEDIA = 1, 244 245 /** 246 * Use this for voice over IP, telephony, etcetera. 247 */ 248 AAUDIO_USAGE_VOICE_COMMUNICATION = 2, 249 250 /** 251 * Use this for sounds associated with telephony such as busy tones, DTMF, etcetera. 252 */ 253 AAUDIO_USAGE_VOICE_COMMUNICATION_SIGNALLING = 3, 254 255 /** 256 * Use this to demand the users attention. 257 */ 258 AAUDIO_USAGE_ALARM = 4, 259 260 /** 261 * Use this for notifying the user when a message has arrived or some 262 * other background event has occured. 263 */ 264 AAUDIO_USAGE_NOTIFICATION = 5, 265 266 /** 267 * Use this when the phone rings. 268 */ 269 AAUDIO_USAGE_NOTIFICATION_RINGTONE = 6, 270 271 /** 272 * Use this to attract the users attention when, for example, the battery is low. 273 */ 274 AAUDIO_USAGE_NOTIFICATION_EVENT = 10, 275 276 /** 277 * Use this for screen readers, etcetera. 278 */ 279 AAUDIO_USAGE_ASSISTANCE_ACCESSIBILITY = 11, 280 281 /** 282 * Use this for driving or navigation directions. 283 */ 284 AAUDIO_USAGE_ASSISTANCE_NAVIGATION_GUIDANCE = 12, 285 286 /** 287 * Use this for user interface sounds, beeps, etcetera. 288 */ 289 AAUDIO_USAGE_ASSISTANCE_SONIFICATION = 13, 290 291 /** 292 * Use this for game audio and sound effects. 293 */ 294 AAUDIO_USAGE_GAME = 14, 295 296 /** 297 * Use this for audio responses to user queries, audio instructions or help utterances. 298 */ 299 AAUDIO_USAGE_ASSISTANT = 16 300 }; 301 typedef int32_t aaudio_usage_t; 302 303 /** 304 * The CONTENT_TYPE attribute describes "what" you are playing. 305 * It expresses the general category of the content. This information is optional. 306 * But in case it is known (for instance {@link #AAUDIO_CONTENT_TYPE_MOVIE} for a 307 * movie streaming service or {@link #AAUDIO_CONTENT_TYPE_SPEECH} for 308 * an audio book application) this information might be used by the audio framework to 309 * enforce audio focus. 310 * 311 * Note that these match the equivalent values in AudioAttributes in the Android Java API. 312 * 313 * Added in API level 28. 314 */ 315 enum { 316 317 /** 318 * Use this for spoken voice, audio books, etcetera. 319 */ 320 AAUDIO_CONTENT_TYPE_SPEECH = 1, 321 322 /** 323 * Use this for pre-recorded or live music. 324 */ 325 AAUDIO_CONTENT_TYPE_MUSIC = 2, 326 327 /** 328 * Use this for a movie or video soundtrack. 329 */ 330 AAUDIO_CONTENT_TYPE_MOVIE = 3, 331 332 /** 333 * Use this for sound is designed to accompany a user action, 334 * such as a click or beep sound made when the user presses a button. 335 */ 336 AAUDIO_CONTENT_TYPE_SONIFICATION = 4 337 }; 338 typedef int32_t aaudio_content_type_t; 339 340 /** 341 * Defines the audio source. 342 * An audio source defines both a default physical source of audio signal, and a recording 343 * configuration. 344 * 345 * Note that these match the equivalent values in MediaRecorder.AudioSource in the Android Java API. 346 * 347 * Added in API level 28. 348 */ 349 enum { 350 /** 351 * Use this preset when other presets do not apply. 352 */ 353 AAUDIO_INPUT_PRESET_GENERIC = 1, 354 355 /** 356 * Use this preset when recording video. 357 */ 358 AAUDIO_INPUT_PRESET_CAMCORDER = 5, 359 360 /** 361 * Use this preset when doing speech recognition. 362 */ 363 AAUDIO_INPUT_PRESET_VOICE_RECOGNITION = 6, 364 365 /** 366 * Use this preset when doing telephony or voice messaging. 367 */ 368 AAUDIO_INPUT_PRESET_VOICE_COMMUNICATION = 7, 369 370 /** 371 * Use this preset to obtain an input with no effects. 372 * Note that this input will not have automatic gain control 373 * so the recorded volume may be very low. 374 */ 375 AAUDIO_INPUT_PRESET_UNPROCESSED = 9, 376 }; 377 typedef int32_t aaudio_input_preset_t; 378 379 /** 380 * These may be used with AAudioStreamBuilder_setSessionId(). 381 * 382 * Added in API level 28. 383 */ 384 enum { 385 /** 386 * Do not allocate a session ID. 387 * Effects cannot be used with this stream. 388 * Default. 389 * 390 * Added in API level 28. 391 */ 392 AAUDIO_SESSION_ID_NONE = -1, 393 394 /** 395 * Allocate a session ID that can be used to attach and control 396 * effects using the Java AudioEffects API. 397 * Note that using this may result in higher latency. 398 * 399 * Note that this matches the value of AudioManager.AUDIO_SESSION_ID_GENERATE. 400 * 401 * Added in API level 28. 402 */ 403 AAUDIO_SESSION_ID_ALLOCATE = 0, 404 }; 405 typedef int32_t aaudio_session_id_t; 406 407 typedef struct AAudioStreamStruct AAudioStream; 408 typedef struct AAudioStreamBuilderStruct AAudioStreamBuilder; 409 410 #ifndef AAUDIO_API 411 #define AAUDIO_API /* export this symbol */ 412 #endif 413 414 // ============================================================ 415 // Audio System 416 // ============================================================ 417 418 /** 419 * The text is the ASCII symbol corresponding to the returnCode, 420 * or an English message saying the returnCode is unrecognized. 421 * This is intended for developers to use when debugging. 422 * It is not for display to users. 423 * 424 * @return pointer to a text representation of an AAudio result code. 425 */ 426 AAUDIO_API const char * AAudio_convertResultToText(aaudio_result_t returnCode); 427 428 /** 429 * The text is the ASCII symbol corresponding to the stream state, 430 * or an English message saying the state is unrecognized. 431 * This is intended for developers to use when debugging. 432 * It is not for display to users. 433 * 434 * @return pointer to a text representation of an AAudio state. 435 */ 436 AAUDIO_API const char * AAudio_convertStreamStateToText(aaudio_stream_state_t state); 437 438 // ============================================================ 439 // StreamBuilder 440 // ============================================================ 441 442 /** 443 * Create a StreamBuilder that can be used to open a Stream. 444 * 445 * The deviceId is initially unspecified, meaning that the current default device will be used. 446 * 447 * The default direction is AAUDIO_DIRECTION_OUTPUT. 448 * The default sharing mode is AAUDIO_SHARING_MODE_SHARED. 449 * The data format, samplesPerFrames and sampleRate are unspecified and will be 450 * chosen by the device when it is opened. 451 * 452 * AAudioStreamBuilder_delete() must be called when you are done using the builder. 453 */ 454 AAUDIO_API aaudio_result_t AAudio_createStreamBuilder(AAudioStreamBuilder** builder); 455 456 /** 457 * Request an audio device identified device using an ID. 458 * On Android, for example, the ID could be obtained from the Java AudioManager. 459 * 460 * The default, if you do not call this function, is AAUDIO_UNSPECIFIED, 461 * in which case the primary device will be used. 462 * 463 * @param builder reference provided by AAudio_createStreamBuilder() 464 * @param deviceId device identifier or AAUDIO_UNSPECIFIED 465 */ 466 AAUDIO_API void AAudioStreamBuilder_setDeviceId(AAudioStreamBuilder* builder, 467 int32_t deviceId); 468 469 /** 470 * Request a sample rate in Hertz. 471 * 472 * The default, if you do not call this function, is AAUDIO_UNSPECIFIED. 473 * An optimal value will then be chosen when the stream is opened. 474 * After opening a stream with an unspecified value, the application must 475 * query for the actual value, which may vary by device. 476 * 477 * If an exact value is specified then an opened stream will use that value. 478 * If a stream cannot be opened with the specified value then the open will fail. 479 * 480 * @param builder reference provided by AAudio_createStreamBuilder() 481 * @param sampleRate frames per second. Common rates include 44100 and 48000 Hz. 482 */ 483 AAUDIO_API void AAudioStreamBuilder_setSampleRate(AAudioStreamBuilder* builder, 484 int32_t sampleRate); 485 486 /** 487 * Request a number of channels for the stream. 488 * 489 * The default, if you do not call this function, is AAUDIO_UNSPECIFIED. 490 * An optimal value will then be chosen when the stream is opened. 491 * After opening a stream with an unspecified value, the application must 492 * query for the actual value, which may vary by device. 493 * 494 * If an exact value is specified then an opened stream will use that value. 495 * If a stream cannot be opened with the specified value then the open will fail. 496 * 497 * @param builder reference provided by AAudio_createStreamBuilder() 498 * @param channelCount Number of channels desired. 499 */ 500 AAUDIO_API void AAudioStreamBuilder_setChannelCount(AAudioStreamBuilder* builder, 501 int32_t channelCount); 502 503 /** 504 * Identical to AAudioStreamBuilder_setChannelCount(). 505 * 506 * @param builder reference provided by AAudio_createStreamBuilder() 507 * @param samplesPerFrame Number of samples in a frame. 508 */ 509 AAUDIO_API void AAudioStreamBuilder_setSamplesPerFrame(AAudioStreamBuilder* builder, 510 int32_t samplesPerFrame); 511 512 /** 513 * Request a sample data format, for example AAUDIO_FORMAT_PCM_I16. 514 * 515 * The default, if you do not call this function, is AAUDIO_UNSPECIFIED. 516 * An optimal value will then be chosen when the stream is opened. 517 * After opening a stream with an unspecified value, the application must 518 * query for the actual value, which may vary by device. 519 * 520 * If an exact value is specified then an opened stream will use that value. 521 * If a stream cannot be opened with the specified value then the open will fail. 522 * 523 * @param builder reference provided by AAudio_createStreamBuilder() 524 * @param format common formats are AAUDIO_FORMAT_PCM_FLOAT and AAUDIO_FORMAT_PCM_I16. 525 */ 526 AAUDIO_API void AAudioStreamBuilder_setFormat(AAudioStreamBuilder* builder, 527 aaudio_format_t format); 528 529 /** 530 * Request a mode for sharing the device. 531 * 532 * The default, if you do not call this function, is AAUDIO_SHARING_MODE_SHARED. 533 * 534 * The requested sharing mode may not be available. 535 * The application can query for the actual mode after the stream is opened. 536 * 537 * @param builder reference provided by AAudio_createStreamBuilder() 538 * @param sharingMode AAUDIO_SHARING_MODE_SHARED or AAUDIO_SHARING_MODE_EXCLUSIVE 539 */ 540 AAUDIO_API void AAudioStreamBuilder_setSharingMode(AAudioStreamBuilder* builder, 541 aaudio_sharing_mode_t sharingMode); 542 543 /** 544 * Request the direction for a stream. 545 * 546 * The default, if you do not call this function, is AAUDIO_DIRECTION_OUTPUT. 547 * 548 * @param builder reference provided by AAudio_createStreamBuilder() 549 * @param direction AAUDIO_DIRECTION_OUTPUT or AAUDIO_DIRECTION_INPUT 550 */ 551 AAUDIO_API void AAudioStreamBuilder_setDirection(AAudioStreamBuilder* builder, 552 aaudio_direction_t direction); 553 554 /** 555 * Set the requested buffer capacity in frames. 556 * The final AAudioStream capacity may differ, but will probably be at least this big. 557 * 558 * The default, if you do not call this function, is AAUDIO_UNSPECIFIED. 559 * 560 * @param builder reference provided by AAudio_createStreamBuilder() 561 * @param numFrames the desired buffer capacity in frames or AAUDIO_UNSPECIFIED 562 */ 563 AAUDIO_API void AAudioStreamBuilder_setBufferCapacityInFrames(AAudioStreamBuilder* builder, 564 int32_t numFrames); 565 566 /** 567 * Set the requested performance mode. 568 * 569 * Supported modes are AAUDIO_PERFORMANCE_MODE_NONE, AAUDIO_PERFORMANCE_MODE_POWER_SAVING 570 * and AAUDIO_PERFORMANCE_MODE_LOW_LATENCY. 571 * 572 * The default, if you do not call this function, is AAUDIO_PERFORMANCE_MODE_NONE. 573 * 574 * You may not get the mode you requested. 575 * You can call AAudioStream_getPerformanceMode() to find out the final mode for the stream. 576 * 577 * @param builder reference provided by AAudio_createStreamBuilder() 578 * @param mode the desired performance mode, eg. AAUDIO_PERFORMANCE_MODE_LOW_LATENCY 579 */ 580 AAUDIO_API void AAudioStreamBuilder_setPerformanceMode(AAudioStreamBuilder* builder, 581 aaudio_performance_mode_t mode); 582 583 /** 584 * Set the intended use case for the stream. 585 * 586 * The AAudio system will use this information to optimize the 587 * behavior of the stream. 588 * This could, for example, affect how volume and focus is handled for the stream. 589 * 590 * The default, if you do not call this function, is AAUDIO_USAGE_MEDIA. 591 * 592 * Added in API level 28. 593 * 594 * @param builder reference provided by AAudio_createStreamBuilder() 595 * @param usage the desired usage, eg. AAUDIO_USAGE_GAME 596 */ 597 AAUDIO_API void AAudioStreamBuilder_setUsage(AAudioStreamBuilder* builder, 598 aaudio_usage_t usage); 599 600 /** 601 * Set the type of audio data that the stream will carry. 602 * 603 * The AAudio system will use this information to optimize the 604 * behavior of the stream. 605 * This could, for example, affect whether a stream is paused when a notification occurs. 606 * 607 * The default, if you do not call this function, is AAUDIO_CONTENT_TYPE_MUSIC. 608 * 609 * Added in API level 28. 610 * 611 * @param builder reference provided by AAudio_createStreamBuilder() 612 * @param contentType the type of audio data, eg. AAUDIO_CONTENT_TYPE_SPEECH 613 */ 614 AAUDIO_API void AAudioStreamBuilder_setContentType(AAudioStreamBuilder* builder, 615 aaudio_content_type_t contentType); 616 617 /** 618 * Set the input (capture) preset for the stream. 619 * 620 * The AAudio system will use this information to optimize the 621 * behavior of the stream. 622 * This could, for example, affect which microphones are used and how the 623 * recorded data is processed. 624 * 625 * The default, if you do not call this function, is AAUDIO_INPUT_PRESET_VOICE_RECOGNITION. 626 * That is because VOICE_RECOGNITION is the preset with the lowest latency 627 * on many platforms. 628 * 629 * Added in API level 28. 630 * 631 * @param builder reference provided by AAudio_createStreamBuilder() 632 * @param inputPreset the desired configuration for recording 633 */ 634 AAUDIO_API void AAudioStreamBuilder_setInputPreset(AAudioStreamBuilder* builder, 635 aaudio_input_preset_t inputPreset); 636 637 /** Set the requested session ID. 638 * 639 * The session ID can be used to associate a stream with effects processors. 640 * The effects are controlled using the Android AudioEffect Java API. 641 * 642 * The default, if you do not call this function, is AAUDIO_SESSION_ID_NONE. 643 * 644 * If set to AAUDIO_SESSION_ID_ALLOCATE then a session ID will be allocated 645 * when the stream is opened. 646 * 647 * The allocated session ID can be obtained by calling AAudioStream_getSessionId() 648 * and then used with this function when opening another stream. 649 * This allows effects to be shared between streams. 650 * 651 * Session IDs from AAudio can be used with the Android Java APIs and vice versa. 652 * So a session ID from an AAudio stream can be passed to Java 653 * and effects applied using the Java AudioEffect API. 654 * 655 * Note that allocating or setting a session ID may result in a stream with higher latency. 656 * 657 * Allocated session IDs will always be positive and nonzero. 658 * 659 * Added in API level 28. 660 * 661 * @param builder reference provided by AAudio_createStreamBuilder() 662 * @param sessionId an allocated sessionID or AAUDIO_SESSION_ID_ALLOCATE 663 */ 664 AAUDIO_API void AAudioStreamBuilder_setSessionId(AAudioStreamBuilder* builder, 665 aaudio_session_id_t sessionId); 666 667 /** 668 * Return one of these values from the data callback function. 669 */ 670 enum { 671 672 /** 673 * Continue calling the callback. 674 */ 675 AAUDIO_CALLBACK_RESULT_CONTINUE = 0, 676 677 /** 678 * Stop calling the callback. 679 * 680 * The application will still need to call AAudioStream_requestPause() 681 * or AAudioStream_requestStop(). 682 */ 683 AAUDIO_CALLBACK_RESULT_STOP, 684 685 }; 686 typedef int32_t aaudio_data_callback_result_t; 687 688 /** 689 * Prototype for the data function that is passed to AAudioStreamBuilder_setDataCallback(). 690 * 691 * For an output stream, this function should render and write numFrames of data 692 * in the streams current data format to the audioData buffer. 693 * 694 * For an input stream, this function should read and process numFrames of data 695 * from the audioData buffer. 696 * 697 * The audio data is passed through the buffer. So do NOT call AAudioStream_read() or 698 * AAudioStream_write() on the stream that is making the callback. 699 * 700 * Note that numFrames can vary unless AAudioStreamBuilder_setFramesPerDataCallback() 701 * is called. 702 * 703 * Also note that this callback function should be considered a "real-time" function. 704 * It must not do anything that could cause an unbounded delay because that can cause the 705 * audio to glitch or pop. 706 * 707 * These are things the function should NOT do: 708 * <ul> 709 * <li>allocate memory using, for example, malloc() or new</li> 710 * <li>any file operations such as opening, closing, reading or writing</li> 711 * <li>any network operations such as streaming</li> 712 * <li>use any mutexes or other synchronization primitives</li> 713 * <li>sleep</li> 714 * <li>stop or close the stream</li> 715 * <li>AAudioStream_read()</li> 716 * <li>AAudioStream_write()</li> 717 * </ul> 718 * 719 * The following are OK to call from the data callback: 720 * <ul> 721 * <li>AAudioStream_get*()</li> 722 * <li>AAudio_convertResultToText()</li> 723 * </ul> 724 * 725 * If you need to move data, eg. MIDI commands, in or out of the callback function then 726 * we recommend the use of non-blocking techniques such as an atomic FIFO. 727 * 728 * @param stream reference provided by AAudioStreamBuilder_openStream() 729 * @param userData the same address that was passed to AAudioStreamBuilder_setCallback() 730 * @param audioData a pointer to the audio data 731 * @param numFrames the number of frames to be processed, which can vary 732 * @return AAUDIO_CALLBACK_RESULT_* 733 */ 734 typedef aaudio_data_callback_result_t (*AAudioStream_dataCallback)( 735 AAudioStream *stream, 736 void *userData, 737 void *audioData, 738 int32_t numFrames); 739 740 /** 741 * Request that AAudio call this functions when the stream is running. 742 * 743 * Note that when using this callback, the audio data will be passed in or out 744 * of the function as an argument. 745 * So you cannot call AAudioStream_write() or AAudioStream_read() on the same stream 746 * that has an active data callback. 747 * 748 * The callback function will start being called after AAudioStream_requestStart() is called. 749 * It will stop being called after AAudioStream_requestPause() or 750 * AAudioStream_requestStop() is called. 751 * 752 * This callback function will be called on a real-time thread owned by AAudio. See 753 * {@link AAudioStream_dataCallback} for more information. 754 * 755 * Note that the AAudio callbacks will never be called simultaneously from multiple threads. 756 * 757 * @param builder reference provided by AAudio_createStreamBuilder() 758 * @param callback pointer to a function that will process audio data. 759 * @param userData pointer to an application data structure that will be passed 760 * to the callback functions. 761 */ 762 AAUDIO_API void AAudioStreamBuilder_setDataCallback(AAudioStreamBuilder* builder, 763 AAudioStream_dataCallback callback, 764 void *userData); 765 766 /** 767 * Set the requested data callback buffer size in frames. 768 * See {@link AAudioStream_dataCallback}. 769 * 770 * The default, if you do not call this function, is AAUDIO_UNSPECIFIED. 771 * 772 * For the lowest possible latency, do not call this function. AAudio will then 773 * call the dataProc callback function with whatever size is optimal. 774 * That size may vary from one callback to another. 775 * 776 * Only use this function if the application requires a specific number of frames for processing. 777 * The application might, for example, be using an FFT that requires 778 * a specific power-of-two sized buffer. 779 * 780 * AAudio may need to add additional buffering in order to adapt between the internal 781 * buffer size and the requested buffer size. 782 * 783 * If you do call this function then the requested size should be less than 784 * half the buffer capacity, to allow double buffering. 785 * 786 * @param builder reference provided by AAudio_createStreamBuilder() 787 * @param numFrames the desired buffer size in frames or AAUDIO_UNSPECIFIED 788 */ 789 AAUDIO_API void AAudioStreamBuilder_setFramesPerDataCallback(AAudioStreamBuilder* builder, 790 int32_t numFrames); 791 792 /** 793 * Prototype for the callback function that is passed to 794 * AAudioStreamBuilder_setErrorCallback(). 795 * 796 * The following may NOT be called from the error callback: 797 * <ul> 798 * <li>AAudioStream_requestStop()</li> 799 * <li>AAudioStream_requestPause()</li> 800 * <li>AAudioStream_close()</li> 801 * <li>AAudioStream_waitForStateChange()</li> 802 * <li>AAudioStream_read()</li> 803 * <li>AAudioStream_write()</li> 804 * </ul> 805 * 806 * The following are OK to call from the error callback: 807 * <ul> 808 * <li>AAudioStream_get*()</li> 809 * <li>AAudio_convertResultToText()</li> 810 * </ul> 811 * 812 * @param stream reference provided by AAudioStreamBuilder_openStream() 813 * @param userData the same address that was passed to AAudioStreamBuilder_setErrorCallback() 814 * @param error an AAUDIO_ERROR_* value. 815 */ 816 typedef void (*AAudioStream_errorCallback)( 817 AAudioStream *stream, 818 void *userData, 819 aaudio_result_t error); 820 821 /** 822 * Request that AAudio call this function if any error occurs or the stream is disconnected. 823 * 824 * It will be called, for example, if a headset or a USB device is unplugged causing the stream's 825 * device to be unavailable or "disconnected". 826 * Another possible cause of error would be a timeout or an unanticipated internal error. 827 * 828 * In response, this function should signal or create another thread to stop 829 * and close this stream. The other thread could then reopen a stream on another device. 830 * Do not stop or close the stream, or reopen the new stream, directly from this callback. 831 * 832 * This callback will not be called because of actions by the application, such as stopping 833 * or closing a stream. 834 * 835 * Note that the AAudio callbacks will never be called simultaneously from multiple threads. 836 * 837 * @param builder reference provided by AAudio_createStreamBuilder() 838 * @param callback pointer to a function that will be called if an error occurs. 839 * @param userData pointer to an application data structure that will be passed 840 * to the callback functions. 841 */ 842 AAUDIO_API void AAudioStreamBuilder_setErrorCallback(AAudioStreamBuilder* builder, 843 AAudioStream_errorCallback callback, 844 void *userData); 845 846 /** 847 * Open a stream based on the options in the StreamBuilder. 848 * 849 * AAudioStream_close must be called when finished with the stream to recover 850 * the memory and to free the associated resources. 851 * 852 * @param builder reference provided by AAudio_createStreamBuilder() 853 * @param stream pointer to a variable to receive the new stream reference 854 * @return AAUDIO_OK or a negative error. 855 */ 856 AAUDIO_API aaudio_result_t AAudioStreamBuilder_openStream(AAudioStreamBuilder* builder, 857 AAudioStream** stream); 858 859 /** 860 * Delete the resources associated with the StreamBuilder. 861 * 862 * @param builder reference provided by AAudio_createStreamBuilder() 863 * @return AAUDIO_OK or a negative error. 864 */ 865 AAUDIO_API aaudio_result_t AAudioStreamBuilder_delete(AAudioStreamBuilder* builder); 866 867 // ============================================================ 868 // Stream Control 869 // ============================================================ 870 871 /** 872 * Free the resources associated with a stream created by AAudioStreamBuilder_openStream() 873 * 874 * @param stream reference provided by AAudioStreamBuilder_openStream() 875 * @return AAUDIO_OK or a negative error. 876 */ 877 AAUDIO_API aaudio_result_t AAudioStream_close(AAudioStream* stream); 878 879 /** 880 * Asynchronously request to start playing the stream. For output streams, one should 881 * write to the stream to fill the buffer before starting. 882 * Otherwise it will underflow. 883 * After this call the state will be in AAUDIO_STREAM_STATE_STARTING or AAUDIO_STREAM_STATE_STARTED. 884 * 885 * @param stream reference provided by AAudioStreamBuilder_openStream() 886 * @return AAUDIO_OK or a negative error. 887 */ 888 AAUDIO_API aaudio_result_t AAudioStream_requestStart(AAudioStream* stream); 889 890 /** 891 * Asynchronous request for the stream to pause. 892 * Pausing a stream will freeze the data flow but not flush any buffers. 893 * Use AAudioStream_Start() to resume playback after a pause. 894 * After this call the state will be in AAUDIO_STREAM_STATE_PAUSING or AAUDIO_STREAM_STATE_PAUSED. 895 * 896 * This will return AAUDIO_ERROR_UNIMPLEMENTED for input streams. 897 * For input streams use AAudioStream_requestStop(). 898 * 899 * @param stream reference provided by AAudioStreamBuilder_openStream() 900 * @return AAUDIO_OK or a negative error. 901 */ 902 AAUDIO_API aaudio_result_t AAudioStream_requestPause(AAudioStream* stream); 903 904 /** 905 * Asynchronous request for the stream to flush. 906 * Flushing will discard any pending data. 907 * This call only works if the stream is pausing or paused. TODO review 908 * Frame counters are not reset by a flush. They may be advanced. 909 * After this call the state will be in AAUDIO_STREAM_STATE_FLUSHING or AAUDIO_STREAM_STATE_FLUSHED. 910 * 911 * This will return AAUDIO_ERROR_UNIMPLEMENTED for input streams. 912 * 913 * @param stream reference provided by AAudioStreamBuilder_openStream() 914 * @return AAUDIO_OK or a negative error. 915 */ 916 AAUDIO_API aaudio_result_t AAudioStream_requestFlush(AAudioStream* stream); 917 918 /** 919 * Asynchronous request for the stream to stop. 920 * The stream will stop after all of the data currently buffered has been played. 921 * After this call the state will be in AAUDIO_STREAM_STATE_STOPPING or AAUDIO_STREAM_STATE_STOPPED. 922 * 923 * @param stream reference provided by AAudioStreamBuilder_openStream() 924 * @return AAUDIO_OK or a negative error. 925 */ 926 AAUDIO_API aaudio_result_t AAudioStream_requestStop(AAudioStream* stream); 927 928 /** 929 * Query the current state of the client, eg. AAUDIO_STREAM_STATE_PAUSING 930 * 931 * This function will immediately return the state without updating the state. 932 * If you want to update the client state based on the server state then 933 * call AAudioStream_waitForStateChange() with currentState 934 * set to AAUDIO_STREAM_STATE_UNKNOWN and a zero timeout. 935 * 936 * @param stream reference provided by AAudioStreamBuilder_openStream() 937 */ 938 AAUDIO_API aaudio_stream_state_t AAudioStream_getState(AAudioStream* stream); 939 940 /** 941 * Wait until the current state no longer matches the input state. 942 * 943 * This will update the current client state. 944 * 945 * <pre><code> 946 * aaudio_result_t result = AAUDIO_OK; 947 * aaudio_stream_state_t currentState = AAudioStream_getState(stream); 948 * aaudio_stream_state_t inputState = currentState; 949 * while (result == AAUDIO_OK && currentState != AAUDIO_STREAM_STATE_PAUSED) { 950 * result = AAudioStream_waitForStateChange( 951 * stream, inputState, ¤tState, MY_TIMEOUT_NANOS); 952 * inputState = currentState; 953 * } 954 * </code></pre> 955 * 956 * @param stream A reference provided by AAudioStreamBuilder_openStream() 957 * @param inputState The state we want to avoid. 958 * @param nextState Pointer to a variable that will be set to the new state. 959 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. 960 * @return AAUDIO_OK or a negative error. 961 */ 962 AAUDIO_API aaudio_result_t AAudioStream_waitForStateChange(AAudioStream* stream, 963 aaudio_stream_state_t inputState, 964 aaudio_stream_state_t *nextState, 965 int64_t timeoutNanoseconds); 966 967 // ============================================================ 968 // Stream I/O 969 // ============================================================ 970 971 /** 972 * Read data from the stream. 973 * 974 * The call will wait until the read is complete or until it runs out of time. 975 * If timeoutNanos is zero then this call will not wait. 976 * 977 * Note that timeoutNanoseconds is a relative duration in wall clock time. 978 * Time will not stop if the thread is asleep. 979 * So it will be implemented using CLOCK_BOOTTIME. 980 * 981 * This call is "strong non-blocking" unless it has to wait for data. 982 * 983 * If the call times out then zero or a partial frame count will be returned. 984 * 985 * @param stream A stream created using AAudioStreamBuilder_openStream(). 986 * @param buffer The address of the first sample. 987 * @param numFrames Number of frames to read. Only complete frames will be written. 988 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. 989 * @return The number of frames actually read or a negative error. 990 */ 991 AAUDIO_API aaudio_result_t AAudioStream_read(AAudioStream* stream, 992 void *buffer, 993 int32_t numFrames, 994 int64_t timeoutNanoseconds); 995 996 /** 997 * Write data to the stream. 998 * 999 * The call will wait until the write is complete or until it runs out of time. 1000 * If timeoutNanos is zero then this call will not wait. 1001 * 1002 * Note that timeoutNanoseconds is a relative duration in wall clock time. 1003 * Time will not stop if the thread is asleep. 1004 * So it will be implemented using CLOCK_BOOTTIME. 1005 * 1006 * This call is "strong non-blocking" unless it has to wait for room in the buffer. 1007 * 1008 * If the call times out then zero or a partial frame count will be returned. 1009 * 1010 * @param stream A stream created using AAudioStreamBuilder_openStream(). 1011 * @param buffer The address of the first sample. 1012 * @param numFrames Number of frames to write. Only complete frames will be written. 1013 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. 1014 * @return The number of frames actually written or a negative error. 1015 */ 1016 AAUDIO_API aaudio_result_t AAudioStream_write(AAudioStream* stream, 1017 const void *buffer, 1018 int32_t numFrames, 1019 int64_t timeoutNanoseconds); 1020 1021 // ============================================================ 1022 // Stream - queries 1023 // ============================================================ 1024 1025 /** 1026 * This can be used to adjust the latency of the buffer by changing 1027 * the threshold where blocking will occur. 1028 * By combining this with AAudioStream_getXRunCount(), the latency can be tuned 1029 * at run-time for each device. 1030 * 1031 * This cannot be set higher than AAudioStream_getBufferCapacityInFrames(). 1032 * 1033 * Note that you will probably not get the exact size you request. 1034 * You can check the return value or call AAudioStream_getBufferSizeInFrames() 1035 * to see what the actual final size is. 1036 * 1037 * @param stream reference provided by AAudioStreamBuilder_openStream() 1038 * @param numFrames requested number of frames that can be filled without blocking 1039 * @return actual buffer size in frames or a negative error 1040 */ 1041 AAUDIO_API aaudio_result_t AAudioStream_setBufferSizeInFrames(AAudioStream* stream, 1042 int32_t numFrames); 1043 1044 /** 1045 * Query the maximum number of frames that can be filled without blocking. 1046 * 1047 * @param stream reference provided by AAudioStreamBuilder_openStream() 1048 * @return buffer size in frames. 1049 */ 1050 AAUDIO_API int32_t AAudioStream_getBufferSizeInFrames(AAudioStream* stream); 1051 1052 /** 1053 * Query the number of frames that the application should read or write at 1054 * one time for optimal performance. It is OK if an application writes 1055 * a different number of frames. But the buffer size may need to be larger 1056 * in order to avoid underruns or overruns. 1057 * 1058 * Note that this may or may not match the actual device burst size. 1059 * For some endpoints, the burst size can vary dynamically. 1060 * But these tend to be devices with high latency. 1061 * 1062 * @param stream reference provided by AAudioStreamBuilder_openStream() 1063 * @return burst size 1064 */ 1065 AAUDIO_API int32_t AAudioStream_getFramesPerBurst(AAudioStream* stream); 1066 1067 /** 1068 * Query maximum buffer capacity in frames. 1069 * 1070 * @param stream reference provided by AAudioStreamBuilder_openStream() 1071 * @return buffer capacity in frames 1072 */ 1073 AAUDIO_API int32_t AAudioStream_getBufferCapacityInFrames(AAudioStream* stream); 1074 1075 /** 1076 * Query the size of the buffer that will be passed to the dataProc callback 1077 * in the numFrames parameter. 1078 * 1079 * This call can be used if the application needs to know the value of numFrames before 1080 * the stream is started. This is not normally necessary. 1081 * 1082 * If a specific size was requested by calling AAudioStreamBuilder_setFramesPerDataCallback() 1083 * then this will be the same size. 1084 * 1085 * If AAudioStreamBuilder_setFramesPerDataCallback() was not called then this will 1086 * return the size chosen by AAudio, or AAUDIO_UNSPECIFIED. 1087 * 1088 * AAUDIO_UNSPECIFIED indicates that the callback buffer size for this stream 1089 * may vary from one dataProc callback to the next. 1090 * 1091 * @param stream reference provided by AAudioStreamBuilder_openStream() 1092 * @return callback buffer size in frames or AAUDIO_UNSPECIFIED 1093 */ 1094 AAUDIO_API int32_t AAudioStream_getFramesPerDataCallback(AAudioStream* stream); 1095 1096 /** 1097 * An XRun is an Underrun or an Overrun. 1098 * During playing, an underrun will occur if the stream is not written in time 1099 * and the system runs out of valid data. 1100 * During recording, an overrun will occur if the stream is not read in time 1101 * and there is no place to put the incoming data so it is discarded. 1102 * 1103 * An underrun or overrun can cause an audible "pop" or "glitch". 1104 * 1105 * Note that some INPUT devices may not support this function. 1106 * In that case a 0 will always be returned. 1107 * 1108 * @param stream reference provided by AAudioStreamBuilder_openStream() 1109 * @return the underrun or overrun count 1110 */ 1111 AAUDIO_API int32_t AAudioStream_getXRunCount(AAudioStream* stream); 1112 1113 /** 1114 * @param stream reference provided by AAudioStreamBuilder_openStream() 1115 * @return actual sample rate 1116 */ 1117 AAUDIO_API int32_t AAudioStream_getSampleRate(AAudioStream* stream); 1118 1119 /** 1120 * A stream has one or more channels of data. 1121 * A frame will contain one sample for each channel. 1122 * 1123 * @param stream reference provided by AAudioStreamBuilder_openStream() 1124 * @return actual number of channels 1125 */ 1126 AAUDIO_API int32_t AAudioStream_getChannelCount(AAudioStream* stream); 1127 1128 /** 1129 * Identical to AAudioStream_getChannelCount(). 1130 * 1131 * @param stream reference provided by AAudioStreamBuilder_openStream() 1132 * @return actual number of samples frame 1133 */ 1134 AAUDIO_API int32_t AAudioStream_getSamplesPerFrame(AAudioStream* stream); 1135 1136 /** 1137 * @param stream reference provided by AAudioStreamBuilder_openStream() 1138 * @return actual device ID 1139 */ 1140 AAUDIO_API int32_t AAudioStream_getDeviceId(AAudioStream* stream); 1141 1142 /** 1143 * @param stream reference provided by AAudioStreamBuilder_openStream() 1144 * @return actual data format 1145 */ 1146 AAUDIO_API aaudio_format_t AAudioStream_getFormat(AAudioStream* stream); 1147 1148 /** 1149 * Provide actual sharing mode. 1150 * @param stream reference provided by AAudioStreamBuilder_openStream() 1151 * @return actual sharing mode 1152 */ 1153 AAUDIO_API aaudio_sharing_mode_t AAudioStream_getSharingMode(AAudioStream* stream); 1154 1155 /** 1156 * Get the performance mode used by the stream. 1157 * 1158 * @param stream reference provided by AAudioStreamBuilder_openStream() 1159 */ 1160 AAUDIO_API aaudio_performance_mode_t AAudioStream_getPerformanceMode(AAudioStream* stream); 1161 1162 /** 1163 * @param stream reference provided by AAudioStreamBuilder_openStream() 1164 * @return direction 1165 */ 1166 AAUDIO_API aaudio_direction_t AAudioStream_getDirection(AAudioStream* stream); 1167 1168 /** 1169 * Passes back the number of frames that have been written since the stream was created. 1170 * For an output stream, this will be advanced by the application calling write() 1171 * or by a data callback. 1172 * For an input stream, this will be advanced by the endpoint. 1173 * 1174 * The frame position is monotonically increasing. 1175 * 1176 * @param stream reference provided by AAudioStreamBuilder_openStream() 1177 * @return frames written 1178 */ 1179 AAUDIO_API int64_t AAudioStream_getFramesWritten(AAudioStream* stream); 1180 1181 /** 1182 * Passes back the number of frames that have been read since the stream was created. 1183 * For an output stream, this will be advanced by the endpoint. 1184 * For an input stream, this will be advanced by the application calling read() 1185 * or by a data callback. 1186 * 1187 * The frame position is monotonically increasing. 1188 * 1189 * @param stream reference provided by AAudioStreamBuilder_openStream() 1190 * @return frames read 1191 */ 1192 AAUDIO_API int64_t AAudioStream_getFramesRead(AAudioStream* stream); 1193 1194 /** 1195 * Passes back the session ID associated with this stream. 1196 * 1197 * The session ID can be used to associate a stream with effects processors. 1198 * The effects are controlled using the Android AudioEffect Java API. 1199 * 1200 * If AAudioStreamBuilder_setSessionId() was called with AAUDIO_SESSION_ID_ALLOCATE 1201 * then a new session ID should be allocated once when the stream is opened. 1202 * 1203 * If AAudioStreamBuilder_setSessionId() was called with a previously allocated 1204 * session ID then that value should be returned. 1205 * 1206 * If AAudioStreamBuilder_setSessionId() was not called then this function should 1207 * return AAUDIO_SESSION_ID_NONE. 1208 * 1209 * The sessionID for a stream should not change once the stream has been opened. 1210 * 1211 * Added in API level 28. 1212 * 1213 * @param stream reference provided by AAudioStreamBuilder_openStream() 1214 * @return session ID or AAUDIO_SESSION_ID_NONE 1215 */ 1216 AAUDIO_API aaudio_session_id_t AAudioStream_getSessionId(AAudioStream* stream); 1217 1218 /** 1219 * Passes back the time at which a particular frame was presented. 1220 * This can be used to synchronize audio with video or MIDI. 1221 * It can also be used to align a recorded stream with a playback stream. 1222 * 1223 * Timestamps are only valid when the stream is in AAUDIO_STREAM_STATE_STARTED. 1224 * AAUDIO_ERROR_INVALID_STATE will be returned if the stream is not started. 1225 * Note that because requestStart() is asynchronous, timestamps will not be valid until 1226 * a short time after calling requestStart(). 1227 * So AAUDIO_ERROR_INVALID_STATE should not be considered a fatal error. 1228 * Just try calling again later. 1229 * 1230 * If an error occurs, then the position and time will not be modified. 1231 * 1232 * The position and time passed back are monotonically increasing. 1233 * 1234 * @param stream reference provided by AAudioStreamBuilder_openStream() 1235 * @param clockid CLOCK_MONOTONIC or CLOCK_BOOTTIME 1236 * @param framePosition pointer to a variable to receive the position 1237 * @param timeNanoseconds pointer to a variable to receive the time 1238 * @return AAUDIO_OK or a negative error 1239 */ 1240 AAUDIO_API aaudio_result_t AAudioStream_getTimestamp(AAudioStream* stream, 1241 clockid_t clockid, 1242 int64_t *framePosition, 1243 int64_t *timeNanoseconds); 1244 1245 /** 1246 * Return the use case for the stream. 1247 * 1248 * Added in API level 28. 1249 * 1250 * @param stream reference provided by AAudioStreamBuilder_openStream() 1251 * @return frames read 1252 */ 1253 AAUDIO_API aaudio_usage_t AAudioStream_getUsage(AAudioStream* stream); 1254 1255 /** 1256 * Return the content type for the stream. 1257 * 1258 * Added in API level 28. 1259 * 1260 * @param stream reference provided by AAudioStreamBuilder_openStream() 1261 * @return content type, for example AAUDIO_CONTENT_TYPE_MUSIC 1262 */ 1263 AAUDIO_API aaudio_content_type_t AAudioStream_getContentType(AAudioStream* stream); 1264 1265 /** 1266 * Return the input preset for the stream. 1267 * 1268 * Added in API level 28. 1269 * 1270 * @param stream reference provided by AAudioStreamBuilder_openStream() 1271 * @return input preset, for example AAUDIO_INPUT_PRESET_CAMCORDER 1272 */ 1273 AAUDIO_API aaudio_input_preset_t AAudioStream_getInputPreset(AAudioStream* stream); 1274 1275 #ifdef __cplusplus 1276 } 1277 #endif 1278 1279 #endif //AAUDIO_AAUDIO_H 1280 1281 /** @} */ 1282