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