1# @ohos.multimedia.audio (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## Modules to Import 16 17```ts 18import { audio } from '@kit.AudioKit'; 19``` 20 21## Constants 22 23| Name | Type | Readable | Writable| Description | 24| --------------------------------------- | ----------| ---- | ---- | ------------------ | 25| DEFAULT_VOLUME_GROUP_ID<sup>9+</sup> | number | Yes | No | Default volume group ID.<br> **System capability**: SystemCapability.Multimedia.Audio.Volume | 26| DEFAULT_INTERRUPT_GROUP_ID<sup>9+</sup> | number | Yes | No | Default audio interruption group ID.<br> **System capability**: SystemCapability.Multimedia.Audio.Interrupt | 27 28**Example** 29 30```ts 31import { audio } from '@kit.AudioKit'; 32 33const defaultVolumeGroupId = audio.DEFAULT_VOLUME_GROUP_ID; 34const defaultInterruptGroupId = audio.DEFAULT_INTERRUPT_GROUP_ID; 35``` 36 37## audio.getAudioManager 38 39getAudioManager(): AudioManager 40 41Obtains an **AudioManager** instance. 42 43**System capability**: SystemCapability.Multimedia.Audio.Core 44 45**Return value** 46 47| Type | Description | 48| ----------------------------- | ------------ | 49| [AudioManager](#audiomanager) | **AudioManager** instance.| 50 51**Example** 52```ts 53import { audio } from '@kit.AudioKit'; 54 55let audioManager = audio.getAudioManager(); 56``` 57 58## audio.createAudioRenderer<sup>8+</sup> 59 60createAudioRenderer(options: AudioRendererOptions, callback: AsyncCallback\<AudioRenderer>): void 61 62Creates an **AudioRenderer** instance. This API uses an asynchronous callback to return the result. 63 64**System capability**: SystemCapability.Multimedia.Audio.Renderer 65 66**Parameters** 67 68| Name | Type | Mandatory| Description | 69| -------- | ----------------------------------------------- | ---- | ---------------- | 70| options | [AudioRendererOptions](#audiorendereroptions8) | Yes | Renderer configurations. | 71| callback | AsyncCallback<[AudioRenderer](#audiorenderer8)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the **AudioRenderer** instance obtained; otherwise, **err** is an error object.| 72 73**Example** 74 75```ts 76import { audio } from '@kit.AudioKit'; 77 78let audioStreamInfo: audio.AudioStreamInfo = { 79 samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_48000, 80 channels: audio.AudioChannel.CHANNEL_2, 81 sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, 82 encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW 83}; 84 85let audioRendererInfo: audio.AudioRendererInfo = { 86 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 87 rendererFlags: 0 88}; 89 90let audioRendererOptions: audio.AudioRendererOptions = { 91 streamInfo: audioStreamInfo, 92 rendererInfo: audioRendererInfo 93}; 94 95audio.createAudioRenderer(audioRendererOptions,(err, data) => { 96 if (err) { 97 console.error(`AudioRenderer Created: Error: ${err}`); 98 } else { 99 console.info('AudioRenderer Created: Success: SUCCESS'); 100 let audioRenderer = data; 101 } 102}); 103``` 104 105## audio.createAudioRenderer<sup>8+</sup> 106 107createAudioRenderer(options: AudioRendererOptions): Promise<AudioRenderer\> 108 109Creates an **AudioRenderer** instance. This API uses a promise to return the result. 110 111**System capability**: SystemCapability.Multimedia.Audio.Renderer 112 113**Parameters** 114 115| Name | Type | Mandatory| Description | 116| :------ | :--------------------------------------------- | :--- | :----------- | 117| options | [AudioRendererOptions](#audiorendereroptions8) | Yes | Renderer configurations.| 118 119**Return value** 120 121| Type | Description | 122| ----------------------------------------- | ---------------- | 123| Promise<[AudioRenderer](#audiorenderer8)> | Promise used to return the **AudioRenderer** instance.| 124 125**Example** 126 127```ts 128import { audio } from '@kit.AudioKit'; 129import { BusinessError } from '@kit.BasicServicesKit'; 130 131let audioStreamInfo: audio.AudioStreamInfo = { 132 samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_48000, 133 channels: audio.AudioChannel.CHANNEL_2, 134 sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, 135 encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW 136}; 137 138let audioRendererInfo: audio.AudioRendererInfo = { 139 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 140 rendererFlags: 0 141}; 142 143let audioRendererOptions: audio.AudioRendererOptions = { 144 streamInfo: audioStreamInfo, 145 rendererInfo: audioRendererInfo 146}; 147 148let audioRenderer: audio.AudioRenderer; 149 150audio.createAudioRenderer(audioRendererOptions).then((data) => { 151 audioRenderer = data; 152 console.info('AudioFrameworkRenderLog: AudioRenderer Created : Success : Stream Type: SUCCESS'); 153}).catch((err: BusinessError) => { 154 console.error(`AudioFrameworkRenderLog: AudioRenderer Created : ERROR : ${err}`); 155}); 156``` 157 158## audio.createAudioCapturer<sup>8+</sup> 159 160createAudioCapturer(options: AudioCapturerOptions, callback: AsyncCallback<AudioCapturer\>): void 161 162Creates an **AudioCapturer** instance. This API uses an asynchronous callback to return the result. 163 164**System capability**: SystemCapability.Multimedia.Audio.Capturer 165 166**Required permissions**: ohos.permission.MICROPHONE 167 168This permission is required when [SourceType](#sourcetype8) is set to **SOURCE_TYPE_MIC**, **SOURCE_TYPE_VOICE_RECOGNITION**, **SOURCE_TYPE_VOICE_COMMUNICATION**, **SOURCE_TYPE_VOICE_MESSAGE**, or **SOURCE_TYPE_CAMCORDER**. 169 170**Parameters** 171 172| Name | Type | Mandatory| Description | 173| :------- | :---------------------------------------------- | :--- | :--------------- | 174| options | [AudioCapturerOptions](#audiocaptureroptions8) | Yes | Capturer configurations.| 175| callback | AsyncCallback<[AudioCapturer](#audiocapturer8)> | Yes | Callback used to return the result. If the operation is successful, an **AudioCapturer** instance is returned; otherwise, an error object with either of the following error codes is returned:<br>Error code 6800301: indicates a parameter verification exception, permission verification exception, or system processing exception. For details, see system logs.<br>Error code 6800101: indicates that a mandatory parameter is null or the parameter type is incorrect.| 176 177**Example** 178 179```ts 180import { audio } from '@kit.AudioKit'; 181 182let audioStreamInfo: audio.AudioStreamInfo = { 183 samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_48000, 184 channels: audio.AudioChannel.CHANNEL_2, 185 sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, 186 encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW 187}; 188 189let audioCapturerInfo: audio.AudioCapturerInfo = { 190 source: audio.SourceType.SOURCE_TYPE_MIC, 191 capturerFlags: 0 192}; 193 194let audioCapturerOptions: audio.AudioCapturerOptions = { 195 streamInfo: audioStreamInfo, 196 capturerInfo: audioCapturerInfo 197}; 198 199audio.createAudioCapturer(audioCapturerOptions, (err, data) => { 200 if (err) { 201 console.error(`AudioCapturer Created : Error: ${err}`); 202 } else { 203 console.info('AudioCapturer Created : Success : SUCCESS'); 204 let audioCapturer = data; 205 } 206}); 207``` 208 209## audio.createAudioCapturer<sup>8+</sup> 210 211createAudioCapturer(options: AudioCapturerOptions): Promise<AudioCapturer\> 212 213Creates an **AudioCapturer** instance. This API uses a promise to return the result. 214 215**System capability**: SystemCapability.Multimedia.Audio.Capturer 216 217**Required permissions**: ohos.permission.MICROPHONE 218 219This permission is required when [SourceType](#sourcetype8) is set to **SOURCE_TYPE_MIC**, **SOURCE_TYPE_VOICE_RECOGNITION**, **SOURCE_TYPE_VOICE_COMMUNICATION**, **SOURCE_TYPE_VOICE_MESSAGE**, or **SOURCE_TYPE_CAMCORDER**. 220 221**Parameters** 222 223| Name | Type | Mandatory| Description | 224| :------ | :--------------------------------------------- | :--- | :--------------- | 225| options | [AudioCapturerOptions](#audiocaptureroptions8) | Yes | Capturer configurations.| 226 227**Return value** 228 229| Type | Description | 230| ----------------------------------------- |----------------------| 231| Promise<[AudioCapturer](#audiocapturer8)> | Promise used to return the result. If the operation is successful, an **AudioCapturer** instance is returned; otherwise, an error object with either of the following error codes is returned:<br>Error code 6800301: indicates a parameter verification exception, permission verification exception, or system processing exception. For details, see system logs.<br>Error code 6800101: indicates that a mandatory parameter is null or the parameter type is incorrect.| 232 233**Example** 234 235```ts 236import { audio } from '@kit.AudioKit'; 237import { BusinessError } from '@kit.BasicServicesKit'; 238 239let audioStreamInfo: audio.AudioStreamInfo = { 240 samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_48000, 241 channels: audio.AudioChannel.CHANNEL_2, 242 sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, 243 encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW 244}; 245 246let audioCapturerInfo: audio.AudioCapturerInfo = { 247 source: audio.SourceType.SOURCE_TYPE_MIC, 248 capturerFlags: 0 249}; 250 251let audioCapturerOptions:audio.AudioCapturerOptions = { 252 streamInfo: audioStreamInfo, 253 capturerInfo: audioCapturerInfo 254}; 255 256let audioCapturer: audio.AudioCapturer; 257 258audio.createAudioCapturer(audioCapturerOptions).then((data) => { 259 audioCapturer = data; 260 console.info('AudioCapturer Created : Success : Stream Type: SUCCESS'); 261}).catch((err: BusinessError) => { 262 console.error(`AudioCapturer Created : ERROR : ${err}`); 263}); 264``` 265 266## AudioVolumeType 267 268Enumerates the audio stream types. 269 270**System capability**: SystemCapability.Multimedia.Audio.Volume 271 272| Name | Value | Description | 273| ---------------------------- | ------ | ---------- | 274| VOICE_CALL<sup>8+</sup> | 0 | Audio stream for voice calls.| 275| RINGTONE | 2 | Audio stream for ringtones. | 276| MEDIA | 3 | Audio stream for media purpose. | 277| ALARM<sup>10+</sup> | 4 | Audio stream for alarming. | 278| ACCESSIBILITY<sup>10+</sup> | 5 | Audio stream for accessibility. | 279| VOICE_ASSISTANT<sup>8+</sup> | 9 | Audio stream for voice assistant.| 280 281## InterruptMode<sup>9+</sup> 282 283Enumerates the audio interruption modes. 284 285**Atomic service API**: This API can be used in atomic services since API version 12. 286 287**System capability**: SystemCapability.Multimedia.Audio.Interrupt 288 289| Name | Value | Description | 290| ---------------------------- | ------ | ---------- | 291| SHARE_MODE | 0 | Shared mode.| 292| INDEPENDENT_MODE | 1 | Independent mode.| 293 294## DeviceFlag 295 296Enumerates the audio device flags. 297 298**System capability**: SystemCapability.Multimedia.Audio.Device 299 300| Name | Value | Description | 301| ------------------------------- | ------ |---------------------------| 302| OUTPUT_DEVICES_FLAG | 1 | Output device. | 303| INPUT_DEVICES_FLAG | 2 | Input device. | 304| ALL_DEVICES_FLAG | 3 | All devices. | 305 306## DeviceUsage<sup>12+</sup> 307 308Enumerates the usage scenarios of audio devices. 309 310**System capability**: SystemCapability.Multimedia.Audio.Device 311 312| Name | Value | Description | 313| ------------------------------- | ------ |---------------------------| 314| MEDIA_OUTPUT_DEVICES | 1 | Media output device.| 315| MEDIA_INPUT_DEVICES | 2 | Media input device.| 316| ALL_MEDIA_DEVICES | 3 | All media devices.| 317| CALL_OUTPUT_DEVICES | 4 | Call output device.| 318| CALL_INPUT_DEVICES | 8 | Call input device.| 319| ALL_CALL_DEVICES | 12 | All call devices.| 320 321## DeviceRole 322 323Enumerates the audio device roles. 324 325**Atomic service API**: This API can be used in atomic services since API version 12. 326 327**System capability**: SystemCapability.Multimedia.Audio.Device 328 329| Name | Value | Description | 330| ------------- | ------ | -------------- | 331| INPUT_DEVICE | 1 | Input role.| 332| OUTPUT_DEVICE | 2 | Output role.| 333 334## DeviceType 335 336Enumerates the audio device types. 337 338**Atomic service API**: This API can be used in atomic services since API version 12. 339 340**System capability**: SystemCapability.Multimedia.Audio.Device 341 342| Name | Value | Description | 343| ---------------------| ------ | --------------------------------------------------------- | 344| INVALID | 0 | Invalid device. | 345| EARPIECE | 1 | Earpiece. | 346| SPEAKER | 2 | Speaker. | 347| WIRED_HEADSET | 3 | Wired headset with a microphone. | 348| WIRED_HEADPHONES | 4 | Wired headset without microphone. | 349| BLUETOOTH_SCO | 7 | Bluetooth device using Synchronous Connection Oriented (SCO) links. | 350| BLUETOOTH_A2DP | 8 | Bluetooth device using Advanced Audio Distribution Profile (A2DP) links.| 351| MIC | 15 | Microphone. | 352| USB_HEADSET | 22 | USB Type-C headset. | 353| DISPLAY_PORT<sup>12+</sup> | 23 | Display port (DP), which is used to connect to external devices. | 354| REMOTE_CAST<sup>12+</sup> | 24 | Remote cast device. | 355| DEFAULT<sup>9+</sup> | 1000 | Default device type. | 356 357## CommunicationDeviceType<sup>9+</sup> 358 359Enumerates the device types used for communication. 360 361**System capability**: SystemCapability.Multimedia.Audio.Communication 362 363| Name | Value | Description | 364| ------------- | ------ | -------------| 365| SPEAKER | 2 | Speaker. | 366 367## AudioRingMode 368 369Enumerates the ringer modes. 370 371**System capability**: SystemCapability.Multimedia.Audio.Communication 372 373| Name | Value | Description | 374| ------------------- | ------ | ---------- | 375| RINGER_MODE_SILENT | 0 | Silent mode.| 376| RINGER_MODE_VIBRATE | 1 | Vibration mode.| 377| RINGER_MODE_NORMAL | 2 | Normal mode.| 378 379## AudioSampleFormat<sup>8+</sup> 380 381Enumerates the audio sample formats. 382 383**System capability**: SystemCapability.Multimedia.Audio.Core 384 385| Name | Value | Description | 386| ---------------------------------- | ------ | -------------------------- | 387| SAMPLE_FORMAT_INVALID | -1 | Invalid format. | 388| SAMPLE_FORMAT_U8 | 0 | Unsigned 8-bit integer. | 389| SAMPLE_FORMAT_S16LE | 1 | Signed 16-bit integer, little endian.| 390| SAMPLE_FORMAT_S24LE | 2 | Signed 24-bit integer, little endian.<br>Due to system restrictions, only some devices support this sampling format.| 391| SAMPLE_FORMAT_S32LE | 3 | Signed 32-bit integer, little endian.<br>Due to system restrictions, only some devices support this sampling format.| 392| SAMPLE_FORMAT_F32LE<sup>9+</sup> | 4 | Signed 32-bit floating point number, little endian.<br>Due to system restrictions, only some devices support this sampling format.| 393 394## AudioErrors<sup>9+</sup> 395 396Enumerates the audio error codes. 397 398**System capability**: SystemCapability.Multimedia.Audio.Core 399 400| Name | Value | Description | 401| ---------------------| --------| ----------------- | 402| ERROR_INVALID_PARAM | 6800101 | Invalid parameter. | 403| ERROR_NO_MEMORY | 6800102 | Memory allocation failure. | 404| ERROR_ILLEGAL_STATE | 6800103 | Unsupported state. | 405| ERROR_UNSUPPORTED | 6800104 | Unsupported parameter value. | 406| ERROR_TIMEOUT | 6800105 | Processing timeout. | 407| ERROR_STREAM_LIMIT | 6800201 | Too many audio streams.| 408| ERROR_SYSTEM | 6800301 | System error. | 409 410## AudioChannel<sup>8+</sup> 411 412Enumerates the audio channels. 413 414**System capability**: SystemCapability.Multimedia.Audio.Core 415 416| Name | Value | Description | 417| --------- | -------- |------| 418| CHANNEL_1 | 1 | One audio channel (mono).| 419| CHANNEL_2 | 2 | Two audio channels (stereo).| 420| CHANNEL_3<sup>11+</sup> | 3 | Three audio channels.| 421| CHANNEL_4<sup>11+</sup> | 4 | Four audio channels.| 422| CHANNEL_5<sup>11+</sup> | 5 | Five audio channels.| 423| CHANNEL_6<sup>11+</sup> | 6 | Six audio channels.| 424| CHANNEL_7<sup>11+</sup> | 7 | Seven audio channels.| 425| CHANNEL_8<sup>11+</sup> | 8 | Eight audio channels.| 426| CHANNEL_9<sup>11+</sup> | 9 | Nine audio channels.| 427| CHANNEL_10<sup>11+</sup> | 10 | Ten audio channels.| 428| CHANNEL_12<sup>11+</sup> | 12 | Twelve audio channels.| 429| CHANNEL_14<sup>11+</sup> | 14 | Fourteen audio channels.| 430| CHANNEL_16<sup>11+</sup> | 16 | Sixteen audio channels.| 431 432## AudioSamplingRate<sup>8+</sup> 433 434Enumerates the audio sampling rates. The sampling rates supported vary according to the device in use. 435 436**System capability**: SystemCapability.Multimedia.Audio.Core 437 438| Name | Value | Description | 439| ----------------- | ------ | --------------- | 440| SAMPLE_RATE_8000 | 8000 | The sampling rate is 8000. | 441| SAMPLE_RATE_11025 | 11025 | The sampling rate is 11025.| 442| SAMPLE_RATE_12000 | 12000 | The sampling rate is 12000.| 443| SAMPLE_RATE_16000 | 16000 | The sampling rate is 16000.| 444| SAMPLE_RATE_22050 | 22050 | The sampling rate is 22050.| 445| SAMPLE_RATE_24000 | 24000 | The sampling rate is 24000.| 446| SAMPLE_RATE_32000 | 32000 | The sampling rate is 32000.| 447| SAMPLE_RATE_44100 | 44100 | The sampling rate is 44100.| 448| SAMPLE_RATE_48000 | 48000 | The sampling rate is 48000.| 449| SAMPLE_RATE_64000 | 64000 | The sampling rate is 64000.| 450| SAMPLE_RATE_88200<sup>12+</sup> | 88200 | The sampling rate is 88200.| 451| SAMPLE_RATE_96000 | 96000 | The sampling rate is 96000.| 452| SAMPLE_RATE_176400<sup>12+</sup> | 176400 | The sampling rate is 176400.| 453| SAMPLE_RATE_192000<sup>12+</sup> | 192000 | The sampling rate is 192000.| 454 455## AudioEncodingType<sup>8+</sup> 456 457Enumerates the audio encoding types. 458 459**Atomic service API**: This API can be used in atomic services since API version 12. 460 461**System capability**: SystemCapability.Multimedia.Audio.Core 462 463| Name | Value | Description | 464| --------------------- | ------ | --------- | 465| ENCODING_TYPE_INVALID | -1 | Invalid. | 466| ENCODING_TYPE_RAW | 0 | PCM encoding.| 467 468## AudioChannelLayout<sup>11+</sup> 469 470Enumerates the audio channel layouts. 471 472**System capability**: SystemCapability.Multimedia.Audio.Core 473 474| Name | Value | Description | 475| ------------------------------ | ---------------- | --------------------------------------------- | 476| CH_LAYOUT_UNKNOWN | 0x0 | Unknown. | 477| CH_LAYOUT_MONO | 0x4 | Mono. | 478| CH_LAYOUT_STEREO | 0x3 | Stereo. | 479| CH_LAYOUT_STEREO_DOWNMIX | 0x60000000 | Stereo downmix. | 480| CH_LAYOUT_2POINT1 | 0xB | 2.1. | 481| CH_LAYOUT_3POINT0 | 0x103 | 3.0. | 482| CH_LAYOUT_SURROUND | 0x7 | Surround. | 483| CH_LAYOUT_3POINT1 | 0xF | 3.1. | 484| CH_LAYOUT_4POINT0 | 0x107 | 4.0. | 485| CH_LAYOUT_QUAD | 0x33 | Quad. | 486| CH_LAYOUT_QUAD_SIDE | 0x603 | Quad side. | 487| CH_LAYOUT_2POINT0POINT2 | 0x3000000003 | 2.0.2. | 488| CH_LAYOUT_AMB_ORDER1_ACN_N3D | 0x100000000001 | First-order FOA file in ACN_N3D (ITU standards). | 489| CH_LAYOUT_AMB_ORDER1_ACN_SN3D | 0x100000001001 | First-order FOA file in ACN_SN3D (ITU standards).| 490| CH_LAYOUT_AMB_ORDER1_FUMA | 0x100000000101 | First-order FOA file in FUMA (ITU standards). | 491| CH_LAYOUT_4POINT1 | 0x10F | 4.1. | 492| CH_LAYOUT_5POINT0 | 0x607 | 5.0. | 493| CH_LAYOUT_5POINT0_BACK | 0x37 | 5.0 back. | 494| CH_LAYOUT_2POINT1POINT2 | 0x300000000B | 2.1.2. | 495| CH_LAYOUT_3POINT0POINT2 | 0x3000000007 | 3.0.2. | 496| CH_LAYOUT_5POINT1 | 0x60F | 5.1. | 497| CH_LAYOUT_5POINT1_BACK | 0x3F | 5.1 back. | 498| CH_LAYOUT_6POINT0 | 0x707 | 6.0. | 499| CH_LAYOUT_HEXAGONAL | 0x137 | Hexagonal. | 500| CH_LAYOUT_3POINT1POINT2 | 0x500F | 3.1.2. | 501| CH_LAYOUT_6POINT0_FRONT | 0x6C3 | 6.0 front. | 502| CH_LAYOUT_6POINT1 | 0x70F | 6.1. | 503| CH_LAYOUT_6POINT1_BACK | 0x13F | 6.1 back. | 504| CH_LAYOUT_6POINT1_FRONT | 0x6CB | 6.1 front. | 505| CH_LAYOUT_7POINT0 | 0x637 | 7.0. | 506| CH_LAYOUT_7POINT0_FRONT | 0x6C7 | 7.0 front. | 507| CH_LAYOUT_7POINT1 | 0x63F | 7.1. | 508| CH_LAYOUT_OCTAGONAL | 0x737 | Octagonal. | 509| CH_LAYOUT_5POINT1POINT2 | 0x300000060F | 5.1.2. | 510| CH_LAYOUT_7POINT1_WIDE | 0x6CF | 7.1 wide. | 511| CH_LAYOUT_7POINT1_WIDE_BACK | 0xFF | 7.1 wide back. | 512| CH_LAYOUT_AMB_ORDER2_ACN_N3D | 0x100000000002 | Second-order HOA file in ACN_N3D (ITU standards). | 513| CH_LAYOUT_AMB_ORDER2_ACN_SN3D | 0x100000001002 | Second-order HOA file in ACN_SN3D (ITU standards).| 514| CH_LAYOUT_AMB_ORDER2_FUMA | 0x100000000102 | Second-order HOA file in FUMA (ITU standards). | 515| CH_LAYOUT_5POINT1POINT4 | 0x2D60F | 5.1.4. | 516| CH_LAYOUT_7POINT1POINT2 | 0x300000063F | 7.1.2. | 517| CH_LAYOUT_7POINT1POINT4 | 0x2D63F | 7.1.4. | 518| CH_LAYOUT_10POINT2 | 0x180005737 | 10.2. | 519| CH_LAYOUT_9POINT1POINT4 | 0x18002D63F | 9.1.4. | 520| CH_LAYOUT_9POINT1POINT6 | 0x318002D63F | 9.1.6. | 521| CH_LAYOUT_HEXADECAGONAL | 0x18003F737 | Hexadecagonal. | 522| CH_LAYOUT_AMB_ORDER3_ACN_N3D | 0x100000000003 | Third-order HOA file in ACN_N3D (ITU standards). | 523| CH_LAYOUT_AMB_ORDER3_ACN_SN3D | 0x100000001003 | Third-order HOA file in ACN_SN3D (ITU standards).| 524| CH_LAYOUT_AMB_ORDER3_FUMA | 0x100000000103 | Third-order HOA file in FUMA (ITU standards). | 525 526## ContentType<sup>(deprecated)</sup> 527 528Enumerates the audio content types. 529 530> **NOTE** 531> This API is supported since API version 7 and deprecated since API version 10. You are advised to use [StreamUsage](#streamusage) to declare the audio stream type. 532 533**System capability**: SystemCapability.Multimedia.Audio.Core 534 535| Name | Value | Description | 536| ---------------------------------- | ------ | ---------- | 537| CONTENT_TYPE_UNKNOWN | 0 | Unknown content.| 538| CONTENT_TYPE_SPEECH | 1 | Speech. | 539| CONTENT_TYPE_MUSIC | 2 | Music. | 540| CONTENT_TYPE_MOVIE | 3 | Movie. | 541| CONTENT_TYPE_SONIFICATION | 4 | Notification tone. | 542| CONTENT_TYPE_RINGTONE<sup>8+</sup> | 5 | Ringtone. | 543 544## StreamUsage 545 546Enumerates the audio stream usage. 547 548**System capability**: SystemCapability.Multimedia.Audio.Core 549 550| Name | Value | Description | 551| ------------------------------------------| ------ |---------------------------------------------------------------------------------------------------------------------------------------------| 552| STREAM_USAGE_UNKNOWN | 0 | Unknown content.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 553| STREAM_USAGE_MEDIA<sup>(deprecated)</sup> | 1 | Media.<br> This enumerated value is supported since API version 7 and deprecated since API version 10. You are advised to use **STREAM_USAGE_MUSIC**, **STREAM_USAGE_MOVIE**, **STREAM_USAGE_GAME**, or **STREAM_USAGE_AUDIOBOOK** instead.| 554| STREAM_USAGE_MUSIC<sup>10+</sup> | 1 | Music.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 555| STREAM_USAGE_VOICE_COMMUNICATION | 2 | VoIP voice call.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 556| STREAM_USAGE_VOICE_ASSISTANT<sup>9+</sup> | 3 | Voice assistant.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 557| STREAM_USAGE_ALARM<sup>10+</sup> | 4 | Audio stream for alarming.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 558| STREAM_USAGE_VOICE_MESSAGE<sup>10+</sup> | 5 | Voice message.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 559| STREAM_USAGE_NOTIFICATION_RINGTONE<sup>(deprecated)</sup> | 6 | Notification tone.<br> This enumerated value is deprecated since API version 10. You are advised to use **STREAM_USAGE_RINGTONE** instead. | 560| STREAM_USAGE_RINGTONE<sup>10+</sup> | 6 | Ringtone.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 561| STREAM_USAGE_NOTIFICATION<sup>10+</sup> | 7 | Notification.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 562| STREAM_USAGE_ACCESSIBILITY<sup>10+</sup> | 8 | Accessibility.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 563| STREAM_USAGE_MOVIE<sup>10+</sup> | 10 | Movie or video.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 564| STREAM_USAGE_GAME<sup>10+</sup> | 11 | Gaming.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 565| STREAM_USAGE_AUDIOBOOK<sup>10+</sup> | 12 | Audiobooks (including crosstalks and storytelling), news radio, and podcasts.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 566| STREAM_USAGE_NAVIGATION<sup>10+</sup> | 13 | Navigation.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 567| STREAM_USAGE_VIDEO_COMMUNICATION<sup>12+</sup> | 17 | VoIP video call.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 568 569## AudioState<sup>8+</sup> 570 571Enumerates the audio states. 572 573**System capability**: SystemCapability.Multimedia.Audio.Core 574 575| Name | Value | Description | 576| -------------- | ------ | ---------------- | 577| STATE_INVALID | -1 | Invalid state. | 578| STATE_NEW | 0 | Creating instance state.| 579| STATE_PREPARED | 1 | Prepared. | 580| STATE_RUNNING | 2 | Running.| 581| STATE_STOPPED | 3 | Stopped. | 582| STATE_RELEASED | 4 | Released. | 583| STATE_PAUSED | 5 | Paused. | 584 585## AudioEffectMode<sup>10+</sup> 586 587Enumerates the audio effect modes. 588 589**Atomic service API**: This API can be used in atomic services since API version 12. 590 591**System capability**: SystemCapability.Multimedia.Audio.Renderer 592 593| Name | Value | Description | 594| ------------------ | ------ | ---------- | 595| EFFECT_NONE | 0 | The audio effect is disabled.| 596| EFFECT_DEFAULT | 1 | The default audio effect is used.| 597 598## AudioRendererRate<sup>8+</sup> 599 600Enumerates the audio renderer rates. 601 602**System capability**: SystemCapability.Multimedia.Audio.Renderer 603 604| Name | Value | Description | 605| ------------------ | ------ | ---------- | 606| RENDER_RATE_NORMAL | 0 | Normal rate.| 607| RENDER_RATE_DOUBLE | 1 | Double rate. | 608| RENDER_RATE_HALF | 2 | Half rate. | 609 610## InterruptType 611 612Enumerates the audio interruption types. 613 614**Atomic service API**: This API can be used in atomic services since API version 12. 615 616**System capability**: SystemCapability.Multimedia.Audio.Renderer 617 618| Name | Value | Description | 619| -------------------- | ------ | ---------------------- | 620| INTERRUPT_TYPE_BEGIN | 1 | Audio interruption started.| 621| INTERRUPT_TYPE_END | 2 | Audio interruption ended.| 622 623## InterruptForceType<sup>9+</sup> 624 625Enumerates the types of force that causes audio interruption. 626 627The force type is obtained when an [InterruptEvent](#interruptevent9) is received. 628 629This type specifies whether the audio interruption operation is forcibly performed by the system. The operation information (such as audio pause or stop) can be obtained through [InterruptHint](#interrupthint). For details about the audio interruption strategy, see [Handling Audio Focus Changes](../../media/audio/audio-playback-concurrency.md). 630 631**Atomic service API**: This API can be used in atomic services since API version 12. 632 633**System capability**: SystemCapability.Multimedia.Audio.Renderer 634 635| Name | Value | Description | 636| --------------- | ------ | ------------------------------------ | 637| INTERRUPT_FORCE | 0 | The operation is forcibly performed by the system. | 638| INTERRUPT_SHARE | 1 | The operation will not be performed by the system. [InterruptHint](#interrupthint) is used to provide recommended operations for the application, and the application can determine the next processing mode.| 639 640## InterruptHint 641 642Enumerates the hints provided along with audio interruption. 643 644The hint is obtained when an [InterruptEvent](#interruptevent9) is received. 645 646The hint specifies the operation (such as audio pause or volume adjustment) to be performed on audio streams based on the focus policy. 647 648You can determine whether the operation is forcibly performed by the system based on [InterruptForceType](#interruptforcetype9) in **InterruptEvent**. For details about the audio interruption strategy, see [Handling Audio Focus Changes](../../media/audio/audio-playback-concurrency.md). 649 650**Atomic service API**: This API can be used in atomic services since API version 12. 651 652**System capability**: SystemCapability.Multimedia.Audio.Renderer 653 654| Name | Value | Description | 655| ---------------------------------- | ------ | -------------------------------------------- | 656| INTERRUPT_HINT_NONE<sup>8+</sup> | 0 | None. | 657| INTERRUPT_HINT_RESUME | 1 | A hint is displayed, indicating that the audio stream is restored. The application can proactively trigger operations related to rendering or recording.<br>This operation cannot be forcibly performed by the system, and the corresponding [InterruptForceType](#interruptforcetype9) must be **INTERRUPT_SHARE**.| 658| INTERRUPT_HINT_PAUSE | 2 | A hint is displayed, indicating that the audio stream is paused and the audio focus is lost temporarily.<br>The **INTERRUPT_HINT_RESUME** event will be triggered when the focus is gained. | 659| INTERRUPT_HINT_STOP | 3 | A hint is displayed, indicating that the audio stream stops and the audio focus is lost. | 660| INTERRUPT_HINT_DUCK | 4 | A hint is displayed, indicating that audio ducking starts and the audio is played at a lower volume.| 661| INTERRUPT_HINT_UNDUCK<sup>8+</sup> | 5 | A hint is displayed, indicating that audio ducking ends and the audio is played at the normal volume. | 662 663## AudioStreamInfo<sup>8+</sup> 664 665Describes audio stream information. 666 667**System capability**: SystemCapability.Multimedia.Audio.Core 668 669| Name | Type | Mandatory| Description | 670| ------------ | ------------------------------------------------- | ---- | ------------------ | 671| samplingRate | [AudioSamplingRate](#audiosamplingrate8) | Yes | Audio sampling rate.| 672| channels | [AudioChannel](#audiochannel8) | Yes | Number of audio channels.| 673| sampleFormat | [AudioSampleFormat](#audiosampleformat8) | Yes | Audio sample format. | 674| encodingType | [AudioEncodingType](#audioencodingtype8) | Yes | Audio encoding type. | 675| channelLayout<sup>11+</sup> | [AudioChannelLayout](#audiochannellayout11) | No | Audio channel layout. The default value is **0x0**.| 676 677## AudioRendererInfo<sup>8+</sup> 678 679Describes audio renderer information. 680 681**System capability**: SystemCapability.Multimedia.Audio.Core 682 683| Name | Type | Mandatory | Description | 684| ------------- | --------------------------- | ---- | ---------------- | 685| content | [ContentType](#contenttypedeprecated) | No | Audio content type.<br>This parameter is mandatory in API versions 8 and 9 and optional since API version 10. The default value is **CONTENT_TYPE_UNKNOWN**. [ContentType](#contenttypedeprecated) is deprecated. You are advised to use [StreamUsage](#streamusage) to declare the audio stream type.| 686| usage | [StreamUsage](#streamusage) | Yes | Audio stream usage.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 687| rendererFlags | number | Yes | Audio renderer flags.<br>The value **0** means an audio renderer.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 688 689## AudioRendererOptions<sup>8+</sup> 690 691Describes audio renderer configurations. 692 693| Name | Type | Mandatory | Description | 694| ------------ | ---------------------------------------- | ---- | ---------------- | 695| streamInfo | [AudioStreamInfo](#audiostreaminfo8) | Yes | Audio stream information.<br>**System capability**: SystemCapability.Multimedia.Audio.Renderer| 696| rendererInfo | [AudioRendererInfo](#audiorendererinfo8) | Yes | Audio renderer information.<br>**System capability**: SystemCapability.Multimedia.Audio.Renderer| 697| privacyType<sup>10+</sup> | [AudioPrivacyType](#audioprivacytype10) | No| Whether the audio stream can be recorded by other applications. The default value is **0**.<br>**System capability**: SystemCapability.Multimedia.Audio.PlaybackCapture| 698 699## AudioPrivacyType<sup>10+</sup> 700 701Enumerates whether an audio stream can be recorded by other applications. 702 703**System capability**: SystemCapability.Multimedia.Audio.PlaybackCapture 704 705| Name | Value | Description | 706| -------------------- | ---- | -------------------------------- | 707| PRIVACY_TYPE_PUBLIC | 0 | The audio stream can be recorded by other applications. | 708| PRIVACY_TYPE_PRIVATE | 1 | The audio stream cannot be recorded by other applications.| 709 710## InterruptEvent<sup>9+</sup> 711 712Describes the interruption event received by the application when playback is interrupted. 713 714**Atomic service API**: This API can be used in atomic services since API version 12. 715 716**System capability**: SystemCapability.Multimedia.Audio.Renderer 717 718| Name | Type |Mandatory | Description | 719| --------- | ------------------------------------------ | ---- | ------------------------------------ | 720| eventType | [InterruptType](#interrupttype) | Yes | Whether the interruption has started or ended. | 721| forceType | [InterruptForceType](#interruptforcetype9) | Yes | Whether the interruption is taken by the system or to be taken by the application.| 722| hintType | [InterruptHint](#interrupthint) | Yes | Hint provided along the interruption. | 723 724## VolumeEvent<sup>9+</sup> 725 726Describes the event received by the application when the volume is changed. 727 728**System capability**: SystemCapability.Multimedia.Audio.Volume 729 730| Name | Type | Mandatory | Description | 731| ---------- | ----------------------------------- | ---- |-------------------------------------------| 732| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 733| volume | number | Yes | Volume to set. The value range can be obtained by calling **getMinVolume** and **getMaxVolume**. | 734| updateUi | boolean | Yes | Whether the volume change is shown on the UI. The value **true** means that the volume change is shown, and **false** means the opposite. | 735 736## MicStateChangeEvent<sup>9+</sup> 737 738Describes the event received by the application when the microphone mute status is changed. 739 740**System capability**: SystemCapability.Multimedia.Audio.Device 741 742| Name | Type | Mandatory| Description | 743| ---------- | ----------------------------------- | ---- |-------------------------------------------------------- | 744| mute | boolean | Yes | Mute status of the microphone. The value **true** means that the microphone is muted, and **false** means the opposite. | 745 746## DeviceChangeAction 747 748Describes the device connection status and device information. 749 750**System capability**: SystemCapability.Multimedia.Audio.Device 751 752| Name | Type | Mandatory| Description | 753| :---------------- | :------------------------------------------------ | :--- | :----------------- | 754| type | [DeviceChangeType](#devicechangetype) | Yes | Device connection status.| 755| deviceDescriptors | [AudioDeviceDescriptors](#audiodevicedescriptors) | Yes | Device information. | 756 757## DeviceBlockStatusInfo<sup>13+</sup> 758 759Describes the audio device blocked status and device information. 760 761**System capability**: SystemCapability.Multimedia.Audio.Device 762 763| Name | Type | Mandatory| Description | 764| :---------------- | :------------------------------------------------ | :--- | :----------------- | 765| blockStatus | [DeviceBlockStatus](#deviceblockstatus13) | Yes | Blocked status of the audio device.| 766| devices | [AudioDeviceDescriptors](#audiodevicedescriptors) | Yes | Device information. | 767 768## ChannelBlendMode<sup>11+</sup> 769 770Enumerates the audio channel blending modes. 771 772**System capability**: SystemCapability.Multimedia.Audio.Core 773 774| Name | Value | Description | 775| :------------------------------------------- | :----- | :--------------------- | 776| MODE_DEFAULT | 0 | The audio channels are not blended. | 777| MODE_BLEND_LR | 1 | The left and right audio channels are blended.| 778| MODE_ALL_LEFT | 2 | The left channel is replicated into the right channel. | 779| MODE_ALL_RIGHT | 3 | The right channel is replicated into the left channel.| 780 781## AudioStreamDeviceChangeReason<sup>11+</sup> 782 783Enumerates the reasons for audio stream device is changed. 784 785**Atomic service API**: This API can be used in atomic services since API version 12. 786 787**System capability**: SystemCapability.Multimedia.Audio.Device 788 789| Name | Value | Description | 790|:------------------------------------------| :----- |:----------------| 791| REASON_UNKNOWN | 0 | Unknown reason. | 792| REASON_NEW_DEVICE_AVAILABLE | 1 | A new device is available. | 793| REASON_OLD_DEVICE_UNAVAILABLE | 2 | The old device is unavailable. When this reason is reported, the application should consider pausing audio playback.| 794| REASON_OVERRODE | 3 | Forcibly selected.| 795 796## AudioStreamDeviceChangeInfo<sup>11+</sup> 797 798Describes the event received by the application when the audio stream device is changed. 799 800**Atomic service API**: This API can be used in atomic services since API version 12. 801 802**System capability**: SystemCapability.Multimedia.Audio.Device 803 804| Name | Type | Mandatory| Description | 805| :---------------- |:------------------------------------------------------------------| :--- | :----------------- | 806| devices | [AudioDeviceDescriptors](#audiodevicedescriptors) | Yes | Device information.| 807| changeReason | [AudioStreamDeviceChangeReason](#audiostreamdevicechangereason11) | Yes | Reason for the change.| 808 809## DeviceChangeType 810 811Enumerates the device connection statuses. 812 813**System capability**: SystemCapability.Multimedia.Audio.Device 814 815| Name | Value | Description | 816| :--------- | :--- | :------------- | 817| CONNECT | 0 | Connected. | 818| DISCONNECT | 1 | Disconnected.| 819 820## DeviceBlockStatus<sup>13+</sup> 821 822Enumerates the blocked statuses of audio devices. 823 824**System capability**: SystemCapability.Multimedia.Audio.Device 825 826| Name | Value | Description | 827| :--------- | :--- | :------------- | 828| UNBLOCKED | 0 | The audio device is not blocked. | 829| BLOCKED | 1 | The audio device is blocked.| 830 831## AudioCapturerOptions<sup>8+</sup> 832 833Describes audio capturer configurations. 834 835| Name | Type | Mandatory| Description | 836| ----------------------------------- | --------------------------------------------------------- | ---- | ------------------------------------------------------------ | 837| streamInfo | [AudioStreamInfo](#audiostreaminfo8) | Yes | Audio stream information.<br>**System capability**: SystemCapability.Multimedia.Audio.Capturer | 838| capturerInfo | [AudioCapturerInfo](#audiocapturerinfo8) | Yes | Audio capturer information.<br>**System capability**: SystemCapability.Multimedia.Audio.Capturer | 839| playbackCaptureConfig<sup>(deprecated)</sup> | [AudioPlaybackCaptureConfig](#audioplaybackcaptureconfigdeprecated) | No | Configuration of internal audio recording.<br>**System capability**: SystemCapability.Multimedia.Audio.PlaybackCapture<br> This API is supported since API version 10 and deprecated since API version 12. The Audio module does not provide APIs for internal recording. You can use [AVScreenCapture](../apis-media-kit/_a_v_screen_capture.md) to perform internal recording.| 840 841## AudioCapturerInfo<sup>8+</sup> 842 843Describes audio capturer information. 844 845**System capability**: SystemCapability.Multimedia.Audio.Core 846 847| Name | Type | Mandatory| Description | 848| :------------ | :------------------------ | :--- | :--------------- | 849| source | [SourceType](#sourcetype8) | Yes | Audio source type. | 850| capturerFlags | number | Yes | Audio capturer flags.<br>The value **0** means an audio capturer.| 851 852## SourceType<sup>8+</sup> 853 854Enumerates the audio source types. 855 856| Name | Value | Description | 857| :------------------------------------------- | :----- | :--------------------- | 858| SOURCE_TYPE_INVALID | -1 | Invalid audio source.<br>**System capability**: SystemCapability.Multimedia.Audio.Core | 859| SOURCE_TYPE_MIC | 0 | Mic source.<br>**System capability**: SystemCapability.Multimedia.Audio.Core| 860| SOURCE_TYPE_VOICE_RECOGNITION<sup>9+</sup> | 1 | Voice recognition source.<br>**System capability**: SystemCapability.Multimedia.Audio.Core | 861| SOURCE_TYPE_PLAYBACK_CAPTURE<sup>(deprecated)</sup> | 2 | Internal audio recording source.<br>**System capability**: SystemCapability.Multimedia.Audio.PlaybackCapture<br> This API is supported since API version 10 and deprecated since API version 12. The Audio module does not provide APIs for internal recording. You can use [AVScreenCapture](../apis-media-kit/_a_v_screen_capture.md) to perform internal recording.| 862| SOURCE_TYPE_VOICE_COMMUNICATION | 7 | Voice communication source.<br>**System capability**: SystemCapability.Multimedia.Audio.Core| 863| SOURCE_TYPE_VOICE_MESSAGE<sup>12+</sup> | 10 | Voice message source.<br>**System capability**: SystemCapability.Multimedia.Audio.Core| 864| SOURCE_TYPE_CAMCORDER<sup>13+</sup> | 13 | Video recording source.<br>**System capability**: SystemCapability.Multimedia.Audio.Core| 865 866## AudioPlaybackCaptureConfig<sup>(deprecated)</sup> 867 868Defines the configuration of internal audio recording. 869 870> **NOTE** 871> 872> This API is supported since API version 10 and deprecated since API version 12. The Audio module does not provide APIs for internal recording. You can use [AVScreenCapture](../apis-media-kit/_a_v_screen_capture.md) to perform internal recording. 873 874**System capability**: SystemCapability.Multimedia.Audio.PlaybackCapture 875 876| Name | Type | Mandatory| Description | 877| ------------- | --------------------------------------------- | ---- | -------------------------------- | 878| filterOptions | [CaptureFilterOptions](#capturefilteroptionsdeprecated) | Yes | Options for filtering the played audio streams to be recorded.| 879 880## CaptureFilterOptions<sup>(deprecated)</sup> 881 882Defines the options for filtering the played audio streams to be recorded. 883 884> **NOTE** 885> 886> This API is supported since API version 10 and deprecated since API version 12. The Audio module does not provide APIs for internal recording. You can use [AVScreenCapture](../apis-media-kit/_a_v_screen_capture.md) to perform internal recording. 887 888**Required permissions**: ohos.permission.CAPTURE_VOICE_DOWNLINK_AUDIO 889 890- In API version 10, **CaptureFilterOptions** supports **StreamUsage.STREAM_USAGE_VOICE_COMMUNICATION**, and therefore the **ohos.permission.CAPTURE_VOICE_DOWNLINK_AUDIO** permission is required. Only system applications can request this permission. 891 892- Since API version 11, **CaptureFilterOptions** does not support **StreamUsage.STREAM_USAGE_VOICE_COMMUNICATION**. Therefore, no permission is required for calling this API. 893 894**System capability**: SystemCapability.Multimedia.Audio.PlaybackCapture 895 896| Name | Type | Mandatory| Description | 897| ------ | ---------------------------------- | ---- | ------------------------------------------------------------ | 898| usages | Array<[StreamUsage](#streamusage)> | Yes | **StreamUsage** of the audio stream to be recorded. You can specify zero or more stream usages. If the array is empty, the audio stream for which **StreamUsage** is **STREAM_USAGE_MUSIC**, **STREAM_USAGE_MOVIE**, **STREAM_USAGE_GAME**, or **STREAM_USAGE_AUDIOBOOK** is recorded by default.| 899 900## AudioScene<sup>8+</sup> 901 902Enumerates the audio scenes. 903 904**System capability**: SystemCapability.Multimedia.Audio.Communication 905 906| Name | Value | Description | 907| :--------------------- | :----- | :-------------------------------------------- | 908| AUDIO_SCENE_DEFAULT | 0 | Default audio scene. | 909| AUDIO_SCENE_RINGING<sup>12+</sup> | 1 | Normal mode.| 910| AUDIO_SCENE_PHONE_CALL<sup>12+</sup> | 2 | Phone call scene.| 911| AUDIO_SCENE_VOICE_CHAT | 3 | Voice chat scene. | 912 913## AudioConcurrencyMode<sup>12+</sup> 914 915Enumerates the audio concurrency modes. 916 917**System capability**: SystemCapability.Multimedia.Audio.Core 918 919| Name | Value| Description | 920| :--------------------- |:--|:--------| 921| CONCURRENCY_DEFAULT | 0 | Uses the system strategy by default. | 922| CONCURRENCY_MIX_WITH_OTHERS | 1 | Mixes with other audio streams. | 923| CONCURRENCY_DUCK_OTHERS | 2 | Ducks other audio streams.| 924| CONCURRENCY_PAUSE_OTHERS | 3 | Pauses other audio streams.| 925 926## AudioSessionDeactivatedReason<sup>12+</sup> 927 928Enumerates the reasons for deactivating an audio session. 929 930**System capability**: SystemCapability.Multimedia.Audio.Core 931 932| Name | Value| Description | 933| :--------------------- |:--|:-------| 934| DEACTIVATED_LOWER_PRIORITY | 0 | The application focus is preempted.| 935| DEACTIVATED_TIMEOUT | 1 | The audio session times out. | 936 937## AudioSessionStrategy<sup>12+</sup> 938 939Describes an audio session strategy. 940 941**System capability**: SystemCapability.Multimedia.Audio.Core 942 943| Name | Type | Mandatory| Description | 944| :------------ |:------------------------------------------------| :--- | :--------------- | 945| concurrencyMode | [AudioConcurrencyMode](#audioconcurrencymode12) | Yes | Audio concurrency mode. | 946 947## AudioSessionDeactivatedEvent<sup>12+</sup> 948 949Describes the event indicating that an audio session is deactivated. 950 951**System capability**: SystemCapability.Multimedia.Audio.Core 952 953| Name | Type | Mandatory| Description | 954| :------------ |:------------------------------------------------------------------| :--- | :--------------- | 955| reason | [AudioSessionDeactivatedReason](#audiosessiondeactivatedreason12) | Yes | Reason for deactivating an audio session. | 956 957## AudioManager 958 959Implements audio volume and audio device management. Before calling any API in **AudioManager**, you must use [getAudioManager](#audiogetaudiomanager) to create an **AudioManager** instance. 960 961### setAudioParameter<sup>(deprecated)</sup> 962 963setAudioParameter(key: string, value: string, callback: AsyncCallback<void>): void 964 965Sets an audio parameter. This API uses an asynchronous callback to return the result. 966 967This API is used to extend the audio configuration based on the hardware capability. The supported audio parameters vary according to the device and are not common parameters. Sample parameters are used in the sample code below. 968 969> **NOTE** 970> 971> This API is supported since API version 7 and deprecated since API version 11. The substitute API is available only for system applications. 972 973**Required permissions**: ohos.permission.MODIFY_AUDIO_SETTINGS 974 975**System capability**: SystemCapability.Multimedia.Audio.Core 976 977**Parameters** 978 979| Name | Type | Mandatory| Description | 980| -------- | ------------------------- | ---- | ------------------------ | 981| key | string | Yes | Key of the audio parameter to set. | 982| value | string | Yes | Value of the audio parameter to set. | 983| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 984 985**Example** 986 987```ts 988import { BusinessError } from '@kit.BasicServicesKit'; 989 990audioManager.setAudioParameter('key_example', 'value_example', (err: BusinessError) => { 991 if (err) { 992 console.error(`Failed to set the audio parameter. ${err}`); 993 return; 994 } 995 console.info('Callback invoked to indicate a successful setting of the audio parameter.'); 996}); 997``` 998 999### setAudioParameter<sup>(deprecated)</sup> 1000 1001setAudioParameter(key: string, value: string): Promise<void> 1002 1003Sets an audio parameter. This API uses a promise to return the result. 1004 1005This API is used to extend the audio configuration based on the hardware capability. The supported audio parameters vary according to the device and are not common parameters. Sample parameters are used in the sample code below. 1006 1007> **NOTE** 1008> 1009> This API is supported since API version 7 and deprecated since API version 11. The substitute API is available only for system applications. 1010 1011**Required permissions**: ohos.permission.MODIFY_AUDIO_SETTINGS 1012 1013**System capability**: SystemCapability.Multimedia.Audio.Core 1014 1015**Parameters** 1016 1017| Name| Type | Mandatory| Description | 1018| ------ | ------ | ---- | ---------------------- | 1019| key | string | Yes | Key of the audio parameter to set.| 1020| value | string | Yes | Value of the audio parameter to set.| 1021 1022**Return value** 1023 1024| Type | Description | 1025| ------------------- | ------------------------------- | 1026| Promise<void> | Promise that returns no value.| 1027 1028**Example** 1029 1030```ts 1031audioManager.setAudioParameter('key_example', 'value_example').then(() => { 1032 console.info('Promise returned to indicate a successful setting of the audio parameter.'); 1033}); 1034``` 1035 1036### getAudioParameter<sup>(deprecated)</sup> 1037 1038getAudioParameter(key: string, callback: AsyncCallback<string>): void 1039 1040Obtains the value of an audio parameter. This API uses an asynchronous callback to return the result. 1041 1042This 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. 1043 1044> **NOTE** 1045> 1046> This API is supported since API version 7 and deprecated since API version 11. The substitute API is available only for system applications. 1047 1048**System capability**: SystemCapability.Multimedia.Audio.Core 1049 1050**Parameters** 1051 1052| Name | Type | Mandatory| Description | 1053| -------- | --------------------------- | ---- | ---------------------------- | 1054| key | string | Yes | Key of the audio parameter whose value is to be obtained. | 1055| callback | AsyncCallback<string> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the audio parameter value obtained; otherwise, **err** is an error object.| 1056 1057**Example** 1058 1059```ts 1060import { BusinessError } from '@kit.BasicServicesKit'; 1061 1062audioManager.getAudioParameter('key_example', (err: BusinessError, value: string) => { 1063 if (err) { 1064 console.error(`Failed to obtain the value of the audio parameter. ${err}`); 1065 return; 1066 } 1067 console.info(`Callback invoked to indicate that the value of the audio parameter is obtained ${value}.`); 1068}); 1069``` 1070 1071### getAudioParameter<sup>(deprecated)</sup> 1072 1073getAudioParameter(key: string): Promise<string> 1074 1075Obtains the value of an audio parameter. This API uses a promise to return the result. 1076 1077This 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. 1078 1079> **NOTE** 1080> 1081> This API is supported since API version 7 and deprecated since API version 11. The substitute API is available only for system applications. 1082 1083**System capability**: SystemCapability.Multimedia.Audio.Core 1084 1085**Parameters** 1086 1087| Name| Type | Mandatory| Description | 1088| ------ | ------ | ---- | ---------------------- | 1089| key | string | Yes | Key of the audio parameter whose value is to be obtained.| 1090 1091**Return value** 1092 1093| Type | Description | 1094| --------------------- | ----------------------------------- | 1095| Promise<string> | Promise used to return the value of the audio parameter.| 1096 1097**Example** 1098 1099```ts 1100audioManager.getAudioParameter('key_example').then((value: string) => { 1101 console.info(`Promise returned to indicate that the value of the audio parameter is obtained ${value}.`); 1102}); 1103``` 1104 1105### getAudioScene<sup>8+</sup> 1106 1107getAudioScene\(callback: AsyncCallback<AudioScene\>\): void 1108 1109Obtains the audio scene. This API uses an asynchronous callback to return the result. 1110 1111**System capability**: SystemCapability.Multimedia.Audio.Communication 1112 1113**Parameters** 1114 1115| Name | Type | Mandatory| Description | 1116| :------- | :-------------------------------------------------- | :--- | :--------------------------- | 1117| callback | AsyncCallback<[AudioScene](#audioscene8)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the audio scene obtained; otherwise, **err** is an error object.| 1118 1119**Example** 1120 1121```ts 1122import { BusinessError } from '@kit.BasicServicesKit'; 1123 1124audioManager.getAudioScene((err: BusinessError, value: audio.AudioScene) => { 1125 if (err) { 1126 console.error(`Failed to obtain the audio scene mode. ${err}`); 1127 return; 1128 } 1129 console.info(`Callback invoked to indicate that the audio scene mode is obtained ${value}.`); 1130}); 1131``` 1132 1133### getAudioScene<sup>8+</sup> 1134 1135getAudioScene\(\): Promise<AudioScene\> 1136 1137Obtains the audio scene. This API uses a promise to return the result. 1138 1139**System capability**: SystemCapability.Multimedia.Audio.Communication 1140 1141**Return value** 1142 1143| Type | Description | 1144| :-------------------------------------------- | :--------------------------- | 1145| Promise<[AudioScene](#audioscene8)> | Promise used to return the audio scene.| 1146 1147**Example** 1148 1149```ts 1150import { BusinessError } from '@kit.BasicServicesKit'; 1151 1152audioManager.getAudioScene().then((value: audio.AudioScene) => { 1153 console.info(`Promise returned to indicate that the audio scene mode is obtained ${value}.`); 1154}).catch ((err: BusinessError) => { 1155 console.error(`Failed to obtain the audio scene mode ${err}`); 1156}); 1157``` 1158 1159### getAudioSceneSync<sup>10+</sup> 1160 1161getAudioSceneSync\(\): AudioScene 1162 1163Obtains the audio scene. This API returns the result synchronously. 1164 1165**System capability**: SystemCapability.Multimedia.Audio.Communication 1166 1167**Return value** 1168 1169| Type | Description | 1170| :-------------------------------------------- | :--------------------------- | 1171| [AudioScene](#audioscene8) | Audio scene.| 1172 1173**Example** 1174 1175```ts 1176import { BusinessError } from '@kit.BasicServicesKit'; 1177 1178try { 1179 let value: audio.AudioScene = audioManager.getAudioSceneSync(); 1180 console.info(`indicate that the audio scene mode is obtained ${value}.`); 1181} catch (err) { 1182 let error = err as BusinessError; 1183 console.error(`Failed to obtain the audio scene mode ${error}`); 1184} 1185``` 1186 1187### getVolumeManager<sup>9+</sup> 1188 1189getVolumeManager(): AudioVolumeManager 1190 1191Obtains an **AudioVolumeManager** instance. 1192 1193**System capability**: SystemCapability.Multimedia.Audio.Volume 1194 1195**Return value** 1196 1197| Type | Description | 1198|-----------------------------------------| ----------------------------- | 1199| [AudioVolumeManager](#audiovolumemanager9) | **AudioVolumeManager** instance.| 1200 1201**Example** 1202 1203```ts 1204import { audio } from '@kit.AudioKit'; 1205 1206let audioVolumeManager: audio.AudioVolumeManager = audioManager.getVolumeManager(); 1207``` 1208 1209### getStreamManager<sup>9+</sup> 1210 1211getStreamManager(): AudioStreamManager 1212 1213Obtains an **AudioStreamManager** instance. 1214 1215**System capability**: SystemCapability.Multimedia.Audio.Core 1216 1217**Return value** 1218 1219| Type | Description | 1220|--------------------------------------------| ----------------------------- | 1221| [AudioStreamManager](#audiostreammanager9) | **AudioStreamManager** instance.| 1222 1223**Example** 1224 1225```ts 1226import { audio } from '@kit.AudioKit'; 1227 1228let audioStreamManager: audio.AudioStreamManager = audioManager.getStreamManager(); 1229``` 1230 1231### getRoutingManager<sup>9+</sup> 1232 1233getRoutingManager(): AudioRoutingManager 1234 1235Obtains an **AudioRoutingManager** instance. 1236 1237**System capability**: SystemCapability.Multimedia.Audio.Device 1238 1239**Return value** 1240 1241| Type | Description | 1242|------------------------------------------| ----------------------------- | 1243| [AudioRoutingManager](#audioroutingmanager9) | **AudioRoutingManager** instance.| 1244 1245**Example** 1246 1247```ts 1248import { audio } from '@kit.AudioKit'; 1249 1250let audioRoutingManager: audio.AudioRoutingManager = audioManager.getRoutingManager(); 1251``` 1252 1253### getSessionManager<sup>12+</sup> 1254 1255getSessionManager(): AudioSessionManager 1256 1257Obtains an **AudioSessionManager** instance. 1258 1259**System capability**: SystemCapability.Multimedia.Audio.Core 1260 1261**Return value** 1262 1263| Type | Description | 1264|----------------------------------------------| ----------------------------- | 1265| [AudioSessionManager](#audiosessionmanager12) | **AudioSessionManager** instance.| 1266 1267**Example** 1268 1269```ts 1270import { audio } from '@kit.AudioKit'; 1271 1272let audioSessionManager: audio.AudioSessionManager = audioManager.getSessionManager(); 1273``` 1274 1275### setVolume<sup>(deprecated)</sup> 1276 1277setVolume(volumeType: AudioVolumeType, volume: number, callback: AsyncCallback<void>): void 1278 1279Sets the volume for a stream. This API uses an asynchronous callback to return the result. 1280 1281> **NOTE** 1282> 1283> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setVolume](#setvolume9) in **AudioVolumeGroupManager**. The substitute API is available only for system applications. 1284 1285**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 1286 1287This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**. 1288 1289**System capability**: SystemCapability.Multimedia.Audio.Volume 1290 1291**Parameters** 1292 1293| Name | Type | Mandatory| Description | 1294| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 1295| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1296| volume | number | Yes | Volume to set. The value range can be obtained by calling [getMinVolume](#getminvolumedeprecated) and [getMaxVolume](#getmaxvolumedeprecated).| 1297| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1298 1299**Example** 1300 1301```ts 1302import { BusinessError } from '@kit.BasicServicesKit'; 1303 1304audioManager.setVolume(audio.AudioVolumeType.MEDIA, 10, (err: BusinessError) => { 1305 if (err) { 1306 console.error(`Failed to set the volume. ${err}`); 1307 return; 1308 } 1309 console.info('Callback invoked to indicate a successful volume setting.'); 1310}); 1311``` 1312 1313### setVolume<sup>(deprecated)</sup> 1314 1315setVolume(volumeType: AudioVolumeType, volume: number): Promise<void> 1316 1317Sets the volume for a stream. This API uses a promise to return the result. 1318 1319> **NOTE** 1320> 1321> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setVolume](#setvolume9) in **AudioVolumeGroupManager**. The substitute API is available only for system applications. 1322 1323**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 1324 1325This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**. 1326 1327**System capability**: SystemCapability.Multimedia.Audio.Volume 1328 1329**Parameters** 1330 1331| Name | Type | Mandatory| Description | 1332| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 1333| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1334| volume | number | Yes | Volume to set. The value range can be obtained by calling [getMinVolume](#getminvolumedeprecated) and [getMaxVolume](#getmaxvolumedeprecated).| 1335 1336**Return value** 1337 1338| Type | Description | 1339| ------------------- | ----------------------------- | 1340| Promise<void> | Promise that returns no value.| 1341 1342**Example** 1343 1344```ts 1345audioManager.setVolume(audio.AudioVolumeType.MEDIA, 10).then(() => { 1346 console.info('Promise returned to indicate a successful volume setting.'); 1347}); 1348``` 1349 1350### getVolume<sup>(deprecated)</sup> 1351 1352getVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 1353 1354Obtains the volume of a stream. This API uses an asynchronous callback to return the result. 1355 1356> **NOTE** 1357> 1358> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getVolume](#getvolume9) in **AudioVolumeGroupManager**. 1359 1360**System capability**: SystemCapability.Multimedia.Audio.Volume 1361 1362**Parameters** 1363 1364| Name | Type | Mandatory| Description | 1365| ---------- | ----------------------------------- | ---- | ------------------ | 1366| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1367| callback | AsyncCallback<number> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the stream volume obtained; otherwise, **err** is an error object. The volume range of a specified stream can be obtained by calling [getMinVolume](#getminvolumedeprecated) and [getMaxVolume](#getmaxvolumedeprecated).| 1368 1369**Example** 1370 1371```ts 1372import { BusinessError } from '@kit.BasicServicesKit'; 1373 1374audioManager.getVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { 1375 if (err) { 1376 console.error(`Failed to obtain the volume. ${err}`); 1377 return; 1378 } 1379 console.info('Callback invoked to indicate that the volume is obtained.'); 1380}); 1381``` 1382 1383### getVolume<sup>(deprecated)</sup> 1384 1385getVolume(volumeType: AudioVolumeType): Promise<number> 1386 1387Obtains the volume of a stream. This API uses a promise to return the result. 1388 1389> **NOTE** 1390> 1391> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getVolume](#getvolume9) in **AudioVolumeGroupManager**. 1392 1393**System capability**: SystemCapability.Multimedia.Audio.Volume 1394 1395**Parameters** 1396 1397| Name | Type | Mandatory| Description | 1398| ---------- | ----------------------------------- | ---- | ------------ | 1399| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 1400 1401**Return value** 1402 1403| Type | Description | 1404| --------------------- | ------------------------- | 1405| Promise<number> | Promise used to return the volume of the stream. The volume range of a specified stream can be obtained by calling [getMinVolume](#getminvolumedeprecated) and [getMaxVolume](#getmaxvolumedeprecated).| 1406 1407**Example** 1408 1409```ts 1410audioManager.getVolume(audio.AudioVolumeType.MEDIA).then((value: number) => { 1411 console.info(`Promise returned to indicate that the volume is obtained ${value} .`); 1412}); 1413``` 1414 1415### getMinVolume<sup>(deprecated)</sup> 1416 1417getMinVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 1418 1419Obtains the minimum volume allowed for a stream. This API uses an asynchronous callback to return the result. 1420 1421> **NOTE** 1422> 1423> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getMinVolume](#getminvolume9) in **AudioVolumeGroupManager**. 1424 1425**System capability**: SystemCapability.Multimedia.Audio.Volume 1426 1427**Parameters** 1428 1429| Name | Type | Mandatory| Description | 1430| ---------- | ----------------------------------- | ---- | ------------------ | 1431| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1432| callback | AsyncCallback<number> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the minimum stream volume obtained; otherwise, **err** is an error object.| 1433 1434**Example** 1435 1436```ts 1437import { BusinessError } from '@kit.BasicServicesKit'; 1438 1439audioManager.getMinVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { 1440 if (err) { 1441 console.error(`Failed to obtain the minimum volume. ${err}`); 1442 return; 1443 } 1444 console.info(`Callback invoked to indicate that the minimum volume is obtained. ${value}`); 1445}); 1446``` 1447 1448### getMinVolume<sup>(deprecated)</sup> 1449 1450getMinVolume(volumeType: AudioVolumeType): Promise<number> 1451 1452Obtains the minimum volume allowed for a stream. This API uses a promise to return the result. 1453 1454> **NOTE** 1455> 1456> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getMinVolume](#getminvolume9) in **AudioVolumeGroupManager**. 1457 1458**System capability**: SystemCapability.Multimedia.Audio.Volume 1459 1460**Parameters** 1461 1462| Name | Type | Mandatory| Description | 1463| ---------- | ----------------------------------- | ---- | ------------ | 1464| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 1465 1466**Return value** 1467 1468| Type | Description | 1469| --------------------- | ------------------------- | 1470| Promise<number> | Promise used to return the minimum volume.| 1471 1472**Example** 1473 1474```ts 1475audioManager.getMinVolume(audio.AudioVolumeType.MEDIA).then((value: number) => { 1476 console.info(`Promised returned to indicate that the minimum volume is obtained. ${value}`); 1477}); 1478``` 1479 1480### getMaxVolume<sup>(deprecated)</sup> 1481 1482getMaxVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 1483 1484Obtains the maximum volume allowed for a stream. This API uses an asynchronous callback to return the result. 1485 1486> **NOTE** 1487> 1488> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getMaxVolume](#getmaxvolume9) in **AudioVolumeGroupManager**. 1489 1490**System capability**: SystemCapability.Multimedia.Audio.Volume 1491 1492**Parameters** 1493 1494| Name | Type | Mandatory| Description | 1495| ---------- | ----------------------------------- | ---- | ---------------------- | 1496| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1497| callback | AsyncCallback<number> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the maximum stream volume obtained; otherwise, **err** is an error object.| 1498 1499**Example** 1500 1501```ts 1502import { BusinessError } from '@kit.BasicServicesKit'; 1503 1504audioManager.getMaxVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { 1505 if (err) { 1506 console.error(`Failed to obtain the maximum volume. ${err}`); 1507 return; 1508 } 1509 console.info(`Callback invoked to indicate that the maximum volume is obtained. ${value}`); 1510}); 1511``` 1512 1513### getMaxVolume<sup>(deprecated)</sup> 1514 1515getMaxVolume(volumeType: AudioVolumeType): Promise<number> 1516 1517Obtains the maximum volume allowed for a stream. This API uses a promise to return the result. 1518 1519> **NOTE** 1520> 1521> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getMaxVolume](#getmaxvolume9) in **AudioVolumeGroupManager**. 1522 1523**System capability**: SystemCapability.Multimedia.Audio.Volume 1524 1525**Parameters** 1526 1527| Name | Type | Mandatory| Description | 1528| ---------- | ----------------------------------- | ---- | ------------ | 1529| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 1530 1531**Return value** 1532 1533| Type | Description | 1534| --------------------- | ----------------------------- | 1535| Promise<number> | Promise used to return the maximum volume.| 1536 1537**Example** 1538 1539```ts 1540audioManager.getMaxVolume(audio.AudioVolumeType.MEDIA).then((data: number) => { 1541 console.info('Promised returned to indicate that the maximum volume is obtained.'); 1542}); 1543``` 1544 1545### mute<sup>(deprecated)</sup> 1546 1547mute(volumeType: AudioVolumeType, mute: boolean, callback: AsyncCallback<void>): void 1548 1549Mutes or unmutes a stream. This API uses an asynchronous callback to return the result. 1550 1551When the minimum volume of a stream cannot be set to 0 (for example, in the case of alarms or phone calls), muting the stream is not supported. 1552 1553> **NOTE** 1554> 1555> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 1556 1557**System capability**: SystemCapability.Multimedia.Audio.Volume 1558 1559**Parameters** 1560 1561| Name | Type | Mandatory| Description | 1562| ---------- | ----------------------------------- | ---- | ------------------------------------- | 1563| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1564| mute | boolean | Yes | Mute status to set. The value **true** means to mute the stream, and **false** means the opposite.| 1565| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1566 1567**Example** 1568 1569```ts 1570import { BusinessError } from '@kit.BasicServicesKit'; 1571 1572audioManager.mute(audio.AudioVolumeType.MEDIA, true, (err: BusinessError) => { 1573 if (err) { 1574 console.error(`Failed to mute the stream. ${err}`); 1575 return; 1576 } 1577 console.info('Callback invoked to indicate that the stream is muted.'); 1578}); 1579``` 1580 1581### mute<sup>(deprecated)</sup> 1582 1583mute(volumeType: AudioVolumeType, mute: boolean): Promise<void> 1584 1585Mutes or unmutes a stream. This API uses a promise to return the result. 1586 1587When the minimum volume of a stream cannot be set to 0 (for example, in the case of alarms or phone calls), muting the stream is not supported. 1588 1589> **NOTE** 1590> 1591> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 1592 1593**System capability**: SystemCapability.Multimedia.Audio.Volume 1594 1595**Parameters** 1596 1597| Name | Type | Mandatory| Description | 1598| ---------- | ----------------------------------- | ---- | ------------------------------------- | 1599| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1600| mute | boolean | Yes | Mute status to set. The value **true** means to mute the stream, and **false** means the opposite.| 1601 1602**Return value** 1603 1604| Type | Description | 1605| ------------------- | ----------------------------- | 1606| Promise<void> | Promise that returns no value.| 1607 1608**Example** 1609 1610 1611```ts 1612audioManager.mute(audio.AudioVolumeType.MEDIA, true).then(() => { 1613 console.info('Promise returned to indicate that the stream is muted.'); 1614}); 1615``` 1616 1617### isMute<sup>(deprecated)</sup> 1618 1619isMute(volumeType: AudioVolumeType, callback: AsyncCallback<boolean>): void 1620 1621Checks whether a stream is muted. This API uses an asynchronous callback to return the result. 1622 1623> **NOTE** 1624> 1625> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isMute](#ismute9) in **AudioVolumeGroupManager**. 1626 1627**System capability**: SystemCapability.Multimedia.Audio.Volume 1628 1629**Parameters** 1630 1631| Name | Type | Mandatory| Description | 1632| ---------- | ----------------------------------- | ---- | ----------------------------------------------- | 1633| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1634| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true** if the stream is muted or **false** if not muted; otherwise, **err** is an error object.| 1635 1636**Example** 1637 1638```ts 1639import { BusinessError } from '@kit.BasicServicesKit'; 1640 1641audioManager.isMute(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: boolean) => { 1642 if (err) { 1643 console.error(`Failed to obtain the mute status. ${err}`); 1644 return; 1645 } 1646 console.info(`Callback invoked to indicate that the mute status of the stream is obtained. ${value}`); 1647}); 1648``` 1649 1650### isMute<sup>(deprecated)</sup> 1651 1652isMute(volumeType: AudioVolumeType): Promise<boolean> 1653 1654Checks whether a stream is muted. This API uses a promise to return the result. 1655 1656> **NOTE** 1657> 1658> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isMute](#ismute9) in **AudioVolumeGroupManager**. 1659 1660**System capability**: SystemCapability.Multimedia.Audio.Volume 1661 1662**Parameters** 1663 1664| Name | Type | Mandatory| Description | 1665| ---------- | ----------------------------------- | ---- | ------------ | 1666| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 1667 1668**Return value** 1669 1670| Type | Description | 1671| ---------------------- | ------------------------------------------------------ | 1672| 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.| 1673 1674**Example** 1675 1676```ts 1677audioManager.isMute(audio.AudioVolumeType.MEDIA).then((value: boolean) => { 1678 console.info(`Promise returned to indicate that the mute status of the stream is obtained ${value}.`); 1679}); 1680``` 1681 1682### isActive<sup>(deprecated)</sup> 1683 1684isActive(volumeType: AudioVolumeType, callback: AsyncCallback<boolean>): void 1685 1686Checks whether a stream is active. This API uses an asynchronous callback to return the result. 1687 1688> **NOTE** 1689> 1690> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isActive](#isactive9) in **AudioStreamManager**. 1691 1692**System capability**: SystemCapability.Multimedia.Audio.Volume 1693 1694**Parameters** 1695 1696| Name | Type | Mandatory| Description | 1697| ---------- | ----------------------------------- | ---- | ------------------------------------------------- | 1698| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1699| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true** if the stream is active or **false** if not active; otherwise, **err** is an error object.| 1700 1701**Example** 1702 1703```ts 1704import { BusinessError } from '@kit.BasicServicesKit'; 1705 1706audioManager.isActive(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: boolean) => { 1707 if (err) { 1708 console.error(`Failed to obtain the active status of the stream. ${err}`); 1709 return; 1710 } 1711 console.info(`Callback invoked to indicate that the active status of the stream is obtained ${value}.`); 1712}); 1713``` 1714 1715### isActive<sup>(deprecated)</sup> 1716 1717isActive(volumeType: AudioVolumeType): Promise<boolean> 1718 1719Checks whether a stream is active. This API uses a promise to return the result. 1720 1721> **NOTE** 1722> 1723> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isActive](#isactive9) in **AudioStreamManager**. 1724 1725**System capability**: SystemCapability.Multimedia.Audio.Volume 1726 1727**Parameters** 1728 1729| Name | Type | Mandatory| Description | 1730| ---------- | ----------------------------------- | ---- | ------------ | 1731| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 1732 1733**Return value** 1734 1735| Type | Description | 1736| ---------------------- | -------------------------------------------------------- | 1737| 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.| 1738 1739**Example** 1740 1741```ts 1742audioManager.isActive(audio.AudioVolumeType.MEDIA).then((value: boolean) => { 1743 console.info(`Promise returned to indicate that the active status of the stream is obtained ${value}.`); 1744}); 1745``` 1746 1747### setRingerMode<sup>(deprecated)</sup> 1748 1749setRingerMode(mode: AudioRingMode, callback: AsyncCallback<void>): void 1750 1751Sets the ringer mode. This API uses an asynchronous callback to return the result. 1752 1753> **NOTE** 1754> 1755> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 1756 1757**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 1758 1759This permission is required only for muting or unmuting the ringer. 1760 1761**System capability**: SystemCapability.Multimedia.Audio.Communication 1762 1763**Parameters** 1764 1765| Name | Type | Mandatory| Description | 1766| -------- | ------------------------------- | ---- | ------------------------ | 1767| mode | [AudioRingMode](#audioringmode) | Yes | Ringer mode. | 1768| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1769 1770**Example** 1771 1772```ts 1773import { BusinessError } from '@kit.BasicServicesKit'; 1774 1775audioManager.setRingerMode(audio.AudioRingMode.RINGER_MODE_NORMAL, (err: BusinessError) => { 1776 if (err) { 1777 console.error(`Failed to set the ringer mode. ${err}`); 1778 return; 1779 } 1780 console.info('Callback invoked to indicate a successful setting of the ringer mode.'); 1781}); 1782``` 1783 1784### setRingerMode<sup>(deprecated)</sup> 1785 1786setRingerMode(mode: AudioRingMode): Promise<void> 1787 1788Sets the ringer mode. This API uses a promise to return the result. 1789 1790> **NOTE** 1791> 1792> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 1793 1794 1795**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 1796 1797This permission is required only for muting or unmuting the ringer. 1798 1799**System capability**: SystemCapability.Multimedia.Audio.Communication 1800 1801**Parameters** 1802 1803| Name| Type | Mandatory| Description | 1804| ------ | ------------------------------- | ---- | -------------- | 1805| mode | [AudioRingMode](#audioringmode) | Yes | Ringer mode.| 1806 1807**Return value** 1808 1809| Type | Description | 1810| ------------------- | ------------------------------- | 1811| Promise<void> | Promise that returns no value.| 1812 1813**Example** 1814 1815```ts 1816audioManager.setRingerMode(audio.AudioRingMode.RINGER_MODE_NORMAL).then(() => { 1817 console.info('Promise returned to indicate a successful setting of the ringer mode.'); 1818}); 1819``` 1820 1821### getRingerMode<sup>(deprecated)</sup> 1822 1823getRingerMode(callback: AsyncCallback<AudioRingMode>): void 1824 1825Obtains the ringer mode. This API uses an asynchronous callback to return the result. 1826 1827> **NOTE** 1828> 1829> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getRingerMode](#getringermode9) in **AudioVolumeGroupManager**. 1830 1831**System capability**: SystemCapability.Multimedia.Audio.Communication 1832 1833**Parameters** 1834 1835| Name | Type | Mandatory| Description | 1836| -------- | ---------------------------------------------------- | ---- | ------------------------ | 1837| callback | AsyncCallback<[AudioRingMode](#audioringmode)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the ringer mode obtained; otherwise, **err** is an error object.| 1838 1839**Example** 1840 1841```ts 1842import { BusinessError } from '@kit.BasicServicesKit'; 1843 1844audioManager.getRingerMode((err: BusinessError, value: audio.AudioRingMode) => { 1845 if (err) { 1846 console.error(`Failed to obtain the ringer mode. ${err}`); 1847 return; 1848 } 1849 console.info(`Callback invoked to indicate that the ringer mode is obtained ${value}.`); 1850}); 1851``` 1852 1853### getRingerMode<sup>(deprecated)</sup> 1854 1855getRingerMode(): Promise<AudioRingMode> 1856 1857Obtains the ringer mode. This API uses a promise to return the result. 1858 1859> **NOTE** 1860> 1861> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getRingerMode](#getringermode9) in **AudioVolumeGroupManager**. 1862 1863**System capability**: SystemCapability.Multimedia.Audio.Communication 1864 1865**Return value** 1866 1867| Type | Description | 1868| ---------------------------------------------- | ------------------------------- | 1869| Promise<[AudioRingMode](#audioringmode)> | Promise used to return the ringer mode.| 1870 1871**Example** 1872 1873```ts 1874audioManager.getRingerMode().then((value: audio.AudioRingMode) => { 1875 console.info(`Promise returned to indicate that the ringer mode is obtained ${value}.`); 1876}); 1877``` 1878 1879### getDevices<sup>(deprecated)</sup> 1880 1881getDevices(deviceFlag: DeviceFlag, callback: AsyncCallback<AudioDeviceDescriptors>): void 1882 1883Obtains the audio devices with a specific flag. This API uses an asynchronous callback to return the result. 1884 1885> **NOTE** 1886> 1887> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getDevices](#getdevices9) in **AudioRoutingManager**. 1888 1889**System capability**: SystemCapability.Multimedia.Audio.Device 1890 1891**Parameters** 1892 1893| Name | Type | Mandatory| Description | 1894| ---------- | ------------------------------------------------------------ | ---- | -------------------- | 1895| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag. | 1896| callback | AsyncCallback<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the audio devices obtained; otherwise, **err** is an error object.| 1897 1898**Example** 1899```ts 1900import { BusinessError } from '@kit.BasicServicesKit'; 1901 1902audioManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG, (err: BusinessError, value: audio.AudioDeviceDescriptors) => { 1903 if (err) { 1904 console.error(`Failed to obtain the device list. ${err}`); 1905 return; 1906 } 1907 console.info('Callback invoked to indicate that the device list is obtained.'); 1908}); 1909``` 1910 1911### getDevices<sup>(deprecated)</sup> 1912 1913getDevices(deviceFlag: DeviceFlag): Promise<AudioDeviceDescriptors> 1914 1915Obtains the audio devices with a specific flag. This API uses a promise to return the result. 1916 1917> **NOTE** 1918> 1919> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getDevices](#getdevices9) in **AudioRoutingManager**. 1920 1921**System capability**: SystemCapability.Multimedia.Audio.Device 1922 1923**Parameters** 1924 1925| Name | Type | Mandatory| Description | 1926| ---------- | ------------------------- | ---- | ---------------- | 1927| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag.| 1928 1929**Return value** 1930 1931| Type | Description | 1932| ------------------------------------------------------------ | ------------------------- | 1933| Promise<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Promise used to return the device list.| 1934 1935**Example** 1936 1937```ts 1938audioManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG).then((data: audio.AudioDeviceDescriptors) => { 1939 console.info('Promise returned to indicate that the device list is obtained.'); 1940}); 1941``` 1942 1943### setDeviceActive<sup>(deprecated)</sup> 1944 1945setDeviceActive(deviceType: ActiveDeviceType, active: boolean, callback: AsyncCallback<void>): void 1946 1947Sets a device to the active state. This API uses an asynchronous callback to return the result. 1948 1949> **NOTE** 1950> 1951> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setCommunicationDevice](#setcommunicationdevice9) in **AudioRoutingManager**. 1952 1953**System capability**: SystemCapability.Multimedia.Audio.Device 1954 1955**Parameters** 1956 1957| Name | Type | Mandatory| Description | 1958| ---------- | ------------------------------------- | ---- |-------------| 1959| deviceType | [ActiveDeviceType](#activedevicetypedeprecated) | Yes | Active audio device type. | 1960| active | boolean | Yes | Active state to set. The value **true** means to set the device to the active state, and **false** means the opposite. | 1961| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1962 1963**Example** 1964 1965```ts 1966import { BusinessError } from '@kit.BasicServicesKit'; 1967 1968audioManager.setDeviceActive(audio.ActiveDeviceType.SPEAKER, true, (err: BusinessError) => { 1969 if (err) { 1970 console.error(`Failed to set the active status of the device. ${err}`); 1971 return; 1972 } 1973 console.info('Callback invoked to indicate that the device is set to the active status.'); 1974}); 1975``` 1976 1977### setDeviceActive<sup>(deprecated)</sup> 1978 1979setDeviceActive(deviceType: ActiveDeviceType, active: boolean): Promise<void> 1980 1981Sets a device to the active state. This API uses a promise to return the result. 1982 1983> **NOTE** 1984> 1985> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setCommunicationDevice](#setcommunicationdevice9) in **AudioRoutingManager**. 1986 1987**System capability**: SystemCapability.Multimedia.Audio.Device 1988 1989**Parameters** 1990 1991| Name | Type | Mandatory| Description | 1992| ---------- | ------------------------------------- | ---- | ------------------ | 1993| deviceType | [ActiveDeviceType](#activedevicetypedeprecated) | Yes | Active audio device type.| 1994| active | boolean | Yes | Active state to set. The value **true** means to set the device to the active state, and **false** means the opposite. | 1995 1996**Return value** 1997 1998| Type | Description | 1999| ------------------- | ------------------------------- | 2000| Promise<void> | Promise that returns no value.| 2001 2002**Example** 2003 2004 2005```ts 2006audioManager.setDeviceActive(audio.ActiveDeviceType.SPEAKER, true).then(() => { 2007 console.info('Promise returned to indicate that the device is set to the active status.'); 2008}); 2009``` 2010 2011### isDeviceActive<sup>(deprecated)</sup> 2012 2013isDeviceActive(deviceType: ActiveDeviceType, callback: AsyncCallback<boolean>): void 2014 2015Checks whether a device is active. This API uses an asynchronous callback to return the result. 2016 2017> **NOTE** 2018> 2019> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isCommunicationDeviceActive](#iscommunicationdeviceactive9) in **AudioRoutingManager**. 2020 2021**System capability**: SystemCapability.Multimedia.Audio.Device 2022 2023**Parameters** 2024 2025| Name | Type | Mandatory| Description | 2026| ---------- | ------------------------------------- | ---- | ------------------------ | 2027| deviceType | [ActiveDeviceType](#activedevicetypedeprecated) | Yes | Active audio device type. | 2028| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true** if the stream is active or **false** if not active; otherwise, **err** is an error object.| 2029 2030**Example** 2031 2032```ts 2033import { BusinessError } from '@kit.BasicServicesKit'; 2034 2035audioManager.isDeviceActive(audio.ActiveDeviceType.SPEAKER, (err: BusinessError, value: boolean) => { 2036 if (err) { 2037 console.error(`Failed to obtain the active status of the device. ${err}`); 2038 return; 2039 } 2040 console.info('Callback invoked to indicate that the active status of the device is obtained.'); 2041}); 2042``` 2043 2044### isDeviceActive<sup>(deprecated)</sup> 2045 2046isDeviceActive(deviceType: ActiveDeviceType): Promise<boolean> 2047 2048Checks whether a device is active. This API uses a promise to return the result. 2049 2050> **NOTE** 2051> 2052> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isCommunicationDeviceActive](#iscommunicationdeviceactive9) in **AudioRoutingManager**. 2053 2054**System capability**: SystemCapability.Multimedia.Audio.Device 2055 2056**Parameters** 2057 2058| Name | Type | Mandatory| Description | 2059| ---------- | ------------------------------------- | ---- | ------------------ | 2060| deviceType | [ActiveDeviceType](#activedevicetypedeprecated) | Yes | Active audio device type.| 2061 2062**Return value** 2063 2064| Type | Description | 2065| ---------------------- |---------------------------------------| 2066| Promise<boolean> | Promise used to return the active status of the device. The value **true** means that the device is active, and **false** means the opposite. | 2067 2068**Example** 2069 2070```ts 2071audioManager.isDeviceActive(audio.ActiveDeviceType.SPEAKER).then((value: boolean) => { 2072 console.info(`Promise returned to indicate that the active status of the device is obtained ${value}.`); 2073}); 2074``` 2075 2076### setMicrophoneMute<sup>(deprecated)</sup> 2077 2078setMicrophoneMute(mute: boolean, callback: AsyncCallback<void>): void 2079 2080Mutes or unmutes the microphone. This API uses an asynchronous callback to return the result. 2081 2082> **NOTE** 2083> 2084> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 2085 2086**Required permissions**: ohos.permission.MICROPHONE 2087 2088**System capability**: SystemCapability.Multimedia.Audio.Device 2089 2090**Parameters** 2091 2092| Name | Type | Mandatory| Description | 2093| -------- | ------------------------- | ---- | --------------------------------------------- | 2094| mute | boolean | Yes | Mute status to set. The value **true** means to mute the microphone, and **false** means the opposite.| 2095| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 2096 2097**Example** 2098 2099```ts 2100import { BusinessError } from '@kit.BasicServicesKit'; 2101 2102audioManager.setMicrophoneMute(true, (err: BusinessError) => { 2103 if (err) { 2104 console.error(`Failed to mute the microphone. ${err}`); 2105 return; 2106 } 2107 console.info('Callback invoked to indicate that the microphone is muted.'); 2108}); 2109``` 2110 2111### setMicrophoneMute<sup>(deprecated)</sup> 2112 2113setMicrophoneMute(mute: boolean): Promise<void> 2114 2115Mutes or unmutes the microphone. This API uses a promise to return the result. 2116 2117> **NOTE** 2118> 2119> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 2120 2121**Required permissions**: ohos.permission.MICROPHONE 2122 2123**System capability**: SystemCapability.Multimedia.Audio.Device 2124 2125**Parameters** 2126 2127| Name| Type | Mandatory| Description | 2128| ------ | ------- | ---- | --------------------------------------------- | 2129| mute | boolean | Yes | Mute status to set. The value **true** means to mute the microphone, and **false** means the opposite.| 2130 2131**Return value** 2132 2133| Type | Description | 2134| ------------------- | ------------------------------- | 2135| Promise<void> | Promise that returns no value.| 2136 2137**Example** 2138 2139```ts 2140audioManager.setMicrophoneMute(true).then(() => { 2141 console.info('Promise returned to indicate that the microphone is muted.'); 2142}); 2143``` 2144 2145### isMicrophoneMute<sup>(deprecated)</sup> 2146 2147isMicrophoneMute(callback: AsyncCallback<boolean>): void 2148 2149Checks whether the microphone is muted. This API uses an asynchronous callback to return the result. 2150 2151> **NOTE** 2152> 2153> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isMicrophoneMute](#ismicrophonemute9) in **AudioVolumeGroupManager**. 2154 2155**Required permissions**: ohos.permission.MICROPHONE 2156 2157**System capability**: SystemCapability.Multimedia.Audio.Device 2158 2159**Parameters** 2160 2161| Name | Type | Mandatory| Description | 2162| -------- | ---------------------------- | ---- | ------------------------------------------------------- | 2163| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true** if the microphone is muted or **false** if not muted; otherwise, **err** is an error object.| 2164 2165**Example** 2166 2167```ts 2168import { BusinessError } from '@kit.BasicServicesKit'; 2169 2170audioManager.isMicrophoneMute((err: BusinessError, value: boolean) => { 2171 if (err) { 2172 console.error(`Failed to obtain the mute status of the microphone. ${err}`); 2173 return; 2174 } 2175 console.info(`Callback invoked to indicate that the mute status of the microphone is obtained ${value}.`); 2176}); 2177``` 2178 2179### isMicrophoneMute<sup>(deprecated)</sup> 2180 2181isMicrophoneMute(): Promise<boolean> 2182 2183Checks whether the microphone is muted. This API uses a promise to return the result. 2184 2185> **NOTE** 2186> 2187> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isMicrophoneMute](#ismicrophonemute9) in **AudioVolumeGroupManager**. 2188 2189**Required permissions**: ohos.permission.MICROPHONE 2190 2191**System capability**: SystemCapability.Multimedia.Audio.Device 2192 2193**Return value** 2194 2195| Type | Description | 2196| ---------------------- | ------------------------------------------------------------ | 2197| 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.| 2198 2199**Example** 2200 2201```ts 2202audioManager.isMicrophoneMute().then((value: boolean) => { 2203 console.info(`Promise returned to indicate that the mute status of the microphone is obtained ${value}.`); 2204}); 2205``` 2206 2207### on('deviceChange')<sup>(deprecated)</sup> 2208 2209on(type: 'deviceChange', callback: Callback<DeviceChangeAction\>): void 2210 2211Subscribes to the audio device change event, which is triggered when the connection status of an audio device is changed. This API uses an asynchronous callback to return the result. 2212 2213> **NOTE** 2214> 2215> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [on('deviceChange')](#ondevicechange9) in **AudioRoutingManager**. 2216 2217**System capability**: SystemCapability.Multimedia.Audio.Device 2218 2219**Parameters** 2220 2221| Name | Type | Mandatory| Description | 2222| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- | 2223| type | string | Yes | Event type. The value is fixed at **'deviceChange'**.| 2224| callback | Callback<[DeviceChangeAction](#devicechangeaction)\> | Yes | Callback used to return the device change details.| 2225 2226**Example** 2227 2228```ts 2229audioManager.on('deviceChange', (deviceChanged: audio.DeviceChangeAction) => { 2230 console.info(`device change type : ${deviceChanged.type} `); 2231 console.info(`device descriptor size : ${deviceChanged.deviceDescriptors.length} `); 2232 console.info(`device change descriptor : ${deviceChanged.deviceDescriptors[0].deviceRole} `); 2233 console.info(`device change descriptor : ${deviceChanged.deviceDescriptors[0].deviceType} `); 2234}); 2235``` 2236 2237### off('deviceChange')<sup>(deprecated)</sup> 2238 2239off(type: 'deviceChange', callback?: Callback<DeviceChangeAction\>): void 2240 2241Unsubscribes from the audio device change event. This API uses an asynchronous callback to return the result. 2242 2243> **NOTE** 2244> 2245> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [off('deviceChange')](#offdevicechange9) in **AudioRoutingManager**. 2246 2247**System capability**: SystemCapability.Multimedia.Audio.Device 2248 2249**Parameters** 2250 2251| Name | Type | Mandatory| Description | 2252| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 2253| type | string | Yes | Event type. The value is fixed at **'deviceChange'**.| 2254| callback | Callback<[DeviceChangeAction](#devicechangeaction)> | No | Callback used to return the device change details.| 2255 2256**Example** 2257 2258```ts 2259// Cancel all subscriptions to the event. 2260audioManager.off('deviceChange'); 2261 2262// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 2263let deviceChangeCallback = (deviceChanged: audio.DeviceChangeAction) => { 2264 console.info(`device change type : ${deviceChanged.type} `); 2265 console.info(`device descriptor size : ${deviceChanged.deviceDescriptors.length} `); 2266 console.info(`device change descriptor : ${deviceChanged.deviceDescriptors[0].deviceRole} `); 2267 console.info(`device change descriptor : ${deviceChanged.deviceDescriptors[0].deviceType} `); 2268}; 2269 2270audioManager.on('deviceChange', deviceChangeCallback); 2271 2272audioManager.off('deviceChange', deviceChangeCallback); 2273``` 2274 2275### on('interrupt')<sup>(deprecated)</sup> 2276 2277on(type: 'interrupt', interrupt: AudioInterrupt, callback: Callback\<InterruptAction>): void 2278 2279Subscribes to the audio interruption event, which is triggered when the application's audio is interrupted by another playback event. This API uses an asynchronous callback to return the result. 2280 2281Same as [on('audioInterrupt')](#onaudiointerrupt9), this API is used to listen for focus is changed. However, this API is used in scenarios without audio streams (no **AudioRenderer** instance is created), such as frequency modulation (FM) and voice wakeup. 2282 2283> **NOTE** 2284> 2285> This API is supported since API version 7 and deprecated since API version 11. You are advised to use [on('audioInterrupt')](#onaudiointerrupt10) in **AudioCapturer**. 2286 2287**System capability**: SystemCapability.Multimedia.Audio.Renderer 2288 2289**Parameters** 2290 2291| Name | Type | Mandatory| Description | 2292| --------- |---------------------------------------------------------| ---- | ------------------------------------------------------------ | 2293| type | string | Yes | Event type. The value is fixed at **'interrupt'**.| 2294| interrupt | [AudioInterrupt](#audiointerruptdeprecated) | Yes | Audio interruption event type. | 2295| callback | Callback<[InterruptAction](#interruptactiondeprecated)> | Yes | Callback used to return the audio interruption event.| 2296 2297**Example** 2298 2299```ts 2300import { audio } from '@kit.AudioKit'; 2301 2302let interAudioInterrupt: audio.AudioInterrupt = { 2303 streamUsage:2, 2304 contentType:0, 2305 pauseWhenDucked:true 2306}; 2307 2308audioManager.on('interrupt', interAudioInterrupt, (interruptAction: audio.InterruptAction) => { 2309 if (interruptAction.actionType === 0) { 2310 console.info('An event to gain the audio focus starts.'); 2311 console.info(`Focus gain event: ${interruptAction} `); 2312 } 2313 if (interruptAction.actionType === 1) { 2314 console.info('An audio interruption event starts.'); 2315 console.info(`Audio interruption event: ${interruptAction} `); 2316 } 2317}); 2318``` 2319 2320### off('interrupt')<sup>(deprecated)</sup> 2321 2322off(type: 'interrupt', interrupt: AudioInterrupt, callback?: Callback\<InterruptAction>): void 2323 2324Unsubscribes from the audio interruption event. This API uses an asynchronous callback to return the result. 2325 2326> **NOTE** 2327> 2328> This API is supported since API version 7 and deprecated since API version 11. You are advised to use [off('audioInterrupt')](#offaudiointerrupt10) in **AudioCapturer**. 2329 2330**System capability**: SystemCapability.Multimedia.Audio.Renderer 2331 2332**Parameters** 2333 2334| Name | Type | Mandatory| Description | 2335| --------- |---------------------------------------------------------| ---- | ------------------------------------------------------------ | 2336| type | string | Yes | Event type. The value is fixed at **'interrupt'**.| 2337| interrupt | [AudioInterrupt](#audiointerruptdeprecated) | Yes | Audio interruption event type. | 2338| callback | Callback<[InterruptAction](#interruptactiondeprecated)> | No | Callback used to return the audio interruption event.| 2339 2340**Example** 2341 2342```ts 2343import { audio } from '@kit.AudioKit'; 2344 2345let interAudioInterrupt: audio.AudioInterrupt = { 2346 streamUsage:2, 2347 contentType:0, 2348 pauseWhenDucked:true 2349}; 2350 2351// Cancel all subscriptions to the event. 2352audioManager.off('interrupt', interAudioInterrupt); 2353 2354// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 2355let interruptCallback = (interruptAction: audio.InterruptAction) => { 2356 if (interruptAction.actionType === 0) { 2357 console.info('An event to gain the audio focus starts.'); 2358 console.info(`Focus gain event: ${interruptAction} `); 2359 } 2360 if (interruptAction.actionType === 1) { 2361 console.info('An audio interruption event starts.'); 2362 console.info(`Audio interruption event: ${interruptAction} `); 2363 } 2364}; 2365 2366audioManager.on('interrupt', interAudioInterrupt, interruptCallback); 2367 2368audioManager.off('interrupt', interAudioInterrupt, interruptCallback); 2369``` 2370 2371## AudioVolumeManager<sup>9+</sup> 2372 2373Implements audio volume management. Before calling an API in **AudioVolumeManager**, you must use [getVolumeManager](#getvolumemanager9) to obtain an **AudioVolumeManager** instance. 2374 2375### getVolumeGroupManager<sup>9+</sup> 2376 2377getVolumeGroupManager(groupId: number, callback: AsyncCallback<AudioVolumeGroupManager\>\): void 2378 2379Obtains the volume group manager. This API uses an asynchronous callback to return the result. 2380 2381**System capability**: SystemCapability.Multimedia.Audio.Volume 2382 2383**Parameters** 2384 2385| Name | Type | Mandatory| Description | 2386| ---------- | ------------------------------------------------------------ | ---- |-----------------------------------------------------------| 2387| groupId | number | Yes | Volume group ID. The default value is **LOCAL_VOLUME_GROUP_ID**. | 2388| callback | AsyncCallback<[AudioVolumeGroupManager](#audiovolumegroupmanager9)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the volume group manager obtained; otherwise, **err** is an error object.| 2389 2390**Example** 2391 2392```ts 2393import { BusinessError } from '@kit.BasicServicesKit'; 2394 2395let groupId: number = audio.DEFAULT_VOLUME_GROUP_ID; 2396 2397audioVolumeManager.getVolumeGroupManager(groupId, (err: BusinessError, value: audio.AudioVolumeGroupManager) => { 2398 if (err) { 2399 console.error(`Failed to obtain the volume group infos list. ${err}`); 2400 return; 2401 } 2402 console.info('Callback invoked to indicate that the volume group infos list is obtained.'); 2403}); 2404 2405``` 2406 2407### getVolumeGroupManager<sup>9+</sup> 2408 2409getVolumeGroupManager(groupId: number\): Promise<AudioVolumeGroupManager\> 2410 2411Obtains the volume group manager. This API uses a promise to return the result. 2412 2413**System capability**: SystemCapability.Multimedia.Audio.Volume 2414 2415**Parameters** 2416 2417| Name | Type | Mandatory| Description | 2418| ---------- | ---------------------------------------- | ---- |----------------------------------| 2419| groupId | number | Yes | Volume group ID. The default value is **LOCAL_VOLUME_GROUP_ID**.| 2420 2421**Return value** 2422 2423| Type | Description | 2424| ------------------- | ----------------------------- | 2425| Promise< [AudioVolumeGroupManager](#audiovolumegroupmanager9) > | Promise used to return the volume group manager.| 2426 2427**Example** 2428 2429```ts 2430import { audio } from '@kit.AudioKit'; 2431 2432let groupId: number = audio.DEFAULT_VOLUME_GROUP_ID; 2433let audioVolumeGroupManager: audio.AudioVolumeGroupManager | undefined = undefined; 2434 2435async function getVolumeGroupManager(){ 2436 audioVolumeGroupManager = await audioVolumeManager.getVolumeGroupManager(groupId); 2437 console.info('Promise returned to indicate that the volume group infos list is obtained.'); 2438} 2439``` 2440 2441### getVolumeGroupManagerSync<sup>10+</sup> 2442 2443getVolumeGroupManagerSync(groupId: number\): AudioVolumeGroupManager 2444 2445Obtains the volume group manager. This API returns the result synchronously. 2446 2447**System capability**: SystemCapability.Multimedia.Audio.Volume 2448 2449**Parameters** 2450 2451| Name | Type | Mandatory| Description | 2452| ---------- | ---------------------------------------- | ---- |----------------------------------| 2453| groupId | number | Yes | Volume group ID. The default value is **LOCAL_VOLUME_GROUP_ID**.| 2454 2455**Return value** 2456 2457| Type | Description | 2458| ------------------- | ----------------------------- | 2459| [AudioVolumeGroupManager](#audiovolumegroupmanager9) | Volume group manager.| 2460 2461**Error codes** 2462 2463For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2464 2465| ID| Error Message| 2466| ------- | --------------------------------------------| 2467| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2468| 6800101 | Parameter verification failed. | 2469 2470**Example** 2471 2472```ts 2473import { BusinessError } from '@kit.BasicServicesKit'; 2474 2475try { 2476 let audioVolumeGroupManager: audio.AudioVolumeGroupManager = audioVolumeManager.getVolumeGroupManagerSync(audio.DEFAULT_VOLUME_GROUP_ID); 2477 console.info(`Get audioVolumeGroupManager success.`); 2478} catch (err) { 2479 let error = err as BusinessError; 2480 console.error(`Failed to get audioVolumeGroupManager, error: ${error}`); 2481} 2482``` 2483 2484### on('volumeChange')<sup>9+</sup> 2485 2486on(type: 'volumeChange', callback: Callback\<VolumeEvent>): void 2487 2488Subscribes to the system volume change event, which is triggered when the system volume is changed. This API uses an asynchronous callback to return the result. 2489 2490**System capability**: SystemCapability.Multimedia.Audio.Volume 2491 2492**Parameters** 2493 2494| Name | Type | Mandatory| Description | 2495| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 2496| type | string | Yes | Event type. The value is fixed at **'volumeChange'**.| 2497| callback | Callback<[VolumeEvent](#volumeevent9)> | Yes | Callback used to return the changed volume.| 2498 2499**Error codes** 2500 2501For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2502 2503| ID| Error Message| 2504| ------- | --------------------------------------------| 2505| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2506| 6800101 | Parameter verification failed. | 2507 2508**Example** 2509 2510```ts 2511audioVolumeManager.on('volumeChange', (volumeEvent: audio.VolumeEvent) => { 2512 console.info(`VolumeType of stream: ${volumeEvent.volumeType} `); 2513 console.info(`Volume level: ${volumeEvent.volume} `); 2514 console.info(`Whether to updateUI: ${volumeEvent.updateUi} `); 2515}); 2516``` 2517 2518### off('volumeChange')<sup>12+</sup> 2519 2520off(type: 'volumeChange', callback?: Callback\<VolumeEvent>): void 2521 2522Unsubscribes from the system volume change event. This API uses an asynchronous callback to return the result. 2523 2524**System capability**: SystemCapability.Multimedia.Audio.Volume 2525 2526**Parameters** 2527 2528| Name | Type | Mandatory| Description | 2529| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 2530| type | string | Yes | Event type. The value is fixed at **'volumeChange'**.| 2531| callback | Callback<[VolumeEvent](#volumeevent9)> | No | Callback used to return the changed volume.| 2532 2533**Error codes** 2534 2535For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2536 2537| ID| Error Message| 2538| ------- | --------------------------------------------| 2539| 401 | Parameter error. Possible causes: 1.Mandatory parameters missing; 2.Incorrect parameter types. | 2540| 6800101 | Parameter verification failed. | 2541 2542**Example** 2543 2544```ts 2545// Cancel all subscriptions to the event. 2546audioVolumeManager.off('volumeChange'); 2547 2548// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 2549let volumeChangeCallback = (volumeEvent: audio.VolumeEvent) => { 2550 console.info(`VolumeType of stream: ${volumeEvent.volumeType} `); 2551 console.info(`Volume level: ${volumeEvent.volume} `); 2552 console.info(`Whether to updateUI: ${volumeEvent.updateUi} `); 2553}; 2554 2555audioVolumeManager.on('volumeChange', volumeChangeCallback); 2556 2557audioVolumeManager.off('volumeChange', volumeChangeCallback); 2558``` 2559 2560## AudioVolumeGroupManager<sup>9+</sup> 2561 2562Manages the volume of an audio group. Before calling any API in **AudioVolumeGroupManager**, you must use [getVolumeGroupManager](#getvolumegroupmanager9) to obtain an **AudioVolumeGroupManager** instance. 2563 2564### getVolume<sup>9+</sup> 2565 2566getVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 2567 2568Obtains the volume of a stream. This API uses an asynchronous callback to return the result. 2569 2570**System capability**: SystemCapability.Multimedia.Audio.Volume 2571 2572**Parameters** 2573 2574| Name | Type | Mandatory| Description | 2575| ---------- | ----------------------------------- | ---- | ------------------ | 2576| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 2577| callback | AsyncCallback<number> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the stream volume obtained; otherwise, **err** is an error object. The volume range of a specified stream can be obtained by calling [getMinVolume](#getminvolume9) and [getMaxVolume](#getmaxvolume9).| 2578 2579**Example** 2580 2581```ts 2582import { BusinessError } from '@kit.BasicServicesKit'; 2583 2584audioVolumeGroupManager.getVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { 2585 if (err) { 2586 console.error(`Failed to obtain the volume. ${err}`); 2587 return; 2588 } 2589 console.info('Callback invoked to indicate that the volume is obtained.'); 2590}); 2591``` 2592 2593### getVolume<sup>9+</sup> 2594 2595getVolume(volumeType: AudioVolumeType): Promise<number> 2596 2597Obtains the volume of a stream. This API uses a promise to return the result. 2598 2599**System capability**: SystemCapability.Multimedia.Audio.Volume 2600 2601**Parameters** 2602 2603| Name | Type | Mandatory| Description | 2604| ---------- | ----------------------------------- | ---- | ------------ | 2605| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2606 2607**Return value** 2608 2609| Type | Description | 2610| --------------------- | ------------------------- | 2611| Promise<number> | Promise used to return the volume of the stream. The volume range of a specified stream can be obtained by calling [getMinVolume](#getminvolume9) and [getMaxVolume](#getmaxvolume9).| 2612 2613**Example** 2614 2615```ts 2616audioVolumeGroupManager.getVolume(audio.AudioVolumeType.MEDIA).then((value: number) => { 2617 console.info(`Promise returned to indicate that the volume is obtained ${value}.`); 2618}); 2619``` 2620 2621### getVolumeSync<sup>10+</sup> 2622 2623getVolumeSync(volumeType: AudioVolumeType): number; 2624 2625Obtains the volume of a stream. This API returns the result synchronously. 2626 2627**System capability**: SystemCapability.Multimedia.Audio.Volume 2628 2629**Parameters** 2630 2631| Name | Type | Mandatory| Description | 2632| ---------- | ----------------------------------- | ---- | ------------ | 2633| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2634 2635**Return value** 2636 2637| Type | Description | 2638| --------------------- | ------------------------- | 2639| number | Volume of the stream. The volume range of a specified stream can be obtained by calling [getMinVolume](#getminvolume9) and [getMaxVolume](#getmaxvolume9).| 2640 2641**Error codes** 2642 2643For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2644 2645| ID| Error Message| 2646| ------- | --------------------------------------------| 2647| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2648| 6800101 | Parameter verification failed. | 2649 2650**Example** 2651 2652```ts 2653import { BusinessError } from '@kit.BasicServicesKit'; 2654 2655try { 2656 let value: number = audioVolumeGroupManager.getVolumeSync(audio.AudioVolumeType.MEDIA); 2657 console.info(`Indicate that the volume is obtained ${value}.`); 2658} catch (err) { 2659 let error = err as BusinessError; 2660 console.error(`Failed to obtain the volume, error ${error}.`); 2661} 2662``` 2663 2664### getMinVolume<sup>9+</sup> 2665 2666getMinVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 2667 2668Obtains the minimum volume allowed for a stream. This API uses an asynchronous callback to return the result. 2669 2670**System capability**: SystemCapability.Multimedia.Audio.Volume 2671 2672**Parameters** 2673 2674| Name | Type | Mandatory| Description | 2675| ---------- | ----------------------------------- | ---- | ------------------ | 2676| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 2677| callback | AsyncCallback<number> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the minimum stream volume obtained; otherwise, **err** is an error object.| 2678 2679**Example** 2680 2681```ts 2682import { BusinessError } from '@kit.BasicServicesKit'; 2683 2684audioVolumeGroupManager.getMinVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { 2685 if (err) { 2686 console.error(`Failed to obtain the minimum volume. ${err}`); 2687 return; 2688 } 2689 console.info(`Callback invoked to indicate that the minimum volume is obtained. ${value}`); 2690}); 2691``` 2692 2693### getMinVolume<sup>9+</sup> 2694 2695getMinVolume(volumeType: AudioVolumeType): Promise<number> 2696 2697Obtains the minimum volume allowed for a stream. This API uses a promise to return the result. 2698 2699**System capability**: SystemCapability.Multimedia.Audio.Volume 2700 2701**Parameters** 2702 2703| Name | Type | Mandatory| Description | 2704| ---------- | ----------------------------------- | ---- | ------------ | 2705| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2706 2707**Return value** 2708 2709| Type | Description | 2710| --------------------- | ------------------------- | 2711| Promise<number> | Promise used to return the minimum volume.| 2712 2713**Example** 2714 2715```ts 2716audioVolumeGroupManager.getMinVolume(audio.AudioVolumeType.MEDIA).then((value: number) => { 2717 console.info(`Promised returned to indicate that the minimum volume is obtained ${value}.`); 2718}); 2719``` 2720 2721### getMinVolumeSync<sup>10+</sup> 2722 2723getMinVolumeSync(volumeType: AudioVolumeType): number; 2724 2725Obtains the minimum volume allowed for a stream. This API returns the result synchronously. 2726 2727**System capability**: SystemCapability.Multimedia.Audio.Volume 2728 2729**Parameters** 2730 2731| Name | Type | Mandatory| Description | 2732| ---------- | ----------------------------------- | ---- | ------------ | 2733| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2734 2735**Return value** 2736 2737| Type | Description | 2738| --------------------- | ------------------------- | 2739| number | Minimum volume.| 2740 2741**Error codes** 2742 2743For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2744 2745| ID| Error Message| 2746| ------- | --------------------------------------------| 2747| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2748| 6800101 | Parameter verification failed. | 2749 2750**Example** 2751 2752```ts 2753import { BusinessError } from '@kit.BasicServicesKit'; 2754 2755try { 2756 let value: number = audioVolumeGroupManager.getMinVolumeSync(audio.AudioVolumeType.MEDIA); 2757 console.info(`Indicate that the minimum volume is obtained ${value}.`); 2758} catch (err) { 2759 let error = err as BusinessError; 2760 console.error(`Failed to obtain the minimum volume, error ${error}.`); 2761} 2762``` 2763 2764### getMaxVolume<sup>9+</sup> 2765 2766getMaxVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 2767 2768Obtains the maximum volume allowed for a stream. This API uses an asynchronous callback to return the result. 2769 2770**System capability**: SystemCapability.Multimedia.Audio.Volume 2771 2772**Parameters** 2773 2774| Name | Type | Mandatory| Description | 2775| ---------- | ----------------------------------- | ---- | ---------------------- | 2776| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 2777| callback | AsyncCallback<number> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the maximum stream volume obtained; otherwise, **err** is an error object.| 2778 2779**Example** 2780 2781```ts 2782import { BusinessError } from '@kit.BasicServicesKit'; 2783 2784audioVolumeGroupManager.getMaxVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { 2785 if (err) { 2786 console.error(`Failed to obtain the maximum volume. ${err}`); 2787 return; 2788 } 2789 console.info(`Callback invoked to indicate that the maximum volume is obtained. ${value}`); 2790}); 2791``` 2792 2793### getMaxVolume<sup>9+</sup> 2794 2795getMaxVolume(volumeType: AudioVolumeType): Promise<number> 2796 2797Obtains the maximum volume allowed for a stream. This API uses a promise to return the result. 2798 2799**System capability**: SystemCapability.Multimedia.Audio.Volume 2800 2801**Parameters** 2802 2803| Name | Type | Mandatory| Description | 2804| ---------- | ----------------------------------- | ---- | ------------ | 2805| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2806 2807**Return value** 2808 2809| Type | Description | 2810| --------------------- | ----------------------------- | 2811| Promise<number> | Promise used to return the maximum volume.| 2812 2813**Example** 2814 2815```ts 2816audioVolumeGroupManager.getMaxVolume(audio.AudioVolumeType.MEDIA).then((data: number) => { 2817 console.info('Promised returned to indicate that the maximum volume is obtained.'); 2818}); 2819``` 2820 2821### getMaxVolumeSync<sup>10+</sup> 2822 2823getMaxVolumeSync(volumeType: AudioVolumeType): number; 2824 2825Obtains the maximum volume allowed for a stream. This API returns the result synchronously. 2826 2827**System capability**: SystemCapability.Multimedia.Audio.Volume 2828 2829**Parameters** 2830 2831| Name | Type | Mandatory| Description | 2832| ---------- | ----------------------------------- | ---- | ------------ | 2833| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2834 2835**Return value** 2836 2837| Type | Description | 2838| --------------------- | ----------------------------- | 2839| number | Maximum volume.| 2840 2841**Error codes** 2842 2843For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2844 2845| ID| Error Message| 2846| ------- | --------------------------------------------| 2847| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2848| 6800101 | Parameter verification failed. | 2849 2850**Example** 2851 2852```ts 2853import { BusinessError } from '@kit.BasicServicesKit'; 2854 2855try { 2856 let value: number = audioVolumeGroupManager.getMaxVolumeSync(audio.AudioVolumeType.MEDIA); 2857 console.info(`Indicate that the maximum volume is obtained. ${value}`); 2858} catch (err) { 2859 let error = err as BusinessError; 2860 console.error(`Failed to obtain the maximum volume, error ${error}.`); 2861} 2862``` 2863 2864### isMute<sup>9+</sup> 2865 2866isMute(volumeType: AudioVolumeType, callback: AsyncCallback<boolean>): void 2867 2868Checks whether a stream is muted. This API uses an asynchronous callback to return the result. 2869 2870**System capability**: SystemCapability.Multimedia.Audio.Volume 2871 2872**Parameters** 2873 2874| Name | Type | Mandatory| Description | 2875| ---------- | ----------------------------------- | ---- | ----------------------------------------------- | 2876| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 2877| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true** if the stream is muted or **false** if not muted; otherwise, **err** is an error object.| 2878 2879**Example** 2880 2881```ts 2882import { BusinessError } from '@kit.BasicServicesKit'; 2883 2884audioVolumeGroupManager.isMute(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: boolean) => { 2885 if (err) { 2886 console.error(`Failed to obtain the mute status. ${err}`); 2887 return; 2888 } 2889 console.info(`Callback invoked to indicate that the mute status of the stream is obtained ${value}.`); 2890}); 2891``` 2892 2893### isMute<sup>9+</sup> 2894 2895isMute(volumeType: AudioVolumeType): Promise<boolean> 2896 2897Checks whether a stream is muted. This API uses a promise to return the result. 2898 2899**System capability**: SystemCapability.Multimedia.Audio.Volume 2900 2901**Parameters** 2902 2903| Name | Type | Mandatory| Description | 2904| ---------- | ----------------------------------- | ---- | ------------ | 2905| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2906 2907**Return value** 2908 2909| Type | Description | 2910| ---------------------- | ------------------------------------------------------ | 2911| 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.| 2912 2913**Example** 2914 2915```ts 2916audioVolumeGroupManager.isMute(audio.AudioVolumeType.MEDIA).then((value: boolean) => { 2917 console.info(`Promise returned to indicate that the mute status of the stream is obtained ${value}.`); 2918}); 2919``` 2920 2921### isMuteSync<sup>10+</sup> 2922 2923isMuteSync(volumeType: AudioVolumeType): boolean 2924 2925Checks whether a stream is muted. This API returns the result synchronously. 2926 2927**System capability**: SystemCapability.Multimedia.Audio.Volume 2928 2929**Parameters** 2930 2931| Name | Type | Mandatory| Description | 2932| ---------- | ----------------------------------- | ---- | ------------ | 2933| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2934 2935**Return value** 2936 2937| Type | Description | 2938| ---------------------- | ------------------------------------------------------ | 2939| boolean | **true**: The stream is muted.<br>**false**: The stream is not muted.| 2940 2941**Error codes** 2942 2943For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2944 2945| ID| Error Message| 2946| ------- | --------------------------------------------| 2947| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2948| 6800101 | Parameter verification failed. | 2949 2950**Example** 2951 2952```ts 2953import { BusinessError } from '@kit.BasicServicesKit'; 2954 2955try { 2956 let value: boolean = audioVolumeGroupManager.isMuteSync(audio.AudioVolumeType.MEDIA); 2957 console.info(`Indicate that the mute status of the stream is obtained ${value}.`); 2958} catch (err) { 2959 let error = err as BusinessError; 2960 console.error(`Failed to obtain the mute status of the stream, error ${error}.`); 2961} 2962``` 2963 2964### getRingerMode<sup>9+</sup> 2965 2966getRingerMode(callback: AsyncCallback<AudioRingMode>): void 2967 2968Obtains the ringer mode. This API uses an asynchronous callback to return the result. 2969 2970**System capability**: SystemCapability.Multimedia.Audio.Volume 2971 2972**Parameters** 2973 2974| Name | Type | Mandatory| Description | 2975| -------- | ---------------------------------------------------- | ---- | ------------------------ | 2976| callback | AsyncCallback<[AudioRingMode](#audioringmode)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the ringer mode obtained; otherwise, **err** is an error object.| 2977 2978**Example** 2979 2980```ts 2981import { BusinessError } from '@kit.BasicServicesKit'; 2982 2983audioVolumeGroupManager.getRingerMode((err: BusinessError, value: audio.AudioRingMode) => { 2984 if (err) { 2985 console.error(`Failed to obtain the ringer mode. ${err}`); 2986 return; 2987 } 2988 console.info(`Callback invoked to indicate that the ringer mode is obtained ${value}.`); 2989}); 2990``` 2991 2992### getRingerMode<sup>9+</sup> 2993 2994getRingerMode(): Promise<AudioRingMode> 2995 2996Obtains the ringer mode. This API uses a promise to return the result. 2997 2998**System capability**: SystemCapability.Multimedia.Audio.Volume 2999 3000**Return value** 3001 3002| Type | Description | 3003| ---------------------------------------------- | ------------------------------- | 3004| Promise<[AudioRingMode](#audioringmode)> | Promise used to return the ringer mode.| 3005 3006**Example** 3007 3008```ts 3009audioVolumeGroupManager.getRingerMode().then((value: audio.AudioRingMode) => { 3010 console.info(`Promise returned to indicate that the ringer mode is obtained ${value}.`); 3011}); 3012``` 3013 3014### getRingerModeSync<sup>10+</sup> 3015 3016getRingerModeSync(): AudioRingMode 3017 3018Obtains the ringer mode. This API returns the result synchronously. 3019 3020**System capability**: SystemCapability.Multimedia.Audio.Volume 3021 3022**Return value** 3023 3024| Type | Description | 3025| ---------------------------------------------- | ------------------------------- | 3026| [AudioRingMode](#audioringmode) | Ringer mode.| 3027 3028**Example** 3029 3030```ts 3031import { BusinessError } from '@kit.BasicServicesKit'; 3032 3033try { 3034 let value: audio.AudioRingMode = audioVolumeGroupManager.getRingerModeSync(); 3035 console.info(`Indicate that the ringer mode is obtained ${value}.`); 3036} catch (err) { 3037 let error = err as BusinessError; 3038 console.error(`Failed to obtain the ringer mode, error ${error}.`); 3039} 3040``` 3041 3042### on('ringerModeChange')<sup>9+</sup> 3043 3044on(type: 'ringerModeChange', callback: Callback\<AudioRingMode>): void 3045 3046Subscribes to the ringer mode change event, which is triggered when [audioringmode](#audioringmode) is changed. This API uses an asynchronous callback to return the result. 3047 3048**System capability**: SystemCapability.Multimedia.Audio.Volume 3049 3050**Parameters** 3051 3052| Name | Type | Mandatory| Description | 3053| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 3054| type | string | Yes | Event type. The value is fixed at **'ringerModeChange'**.| 3055| callback | Callback<[AudioRingMode](#audioringmode)> | Yes | Callback used to return the changed ringer mode.| 3056 3057**Error codes** 3058 3059For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3060 3061| ID| Error Message| 3062| ------- | --------------------------------------------| 3063| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3064| 6800101 | Parameter verification failed. | 3065 3066**Example** 3067 3068```ts 3069audioVolumeGroupManager.on('ringerModeChange', (ringerMode: audio.AudioRingMode) => { 3070 console.info(`Updated ringermode: ${ringerMode}`); 3071}); 3072``` 3073 3074### setMicrophoneMute<sup>(deprecated)</sup> 3075 3076setMicrophoneMute(mute: boolean, callback: AsyncCallback<void>): void 3077 3078Mutes or unmutes the microphone. This API uses an asynchronous callback to return the result. 3079 3080> **NOTE** 3081> 3082> This API is supported since API version 9 and deprecated since API version 11. The substitute API is available only for system applications. 3083 3084**Required permissions**: ohos.permission.MANAGE_AUDIO_CONFIG (available only for system applications) 3085 3086**System capability**: SystemCapability.Multimedia.Audio.Volume 3087 3088**Parameters** 3089 3090| Name | Type | Mandatory| Description | 3091| -------- | ------------------------- | ---- | --------------------------------------------- | 3092| mute | boolean | Yes | Mute status to set. The value **true** means to mute the microphone, and **false** means the opposite.| 3093| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 3094 3095**Example** 3096 3097```ts 3098import { BusinessError } from '@kit.BasicServicesKit'; 3099 3100audioVolumeGroupManager.setMicrophoneMute(true, (err: BusinessError) => { 3101 if (err) { 3102 console.error(`Failed to mute the microphone. ${err}`); 3103 return; 3104 } 3105 console.info('Callback invoked to indicate that the microphone is muted.'); 3106}); 3107``` 3108 3109### setMicrophoneMute<sup>(deprecated)</sup> 3110 3111setMicrophoneMute(mute: boolean): Promise<void> 3112 3113Mutes or unmutes the microphone. This API uses a promise to return the result. 3114 3115> **NOTE** 3116> 3117> This API is supported since API version 9 and deprecated since API version 11. The substitute API is available only for system applications. 3118 3119**Required permissions**: ohos.permission.MANAGE_AUDIO_CONFIG (available only for system applications) 3120 3121**System capability**: SystemCapability.Multimedia.Audio.Volume 3122 3123**Parameters** 3124 3125| Name| Type | Mandatory| Description | 3126| ------ | ------- | ---- | --------------------------------------------- | 3127| mute | boolean | Yes | Mute status to set. The value **true** means to mute the microphone, and **false** means the opposite.| 3128 3129**Return value** 3130 3131| Type | Description | 3132| ------------------- | ------------------------------- | 3133| Promise<void> | Promise that returns no value.| 3134 3135**Example** 3136 3137```ts 3138audioVolumeGroupManager.setMicrophoneMute(true).then(() => { 3139 console.info('Promise returned to indicate that the microphone is muted.'); 3140}); 3141``` 3142 3143### isMicrophoneMute<sup>9+</sup> 3144 3145isMicrophoneMute(callback: AsyncCallback<boolean>): void 3146 3147Checks whether the microphone is muted. This API uses an asynchronous callback to return the result. 3148 3149**System capability**: SystemCapability.Multimedia.Audio.Volume 3150 3151**Parameters** 3152 3153| Name | Type | Mandatory| Description | 3154| -------- | ---------------------------- | ---- | ------------------------------------------------------- | 3155| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true** if the microphone is muted or **false** if not muted; otherwise, **err** is an error object.| 3156 3157**Example** 3158 3159```ts 3160import { BusinessError } from '@kit.BasicServicesKit'; 3161 3162audioVolumeGroupManager.isMicrophoneMute((err: BusinessError, value: boolean) => { 3163 if (err) { 3164 console.error(`Failed to obtain the mute status of the microphone. ${err}`); 3165 return; 3166 } 3167 console.info(`Callback invoked to indicate that the mute status of the microphone is obtained ${value}.`); 3168}); 3169``` 3170 3171### isMicrophoneMute<sup>9+</sup> 3172 3173isMicrophoneMute(): Promise<boolean> 3174 3175Checks whether the microphone is muted. This API uses a promise to return the result. 3176 3177**System capability**: SystemCapability.Multimedia.Audio.Volume 3178 3179**Return value** 3180 3181| Type | Description | 3182| ---------------------- | ------------------------------------------------------------ | 3183| 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.| 3184 3185**Example** 3186 3187```ts 3188audioVolumeGroupManager.isMicrophoneMute().then((value: boolean) => { 3189 console.info(`Promise returned to indicate that the mute status of the microphone is obtained ${value}.`); 3190}); 3191``` 3192 3193### isMicrophoneMuteSync<sup>10+</sup> 3194 3195isMicrophoneMuteSync(): boolean 3196 3197Checks whether the microphone is muted. This API returns the result synchronously. 3198 3199**System capability**: SystemCapability.Multimedia.Audio.Volume 3200 3201**Return value** 3202 3203| Type | Description | 3204| ---------------------- | ------------------------------------------------------------ | 3205| boolean | **true**: The microphone is muted.<br>**false**: The microphone is not muted.| 3206 3207**Example** 3208 3209```ts 3210import { BusinessError } from '@kit.BasicServicesKit'; 3211 3212try { 3213 let value: boolean = audioVolumeGroupManager.isMicrophoneMuteSync(); 3214 console.info(`Indicate that the mute status of the microphone is obtained ${value}.`); 3215} catch (err) { 3216 let error = err as BusinessError; 3217 console.error(`Failed to obtain the mute status of the microphone, error ${error}.`); 3218} 3219``` 3220 3221### on('micStateChange')<sup>9+</sup> 3222 3223on(type: 'micStateChange', callback: Callback<MicStateChangeEvent>): void 3224 3225Subscribes to the microphone state change event, which is triggered when the microphone state is changed. This API uses an asynchronous callback to return the result. 3226 3227Currently, when multiple **AudioManager** instances are used in a single process, only the subscription of the last instance takes effect, and the subscription of other instances is overwritten (even if the last instance does not initiate a subscription). Therefore, you are advised to use a single **AudioManager** instance. 3228 3229**System capability**: SystemCapability.Multimedia.Audio.Volume 3230 3231**Parameters** 3232 3233| Name | Type | Mandatory| Description | 3234| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 3235| type | string | Yes | Event type. The value is fixed at **'micStateChange'**.| 3236| callback | Callback<[MicStateChangeEvent](#micstatechangeevent9)> | Yes | Callback used to return the changed microphone state.| 3237 3238**Error codes** 3239 3240For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3241 3242| ID| Error Message| 3243| ------- | --------------------------------------------| 3244| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3245| 6800101 | Parameter verification failed. | 3246 3247**Example** 3248 3249```ts 3250audioVolumeGroupManager.on('micStateChange', (micStateChange: audio.MicStateChangeEvent) => { 3251 console.info(`Current microphone status is: ${micStateChange.mute} `); 3252}); 3253``` 3254 3255### isVolumeUnadjustable<sup>10+</sup> 3256 3257isVolumeUnadjustable(): boolean 3258 3259Checks whether the fixed volume mode is enabled. When the fixed volume mode is enabled, the volume cannot be adjusted. This API returns the result synchronously. 3260 3261**System capability**: SystemCapability.Multimedia.Audio.Volume 3262 3263**Return value** 3264 3265| Type | Description | 3266| ---------------------- | ------------------------------------------------------ | 3267| boolean | **true**: The fixed volume mode is enabled.<br>**false**: The fixed volume mode is disabled.| 3268 3269**Example** 3270 3271```ts 3272let volumeAdjustSwitch: boolean = audioVolumeGroupManager.isVolumeUnadjustable(); 3273console.info(`Whether it is volume unadjustable: ${volumeAdjustSwitch}.`); 3274``` 3275 3276### getSystemVolumeInDb<sup>10+</sup> 3277 3278getSystemVolumeInDb(volumeType: AudioVolumeType, volumeLevel: number, device: DeviceType, callback: AsyncCallback<number>): void 3279 3280Obtains the volume gain. This API uses an asynchronous callback to return the result. 3281 3282**System capability**: SystemCapability.Multimedia.Audio.Volume 3283 3284**Parameters** 3285 3286| Name | Type | Mandatory| Description | 3287| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 3288| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 3289| volumeLevel | number | Yes | Volume level. | 3290| device | [DeviceType](#devicetype) | Yes | Device type. | 3291| callback | AsyncCallback<number> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the volume gain obtained; otherwise, **err** is an error object.| 3292 3293**Error codes** 3294 3295For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3296 3297| ID| Error Message| 3298| ------- | --------------------------------------------| 3299| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3300| 6800101 | Parameter verification failed. Return by callback. | 3301| 6800301 | System error. Return by callback. | 3302 3303**Example** 3304 3305```ts 3306import { BusinessError } from '@kit.BasicServicesKit'; 3307 3308audioVolumeGroupManager.getSystemVolumeInDb(audio.AudioVolumeType.MEDIA, 3, audio.DeviceType.SPEAKER, (err: BusinessError, dB: number) => { 3309 if (err) { 3310 console.error(`Failed to get the volume DB. ${err}`); 3311 } else { 3312 console.info(`Success to get the volume DB. ${dB}`); 3313 } 3314}); 3315``` 3316### getSystemVolumeInDb<sup>10+</sup> 3317 3318getSystemVolumeInDb(volumeType: AudioVolumeType, volumeLevel: number, device: DeviceType): Promise<number> 3319 3320Obtains the volume gain. This API uses a promise to return the result. 3321 3322**System capability**: SystemCapability.Multimedia.Audio.Volume 3323 3324**Parameters** 3325 3326| Name | Type | Mandatory| Description | 3327| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 3328| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 3329| volumeLevel | number | Yes | Volume level. | 3330| device | [DeviceType](#devicetype) | Yes | Device type. | 3331 3332**Return value** 3333 3334| Type | Description | 3335| --------------------- | ---------------------------------- | 3336| Promise<number> | Promise used to return the volume gain (in dB).| 3337 3338**Error codes** 3339 3340For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3341 3342| ID| Error Message| 3343| ------- | --------------------------------------------| 3344| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3345| 6800101 | Parameter verification failed. Return by promise. | 3346| 6800301 | System error. Return by promise. | 3347 3348**Example** 3349 3350```ts 3351import { BusinessError } from '@kit.BasicServicesKit'; 3352 3353audioVolumeGroupManager.getSystemVolumeInDb(audio.AudioVolumeType.MEDIA, 3, audio.DeviceType.SPEAKER).then((value: number) => { 3354 console.info(`Success to get the volume DB. ${value}`); 3355}).catch((error: BusinessError) => { 3356 console.error(`Fail to adjust the system volume by step. ${error}`); 3357}); 3358``` 3359 3360### getSystemVolumeInDbSync<sup>10+</sup> 3361 3362getSystemVolumeInDbSync(volumeType: AudioVolumeType, volumeLevel: number, device: DeviceType): number 3363 3364Obtains the volume gain. This API returns the result synchronously. 3365 3366**System capability**: SystemCapability.Multimedia.Audio.Volume 3367 3368**Parameters** 3369 3370| Name | Type | Mandatory| Description | 3371| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 3372| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 3373| volumeLevel | number | Yes | Volume level. | 3374| device | [DeviceType](#devicetype) | Yes | Device type. | 3375 3376**Return value** 3377 3378| Type | Description | 3379| --------------------- | ---------------------------------- | 3380| number | Volume gain (in dB).| 3381 3382**Error codes** 3383 3384For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3385 3386| ID| Error Message| 3387| ------- | --------------------------------------------| 3388| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3389| 6800101 | Parameter verification failed. | 3390 3391**Example** 3392 3393```ts 3394import { BusinessError } from '@kit.BasicServicesKit'; 3395 3396try { 3397 let value: number = audioVolumeGroupManager.getSystemVolumeInDbSync(audio.AudioVolumeType.MEDIA, 3, audio.DeviceType.SPEAKER); 3398 console.info(`Success to get the volume DB. ${value}`); 3399} catch (err) { 3400 let error = err as BusinessError; 3401 console.error(`Fail to adjust the system volume by step. ${error}`); 3402} 3403``` 3404 3405### getMaxAmplitudeForInputDevice<sup>12+</sup> 3406 3407getMaxAmplitudeForInputDevice(inputDevice: AudioDeviceDescriptor): Promise<number> 3408 3409Obtains the maximum amplitude of the audio stream for an input device. This API uses a promise to return the result. 3410 3411**System capability**: SystemCapability.Multimedia.Audio.Volume 3412 3413**Parameters** 3414 3415| Name | Type | Mandatory| Description | 3416| ----------- | ------------------------------------- | ---- | --------------------------------------------------- | 3417| inputDevice | [AudioDeviceDescriptor](#audiodevicedescriptor) | Yes | Descriptor of the target device. | 3418 3419**Return value** 3420 3421| Type | Description | 3422| --------------------- | ---------------------------------- | 3423| Promise<number> | Promise used to return the maximum amplitude, which ranges from 0 to 1.| 3424 3425**Error codes** 3426 3427For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3428 3429| ID| Error Message| 3430| ------- | --------------------------------------------| 3431| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3432| 6800101 | Parameter verification failed. Return by promise. | 3433| 6800301 | System error. Return by promise. | 3434 3435**Example** 3436 3437```ts 3438import { BusinessError } from '@kit.BasicServicesKit'; 3439 3440let capturerInfo: audio.AudioCapturerInfo = { 3441 source: audio.SourceType.SOURCE_TYPE_MIC, 3442 capturerFlags: 0 3443}; 3444 3445audio.getAudioManager().getRoutingManager().getPreferredInputDeviceForCapturerInfo(capturerInfo).then((data) => { 3446 audioVolumeGroupManager.getMaxAmplitudeForInputDevice(data[0]).then((value) => { 3447 console.info(`mic volatileume amplitude is: ${value}`); 3448 }).catch((err: BusinessError) => { 3449 console.error("getMaxAmplitudeForInputDevice error" + JSON.stringify(err)); 3450 }) 3451}).catch((err: BusinessError) => { 3452 console.error("get outputDeviceId error" + JSON.stringify(err)); 3453}) 3454``` 3455 3456### getMaxAmplitudeForOutputDevice<sup>12+</sup> 3457 3458getMaxAmplitudeForOutputDevice(outputDevice: AudioDeviceDescriptor): Promise<number> 3459 3460Obtains the maximum amplitude of the audio stream for an output device. This API uses a promise to return the result. 3461 3462**System capability**: SystemCapability.Multimedia.Audio.Volume 3463 3464**Parameters** 3465 3466| Name | Type | Mandatory| Description | 3467| ------------ | --------------------------------------- | ---- | -------------------------------------------------------- | 3468| outputDevice | [AudioDeviceDescriptor](#audiodevicedescriptor) | Yes | Descriptor of the target device. | 3469 3470**Return value** 3471 3472| Type | Description | 3473| --------------------- | ---------------------------------- | 3474| Promise<number> | Promise used to return the maximum amplitude, which ranges from 0 to 1.| 3475 3476**Error codes** 3477 3478For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3479 3480| ID| Error Message| 3481| ------- | --------------------------------------------| 3482| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3483| 6800101 | Parameter verification failed. Return by promise. | 3484| 6800301 | System error. Return by promise. | 3485 3486**Example** 3487 3488```ts 3489import { BusinessError } from '@kit.BasicServicesKit'; 3490 3491let rendererInfo: audio.AudioRendererInfo = { 3492 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 3493 rendererFlags : 0 3494}; 3495 3496audio.getAudioManager().getRoutingManager().getPreferOutputDeviceForRendererInfo(rendererInfo).then((data) => { 3497 audioVolumeGroupManager.getMaxAmplitudeForOutputDevice(data[0]).then((value) => { 3498 console.info(`mic volatileume amplitude is: ${value}`); 3499 }).catch((err: BusinessError) => { 3500 console.error("getMaxAmplitudeForOutputDevice error" + JSON.stringify(err)); 3501 }) 3502}).catch((err: BusinessError) => { 3503 console.error("getPreferOutputDeviceForRendererInfo error" + JSON.stringify(err)); 3504}) 3505``` 3506 3507## AudioStreamManager<sup>9+</sup> 3508 3509Implements audio stream management. Before calling any API in **AudioStreamManager**, you must use [getStreamManager](#getstreammanager9) to obtain an **AudioStreamManager** instance. 3510 3511### getCurrentAudioRendererInfoArray<sup>9+</sup> 3512 3513getCurrentAudioRendererInfoArray(callback: AsyncCallback<AudioRendererChangeInfoArray>): void 3514 3515Obtains the information about the current audio renderer. This API uses an asynchronous callback to return the result. 3516 3517**System capability**: SystemCapability.Multimedia.Audio.Renderer 3518 3519**Parameters** 3520 3521| Name | Type | Mandatory | Description | 3522| -------- | ----------------------------------- | -------- | --------------------------- | 3523| callback | AsyncCallback<[AudioRendererChangeInfoArray](#audiorendererchangeinfoarray9)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the information about the current audio renderer obtained; otherwise, **err** is an error object.| 3524 3525**Example** 3526 3527```ts 3528import { BusinessError } from '@kit.BasicServicesKit'; 3529 3530audioStreamManager.getCurrentAudioRendererInfoArray(async (err: BusinessError, AudioRendererChangeInfoArray: audio.AudioRendererChangeInfoArray) => { 3531 console.info('getCurrentAudioRendererInfoArray **** Get Callback Called ****'); 3532 if (err) { 3533 console.error(`getCurrentAudioRendererInfoArray :ERROR: ${err}`); 3534 } else { 3535 if (AudioRendererChangeInfoArray != null) { 3536 for (let i = 0; i < AudioRendererChangeInfoArray.length; i++) { 3537 let AudioRendererChangeInfo: audio.AudioRendererChangeInfo = AudioRendererChangeInfoArray[i]; 3538 console.info(`StreamId for ${i} is: ${AudioRendererChangeInfo.streamId}`); 3539 console.info(`Content ${i} is: ${AudioRendererChangeInfo.rendererInfo.content}`); 3540 console.info(`Stream ${i} is: ${AudioRendererChangeInfo.rendererInfo.usage}`); 3541 console.info(`Flag ${i} is: ${AudioRendererChangeInfo.rendererInfo.rendererFlags}`); 3542 for (let j = 0;j < AudioRendererChangeInfo.deviceDescriptors.length; j++) { 3543 console.info(`Id: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].id}`); 3544 console.info(`Type: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceType}`); 3545 console.info(`Role: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceRole}`); 3546 console.info(`Name: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].name}`); 3547 console.info(`Address: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].address}`); 3548 console.info(`SampleRate: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].sampleRates[0]}`); 3549 console.info(`ChannelCount: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelCounts[0]}`); 3550 console.info(`ChannelMask: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelMasks[0]}`); 3551 } 3552 } 3553 } 3554 } 3555}); 3556``` 3557 3558### getCurrentAudioRendererInfoArray<sup>9+</sup> 3559 3560getCurrentAudioRendererInfoArray(): Promise<AudioRendererChangeInfoArray> 3561 3562Obtains the information about the current audio renderer. This API uses a promise to return the result. 3563 3564**System capability**: SystemCapability.Multimedia.Audio.Renderer 3565 3566**Return value** 3567 3568| Type | Description | 3569| ---------------------------------------------------------------------------------| --------------------------------------- | 3570| Promise<[AudioRendererChangeInfoArray](#audiorendererchangeinfoarray9)> | Promise used to return the renderer information. | 3571 3572**Example** 3573 3574```ts 3575import { BusinessError } from '@kit.BasicServicesKit'; 3576 3577async function getCurrentAudioRendererInfoArray(){ 3578 await audioStreamManager.getCurrentAudioRendererInfoArray().then((AudioRendererChangeInfoArray: audio.AudioRendererChangeInfoArray) => { 3579 console.info(`getCurrentAudioRendererInfoArray ######### Get Promise is called ##########`); 3580 if (AudioRendererChangeInfoArray != null) { 3581 for (let i = 0; i < AudioRendererChangeInfoArray.length; i++) { 3582 let AudioRendererChangeInfo: audio.AudioRendererChangeInfo = AudioRendererChangeInfoArray[i]; 3583 console.info(`StreamId for ${i} is: ${AudioRendererChangeInfo.streamId}`); 3584 console.info(`Content ${i} is: ${AudioRendererChangeInfo.rendererInfo.content}`); 3585 console.info(`Stream ${i} is: ${AudioRendererChangeInfo.rendererInfo.usage}`); 3586 console.info(`Flag ${i} is: ${AudioRendererChangeInfo.rendererInfo.rendererFlags}`); 3587 for (let j = 0;j < AudioRendererChangeInfo.deviceDescriptors.length; j++) { 3588 console.info(`Id: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].id}`); 3589 console.info(`Type: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceType}`); 3590 console.info(`Role: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceRole}`); 3591 console.info(`Name: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].name}`); 3592 console.info(`Address: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].address}`); 3593 console.info(`SampleRate: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].sampleRates[0]}`); 3594 console.info(`ChannelCount: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelCounts[0]}`); 3595 console.info(`ChannelMask: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelMasks[0]}`); 3596 } 3597 } 3598 } 3599 }).catch((err: BusinessError) => { 3600 console.error(`getCurrentAudioRendererInfoArray :ERROR: ${err}`); 3601 }); 3602} 3603``` 3604### getCurrentAudioRendererInfoArraySync<sup>10+</sup> 3605 3606getCurrentAudioRendererInfoArraySync(): AudioRendererChangeInfoArray 3607 3608Obtains the information about the current audio renderer. This API returns the result synchronously. 3609 3610**System capability**: SystemCapability.Multimedia.Audio.Renderer 3611 3612**Return value** 3613 3614| Type | Description | 3615| ---------------------------------------------------------------------------------| --------------------------------------- | 3616| [AudioRendererChangeInfoArray](#audiorendererchangeinfoarray9) | Audio renderer information. | 3617 3618**Example** 3619 3620```ts 3621import { BusinessError } from '@kit.BasicServicesKit'; 3622 3623try { 3624 let audioRendererChangeInfoArray: audio.AudioRendererChangeInfoArray = audioStreamManager.getCurrentAudioRendererInfoArraySync(); 3625 console.info(`getCurrentAudioRendererInfoArraySync success.`); 3626 if (audioRendererChangeInfoArray != null) { 3627 for (let i = 0; i < audioRendererChangeInfoArray.length; i++) { 3628 let AudioRendererChangeInfo: audio.AudioRendererChangeInfo = audioRendererChangeInfoArray[i]; 3629 console.info(`StreamId for ${i} is: ${AudioRendererChangeInfo.streamId}`); 3630 console.info(`Content ${i} is: ${AudioRendererChangeInfo.rendererInfo.content}`); 3631 console.info(`Stream ${i} is: ${AudioRendererChangeInfo.rendererInfo.usage}`); 3632 console.info(`Flag ${i} is: ${AudioRendererChangeInfo.rendererInfo.rendererFlags}`); 3633 for (let j = 0;j < AudioRendererChangeInfo.deviceDescriptors.length; j++) { 3634 console.info(`Id: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].id}`); 3635 console.info(`Type: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceType}`); 3636 console.info(`Role: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceRole}`); 3637 console.info(`Name: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].name}`); 3638 console.info(`Address: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].address}`); 3639 console.info(`SampleRate: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].sampleRates[0]}`); 3640 console.info(`ChannelCount: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelCounts[0]}`); 3641 console.info(`ChannelMask: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelMasks[0]}`); 3642 } 3643 } 3644 } 3645} catch (err) { 3646 let error = err as BusinessError; 3647 console.error(`getCurrentAudioRendererInfoArraySync :ERROR: ${error}`); 3648} 3649``` 3650 3651### getCurrentAudioCapturerInfoArray<sup>9+</sup> 3652 3653getCurrentAudioCapturerInfoArray(callback: AsyncCallback<AudioCapturerChangeInfoArray>): void 3654 3655Obtains the information about the current audio capturer. This API uses an asynchronous callback to return the result. 3656 3657**System capability**: SystemCapability.Multimedia.Audio.Renderer 3658 3659**Parameters** 3660 3661| Name | Type | Mandatory | Description | 3662| ---------- | ----------------------------------- | --------- | -------------------------------------------------------- | 3663| callback | AsyncCallback<[AudioCapturerChangeInfoArray](#audiocapturerchangeinfoarray9)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the information about the current audio capturer obtained; otherwise, **err** is an error object.| 3664 3665**Example** 3666 3667```ts 3668import { BusinessError } from '@kit.BasicServicesKit'; 3669 3670audioStreamManager.getCurrentAudioCapturerInfoArray(async (err: BusinessError, AudioCapturerChangeInfoArray: audio.AudioCapturerChangeInfoArray) => { 3671 console.info('getCurrentAudioCapturerInfoArray **** Get Callback Called ****'); 3672 if (err) { 3673 console.error(`getCurrentAudioCapturerInfoArray :ERROR: ${err}`); 3674 } else { 3675 if (AudioCapturerChangeInfoArray != null) { 3676 for (let i = 0; i < AudioCapturerChangeInfoArray.length; i++) { 3677 console.info(`StreamId for ${i} is: ${AudioCapturerChangeInfoArray[i].streamId}`); 3678 console.info(`Source for ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.source}`); 3679 console.info(`Flag ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.capturerFlags}`); 3680 for (let j = 0; j < AudioCapturerChangeInfoArray[i].deviceDescriptors.length; j++) { 3681 console.info(`Id: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].id}`); 3682 console.info(`Type: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceType}`); 3683 console.info(`Role: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceRole}`); 3684 console.info(`Name: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].name}`); 3685 console.info(`Address: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].address}`); 3686 console.info(`SampleRate: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].sampleRates[0]}`); 3687 console.info(`ChannelCount: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelCounts[0]}`); 3688 console.info(`ChannelMask: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelMasks[0]}`); 3689 } 3690 } 3691 } 3692 } 3693}); 3694``` 3695 3696### getCurrentAudioCapturerInfoArray<sup>9+</sup> 3697 3698getCurrentAudioCapturerInfoArray(): Promise<AudioCapturerChangeInfoArray> 3699 3700Obtains the information about the current audio capturer. This API uses a promise to return the result. 3701 3702**System capability**: SystemCapability.Multimedia.Audio.Renderer 3703 3704**Return value** 3705 3706| Type | Description | 3707| -----------------------------------------------------------------------------| ----------------------------------- | 3708| Promise<[AudioCapturerChangeInfoArray](#audiocapturerchangeinfoarray9)> | Promise used to return the audio capturer information. | 3709 3710**Example** 3711 3712```ts 3713import { BusinessError } from '@kit.BasicServicesKit'; 3714 3715async function getCurrentAudioCapturerInfoArray(){ 3716 await audioStreamManager.getCurrentAudioCapturerInfoArray().then((AudioCapturerChangeInfoArray: audio.AudioCapturerChangeInfoArray) => { 3717 console.info('getCurrentAudioCapturerInfoArray **** Get Promise Called ****'); 3718 if (AudioCapturerChangeInfoArray != null) { 3719 for (let i = 0; i < AudioCapturerChangeInfoArray.length; i++) { 3720 console.info(`StreamId for ${i} is: ${AudioCapturerChangeInfoArray[i].streamId}`); 3721 console.info(`Source for ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.source}`); 3722 console.info(`Flag ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.capturerFlags}`); 3723 for (let j = 0; j < AudioCapturerChangeInfoArray[i].deviceDescriptors.length; j++) { 3724 console.info(`Id: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].id}`); 3725 console.info(`Type: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceType}`); 3726 console.info(`Role: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceRole}`); 3727 console.info(`Name: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].name}`); 3728 console.info(`Address: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].address}`); 3729 console.info(`SampleRate: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].sampleRates[0]}`); 3730 console.info(`ChannelCount: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelCounts[0]}`); 3731 console.info(`ChannelMask: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelMasks[0]}`); 3732 } 3733 } 3734 } 3735 }).catch((err: BusinessError) => { 3736 console.error(`getCurrentAudioCapturerInfoArray :ERROR: ${err}`); 3737 }); 3738} 3739``` 3740### getCurrentAudioCapturerInfoArraySync<sup>10+</sup> 3741 3742getCurrentAudioCapturerInfoArraySync(): AudioCapturerChangeInfoArray 3743 3744Obtains the information about the current audio capturer. This API returns the result synchronously. 3745 3746**System capability**: SystemCapability.Multimedia.Audio.Capturer 3747 3748**Return value** 3749 3750| Type | Description | 3751| -----------------------------------------------------------------------------| ----------------------------------- | 3752| [AudioCapturerChangeInfoArray](#audiocapturerchangeinfoarray9) | Audio capturer information. | 3753 3754**Example** 3755 3756```ts 3757import { BusinessError } from '@kit.BasicServicesKit'; 3758 3759try { 3760 let audioCapturerChangeInfoArray: audio.AudioCapturerChangeInfoArray = audioStreamManager.getCurrentAudioCapturerInfoArraySync(); 3761 console.info('getCurrentAudioCapturerInfoArraySync success.'); 3762 if (audioCapturerChangeInfoArray != null) { 3763 for (let i = 0; i < audioCapturerChangeInfoArray.length; i++) { 3764 console.info(`StreamId for ${i} is: ${audioCapturerChangeInfoArray[i].streamId}`); 3765 console.info(`Source for ${i} is: ${audioCapturerChangeInfoArray[i].capturerInfo.source}`); 3766 console.info(`Flag ${i} is: ${audioCapturerChangeInfoArray[i].capturerInfo.capturerFlags}`); 3767 for (let j = 0; j < audioCapturerChangeInfoArray[i].deviceDescriptors.length; j++) { 3768 console.info(`Id: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].id}`); 3769 console.info(`Type: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceType}`); 3770 console.info(`Role: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceRole}`); 3771 console.info(`Name: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].name}`); 3772 console.info(`Address: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].address}`); 3773 console.info(`SampleRate: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].sampleRates[0]}`); 3774 console.info(`ChannelCount: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].channelCounts[0]}`); 3775 console.info(`ChannelMask: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].channelMasks[0]}`); 3776 } 3777 } 3778 } 3779} catch (err) { 3780 let error = err as BusinessError; 3781 console.error(`getCurrentAudioCapturerInfoArraySync ERROR: ${error}`); 3782} 3783``` 3784 3785### on('audioRendererChange')<sup>9+</sup> 3786 3787on(type: 'audioRendererChange', callback: Callback<AudioRendererChangeInfoArray>): void 3788 3789Subscribes to the audio renderer change event, which is triggered when the audio playback stream status or device is changed. This API uses an asynchronous callback to return the result. 3790 3791**System capability**: SystemCapability.Multimedia.Audio.Renderer 3792 3793**Parameters** 3794 3795| Name | Type | Mandatory | Description | 3796| -------- | ---------- | --------- | ------------------------------------------------------------------------ | 3797| type | string | Yes | Event type. The value is fixed at **'audioRendererChange'**. | 3798| callback | Callback<[AudioRendererChangeInfoArray](#audiorendererchangeinfoarray9)> | Yes | Callback used to return the audio renderer information.| 3799 3800**Error codes** 3801 3802For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3803 3804| ID| Error Message| 3805| ------- | --------------------------------------------| 3806| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3807| 6800101 | Parameter verification failed. | 3808 3809**Example** 3810 3811```ts 3812audioStreamManager.on('audioRendererChange', (audioRendererChangeInfoArray: audio.AudioRendererChangeInfoArray) => { 3813 for (let i = 0; i < audioRendererChangeInfoArray.length; i++) { 3814 let audioRendererChangeInfo: audio.AudioRendererChangeInfo = audioRendererChangeInfoArray[i]; 3815 console.info(`## RendererChange on is called for ${i} ##`); 3816 console.info(`StreamId for ${i} is: ${audioRendererChangeInfo.streamId}`); 3817 console.info(`Content ${i} is: ${audioRendererChangeInfo.rendererInfo.content}`); 3818 console.info(`Stream ${i} is: ${audioRendererChangeInfo.rendererInfo.usage}`); 3819 console.info(`Flag ${i} is: ${audioRendererChangeInfo.rendererInfo.rendererFlags}`); 3820 for (let j = 0;j < audioRendererChangeInfo.deviceDescriptors.length; j++) { 3821 console.info(`Id: ${i} : ${audioRendererChangeInfo.deviceDescriptors[j].id}`); 3822 console.info(`Type: ${i} : ${audioRendererChangeInfo.deviceDescriptors[j].deviceType}`); 3823 console.info(`Role: ${i} : ${audioRendererChangeInfo.deviceDescriptors[j].deviceRole}`); 3824 console.info(`Name: ${i} : ${audioRendererChangeInfo.deviceDescriptors[j].name}`); 3825 console.info(`Address: ${i} : ${audioRendererChangeInfo.deviceDescriptors[j].address}`); 3826 console.info(`SampleRate: ${i} : ${audioRendererChangeInfo.deviceDescriptors[j].sampleRates[0]}`); 3827 console.info(`ChannelCount: ${i} : ${audioRendererChangeInfo.deviceDescriptors[j].channelCounts[0]}`); 3828 console.info(`ChannelMask: ${i} : ${audioRendererChangeInfo.deviceDescriptors[j].channelMasks[0]}`); 3829 } 3830 } 3831}); 3832``` 3833 3834### off('audioRendererChange')<sup>9+</sup> 3835 3836off(type: 'audioRendererChange'): void 3837 3838Unsubscribes from the audio renderer change event. 3839 3840**System capability**: SystemCapability.Multimedia.Audio.Renderer 3841 3842**Parameters** 3843 3844| Name | Type | Mandatory| Description | 3845| -------- | ------- | ---- | ---------------- | 3846| type | string | Yes | Event type. The value is fixed at **'audioRendererChange'**.| 3847 3848**Error codes** 3849 3850For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3851 3852| ID| Error Message | 3853| ------- |--------------------------| 3854| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3855| 6800101 | Parameter verification failed. | 3856 3857**Example** 3858 3859```ts 3860audioStreamManager.off('audioRendererChange'); 3861``` 3862 3863### on('audioCapturerChange')<sup>9+</sup> 3864 3865on(type: 'audioCapturerChange', callback: Callback<AudioCapturerChangeInfoArray>): void 3866 3867Subscribes to the audio capturer change event, which is triggered when the audio recording stream status or device is changed. This API uses an asynchronous callback to return the result. 3868 3869**System capability**: SystemCapability.Multimedia.Audio.Capturer 3870 3871**Parameters** 3872 3873| Name | Type | Mandatory | Description | 3874| -------- | ------- | --------- | ---------------------------------------------------------------------- | 3875| type | string | Yes | Event type. The value is fixed at **'audioCapturerChange'**. | 3876| callback | Callback<[AudioCapturerChangeInfoArray](#audiocapturerchangeinfoarray9)> | Yes | Callback used to return the audio capturer information.| 3877 3878**Error codes** 3879 3880For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3881 3882| ID| Error Message| 3883| ------- | --------------------------------------------| 3884| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3885| 6800101 | Parameter verification failed. | 3886 3887**Example** 3888 3889```ts 3890audioStreamManager.on('audioCapturerChange', (AudioCapturerChangeInfoArray: audio.AudioCapturerChangeInfoArray) => { 3891 for (let i = 0; i < AudioCapturerChangeInfoArray.length; i++) { 3892 console.info(`## CapChange on is called for element ${i} ##`); 3893 console.info(`StreamId for ${i} is: ${AudioCapturerChangeInfoArray[i].streamId}`); 3894 console.info(`Source for ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.source}`); 3895 console.info(`Flag ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.capturerFlags}`); 3896 for (let j = 0; j < AudioCapturerChangeInfoArray[i].deviceDescriptors.length; j++) { 3897 console.info(`Id: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].id}`); 3898 console.info(`Type: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceType}`); 3899 console.info(`Role: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceRole}`); 3900 console.info(`Name: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].name}`); 3901 console.info(`Address: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].address}`); 3902 console.info(`SampleRate: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].sampleRates[0]}`); 3903 console.info(`ChannelCount: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelCounts[0]}`); 3904 console.info(`ChannelMask: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelMasks[0]}`); 3905 } 3906 } 3907}); 3908``` 3909 3910### off('audioCapturerChange')<sup>9+</sup> 3911 3912off(type: 'audioCapturerChange'): void 3913 3914Unsubscribes from the audio capturer change event. 3915 3916**System capability**: SystemCapability.Multimedia.Audio.Capturer 3917 3918**Parameters** 3919 3920| Name | Type | Mandatory| Description | 3921| -------- | -------- | --- | ------------------------------------------------------------- | 3922| type | string |Yes | Event type. The value is fixed at **'audioCapturerChange'**.| 3923 3924**Error codes** 3925 3926For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3927 3928| ID| Error Message| 3929| ------- | --------------------------------------------| 3930| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3931| 6800101 | Parameter verification failed. | 3932 3933**Example** 3934 3935```ts 3936audioStreamManager.off('audioCapturerChange'); 3937``` 3938 3939### isActive<sup>9+</sup> 3940 3941isActive(volumeType: AudioVolumeType, callback: AsyncCallback<boolean>): void 3942 3943Checks whether a stream is active. This API uses an asynchronous callback to return the result. 3944 3945**System capability**: SystemCapability.Multimedia.Audio.Renderer 3946 3947**Parameters** 3948 3949| Name | Type | Mandatory| Description | 3950| ---------- | ----------------------------------- | ---- | ------------------------------------------------- | 3951| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream types. | 3952| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true** if the stream is active or **false** if not active; otherwise, **err** is an error object.| 3953 3954**Example** 3955 3956```ts 3957import { BusinessError } from '@kit.BasicServicesKit'; 3958 3959audioStreamManager.isActive(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: boolean) => { 3960if (err) { 3961 console.error(`Failed to obtain the active status of the stream. ${err}`); 3962 return; 3963} 3964 console.info(`Callback invoked to indicate that the active status of the stream is obtained ${value}.`); 3965}); 3966``` 3967 3968### isActive<sup>9+</sup> 3969 3970isActive(volumeType: AudioVolumeType): Promise<boolean> 3971 3972Checks whether a stream is active. This API uses a promise to return the result. 3973 3974**System capability**: SystemCapability.Multimedia.Audio.Renderer 3975 3976**Parameters** 3977 3978| Name | Type | Mandatory| Description | 3979| ---------- | ----------------------------------- | ---- | ------------ | 3980| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream types.| 3981 3982**Return value** 3983 3984| Type | Description | 3985| ---------------------- | -------------------------------------------------------- | 3986| 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.| 3987 3988**Example** 3989 3990```ts 3991audioStreamManager.isActive(audio.AudioVolumeType.MEDIA).then((value: boolean) => { 3992 console.info(`Promise returned to indicate that the active status of the stream is obtained ${value}.`); 3993}); 3994``` 3995 3996### isActiveSync<sup>10+</sup> 3997 3998isActiveSync(volumeType: AudioVolumeType): boolean 3999 4000Checks whether a stream is active. This API returns the result synchronously. 4001 4002**System capability**: SystemCapability.Multimedia.Audio.Renderer 4003 4004**Parameters** 4005 4006| Name | Type | Mandatory| Description | 4007| ---------- | ----------------------------------- | ---- | ------------ | 4008| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream types.| 4009 4010**Return value** 4011 4012| Type | Description | 4013| ---------------------- | -------------------------------------------------------- | 4014| boolean | **true**: The stream is active.<br> **false**: The stream is inactive.| 4015 4016**Error codes** 4017 4018For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4019 4020| ID| Error Message| 4021| ------- | --------------------------------------------| 4022| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4023| 6800101 | Parameter verification failed. | 4024 4025**Example** 4026 4027```ts 4028import { BusinessError } from '@kit.BasicServicesKit'; 4029 4030try { 4031 let value: boolean = audioStreamManager.isActiveSync(audio.AudioVolumeType.MEDIA); 4032 console.info(`Indicate that the active status of the stream is obtained ${value}.`); 4033} catch (err) { 4034 let error = err as BusinessError; 4035 console.error(`Failed to obtain the active status of the stream ${error}.`); 4036} 4037``` 4038 4039### getAudioEffectInfoArray<sup>10+</sup> 4040 4041getAudioEffectInfoArray(usage: StreamUsage, callback: AsyncCallback<AudioEffectInfoArray>): void 4042 4043Obtains information about the audio effect mode in use. This API uses an asynchronous callback to return the result. 4044 4045**System capability**: SystemCapability.Multimedia.Audio.Renderer 4046 4047**Parameters** 4048 4049| Name | Type | Mandatory | Description | 4050| -------- | ----------------------------------- | -------- | --------------------------- | 4051| usage | [StreamUsage](#streamusage) | Yes | Audio stream usage. | 4052| callback | AsyncCallback<[AudioEffectInfoArray](#audioeffectinfoarray10)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the information about the audio effect mode obtained; otherwise, **err** is an error object.| 4053 4054**Error codes** 4055 4056For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4057 4058| ID| Error Message| 4059| ------- | --------------------------------------------| 4060| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4061| 6800101 | Parameter verification failed. Return by callback.| 4062 4063**Example** 4064 4065```ts 4066import { BusinessError } from '@kit.BasicServicesKit'; 4067 4068audioStreamManager.getAudioEffectInfoArray(audio.StreamUsage.STREAM_USAGE_MUSIC, async (err: BusinessError, audioEffectInfoArray: audio.AudioEffectInfoArray) => { 4069 console.info('getAudioEffectInfoArray **** Get Callback Called ****'); 4070 if (err) { 4071 console.error(`getAudioEffectInfoArray :ERROR: ${err}`); 4072 return; 4073 } else { 4074 console.info(`The effect modes are: ${audioEffectInfoArray}`); 4075 } 4076}); 4077``` 4078 4079### getAudioEffectInfoArray<sup>10+</sup> 4080 4081getAudioEffectInfoArray(usage: StreamUsage): Promise<AudioEffectInfoArray> 4082 4083Obtains information about the audio effect mode in use. This API uses a promise to return the result. 4084 4085**System capability**: SystemCapability.Multimedia.Audio.Renderer 4086 4087**Parameters** 4088 4089| Name | Type | Mandatory | Description | 4090| -------- | ----------------------------------- | -------- | --------------------------- | 4091| usage | [StreamUsage](#streamusage) | Yes | Audio stream usage. | 4092 4093**Return value** 4094 4095| Type | Description | 4096| --------------------------------------------------------------------------| --------------------------------------- | 4097| Promise<[AudioEffectInfoArray](#audioeffectinfoarray10)> | Promise used to return the information about the audio effect mode obtained. | 4098 4099**Error codes** 4100 4101For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4102 4103| ID| Error Message| 4104| ------- | --------------------------------------------| 4105| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4106| 6800101 | Parameter verification failed. Return by promise. | 4107 4108**Example** 4109 4110```ts 4111import { BusinessError } from '@kit.BasicServicesKit'; 4112 4113audioStreamManager.getAudioEffectInfoArray(audio.StreamUsage.STREAM_USAGE_MUSIC).then((audioEffectInfoArray: audio.AudioEffectInfoArray) => { 4114 console.info('getAudioEffectInfoArray ######### Get Promise is called ##########'); 4115 console.info(`The effect modes are: ${audioEffectInfoArray}`); 4116}).catch((err: BusinessError) => { 4117 console.error(`getAudioEffectInfoArray :ERROR: ${err}`); 4118}); 4119``` 4120 4121### getAudioEffectInfoArraySync<sup>10+</sup> 4122 4123getAudioEffectInfoArraySync(usage: StreamUsage): AudioEffectInfoArray 4124 4125Obtains information about the audio effect mode in use. This API returns the result synchronously. 4126 4127**System capability**: SystemCapability.Multimedia.Audio.Renderer 4128 4129**Parameters** 4130 4131| Name | Type | Mandatory | Description | 4132| -------- | ----------------------------------- | -------- | --------------------------- | 4133| usage | [StreamUsage](#streamusage) | Yes | Audio stream usage. | 4134 4135**Return value** 4136 4137| Type | Description | 4138| --------------------------------------------------------------------------| --------------------------------------- | 4139| [AudioEffectInfoArray](#audioeffectinfoarray10) | Information about the audio effect mode. | 4140 4141**Error codes** 4142 4143For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4144 4145| ID| Error Message| 4146| ------- | --------------------------------------------| 4147| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4148| 6800101 | Parameter verification failed. | 4149 4150**Example** 4151 4152```ts 4153import { BusinessError } from '@kit.BasicServicesKit'; 4154 4155try { 4156 let audioEffectInfoArray: audio.AudioEffectInfoArray = audioStreamManager.getAudioEffectInfoArraySync(audio.StreamUsage.STREAM_USAGE_MUSIC); 4157 console.info(`The effect modes are: ${audioEffectInfoArray}`); 4158} catch (err) { 4159 let error = err as BusinessError; 4160 console.error(`getAudioEffectInfoArraySync ERROR: ${error}`); 4161} 4162``` 4163 4164## AudioRoutingManager<sup>9+</sup> 4165 4166Implements audio routing management. Before calling any API in **AudioRoutingManager**, you must use [getRoutingManager](#getroutingmanager9) to obtain an **AudioRoutingManager** instance. 4167 4168### getDevices<sup>9+</sup> 4169 4170getDevices(deviceFlag: DeviceFlag, callback: AsyncCallback<AudioDeviceDescriptors>): void 4171 4172Obtains the audio devices with a specific flag. This API uses an asynchronous callback to return the result. 4173 4174**System capability**: SystemCapability.Multimedia.Audio.Device 4175 4176**Parameters** 4177 4178| Name | Type | Mandatory| Description | 4179| ---------- | ------------------------------------------------------------ | ---- | -------------------- | 4180| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag. | 4181| callback | AsyncCallback<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the audio devices obtained; otherwise, **err** is an error object.| 4182 4183**Example** 4184 4185```ts 4186import { BusinessError } from '@kit.BasicServicesKit'; 4187 4188audioRoutingManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG, (err: BusinessError, value: audio.AudioDeviceDescriptors) => { 4189 if (err) { 4190 console.error(`Failed to obtain the device list. ${err}`); 4191 return; 4192 } 4193 console.info('Callback invoked to indicate that the device list is obtained.'); 4194}); 4195``` 4196 4197### getDevices<sup>9+</sup> 4198 4199getDevices(deviceFlag: DeviceFlag): Promise<AudioDeviceDescriptors> 4200 4201Obtains the audio devices with a specific flag. This API uses a promise to return the result. 4202 4203**System capability**: SystemCapability.Multimedia.Audio.Device 4204 4205**Parameters** 4206 4207| Name | Type | Mandatory| Description | 4208| ---------- | ------------------------- | ---- | ---------------- | 4209| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag.| 4210 4211**Return value** 4212 4213| Type | Description | 4214| ------------------------------------------------------------ | ------------------------- | 4215| Promise<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Promise used to return the device list.| 4216 4217**Example** 4218 4219```ts 4220audioRoutingManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG).then((data: audio.AudioDeviceDescriptors) => { 4221 console.info('Promise returned to indicate that the device list is obtained.'); 4222}); 4223``` 4224 4225### getDevicesSync<sup>10+</sup> 4226 4227getDevicesSync(deviceFlag: DeviceFlag): AudioDeviceDescriptors 4228 4229Obtains the audio devices with a specific flag. This API returns the result synchronously. 4230 4231**System capability**: SystemCapability.Multimedia.Audio.Device 4232 4233**Parameters** 4234 4235| Name | Type | Mandatory| Description | 4236| ---------- | ------------------------- | ---- | ---------------- | 4237| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag.| 4238 4239**Return value** 4240 4241| Type | Description | 4242| ------------------------------------------------------------ | ------------------------- | 4243| [AudioDeviceDescriptors](#audiodevicedescriptors) | Device list.| 4244 4245**Error codes** 4246 4247For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4248 4249| ID| Error Message| 4250| ------- | --------------------------------------------| 4251| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4252| 6800101 | Parameter verification failed. | 4253 4254**Example** 4255 4256```ts 4257import { BusinessError } from '@kit.BasicServicesKit'; 4258 4259try { 4260 let data: audio.AudioDeviceDescriptors = audioRoutingManager.getDevicesSync(audio.DeviceFlag.OUTPUT_DEVICES_FLAG); 4261 console.info(`Indicate that the device list is obtained ${data}`); 4262} catch (err) { 4263 let error = err as BusinessError; 4264 console.error(`Failed to obtain the device list. ${error}`); 4265} 4266``` 4267 4268### isMicBlockDetectionSupported<sup>13+</sup> 4269 4270isMicBlockDetectionSupported(): Promise<boolean> 4271 4272Checks whether the current device supports microphone blocking detection. This API uses a promise to return the result. 4273 4274**System capability**: SystemCapability.Multimedia.Audio.Device 4275 4276**Return value** 4277 4278| Type | Description | 4279| ---------------------- | ------------------------------------------------------------ | 4280| Promise<boolean> | Promise used to return the check result. The value **true** means that the current device supports microphone blocking detection, and **false** means the opposite.| 4281 4282**Example** 4283 4284```ts 4285audioRoutingManager.isMicBlockDetectionSupported().then((value: boolean) => { 4286 console.info(`Query whether microphone block detection is supported on current device result is ${value}.`); 4287}); 4288``` 4289 4290### on('micBlockStatusChanged')<sup>13+</sup> 4291 4292on(type: 'micBlockStatusChanged', callback: Callback<DeviceBlockStatusInfo\>): void 4293 4294Subscribes to the microphone blocked status change event. This API uses an asynchronous callback to return the result. 4295 4296Before using this API, check whether the current device supports microphone blocking detection. The application receives a callback only when the microphone is used for recording and the microphone's blocked status changes. 4297 4298Currently, this API takes effect only for the microphone on the local device. 4299 4300**System capability**: SystemCapability.Multimedia.Audio.Device 4301 4302**Parameters** 4303 4304| Name | Type | Mandatory| Description | 4305| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- | 4306| type | string | Yes | Event type. The value is fixed at **'micBlockStatusChanged'**.| 4307| callback | Callback<[DeviceBlockStatusInfo](#deviceblockstatusinfo13)\> | Yes | Callback used to return details about whether the microphone is blocked.| 4308 4309**Error codes** 4310 4311For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4312 4313| ID| Error Message| 4314| ------- | --------------------------------------------| 4315| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4316| 6800101 | Parameter verification failed. | 4317 4318**Example** 4319 4320```ts 4321let blockMic: boolean = audioRoutingManager.isMicBlockDetectionSupported(); 4322if (blockMic == true) { 4323 audioRoutingManager.on('micBlockStatusChanged', (micBlockStatusChanged: audio.DeviceBlockStatusInfo) => { 4324 if (micBlockStatusChanged.blockStatus == audio.DeviceBlockStatus.BLOCKED || 4325 micBlockStatusChanged.blockStatus == audio.DeviceBlockStatus.UNBLOCKED) { 4326 console.info(`${Tag}: on_micBlockStatusChanged: SUCCESS`); 4327 } 4328 }); 4329} 4330``` 4331 4332### off('micBlockStatusChanged')<sup>13+</sup> 4333 4334off(type: 'micBlockStatusChanged', callback?: Callback<DeviceBlockStatusInfo\>): void 4335 4336Unsubscribes from the microphone blocked status change event. This API uses an asynchronous callback to return the result. 4337 4338**System capability**: SystemCapability.Multimedia.Audio.Device 4339 4340**Parameters** 4341 4342| Name | Type | Mandatory| Description | 4343| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 4344| type | string | Yes | Event type. The value is fixed at **'micBlockStatusChanged'**.| 4345| callback | Callback<[DeviceBlockStatusInfo](#deviceblockstatusinfo13)\> | No | Callback used to return details about whether the microphone is blocked.| 4346 4347**Error codes** 4348 4349For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4350 4351| ID| Error Message| 4352| ------- | --------------------------------------------| 4353| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4354| 6800101 | Parameter verification failed. | 4355 4356**Example** 4357 4358```ts 4359// Cancel all subscriptions to the event. 4360audioRoutingManager.off('micBlockStatusChanged'); 4361 4362// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 4363let micBlockStatusCallback = (micBlockStatusChanged: audio.DeviceBlockStatusInfo) => { 4364 console.info(`device descriptor size : ${micBlockStatusChanged.deviceDescriptors.length} `); 4365 console.info(`block status : ${micBlockStatusChanged.blockStatus} `); 4366}; 4367 4368audioRoutingManager.on('micBlockStatusChanged', micBlockStatusCallback); 4369 4370audioRoutingManager.off('micBlockStatusChanged', micBlockStatusCallback); 4371``` 4372 4373### on('deviceChange')<sup>9+</sup> 4374 4375on(type: 'deviceChange', deviceFlag: DeviceFlag, callback: Callback<DeviceChangeAction\>): void 4376 4377Subscribes to the audio device change event, which is triggered when the connection status of an audio device is changed. This API uses an asynchronous callback to return the result. 4378 4379**System capability**: SystemCapability.Multimedia.Audio.Device 4380 4381**Parameters** 4382 4383| Name | Type | Mandatory| Description | 4384| :------- | :--------------------------------------------------- | :--- |:------------------------| 4385| type | string | Yes | Event type. The value is fixed at **'deviceChange'**.| 4386| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag. | 4387| callback | Callback<[DeviceChangeAction](#devicechangeaction)\> | Yes | Callback used to return the device change details. | 4388 4389**Error codes** 4390 4391For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4392 4393| ID| Error Message| 4394| ------- | --------------------------------------------| 4395| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4396| 6800101 | Parameter verification failed. | 4397 4398**Example** 4399 4400```ts 4401audioRoutingManager.on('deviceChange', audio.DeviceFlag.OUTPUT_DEVICES_FLAG, (deviceChanged: audio.DeviceChangeAction) => { 4402 console.info('device change type : ' + deviceChanged.type); 4403 console.info('device descriptor size : ' + deviceChanged.deviceDescriptors.length); 4404 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceRole); 4405 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceType); 4406}); 4407``` 4408 4409### off('deviceChange')<sup>9+</sup> 4410 4411off(type: 'deviceChange', callback?: Callback<DeviceChangeAction\>): void 4412 4413Unsubscribes from the audio device change event. This API uses an asynchronous callback to return the result. 4414 4415**System capability**: SystemCapability.Multimedia.Audio.Device 4416 4417**Parameters** 4418 4419| Name | Type | Mandatory| Description | 4420| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 4421| type | string | Yes | Event type. The value is fixed at **'deviceChange'**.| 4422| callback | Callback<[DeviceChangeAction](#devicechangeaction)> | No | Callback used to return the device change details.| 4423 4424**Error codes** 4425 4426For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4427 4428| ID| Error Message| 4429| ------- | --------------------------------------------| 4430| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4431| 6800101 | Parameter verification failed. | 4432 4433**Example** 4434 4435```ts 4436// Cancel all subscriptions to the event. 4437audioRoutingManager.off('deviceChange'); 4438 4439// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 4440let deviceChangeCallback = (deviceChanged: audio.DeviceChangeAction) => { 4441 console.info('device change type : ' + deviceChanged.type); 4442 console.info('device descriptor size : ' + deviceChanged.deviceDescriptors.length); 4443 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceRole); 4444 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceType); 4445}; 4446 4447audioRoutingManager.on('deviceChange', audio.DeviceFlag.OUTPUT_DEVICES_FLAG, deviceChangeCallback); 4448 4449audioRoutingManager.off('deviceChange', deviceChangeCallback); 4450``` 4451 4452### setCommunicationDevice<sup>9+</sup> 4453 4454setCommunicationDevice(deviceType: CommunicationDeviceType, active: boolean, callback: AsyncCallback<void>): void 4455 4456Sets a communication device to the active state. This API uses an asynchronous callback to return the result. 4457 4458This API will be deprecated in a later version due to function design is changed. You are not advised to use it. 4459 4460You are advised to use the [AVCastPicker component](../../media/avsession/using-switch-call-devices.md) provided by AVSession to switch between call devices. 4461 4462**System capability**: SystemCapability.Multimedia.Audio.Communication 4463 4464**Parameters** 4465 4466| Name | Type | Mandatory| Description | 4467| ---------- | ------------------------------------- | ---- |-------------------------| 4468| deviceType | [CommunicationDeviceType](#communicationdevicetype9) | Yes | Communication device type. | 4469| active | boolean | Yes | Active status of the device. The value **true** means to set the device to the active state, and **false** means the opposite.| 4470| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 4471 4472**Example** 4473 4474```ts 4475import { BusinessError } from '@kit.BasicServicesKit'; 4476 4477audioRoutingManager.setCommunicationDevice(audio.CommunicationDeviceType.SPEAKER, true, (err: BusinessError) => { 4478 if (err) { 4479 console.error(`Failed to set the active status of the device. ${err}`); 4480 return; 4481 } 4482 console.info('Callback invoked to indicate that the device is set to the active status.'); 4483}); 4484``` 4485 4486### getAvailableDevices<sup>12+</sup> 4487 4488getAvailableDevices(deviceUsage: DeviceUsage): AudioDeviceDescriptors 4489 4490Obtains the available audio devices. This API returns the result synchronously. 4491 4492**System capability**: SystemCapability.Multimedia.Audio.Device 4493 4494**Parameters** 4495 4496| Name | Type | Mandatory| Description | 4497| ---------- | ------------------------- | ---- | ---------------- | 4498| deviceUsage| [DeviceUsage](#deviceusage12) | Yes | Usage scenario of the device.| 4499 4500**Return value** 4501 4502| Type | Description | 4503| ------------------------------------------------------------ | ------------------------- | 4504| [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | Device list.| 4505 4506**Error codes** 4507 4508For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4509 4510| ID| Error Message| 4511| ------- | --------------------------------------------| 4512| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4513| 6800101 | Parameter verification failed. | 4514 4515**Example** 4516 4517```ts 4518import { BusinessError } from '@kit.BasicServicesKit'; 4519 4520try { 4521 let data: audio.AudioDeviceDescriptors = audioRoutingManager.getAvailableDevices(audio.DeviceUsage.MEDIA_OUTPUT_DEVICES); 4522 console.info(`Indicate that the device list is obtained ${data}`); 4523} catch (err) { 4524 let error = err as BusinessError; 4525 console.error(`Failed to obtain the device list. ${error}`); 4526} 4527``` 4528 4529### on('availableDeviceChange')<sup>12+</sup> 4530 4531on(type: 'availableDeviceChange', deviceUsage: DeviceUsage, callback: Callback<DeviceChangeAction\>): void 4532 4533Subscribes to the available audio device change event, which is triggered when the connection status of available audio devices is changed. This API uses an asynchronous callback to return the result. 4534 4535**System capability**: SystemCapability.Multimedia.Audio.Device 4536 4537**Parameters** 4538 4539| Name | Type | Mandatory| Description | 4540| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- | 4541| type | string | Yes | Event type. The value is fixed at **'availableDeviceChange'**.| 4542| deviceUsage | [DeviceUsage](#deviceusage12) | Yes | Usage scenario of the device. | 4543| callback | Callback<[DeviceChangeAction](js-apis-audio.md#devicechangeaction)\> | Yes | Callback used to return the device change details.| 4544 4545**Error codes** 4546 4547For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4548 4549| ID| Error Message| 4550| ------- | --------------------------------------------| 4551| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4552| 6800101 | Parameter verification failed. | 4553 4554**Example** 4555 4556```ts 4557audioRoutingManager.on('availableDeviceChange', audio.DeviceUsage.MEDIA_OUTPUT_DEVICES, (deviceChanged: audio.DeviceChangeAction) => { 4558 console.info('device change type : ' + deviceChanged.type); 4559 console.info('device descriptor size : ' + deviceChanged.deviceDescriptors.length); 4560 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceRole); 4561 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceType); 4562}); 4563``` 4564 4565### off('availableDeviceChange')<sup>12+</sup> 4566 4567off(type: 'availableDeviceChange', callback?: Callback<DeviceChangeAction\>): void 4568 4569Unsubscribes from the available audio device change event. This API uses an asynchronous callback to return the result. 4570 4571**System capability**: SystemCapability.Multimedia.Audio.Device 4572 4573**Parameters** 4574 4575| Name | Type | Mandatory| Description | 4576| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 4577| type | string | Yes | Event type. The value is fixed at **'availableDeviceChange'**.| 4578| callback | Callback<[DeviceChangeAction](js-apis-audio.md#devicechangeaction)> | No | Callback used to return the available device change details.| 4579 4580**Error codes** 4581 4582For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4583 4584| ID| Error Message| 4585| ------- | --------------------------------------------| 4586| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4587| 6800101 | Parameter verification failed. | 4588 4589**Example** 4590 4591```ts 4592// Cancel all subscriptions to the event. 4593audioRoutingManager.off('availableDeviceChange'); 4594 4595// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 4596let availableDeviceChangeCallback = (deviceChanged: audio.DeviceChangeAction) => { 4597 console.info('device change type : ' + deviceChanged.type); 4598 console.info('device descriptor size : ' + deviceChanged.deviceDescriptors.length); 4599 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceRole); 4600 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceType); 4601}; 4602 4603audioRoutingManager.on('availableDeviceChange', audio.DeviceUsage.MEDIA_OUTPUT_DEVICES, availableDeviceChangeCallback); 4604 4605audioRoutingManager.off('availableDeviceChange', availableDeviceChangeCallback); 4606``` 4607 4608### setCommunicationDevice<sup>9+</sup> 4609 4610setCommunicationDevice(deviceType: CommunicationDeviceType, active: boolean): Promise<void> 4611 4612Sets a communication device to the active state. This API uses a promise to return the result. 4613 4614This API will be deprecated in a later version due to function design is changed. You are not advised to use it. 4615 4616You are advised to use the [AVCastPicker component](../../media/avsession/using-switch-call-devices.md) provided by AVSession to switch between call devices. 4617 4618**System capability**: SystemCapability.Multimedia.Audio.Communication 4619 4620**Parameters** 4621 4622| Name | Type | Mandatory| Description | 4623| ---------- | ----------------------------------------------------- | ---- | ------------------ | 4624| deviceType | [CommunicationDeviceType](#communicationdevicetype9) | Yes | Communication device type.| 4625| active | boolean | Yes | Active status of the device. The value **true** means to set the device to the active state, and **false** means the opposite. | 4626 4627**Return value** 4628 4629| Type | Description | 4630| ------------------- | ------------------------------- | 4631| Promise<void> | Promise that returns no value.| 4632 4633**Example** 4634 4635```ts 4636audioRoutingManager.setCommunicationDevice(audio.CommunicationDeviceType.SPEAKER, true).then(() => { 4637 console.info('Promise returned to indicate that the device is set to the active status.'); 4638}); 4639``` 4640 4641### isCommunicationDeviceActive<sup>9+</sup> 4642 4643isCommunicationDeviceActive(deviceType: CommunicationDeviceType, callback: AsyncCallback<boolean>): void 4644 4645Checks whether a communication device is active. This API uses an asynchronous callback to return the result. 4646 4647**System capability**: SystemCapability.Multimedia.Audio.Communication 4648 4649**Parameters** 4650 4651| Name | Type | Mandatory| Description | 4652| ---------- | ---------------------------------------------------- | ---- | ------------------------ | 4653| deviceType | [CommunicationDeviceType](#communicationdevicetype9) | Yes | Communication device type. | 4654| callback | AsyncCallback<boolean> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is **true** if the communication device is active or **false** if not active; otherwise, **err** is an error object.| 4655 4656**Example** 4657 4658```ts 4659import { BusinessError } from '@kit.BasicServicesKit'; 4660 4661audioRoutingManager.isCommunicationDeviceActive(audio.CommunicationDeviceType.SPEAKER, (err: BusinessError, value: boolean) => { 4662 if (err) { 4663 console.error(`Failed to obtain the active status of the device. ${err}`); 4664 return; 4665 } 4666 console.info('Callback invoked to indicate that the active status of the device is obtained.'); 4667}); 4668``` 4669 4670### isCommunicationDeviceActive<sup>9+</sup> 4671 4672isCommunicationDeviceActive(deviceType: CommunicationDeviceType): Promise<boolean> 4673 4674Checks whether a communication device is active. This API uses a promise to return the result. 4675 4676**System capability**: SystemCapability.Multimedia.Audio.Communication 4677 4678**Parameters** 4679 4680| Name | Type | Mandatory| Description | 4681| ---------- | ---------------------------------------------------- | ---- | ------------------ | 4682| deviceType | [CommunicationDeviceType](#communicationdevicetype9) | Yes | Communication device type.| 4683 4684**Return value** 4685 4686| Type | Description | 4687| ---------------------- | ------------------------------- | 4688| Promise<boolean> | Promise used to return the active status of the device. The value **true** means that the device is active, and **false** means the opposite.| 4689 4690**Example** 4691 4692```ts 4693audioRoutingManager.isCommunicationDeviceActive(audio.CommunicationDeviceType.SPEAKER).then((value: boolean) => { 4694 console.info(`Promise returned to indicate that the active status of the device is obtained ${value}.`); 4695}); 4696``` 4697 4698### isCommunicationDeviceActiveSync<sup>10+</sup> 4699 4700isCommunicationDeviceActiveSync(deviceType: CommunicationDeviceType): boolean 4701 4702Checks whether a communication device is active. This API returns the result synchronously. 4703 4704**System capability**: SystemCapability.Multimedia.Audio.Communication 4705 4706**Parameters** 4707 4708| Name | Type | Mandatory| Description | 4709| ---------- | ---------------------------------------------------- | ---- | ------------------ | 4710| deviceType | [CommunicationDeviceType](#communicationdevicetype9) | Yes | Communication device type.| 4711 4712**Return value** 4713 4714| Type | Description | 4715| ---------------------- | ------------------------------- | 4716| boolean | **true**: The device is active.<br>**false**: The device is inactive.| 4717 4718**Error codes** 4719 4720For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4721 4722| ID| Error Message| 4723| ------- | --------------------------------------------| 4724| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4725| 6800101 | Parameter verification failed. | 4726 4727**Example** 4728 4729```ts 4730import { BusinessError } from '@kit.BasicServicesKit'; 4731 4732try { 4733 let value: boolean = audioRoutingManager.isCommunicationDeviceActiveSync(audio.CommunicationDeviceType.SPEAKER); 4734 console.info(`Indicate that the active status of the device is obtained ${value}.`); 4735} catch (err) { 4736 let error = err as BusinessError; 4737 console.error(`Failed to obtain the active status of the device ${error}.`); 4738} 4739``` 4740 4741### getPreferOutputDeviceForRendererInfo<sup>10+</sup> 4742 4743getPreferOutputDeviceForRendererInfo(rendererInfo: AudioRendererInfo, callback: AsyncCallback<AudioDeviceDescriptors>): void 4744 4745Obtains the output device with the highest priority based on the audio renderer information. This API uses an asynchronous callback to return the result. 4746 4747**System capability**: SystemCapability.Multimedia.Audio.Device 4748 4749**Parameters** 4750 4751| Name | Type | Mandatory| Description | 4752| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 4753| rendererInfo | [AudioRendererInfo](#audiorendererinfo8) | Yes | Audio renderer information. | 4754| callback | AsyncCallback<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the output device with the highest priority obtained; otherwise, **err** is an error object.| 4755 4756**Error codes** 4757 4758For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4759 4760| ID| Error Message | 4761| ------- |--------------------------------------------------| 4762| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4763| 6800101 | Parameter verification failed. Return by callback. | 4764| 6800301 | System error. Return by callback. | 4765 4766**Example** 4767```ts 4768import { audio } from '@kit.AudioKit'; 4769import { BusinessError } from '@kit.BasicServicesKit'; 4770 4771let rendererInfo: audio.AudioRendererInfo = { 4772 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 4773 rendererFlags : 0 4774}; 4775 4776async function getPreferOutputDevice() { 4777 audioRoutingManager.getPreferOutputDeviceForRendererInfo(rendererInfo, (err: BusinessError, desc: audio.AudioDeviceDescriptors) => { 4778 if (err) { 4779 console.error(`Result ERROR: ${err}`); 4780 } else { 4781 console.info(`device descriptor: ${desc}`); 4782 } 4783 }); 4784} 4785``` 4786 4787### getPreferOutputDeviceForRendererInfo<sup>10+</sup> 4788getPreferOutputDeviceForRendererInfo(rendererInfo: AudioRendererInfo): Promise<AudioDeviceDescriptors> 4789 4790Obtains the output device with the highest priority based on the audio renderer information. This API uses a promise to return the result. 4791 4792**System capability**: SystemCapability.Multimedia.Audio.Device 4793 4794**Parameters** 4795 4796| Name | Type | Mandatory| Description | 4797| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 4798| rendererInfo | [AudioRendererInfo](#audiorendererinfo8) | Yes | Audio renderer information. | 4799 4800**Return value** 4801 4802| Type | Description | 4803| --------------------- | --------------------------- | 4804| Promise<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Promise used to return the information about the output device with the highest priority.| 4805 4806**Error codes** 4807 4808For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4809 4810| ID| Error Message | 4811| ------- |-------------------------------------------------| 4812| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4813| 6800101 | Parameter verification failed. Return by promise. | 4814| 6800301 | System error. Return by promise. | 4815 4816**Example** 4817 4818```ts 4819import { audio } from '@kit.AudioKit'; 4820import { BusinessError } from '@kit.BasicServicesKit'; 4821 4822let rendererInfo: audio.AudioRendererInfo = { 4823 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 4824 rendererFlags : 0 4825}; 4826 4827async function getPreferOutputDevice() { 4828 audioRoutingManager.getPreferOutputDeviceForRendererInfo(rendererInfo).then((desc: audio.AudioDeviceDescriptors) => { 4829 console.info(`device descriptor: ${desc}`); 4830 }).catch((err: BusinessError) => { 4831 console.error(`Result ERROR: ${err}`); 4832 }) 4833} 4834``` 4835 4836### getPreferredOutputDeviceForRendererInfoSync<sup>10+</sup> 4837getPreferredOutputDeviceForRendererInfoSync(rendererInfo: AudioRendererInfo): AudioDeviceDescriptors 4838 4839Obtains the output device with the highest priority based on the audio renderer information. This API returns the result synchronously. 4840 4841**System capability**: SystemCapability.Multimedia.Audio.Device 4842 4843**Parameters** 4844 4845| Name | Type | Mandatory| Description | 4846| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 4847| rendererInfo | [AudioRendererInfo](#audiorendererinfo8) | Yes | Audio renderer information. | 4848 4849**Return value** 4850 4851| Type | Description | 4852| --------------------- | --------------------------- | 4853| [AudioDeviceDescriptors](#audiodevicedescriptors) | Information about the output device with the highest priority.| 4854 4855**Error codes** 4856 4857For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4858 4859| ID| Error Message | 4860| ------- |--------------------------| 4861| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4862| 6800101 | Parameter verification failed. | 4863 4864**Example** 4865 4866```ts 4867import { audio } from '@kit.AudioKit'; 4868import { BusinessError } from '@kit.BasicServicesKit'; 4869 4870let rendererInfo: audio.AudioRendererInfo = { 4871 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 4872 rendererFlags : 0 4873}; 4874 4875try { 4876 let desc: audio.AudioDeviceDescriptors = audioRoutingManager.getPreferredOutputDeviceForRendererInfoSync(rendererInfo); 4877 console.info(`device descriptor: ${desc}`); 4878} catch (err) { 4879 let error = err as BusinessError; 4880 console.error(`Result ERROR: ${error}`); 4881} 4882``` 4883 4884### on('preferOutputDeviceChangeForRendererInfo')<sup>10+</sup> 4885 4886on(type: 'preferOutputDeviceChangeForRendererInfo', rendererInfo: AudioRendererInfo, callback: Callback<AudioDeviceDescriptors\>): void 4887 4888Subscribes to the change event of the output device with the highest priority, which is triggered when the output device with the highest priority is changed. This API uses an asynchronous callback to return the result. 4889 4890**System capability**: SystemCapability.Multimedia.Audio.Device 4891 4892**Parameters** 4893 4894| Name | Type | Mandatory| Description | 4895| :------- | :--------------------------------------------------- | :--- |:--------------------------------------------------------| 4896| type | string | Yes | Event type. The value is fixed at **'preferOutputDeviceChangeForRendererInfo'**.| 4897| rendererInfo | [AudioRendererInfo](#audiorendererinfo8) | Yes | Audio renderer information. | 4898| callback | Callback<[AudioDeviceDescriptors](#audiodevicedescriptors)\> | Yes | Callback used to return the information about the output device with the highest priority.| 4899 4900**Error codes** 4901 4902For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4903 4904| ID| Error Message| 4905| ------- | --------------------------------------------| 4906| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4907| 6800101 | Parameter verification failed. | 4908 4909**Example** 4910 4911```ts 4912import { audio } from '@kit.AudioKit'; 4913 4914let rendererInfo: audio.AudioRendererInfo = { 4915 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 4916 rendererFlags : 0 4917}; 4918 4919audioRoutingManager.on('preferOutputDeviceChangeForRendererInfo', rendererInfo, (desc: audio.AudioDeviceDescriptors) => { 4920 console.info(`device descriptor: ${desc}`); 4921}); 4922``` 4923 4924### off('preferOutputDeviceChangeForRendererInfo')<sup>10+</sup> 4925 4926off(type: 'preferOutputDeviceChangeForRendererInfo', callback?: Callback<AudioDeviceDescriptors\>): void 4927 4928Unsubscribes from the change of the output device with the highest priority. This API uses an asynchronous callback to return the result. 4929 4930**System capability**: SystemCapability.Multimedia.Audio.Device 4931 4932**Parameters** 4933 4934| Name | Type | Mandatory| Description | 4935| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 4936| type | string | Yes | Event type. The value is fixed at **'preferOutputDeviceChangeForRendererInfo'**.| 4937| callback | Callback<[AudioDeviceDescriptors](#audiodevicedescriptors)> | No | Callback used to return the information about the output device with the highest priority.| 4938 4939**Error codes** 4940 4941For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4942 4943| ID| Error Message| 4944| ------- | --------------------------------------------| 4945| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4946| 6800101 | Parameter verification failed. | 4947 4948**Example** 4949 4950```ts 4951// Cancel all subscriptions to the event. 4952audioRoutingManager.off('preferOutputDeviceChangeForRendererInfo'); 4953 4954// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 4955let preferOutputDeviceChangeForRendererInfoCallback = (desc: audio.AudioDeviceDescriptors) => { 4956 console.info(`device descriptor: ${desc}`); 4957}; 4958let rendererInfo: audio.AudioRendererInfo = { 4959 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 4960 rendererFlags : 0 4961}; 4962 4963audioRoutingManager.on('preferOutputDeviceChangeForRendererInfo', rendererInfo, preferOutputDeviceChangeForRendererInfoCallback); 4964 4965audioRoutingManager.off('preferOutputDeviceChangeForRendererInfo', preferOutputDeviceChangeForRendererInfoCallback); 4966``` 4967 4968### getPreferredInputDeviceForCapturerInfo<sup>10+</sup> 4969 4970getPreferredInputDeviceForCapturerInfo(capturerInfo: AudioCapturerInfo, callback: AsyncCallback<AudioDeviceDescriptors>): void 4971 4972Obtains the input device with the highest priority based on the audio capturer information. This API uses an asynchronous callback to return the result. 4973 4974**System capability**: SystemCapability.Multimedia.Audio.Device 4975 4976**Parameters** 4977 4978| Name | Type | Mandatory| Description | 4979| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 4980| capturerInfo | [AudioCapturerInfo](#audiocapturerinfo8) | Yes | Audio capturer information. | 4981| callback | AsyncCallback<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the input device with the highest priority obtained; otherwise, **err** is an error object.| 4982 4983**Error codes** 4984 4985For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4986 4987| ID| Error Message| 4988| ------- | --------------------------------------------| 4989| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4990| 6800101 | Parameter verification failed. Return by callback.| 4991| 6800301 | System error. Return by callback. | 4992 4993**Example** 4994```ts 4995import { audio } from '@kit.AudioKit'; 4996import { BusinessError } from '@kit.BasicServicesKit'; 4997 4998let capturerInfo: audio.AudioCapturerInfo = { 4999 source: audio.SourceType.SOURCE_TYPE_MIC, 5000 capturerFlags: 0 5001}; 5002 5003audioRoutingManager.getPreferredInputDeviceForCapturerInfo(capturerInfo, (err: BusinessError, desc: audio.AudioDeviceDescriptors) => { 5004 if (err) { 5005 console.error(`Result ERROR: ${err}`); 5006 } else { 5007 console.info(`device descriptor: ${desc}`); 5008 } 5009}); 5010``` 5011 5012### getPreferredInputDeviceForCapturerInfo<sup>10+</sup> 5013 5014getPreferredInputDeviceForCapturerInfo(capturerInfo: AudioCapturerInfo): Promise<AudioDeviceDescriptors> 5015 5016Obtains the input device with the highest priority based on the audio capturer information. This API uses a promise to return the result. 5017 5018**System capability**: SystemCapability.Multimedia.Audio.Device 5019 5020**Parameters** 5021 5022| Name | Type | Mandatory| Description | 5023| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 5024| capturerInfo | [AudioCapturerInfo](#audiocapturerinfo8) | Yes | Audio capturer information. | 5025 5026**Return value** 5027 5028| Type | Description | 5029| --------------------- | --------------------------- | 5030| Promise<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Promise used to return the information about the input device with the highest priority.| 5031 5032**Error codes** 5033 5034For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5035 5036| ID| Error Message| 5037| ------- | --------------------------------------------| 5038| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5039| 6800101 | Parameter verification failed. Return by promise. | 5040| 6800301 | System error. Return by promise. | 5041 5042**Example** 5043 5044```ts 5045import { audio } from '@kit.AudioKit'; 5046import { BusinessError } from '@kit.BasicServicesKit'; 5047 5048let capturerInfo: audio.AudioCapturerInfo = { 5049 source: audio.SourceType.SOURCE_TYPE_MIC, 5050 capturerFlags: 0 5051}; 5052 5053audioRoutingManager.getPreferredInputDeviceForCapturerInfo(capturerInfo).then((desc: audio.AudioDeviceDescriptors) => { 5054 console.info(`device descriptor: ${desc}`); 5055}).catch((err: BusinessError) => { 5056 console.error(`Result ERROR: ${err}`); 5057}); 5058``` 5059 5060### getPreferredInputDeviceForCapturerInfoSync<sup>10+</sup> 5061 5062getPreferredInputDeviceForCapturerInfoSync(capturerInfo: AudioCapturerInfo): AudioDeviceDescriptors 5063 5064Obtains the input device with the highest priority based on the audio capturer information. This API returns the result synchronously. 5065 5066**System capability**: SystemCapability.Multimedia.Audio.Device 5067 5068**Parameters** 5069 5070| Name | Type | Mandatory| Description | 5071| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 5072| capturerInfo | [AudioCapturerInfo](#audiocapturerinfo8) | Yes | Audio capturer information. | 5073 5074**Return value** 5075 5076| Type | Description | 5077| --------------------- | --------------------------- | 5078| [AudioDeviceDescriptors](#audiodevicedescriptors) | Information about the input device with the highest priority.| 5079 5080**Error codes** 5081 5082For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5083 5084| ID| Error Message| 5085| ------- | --------------------------------------------| 5086| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5087| 6800101 | Parameter verification failed. | 5088 5089**Example** 5090 5091```ts 5092import { audio } from '@kit.AudioKit'; 5093import { BusinessError } from '@kit.BasicServicesKit'; 5094 5095let capturerInfo: audio.AudioCapturerInfo = { 5096 source: audio.SourceType.SOURCE_TYPE_MIC, 5097 capturerFlags: 0 5098}; 5099 5100try { 5101 let desc: audio.AudioDeviceDescriptors = audioRoutingManager.getPreferredInputDeviceForCapturerInfoSync(capturerInfo); 5102 console.info(`device descriptor: ${desc}`); 5103} catch (err) { 5104 let error = err as BusinessError; 5105 console.error(`Result ERROR: ${error}`); 5106} 5107``` 5108 5109### on('preferredInputDeviceChangeForCapturerInfo')<sup>10+</sup> 5110 5111on(type: 'preferredInputDeviceChangeForCapturerInfo', capturerInfo: AudioCapturerInfo, callback: Callback<AudioDeviceDescriptors\>): void 5112 5113Subscribes to the change event of the input device with the highest priority, which is triggered when the input device with the highest priority is changed. This API uses an asynchronous callback to return the result. 5114 5115**System capability**: SystemCapability.Multimedia.Audio.Device 5116 5117**Parameters** 5118 5119| Name | Type | Mandatory| Description | 5120| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- | 5121| type | string | Yes | Event type. The value is fixed at **'preferredInputDeviceChangeForCapturerInfo'**.| 5122| capturerInfo | [AudioCapturerInfo](#audiocapturerinfo8) | Yes | Audio capturer information. | 5123| callback | Callback<[AudioDeviceDescriptors](#audiodevicedescriptors)\> | Yes | Callback used to return the information about the input device with the highest priority.| 5124 5125**Error codes** 5126 5127For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5128 5129| ID| Error Message| 5130| ------- | --------------------------------------------| 5131| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5132| 6800101 | Parameter verification failed. | 5133 5134**Example** 5135 5136```ts 5137import { audio } from '@kit.AudioKit'; 5138 5139let capturerInfo: audio.AudioCapturerInfo = { 5140 source: audio.SourceType.SOURCE_TYPE_MIC, 5141 capturerFlags: 0 5142}; 5143 5144audioRoutingManager.on('preferredInputDeviceChangeForCapturerInfo', capturerInfo, (desc: audio.AudioDeviceDescriptors) => { 5145 console.info(`device descriptor: ${desc}`); 5146}); 5147``` 5148 5149### off('preferredInputDeviceChangeForCapturerInfo')<sup>10+</sup> 5150 5151off(type: 'preferredInputDeviceChangeForCapturerInfo', callback?: Callback<AudioDeviceDescriptors\>): void 5152 5153Unsubscribes from the change of the input device with the highest priority. This API uses an asynchronous callback to return the result. 5154 5155**System capability**: SystemCapability.Multimedia.Audio.Device 5156 5157**Parameters** 5158 5159| Name | Type | Mandatory| Description | 5160| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 5161| type | string | Yes | Event type. The value is fixed at **'preferredInputDeviceChangeForCapturerInfo'**.| 5162| callback | Callback<[AudioDeviceDescriptors](#audiodevicedescriptors)> | No | Callback used to return the information about the input device with the highest priority.| 5163 5164**Error codes** 5165 5166For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5167 5168| ID| Error Message| 5169| ------- | --------------------------------------------| 5170| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5171| 6800101 | Parameter verification failed. | 5172 5173**Example** 5174 5175```ts 5176// Cancel all subscriptions to the event. 5177audioRoutingManager.off('preferredInputDeviceChangeForCapturerInfo'); 5178 5179// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 5180let preferredInputDeviceChangeForCapturerInfoCallback = (desc: audio.AudioDeviceDescriptors) => { 5181 console.info(`device descriptor: ${desc}`); 5182}; 5183let capturerInfo: audio.AudioCapturerInfo = { 5184 source: audio.SourceType.SOURCE_TYPE_MIC, 5185 capturerFlags: 0 5186}; 5187 5188audioRoutingManager.on('preferredInputDeviceChangeForCapturerInfo', capturerInfo, preferredInputDeviceChangeForCapturerInfoCallback); 5189 5190audioRoutingManager.off('preferredInputDeviceChangeForCapturerInfo', preferredInputDeviceChangeForCapturerInfoCallback); 5191``` 5192 5193## AudioSessionManager<sup>12+</sup> 5194 5195Manages audio sessions. Before calling an API in **AudioSessionManager**, you must use [getSessionManager](#getsessionmanager12) to obtain an **AudioSessionManager** instance. 5196 5197### activateAudioSession<sup>12+</sup> 5198 5199activateAudioSession(strategy: AudioSessionStrategy): Promise\<void> 5200 5201Activates an audio session. This API uses a promise to return the result. 5202 5203**System capability**: SystemCapability.Multimedia.Audio.Core 5204 5205**Parameters** 5206 5207| Name| Type | Mandatory| Description | 5208| ------ |-------------------------------------------------| ---- | ------------ | 5209| strategy | [AudioSessionStrategy](#audiosessionstrategy12) | Yes | Audio session strategy.| 5210 5211**Return value** 5212 5213| Type | Description | 5214| -------------- | ------------------------- | 5215| Promise\<void> | Promise that returns no value.| 5216 5217**Error codes** 5218 5219For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5220 5221| ID| Error Message| 5222| ------- | ---------------------------------------------| 5223| 401 | Parameter error. Possible causes: 1.Mandatory parameters unspecified. 2.Incorrect parameter types. | 5224| 6800101 | Parameter verification failed.| 5225| 6800301 | System error. Returned by promise. | 5226 5227**Example** 5228 5229```ts 5230import { BusinessError } from '@kit.BasicServicesKit'; 5231 5232let strategy: audio.AudioSessionStrategy = { 5233 concurrencyMode: audio.AudioConcurrencyMode.CONCURRENCY_MIX_WITH_OTHERS 5234}; 5235 5236audioSessionManager.activateAudioSession(strategy).then(() => { 5237 console.info('activateAudioSession SUCCESS'); 5238}).catch((err: BusinessError) => { 5239 console.error(`ERROR: ${err}`); 5240}); 5241``` 5242 5243### deactivateAudioSession<sup>12+</sup> 5244 5245deactivateAudioSession(): Promise\<void> 5246 5247Deactivates this audio session. This API uses a promise to return the result. 5248 5249**System capability**: SystemCapability.Multimedia.Audio.Core 5250 5251**Return value** 5252 5253| Type | Description | 5254| -------------- | ------------------------- | 5255| Promise\<void> | Promise that returns no value.| 5256 5257**Error codes** 5258 5259For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5260 5261| ID| Error Message| 5262| ------- | ---------------------------------------------| 5263| 6800301 | System error. Returned by promise. | 5264 5265**Example** 5266 5267```ts 5268import { BusinessError } from '@kit.BasicServicesKit'; 5269 5270audioSessionManager.deactivateAudioSession().then(() => { 5271 console.info('deactivateAudioSession SUCCESS'); 5272}).catch((err: BusinessError) => { 5273 console.error(`ERROR: ${err}`); 5274}); 5275``` 5276 5277### isAudioSessionActivated<sup>12+</sup> 5278 5279isAudioSessionActivated(): boolean 5280 5281Checks whether this audio session is activated. 5282 5283**System capability**: SystemCapability.Multimedia.Audio.Core 5284 5285**Return value** 5286 5287| Type | Description | 5288| ------------------------------------------------- |---------------------------------------| 5289| boolean | Returns **true** if the audio session is activated; returns **false** otherwise.| 5290 5291**Example** 5292 5293```ts 5294let isActivated = audioSessionManager.isAudioSessionActivated(); 5295``` 5296 5297### on('audioSessionDeactivated')<sup>12+</sup> 5298 5299on(type: 'audioSessionDeactivated', callback: Callback\<AudioSessionDeactivatedEvent>): void 5300 5301Subscribes to the audio session deactivation event, which is triggered when an audio session is deactivated. This API uses an asynchronous callback to return the result. 5302 5303**System capability**: SystemCapability.Multimedia.Audio.Core 5304 5305**Parameters** 5306 5307| Name | Type | Mandatory| Description | 5308| -------- |---------------------------------------------------------------------------| ---- | ------------------------------------------------------------ | 5309| type | string | Yes | Event type. The value is fixed at **'audioSessionDeactivated'**.| 5310| callback | Callback<[AudioSessionDeactivatedEvent](#audiosessiondeactivatedevent12)> | Yes | Callback used to return the reason why the audio session is deactivated.| 5311 5312**Error codes** 5313 5314For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5315 5316| ID| Error Message| 5317| ------- | --------------------------------------------| 5318| 401 | Parameter error. Possible causes: 1.Mandatory parameters unspecified. 2.Incorrect parameter types. | 5319| 6800101 | Parameter verification failed. | 5320 5321**Example** 5322 5323```ts 5324audioSessionManager.on('audioSessionDeactivated', (audioSessionDeactivatedEvent: audio.AudioSessionDeactivatedEvent) => { 5325 console.info(`reason of audioSessionDeactivated: ${audioSessionDeactivatedEvent.reason} `); 5326}); 5327``` 5328 5329### off('audioSessionDeactivated')<sup>12+</sup> 5330 5331off(type: 'audioSessionDeactivated', callback?: Callback\<AudioSessionDeactivatedEvent>): void 5332 5333Unsubscribes from the audio session deactivation event. This API uses an asynchronous callback to return the result. 5334 5335**System capability**: SystemCapability.Multimedia.Audio.Core 5336 5337**Parameters** 5338 5339| Name | Type | Mandatory| Description | 5340| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 5341| type | string | Yes | Event type. The value is fixed at **'audioSessionDeactivated'**.| 5342| callback |Callback<[AudioSessionDeactivatedEvent](#audiosessiondeactivatedevent12)> | No | Callback used to return the reason why the audio session is deactivated.| 5343 5344**Error codes** 5345 5346For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5347 5348| ID| Error Message| 5349| ------- | --------------------------------------------| 5350| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5351| 6800101 | Parameter verification failed. | 5352 5353**Example** 5354 5355```ts 5356// Cancel all subscriptions to the event. 5357audioSessionManager.off('audioSessionDeactivated'); 5358 5359// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 5360let audioSessionDeactivatedCallback = (audioSessionDeactivatedEvent: audio.AudioSessionDeactivatedEvent) => { 5361 console.info(`reason of audioSessionDeactivated: ${audioSessionDeactivatedEvent.reason} `); 5362}; 5363 5364audioSessionManager.on('audioSessionDeactivated', audioSessionDeactivatedCallback); 5365 5366audioSessionManager.off('audioSessionDeactivated', audioSessionDeactivatedCallback); 5367``` 5368 5369## AudioRendererChangeInfoArray<sup>9+</sup> 5370 5371type AudioRendererChangeInfoArray = Array<Readonly<AudioRendererChangeInfo>> 5372 5373Defines an **AudioRenderChangeInfo** array, which is read-only. 5374 5375**System capability**: SystemCapability.Multimedia.Audio.Renderer 5376 5377| Type | Description | 5378|---------|---------------------------------------------------------------| 5379| Array<Readonly<AudioRendererChangeInfo>> | Defines an [AudioRenderChangeInfo](#audiorendererchangeinfo9) array, which is read-only.| 5380 5381## AudioRendererChangeInfo<sup>9+</sup> 5382 5383Describes the audio renderer change event. 5384 5385**System capability**: SystemCapability.Multimedia.Audio.Renderer 5386 5387| Name | Type | Readable| Writable| Description | 5388| -------------------| ----------------------------------------- | ---- | ---- | ---------------------------- | 5389| streamId | number | Yes | No | Unique ID of an audio stream. | 5390| rendererInfo | [AudioRendererInfo](#audiorendererinfo8) | Yes | No | Audio renderer information. | 5391| deviceDescriptors | [AudioDeviceDescriptors](#audiodevicedescriptors) | Yes | No | Audio device description.| 5392 5393**Example** 5394 5395```ts 5396import { audio } from '@kit.AudioKit'; 5397 5398const audioManager = audio.getAudioManager(); 5399let audioStreamManager = audioManager.getStreamManager(); 5400 5401audioStreamManager.on('audioRendererChange', (AudioRendererChangeInfoArray) => { 5402 for (let i = 0; i < AudioRendererChangeInfoArray.length; i++) { 5403 console.info(`## RendererChange on is called for ${i} ##`); 5404 console.info(`StreamId for ${i} is: ${AudioRendererChangeInfoArray[i].streamId}`); 5405 console.info(`Content for ${i} is: ${AudioRendererChangeInfoArray[i].rendererInfo.content}`); 5406 console.info(`Stream for ${i} is: ${AudioRendererChangeInfoArray[i].rendererInfo.usage}`); 5407 console.info(`Flag ${i} is: ${AudioRendererChangeInfoArray[i].rendererInfo.rendererFlags}`); 5408 let devDescriptor = AudioRendererChangeInfoArray[i].deviceDescriptors; 5409 for (let j = 0; j < AudioRendererChangeInfoArray[i].deviceDescriptors.length; j++) { 5410 console.info(`Id: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].id}`); 5411 console.info(`Type: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].deviceType}`); 5412 console.info(`Role: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].deviceRole}`); 5413 console.info(`Name: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].name}`); 5414 console.info(`Addr: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].address}`); 5415 console.info(`SR: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].sampleRates[0]}`); 5416 console.info(`C ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].channelCounts[0]}`); 5417 console.info(`CM: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].channelMasks[0]}`); 5418 } 5419 } 5420}); 5421``` 5422 5423 5424## AudioCapturerChangeInfoArray<sup>9+</sup> 5425 5426type AudioCapturerChangeInfoArray = Array<Readonly<AudioCapturerChangeInfo>> 5427 5428Defines an **AudioCapturerChangeInfo** array, which is read-only. 5429 5430**System capability**: SystemCapability.Multimedia.Audio.Capturer 5431 5432| Type | Description | 5433|---------|-----------------------------------------------------------------| 5434| Array<Readonly<AudioCapturerChangeInfo>> | An [AudioCapturerChangeInfo](#audiocapturerchangeinfo9) array, which is read-only.| 5435 5436## AudioCapturerChangeInfo<sup>9+</sup> 5437 5438Describes the audio capturer change event. 5439 5440**System capability**: SystemCapability.Multimedia.Audio.Capturer 5441 5442| Name | Type | Readable| Writable| Description | 5443| -------------------| ----------------------------------------- | ---- | ---- | ---------------------------- | 5444| streamId | number | Yes | No | Unique ID of an audio stream. | 5445| capturerInfo | [AudioCapturerInfo](#audiocapturerinfo8) | Yes | No | Audio capturer information. | 5446| deviceDescriptors | [AudioDeviceDescriptors](#audiodevicedescriptors) | Yes | No | Audio device description.| 5447| muted<sup>11+</sup> | boolean | Yes | No | Whether the audio capturer is muted. The value **true** means that the audio capturer is muted, and **false** means the opposite.| 5448 5449**Example** 5450 5451```ts 5452import { audio } from '@kit.AudioKit'; 5453 5454const audioManager = audio.getAudioManager(); 5455let audioStreamManager = audioManager.getStreamManager(); 5456 5457audioStreamManager.on('audioCapturerChange', (AudioCapturerChangeInfoArray) => { 5458 for (let i = 0; i < AudioCapturerChangeInfoArray.length; i++) { 5459 console.info(`## CapChange on is called for element ${i} ##`); 5460 console.info(`StrId for ${i} is: ${AudioCapturerChangeInfoArray[i].streamId}`); 5461 console.info(`Src for ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.source}`); 5462 console.info(`Flag ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.capturerFlags}`); 5463 let devDescriptor = AudioCapturerChangeInfoArray[i].deviceDescriptors; 5464 for (let j = 0; j < AudioCapturerChangeInfoArray[i].deviceDescriptors.length; j++) { 5465 console.info(`Id: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].id}`); 5466 console.info(`Type: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceType}`); 5467 console.info(`Role: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceRole}`); 5468 console.info(`Name: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].name}`); 5469 console.info(`Addr: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].address}`); 5470 console.info(`SR: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].sampleRates[0]}`); 5471 console.info(`C ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelCounts[0]}`); 5472 console.info(`CM ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelMasks[0]}`); 5473 } 5474 } 5475}); 5476``` 5477 5478## AudioEffectInfoArray<sup>10+</sup> 5479 5480type AudioEffectInfoArray = Array<Readonly<AudioEffectMode>> 5481 5482Defines an array that contains the audio effect mode corresponding to a specific audio content type (specified by **ContentType**) and audio stream usage (specified by **StreamUsage**). The [AudioEffectMode](#audioeffectmode10) array is read-only. 5483 5484**System capability**: SystemCapability.Multimedia.Audio.Renderer 5485 5486| Type | Description | 5487|---------|---------------------------------------------------------------| 5488| Array<Readonly<AudioEffectMode>> | Defines an array that contains the audio effect mode corresponding to a specific audio content type (specified by **ContentType**) and audio stream usage (specified by **StreamUsage**). The [AudioEffectMode](#audioeffectmode10) array is read-only.| 5489 5490## AudioDeviceDescriptors 5491 5492type AudioDeviceDescriptors = Array<Readonly<AudioDeviceDescriptor>> 5493 5494Defines an [AudioDeviceDescriptor](#audiodevicedescriptor) array, which is read-only. 5495 5496**Atomic service API**: This API can be used in atomic services since API version 12. 5497 5498**System capability**: SystemCapability.Multimedia.Audio.Device 5499 5500| Type | Description | 5501|---------|---------------------------------------------------------------| 5502| Array<Readonly<AudioDeviceDescriptor>> | Defines an [AudioDeviceDescriptor](#audiodevicedescriptor) array, which is read-only.| 5503 5504## AudioDeviceDescriptor 5505 5506Describes an audio device. 5507 5508**Atomic service API**: This API can be used in atomic services since API version 12. 5509 5510| Name | Type | Readable| Writable| Description | 5511| ----------------------------- | -------------------------- | ---- | ---- | ---------- | 5512| deviceRole | [DeviceRole](#devicerole) | Yes | No | Device role.<br> **System capability**: SystemCapability.Multimedia.Audio.Device| 5513| deviceType | [DeviceType](#devicetype) | Yes | No | Device type.<br> **System capability**: SystemCapability.Multimedia.Audio.Device| 5514| id<sup>9+</sup> | number | Yes | No | Device ID, which is unique.<br> **System capability**: SystemCapability.Multimedia.Audio.Device| 5515| name<sup>9+</sup> | string | Yes | No | Device name.<br>For a Bluetooth device, you must request the **ohos.permission.USE_BLUETOOTH** permission.<br> **System capability**: SystemCapability.Multimedia.Audio.Device| 5516| address<sup>9+</sup> | string | Yes | No | Device address.<br>For a Bluetooth device, you must request the **ohos.permission.USE_BLUETOOTH** permission.<br> **System capability**: SystemCapability.Multimedia.Audio.Device| 5517| sampleRates<sup>9+</sup> | Array<number> | Yes | No | Supported sampling rates.<br> **System capability**: SystemCapability.Multimedia.Audio.Device| 5518| channelCounts<sup>9+</sup> | Array<number> | Yes | No | Number of channels supported.<br> **System capability**: SystemCapability.Multimedia.Audio.Device| 5519| channelMasks<sup>9+</sup> | Array<number> | Yes | No | Supported channel masks.<br> **System capability**: SystemCapability.Multimedia.Audio.Device| 5520| displayName<sup>10+</sup> | string | Yes | No | Display name of the device.<br> **System capability**: SystemCapability.Multimedia.Audio.Device| 5521| encodingTypes<sup>11+</sup> | Array<[AudioEncodingType](#audioencodingtype8)> | Yes | No | Supported encoding types.<br> **System capability**: SystemCapability.Multimedia.Audio.Core| 5522 5523**Example** 5524 5525```ts 5526import { audio } from '@kit.AudioKit'; 5527 5528function displayDeviceProp(value: audio.AudioDeviceDescriptor) { 5529 deviceRoleValue = value.deviceRole; 5530 deviceTypeValue = value.deviceType; 5531} 5532 5533let deviceRoleValue: audio.DeviceRole | undefined = undefined; 5534let deviceTypeValue: audio.DeviceType | undefined = undefined; 5535audio.getAudioManager().getRoutingManager().getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG).then((value: audio.AudioDeviceDescriptors) => { 5536 console.info('AudioFrameworkTest: Promise: getDevices OUTPUT_DEVICES_FLAG'); 5537 value.forEach(displayDeviceProp); 5538 if (deviceTypeValue != undefined && deviceRoleValue != undefined){ 5539 console.info('AudioFrameworkTest: Promise: getDevices : OUTPUT_DEVICES_FLAG : PASS'); 5540 } else { 5541 console.error('AudioFrameworkTest: Promise: getDevices : OUTPUT_DEVICES_FLAG : FAIL'); 5542 } 5543}); 5544``` 5545## AudioDataCallbackResult<sup>12+</sup> 5546 5547Enumerates the audio data callback results. 5548 5549**System capability**: SystemCapability.Multimedia.Audio.Core 5550 5551| Name | Value | Description | 5552| ---------------------| --------| ----------------- | 5553| INVALID | -1 | The callback data is invalid. | 5554| VALID | 0 | The callback data is valid. | 5555 5556## AudioRendererWriteDataCallback<sup>12+</sup> 5557 5558type AudioRendererWriteDataCallback = (data: ArrayBuffer) => AudioDataCallbackResult | void 5559 5560Defines the callback function used to write data to the audio renderer. Once the callback function finishes its execution, the audio service queues the data pointed to by **data** for playback. Therefore, do not change the data outside the callback. It is crucial to fill **data** with the exact length of data designated for playback; otherwise, noises may occur during playback. 5561 5562**System capability**: SystemCapability.Multimedia.Audio.Renderer 5563 5564**Parameters** 5565 5566| Name | Type |Mandatory | Description | 5567| :--------------| :--------| :----- | :------------ | 5568| data | ArrayBuffer | Yes| Data to be written to the buffer.| 5569 5570**Return value** 5571 5572| Type | Description | 5573|--------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------| 5574| [AudioDataCallbackResult](#audiodatacallbackresult12) \| void | If **void** or **AudioDataCallbackResult.VALID** is returned, the data is valid and the audio data is played. If **AudioDataCallbackResult.INVALID** is returned, the data is invalid and the audio data is not played.| 5575 5576## AudioRenderer<sup>8+</sup> 5577 5578Provides APIs for audio rendering. Before calling any API in **AudioRenderer**, you must use [createAudioRenderer](#audiocreateaudiorenderer8) to create an **AudioRenderer** instance. 5579 5580### Attributes 5581 5582**System capability**: SystemCapability.Multimedia.Audio.Renderer 5583 5584| Name | Type | Readable| Writable| Description | 5585| ----- | -------------------------- | ---- | ---- | ------------------ | 5586| state<sup>8+</sup> | [AudioState](#audiostate8) | Yes | No | Audio renderer state.| 5587 5588**Example** 5589 5590```ts 5591import { audio } from '@kit.AudioKit'; 5592 5593let state: audio.AudioState = audioRenderer.state; 5594``` 5595 5596### getRendererInfo<sup>8+</sup> 5597 5598getRendererInfo(callback: AsyncCallback<AudioRendererInfo\>): void 5599 5600Obtains the renderer information of this **AudioRenderer** instance. This API uses an asynchronous callback to return the result. 5601 5602**System capability**: SystemCapability.Multimedia.Audio.Renderer 5603 5604**Parameters** 5605 5606| Name | Type | Mandatory| Description | 5607| :------- | :------------------------------------------------------- | :--- | :--------------------- | 5608| callback | AsyncCallback<[AudioRendererInfo](#audiorendererinfo8)\> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the renderer information obtained; otherwise, **err** is an error object.| 5609 5610**Example** 5611 5612```ts 5613import { BusinessError } from '@kit.BasicServicesKit'; 5614 5615audioRenderer.getRendererInfo((err: BusinessError, rendererInfo: audio.AudioRendererInfo) => { 5616 console.info('Renderer GetRendererInfo:'); 5617 console.info(`Renderer content: ${rendererInfo.content}`); 5618 console.info(`Renderer usage: ${rendererInfo.usage}`); 5619 console.info(`Renderer flags: ${rendererInfo.rendererFlags}`); 5620}); 5621``` 5622 5623### getRendererInfo<sup>8+</sup> 5624 5625getRendererInfo(): Promise<AudioRendererInfo\> 5626 5627Obtains the renderer information of this **AudioRenderer** instance. This API uses a promise to return the result. 5628 5629**System capability**: SystemCapability.Multimedia.Audio.Renderer 5630 5631**Return value** 5632 5633| Type | Description | 5634| -------------------------------------------------- | ------------------------------- | 5635| Promise<[AudioRendererInfo](#audiorendererinfo8)\> | Promise used to return the renderer information.| 5636 5637**Example** 5638 5639```ts 5640import { BusinessError } from '@kit.BasicServicesKit'; 5641 5642audioRenderer.getRendererInfo().then((rendererInfo: audio.AudioRendererInfo) => { 5643 console.info('Renderer GetRendererInfo:'); 5644 console.info(`Renderer content: ${rendererInfo.content}`); 5645 console.info(`Renderer usage: ${rendererInfo.usage}`); 5646 console.info(`Renderer flags: ${rendererInfo.rendererFlags}`) 5647}).catch((err: BusinessError) => { 5648 console.error(`AudioFrameworkRenderLog: RendererInfo :ERROR: ${err}`); 5649}); 5650``` 5651 5652### getRendererInfoSync<sup>10+</sup> 5653 5654getRendererInfoSync(): AudioRendererInfo 5655 5656Obtains the renderer information of this **AudioRenderer** instance. This API returns the result synchronously. 5657 5658**System capability**: SystemCapability.Multimedia.Audio.Renderer 5659 5660**Return value** 5661 5662| Type | Description | 5663| -------------------------------------------------- | ------------------------------- | 5664| [AudioRendererInfo](#audiorendererinfo8) | Audio renderer information.| 5665 5666**Example** 5667 5668```ts 5669import { BusinessError } from '@kit.BasicServicesKit'; 5670 5671try { 5672 let rendererInfo: audio.AudioRendererInfo = audioRenderer.getRendererInfoSync(); 5673 console.info(`Renderer content: ${rendererInfo.content}`); 5674 console.info(`Renderer usage: ${rendererInfo.usage}`); 5675 console.info(`Renderer flags: ${rendererInfo.rendererFlags}`) 5676} catch (err) { 5677 let error = err as BusinessError; 5678 console.error(`AudioFrameworkRenderLog: RendererInfo :ERROR: ${error}`); 5679} 5680``` 5681 5682### getStreamInfo<sup>8+</sup> 5683 5684getStreamInfo(callback: AsyncCallback<AudioStreamInfo\>): void 5685 5686Obtains the stream information of this **AudioRenderer** instance. This API uses an asynchronous callback to return the result. 5687 5688**System capability**: SystemCapability.Multimedia.Audio.Renderer 5689 5690**Parameters** 5691 5692| Name | Type | Mandatory| Description | 5693| :------- | :--------------------------------------------------- | :--- | :------------------- | 5694| callback | AsyncCallback<[AudioStreamInfo](#audiostreaminfo8)\> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the stream information obtained; otherwise, **err** is an error object.| 5695 5696**Example** 5697 5698```ts 5699import { BusinessError } from '@kit.BasicServicesKit'; 5700 5701audioRenderer.getStreamInfo((err: BusinessError, streamInfo: audio.AudioStreamInfo) => { 5702 console.info('Renderer GetStreamInfo:'); 5703 console.info(`Renderer sampling rate: ${streamInfo.samplingRate}`); 5704 console.info(`Renderer channel: ${streamInfo.channels}`); 5705 console.info(`Renderer format: ${streamInfo.sampleFormat}`); 5706 console.info(`Renderer encoding type: ${streamInfo.encodingType}`); 5707}); 5708``` 5709 5710### getStreamInfo<sup>8+</sup> 5711 5712getStreamInfo(): Promise<AudioStreamInfo\> 5713 5714Obtains the stream information of this **AudioRenderer** instance. This API uses a promise to return the result. 5715 5716**System capability**: SystemCapability.Multimedia.Audio.Renderer 5717 5718**Return value** 5719 5720| Type | Description | 5721| :--------------------------------------------- | :--------------------- | 5722| Promise<[AudioStreamInfo](#audiostreaminfo8)\> | Promise used to return the stream information.| 5723 5724**Example** 5725 5726```ts 5727import { BusinessError } from '@kit.BasicServicesKit'; 5728 5729audioRenderer.getStreamInfo().then((streamInfo: audio.AudioStreamInfo) => { 5730 console.info('Renderer GetStreamInfo:'); 5731 console.info(`Renderer sampling rate: ${streamInfo.samplingRate}`); 5732 console.info(`Renderer channel: ${streamInfo.channels}`); 5733 console.info(`Renderer format: ${streamInfo.sampleFormat}`); 5734 console.info(`Renderer encoding type: ${streamInfo.encodingType}`); 5735}).catch((err: BusinessError) => { 5736 console.error(`ERROR: ${err}`); 5737}); 5738``` 5739 5740### getStreamInfoSync<sup>10+</sup> 5741 5742getStreamInfoSync(): AudioStreamInfo 5743 5744Obtains the stream information of this **AudioRenderer** instance. This API returns the result synchronously. 5745 5746**System capability**: SystemCapability.Multimedia.Audio.Renderer 5747 5748**Return value** 5749 5750| Type | Description | 5751| :--------------------------------------------- | :--------------------- | 5752| [AudioStreamInfo](#audiostreaminfo8) | Stream information.| 5753 5754**Example** 5755 5756```ts 5757import { BusinessError } from '@kit.BasicServicesKit'; 5758 5759try { 5760 let streamInfo: audio.AudioStreamInfo = audioRenderer.getStreamInfoSync(); 5761 console.info(`Renderer sampling rate: ${streamInfo.samplingRate}`); 5762 console.info(`Renderer channel: ${streamInfo.channels}`); 5763 console.info(`Renderer format: ${streamInfo.sampleFormat}`); 5764 console.info(`Renderer encoding type: ${streamInfo.encodingType}`); 5765} catch (err) { 5766 let error = err as BusinessError; 5767 console.error(`ERROR: ${error}`); 5768} 5769``` 5770 5771### getAudioStreamId<sup>9+</sup> 5772 5773getAudioStreamId(callback: AsyncCallback<number\>): void 5774 5775Obtains the stream ID of this **AudioRenderer** instance. This API uses an asynchronous callback to return the result. 5776 5777**System capability**: SystemCapability.Multimedia.Audio.Renderer 5778 5779**Parameters** 5780 5781| Name | Type | Mandatory| Description | 5782| :------- | :--------------------------------------------------- | :--- | :------------------- | 5783| callback | AsyncCallback<number\> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the stream ID obtained; otherwise, **err** is an error object.| 5784 5785**Example** 5786 5787```ts 5788import { BusinessError } from '@kit.BasicServicesKit'; 5789 5790audioRenderer.getAudioStreamId((err: BusinessError, streamId: number) => { 5791 console.info(`Renderer GetStreamId: ${streamId}`); 5792}); 5793``` 5794 5795### getAudioStreamId<sup>9+</sup> 5796 5797getAudioStreamId(): Promise<number\> 5798 5799Obtains the stream ID of this **AudioRenderer** instance. This API uses a promise to return the result. 5800 5801**System capability**: SystemCapability.Multimedia.Audio.Renderer 5802 5803**Return value** 5804 5805| Type | Description | 5806| :--------------------------------------------- | :--------------------- | 5807| Promise<number\> | Promise used to return the stream ID.| 5808 5809**Example** 5810 5811```ts 5812import { BusinessError } from '@kit.BasicServicesKit'; 5813 5814audioRenderer.getAudioStreamId().then((streamId: number) => { 5815 console.info(`Renderer getAudioStreamId: ${streamId}`); 5816}).catch((err: BusinessError) => { 5817 console.error(`ERROR: ${err}`); 5818}); 5819``` 5820 5821### getAudioStreamIdSync<sup>10+</sup> 5822 5823getAudioStreamIdSync(): number 5824 5825Obtains the stream ID of this **AudioRenderer** instance. This API returns the result synchronously. 5826 5827**System capability**: SystemCapability.Multimedia.Audio.Renderer 5828 5829**Return value** 5830 5831| Type | Description | 5832| :--------------------------------------------- | :--------------------- | 5833| number | Stream ID.| 5834 5835**Example** 5836 5837```ts 5838import { BusinessError } from '@kit.BasicServicesKit'; 5839 5840try { 5841 let streamId: number = audioRenderer.getAudioStreamIdSync(); 5842 console.info(`Renderer getAudioStreamIdSync: ${streamId}`); 5843} catch (err) { 5844 let error = err as BusinessError; 5845 console.error(`ERROR: ${error}`); 5846} 5847``` 5848 5849### setAudioEffectMode<sup>10+</sup> 5850 5851setAudioEffectMode(mode: AudioEffectMode, callback: AsyncCallback\<void>): void 5852 5853Sets an audio effect mode. This API uses an asynchronous callback to return the result. 5854 5855**System capability**: SystemCapability.Multimedia.Audio.Renderer 5856 5857**Parameters** 5858 5859| Name | Type | Mandatory| Description | 5860| -------- | ---------------------------------------- | ---- | ------------------------ | 5861| mode | [AudioEffectMode](#audioeffectmode10) | Yes | Audio effect mode to set. | 5862| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 5863 5864**Error codes** 5865 5866For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5867 5868| ID| Error Message| 5869| ------- | ----------------------------------------------| 5870| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5871| 6800101 | Parameter verification failed. Return by callback. | 5872 5873**Example** 5874 5875```ts 5876import { BusinessError } from '@kit.BasicServicesKit'; 5877 5878audioRenderer.setAudioEffectMode(audio.AudioEffectMode.EFFECT_DEFAULT, (err: BusinessError) => { 5879 if (err) { 5880 console.error('Failed to set params'); 5881 } else { 5882 console.info('Callback invoked to indicate a successful audio effect mode setting.'); 5883 } 5884}); 5885``` 5886 5887### setAudioEffectMode<sup>10+</sup> 5888 5889setAudioEffectMode(mode: AudioEffectMode): Promise\<void> 5890 5891Sets an audio effect mode. This API uses a promise to return the result. 5892 5893**System capability**: SystemCapability.Multimedia.Audio.Renderer 5894 5895**Parameters** 5896 5897| Name| Type | Mandatory| Description | 5898| ------ | ---------------------------------------- | ---- | ------------ | 5899| mode | [AudioEffectMode](#audioeffectmode10) | Yes | Audio effect mode to set.| 5900 5901**Return value** 5902 5903| Type | Description | 5904| -------------- | ------------------------- | 5905| Promise\<void> | Promise that returns no value.| 5906 5907**Error codes** 5908 5909For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5910 5911| ID| Error Message| 5912| ------- | ---------------------------------------------| 5913| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5914| 6800101 | Parameter verification failed. Return by promise. | 5915 5916**Example** 5917 5918```ts 5919import { BusinessError } from '@kit.BasicServicesKit'; 5920 5921audioRenderer.setAudioEffectMode(audio.AudioEffectMode.EFFECT_DEFAULT).then(() => { 5922 console.info('setAudioEffectMode SUCCESS'); 5923}).catch((err: BusinessError) => { 5924 console.error(`ERROR: ${err}`); 5925}); 5926``` 5927 5928### getAudioEffectMode<sup>10+</sup> 5929 5930getAudioEffectMode(callback: AsyncCallback\<AudioEffectMode>): void 5931 5932Obtains the audio effect mode in use. This API uses an asynchronous callback to return the result. 5933 5934**System capability**: SystemCapability.Multimedia.Audio.Renderer 5935 5936**Parameters** 5937 5938| Name | Type | Mandatory| Description | 5939| -------- | ------------------------------------------------------- | ---- | ------------------ | 5940| callback | AsyncCallback<[AudioEffectMode](#audioeffectmode10)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the audio effect mode obtained; otherwise, **err** is an error object.| 5941 5942**Example** 5943 5944```ts 5945import { BusinessError } from '@kit.BasicServicesKit'; 5946 5947audioRenderer.getAudioEffectMode((err: BusinessError, effectMode: audio.AudioEffectMode) => { 5948 if (err) { 5949 console.error('Failed to get params'); 5950 } else { 5951 console.info(`getAudioEffectMode: ${effectMode}`); 5952 } 5953}); 5954``` 5955 5956### getAudioEffectMode<sup>10+</sup> 5957 5958getAudioEffectMode(): Promise\<AudioEffectMode> 5959 5960Obtains the audio effect mode in use. This API uses a promise to return the result. 5961 5962**System capability**: SystemCapability.Multimedia.Audio.Renderer 5963 5964**Return value** 5965 5966| Type | Description | 5967| ------------------------------------------------- | ------------------------- | 5968| Promise<[AudioEffectMode](#audioeffectmode10)> | Promise used to return the audio effect mode.| 5969 5970**Example** 5971 5972```ts 5973import { BusinessError } from '@kit.BasicServicesKit'; 5974 5975audioRenderer.getAudioEffectMode().then((effectMode: audio.AudioEffectMode) => { 5976 console.info(`getAudioEffectMode: ${effectMode}`); 5977}).catch((err: BusinessError) => { 5978 console.error(`ERROR: ${err}`); 5979}); 5980``` 5981 5982### start<sup>8+</sup> 5983 5984start(callback: AsyncCallback<void\>): void 5985 5986Starts the renderer. This API uses an asynchronous callback to return the result. 5987 5988**System capability**: SystemCapability.Multimedia.Audio.Renderer 5989 5990**Parameters** 5991 5992| Name | Type | Mandatory| Description | 5993| -------- | -------------------- | ---- | ---------- | 5994| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation fails, an error object with the following error code is returned:<br>Error code 6800301: indicates abnormal status, focus preemption failure, and abnormal system processing. For details, see system logs.| 5995 5996**Example** 5997 5998```ts 5999import { BusinessError } from '@kit.BasicServicesKit'; 6000 6001audioRenderer.start((err: BusinessError) => { 6002 if (err) { 6003 console.error('Renderer start failed.'); 6004 } else { 6005 console.info('Renderer start success.'); 6006 } 6007}); 6008``` 6009 6010### start<sup>8+</sup> 6011 6012start(): Promise<void\> 6013 6014Starts the renderer. This API uses a promise to return the result. 6015 6016**System capability**: SystemCapability.Multimedia.Audio.Renderer 6017 6018**Return value** 6019 6020| Type | Description | 6021| -------------- | ------------------------- | 6022| Promise\<void> | Promise used to return the result. If the operation fails, an error object with the following error code is returned:<br>Error code 6800301: indicates abnormal status, focus preemption failure, and abnormal system processing. For details, see system logs.| 6023 6024**Example** 6025 6026```ts 6027import { BusinessError } from '@kit.BasicServicesKit'; 6028 6029audioRenderer.start().then(() => { 6030 console.info('Renderer started'); 6031}).catch((err: BusinessError) => { 6032 console.error(`ERROR: ${err}`); 6033}); 6034``` 6035 6036### pause<sup>8+</sup> 6037 6038pause(callback: AsyncCallback\<void>): void 6039 6040Pauses rendering. This API uses an asynchronous callback to return the result. 6041 6042**System capability**: SystemCapability.Multimedia.Audio.Renderer 6043 6044**Parameters** 6045 6046| Name | Type | Mandatory| Description | 6047| -------- | -------------------- | ---- | ---------------- | 6048| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 6049 6050**Example** 6051 6052```ts 6053import { BusinessError } from '@kit.BasicServicesKit'; 6054 6055audioRenderer.pause((err: BusinessError) => { 6056 if (err) { 6057 console.error('Renderer pause failed'); 6058 } else { 6059 console.info('Renderer paused.'); 6060 } 6061}); 6062``` 6063 6064### pause<sup>8+</sup> 6065 6066pause(): Promise\<void> 6067 6068Pauses rendering. This API uses a promise to return the result. 6069 6070**System capability**: SystemCapability.Multimedia.Audio.Renderer 6071 6072**Return value** 6073 6074| Type | Description | 6075| -------------- | ------------------------- | 6076| Promise\<void> | Promise that returns no value.| 6077 6078**Example** 6079 6080```ts 6081import { BusinessError } from '@kit.BasicServicesKit'; 6082 6083audioRenderer.pause().then(() => { 6084 console.info('Renderer paused'); 6085}).catch((err: BusinessError) => { 6086 console.error(`ERROR: ${err}`); 6087}); 6088``` 6089 6090### drain<sup>8+</sup> 6091 6092drain(callback: AsyncCallback\<void>): void 6093 6094Drains the playback buffer. This API uses an asynchronous callback to return the result. 6095 6096**System capability**: SystemCapability.Multimedia.Audio.Renderer 6097 6098**Parameters** 6099 6100| Name | Type | Mandatory| Description | 6101| -------- | -------------------- | ---- | ---------------- | 6102| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 6103 6104**Example** 6105 6106```ts 6107import { BusinessError } from '@kit.BasicServicesKit'; 6108 6109audioRenderer.drain((err: BusinessError) => { 6110 if (err) { 6111 console.error('Renderer drain failed'); 6112 } else { 6113 console.info('Renderer drained.'); 6114 } 6115}); 6116``` 6117 6118### drain<sup>8+</sup> 6119 6120drain(): Promise\<void> 6121 6122Drains the playback buffer. This API uses a promise to return the result. 6123 6124**System capability**: SystemCapability.Multimedia.Audio.Renderer 6125 6126**Return value** 6127 6128| Type | Description | 6129| -------------- | ------------------------- | 6130| Promise\<void> | Promise that returns no value.| 6131 6132**Example** 6133 6134```ts 6135import { BusinessError } from '@kit.BasicServicesKit'; 6136 6137audioRenderer.drain().then(() => { 6138 console.info('Renderer drained successfully'); 6139}).catch((err: BusinessError) => { 6140 console.error(`ERROR: ${err}`); 6141}); 6142``` 6143 6144### flush<sup>11+</sup> 6145 6146flush(): Promise\<void> 6147 6148Flushes the buffer. This API is available when [AudioState](#audiostate8) is **STATE_RUNNING**, **STATE_PAUSED**, or **STATE_STOPPED**. This API uses a promise to return the result. 6149 6150**System capability**: SystemCapability.Multimedia.Audio.Renderer 6151 6152**Return value** 6153 6154| Type | Description | 6155| -------------- | ------------------------- | 6156| Promise\<void> | Promise that returns no value.| 6157 6158**Error codes** 6159 6160For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 6161 6162| ID| Error Message| 6163| ------- | --------------------------------------------| 6164| 6800103 | Operation not permit at current state. Return by promise. | 6165 6166**Example** 6167 6168```ts 6169import { BusinessError } from '@kit.BasicServicesKit'; 6170 6171audioRenderer.flush().then(() => { 6172 console.info('Renderer flushed successfully'); 6173}).catch((err: BusinessError) => { 6174 console.error(`ERROR: ${err}`); 6175}); 6176``` 6177 6178### stop<sup>8+</sup> 6179 6180stop(callback: AsyncCallback\<void>): void 6181 6182Stops rendering. This API uses an asynchronous callback to return the result. 6183 6184**System capability**: SystemCapability.Multimedia.Audio.Renderer 6185 6186**Parameters** 6187 6188| Name | Type | Mandatory| Description | 6189| -------- | -------------------- | ---- | ---------------- | 6190| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 6191 6192**Example** 6193 6194```ts 6195import { BusinessError } from '@kit.BasicServicesKit'; 6196 6197audioRenderer.stop((err: BusinessError) => { 6198 if (err) { 6199 console.error('Renderer stop failed'); 6200 } else { 6201 console.info('Renderer stopped.'); 6202 } 6203}); 6204``` 6205 6206### stop<sup>8+</sup> 6207 6208stop(): Promise\<void> 6209 6210Stops rendering. This API uses a promise to return the result. 6211 6212**System capability**: SystemCapability.Multimedia.Audio.Renderer 6213 6214**Return value** 6215 6216| Type | Description | 6217| -------------- | ------------------------- | 6218| Promise\<void> | Promise that returns no value.| 6219 6220**Example** 6221 6222```ts 6223import { BusinessError } from '@kit.BasicServicesKit'; 6224 6225audioRenderer.stop().then(() => { 6226 console.info('Renderer stopped successfully'); 6227}).catch((err: BusinessError) => { 6228 console.error(`ERROR: ${err}`); 6229}); 6230``` 6231 6232### release<sup>8+</sup> 6233 6234release(callback: AsyncCallback\<void>): void 6235 6236Releases the renderer. This API uses an asynchronous callback to return the result. 6237 6238**System capability**: SystemCapability.Multimedia.Audio.Renderer 6239 6240**Parameters** 6241 6242| Name | Type | Mandatory| Description | 6243| -------- | -------------------- | ---- | ---------------- | 6244| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 6245 6246**Example** 6247 6248```ts 6249import { BusinessError } from '@kit.BasicServicesKit'; 6250 6251audioRenderer.release((err: BusinessError) => { 6252 if (err) { 6253 console.error('Renderer release failed'); 6254 } else { 6255 console.info('Renderer released.'); 6256 } 6257}); 6258``` 6259 6260### release<sup>8+</sup> 6261 6262release(): Promise\<void> 6263 6264Releases the renderer. This API uses a promise to return the result. 6265 6266**System capability**: SystemCapability.Multimedia.Audio.Renderer 6267 6268**Return value** 6269 6270| Type | Description | 6271| -------------- | ------------------------- | 6272| Promise\<void> | Promise that returns no value.| 6273 6274**Example** 6275 6276```ts 6277import { BusinessError } from '@kit.BasicServicesKit'; 6278 6279audioRenderer.release().then(() => { 6280 console.info('Renderer released successfully'); 6281}).catch((err: BusinessError) => { 6282 console.error(`ERROR: ${err}`); 6283}); 6284``` 6285 6286### write<sup>8+(deprecated)</sup> 6287 6288write(buffer: ArrayBuffer, callback: AsyncCallback\<number>): void 6289 6290Writes the buffer. This API uses an asynchronous callback to return the result. 6291 6292> **NOTE** 6293> 6294> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [on('writeData')](#onwritedata11) in **AudioRenderer**. 6295 6296**System capability**: SystemCapability.Multimedia.Audio.Renderer 6297 6298**Parameters** 6299 6300| Name | Type | Mandatory| Description | 6301| -------- | ---------------------- | ---- | --------------------------------------------------- | 6302| buffer | ArrayBuffer | Yes | Data to be written to the buffer. | 6303| callback | AsyncCallback\<number> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the number of bytes written; otherwise, **err** is an error object.| 6304 6305**Example** 6306 6307```ts 6308import { BusinessError } from '@kit.BasicServicesKit'; 6309import { fileIo as fs } from '@kit.CoreFileKit'; 6310 6311let bufferSize: number; 6312class Options { 6313 offset?: number; 6314 length?: number; 6315} 6316audioRenderer.getBufferSize().then((data: number)=> { 6317 console.info(`AudioFrameworkRenderLog: getBufferSize: SUCCESS ${data}`); 6318 bufferSize = data; 6319 console.info(`Buffer size: ${bufferSize}`); 6320 let path = getContext().cacheDir; 6321 let filePath = path + '/StarWars10s-2C-48000-4SW.wav'; 6322 let file: fs.File = fs.openSync(filePath, fs.OpenMode.READ_ONLY); 6323 fs.stat(filePath).then(async (stat: fs.Stat) => { 6324 let buf = new ArrayBuffer(bufferSize); 6325 let len = stat.size % bufferSize == 0 ? Math.floor(stat.size / bufferSize) : Math.floor(stat.size / bufferSize + 1); 6326 for (let i = 0;i < len; i++) { 6327 let options: Options = { 6328 offset: i * bufferSize, 6329 length: bufferSize 6330 }; 6331 let readSize: number = await fs.read(file.fd, buf, options); 6332 let writeSize: number = await new Promise((resolve,reject)=>{ 6333 audioRenderer.write(buf,(err: BusinessError, writeSize: number)=>{ 6334 if(err){ 6335 reject(err) 6336 }else{ 6337 resolve(writeSize) 6338 } 6339 }) 6340 }) 6341 } 6342 }); 6343 }).catch((err: BusinessError) => { 6344 console.error(`AudioFrameworkRenderLog: getBufferSize: ERROR: ${err}`); 6345}); 6346``` 6347 6348### write<sup>8+(deprecated)</sup> 6349 6350write(buffer: ArrayBuffer): Promise\<number> 6351 6352Writes the buffer. This API uses a promise to return the result. 6353 6354> **NOTE** 6355> 6356> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [on('writeData')](#onwritedata11) in **AudioRenderer**. 6357 6358**System capability**: SystemCapability.Multimedia.Audio.Renderer 6359 6360**Parameters** 6361 6362| Name | Type | Mandatory| Description | 6363| -------- | ---------------------- | ---- | --------------------------------------------------- | 6364| buffer | ArrayBuffer | Yes | Data to be written to the buffer. | 6365 6366**Return value** 6367 6368| Type | Description | 6369| ---------------- | ------------------------------------------------------------ | 6370| Promise\<number> | Promise used to return the number of written bytes.| 6371 6372**Example** 6373 6374```ts 6375import { BusinessError } from '@kit.BasicServicesKit'; 6376import { fileIo as fs } from '@kit.CoreFileKit'; 6377 6378let bufferSize: number; 6379class Options { 6380 offset?: number; 6381 length?: number; 6382} 6383audioRenderer.getBufferSize().then((data: number) => { 6384 console.info(`AudioFrameworkRenderLog: getBufferSize: SUCCESS ${data}`); 6385 bufferSize = data; 6386 console.info(`BufferSize: ${bufferSize}`); 6387 let path = getContext().cacheDir; 6388 let filePath = path + '/StarWars10s-2C-48000-4SW.wav'; 6389 let file: fs.File = fs.openSync(filePath, fs.OpenMode.READ_ONLY); 6390 fs.stat(filePath).then(async (stat: fs.Stat) => { 6391 let buf = new ArrayBuffer(bufferSize); 6392 let len = stat.size % bufferSize == 0 ? Math.floor(stat.size / bufferSize) : Math.floor(stat.size / bufferSize + 1); 6393 for (let i = 0;i < len; i++) { 6394 let options: Options = { 6395 offset: i * bufferSize, 6396 length: bufferSize 6397 }; 6398 let readSize: number = await fs.read(file.fd, buf, options); 6399 try{ 6400 let writeSize: number = await audioRenderer.write(buf); 6401 } catch(err) { 6402 let error = err as BusinessError; 6403 console.error(`audioRenderer.write err: ${error}`); 6404 } 6405 } 6406 }); 6407}).catch((err: BusinessError) => { 6408 console.error(`AudioFrameworkRenderLog: getBufferSize: ERROR: ${err}`); 6409}); 6410``` 6411 6412### getAudioTime<sup>8+</sup> 6413 6414getAudioTime(callback: AsyncCallback\<number>): void 6415 6416Obtains the timestamp of the current playback position, measured in nanoseconds from the Unix epoch (January 1, 1970). This API uses an asynchronous callback to return the result. 6417 6418**System capability**: SystemCapability.Multimedia.Audio.Renderer 6419 6420**Parameters** 6421 6422| Name | Type | Mandatory| Description | 6423| -------- | ---------------------- | ---- | ---------------- | 6424| callback | AsyncCallback\<number> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the number of nanoseconds obtained; otherwise, **err** is an error object.| 6425 6426**Example** 6427 6428```ts 6429import { BusinessError } from '@kit.BasicServicesKit'; 6430 6431audioRenderer.getAudioTime((err: BusinessError, timestamp: number) => { 6432 console.info(`Current timestamp: ${timestamp}`); 6433}); 6434``` 6435 6436### getAudioTime<sup>8+</sup> 6437 6438getAudioTime(): Promise\<number> 6439 6440Obtains the timestamp of the current playback position, measured in nanoseconds from the Unix epoch (January 1, 1970). This API uses a promise to return the result. 6441 6442**System capability**: SystemCapability.Multimedia.Audio.Renderer 6443 6444**Return value** 6445 6446| Type | Description | 6447| ---------------- | ----------------------- | 6448| Promise\<number> | Promise used to return the timestamp.| 6449 6450**Example** 6451 6452```ts 6453import { BusinessError } from '@kit.BasicServicesKit'; 6454 6455audioRenderer.getAudioTime().then((timestamp: number) => { 6456 console.info(`Current timestamp: ${timestamp}`); 6457}).catch((err: BusinessError) => { 6458 console.error(`ERROR: ${err}`); 6459}); 6460``` 6461 6462### getAudioTimeSync<sup>10+</sup> 6463 6464getAudioTimeSync(): number 6465 6466Obtains the timestamp of the current playback position, measured in nanoseconds from the Unix epoch (January 1, 1970). This API returns the result synchronously: 6467 6468**System capability**: SystemCapability.Multimedia.Audio.Renderer 6469 6470**Return value** 6471 6472| Type | Description | 6473| ---------------- | ----------------------- | 6474| number | Timestamp.| 6475 6476**Example** 6477 6478```ts 6479import { BusinessError } from '@kit.BasicServicesKit'; 6480 6481try { 6482 let timestamp: number = audioRenderer.getAudioTimeSync(); 6483 console.info(`Current timestamp: ${timestamp}`); 6484} catch (err) { 6485 let error = err as BusinessError; 6486 console.error(`ERROR: ${error}`); 6487} 6488``` 6489 6490### getBufferSize<sup>8+</sup> 6491 6492getBufferSize(callback: AsyncCallback\<number>): void 6493 6494Obtains a reasonable minimum buffer size in bytes for rendering. This API uses an asynchronous callback to return the result. 6495 6496**System capability**: SystemCapability.Multimedia.Audio.Renderer 6497 6498**Parameters** 6499 6500| Name | Type | Mandatory| Description | 6501| -------- | ---------------------- | ---- | -------------------- | 6502| callback | AsyncCallback\<number> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the minimum buffer size obtained; otherwise, **err** is an error object.| 6503 6504**Example** 6505 6506```ts 6507import { BusinessError } from '@kit.BasicServicesKit'; 6508 6509let bufferSize: number; 6510 6511audioRenderer.getBufferSize((err: BusinessError, data: number) => { 6512 if (err) { 6513 console.error('getBufferSize error'); 6514 } else { 6515 console.info(`AudioFrameworkRenderLog: getBufferSize: SUCCESS ${data}`); 6516 bufferSize = data; 6517 } 6518}); 6519``` 6520 6521### getBufferSize<sup>8+</sup> 6522 6523getBufferSize(): Promise\<number> 6524 6525Obtains a reasonable minimum buffer size in bytes for rendering. This API uses a promise to return the result. 6526 6527**System capability**: SystemCapability.Multimedia.Audio.Renderer 6528 6529**Return value** 6530 6531| Type | Description | 6532| ---------------- | --------------------------- | 6533| Promise\<number> | Promise used to return the buffer size.| 6534 6535**Example** 6536 6537```ts 6538import { BusinessError } from '@kit.BasicServicesKit'; 6539 6540let bufferSize: number; 6541 6542audioRenderer.getBufferSize().then((data: number) => { 6543 console.info(`AudioFrameworkRenderLog: getBufferSize: SUCCESS ${data}`); 6544 bufferSize = data; 6545}).catch((err: BusinessError) => { 6546 console.error(`AudioFrameworkRenderLog: getBufferSize: ERROR: ${err}`); 6547}); 6548``` 6549 6550### getBufferSizeSync<sup>10+</sup> 6551 6552getBufferSizeSync(): number 6553 6554Obtains a reasonable minimum buffer size in bytes for rendering. This API returns the result synchronously. 6555 6556**System capability**: SystemCapability.Multimedia.Audio.Renderer 6557 6558**Return value** 6559 6560| Type | Description | 6561| ---------------- | --------------------------- | 6562| number | Buffer size.| 6563 6564**Example** 6565 6566```ts 6567import { BusinessError } from '@kit.BasicServicesKit'; 6568 6569let bufferSize: number = 0; 6570 6571try { 6572 bufferSize = audioRenderer.getBufferSizeSync(); 6573 console.info(`AudioFrameworkRenderLog: getBufferSize: SUCCESS ${bufferSize}`); 6574} catch (err) { 6575 let error = err as BusinessError; 6576 console.error(`AudioFrameworkRenderLog: getBufferSize: ERROR: ${error}`); 6577} 6578``` 6579 6580### setRenderRate<sup>8+(deprecated)</sup> 6581 6582setRenderRate(rate: AudioRendererRate, callback: AsyncCallback\<void>): void 6583 6584Sets the render rate. This API uses an asynchronous callback to return the result. 6585 6586> **NOTE** 6587> 6588> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [setSpeed](#setspeed11) in **AudioRenderer**. 6589 6590**System capability**: SystemCapability.Multimedia.Audio.Renderer 6591 6592**Parameters** 6593 6594| Name | Type | Mandatory| Description | 6595| -------- | ---------------------------------------- | ---- | ------------------------ | 6596| rate | [AudioRendererRate](#audiorendererrate8) | Yes | Audio render rate. | 6597| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 6598 6599**Example** 6600 6601```ts 6602import { BusinessError } from '@kit.BasicServicesKit'; 6603 6604audioRenderer.setRenderRate(audio.AudioRendererRate.RENDER_RATE_NORMAL, (err: BusinessError) => { 6605 if (err) { 6606 console.error('Failed to set params'); 6607 } else { 6608 console.info('Callback invoked to indicate a successful render rate setting.'); 6609 } 6610}); 6611``` 6612 6613### setRenderRate<sup>8+(deprecated)</sup> 6614 6615setRenderRate(rate: AudioRendererRate): Promise\<void> 6616 6617Sets the render rate. This API uses a promise to return the result. 6618 6619> **NOTE** 6620> 6621> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [setSpeed](#setspeed11) in **AudioRenderer**. 6622 6623**System capability**: SystemCapability.Multimedia.Audio.Renderer 6624 6625**Parameters** 6626 6627| Name| Type | Mandatory| Description | 6628| ------ | ---------------------------------------- | ---- | ------------ | 6629| rate | [AudioRendererRate](#audiorendererrate8) | Yes | Audio render rate.| 6630 6631**Return value** 6632 6633| Type | Description | 6634| -------------- | ------------------------- | 6635| Promise\<void> | Promise that returns no value.| 6636 6637**Example** 6638 6639```ts 6640import { BusinessError } from '@kit.BasicServicesKit'; 6641 6642audioRenderer.setRenderRate(audio.AudioRendererRate.RENDER_RATE_NORMAL).then(() => { 6643 console.info('setRenderRate SUCCESS'); 6644}).catch((err: BusinessError) => { 6645 console.error(`ERROR: ${err}`); 6646}); 6647``` 6648 6649### setSpeed<sup>11+</sup> 6650 6651setSpeed(speed: number): void 6652 6653Sets the playback speed. 6654 6655**System capability**: SystemCapability.Multimedia.Audio.Renderer 6656 6657**Parameters** 6658 6659| Name| Type | Mandatory| Description | 6660| ------ | ---------------------------------------- | ---- |----------------------| 6661| speed | number | Yes | Playback speed, which ranges from 0.125 to 4.0.| 6662 6663**Error codes** 6664 6665For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 6666 6667| ID| Error Message| 6668| ------- | --------------------------------------------| 6669| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 6670| 6800101 | Parameter verification failed. | 6671 6672**Example** 6673 6674```ts 6675audioRenderer.setSpeed(1.5); 6676``` 6677 6678### getRenderRate<sup>8+(deprecated)</sup> 6679 6680getRenderRate(callback: AsyncCallback\<AudioRendererRate>): void 6681 6682Obtains the current render rate. This API uses an asynchronous callback to return the result. 6683 6684> **NOTE** 6685> 6686> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [getSpeed](#getspeed11) in **AudioRenderer**. 6687 6688**System capability**: SystemCapability.Multimedia.Audio.Renderer 6689 6690**Parameters** 6691 6692| Name | Type | Mandatory| Description | 6693| -------- | ------------------------------------------------------- | ---- | ------------------ | 6694| callback | AsyncCallback<[AudioRendererRate](#audiorendererrate8)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the render rate obtained; otherwise, **err** is an error object.| 6695 6696**Example** 6697 6698```ts 6699import { BusinessError } from '@kit.BasicServicesKit'; 6700 6701audioRenderer.getRenderRate((err: BusinessError, renderRate: audio.AudioRendererRate) => { 6702 console.info(`getRenderRate: ${renderRate}`); 6703}); 6704``` 6705 6706### getRenderRate<sup>8+(deprecated)</sup> 6707 6708getRenderRate(): Promise\<AudioRendererRate> 6709 6710Obtains the current render rate. This API uses a promise to return the result. 6711 6712> **NOTE** 6713> 6714> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [getSpeed](#getspeed11) in **AudioRenderer**. 6715 6716**System capability**: SystemCapability.Multimedia.Audio.Renderer 6717 6718**Return value** 6719 6720| Type | Description | 6721| ------------------------------------------------- | ------------------------- | 6722| Promise<[AudioRendererRate](#audiorendererrate8)> | Promise used to return the render rate.| 6723 6724**Example** 6725 6726```ts 6727import { BusinessError } from '@kit.BasicServicesKit'; 6728 6729audioRenderer.getRenderRate().then((renderRate: audio.AudioRendererRate) => { 6730 console.info(`getRenderRate: ${renderRate}`); 6731}).catch((err: BusinessError) => { 6732 console.error(`ERROR: ${err}`); 6733}); 6734``` 6735 6736### getRenderRateSync<sup>10+(deprecated)</sup> 6737 6738getRenderRateSync(): AudioRendererRate 6739 6740Obtains the current render rate. This API returns the result synchronously. 6741 6742> **NOTE** 6743> 6744> This API is supported since API version 10 and deprecated since API version 11. You are advised to use [getSpeed](#getspeed11) in **AudioRenderer**. 6745 6746**System capability**: SystemCapability.Multimedia.Audio.Renderer 6747 6748**Return value** 6749 6750| Type | Description | 6751| ------------------------------------------------- | ------------------------- | 6752| [AudioRendererRate](#audiorendererrate8) | Audio render rate.| 6753 6754**Example** 6755 6756```ts 6757import { BusinessError } from '@kit.BasicServicesKit'; 6758 6759try { 6760 let renderRate: audio.AudioRendererRate = audioRenderer.getRenderRateSync(); 6761 console.info(`getRenderRate: ${renderRate}`); 6762} catch (err) { 6763 let error = err as BusinessError; 6764 console.error(`ERROR: ${error}`); 6765} 6766``` 6767 6768### getSpeed<sup>11+</sup> 6769 6770getSpeed(): number 6771 6772Obtains the playback speed. 6773 6774**System capability**: SystemCapability.Multimedia.Audio.Renderer 6775 6776**Return value** 6777 6778| Type | Description | 6779| ------------------------------------------------- |-----------| 6780| number | Playback speed.| 6781 6782**Example** 6783 6784```ts 6785let speed = audioRenderer.getSpeed(); 6786``` 6787 6788### setInterruptMode<sup>9+</sup> 6789 6790setInterruptMode(mode: InterruptMode): Promise<void> 6791 6792Sets the audio interruption mode for the application. This API uses a promise to return the result. 6793 6794**System capability**: SystemCapability.Multimedia.Audio.Interrupt 6795 6796**Parameters** 6797 6798| Name | Type | Mandatory | Description | 6799| ---------- | ---------------------------------- | ------ | ---------- | 6800| mode | [InterruptMode](#interruptmode9) | Yes | Audio interruption mode. | 6801 6802**Return value** 6803 6804| Type | Description | 6805| ------------------- | ----------------------------- | 6806| Promise<void> | Promise that returns no value.| 6807 6808**Example** 6809 6810```ts 6811import { BusinessError } from '@kit.BasicServicesKit'; 6812 6813let mode = 0; 6814 6815audioRenderer.setInterruptMode(mode).then(() => { 6816 console.info('setInterruptMode Success!'); 6817}).catch((err: BusinessError) => { 6818 console.error(`setInterruptMode Fail: ${err}`); 6819}); 6820``` 6821### setInterruptMode<sup>9+</sup> 6822 6823setInterruptMode(mode: InterruptMode, callback: AsyncCallback\<void>): void 6824 6825Sets the audio interruption mode for the application. This API uses an asynchronous callback to return the result. 6826 6827**System capability**: SystemCapability.Multimedia.Audio.Interrupt 6828 6829**Parameters** 6830 6831| Name | Type | Mandatory | Description | 6832| ------- | ----------------------------------- | ------ | -------------- | 6833|mode | [InterruptMode](#interruptmode9) | Yes | Audio interruption mode.| 6834|callback | AsyncCallback\<void> | Yes |Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 6835 6836**Example** 6837 6838```ts 6839import { BusinessError } from '@kit.BasicServicesKit'; 6840 6841let mode = 1; 6842 6843audioRenderer.setInterruptMode(mode, (err: BusinessError) => { 6844 if(err){ 6845 console.error(`setInterruptMode Fail: ${err}`); 6846 } 6847 console.info('setInterruptMode Success!'); 6848}); 6849``` 6850 6851### setInterruptModeSync<sup>10+</sup> 6852 6853setInterruptModeSync(mode: InterruptMode): void 6854 6855Sets the audio interruption mode for the application. This API returns the result synchronously. 6856 6857**System capability**: SystemCapability.Multimedia.Audio.Interrupt 6858 6859**Parameters** 6860 6861| Name | Type | Mandatory | Description | 6862| ---------- | ---------------------------------- | ------ | ---------- | 6863| mode | [InterruptMode](#interruptmode9) | Yes | Audio interruption mode. | 6864 6865**Error codes** 6866 6867For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 6868 6869| ID| Error Message| 6870| ------- | --------------------------------------------| 6871| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 6872| 6800101 | Parameter verification failed. | 6873 6874**Example** 6875 6876```ts 6877import { BusinessError } from '@kit.BasicServicesKit'; 6878 6879try { 6880 audioRenderer.setInterruptModeSync(0); 6881 console.info('setInterruptMode Success!'); 6882} catch (err) { 6883 let error = err as BusinessError; 6884 console.error(`setInterruptMode Fail: ${error}`); 6885} 6886``` 6887 6888### setVolume<sup>9+</sup> 6889 6890setVolume(volume: number): Promise<void> 6891 6892Sets the volume for the application. This API uses a promise to return the result. 6893 6894**System capability**: SystemCapability.Multimedia.Audio.Renderer 6895 6896**Parameters** 6897 6898| Name | Type | Mandatory | Description | 6899| ---------- | ------- | ------ | ------------------- | 6900| volume | number | Yes | Volume to set, which can be within the range from 0.0 to 1.0.| 6901 6902**Return value** 6903 6904| Type | Description | 6905| ------------------- | ----------------------------- | 6906| Promise<void> | Promise that returns no value.| 6907 6908**Example** 6909 6910```ts 6911import { BusinessError } from '@kit.BasicServicesKit'; 6912 6913audioRenderer.setVolume(0.5).then(() => { 6914 console.info('setVolume Success!'); 6915}).catch((err: BusinessError) => { 6916 console.error(`setVolume Fail: ${err}`); 6917}); 6918``` 6919### setVolume<sup>9+</sup> 6920 6921setVolume(volume: number, callback: AsyncCallback\<void>): void 6922 6923Sets the volume for the application. This API uses an asynchronous callback to return the result. 6924 6925**System capability**: SystemCapability.Multimedia.Audio.Renderer 6926 6927**Parameters** 6928 6929| Name | Type | Mandatory | Description | 6930| ------- | -----------| ------ | ------------------- | 6931|volume | number | Yes | Volume to set, which can be within the range from 0.0 to 1.0.| 6932|callback | AsyncCallback\<void> | Yes |Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 6933 6934**Example** 6935 6936```ts 6937import { BusinessError } from '@kit.BasicServicesKit'; 6938 6939audioRenderer.setVolume(0.5, (err: BusinessError) => { 6940 if(err){ 6941 console.error(`setVolume Fail: ${err}`); 6942 return; 6943 } 6944 console.info('setVolume Success!'); 6945}); 6946``` 6947### getVolume<sup>12+</sup> 6948 6949getVolume(): number 6950 6951Obtains the volume of the audio render. This API returns the result synchronously. 6952 6953**System capability**: SystemCapability.Multimedia.Audio.Renderer 6954 6955**Return value** 6956 6957| Type | Description | 6958| ---------------- | --------------------------- | 6959| number | Volume, in the range [0.0-1.0].| 6960 6961**Example** 6962 6963```ts 6964import { BusinessError } from '@kit.BasicServicesKit'; 6965 6966try { 6967 let value: number = audioRenderer.getVolume(); 6968 console.info(`Indicate that the volume is obtained ${value}.`); 6969} catch (err) { 6970 let error = err as BusinessError; 6971 console.error(`Failed to obtain the volume, error ${error}.`); 6972} 6973``` 6974 6975### getMinStreamVolume<sup>10+</sup> 6976 6977getMinStreamVolume(callback: AsyncCallback<number>): void 6978 6979Obtains the minimum volume of the application from the perspective of an audio stream. This API uses an asynchronous callback to return the result. 6980 6981**System capability**: SystemCapability.Multimedia.Audio.Renderer 6982 6983**Parameters** 6984 6985| Name | Type | Mandatory | Description | 6986| ------- | -----------| ------ | ------------------- | 6987|callback |AsyncCallback<number> | Yes |Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the minimum volume (range: 0-1) obtained; otherwise, **err** is an error object.| 6988 6989**Example** 6990 6991```ts 6992import { BusinessError } from '@kit.BasicServicesKit'; 6993 6994audioRenderer.getMinStreamVolume((err: BusinessError, minVolume: number) => { 6995 if (err) { 6996 console.error(`getMinStreamVolume error: ${err}`); 6997 } else { 6998 console.info(`getMinStreamVolume Success! ${minVolume}`); 6999 } 7000}); 7001``` 7002### getMinStreamVolume<sup>10+</sup> 7003 7004getMinStreamVolume(): Promise<number> 7005 7006Obtains the minimum volume of the application from the perspective of an audio stream. This API uses a promise to return the result. 7007 7008**System capability**: SystemCapability.Multimedia.Audio.Renderer 7009 7010**Return value** 7011 7012| Type | Description | 7013| ------------------- | ----------------------------- | 7014| Promise<number>| Promise used to return the minimum volume, ranging from 0 to 1.| 7015 7016**Example** 7017 7018```ts 7019import { BusinessError } from '@kit.BasicServicesKit'; 7020 7021audioRenderer.getMinStreamVolume().then((value: number) => { 7022 console.info(`Get min stream volume Success! ${value}`); 7023}).catch((err: BusinessError) => { 7024 console.error(`Get min stream volume Fail: ${err}`); 7025}); 7026``` 7027 7028### getMinStreamVolumeSync<sup>10+</sup> 7029 7030getMinStreamVolumeSync(): number 7031 7032Obtains the minimum volume of the application from the perspective of an audio stream. This API returns the result synchronously. 7033 7034**System capability**: SystemCapability.Multimedia.Audio.Renderer 7035 7036**Return value** 7037 7038| Type | Description | 7039| ------------------- | ----------------------------- | 7040| number| Minimum volume, ranging from 0 to 1.| 7041 7042**Example** 7043 7044```ts 7045import { BusinessError } from '@kit.BasicServicesKit'; 7046 7047try { 7048 let value: number = audioRenderer.getMinStreamVolumeSync(); 7049 console.info(`Get min stream volume Success! ${value}`); 7050} catch (err) { 7051 let error = err as BusinessError; 7052 console.error(`Get min stream volume Fail: ${error}`); 7053} 7054``` 7055 7056### getMaxStreamVolume<sup>10+</sup> 7057 7058getMaxStreamVolume(callback: AsyncCallback<number>): void 7059 7060Obtains the maximum volume of the application from the perspective of an audio stream. This API uses an asynchronous callback to return the result. 7061 7062**System capability**: SystemCapability.Multimedia.Audio.Renderer 7063 7064**Parameters** 7065 7066| Name | Type | Mandatory | Description | 7067| ------- | -----------| ------ | ------------------- | 7068|callback | AsyncCallback<number> | Yes |Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the maximum volume (range: 0-1) obtained; otherwise, **err** is an error object.| 7069 7070**Example** 7071 7072```ts 7073import { BusinessError } from '@kit.BasicServicesKit'; 7074 7075audioRenderer.getMaxStreamVolume((err: BusinessError, maxVolume: number) => { 7076 if (err) { 7077 console.error(`getMaxStreamVolume Fail: ${err}`); 7078 } else { 7079 console.info(`getMaxStreamVolume Success! ${maxVolume}`); 7080 } 7081}); 7082``` 7083### getMaxStreamVolume<sup>10+</sup> 7084 7085getMaxStreamVolume(): Promise<number> 7086 7087Obtains the maximum volume of the application from the perspective of an audio stream. This API uses a promise to return the result. 7088 7089**System capability**: SystemCapability.Multimedia.Audio.Renderer 7090 7091**Return value** 7092 7093| Type | Description | 7094| ------------------- | ----------------------------- | 7095| Promise<number>| Promise used to return the maximum volume, ranging from 0 to 1.| 7096 7097**Example** 7098 7099```ts 7100import { BusinessError } from '@kit.BasicServicesKit'; 7101 7102audioRenderer.getMaxStreamVolume().then((value: number) => { 7103 console.info(`Get max stream volume Success! ${value}`); 7104}).catch((err: BusinessError) => { 7105 console.error(`Get max stream volume Fail: ${err}`); 7106}); 7107``` 7108 7109### getMaxStreamVolumeSync<sup>10+</sup> 7110 7111getMaxStreamVolumeSync(): number 7112 7113Obtains the maximum volume of the application from the perspective of an audio stream. This API returns the result synchronously. 7114 7115**System capability**: SystemCapability.Multimedia.Audio.Renderer 7116 7117**Return value** 7118 7119| Type | Description | 7120| ------------------- | ----------------------------- | 7121| number| Maximum volume, ranging from 0 to 1.| 7122 7123**Example** 7124 7125```ts 7126import { BusinessError } from '@kit.BasicServicesKit'; 7127 7128try { 7129 let value: number = audioRenderer.getMaxStreamVolumeSync(); 7130 console.info(`Get max stream volume Success! ${value}`); 7131} catch (err) { 7132 let error = err as BusinessError; 7133 console.error(`Get max stream volume Fail: ${error}`); 7134} 7135``` 7136 7137### getUnderflowCount<sup>10+</sup> 7138 7139getUnderflowCount(callback: AsyncCallback<number>): void 7140 7141Obtains the number of underflow audio frames in the audio stream that is being played. This API uses an asynchronous callback to return the result. 7142 7143**System capability**: SystemCapability.Multimedia.Audio.Renderer 7144 7145**Parameters** 7146 7147| Name | Type | Mandatory | Description | 7148| ------- | -----------| ------ | ------------------- | 7149|callback | AsyncCallback<number> | Yes |Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the number of underloaded audio frames obtained; otherwise, **err** is an error object.| 7150 7151**Example** 7152 7153```ts 7154import { BusinessError } from '@kit.BasicServicesKit'; 7155 7156audioRenderer.getUnderflowCount((err: BusinessError, underflowCount: number) => { 7157 if (err) { 7158 console.error(`getUnderflowCount Fail: ${err}`); 7159 } else { 7160 console.info(`getUnderflowCount Success! ${underflowCount}`); 7161 } 7162}); 7163``` 7164### getUnderflowCount<sup>10+</sup> 7165 7166getUnderflowCount(): Promise<number> 7167 7168Obtains the number of underflow audio frames in the audio stream that is being played. This API uses a promise to return the result. 7169 7170**System capability**: SystemCapability.Multimedia.Audio.Renderer 7171 7172**Return value** 7173 7174| Type | Description | 7175| ------------------- | ----------------------------- | 7176| Promise<number>| Promise used to return the number of underflow audio frames.| 7177 7178**Example** 7179 7180```ts 7181import { BusinessError } from '@kit.BasicServicesKit'; 7182 7183audioRenderer.getUnderflowCount().then((value: number) => { 7184 console.info(`Get underflow count Success! ${value}`); 7185}).catch((err: BusinessError) => { 7186 console.error(`Get underflow count Fail: ${err}`); 7187}); 7188``` 7189 7190### getUnderflowCountSync<sup>10+</sup> 7191 7192getUnderflowCountSync(): number 7193 7194Obtains the number of underflow audio frames in the audio stream that is being played. This API returns the result synchronously. 7195 7196**System capability**: SystemCapability.Multimedia.Audio.Renderer 7197 7198**Return value** 7199 7200| Type | Description | 7201| ------------------- | ----------------------------- | 7202| number| Number of underflow audio frames.| 7203 7204**Example** 7205 7206```ts 7207import { BusinessError } from '@kit.BasicServicesKit'; 7208 7209try { 7210 let value: number = audioRenderer.getUnderflowCountSync(); 7211 console.info(`Get underflow count Success! ${value}`); 7212} catch (err) { 7213 let error = err as BusinessError; 7214 console.error(`Get underflow count Fail: ${error}`); 7215} 7216``` 7217 7218### getCurrentOutputDevices<sup>10+</sup> 7219 7220getCurrentOutputDevices(callback: AsyncCallback<AudioDeviceDescriptors>): void 7221 7222Obtains the output device descriptors of the audio streams. This API uses an asynchronous callback to return the result. 7223 7224**System capability**: SystemCapability.Multimedia.Audio.Device 7225 7226**Parameters** 7227 7228| Name | Type | Mandatory | Description | 7229| ------- | -----------| ------ | ------------------- | 7230|callback | AsyncCallback\<[AudioDeviceDescriptors](#audiodevicedescriptors)>| Yes |Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the output device descriptors obtained; otherwise, **err** is an error object.| 7231 7232**Example** 7233 7234```ts 7235import { BusinessError } from '@kit.BasicServicesKit'; 7236 7237audioRenderer.getCurrentOutputDevices((err: BusinessError, deviceInfo: audio.AudioDeviceDescriptors) => { 7238 if (err) { 7239 console.error(`getCurrentOutputDevices Fail: ${err}`); 7240 } else { 7241 for (let i = 0; i < deviceInfo.length; i++) { 7242 console.info(`DeviceInfo id: ${deviceInfo[i].id}`); 7243 console.info(`DeviceInfo type: ${deviceInfo[i].deviceType}`); 7244 console.info(`DeviceInfo role: ${deviceInfo[i].deviceRole}`); 7245 console.info(`DeviceInfo name: ${deviceInfo[i].name}`); 7246 console.info(`DeviceInfo address: ${deviceInfo[i].address}`); 7247 console.info(`DeviceInfo samplerate: ${deviceInfo[i].sampleRates[0]}`); 7248 console.info(`DeviceInfo channelcount: ${deviceInfo[i].channelCounts[0]}`); 7249 console.info(`DeviceInfo channelmask: ${deviceInfo[i].channelMasks[0]}`); 7250 } 7251 } 7252}); 7253``` 7254### getCurrentOutputDevices<sup>10+</sup> 7255 7256getCurrentOutputDevices(): Promise<AudioDeviceDescriptors> 7257 7258Obtains the output device descriptors of the audio streams. This API uses a promise to return the result. 7259 7260**System capability**: SystemCapability.Multimedia.Audio.Device 7261 7262**Return value** 7263 7264| Type | Description | 7265| ------------------- | ----------------------------- | 7266| Promise<[AudioDeviceDescriptors](#audiodevicedescriptors)>| Promise used to return the output device descriptors.| 7267 7268**Example** 7269 7270```ts 7271import { BusinessError } from '@kit.BasicServicesKit'; 7272 7273audioRenderer.getCurrentOutputDevices().then((deviceInfo: audio.AudioDeviceDescriptors) => { 7274 for (let i = 0; i < deviceInfo.length; i++) { 7275 console.info(`DeviceInfo id: ${deviceInfo[i].id}`); 7276 console.info(`DeviceInfo type: ${deviceInfo[i].deviceType}`); 7277 console.info(`DeviceInfo role: ${deviceInfo[i].deviceRole}`); 7278 console.info(`DeviceInfo name: ${deviceInfo[i].name}`); 7279 console.info(`DeviceInfo address: ${deviceInfo[i].address}`); 7280 console.info(`DeviceInfo samplerate: ${deviceInfo[i].sampleRates[0]}`); 7281 console.info(`DeviceInfo channelcount: ${deviceInfo[i].channelCounts[0]}`); 7282 console.info(`DeviceInfo channelmask: ${deviceInfo[i].channelMasks[0]}`); 7283 } 7284}).catch((err: BusinessError) => { 7285 console.error(`Get current output devices Fail: ${err}`); 7286}); 7287``` 7288 7289### getCurrentOutputDevicesSync<sup>10+</sup> 7290 7291getCurrentOutputDevicesSync(): AudioDeviceDescriptors 7292 7293Obtains the output device descriptors of the audio streams. This API returns the result synchronously. 7294 7295**System capability**: SystemCapability.Multimedia.Audio.Device 7296 7297**Return value** 7298 7299| Type | Description | 7300| ------------------- | ----------------------------- | 7301| [AudioDeviceDescriptors](#audiodevicedescriptors) | Output device descriptors.| 7302 7303**Example** 7304 7305```ts 7306import { BusinessError } from '@kit.BasicServicesKit'; 7307 7308try { 7309 let deviceInfo: audio.AudioDeviceDescriptors = audioRenderer.getCurrentOutputDevicesSync(); 7310 for (let i = 0; i < deviceInfo.length; i++) { 7311 console.info(`DeviceInfo id: ${deviceInfo[i].id}`); 7312 console.info(`DeviceInfo type: ${deviceInfo[i].deviceType}`); 7313 console.info(`DeviceInfo role: ${deviceInfo[i].deviceRole}`); 7314 console.info(`DeviceInfo name: ${deviceInfo[i].name}`); 7315 console.info(`DeviceInfo address: ${deviceInfo[i].address}`); 7316 console.info(`DeviceInfo samplerate: ${deviceInfo[i].sampleRates[0]}`); 7317 console.info(`DeviceInfo channelcount: ${deviceInfo[i].channelCounts[0]}`); 7318 console.info(`DeviceInfo channelmask: ${deviceInfo[i].channelMasks[0]}`); 7319 } 7320} catch (err) { 7321 let error = err as BusinessError; 7322 console.error(`Get current output devices Fail: ${error}`); 7323} 7324``` 7325### setChannelBlendMode<sup>11+</sup> 7326 7327setChannelBlendMode(mode: ChannelBlendMode): void 7328 7329Sets the audio channel blending mode. This API returns the result synchronously. 7330 7331**System capability**: SystemCapability.Multimedia.Audio.Renderer 7332 7333**Parameters** 7334 7335| Name | Type | Mandatory| Description | 7336| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 7337| mode | [ChannelBlendMode](#channelblendmode11) | Yes | Audio channel blending mode. | 7338 7339**Error codes** 7340 7341For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7342 7343| ID| Error Message| 7344| ------- | --------------------------------------------| 7345| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7346| 6800101 | Parameter verification failed. | 7347| 6800103 | Operation not permit at current state. | 7348 7349**Example** 7350 7351```ts 7352let mode = audio.ChannelBlendMode.MODE_DEFAULT; 7353 7354audioRenderer.setChannelBlendMode(mode); 7355console.info(`BlendMode: ${mode}`); 7356``` 7357### setVolumeWithRamp<sup>11+</sup> 7358 7359setVolumeWithRamp(volume: number, duration: number): void 7360 7361Sets a volume ramp. This API returns the result synchronously. 7362 7363**System capability**: SystemCapability.Multimedia.Audio.Renderer 7364 7365**Parameters** 7366 7367| Name | Type | Mandatory| Description | 7368| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 7369| volume | number | Yes | Target volume, within the range [0.0, 1.0]. | 7370| duration | number | Yes | Time range during which the ramp applies, in ms. | 7371 7372**Error codes** 7373 7374For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7375 7376| ID| Error Message| 7377| ------- | --------------------------------------------| 7378| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7379| 6800101 | Parameter verification failed. | 7380 7381**Example** 7382 7383```ts 7384let volume = 0.5; 7385let duration = 1000; 7386 7387audioRenderer.setVolumeWithRamp(volume, duration); 7388console.info(`setVolumeWithRamp: ${volume}`); 7389``` 7390 7391### setSilentModeAndMixWithOthers<sup>12+</sup> 7392 7393setSilentModeAndMixWithOthers(on: boolean): void 7394 7395Sets the silent mode in concurrent playback for the audio stream. 7396 7397If the silent mode in concurrent playback is enabled, the system mutes the audio stream and does not interrupt other audio streams. If the silent mode in concurrent playback is disabled, the audio stream can gain focus based on the system focus policy. 7398 7399**System capability**: SystemCapability.Multimedia.Audio.Renderer 7400 7401**Parameters** 7402 7403| Name| Type | Mandatory| Description | 7404| ------ | ---------------------------------------- | ---- |----------------------| 7405| on | boolean | Yes | Whether to enable or disable the silent mode in concurrent playback for the audio stream. The value **true** means to enable the silent mode in concurrent playback, and **false** mans the opposite.| 7406 7407**Example** 7408 7409```ts 7410audioRenderer.setSilentModeAndMixWithOthers(true); 7411``` 7412 7413### getSilentModeAndMixWithOthers<sup>12+</sup> 7414 7415getSilentModeAndMixWithOthers(): boolean 7416 7417Obtains the silent mode in concurrent playback for the audio stream. 7418 7419**System capability**: SystemCapability.Multimedia.Audio.Renderer 7420 7421**Return value** 7422 7423| Type | Description | 7424| ------------------------------------------------- |-----------| 7425| boolean | **true**: The silent mode in concurrent playback is enabled.<br>**false**: The silent mode in concurrent playback is disabled.| 7426 7427**Example** 7428 7429```ts 7430let on = audioRenderer.getSilentModeAndMixWithOthers(); 7431``` 7432 7433### setDefaultOutputDevice<sup>12+</sup> 7434 7435setDefaultOutputDevice(deviceType: DeviceType): Promise<void> 7436 7437Sets the default built-in audio output device. This API uses a promise to return the result. 7438 7439This API applies only to the scenario where [StreamUsage](#streamusage) is set to voice messages, VoIP voice calls, and VoIP video calls and the available device types are the receiver, speaker, and system default device. 7440 7441This API can be called at any time after an **AudioRenderer** instance is created. The system records the device set by the application. When the application is started, if an external device such as a Bluetooth or wired headset is connected, the system preferentially uses the external device to play sound. Otherwise, the system uses this default device to play sound. 7442 7443**System capability**: SystemCapability.Multimedia.Audio.Renderer 7444 7445**Parameters** 7446 7447| Name | Type | Mandatory | Description | 7448| ---------- |----------------| ------ |---------------------------------------------------------| 7449| deviceType | [DeviceType](#devicetype) | Yes | Device type.<br>The options are **EARPIECE**, **SPEAKER**, and **DEFAULT**.| 7450 7451**Return value** 7452 7453| Type | Description | 7454| ------------------- | ----------------------------- | 7455| Promise<void> | Promise that returns no value.| 7456 7457**Error codes** 7458 7459For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7460 7461| ID| Error Message| 7462| ------- | --------------------------------------------| 7463| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7464| 6800101 | Parameter verification failed. | 7465| 6800103 | Operation not permit at current state. | 7466 7467**Example** 7468 7469```ts 7470import { BusinessError } from '@kit.BasicServicesKit'; 7471 7472// This API can be called at any time after an **AudioRenderer** instance is created. 7473// If the API is called when no audio is being played, the system records the default device set by the application. When the application starts playing, the sound is played from this default device. 7474// If the API is called when audio is being played and no external device, such as a Bluetooth or wired headset, is connected, the system immediately switches to the default device. If an external device is connected, the system records the default device and switches to it once the external device is disconnected. 7475audioRenderer.setDefaultOutputDevice(audio.DeviceType.SPEAKER).then(() => { 7476 console.info('setDefaultOutputDevice Success!'); 7477}).catch((err: BusinessError) => { 7478 console.error(`setDefaultOutputDevice Fail: ${err}`); 7479}); 7480``` 7481 7482### on('audioInterrupt')<sup>9+</sup> 7483 7484on(type: 'audioInterrupt', callback: Callback\<InterruptEvent>): void 7485 7486Subscribes to the audio interruption event, which is triggered when the audio focus is changed. This API uses an asynchronous callback to return the result. 7487 7488The **AudioRenderer** instance proactively gains the focus when the **start** event occurs and releases the focus when the **pause** or **stop** event occurs. Therefore, you do not need to request to gain or release the focus. 7489 7490After this API is called, an [InterruptEvent](#interruptevent9) is received when the **AudioRenderer** object fails to obtain the focus or an audio interruption event occurs (for example, the audio stream is interrupted by others). It is recommended that the application perform further processing based on the **InterruptEvent** information. For details, see [Handling Audio Focus Changes](../../media/audio/audio-playback-concurrency.md). 7491 7492**System capability**: SystemCapability.Multimedia.Audio.Interrupt 7493 7494**Parameters** 7495 7496| Name | Type | Mandatory| Description | 7497| -------- | -------------------------------------------- | ---- | ----------------------------------------------------------- | 7498| type | string | Yes | Event type. The value is fixed at **'audioInterrupt'**.| 7499| callback | Callback\<[InterruptEvent](#interruptevent9)\> | Yes | Callback used to return the audio interruption event received by the application when playback is interrupted.| 7500 7501**Error codes** 7502 7503For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7504 7505| ID| Error Message| 7506| ------- | --------------------------------------------| 7507| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7508| 6800101 | Parameter verification failed. | 7509 7510**Example** 7511 7512```ts 7513import { audio } from '@kit.AudioKit'; 7514 7515let isPlaying: boolean; // An identifier specifying whether rendering is in progress. 7516let isDucked: boolean; // An identifier specifying whether the audio volume is reduced. 7517onAudioInterrupt(); 7518 7519async function onAudioInterrupt(){ 7520 audioRenderer.on('audioInterrupt', (interruptEvent: audio.InterruptEvent) => { 7521 // When an audio interruption event occurs, the AudioRenderer receives the interruptEvent callback and performs processing based on the content in the callback. 7522 // 1. (Optional) The AudioRenderer reads the value of interruptEvent.forceType to see whether the system has forcibly performed the operation. 7523 // Note: In the default focus policy, INTERRUPT_HINT_RESUME maps to the force type INTERRUPT_SHARE, and others map to INTERRUPT_FORCE. Therefore, the value of forceType does not need to be checked. 7524 // 2. (Mandatory) The AudioRenderer then reads the value of interruptEvent.hintType and performs corresponding processing. 7525 if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_FORCE) { 7526 // The audio focus event has been forcibly executed by the system. The application needs to update its status and displayed content. 7527 switch (interruptEvent.hintType) { 7528 case audio.InterruptHint.INTERRUPT_HINT_PAUSE: 7529 // The audio stream has been paused and temporarily loses the focus. It will receive the interruptEvent corresponding to resume when it is able to regain the focus. 7530 console.info('Force paused. Update playing status and stop writing'); 7531 isPlaying = false; // A simplified processing indicating several operations for switching the application to the paused state. 7532 break; 7533 case audio.InterruptHint.INTERRUPT_HINT_STOP: 7534 // The audio stream has been stopped and permanently loses the focus. The user must manually trigger the operation to resume rendering. 7535 console.info('Force stopped. Update playing status and stop writing'); 7536 isPlaying = false; // A simplified processing indicating several operations for switching the application to the paused state. 7537 break; 7538 case audio.InterruptHint.INTERRUPT_HINT_DUCK: 7539 // The audio stream is rendered at a reduced volume. 7540 console.info('Force ducked. Update volume status'); 7541 isDucked = true; // A simplified processing indicating several operations for updating the volume status. 7542 break; 7543 case audio.InterruptHint.INTERRUPT_HINT_UNDUCK: 7544 // The audio stream is rendered at the normal volume. 7545 console.info('Force ducked. Update volume status'); 7546 isDucked = false; // A simplified processing indicating several operations for updating the volume status. 7547 break; 7548 default: 7549 console.info('Invalid interruptEvent'); 7550 break; 7551 } 7552 } else if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_SHARE) { 7553 // The audio focus event needs to be operated by the application, which can choose the processing mode. It is recommended that the application process the event according to the value of InterruptHint. 7554 switch (interruptEvent.hintType) { 7555 case audio.InterruptHint.INTERRUPT_HINT_RESUME: 7556 // It is recommended that the application continue rendering. (The audio stream has been forcibly paused and temporarily lost the focus. It can resume rendering now.) 7557 // The INTERRUPT_HINT_RESUME operation must be proactively executed by the application and cannot be forcibly executed by the system. Therefore, the INTERRUPT_HINT_RESUME event must map to INTERRUPT_SHARE. 7558 console.info('Resume force paused renderer or ignore'); 7559 // To continue rendering, the application must perform the required operations. 7560 break; 7561 default: 7562 console.info('Invalid interruptEvent'); 7563 break; 7564 } 7565 } 7566 }); 7567} 7568``` 7569 7570### on('markReach')<sup>8+</sup> 7571 7572on(type: 'markReach', frame: number, callback: Callback<number>): void 7573 7574Subscribes to the mark reached event, which is triggered (only once) when the number of frames rendered reaches the value of the **frame** parameter. This API uses an asynchronous callback to return the result. 7575 7576For example, if **frame** is set to **100**, the callback is invoked when the number of rendered frames reaches the 100th frame. 7577 7578**System capability**: SystemCapability.Multimedia.Audio.Renderer 7579 7580**Parameters** 7581 7582| Name | Type | Mandatory| Description | 7583| :------- | :----------------------- | :--- | :---------------------------------------- | 7584| type | string | Yes | Event type. The value is fixed at **'markReach'**.| 7585| frame | number | Yes | Number of frames to trigger the event. The value must be greater than **0**. | 7586| callback | Callback\<number> | Yes | Callback used to return the value of the **frame** parameter.| 7587 7588**Example** 7589 7590```ts 7591audioRenderer.on('markReach', 1000, (position: number) => { 7592 if (position == 1000) { 7593 console.info('ON Triggered successfully'); 7594 } 7595}); 7596``` 7597 7598 7599### off('markReach')<sup>8+</sup> 7600 7601off(type: 'markReach'): void 7602 7603Unsubscribes from the mark reached event. 7604 7605**System capability**: SystemCapability.Multimedia.Audio.Renderer 7606 7607**Parameters** 7608 7609| Name| Type | Mandatory| Description | 7610| :----- | :----- | :--- | :------------------------------------------------ | 7611| type | string | Yes | Event type. The value is fixed at **'markReach'**.| 7612 7613**Example** 7614 7615```ts 7616audioRenderer.off('markReach'); 7617``` 7618 7619### on('periodReach')<sup>8+</sup> 7620 7621on(type: 'periodReach', frame: number, callback: Callback<number>): void 7622 7623Subscribes to the period reached event, which is triggered each time the number of frames rendered reaches the value of the **frame** parameter. In other words, the information is reported periodically. This API uses an asynchronous callback to return the result. 7624 7625For example, if **frame** is set to **10**, the callback is invoked each time 10 frames are rendered, for example, when the number of frames rendered reaches the 10th frame, 20th frame, and 30th frame. 7626 7627**System capability**: SystemCapability.Multimedia.Audio.Renderer 7628 7629**Parameters** 7630 7631| Name | Type | Mandatory| Description | 7632| :------- | :----------------------- | :--- | :------------------------------------------ | 7633| type | string | Yes | Event type. The value is fixed at **'periodReach'**.| 7634| frame | number | Yes | Number of frames to trigger the event. The value must be greater than **0**. | 7635| callback | Callback\<number> | Yes | Callback used to return the value of the **frame** parameter.| 7636 7637**Example** 7638 7639```ts 7640audioRenderer.on('periodReach', 1000, (position: number) => { 7641 if (position == 1000) { 7642 console.info('ON Triggered successfully'); 7643 } 7644}); 7645``` 7646 7647### off('periodReach')<sup>8+</sup> 7648 7649off(type: 'periodReach'): void 7650 7651Unsubscribes from the period reached event. 7652 7653**System capability**: SystemCapability.Multimedia.Audio.Renderer 7654 7655**Parameters** 7656 7657| Name| Type | Mandatory| Description | 7658| :----- | :----- | :--- | :-------------------------------------------------- | 7659| type | string | Yes | Event type. The value is fixed at **'periodReach'**.| 7660 7661**Example** 7662 7663```ts 7664audioRenderer.off('periodReach'); 7665``` 7666 7667### on('stateChange')<sup>8+</sup> 7668 7669on(type: 'stateChange', callback: Callback<AudioState\>): void 7670 7671Subscribes to the audio renderer state change event, which is triggered when the state of the audio renderer is changed. This API uses an asynchronous callback to return the result. 7672 7673**System capability**: SystemCapability.Multimedia.Audio.Renderer 7674 7675**Parameters** 7676 7677| Name | Type | Mandatory| Description | 7678| :------- | :------------------------- | :--- | :------------------------------------------ | 7679| type | string | Yes | Event type. The value is fixed at **'stateChange'**.| 7680| callback | Callback\<[AudioState](#audiostate8)> | Yes | Callback used to return the audio status.| 7681 7682**Example** 7683 7684```ts 7685audioRenderer.on('stateChange', (state: audio.AudioState) => { 7686 if (state == 1) { 7687 console.info('audio renderer state is: STATE_PREPARED'); 7688 } 7689 if (state == 2) { 7690 console.info('audio renderer state is: STATE_RUNNING'); 7691 } 7692}); 7693``` 7694 7695### on('outputDeviceChange')<sup>10+</sup> 7696 7697on(type: 'outputDeviceChange', callback: Callback\<AudioDeviceDescriptors>): void 7698 7699Subscribes to the audio output device change event, which is triggered when an audio output device is changed. This API uses an asynchronous callback to return the result. 7700 7701**System capability**: SystemCapability.Multimedia.Audio.Device 7702 7703**Parameters** 7704 7705| Name | Type | Mandatory| Description | 7706| :------- | :------------------------- | :--- | :------------------------------------------ | 7707| type | string | Yes | Event type. The value is fixed at **'outputDeviceChange'**.| 7708| callback | Callback\<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Yes | Callback used to return the output device descriptor of the current audio stream.| 7709 7710**Error codes** 7711 7712For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7713 7714| ID| Error Message| 7715| ------- | --------------------------------------------| 7716| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7717| 6800101 | Parameter verification failed. | 7718 7719**Example** 7720 7721```ts 7722audioRenderer.on('outputDeviceChange', (deviceInfo: audio.AudioDeviceDescriptors) => { 7723 console.info(`DeviceInfo id: ${deviceInfo[0].id}`); 7724 console.info(`DeviceInfo name: ${deviceInfo[0].name}`); 7725 console.info(`DeviceInfo address: ${deviceInfo[0].address}`); 7726}); 7727``` 7728 7729### off('outputDeviceChange')<sup>10+</sup> 7730 7731off(type: 'outputDeviceChange', callback?: Callback\<AudioDeviceDescriptors>): void 7732 7733Unsubscribes from the audio output device change event. This API uses an asynchronous callback to return the result. 7734 7735**System capability**: SystemCapability.Multimedia.Audio.Device 7736 7737**Parameters** 7738 7739| Name | Type | Mandatory| Description | 7740| :------- | :------------------------- | :--- | :------------------------------------------ | 7741| type | string | Yes | Event type. The value is fixed at **'outputDeviceChange'**.| 7742| callback | Callback\<[AudioDeviceDescriptors](#audiodevicedescriptors)> | No | Callback used to return the output device descriptor of the current audio stream.| 7743 7744**Error codes** 7745 7746For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7747 7748| ID| Error Message| 7749| ------- | --------------------------------------------| 7750| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7751| 6800101 | Parameter verification failed. | 7752 7753**Example** 7754 7755```ts 7756// Cancel all subscriptions to the event. 7757audioRenderer.off('outputDeviceChange'); 7758 7759// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 7760let outputDeviceChangeCallback = (deviceInfo: audio.AudioDeviceDescriptors) => { 7761 console.info(`DeviceInfo id: ${deviceInfo[0].id}`); 7762 console.info(`DeviceInfo name: ${deviceInfo[0].name}`); 7763 console.info(`DeviceInfo address: ${deviceInfo[0].address}`); 7764}; 7765 7766audioRenderer.on('outputDeviceChange', outputDeviceChangeCallback); 7767 7768audioRenderer.off('outputDeviceChange', outputDeviceChangeCallback); 7769``` 7770 7771### on('outputDeviceChangeWithInfo')<sup>11+</sup> 7772 7773on(type: 'outputDeviceChangeWithInfo', callback: Callback\<AudioStreamDeviceChangeInfo>): void 7774 7775Subscribes to the change event of audio output devices and reasons, which is triggered when an audio output device changes, and the change reason is reported. This API uses an asynchronous callback to return the result. 7776 7777**System capability**: SystemCapability.Multimedia.Audio.Device 7778 7779**Parameters** 7780 7781| Name | Type | Mandatory| Description | 7782| :------- |:-------------------------------------------------------------------------| :--- |:--------------------------------------------| 7783| type | string | Yes | Event type. The value is fixed at **'outputDeviceChangeWithInfo'**.| 7784| callback | Callback\<[AudioStreamDeviceChangeInfo](#audiostreamdevicechangeinfo11)> | Yes | Callback used to return the output device descriptor of the current audio stream and the change reason.| 7785 7786**Error codes** 7787 7788For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7789 7790| ID| Error Message| 7791| ------- | --------------------------------------------| 7792| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7793| 6800101 | Parameter verification failed. | 7794 7795**Example** 7796 7797```ts 7798audioRenderer.on('outputDeviceChangeWithInfo', (deviceChangeInfo: audio.AudioStreamDeviceChangeInfo) => { 7799 console.info(`DeviceInfo id: ${deviceChangeInfo.devices[0].id}`); 7800 console.info(`DeviceInfo name: ${deviceChangeInfo.devices[0].name}`); 7801 console.info(`DeviceInfo address: ${deviceChangeInfo.devices[0].address}`); 7802 console.info(`Device change reason: ${deviceChangeInfo.changeReason}`); 7803}); 7804``` 7805 7806### off('outputDeviceChangeWithInfo')<sup>11+</sup> 7807 7808off(type: 'outputDeviceChangeWithInfo', callback?: Callback\<AudioStreamDeviceChangeInfo>): void 7809 7810Unsubscribes from audio output device changes and reasons. This API uses an asynchronous callback to return the result. 7811 7812**System capability**: SystemCapability.Multimedia.Audio.Device 7813 7814**Parameters** 7815 7816| Name | Type | Mandatory| Description | 7817| :------- |:-------------------------------------------------------------------------| :--- |:--------------------------------------------| 7818| type | string | Yes | Event type. The value is fixed at **'outputDeviceChangeWithInfo'**.| 7819| callback | Callback\<[AudioStreamDeviceChangeInfo](#audiostreamdevicechangeinfo11)> | No | Callback used to return the output device descriptor of the current audio stream and the change reason.| 7820 7821**Error codes** 7822 7823For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7824 7825| ID| Error Message| 7826| ------- | --------------------------------------------| 7827| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7828| 6800101 | Parameter verification failed. | 7829 7830**Example** 7831 7832```ts 7833// Cancel all subscriptions to the event. 7834audioRenderer.off('outputDeviceChangeWithInfo'); 7835 7836// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 7837let outputDeviceChangeWithInfoCallback = (deviceChangeInfo: audio.AudioStreamDeviceChangeInfo) => { 7838 console.info(`DeviceInfo id: ${deviceChangeInfo.devices[0].id}`); 7839 console.info(`DeviceInfo name: ${deviceChangeInfo.devices[0].name}`); 7840 console.info(`DeviceInfo address: ${deviceChangeInfo.devices[0].address}`); 7841 console.info(`Device change reason: ${deviceChangeInfo.changeReason}`); 7842}; 7843 7844audioRenderer.on('outputDeviceChangeWithInfo', outputDeviceChangeWithInfoCallback); 7845 7846audioRenderer.off('outputDeviceChangeWithInfo', outputDeviceChangeWithInfoCallback); 7847``` 7848 7849### on('writeData')<sup>11+</sup> 7850 7851on(type: 'writeData', callback: AudioRendererWriteDataCallback): void 7852 7853Subscribes to the audio data write event, which is triggered when audio data needs to be written. This API uses an asynchronous callback to return the result. 7854 7855The callback function is used only to write audio data. Do not call AudioRenderer APIs in it. 7856 7857**System capability**: SystemCapability.Multimedia.Audio.Renderer 7858 7859**Parameters** 7860 7861| Name | Type | Mandatory| Description | 7862| :------- |:--------------------------------| :--- |:--------------------------------------| 7863| type | string | Yes | Event type. The value is fixed at **'writeData'**.| 7864| callback | [AudioRendererWriteDataCallback](#audiorendererwritedatacallback12) | Yes | Callback used to write the data to the buffer.<br>API version 11 does not support the return of the callback result. API version 12 and later support the return of the callback result [AudioDataCallbackResult](#audiodatacallbackresult12). | 7865 7866**Error codes** 7867 7868For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7869 7870| ID| Error Message| 7871| ------- | --------------------------------------------| 7872| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7873| 6800101 | Parameter verification failed. | 7874 7875**Example** 7876 7877```ts 7878import { BusinessError } from '@kit.BasicServicesKit'; 7879import {fileIo as fs} from '@kit.CoreFileKit'; 7880 7881class Options { 7882 offset?: number; 7883 length?: number; 7884} 7885 7886let bufferSize: number = 0; 7887let path = getContext().cacheDir; 7888// Ensure that the resource exists in the path. 7889let filePath = path + '/StarWars10s-2C-48000-4SW.wav'; 7890let file: fs.File = fs.openSync(filePath, fs.OpenMode.READ_ONLY); 7891let writeDataCallback = (buffer: ArrayBuffer) => { 7892 let options: Options = { 7893 offset: bufferSize, 7894 length: buffer.byteLength 7895 }; 7896 7897 try { 7898 fs.readSync(file.fd, buffer, options); 7899 bufferSize += buffer.byteLength; 7900 // API version 11 does not support the return of the callback result. API version 12 and later support the return of the callback result. 7901 return audio.AudioDataCallbackResult.VALID; 7902 } catch (error) { 7903 console.error('Error reading file:', error); 7904 // API version 11 does not support the return of the callback result. API version 12 and later support the return of the callback result. 7905 return audio.AudioDataCallbackResult.INVALID; 7906 } 7907}; 7908 7909audioRenderer.on('writeData', writeDataCallback); 7910audioRenderer.start().then(() => { 7911 console.info('Renderer started'); 7912}).catch((err: BusinessError) => { 7913 console.error(`ERROR: ${err}`); 7914}); 7915``` 7916 7917### off('writeData')<sup>11+</sup> 7918 7919off(type: 'writeData', callback?: AudioRendererWriteDataCallback): void 7920 7921Unsubscribes from the audio data write event. This API uses an asynchronous callback to return the result. 7922 7923**System capability**: SystemCapability.Multimedia.Audio.Renderer 7924 7925**Parameters** 7926 7927| Name | Type | Mandatory| Description | 7928| :------- |:--------------------------------| :--- |:--------------------------------------| 7929| type | string | Yes | Event type. The value is fixed at **'writeData'**.| 7930| callback | [AudioRendererWriteDataCallback](#audiorendererwritedatacallback12) | No | Callback used to write the data to the buffer.<br>API version 11 does not support the return of the callback result. API version 12 and later support the return of the callback result [AudioDataCallbackResult](#audiodatacallbackresult12).| 7931 7932**Error codes** 7933 7934For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7935 7936| ID| Error Message| 7937| ------- | --------------------------------------------| 7938| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7939| 6800101 | Parameter verification failed. | 7940 7941**Example** 7942 7943```ts 7944// Cancel all subscriptions to the event. 7945audioRenderer.off('writeData'); 7946 7947// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 7948let writeDataCallback = (data: ArrayBuffer) => { 7949 console.info(`write data: ${data}`); 7950}; 7951 7952audioRenderer.on('writeData', writeDataCallback); 7953 7954audioRenderer.off('writeData', writeDataCallback); 7955``` 7956 7957## AudioCapturer<sup>8+</sup> 7958 7959Provides APIs for audio capture. Before calling any API in **AudioCapturer**, you must use [createAudioCapturer](#audiocreateaudiocapturer8) to create an **AudioCapturer** instance. 7960 7961### Attributes 7962 7963**System capability**: SystemCapability.Multimedia.Audio.Capturer 7964 7965| Name | Type | Readable| Writable| Description | 7966| :---- | :------------------------- | :--- | :--- | :--------------- | 7967| state<sup>8+</sup> | [AudioState](#audiostate8) | Yes| No | Audio capturer state.| 7968 7969**Example** 7970 7971```ts 7972import { audio } from '@kit.AudioKit'; 7973 7974let state: audio.AudioState = audioCapturer.state; 7975``` 7976 7977### getCapturerInfo<sup>8+</sup> 7978 7979getCapturerInfo(callback: AsyncCallback<AudioCapturerInfo\>): void 7980 7981Obtains the capturer information of this **AudioCapturer** instance. This API uses an asynchronous callback to return the result. 7982 7983**System capability**: SystemCapability.Multimedia.Audio.Capturer 7984 7985**Parameters** 7986 7987| Name | Type | Mandatory| Description | 7988| :------- | :-------------------------------- | :--- | :----------------------------------- | 7989| callback | AsyncCallback<[AudioCapturerInfo](#audiocapturerinfo8)\> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the capturer information obtained; otherwise, **err** is an error object.| 7990 7991**Example** 7992 7993```ts 7994import { BusinessError } from '@kit.BasicServicesKit'; 7995 7996audioCapturer.getCapturerInfo((err: BusinessError, capturerInfo: audio.AudioCapturerInfo) => { 7997 if (err) { 7998 console.error('Failed to get capture info'); 7999 } else { 8000 console.info('Capturer getCapturerInfo:'); 8001 console.info(`Capturer source: ${capturerInfo.source}`); 8002 console.info(`Capturer flags: ${capturerInfo.capturerFlags}`); 8003 } 8004}); 8005``` 8006 8007 8008### getCapturerInfo<sup>8+</sup> 8009 8010getCapturerInfo(): Promise<AudioCapturerInfo\> 8011 8012Obtains the capturer information of this **AudioCapturer** instance. This API uses a promise to return the result. 8013 8014**System capability**: SystemCapability.Multimedia.Audio.Capturer 8015 8016**Return value** 8017 8018| Type | Description | 8019| :------------------------------------------------ | :---------------------------------- | 8020| Promise<[AudioCapturerInfo](#audiocapturerinfo8)\> | Promise used to return capturer information.| 8021 8022**Example** 8023 8024```ts 8025import { BusinessError } from '@kit.BasicServicesKit'; 8026 8027audioCapturer.getCapturerInfo().then((audioParamsGet: audio.AudioCapturerInfo) => { 8028 if (audioParamsGet != undefined) { 8029 console.info('AudioFrameworkRecLog: Capturer CapturerInfo:'); 8030 console.info(`AudioFrameworkRecLog: Capturer SourceType: ${audioParamsGet.source}`); 8031 console.info(`AudioFrameworkRecLog: Capturer capturerFlags: ${audioParamsGet.capturerFlags}`); 8032 } else { 8033 console.info(`AudioFrameworkRecLog: audioParamsGet is : ${audioParamsGet}`); 8034 console.info('AudioFrameworkRecLog: audioParams getCapturerInfo are incorrect'); 8035 } 8036}).catch((err: BusinessError) => { 8037 console.error(`AudioFrameworkRecLog: CapturerInfo :ERROR: ${err}`); 8038}) 8039``` 8040 8041### getCapturerInfoSync<sup>10+</sup> 8042 8043getCapturerInfoSync(): AudioCapturerInfo 8044 8045Obtains the capturer information of this **AudioCapturer** instance. This API returns the result synchronously. 8046 8047**System capability**: SystemCapability.Multimedia.Audio.Capturer 8048 8049**Return value** 8050 8051| Type | Description | 8052| :------------------------------------------------ | :---------------------------------- | 8053| [AudioCapturerInfo](#audiocapturerinfo8) | Capturer information.| 8054 8055**Example** 8056 8057```ts 8058import { BusinessError } from '@kit.BasicServicesKit'; 8059 8060try { 8061 let audioParamsGet: audio.AudioCapturerInfo = audioCapturer.getCapturerInfoSync(); 8062 console.info(`AudioFrameworkRecLog: Capturer SourceType: ${audioParamsGet.source}`); 8063 console.info(`AudioFrameworkRecLog: Capturer capturerFlags: ${audioParamsGet.capturerFlags}`); 8064} catch (err) { 8065 let error = err as BusinessError; 8066 console.error(`AudioFrameworkRecLog: CapturerInfo :ERROR: ${error}`); 8067} 8068``` 8069 8070### getStreamInfo<sup>8+</sup> 8071 8072getStreamInfo(callback: AsyncCallback<AudioStreamInfo\>): void 8073 8074Obtains the stream information of this **AudioCapturer** instance. This API uses an asynchronous callback to return the result. 8075 8076**System capability**: SystemCapability.Multimedia.Audio.Capturer 8077 8078**Parameters** 8079 8080| Name | Type | Mandatory| Description | 8081| :------- | :--------------------------------------------------- | :--- | :------------------------------- | 8082| callback | AsyncCallback<[AudioStreamInfo](#audiostreaminfo8)\> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the stream information obtained; otherwise, **err** is an error object.| 8083 8084**Example** 8085 8086```ts 8087import { BusinessError } from '@kit.BasicServicesKit'; 8088 8089audioCapturer.getStreamInfo((err: BusinessError, streamInfo: audio.AudioStreamInfo) => { 8090 if (err) { 8091 console.error('Failed to get stream info'); 8092 } else { 8093 console.info('Capturer GetStreamInfo:'); 8094 console.info(`Capturer sampling rate: ${streamInfo.samplingRate}`); 8095 console.info(`Capturer channel: ${streamInfo.channels}`); 8096 console.info(`Capturer format: ${streamInfo.sampleFormat}`); 8097 console.info(`Capturer encoding type: ${streamInfo.encodingType}`); 8098 } 8099}); 8100``` 8101 8102### getStreamInfo<sup>8+</sup> 8103 8104getStreamInfo(): Promise<AudioStreamInfo\> 8105 8106Obtains the stream information of this **AudioCapturer** instance. This API uses a promise to return the result. 8107 8108**System capability**: SystemCapability.Multimedia.Audio.Capturer 8109 8110**Return value** 8111 8112| Type | Description | 8113| :--------------------------------------------- | :------------------------------ | 8114| Promise<[AudioStreamInfo](#audiostreaminfo8)\> | Promise used to return the stream information.| 8115 8116**Example** 8117 8118```ts 8119import { BusinessError } from '@kit.BasicServicesKit'; 8120 8121audioCapturer.getStreamInfo().then((audioParamsGet: audio.AudioStreamInfo) => { 8122 console.info('getStreamInfo:'); 8123 console.info(`sampleFormat: ${audioParamsGet.sampleFormat}`); 8124 console.info(`samplingRate: ${audioParamsGet.samplingRate}`); 8125 console.info(`channels: ${audioParamsGet.channels}`); 8126 console.info(`encodingType: ${audioParamsGet.encodingType}`); 8127}).catch((err: BusinessError) => { 8128 console.error(`getStreamInfo :ERROR: ${err}`); 8129}); 8130``` 8131 8132### getStreamInfoSync<sup>10+</sup> 8133 8134getStreamInfoSync(): AudioStreamInfo 8135 8136Obtains the stream information of this **AudioCapturer** instance. This API returns the result synchronously. 8137 8138**System capability**: SystemCapability.Multimedia.Audio.Capturer 8139 8140**Return value** 8141 8142| Type | Description | 8143| :--------------------------------------------- | :------------------------------ | 8144| [AudioStreamInfo](#audiostreaminfo8) | Stream information.| 8145 8146**Example** 8147 8148```ts 8149import { BusinessError } from '@kit.BasicServicesKit'; 8150 8151try { 8152 let audioParamsGet: audio.AudioStreamInfo = audioCapturer.getStreamInfoSync(); 8153 console.info(`sampleFormat: ${audioParamsGet.sampleFormat}`); 8154 console.info(`samplingRate: ${audioParamsGet.samplingRate}`); 8155 console.info(`channels: ${audioParamsGet.channels}`); 8156 console.info(`encodingType: ${audioParamsGet.encodingType}`); 8157} catch (err) { 8158 let error = err as BusinessError; 8159 console.error(`getStreamInfo :ERROR: ${error}`); 8160} 8161``` 8162 8163### getAudioStreamId<sup>9+</sup> 8164 8165getAudioStreamId(callback: AsyncCallback<number\>): void 8166 8167Obtains the stream ID of this **AudioCapturer** instance. This API uses an asynchronous callback to return the result. 8168 8169**System capability**: SystemCapability.Multimedia.Audio.Capturer 8170 8171**Parameters** 8172 8173| Name | Type | Mandatory| Description | 8174| :------- | :--------------------------------------------------- | :--- | :------------------- | 8175| callback | AsyncCallback<number\> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the stream ID obtained; otherwise, **err** is an error object.| 8176 8177**Example** 8178 8179```ts 8180import { BusinessError } from '@kit.BasicServicesKit'; 8181 8182audioCapturer.getAudioStreamId((err: BusinessError, streamId: number) => { 8183 console.info(`audioCapturer GetStreamId: ${streamId}`); 8184}); 8185``` 8186 8187### getAudioStreamId<sup>9+</sup> 8188 8189getAudioStreamId(): Promise<number\> 8190 8191Obtains the stream ID of this **AudioCapturer** instance. This API uses a promise to return the result. 8192 8193**System capability**: SystemCapability.Multimedia.Audio.Capturer 8194 8195**Return value** 8196 8197| Type | Description | 8198| :----------------| :--------------------- | 8199| Promise<number\> | Promise used to return the stream ID.| 8200 8201**Example** 8202 8203```ts 8204import { BusinessError } from '@kit.BasicServicesKit'; 8205 8206audioCapturer.getAudioStreamId().then((streamId: number) => { 8207 console.info(`audioCapturer getAudioStreamId: ${streamId}`); 8208}).catch((err: BusinessError) => { 8209 console.error(`ERROR: ${err}`); 8210}); 8211``` 8212 8213### getAudioStreamIdSync<sup>10+</sup> 8214 8215getAudioStreamIdSync(): number 8216 8217Obtains the stream ID of this **AudioCapturer** instance. This API returns the result synchronously. 8218 8219**System capability**: SystemCapability.Multimedia.Audio.Capturer 8220 8221**Return value** 8222 8223| Type | Description | 8224| :----------------| :--------------------- | 8225| number | Stream ID.| 8226 8227**Example** 8228 8229```ts 8230import { BusinessError } from '@kit.BasicServicesKit'; 8231 8232try { 8233 let streamId: number = audioCapturer.getAudioStreamIdSync(); 8234 console.info(`audioCapturer getAudioStreamIdSync: ${streamId}`); 8235} catch (err) { 8236 let error = err as BusinessError; 8237 console.error(`ERROR: ${error}`); 8238} 8239``` 8240 8241### start<sup>8+</sup> 8242 8243start(callback: AsyncCallback<void\>): void 8244 8245Starts capturing. This API uses an asynchronous callback to return the result. 8246 8247**System capability**: SystemCapability.Multimedia.Audio.Capturer 8248 8249**Parameters** 8250 8251| Name | Type | Mandatory| Description | 8252| :------- | :------------------- | :--- | :----------------------------- | 8253| callback | AsyncCallback<void\> | Yes | Callback used to return the result. If the operation fails, an error object with the following error code is returned:<br>Error code 6800301: indicates abnormal status, focus preemption failure, and abnormal system processing. For details, see system logs.| 8254 8255**Example** 8256 8257```ts 8258import { BusinessError } from '@kit.BasicServicesKit'; 8259 8260audioCapturer.start((err: BusinessError) => { 8261 if (err) { 8262 console.error('Capturer start failed.'); 8263 } else { 8264 console.info('Capturer start success.'); 8265 } 8266}); 8267``` 8268 8269 8270### start<sup>8+</sup> 8271 8272start(): Promise<void\> 8273 8274Starts capturing. This API uses a promise to return the result. 8275 8276**System capability**: SystemCapability.Multimedia.Audio.Capturer 8277 8278**Return value** 8279 8280| Type | Description | 8281| :------------- | :---------------------------- | 8282| Promise<void\> | Promise used to return the result. If the operation fails, an error object with the following error code is returned:<br>Error code 6800301: indicates abnormal status, focus preemption failure, and abnormal system processing. For details, see system logs.| 8283 8284**Example** 8285 8286```ts 8287import { BusinessError } from '@kit.BasicServicesKit'; 8288 8289audioCapturer.start().then(() => { 8290 console.info('AudioFrameworkRecLog: ---------START---------'); 8291 console.info('AudioFrameworkRecLog: Capturer started: SUCCESS'); 8292 console.info(`AudioFrameworkRecLog: AudioCapturer: STATE: ${audioCapturer.state}`); 8293 console.info('AudioFrameworkRecLog: Capturer started: SUCCESS'); 8294 if ((audioCapturer.state == audio.AudioState.STATE_RUNNING)) { 8295 console.info('AudioFrameworkRecLog: AudioCapturer is in Running State'); 8296 } 8297}).catch((err: BusinessError) => { 8298 console.error(`AudioFrameworkRecLog: Capturer start :ERROR : ${err}`); 8299}); 8300``` 8301 8302### stop<sup>8+</sup> 8303 8304stop(callback: AsyncCallback<void\>): void 8305 8306Stops capturing. This API uses an asynchronous callback to return the result. 8307 8308**System capability**: SystemCapability.Multimedia.Audio.Capturer 8309 8310**Parameters** 8311 8312| Name | Type | Mandatory| Description | 8313| :------- | :------------------- | :--- | :----------------------------- | 8314| callback | AsyncCallback<void\> | Yes | Callback used to return the result. If the vibration stops, **err** is **undefined**; otherwise, **err** is an error object.| 8315 8316**Example** 8317 8318```ts 8319import { BusinessError } from '@kit.BasicServicesKit'; 8320 8321audioCapturer.stop((err: BusinessError) => { 8322 if (err) { 8323 console.error('Capturer stop failed'); 8324 } else { 8325 console.info('Capturer stopped.'); 8326 } 8327}); 8328``` 8329 8330 8331### stop<sup>8+</sup> 8332 8333stop(): Promise<void\> 8334 8335Stops capturing. This API uses a promise to return the result. 8336 8337**System capability**: SystemCapability.Multimedia.Audio.Capturer 8338 8339**Return value** 8340 8341| Type | Description | 8342| :------------- | :---------------------------- | 8343| Promise<void\> | Promise that returns no value.| 8344 8345**Example** 8346 8347```ts 8348import { BusinessError } from '@kit.BasicServicesKit'; 8349 8350audioCapturer.stop().then(() => { 8351 console.info('AudioFrameworkRecLog: ---------STOP RECORD---------'); 8352 console.info('AudioFrameworkRecLog: Capturer stopped: SUCCESS'); 8353 if ((audioCapturer.state == audio.AudioState.STATE_STOPPED)){ 8354 console.info('AudioFrameworkRecLog: State is Stopped:'); 8355 } 8356}).catch((err: BusinessError) => { 8357 console.error(`AudioFrameworkRecLog: Capturer stop: ERROR: ${err}`); 8358}); 8359``` 8360 8361### release<sup>8+</sup> 8362 8363release(callback: AsyncCallback<void\>): void 8364 8365Releases this **AudioCapturer** instance. This API uses an asynchronous callback to return the result. 8366 8367**System capability**: SystemCapability.Multimedia.Audio.Capturer 8368 8369**Parameters** 8370 8371| Name | Type | Mandatory| Description | 8372| :------- | :------------------- | :--- | :---------------------------------- | 8373| callback | AsyncCallback<void\> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 8374 8375**Example** 8376 8377```ts 8378import { BusinessError } from '@kit.BasicServicesKit'; 8379 8380audioCapturer.release((err: BusinessError) => { 8381 if (err) { 8382 console.error('capturer release failed'); 8383 } else { 8384 console.info('capturer released.'); 8385 } 8386}); 8387``` 8388 8389 8390### release<sup>8+</sup> 8391 8392release(): Promise<void\> 8393 8394Releases this **AudioCapturer** instance. This API uses a promise to return the result. 8395 8396**System capability**: SystemCapability.Multimedia.Audio.Capturer 8397 8398**Return value** 8399 8400| Type | Description | 8401| :------------- | :---------------------------- | 8402| Promise<void\> | Promise that returns no value.| 8403 8404**Example** 8405 8406```ts 8407import { BusinessError } from '@kit.BasicServicesKit'; 8408 8409audioCapturer.release().then(() => { 8410 console.info('AudioFrameworkRecLog: ---------RELEASE RECORD---------'); 8411 console.info('AudioFrameworkRecLog: Capturer release : SUCCESS'); 8412 console.info(`AudioFrameworkRecLog: AudioCapturer : STATE : ${audioCapturer.state}`); 8413}).catch((err: BusinessError) => { 8414 console.error(`AudioFrameworkRecLog: Capturer stop: ERROR: ${err}`); 8415}); 8416``` 8417 8418### read<sup>8+(deprecated)</sup> 8419 8420read(size: number, isBlockingRead: boolean, callback: AsyncCallback<ArrayBuffer\>): void 8421 8422Reads the buffer. This API uses an asynchronous callback to return the result. 8423 8424> **NOTE** 8425> 8426> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [on('readData')](#onreaddata11) in **AudioCapturer**. 8427 8428**System capability**: SystemCapability.Multimedia.Audio.Capturer 8429 8430**Parameters** 8431 8432| Name | Type | Mandatory| Description | 8433| :------------- | :-------------------------- | :--- | :------------------------------- | 8434| size | number | Yes | Number of bytes to read. | 8435| isBlockingRead | boolean | Yes | Whether to block the read operation. The value **true** means to block the read operation, and **false** means the opposite. | 8436| callback | AsyncCallback<ArrayBuffer\> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the buffer read; otherwise, **err** is an error object.| 8437 8438**Example** 8439 8440```ts 8441import { BusinessError } from '@kit.BasicServicesKit'; 8442 8443let bufferSize: number = 0; 8444 8445audioCapturer.getBufferSize().then((data: number) => { 8446 console.info(`AudioFrameworkRecLog: getBufferSize: SUCCESS ${data}`); 8447 bufferSize = data; 8448}).catch((err: BusinessError) => { 8449 console.error(`AudioFrameworkRecLog: getBufferSize: ERROR: ${err}`); 8450}); 8451 8452audioCapturer.read(bufferSize, true, (err: BusinessError, buffer: ArrayBuffer) => { 8453 if (!err) { 8454 console.info('Success in reading the buffer data'); 8455 } 8456}); 8457``` 8458 8459### read<sup>8+(deprecated)</sup> 8460 8461read(size: number, isBlockingRead: boolean): Promise<ArrayBuffer\> 8462 8463Reads the buffer. This API uses a promise to return the result. 8464 8465> **NOTE** 8466> 8467> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [on('readData')](#onreaddata11) in **AudioCapturer**. 8468 8469**System capability**: SystemCapability.Multimedia.Audio.Capturer 8470 8471**Parameters** 8472 8473| Name | Type | Mandatory| Description | 8474| :------------- | :------ | :--- | :--------------- | 8475| size | number | Yes | Number of bytes to read. | 8476| isBlockingRead | boolean | Yes | Whether to block the read operation. The value **true** means to block the read operation, and **false** means the opposite.| 8477 8478**Return value** 8479 8480| Type | Description | 8481| :-------------------- | :----------------------------------------------------- | 8482| Promise<ArrayBuffer\> | Promise used to return the data read from the buffer.| 8483 8484**Example** 8485 8486```ts 8487import { BusinessError } from '@kit.BasicServicesKit'; 8488 8489let bufferSize: number = 0; 8490 8491audioCapturer.getBufferSize().then((data: number) => { 8492 console.info(`AudioFrameworkRecLog: getBufferSize: SUCCESS ${data}`); 8493 bufferSize = data; 8494}).catch((err: BusinessError) => { 8495 console.error(`AudioFrameworkRecLog: getBufferSize: ERROR ${err}`); 8496}); 8497console.info(`Buffer size: ${bufferSize}`); 8498 8499audioCapturer.read(bufferSize, true).then((buffer: ArrayBuffer) => { 8500 console.info('buffer read successfully'); 8501}).catch((err: BusinessError) => { 8502 console.error(`ERROR : ${err}`); 8503}); 8504``` 8505 8506### getAudioTime<sup>8+</sup> 8507 8508getAudioTime(callback: AsyncCallback<number\>): void 8509 8510Obtains the timestamp of the current recording position, measured in nanoseconds from the Unix epoch (January 1, 1970). This API uses an asynchronous callback to return the result. 8511 8512**System capability**: SystemCapability.Multimedia.Audio.Capturer 8513 8514**Parameters** 8515 8516| Name | Type | Mandatory| Description | 8517| :------- | :--------------------- | :--- | :----------------------------- | 8518| callback | AsyncCallback<number\> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the number of nanoseconds obtained; otherwise, **err** is an error object.| 8519 8520**Example** 8521 8522```ts 8523import { BusinessError } from '@kit.BasicServicesKit'; 8524 8525audioCapturer.getAudioTime((err: BusinessError, timestamp: number) => { 8526 console.info(`Current timestamp: ${timestamp}`); 8527}); 8528``` 8529 8530### getAudioTime<sup>8+</sup> 8531 8532getAudioTime(): Promise<number\> 8533 8534Obtains the timestamp of the current recording position, measured in nanoseconds from the Unix epoch (January 1, 1970). This API uses a promise to return the result. 8535 8536**System capability**: SystemCapability.Multimedia.Audio.Capturer 8537 8538**Return value** 8539 8540| Type | Description | 8541| :--------------- | :---------------------------- | 8542| Promise<number\> | Promise used to return the number of nanoseconds elapsed from the Unix epoch.| 8543 8544**Example** 8545 8546```ts 8547import { BusinessError } from '@kit.BasicServicesKit'; 8548 8549audioCapturer.getAudioTime().then((audioTime: number) => { 8550 console.info(`AudioFrameworkRecLog: AudioCapturer getAudioTime : Success ${audioTime}`); 8551}).catch((err: BusinessError) => { 8552 console.error(`AudioFrameworkRecLog: AudioCapturer Created : ERROR : ${err}`); 8553}); 8554``` 8555 8556### getAudioTimeSync<sup>10+</sup> 8557 8558getAudioTimeSync(): number 8559 8560Obtains the timestamp of the current recording position, measured in nanoseconds from the Unix epoch (January 1, 1970). This API returns the result synchronously: 8561 8562**System capability**: SystemCapability.Multimedia.Audio.Capturer 8563 8564**Return value** 8565 8566| Type | Description | 8567| :--------------- | :---------------------------- | 8568| number | Timestamp.| 8569 8570**Example** 8571 8572```ts 8573import { BusinessError } from '@kit.BasicServicesKit'; 8574 8575try { 8576 let audioTime: number = audioCapturer.getAudioTimeSync(); 8577 console.info(`AudioFrameworkRecLog: AudioCapturer getAudioTimeSync : Success ${audioTime}`); 8578} catch (err) { 8579 let error = err as BusinessError; 8580 console.error(`AudioFrameworkRecLog: AudioCapturer getAudioTimeSync : ERROR : ${error}`); 8581} 8582``` 8583 8584### getBufferSize<sup>8+</sup> 8585 8586getBufferSize(callback: AsyncCallback<number\>): void 8587 8588Obtains a reasonable minimum buffer size in bytes for capturing. This API uses an asynchronous callback to return the result. 8589 8590**System capability**: SystemCapability.Multimedia.Audio.Capturer 8591 8592**Parameters** 8593 8594| Name | Type | Mandatory| Description | 8595| :------- | :--------------------- | :--- | :----------------------------------- | 8596| callback | AsyncCallback<number\> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the minimum buffer size obtained; otherwise, **err** is an error object.| 8597 8598**Example** 8599 8600```ts 8601import { BusinessError } from '@kit.BasicServicesKit'; 8602 8603audioCapturer.getBufferSize((err: BusinessError, bufferSize: number) => { 8604 if (!err) { 8605 console.info(`BufferSize : ${bufferSize}`); 8606 audioCapturer.read(bufferSize, true).then((buffer: ArrayBuffer) => { 8607 console.info(`Buffer read is ${buffer.byteLength}`); 8608 }).catch((err: BusinessError) => { 8609 console.error(`AudioFrameworkRecLog: AudioCapturer Created : ERROR : ${err}`); 8610 }); 8611 } 8612}); 8613``` 8614 8615### getBufferSize<sup>8+</sup> 8616 8617getBufferSize(): Promise<number\> 8618 8619Obtains a reasonable minimum buffer size in bytes for capturing. This API uses a promise to return the result. 8620 8621**System capability**: SystemCapability.Multimedia.Audio.Capturer 8622 8623**Return value** 8624 8625| Type | Description | 8626| :--------------- | :---------------------------------- | 8627| Promise<number\> | Promise used to return the buffer size.| 8628 8629**Example** 8630 8631```ts 8632import { BusinessError } from '@kit.BasicServicesKit'; 8633 8634let bufferSize: number = 0; 8635 8636audioCapturer.getBufferSize().then((data: number) => { 8637 console.info(`AudioFrameworkRecLog: getBufferSize :SUCCESS ${data}`); 8638 bufferSize = data; 8639}).catch((err: BusinessError) => { 8640 console.error(`AudioFrameworkRecLog: getBufferSize :ERROR : ${err}`); 8641}); 8642``` 8643 8644### getBufferSizeSync<sup>10+</sup> 8645 8646getBufferSizeSync(): number 8647 8648Obtains a reasonable minimum buffer size in bytes for capturing. This API returns the result synchronously. 8649 8650**System capability**: SystemCapability.Multimedia.Audio.Capturer 8651 8652**Return value** 8653 8654| Type | Description | 8655| :--------------- | :---------------------------------- | 8656| number | Buffer size.| 8657 8658**Example** 8659 8660```ts 8661import { BusinessError } from '@kit.BasicServicesKit'; 8662 8663let bufferSize: number = 0; 8664 8665try { 8666 bufferSize = audioCapturer.getBufferSizeSync(); 8667 console.info(`AudioFrameworkRecLog: getBufferSizeSync :SUCCESS ${bufferSize}`); 8668} catch (err) { 8669 let error = err as BusinessError; 8670 console.error(`AudioFrameworkRecLog: getBufferSizeSync :ERROR : ${error}`); 8671} 8672``` 8673 8674### getCurrentInputDevices<sup>11+</sup> 8675 8676getCurrentInputDevices(): AudioDeviceDescriptors 8677 8678Obtains the descriptors of the current input devices. This API returns the result synchronously. 8679 8680**System capability**: SystemCapability.Multimedia.Audio.Device 8681 8682**Return value** 8683 8684| Type | Description | 8685| ---------------------- | ------------------------------------------------------ | 8686| [AudioDeviceDescriptors](#audiodevicedescriptors) | An array of the audio device descriptors.| 8687 8688**Example** 8689 8690```ts 8691let deviceDescriptors: audio.AudioDeviceDescriptors = audioCapturer.getCurrentInputDevices(); 8692console.info(`Device id: ${deviceDescriptors[0].id}`); 8693console.info(`Device type: ${deviceDescriptors[0].deviceType}`); 8694console.info(`Device role: ${deviceDescriptors[0].deviceRole}`); 8695console.info(`Device name: ${deviceDescriptors[0].name}`); 8696console.info(`Device address: ${deviceDescriptors[0].address}`); 8697console.info(`Device samplerates: ${deviceDescriptors[0].sampleRates[0]}`); 8698console.info(`Device channelcounts: ${deviceDescriptors[0].channelCounts[0]}`); 8699console.info(`Device channelmask: ${deviceDescriptors[0].channelMasks[0]}`); 8700if (deviceDescriptors[0].encodingTypes) { 8701 console.info(`Device encodingTypes: ${deviceDescriptors[0].encodingTypes[0]}`); 8702} 8703``` 8704 8705### getCurrentAudioCapturerChangeInfo<sup>11+</sup> 8706 8707getCurrentAudioCapturerChangeInfo(): AudioCapturerChangeInfo 8708 8709Obtains the configuration changes of the current audio capturer. This API returns the result synchronously. 8710 8711**System capability**: SystemCapability.Multimedia.Audio.Device 8712 8713**Return value** 8714 8715| Type | Description | 8716| :--------------- | :---------------------------------- | 8717| [AudioCapturerChangeInfo](#audiocapturerchangeinfo9) | Configuration changes of the audio capturer.| 8718 8719**Example** 8720 8721```ts 8722let info: audio.AudioCapturerChangeInfo = audioCapturer.getCurrentAudioCapturerChangeInfo(); 8723console.info(`Info streamId: ${info.streamId}`); 8724console.info(`Info source: ${info.capturerInfo.source}`); 8725console.info(`Info capturerFlags: ${info.capturerInfo.capturerFlags}`); 8726console.info(`Info muted: ${info.muted}`); 8727console.info(`Info type: ${info.deviceDescriptors[0].deviceType}`); 8728console.info(`Info role: ${info.deviceDescriptors[0].deviceRole}`); 8729console.info(`Info name: ${info.deviceDescriptors[0].name}`); 8730console.info(`Info address: ${info.deviceDescriptors[0].address}`); 8731console.info(`Info samplerates: ${info.deviceDescriptors[0].sampleRates[0]}`); 8732console.info(`Info channelcounts: ${info.deviceDescriptors[0].channelCounts[0]}`); 8733console.info(`Info channelmask: ${info.deviceDescriptors[0].channelMasks[0]}`); 8734if (info.deviceDescriptors[0].encodingTypes) { 8735 console.info(`Device encodingTypes: ${info.deviceDescriptors[0].encodingTypes[0]}`); 8736} 8737``` 8738 8739### on('audioInterrupt')<sup>10+</sup> 8740 8741on(type: 'audioInterrupt', callback: Callback\<InterruptEvent>): void 8742 8743Subscribes to the audio interruption event, which is triggered when the audio focus is changed. This API uses an asynchronous callback to return the result. 8744 8745The **AudioCapturer** instance proactively gains the focus when the **start** event occurs and releases the focus when the **pause** or **stop** event occurs. Therefore, you do not need to request to gain or release the focus. 8746 8747After this API is called, an [InterruptEvent](#interruptevent9) is received when the **AudioCapturer** object fails to obtain the focus or an audio interruption event occurs (for example, the audio stream is interrupted by others). It is recommended that the application perform further processing based on the **InterruptEvent** information. For details, see [Handling Audio Focus Changes](../../media/audio/audio-playback-concurrency.md). 8748 8749**System capability**: SystemCapability.Multimedia.Audio.Interrupt 8750 8751**Parameters** 8752 8753| Name | Type | Mandatory| Description | 8754| -------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | 8755| type | string | Yes | Event type. The value is fixed at **'audioInterrupt'**.| 8756| callback | Callback\<[InterruptEvent](#interruptevent9)\> | Yes | Callback used to return the audio interruption event received by the application when recording is interrupted.| 8757 8758**Error codes** 8759 8760For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 8761 8762| ID| Error Message| 8763| ------- | --------------------------------------------| 8764| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 8765| 6800101 | Parameter verification failed. | 8766 8767**Example** 8768 8769```ts 8770import { audio } from '@kit.AudioKit'; 8771 8772let isCapturing: boolean; // An identifier specifying whether capturing is in progress. 8773onAudioInterrupt(); 8774 8775async function onAudioInterrupt(){ 8776 audioCapturer.on('audioInterrupt', (interruptEvent: audio.InterruptEvent) => { 8777 // When an audio interruption event occurs, the AudioCapturer receives the interruptEvent callback and performs processing based on the content in the callback. 8778 // 1. (Optional) The AudioCapturer reads the value of interruptEvent.forceType to see whether the system has forcibly performed the operation. 8779 // Note: In the default focus policy, INTERRUPT_HINT_RESUME maps to the force type INTERRUPT_SHARE, and others map to INTERRUPT_FORCE. Therefore, the value of forceType does not need to be checked. 8780 // 2. (Mandatory) The AudioCapturer then reads the value of interruptEvent.hintType and performs corresponding processing. 8781 if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_FORCE) { 8782 // The audio focus event has been forcibly executed by the system. The application needs to update its status and displayed content. 8783 switch (interruptEvent.hintType) { 8784 case audio.InterruptHint.INTERRUPT_HINT_PAUSE: 8785 // The audio stream has been paused and temporarily loses the focus. It will receive the interruptEvent corresponding to resume when it is able to regain the focus. 8786 console.info('Force paused. Update capturing status and stop reading'); 8787 isCapturing = false; // A simplified processing indicating several operations for switching the application to the paused state. 8788 break; 8789 case audio.InterruptHint.INTERRUPT_HINT_STOP: 8790 // The audio stream has been stopped and permanently loses the focus. The user must manually trigger the operation to resume capturing. 8791 console.info('Force stopped. Update capturing status and stop reading'); 8792 isCapturing = false; // A simplified processing indicating several operations for switching the application to the paused state. 8793 break; 8794 default: 8795 console.info('Invalid interruptEvent'); 8796 break; 8797 } 8798 } else if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_SHARE) { 8799 // The audio focus event needs to be operated by the application, which can choose the processing mode. It is recommended that the application process the event according to the value of InterruptHint. 8800 switch (interruptEvent.hintType) { 8801 case audio.InterruptHint.INTERRUPT_HINT_RESUME: 8802 // It is recommended that the application continue capturing. (The audio stream has been forcibly paused and temporarily lost the focus. It can resume capturing now.) 8803 // The INTERRUPT_HINT_RESUME operation must be proactively executed by the application and cannot be forcibly executed by the system. Therefore, the INTERRUPT_HINT_RESUME event must map to INTERRUPT_SHARE. 8804 console.info('Resume force paused renderer or ignore'); 8805 // To continue capturing, the application must perform the required operations. 8806 break; 8807 default: 8808 console.info('Invalid interruptEvent'); 8809 break; 8810 } 8811 } 8812 }); 8813} 8814``` 8815 8816### off('audioInterrupt')<sup>10+</sup> 8817 8818off(type: 'audioInterrupt'): void 8819 8820Unsubscribes from the audio interruption event. 8821 8822**System capability**: SystemCapability.Multimedia.Audio.Interrupt 8823 8824**Parameters** 8825 8826| Name | Type | Mandatory| Description | 8827| -------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | 8828| type | string | Yes | Event type. The value is fixed at **'audioInterrupt'**.| 8829 8830**Error codes** 8831 8832For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 8833 8834| ID| Error Message| 8835| ------- | --------------------------------------------| 8836| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 8837| 6800101 | Parameter verification failed. | 8838 8839**Example** 8840 8841```ts 8842audioCapturer.off('audioInterrupt'); 8843``` 8844 8845### on('inputDeviceChange')<sup>11+</sup> 8846 8847on(type: 'inputDeviceChange', callback: Callback\<AudioDeviceDescriptors>): void 8848 8849Subscribes to the audio input device change event, which is triggered when an audio input device is changed. This API uses an asynchronous callback to return the result. 8850 8851**System capability**: SystemCapability.Multimedia.Audio.Device 8852 8853**Parameters** 8854 8855| Name | Type | Mandatory| Description | 8856| :------- | :------------------------- | :--- | :------------------------------------------ | 8857| type | string | Yes | Event type. The value is fixed at **'inputDeviceChange**.| 8858| callback | Callback\<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Yes | Callback used to return the information about the new audio input device.| 8859 8860**Error codes** 8861 8862For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 8863 8864| ID| Error Message| 8865| ------- | --------------------------------------------| 8866| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 8867| 6800101 | Parameter verification failed. | 8868 8869**Example** 8870 8871```ts 8872audioCapturer.on('inputDeviceChange', (deviceChangeInfo: audio.AudioDeviceDescriptors) => { 8873 console.info(`inputDevice id: ${deviceChangeInfo[0].id}`); 8874 console.info(`inputDevice deviceRole: ${deviceChangeInfo[0].deviceRole}`); 8875 console.info(`inputDevice deviceType: ${deviceChangeInfo[0].deviceType}`); 8876}); 8877``` 8878### off('inputDeviceChange')<sup>11+</sup> 8879 8880off(type: 'inputDeviceChange', callback?: Callback\<AudioDeviceDescriptors>): void 8881 8882Unsubscribes from the audio input device change event. This API uses an asynchronous callback to return the result. 8883 8884**System capability**: SystemCapability.Multimedia.Audio.Device 8885 8886**Parameters** 8887 8888| Name | Type | Mandatory| Description | 8889| :------- | :------------------------- | :--- |:-----------------------------------------| 8890| type | string | Yes | Event type. The value is fixed at **'inputDeviceChange**. | 8891| callback | Callback\<[AudioDeviceDescriptors](#audiodevicedescriptors)> | No | Callback used to return the information about the audio input device.| 8892 8893**Error codes** 8894 8895For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 8896 8897| ID| Error Message| 8898| ------- | --------------------------------------------| 8899| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 8900| 6800101 | Parameter verification failed. | 8901 8902**Example** 8903 8904```ts 8905// Cancel all subscriptions to the event. 8906audioCapturer.off('inputDeviceChange'); 8907 8908// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 8909let inputDeviceChangeCallback = (deviceChangeInfo: audio.AudioDeviceDescriptors) => { 8910 console.info(`inputDevice id: ${deviceChangeInfo[0].id}`); 8911 console.info(`inputDevice deviceRole: ${deviceChangeInfo[0].deviceRole}`); 8912 console.info(`inputDevice deviceType: ${deviceChangeInfo[0].deviceType}`); 8913}; 8914 8915audioCapturer.on('inputDeviceChange', inputDeviceChangeCallback); 8916 8917audioCapturer.off('inputDeviceChange', inputDeviceChangeCallback); 8918``` 8919 8920### on('audioCapturerChange')<sup>11+</sup> 8921 8922on(type: 'audioCapturerChange', callback: Callback\<AudioCapturerChangeInfo>): void 8923 8924Subscribes to the audio capturer configuration change event, which is triggered when the audio recording stream status or device is changed. This API uses an asynchronous callback to return the result. The subscription is implemented asynchronously and the callback, which is triggered when the audio capturer configuration changes, may fail to reflect the actual condition. 8925 8926**System capability**: SystemCapability.Multimedia.Audio.Capturer 8927 8928**Parameters** 8929 8930| Name | Type | Mandatory| Description | 8931| :------- | :------------------------- | :--- | :------------------------------------------ | 8932| type | string | Yes | Event type. The value is fixed at **'audioCapturerChange'**.| 8933| callback | Callback\<[AudioCapturerChangeInfo](#audiocapturerchangeinfo9)> | Yes | Callback used to return the current configuration and status information of the audio capturer.| 8934 8935**Error codes** 8936 8937For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 8938 8939| ID| Error Message| 8940| ------- | --------------------------------------------| 8941| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 8942| 6800101 | Parameter verification failed. | 8943 8944**Example** 8945 8946```ts 8947audioCapturer.on('audioCapturerChange', (capturerChangeInfo: audio.AudioCapturerChangeInfo) => { 8948 console.info(`audioCapturerChange id: ${capturerChangeInfo[0].id}`); 8949 console.info(`audioCapturerChange deviceRole: ${capturerChangeInfo[0].deviceRole}`); 8950 console.info(`audioCapturerChange deviceType: ${capturerChangeInfo[0].deviceType}`); 8951}); 8952``` 8953 8954### off('audioCapturerChange')<sup>11+</sup> 8955 8956off(type: 'audioCapturerChange', callback?: Callback\<AudioCapturerChangeInfo>): void 8957 8958Unsubscribes from the audio capturer configuration change event. This API uses an asynchronous callback to return the result. 8959 8960**System capability**: SystemCapability.Multimedia.Audio.Capturer 8961 8962**Parameters** 8963 8964| Name | Type | Mandatory| Description | 8965| :------- | :------------------------- | :--- | :------------------------------------------ | 8966| type | string | Yes | Event type. The value is fixed at **'audioCapturerChange'**.| 8967| callback | Callback\<[AudioCapturerChangeInfo](#audiocapturerchangeinfo9)> | No | Callback used for unsubscription.| 8968 8969**Error codes** 8970 8971For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 8972 8973| ID| Error Message| 8974| ------- | --------------------------------------------| 8975| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 8976| 6800101 | Parameter verification failed. | 8977 8978**Example** 8979 8980```ts 8981// Cancel all subscriptions to the event. 8982audioCapturer.off('audioCapturerChange'); 8983 8984// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 8985let audioCapturerChangeCallback = (capturerChangeInfo: audio.AudioCapturerChangeInfo) => { 8986 console.info(`audioCapturerChange id: ${capturerChangeInfo[0].id}`); 8987 console.info(`audioCapturerChange deviceRole: ${capturerChangeInfo[0].deviceRole}`); 8988 console.info(`audioCapturerChange deviceType: ${capturerChangeInfo[0].deviceType}`); 8989}; 8990 8991audioCapturer.on('audioCapturerChange', audioCapturerChangeCallback); 8992 8993audioCapturer.off('audioCapturerChange', audioCapturerChangeCallback); 8994``` 8995 8996### on('markReach')<sup>8+</sup> 8997 8998on(type: 'markReach', frame: number, callback: Callback<number>): void 8999 9000Subscribes to the mark reached event, which is triggered (only once) when the number of frames captured reaches the value of the **frame** parameter. This API uses an asynchronous callback to return the result. 9001 9002For example, if **frame** is set to **100**, the callback is invoked when the number of captured frames reaches the 100th frame. 9003 9004**System capability**: SystemCapability.Multimedia.Audio.Capturer 9005 9006**Parameters** 9007 9008| Name | Type | Mandatory| Description | 9009| :------- | :---------------------- | :--- | :----------------------------------------- | 9010| type | string | Yes | Event type. The value is fixed at **'markReach'**. | 9011| frame | number | Yes | Number of frames to trigger the event. The value must be greater than **0**. | 9012| callback | Callback\<number> | Yes | Callback used to return the value of the **frame** parameter.| 9013 9014**Example** 9015 9016```ts 9017audioCapturer.on('markReach', 1000, (position: number) => { 9018 if (position == 1000) { 9019 console.info('ON Triggered successfully'); 9020 } 9021}); 9022``` 9023 9024### off('markReach')<sup>8+</sup> 9025 9026off(type: 'markReach'): void 9027 9028Unsubscribes from the mark reached event. 9029 9030**System capability**: SystemCapability.Multimedia.Audio.Capturer 9031 9032**Parameters** 9033 9034| Name| Type | Mandatory| Description | 9035| :----- | :----- | :--- | :-------------------------------------------- | 9036| type | string | Yes | Event type. The value is fixed at **'markReach'**.| 9037 9038**Example** 9039 9040```ts 9041audioCapturer.off('markReach'); 9042``` 9043 9044### on('periodReach')<sup>8+</sup> 9045 9046on(type: 'periodReach', frame: number, callback: Callback<number>): void 9047 9048Subscribes to the period reached event, which is triggered each time the number of frames captured reaches the value of the **frame** parameter. In other words, the information is reported periodically. This API uses an asynchronous callback to return the result. 9049 9050For example, if **frame** is set to **10**, the callback is invoked each time 10 frames are captured, for example, when the number of frames rendered reaches the 10th frame, 20th frame, and 30th frame. 9051 9052**System capability**: SystemCapability.Multimedia.Audio.Capturer 9053 9054**Parameters** 9055 9056| Name | Type | Mandatory| Description | 9057| :------- | :----------------------- | :--- | :------------------------------------------ | 9058| type | string | Yes | Event type. The value is fixed at **'periodReach'**.| 9059| frame | number | Yes | Number of frames to trigger the event. The value must be greater than **0**. | 9060| callback | Callback\<number> | Yes |Callback used to return the value of the **frame** parameter. | 9061 9062**Example** 9063 9064```ts 9065audioCapturer.on('periodReach', 1000, (position: number) => { 9066 if (position == 1000) { 9067 console.info('ON Triggered successfully'); 9068 } 9069}); 9070``` 9071 9072### off('periodReach')<sup>8+</sup> 9073 9074off(type: 'periodReach'): void 9075 9076Unsubscribes from the period reached event. 9077 9078**System capability**: SystemCapability.Multimedia.Audio.Capturer 9079 9080**Parameters** 9081 9082| Name| Type | Mandatory| Description | 9083| :----- | :----- | :--- | :---------------------------------------------- | 9084| type | string | Yes | Event type. The value is fixed at **'periodReach'**.| 9085 9086**Example** 9087 9088```ts 9089audioCapturer.off('periodReach'); 9090``` 9091 9092### on('stateChange')<sup>8+</sup> 9093 9094on(type: 'stateChange', callback: Callback<AudioState\>): void 9095 9096Subscribes to the audio capturer state change event, which is triggered when the state of the audio capturer is changed. This API uses an asynchronous callback to return the result. 9097 9098**System capability**: SystemCapability.Multimedia.Audio.Capturer 9099 9100**Parameters** 9101 9102| Name | Type | Mandatory| Description | 9103| :------- | :------------------------- | :--- | :------------------------------------------ | 9104| type | string | Yes | Event type. The value is fixed at **'stateChange'**.| 9105| callback | Callback\<[AudioState](#audiostate8)> | Yes | Callback used to return the audio status.| 9106 9107**Example** 9108 9109```ts 9110audioCapturer.on('stateChange', (state: audio.AudioState) => { 9111 if (state == 1) { 9112 console.info('audio capturer state is: STATE_PREPARED'); 9113 } 9114 if (state == 2) { 9115 console.info('audio capturer state is: STATE_RUNNING'); 9116 } 9117}); 9118``` 9119 9120### on('readData')<sup>11+</sup> 9121 9122on(type: 'readData', callback: Callback\<ArrayBuffer>): void 9123 9124Subscribes to the audio data read event, which is triggered when audio stream data needs to be read. This API uses an asynchronous callback to return the result. 9125 9126The callback function is used only to read audio data. Do not call AudioCapturer APIs in it. 9127 9128**System capability**: SystemCapability.Multimedia.Audio.Capturer 9129 9130**Parameters** 9131 9132| Name | Type | Mandatory| Description | 9133| :------- |:-----------------------| :--- |:--------------------------| 9134| type | string | Yes | Event type. The value is fixed at **'readData'**.| 9135| callback | Callback\<ArrayBuffer> | Yes | Callback used to return the buffer from which the data is read. | 9136 9137**Error codes** 9138 9139For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 9140 9141| ID| Error Message| 9142| ------- | --------------------------------------------| 9143| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 9144| 6800101 | Parameter verification failed. | 9145 9146**Example** 9147 9148```ts 9149import { BusinessError } from '@kit.BasicServicesKit'; 9150import { fileIo as fs } from '@kit.CoreFileKit'; 9151 9152class Options { 9153 offset?: number; 9154 length?: number; 9155} 9156 9157let bufferSize: number = 0; 9158let path = getContext().cacheDir; 9159// Ensure that the resource exists in the path. 9160let filePath = path + '/StarWars10s-2C-48000-4SW.pcm'; 9161let file: fs.File = fs.openSync(filePath, fs.OpenMode.READ_WRITE); 9162let readDataCallback = (buffer: ArrayBuffer) => { 9163 let options: Options = { 9164 offset: bufferSize, 9165 length: buffer.byteLength 9166 }; 9167 fs.writeSync(file.fd, buffer, options); 9168 bufferSize += buffer.byteLength; 9169} 9170 9171audioCapturer.on('readData', readDataCallback); 9172 9173audioCapturer.start((err: BusinessError) => { 9174 if (err) { 9175 console.error('Capturer start failed.'); 9176 } else { 9177 console.info('Capturer start success.'); 9178 } 9179}); 9180``` 9181 9182### off('readData')<sup>11+</sup> 9183 9184off(type: 'readData', callback?: Callback\<ArrayBuffer>): void 9185 9186Unsubscribes from the audio data read event. This API uses an asynchronous callback to return the result. 9187 9188**System capability**: SystemCapability.Multimedia.Audio.Capturer 9189 9190**Parameters** 9191 9192| Name | Type | Mandatory| Description | 9193| :------- |:-----------------------| :--- |:-------------------------------------------| 9194| type | string | Yes | Event type. The value is fixed at **'readData'**. | 9195| callback | Callback\<ArrayBuffer> | No | Callback used to return the buffer from which the data is read. | 9196 9197**Error codes** 9198 9199For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 9200 9201| ID| Error Message| 9202| ------- | --------------------------------------------| 9203| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 9204| 6800101 | Parameter verification failed. | 9205 9206**Example** 9207 9208```ts 9209// Cancel all subscriptions to the event. 9210audioCapturer.off('readData'); 9211 9212// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 9213let readDataCallback = (data: ArrayBuffer) => { 9214 console.info(`read data: ${data}`); 9215}; 9216 9217audioCapturer.on('readData', readDataCallback); 9218 9219audioCapturer.off('readData', readDataCallback); 9220``` 9221 9222### getOverflowCount<sup>12+</sup> 9223 9224getOverflowCount(): Promise<number> 9225 9226Obtains the number of overflow audio frames in the audio stream that is being captured. This API uses a promise to return the result. 9227 9228**System capability**: SystemCapability.Multimedia.Audio.Capturer 9229 9230**Return value** 9231 9232| Type | Description | 9233| ------------------- | ----------------------------- | 9234| Promise<number>| Promise used to return the number of overflow audio frames.| 9235 9236**Example** 9237 9238```ts 9239import { BusinessError } from '@kit.BasicServicesKit'; 9240 9241audioCapturer.getOverflowCount().then((value: number) => { 9242 console.info(`Get overflow count Success! ${value}`); 9243}).catch((err: BusinessError) => { 9244 console.error(`Get overflow count Fail: ${err}`); 9245}); 9246``` 9247 9248### getOverflowCountSync<sup>12+</sup> 9249 9250getOverflowCountSync(): number 9251 9252Obtains the number of overflow audio frames in the audio stream that is being captured. This API returns the result synchronously. 9253 9254**System capability**: SystemCapability.Multimedia.Audio.Capturer 9255 9256**Return value** 9257 9258| Type | Description | 9259| ------------------- | ----------------------------- | 9260| number| Number of overflow audio frames.| 9261 9262**Example** 9263 9264```ts 9265import { BusinessError } from '@kit.BasicServicesKit'; 9266 9267try { 9268 let value: number = audioCapturer.getOverflowCountSync(); 9269 console.info(`Get overflow count Success! ${value}`); 9270} catch (err) { 9271 let error = err as BusinessError; 9272 console.error(`Get overflow count Fail: ${error}`); 9273} 9274``` 9275 9276## ActiveDeviceType<sup>(deprecated)</sup> 9277 9278Enumerates the active device types. 9279 9280> **NOTE** 9281> 9282> This API is deprecated since API version 9. You are advised to use [CommunicationDeviceType](#communicationdevicetype9) instead. 9283 9284**System capability**: SystemCapability.Multimedia.Audio.Device 9285 9286| Name | Value | Description | 9287| ------------- | ------ | ---------------------------------------------------- | 9288| SPEAKER | 2 | Speaker. | 9289| BLUETOOTH_SCO | 7 | Bluetooth device using Synchronous Connection Oriented (SCO) links.| 9290 9291## InterruptActionType<sup>(deprecated)</sup> 9292 9293Enumerates the returned event types for audio interruption events. 9294 9295> **NOTE** 9296> 9297> This API is supported since API version 7 and deprecated since API version 9. No substitute enum is provided. It is used together with the audio interruption events. 9298 9299**System capability**: SystemCapability.Multimedia.Audio.Renderer 9300 9301| Name | Value | Description | 9302| -------------- | ------ | ------------------ | 9303| TYPE_ACTIVATED | 0 | Focus gain event.| 9304| TYPE_INTERRUPT | 1 | Audio interruption event.| 9305 9306## AudioInterrupt<sup>(deprecated)</sup> 9307 9308Describes input parameters of audio interruption events. 9309 9310> **NOTE** 9311> 9312> This API is supported since API version 7 and deprecated since API version 9. No substitute enum is provided. It is used together with the audio interruption events. 9313 9314**System capability**: SystemCapability.Multimedia.Audio.Renderer 9315 9316| Name | Type | Mandatory| Description | 9317| --------------- | --------------------------- | ----| ------------------------------------------------------------ | 9318| streamUsage | [StreamUsage](#streamusage) | Yes | Audio stream usage. | 9319| contentType | [ContentType](#contenttypedeprecated) | Yes | Audio content type. | 9320| 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.| 9321 9322## InterruptAction<sup>(deprecated)</sup> 9323 9324Describes the callback invoked for audio interruption or focus gain events. 9325 9326> **NOTE** 9327> 9328> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [InterruptEvent](#interruptevent9). 9329 9330**System capability**: SystemCapability.Multimedia.Audio.Renderer 9331 9332| Name | Type | Mandatory| Description | 9333| ---------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | 9334| actionType | [InterruptActionType](#interruptactiontypedeprecated) | Yes | Returned event type. The value **TYPE_ACTIVATED** means the focus gain event, and **TYPE_INTERRUPT** means the audio interruption event.| 9335| type | [InterruptType](#interrupttype) | No | Type of the audio interruption event. | 9336| hint | [InterruptHint](#interrupthint) | No | Hint provided along with the audio interruption event. | 9337| 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.| 9338