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