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 <stdbool.h> 33 #include <stdint.h> 34 #include <time.h> 35 36 #ifdef __cplusplus 37 extern "C" { 38 #endif 39 40 /** 41 * This is used to represent a value that has not been specified. 42 * For example, an application could use {@link #AAUDIO_UNSPECIFIED} to indicate 43 * that is did not not care what the specific value of a parameter was 44 * and would accept whatever it was given. 45 */ 46 #define AAUDIO_UNSPECIFIED 0 47 48 enum { 49 /** 50 * Audio data will travel out of the device, for example through a speaker. 51 */ 52 AAUDIO_DIRECTION_OUTPUT, 53 54 55 /** 56 * Audio data will travel into the device, for example from a microphone. 57 */ 58 AAUDIO_DIRECTION_INPUT 59 }; 60 typedef int32_t aaudio_direction_t; 61 62 enum { 63 AAUDIO_FORMAT_INVALID = -1, 64 AAUDIO_FORMAT_UNSPECIFIED = 0, 65 66 /** 67 * This format uses the int16_t data type. 68 * The maximum range of the data is -32768 (0x8000) to 32767 (0x7FFF). 69 */ 70 AAUDIO_FORMAT_PCM_I16, 71 72 /** 73 * This format uses the float data type. 74 * The nominal range of the data is [-1.0f, 1.0f). 75 * Values outside that range may be clipped. 76 * 77 * See also the float Data in 78 * <a href="/reference/android/media/AudioTrack#write(float[],%20int,%20int,%20int)"> 79 * write(float[], int, int, int)</a>. 80 */ 81 AAUDIO_FORMAT_PCM_FLOAT, 82 83 /** 84 * This format uses 24-bit samples packed into 3 bytes. 85 * The bytes are in little-endian order, so the least significant byte 86 * comes first in the byte array. 87 * 88 * The maximum range of the data is -8388608 (0x800000) 89 * to 8388607 (0x7FFFFF). 90 * 91 * Note that the lower precision bits may be ignored by the device. 92 * 93 * Available since API level 31. 94 */ 95 AAUDIO_FORMAT_PCM_I24_PACKED, 96 97 /** 98 * This format uses 32-bit samples stored in an int32_t data type. 99 * The maximum range of the data is -2147483648 (0x80000000) 100 * to 2147483647 (0x7FFFFFFF). 101 * 102 * Note that the lower precision bits may be ignored by the device. 103 * 104 * Available since API level 31. 105 */ 106 AAUDIO_FORMAT_PCM_I32 107 108 }; 109 typedef int32_t aaudio_format_t; 110 111 /** 112 * These result codes are returned from AAudio functions to indicate success or failure. 113 * Note that error return codes may change in the future so applications should generally 114 * not rely on specific return codes. 115 */ 116 enum { 117 /** 118 * The call was successful. 119 */ 120 AAUDIO_OK, 121 AAUDIO_ERROR_BASE = -900, // TODO review 122 123 /** 124 * The audio device was disconnected. This could occur, for example, when headphones 125 * are plugged in or unplugged. The stream cannot be used after the device is disconnected. 126 * Applications should stop and close the stream. 127 * If this error is received in an error callback then another thread should be 128 * used to stop and close the stream. 129 */ 130 AAUDIO_ERROR_DISCONNECTED, 131 132 /** 133 * An invalid parameter was passed to AAudio. 134 */ 135 AAUDIO_ERROR_ILLEGAL_ARGUMENT, 136 // reserved 137 AAUDIO_ERROR_INTERNAL = AAUDIO_ERROR_ILLEGAL_ARGUMENT + 2, 138 139 /** 140 * The requested operation is not appropriate for the current state of AAudio. 141 */ 142 AAUDIO_ERROR_INVALID_STATE, 143 // reserved 144 // reserved 145 /* The server rejected the handle used to identify the stream. 146 */ 147 AAUDIO_ERROR_INVALID_HANDLE = AAUDIO_ERROR_INVALID_STATE + 3, 148 // reserved 149 150 /** 151 * The function is not implemented for this stream. 152 */ 153 AAUDIO_ERROR_UNIMPLEMENTED = AAUDIO_ERROR_INVALID_HANDLE + 2, 154 155 /** 156 * A resource or information is unavailable. 157 * This could occur when an application tries to open too many streams, 158 * or a timestamp is not available. 159 */ 160 AAUDIO_ERROR_UNAVAILABLE, 161 AAUDIO_ERROR_NO_FREE_HANDLES, 162 163 /** 164 * Memory could not be allocated. 165 */ 166 AAUDIO_ERROR_NO_MEMORY, 167 168 /** 169 * A NULL pointer was passed to AAudio. 170 * Or a NULL pointer was detected internally. 171 */ 172 AAUDIO_ERROR_NULL, 173 174 /** 175 * An operation took longer than expected. 176 */ 177 AAUDIO_ERROR_TIMEOUT, 178 AAUDIO_ERROR_WOULD_BLOCK, 179 180 /** 181 * The requested data format is not supported. 182 */ 183 AAUDIO_ERROR_INVALID_FORMAT, 184 185 /** 186 * A requested was out of range. 187 */ 188 AAUDIO_ERROR_OUT_OF_RANGE, 189 190 /** 191 * The audio service was not available. 192 */ 193 AAUDIO_ERROR_NO_SERVICE, 194 195 /** 196 * The requested sample rate was not supported. 197 */ 198 AAUDIO_ERROR_INVALID_RATE 199 }; 200 typedef int32_t aaudio_result_t; 201 202 /** 203 * AAudio Stream states, for details, refer to 204 * <a href="/ndk/guides/audio/aaudio/aaudio#using-streams">Using an Audio Stream</a> 205 */ 206 enum 207 { 208 209 /** 210 * The stream is created but not initialized yet. 211 */ 212 AAUDIO_STREAM_STATE_UNINITIALIZED = 0, 213 /** 214 * The stream is in an unrecognized state. 215 */ 216 AAUDIO_STREAM_STATE_UNKNOWN, 217 218 /** 219 * The stream is open and ready to use. 220 */ 221 AAUDIO_STREAM_STATE_OPEN, 222 /** 223 * The stream is just starting up. 224 */ 225 AAUDIO_STREAM_STATE_STARTING, 226 /** 227 * The stream has started. 228 */ 229 AAUDIO_STREAM_STATE_STARTED, 230 /** 231 * The stream is pausing. 232 */ 233 AAUDIO_STREAM_STATE_PAUSING, 234 /** 235 * The stream has paused, could be restarted or flushed. 236 */ 237 AAUDIO_STREAM_STATE_PAUSED, 238 /** 239 * The stream is being flushed. 240 */ 241 AAUDIO_STREAM_STATE_FLUSHING, 242 /** 243 * The stream is flushed, ready to be restarted. 244 */ 245 AAUDIO_STREAM_STATE_FLUSHED, 246 /** 247 * The stream is stopping. 248 */ 249 AAUDIO_STREAM_STATE_STOPPING, 250 /** 251 * The stream has been stopped. 252 */ 253 AAUDIO_STREAM_STATE_STOPPED, 254 /** 255 * The stream is closing. 256 */ 257 AAUDIO_STREAM_STATE_CLOSING, 258 /** 259 * The stream has been closed. 260 */ 261 AAUDIO_STREAM_STATE_CLOSED, 262 /** 263 * The stream is disconnected from audio device. 264 */ 265 AAUDIO_STREAM_STATE_DISCONNECTED 266 }; 267 typedef int32_t aaudio_stream_state_t; 268 269 270 enum { 271 /** 272 * This will be the only stream using a particular source or sink. 273 * This mode will provide the lowest possible latency. 274 * You should close EXCLUSIVE streams immediately when you are not using them. 275 */ 276 AAUDIO_SHARING_MODE_EXCLUSIVE, 277 /** 278 * Multiple applications will be mixed by the AAudio Server. 279 * This will have higher latency than the EXCLUSIVE mode. 280 */ 281 AAUDIO_SHARING_MODE_SHARED 282 }; 283 typedef int32_t aaudio_sharing_mode_t; 284 285 286 enum { 287 /** 288 * No particular performance needs. Default. 289 */ 290 AAUDIO_PERFORMANCE_MODE_NONE = 10, 291 292 /** 293 * Extending battery life is more important than low latency. 294 * 295 * This mode is not supported in input streams. 296 * For input, mode NONE will be used if this is requested. 297 */ 298 AAUDIO_PERFORMANCE_MODE_POWER_SAVING, 299 300 /** 301 * Reducing latency is more important than battery life. 302 */ 303 AAUDIO_PERFORMANCE_MODE_LOW_LATENCY 304 }; 305 typedef int32_t aaudio_performance_mode_t; 306 307 #define AAUDIO_SYSTEM_USAGE_OFFSET 1000 308 309 /** 310 * The USAGE attribute expresses "why" you are playing a sound, what is this sound used for. 311 * This information is used by certain platforms or routing policies 312 * to make more refined volume or routing decisions. 313 * 314 * Note that these match the equivalent values in 315 * <a href="/reference/android/media/AudioAttributes">AudioAttributes</a> 316 * in the Android Java API. 317 * 318 * Added in API level 28. 319 */ 320 enum { 321 /** 322 * Use this for streaming media, music performance, video, podcasts, etcetera. 323 */ 324 AAUDIO_USAGE_MEDIA = 1, 325 326 /** 327 * Use this for voice over IP, telephony, etcetera. 328 */ 329 AAUDIO_USAGE_VOICE_COMMUNICATION = 2, 330 331 /** 332 * Use this for sounds associated with telephony such as busy tones, DTMF, etcetera. 333 */ 334 AAUDIO_USAGE_VOICE_COMMUNICATION_SIGNALLING = 3, 335 336 /** 337 * Use this to demand the users attention. 338 */ 339 AAUDIO_USAGE_ALARM = 4, 340 341 /** 342 * Use this for notifying the user when a message has arrived or some 343 * other background event has occured. 344 */ 345 AAUDIO_USAGE_NOTIFICATION = 5, 346 347 /** 348 * Use this when the phone rings. 349 */ 350 AAUDIO_USAGE_NOTIFICATION_RINGTONE = 6, 351 352 /** 353 * Use this to attract the users attention when, for example, the battery is low. 354 */ 355 AAUDIO_USAGE_NOTIFICATION_EVENT = 10, 356 357 /** 358 * Use this for screen readers, etcetera. 359 */ 360 AAUDIO_USAGE_ASSISTANCE_ACCESSIBILITY = 11, 361 362 /** 363 * Use this for driving or navigation directions. 364 */ 365 AAUDIO_USAGE_ASSISTANCE_NAVIGATION_GUIDANCE = 12, 366 367 /** 368 * Use this for user interface sounds, beeps, etcetera. 369 */ 370 AAUDIO_USAGE_ASSISTANCE_SONIFICATION = 13, 371 372 /** 373 * Use this for game audio and sound effects. 374 */ 375 AAUDIO_USAGE_GAME = 14, 376 377 /** 378 * Use this for audio responses to user queries, audio instructions or help utterances. 379 */ 380 AAUDIO_USAGE_ASSISTANT = 16, 381 382 /** 383 * Use this in case of playing sounds in an emergency. 384 * Privileged MODIFY_AUDIO_ROUTING permission required. 385 */ 386 AAUDIO_SYSTEM_USAGE_EMERGENCY = AAUDIO_SYSTEM_USAGE_OFFSET, 387 388 /** 389 * Use this for safety sounds and alerts, for example backup camera obstacle detection. 390 * Privileged MODIFY_AUDIO_ROUTING permission required. 391 */ 392 AAUDIO_SYSTEM_USAGE_SAFETY = AAUDIO_SYSTEM_USAGE_OFFSET + 1, 393 394 /** 395 * Use this for vehicle status alerts and information, for example the check engine light. 396 * Privileged MODIFY_AUDIO_ROUTING permission required. 397 */ 398 AAUDIO_SYSTEM_USAGE_VEHICLE_STATUS = AAUDIO_SYSTEM_USAGE_OFFSET + 2, 399 400 /** 401 * Use this for traffic announcements, etc. 402 * Privileged MODIFY_AUDIO_ROUTING permission required. 403 */ 404 AAUDIO_SYSTEM_USAGE_ANNOUNCEMENT = AAUDIO_SYSTEM_USAGE_OFFSET + 3, 405 }; 406 typedef int32_t aaudio_usage_t; 407 408 /** 409 * The CONTENT_TYPE attribute describes "what" you are playing. 410 * It expresses the general category of the content. This information is optional. 411 * But in case it is known (for instance AAUDIO_CONTENT_TYPE_MOVIE for a 412 * movie streaming service or AAUDIO_CONTENT_TYPE_SPEECH for 413 * an audio book application) this information might be used by the audio framework to 414 * enforce audio focus. 415 * 416 * Note that these match the equivalent values in 417 * <a href="/reference/android/media/AudioAttributes">AudioAttributes</a> 418 * in the Android Java API. 419 * 420 * Added in API level 28. 421 */ 422 enum { 423 424 /** 425 * Use this for spoken voice, audio books, etcetera. 426 */ 427 AAUDIO_CONTENT_TYPE_SPEECH = 1, 428 429 /** 430 * Use this for pre-recorded or live music. 431 */ 432 AAUDIO_CONTENT_TYPE_MUSIC = 2, 433 434 /** 435 * Use this for a movie or video soundtrack. 436 */ 437 AAUDIO_CONTENT_TYPE_MOVIE = 3, 438 439 /** 440 * Use this for sound is designed to accompany a user action, 441 * such as a click or beep sound made when the user presses a button. 442 */ 443 AAUDIO_CONTENT_TYPE_SONIFICATION = 4 444 }; 445 typedef int32_t aaudio_content_type_t; 446 447 /** 448 * Defines the audio source. 449 * An audio source defines both a default physical source of audio signal, and a recording 450 * configuration. 451 * 452 * Note that these match the equivalent values in MediaRecorder.AudioSource in the Android Java API. 453 * 454 * Added in API level 28. 455 */ 456 enum { 457 /** 458 * Use this preset when other presets do not apply. 459 */ 460 AAUDIO_INPUT_PRESET_GENERIC = 1, 461 462 /** 463 * Use this preset when recording video. 464 */ 465 AAUDIO_INPUT_PRESET_CAMCORDER = 5, 466 467 /** 468 * Use this preset when doing speech recognition. 469 */ 470 AAUDIO_INPUT_PRESET_VOICE_RECOGNITION = 6, 471 472 /** 473 * Use this preset when doing telephony or voice messaging. 474 */ 475 AAUDIO_INPUT_PRESET_VOICE_COMMUNICATION = 7, 476 477 /** 478 * Use this preset to obtain an input with no effects. 479 * Note that this input will not have automatic gain control 480 * so the recorded volume may be very low. 481 */ 482 AAUDIO_INPUT_PRESET_UNPROCESSED = 9, 483 484 /** 485 * Use this preset for capturing audio meant to be processed in real time 486 * and played back for live performance (e.g karaoke). 487 * The capture path will minimize latency and coupling with playback path. 488 * Available since API level 29. 489 */ 490 AAUDIO_INPUT_PRESET_VOICE_PERFORMANCE = 10, 491 }; 492 typedef int32_t aaudio_input_preset_t; 493 494 /** 495 * Specifying if audio may or may not be captured by other apps or the system. 496 * 497 * Note that these match the equivalent values in 498 * <a href="/reference/android/media/AudioAttributes">AudioAttributes</a> 499 * in the Android Java API. 500 * 501 * Added in API level 29. 502 */ 503 enum { 504 /** 505 * Indicates that the audio may be captured by any app. 506 * 507 * For privacy, the following usages can not be recorded: AAUDIO_VOICE_COMMUNICATION*, 508 * AAUDIO_USAGE_NOTIFICATION*, AAUDIO_USAGE_ASSISTANCE* and {@link #AAUDIO_USAGE_ASSISTANT}. 509 * 510 * On <a href="/reference/android/os/Build.VERSION_CODES#Q">Build.VERSION_CODES</a>, 511 * this means only {@link #AAUDIO_USAGE_MEDIA} and {@link #AAUDIO_USAGE_GAME} may be captured. 512 * 513 * See <a href="/reference/android/media/AudioAttributes.html#ALLOW_CAPTURE_BY_ALL"> 514 * ALLOW_CAPTURE_BY_ALL</a>. 515 */ 516 AAUDIO_ALLOW_CAPTURE_BY_ALL = 1, 517 /** 518 * Indicates that the audio may only be captured by system apps. 519 * 520 * System apps can capture for many purposes like accessibility, user guidance... 521 * but have strong restriction. See 522 * <a href="/reference/android/media/AudioAttributes.html#ALLOW_CAPTURE_BY_SYSTEM"> 523 * ALLOW_CAPTURE_BY_SYSTEM</a> 524 * for what the system apps can do with the capture audio. 525 */ 526 AAUDIO_ALLOW_CAPTURE_BY_SYSTEM = 2, 527 /** 528 * Indicates that the audio may not be recorded by any app, even if it is a system app. 529 * 530 * It is encouraged to use {@link #AAUDIO_ALLOW_CAPTURE_BY_SYSTEM} instead of this value as system apps 531 * provide significant and useful features for the user (eg. accessibility). 532 * See <a href="/reference/android/media/AudioAttributes.html#ALLOW_CAPTURE_BY_NONE"> 533 * ALLOW_CAPTURE_BY_NONE</a>. 534 */ 535 AAUDIO_ALLOW_CAPTURE_BY_NONE = 3, 536 }; 537 538 typedef int32_t aaudio_allowed_capture_policy_t; 539 540 /** 541 * These may be used with AAudioStreamBuilder_setSessionId(). 542 * 543 * Added in API level 28. 544 */ 545 enum { 546 /** 547 * Do not allocate a session ID. 548 * Effects cannot be used with this stream. 549 * Default. 550 * 551 * Added in API level 28. 552 */ 553 AAUDIO_SESSION_ID_NONE = -1, 554 555 /** 556 * Allocate a session ID that can be used to attach and control 557 * effects using the Java AudioEffects API. 558 * Note that using this may result in higher latency. 559 * 560 * Note that this matches the value of AudioManager.AUDIO_SESSION_ID_GENERATE. 561 * 562 * Added in API level 28. 563 */ 564 AAUDIO_SESSION_ID_ALLOCATE = 0, 565 }; 566 typedef int32_t aaudio_session_id_t; 567 568 typedef struct AAudioStreamStruct AAudioStream; 569 typedef struct AAudioStreamBuilderStruct AAudioStreamBuilder; 570 571 #ifndef AAUDIO_API 572 #define AAUDIO_API /* export this symbol */ 573 #endif 574 575 // ============================================================ 576 // Audio System 577 // ============================================================ 578 579 /** 580 * The text is the ASCII symbol corresponding to the returnCode, 581 * or an English message saying the returnCode is unrecognized. 582 * This is intended for developers to use when debugging. 583 * It is not for display to users. 584 * 585 * Available since API level 26. 586 * 587 * @return pointer to a text representation of an AAudio result code. 588 */ 589 AAUDIO_API const char * AAudio_convertResultToText(aaudio_result_t returnCode) __INTRODUCED_IN(26); 590 591 /** 592 * The text is the ASCII symbol corresponding to the stream state, 593 * or an English message saying the state is unrecognized. 594 * This is intended for developers to use when debugging. 595 * It is not for display to users. 596 * 597 * Available since API level 26. 598 * 599 * @return pointer to a text representation of an AAudio state. 600 */ 601 AAUDIO_API const char * AAudio_convertStreamStateToText(aaudio_stream_state_t state) 602 __INTRODUCED_IN(26); 603 604 // ============================================================ 605 // StreamBuilder 606 // ============================================================ 607 608 /** 609 * Create a StreamBuilder that can be used to open a Stream. 610 * 611 * The deviceId is initially unspecified, meaning that the current default device will be used. 612 * 613 * The default direction is {@link #AAUDIO_DIRECTION_OUTPUT}. 614 * The default sharing mode is {@link #AAUDIO_SHARING_MODE_SHARED}. 615 * The data format, samplesPerFrames and sampleRate are unspecified and will be 616 * chosen by the device when it is opened. 617 * 618 * AAudioStreamBuilder_delete() must be called when you are done using the builder. 619 * 620 * Available since API level 26. 621 */ 622 AAUDIO_API aaudio_result_t AAudio_createStreamBuilder(AAudioStreamBuilder** builder) 623 __INTRODUCED_IN(26); 624 625 /** 626 * Request an audio device identified device using an ID. 627 * On Android, for example, the ID could be obtained from the Java AudioManager. 628 * 629 * The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED}, 630 * in which case the primary device will be used. 631 * 632 * Available since API level 26. 633 * 634 * @param builder reference provided by AAudio_createStreamBuilder() 635 * @param deviceId device identifier or {@link #AAUDIO_UNSPECIFIED} 636 */ 637 AAUDIO_API void AAudioStreamBuilder_setDeviceId(AAudioStreamBuilder* builder, 638 int32_t deviceId) __INTRODUCED_IN(26); 639 640 /** 641 * Declare the name of the package creating the stream. 642 * 643 * This is usually {@code Context#getPackageName()}. 644 * 645 * The default, if you do not call this function, is a random package in the calling uid. 646 * The vast majority of apps have only one package per calling UID. If the package 647 * name does not match the calling UID, then requests will be rejected. 648 * 649 * Available since API level 31. 650 * 651 * @param builder reference provided by AAudio_createStreamBuilder() 652 * @param packageName packageName of the calling app. 653 */ 654 AAUDIO_API void AAudioStreamBuilder_setPackageName(AAudioStreamBuilder* builder, 655 const char * packageName) __INTRODUCED_IN(31); 656 657 /** 658 * Declare the attribution tag of the context creating the stream. 659 * 660 * This is usually {@code Context#getAttributionTag()}. 661 * 662 * The default, if you do not call this function, is null. 663 * 664 * Available since API level 31. 665 * 666 * @param builder reference provided by AAudio_createStreamBuilder() 667 * @param attributionTag attributionTag of the calling context. 668 */ 669 AAUDIO_API void AAudioStreamBuilder_setAttributionTag(AAudioStreamBuilder* builder, 670 const char * attributionTag) __INTRODUCED_IN(31); 671 672 /** 673 * Request a sample rate in Hertz. 674 * 675 * The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED}. 676 * An optimal value will then be chosen when the stream is opened. 677 * After opening a stream with an unspecified value, the application must 678 * query for the actual value, which may vary by device. 679 * 680 * If an exact value is specified then an opened stream will use that value. 681 * If a stream cannot be opened with the specified value then the open will fail. 682 * 683 * Available since API level 26. 684 * 685 * @param builder reference provided by AAudio_createStreamBuilder() 686 * @param sampleRate frames per second. Common rates include 44100 and 48000 Hz. 687 */ 688 AAUDIO_API void AAudioStreamBuilder_setSampleRate(AAudioStreamBuilder* builder, 689 int32_t sampleRate) __INTRODUCED_IN(26); 690 691 /** 692 * Request a number of channels for the stream. 693 * 694 * The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED}. 695 * An optimal value will then be chosen when the stream is opened. 696 * After opening a stream with an unspecified value, the application must 697 * query for the actual value, which may vary by device. 698 * 699 * If an exact value is specified then an opened stream will use that value. 700 * If a stream cannot be opened with the specified value then the open will fail. 701 * 702 * Available since API level 26. 703 * 704 * @param builder reference provided by AAudio_createStreamBuilder() 705 * @param channelCount Number of channels desired. 706 */ 707 AAUDIO_API void AAudioStreamBuilder_setChannelCount(AAudioStreamBuilder* builder, 708 int32_t channelCount) __INTRODUCED_IN(26); 709 710 /** 711 * Identical to AAudioStreamBuilder_setChannelCount(). 712 * 713 * Available since API level 26. 714 * 715 * @param builder reference provided by AAudio_createStreamBuilder() 716 * @param samplesPerFrame Number of samples in a frame. 717 */ 718 AAUDIO_API void AAudioStreamBuilder_setSamplesPerFrame(AAudioStreamBuilder* builder, 719 int32_t samplesPerFrame) __INTRODUCED_IN(26); 720 721 /** 722 * Request a sample data format, for example {@link #AAUDIO_FORMAT_PCM_I16}. 723 * 724 * The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED}. 725 * An optimal value will then be chosen when the stream is opened. 726 * After opening a stream with an unspecified value, the application must 727 * query for the actual value, which may vary by device. 728 * 729 * If an exact value is specified then an opened stream will use that value. 730 * If a stream cannot be opened with the specified value then the open will fail. 731 * 732 * Available since API level 26. 733 * 734 * @param builder reference provided by AAudio_createStreamBuilder() 735 * @param format common formats are {@link #AAUDIO_FORMAT_PCM_FLOAT} and 736 * {@link #AAUDIO_FORMAT_PCM_I16}. 737 */ 738 AAUDIO_API void AAudioStreamBuilder_setFormat(AAudioStreamBuilder* builder, 739 aaudio_format_t format) __INTRODUCED_IN(26); 740 741 /** 742 * Request a mode for sharing the device. 743 * 744 * The default, if you do not call this function, is {@link #AAUDIO_SHARING_MODE_SHARED}. 745 * 746 * The requested sharing mode may not be available. 747 * The application can query for the actual mode after the stream is opened. 748 * 749 * Available since API level 26. 750 * 751 * @param builder reference provided by AAudio_createStreamBuilder() 752 * @param sharingMode {@link #AAUDIO_SHARING_MODE_SHARED} or {@link #AAUDIO_SHARING_MODE_EXCLUSIVE} 753 */ 754 AAUDIO_API void AAudioStreamBuilder_setSharingMode(AAudioStreamBuilder* builder, 755 aaudio_sharing_mode_t sharingMode) __INTRODUCED_IN(26); 756 757 /** 758 * Request the direction for a stream. 759 * 760 * The default, if you do not call this function, is {@link #AAUDIO_DIRECTION_OUTPUT}. 761 * 762 * Available since API level 26. 763 * 764 * @param builder reference provided by AAudio_createStreamBuilder() 765 * @param direction {@link #AAUDIO_DIRECTION_OUTPUT} or {@link #AAUDIO_DIRECTION_INPUT} 766 */ 767 AAUDIO_API void AAudioStreamBuilder_setDirection(AAudioStreamBuilder* builder, 768 aaudio_direction_t direction) __INTRODUCED_IN(26); 769 770 /** 771 * Set the requested buffer capacity in frames. 772 * The final AAudioStream capacity may differ, but will probably be at least this big. 773 * 774 * The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED}. 775 * 776 * Available since API level 26. 777 * 778 * @param builder reference provided by AAudio_createStreamBuilder() 779 * @param numFrames the desired buffer capacity in frames or {@link #AAUDIO_UNSPECIFIED} 780 */ 781 AAUDIO_API void AAudioStreamBuilder_setBufferCapacityInFrames(AAudioStreamBuilder* builder, 782 int32_t numFrames) __INTRODUCED_IN(26); 783 784 /** 785 * Set the requested performance mode. 786 * 787 * Supported modes are {@link #AAUDIO_PERFORMANCE_MODE_NONE}, 788 * {@link #AAUDIO_PERFORMANCE_MODE_POWER_SAVING} * and {@link #AAUDIO_PERFORMANCE_MODE_LOW_LATENCY}. 789 * 790 * The default, if you do not call this function, is {@link #AAUDIO_PERFORMANCE_MODE_NONE}. 791 * 792 * You may not get the mode you requested. 793 * You can call AAudioStream_getPerformanceMode() 794 * to find out the final mode for the stream. 795 * 796 * Available since API level 26. 797 * 798 * @param builder reference provided by AAudio_createStreamBuilder() 799 * @param mode the desired performance mode, eg. {@link #AAUDIO_PERFORMANCE_MODE_LOW_LATENCY} 800 */ 801 AAUDIO_API void AAudioStreamBuilder_setPerformanceMode(AAudioStreamBuilder* builder, 802 aaudio_performance_mode_t mode) __INTRODUCED_IN(26); 803 804 /** 805 * Set the intended use case for the output stream. 806 * 807 * The AAudio system will use this information to optimize the 808 * behavior of the stream. 809 * This could, for example, affect how volume and focus is handled for the stream. 810 * 811 * The default, if you do not call this function, is {@link #AAUDIO_USAGE_MEDIA}. 812 * 813 * Available since API level 28. 814 * 815 * @param builder reference provided by AAudio_createStreamBuilder() 816 * @param usage the desired usage, eg. {@link #AAUDIO_USAGE_GAME} 817 */ 818 AAUDIO_API void AAudioStreamBuilder_setUsage(AAudioStreamBuilder* builder, 819 aaudio_usage_t usage) __INTRODUCED_IN(28); 820 821 /** 822 * Set the type of audio data that the output stream will carry. 823 * 824 * The AAudio system will use this information to optimize the 825 * behavior of the stream. 826 * This could, for example, affect whether a stream is paused when a notification occurs. 827 * 828 * The default, if you do not call this function, is {@link #AAUDIO_CONTENT_TYPE_MUSIC}. 829 * 830 * Available since API level 28. 831 * 832 * @param builder reference provided by AAudio_createStreamBuilder() 833 * @param contentType the type of audio data, eg. {@link #AAUDIO_CONTENT_TYPE_SPEECH} 834 */ 835 AAUDIO_API void AAudioStreamBuilder_setContentType(AAudioStreamBuilder* builder, 836 aaudio_content_type_t contentType) __INTRODUCED_IN(28); 837 838 /** 839 * Set the input (capture) preset for the stream. 840 * 841 * The AAudio system will use this information to optimize the 842 * behavior of the stream. 843 * This could, for example, affect which microphones are used and how the 844 * recorded data is processed. 845 * 846 * The default, if you do not call this function, is {@link #AAUDIO_INPUT_PRESET_VOICE_RECOGNITION}. 847 * That is because VOICE_RECOGNITION is the preset with the lowest latency 848 * on many platforms. 849 * 850 * Available since API level 28. 851 * 852 * @param builder reference provided by AAudio_createStreamBuilder() 853 * @param inputPreset the desired configuration for recording 854 */ 855 AAUDIO_API void AAudioStreamBuilder_setInputPreset(AAudioStreamBuilder* builder, 856 aaudio_input_preset_t inputPreset) __INTRODUCED_IN(28); 857 858 /** 859 * Specify whether this stream audio may or may not be captured by other apps or the system. 860 * 861 * The default is {@link #AAUDIO_ALLOW_CAPTURE_BY_ALL}. 862 * 863 * Note that an application can also set its global policy, in which case the most restrictive 864 * policy is always applied. See 865 * <a href="/reference/android/media/AudioManager#setAllowedCapturePolicy(int)"> 866 * setAllowedCapturePolicy(int)</a> 867 * 868 * Available since API level 29. 869 * 870 * @param builder reference provided by AAudio_createStreamBuilder() 871 * @param capturePolicy the desired level of opt-out from being captured. 872 */ 873 AAUDIO_API void AAudioStreamBuilder_setAllowedCapturePolicy(AAudioStreamBuilder* builder, 874 aaudio_allowed_capture_policy_t capturePolicy) __INTRODUCED_IN(29); 875 876 /** Set the requested session ID. 877 * 878 * The session ID can be used to associate a stream with effects processors. 879 * The effects are controlled using the Android AudioEffect Java API. 880 * 881 * The default, if you do not call this function, is {@link #AAUDIO_SESSION_ID_NONE}. 882 * 883 * If set to {@link #AAUDIO_SESSION_ID_ALLOCATE} then a session ID will be allocated 884 * when the stream is opened. 885 * 886 * The allocated session ID can be obtained by calling AAudioStream_getSessionId() 887 * and then used with this function when opening another stream. 888 * This allows effects to be shared between streams. 889 * 890 * Session IDs from AAudio can be used with the Android Java APIs and vice versa. 891 * So a session ID from an AAudio stream can be passed to Java 892 * and effects applied using the Java AudioEffect API. 893 * 894 * Note that allocating or setting a session ID may result in a stream with higher latency. 895 * 896 * Allocated session IDs will always be positive and nonzero. 897 * 898 * Available since API level 28. 899 * 900 * @param builder reference provided by AAudio_createStreamBuilder() 901 * @param sessionId an allocated sessionID or {@link #AAUDIO_SESSION_ID_ALLOCATE} 902 */ 903 AAUDIO_API void AAudioStreamBuilder_setSessionId(AAudioStreamBuilder* builder, 904 aaudio_session_id_t sessionId) __INTRODUCED_IN(28); 905 906 907 /** Indicates whether this input stream must be marked as privacy sensitive or not. 908 * 909 * When true, this input stream is privacy sensitive and any concurrent capture 910 * is not permitted. 911 * 912 * This is off (false) by default except when the input preset is {@link #AAUDIO_INPUT_PRESET_VOICE_COMMUNICATION} 913 * or {@link #AAUDIO_INPUT_PRESET_CAMCORDER}. 914 * 915 * Always takes precedence over default from input preset when set explicitly. 916 * 917 * Only relevant if the stream direction is {@link #AAUDIO_DIRECTION_INPUT}. 918 * 919 * Added in API level 30. 920 * 921 * @param builder reference provided by AAudio_createStreamBuilder() 922 * @param privacySensitive true if capture from this stream must be marked as privacy sensitive, 923 * false otherwise. 924 */ 925 AAUDIO_API void AAudioStreamBuilder_setPrivacySensitive(AAudioStreamBuilder* builder, 926 bool privacySensitive) __INTRODUCED_IN(30); 927 928 /** 929 * Return one of these values from the data callback function. 930 */ 931 enum { 932 933 /** 934 * Continue calling the callback. 935 */ 936 AAUDIO_CALLBACK_RESULT_CONTINUE = 0, 937 938 /** 939 * Stop calling the callback. 940 * 941 * The application will still need to call AAudioStream_requestPause() 942 * or AAudioStream_requestStop(). 943 */ 944 AAUDIO_CALLBACK_RESULT_STOP, 945 946 }; 947 typedef int32_t aaudio_data_callback_result_t; 948 949 /** 950 * Prototype for the data function that is passed to AAudioStreamBuilder_setDataCallback(). 951 * 952 * For an output stream, this function should render and write numFrames of data 953 * in the streams current data format to the audioData buffer. 954 * 955 * For an input stream, this function should read and process numFrames of data 956 * from the audioData buffer. 957 * 958 * The audio data is passed through the buffer. So do NOT call AAudioStream_read() or 959 * AAudioStream_write() on the stream that is making the callback. 960 * 961 * Note that numFrames can vary unless AAudioStreamBuilder_setFramesPerDataCallback() 962 * is called. 963 * 964 * Also note that this callback function should be considered a "real-time" function. 965 * It must not do anything that could cause an unbounded delay because that can cause the 966 * audio to glitch or pop. 967 * 968 * These are things the function should NOT do: 969 * <ul> 970 * <li>allocate memory using, for example, malloc() or new</li> 971 * <li>any file operations such as opening, closing, reading or writing</li> 972 * <li>any network operations such as streaming</li> 973 * <li>use any mutexes or other synchronization primitives</li> 974 * <li>sleep</li> 975 * <li>stop or close the stream</li> 976 * <li>AAudioStream_read()</li> 977 * <li>AAudioStream_write()</li> 978 * </ul> 979 * 980 * The following are OK to call from the data callback: 981 * <ul> 982 * <li>AAudioStream_get*()</li> 983 * <li>AAudio_convertResultToText()</li> 984 * </ul> 985 * 986 * If you need to move data, eg. MIDI commands, in or out of the callback function then 987 * we recommend the use of non-blocking techniques such as an atomic FIFO. 988 * 989 * @param stream reference provided by AAudioStreamBuilder_openStream() 990 * @param userData the same address that was passed to AAudioStreamBuilder_setCallback() 991 * @param audioData a pointer to the audio data 992 * @param numFrames the number of frames to be processed, which can vary 993 * @return AAUDIO_CALLBACK_RESULT_* 994 */ 995 typedef aaudio_data_callback_result_t (*AAudioStream_dataCallback)( 996 AAudioStream *stream, 997 void *userData, 998 void *audioData, 999 int32_t numFrames); 1000 1001 /** 1002 * Request that AAudio call this functions when the stream is running. 1003 * 1004 * Note that when using this callback, the audio data will be passed in or out 1005 * of the function as an argument. 1006 * So you cannot call AAudioStream_write() or AAudioStream_read() 1007 * on the same stream that has an active data callback. 1008 * 1009 * The callback function will start being called after AAudioStream_requestStart() 1010 * is called. 1011 * It will stop being called after AAudioStream_requestPause() or 1012 * AAudioStream_requestStop() is called. 1013 * 1014 * This callback function will be called on a real-time thread owned by AAudio. 1015 * The low latency streams may have callback threads with higher priority than normal streams. 1016 * See {@link #AAudioStream_dataCallback} for more information. 1017 * 1018 * Note that the AAudio callbacks will never be called simultaneously from multiple threads. 1019 * 1020 * Available since API level 26. 1021 * 1022 * @param builder reference provided by AAudio_createStreamBuilder() 1023 * @param callback pointer to a function that will process audio data. 1024 * @param userData pointer to an application data structure that will be passed 1025 * to the callback functions. 1026 */ 1027 AAUDIO_API void AAudioStreamBuilder_setDataCallback(AAudioStreamBuilder* builder, 1028 AAudioStream_dataCallback callback, void *userData) __INTRODUCED_IN(26); 1029 1030 /** 1031 * Set the requested data callback buffer size in frames. 1032 * See {@link #AAudioStream_dataCallback}. 1033 * 1034 * The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED}. 1035 * 1036 * For the lowest possible latency, do not call this function. AAudio will then 1037 * call the dataProc callback function with whatever size is optimal. 1038 * That size may vary from one callback to another. 1039 * 1040 * Only use this function if the application requires a specific number of frames for processing. 1041 * The application might, for example, be using an FFT that requires 1042 * a specific power-of-two sized buffer. 1043 * 1044 * AAudio may need to add additional buffering in order to adapt between the internal 1045 * buffer size and the requested buffer size. 1046 * 1047 * If you do call this function then the requested size should be less than 1048 * half the buffer capacity, to allow double buffering. 1049 * 1050 * Available since API level 26. 1051 * 1052 * @param builder reference provided by AAudio_createStreamBuilder() 1053 * @param numFrames the desired buffer size in frames or {@link #AAUDIO_UNSPECIFIED} 1054 */ 1055 AAUDIO_API void AAudioStreamBuilder_setFramesPerDataCallback(AAudioStreamBuilder* builder, 1056 int32_t numFrames) __INTRODUCED_IN(26); 1057 1058 /** 1059 * Prototype for the callback function that is passed to 1060 * AAudioStreamBuilder_setErrorCallback(). 1061 * 1062 * The following may NOT be called from the error callback: 1063 * <ul> 1064 * <li>AAudioStream_requestStop()</li> 1065 * <li>AAudioStream_requestPause()</li> 1066 * <li>AAudioStream_close()</li> 1067 * <li>AAudioStream_waitForStateChange()</li> 1068 * <li>AAudioStream_read()</li> 1069 * <li>AAudioStream_write()</li> 1070 * </ul> 1071 * 1072 * The following are OK to call from the error callback: 1073 * <ul> 1074 * <li>AAudioStream_get*()</li> 1075 * <li>AAudio_convertResultToText()</li> 1076 * </ul> 1077 * 1078 * @param stream reference provided by AAudioStreamBuilder_openStream() 1079 * @param userData the same address that was passed to AAudioStreamBuilder_setErrorCallback() 1080 * @param error an AAUDIO_ERROR_* value. 1081 */ 1082 typedef void (*AAudioStream_errorCallback)( 1083 AAudioStream *stream, 1084 void *userData, 1085 aaudio_result_t error); 1086 1087 /** 1088 * Request that AAudio call this function if any error occurs or the stream is disconnected. 1089 * 1090 * It will be called, for example, if a headset or a USB device is unplugged causing the stream's 1091 * device to be unavailable or "disconnected". 1092 * Another possible cause of error would be a timeout or an unanticipated internal error. 1093 * 1094 * In response, this function should signal or create another thread to stop 1095 * and close this stream. The other thread could then reopen a stream on another device. 1096 * Do not stop or close the stream, or reopen the new stream, directly from this callback. 1097 * 1098 * This callback will not be called because of actions by the application, such as stopping 1099 * or closing a stream. 1100 * 1101 * Note that the AAudio callbacks will never be called simultaneously from multiple threads. 1102 * 1103 * Available since API level 26. 1104 * 1105 * @param builder reference provided by AAudio_createStreamBuilder() 1106 * @param callback pointer to a function that will be called if an error occurs. 1107 * @param userData pointer to an application data structure that will be passed 1108 * to the callback functions. 1109 */ 1110 AAUDIO_API void AAudioStreamBuilder_setErrorCallback(AAudioStreamBuilder* builder, 1111 AAudioStream_errorCallback callback, void *userData) __INTRODUCED_IN(26); 1112 1113 /** 1114 * Open a stream based on the options in the StreamBuilder. 1115 * 1116 * AAudioStream_close() must be called when finished with the stream to recover 1117 * the memory and to free the associated resources. 1118 * 1119 * Available since API level 26. 1120 * 1121 * @param builder reference provided by AAudio_createStreamBuilder() 1122 * @param stream pointer to a variable to receive the new stream reference 1123 * @return {@link #AAUDIO_OK} or a negative error. 1124 */ 1125 AAUDIO_API aaudio_result_t AAudioStreamBuilder_openStream(AAudioStreamBuilder* builder, 1126 AAudioStream** stream) __INTRODUCED_IN(26); 1127 1128 /** 1129 * Delete the resources associated with the StreamBuilder. 1130 * 1131 * Available since API level 26. 1132 * 1133 * @param builder reference provided by AAudio_createStreamBuilder() 1134 * @return {@link #AAUDIO_OK} or a negative error. 1135 */ 1136 AAUDIO_API aaudio_result_t AAudioStreamBuilder_delete(AAudioStreamBuilder* builder) 1137 __INTRODUCED_IN(26); 1138 1139 // ============================================================ 1140 // Stream Control 1141 // ============================================================ 1142 1143 /** 1144 * Free the audio resources associated with a stream created by 1145 * AAudioStreamBuilder_openStream(). 1146 * AAudioStream_close() should be called at some point after calling 1147 * this function. 1148 * 1149 * After this call, the stream will be in {@link #AAUDIO_STREAM_STATE_CLOSING} 1150 * 1151 * This function is useful if you want to release the audio resources immediately, 1152 * but still allow queries to the stream to occur from other threads. This often 1153 * happens if you are monitoring stream progress from a UI thread. 1154 * 1155 * NOTE: This function is only fully implemented for MMAP streams, 1156 * which are low latency streams supported by some devices. 1157 * On other "Legacy" streams some audio resources will still be in use 1158 * and some callbacks may still be in process after this call. 1159 * 1160 * Available since API level 30. 1161 * 1162 * @param stream reference provided by AAudioStreamBuilder_openStream() 1163 * @return {@link #AAUDIO_OK} or a negative error. 1164 */ 1165 AAUDIO_API aaudio_result_t AAudioStream_release(AAudioStream* stream) __INTRODUCED_IN(30); 1166 1167 /** 1168 * Delete the internal data structures associated with the stream created 1169 * by AAudioStreamBuilder_openStream(). 1170 * 1171 * If AAudioStream_release() has not been called then it will be called automatically. 1172 * 1173 * Available since API level 26. 1174 * 1175 * @param stream reference provided by AAudioStreamBuilder_openStream() 1176 * @return {@link #AAUDIO_OK} or a negative error. 1177 */ 1178 AAUDIO_API aaudio_result_t AAudioStream_close(AAudioStream* stream) __INTRODUCED_IN(26); 1179 1180 /** 1181 * Asynchronously request to start playing the stream. For output streams, one should 1182 * write to the stream to fill the buffer before starting. 1183 * Otherwise it will underflow. 1184 * After this call the state will be in {@link #AAUDIO_STREAM_STATE_STARTING} or 1185 * {@link #AAUDIO_STREAM_STATE_STARTED}. 1186 * 1187 * Available since API level 26. 1188 * 1189 * @param stream reference provided by AAudioStreamBuilder_openStream() 1190 * @return {@link #AAUDIO_OK} or a negative error. 1191 */ 1192 AAUDIO_API aaudio_result_t AAudioStream_requestStart(AAudioStream* stream) __INTRODUCED_IN(26); 1193 1194 /** 1195 * Asynchronous request for the stream to pause. 1196 * Pausing a stream will freeze the data flow but not flush any buffers. 1197 * Use AAudioStream_requestStart() to resume playback after a pause. 1198 * After this call the state will be in {@link #AAUDIO_STREAM_STATE_PAUSING} or 1199 * {@link #AAUDIO_STREAM_STATE_PAUSED}. 1200 * 1201 * This will return {@link #AAUDIO_ERROR_UNIMPLEMENTED} for input streams. 1202 * For input streams use AAudioStream_requestStop(). 1203 * 1204 * Available since API level 26. 1205 * 1206 * @param stream reference provided by AAudioStreamBuilder_openStream() 1207 * @return {@link #AAUDIO_OK} or a negative error. 1208 */ 1209 AAUDIO_API aaudio_result_t AAudioStream_requestPause(AAudioStream* stream) __INTRODUCED_IN(26); 1210 1211 /** 1212 * Asynchronous request for the stream to flush. 1213 * Flushing will discard any pending data. 1214 * This call only works if the stream is pausing or paused. TODO review 1215 * Frame counters are not reset by a flush. They may be advanced. 1216 * After this call the state will be in {@link #AAUDIO_STREAM_STATE_FLUSHING} or 1217 * {@link #AAUDIO_STREAM_STATE_FLUSHED}. 1218 * 1219 * This will return {@link #AAUDIO_ERROR_UNIMPLEMENTED} for input streams. 1220 * 1221 * Available since API level 26. 1222 * 1223 * @param stream reference provided by AAudioStreamBuilder_openStream() 1224 * @return {@link #AAUDIO_OK} or a negative error. 1225 */ 1226 AAUDIO_API aaudio_result_t AAudioStream_requestFlush(AAudioStream* stream) __INTRODUCED_IN(26); 1227 1228 /** 1229 * Asynchronous request for the stream to stop. 1230 * The stream will stop after all of the data currently buffered has been played. 1231 * After this call the state will be in {@link #AAUDIO_STREAM_STATE_STOPPING} or 1232 * {@link #AAUDIO_STREAM_STATE_STOPPED}. 1233 * 1234 * Available since API level 26. 1235 * 1236 * @param stream reference provided by AAudioStreamBuilder_openStream() 1237 * @return {@link #AAUDIO_OK} or a negative error. 1238 */ 1239 AAUDIO_API aaudio_result_t AAudioStream_requestStop(AAudioStream* stream) __INTRODUCED_IN(26); 1240 1241 /** 1242 * Query the current state of the client, eg. {@link #AAUDIO_STREAM_STATE_PAUSING} 1243 * 1244 * This function will immediately return the state without updating the state. 1245 * If you want to update the client state based on the server state then 1246 * call AAudioStream_waitForStateChange() with currentState 1247 * set to {@link #AAUDIO_STREAM_STATE_UNKNOWN} and a zero timeout. 1248 * 1249 * Available since API level 26. 1250 * 1251 * @param stream reference provided by AAudioStreamBuilder_openStream() 1252 */ 1253 AAUDIO_API aaudio_stream_state_t AAudioStream_getState(AAudioStream* stream) __INTRODUCED_IN(26); 1254 1255 /** 1256 * Wait until the current state no longer matches the input state. 1257 * 1258 * This will update the current client state. 1259 * 1260 * <pre><code> 1261 * aaudio_result_t result = AAUDIO_OK; 1262 * aaudio_stream_state_t currentState = AAudioStream_getState(stream); 1263 * aaudio_stream_state_t inputState = currentState; 1264 * while (result == AAUDIO_OK && currentState != AAUDIO_STREAM_STATE_PAUSED) { 1265 * result = AAudioStream_waitForStateChange( 1266 * stream, inputState, ¤tState, MY_TIMEOUT_NANOS); 1267 * inputState = currentState; 1268 * } 1269 * </code></pre> 1270 * 1271 * Available since API level 26. 1272 * 1273 * @param stream A reference provided by AAudioStreamBuilder_openStream() 1274 * @param inputState The state we want to avoid. 1275 * @param nextState Pointer to a variable that will be set to the new state. 1276 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. 1277 * @return {@link #AAUDIO_OK} or a negative error. 1278 */ 1279 AAUDIO_API aaudio_result_t AAudioStream_waitForStateChange(AAudioStream* stream, 1280 aaudio_stream_state_t inputState, aaudio_stream_state_t *nextState, 1281 int64_t timeoutNanoseconds) __INTRODUCED_IN(26); 1282 1283 // ============================================================ 1284 // Stream I/O 1285 // ============================================================ 1286 1287 /** 1288 * Read data from the stream. 1289 * 1290 * The call will wait until the read is complete or until it runs out of time. 1291 * If timeoutNanos is zero then this call will not wait. 1292 * 1293 * Note that timeoutNanoseconds is a relative duration in wall clock time. 1294 * Time will not stop if the thread is asleep. 1295 * So it will be implemented using CLOCK_BOOTTIME. 1296 * 1297 * This call is "strong non-blocking" unless it has to wait for data. 1298 * 1299 * If the call times out then zero or a partial frame count will be returned. 1300 * 1301 * Available since API level 26. 1302 * 1303 * @param stream A stream created using AAudioStreamBuilder_openStream(). 1304 * @param buffer The address of the first sample. 1305 * @param numFrames Number of frames to read. Only complete frames will be written. 1306 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. 1307 * @return The number of frames actually read or a negative error. 1308 */ 1309 AAUDIO_API aaudio_result_t AAudioStream_read(AAudioStream* stream, 1310 void *buffer, int32_t numFrames, int64_t timeoutNanoseconds) __INTRODUCED_IN(26); 1311 1312 /** 1313 * Write data to the stream. 1314 * 1315 * The call will wait until the write is complete or until it runs out of time. 1316 * If timeoutNanos is zero then this call will not wait. 1317 * 1318 * Note that timeoutNanoseconds is a relative duration in wall clock time. 1319 * Time will not stop if the thread is asleep. 1320 * So it will be implemented using CLOCK_BOOTTIME. 1321 * 1322 * This call is "strong non-blocking" unless it has to wait for room in the buffer. 1323 * 1324 * If the call times out then zero or a partial frame count will be returned. 1325 * 1326 * Available since API level 26. 1327 * 1328 * @param stream A stream created using AAudioStreamBuilder_openStream(). 1329 * @param buffer The address of the first sample. 1330 * @param numFrames Number of frames to write. Only complete frames will be written. 1331 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. 1332 * @return The number of frames actually written or a negative error. 1333 */ 1334 AAUDIO_API aaudio_result_t AAudioStream_write(AAudioStream* stream, 1335 const void *buffer, int32_t numFrames, int64_t timeoutNanoseconds) __INTRODUCED_IN(26); 1336 1337 // ============================================================ 1338 // Stream - queries 1339 // ============================================================ 1340 1341 /** 1342 * This can be used to adjust the latency of the buffer by changing 1343 * the threshold where blocking will occur. 1344 * By combining this with AAudioStream_getXRunCount(), the latency can be tuned 1345 * at run-time for each device. 1346 * 1347 * This cannot be set higher than AAudioStream_getBufferCapacityInFrames(). 1348 * 1349 * Note that you will probably not get the exact size you request. 1350 * You can check the return value or call AAudioStream_getBufferSizeInFrames() 1351 * to see what the actual final size is. 1352 * 1353 * Available since API level 26. 1354 * 1355 * @param stream reference provided by AAudioStreamBuilder_openStream() 1356 * @param numFrames requested number of frames that can be filled without blocking 1357 * @return actual buffer size in frames or a negative error 1358 */ 1359 AAUDIO_API aaudio_result_t AAudioStream_setBufferSizeInFrames(AAudioStream* stream, 1360 int32_t numFrames) __INTRODUCED_IN(26); 1361 1362 /** 1363 * Query the maximum number of frames that can be filled without blocking. 1364 * 1365 * Available since API level 26. 1366 * 1367 * @param stream reference provided by AAudioStreamBuilder_openStream() 1368 * @return buffer size in frames. 1369 */ 1370 AAUDIO_API int32_t AAudioStream_getBufferSizeInFrames(AAudioStream* stream) __INTRODUCED_IN(26); 1371 1372 /** 1373 * Query the number of frames that the application should read or write at 1374 * one time for optimal performance. It is OK if an application writes 1375 * a different number of frames. But the buffer size may need to be larger 1376 * in order to avoid underruns or overruns. 1377 * 1378 * Note that this may or may not match the actual device burst size. 1379 * For some endpoints, the burst size can vary dynamically. 1380 * But these tend to be devices with high latency. 1381 * 1382 * Available since API level 26. 1383 * 1384 * @param stream reference provided by AAudioStreamBuilder_openStream() 1385 * @return burst size 1386 */ 1387 AAUDIO_API int32_t AAudioStream_getFramesPerBurst(AAudioStream* stream) __INTRODUCED_IN(26); 1388 1389 /** 1390 * Query maximum buffer capacity in frames. 1391 * 1392 * Available since API level 26. 1393 * 1394 * @param stream reference provided by AAudioStreamBuilder_openStream() 1395 * @return buffer capacity in frames 1396 */ 1397 AAUDIO_API int32_t AAudioStream_getBufferCapacityInFrames(AAudioStream* stream) __INTRODUCED_IN(26); 1398 1399 /** 1400 * Query the size of the buffer that will be passed to the dataProc callback 1401 * in the numFrames parameter. 1402 * 1403 * This call can be used if the application needs to know the value of numFrames before 1404 * the stream is started. This is not normally necessary. 1405 * 1406 * If a specific size was requested by calling 1407 * AAudioStreamBuilder_setFramesPerDataCallback() then this will be the same size. 1408 * 1409 * If AAudioStreamBuilder_setFramesPerDataCallback() was not called then this will 1410 * return the size chosen by AAudio, or {@link #AAUDIO_UNSPECIFIED}. 1411 * 1412 * {@link #AAUDIO_UNSPECIFIED} indicates that the callback buffer size for this stream 1413 * may vary from one dataProc callback to the next. 1414 * 1415 * Available since API level 26. 1416 * 1417 * @param stream reference provided by AAudioStreamBuilder_openStream() 1418 * @return callback buffer size in frames or {@link #AAUDIO_UNSPECIFIED} 1419 */ 1420 AAUDIO_API int32_t AAudioStream_getFramesPerDataCallback(AAudioStream* stream) __INTRODUCED_IN(26); 1421 1422 /** 1423 * An XRun is an Underrun or an Overrun. 1424 * During playing, an underrun will occur if the stream is not written in time 1425 * and the system runs out of valid data. 1426 * During recording, an overrun will occur if the stream is not read in time 1427 * and there is no place to put the incoming data so it is discarded. 1428 * 1429 * An underrun or overrun can cause an audible "pop" or "glitch". 1430 * 1431 * Note that some INPUT devices may not support this function. 1432 * In that case a 0 will always be returned. 1433 * 1434 * Available since API level 26. 1435 * 1436 * @param stream reference provided by AAudioStreamBuilder_openStream() 1437 * @return the underrun or overrun count 1438 */ 1439 AAUDIO_API int32_t AAudioStream_getXRunCount(AAudioStream* stream) __INTRODUCED_IN(26); 1440 1441 /** 1442 * Available since API level 26. 1443 * 1444 * @param stream reference provided by AAudioStreamBuilder_openStream() 1445 * @return actual sample rate 1446 */ 1447 AAUDIO_API int32_t AAudioStream_getSampleRate(AAudioStream* stream) __INTRODUCED_IN(26); 1448 1449 /** 1450 * A stream has one or more channels of data. 1451 * A frame will contain one sample for each channel. 1452 * 1453 * Available since API level 26. 1454 * 1455 * @param stream reference provided by AAudioStreamBuilder_openStream() 1456 * @return actual number of channels 1457 */ 1458 AAUDIO_API int32_t AAudioStream_getChannelCount(AAudioStream* stream) __INTRODUCED_IN(26); 1459 1460 /** 1461 * Identical to AAudioStream_getChannelCount(). 1462 * 1463 * Available since API level 26. 1464 * 1465 * @param stream reference provided by AAudioStreamBuilder_openStream() 1466 * @return actual number of samples frame 1467 */ 1468 AAUDIO_API int32_t AAudioStream_getSamplesPerFrame(AAudioStream* stream) __INTRODUCED_IN(26); 1469 1470 /** 1471 * Available since API level 26. 1472 * 1473 * @param stream reference provided by AAudioStreamBuilder_openStream() 1474 * @return actual device ID 1475 */ 1476 AAUDIO_API int32_t AAudioStream_getDeviceId(AAudioStream* stream) __INTRODUCED_IN(26); 1477 1478 /** 1479 * Available since API level 26. 1480 * 1481 * @param stream reference provided by AAudioStreamBuilder_openStream() 1482 * @return actual data format 1483 */ 1484 AAUDIO_API aaudio_format_t AAudioStream_getFormat(AAudioStream* stream) __INTRODUCED_IN(26); 1485 1486 /** 1487 * Provide actual sharing mode. 1488 * 1489 * Available since API level 26. 1490 * 1491 * @param stream reference provided by AAudioStreamBuilder_openStream() 1492 * @return actual sharing mode 1493 */ 1494 AAUDIO_API aaudio_sharing_mode_t AAudioStream_getSharingMode(AAudioStream* stream) 1495 __INTRODUCED_IN(26); 1496 1497 /** 1498 * Get the performance mode used by the stream. 1499 * 1500 * Available since API level 26. 1501 * 1502 * @param stream reference provided by AAudioStreamBuilder_openStream() 1503 */ 1504 AAUDIO_API aaudio_performance_mode_t AAudioStream_getPerformanceMode(AAudioStream* stream) 1505 __INTRODUCED_IN(26); 1506 1507 /** 1508 * Available since API level 26. 1509 * 1510 * @param stream reference provided by AAudioStreamBuilder_openStream() 1511 * @return direction 1512 */ 1513 AAUDIO_API aaudio_direction_t AAudioStream_getDirection(AAudioStream* stream) __INTRODUCED_IN(26); 1514 1515 /** 1516 * Passes back the number of frames that have been written since the stream was created. 1517 * For an output stream, this will be advanced by the application calling write() 1518 * or by a data callback. 1519 * For an input stream, this will be advanced by the endpoint. 1520 * 1521 * The frame position is monotonically increasing. 1522 * 1523 * Available since API level 26. 1524 * 1525 * @param stream reference provided by AAudioStreamBuilder_openStream() 1526 * @return frames written 1527 */ 1528 AAUDIO_API int64_t AAudioStream_getFramesWritten(AAudioStream* stream) __INTRODUCED_IN(26); 1529 1530 /** 1531 * Passes back the number of frames that have been read since the stream was created. 1532 * For an output stream, this will be advanced by the endpoint. 1533 * For an input stream, this will be advanced by the application calling read() 1534 * or by a data callback. 1535 * 1536 * The frame position is monotonically increasing. 1537 * 1538 * Available since API level 26. 1539 * 1540 * @param stream reference provided by AAudioStreamBuilder_openStream() 1541 * @return frames read 1542 */ 1543 AAUDIO_API int64_t AAudioStream_getFramesRead(AAudioStream* stream) __INTRODUCED_IN(26); 1544 1545 /** 1546 * Passes back the session ID associated with this stream. 1547 * 1548 * The session ID can be used to associate a stream with effects processors. 1549 * The effects are controlled using the Android AudioEffect Java API. 1550 * 1551 * If AAudioStreamBuilder_setSessionId() was 1552 * called with {@link #AAUDIO_SESSION_ID_ALLOCATE} 1553 * then a new session ID should be allocated once when the stream is opened. 1554 * 1555 * If AAudioStreamBuilder_setSessionId() was called with a previously allocated 1556 * session ID then that value should be returned. 1557 * 1558 * If AAudioStreamBuilder_setSessionId() was not called then this function should 1559 * return {@link #AAUDIO_SESSION_ID_NONE}. 1560 * 1561 * The sessionID for a stream should not change once the stream has been opened. 1562 * 1563 * Available since API level 28. 1564 * 1565 * @param stream reference provided by AAudioStreamBuilder_openStream() 1566 * @return session ID or {@link #AAUDIO_SESSION_ID_NONE} 1567 */ 1568 AAUDIO_API aaudio_session_id_t AAudioStream_getSessionId(AAudioStream* stream) __INTRODUCED_IN(28); 1569 1570 /** 1571 * Passes back the time at which a particular frame was presented. 1572 * This can be used to synchronize audio with video or MIDI. 1573 * It can also be used to align a recorded stream with a playback stream. 1574 * 1575 * Timestamps are only valid when the stream is in {@link #AAUDIO_STREAM_STATE_STARTED}. 1576 * {@link #AAUDIO_ERROR_INVALID_STATE} will be returned if the stream is not started. 1577 * Note that because requestStart() is asynchronous, timestamps will not be valid until 1578 * a short time after calling requestStart(). 1579 * So {@link #AAUDIO_ERROR_INVALID_STATE} should not be considered a fatal error. 1580 * Just try calling again later. 1581 * 1582 * If an error occurs, then the position and time will not be modified. 1583 * 1584 * The position and time passed back are monotonically increasing. 1585 * 1586 * Available since API level 26. 1587 * 1588 * @param stream reference provided by AAudioStreamBuilder_openStream() 1589 * @param clockid CLOCK_MONOTONIC or CLOCK_BOOTTIME 1590 * @param framePosition pointer to a variable to receive the position 1591 * @param timeNanoseconds pointer to a variable to receive the time 1592 * @return {@link #AAUDIO_OK} or a negative error 1593 */ 1594 AAUDIO_API aaudio_result_t AAudioStream_getTimestamp(AAudioStream* stream, 1595 clockid_t clockid, int64_t *framePosition, int64_t *timeNanoseconds) __INTRODUCED_IN(26); 1596 1597 /** 1598 * Return the use case for the stream. 1599 * 1600 * Available since API level 28. 1601 * 1602 * @param stream reference provided by AAudioStreamBuilder_openStream() 1603 * @return frames read 1604 */ 1605 AAUDIO_API aaudio_usage_t AAudioStream_getUsage(AAudioStream* stream) __INTRODUCED_IN(28); 1606 1607 /** 1608 * Return the content type for the stream. 1609 * 1610 * Available since API level 28. 1611 * 1612 * @param stream reference provided by AAudioStreamBuilder_openStream() 1613 * @return content type, for example {@link #AAUDIO_CONTENT_TYPE_MUSIC} 1614 */ 1615 AAUDIO_API aaudio_content_type_t AAudioStream_getContentType(AAudioStream* stream) 1616 __INTRODUCED_IN(28); 1617 1618 /** 1619 * Return the input preset for the stream. 1620 * 1621 * Available since API level 28. 1622 * 1623 * @param stream reference provided by AAudioStreamBuilder_openStream() 1624 * @return input preset, for example {@link #AAUDIO_INPUT_PRESET_CAMCORDER} 1625 */ 1626 AAUDIO_API aaudio_input_preset_t AAudioStream_getInputPreset(AAudioStream* stream) 1627 __INTRODUCED_IN(28); 1628 1629 /** 1630 * Return the policy that determines whether the audio may or may not be captured 1631 * by other apps or the system. 1632 * 1633 * Available since API level 29. 1634 * 1635 * @param stream reference provided by AAudioStreamBuilder_openStream() 1636 * @return the allowed capture policy, for example {@link #AAUDIO_ALLOW_CAPTURE_BY_ALL} 1637 */ 1638 AAUDIO_API aaudio_allowed_capture_policy_t AAudioStream_getAllowedCapturePolicy( 1639 AAudioStream* stream) __INTRODUCED_IN(29); 1640 1641 1642 /** 1643 * Return whether this input stream is marked as privacy sensitive or not. 1644 * 1645 * See {@link #AAudioStreamBuilder_setPrivacySensitive()}. 1646 * 1647 * Added in API level 30. 1648 * 1649 * @param stream reference provided by AAudioStreamBuilder_openStream() 1650 * @return true if privacy sensitive, false otherwise 1651 */ 1652 AAUDIO_API bool AAudioStream_isPrivacySensitive(AAudioStream* stream) 1653 __INTRODUCED_IN(30); 1654 1655 #ifdef __cplusplus 1656 } 1657 #endif 1658 1659 #endif //AAUDIO_AAUDIO_H 1660 1661 /** @} */ 1662