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 typedef int32_t aaudio_input_preset_t; 544 545 /** 546 * Specifying if audio may or may not be captured by other apps or the system. 547 * 548 * Note that these match the equivalent values in 549 * <a href="/reference/android/media/AudioAttributes">AudioAttributes</a> 550 * in the Android Java API. 551 * 552 * Added in API level 29. 553 */ 554 enum { 555 /** 556 * Indicates that the audio may be captured by any app. 557 * 558 * For privacy, the following usages can not be recorded: AAUDIO_VOICE_COMMUNICATION*, 559 * AAUDIO_USAGE_NOTIFICATION*, AAUDIO_USAGE_ASSISTANCE* and {@link #AAUDIO_USAGE_ASSISTANT}. 560 * 561 * On <a href="/reference/android/os/Build.VERSION_CODES#Q">Build.VERSION_CODES</a>, 562 * this means only {@link #AAUDIO_USAGE_MEDIA} and {@link #AAUDIO_USAGE_GAME} may be captured. 563 * 564 * See <a href="/reference/android/media/AudioAttributes.html#ALLOW_CAPTURE_BY_ALL"> 565 * ALLOW_CAPTURE_BY_ALL</a>. 566 */ 567 AAUDIO_ALLOW_CAPTURE_BY_ALL = 1, 568 /** 569 * Indicates that the audio may only be captured by system apps. 570 * 571 * System apps can capture for many purposes like accessibility, user guidance... 572 * but have strong restriction. See 573 * <a href="/reference/android/media/AudioAttributes.html#ALLOW_CAPTURE_BY_SYSTEM"> 574 * ALLOW_CAPTURE_BY_SYSTEM</a> 575 * for what the system apps can do with the capture audio. 576 */ 577 AAUDIO_ALLOW_CAPTURE_BY_SYSTEM = 2, 578 /** 579 * Indicates that the audio may not be recorded by any app, even if it is a system app. 580 * 581 * It is encouraged to use {@link #AAUDIO_ALLOW_CAPTURE_BY_SYSTEM} instead of this value as system apps 582 * provide significant and useful features for the user (eg. accessibility). 583 * See <a href="/reference/android/media/AudioAttributes.html#ALLOW_CAPTURE_BY_NONE"> 584 * ALLOW_CAPTURE_BY_NONE</a>. 585 */ 586 AAUDIO_ALLOW_CAPTURE_BY_NONE = 3, 587 }; 588 589 typedef int32_t aaudio_allowed_capture_policy_t; 590 591 /** 592 * These may be used with AAudioStreamBuilder_setSessionId(). 593 * 594 * Added in API level 28. 595 */ 596 enum { 597 /** 598 * Do not allocate a session ID. 599 * Effects cannot be used with this stream. 600 * Default. 601 * 602 * Added in API level 28. 603 */ 604 AAUDIO_SESSION_ID_NONE = -1, 605 606 /** 607 * Allocate a session ID that can be used to attach and control 608 * effects using the Java AudioEffects API. 609 * Note that using this may result in higher latency. 610 * 611 * Note that this matches the value of AudioManager.AUDIO_SESSION_ID_GENERATE. 612 * 613 * Added in API level 28. 614 */ 615 AAUDIO_SESSION_ID_ALLOCATE = 0, 616 }; 617 typedef int32_t aaudio_session_id_t; 618 619 /** 620 * Defines the audio channel mask. 621 * Channel masks are used to describe the samples and their 622 * arrangement in the audio frame. They are also used in the endpoint 623 * (e.g. a USB audio interface, a DAC connected to headphones) to 624 * specify allowable configurations of a particular device. 625 * 626 * Added in API level 32. 627 */ 628 enum { 629 /** 630 * Invalid channel mask 631 */ 632 AAUDIO_CHANNEL_INVALID = -1, 633 634 /** 635 * Output audio channel mask 636 */ 637 AAUDIO_CHANNEL_FRONT_LEFT = 1 << 0, 638 AAUDIO_CHANNEL_FRONT_RIGHT = 1 << 1, 639 AAUDIO_CHANNEL_FRONT_CENTER = 1 << 2, 640 AAUDIO_CHANNEL_LOW_FREQUENCY = 1 << 3, 641 AAUDIO_CHANNEL_BACK_LEFT = 1 << 4, 642 AAUDIO_CHANNEL_BACK_RIGHT = 1 << 5, 643 AAUDIO_CHANNEL_FRONT_LEFT_OF_CENTER = 1 << 6, 644 AAUDIO_CHANNEL_FRONT_RIGHT_OF_CENTER = 1 << 7, 645 AAUDIO_CHANNEL_BACK_CENTER = 1 << 8, 646 AAUDIO_CHANNEL_SIDE_LEFT = 1 << 9, 647 AAUDIO_CHANNEL_SIDE_RIGHT = 1 << 10, 648 AAUDIO_CHANNEL_TOP_CENTER = 1 << 11, 649 AAUDIO_CHANNEL_TOP_FRONT_LEFT = 1 << 12, 650 AAUDIO_CHANNEL_TOP_FRONT_CENTER = 1 << 13, 651 AAUDIO_CHANNEL_TOP_FRONT_RIGHT = 1 << 14, 652 AAUDIO_CHANNEL_TOP_BACK_LEFT = 1 << 15, 653 AAUDIO_CHANNEL_TOP_BACK_CENTER = 1 << 16, 654 AAUDIO_CHANNEL_TOP_BACK_RIGHT = 1 << 17, 655 AAUDIO_CHANNEL_TOP_SIDE_LEFT = 1 << 18, 656 AAUDIO_CHANNEL_TOP_SIDE_RIGHT = 1 << 19, 657 AAUDIO_CHANNEL_BOTTOM_FRONT_LEFT = 1 << 20, 658 AAUDIO_CHANNEL_BOTTOM_FRONT_CENTER = 1 << 21, 659 AAUDIO_CHANNEL_BOTTOM_FRONT_RIGHT = 1 << 22, 660 AAUDIO_CHANNEL_LOW_FREQUENCY_2 = 1 << 23, 661 AAUDIO_CHANNEL_FRONT_WIDE_LEFT = 1 << 24, 662 AAUDIO_CHANNEL_FRONT_WIDE_RIGHT = 1 << 25, 663 664 AAUDIO_CHANNEL_MONO = AAUDIO_CHANNEL_FRONT_LEFT, 665 AAUDIO_CHANNEL_STEREO = AAUDIO_CHANNEL_FRONT_LEFT | 666 AAUDIO_CHANNEL_FRONT_RIGHT, 667 AAUDIO_CHANNEL_2POINT1 = AAUDIO_CHANNEL_FRONT_LEFT | 668 AAUDIO_CHANNEL_FRONT_RIGHT | 669 AAUDIO_CHANNEL_LOW_FREQUENCY, 670 AAUDIO_CHANNEL_TRI = AAUDIO_CHANNEL_FRONT_LEFT | 671 AAUDIO_CHANNEL_FRONT_RIGHT | 672 AAUDIO_CHANNEL_FRONT_CENTER, 673 AAUDIO_CHANNEL_TRI_BACK = AAUDIO_CHANNEL_FRONT_LEFT | 674 AAUDIO_CHANNEL_FRONT_RIGHT | 675 AAUDIO_CHANNEL_BACK_CENTER, 676 AAUDIO_CHANNEL_3POINT1 = AAUDIO_CHANNEL_FRONT_LEFT | 677 AAUDIO_CHANNEL_FRONT_RIGHT | 678 AAUDIO_CHANNEL_FRONT_CENTER | 679 AAUDIO_CHANNEL_LOW_FREQUENCY, 680 AAUDIO_CHANNEL_2POINT0POINT2 = AAUDIO_CHANNEL_FRONT_LEFT | 681 AAUDIO_CHANNEL_FRONT_RIGHT | 682 AAUDIO_CHANNEL_TOP_SIDE_LEFT | 683 AAUDIO_CHANNEL_TOP_SIDE_RIGHT, 684 AAUDIO_CHANNEL_2POINT1POINT2 = AAUDIO_CHANNEL_2POINT0POINT2 | 685 AAUDIO_CHANNEL_LOW_FREQUENCY, 686 AAUDIO_CHANNEL_3POINT0POINT2 = AAUDIO_CHANNEL_FRONT_LEFT | 687 AAUDIO_CHANNEL_FRONT_RIGHT | 688 AAUDIO_CHANNEL_FRONT_CENTER | 689 AAUDIO_CHANNEL_TOP_SIDE_LEFT | 690 AAUDIO_CHANNEL_TOP_SIDE_RIGHT, 691 AAUDIO_CHANNEL_3POINT1POINT2 = AAUDIO_CHANNEL_3POINT0POINT2 | 692 AAUDIO_CHANNEL_LOW_FREQUENCY, 693 AAUDIO_CHANNEL_QUAD = AAUDIO_CHANNEL_FRONT_LEFT | 694 AAUDIO_CHANNEL_FRONT_RIGHT | 695 AAUDIO_CHANNEL_BACK_LEFT | 696 AAUDIO_CHANNEL_BACK_RIGHT, 697 AAUDIO_CHANNEL_QUAD_SIDE = AAUDIO_CHANNEL_FRONT_LEFT | 698 AAUDIO_CHANNEL_FRONT_RIGHT | 699 AAUDIO_CHANNEL_SIDE_LEFT | 700 AAUDIO_CHANNEL_SIDE_RIGHT, 701 AAUDIO_CHANNEL_SURROUND = AAUDIO_CHANNEL_FRONT_LEFT | 702 AAUDIO_CHANNEL_FRONT_RIGHT | 703 AAUDIO_CHANNEL_FRONT_CENTER | 704 AAUDIO_CHANNEL_BACK_CENTER, 705 AAUDIO_CHANNEL_PENTA = AAUDIO_CHANNEL_QUAD | 706 AAUDIO_CHANNEL_FRONT_CENTER, 707 // aka 5POINT1_BACK 708 AAUDIO_CHANNEL_5POINT1 = AAUDIO_CHANNEL_FRONT_LEFT | 709 AAUDIO_CHANNEL_FRONT_RIGHT | 710 AAUDIO_CHANNEL_FRONT_CENTER | 711 AAUDIO_CHANNEL_LOW_FREQUENCY | 712 AAUDIO_CHANNEL_BACK_LEFT | 713 AAUDIO_CHANNEL_BACK_RIGHT, 714 AAUDIO_CHANNEL_5POINT1_SIDE = AAUDIO_CHANNEL_FRONT_LEFT | 715 AAUDIO_CHANNEL_FRONT_RIGHT | 716 AAUDIO_CHANNEL_FRONT_CENTER | 717 AAUDIO_CHANNEL_LOW_FREQUENCY | 718 AAUDIO_CHANNEL_SIDE_LEFT | 719 AAUDIO_CHANNEL_SIDE_RIGHT, 720 AAUDIO_CHANNEL_6POINT1 = AAUDIO_CHANNEL_FRONT_LEFT | 721 AAUDIO_CHANNEL_FRONT_RIGHT | 722 AAUDIO_CHANNEL_FRONT_CENTER | 723 AAUDIO_CHANNEL_LOW_FREQUENCY | 724 AAUDIO_CHANNEL_BACK_LEFT | 725 AAUDIO_CHANNEL_BACK_RIGHT | 726 AAUDIO_CHANNEL_BACK_CENTER, 727 AAUDIO_CHANNEL_7POINT1 = AAUDIO_CHANNEL_5POINT1 | 728 AAUDIO_CHANNEL_SIDE_LEFT | 729 AAUDIO_CHANNEL_SIDE_RIGHT, 730 AAUDIO_CHANNEL_5POINT1POINT2 = AAUDIO_CHANNEL_5POINT1 | 731 AAUDIO_CHANNEL_TOP_SIDE_LEFT | 732 AAUDIO_CHANNEL_TOP_SIDE_RIGHT, 733 AAUDIO_CHANNEL_5POINT1POINT4 = AAUDIO_CHANNEL_5POINT1 | 734 AAUDIO_CHANNEL_TOP_FRONT_LEFT | 735 AAUDIO_CHANNEL_TOP_FRONT_RIGHT | 736 AAUDIO_CHANNEL_TOP_BACK_LEFT | 737 AAUDIO_CHANNEL_TOP_BACK_RIGHT, 738 AAUDIO_CHANNEL_7POINT1POINT2 = AAUDIO_CHANNEL_7POINT1 | 739 AAUDIO_CHANNEL_TOP_SIDE_LEFT | 740 AAUDIO_CHANNEL_TOP_SIDE_RIGHT, 741 AAUDIO_CHANNEL_7POINT1POINT4 = AAUDIO_CHANNEL_7POINT1 | 742 AAUDIO_CHANNEL_TOP_FRONT_LEFT | 743 AAUDIO_CHANNEL_TOP_FRONT_RIGHT | 744 AAUDIO_CHANNEL_TOP_BACK_LEFT | 745 AAUDIO_CHANNEL_TOP_BACK_RIGHT, 746 AAUDIO_CHANNEL_9POINT1POINT4 = AAUDIO_CHANNEL_7POINT1POINT4 | 747 AAUDIO_CHANNEL_FRONT_WIDE_LEFT | 748 AAUDIO_CHANNEL_FRONT_WIDE_RIGHT, 749 AAUDIO_CHANNEL_9POINT1POINT6 = AAUDIO_CHANNEL_9POINT1POINT4 | 750 AAUDIO_CHANNEL_TOP_SIDE_LEFT | 751 AAUDIO_CHANNEL_TOP_SIDE_RIGHT, 752 753 AAUDIO_CHANNEL_FRONT_BACK = AAUDIO_CHANNEL_FRONT_CENTER | 754 AAUDIO_CHANNEL_BACK_CENTER, 755 }; 756 typedef uint32_t aaudio_channel_mask_t; 757 758 typedef struct AAudioStreamStruct AAudioStream; 759 typedef struct AAudioStreamBuilderStruct AAudioStreamBuilder; 760 761 #ifndef AAUDIO_API 762 #define AAUDIO_API /* export this symbol */ 763 #endif 764 765 // ============================================================ 766 // Audio System 767 // ============================================================ 768 769 /** 770 * The text is the ASCII symbol corresponding to the returnCode, 771 * or an English message saying the returnCode is unrecognized. 772 * This is intended for developers to use when debugging. 773 * It is not for display to users. 774 * 775 * Available since API level 26. 776 * 777 * @return pointer to a text representation of an AAudio result code. 778 */ 779 AAUDIO_API const char * _Nonnull AAudio_convertResultToText(aaudio_result_t returnCode) 780 __INTRODUCED_IN(26); 781 782 /** 783 * The text is the ASCII symbol corresponding to the stream state, 784 * or an English message saying the state is unrecognized. 785 * This is intended for developers to use when debugging. 786 * It is not for display to users. 787 * 788 * Available since API level 26. 789 * 790 * @return pointer to a text representation of an AAudio state. 791 */ 792 AAUDIO_API const char * _Nonnull AAudio_convertStreamStateToText(aaudio_stream_state_t state) 793 __INTRODUCED_IN(26); 794 795 // ============================================================ 796 // StreamBuilder 797 // ============================================================ 798 799 /** 800 * Create a StreamBuilder that can be used to open a Stream. 801 * 802 * The deviceId is initially unspecified, meaning that the current default device will be used. 803 * 804 * The default direction is {@link #AAUDIO_DIRECTION_OUTPUT}. 805 * The default sharing mode is {@link #AAUDIO_SHARING_MODE_SHARED}. 806 * The data format, samplesPerFrames and sampleRate are unspecified and will be 807 * chosen by the device when it is opened. 808 * 809 * AAudioStreamBuilder_delete() must be called when you are done using the builder. 810 * 811 * Available since API level 26. 812 */ 813 AAUDIO_API aaudio_result_t AAudio_createStreamBuilder(AAudioStreamBuilder* _Nullable* _Nonnull 814 builder) __INTRODUCED_IN(26); 815 816 /** 817 * Request an audio device identified by an ID. 818 * 819 * The ID could be obtained from the Java AudioManager. 820 * AudioManager.getDevices() returns an array of {@link AudioDeviceInfo}, 821 * which contains a getId() method. That ID can be passed to this function. 822 * 823 * It is possible that you may not get the device that you requested. 824 * So if it is important to you, you should call 825 * AAudioStream_getDeviceId() after the stream is opened to 826 * verify the actual ID. 827 * 828 * The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED}, 829 * in which case the primary device will be used. 830 * 831 * Available since API level 26. 832 * 833 * @param builder reference provided by AAudio_createStreamBuilder() 834 * @param deviceId device identifier or {@link #AAUDIO_UNSPECIFIED} 835 */ 836 AAUDIO_API void AAudioStreamBuilder_setDeviceId(AAudioStreamBuilder* _Nonnull builder, 837 int32_t deviceId) __INTRODUCED_IN(26); 838 839 /** 840 * Declare the name of the package creating the stream. 841 * 842 * This is usually {@code Context#getPackageName()}. 843 * 844 * The default, if you do not call this function, is a random package in the calling uid. 845 * The vast majority of apps have only one package per calling UID. 846 * If an invalid package name is set, input streams may not be given permission to 847 * record when started. 848 * 849 * The package name is usually the applicationId in your app's build.gradle file. 850 * 851 * Available since API level 31. 852 * 853 * @param builder reference provided by AAudio_createStreamBuilder() 854 * @param packageName packageName of the calling app. 855 */ 856 AAUDIO_API void AAudioStreamBuilder_setPackageName(AAudioStreamBuilder* _Nonnull builder, 857 const char * _Nonnull packageName) __INTRODUCED_IN(31); 858 859 /** 860 * Declare the attribution tag of the context creating the stream. 861 * 862 * This is usually {@code Context#getAttributionTag()}. 863 * 864 * The default, if you do not call this function, is null. 865 * 866 * Available since API level 31. 867 * 868 * @param builder reference provided by AAudio_createStreamBuilder() 869 * @param attributionTag attributionTag of the calling context. 870 */ 871 AAUDIO_API void AAudioStreamBuilder_setAttributionTag(AAudioStreamBuilder* _Nonnull builder, 872 const char * _Nonnull attributionTag) __INTRODUCED_IN(31); 873 874 /** 875 * Request a sample rate in Hertz. 876 * 877 * The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED}. 878 * An optimal value will then be chosen when the stream is opened. 879 * After opening a stream with an unspecified value, the application must 880 * query for the actual value, which may vary by device. 881 * 882 * If an exact value is specified then an opened stream will use that value. 883 * If a stream cannot be opened with the specified value then the open will fail. 884 * 885 * Available since API level 26. 886 * 887 * @param builder reference provided by AAudio_createStreamBuilder() 888 * @param sampleRate frames per second. Common rates include 44100 and 48000 Hz. 889 */ 890 AAUDIO_API void AAudioStreamBuilder_setSampleRate(AAudioStreamBuilder* _Nonnull builder, 891 int32_t sampleRate) __INTRODUCED_IN(26); 892 893 /** 894 * Request a number of channels for the stream. 895 * 896 * The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED}. 897 * An optimal value will then be chosen when the stream is opened. 898 * After opening a stream with an unspecified value, the application must 899 * query for the actual value, which may vary by device. 900 * 901 * If an exact value is specified then an opened stream will use that value. 902 * If a stream cannot be opened with the specified value then the open will fail. 903 * 904 * As the channel count provided here may be different from the corresponding channel count 905 * of channel mask used in {@link AAudioStreamBuilder_setChannelMask}, the last called function 906 * will be respected if both this function and {@link AAudioStreamBuilder_setChannelMask} are 907 * called. 908 * 909 * Note that if the channel count is two then it may get mixed to mono when the device only supports 910 * one channel. If the channel count is greater than two but the device's supported channel count is 911 * less than the requested value, the channels higher than the device channel will be dropped. If 912 * higher channels should be mixed or spatialized, use {@link AAudioStreamBuilder_setChannelMask} 913 * instead. 914 * 915 * Available since API level 26. 916 * 917 * @param builder reference provided by AAudio_createStreamBuilder() 918 * @param channelCount Number of channels desired. 919 */ 920 AAUDIO_API void AAudioStreamBuilder_setChannelCount(AAudioStreamBuilder* _Nonnull builder, 921 int32_t channelCount) __INTRODUCED_IN(26); 922 923 /** 924 * Identical to AAudioStreamBuilder_setChannelCount(). 925 * 926 * Available since API level 26. 927 * 928 * @param builder reference provided by AAudio_createStreamBuilder() 929 * @param samplesPerFrame Number of samples in a frame. 930 * 931 * @deprecated use {@link AAudioStreamBuilder_setChannelCount} 932 */ 933 AAUDIO_API void AAudioStreamBuilder_setSamplesPerFrame(AAudioStreamBuilder* _Nonnull builder, 934 int32_t samplesPerFrame) __INTRODUCED_IN(26); 935 936 /** 937 * Request a sample data format, for example {@link #AAUDIO_FORMAT_PCM_I16}. 938 * 939 * The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED}. 940 * An optimal value will then be chosen when the stream is opened. 941 * After opening a stream with an unspecified value, the application must 942 * query for the actual value, which may vary by device. 943 * 944 * If an exact value is specified then an opened stream will use that value. 945 * If a stream cannot be opened with the specified value then the open will fail. 946 * 947 * Available since API level 26. 948 * 949 * @param builder reference provided by AAudio_createStreamBuilder() 950 * @param format common formats are {@link #AAUDIO_FORMAT_PCM_FLOAT} and 951 * {@link #AAUDIO_FORMAT_PCM_I16}. 952 */ 953 AAUDIO_API void AAudioStreamBuilder_setFormat(AAudioStreamBuilder* _Nonnull builder, 954 aaudio_format_t format) __INTRODUCED_IN(26); 955 956 /** 957 * Request a mode for sharing the device. 958 * 959 * The default, if you do not call this function, is {@link #AAUDIO_SHARING_MODE_SHARED}. 960 * 961 * The requested sharing mode may not be available. 962 * The application can query for the actual mode after the stream is opened. 963 * 964 * Available since API level 26. 965 * 966 * @param builder reference provided by AAudio_createStreamBuilder() 967 * @param sharingMode {@link #AAUDIO_SHARING_MODE_SHARED} or {@link #AAUDIO_SHARING_MODE_EXCLUSIVE} 968 */ 969 AAUDIO_API void AAudioStreamBuilder_setSharingMode(AAudioStreamBuilder* _Nonnull builder, 970 aaudio_sharing_mode_t sharingMode) __INTRODUCED_IN(26); 971 972 /** 973 * Request the direction for a stream. 974 * 975 * The default, if you do not call this function, is {@link #AAUDIO_DIRECTION_OUTPUT}. 976 * 977 * Available since API level 26. 978 * 979 * @param builder reference provided by AAudio_createStreamBuilder() 980 * @param direction {@link #AAUDIO_DIRECTION_OUTPUT} or {@link #AAUDIO_DIRECTION_INPUT} 981 */ 982 AAUDIO_API void AAudioStreamBuilder_setDirection(AAudioStreamBuilder* _Nonnull builder, 983 aaudio_direction_t direction) __INTRODUCED_IN(26); 984 985 /** 986 * Set the requested buffer capacity in frames. 987 * The final AAudioStream capacity may differ, but will probably be at least this big. 988 * 989 * The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED}. 990 * 991 * Available since API level 26. 992 * 993 * @param builder reference provided by AAudio_createStreamBuilder() 994 * @param numFrames the desired buffer capacity in frames or {@link #AAUDIO_UNSPECIFIED} 995 */ 996 AAUDIO_API void AAudioStreamBuilder_setBufferCapacityInFrames( 997 AAudioStreamBuilder* _Nonnull builder, int32_t numFrames) __INTRODUCED_IN(26); 998 999 /** 1000 * Set the requested performance mode. 1001 * 1002 * Supported modes are {@link #AAUDIO_PERFORMANCE_MODE_NONE}, 1003 * {@link #AAUDIO_PERFORMANCE_MODE_POWER_SAVING} * and {@link #AAUDIO_PERFORMANCE_MODE_LOW_LATENCY}. 1004 * 1005 * The default, if you do not call this function, is {@link #AAUDIO_PERFORMANCE_MODE_NONE}. 1006 * 1007 * You may not get the mode you requested. 1008 * You can call AAudioStream_getPerformanceMode() 1009 * to find out the final mode for the stream. 1010 * 1011 * Available since API level 26. 1012 * 1013 * @param builder reference provided by AAudio_createStreamBuilder() 1014 * @param mode the desired performance mode, eg. {@link #AAUDIO_PERFORMANCE_MODE_LOW_LATENCY} 1015 */ 1016 AAUDIO_API void AAudioStreamBuilder_setPerformanceMode(AAudioStreamBuilder* _Nonnull builder, 1017 aaudio_performance_mode_t mode) __INTRODUCED_IN(26); 1018 1019 /** 1020 * Set the intended use case for the output stream. 1021 * 1022 * The AAudio system will use this information to optimize the 1023 * behavior of the stream. 1024 * This could, for example, affect how volume and focus is handled for the stream. 1025 * 1026 * The default, if you do not call this function, is {@link #AAUDIO_USAGE_MEDIA}. 1027 * 1028 * Available since API level 28. 1029 * 1030 * @param builder reference provided by AAudio_createStreamBuilder() 1031 * @param usage the desired usage, eg. {@link #AAUDIO_USAGE_GAME} 1032 */ 1033 AAUDIO_API void AAudioStreamBuilder_setUsage(AAudioStreamBuilder* _Nonnull builder, 1034 aaudio_usage_t usage) __INTRODUCED_IN(28); 1035 1036 /** 1037 * Set the type of audio data that the output stream will carry. 1038 * 1039 * The AAudio system will use this information to optimize the 1040 * behavior of the stream. 1041 * This could, for example, affect whether a stream is paused when a notification occurs. 1042 * 1043 * The default, if you do not call this function, is {@link #AAUDIO_CONTENT_TYPE_MUSIC}. 1044 * 1045 * Available since API level 28. 1046 * 1047 * @param builder reference provided by AAudio_createStreamBuilder() 1048 * @param contentType the type of audio data, eg. {@link #AAUDIO_CONTENT_TYPE_SPEECH} 1049 */ 1050 AAUDIO_API void AAudioStreamBuilder_setContentType(AAudioStreamBuilder* _Nonnull builder, 1051 aaudio_content_type_t contentType) __INTRODUCED_IN(28); 1052 1053 /** 1054 * Sets the behavior affecting whether spatialization will be used. 1055 * 1056 * The AAudio system will use this information to select whether the stream will go 1057 * through a spatializer effect or not when the effect is supported and enabled. 1058 * 1059 * Available since API level 32. 1060 * 1061 * @param builder reference provided by AAudio_createStreamBuilder() 1062 * @param spatializationBehavior the desired behavior with regards to spatialization, eg. 1063 * {@link #AAUDIO_SPATIALIZATION_BEHAVIOR_AUTO} 1064 */ 1065 AAUDIO_API void AAudioStreamBuilder_setSpatializationBehavior( 1066 AAudioStreamBuilder* _Nonnull builder, 1067 aaudio_spatialization_behavior_t spatializationBehavior) __INTRODUCED_IN(32); 1068 1069 /** 1070 * Specifies whether the audio data of this output stream has already been processed for 1071 * spatialization. 1072 * 1073 * If the stream has been processed for spatialization, setting this to true will prevent 1074 * issues such as double-processing on platforms that will spatialize audio data. 1075 * 1076 * Available since API level 32. 1077 * 1078 * @param builder reference provided by AAudio_createStreamBuilder() 1079 * @param isSpatialized true if the content is already processed for binaural or transaural spatial 1080 * rendering, false otherwise. 1081 */ 1082 AAUDIO_API void AAudioStreamBuilder_setIsContentSpatialized(AAudioStreamBuilder* _Nonnull builder, 1083 bool isSpatialized) __INTRODUCED_IN(32); 1084 1085 /** 1086 * Set the input (capture) preset for the stream. 1087 * 1088 * The AAudio system will use this information to optimize the 1089 * behavior of the stream. 1090 * This could, for example, affect which microphones are used and how the 1091 * recorded data is processed. 1092 * 1093 * The default, if you do not call this function, is {@link #AAUDIO_INPUT_PRESET_VOICE_RECOGNITION}. 1094 * That is because VOICE_RECOGNITION is the preset with the lowest latency 1095 * on many platforms. 1096 * 1097 * Available since API level 28. 1098 * 1099 * @param builder reference provided by AAudio_createStreamBuilder() 1100 * @param inputPreset the desired configuration for recording 1101 */ 1102 AAUDIO_API void AAudioStreamBuilder_setInputPreset(AAudioStreamBuilder* _Nonnull builder, 1103 aaudio_input_preset_t inputPreset) __INTRODUCED_IN(28); 1104 1105 /** 1106 * Specify whether this stream audio may or may not be captured by other apps or the system. 1107 * 1108 * The default is {@link #AAUDIO_ALLOW_CAPTURE_BY_ALL}. 1109 * 1110 * Note that an application can also set its global policy, in which case the most restrictive 1111 * policy is always applied. See 1112 * <a href="/reference/android/media/AudioManager#setAllowedCapturePolicy(int)"> 1113 * setAllowedCapturePolicy(int)</a> 1114 * 1115 * Available since API level 29. 1116 * 1117 * @param builder reference provided by AAudio_createStreamBuilder() 1118 * @param capturePolicy the desired level of opt-out from being captured. 1119 */ 1120 AAUDIO_API void AAudioStreamBuilder_setAllowedCapturePolicy(AAudioStreamBuilder* _Nonnull builder, 1121 aaudio_allowed_capture_policy_t capturePolicy) __INTRODUCED_IN(29); 1122 1123 /** Set the requested session ID. 1124 * 1125 * The session ID can be used to associate a stream with effects processors. 1126 * The effects are controlled using the Android AudioEffect Java API. 1127 * 1128 * The default, if you do not call this function, is {@link #AAUDIO_SESSION_ID_NONE}. 1129 * 1130 * If set to {@link #AAUDIO_SESSION_ID_ALLOCATE} then a session ID will be allocated 1131 * when the stream is opened. 1132 * 1133 * The allocated session ID can be obtained by calling AAudioStream_getSessionId() 1134 * and then used with this function when opening another stream. 1135 * This allows effects to be shared between streams. 1136 * 1137 * Session IDs from AAudio can be used with the Android Java APIs and vice versa. 1138 * So a session ID from an AAudio stream can be passed to Java 1139 * and effects applied using the Java AudioEffect API. 1140 * 1141 * Note that allocating or setting a session ID may result in a stream with higher latency. 1142 * 1143 * Allocated session IDs will always be positive and nonzero. 1144 * 1145 * Available since API level 28. 1146 * 1147 * @param builder reference provided by AAudio_createStreamBuilder() 1148 * @param sessionId an allocated sessionID or {@link #AAUDIO_SESSION_ID_ALLOCATE} 1149 */ 1150 AAUDIO_API void AAudioStreamBuilder_setSessionId(AAudioStreamBuilder* _Nonnull builder, 1151 aaudio_session_id_t sessionId) __INTRODUCED_IN(28); 1152 1153 1154 /** Indicates whether this input stream must be marked as privacy sensitive or not. 1155 * 1156 * When true, this input stream is privacy sensitive and any concurrent capture 1157 * is not permitted. 1158 * 1159 * This is off (false) by default except when the input preset is {@link #AAUDIO_INPUT_PRESET_VOICE_COMMUNICATION} 1160 * or {@link #AAUDIO_INPUT_PRESET_CAMCORDER}. 1161 * 1162 * Always takes precedence over default from input preset when set explicitly. 1163 * 1164 * Only relevant if the stream direction is {@link #AAUDIO_DIRECTION_INPUT}. 1165 * 1166 * Added in API level 30. 1167 * 1168 * @param builder reference provided by AAudio_createStreamBuilder() 1169 * @param privacySensitive true if capture from this stream must be marked as privacy sensitive, 1170 * false otherwise. 1171 */ 1172 AAUDIO_API void AAudioStreamBuilder_setPrivacySensitive(AAudioStreamBuilder* _Nonnull builder, 1173 bool privacySensitive) __INTRODUCED_IN(30); 1174 1175 /** 1176 * Return one of these values from the data callback function. 1177 */ 1178 enum { 1179 1180 /** 1181 * Continue calling the callback. 1182 */ 1183 AAUDIO_CALLBACK_RESULT_CONTINUE = 0, 1184 1185 /** 1186 * Stop calling the callback. 1187 * 1188 * The application will still need to call AAudioStream_requestPause() 1189 * or AAudioStream_requestStop(). 1190 */ 1191 AAUDIO_CALLBACK_RESULT_STOP, 1192 1193 }; 1194 typedef int32_t aaudio_data_callback_result_t; 1195 1196 /** 1197 * Prototype for the data function that is passed to AAudioStreamBuilder_setDataCallback(). 1198 * 1199 * For an output stream, this function should render and write numFrames of data 1200 * in the streams current data format to the audioData buffer. 1201 * 1202 * For an input stream, this function should read and process numFrames of data 1203 * from the audioData buffer. The data in the audioData buffer must not be modified 1204 * directly. Instead, it should be copied to another buffer before doing any modification. 1205 * In many cases, writing to the audioData buffer of an input stream will result in a 1206 * native exception. 1207 * 1208 * The audio data is passed through the buffer. So do NOT call AAudioStream_read() or 1209 * AAudioStream_write() on the stream that is making the callback. 1210 * 1211 * Note that numFrames can vary unless AAudioStreamBuilder_setFramesPerDataCallback() 1212 * is called. 1213 * 1214 * Also note that this callback function should be considered a "real-time" function. 1215 * It must not do anything that could cause an unbounded delay because that can cause the 1216 * audio to glitch or pop. 1217 * 1218 * These are things the function should NOT do: 1219 * <ul> 1220 * <li>allocate memory using, for example, malloc() or new</li> 1221 * <li>any file operations such as opening, closing, reading or writing</li> 1222 * <li>any network operations such as streaming</li> 1223 * <li>use any mutexes or other synchronization primitives</li> 1224 * <li>sleep</li> 1225 * <li>stop or close the stream</li> 1226 * <li>AAudioStream_read()</li> 1227 * <li>AAudioStream_write()</li> 1228 * </ul> 1229 * 1230 * The following are OK to call from the data callback: 1231 * <ul> 1232 * <li>AAudioStream_get*()</li> 1233 * <li>AAudio_convertResultToText()</li> 1234 * </ul> 1235 * 1236 * If you need to move data, eg. MIDI commands, in or out of the callback function then 1237 * we recommend the use of non-blocking techniques such as an atomic FIFO. 1238 * 1239 * @param stream reference provided by AAudioStreamBuilder_openStream() 1240 * @param userData the same address that was passed to AAudioStreamBuilder_setCallback() 1241 * @param audioData a pointer to the audio data 1242 * @param numFrames the number of frames to be processed, which can vary 1243 * @return AAUDIO_CALLBACK_RESULT_* 1244 */ 1245 typedef aaudio_data_callback_result_t (*AAudioStream_dataCallback)( 1246 AAudioStream* _Nonnull stream, 1247 void* _Nullable userData, 1248 void* _Nonnull audioData, 1249 int32_t numFrames); 1250 1251 /** 1252 * Request that AAudio call this functions when the stream is running. 1253 * 1254 * Note that when using this callback, the audio data will be passed in or out 1255 * of the function as an argument. 1256 * So you cannot call AAudioStream_write() or AAudioStream_read() 1257 * on the same stream that has an active data callback. 1258 * 1259 * The callback function will start being called after AAudioStream_requestStart() 1260 * is called. 1261 * It will stop being called after AAudioStream_requestPause() or 1262 * AAudioStream_requestStop() is called. 1263 * 1264 * This callback function will be called on a real-time thread owned by AAudio. 1265 * The low latency streams may have callback threads with higher priority than normal streams. 1266 * See {@link #AAudioStream_dataCallback} for more information. 1267 * 1268 * Note that the AAudio callbacks will never be called simultaneously from multiple threads. 1269 * 1270 * Available since API level 26. 1271 * 1272 * @param builder reference provided by AAudio_createStreamBuilder() 1273 * @param callback pointer to a function that will process audio data. 1274 * @param userData pointer to an application data structure that will be passed 1275 * to the callback functions. 1276 */ 1277 AAUDIO_API void AAudioStreamBuilder_setDataCallback(AAudioStreamBuilder* _Nonnull builder, 1278 AAudioStream_dataCallback _Nullable callback, void* _Nullable userData) 1279 __INTRODUCED_IN(26); 1280 1281 /** 1282 * Set the requested data callback buffer size in frames. 1283 * See {@link #AAudioStream_dataCallback}. 1284 * 1285 * The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED}. 1286 * 1287 * For the lowest possible latency, do not call this function. AAudio will then 1288 * call the dataProc callback function with whatever size is optimal. 1289 * That size may vary from one callback to another. 1290 * 1291 * Only use this function if the application requires a specific number of frames for processing. 1292 * The application might, for example, be using an FFT that requires 1293 * a specific power-of-two sized buffer. 1294 * 1295 * AAudio may need to add additional buffering in order to adapt between the internal 1296 * buffer size and the requested buffer size. 1297 * 1298 * If you do call this function then the requested size should be less than 1299 * half the buffer capacity, to allow double buffering. 1300 * 1301 * Available since API level 26. 1302 * 1303 * @param builder reference provided by AAudio_createStreamBuilder() 1304 * @param numFrames the desired buffer size in frames or {@link #AAUDIO_UNSPECIFIED} 1305 */ 1306 AAUDIO_API void AAudioStreamBuilder_setFramesPerDataCallback(AAudioStreamBuilder* _Nonnull builder, 1307 int32_t numFrames) __INTRODUCED_IN(26); 1308 1309 /** 1310 * Prototype for the callback function that is passed to 1311 * AAudioStreamBuilder_setErrorCallback(). 1312 * 1313 * The following may NOT be called from the error callback: 1314 * <ul> 1315 * <li>AAudioStream_requestStop()</li> 1316 * <li>AAudioStream_requestPause()</li> 1317 * <li>AAudioStream_close()</li> 1318 * <li>AAudioStream_waitForStateChange()</li> 1319 * <li>AAudioStream_read()</li> 1320 * <li>AAudioStream_write()</li> 1321 * </ul> 1322 * 1323 * The following are OK to call from the error callback: 1324 * <ul> 1325 * <li>AAudioStream_get*()</li> 1326 * <li>AAudio_convertResultToText()</li> 1327 * </ul> 1328 * 1329 * @param stream reference provided by AAudioStreamBuilder_openStream() 1330 * @param userData the same address that was passed to AAudioStreamBuilder_setErrorCallback() 1331 * @param error an AAUDIO_ERROR_* value. 1332 */ 1333 typedef void (*AAudioStream_errorCallback)( 1334 AAudioStream* _Nonnull stream, 1335 void* _Nullable userData, 1336 aaudio_result_t error); 1337 1338 /** 1339 * Request that AAudio call this function if any error occurs or the stream is disconnected. 1340 * 1341 * It will be called, for example, if a headset or a USB device is unplugged causing the stream's 1342 * device to be unavailable or "disconnected". 1343 * Another possible cause of error would be a timeout or an unanticipated internal error. 1344 * 1345 * In response, this function should signal or create another thread to stop 1346 * and close this stream. The other thread could then reopen a stream on another device. 1347 * Do not stop or close the stream, or reopen the new stream, directly from this callback. 1348 * 1349 * This callback will not be called because of actions by the application, such as stopping 1350 * or closing a stream. 1351 * 1352 * Note that the AAudio callbacks will never be called simultaneously from multiple threads. 1353 * 1354 * Available since API level 26. 1355 * 1356 * @param builder reference provided by AAudio_createStreamBuilder() 1357 * @param callback pointer to a function that will be called if an error occurs. 1358 * @param userData pointer to an application data structure that will be passed 1359 * to the callback functions. 1360 */ 1361 AAUDIO_API void AAudioStreamBuilder_setErrorCallback(AAudioStreamBuilder* _Nonnull builder, 1362 AAudioStream_errorCallback _Nullable callback, void* _Nullable userData) 1363 __INTRODUCED_IN(26); 1364 1365 /** 1366 * Open a stream based on the options in the StreamBuilder. 1367 * 1368 * AAudioStream_close() must be called when finished with the stream to recover 1369 * the memory and to free the associated resources. 1370 * 1371 * Available since API level 26. 1372 * 1373 * @param builder reference provided by AAudio_createStreamBuilder() 1374 * @param stream pointer to a variable to receive the new stream reference 1375 * @return {@link #AAUDIO_OK} or a negative error. 1376 */ 1377 AAUDIO_API aaudio_result_t AAudioStreamBuilder_openStream(AAudioStreamBuilder* _Nonnull builder, 1378 AAudioStream* _Nullable* _Nonnull stream) __INTRODUCED_IN(26); 1379 1380 /** 1381 * Delete the resources associated with the StreamBuilder. 1382 * 1383 * Available since API level 26. 1384 * 1385 * @param builder reference provided by AAudio_createStreamBuilder() 1386 * @return {@link #AAUDIO_OK} or a negative error. 1387 */ 1388 AAUDIO_API aaudio_result_t AAudioStreamBuilder_delete(AAudioStreamBuilder* _Nonnull builder) 1389 __INTRODUCED_IN(26); 1390 1391 /** 1392 * Set audio channel mask for the stream. 1393 * 1394 * The default, if you do not call this function, is {@link #AAUDIO_UNSPECIFIED}. 1395 * If both channel mask and count are not set, then stereo will then be chosen when the 1396 * stream is opened. 1397 * After opening a stream with an unspecified value, the application must query for the 1398 * actual value, which may vary by device. 1399 * 1400 * If an exact value is specified then an opened stream will use that value. 1401 * If a stream cannot be opened with the specified value then the open will fail. 1402 * 1403 * As the corresponding channel count of provided channel mask here may be different 1404 * from the channel count used in {@link AAudioStreamBuilder_setChannelCount} or 1405 * {@link AAudioStreamBuilder_setSamplesPerFrame}, the last called function will be 1406 * respected if this function and {@link AAudioStreamBuilder_setChannelCount} or 1407 * {@link AAudioStreamBuilder_setSamplesPerFrame} are called. 1408 * 1409 * Available since API level 32. 1410 * 1411 * @param builder reference provided by AAudio_createStreamBuilder() 1412 * @param channelMask Audio channel mask desired. 1413 */ 1414 AAUDIO_API void AAudioStreamBuilder_setChannelMask(AAudioStreamBuilder* _Nonnull builder, 1415 aaudio_channel_mask_t channelMask) __INTRODUCED_IN(32); 1416 1417 // ============================================================ 1418 // Stream Control 1419 // ============================================================ 1420 1421 /** 1422 * Free the audio resources associated with a stream created by 1423 * AAudioStreamBuilder_openStream(). 1424 * AAudioStream_close() should be called at some point after calling 1425 * this function. 1426 * 1427 * After this call, the stream will be in {@link #AAUDIO_STREAM_STATE_CLOSING} 1428 * 1429 * This function is useful if you want to release the audio resources immediately, 1430 * but still allow queries to the stream to occur from other threads. This often 1431 * happens if you are monitoring stream progress from a UI thread. 1432 * 1433 * NOTE: This function is only fully implemented for MMAP streams, 1434 * which are low latency streams supported by some devices. 1435 * On other "Legacy" streams some audio resources will still be in use 1436 * and some callbacks may still be in process after this call. 1437 * 1438 * Available since API level 30. 1439 * 1440 * @param stream reference provided by AAudioStreamBuilder_openStream() 1441 * @return {@link #AAUDIO_OK} or a negative error. 1442 */ 1443 AAUDIO_API aaudio_result_t AAudioStream_release(AAudioStream* _Nonnull stream) 1444 __INTRODUCED_IN(30); 1445 1446 /** 1447 * Delete the internal data structures associated with the stream created 1448 * by AAudioStreamBuilder_openStream(). 1449 * 1450 * If AAudioStream_release() has not been called then it will be called automatically. 1451 * 1452 * Available since API level 26. 1453 * 1454 * @param stream reference provided by AAudioStreamBuilder_openStream() 1455 * @return {@link #AAUDIO_OK} or a negative error. 1456 */ 1457 AAUDIO_API aaudio_result_t AAudioStream_close(AAudioStream* _Nonnull stream) __INTRODUCED_IN(26); 1458 1459 /** 1460 * Asynchronously request to start playing the stream. For output streams, one should 1461 * write to the stream to fill the buffer before starting. 1462 * Otherwise it will underflow. 1463 * After this call the state will be in {@link #AAUDIO_STREAM_STATE_STARTING} or 1464 * {@link #AAUDIO_STREAM_STATE_STARTED}. 1465 * 1466 * Available since API level 26. 1467 * 1468 * @param stream reference provided by AAudioStreamBuilder_openStream() 1469 * @return {@link #AAUDIO_OK} or a negative error. 1470 */ 1471 AAUDIO_API aaudio_result_t AAudioStream_requestStart(AAudioStream* _Nonnull stream) 1472 __INTRODUCED_IN(26); 1473 1474 /** 1475 * Asynchronous request for the stream to pause. 1476 * Pausing a stream will freeze the data flow but not flush any buffers. 1477 * Use AAudioStream_requestStart() to resume playback after a pause. 1478 * After this call the state will be in {@link #AAUDIO_STREAM_STATE_PAUSING} or 1479 * {@link #AAUDIO_STREAM_STATE_PAUSED}. 1480 * 1481 * This will return {@link #AAUDIO_ERROR_UNIMPLEMENTED} for input streams. 1482 * For input streams use AAudioStream_requestStop(). 1483 * 1484 * Available since API level 26. 1485 * 1486 * @param stream reference provided by AAudioStreamBuilder_openStream() 1487 * @return {@link #AAUDIO_OK} or a negative error. 1488 */ 1489 AAUDIO_API aaudio_result_t AAudioStream_requestPause(AAudioStream* _Nonnull stream) 1490 __INTRODUCED_IN(26); 1491 1492 /** 1493 * Asynchronous request for the stream to flush. 1494 * Flushing will discard any pending data. 1495 * This call only works if the stream is OPEN, PAUSED, STOPPED, or FLUSHED. 1496 * Calling this function when in other states, 1497 * or calling from an AAudio callback function, 1498 * will have no effect and an error will be returned. 1499 * Frame counters are not reset by a flush. They may be advanced. 1500 * After this call the state will be in {@link #AAUDIO_STREAM_STATE_FLUSHING} or 1501 * {@link #AAUDIO_STREAM_STATE_FLUSHED}. 1502 * 1503 * This will return {@link #AAUDIO_ERROR_UNIMPLEMENTED} for input streams. 1504 * 1505 * Available since API level 26. 1506 * 1507 * @param stream reference provided by AAudioStreamBuilder_openStream() 1508 * @return {@link #AAUDIO_OK} or a negative error. 1509 */ 1510 AAUDIO_API aaudio_result_t AAudioStream_requestFlush(AAudioStream* _Nonnull stream) 1511 __INTRODUCED_IN(26); 1512 1513 /** 1514 * Asynchronous request for the stream to stop. 1515 * The stream will stop after all of the data currently buffered has been played. 1516 * After this call the state will be in {@link #AAUDIO_STREAM_STATE_STOPPING} or 1517 * {@link #AAUDIO_STREAM_STATE_STOPPED}. 1518 * 1519 * Available since API level 26. 1520 * 1521 * @param stream reference provided by AAudioStreamBuilder_openStream() 1522 * @return {@link #AAUDIO_OK} or a negative error. 1523 */ 1524 AAUDIO_API aaudio_result_t AAudioStream_requestStop(AAudioStream* _Nonnull stream) 1525 __INTRODUCED_IN(26); 1526 1527 /** 1528 * Query the current state of the client, eg. {@link #AAUDIO_STREAM_STATE_PAUSING} 1529 * 1530 * This function will immediately return the state without updating the state. 1531 * If you want to update the client state based on the server state then 1532 * call AAudioStream_waitForStateChange() with currentState 1533 * set to {@link #AAUDIO_STREAM_STATE_UNKNOWN} and a zero timeout. 1534 * 1535 * Available since API level 26. 1536 * 1537 * @param stream reference provided by AAudioStreamBuilder_openStream() 1538 */ 1539 AAUDIO_API aaudio_stream_state_t AAudioStream_getState(AAudioStream* _Nonnull stream) 1540 __INTRODUCED_IN(26); 1541 1542 /** 1543 * Wait until the current state no longer matches the input state. 1544 * 1545 * This will update the current client state. 1546 * 1547 * <pre><code> 1548 * aaudio_result_t result = AAUDIO_OK; 1549 * aaudio_stream_state_t currentState = AAudioStream_getState(stream); 1550 * aaudio_stream_state_t inputState = currentState; 1551 * while (result == AAUDIO_OK && currentState != AAUDIO_STREAM_STATE_PAUSED) { 1552 * result = AAudioStream_waitForStateChange( 1553 * stream, inputState, ¤tState, MY_TIMEOUT_NANOS); 1554 * inputState = currentState; 1555 * } 1556 * </code></pre> 1557 * 1558 * Available since API level 26. 1559 * 1560 * @param stream A reference provided by AAudioStreamBuilder_openStream() 1561 * @param inputState The state we want to avoid. 1562 * @param nextState Pointer to a variable that will be set to the new state. 1563 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. 1564 * @return {@link #AAUDIO_OK} or a negative error. 1565 */ 1566 AAUDIO_API aaudio_result_t AAudioStream_waitForStateChange(AAudioStream* _Nonnull stream, 1567 aaudio_stream_state_t inputState, aaudio_stream_state_t* _Nullable nextState, 1568 int64_t timeoutNanoseconds) __INTRODUCED_IN(26); 1569 1570 // ============================================================ 1571 // Stream I/O 1572 // ============================================================ 1573 1574 /** 1575 * Read data from the stream. 1576 * 1577 * The call will wait until the read is complete or until it runs out of time. 1578 * If timeoutNanos is zero then this call will not wait. 1579 * 1580 * Note that timeoutNanoseconds is a relative duration in wall clock time. 1581 * Time will not stop if the thread is asleep. 1582 * So it will be implemented using CLOCK_BOOTTIME. 1583 * 1584 * This call is "strong non-blocking" unless it has to wait for data. 1585 * 1586 * If the call times out then zero or a partial frame count will be returned. 1587 * 1588 * Available since API level 26. 1589 * 1590 * @param stream A stream created using AAudioStreamBuilder_openStream(). 1591 * @param buffer The address of the first sample. 1592 * @param numFrames Number of frames to read. Only complete frames will be written. 1593 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. 1594 * @return The number of frames actually read or a negative error. 1595 */ 1596 AAUDIO_API aaudio_result_t AAudioStream_read(AAudioStream* _Nonnull stream, 1597 void* _Nonnull buffer, int32_t numFrames, int64_t timeoutNanoseconds) __INTRODUCED_IN(26); 1598 1599 /** 1600 * Write data to the stream. 1601 * 1602 * The call will wait until the write is complete or until it runs out of time. 1603 * If timeoutNanos is zero then this call will not wait. 1604 * 1605 * Note that timeoutNanoseconds is a relative duration in wall clock time. 1606 * Time will not stop if the thread is asleep. 1607 * So it will be implemented using CLOCK_BOOTTIME. 1608 * 1609 * This call is "strong non-blocking" unless it has to wait for room in the buffer. 1610 * 1611 * If the call times out then zero or a partial frame count will be returned. 1612 * 1613 * Available since API level 26. 1614 * 1615 * @param stream A stream created using AAudioStreamBuilder_openStream(). 1616 * @param buffer The address of the first sample. 1617 * @param numFrames Number of frames to write. Only complete frames will be written. 1618 * @param timeoutNanoseconds Maximum number of nanoseconds to wait for completion. 1619 * @return The number of frames actually written or a negative error. 1620 */ 1621 AAUDIO_API aaudio_result_t AAudioStream_write(AAudioStream* _Nonnull stream, 1622 const void* _Nonnull buffer, int32_t numFrames, int64_t timeoutNanoseconds) 1623 __INTRODUCED_IN(26); 1624 1625 // ============================================================ 1626 // Stream - queries 1627 // ============================================================ 1628 1629 /** 1630 * This can be used to adjust the latency of the buffer by changing 1631 * the threshold where blocking will occur. 1632 * By combining this with AAudioStream_getXRunCount(), the latency can be tuned 1633 * at run-time for each device. 1634 * 1635 * This cannot be set higher than AAudioStream_getBufferCapacityInFrames(). 1636 * 1637 * Note that you will probably not get the exact size you request. 1638 * You can check the return value or call AAudioStream_getBufferSizeInFrames() 1639 * to see what the actual final size is. 1640 * 1641 * Available since API level 26. 1642 * 1643 * @param stream reference provided by AAudioStreamBuilder_openStream() 1644 * @param numFrames requested number of frames that can be filled without blocking 1645 * @return actual buffer size in frames or a negative error 1646 */ 1647 AAUDIO_API aaudio_result_t AAudioStream_setBufferSizeInFrames(AAudioStream* _Nonnull stream, 1648 int32_t numFrames) __INTRODUCED_IN(26); 1649 1650 /** 1651 * Query the maximum number of frames that can be filled without blocking. 1652 * 1653 * Available since API level 26. 1654 * 1655 * @param stream reference provided by AAudioStreamBuilder_openStream() 1656 * @return buffer size in frames. 1657 */ 1658 AAUDIO_API int32_t AAudioStream_getBufferSizeInFrames(AAudioStream* _Nonnull stream) 1659 __INTRODUCED_IN(26); 1660 1661 /** 1662 * Query the number of frames that the application should read or write at 1663 * one time for optimal performance. It is OK if an application writes 1664 * a different number of frames. But the buffer size may need to be larger 1665 * in order to avoid underruns or overruns. 1666 * 1667 * Note that this may or may not match the actual device burst size. 1668 * For some endpoints, the burst size can vary dynamically. 1669 * But these tend to be devices with high latency. 1670 * 1671 * Available since API level 26. 1672 * 1673 * @param stream reference provided by AAudioStreamBuilder_openStream() 1674 * @return burst size 1675 */ 1676 AAUDIO_API int32_t AAudioStream_getFramesPerBurst(AAudioStream* _Nonnull stream) 1677 __INTRODUCED_IN(26); 1678 1679 /** 1680 * Query maximum buffer capacity in frames. 1681 * 1682 * Available since API level 26. 1683 * 1684 * @param stream reference provided by AAudioStreamBuilder_openStream() 1685 * @return buffer capacity in frames 1686 */ 1687 AAUDIO_API int32_t AAudioStream_getBufferCapacityInFrames(AAudioStream* _Nonnull stream) 1688 __INTRODUCED_IN(26); 1689 1690 /** 1691 * Query the size of the buffer that will be passed to the dataProc callback 1692 * in the numFrames parameter. 1693 * 1694 * This call can be used if the application needs to know the value of numFrames before 1695 * the stream is started. This is not normally necessary. 1696 * 1697 * If a specific size was requested by calling 1698 * AAudioStreamBuilder_setFramesPerDataCallback() then this will be the same size. 1699 * 1700 * If AAudioStreamBuilder_setFramesPerDataCallback() was not called then this will 1701 * return the size chosen by AAudio, or {@link #AAUDIO_UNSPECIFIED}. 1702 * 1703 * {@link #AAUDIO_UNSPECIFIED} indicates that the callback buffer size for this stream 1704 * may vary from one dataProc callback to the next. 1705 * 1706 * Available since API level 26. 1707 * 1708 * @param stream reference provided by AAudioStreamBuilder_openStream() 1709 * @return callback buffer size in frames or {@link #AAUDIO_UNSPECIFIED} 1710 */ 1711 AAUDIO_API int32_t AAudioStream_getFramesPerDataCallback(AAudioStream* _Nonnull stream) 1712 __INTRODUCED_IN(26); 1713 1714 /** 1715 * An XRun is an Underrun or an Overrun. 1716 * During playing, an underrun will occur if the stream is not written in time 1717 * and the system runs out of valid data. 1718 * During recording, an overrun will occur if the stream is not read in time 1719 * and there is no place to put the incoming data so it is discarded. 1720 * 1721 * An underrun or overrun can cause an audible "pop" or "glitch". 1722 * 1723 * Note that some INPUT devices may not support this function. 1724 * In that case a 0 will always be returned. 1725 * 1726 * Available since API level 26. 1727 * 1728 * @param stream reference provided by AAudioStreamBuilder_openStream() 1729 * @return the underrun or overrun count 1730 */ 1731 AAUDIO_API int32_t AAudioStream_getXRunCount(AAudioStream* _Nonnull stream) __INTRODUCED_IN(26); 1732 1733 /** 1734 * Available since API level 26. 1735 * 1736 * @param stream reference provided by AAudioStreamBuilder_openStream() 1737 * @return actual sample rate of the stream 1738 */ 1739 AAUDIO_API int32_t AAudioStream_getSampleRate(AAudioStream* _Nonnull stream) __INTRODUCED_IN(26); 1740 1741 /** 1742 * There may be sample rate conversions in the Audio framework. 1743 * The sample rate set in the stream builder may not be actual sample rate used in the hardware. 1744 * 1745 * This returns the sample rate used by the hardware in Hertz. 1746 * 1747 * If AAudioStreamBuilder_openStream() returned AAUDIO_OK, the result should always be valid. 1748 * 1749 * Available since API level 34. 1750 * 1751 * @param stream reference provided by AAudioStreamBuilder_openStream() 1752 * @return actual sample rate of the underlying hardware 1753 */ 1754 AAUDIO_API int32_t AAudioStream_getHardwareSampleRate(AAudioStream* _Nonnull stream) 1755 __INTRODUCED_IN(__ANDROID_API_U__); 1756 1757 /** 1758 * A stream has one or more channels of data. 1759 * A frame will contain one sample for each channel. 1760 * 1761 * Available since API level 26. 1762 * 1763 * @param stream reference provided by AAudioStreamBuilder_openStream() 1764 * @return actual number of channels of the stream 1765 */ 1766 AAUDIO_API int32_t AAudioStream_getChannelCount(AAudioStream* _Nonnull stream) __INTRODUCED_IN(26); 1767 1768 /** 1769 * There may be channel conversions in the Audio framework. 1770 * The channel count or channel mask set in the stream builder may not be actual number of 1771 * channels used in the hardware. 1772 * 1773 * This returns the channel count used by the hardware. 1774 * 1775 * If AAudioStreamBuilder_openStream() returned AAUDIO_OK, the result should always be valid. 1776 * 1777 * Available since API level 34. 1778 * 1779 * @param stream reference provided by AAudioStreamBuilder_openStream() 1780 * @return actual number of channels of the underlying hardware 1781 */ 1782 AAUDIO_API int32_t AAudioStream_getHardwareChannelCount(AAudioStream* _Nonnull stream) 1783 __INTRODUCED_IN(__ANDROID_API_U__); 1784 1785 /** 1786 * Identical to AAudioStream_getChannelCount(). 1787 * 1788 * Available since API level 26. 1789 * 1790 * @param stream reference provided by AAudioStreamBuilder_openStream() 1791 * @return actual number of samples frame 1792 */ 1793 AAUDIO_API int32_t AAudioStream_getSamplesPerFrame(AAudioStream* _Nonnull stream) 1794 __INTRODUCED_IN(26); 1795 1796 /** 1797 * Available since API level 26. 1798 * 1799 * @param stream reference provided by AAudioStreamBuilder_openStream() 1800 * @return actual device ID 1801 */ 1802 AAUDIO_API int32_t AAudioStream_getDeviceId(AAudioStream* _Nonnull stream) __INTRODUCED_IN(26); 1803 1804 /** 1805 * Available since API level 26. 1806 * 1807 * @param stream reference provided by AAudioStreamBuilder_openStream() 1808 * @return actual data format of the stream 1809 */ 1810 AAUDIO_API aaudio_format_t AAudioStream_getFormat(AAudioStream* _Nonnull stream) 1811 __INTRODUCED_IN(26); 1812 1813 /** 1814 * There may be data format conversions in the Audio framework. 1815 * The data format set in the stream builder may not be actual format used in the hardware. 1816 * 1817 * This returns the audio format used by the hardware. 1818 * 1819 * If AAudioStreamBuilder_openStream() returned AAUDIO_OK, this should always return an 1820 * aaudio_format_t. 1821 * 1822 * AUDIO_FORMAT_PCM_8_24_BIT is currently not supported in AAudio, but the hardware may use it. 1823 * If AUDIO_FORMAT_PCM_8_24_BIT is used by the hardware, return AAUDIO_FORMAT_PCM_I24_PACKED. 1824 * 1825 * If any other format used by the hardware is not supported by AAudio, this will return 1826 * AAUDIO_FORMAT_INVALID. 1827 * 1828 * Available since API level 34. 1829 * 1830 * @param stream reference provided by AAudioStreamBuilder_openStream() 1831 * @return actual data format of the underlying hardware. 1832 */ 1833 AAUDIO_API aaudio_format_t AAudioStream_getHardwareFormat(AAudioStream* _Nonnull stream) 1834 __INTRODUCED_IN(__ANDROID_API_U__); 1835 1836 /** 1837 * Provide actual sharing mode. 1838 * 1839 * Available since API level 26. 1840 * 1841 * @param stream reference provided by AAudioStreamBuilder_openStream() 1842 * @return actual sharing mode 1843 */ 1844 AAUDIO_API aaudio_sharing_mode_t AAudioStream_getSharingMode(AAudioStream* _Nonnull stream) 1845 __INTRODUCED_IN(26); 1846 1847 /** 1848 * Get the performance mode used by the stream. 1849 * 1850 * Available since API level 26. 1851 * 1852 * @param stream reference provided by AAudioStreamBuilder_openStream() 1853 */ 1854 AAUDIO_API aaudio_performance_mode_t AAudioStream_getPerformanceMode(AAudioStream* _Nonnull stream) 1855 __INTRODUCED_IN(26); 1856 1857 /** 1858 * Available since API level 26. 1859 * 1860 * @param stream reference provided by AAudioStreamBuilder_openStream() 1861 * @return direction 1862 */ 1863 AAUDIO_API aaudio_direction_t AAudioStream_getDirection(AAudioStream* _Nonnull stream) 1864 __INTRODUCED_IN(26); 1865 1866 /** 1867 * Passes back the number of frames that have been written since the stream was created. 1868 * For an output stream, this will be advanced by the application calling write() 1869 * or by a data callback. 1870 * For an input stream, this will be advanced by the endpoint. 1871 * 1872 * The frame position is monotonically increasing. 1873 * 1874 * Available since API level 26. 1875 * 1876 * @param stream reference provided by AAudioStreamBuilder_openStream() 1877 * @return frames written 1878 */ 1879 AAUDIO_API int64_t AAudioStream_getFramesWritten(AAudioStream* _Nonnull stream) 1880 __INTRODUCED_IN(26); 1881 1882 /** 1883 * Passes back the number of frames that have been read since the stream was created. 1884 * For an output stream, this will be advanced by the endpoint. 1885 * For an input stream, this will be advanced by the application calling read() 1886 * or by a data callback. 1887 * 1888 * The frame position is monotonically increasing. 1889 * 1890 * Available since API level 26. 1891 * 1892 * @param stream reference provided by AAudioStreamBuilder_openStream() 1893 * @return frames read 1894 */ 1895 AAUDIO_API int64_t AAudioStream_getFramesRead(AAudioStream* _Nonnull stream) __INTRODUCED_IN(26); 1896 1897 /** 1898 * Passes back the session ID associated with this stream. 1899 * 1900 * The session ID can be used to associate a stream with effects processors. 1901 * The effects are controlled using the Android AudioEffect Java API. 1902 * 1903 * If AAudioStreamBuilder_setSessionId() was 1904 * called with {@link #AAUDIO_SESSION_ID_ALLOCATE} 1905 * then a new session ID should be allocated once when the stream is opened. 1906 * 1907 * If AAudioStreamBuilder_setSessionId() was called with a previously allocated 1908 * session ID then that value should be returned. 1909 * 1910 * If AAudioStreamBuilder_setSessionId() was not called then this function should 1911 * return {@link #AAUDIO_SESSION_ID_NONE}. 1912 * 1913 * The sessionID for a stream should not change once the stream has been opened. 1914 * 1915 * Available since API level 28. 1916 * 1917 * @param stream reference provided by AAudioStreamBuilder_openStream() 1918 * @return session ID or {@link #AAUDIO_SESSION_ID_NONE} 1919 */ 1920 AAUDIO_API aaudio_session_id_t AAudioStream_getSessionId(AAudioStream* _Nonnull stream) 1921 __INTRODUCED_IN(28); 1922 1923 /** 1924 * Passes back the time at which a particular frame was presented. 1925 * This can be used to synchronize audio with video or MIDI. 1926 * It can also be used to align a recorded stream with a playback stream. 1927 * 1928 * Timestamps are only valid when the stream is in {@link #AAUDIO_STREAM_STATE_STARTED}. 1929 * {@link #AAUDIO_ERROR_INVALID_STATE} will be returned if the stream is not started. 1930 * Note that because requestStart() is asynchronous, timestamps will not be valid until 1931 * a short time after calling requestStart(). 1932 * So {@link #AAUDIO_ERROR_INVALID_STATE} should not be considered a fatal error. 1933 * Just try calling again later. 1934 * 1935 * If an error occurs, then the position and time will not be modified. 1936 * 1937 * The position and time passed back are monotonically increasing. 1938 * 1939 * Available since API level 26. 1940 * 1941 * @param stream reference provided by AAudioStreamBuilder_openStream() 1942 * @param clockid CLOCK_MONOTONIC or CLOCK_BOOTTIME 1943 * @param framePosition pointer to a variable to receive the position 1944 * @param timeNanoseconds pointer to a variable to receive the time 1945 * @return {@link #AAUDIO_OK} or a negative error 1946 */ 1947 AAUDIO_API aaudio_result_t AAudioStream_getTimestamp(AAudioStream* _Nonnull stream, 1948 clockid_t clockid, int64_t* _Nonnull framePosition, int64_t* _Nonnull timeNanoseconds) 1949 __INTRODUCED_IN(26); 1950 1951 /** 1952 * Return the use case for the stream. 1953 * 1954 * Available since API level 28. 1955 * 1956 * @param stream reference provided by AAudioStreamBuilder_openStream() 1957 * @return frames read 1958 */ 1959 AAUDIO_API aaudio_usage_t AAudioStream_getUsage(AAudioStream* _Nonnull stream) __INTRODUCED_IN(28); 1960 1961 /** 1962 * Return the content type for the stream. 1963 * 1964 * Available since API level 28. 1965 * 1966 * @param stream reference provided by AAudioStreamBuilder_openStream() 1967 * @return content type, for example {@link #AAUDIO_CONTENT_TYPE_MUSIC} 1968 */ 1969 AAUDIO_API aaudio_content_type_t AAudioStream_getContentType(AAudioStream* _Nonnull stream) 1970 __INTRODUCED_IN(28); 1971 1972 /** 1973 * Return the spatialization behavior for the stream. 1974 * 1975 * If none was explicitly set, it will return the default 1976 * {@link #AAUDIO_SPATIALIZATION_BEHAVIOR_AUTO} behavior. 1977 * 1978 * Available since API level 32. 1979 * 1980 * @param stream reference provided by AAudioStreamBuilder_openStream() 1981 * @return spatialization behavior, for example {@link #AAUDIO_SPATIALIZATION_BEHAVIOR_AUTO} 1982 */ 1983 AAUDIO_API aaudio_spatialization_behavior_t AAudioStream_getSpatializationBehavior( 1984 AAudioStream* _Nonnull stream) __INTRODUCED_IN(32); 1985 1986 /** 1987 * Return whether the content of the stream is spatialized. 1988 * 1989 * Available since API level 32. 1990 * 1991 * @param stream reference provided by AAudioStreamBuilder_openStream() 1992 * @return true if the content is spatialized 1993 */ 1994 AAUDIO_API bool AAudioStream_isContentSpatialized(AAudioStream* _Nonnull stream) 1995 __INTRODUCED_IN(32); 1996 1997 1998 /** 1999 * Return the input preset for the stream. 2000 * 2001 * Available since API level 28. 2002 * 2003 * @param stream reference provided by AAudioStreamBuilder_openStream() 2004 * @return input preset, for example {@link #AAUDIO_INPUT_PRESET_CAMCORDER} 2005 */ 2006 AAUDIO_API aaudio_input_preset_t AAudioStream_getInputPreset(AAudioStream* _Nonnull stream) 2007 __INTRODUCED_IN(28); 2008 2009 /** 2010 * Return the policy that determines whether the audio may or may not be captured 2011 * by other apps or the system. 2012 * 2013 * Available since API level 29. 2014 * 2015 * @param stream reference provided by AAudioStreamBuilder_openStream() 2016 * @return the allowed capture policy, for example {@link #AAUDIO_ALLOW_CAPTURE_BY_ALL} 2017 */ 2018 AAUDIO_API aaudio_allowed_capture_policy_t AAudioStream_getAllowedCapturePolicy( 2019 AAudioStream* _Nonnull stream) __INTRODUCED_IN(29); 2020 2021 2022 /** 2023 * Return whether this input stream is marked as privacy sensitive or not. 2024 * 2025 * See {@link #AAudioStreamBuilder_setPrivacySensitive()}. 2026 * 2027 * Added in API level 30. 2028 * 2029 * @param stream reference provided by AAudioStreamBuilder_openStream() 2030 * @return true if privacy sensitive, false otherwise 2031 */ 2032 AAUDIO_API bool AAudioStream_isPrivacySensitive(AAudioStream* _Nonnull stream) 2033 __INTRODUCED_IN(30); 2034 2035 /** 2036 * Return the channel mask for the stream. This will be the mask set using 2037 * {@link #AAudioStreamBuilder_setChannelMask}, or {@link #AAUDIO_UNSPECIFIED} otherwise. 2038 * 2039 * Available since API level 32. 2040 * 2041 * @param stream reference provided by AAudioStreamBuilder_openStream() 2042 * @return actual channel mask 2043 */ 2044 AAUDIO_API aaudio_channel_mask_t AAudioStream_getChannelMask(AAudioStream* _Nonnull stream) 2045 __INTRODUCED_IN(32); 2046 2047 #ifdef __cplusplus 2048 } 2049 #endif 2050 2051 #endif //AAUDIO_AAUDIO_H 2052 2053 /** @} */ 2054