1 /* 2 * Copyright (c) 2023 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup OHAudio 18 * @{ 19 * 20 * @brief Provide the definition of the C interface for the audio module. 21 * 22 * @syscap SystemCapability.Multimedia.Audio.Core 23 * 24 * @since 10 25 * @version 1.0 26 */ 27 28 /** 29 * @file native_audiostream_base.h 30 * 31 * @brief Declare the underlying data structure. 32 * 33 * @library libohaudio.so 34 * @syscap SystemCapability.Multimedia.Audio.Core 35 * @kit AudioKit 36 * @since 10 37 * @version 1.0 38 */ 39 40 #ifndef NATIVE_AUDIOSTREAM_BASE_H 41 #define NATIVE_AUDIOSTREAM_BASE_H 42 43 #include <stdint.h> 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 /** 50 * @brief Define the result of the function execution. 51 * 52 * @since 10 53 */ 54 typedef enum { 55 /** 56 * @error The call was successful. 57 * 58 * @since 10 59 */ 60 AUDIOSTREAM_SUCCESS = 0, 61 62 /** 63 * @error This means that the function was executed with an invalid input parameter. 64 * 65 * @since 10 66 */ 67 AUDIOSTREAM_ERROR_INVALID_PARAM = 1, 68 69 /** 70 * @error Execution status exception. 71 * 72 * @since 10 73 */ 74 AUDIOSTREAM_ERROR_ILLEGAL_STATE = 2, 75 76 /** 77 * @error An system error has occurred. 78 * 79 * @since 10 80 */ 81 AUDIOSTREAM_ERROR_SYSTEM = 3 82 } OH_AudioStream_Result; 83 84 /** 85 * @brief Define the audio stream type. 86 * 87 * @since 10 88 */ 89 typedef enum { 90 /** 91 * The type for audio stream is renderer. 92 * 93 * @since 10 94 */ 95 AUDIOSTREAM_TYPE_RENDERER = 1, 96 97 /** 98 * The type for audio stream is capturer. 99 * 100 * @since 10 101 */ 102 AUDIOSTREAM_TYPE_CAPTURER = 2 103 } OH_AudioStream_Type; 104 105 /** 106 * @brief Define the audio stream sample format. 107 * 108 * @since 10 109 */ 110 typedef enum { 111 /** 112 * Unsigned 8 format. 113 * 114 * @since 10 115 */ 116 AUDIOSTREAM_SAMPLE_U8 = 0, 117 /** 118 * Signed 16 bit integer, little endian. 119 * 120 * @since 10 121 */ 122 AUDIOSTREAM_SAMPLE_S16LE = 1, 123 /** 124 * Signed 24 bit integer, little endian. 125 * 126 * @since 10 127 */ 128 AUDIOSTREAM_SAMPLE_S24LE = 2, 129 /** 130 * Signed 32 bit integer, little endian. 131 * 132 * @since 10 133 */ 134 AUDIOSTREAM_SAMPLE_S32LE = 3, 135 136 /** 137 * Float 32, little endian. 138 * 139 * @since 17 140 */ 141 AUDIOSTREAM_SAMPLE_F32LE = 4, 142 } OH_AudioStream_SampleFormat; 143 144 /** 145 * @brief Define the audio encoding type. 146 * 147 * @since 10 148 */ 149 typedef enum { 150 /** 151 * PCM encoding type. 152 * 153 * @since 10 154 */ 155 AUDIOSTREAM_ENCODING_TYPE_RAW = 0, 156 /** 157 * AudioVivid encoding type. 158 * 159 * @since 12 160 */ 161 AUDIOSTREAM_ENCODING_TYPE_AUDIOVIVID = 1, 162 } OH_AudioStream_EncodingType; 163 164 /** 165 * @brief Define the audio stream usage. 166 * Audio stream usage is used to describe what work scenario 167 * the current stream is used for. 168 * 169 * @since 10 170 */ 171 typedef enum { 172 /** 173 * Unknown usage. 174 * 175 * @since 10 176 */ 177 AUDIOSTREAM_USAGE_UNKNOWN = 0, 178 /** 179 * Music usage. 180 * 181 * @since 10 182 */ 183 AUDIOSTREAM_USAGE_MUSIC = 1, 184 /** 185 * Voice communication usage. 186 * 187 * @since 10 188 */ 189 AUDIOSTREAM_USAGE_VOICE_COMMUNICATION = 2, 190 /** 191 * Voice assistant usage. 192 * 193 * @since 10 194 */ 195 AUDIOSTREAM_USAGE_VOICE_ASSISTANT = 3, 196 /** 197 * Alarm usage. 198 * 199 * @since 10 200 */ 201 AUDIOSTREAM_USAGE_ALARM = 4, 202 /** 203 * Voice message usage. 204 * 205 * @since 10 206 */ 207 AUDIOSTREAM_USAGE_VOICE_MESSAGE = 5, 208 /** 209 * Ringtone usage. 210 * 211 * @since 10 212 */ 213 AUDIOSTREAM_USAGE_RINGTONE = 6, 214 /** 215 * Notification usage. 216 * 217 * @since 10 218 */ 219 AUDIOSTREAM_USAGE_NOTIFICATION = 7, 220 /** 221 * Accessibility usage, such as screen reader. 222 * 223 * @since 10 224 */ 225 AUDIOSTREAM_USAGE_ACCESSIBILITY = 8, 226 /** 227 * Movie or video usage. 228 * 229 * @since 10 230 */ 231 AUDIOSTREAM_USAGE_MOVIE = 10, 232 /** 233 * Game sound effect usage. 234 * 235 * @since 10 236 */ 237 AUDIOSTREAM_USAGE_GAME = 11, 238 /** 239 * Audiobook usage. 240 * 241 * @since 10 242 */ 243 AUDIOSTREAM_USAGE_AUDIOBOOK = 12, 244 /** 245 * Navigation usage. 246 * 247 * @since 10 248 */ 249 AUDIOSTREAM_USAGE_NAVIGATION = 13, 250 /** 251 * Video call usage. 252 * 253 * @since 12 254 */ 255 AUDIOSTREAM_USAGE_VIDEO_COMMUNICATION = 17, 256 } OH_AudioStream_Usage; 257 258 /** 259 * @brief Define the audio latency mode. 260 * 261 * @since 10 262 */ 263 typedef enum { 264 /** 265 * This is a normal audio scene. 266 * 267 * @since 10 268 */ 269 AUDIOSTREAM_LATENCY_MODE_NORMAL = 0, 270 /** 271 * This is a low latency audio scene. 272 * 273 * @since 10 274 */ 275 AUDIOSTREAM_LATENCY_MODE_FAST = 1 276 } OH_AudioStream_LatencyMode; 277 278 /** 279 * @brief Define the audio event. 280 * 281 * @since 10 282 */ 283 typedef enum { 284 /** 285 * The routing of the audio has changed. 286 * 287 * @since 10 288 */ 289 AUDIOSTREAM_EVENT_ROUTING_CHANGED = 0 290 } OH_AudioStream_Event; 291 292 /** 293 * @brief The audio stream states 294 * 295 * @since 10 296 */ 297 typedef enum { 298 /** 299 * The invalid state. 300 * 301 * @since 10 302 */ 303 AUDIOSTREAM_STATE_INVALID = -1, 304 /** 305 * Create new instance state. 306 * 307 * @since 10 308 */ 309 AUDIOSTREAM_STATE_NEW = 0, 310 /** 311 * The prepared state. 312 * 313 * @since 10 314 */ 315 AUDIOSTREAM_STATE_PREPARED = 1, 316 /** 317 * The stream is running. 318 * 319 * @since 10 320 */ 321 AUDIOSTREAM_STATE_RUNNING = 2, 322 /** 323 * The stream is stopped. 324 * 325 * @since 10 326 */ 327 AUDIOSTREAM_STATE_STOPPED = 3, 328 /** 329 * The stream is released. 330 * 331 * @since 10 332 */ 333 AUDIOSTREAM_STATE_RELEASED = 4, 334 /** 335 * The stream is paused. 336 * 337 * @since 10 338 */ 339 AUDIOSTREAM_STATE_PAUSED = 5, 340 } OH_AudioStream_State; 341 342 /** 343 * @brief Defines the audio interrupt type. 344 * 345 * @since 10 346 */ 347 typedef enum { 348 /** 349 * Force type, system change audio state. 350 * 351 * @since 10 352 */ 353 AUDIOSTREAM_INTERRUPT_FORCE = 0, 354 /** 355 * Share type, application change audio state. 356 * 357 * @since 10 358 */ 359 AUDIOSTREAM_INTERRUPT_SHARE = 1 360 } OH_AudioInterrupt_ForceType; 361 362 /** 363 * @brief Defines the audio interrupt hint type. 364 * 365 * @since 10 366 */ 367 typedef enum { 368 /** 369 * None. 370 * 371 * @since 10 372 */ 373 AUDIOSTREAM_INTERRUPT_HINT_NONE = 0, 374 /** 375 * Resume the stream. 376 * 377 * @since 10 378 */ 379 AUDIOSTREAM_INTERRUPT_HINT_RESUME = 1, 380 /** 381 * Pause the stream. 382 * 383 * @since 10 384 */ 385 AUDIOSTREAM_INTERRUPT_HINT_PAUSE = 2, 386 /** 387 * Stop the stream. 388 * 389 * @since 10 390 */ 391 AUDIOSTREAM_INTERRUPT_HINT_STOP = 3, 392 /** 393 * Ducked the stream. 394 * 395 * @since 10 396 */ 397 AUDIOSTREAM_INTERRUPT_HINT_DUCK = 4, 398 /** 399 * Unducked the stream. 400 * 401 * @since 10 402 */ 403 AUDIOSTREAM_INTERRUPT_HINT_UNDUCK = 5 404 } OH_AudioInterrupt_Hint; 405 406 /** 407 * @brief Defines the audio source type. 408 * 409 * @since 10 410 */ 411 typedef enum { 412 /** 413 * Invalid type. 414 * 415 * @since 10 416 */ 417 AUDIOSTREAM_SOURCE_TYPE_INVALID = -1, 418 /** 419 * Mic source type. 420 * 421 * @since 10 422 */ 423 AUDIOSTREAM_SOURCE_TYPE_MIC = 0, 424 /** 425 * Voice recognition source type. 426 * 427 * @since 10 428 */ 429 AUDIOSTREAM_SOURCE_TYPE_VOICE_RECOGNITION = 1, 430 /** 431 * Playback capture source type. 432 * 433 * @deprecated since 12 434 * @useinstead OH_AVScreenCapture in native interface. 435 * @since 10 436 */ 437 AUDIOSTREAM_SOURCE_TYPE_PLAYBACK_CAPTURE = 2, 438 /** 439 * Voice communication source type. 440 * 441 * @since 10 442 */ 443 AUDIOSTREAM_SOURCE_TYPE_VOICE_COMMUNICATION = 7, 444 /** 445 * Voice message source type. 446 * 447 * @since 12 448 */ 449 AUDIOSTREAM_SOURCE_TYPE_VOICE_MESSAGE = 10, 450 /** 451 * Camcorder source type. 452 * 453 * @since 13 454 */ 455 AUDIOSTREAM_SOURCE_TYPE_CAMCORDER = 13, 456 /** 457 * Unprocessed source type. 458 * 459 * @since 14 460 */ 461 AUDIOSTREAM_SOURCE_TYPE_UNPROCESSED = 14 462 } OH_AudioStream_SourceType; 463 464 /** 465 * @brief Defines the audio interrupt mode. 466 * 467 * @since 12 468 */ 469 typedef enum { 470 /** 471 * Share mode 472 */ 473 AUDIOSTREAM_INTERRUPT_MODE_SHARE = 0, 474 /** 475 * Independent mode 476 */ 477 AUDIOSTREAM_INTERRUPT_MODE_INDEPENDENT = 1 478 } OH_AudioInterrupt_Mode; 479 480 /** 481 * @brief Defines the audio effect mode. 482 * 483 * @since 12 484 */ 485 typedef enum { 486 /** 487 * Audio Effect Mode effect none. 488 * 489 * @since 12 490 */ 491 EFFECT_NONE = 0, 492 /** 493 * Audio Effect Mode effect default. 494 * 495 * @since 12 496 */ 497 EFFECT_DEFAULT = 1, 498 } OH_AudioStream_AudioEffectMode; 499 500 /** 501 * @brief Declaring the audio stream builder. 502 * The instance of builder is used for creating audio stream. 503 * 504 * @since 10 505 */ 506 typedef struct OH_AudioStreamBuilderStruct OH_AudioStreamBuilder; 507 508 /** 509 * @brief Declaring the audio renderer stream. 510 * The instance of renderer stream is used for playing audio data. 511 * 512 * @since 10 513 */ 514 typedef struct OH_AudioRendererStruct OH_AudioRenderer; 515 516 /** 517 * @brief Declaring the audio capturer stream. 518 * The instance of renderer stream is used for capturing audio data. 519 * 520 * @since 10 521 */ 522 typedef struct OH_AudioCapturerStruct OH_AudioCapturer; 523 524 /** 525 * @brief Declaring the callback struct for renderer stream. 526 * 527 * @since 10 528 */ 529 typedef struct OH_AudioRenderer_Callbacks_Struct { 530 /** 531 * This function pointer will point to the callback function that 532 * is used to write audio data 533 * 534 * @since 10 535 */ 536 int32_t (*OH_AudioRenderer_OnWriteData)( 537 OH_AudioRenderer* renderer, 538 void* userData, 539 void* buffer, 540 int32_t length); 541 542 /** 543 * This function pointer will point to the callback function that 544 * is used to handle audio renderer stream events. 545 * 546 * @since 10 547 */ 548 int32_t (*OH_AudioRenderer_OnStreamEvent)( 549 OH_AudioRenderer* renderer, 550 void* userData, 551 OH_AudioStream_Event event); 552 553 /** 554 * This function pointer will point to the callback function that 555 * is used to handle audio interrupt events. 556 * 557 * @since 10 558 */ 559 int32_t (*OH_AudioRenderer_OnInterruptEvent)( 560 OH_AudioRenderer* renderer, 561 void* userData, 562 OH_AudioInterrupt_ForceType type, 563 OH_AudioInterrupt_Hint hint); 564 565 /** 566 * This function pointer will point to the callback function that 567 * is used to handle audio error result. 568 * 569 * @since 10 570 */ 571 int32_t (*OH_AudioRenderer_OnError)( 572 OH_AudioRenderer* renderer, 573 void* userData, 574 OH_AudioStream_Result error); 575 } OH_AudioRenderer_Callbacks; 576 577 /** 578 * @brief Declaring the callback struct for capturer stream. 579 * 580 * @since 10 581 */ 582 typedef struct OH_AudioCapturer_Callbacks_Struct { 583 /** 584 * This function pointer will point to the callback function that 585 * is used to read audio data. 586 * 587 * @since 10 588 */ 589 int32_t (*OH_AudioCapturer_OnReadData)( 590 OH_AudioCapturer* capturer, 591 void* userData, 592 void* buffer, 593 int32_t length); 594 595 /** 596 * This function pointer will point to the callback function that 597 * is used to handle audio capturer stream events. 598 * 599 * @since 10 600 */ 601 int32_t (*OH_AudioCapturer_OnStreamEvent)( 602 OH_AudioCapturer* capturer, 603 void* userData, 604 OH_AudioStream_Event event); 605 606 /** 607 * This function pointer will point to the callback function that 608 * is used to handle audio interrupt events. 609 * 610 * @since 10 611 */ 612 int32_t (*OH_AudioCapturer_OnInterruptEvent)( 613 OH_AudioCapturer* capturer, 614 void* userData, 615 OH_AudioInterrupt_ForceType type, 616 OH_AudioInterrupt_Hint hint); 617 618 /** 619 * This function pointer will point to the callback function that 620 * is used to handle audio error result. 621 * 622 * @since 10 623 */ 624 int32_t (*OH_AudioCapturer_OnError)( 625 OH_AudioCapturer* capturer, 626 void* userData, 627 OH_AudioStream_Result error); 628 } OH_AudioCapturer_Callbacks; 629 630 /** 631 * @brief Defines reason for device changes of one audio stream. 632 * 633 * @since 11 634 */ 635 typedef enum { 636 /* Unknown. */ 637 REASON_UNKNOWN = 0, 638 /* New Device available. */ 639 REASON_NEW_DEVICE_AVAILABLE = 1, 640 /* Old Device unavailable. Applications should consider to pause the audio playback when this reason is 641 reported. */ 642 REASON_OLD_DEVICE_UNAVAILABLE = 2, 643 /* Device is overrode by user or system. */ 644 REASON_OVERRODE = 3, 645 } OH_AudioStream_DeviceChangeReason; 646 647 /** 648 * @brief Callback when the output device of an audio renderer changed. 649 * 650 * @param renderer AudioRenderer where this event occurs. 651 * @param userData User data which is passed by user. 652 * @param reason Indicates that why does the output device changes. 653 * @since 11 654 */ 655 typedef void (*OH_AudioRenderer_OutputDeviceChangeCallback)(OH_AudioRenderer* renderer, void* userData, 656 OH_AudioStream_DeviceChangeReason reason); 657 658 /** 659 * @brief Callback when the mark position reached. 660 * 661 * @param renderer AudioRenderer where this event occurs. 662 * @param samplePos Mark position in samples. 663 * @param userData User data which is passed by user. 664 * @since 12 665 */ 666 typedef void (*OH_AudioRenderer_OnMarkReachedCallback)(OH_AudioRenderer* renderer, uint32_t samplePos, void* userData); 667 668 /** 669 * @brief This function pointer will point to the callback function that 670 * is used to write audio data with metadata 671 * 672 * @param renderer AudioRenderer where this event occurs. 673 * @param userData User data which is passed by user. 674 * @param audioData Audio data which is written by user. 675 * @param audioDataSize Audio data size which is the size of audio data written by user. 676 * @param metadata Metadata which is written by user. 677 * @param metadataSize Metadata size which is the size of metadata written by user. 678 * @return Error code of the callback function returned by user. 679 * @since 12 680 */ 681 typedef int32_t (*OH_AudioRenderer_WriteDataWithMetadataCallback)(OH_AudioRenderer* renderer, 682 void* userData, void* audioData, int32_t audioDataSize, void* metadata, int32_t metadataSize); 683 684 /** 685 * @brief Defines Enumeration of audio stream privacy type for playback capture. 686 * 687 * @since 12 688 */ 689 typedef enum { 690 /** Privacy type that stream can be captured by third party applications. 691 * @since 12 692 */ 693 AUDIO_STREAM_PRIVACY_TYPE_PUBLIC = 0, 694 /** Privacy type that stream can not be captured. 695 * @since 12 696 */ 697 AUDIO_STREAM_PRIVACY_TYPE_PRIVATE = 1, 698 } OH_AudioStream_PrivacyType; 699 700 /** 701 * @brief Defines enumeration of audio data callback result. 702 * 703 * @since 12 704 */ 705 typedef enum { 706 /** Result of audio data callabck is invalid. */ 707 AUDIO_DATA_CALLBACK_RESULT_INVALID = -1, 708 /** Result of audio data callabck is valid. */ 709 AUDIO_DATA_CALLBACK_RESULT_VALID = 0, 710 } OH_AudioData_Callback_Result; 711 712 /** 713 * @brief Callback function of write data. 714 * 715 * This function is similar with OH_AudioRenderer_Callbacks_Struct.OH_AudioRenderer_OnWriteData instead of the return 716 * value. The return result of this function indicates whether the data filled in the buffer is valid or invalid. If 717 * result is invalid, the data filled by user will not be played. 718 * 719 * @param renderer AudioRenderer where this callback occurs. 720 * @param userData User data which is passed by user. 721 * @param audioData Audio data pointer, where user should fill in audio data. 722 * @param audioDataSize Size of audio data that user should fill in. 723 * @return Audio Data callback result. 724 * @see OH_AudioRenderer_Callbacks_Struct.OH_AudioRenderer_OnWriteData 725 * @since 12 726 */ 727 typedef OH_AudioData_Callback_Result (*OH_AudioRenderer_OnWriteDataCallback)(OH_AudioRenderer* renderer, void* userData, 728 void* audioData, int32_t audioDataSize); 729 730 #ifdef __cplusplus 731 } 732 #endif 733 734 #endif // NATIVE_AUDIOSTREAM_BASE_H 735 /** @} */