1# Audio Management 2 3The **Audio** module provides basic audio management capabilities, including audio volume and audio device management, and audio data collection and rendering. 4 5This module provides the following common audio-related functions: 6 7- [AudioManager](#audiomanager): audio management. 8- [AudioRenderer](#audiorenderer8): audio rendering, used to play Pulse Code Modulation (PCM) audio data. 9- [AudioCapturer](#audiocapturer8): audio capture, used to record PCM audio data. 10 11> **NOTE** 12> 13> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. 14> 15> API version 9 is a canary release for trial use. The APIs of this version may be unstable. 16 17## Modules to Import 18 19``` 20import audio from '@ohos.multimedia.audio'; 21``` 22 23 24## audio.getAudioManager 25 26getAudioManager(): AudioManager 27 28Obtains an **AudioManager** instance. 29 30**System capability**: SystemCapability.Multimedia.Audio.Core 31 32**Return value** 33| Type | Description | 34| ----------------------------- | ------------ | 35| [AudioManager](#audiomanager) | **AudioManager** instance.| 36 37**Example** 38``` 39var audioManager = audio.getAudioManager(); 40``` 41 42## audio.createAudioRenderer<sup>8+</sup> 43 44createAudioRenderer(options: AudioRendererOptions, callback: AsyncCallback\<AudioRenderer>): void 45 46Obtains an **AudioRenderer** instance. This API uses an asynchronous callback to return the result. 47 48**System capability**: SystemCapability.Multimedia.Audio.Renderer 49 50**Parameters** 51 52| Name | Type | Mandatory| Description | 53| -------- | ----------------------------------------------- | ---- | ---------------- | 54| options | [AudioRendererOptions](#audiorendereroptions8) | Yes | Renderer configurations. | 55| callback | AsyncCallback<[AudioRenderer](#audiorenderer8)> | Yes | Callback used to return the **AudioRenderer** instance.| 56 57**Example** 58 59``` 60import audio from '@ohos.multimedia.audio'; 61var audioStreamInfo = { 62 samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_44100, 63 channels: audio.AudioChannel.CHANNEL_1, 64 sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, 65 encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW 66} 67 68var audioRendererInfo = { 69 content: audio.ContentType.CONTENT_TYPE_SPEECH, 70 usage: audio.StreamUsage.STREAM_USAGE_VOICE_COMMUNICATION, 71 rendererFlags: 1 72} 73 74var audioRendererOptions = { 75 streamInfo: audioStreamInfo, 76 rendererInfo: audioRendererInfo 77} 78 79audio.createAudioRenderer(audioRendererOptions,(err, data) => { 80 if (err) { 81 console.error(`AudioRenderer Created : Error: ${err.message}`); 82 } 83 else { 84 console.info('AudioRenderer Created : Success : SUCCESS'); 85 let audioRenderer = data; 86 } 87}); 88``` 89 90## audio.createAudioRenderer<sup>8+</sup> 91 92createAudioRenderer(options: AudioRendererOptions): Promise<AudioRenderer\> 93 94Obtains an **AudioRenderer** instance. This API uses a promise to return the result. 95 96**System capability**: SystemCapability.Multimedia.Audio.Renderer 97 98**Parameters** 99 100| Name | Type | Mandatory| Description | 101| :------ | :--------------------------------------------- | :--- | :----------- | 102| options | [AudioRendererOptions](#audiorendereroptions8) | Yes | Renderer configurations.| 103 104**Return value** 105 106| Type | Description | 107| ----------------------------------------- | ---------------- | 108| Promise<[AudioRenderer](#audiorenderer8)> | Promise used to return the **AudioRenderer** instance.| 109 110**Example** 111 112``` 113import audio from '@ohos.multimedia.audio'; 114 115var audioStreamInfo = { 116 samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_44100, 117 channels: audio.AudioChannel.CHANNEL_1, 118 sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, 119 encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW 120} 121 122var audioRendererInfo = { 123 content: audio.ContentType.CONTENT_TYPE_SPEECH, 124 usage: audio.StreamUsage.STREAM_USAGE_VOICE_COMMUNICATION, 125 rendererFlags: 1 126} 127 128var audioRendererOptions = { 129 streamInfo: audioStreamInfo, 130 rendererInfo: audioRendererInfo 131} 132 133var audioRenderer; 134audio.createAudioRenderer(audioRendererOptions).then((data) => { 135 audioRenderer = data; 136 console.info('AudioFrameworkRenderLog: AudioRenderer Created : Success : Stream Type: SUCCESS'); 137}).catch((err) => { 138 console.info('AudioFrameworkRenderLog: AudioRenderer Created : ERROR : '+err.message); 139}); 140``` 141 142## audio.createAudioCapturer<sup>8+</sup> 143 144createAudioCapturer(options: AudioCapturerOptions, callback: AsyncCallback<AudioCapturer\>): void 145 146Obtains an **AudioCapturer** instance. This API uses an asynchronous callback to return the result. 147 148**System capability**: SystemCapability.Multimedia.Audio.Capturer 149 150**Parameters** 151 152| Name | Type | Mandatory| Description | 153| :------- | :---------------------------------------------- | :--- | :--------------- | 154| options | [AudioCapturerOptions](#audiocaptureroptions8) | Yes | Capturer configurations.| 155| callback | AsyncCallback<[AudioCapturer](#audiocapturer8)> | Yes | Callback used to return the **AudioCapturer** instance.| 156 157**Example** 158 159``` 160import audio from '@ohos.multimedia.audio'; 161var audioStreamInfo = { 162 samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_44100, 163 channels: audio.AudioChannel.CHANNEL_2, 164 sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, 165 encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW 166} 167 168var audioCapturerInfo = { 169 source: audio.SourceType.SOURCE_TYPE_MIC, 170 capturerFlags: 1 171} 172 173var audioCapturerOptions = { 174 streamInfo: audioStreamInfo, 175 capturerInfo: audioCapturerInfo 176} 177 178audio.createAudioCapturer(audioCapturerOptions,(err, data) => { 179 if (err) { 180 console.error(`AudioCapturer Created : Error: ${err.message}`); 181 } 182 else { 183 console.info('AudioCapturer Created : Success : SUCCESS'); 184 let audioCapturer = data; 185 } 186}); 187``` 188 189## audio.createAudioCapturer<sup>8+</sup> 190 191createAudioCapturer(options: AudioCapturerOptions): Promise<AudioCapturer\> 192 193Obtains an **AudioCapturer** instance. This API uses a promise to return the result. 194 195**System capability**: SystemCapability.Multimedia.Audio.Capturer 196 197**Parameters** 198 199| Name | Type | Mandatory| Description | 200| :------ | :--------------------------------------------- | :--- | :--------------- | 201| options | [AudioCapturerOptions](#audiocaptureroptions8) | Yes | Capturer configurations.| 202 203**Return value** 204 205| Type | Description | 206| ----------------------------------------- | -------------- | 207| Promise<[AudioCapturer](#audiocapturer8)> | Promise used to return the **AudioCapturer** instance.| 208 209**Example** 210 211``` 212import audio from '@ohos.multimedia.audio'; 213 214var audioStreamInfo = { 215 samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_44100, 216 channels: audio.AudioChannel.CHANNEL_2, 217 sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, 218 encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW 219} 220 221var audioCapturerInfo = { 222 source: audio.SourceType.SOURCE_TYPE_MIC, 223 capturerFlags: 1 224} 225 226var audioCapturerOptions = { 227 streamInfo: audioStreamInfo, 228 capturerInfo: audioCapturerInfo 229} 230 231var audioCapturer; 232audio.createAudioCapturer(audioCapturerOptions).then((data) => { 233 audioCapturer = data; 234 console.info('AudioCapturer Created : Success : Stream Type: SUCCESS'); 235}).catch((err) => { 236 console.info('AudioCapturer Created : ERROR : '+err.message); 237}); 238``` 239 240## AudioVolumeType 241 242Enumerates the audio stream types. 243 244**System capability**: SystemCapability.Multimedia.Audio.Volume 245 246| Name | Default Value| Description | 247| ---------------------------- | ------ | ---------- | 248| VOICE_CALL<sup>8+</sup> | 0 | Audio stream for voice calls.| 249| RINGTONE | 2 | Audio stream for ringtones. | 250| MEDIA | 3 | Audio stream for media purpose. | 251| VOICE_ASSISTANT<sup>8+</sup> | 9 | Audio stream for voice assistant.| 252 253 254## DeviceFlag 255 256Enumerates the audio device flags. 257 258**System capability**: SystemCapability.Multimedia.Audio.Device 259 260| Name | Default Value| Description | 261| ------------------- | ------ | ---------- | 262| OUTPUT_DEVICES_FLAG | 1 | Output device.| 263| INPUT_DEVICES_FLAG | 2 | Input device.| 264| ALL_DEVICES_FLAG | 3 | All devices.| 265 266 267## DeviceRole 268 269Enumerates the audio device roles. 270 271**System capability**: SystemCapability.Multimedia.Audio.Device 272 273| Name | Default Value| Description | 274| ------------- | ------ | -------------- | 275| INPUT_DEVICE | 1 | Input role.| 276| OUTPUT_DEVICE | 2 | Output role.| 277 278 279## DeviceType 280 281Enumerates the audio device types. 282 283**System capability**: SystemCapability.Multimedia.Audio.Device 284 285| Name | Default Value| Description | 286| ---------------- | ------ | --------------------------------------------------------- | 287| INVALID | 0 | Invalid device. | 288| EARPIECE | 1 | Earpiece. | 289| SPEAKER | 2 | Speaker. | 290| WIRED_HEADSET | 3 | Wired headset with a microphone. | 291| WIRED_HEADPHONES | 4 | Wired headset without microphone. | 292| BLUETOOTH_SCO | 7 | Bluetooth device using Synchronous Connection Oriented (SCO) links. | 293| BLUETOOTH_A2DP | 8 | Bluetooth device using Advanced Audio Distribution Profile (A2DP) links.| 294| MIC | 15 | Microphone. | 295| USB_HEADSET | 22 | USB Type-C headset. | 296 297## ActiveDeviceType 298 299Enumerates the active device types. 300 301**System capability**: SystemCapability.Multimedia.Audio.Device 302 303| Name | Default Value| Description | 304| ------------- | ------ | ---------------------------------------------------- | 305| SPEAKER | 2 | Speaker. | 306| BLUETOOTH_SCO | 7 | Bluetooth device using the SCO links.| 307 308## AudioRingMode 309 310Enumerates the ringer modes. 311 312**System capability**: SystemCapability.Multimedia.Audio.Communication 313 314| Name | Default Value| Description | 315| ------------------- | ------ | ---------- | 316| RINGER_MODE_SILENT | 0 | Silent mode.| 317| RINGER_MODE_VIBRATE | 1 | Vibration mode.| 318| RINGER_MODE_NORMAL | 2 | Normal mode.| 319 320## AudioSampleFormat<sup>8+</sup> 321 322Enumerate the audio sample formats. 323 324**System capability**: SystemCapability.Multimedia.Audio.Core 325 326| Name | Default Value| Description | 327| --------------------- | ------ | -------------------------- | 328| SAMPLE_FORMAT_INVALID | -1 | Invalid format. | 329| SAMPLE_FORMAT_U8 | 0 | Unsigned 8-bit integer. | 330| SAMPLE_FORMAT_S16LE | 1 | Signed 16-bit integer, little endian.| 331| SAMPLE_FORMAT_S24LE | 2 | Signed 24-bit integer, little endian.| 332| SAMPLE_FORMAT_S32LE | 3 | Signed 32-bit integer, little endian.| 333 334## AudioChannel<sup>8+</sup> 335 336Enumerates the audio channels. 337 338**System capability**: SystemCapability.Multimedia.Audio.Core 339 340| Name | Default Value | Description | 341| --------- | -------- | -------- | 342| CHANNEL_1 | 0x1 << 0 | Mono.| 343| CHANNEL_2 | 0x1 << 1 | Dual-channel.| 344 345## AudioSamplingRate<sup>8+</sup> 346 347Enumerates the audio sampling rates. 348 349**System capability**: SystemCapability.Multimedia.Audio.Core 350 351| Name | Default Value| Description | 352| ----------------- | ------ | --------------- | 353| SAMPLE_RATE_8000 | 8000 | The sampling rate is 8000. | 354| SAMPLE_RATE_11025 | 11025 | The sampling rate is 11025.| 355| SAMPLE_RATE_12000 | 12000 | The sampling rate is 12000.| 356| SAMPLE_RATE_16000 | 16000 | The sampling rate is 16000.| 357| SAMPLE_RATE_22050 | 22050 | The sampling rate is 22050.| 358| SAMPLE_RATE_24000 | 24000 | The sampling rate is 24000.| 359| SAMPLE_RATE_32000 | 32000 | The sampling rate is 32000.| 360| SAMPLE_RATE_44100 | 44100 | The sampling rate is 44100.| 361| SAMPLE_RATE_48000 | 48000 | The sampling rate is 48000.| 362| SAMPLE_RATE_64000 | 64000 | The sampling rate is 64000.| 363| SAMPLE_RATE_96000 | 96000 | The sampling rate is 96000.| 364 365## AudioEncodingType<sup>8+</sup> 366 367Enumerates the audio encoding types. 368 369**System capability**: SystemCapability.Multimedia.Audio.Core 370 371| Name | Default Value| Description | 372| --------------------- | ------ | --------- | 373| ENCODING_TYPE_INVALID | -1 | Invalid. | 374| ENCODING_TYPE_RAW | 0 | PCM encoding.| 375 376## ContentType 377 378Enumerates the audio content types. 379 380**System capability**: SystemCapability.Multimedia.Audio.Core 381 382| Name | Default Value| Description | 383| ---------------------------------- | ------ | ---------- | 384| CONTENT_TYPE_UNKNOWN | 0 | Unknown content.| 385| CONTENT_TYPE_SPEECH | 1 | Speech. | 386| CONTENT_TYPE_MUSIC | 2 | Music. | 387| CONTENT_TYPE_MOVIE | 3 | Movie. | 388| CONTENT_TYPE_SONIFICATION | 4 | Sonification content.| 389| CONTENT_TYPE_RINGTONE<sup>8+</sup> | 5 | Ringtone. | 390 391## StreamUsage 392 393Enumerates the audio stream usage. 394 395**System capability**: SystemCapability.Multimedia.Audio.Core 396 397| Name | Default Value| Description | 398| ---------------------------------- | ------ | ---------- | 399| STREAM_USAGE_UNKNOWN | 0 | Unknown usage.| 400| STREAM_USAGE_MEDIA | 1 | Used for media. | 401| STREAM_USAGE_VOICE_COMMUNICATION | 2 | Used for voice communication.| 402| STREAM_USAGE_NOTIFICATION_RINGTONE | 6 | Used for notification.| 403 404## AudioState<sup>8+</sup> 405 406Enumerates the audio states. 407 408**System capability**: SystemCapability.Multimedia.Audio.Core 409 410| Name | Default Value| Description | 411| -------------- | ------ | ---------------- | 412| STATE_INVALID | -1 | Invalid state. | 413| STATE_NEW | 0 | Creating instance state.| 414| STATE_PREPARED | 1 | Prepared. | 415| STATE_RUNNING | 2 | Running. | 416| STATE_STOPPED | 3 | Stopped. | 417| STATE_RELEASED | 4 | Released. | 418| STATE_PAUSED | 5 | Paused. | 419 420## AudioRendererRate<sup>8+</sup> 421 422Enumerates the audio renderer rates. 423 424**System capability**: SystemCapability.Multimedia.Audio.Renderer 425 426| Name | Default Value| Description | 427| ------------------ | ------ | ---------- | 428| RENDER_RATE_NORMAL | 0 | Normal rate.| 429| RENDER_RATE_DOUBLE | 1 | Double rate. | 430| RENDER_RATE_HALF | 2 | Half rate. | 431 432## InterruptType 433 434Enumerates the audio interruption types. 435 436**System capability**: SystemCapability.Multimedia.Audio.Renderer 437 438| Name | Default Value| Description | 439| -------------------- | ------ | ---------------------- | 440| INTERRUPT_TYPE_BEGIN | 1 | Audio interruption started.| 441| INTERRUPT_TYPE_END | 2 | Audio interruption ended.| 442 443## InterruptForceType<sup>9+</sup> 444 445Enumerates the types of force that causes audio interruption. 446 447**System capability**: SystemCapability.Multimedia.Audio.Renderer 448 449| Name | Default Value| Description | 450| --------------- | ------ | ------------------------------------ | 451| INTERRUPT_FORCE | 0 | Forced action taken by the system. | 452| INTERRUPT_SHARE | 1 | The application can choose to take action or ignore.| 453 454## InterruptHint 455 456Enumerates the hints provided along with audio interruption. 457 458**System capability**: SystemCapability.Multimedia.Audio.Renderer 459 460| Name | Default Value| Description | 461| ---------------------------------- | ------ | -------------------------------------------- | 462| INTERRUPT_HINT_NONE<sup>8+</sup> | 0 | None. | 463| INTERRUPT_HINT_RESUME | 1 | Resume the playback. | 464| INTERRUPT_HINT_PAUSE | 2 | Paused/Pause the playback. | 465| INTERRUPT_HINT_STOP | 3 | Stopped/Stop the playback. | 466| INTERRUPT_HINT_DUCK | 4 | Ducked the playback. (In ducking, the audio volume is reduced, but not silenced.)| 467| INTERRUPT_HINT_UNDUCK<sup>8+</sup> | 5 | Unducked the playback. | 468 469## InterruptActionType 470 471Enumerates the returned event types for audio interruption events. 472 473**System capability**: SystemCapability.Multimedia.Audio.Renderer 474 475| Name | Default Value| Description | 476| -------------- | ------ | ------------------ | 477| TYPE_ACTIVATED | 0 | Focus gain event.| 478| TYPE_INTERRUPT | 1 | Audio interruption event.| 479 480## AudioStreamInfo<sup>8+</sup> 481 482Describes audio stream information. 483 484**System capability**: SystemCapability.Multimedia.Audio.Core 485 486| Name | Type | Mandatory| Description | 487| ------------ | ---------------------------------------- | ---- | ------------------ | 488| samplingRate | [AudioSamplingRate](#audiosamplingrate8) | Yes | Audio sampling rate.| 489| channels | [AudioChannel](#audiochannel8) | Yes | Number of audio channels.| 490| sampleFormat | [AudioSampleFormat](#audiosampleformat8) | Yes | Audio sample format. | 491| encodingType | [AudioEncodingType](#audioencodingtype8) | Yes | Audio encoding type. | 492 493## AudioRendererInfo<sup>8+</sup> 494 495Describes audio renderer information. 496 497**System capability**: SystemCapability.Multimedia.Audio.Core 498 499| Name | Type | Mandatory| Description | 500| ------------- | --------------------------- | ---- | ---------------- | 501| content | [ContentType](#contenttype) | Yes | Audio content type. | 502| usage | [StreamUsage](#streamusage) | Yes | Audio stream usage.| 503| rendererFlags | number | Yes | Audio renderer flags.| 504 505## AudioRendererOptions<sup>8+</sup> 506 507Describes audio renderer configurations. 508 509**System capability**: SystemCapability.Multimedia.Audio.Renderer 510 511| Name | Type | Mandatory| Description | 512| ------------ | ---------------------------------------- | ---- | ---------------- | 513| streamInfo | [AudioStreamInfo](#audiostreaminfo8) | Yes | Audio stream information.| 514| rendererInfo | [AudioRendererInfo](#audiorendererinfo8) | Yes | Audio renderer information.| 515 516## InterruptEvent<sup>9+</sup> 517 518Describes the interruption event received by the application when playback is interrupted. 519 520**System capability**: SystemCapability.Multimedia.Audio.Renderer 521 522| Name | Type | Mandatory| Description | 523| --------- | ------------------------------------------ | ---- | ------------------------------------ | 524| eventType | [InterruptType](#interrupttype) | Yes | Whether the interruption has started or ended. | 525| forceType | [InterruptForceType](#interruptforcetype9) | Yes | Whether the interruption is taken by the system or to be taken by the application.| 526| hintType | [InterruptHint](#interrupthint) | Yes | Hint provided along the interruption. | 527 528## AudioInterrupt 529 530Describes input parameters of audio interruption events. 531 532**System capability**: SystemCapability.Multimedia.Audio.Renderer 533 534| Name | Type | Mandatory| Description | 535| --------------- | --------------------------- | ---- | ------------------------------------------------------------ | 536| streamUsage | [StreamUsage](#streamusage) | Yes | Audio stream usage. | 537| contentType | [ContentType](#contenttype) | Yes | Audio content type. | 538| pauseWhenDucked | boolean | Yes | Whether audio playback can be paused during audio interruption. The value **true** means that audio playback can be paused during audio interruption, and **false** means the opposite.| 539 540## InterruptAction 541 542Describes the callback invoked for audio interruption or focus gain events. 543 544**System capability**: SystemCapability.Multimedia.Audio.Renderer 545 546| Name | Type | Mandatory| Description | 547| ---------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | 548| actionType | [InterruptActionType](#interruptactiontype) | Yes | Returned event type. The value **TYPE_ACTIVATED** means the focus gain event, and **TYPE_INTERRUPT** means the audio interruption event.| 549| type | [InterruptType](#interrupttype) | No | Type of the audio interruption event. | 550| hint | [InterruptHint](#interrupthint) | No | Hint provided along with the audio interruption event. | 551| activated | boolean | No | Whether the focus is gained or released. The value **true** means that the focus is gained or released, and **false** means that the focus fails to be gained or released.| 552 553## VolumeEvent<sup>8+</sup> 554 555Describes the event received by the application when the volume is changed. 556 557This is a system API and cannot be called by third-party applications. 558 559**System capability**: SystemCapability.Multimedia.Audio.Volume 560 561| Name | Type | Mandatory| Description | 562| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 563| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 564| volume | number | Yes | Volume level. The value range can be obtained by calling **getMinVolume** and **getMaxVolume**.| 565| updateUi | boolean | Yes | Whether to show the volume change in UI. | 566 567## DeviceChangeAction 568 569Describes the device connection status and device information. 570 571**System capability**: SystemCapability.Multimedia.Audio.Device 572 573| Name | Type | Mandatory| Description | 574| :---------------- | :------------------------------------------------ | :--- | :----------------- | 575| type | [DeviceChangeType](#devicechangetype) | Yes | Device connection status.| 576| deviceDescriptors | [AudioDeviceDescriptors](#audiodevicedescriptors) | Yes | Device information. | 577 578## DeviceChangeType 579 580Enumerates the device connection statuses. 581 582**System capability**: SystemCapability.Multimedia.Audio.Device 583 584| Name | Default Value| Description | 585| :--------- | :----- | :------------- | 586| CONNECT | 0 | Connected. | 587| DISCONNECT | 1 | Disconnected.| 588 589## AudioCapturerOptions<sup>8+</sup> 590 591Describes audio capturer configurations. 592 593**System capability**: SystemCapability.Multimedia.Audio.Capturer 594 595| Name | Type | Mandatory| Description | 596| ------------ | --------------------------------------- | ---- | ---------------- | 597| streamInfo | [AudioStreamInfo](#audiostreaminfo8) | Yes | Audio stream information.| 598| capturerInfo | [AudioCapturerInfo](#audiocapturerinfo) | Yes | Audio capturer information.| 599 600## AudioCapturerInfo<sup>8+</sup><a name="audiocapturerinfo"></a> 601 602Describes audio capturer information. 603 604**System capability**: SystemCapability.Multimedia.Audio.Core 605 606| Name | Type | Mandatory| Description | 607| :------------ | :------------------------ | :--- | :--------------- | 608| source | [SourceType](#sourcetype) | Yes | Audio source type. | 609| capturerFlags | number | Yes | Audio capturer flags.| 610 611## SourceType<sup>8+</sup><a name="sourcetype"></a> 612 613Enumerates the audio source types. 614 615**System capability**: SystemCapability.Multimedia.Audio.Core 616 617| Name | Default Value| Description | 618| :------------------------------ | :----- | :--------------------- | 619| SOURCE_TYPE_INVALID | -1 | Invalid audio source. | 620| SOURCE_TYPE_MIC | 0 | Mic source. | 621| SOURCE_TYPE_VOICE_COMMUNICATION | 7 | Voice communication source.| 622 623## AudioScene<sup>8+</sup><a name="audioscene"></a> 624 625Enumerates the audio scenes. 626 627**System capability**: SystemCapability.Multimedia.Audio.Communication 628 629| Name | Default Value| Description | 630| :--------------------- | :----- | :-------------------------------------------- | 631| AUDIO_SCENE_DEFAULT | 0 | Default audio scene. | 632| AUDIO_SCENE_RINGING | 1 | Ringing audio scene.<br>This is a system API and cannot be called by third-party applications.| 633| AUDIO_SCENE_PHONE_CALL | 2 | Phone call audio scene.<br>This is a system API and cannot be called by third-party applications.| 634| AUDIO_SCENE_VOICE_CHAT | 3 | Voice chat audio scene. | 635 636## AudioManager 637 638Implements audio volume and audio device management. Before calling any API in **AudioManager**, you must use [getAudioManager](#audiogetaudiomanager) to create an **AudioManager** instance. 639 640### setVolume 641 642setVolume(volumeType: AudioVolumeType, volume: number, callback: AsyncCallback<void>): void 643 644Sets the volume for a stream. This API uses an asynchronous callback to return the result. 645 646**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY (This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**.) 647 648**System capability**: SystemCapability.Multimedia.Audio.Volume 649 650**Parameters** 651 652| Name | Type | Mandatory| Description | 653| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 654| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 655| volume | number | Yes | Volume to set. The value range can be obtained by calling **getMinVolume** and **getMaxVolume**.| 656| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 657 658**Example** 659 660``` 661audioManager.setVolume(audio.AudioVolumeType.MEDIA, 10, (err) => { 662 if (err) { 663 console.error('Failed to set the volume. ${err.message}'); 664 return; 665 } 666 console.log('Callback invoked to indicate a successful volume setting.'); 667}); 668``` 669 670### setVolume 671 672setVolume(volumeType: AudioVolumeType, volume: number): Promise<void> 673 674Sets the volume for a stream. This API uses a promise to return the result. 675 676**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY (This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**.) 677 678**System capability**: SystemCapability.Multimedia.Audio.Volume 679 680**Parameters** 681 682| Name | Type | Mandatory| Description | 683| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 684| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 685| volume | number | Yes | Volume to set. The value range can be obtained by calling **getMinVolume** and **getMaxVolume**.| 686 687**Return value** 688 689| Type | Description | 690| ------------------- | ----------------------------- | 691| Promise<void> | Promise used to return the result.| 692 693**Example** 694 695``` 696audioManager.setVolume(audio.AudioVolumeType.MEDIA, 10).then(() => { 697 console.log('Promise returned to indicate a successful volume setting.'); 698}); 699``` 700 701### getVolume 702 703getVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 704 705Obtains the volume of a stream. This API uses an asynchronous callback to return the result. 706 707**System capability**: SystemCapability.Multimedia.Audio.Volume 708 709**Parameters** 710 711| Name | Type | Mandatory| Description | 712| ---------- | ----------------------------------- | ---- | ------------------ | 713| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 714| callback | AsyncCallback<number> | Yes | Callback used to return the volume.| 715 716**Example** 717 718``` 719audioManager.getVolume(audio.AudioVolumeType.MEDIA, (err, value) => { 720 if (err) { 721 console.error('Failed to obtain the volume. ${err.message}'); 722 return; 723 } 724 console.log('Callback invoked to indicate that the volume is obtained.'); 725}); 726``` 727 728### getVolume 729 730getVolume(volumeType: AudioVolumeType): Promise<number> 731 732Obtains the volume of a stream. This API uses a promise to return the result. 733 734**System capability**: SystemCapability.Multimedia.Audio.Volume 735 736**Parameters** 737 738| Name | Type | Mandatory| Description | 739| ---------- | ----------------------------------- | ---- | ------------ | 740| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 741 742**Return value** 743 744| Type | Description | 745| --------------------- | ------------------------- | 746| Promise<number> | Promise used to return the volume.| 747 748**Example** 749 750``` 751audioManager.getVolume(audio.AudioVolumeType.MEDIA).then((value) => { 752 console.log('Promise returned to indicate that the volume is obtained.' + value); 753}); 754``` 755 756### getMinVolume 757 758getMinVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 759 760Obtains the minimum volume allowed for a stream. This API uses an asynchronous callback to return the result. 761 762**System capability**: SystemCapability.Multimedia.Audio.Volume 763 764**Parameters** 765 766| Name | Type | Mandatory| Description | 767| ---------- | ----------------------------------- | ---- | ------------------ | 768| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 769| callback | AsyncCallback<number> | Yes | Callback used to return the minimum volume.| 770 771**Example** 772 773``` 774audioManager.getMinVolume(audio.AudioVolumeType.MEDIA, (err, value) => { 775 if (err) { 776 console.error('Failed to obtain the minimum volume. ${err.message}'); 777 return; 778 } 779 console.log('Callback invoked to indicate that the minimum volume is obtained.' + value); 780}); 781``` 782 783### getMinVolume 784 785getMinVolume(volumeType: AudioVolumeType): Promise<number> 786 787Obtains the minimum volume allowed for a stream. This API uses a promise to return the result. 788 789**System capability**: SystemCapability.Multimedia.Audio.Volume 790 791**Parameters** 792 793| Name | Type | Mandatory| Description | 794| ---------- | ----------------------------------- | ---- | ------------ | 795| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 796 797**Return value** 798 799| Type | Description | 800| --------------------- | ------------------------- | 801| Promise<number> | Promise used to return the minimum volume.| 802 803**Example** 804 805``` 806audioManager.getMinVolume(audio.AudioVolumeType.MEDIA).then((value) => { 807 console.log('Promised returned to indicate that the minimum volume is obtained.' + value); 808}); 809``` 810 811### getMaxVolume 812 813getMaxVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 814 815Obtains the maximum volume allowed for a stream. This API uses an asynchronous callback to return the result. 816 817**System capability**: SystemCapability.Multimedia.Audio.Volume 818 819**Parameters** 820 821| Name | Type | Mandatory| Description | 822| ---------- | ----------------------------------- | ---- | ---------------------- | 823| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 824| callback | AsyncCallback<number> | Yes | Callback used to return the maximum volume.| 825 826**Example** 827 828``` 829audioManager.getMaxVolume(audio.AudioVolumeType.MEDIA, (err, value) => { 830 if (err) { 831 console.error('Failed to obtain the maximum volume. ${err.message}'); 832 return; 833 } 834 console.log('Callback invoked to indicate that the maximum volume is obtained.' + value); 835}); 836``` 837 838### getMaxVolume 839 840getMaxVolume(volumeType: AudioVolumeType): Promise<number> 841 842Obtains the maximum volume allowed for a stream. This API uses a promise to return the result. 843 844**System capability**: SystemCapability.Multimedia.Audio.Volume 845 846**Parameters** 847 848| Name | Type | Mandatory| Description | 849| ---------- | ----------------------------------- | ---- | ------------ | 850| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 851 852**Return value** 853 854| Type | Description | 855| --------------------- | ----------------------------- | 856| Promise<number> | Promise used to return the maximum volume.| 857 858**Example** 859 860``` 861audioManager.getMaxVolume(audio.AudioVolumeType.MEDIA).then((data) => { 862 console.log('Promised returned to indicate that the maximum volume is obtained.'); 863}); 864``` 865 866### mute 867 868mute(volumeType: AudioVolumeType, mute: boolean, callback: AsyncCallback<void>): void 869 870Mutes or unmutes a stream. This API uses an asynchronous callback to return the result. 871 872**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY (This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**.) 873 874**System capability**: SystemCapability.Multimedia.Audio.Volume 875 876**Parameters** 877 878| Name | Type | Mandatory| Description | 879| ---------- | ----------------------------------- | ---- | ------------------------------------- | 880| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 881| mute | boolean | Yes | Mute status to set. The value **true** means to mute the stream, and **false** means the opposite.| 882| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 883 884**Example** 885 886``` 887audioManager.mute(audio.AudioVolumeType.MEDIA, true, (err) => { 888 if (err) { 889 console.error('Failed to mute the stream. ${err.message}'); 890 return; 891 } 892 console.log('Callback invoked to indicate that the stream is muted.'); 893}); 894``` 895 896### mute 897 898mute(volumeType: AudioVolumeType, mute: boolean): Promise<void> 899 900Mutes or unmutes a stream. This API uses a promise to return the result. 901 902**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY (This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**.) 903 904**System capability**: SystemCapability.Multimedia.Audio.Volume 905 906**Parameters** 907 908| Name | Type | Mandatory| Description | 909| ---------- | ----------------------------------- | ---- | ------------------------------------- | 910| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 911| mute | boolean | Yes | Mute status to set. The value **true** means to mute the stream, and **false** means the opposite.| 912 913**Return value** 914 915| Type | Description | 916| ------------------- | ----------------------------- | 917| Promise<void> | Promise used to return the result.| 918 919**Example** 920 921 922``` 923audioManager.mute(audio.AudioVolumeType.MEDIA, true).then(() => { 924 console.log('Promise returned to indicate that the stream is muted.'); 925}); 926``` 927 928 929### isMute 930 931isMute(volumeType: AudioVolumeType, callback: AsyncCallback<boolean>): void 932 933Checks whether a stream is muted. This API uses an asynchronous callback to return the result. 934 935**System capability**: SystemCapability.Multimedia.Audio.Volume 936 937**Parameters** 938 939| Name | Type | Mandatory| Description | 940| ---------- | ----------------------------------- | ---- | ----------------------------------------------- | 941| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 942| callback | AsyncCallback<boolean> | Yes | Callback used to return the mute status of the stream. The value **true** means that the stream is muted, and **false** means the opposite.| 943 944**Example** 945 946``` 947audioManager.isMute(audio.AudioVolumeType.MEDIA, (err, value) => { 948 if (err) { 949 console.error('Failed to obtain the mute status. ${err.message}'); 950 return; 951 } 952 console.log('Callback invoked to indicate that the mute status of the stream is obtained.' + value); 953}); 954``` 955 956 957### isMute 958 959isMute(volumeType: AudioVolumeType): Promise<boolean> 960 961Checks whether a stream is muted. This method uses a promise to return the result. 962 963**System capability**: SystemCapability.Multimedia.Audio.Volume 964 965**Parameters** 966 967| Name | Type | Mandatory| Description | 968| ---------- | ----------------------------------- | ---- | ------------ | 969| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 970 971**Return value** 972 973| Type | Description | 974| ---------------------- | ------------------------------------------------------ | 975| Promise<boolean> | Promise used to return the mute status of the stream. The value **true** means that the stream is muted, and **false** means the opposite.| 976 977**Example** 978 979``` 980audioManager.isMute(audio.AudioVolumeType.MEDIA).then((value) => { 981 console.log('Promise returned to indicate that the mute status of the stream is obtained.' + value); 982}); 983``` 984 985### isActive 986 987isActive(volumeType: AudioVolumeType, callback: AsyncCallback<boolean>): void 988 989Checks whether a stream is active. This API uses an asynchronous callback to return the result. 990 991**System capability**: SystemCapability.Multimedia.Audio.Volume 992 993**Parameters** 994 995| Name | Type | Mandatory| Description | 996| ---------- | ----------------------------------- | ---- | ------------------------------------------------- | 997| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 998| callback | AsyncCallback<boolean> | Yes | Callback used to return the active status of the stream. The value **true** means that the stream is active, and **false** means the opposite.| 999 1000**Example** 1001 1002``` 1003audioManager.isActive(audio.AudioVolumeType.MEDIA, (err, value) => { 1004 if (err) { 1005 console.error('Failed to obtain the active status of the stream. ${err.message}'); 1006 return; 1007 } 1008 console.log('Callback invoked to indicate that the active status of the stream is obtained.' + value); 1009}); 1010``` 1011 1012### isActive 1013 1014isActive(volumeType: AudioVolumeType): Promise<boolean> 1015 1016Checks whether a stream is active. This method uses a promise to return the result. 1017 1018**System capability**: SystemCapability.Multimedia.Audio.Volume 1019 1020**Parameters** 1021 1022| Name | Type | Mandatory| Description | 1023| ---------- | ----------------------------------- | ---- | ------------ | 1024| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 1025 1026**Return value** 1027 1028| Type | Description | 1029| ---------------------- | -------------------------------------------------------- | 1030| Promise<boolean> | Promise used to return the active status of the stream. The value **true** means that the stream is active, and **false** means the opposite.| 1031 1032**Example** 1033 1034``` 1035audioManager.isActive(audio.AudioVolumeType.MEDIA).then((value) => { 1036 console.log('Promise returned to indicate that the active status of the stream is obtained.' + value); 1037}); 1038``` 1039 1040### setRingerMode 1041 1042setRingerMode(mode: AudioRingMode, callback: AsyncCallback<void>): void 1043 1044Sets the ringer mode. This API uses an asynchronous callback to return the result. 1045 1046**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY (This permission is required only for muting or unmuting the ringer.) 1047 1048**System capability**: SystemCapability.Multimedia.Audio.Communication 1049 1050**Parameters** 1051 1052| Name | Type | Mandatory| Description | 1053| -------- | ------------------------------- | ---- | ------------------------ | 1054| mode | [AudioRingMode](#audioringmode) | Yes | Ringer mode. | 1055| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 1056 1057**Example** 1058 1059``` 1060audioManager.setRingerMode(audio.AudioRingMode.RINGER_MODE_NORMAL, (err) => { 1061 if (err) { 1062 console.error('Failed to set the ringer mode. ${err.message}'); 1063 return; 1064 } 1065 console.log('Callback invoked to indicate a successful setting of the ringer mode.'); 1066}); 1067``` 1068 1069### setRingerMode 1070 1071setRingerMode(mode: AudioRingMode): Promise<void> 1072 1073Sets the ringer mode. This API uses a promise to return the result. 1074 1075**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY (This permission is required only for muting or unmuting the ringer.) 1076 1077**System capability**: SystemCapability.Multimedia.Audio.Communication 1078 1079**Parameters** 1080 1081| Name| Type | Mandatory| Description | 1082| ------ | ------------------------------- | ---- | -------------- | 1083| mode | [AudioRingMode](#audioringmode) | Yes | Ringer mode.| 1084 1085**Return value** 1086 1087| Type | Description | 1088| ------------------- | ------------------------------- | 1089| Promise<void> | Promise used to return the result.| 1090 1091**Example** 1092 1093``` 1094audioManager.setRingerMode(audio.AudioRingMode.RINGER_MODE_NORMAL).then(() => { 1095 console.log('Promise returned to indicate a successful setting of the ringer mode.'); 1096}); 1097``` 1098 1099 1100### getRingerMode 1101 1102getRingerMode(callback: AsyncCallback<AudioRingMode>): void 1103 1104Obtains the ringer mode. This API uses an asynchronous callback to return the result. 1105 1106**System capability**: SystemCapability.Multimedia.Audio.Communication 1107 1108**Parameters** 1109 1110| Name | Type | Mandatory| Description | 1111| -------- | ---------------------------------------------------- | ---- | ------------------------ | 1112| callback | AsyncCallback<[AudioRingMode](#audioringmode)> | Yes | Callback used to return the ringer mode.| 1113 1114**Example** 1115 1116``` 1117audioManager.getRingerMode((err, value) => { 1118 if (err) { 1119 console.error('Failed to obtain the ringer mode. ${err.message}'); 1120 return; 1121 } 1122 console.log('Callback invoked to indicate that the ringer mode is obtained.' + value); 1123}); 1124``` 1125 1126 1127### getRingerMode 1128 1129getRingerMode(): Promise<AudioRingMode> 1130 1131Obtains the ringer mode. This API uses a promise to return the result. 1132 1133**System capability**: SystemCapability.Multimedia.Audio.Communication 1134 1135**Return value** 1136 1137| Type | Description | 1138| ---------------------------------------------- | ------------------------------- | 1139| Promise<[AudioRingMode](#audioringmode)> | Promise used to return the ringer mode.| 1140 1141**Example** 1142 1143``` 1144audioManager.getRingerMode().then((value) => { 1145 console.log('Promise returned to indicate that the ringer mode is obtained.' + value); 1146}); 1147``` 1148 1149### setAudioParameter 1150 1151setAudioParameter(key: string, value: string, callback: AsyncCallback<void>): void 1152 1153Sets an audio parameter. This API uses an asynchronous callback to return the result. 1154 1155This API is used to extend the audio configuration based on the hardware capability. The supported audio parameters vary according to the device and can be obtained from the device manual. The example below is for reference only. 1156 1157**Required permissions**: ohos.permission.MODIFY_AUDIO_SETTINGS 1158 1159**System capability**: SystemCapability.Multimedia.Audio.Core 1160 1161**Parameters** 1162 1163| Name | Type | Mandatory| Description | 1164| -------- | ------------------------- | ---- | ------------------------ | 1165| key | string | Yes | Key of the audio parameter to set. | 1166| value | string | Yes | Value of the audio parameter to set. | 1167| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 1168 1169**Example** 1170 1171``` 1172audioManager.setAudioParameter('key_example', 'value_example', (err) => { 1173 if (err) { 1174 console.error('Failed to set the audio parameter. ${err.message}'); 1175 return; 1176 } 1177 console.log('Callback invoked to indicate a successful setting of the audio parameter.'); 1178}); 1179``` 1180 1181### setAudioParameter 1182 1183setAudioParameter(key: string, value: string): Promise<void> 1184 1185Sets an audio parameter. This API uses a promise to return the result. 1186 1187This API is used to extend the audio configuration based on the hardware capability. The supported audio parameters vary according to the device and can be obtained from the device manual. The example below is for reference only. 1188 1189**Required permissions**: ohos.permission.MODIFY_AUDIO_SETTINGS 1190 1191**System capability**: SystemCapability.Multimedia.Audio.Core 1192 1193**Parameters** 1194 1195| Name| Type | Mandatory| Description | 1196| ------ | ------ | ---- | ---------------------- | 1197| key | string | Yes | Key of the audio parameter to set.| 1198| value | string | Yes | Value of the audio parameter to set.| 1199 1200**Return value** 1201 1202| Type | Description | 1203| ------------------- | ------------------------------- | 1204| Promise<void> | Promise used to return the result.| 1205 1206**Example** 1207 1208``` 1209audioManager.setAudioParameter('key_example', 'value_example').then(() => { 1210 console.log('Promise returned to indicate a successful setting of the audio parameter.'); 1211}); 1212``` 1213 1214### getAudioParameter 1215 1216getAudioParameter(key: string, callback: AsyncCallback<string>): void 1217 1218Obtains the value of an audio parameter. This API uses an asynchronous callback to return the result. 1219 1220This API is used to extend the audio configuration based on the hardware capability. The supported audio parameters vary according to the device and can be obtained from the device manual. The example below is for reference only. 1221 1222**System capability**: SystemCapability.Multimedia.Audio.Core 1223 1224**Parameters** 1225 1226| Name | Type | Mandatory| Description | 1227| -------- | --------------------------- | ---- | ---------------------------- | 1228| key | string | Yes | Key of the audio parameter whose value is to be obtained. | 1229| callback | AsyncCallback<string> | Yes | Callback used to return the value of the audio parameter.| 1230 1231**Example** 1232 1233``` 1234audioManager.getAudioParameter('key_example', (err, value) => { 1235 if (err) { 1236 console.error('Failed to obtain the value of the audio parameter. ${err.message}'); 1237 return; 1238 } 1239 console.log('Callback invoked to indicate that the value of the audio parameter is obtained.' + value); 1240}); 1241``` 1242 1243### getAudioParameter 1244 1245getAudioParameter(key: string): Promise<string> 1246 1247Obtains the value of an audio parameter. This API uses a promise to return the result. 1248 1249This API is used to extend the audio configuration based on the hardware capability. The supported audio parameters vary according to the device and can be obtained from the device manual. The example below is for reference only. 1250 1251**System capability**: SystemCapability.Multimedia.Audio.Core 1252 1253**Parameters** 1254 1255| Name| Type | Mandatory| Description | 1256| ------ | ------ | ---- | ---------------------- | 1257| key | string | Yes | Key of the audio parameter whose value is to be obtained.| 1258 1259**Return value** 1260 1261| Type | Description | 1262| --------------------- | ----------------------------------- | 1263| Promise<string> | Promise used to return the value of the audio parameter.| 1264 1265**Example** 1266 1267``` 1268audioManager.getAudioParameter('key_example').then((value) => { 1269 console.log('Promise returned to indicate that the value of the audio parameter is obtained.' + value); 1270}); 1271``` 1272 1273### getDevices 1274 1275getDevices(deviceFlag: DeviceFlag, callback: AsyncCallback<AudioDeviceDescriptors>): void 1276 1277Obtains the audio devices with a specific flag. This API uses an asynchronous callback to return the result. 1278 1279**System capability**: SystemCapability.Multimedia.Audio.Device 1280 1281**Parameters** 1282 1283| Name | Type | Mandatory| Description | 1284| ---------- | ------------------------------------------------------------ | ---- | -------------------- | 1285| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag. | 1286| callback | AsyncCallback<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Yes | Callback used to return the device list.| 1287 1288**Example** 1289``` 1290audioManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG, (err, value) => { 1291 if (err) { 1292 console.error('Failed to obtain the device list. ${err.message}'); 1293 return; 1294 } 1295 console.log('Callback invoked to indicate that the device list is obtained.'); 1296}); 1297``` 1298 1299### getDevices 1300 1301getDevices(deviceFlag: DeviceFlag): Promise<AudioDeviceDescriptors> 1302 1303Obtains the audio devices with a specific flag. This API uses a promise to return the result. 1304 1305**System capability**: SystemCapability.Multimedia.Audio.Device 1306 1307**Parameters** 1308 1309| Name | Type | Mandatory| Description | 1310| ---------- | ------------------------- | ---- | ---------------- | 1311| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag.| 1312 1313**Return value** 1314 1315| Type | Description | 1316| ------------------------------------------------------------ | ------------------------- | 1317| Promise<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Promise used to return the device list.| 1318 1319**Example** 1320 1321``` 1322audioManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG).then((data) => { 1323 console.log('Promise returned to indicate that the device list is obtained.'); 1324}); 1325``` 1326 1327### setDeviceActive 1328 1329setDeviceActive(deviceType: ActiveDeviceType, active: boolean, callback: AsyncCallback<void>): void 1330 1331Sets a device to the active state. This API uses an asynchronous callback to return the result. 1332 1333**System capability**: SystemCapability.Multimedia.Audio.Device 1334 1335**Parameters** 1336 1337| Name | Type | Mandatory| Description | 1338| ---------- | ------------------------------------- | ---- | ------------------------ | 1339| deviceType | [ActiveDeviceType](#activedevicetype) | Yes | Audio device type. | 1340| active | boolean | Yes | Active state to set. The value **true** means to set the device to the active state, and **false** means the opposite. | 1341| callback | AsyncCallback<void> | Yes | Callback used to return the result.| 1342 1343**Example** 1344 1345``` 1346audioManager.setDeviceActive(audio.ActiveDeviceType.SPEAKER, true, (err) => { 1347 if (err) { 1348 console.error('Failed to set the active status of the device. ${err.message}'); 1349 return; 1350 } 1351 console.log('Callback invoked to indicate that the device is set to the active status.'); 1352}); 1353``` 1354 1355### setDeviceActive 1356 1357setDeviceActive(deviceType: ActiveDeviceType, active: boolean): Promise<void> 1358 1359Sets a device to the active state. This API uses a promise to return the result. 1360 1361**System capability**: SystemCapability.Multimedia.Audio.Device 1362 1363**Parameters** 1364 1365| Name | Type | Mandatory| Description | 1366| ---------- | ------------------------------------- | ---- | ------------------ | 1367| deviceType | [ActiveDeviceType](#activedevicetype) | Yes | Audio device type.| 1368| active | boolean | Yes | Active state to set. The value **true** means to set the device to the active state, and **false** means the opposite. | 1369 1370**Return value** 1371 1372| Type | Description | 1373| ------------------- | ------------------------------- | 1374| Promise<void> | Promise used to return the result.| 1375 1376**Example** 1377 1378 1379``` 1380audioManager.setDeviceActive(audio.ActiveDeviceType.SPEAKER, true).then(() => { 1381 console.log('Promise returned to indicate that the device is set to the active status.'); 1382}); 1383``` 1384 1385### isDeviceActive 1386 1387isDeviceActive(deviceType: ActiveDeviceType, callback: AsyncCallback<boolean>): void 1388 1389Checks whether a device is active. This API uses an asynchronous callback to return the result. 1390 1391**System capability**: SystemCapability.Multimedia.Audio.Device 1392 1393**Parameters** 1394 1395| Name | Type | Mandatory| Description | 1396| ---------- | ------------------------------------- | ---- | ------------------------ | 1397| deviceType | [ActiveDeviceType](#activedevicetype) | Yes | Audio device type. | 1398| callback | AsyncCallback<boolean> | Yes | Callback used to return the active state of the device.| 1399 1400**Example** 1401 1402``` 1403audioManager.isDeviceActive(audio.ActiveDeviceType.SPEAKER, (err, value) => { 1404 if (err) { 1405 console.error('Failed to obtain the active status of the device. ${err.message}'); 1406 return; 1407 } 1408 console.log('Callback invoked to indicate that the active status of the device is obtained.'); 1409}); 1410``` 1411 1412 1413### isDeviceActive 1414 1415isDeviceActive(deviceType: ActiveDeviceType): Promise<boolean> 1416 1417Checks whether a device is active. This API uses a promise to return the result. 1418 1419**System capability**: SystemCapability.Multimedia.Audio.Device 1420 1421**Parameters** 1422 1423| Name | Type | Mandatory| Description | 1424| ---------- | ------------------------------------- | ---- | ------------------ | 1425| deviceType | [ActiveDeviceType](#activedevicetype) | Yes | Audio device type.| 1426 1427**Return value** 1428 1429| Type | Description | 1430| ---------------------- | ------------------------------- | 1431| Promise<boolean> | Promise used to return the active state of the device.| 1432 1433**Example** 1434 1435``` 1436audioManager.isDeviceActive(audio.ActiveDeviceType.SPEAKER).then((value) => { 1437 console.log('Promise returned to indicate that the active status of the device is obtained.' + value); 1438}); 1439``` 1440 1441### setMicrophoneMute 1442 1443setMicrophoneMute(mute: boolean, callback: AsyncCallback<void>): void 1444 1445Mutes or unmutes the microphone. This API uses an asynchronous callback to return the result. 1446 1447**Required permissions**: ohos.permission.MICROPHONE 1448 1449**System capability**: SystemCapability.Multimedia.Audio.Device 1450 1451**Parameters** 1452 1453| Name | Type | Mandatory| Description | 1454| -------- | ------------------------- | ---- | --------------------------------------------- | 1455| mute | boolean | Yes | Mute status to set. The value **true** means to mute the microphone, and **false** means the opposite.| 1456| callback | AsyncCallback<void> | Yes | Callback used to return the result. | 1457 1458**Example** 1459 1460``` 1461audioManager.setMicrophoneMute(true, (err) => { 1462 if (err) { 1463 console.error('Failed to mute the microphone. ${err.message}'); 1464 return; 1465 } 1466 console.log('Callback invoked to indicate that the microphone is muted.'); 1467}); 1468``` 1469 1470### setMicrophoneMute 1471 1472setMicrophoneMute(mute: boolean): Promise<void> 1473 1474Mutes or unmutes the microphone. This API uses a promise to return the result. 1475 1476**Required permissions**: ohos.permission.MICROPHONE 1477 1478**System capability**: SystemCapability.Multimedia.Audio.Device 1479 1480**Parameters** 1481 1482| Name| Type | Mandatory| Description | 1483| ------ | ------- | ---- | --------------------------------------------- | 1484| mute | boolean | Yes | Mute status to set. The value **true** means to mute the microphone, and **false** means the opposite.| 1485 1486**Return value** 1487 1488| Type | Description | 1489| ------------------- | ------------------------------- | 1490| Promise<void> | Promise used to return the result.| 1491 1492**Example** 1493 1494``` 1495audioManager.setMicrophoneMute(true).then(() => { 1496 console.log('Promise returned to indicate that the microphone is muted.'); 1497}); 1498``` 1499 1500### isMicrophoneMute 1501 1502isMicrophoneMute(callback: AsyncCallback<boolean>): void 1503 1504Checks whether the microphone is muted. This API uses an asynchronous callback to return the result. 1505 1506**Required permissions**: ohos.permission.MICROPHONE 1507 1508**System capability**: SystemCapability.Multimedia.Audio.Device 1509 1510**Parameters** 1511 1512| Name | Type | Mandatory| Description | 1513| -------- | ---------------------------- | ---- | ------------------------------------------------------- | 1514| callback | AsyncCallback<boolean> | Yes | Callback used to return the mute status of the microphone. The value **true** means that the microphone is muted, and **false** means the opposite.| 1515 1516**Example** 1517 1518``` 1519audioManager.isMicrophoneMute((err, value) => { 1520 if (err) { 1521 console.error('Failed to obtain the mute status of the microphone. ${err.message}'); 1522 return; 1523 } 1524 console.log('Callback invoked to indicate that the mute status of the microphone is obtained.' + value); 1525}); 1526``` 1527 1528### isMicrophoneMute 1529 1530isMicrophoneMute(): Promise<boolean> 1531 1532Checks whether the microphone is muted. This API uses a promise to return the result. 1533 1534**Required permissions**: ohos.permission.MICROPHONE 1535 1536**System capability**: SystemCapability.Multimedia.Audio.Device 1537 1538**Return value** 1539 1540| Type | Description | 1541| ---------------------- | ------------------------------------------------------------ | 1542| Promise<boolean> | Promise used to return the mute status of the microphone. The value **true** means that the microphone is muted, and **false** means the opposite.| 1543 1544**Example** 1545 1546 1547``` 1548audioManager.isMicrophoneMute().then((value) => { 1549 console.log('Promise returned to indicate that the mute status of the microphone is obtained.', + value); 1550}); 1551``` 1552 1553### on('volumeChange')<sup>8+</sup> 1554 1555on(type: 'volumeChange', callback: Callback\<VolumeEvent>): void 1556 1557Subscribes to system volume change events. 1558 1559This is a system API and cannot be called by third-party applications. 1560 1561**System capability**: SystemCapability.Multimedia.Audio.Volume 1562 1563**Parameters** 1564 1565| Name | Type | Mandatory| Description | 1566| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 1567| type | string | Yes | Event type. The value **'volumeChange'** means the system volume change event, which is triggered when a system volume change is detected.| 1568| callback | Callback<[VolumeEvent](#volumeevent8)> | Yes | Callback used to return the system volume change event. | 1569 1570**Example** 1571 1572``` 1573audioManager.on('volumeChange', (volumeEvent) => { 1574 console.log('VolumeType of stream: ' + volumeEvent.volumeType); 1575 console.log('Volume level: ' + volumeEvent.volume); 1576 console.log('Whether to updateUI: ' + volumeEvent.updateUi); 1577}); 1578``` 1579 1580### on('ringerModeChange')<sup>8+</sup> 1581 1582on(type: 'ringerModeChange', callback: Callback\<AudioRingMode>): void 1583 1584Subscribes to ringer mode change events. 1585 1586This is a system API and cannot be called by third-party applications. 1587 1588**System capability**: SystemCapability.Multimedia.Audio.Communication 1589 1590**Parameters** 1591 1592| Name | Type | Mandatory| Description | 1593| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 1594| type | string | Yes | Event type. The value **'ringerModeChange'** means the ringer mode change event, which is triggered when a ringer mode change is detected.| 1595| callback | Callback<[AudioRingMode](#audioringmode)> | Yes | Callback used to return the updated ringer mode. | 1596 1597**Example** 1598 1599``` 1600audioManager.on('ringerModeChange', (ringerMode) => { 1601 console.log('Updated ringermode: ' + ringerMode); 1602}); 1603``` 1604 1605### on('deviceChange') 1606 1607on(type: 'deviceChange', callback: Callback<DeviceChangeAction\>): void 1608 1609Subscribes to device change events. When a device is connected or disconnected, registered clients will receive the callback. 1610 1611**System capability**: SystemCapability.Multimedia.Audio.Device 1612 1613**Parameters** 1614 1615| Name | Type | Mandatory| Description | 1616| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- | 1617| type | string | Yes | Event type. The value **'deviceChange'** means the device change event, which is triggered when a device connection status change is detected.| 1618| callback | Callback<[DeviceChangeAction](#DeviceChangeAction)\> | Yes | Callback used to return the device update details. | 1619 1620**Example** 1621 1622``` 1623audioManager.on('deviceChange', (deviceChanged) => { 1624 console.info("device change type : " + deviceChanged.type); 1625 console.info("device descriptor size : " + deviceChanged.deviceDescriptors.length); 1626 console.info("device change descriptor : " + deviceChanged.deviceDescriptors[0].deviceRole); 1627 console.info("device change descriptor : " + deviceChanged.deviceDescriptors[0].deviceType); 1628}); 1629``` 1630 1631### off('deviceChange') 1632 1633off(type: 'deviceChange', callback?: Callback<DeviceChangeAction\>): void 1634 1635Unsubscribes from device change events. 1636 1637**System capability**: SystemCapability.Multimedia.Audio.Device 1638 1639**Parameters** 1640 1641| Name | Type | Mandatory| Description | 1642| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 1643| type | string | Yes | Event type. The value **'deviceChange'** means the device change event, which is triggered when a device connection status change is detected.| 1644| callback | Callback<[DeviceChangeAction](#DeviceChangeAction)> | No | Callback used to return the device update details. | 1645 1646**Example** 1647 1648``` 1649audioManager.off('deviceChange', (deviceChanged) => { 1650 console.log("Should be no callback."); 1651}); 1652``` 1653 1654### on('interrupt') 1655 1656on(type: 'interrupt', interrupt: AudioInterrupt, callback: Callback\<InterruptAction>): void 1657 1658Subscribes to audio interruption events. When the application's audio is interrupted by another playback event, the application will receive the callback. 1659 1660**System capability**: SystemCapability.Multimedia.Audio.Renderer 1661 1662**Parameters** 1663 1664| Name | Type | Mandatory| Description | 1665| --------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | 1666| type | string | Yes | Event type. The value **'interrupt'** means the audio interruption event, which is triggered when the audio playback of the current application is interrupted by another application.| 1667| interrupt | AudioInterrupt | Yes | Audio interruption event type. | 1668| callback | Callback<[InterruptAction](#interruptaction)> | Yes | Callback invoked for the audio interruption event. | 1669 1670**Example** 1671 1672``` 1673var interAudioInterrupt = { 1674 streamUsage:2, 1675 contentType:0, 1676 pauseWhenDucked:true 1677}; 1678audioManager.on('interrupt', interAudioInterrupt, (InterruptAction) => { 1679 if (InterruptAction.actionType === 0) { 1680 console.log("An event to gain the audio focus starts."); 1681 console.log("Focus gain event:" + JSON.stringify(InterruptAction)); 1682 } 1683 if (InterruptAction.actionType === 1) { 1684 console.log("An audio interruption event starts."); 1685 console.log("Audio interruption event:" + JSON.stringify(InterruptAction)); 1686 } 1687}); 1688``` 1689 1690### off('interrupt') 1691 1692off(type: 'interrupt', interrupt: AudioInterrupt, callback?: Callback\<InterruptAction>): void 1693 1694Unsubscribes from audio interruption events. 1695 1696**System capability**: SystemCapability.Multimedia.Audio.Renderer 1697 1698**Parameters** 1699 1700| Name | Type | Mandatory| Description | 1701| --------- | --------------------------------------------- | ---- | ------------------------------------------------------------ | 1702| type | string | Yes | Event type. The value **'interrupt'** means the audio interruption event, which is triggered when the audio playback of the current application is interrupted by another application.| 1703| interrupt | AudioInterrupt | Yes | Audio interruption event type. | 1704| callback | Callback<[InterruptAction](#interruptaction)> | No | Callback invoked for the audio interruption event. | 1705 1706**Example** 1707 1708``` 1709var interAudioInterrupt = { 1710 streamUsage:2, 1711 contentType:0, 1712 pauseWhenDucked:true 1713}; 1714audioManager.off('interrupt', interAudioInterrupt, (InterruptAction) => { 1715 if (InterruptAction.actionType === 0) { 1716 console.log("An event to release the audio focus starts."); 1717 console.log("Focus release event:" + JSON.stringify(InterruptAction)); 1718 } 1719}); 1720``` 1721 1722### setAudioScene<sup>8+</sup> 1723 1724setAudioScene\(scene: AudioScene, callback: AsyncCallback<void\>\): void 1725 1726Sets an audio scene. This API uses an asynchronous callback to return the result. 1727 1728This is a system API and cannot be called by third-party applications. 1729 1730**System capability**: SystemCapability.Multimedia.Audio.Communication 1731 1732**Parameters** 1733 1734| Name | Type | Mandatory| Description | 1735| :------- | :----------------------------------- | :--- | :------------------- | 1736| scene | <a href="#audioscene">AudioScene</a> | Yes | Audio scene to set. | 1737| callback | AsyncCallback<void\> | Yes | Callback used to return the result.| 1738 1739**Example** 1740 1741``` 1742audioManager.setAudioScene(audio.AudioScene.AUDIO_SCENE_PHONE_CALL, (err) => { 1743 if (err) { 1744 console.error('Failed to set the audio scene mode. ${err.message}'); 1745 return; 1746 } 1747 console.log('Callback invoked to indicate a successful setting of the audio scene mode.'); 1748}); 1749``` 1750 1751### setAudioScene<sup>8+</sup> 1752 1753setAudioScene\(scene: AudioScene\): Promise<void\> 1754 1755Sets an audio scene. This API uses a promise to return the result. 1756 1757This is a system API and cannot be called by third-party applications. 1758 1759**System capability**: SystemCapability.Multimedia.Audio.Communication 1760 1761**Parameters** 1762 1763| Name| Type | Mandatory| Description | 1764| :----- | :----------------------------------- | :--- | :------------- | 1765| scene | <a href="#audioscene">AudioScene</a> | Yes | Audio scene to set.| 1766 1767**Return value** 1768 1769| Type | Description | 1770| :------------- | :------------------- | 1771| Promise<void\> | Promise used to return the result.| 1772 1773**Example** 1774 1775``` 1776audioManager.setAudioScene(audio.AudioScene.AUDIO_SCENE_PHONE_CALL).then(() => { 1777 console.log('Promise returned to indicate a successful setting of the audio scene mode.'); 1778}).catch ((err) => { 1779 console.log('Failed to set the audio scene mode'); 1780}); 1781``` 1782 1783### getAudioScene<sup>8+</sup> 1784 1785getAudioScene\(callback: AsyncCallback<AudioScene\>\): void 1786 1787Obtains the audio scene. This API uses an asynchronous callback to return the result. 1788 1789**System capability**: SystemCapability.Multimedia.Audio.Communication 1790 1791**Parameters** 1792 1793| Name | Type | Mandatory| Description | 1794| :------- | :-------------------------------------------------- | :--- | :--------------------------- | 1795| callback | AsyncCallback<<a href="#audioscene">AudioScene</a>> | Yes | Callback used to return the audio scene.| 1796 1797**Example** 1798 1799``` 1800audioManager.getAudioScene((err, value) => { 1801 if (err) { 1802 console.error('Failed to obtain the audio scene mode. ${err.message}'); 1803 return; 1804 } 1805 console.log('Callback invoked to indicate that the audio scene mode is obtained.' + value); 1806}); 1807``` 1808 1809 1810### getAudioScene<sup>8+</sup> 1811 1812getAudioScene\(\): Promise<AudioScene\> 1813 1814Obtains the audio scene. This API uses a promise to return the result. 1815 1816**System capability**: SystemCapability.Multimedia.Audio.Communication 1817 1818**Return value** 1819 1820| Type | Description | 1821| :-------------------------------------------- | :--------------------------- | 1822| Promise<<a href="#audioscene">AudioScene</a>> | Promise used to return the audio scene.| 1823 1824**Example** 1825 1826``` 1827audioManager.getAudioScene().then((value) => { 1828 console.log('Promise returned to indicate that the audio scene mode is obtained.' + value); 1829}).catch ((err) => { 1830 console.log('Failed to obtain the audio scene mode'); 1831}); 1832``` 1833 1834## AudioDeviceDescriptor 1835 1836Describes an audio device. 1837 1838**System capability**: SystemCapability.Multimedia.Audio.Device 1839 1840| Name | Type | Readable| Writable| Description | 1841| ---------- | ------------------------- | ---- | ---- | ---------- | 1842| deviceRole | [DeviceRole](#devicerole) | Yes | No | Device role.| 1843| deviceType | [DeviceType](#devicetype) | Yes | No | Device type.| 1844 1845## AudioDeviceDescriptors 1846 1847Array of [AudioDeviceDescriptor](#audiodevicedescriptor), which is read-only. 1848 1849**Example** 1850 1851``` 1852import audio from '@ohos.multimedia.audio'; 1853 1854function displayDeviceProp(value) { 1855 deviceRoleValue = value.deviceRole; 1856 deviceTypeValue = value.deviceType; 1857 1858} 1859 1860var deviceRoleValue = null; 1861var deviceTypeValue = null; 1862const promise = audio.getAudioManager().getDevices(1); 1863promise.then(function (value) { 1864 console.info('AudioFrameworkTest: Promise: getDevices OUTPUT_DEVICES_FLAG'); 1865 value.forEach(displayDeviceProp); 1866 if (deviceTypeValue != null && deviceRoleValue != null){ 1867 console.info('AudioFrameworkTest: Promise: getDevices : OUTPUT_DEVICES_FLAG : PASS'); 1868 } 1869 else{ 1870 console.info('AudioFrameworkTest: Promise: getDevices : OUTPUT_DEVICES_FLAG : FAIL'); 1871 } 1872}); 1873``` 1874 1875## AudioRenderer<sup>8+</sup> 1876 1877Provides APIs for audio rendering. Before calling any API in **AudioRenderer**, you must use [createAudioRenderer](#audiocreateaudiorenderer8) to create an **AudioRenderer** instance. 1878 1879### Attributes 1880 1881**System capability**: SystemCapability.Multimedia.Audio.Renderer 1882 1883| Name | Type | Readable| Writable| Description | 1884| ----- | -------------------------- | ---- | ---- | ------------------ | 1885| state<sup>8+</sup> | [AudioState](#audiostate8) | Yes | No | Audio renderer state.| 1886 1887**Example** 1888 1889``` 1890var state = audioRenderer.state; 1891``` 1892 1893### getRendererInfo<sup>8+</sup> 1894 1895getRendererInfo(callback: AsyncCallback<AudioRendererInfo\>): void 1896 1897Obtains the renderer information of this **AudioRenderer** instance. This API uses an asynchronous callback to return the result. 1898 1899**System capability**: SystemCapability.Multimedia.Audio.Renderer 1900 1901**Parameters** 1902 1903| Name | Type | Mandatory| Description | 1904| :------- | :------------------------------------------------------- | :--- | :--------------------- | 1905| callback | AsyncCallback<[AudioRendererInfo](#audiorendererinfo8)\> | Yes | Callback used to return the renderer information.| 1906 1907**Example** 1908 1909``` 1910audioRenderer.getRendererInfo((err, rendererInfo) => { 1911 console.log('Renderer GetRendererInfo:'); 1912 console.log('Renderer content:' + rendererInfo.content); 1913 console.log('Renderer usage:' + rendererInfo.usage); 1914 console.log('Renderer flags:' + rendererInfo.rendererFlags); 1915}); 1916``` 1917 1918### getRendererInfo<sup>8+</sup> 1919 1920getRendererInfo(): Promise<AudioRendererInfo\> 1921 1922Obtains the renderer information of this **AudioRenderer** instance. This API uses a promise to return the result. 1923 1924**System capability**: SystemCapability.Multimedia.Audio.Renderer 1925 1926**Return value** 1927 1928| Type | Description | 1929| -------------------------------------------------- | ------------------------------- | 1930| Promise<[AudioRendererInfo](#audiorendererinfo8)\> | Promise used to return the renderer information.| 1931 1932**Example** 1933 1934``` 1935var resultFlag = true; 1936audioRenderer.getRendererInfo().then((rendererInfo) => { 1937 console.log('Renderer GetRendererInfo:'); 1938 console.log('Renderer content:' + rendererInfo.content); 1939 console.log('Renderer usage:' + rendererInfo.usage); 1940 console.log('Renderer flags:' + rendererInfo.rendererFlags); 1941}).catch((err) => { 1942 console.log('AudioFrameworkRenderLog: RendererInfo :ERROR: '+err.message); 1943 resultFlag = false; 1944}); 1945``` 1946 1947### getStreamInfo<sup>8+</sup> 1948 1949getStreamInfo(callback: AsyncCallback<AudioStreamInfo\>): void 1950 1951Obtains the stream information of this **AudioRenderer** instance. This API uses an asynchronous callback to return the result. 1952 1953**System capability**: SystemCapability.Multimedia.Audio.Renderer 1954 1955**Parameters** 1956 1957| Name | Type | Mandatory| Description | 1958| :------- | :--------------------------------------------------- | :--- | :------------------- | 1959| callback | AsyncCallback<[AudioStreamInfo](#audiostreaminfo8)\> | Yes | Callback used to return the stream information.| 1960 1961**Example** 1962 1963``` 1964audioRenderer.getStreamInfo((err, streamInfo) => { 1965 console.log('Renderer GetStreamInfo:'); 1966 console.log('Renderer sampling rate:' + streamInfo.samplingRate); 1967 console.log('Renderer channel:' + streamInfo.channels); 1968 console.log('Renderer format:' + streamInfo.sampleFormat); 1969 console.log('Renderer encoding type:' + streamInfo.encodingType); 1970}); 1971``` 1972 1973### getStreamInfo<sup>8+</sup> 1974 1975getStreamInfo(): Promise<AudioStreamInfo\> 1976 1977Obtains the stream information of this **AudioRenderer** instance. This API uses a promise to return the result. 1978 1979**System capability**: SystemCapability.Multimedia.Audio.Renderer 1980 1981**Return value** 1982 1983| Type | Description | 1984| :--------------------------------------------- | :--------------------- | 1985| Promise<[AudioStreamInfo](#audiostreaminfo8)\> | Promise used to return the stream information.| 1986 1987**Example** 1988 1989``` 1990audioRenderer.getStreamInfo().then((streamInfo) => { 1991 console.log('Renderer GetStreamInfo:'); 1992 console.log('Renderer sampling rate:' + streamInfo.samplingRate); 1993 console.log('Renderer channel:' + streamInfo.channels); 1994 console.log('Renderer format:' + streamInfo.sampleFormat); 1995 console.log('Renderer encoding type:' + streamInfo.encodingType); 1996}).catch((err) => { 1997 console.log('ERROR: '+err.message); 1998}); 1999``` 2000 2001### start<sup>8+</sup> 2002 2003start(callback: AsyncCallback<void\>): void 2004 2005Starts the renderer. This API uses an asynchronous callback to return the result. 2006 2007**System capability**: SystemCapability.Multimedia.Audio.Renderer 2008 2009**Parameters** 2010 2011| Name | Type | Mandatory| Description | 2012| -------- | -------------------- | ---- | ---------- | 2013| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 2014 2015**Example** 2016 2017``` 2018audioRenderer.start((err) => { 2019 if (err) { 2020 console.error('Renderer start failed.'); 2021 } else { 2022 console.info('Renderer start success.'); 2023 } 2024}); 2025``` 2026 2027### start<sup>8+</sup> 2028 2029start(): Promise<void\> 2030 2031Starts the renderer. This API uses a promise to return the result. 2032 2033**System capability**: SystemCapability.Multimedia.Audio.Renderer 2034 2035**Return value** 2036 2037| Type | Description | 2038| -------------- | ------------------------- | 2039| Promise\<void> | Promise used to return the result.| 2040 2041**Example** 2042 2043``` 2044audioRenderer.start().then(() => { 2045 console.log('Renderer started'); 2046}).catch((err) => { 2047 console.log('ERROR: '+err.message); 2048}); 2049``` 2050 2051### pause<sup>8+</sup> 2052 2053pause(callback: AsyncCallback\<void>): void 2054 2055Pauses rendering. This API uses an asynchronous callback to return the result. 2056 2057**System capability**: SystemCapability.Multimedia.Audio.Renderer 2058 2059**Parameters** 2060 2061| Name | Type | Mandatory| Description | 2062| -------- | -------------------- | ---- | ---------------- | 2063| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 2064 2065**Example** 2066 2067``` 2068audioRenderer.pause((err) => { 2069 if (err) { 2070 console.error('Renderer pause failed'); 2071 } else { 2072 console.log('Renderer paused.'); 2073 } 2074}); 2075``` 2076 2077### pause<sup>8+</sup> 2078 2079pause(): Promise\<void> 2080 2081Pauses rendering. This API uses a promise to return the result. 2082 2083**System capability**: SystemCapability.Multimedia.Audio.Renderer 2084 2085**Return value** 2086 2087| Type | Description | 2088| -------------- | ------------------------- | 2089| Promise\<void> | Promise used to return the result.| 2090 2091**Example** 2092 2093``` 2094audioRenderer.pause().then(() => { 2095 console.log('Renderer paused'); 2096}).catch((err) => { 2097 console.log('ERROR: '+err.message); 2098}); 2099``` 2100 2101### drain<sup>8+</sup> 2102 2103drain(callback: AsyncCallback\<void>): void 2104 2105Drains the playback buffer. This API uses an asynchronous callback to return the result. 2106 2107**System capability**: SystemCapability.Multimedia.Audio.Renderer 2108 2109**Parameters** 2110 2111| Name | Type | Mandatory| Description | 2112| -------- | -------------------- | ---- | ---------------- | 2113| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 2114 2115**Example** 2116 2117``` 2118audioRenderer.drain((err) => { 2119 if (err) { 2120 console.error('Renderer drain failed'); 2121 } else { 2122 console.log('Renderer drained.'); 2123 } 2124}); 2125``` 2126 2127### drain<sup>8+</sup> 2128 2129drain(): Promise\<void> 2130 2131Drains the playback buffer. This API uses a promise to return the result. 2132 2133**System capability**: SystemCapability.Multimedia.Audio.Renderer 2134 2135**Return value** 2136 2137| Type | Description | 2138| -------------- | ------------------------- | 2139| Promise\<void> | Promise used to return the result.| 2140 2141**Example** 2142 2143``` 2144audioRenderer.drain().then(() => { 2145 console.log('Renderer drained successfully'); 2146}).catch((err) => { 2147 console.log('ERROR: '+err.message); 2148}); 2149``` 2150 2151### stop<sup>8+</sup> 2152 2153stop(callback: AsyncCallback\<void>): void 2154 2155Stops rendering. This API uses an asynchronous callback to return the result. 2156 2157**System capability**: SystemCapability.Multimedia.Audio.Renderer 2158 2159**Parameters** 2160 2161| Name | Type | Mandatory| Description | 2162| -------- | -------------------- | ---- | ---------------- | 2163| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 2164 2165**Example** 2166 2167``` 2168audioRenderer.stop((err) => { 2169 if (err) { 2170 console.error('Renderer stop failed'); 2171 } else { 2172 console.log('Renderer stopped.'); 2173 } 2174}); 2175``` 2176 2177### stop<sup>8+</sup> 2178 2179stop(): Promise\<void> 2180 2181Stops rendering. This API uses a promise to return the result. 2182 2183**System capability**: SystemCapability.Multimedia.Audio.Renderer 2184 2185**Return value** 2186 2187| Type | Description | 2188| -------------- | ------------------------- | 2189| Promise\<void> | Promise used to return the result.| 2190 2191**Example** 2192 2193``` 2194audioRenderer.stop().then(() => { 2195 console.log('Renderer stopped successfully'); 2196}).catch((err) => { 2197 console.log('ERROR: '+err.message); 2198}); 2199``` 2200 2201### release<sup>8+</sup> 2202 2203release(callback: AsyncCallback\<void>): void 2204 2205Releases the renderer. This API uses an asynchronous callback to return the result. 2206 2207**System capability**: SystemCapability.Multimedia.Audio.Renderer 2208 2209**Parameters** 2210 2211| Name | Type | Mandatory| Description | 2212| -------- | -------------------- | ---- | ---------------- | 2213| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 2214 2215**Example** 2216 2217``` 2218audioRenderer.release((err) => { 2219 if (err) { 2220 console.error('Renderer release failed'); 2221 } else { 2222 console.log('Renderer released.'); 2223 } 2224}); 2225``` 2226 2227### release<sup>8+</sup> 2228 2229release(): Promise\<void> 2230 2231Releases the renderer. This API uses a promise to return the result. 2232 2233**System capability**: SystemCapability.Multimedia.Audio.Renderer 2234 2235**Return value** 2236 2237| Type | Description | 2238| -------------- | ------------------------- | 2239| Promise\<void> | Promise used to return the result.| 2240 2241**Example** 2242 2243``` 2244audioRenderer.release().then(() => { 2245 console.log('Renderer released successfully'); 2246}).catch((err) => { 2247 console.log('ERROR: '+err.message); 2248}); 2249``` 2250 2251### write<sup>8+</sup> 2252 2253write(buffer: ArrayBuffer, callback: AsyncCallback\<number>): void 2254 2255Writes the buffer. This API uses an asynchronous callback to return the result. 2256 2257**System capability**: SystemCapability.Multimedia.Audio.Renderer 2258 2259**Parameters** 2260 2261| Name | Type | Mandatory| Description | 2262| -------- | ---------------------- | ---- | --------------------------------------------------- | 2263| buffer | ArrayBuffer | Yes | Buffer to be written. | 2264| callback | AsyncCallback\<number> | Yes | Callback used to return the result. If the operation is successful, the number of bytes written is returned; otherwise, an error code is returned.| 2265 2266**Example** 2267 2268``` 2269import audio from '@ohos.multimedia.audio'; 2270import fileio from '@ohos.fileio'; 2271import featureAbility from '@ohos.ability.featureAbility' 2272 2273var audioStreamInfo = { 2274 samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_48000, 2275 channels: audio.AudioChannel.CHANNEL_2, 2276 sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S32LE, 2277 encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW 2278} 2279 2280var audioRendererInfo = { 2281 content: audio.ContentType.CONTENT_TYPE_SPEECH, 2282 usage: audio.streamUsage.STREAM_USAGE_VOICE_COMMUNICATION 2283 rendererFlags: 1 2284} 2285 2286var audioRendererOptions = { 2287 streamInfo: audioStreamInfo, 2288 rendererInfo: audioRendererInfo 2289} 2290var audioRenderer; 2291audio.createAudioRenderer(audioRendererOptions).then((data)=> { 2292 audioRenderer = data; 2293 console.info('AudioFrameworkRenderLog: AudioRenderer Created: SUCCESS'); 2294 }).catch((err) => { 2295 console.info('AudioFrameworkRenderLog: AudioRenderer Created: ERROR: '+err.message); 2296 }); 2297var bufferSize; 2298audioRenderer.getBufferSize().then((data)=> { 2299 console.info('AudioFrameworkRenderLog: getBufferSize: SUCCESS '+data); 2300 bufferSize = data; 2301 }).catch((err) => { 2302 console.info.('AudioFrameworkRenderLog: getBufferSize: ERROR: '+err.message); 2303 }); 2304console.info('Buffer size:'+bufferSize); 2305var context = featureAbility.getContext(); 2306var path = await context.getCacheDir(); 2307var filePath = path+"/StarWars10s-2C-48000-4SW.wav" 2308let ss = fileio.createStreamSync(filePath, 'r'); 2309let buf = new ArrayBuffer(bufferSize); 2310ss.readSync(buf); 2311audioRenderer.write(buf, (err, writtenbytes) => { 2312 if (writtenbytes < 0) { 2313 console.error('write failed.'); 2314 } else { 2315 console.log('Actual written bytes: ' + writtenbytes); 2316 } 2317}); 2318``` 2319 2320### write<sup>8+</sup> 2321 2322write(buffer: ArrayBuffer): Promise\<number> 2323 2324Writes the buffer. This API uses a promise to return the result. 2325 2326**System capability**: SystemCapability.Multimedia.Audio.Renderer 2327 2328**Return value** 2329 2330| Type | Description | 2331| ---------------- | ------------------------------------------------------------ | 2332| Promise\<number> | Promise used to return the result. If the operation is successful, the number of bytes written is returned; otherwise, an error code is returned.| 2333 2334**Example** 2335 2336``` 2337import audio from '@ohos.multimedia.audio'; 2338import fileio from '@ohos.fileio'; 2339import featureAbility from '@ohos.ability.featureAbility' 2340 2341var audioStreamInfo = { 2342 samplingRate:audio.AudioSamplingRate.SAMPLE_RATE_48000, 2343 channels:audio.AudioChannel.CHANNEL_2, 2344 sampleFormat.audio.AudioSampleFormat.SAMPLE_FORMAT_S32LE, 2345 encodingType.audio.AudioEncodingType.ENCODING_TYPE_RAW 2346} 2347 2348var audioRendererInfo = { 2349 content: audio.ContentType.CONTENT_TYPE_SPEECH, 2350 usage: audio.streamUsage.STREAM_USAGE_VOICE_COMMUNICATION, 2351 rendererFlags: 1 2352} 2353 2354var audioRendererOptions = { 2355 streamInfo: audioStreamInfo, 2356 rendererInfo: audioRendererInfo 2357} 2358var audioRenderer; 2359audio.createAudioRenderer(audioRendererOptions).then((data) => { 2360 audioRenderer = data; 2361 console.info('AudioFrameworkRenderLog: AudioRenderer Created: SUCCESS'); 2362 }).catch((err) => { 2363 console.info('AudioFrameworkRenderLog: AudioRenderer Created: ERROR: '+err.message); 2364 }); 2365var bufferSize; 2366audioRenderer.getBufferSize().then((data) => { 2367 console.info('AudioFrameworkRenderLog: getBufferSize: SUCCESS '+data); 2368 bufferSize = data; 2369 }).catch((err) => { 2370 console.info('AudioFrameworkRenderLog: getBufferSize: ERROR: '+err.message); 2371 }); 2372console.info('BufferSize: ' + bufferSize); 2373var context = featureAbility.getContext(); 2374var path = await context.getCacheDir(); 2375var filePath = 'data/StarWars10s-2C-48000-4SW.wav'; 2376let ss = fileio.createStreamSync(filePath, 'r'); 2377let buf = new ArrayBuffer(bufferSize); 2378ss.readSync(buf); 2379audioRenderer.write(buf).then((writtenbytes) => { 2380 if (writtenbytes < 0) { 2381 console.error('write failed.'); 2382 } else { 2383 console.log('Actual written bytes: ' + writtenbytes); 2384 } 2385}).catch((err) => { 2386 console.log('ERROR: '+err.message); 2387}); 2388``` 2389 2390### getAudioTime<sup>8+</sup> 2391 2392getAudioTime(callback: AsyncCallback\<number>): void 2393 2394Obtains the number of nanoseconds elapsed from the Unix epoch (January 1, 1970). This API uses an asynchronous callback to return the result. 2395 2396**System capability**: SystemCapability.Multimedia.Audio.Renderer 2397 2398**Parameters** 2399 2400| Name | Type | Mandatory| Description | 2401| -------- | ---------------------- | ---- | ---------------- | 2402| callback | AsyncCallback\<number> | Yes | Callback used to return the timestamp.| 2403 2404**Example** 2405 2406``` 2407audioRenderer.getAudioTime((err, timestamp) => { 2408 console.log('Current timestamp: ' + timestamp); 2409}); 2410``` 2411 2412### getAudioTime<sup>8+</sup> 2413 2414getAudioTime(): Promise\<number> 2415 2416Obtains the number of nanoseconds elapsed from the Unix epoch (January 1, 1970). This API uses a promise to return the result. 2417 2418**System capability**: SystemCapability.Multimedia.Audio.Renderer 2419 2420**Return value** 2421 2422| Type | Description | 2423| ---------------- | ----------------------- | 2424| Promise\<number> | Promise used to return the timestamp.| 2425 2426**Example** 2427 2428``` 2429audioRenderer.getAudioTime().then((timestamp) => { 2430 console.log('Current timestamp: ' + timestamp); 2431}).catch((err) => { 2432 console.log('ERROR: '+err.message); 2433}); 2434``` 2435 2436### getBufferSize<sup>8+</sup> 2437 2438getBufferSize(callback: AsyncCallback\<number>): void 2439 2440Obtains a reasonable minimum buffer size in bytes for rendering. This API uses an asynchronous callback to return the result. 2441 2442**System capability**: SystemCapability.Multimedia.Audio.Renderer 2443 2444**Parameters** 2445 2446| Name | Type | Mandatory| Description | 2447| -------- | ---------------------- | ---- | -------------------- | 2448| callback | AsyncCallback\<number> | Yes | Callback used to return the buffer size.| 2449 2450**Example** 2451 2452``` 2453var bufferSize = audioRenderer.getBufferSize(async(err, bufferSize) => { 2454 if (err) { 2455 console.error('getBufferSize error'); 2456 } 2457}); 2458``` 2459 2460### getBufferSize<sup>8+</sup> 2461 2462getBufferSize(): Promise\<number> 2463 2464Obtains a reasonable minimum buffer size in bytes for rendering. This API uses a promise to return the result. 2465 2466**System capability**: SystemCapability.Multimedia.Audio.Renderer 2467 2468**Return value** 2469 2470| Type | Description | 2471| ---------------- | --------------------------- | 2472| Promise\<number> | Promise used to return the buffer size.| 2473 2474**Example** 2475 2476``` 2477import audio from '@ohos.multimedia.audio'; 2478import fileio from '@ohos.fileio'; 2479 2480var audioStreamInfo = { 2481 samplingRate:audio.AudioSamplingRate.SAMPLE_RATE_48000, 2482 channels:audio.AudioChannel.CHANNEL_2, 2483 sampleFormat.audio.AudioSampleFormat.SAMPLE_FORMAT_S32LE, 2484 encodingType.audio.AudioEncodingType.ENCODING_TYPE_RAW 2485} 2486 2487var audioRendererInfo = { 2488 content: audio.ContentType.CONTENT_TYPE_SPEECH, 2489 usage: audio.streamUsage.STREAM_USAGE_VOICE_COMMUNICATION, 2490 rendererFlags: 1 2491} 2492 2493var audioRendererOptions = { 2494 streamInfo: audioStreamInfo, 2495 rendererInfo: audioRendererInfo 2496} 2497var audioRenderer; 2498audio.createAudioRenderer(audioRendererOptions).then((data) => { 2499 audioRenderer = data; 2500 console.info('AudioFrameworkRenderLog: AudioRenderer Created: SUCCESS'); 2501 }).catch((err) => { 2502 console.info('AudioFrameworkRenderLog: AudioRenderer Created: ERROR: '+err.message); 2503 }); 2504var bufferSize; 2505audioRenderer.getBufferSize().then((data) => { 2506 console.info('AudioFrameworkRenderLog: getBufferSize: SUCCESS '+data); 2507 bufferSize=data; 2508}).catch((err) => { 2509 console.info('AudioFrameworkRenderLog: getBufferSize: ERROR: '+err.message); 2510}); 2511``` 2512 2513### setRenderRate<sup>8+</sup> 2514 2515setRenderRate(rate: AudioRendererRate, callback: AsyncCallback\<void>): void 2516 2517Sets the render rate. This API uses an asynchronous callback to return the result. 2518 2519**System capability**: SystemCapability.Multimedia.Audio.Renderer 2520 2521**Parameters** 2522 2523| Name | Type | Mandatory| Description | 2524| -------- | ---------------------------------------- | ---- | ------------------------ | 2525| rate | [AudioRendererRate](#audiorendererrate8) | Yes | Audio render rate. | 2526| callback | AsyncCallback\<void> | Yes | Callback used to return the result.| 2527 2528**Example** 2529 2530``` 2531audioRenderer.setRenderRate(audio.AudioRendererRate.RENDER_RATE_NORMAL, (err) => { 2532 if (err) { 2533 console.error('Failed to set params'); 2534 } else { 2535 console.log('Callback invoked to indicate a successful render rate setting.'); 2536 } 2537}); 2538``` 2539 2540### setRenderRate<sup>8+</sup> 2541 2542setRenderRate(rate: AudioRendererRate): Promise\<void> 2543 2544Sets the render rate. This API uses a promise to return the result. 2545 2546**System capability**: SystemCapability.Multimedia.Audio.Renderer 2547 2548**Parameters** 2549 2550| Name| Type | Mandatory| Description | 2551| ------ | ---------------------------------------- | ---- | ------------ | 2552| rate | [AudioRendererRate](#audiorendererrate8) | Yes | Audio render rate.| 2553 2554**Return value** 2555 2556| Type | Description | 2557| -------------- | ------------------------- | 2558| Promise\<void> | Promise used to return the result.| 2559 2560**Example** 2561 2562``` 2563audioRenderer.setRenderRate(audio.AudioRendererRate.RENDER_RATE_NORMAL).then(() => { 2564 console.log('setRenderRate SUCCESS'); 2565}).catch((err) => { 2566 console.log('ERROR: '+err.message); 2567}); 2568``` 2569 2570### getRenderRate<sup>8+</sup> 2571 2572getRenderRate(callback: AsyncCallback\<AudioRendererRate>): void 2573 2574Obtains the current render rate. This API uses an asynchronous callback to return the result. 2575 2576**System capability**: SystemCapability.Multimedia.Audio.Renderer 2577 2578**Parameters** 2579 2580| Name | Type | Mandatory| Description | 2581| -------- | ------------------------------------------------------- | ---- | ------------------ | 2582| callback | AsyncCallback<[AudioRendererRate](#audiorendererrate8)> | Yes | Callback used to return the audio render rate.| 2583 2584**Example** 2585 2586``` 2587audioRenderer.getRenderRate((err, renderrate) => { 2588 console.log('getRenderRate: ' + renderrate); 2589}); 2590``` 2591 2592### getRenderRate<sup>8+</sup> 2593 2594getRenderRate(): Promise\<AudioRendererRate> 2595 2596Obtains the current render rate. This API uses a promise to return the result. 2597 2598**System capability**: SystemCapability.Multimedia.Audio.Renderer 2599 2600**Return value** 2601 2602| Type | Description | 2603| ------------------------------------------------- | ------------------------- | 2604| Promise<[AudioRendererRate](#audiorendererrate8)> | Promise used to return the audio render rate.| 2605 2606**Example** 2607 2608``` 2609audioRenderer.getRenderRate().then((renderRate) => { 2610 console.log('getRenderRate: ' + renderRate); 2611}).catch((err) => { 2612 console.log('ERROR: '+err.message); 2613}); 2614``` 2615 2616### on('interrupt')<sup>9+</sup> 2617 2618on(type: 'interrupt', callback: Callback\<InterruptEvent>): void 2619 2620Subscribes to audio interruption events. This API uses a callback to get interrupt events. 2621 2622**System capability**: SystemCapability.Multimedia.Audio.Renderer 2623 2624**Parameters** 2625 2626| Name | Type | Mandatory| Description | 2627| -------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | 2628| type | string | Yes | Event type. The value **'interrupt'** means the audio interruption event, which is triggered when audio playback is interrupted.| 2629| callback | Callback<[InterruptEvent](#interruptevent9)> | Yes | Callback used to return the audio interruption event. | 2630 2631**Example** 2632 2633``` 2634var isPlay; 2635var started; 2636audioRenderer.on('interrupt', async(interruptEvent) => { 2637 if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_FORCE) { 2638 switch (interruptEvent.hintType) { 2639 case audio.InterruptHint.INTERRUPT_HINT_PAUSE: 2640 console.log('Force paused. Stop writing'); 2641 isPlay = false; 2642 break; 2643 case audio.InterruptHint.INTERRUPT_HINT_STOP: 2644 console.log('Force stopped. Stop writing'); 2645 isPlay = false; 2646 break; 2647 } 2648 } else if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_SHARE) { 2649 switch (interruptEvent.hintType) { 2650 case audio.InterruptHint.INTERRUPT_HINT_RESUME: 2651 console.log('Resume force paused renderer or ignore'); 2652 await audioRenderer.start().then(async function () { 2653 console.info('AudioInterruptMusic: renderInstant started :SUCCESS '); 2654 started = true; 2655 }).catch((err) => { 2656 console.info('AudioInterruptMusic: renderInstant start :ERROR : '+err.message); 2657 started = false; 2658 }); 2659 if (started) { 2660 isPlay = true; 2661 console.info('AudioInterruptMusic Renderer started : isPlay : '+isPlay); 2662 } else { 2663 console.error('AudioInterruptMusic Renderer start failed'); 2664 } 2665 break; 2666 case audio.InterruptHint.INTERRUPT_HINT_PAUSE: 2667 console.log('Choose to pause or ignore'); 2668 if (isPlay == true) { 2669 isPlay == false; 2670 console.info('AudioInterruptMusic: Media PAUSE : TRUE'); 2671 } 2672 else { 2673 isPlay = true; 2674 console.info('AudioInterruptMusic: Media PLAY : TRUE'); 2675 } 2676 break; 2677 } 2678 } 2679}); 2680``` 2681 2682### on('markReach')<sup>8+</sup> 2683 2684on(type: 'markReach', frame: number, callback: (position: number) => {}): void 2685 2686Subscribes to mark reached events. When the number of frames rendered reaches the value of the **frame** parameter, the callback is invoked. 2687 2688**System capability**: SystemCapability.Multimedia.Audio.Renderer 2689 2690**Parameters** 2691 2692| Name | Type | Mandatory| Description | 2693| :------- | :----------------------- | :--- | :---------------------------------------- | 2694| type | string | Yes | Event type. The value **'markReach'** means the mark reached event, which is triggered when the number of frames captured reaches the value of the **frame** parameter.| 2695| frame | number | Yes | Number of frames to trigger the event. The value must be greater than **0**. | 2696| callback | (position: number) => {} | Yes | Callback invoked when the event is triggered. | 2697 2698**Example** 2699 2700``` 2701audioRenderer.on('markReach', 1000, (position) => { 2702 if (position == 1000) { 2703 console.log('ON Triggered successfully'); 2704 } 2705}); 2706``` 2707 2708 2709### off('markReach') <sup>8+</sup> 2710 2711off(type: 'markReach'): void 2712 2713Unsubscribes from mark reached events. 2714 2715**System capability**: SystemCapability.Multimedia.Audio.Renderer 2716 2717**Parameters** 2718 2719| Name| Type | Mandatory| Description | 2720| :----- | :----- | :--- | :------------------------------------------------ | 2721| type | string | Yes | Event type. The value is fixed at **'markReach'**.| 2722 2723**Example** 2724 2725``` 2726audioRenderer.off('markReach'); 2727``` 2728 2729### on('periodReach') <sup>8+</sup> 2730 2731on(type: "periodReach", frame: number, callback: (position: number) => {}): void 2732 2733Subscribes to period reached events. When the period of frame rendering reaches the value of the **frame** parameter, the callback is invoked. 2734 2735**System capability**: SystemCapability.Multimedia.Audio.Renderer 2736 2737**Parameters** 2738 2739| Name | Type | Mandatory| Description | 2740| :------- | :----------------------- | :--- | :------------------------------------------ | 2741| type | string | Yes | Event type. The value **'periodReach'** means the period reached event, which is triggered when the period of frame rendering reaches the value of the **frame** parameter.| 2742| frame | number | Yes | Period during which frame rendering is listened. The value must be greater than **0**. | 2743| callback | (position: number) => {} | Yes | Callback invoked when the event is triggered. | 2744 2745**Example** 2746 2747``` 2748audioRenderer.on('periodReach', 1000, (position) => { 2749 if (position == 1000) { 2750 console.log('ON Triggered successfully'); 2751 } 2752}); 2753``` 2754 2755### off('periodReach') <sup>8+</sup> 2756 2757off(type: 'periodReach'): void 2758 2759Unsubscribes from period reached events. 2760 2761**System capability**: SystemCapability.Multimedia.Audio.Renderer 2762 2763**Parameters** 2764 2765| Name| Type | Mandatory| Description | 2766| :----- | :----- | :--- | :-------------------------------------------------- | 2767| type | string | Yes | Event type. The value is fixed at **'periodReach'**.| 2768 2769**Example** 2770 2771``` 2772audioRenderer.off('periodReach') 2773``` 2774 2775### on('stateChange') <sup>8+</sup> 2776 2777on(type: 'stateChange', callback: Callback<AudioState\>): void 2778 2779Subscribes to state change events. 2780 2781**System capability**: SystemCapability.Multimedia.Audio.Renderer 2782 2783**Parameters** 2784 2785| Name | Type | Mandatory| Description | 2786| :------- | :------------------------- | :--- | :------------------------------------------ | 2787| type | string | Yes | Event type. The value **'stateChange'** means the state change event.| 2788| callback | [AudioState](#audiostate8) | Yes | Callback used to return the state change. | 2789 2790**Example** 2791 2792``` 2793audioRenderer.on('stateChange', (state) => { 2794 if (state == 1) { 2795 console.log("audio renderer state is: STATE_PREPARED"); 2796 } 2797 if (state == 2) { 2798 console.log("audio renderer state is: STATE_RUNNING"); 2799 } 2800}); 2801``` 2802 2803## AudioCapturer<sup>8+</sup> 2804 2805Provides APIs for audio capture. Before calling any API in **AudioCapturer**, you must use [createAudioCapturer](#audiocreateaudiocapturer8) to create an **AudioCapturer** instance. 2806 2807### Attributes 2808 2809**System capability**: SystemCapability.Multimedia.Audio.Capturer 2810 2811| Name | Type | Readable| Writable| Description | 2812| :---- | :------------------------- | :--- | :--- | :--------------- | 2813| state<sup>8+</sup> | [AudioState](#audiostate8) | Yes | No | Audio capturer state.| 2814 2815**Example** 2816 2817``` 2818var state = audioCapturer.state; 2819``` 2820 2821### getCapturerInfo<sup>8+</sup> 2822 2823getCapturerInfo(callback: AsyncCallback<AudioCapturerInfo\>): void 2824 2825Obtains the capturer information of this **AudioCapturer** instance. This API uses an asynchronous callback to return the result. 2826 2827**System capability**: SystemCapability.Multimedia.Audio.Capturer 2828 2829**Parameters** 2830 2831| Name | Type | Mandatory| Description | 2832| :------- | :-------------------------------- | :--- | :----------------------------------- | 2833| callback | AsyncCallback<AudioCapturerInfo\> | Yes | Callback used to return the capturer information.| 2834 2835**Example** 2836 2837``` 2838audioCapturer.getCapturerInfo((err, capturerInfo) => { 2839 if (err) { 2840 console.error('Failed to get capture info'); 2841 } else { 2842 console.log('Capturer getCapturerInfo:'); 2843 console.log('Capturer source:' + capturerInfo.source); 2844 console.log('Capturer flags:' + capturerInfo.capturerFlags); 2845 } 2846}); 2847``` 2848 2849 2850### getCapturerInfo<sup>8+</sup> 2851 2852getCapturerInfo(): Promise<AudioCapturerInfo\> 2853 2854Obtains the capturer information of this **AudioCapturer** instance. This API uses a promise to return the result. 2855 2856**System capability**: SystemCapability.Multimedia.Audio.Capturer 2857 2858**Return value** 2859 2860| Type | Description | 2861| :------------------------------------------------ | :---------------------------------- | 2862| Promise<[AudioCapturerInfo](#audiocapturerinfo)\> | Promise used to return the capturer information.| 2863 2864**Example** 2865 2866``` 2867audioCapturer.getCapturerInfo().then((audioParamsGet) => { 2868 if (audioParamsGet != undefined) { 2869 console.info('AudioFrameworkRecLog: Capturer CapturerInfo:'); 2870 console.info('AudioFrameworkRecLog: Capturer SourceType:' + audioParamsGet.source); 2871 console.info('AudioFrameworkRecLog: Capturer capturerFlags:' + audioParamsGet.capturerFlags); 2872 }else { 2873 console.info('AudioFrameworkRecLog: audioParamsGet is : '+audioParamsGet); 2874 console.info('AudioFrameworkRecLog: audioParams getCapturerInfo are incorrect: '); 2875 } 2876}).catch((err) => { 2877 console.log('AudioFrameworkRecLog: CapturerInfo :ERROR: '+err.message); 2878}); 2879``` 2880 2881### getStreamInfo<sup>8+</sup> 2882 2883getStreamInfo(callback: AsyncCallback<AudioStreamInfo\>): void 2884 2885Obtains the stream information of this **AudioCapturer** instance. This API uses an asynchronous callback to return the result. 2886 2887**System capability**: SystemCapability.Multimedia.Audio.Capturer 2888 2889**Parameters** 2890 2891| Name | Type | Mandatory| Description | 2892| :------- | :--------------------------------------------------- | :--- | :------------------------------- | 2893| callback | AsyncCallback<[AudioStreamInfo](#audiostreaminfo8)\> | Yes | Callback used to return the stream information.| 2894 2895**Example** 2896 2897``` 2898audioCapturer.getStreamInfo((err, streamInfo) => { 2899 if (err) { 2900 console.error('Failed to get stream info'); 2901 } else { 2902 console.log('Capturer GetStreamInfo:'); 2903 console.log('Capturer sampling rate:' + streamInfo.samplingRate); 2904 console.log('Capturer channel:' + streamInfo.channels); 2905 console.log('Capturer format:' + streamInfo.sampleFormat); 2906 console.log('Capturer encoding type:' + streamInfo.encodingType); 2907 } 2908}); 2909``` 2910 2911### getStreamInfo<sup>8+</sup> 2912 2913getStreamInfo(): Promise<AudioStreamInfo\> 2914 2915Obtains the stream information of this **AudioCapturer** instance. This API uses a promise to return the result. 2916 2917**System capability**: SystemCapability.Multimedia.Audio.Capturer 2918 2919**Return value** 2920 2921| Type | Description | 2922| :--------------------------------------------- | :------------------------------ | 2923| Promise<[AudioStreamInfo](#audiostreaminfo8)\> | Promise used to return the stream information.| 2924 2925**Example** 2926 2927``` 2928audioCapturer.getStreamInfo().then((audioParamsGet) => { 2929 console.info('getStreamInfo:'); 2930 console.info('sampleFormat:' + audioParamsGet.sampleFormat); 2931 console.info('samplingRate:' + audioParamsGet.samplingRate); 2932 console.info('channels:' + audioParamsGet.channels); 2933 console.info('encodingType:' + audioParamsGet.encodingType); 2934}).catch((err) => { 2935 console.log('getStreamInfo :ERROR: ' + err.message); 2936}); 2937``` 2938 2939### start<sup>8+</sup> 2940 2941start(callback: AsyncCallback<void\>): void 2942 2943Starts capturing. This API uses an asynchronous callback to return the result. 2944 2945**System capability**: SystemCapability.Multimedia.Audio.Capturer 2946 2947**Parameters** 2948 2949| Name | Type | Mandatory| Description | 2950| :------- | :------------------- | :--- | :----------------------------- | 2951| callback | AsyncCallback<void\> | Yes | Callback used to return the result.| 2952 2953**Example** 2954 2955``` 2956audioCapturer.start((err) => { 2957 if (err) { 2958 console.error('Capturer start failed.'); 2959 } else { 2960 console.info('Capturer start success.'); 2961 } 2962}); 2963``` 2964 2965 2966### start<sup>8+</sup> 2967 2968start(): Promise<void\> 2969 2970Starts capturing. This API uses a promise to return the result. 2971 2972**System capability**: SystemCapability.Multimedia.Audio.Capturer 2973 2974**Return value** 2975 2976| Type | Description | 2977| :------------- | :---------------------------- | 2978| Promise<void\> | Promise used to return the result.| 2979 2980**Example** 2981 2982``` 2983import audio from '@ohos.multimedia.audio'; 2984import fileio from '@ohos.fileio'; 2985 2986var audioStreamInfo = { 2987 samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_44100, 2988 channels: audio.AudioChannel.CHANNEL_2, 2989 sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, 2990 encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW 2991} 2992 2993var audioCapturerInfo = { 2994 source: audio.SourceType.SOURCE_TYPE_MIC, 2995 capturerFlags = 1 2996} 2997 2998var audioCapturer; 2999audio.createAudioCapturer(audioCapturerOptions).then((data) => { 3000 audioCapturer = data; 3001 console.info('AudioFrameworkRecLog: AudioCapturer Created: SUCCESS'); 3002 }).catch((err) => { 3003 console.info('AudioFrameworkRecLog: AudioCapturer Created: ERROR: '+err.message); 3004 }); 3005audioCapturer.start().then(() => { 3006 console.info('AudioFrameworkRecLog: ---------START---------'); 3007 console.info('AudioFrameworkRecLog: Capturer started: SUCCESS'); 3008 console.info('AudioFrameworkRecLog: AudioCapturer: STATE: '+audioCapturer.state); 3009 console.info('AudioFrameworkRecLog: Capturer started: SUCCESS '); 3010 if ((audioCapturer.state == audio.AudioState.STATE_RUNNING)) { 3011 console.info('AudioFrameworkRecLog: AudioCapturer is in Running State'); 3012 } 3013}).catch((err) => { 3014 console.info('AudioFrameworkRecLog: Capturer start :ERROR : '+err.message); 3015 stateFlag=false; 3016}); 3017``` 3018 3019### stop<sup>8+</sup> 3020 3021stop(callback: AsyncCallback<void\>): void 3022 3023Stops capturing. This API uses an asynchronous callback to return the result. 3024 3025**System capability**: SystemCapability.Multimedia.Audio.Capturer 3026 3027**Parameters** 3028 3029| Name | Type | Mandatory| Description | 3030| :------- | :------------------- | :--- | :----------------------------- | 3031| callback | AsyncCallback<void\> | Yes | Callback used to return the result.| 3032 3033**Example** 3034 3035``` 3036audioCapturer.stop((err) => { 3037 if (err) { 3038 console.error('Capturer stop failed'); 3039 } else { 3040 console.log('Capturer stopped.'); 3041 } 3042}); 3043``` 3044 3045 3046### stop<sup>8+</sup> 3047 3048stop(): Promise<void\> 3049 3050Stops capturing. This API uses a promise to return the result. 3051 3052**System capability**: SystemCapability.Multimedia.Audio.Capturer 3053 3054**Return value** 3055 3056| Type | Description | 3057| :------------- | :---------------------------- | 3058| Promise<void\> | Promise used to return the result.| 3059 3060**Example** 3061 3062``` 3063audioCapturer.stop().then(() => { 3064 console.info('AudioFrameworkRecLog: ---------STOP RECORD---------'); 3065 console.info('AudioFrameworkRecLog: Capturer stopped: SUCCESS'); 3066 if ((audioCapturer.state == audio.AudioState.STATE_STOPPED)){ 3067 console.info('AudioFrameworkRecLog: State is Stopped': '); 3068 } 3069}).catch((err) => { 3070 console.info('AudioFrameworkRecLog: Capturer stop: ERROR: '+err.message); 3071}); 3072``` 3073 3074### release<sup>8+</sup> 3075 3076release(callback: AsyncCallback<void\>): void 3077 3078Releases this **AudioCapturer** instance. This API uses an asynchronous callback to return the result. 3079 3080**System capability**: SystemCapability.Multimedia.Audio.Capturer 3081 3082**Parameters** 3083 3084| Name | Type | Mandatory| Description | 3085| :------- | :------------------- | :--- | :---------------------------------- | 3086| callback | AsyncCallback<void\> | Yes | Callback used to return the result. | 3087 3088**Example** 3089 3090``` 3091audioCapturer.release((err) => { 3092 if (err) { 3093 console.error('capturer release failed'); 3094 } else { 3095 console.log('capturer released.'); 3096 } 3097}); 3098``` 3099 3100 3101### release<sup>8+</sup> 3102 3103release(): Promise<void\> 3104 3105Releases this **AudioCapturer** instance. This API uses a promise to return the result. 3106 3107**System capability**: SystemCapability.Multimedia.Audio.Capturer 3108 3109**Return value** 3110 3111| Type | Description | 3112| :------------- | :---------------------------- | 3113| Promise<void\> | Promise used to return the result.| 3114 3115**Example** 3116 3117``` 3118audioCapturer.release().then(() => { 3119 console.info('AudioFrameworkRecLog: ---------RELEASE RECORD---------'); 3120 console.info('AudioFrameworkRecLog: Capturer release : SUCCESS'); 3121 console.info('AudioFrameworkRecLog: AudioCapturer : STATE : '+audioCapturer.state); 3122 console.info('AudioFrameworkRecLog: stateFlag : '+stateFlag); 3123}).catch((err) => { 3124 console.info('AudioFrameworkRecLog: Capturer stop: ERROR: '+err.message); 3125}); 3126``` 3127 3128 3129### read<sup>8+</sup> 3130 3131read(size: number, isBlockingRead: boolean, callback: AsyncCallback<ArrayBuffer\>): void 3132 3133Reads the buffer. This API uses an asynchronous callback to return the result. 3134 3135**System capability**: SystemCapability.Multimedia.Audio.Capturer 3136 3137**Parameters** 3138 3139| Name | Type | Mandatory| Description | 3140| :------------- | :-------------------------- | :--- | :------------------------------- | 3141| size | number | Yes | Number of bytes to read. | 3142| isBlockingRead | boolean | Yes | Whether to block the read operation. | 3143| callback | AsyncCallback<ArrayBuffer\> | Yes | Callback used to return the buffer.| 3144 3145**Example** 3146 3147``` 3148var bufferSize; 3149audioCapturer.getBufferSize().then((data) => { 3150 console.info('AudioFrameworkRecLog: getBufferSize: SUCCESS '+data); 3151 bufferSize = data; 3152 }).catch((err) => { 3153 console.info('AudioFrameworkRecLog: getBufferSize: EROOR: '+err.message); 3154 }); 3155audioCapturer.read(bufferSize, true, async(err, buffer) => { 3156 if (!err) { 3157 console.log("Success in reading the buffer data"); 3158 } 3159}); 3160``` 3161 3162 3163### read<sup>8+</sup> 3164 3165read(size: number, isBlockingRead: boolean): Promise<ArrayBuffer\> 3166 3167Reads the buffer. This API uses a promise to return the result. 3168 3169**System capability**: SystemCapability.Multimedia.Audio.Capturer 3170 3171**Parameters** 3172 3173| Name | Type | Mandatory| Description | 3174| :------------- | :------ | :--- | :--------------- | 3175| size | number | Yes | Number of bytes to read. | 3176| isBlockingRead | boolean | Yes | Whether to block the read operation.| 3177 3178**Return value** 3179 3180| Type | Description | 3181| :-------------------- | :----------------------------------------------------- | 3182| Promise<ArrayBuffer\> | Promise used to return the result. If the operation is successful, the buffer data read is returned; otherwise, an error code is returned.| 3183 3184**Example** 3185 3186``` 3187var bufferSize; 3188audioCapturer.getBufferSize().then((data) => { 3189 console.info('AudioFrameworkRecLog: getBufferSize: SUCCESS '+data); 3190 bufferSize = data; 3191 }).catch((err) => { 3192 console.info('AudioFrameworkRecLog: getBufferSize: ERROR '+err.message); 3193 }); 3194console.info('Buffer size: ' + bufferSize); 3195audioCapturer.read(bufferSize, true).then((buffer) => { 3196 console.info('buffer read successfully'); 3197}).catch((err) => { 3198 console.info('ERROR : '+err.message); 3199}); 3200``` 3201 3202 3203### getAudioTime<sup>8+</sup> 3204 3205getAudioTime(callback: AsyncCallback<number\>): void 3206 3207Obtains the number of nanoseconds elapsed from the Unix epoch (January 1, 1970). This API uses an asynchronous callback to return the result. 3208 3209**System capability**: SystemCapability.Multimedia.Audio.Capturer 3210 3211**Parameters** 3212 3213| Name | Type | Mandatory| Description | 3214| :------- | :--------------------- | :--- | :----------------------------- | 3215| callback | AsyncCallback<number\> | Yes | Callback used to return the timestamp. | 3216 3217**Example** 3218 3219``` 3220audioCapturer.getAudioTime((err, timestamp) => { 3221 console.log('Current timestamp: ' + timestamp); 3222}); 3223``` 3224 3225 3226### getAudioTime<sup>8+</sup> 3227 3228getAudioTime(): Promise<number\> 3229 3230Obtains the number of nanoseconds elapsed from the Unix epoch (January 1, 1970). This API uses a promise to return the result. 3231 3232**System capability**: SystemCapability.Multimedia.Audio.Capturer 3233 3234**Return value** 3235 3236| Type | Description | 3237| :--------------- | :---------------------------- | 3238| Promise<number\> | Promise used to return the timestamp.| 3239 3240**Example** 3241 3242``` 3243audioCapturer.getAudioTime().then((audioTime) => { 3244 console.info('AudioFrameworkRecLog: AudioCapturer getAudioTime : Success' + audioTime ); 3245}).catch((err) => { 3246 console.info('AudioFrameworkRecLog: AudioCapturer Created : ERROR : '+err.message); 3247}); 3248``` 3249 3250 3251### getBufferSize<sup>8+</sup> 3252 3253getBufferSize(callback: AsyncCallback<number\>): void 3254 3255Obtains a reasonable minimum buffer size in bytes for capturing. This API uses an asynchronous callback to return the result. 3256 3257**System capability**: SystemCapability.Multimedia.Audio.Capturer 3258 3259**Parameters** 3260 3261| Name | Type | Mandatory| Description | 3262| :------- | :--------------------- | :--- | :----------------------------------- | 3263| callback | AsyncCallback<number\> | Yes | Callback used to return the buffer size.| 3264 3265**Example** 3266 3267``` 3268audioCapturer.getBufferSize((err, bufferSize) => { 3269 if (!err) { 3270 console.log('BufferSize : ' + bufferSize); 3271 audioCapturer.read(bufferSize, true).then((buffer) => { 3272 console.info('Buffer read is ' + buffer ); 3273 }).catch((err) => { 3274 console.info('AudioFrameworkRecLog: AudioCapturer Created : ERROR : '+err.message); 3275 }); 3276 } 3277}); 3278``` 3279 3280 3281### getBufferSize<sup>8+</sup> 3282 3283getBufferSize(): Promise<number\> 3284 3285Obtains a reasonable minimum buffer size in bytes for capturing. This API uses a promise to return the result. 3286 3287**System capability**: SystemCapability.Multimedia.Audio.Capturer 3288 3289**Return value** 3290 3291| Type | Description | 3292| :--------------- | :---------------------------------- | 3293| Promise<number\> | Promise used to return the buffer size.| 3294 3295**Example** 3296 3297``` 3298var bufferSize; 3299audioCapturer.getBufferSize().then((data) => { 3300 console.info('AudioFrameworkRecLog: getBufferSize :SUCCESS '+ data); 3301 bufferSize = data; 3302}).catch((err) => { 3303 console.info('AudioFrameworkRecLog: getBufferSize :ERROR : '+ err.message); 3304}); 3305``` 3306 3307 3308### on('markReach')<sup>8+</sup> 3309 3310on(type: 'markReach', frame: number, callback: (position: number) => {}): void 3311 3312Subscribes to mark reached events. When the number of frames captured reaches the value of the **frame** parameter, the callback is invoked. 3313 3314**System capability**: SystemCapability.Multimedia.Audio.Capturer 3315 3316**Parameters** 3317 3318| Name | Type | Mandatory| Description | 3319| :------- | :---------------------- | :--- | :----------------------------------------- | 3320| type | string | Yes | Event type. The value **'markReach'** means the mark reached event, which is triggered when the number of frames captured reaches the value of the **frame** parameter. | 3321| frame | number | Yes | Number of frames to trigger the event. The value must be greater than **0**. | 3322| callback | position: number) => {} | Yes | Callback invoked when the event is triggered.| 3323 3324**Example** 3325 3326``` 3327audioCapturer.on('markReach', 1000, (position) => { 3328 if (position == 1000) { 3329 console.log('ON Triggered successfully'); 3330 } 3331}); 3332``` 3333 3334### off('markReach')<sup>8+</sup> 3335 3336off(type: 'markReach'): void 3337 3338Unsubscribes from mark reached events. 3339 3340**System capability**: SystemCapability.Multimedia.Audio.Capturer 3341 3342**Parameters** 3343 3344| Name| Type | Mandatory| Description | 3345| :----- | :----- | :--- | :-------------------------------------------- | 3346| type | string | Yes | Event type. The value **'markReach'** means the mark reached event, which is triggered when the number of frames captured reaches the value of the **frame** parameter.| 3347 3348**Example** 3349 3350``` 3351audioCapturer.off('markReach'); 3352``` 3353 3354### on('periodReach')<sup>8+</sup> 3355 3356on(type: "periodReach", frame: number, callback: (position: number) => {}): void 3357 3358Subscribes to mark reached events. When the period of frame capturing reaches the value of the **frame** parameter, the callback is invoked. 3359 3360**System capability**: SystemCapability.Multimedia.Audio.Capturer 3361 3362**Parameters** 3363 3364| Name | Type | Mandatory| Description | 3365| :------- | :----------------------- | :--- | :------------------------------------------ | 3366| type | string | Yes | Event type. The value **'periodReach'** means the period reached event, which is triggered when the period of frame capturing reaches the value of the **frame** parameter. | 3367| frame | number | Yes | Period during which frame capturing is listened. The value must be greater than **0**. | 3368| callback | (position: number) => {} | Yes | Callback invoked when the event is triggered. | 3369 3370**Example** 3371 3372``` 3373audioCapturer.on('periodReach', 1000, (position) => { 3374 if (position == 1000) { 3375 console.log('ON Triggered successfully'); 3376 } 3377}); 3378``` 3379 3380### off('periodReach')<sup>8+</sup> 3381 3382off(type: 'periodReach'): void 3383 3384Unsubscribes from period reached events. 3385 3386**System capability**: SystemCapability.Multimedia.Audio.Capturer 3387 3388**Parameters** 3389 3390| Name| Type | Mandatory| Description | 3391| :----- | :----- | :--- | :---------------------------------------------- | 3392| type | string | Yes | Event type. The value **'periodReach'** means the period reached event, which is triggered when the period of frame capturing reaches the value of the **frame** parameter.| 3393 3394**Example** 3395 3396``` 3397audioCapturer.off('periodReach') 3398``` 3399 3400### on('stateChange') <sup>8+</sup> 3401 3402on(type: 'stateChange', callback: Callback<AudioState\>): void 3403 3404Subscribes to state change events. 3405 3406**System capability**: SystemCapability.Multimedia.Audio.Capturer 3407 3408**Parameters** 3409 3410| Name | Type | Mandatory| Description | 3411| :------- | :------------------------- | :--- | :------------------------------------------ | 3412| type | string | Yes | Event type. The value **'stateChange'** means the state change event.| 3413| callback | [AudioState](#audiostate8) | Yes | Callback used to return the state change. | 3414 3415**Example** 3416 3417``` 3418audioCapturer.on('stateChange', (state) => { 3419 if (state == 1) { 3420 console.log("audio capturer state is: STATE_PREPARED"); 3421 } 3422 if (state == 2) { 3423 console.log("audio capturer state is: STATE_RUNNING"); 3424 } 3425}); 3426``` 3427