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/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 it did 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 * This format is used for compressed audio wrapped in IEC61937 for HDMI 110 * or S/PDIF passthrough. 111 * 112 * Unlike PCM playback, the Android framework is not able to do format 113 * conversion for IEC61937. In that case, when IEC61937 is requested, sampling 114 * rate and channel count or channel mask must be specified. Otherwise, it may 115 * fail when opening the stream. Apps are able to get the correct configuration 116 * for the playback by calling 117 * <a href="/reference/android/media/AudioManager#getDevices(int)"> 118 * AudioManager#getDevices(int)</a>. 119 * 120 * Available since API level 34. 121 */ 122 AAUDIO_FORMAT_IEC61937 123 124 }; 125 typedef int32_t aaudio_format_t; 126 127 /** 128 * These result codes are returned from AAudio functions to indicate success or failure. 129 * Note that error return codes may change in the future so applications should generally 130 * not rely on specific return codes. 131 */ 132 enum { 133 /** 134 * The call was successful. 135 */ 136 AAUDIO_OK, 137 138 /** 139 * Reserved. This should not be returned. 140 */ 141 AAUDIO_ERROR_BASE = -900, 142 143 /** 144 * The audio device was disconnected. This could occur, for example, when headphones 145 * are plugged in or unplugged. The stream cannot be used after the device is disconnected. 146 * Applications should stop and close the stream. 147 * If this error is received in an error callback then another thread should be 148 * used to stop and close the stream. 149 */ 150 AAUDIO_ERROR_DISCONNECTED, 151 152 /** 153 * An invalid parameter was passed to AAudio. 154 */ 155 AAUDIO_ERROR_ILLEGAL_ARGUMENT, 156 // reserved 157 158 /** 159 * An internal error occurred. 160 */ 161 AAUDIO_ERROR_INTERNAL = AAUDIO_ERROR_ILLEGAL_ARGUMENT + 2, 162 163 /** 164 * The requested operation is not appropriate for the current state of AAudio. 165 */ 166 AAUDIO_ERROR_INVALID_STATE, 167 // reserved 168 // reserved 169 170 /** 171 * The server rejected the handle used to identify the stream. 172 */ 173 AAUDIO_ERROR_INVALID_HANDLE = AAUDIO_ERROR_INVALID_STATE + 3, 174 // reserved 175 176 /** 177 * The function is not implemented for this stream. 178 */ 179 AAUDIO_ERROR_UNIMPLEMENTED = AAUDIO_ERROR_INVALID_HANDLE + 2, 180 181 /** 182 * A resource or information is unavailable. 183 * This could occur when an application tries to open too many streams, 184 * or a timestamp is not available. 185 */ 186 AAUDIO_ERROR_UNAVAILABLE, 187 188 /** 189 * Reserved. This should not be returned. 190 */ 191 AAUDIO_ERROR_NO_FREE_HANDLES, 192 193 /** 194 * Memory could not be allocated. 195 */ 196 AAUDIO_ERROR_NO_MEMORY, 197 198 /** 199 * A NULL pointer was passed to AAudio. 200 * Or a NULL pointer was detected internally. 201 */ 202 AAUDIO_ERROR_NULL, 203 204 /** 205 * An operation took longer than expected. 206 */ 207 AAUDIO_ERROR_TIMEOUT, 208 209 /** 210 * A queue is full. This queue would be blocked. 211 */ 212 AAUDIO_ERROR_WOULD_BLOCK, 213 214 /** 215 * The requested data format is not supported. 216 */ 217 AAUDIO_ERROR_INVALID_FORMAT, 218 219 /** 220 * A requested was out of range. 221 */ 222 AAUDIO_ERROR_OUT_OF_RANGE, 223 224 /** 225 * The audio service was not available. 226 */ 227 AAUDIO_ERROR_NO_SERVICE, 228 229 /** 230 * The requested sample rate was not supported. 231 */ 232 AAUDIO_ERROR_INVALID_RATE 233 }; 234 typedef int32_t aaudio_result_t; 235 236 /** 237 * AAudio Stream states, for details, refer to 238 * <a href="/ndk/guides/audio/aaudio/aaudio#using-streams">Using an Audio Stream</a> 239 */ 240 enum 241 { 242 243 /** 244 * The stream is created but not initialized yet. 245 */ 246 AAUDIO_STREAM_STATE_UNINITIALIZED = 0, 247 /** 248 * The stream is in an unrecognized state. 249 */ 250 AAUDIO_STREAM_STATE_UNKNOWN, 251 252 /** 253 * The stream is open and ready to use. 254 */ 255 AAUDIO_STREAM_STATE_OPEN, 256 /** 257 * The stream is just starting up. 258 */ 259 AAUDIO_STREAM_STATE_STARTING, 260 /** 261 * The stream has started. 262 */ 263 AAUDIO_STREAM_STATE_STARTED, 264 /** 265 * The stream is pausing. 266 */ 267 AAUDIO_STREAM_STATE_PAUSING, 268 /** 269 * The stream has paused, could be restarted or flushed. 270 */ 271 AAUDIO_STREAM_STATE_PAUSED, 272 /** 273 * The stream is being flushed. 274 */ 275 AAUDIO_STREAM_STATE_FLUSHING, 276 /** 277 * The stream is flushed, ready to be restarted. 278 */ 279 AAUDIO_STREAM_STATE_FLUSHED, 280 /** 281 * The stream is stopping. 282 */ 283 AAUDIO_STREAM_STATE_STOPPING, 284 /** 285 * The stream has been stopped. 286 */ 287 AAUDIO_STREAM_STATE_STOPPED, 288 /** 289 * The stream is closing. 290 */ 291 AAUDIO_STREAM_STATE_CLOSING, 292 /** 293 * The stream has been closed. 294 */ 295 AAUDIO_STREAM_STATE_CLOSED, 296 /** 297 * The stream is disconnected from audio device. 298 * @deprecated 299 */ 300 AAUDIO_STREAM_STATE_DISCONNECTED 301 }; 302 typedef int32_t aaudio_stream_state_t; 303 304 305 enum { 306 /** 307 * This will be the only stream using a particular source or sink. 308 * This mode will provide the lowest possible latency. 309 * You should close EXCLUSIVE streams immediately when you are not using them. 310 */ 311 AAUDIO_SHARING_MODE_EXCLUSIVE, 312 /** 313 * Multiple applications will be mixed by the AAudio Server. 314 * This will have higher latency than the EXCLUSIVE mode. 315 */ 316 AAUDIO_SHARING_MODE_SHARED 317 }; 318 typedef int32_t aaudio_sharing_mode_t; 319 320 321 enum { 322 /** 323 * No particular performance needs. Default. 324 */ 325 AAUDIO_PERFORMANCE_MODE_NONE = 10, 326 327 /** 328 * Extending battery life is more important than low latency. 329 * 330 * This mode is not supported in input streams. 331 * For input, mode NONE will be used if this is requested. 332 */ 333 AAUDIO_PERFORMANCE_MODE_POWER_SAVING, 334 335 /** 336 * Reducing latency is more important than battery life. 337 */ 338 AAUDIO_PERFORMANCE_MODE_LOW_LATENCY 339 }; 340 typedef int32_t aaudio_performance_mode_t; 341 342 #define AAUDIO_SYSTEM_USAGE_OFFSET 1000 343 344 /** 345 * The USAGE attribute expresses "why" you are playing a sound, what is this sound used for. 346 * This information is used by certain platforms or routing policies 347 * to make more refined volume or routing decisions. 348 * 349 * Note that these match the equivalent values in 350 * <a href="/reference/android/media/AudioAttributes">AudioAttributes</a> 351 * in the Android Java API. 352 * 353 * Added in API level 28. 354 */ 355 enum { 356 /** 357 * Use this for streaming media, music performance, video, podcasts, etcetera. 358 */ 359 AAUDIO_USAGE_MEDIA = 1, 360 361 /** 362 * Use this for voice over IP, telephony, etcetera. 363 */ 364 AAUDIO_USAGE_VOICE_COMMUNICATION = 2, 365 366 /** 367 * Use this for sounds associated with telephony such as busy tones, DTMF, etcetera. 368 */ 369 AAUDIO_USAGE_VOICE_COMMUNICATION_SIGNALLING = 3, 370 371 /** 372 * Use this to demand the users attention. 373 */ 374 AAUDIO_USAGE_ALARM = 4, 375 376 /** 377 * Use this for notifying the user when a message has arrived or some 378 * other background event has occured. 379 */ 380 AAUDIO_USAGE_NOTIFICATION = 5, 381 382 /** 383 * Use this when the phone rings. 384 */ 385 AAUDIO_USAGE_NOTIFICATION_RINGTONE = 6, 386 387 /** 388 * Use this to attract the users attention when, for example, the battery is low. 389 */ 390 AAUDIO_USAGE_NOTIFICATION_EVENT = 10, 391 392 /** 393 * Use this for screen readers, etcetera. 394 */ 395 AAUDIO_USAGE_ASSISTANCE_ACCESSIBILITY = 11, 396 397 /** 398 * Use this for driving or navigation directions. 399 */ 400 AAUDIO_USAGE_ASSISTANCE_NAVIGATION_GUIDANCE = 12, 401 402 /** 403 * Use this for user interface sounds, beeps, etcetera. 404 */ 405 AAUDIO_USAGE_ASSISTANCE_SONIFICATION = 13, 406 407 /** 408 * Use this for game audio and sound effects. 409 */ 410 AAUDIO_USAGE_GAME = 14, 411 412 /** 413 * Use this for audio responses to user queries, audio instructions or help utterances. 414 */ 415 AAUDIO_USAGE_ASSISTANT = 16, 416 417 /** 418 * Use this in case of playing sounds in an emergency. 419 * Privileged MODIFY_AUDIO_ROUTING permission required. 420 */ 421 AAUDIO_SYSTEM_USAGE_EMERGENCY = AAUDIO_SYSTEM_USAGE_OFFSET, 422 423 /** 424 * Use this for safety sounds and alerts, for example backup camera obstacle detection. 425 * Privileged MODIFY_AUDIO_ROUTING permission required. 426 */ 427 AAUDIO_SYSTEM_USAGE_SAFETY = AAUDIO_SYSTEM_USAGE_OFFSET + 1, 428 429 /** 430 * Use this for vehicle status alerts and information, for example the check engine light. 431 * Privileged MODIFY_AUDIO_ROUTING permission required. 432 */ 433 AAUDIO_SYSTEM_USAGE_VEHICLE_STATUS = AAUDIO_SYSTEM_USAGE_OFFSET + 2, 434 435 /** 436 * Use this for traffic announcements, etc. 437 * Privileged MODIFY_AUDIO_ROUTING permission required. 438 */ 439 AAUDIO_SYSTEM_USAGE_ANNOUNCEMENT = AAUDIO_SYSTEM_USAGE_OFFSET + 3, 440 }; 441 typedef int32_t aaudio_usage_t; 442 443 /** 444 * The CONTENT_TYPE attribute describes "what" you are playing. 445 * It expresses the general category of the content. This information is optional. 446 * But in case it is known (for instance AAUDIO_CONTENT_TYPE_MOVIE for a 447 * movie streaming service or AAUDIO_CONTENT_TYPE_SPEECH for 448 * an audio book application) this information might be used by the audio framework to 449 * enforce audio focus. 450 * 451 * Note that these match the equivalent values in 452 * <a href="/reference/android/media/AudioAttributes">AudioAttributes</a> 453 * in the Android Java API. 454 * 455 * Added in API level 28. 456 */ 457 enum { 458 459 /** 460 * Use this for spoken voice, audio books, etcetera. 461 */ 462 AAUDIO_CONTENT_TYPE_SPEECH = 1, 463 464 /** 465 * Use this for pre-recorded or live music. 466 */ 467 AAUDIO_CONTENT_TYPE_MUSIC = 2, 468 469 /** 470 * Use this for a movie or video soundtrack. 471 */ 472 AAUDIO_CONTENT_TYPE_MOVIE = 3, 473 474 /** 475 * Use this for sound is designed to accompany a user action, 476 * such as a click or beep sound made when the user presses a button. 477 */ 478 AAUDIO_CONTENT_TYPE_SONIFICATION = 4 479 }; 480 typedef int32_t aaudio_content_type_t; 481 482 enum { 483 484 /** 485 * Constant indicating the audio content associated with these attributes will follow the 486 * default platform behavior with regards to which content will be spatialized or not. 487 */ 488 AAUDIO_SPATIALIZATION_BEHAVIOR_AUTO = 1, 489 490 /** 491 * Constant indicating the audio content associated with these attributes should never 492 * be spatialized. 493 */ 494 AAUDIO_SPATIALIZATION_BEHAVIOR_NEVER = 2, 495 }; 496 typedef int32_t aaudio_spatialization_behavior_t; 497 498 /** 499 * Defines the audio source. 500 * An audio source defines both a default physical source of audio signal, and a recording 501 * configuration. 502 * 503 * Note that these match the equivalent values in MediaRecorder.AudioSource in the Android Java API. 504 * 505 * Added in API level 28. 506 */ 507 enum { 508 /** 509 * Use this preset when other presets do not apply. 510 */ 511 AAUDIO_INPUT_PRESET_GENERIC = 1, 512 513 /** 514 * Use this preset when recording video. 515 */ 516 AAUDIO_INPUT_PRESET_CAMCORDER = 5, 517 518 /** 519 * Use this preset when doing speech recognition. 520 */ 521 AAUDIO_INPUT_PRESET_VOICE_RECOGNITION = 6, 522 523 /** 524 * Use this preset when doing telephony or voice messaging. 525 */ 526 AAUDIO_INPUT_PRESET_VOICE_COMMUNICATION = 7, 527 528 /** 529 * Use this preset to obtain an input with no effects. 530 * Note that this input will not have automatic gain control 531 * so the recorded volume may be very low. 532 */ 533 AAUDIO_INPUT_PRESET_UNPROCESSED = 9, 534 535 /** 536 * Use this preset for capturing audio meant to be processed in real time 537 * and played back for live performance (e.g karaoke). 538 * The capture path will minimize latency and coupling with playback path. 539 * Available since API level 29. 540 */ 541 AAUDIO_INPUT_PRESET_VOICE_PERFORMANCE = 10, 542 543 /** 544 * Use this preset for an echo canceller to capture the reference signal. 545 * Reserved for system components. 546 * Requires CAPTURE_AUDIO_OUTPUT permission 547 * Available since API level 35. 548 */ 549 AAUDIO_INPUT_PRESET_SYSTEM_ECHO_REFERENCE = 1997, 550 551 /** 552 * Use this preset for preemptible, low-priority software hotword detection. 553 * Reserved for system components. 554 * Requires CAPTURE_AUDIO_HOTWORD permission. 555 * Available since API level 35. 556 */ 557 AAUDIO_INPUT_PRESET_SYSTEM_HOTWORD = 1999, 558 }; 559 typedef int32_t aaudio_input_preset_t; 560 561 /** 562 * Specifying if audio may or may not be captured by other apps or the system. 563 * 564 * Note that these match the equivalent values in 565 * <a href="/reference/android/media/AudioAttributes">AudioAttributes</a> 566 * in the Android Java API. 567 * 568 * Added in API level 29. 569 */ 570 enum { 571 /** 572 * Indicates that the audio may be captured by any app. 573 * 574 * For privacy, the following usages can not be recorded: AAUDIO_VOICE_COMMUNICATION*, 575 * AAUDIO_USAGE_NOTIFICATION*, AAUDIO_USAGE_ASSISTANCE* and {@link #AAUDIO_USAGE_ASSISTANT}. 576 * 577 * On <a href="/reference/android/os/Build.VERSION_CODES#Q">Build.VERSION_CODES</a>, 578 * this means only {@link #AAUDIO_USAGE_MEDIA} and {@link #AAUDIO_USAGE_GAME} may be captured. 579 * 580 * See <a href="/reference/android/media/AudioAttributes.html#ALLOW_CAPTURE_BY_ALL"> 581 * ALLOW_CAPTURE_BY_ALL</a>. 582 */ 583 AAUDIO_ALLOW_CAPTURE_BY_ALL = 1, 584 /** 585 * Indicates that the audio may only be captured by system apps. 586 * 587 * System apps can capture for many purposes like accessibility, user guidance... 588 * but have strong restriction. See 589 * <a href="/reference/android/media/AudioAttributes.html#ALLOW_CAPTURE_BY_SYSTEM"> 590 * ALLOW_CAPTURE_BY_SYSTEM</a> 591 * for what the system apps can do with the capture audio. 592 */ 593 AAUDIO_ALLOW_CAPTURE_BY_SYSTEM = 2, 594 /** 595 * Indicates that the audio may not be recorded by any app, even if it is a system app. 596 * 597 * It is encouraged to use {@link #AAUDIO_ALLOW_CAPTURE_BY_SYSTEM} instead of this value as system apps 598 * provide significant and useful features for the user (eg. accessibility). 599 * See <a href="/reference/android/media/AudioAttributes.html#ALLOW_CAPTURE_BY_NONE"> 600 * ALLOW_CAPTURE_BY_NONE</a>. 601 */ 602 AAUDIO_ALLOW_CAPTURE_BY_NONE = 3, 603 }; 604 605 typedef int32_t aaudio_allowed_capture_policy_t; 606 607 /** 608 * These may be used with AAudioStreamBuilder_setSessionId(). 609 * 610 * Added in API level 28. 611 */ 612 enum { 613 /** 614 * Do not allocate a session ID. 615 * Effects cannot be used with this stream. 616 * Default. 617 * 618 * Added in API level 28. 619 */ 620 AAUDIO_SESSION_ID_NONE = -1, 621 622 /** 623 * Allocate a session ID that can be used to attach and control 624 * effects using the Java AudioEffects API. 625 * Note that using this may result in higher latency. 626 * 627 * Note that this matches the value of AudioManager.AUDIO_SESSION_ID_GENERATE. 628 * 629 * Added in API level 28. 630 */ 631 AAUDIO_SESSION_ID_ALLOCATE = 0, 632 }; 633 typedef int32_t aaudio_session_id_t; 634 635 /** 636 * Defines the audio channel mask. 637 * Channel masks are used to describe the samples and their 638 * arrangement in the audio frame. They are also used in the endpoint 639 * (e.g. a USB audio interface, a DAC connected to headphones) to 640 * specify allowable configurations of a particular device. 641 * 642 * Channel masks are for input only, output only, or both input and output. 643 * These channel masks are different than those defined in AudioFormat.java. 644 * If an app gets a channel mask from Java API and wants to use it in AAudio, 645 * conversion should be done by the app. 646 * 647 * Added in API level 32. 648 */ 649 enum { 650 /** 651 * Invalid channel mask 652 */ 653 AAUDIO_CHANNEL_INVALID = -1, 654 AAUDIO_CHANNEL_FRONT_LEFT = 1 << 0, 655 AAUDIO_CHANNEL_FRONT_RIGHT = 1 << 1, 656 AAUDIO_CHANNEL_FRONT_CENTER = 1 << 2, 657 AAUDIO_CHANNEL_LOW_FREQUENCY = 1 << 3, 658 AAUDIO_CHANNEL_BACK_LEFT = 1 << 4, 659 AAUDIO_CHANNEL_BACK_RIGHT = 1 << 5, 660 AAUDIO_CHANNEL_FRONT_LEFT_OF_CENTER = 1 << 6, 661 AAUDIO_CHANNEL_FRONT_RIGHT_OF_CENTER = 1 << 7, 662 AAUDIO_CHANNEL_BACK_CENTER = 1 << 8, 663 AAUDIO_CHANNEL_SIDE_LEFT = 1 << 9, 664 AAUDIO_CHANNEL_SIDE_RIGHT = 1 << 10, 665 AAUDIO_CHANNEL_TOP_CENTER = 1 << 11, 666 AAUDIO_CHANNEL_TOP_FRONT_LEFT = 1 << 12, 667 AAUDIO_CHANNEL_TOP_FRONT_CENTER = 1 << 13, 668 AAUDIO_CHANNEL_TOP_FRONT_RIGHT = 1 << 14, 669 AAUDIO_CHANNEL_TOP_BACK_LEFT = 1 << 15, 670 AAUDIO_CHANNEL_TOP_BACK_CENTER = 1 << 16, 671 AAUDIO_CHANNEL_TOP_BACK_RIGHT = 1 << 17, 672 AAUDIO_CHANNEL_TOP_SIDE_LEFT = 1 << 18, 673 AAUDIO_CHANNEL_TOP_SIDE_RIGHT = 1 << 19, 674 AAUDIO_CHANNEL_BOTTOM_FRONT_LEFT = 1 << 20, 675 AAUDIO_CHANNEL_BOTTOM_FRONT_CENTER = 1 << 21, 676 AAUDIO_CHANNEL_BOTTOM_FRONT_RIGHT = 1 << 22, 677 AAUDIO_CHANNEL_LOW_FREQUENCY_2 = 1 << 23, 678 AAUDIO_CHANNEL_FRONT_WIDE_LEFT = 1 << 24, 679 AAUDIO_CHANNEL_FRONT_WIDE_RIGHT = 1 << 25, 680 681 /** 682 * Supported for Input and Output 683 */ 684 AAUDIO_CHANNEL_MONO = AAUDIO_CHANNEL_FRONT_LEFT, 685 /** 686 * Supported for Input and Output 687 */ 688 AAUDIO_CHANNEL_STEREO = AAUDIO_CHANNEL_FRONT_LEFT | 689 AAUDIO_CHANNEL_FRONT_RIGHT, 690 /** 691 * Supported for only Output 692 */ 693 AAUDIO_CHANNEL_2POINT1 = AAUDIO_CHANNEL_FRONT_LEFT | 694 AAUDIO_CHANNEL_FRONT_RIGHT | 695 AAUDIO_CHANNEL_LOW_FREQUENCY, 696 /** 697 * Supported for only Output 698 */ 699 AAUDIO_CHANNEL_TRI = AAUDIO_CHANNEL_FRONT_LEFT | 700 AAUDIO_CHANNEL_FRONT_RIGHT | 701 AAUDIO_CHANNEL_FRONT_CENTER, 702 /** 703 * Supported for only Output 704 */ 705 AAUDIO_CHANNEL_TRI_BACK = AAUDIO_CHANNEL_FRONT_LEFT | 706 AAUDIO_CHANNEL_FRONT_RIGHT | 707 AAUDIO_CHANNEL_BACK_CENTER, 708 /** 709 * Supported for only Output 710 */ 711 AAUDIO_CHANNEL_3POINT1 = AAUDIO_CHANNEL_FRONT_LEFT | 712 AAUDIO_CHANNEL_FRONT_RIGHT | 713 AAUDIO_CHANNEL_FRONT_CENTER | 714 AAUDIO_CHANNEL_LOW_FREQUENCY, 715 /** 716 * Supported for Input and Output 717 */ 718 AAUDIO_CHANNEL_2POINT0POINT2 = AAUDIO_CHANNEL_FRONT_LEFT | 719 AAUDIO_CHANNEL_FRONT_RIGHT | 720 AAUDIO_CHANNEL_TOP_SIDE_LEFT | 721 AAUDIO_CHANNEL_TOP_SIDE_RIGHT, 722 /** 723 * Supported for Input and Output 724 */ 725 AAUDIO_CHANNEL_2POINT1POINT2 = AAUDIO_CHANNEL_2POINT0POINT2 | 726 AAUDIO_CHANNEL_LOW_FREQUENCY, 727 /** 728 * Supported for Input and Output 729 */ 730 AAUDIO_CHANNEL_3POINT0POINT2 = AAUDIO_CHANNEL_FRONT_LEFT | 731 AAUDIO_CHANNEL_FRONT_RIGHT | 732 AAUDIO_CHANNEL_FRONT_CENTER | 733 AAUDIO_CHANNEL_TOP_SIDE_LEFT | 734 AAUDIO_CHANNEL_TOP_SIDE_RIGHT, 735 /** 736 * Supported for Input and Output 737 */ 738 AAUDIO_CHANNEL_3POINT1POINT2 = AAUDIO_CHANNEL_3POINT0POINT2 | 739 AAUDIO_CHANNEL_LOW_FREQUENCY, 740 /** 741 * Supported for only Output 742 */ 743 AAUDIO_CHANNEL_QUAD = AAUDIO_CHANNEL_FRONT_LEFT | 744 AAUDIO_CHANNEL_FRONT_RIGHT | 745 AAUDIO_CHANNEL_BACK_LEFT | 746 AAUDIO_CHANNEL_BACK_RIGHT, 747 /** 748 * Supported for only Output 749 */ 750 AAUDIO_CHANNEL_QUAD_SIDE = AAUDIO_CHANNEL_FRONT_LEFT | 751 AAUDIO_CHANNEL_FRONT_RIGHT | 752 AAUDIO_CHANNEL_SIDE_LEFT | 753 AAUDIO_CHANNEL_SIDE_RIGHT, 754 /** 755 * Supported for only Output 756 */ 757 AAUDIO_CHANNEL_SURROUND = AAUDIO_CHANNEL_FRONT_LEFT | 758 AAUDIO_CHANNEL_FRONT_RIGHT | 759 AAUDIO_CHANNEL_FRONT_CENTER | 760 AAUDIO_CHANNEL_BACK_CENTER, 761 /** 762 * Supported for only Output 763 */ 764 AAUDIO_CHANNEL_PENTA = AAUDIO_CHANNEL_QUAD | 765 AAUDIO_CHANNEL_FRONT_CENTER, 766 /** 767 * Supported for Input and Output. aka 5POINT1_BACK 768 */ 769 AAUDIO_CHANNEL_5POINT1 = AAUDIO_CHANNEL_FRONT_LEFT | 770 AAUDIO_CHANNEL_FRONT_RIGHT | 771 AAUDIO_CHANNEL_FRONT_CENTER | 772 AAUDIO_CHANNEL_LOW_FREQUENCY | 773 AAUDIO_CHANNEL_BACK_LEFT | 774 AAUDIO_CHANNEL_BACK_RIGHT, 775 /** 776 * Supported for only Output 777 */ 778 AAUDIO_CHANNEL_5POINT1_SIDE = AAUDIO_CHANNEL_FRONT_LEFT | 779 AAUDIO_CHANNEL_FRONT_RIGHT | 780 AAUDIO_CHANNEL_FRONT_CENTER | 781 AAUDIO_CHANNEL_LOW_FREQUENCY | 782 AAUDIO_CHANNEL_SIDE_LEFT | 783 AAUDIO_CHANNEL_SIDE_RIGHT, 784 /** 785 * Supported for only Output 786 */ 787 AAUDIO_CHANNEL_6POINT1 = AAUDIO_CHANNEL_FRONT_LEFT | 788 AAUDIO_CHANNEL_FRONT_RIGHT | 789 AAUDIO_CHANNEL_FRONT_CENTER | 790 AAUDIO_CHANNEL_LOW_FREQUENCY | 791 AAUDIO_CHANNEL_BACK_LEFT | 792 AAUDIO_CHANNEL_BACK_RIGHT | 793 AAUDIO_CHANNEL_BACK_CENTER, 794 /** 795 * Supported for only Output 796 */ 797 AAUDIO_CHANNEL_7POINT1 = AAUDIO_CHANNEL_5POINT1 | 798 AAUDIO_CHANNEL_SIDE_LEFT | 799 AAUDIO_CHANNEL_SIDE_RIGHT, 800 /** 801 * Supported for only Output 802 */ 803 AAUDIO_CHANNEL_5POINT1POINT2 = AAUDIO_CHANNEL_5POINT1 | 804 AAUDIO_CHANNEL_TOP_SIDE_LEFT | 805 AAUDIO_CHANNEL_TOP_SIDE_RIGHT, 806 /** 807 * Supported for only Output 808 */ 809 AAUDIO_CHANNEL_5POINT1POINT4 = AAUDIO_CHANNEL_5POINT1 | 810 AAUDIO_CHANNEL_TOP_FRONT_LEFT | 811 AAUDIO_CHANNEL_TOP_FRONT_RIGHT | 812 AAUDIO_CHANNEL_TOP_BACK_LEFT | 813 AAUDIO_CHANNEL_TOP_BACK_RIGHT, 814 /** 815 * Supported for only Output 816 */ 817 AAUDIO_CHANNEL_7POINT1POINT2 = AAUDIO_CHANNEL_7POINT1 | 818 AAUDIO_CHANNEL_TOP_SIDE_LEFT | 819 AAUDIO_CHANNEL_TOP_SIDE_RIGHT, 820 /** 821 * Supported for only Output 822 */ 823 AAUDIO_CHANNEL_7POINT1POINT4 = AAUDIO_CHANNEL_7POINT1 | 824 AAUDIO_CHANNEL_TOP_FRONT_LEFT | 825 AAUDIO_CHANNEL_TOP_FRONT_RIGHT | 826 AAUDIO_CHANNEL_TOP_BACK_LEFT | 827 AAUDIO_CHANNEL_TOP_BACK_RIGHT, 828 /** 829 * Supported for only Output 830 */ 831 AAUDIO_CHANNEL_9POINT1POINT4 = AAUDIO_CHANNEL_7POINT1POINT4 | 832 AAUDIO_CHANNEL_FRONT_WIDE_LEFT | 833 AAUDIO_CHANNEL_FRONT_WIDE_RIGHT, 834 /** 835 * Supported for only Output 836 */ 837 AAUDIO_CHANNEL_9POINT1POINT6 = AAUDIO_CHANNEL_9POINT1POINT4 | 838 AAUDIO_CHANNEL_TOP_SIDE_LEFT | 839 AAUDIO_CHANNEL_TOP_SIDE_RIGHT, 840 /** 841 * Supported for only Input 842 */ 843 AAUDIO_CHANNEL_FRONT_BACK = AAUDIO_CHANNEL_FRONT_CENTER | 844 AAUDIO_CHANNEL_BACK_CENTER, 845 }; 846 typedef uint32_t aaudio_channel_mask_t; 847 848 typedef struct AAudioStreamStruct AAudioStream; 849 typedef struct AAudioStreamBuilderStruct AAudioStreamBuilder; 850 851 #ifndef AAUDIO_API 852 #define AAUDIO_API /* export this symbol */ 853 #endif 854 855 // ============================================================ 856 // Audio System 857 // ============================================================ 858 859 /** 860 * The text is the ASCII symbol corresponding to the returnCode, 861 * or an English message saying the returnCode is unrecognized. 862 * This is intended for developers to use when debugging. 863 * It is not for display to users. 864 * 865 * Available since API level 26. 866 * 867 * @return pointer to a text representation of an AAudio result code. 868 */ 869 AAUDIO_API const char * _Nonnull AAudio_convertResultToText(aaudio_result_t returnCode) 870 __INTRODUCED_IN(26); 871 872 /** 873 * The text is the ASCII symbol corresponding to the stream state, 874 * or an English message saying the state is unrecognized. 875 * This is intended for developers to use when debugging. 876 * It is not for display to users. 877 * 878 * Available since API level 26. 879 * 880 * @return pointer to a text representation of an AAudio state. 881 */ 882 AAUDIO_API const char * _Nonnull AAudio_convertStreamStateToText(aaudio_stream_state_t state) 883 __INTRODUCED_IN(26); 884 885 // ============================================================ 886 // StreamBuilder 887 // ============================================================ 888 889 /** 890 * Create a StreamBuilder that can be used to open a Stream. 891 * 892 * The deviceId is initially unspecified, meaning that the current default device will be used. 893 * 894 * The default direction is {@link #AAUDIO_DIRECTION_OUTPUT}. 895 * The default sharing mode is {@link #AAUDIO_SHARING_MODE_SHARED}. 896 * The data format, samplesPerFrames and sampleRate are unspecified and will be 897 * chosen by the device when it is opened. 898 * 899 * AAudioStreamBuilder_delete() must be called when you are done using the builder. 900 * 901 * Available since API level 26. 902 */ 903 AAUDIO_API aaudio_result_t AAudio_createStreamBuilder(AAudioStreamBuilder* _Nullable* _Nonnull 904 builder) __INTRODUCED_IN(26); 905 906 /** 907 * Request an audio device identified by an ID. 908 * 909 * The ID could be obtained from the Java AudioManager. 910 * AudioManager.getDevices() returns an array of {@link AudioDeviceInfo}, 911 * which contains a getId() method. That ID can be passed to this function. 912 * 913 * It is possible that you may not get the device that you requested. 914 * So if it is important to you, you should call 915 * AAudioStream_getDeviceId() after the stream is opened to 916 * verify the actual ID. 917 * 918 * The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED}, 919 * in which case the primary device will be used. 920 * 921 * Available since API level 26. 922 * 923 * @param builder reference provided by AAudio_createStreamBuilder() 924 * @param deviceId device identifier or {@link #AAUDIO_UNSPECIFIED} 925 */ 926 AAUDIO_API void AAudioStreamBuilder_setDeviceId(AAudioStreamBuilder* _Nonnull builder, 927 int32_t deviceId) __INTRODUCED_IN(26); 928 929 /** 930 * Declare the name of the package creating the stream. 931 * 932 * This is usually {@code Context#getPackageName()}. 933 * 934 * The default, if you do not call this function, is a random package in the calling uid. 935 * The vast majority of apps have only one package per calling UID. 936 * If an invalid package name is set, input streams may not be given permission to 937 * record when started. 938 * 939 * The package name is usually the applicationId in your app's build.gradle file. 940 * 941 * Available since API level 31. 942 * 943 * @param builder reference provided by AAudio_createStreamBuilder() 944 * @param packageName packageName of the calling app. 945 */ 946 AAUDIO_API void AAudioStreamBuilder_setPackageName(AAudioStreamBuilder* _Nonnull builder, 947 const char * _Nonnull packageName) __INTRODUCED_IN(31); 948 949 /** 950 * Declare the attribution tag of the context creating the stream. 951 * 952 * This is usually {@code Context#getAttributionTag()}. 953 * 954 * The default, if you do not call this function, is null. 955 * 956 * Available since API level 31. 957 * 958 * @param builder reference provided by AAudio_createStreamBuilder() 959 * @param attributionTag attributionTag of the calling context. 960 */ 961 AAUDIO_API void AAudioStreamBuilder_setAttributionTag(AAudioStreamBuilder* _Nonnull builder, 962 const char * _Nonnull attributionTag) __INTRODUCED_IN(31); 963 964 /** 965 * Request a sample rate in Hertz. 966 * 967 * The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED}. 968 * An optimal value will then be chosen when the stream is opened. 969 * After opening a stream with an unspecified value, the application must 970 * query for the actual value, which may vary by device. 971 * 972 * If an exact value is specified then an opened stream will use that value. 973 * If a stream cannot be opened with the specified value then the open will fail. 974 * 975 * Available since API level 26. 976 * 977 * @param builder reference provided by AAudio_createStreamBuilder() 978 * @param sampleRate frames per second. Common rates include 44100 and 48000 Hz. 979 */ 980 AAUDIO_API void AAudioStreamBuilder_setSampleRate(AAudioStreamBuilder* _Nonnull builder, 981 int32_t sampleRate) __INTRODUCED_IN(26); 982 983 /** 984 * Request a number of channels for the stream. 985 * 986 * The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED}. 987 * An optimal value will then be chosen when the stream is opened. 988 * After opening a stream with an unspecified value, the application must 989 * query for the actual value, which may vary by device. 990 * 991 * If an exact value is specified then an opened stream will use that value. 992 * If a stream cannot be opened with the specified value then the open will fail. 993 * 994 * As the channel count provided here may be different from the corresponding channel count 995 * of channel mask used in {@link AAudioStreamBuilder_setChannelMask}, the last called function 996 * will be respected if both this function and {@link AAudioStreamBuilder_setChannelMask} are 997 * called. 998 * 999 * Note that if the channel count is two then it may get mixed to mono when the device only supports 1000 * one channel. If the channel count is greater than two but the device's supported channel count is 1001 * less than the requested value, the channels higher than the device channel will be dropped. If 1002 * higher channels should be mixed or spatialized, use {@link AAudioStreamBuilder_setChannelMask} 1003 * instead. 1004 * 1005 * Available since API level 26. 1006 * 1007 * @param builder reference provided by AAudio_createStreamBuilder() 1008 * @param channelCount Number of channels desired. 1009 */ 1010 AAUDIO_API void AAudioStreamBuilder_setChannelCount(AAudioStreamBuilder* _Nonnull builder, 1011 int32_t channelCount) __INTRODUCED_IN(26); 1012 1013 /** 1014 * Identical to AAudioStreamBuilder_setChannelCount(). 1015 * 1016 * Available since API level 26. 1017 * 1018 * @param builder reference provided by AAudio_createStreamBuilder() 1019 * @param samplesPerFrame Number of samples in a frame. 1020 * 1021 * @deprecated use {@link AAudioStreamBuilder_setChannelCount} 1022 */ 1023 AAUDIO_API void AAudioStreamBuilder_setSamplesPerFrame(AAudioStreamBuilder* _Nonnull builder, 1024 int32_t samplesPerFrame) __INTRODUCED_IN(26); 1025 1026 /** 1027 * Request a sample data format, for example {@link #AAUDIO_FORMAT_PCM_I16}. 1028 * 1029 * The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED}. 1030 * An optimal value will then be chosen when the stream is opened. 1031 * After opening a stream with an unspecified value, the application must 1032 * query for the actual value, which may vary by device. 1033 * 1034 * If an exact value is specified then an opened stream will use that value. 1035 * If a stream cannot be opened with the specified value then the open will fail. 1036 * 1037 * Available since API level 26. 1038 * 1039 * @param builder reference provided by AAudio_createStreamBuilder() 1040 * @param format common formats are {@link #AAUDIO_FORMAT_PCM_FLOAT} and 1041 * {@link #AAUDIO_FORMAT_PCM_I16}. 1042 */ 1043 AAUDIO_API void AAudioStreamBuilder_setFormat(AAudioStreamBuilder* _Nonnull builder, 1044 aaudio_format_t format) __INTRODUCED_IN(26); 1045 1046 /** 1047 * Request a mode for sharing the device. 1048 * 1049 * The default, if you do not call this function, is {@link #AAUDIO_SHARING_MODE_SHARED}. 1050 * 1051 * The requested sharing mode may not be available. 1052 * The application can query for the actual mode after the stream is opened. 1053 * 1054 * Available since API level 26. 1055 * 1056 * @param builder reference provided by AAudio_createStreamBuilder() 1057 * @param sharingMode {@link #AAUDIO_SHARING_MODE_SHARED} or {@link #AAUDIO_SHARING_MODE_EXCLUSIVE} 1058 */ 1059 AAUDIO_API void AAudioStreamBuilder_setSharingMode(AAudioStreamBuilder* _Nonnull builder, 1060 aaudio_sharing_mode_t sharingMode) __INTRODUCED_IN(26); 1061 1062 /** 1063 * Request the direction for a stream. 1064 * 1065 * The default, if you do not call this function, is {@link #AAUDIO_DIRECTION_OUTPUT}. 1066 * 1067 * Available since API level 26. 1068 * 1069 * @param builder reference provided by AAudio_createStreamBuilder() 1070 * @param direction {@link #AAUDIO_DIRECTION_OUTPUT} or {@link #AAUDIO_DIRECTION_INPUT} 1071 */ 1072 AAUDIO_API void AAudioStreamBuilder_setDirection(AAudioStreamBuilder* _Nonnull builder, 1073 aaudio_direction_t direction) __INTRODUCED_IN(26); 1074 1075 /** 1076 * Set the requested buffer capacity in frames. 1077 * The final AAudioStream capacity may differ, but will probably be at least this big. 1078 * 1079 * The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED}. 1080 * 1081 * Available since API level 26. 1082 * 1083 * @param builder reference provided by AAudio_createStreamBuilder() 1084 * @param numFrames the desired buffer capacity in frames or {@link #AAUDIO_UNSPECIFIED} 1085 */ 1086 AAUDIO_API void AAudioStreamBuilder_setBufferCapacityInFrames( 1087 AAudioStreamBuilder* _Nonnull builder, int32_t numFrames) __INTRODUCED_IN(26); 1088 1089 /** 1090 * Set the requested performance mode. 1091 * 1092 * Supported modes are {@link #AAUDIO_PERFORMANCE_MODE_NONE}, 1093 * {@link #AAUDIO_PERFORMANCE_MODE_POWER_SAVING} * and {@link #AAUDIO_PERFORMANCE_MODE_LOW_LATENCY}. 1094 * 1095 * The default, if you do not call this function, is {@link #AAUDIO_PERFORMANCE_MODE_NONE}. 1096 * 1097 * You may not get the mode you requested. 1098 * You can call AAudioStream_getPerformanceMode() 1099 * to find out the final mode for the stream. 1100 * 1101 * Available since API level 26. 1102 * 1103 * @param builder reference provided by AAudio_createStreamBuilder() 1104 * @param mode the desired performance mode, eg. {@link #AAUDIO_PERFORMANCE_MODE_LOW_LATENCY} 1105 */ 1106 AAUDIO_API void AAudioStreamBuilder_setPerformanceMode(AAudioStreamBuilder* _Nonnull builder, 1107 aaudio_performance_mode_t mode) __INTRODUCED_IN(26); 1108 1109 /** 1110 * Set the intended use case for the output stream. 1111 * 1112 * The AAudio system will use this information to optimize the 1113 * behavior of the stream. 1114 * This could, for example, affect how volume and focus is handled for the stream. 1115 * 1116 * The default, if you do not call this function, is {@link #AAUDIO_USAGE_MEDIA}. 1117 * 1118 * If you set Usage then you will need to associate the volume keys with the resulting stream. 1119 * Otherwise the volume keys may not work correctly. 1120 * This is done in Java with the following code block. 1121 * 1122 * <pre><code>if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) { 1123 * AudioAttributes attributes = new AudioAttributes.Builder().setUsage(usage) 1124 * .setContentType(contentType).build(); 1125 * setVolumeControlStream(attributes.getVolumeControlStream()); 1126 * } 1127 * </code></pre> 1128 * 1129 * Available since API level 28. 1130 * 1131 * @param builder reference provided by AAudio_createStreamBuilder() 1132 * @param usage the desired usage, eg. {@link #AAUDIO_USAGE_GAME} 1133 */ 1134 AAUDIO_API void AAudioStreamBuilder_setUsage(AAudioStreamBuilder* _Nonnull builder, 1135 aaudio_usage_t usage) __INTRODUCED_IN(28); 1136 1137 /** 1138 * Set the type of audio data that the output stream will carry. 1139 * 1140 * The AAudio system will use this information to optimize the 1141 * behavior of the stream. 1142 * This could, for example, affect whether a stream is paused when a notification occurs. 1143 * 1144 * The default, if you do not call this function, is {@link #AAUDIO_CONTENT_TYPE_MUSIC}. 1145 * 1146 * If you set ContentType then you will need to associate the volume keys with the resulting stream. 1147 * Otherwise the volume keys may not work correctly. 1148 * This is done in Java with the following code block. 1149 * 1150 * <pre><code>if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) { 1151 * AudioAttributes attributes = new AudioAttributes.Builder().setUsage(usage) 1152 * .setContentType(contentType).build(); 1153 * setVolumeControlStream(attributes.getVolumeControlStream()); 1154 * } 1155 * </code></pre> 1156 * 1157 * Available since API level 28. 1158 * 1159 * @param builder reference provided by AAudio_createStreamBuilder() 1160 * @param contentType the type of audio data, eg. {@link #AAUDIO_CONTENT_TYPE_SPEECH} 1161 */ 1162 AAUDIO_API void AAudioStreamBuilder_setContentType(AAudioStreamBuilder* _Nonnull builder, 1163 aaudio_content_type_t contentType) __INTRODUCED_IN(28); 1164 1165 /** 1166 * Sets the behavior affecting whether spatialization will be used. 1167 * 1168 * The AAudio system will use this information to select whether the stream will go 1169 * through a spatializer effect or not when the effect is supported and enabled. 1170 * 1171 * Available since API level 32. 1172 * 1173 * @param builder reference provided by AAudio_createStreamBuilder() 1174 * @param spatializationBehavior the desired behavior with regards to spatialization, eg. 1175 * {@link #AAUDIO_SPATIALIZATION_BEHAVIOR_AUTO} 1176 */ 1177 AAUDIO_API void AAudioStreamBuilder_setSpatializationBehavior( 1178 AAudioStreamBuilder* _Nonnull builder, 1179 aaudio_spatialization_behavior_t spatializationBehavior) __INTRODUCED_IN(32); 1180 1181 /** 1182 * Specifies whether the audio data of this output stream has already been processed for 1183 * spatialization. 1184 * 1185 * If the stream has been processed for spatialization, setting this to true will prevent 1186 * issues such as double-processing on platforms that will spatialize audio data. 1187 * 1188 * Available since API level 32. 1189 * 1190 * @param builder reference provided by AAudio_createStreamBuilder() 1191 * @param isSpatialized true if the content is already processed for binaural or transaural spatial 1192 * rendering, false otherwise. 1193 */ 1194 AAUDIO_API void AAudioStreamBuilder_setIsContentSpatialized(AAudioStreamBuilder* _Nonnull builder, 1195 bool isSpatialized) __INTRODUCED_IN(32); 1196 1197 /** 1198 * Set the input (capture) preset for the stream. 1199 * 1200 * The AAudio system will use this information to optimize the 1201 * behavior of the stream. 1202 * This could, for example, affect which microphones are used and how the 1203 * recorded data is processed. 1204 * 1205 * The default, if you do not call this function, is {@link #AAUDIO_INPUT_PRESET_VOICE_RECOGNITION}. 1206 * That is because VOICE_RECOGNITION is the preset with the lowest latency 1207 * on many platforms. 1208 * 1209 * Available since API level 28. 1210 * 1211 * @param builder reference provided by AAudio_createStreamBuilder() 1212 * @param inputPreset the desired configuration for recording 1213 */ 1214 AAUDIO_API void AAudioStreamBuilder_setInputPreset(AAudioStreamBuilder* _Nonnull builder, 1215 aaudio_input_preset_t inputPreset) __INTRODUCED_IN(28); 1216 1217 /** 1218 * Specify whether this stream audio may or may not be captured by other apps or the system. 1219 * 1220 * The default is {@link #AAUDIO_ALLOW_CAPTURE_BY_ALL}. 1221 * 1222 * Note that an application can also set its global policy, in which case the most restrictive 1223 * policy is always applied. See 1224 * <a href="/reference/android/media/AudioManager#setAllowedCapturePolicy(int)"> 1225 * setAllowedCapturePolicy(int)</a> 1226 * 1227 * Available since API level 29. 1228 * 1229 * @param builder reference provided by AAudio_createStreamBuilder() 1230 * @param capturePolicy the desired level of opt-out from being captured. 1231 */ 1232 AAUDIO_API void AAudioStreamBuilder_setAllowedCapturePolicy(AAudioStreamBuilder* _Nonnull builder, 1233 aaudio_allowed_capture_policy_t capturePolicy) __INTRODUCED_IN(29); 1234 1235 /** Set the requested session ID. 1236 * 1237 * The session ID can be used to associate a stream with effects processors. 1238 * The effects are controlled using the Android AudioEffect Java API. 1239 * 1240 * The default, if you do not call this function, is {@link #AAUDIO_SESSION_ID_NONE}. 1241 * 1242 * If set to {@link #AAUDIO_SESSION_ID_ALLOCATE} then a session ID will be allocated 1243 * when the stream is opened. 1244 * 1245 * The allocated session ID can be obtained by calling AAudioStream_getSessionId() 1246 * and then used with this function when opening another stream. 1247 * This allows effects to be shared between streams. 1248 * 1249 * Session IDs from AAudio can be used with the Android Java APIs and vice versa. 1250 * So a session ID from an AAudio stream can be passed to Java 1251 * and effects applied using the Java AudioEffect API. 1252 * 1253 * Note that allocating or setting a session ID may result in a stream with higher latency. 1254 * 1255 * Allocated session IDs will always be positive and nonzero. 1256 * 1257 * Available since API level 28. 1258 * 1259 * @param builder reference provided by AAudio_createStreamBuilder() 1260 * @param sessionId an allocated sessionID or {@link #AAUDIO_SESSION_ID_ALLOCATE} 1261 */ 1262 AAUDIO_API void AAudioStreamBuilder_setSessionId(AAudioStreamBuilder* _Nonnull builder, 1263 aaudio_session_id_t sessionId) __INTRODUCED_IN(28); 1264 1265 1266 /** Indicates whether this input stream must be marked as privacy sensitive or not. 1267 * 1268 * When true, this input stream is privacy sensitive and any concurrent capture 1269 * is not permitted. 1270 * 1271 * This is off (false) by default except when the input preset is {@link #AAUDIO_INPUT_PRESET_VOICE_COMMUNICATION} 1272 * or {@link #AAUDIO_INPUT_PRESET_CAMCORDER}. 1273 * 1274 * Always takes precedence over default from input preset when set explicitly. 1275 * 1276 * Only relevant if the stream direction is {@link #AAUDIO_DIRECTION_INPUT}. 1277 * 1278 * Added in API level 30. 1279 * 1280 * @param builder reference provided by AAudio_createStreamBuilder() 1281 * @param privacySensitive true if capture from this stream must be marked as privacy sensitive, 1282 * false otherwise. 1283 */ 1284 AAUDIO_API void AAudioStreamBuilder_setPrivacySensitive(AAudioStreamBuilder* _Nonnull builder, 1285 bool privacySensitive) __INTRODUCED_IN(30); 1286 1287 /** 1288 * Return one of these values from the data callback function. 1289 */ 1290 enum { 1291 1292 /** 1293 * Continue calling the callback. 1294 */ 1295 AAUDIO_CALLBACK_RESULT_CONTINUE = 0, 1296 1297 /** 1298 * Stop calling the callback. 1299 * 1300 * The application will still need to call AAudioStream_requestPause() 1301 * or AAudioStream_requestStop(). 1302 */ 1303 AAUDIO_CALLBACK_RESULT_STOP, 1304 1305 }; 1306 typedef int32_t aaudio_data_callback_result_t; 1307 1308 /** 1309 * Prototype for the data function that is passed to AAudioStreamBuilder_setDataCallback(). 1310 * 1311 * For an output stream, this function should render and write numFrames of data 1312 * in the streams current data format to the audioData buffer. 1313 * 1314 * For an input stream, this function should read and process numFrames of data 1315 * from the audioData buffer. The data in the audioData buffer must not be modified 1316 * directly. Instead, it should be copied to another buffer before doing any modification. 1317 * In many cases, writing to the audioData buffer of an input stream will result in a 1318 * native exception. 1319 * 1320 * The audio data is passed through the buffer. So do NOT call AAudioStream_read() or 1321 * AAudioStream_write() on the stream that is making the callback. 1322 * 1323 * Note that numFrames can vary unless AAudioStreamBuilder_setFramesPerDataCallback() 1324 * is called. 1325 * 1326 * Also note that this callback function should be considered a "real-time" function. 1327 * It must not do anything that could cause an unbounded delay because that can cause the 1328 * audio to glitch or pop. 1329 * 1330 * These are things the function should NOT do: 1331 * <ul> 1332 * <li>allocate memory using, for example, malloc() or new</li> 1333 * <li>any file operations such as opening, closing, reading or writing</li> 1334 * <li>any network operations such as streaming</li> 1335 * <li>use any mutexes or other synchronization primitives</li> 1336 * <li>sleep</li> 1337 * <li>stop or close the stream</li> 1338 * <li>AAudioStream_read()</li> 1339 * <li>AAudioStream_write()</li> 1340 * </ul> 1341 * 1342 * The following are OK to call from the data callback: 1343 * <ul> 1344 * <li>AAudioStream_get*()</li> 1345 * <li>AAudio_convertResultToText()</li> 1346 * </ul> 1347 * 1348 * If you need to move data, eg. MIDI commands, in or out of the callback function then 1349 * we recommend the use of non-blocking techniques such as an atomic FIFO. 1350 * 1351 * @param stream reference provided by AAudioStreamBuilder_openStream() 1352 * @param userData the same address that was passed to AAudioStreamBuilder_setCallback() 1353 * @param audioData a pointer to the audio data 1354 * @param numFrames the number of frames to be processed, which can vary 1355 * @return AAUDIO_CALLBACK_RESULT_* 1356 */ 1357 typedef aaudio_data_callback_result_t (*AAudioStream_dataCallback)( 1358 AAudioStream* _Nonnull stream, 1359 void* _Nullable userData, 1360 void* _Nonnull audioData, 1361 int32_t numFrames); 1362 1363 /** 1364 * Request that AAudio call this functions when the stream is running. 1365 * 1366 * Note that when using this callback, the audio data will be passed in or out 1367 * of the function as an argument. 1368 * So you cannot call AAudioStream_write() or AAudioStream_read() 1369 * on the same stream that has an active data callback. 1370 * 1371 * The callback function will start being called after AAudioStream_requestStart() 1372 * is called. 1373 * It will stop being called after AAudioStream_requestPause() or 1374 * AAudioStream_requestStop() is called. 1375 * 1376 * This callback function will be called on a real-time thread owned by AAudio. 1377 * The low latency streams may have callback threads with higher priority than normal streams. 1378 * See {@link #AAudioStream_dataCallback} for more information. 1379 * 1380 * Note that the AAudio callbacks will never be called simultaneously from multiple threads. 1381 * 1382 * Available since API level 26. 1383 * 1384 * @param builder reference provided by AAudio_createStreamBuilder() 1385 * @param callback pointer to a function that will process audio data. 1386 * @param userData pointer to an application data structure that will be passed 1387 * to the callback functions. 1388 */ 1389 AAUDIO_API void AAudioStreamBuilder_setDataCallback(AAudioStreamBuilder* _Nonnull builder, 1390 AAudioStream_dataCallback _Nullable callback, void* _Nullable userData) 1391 __INTRODUCED_IN(26); 1392 1393 /** 1394 * Set the requested data callback buffer size in frames. 1395 * See {@link #AAudioStream_dataCallback}. 1396 * 1397 * The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED}. 1398 * 1399 * For the lowest possible latency, do not call this function. AAudio will then 1400 * call the dataProc callback function with whatever size is optimal. 1401 * That size may vary from one callback to another. 1402 * 1403 * Only use this function if the application requires a specific number of frames for processing. 1404 * The application might, for example, be using an FFT that requires 1405 * a specific power-of-two sized buffer. 1406 * 1407 * AAudio may need to add additional buffering in order to adapt between the internal 1408 * buffer size and the requested buffer size. 1409 * 1410 * If you do call this function then the requested size should be less than 1411 * half the buffer capacity, to allow double buffering. 1412 * 1413 * Available since API level 26. 1414 * 1415 * @param builder reference provided by AAudio_createStreamBuilder() 1416 * @param numFrames the desired buffer size in frames or {@link #AAUDIO_UNSPECIFIED} 1417 */ 1418 AAUDIO_API void AAudioStreamBuilder_setFramesPerDataCallback(AAudioStreamBuilder* _Nonnull builder, 1419 int32_t numFrames) __INTRODUCED_IN(26); 1420 1421 /** 1422 * Prototype for the callback function that is passed to 1423 * AAudioStreamBuilder_setErrorCallback(). 1424 * 1425 * The following may NOT be called from the error callback: 1426 * <ul> 1427 * <li>AAudioStream_requestStop()</li> 1428 * <li>AAudioStream_requestPause()</li> 1429 * <li>AAudioStream_close()</li> 1430 * <li>AAudioStream_waitForStateChange()</li> 1431 * <li>AAudioStream_read()</li> 1432 * <li>AAudioStream_write()</li> 1433 * </ul> 1434 * 1435 * The following are OK to call from the error callback: 1436 * <ul> 1437 * <li>AAudioStream_get*()</li> 1438 * <li>AAudio_convertResultToText()</li> 1439 * </ul> 1440 * 1441 * @param stream reference provided by AAudioStreamBuilder_openStream() 1442 * @param userData the same address that was passed to AAudioStreamBuilder_setErrorCallback() 1443 * @param error an AAUDIO_ERROR_* value. 1444 */ 1445 typedef void (*AAudioStream_errorCallback)( 1446 AAudioStream* _Nonnull stream, 1447 void* _Nullable userData, 1448 aaudio_result_t error); 1449 1450 /** 1451 * Request that AAudio call this function if any error occurs or the stream is disconnected. 1452 * 1453 * It will be called, for example, if a headset or a USB device is unplugged causing the stream's 1454 * device to be unavailable or "disconnected". 1455 * Another possible cause of error would be a timeout or an unanticipated internal error. 1456 * 1457 * In response, this function should signal or create another thread to stop 1458 * and close this stream. The other thread could then reopen a stream on another device. 1459 * Do not stop or close the stream, or reopen the new stream, directly from this callback. 1460 * 1461 * This callback will not be called because of actions by the application, such as stopping 1462 * or closing a stream. 1463 * 1464 * Note that the AAudio callbacks will never be called simultaneously from multiple threads. 1465 * 1466 * Available since API level 26. 1467 * 1468 * @param builder reference provided by AAudio_createStreamBuilder() 1469 * @param callback pointer to a function that will be called if an error occurs. 1470 * @param userData pointer to an application data structure that will be passed 1471 * to the callback functions. 1472 */ 1473 AAUDIO_API void AAudioStreamBuilder_setErrorCallback(AAudioStreamBuilder* _Nonnull builder, 1474 AAudioStream_errorCallback _Nullable callback, void* _Nullable userData) 1475 __INTRODUCED_IN(26); 1476 1477 /** 1478 * Open a stream based on the options in the StreamBuilder. 1479 * 1480 * AAudioStream_close() must be called when finished with the stream to recover 1481 * the memory and to free the associated resources. 1482 * 1483 * Available since API level 26. 1484 * 1485 * @param builder reference provided by AAudio_createStreamBuilder() 1486 * @param stream pointer to a variable to receive the new stream reference 1487 * @return {@link #AAUDIO_OK} or a negative error. 1488 */ 1489 AAUDIO_API aaudio_result_t AAudioStreamBuilder_openStream(AAudioStreamBuilder* _Nonnull builder, 1490 AAudioStream* _Nullable* _Nonnull stream) __INTRODUCED_IN(26); 1491 1492 /** 1493 * Delete the resources associated with the StreamBuilder. 1494 * 1495 * Available since API level 26. 1496 * 1497 * @param builder reference provided by AAudio_createStreamBuilder() 1498 * @return {@link #AAUDIO_OK} or a negative error. 1499 */ 1500 AAUDIO_API aaudio_result_t AAudioStreamBuilder_delete(AAudioStreamBuilder* _Nonnull builder) 1501 __INTRODUCED_IN(26); 1502 1503 /** 1504 * Set audio channel mask for the stream. 1505 * 1506 * The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED}. 1507 * If both channel mask and count are not set, then stereo will then be chosen when the 1508 * stream is opened. 1509 * After opening a stream with an unspecified value, the application must query for the 1510 * actual value, which may vary by device. 1511 * 1512 * If an exact value is specified then an opened stream will use that value. 1513 * If a stream cannot be opened with the specified value then the open will fail. 1514 * 1515 * As the corresponding channel count of provided channel mask here may be different 1516 * from the channel count used in {@link AAudioStreamBuilder_setChannelCount} or 1517 * {@link AAudioStreamBuilder_setSamplesPerFrame}, the last called function will be 1518 * respected if this function and {@link AAudioStreamBuilder_setChannelCount} or 1519 * {@link AAudioStreamBuilder_setSamplesPerFrame} are called. 1520 * 1521 * Available since API level 32. 1522 * 1523 * @param builder reference provided by AAudio_createStreamBuilder() 1524 * @param channelMask Audio channel mask desired. 1525 */ 1526 AAUDIO_API void AAudioStreamBuilder_setChannelMask(AAudioStreamBuilder* _Nonnull builder, 1527 aaudio_channel_mask_t channelMask) __INTRODUCED_IN(32); 1528 1529 // ============================================================ 1530 // Stream Control 1531 // ============================================================ 1532 1533 /** 1534 * Free the audio resources associated with a stream created by 1535 * AAudioStreamBuilder_openStream(). 1536 * AAudioStream_close() should be called at some point after calling 1537 * this function. 1538 * 1539 * After this call, the stream will be in {@link #AAUDIO_STREAM_STATE_CLOSING} 1540 * 1541 * This function is useful if you want to release the audio resources immediately, 1542 * but still allow queries to the stream to occur from other threads. This often 1543 * happens if you are monitoring stream progress from a UI thread. 1544 * 1545 * NOTE: This function is only fully implemented for MMAP streams, 1546 * which are low latency streams supported by some devices. 1547 * On other "Legacy" streams some audio resources will still be in use 1548 * and some callbacks may still be in process after this call. 1549 * 1550 * Available since API level 30. 1551 * 1552 * @param stream reference provided by AAudioStreamBuilder_openStream() 1553 * @return {@link #AAUDIO_OK} or a negative error. 1554 */ 1555 AAUDIO_API aaudio_result_t AAudioStream_release(AAudioStream* _Nonnull stream) 1556 __INTRODUCED_IN(30); 1557 1558 /** 1559 * Delete the internal data structures associated with the stream created 1560 * by AAudioStreamBuilder_openStream(). 1561 * 1562 * If AAudioStream_release() has not been called then it will be called automatically. 1563 * 1564 * Available since API level 26. 1565 * 1566 * @param stream reference provided by AAudioStreamBuilder_openStream() 1567 * @return {@link #AAUDIO_OK} or a negative error. 1568 */ 1569 AAUDIO_API aaudio_result_t AAudioStream_close(AAudioStream* _Nonnull stream) __INTRODUCED_IN(26); 1570 1571 /** 1572 * Asynchronously request to start playing the stream. For output streams, one should 1573 * write to the stream to fill the buffer before starting. 1574 * Otherwise it will underflow. 1575 * After this call the state will be in {@link #AAUDIO_STREAM_STATE_STARTING} or 1576 * {@link #AAUDIO_STREAM_STATE_STARTED}. 1577 * 1578 * Available since API level 26. 1579 * 1580 * @param stream reference provided by AAudioStreamBuilder_openStream() 1581 * @return {@link #AAUDIO_OK} or a negative error. 1582 */ 1583 AAUDIO_API aaudio_result_t AAudioStream_requestStart(AAudioStream* _Nonnull stream) 1584 __INTRODUCED_IN(26); 1585 1586 /** 1587 * Asynchronous request for the stream to pause. 1588 * Pausing a stream will freeze the data flow but not flush any buffers. 1589 * Use AAudioStream_requestStart() to resume playback after a pause. 1590 * After this call the state will be in {@link #AAUDIO_STREAM_STATE_PAUSING} or 1591 * {@link #AAUDIO_STREAM_STATE_PAUSED}. 1592 * 1593 * This will return {@link #AAUDIO_ERROR_UNIMPLEMENTED} for input streams. 1594 * For input streams use AAudioStream_requestStop(). 1595 * 1596 * Available since API level 26. 1597 * 1598 * @param stream reference provided by AAudioStreamBuilder_openStream() 1599 * @return {@link #AAUDIO_OK} or a negative error. 1600 */ 1601 AAUDIO_API aaudio_result_t AAudioStream_requestPause(AAudioStream* _Nonnull stream) 1602 __INTRODUCED_IN(26); 1603 1604 /** 1605 * Asynchronous request for the stream to flush. 1606 * Flushing will discard any pending data. 1607 * This call only works if the stream is OPEN, PAUSED, STOPPED, or FLUSHED. 1608 * Calling this function when in other states, 1609 * or calling from an AAudio callback function, 1610 * will have no effect and an error will be returned. 1611 * Frame counters are not reset by a flush. They may be advanced. 1612 * After this call the state will be in {@link #AAUDIO_STREAM_STATE_FLUSHING} or 1613 * {@link #AAUDIO_STREAM_STATE_FLUSHED}. 1614 * 1615 * This will return {@link #AAUDIO_ERROR_UNIMPLEMENTED} for input streams. 1616 * 1617 * Available since API level 26. 1618 * 1619 * @param stream reference provided by AAudioStreamBuilder_openStream() 1620 * @return {@link #AAUDIO_OK} or a negative error. 1621 */ 1622 AAUDIO_API aaudio_result_t AAudioStream_requestFlush(AAudioStream* _Nonnull stream) 1623 __INTRODUCED_IN(26); 1624 1625 /** 1626 * Asynchronous request for the stream to stop. 1627 * The stream will stop after all of the data currently buffered has been played. 1628 * After this call the state will be in {@link #AAUDIO_STREAM_STATE_STOPPING} or 1629 * {@link #AAUDIO_STREAM_STATE_STOPPED}. 1630 * 1631 * Available since API level 26. 1632 * 1633 * @param stream reference provided by AAudioStreamBuilder_openStream() 1634 * @return {@link #AAUDIO_OK} or a negative error. 1635 */ 1636 AAUDIO_API aaudio_result_t AAudioStream_requestStop(AAudioStream* _Nonnull stream) 1637 __INTRODUCED_IN(26); 1638 1639 /** 1640 * Query the current state of the client, eg. {@link #AAUDIO_STREAM_STATE_PAUSING} 1641 * 1642 * This function will immediately return the state without updating the state. 1643 * If you want to update the client state based on the server state then 1644 * call AAudioStream_waitForStateChange() with currentState 1645 * set to {@link #AAUDIO_STREAM_STATE_UNKNOWN} and a zero timeout. 1646 * 1647 * Available since API level 26. 1648 * 1649 * @param stream reference provided by AAudioStreamBuilder_openStream() 1650 */ 1651 AAUDIO_API aaudio_stream_state_t AAudioStream_getState(AAudioStream* _Nonnull stream) 1652 __INTRODUCED_IN(26); 1653 1654 /** 1655 * Wait until the current state no longer matches the input state. 1656 * 1657 * This will update the current client state. 1658 * 1659 * <pre><code> 1660 * aaudio_result_t result = AAUDIO_OK; 1661 * aaudio_stream_state_t currentState = AAudioStream_getState(stream); 1662 * aaudio_stream_state_t inputState = currentState; 1663 * while (result == AAUDIO_OK && currentState != AAUDIO_STREAM_STATE_PAUSED) { 1664 * result = AAudioStream_waitForStateChange( 1665 * stream, inputState, ¤tState, MY_TIMEOUT_NANOS); 1666 * inputState = currentState; 1667 * } 1668 * </code></pre> 1669 * 1670 * Available since API level 26. 1671 * 1672 * @param stream A reference provided by AAudioStreamBuilder_openStream() 1673 * @param inputState The state we want to avoid. 1674 * @param nextState Pointer to a variable that will be set to the new state. 1675 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. 1676 * @return {@link #AAUDIO_OK} or a negative error. 1677 */ 1678 AAUDIO_API aaudio_result_t AAudioStream_waitForStateChange(AAudioStream* _Nonnull stream, 1679 aaudio_stream_state_t inputState, aaudio_stream_state_t* _Nullable nextState, 1680 int64_t timeoutNanoseconds) __INTRODUCED_IN(26); 1681 1682 // ============================================================ 1683 // Stream I/O 1684 // ============================================================ 1685 1686 /** 1687 * Read data from the stream. 1688 * 1689 * The call will wait until the read is complete or until it runs out of time. 1690 * If timeoutNanos is zero then this call will not wait. 1691 * 1692 * Note that timeoutNanoseconds is a relative duration in wall clock time. 1693 * Time will not stop if the thread is asleep. 1694 * So it will be implemented using CLOCK_BOOTTIME. 1695 * 1696 * This call is "strong non-blocking" unless it has to wait for data. 1697 * 1698 * If the call times out then zero or a partial frame count will be returned. 1699 * 1700 * Available since API level 26. 1701 * 1702 * @param stream A stream created using AAudioStreamBuilder_openStream(). 1703 * @param buffer The address of the first sample. 1704 * @param numFrames Number of frames to read. Only complete frames will be written. 1705 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. 1706 * @return The number of frames actually read or a negative error. 1707 */ 1708 AAUDIO_API aaudio_result_t AAudioStream_read(AAudioStream* _Nonnull stream, 1709 void* _Nonnull buffer, int32_t numFrames, int64_t timeoutNanoseconds) __INTRODUCED_IN(26); 1710 1711 /** 1712 * Write data to the stream. 1713 * 1714 * The call will wait until the write is complete or until it runs out of time. 1715 * If timeoutNanos is zero then this call will not wait. 1716 * 1717 * Note that timeoutNanoseconds is a relative duration in wall clock time. 1718 * Time will not stop if the thread is asleep. 1719 * So it will be implemented using CLOCK_BOOTTIME. 1720 * 1721 * This call is "strong non-blocking" unless it has to wait for room in the buffer. 1722 * 1723 * If the call times out then zero or a partial frame count will be returned. 1724 * 1725 * Available since API level 26. 1726 * 1727 * @param stream A stream created using AAudioStreamBuilder_openStream(). 1728 * @param buffer The address of the first sample. 1729 * @param numFrames Number of frames to write. Only complete frames will be written. 1730 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. 1731 * @return The number of frames actually written or a negative error. 1732 */ 1733 AAUDIO_API aaudio_result_t AAudioStream_write(AAudioStream* _Nonnull stream, 1734 const void* _Nonnull buffer, int32_t numFrames, int64_t timeoutNanoseconds) 1735 __INTRODUCED_IN(26); 1736 1737 // ============================================================ 1738 // Stream - queries 1739 // ============================================================ 1740 1741 /** 1742 * This can be used to adjust the latency of the buffer by changing 1743 * the threshold where blocking will occur. 1744 * By combining this with AAudioStream_getXRunCount(), the latency can be tuned 1745 * at run-time for each device. 1746 * 1747 * This cannot be set higher than AAudioStream_getBufferCapacityInFrames(). 1748 * 1749 * Note that you will probably not get the exact size you request. 1750 * You can check the return value or call AAudioStream_getBufferSizeInFrames() 1751 * to see what the actual final size is. 1752 * 1753 * Available since API level 26. 1754 * 1755 * @param stream reference provided by AAudioStreamBuilder_openStream() 1756 * @param numFrames requested number of frames that can be filled without blocking 1757 * @return actual buffer size in frames or a negative error 1758 */ 1759 AAUDIO_API aaudio_result_t AAudioStream_setBufferSizeInFrames(AAudioStream* _Nonnull stream, 1760 int32_t numFrames) __INTRODUCED_IN(26); 1761 1762 /** 1763 * Query the maximum number of frames that can be filled without blocking. 1764 * 1765 * Available since API level 26. 1766 * 1767 * @param stream reference provided by AAudioStreamBuilder_openStream() 1768 * @return buffer size in frames. 1769 */ 1770 AAUDIO_API int32_t AAudioStream_getBufferSizeInFrames(AAudioStream* _Nonnull stream) 1771 __INTRODUCED_IN(26); 1772 1773 /** 1774 * Query the number of frames that the application should read or write at 1775 * one time for optimal performance. It is OK if an application writes 1776 * a different number of frames. But the buffer size may need to be larger 1777 * in order to avoid underruns or overruns. 1778 * 1779 * Note that this may or may not match the actual device burst size. 1780 * For some endpoints, the burst size can vary dynamically. 1781 * But these tend to be devices with high latency. 1782 * 1783 * Available since API level 26. 1784 * 1785 * @param stream reference provided by AAudioStreamBuilder_openStream() 1786 * @return burst size 1787 */ 1788 AAUDIO_API int32_t AAudioStream_getFramesPerBurst(AAudioStream* _Nonnull stream) 1789 __INTRODUCED_IN(26); 1790 1791 /** 1792 * Query maximum buffer capacity in frames. 1793 * 1794 * Available since API level 26. 1795 * 1796 * @param stream reference provided by AAudioStreamBuilder_openStream() 1797 * @return buffer capacity in frames 1798 */ 1799 AAUDIO_API int32_t AAudioStream_getBufferCapacityInFrames(AAudioStream* _Nonnull stream) 1800 __INTRODUCED_IN(26); 1801 1802 /** 1803 * Query the size of the buffer that will be passed to the dataProc callback 1804 * in the numFrames parameter. 1805 * 1806 * This call can be used if the application needs to know the value of numFrames before 1807 * the stream is started. This is not normally necessary. 1808 * 1809 * If a specific size was requested by calling 1810 * AAudioStreamBuilder_setFramesPerDataCallback() then this will be the same size. 1811 * 1812 * If AAudioStreamBuilder_setFramesPerDataCallback() was not called then this will 1813 * return the size chosen by AAudio, or {@link #AAUDIO_UNSPECIFIED}. 1814 * 1815 * {@link #AAUDIO_UNSPECIFIED} indicates that the callback buffer size for this stream 1816 * may vary from one dataProc callback to the next. 1817 * 1818 * Available since API level 26. 1819 * 1820 * @param stream reference provided by AAudioStreamBuilder_openStream() 1821 * @return callback buffer size in frames or {@link #AAUDIO_UNSPECIFIED} 1822 */ 1823 AAUDIO_API int32_t AAudioStream_getFramesPerDataCallback(AAudioStream* _Nonnull stream) 1824 __INTRODUCED_IN(26); 1825 1826 /** 1827 * An XRun is an Underrun or an Overrun. 1828 * During playing, an underrun will occur if the stream is not written in time 1829 * and the system runs out of valid data. 1830 * During recording, an overrun will occur if the stream is not read in time 1831 * and there is no place to put the incoming data so it is discarded. 1832 * 1833 * An underrun or overrun can cause an audible "pop" or "glitch". 1834 * 1835 * Note that some INPUT devices may not support this function. 1836 * In that case a 0 will always be returned. 1837 * 1838 * Available since API level 26. 1839 * 1840 * @param stream reference provided by AAudioStreamBuilder_openStream() 1841 * @return the underrun or overrun count 1842 */ 1843 AAUDIO_API int32_t AAudioStream_getXRunCount(AAudioStream* _Nonnull stream) __INTRODUCED_IN(26); 1844 1845 /** 1846 * Available since API level 26. 1847 * 1848 * @param stream reference provided by AAudioStreamBuilder_openStream() 1849 * @return actual sample rate of the stream 1850 */ 1851 AAUDIO_API int32_t AAudioStream_getSampleRate(AAudioStream* _Nonnull stream) __INTRODUCED_IN(26); 1852 1853 /** 1854 * There may be sample rate conversions in the Audio framework. 1855 * The sample rate set in the stream builder may not be actual sample rate used in the hardware. 1856 * 1857 * This returns the sample rate used by the hardware in Hertz. 1858 * 1859 * If AAudioStreamBuilder_openStream() returned AAUDIO_OK, the result should always be valid. 1860 * 1861 * Available since API level 34. 1862 * 1863 * @param stream reference provided by AAudioStreamBuilder_openStream() 1864 * @return actual sample rate of the underlying hardware 1865 */ 1866 AAUDIO_API int32_t AAudioStream_getHardwareSampleRate(AAudioStream* _Nonnull stream) 1867 __INTRODUCED_IN(__ANDROID_API_U__); 1868 1869 /** 1870 * A stream has one or more channels of data. 1871 * A frame will contain one sample for each channel. 1872 * 1873 * Available since API level 26. 1874 * 1875 * @param stream reference provided by AAudioStreamBuilder_openStream() 1876 * @return actual number of channels of the stream 1877 */ 1878 AAUDIO_API int32_t AAudioStream_getChannelCount(AAudioStream* _Nonnull stream) __INTRODUCED_IN(26); 1879 1880 /** 1881 * There may be channel conversions in the Audio framework. 1882 * The channel count or channel mask set in the stream builder may not be actual number of 1883 * channels used in the hardware. 1884 * 1885 * This returns the channel count used by the hardware. 1886 * 1887 * If AAudioStreamBuilder_openStream() returned AAUDIO_OK, the result should always be valid. 1888 * 1889 * Available since API level 34. 1890 * 1891 * @param stream reference provided by AAudioStreamBuilder_openStream() 1892 * @return actual number of channels of the underlying hardware 1893 */ 1894 AAUDIO_API int32_t AAudioStream_getHardwareChannelCount(AAudioStream* _Nonnull stream) 1895 __INTRODUCED_IN(__ANDROID_API_U__); 1896 1897 /** 1898 * Identical to AAudioStream_getChannelCount(). 1899 * 1900 * Available since API level 26. 1901 * 1902 * @param stream reference provided by AAudioStreamBuilder_openStream() 1903 * @return actual number of samples frame 1904 */ 1905 AAUDIO_API int32_t AAudioStream_getSamplesPerFrame(AAudioStream* _Nonnull stream) 1906 __INTRODUCED_IN(26); 1907 1908 /** 1909 * Available since API level 26. 1910 * 1911 * @param stream reference provided by AAudioStreamBuilder_openStream() 1912 * @return actual device ID 1913 */ 1914 AAUDIO_API int32_t AAudioStream_getDeviceId(AAudioStream* _Nonnull stream) __INTRODUCED_IN(26); 1915 1916 /** 1917 * Available since API level 26. 1918 * 1919 * @param stream reference provided by AAudioStreamBuilder_openStream() 1920 * @return actual data format of the stream 1921 */ 1922 AAUDIO_API aaudio_format_t AAudioStream_getFormat(AAudioStream* _Nonnull stream) 1923 __INTRODUCED_IN(26); 1924 1925 /** 1926 * There may be data format conversions in the Audio framework. 1927 * The data format set in the stream builder may not be actual format used in the hardware. 1928 * 1929 * This returns the audio format used by the hardware. 1930 * 1931 * If AAudioStreamBuilder_openStream() returned AAUDIO_OK, this should always return an 1932 * aaudio_format_t. 1933 * 1934 * AUDIO_FORMAT_PCM_8_24_BIT is currently not supported in AAudio, but the hardware may use it. 1935 * If AUDIO_FORMAT_PCM_8_24_BIT is used by the hardware, return AAUDIO_FORMAT_PCM_I24_PACKED. 1936 * 1937 * If any other format used by the hardware is not supported by AAudio, this will return 1938 * AAUDIO_FORMAT_INVALID. 1939 * 1940 * Available since API level 34. 1941 * 1942 * @param stream reference provided by AAudioStreamBuilder_openStream() 1943 * @return actual data format of the underlying hardware. 1944 */ 1945 AAUDIO_API aaudio_format_t AAudioStream_getHardwareFormat(AAudioStream* _Nonnull stream) 1946 __INTRODUCED_IN(__ANDROID_API_U__); 1947 1948 /** 1949 * Provide actual sharing mode. 1950 * 1951 * Available since API level 26. 1952 * 1953 * @param stream reference provided by AAudioStreamBuilder_openStream() 1954 * @return actual sharing mode 1955 */ 1956 AAUDIO_API aaudio_sharing_mode_t AAudioStream_getSharingMode(AAudioStream* _Nonnull stream) 1957 __INTRODUCED_IN(26); 1958 1959 /** 1960 * Get the performance mode used by the stream. 1961 * 1962 * Available since API level 26. 1963 * 1964 * @param stream reference provided by AAudioStreamBuilder_openStream() 1965 */ 1966 AAUDIO_API aaudio_performance_mode_t AAudioStream_getPerformanceMode(AAudioStream* _Nonnull stream) 1967 __INTRODUCED_IN(26); 1968 1969 /** 1970 * Available since API level 26. 1971 * 1972 * @param stream reference provided by AAudioStreamBuilder_openStream() 1973 * @return direction 1974 */ 1975 AAUDIO_API aaudio_direction_t AAudioStream_getDirection(AAudioStream* _Nonnull stream) 1976 __INTRODUCED_IN(26); 1977 1978 /** 1979 * Passes back the number of frames that have been written since the stream was created. 1980 * For an output stream, this will be advanced by the application calling write() 1981 * or by a data callback. 1982 * For an input stream, this will be advanced by the endpoint. 1983 * 1984 * The frame position is monotonically increasing. 1985 * 1986 * Available since API level 26. 1987 * 1988 * @param stream reference provided by AAudioStreamBuilder_openStream() 1989 * @return frames written 1990 */ 1991 AAUDIO_API int64_t AAudioStream_getFramesWritten(AAudioStream* _Nonnull stream) 1992 __INTRODUCED_IN(26); 1993 1994 /** 1995 * Passes back the number of frames that have been read since the stream was created. 1996 * For an output stream, this will be advanced by the endpoint. 1997 * For an input stream, this will be advanced by the application calling read() 1998 * or by a data callback. 1999 * 2000 * The frame position is monotonically increasing. 2001 * 2002 * Available since API level 26. 2003 * 2004 * @param stream reference provided by AAudioStreamBuilder_openStream() 2005 * @return frames read 2006 */ 2007 AAUDIO_API int64_t AAudioStream_getFramesRead(AAudioStream* _Nonnull stream) __INTRODUCED_IN(26); 2008 2009 /** 2010 * Passes back the session ID associated with this stream. 2011 * 2012 * The session ID can be used to associate a stream with effects processors. 2013 * The effects are controlled using the Android AudioEffect Java API. 2014 * 2015 * If AAudioStreamBuilder_setSessionId() was 2016 * called with {@link #AAUDIO_SESSION_ID_ALLOCATE} 2017 * then a new session ID should be allocated once when the stream is opened. 2018 * 2019 * If AAudioStreamBuilder_setSessionId() was called with a previously allocated 2020 * session ID then that value should be returned. 2021 * 2022 * If AAudioStreamBuilder_setSessionId() was not called then this function should 2023 * return {@link #AAUDIO_SESSION_ID_NONE}. 2024 * 2025 * The sessionID for a stream should not change once the stream has been opened. 2026 * 2027 * Available since API level 28. 2028 * 2029 * @param stream reference provided by AAudioStreamBuilder_openStream() 2030 * @return session ID or {@link #AAUDIO_SESSION_ID_NONE} 2031 */ 2032 AAUDIO_API aaudio_session_id_t AAudioStream_getSessionId(AAudioStream* _Nonnull stream) 2033 __INTRODUCED_IN(28); 2034 2035 /** 2036 * Returns the time at which a particular frame was played on a speaker or headset, 2037 * or was recorded on a microphone. 2038 * 2039 * This can be used to synchronize audio with video or MIDI. 2040 * It can also be used to align a recorded stream with a playback stream. 2041 * 2042 * The framePosition is an index into the stream of audio data. 2043 * The first frame played or recorded is at framePosition 0. 2044 * 2045 * These framePositions are the same units that you get from AAudioStream_getFramesRead() 2046 * or AAudioStream_getFramesWritten(). 2047 * A "frame" is a set of audio sample values that are played simultaneously. 2048 * For example, a stereo stream has two samples in a frame, left and right. 2049 * 2050 * Timestamps are only valid when the stream is in {@link #AAUDIO_STREAM_STATE_STARTED}. 2051 * {@link #AAUDIO_ERROR_INVALID_STATE} will be returned if the stream is not started. 2052 * Note that because requestStart() is asynchronous, timestamps will not be valid until 2053 * a short time after calling requestStart(). 2054 * So {@link #AAUDIO_ERROR_INVALID_STATE} should not be considered a fatal error. 2055 * Just try calling again later. 2056 * 2057 * If an error occurs, then the position and time will not be modified. 2058 * 2059 * The position and time passed back are monotonically increasing. 2060 * 2061 * Available since API level 26. 2062 * 2063 * @param stream reference provided by AAudioStreamBuilder_openStream() 2064 * @param clockid CLOCK_MONOTONIC or CLOCK_BOOTTIME 2065 * @param[out] framePosition pointer to a variable to receive the position 2066 * @param[out] timeNanoseconds pointer to a variable to receive the time 2067 * @return {@link #AAUDIO_OK} or a negative error 2068 */ 2069 AAUDIO_API aaudio_result_t AAudioStream_getTimestamp(AAudioStream* _Nonnull stream, 2070 clockid_t clockid, int64_t* _Nonnull framePosition, int64_t* _Nonnull timeNanoseconds) 2071 __INTRODUCED_IN(26); 2072 2073 /** 2074 * Return the use case for the stream. 2075 * 2076 * Available since API level 28. 2077 * 2078 * @param stream reference provided by AAudioStreamBuilder_openStream() 2079 * @return frames read 2080 */ 2081 AAUDIO_API aaudio_usage_t AAudioStream_getUsage(AAudioStream* _Nonnull stream) __INTRODUCED_IN(28); 2082 2083 /** 2084 * Return the content type for the stream. 2085 * 2086 * Available since API level 28. 2087 * 2088 * @param stream reference provided by AAudioStreamBuilder_openStream() 2089 * @return content type, for example {@link #AAUDIO_CONTENT_TYPE_MUSIC} 2090 */ 2091 AAUDIO_API aaudio_content_type_t AAudioStream_getContentType(AAudioStream* _Nonnull stream) 2092 __INTRODUCED_IN(28); 2093 2094 /** 2095 * Return the spatialization behavior for the stream. 2096 * 2097 * If none was explicitly set, it will return the default 2098 * {@link #AAUDIO_SPATIALIZATION_BEHAVIOR_AUTO} behavior. 2099 * 2100 * Available since API level 32. 2101 * 2102 * @param stream reference provided by AAudioStreamBuilder_openStream() 2103 * @return spatialization behavior, for example {@link #AAUDIO_SPATIALIZATION_BEHAVIOR_AUTO} 2104 */ 2105 AAUDIO_API aaudio_spatialization_behavior_t AAudioStream_getSpatializationBehavior( 2106 AAudioStream* _Nonnull stream) __INTRODUCED_IN(32); 2107 2108 /** 2109 * Return whether the content of the stream is spatialized. 2110 * 2111 * Available since API level 32. 2112 * 2113 * @param stream reference provided by AAudioStreamBuilder_openStream() 2114 * @return true if the content is spatialized 2115 */ 2116 AAUDIO_API bool AAudioStream_isContentSpatialized(AAudioStream* _Nonnull stream) 2117 __INTRODUCED_IN(32); 2118 2119 2120 /** 2121 * Return the input preset for the stream. 2122 * 2123 * Available since API level 28. 2124 * 2125 * @param stream reference provided by AAudioStreamBuilder_openStream() 2126 * @return input preset, for example {@link #AAUDIO_INPUT_PRESET_CAMCORDER} 2127 */ 2128 AAUDIO_API aaudio_input_preset_t AAudioStream_getInputPreset(AAudioStream* _Nonnull stream) 2129 __INTRODUCED_IN(28); 2130 2131 /** 2132 * Return the policy that determines whether the audio may or may not be captured 2133 * by other apps or the system. 2134 * 2135 * Available since API level 29. 2136 * 2137 * @param stream reference provided by AAudioStreamBuilder_openStream() 2138 * @return the allowed capture policy, for example {@link #AAUDIO_ALLOW_CAPTURE_BY_ALL} 2139 */ 2140 AAUDIO_API aaudio_allowed_capture_policy_t AAudioStream_getAllowedCapturePolicy( 2141 AAudioStream* _Nonnull stream) __INTRODUCED_IN(29); 2142 2143 2144 /** 2145 * Return whether this input stream is marked as privacy sensitive or not. 2146 * 2147 * See {@link #AAudioStreamBuilder_setPrivacySensitive()}. 2148 * 2149 * Added in API level 30. 2150 * 2151 * @param stream reference provided by AAudioStreamBuilder_openStream() 2152 * @return true if privacy sensitive, false otherwise 2153 */ 2154 AAUDIO_API bool AAudioStream_isPrivacySensitive(AAudioStream* _Nonnull stream) 2155 __INTRODUCED_IN(30); 2156 2157 /** 2158 * Return the channel mask for the stream. This will be the mask set using 2159 * {@link #AAudioStreamBuilder_setChannelMask}, or {@link #AAUDIO_UNSPECIFIED} otherwise. 2160 * 2161 * Available since API level 32. 2162 * 2163 * @param stream reference provided by AAudioStreamBuilder_openStream() 2164 * @return actual channel mask 2165 */ 2166 AAUDIO_API aaudio_channel_mask_t AAudioStream_getChannelMask(AAudioStream* _Nonnull stream) 2167 __INTRODUCED_IN(32); 2168 2169 #ifdef __cplusplus 2170 } 2171 #endif 2172 2173 #endif //AAUDIO_AAUDIO_H 2174 2175 /** @} */ 2176