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, // Sampling rate. 80 channels: audio.AudioChannel.CHANNEL_2, // Channel. 81 sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, // Sampling format. 82 encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW // Encoding format. 83}; 84 85let audioRendererInfo: audio.AudioRendererInfo = { 86 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, // Audio stream usage type: music. Set this parameter based on the service scenario. 87 rendererFlags: 0 // AudioRenderer flag. 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, // Sampling rate. 133 channels: audio.AudioChannel.CHANNEL_2, // Channel. 134 sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, // Sampling format. 135 encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW // Encoding format. 136}; 137 138let audioRendererInfo: audio.AudioRendererInfo = { 139 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, // Audio stream usage type: music. Set this parameter based on the service scenario. 140 rendererFlags: 0 // AudioRenderer flag. 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, // Sampling rate. 184 channels: audio.AudioChannel.CHANNEL_2, // Channel. 185 sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, // Sampling format. 186 encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW // Encoding format. 187}; 188 189let audioCapturerInfo: audio.AudioCapturerInfo = { 190 source: audio.SourceType.SOURCE_TYPE_MIC, // Audio source type: microphone. Set this parameter based on the service scenario. 191 capturerFlags: 0 // AudioCapturer flag. 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, // Sampling rate. 241 channels: audio.AudioChannel.CHANNEL_2, // Channel. 242 sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, // Sampling format. 243 encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW // Encoding format. 244}; 245 246let audioCapturerInfo: audio.AudioCapturerInfo = { 247 source: audio.SourceType.SOURCE_TYPE_MIC, // Audio source type: microphone. Set this parameter based on the service scenario. 248 capturerFlags: 0 // AudioCapturer flag. 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**System capability**: SystemCapability.Multimedia.Audio.Device 339 340| Name | Value | Description | 341| ---------------------| ------ | --------------------------------------------------------- | 342| INVALID | 0 | Invalid device.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 343| EARPIECE | 1 | Earpiece.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 344| SPEAKER | 2 | Speaker.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 345| WIRED_HEADSET | 3 | Wired headset with a microphone.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 346| WIRED_HEADPHONES | 4 | Wired headset without microphone.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 347| BLUETOOTH_SCO | 7 | Bluetooth device using Synchronous Connection Oriented (SCO) links.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 348| BLUETOOTH_A2DP | 8 | Bluetooth device using Advanced Audio Distribution Profile (A2DP) links.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 349| MIC | 15 | Microphone.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 350| USB_HEADSET | 22 | USB Type-C headset.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 351| DISPLAY_PORT<sup>12+</sup> | 23 | Display port (DP), which is used to connect to external devices.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 352| REMOTE_CAST<sup>12+</sup> | 24 | Remote cast device.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 353| USB_DEVICE<sup>18+</sup> | 25 | USB device (excluding USB headsets). | 354| REMOTE_DAUDIO<sup>18+</sup> | 29 | Distributed device.<br>**Atomic service API**: This API can be used in atomic services since API version 18.| 355| DEFAULT<sup>9+</sup> | 1000 | Default device type.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 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| SOURCE_TYPE_UNPROCESSED<sup>14+</sup> | 14 | Audio source for raw microphone recording, where the system does not perform any algorithm processing.<br>**System capability**: SystemCapability.Multimedia.Audio.Core| 866 867## AudioPlaybackCaptureConfig<sup>(deprecated)</sup> 868 869Defines the configuration of internal audio recording. 870 871> **NOTE** 872> 873> 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. 874 875**System capability**: SystemCapability.Multimedia.Audio.PlaybackCapture 876 877| Name | Type | Mandatory| Description | 878| ------------- | --------------------------------------------- | ---- | -------------------------------- | 879| filterOptions | [CaptureFilterOptions](#capturefilteroptionsdeprecated) | Yes | Options for filtering the played audio streams to be recorded.| 880 881## CaptureFilterOptions<sup>(deprecated)</sup> 882 883Defines the options for filtering the played audio streams to be recorded. 884 885> **NOTE** 886> 887> 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. 888 889**System capability**: SystemCapability.Multimedia.Audio.PlaybackCapture 890 891| Name | Type | Mandatory| Description | 892| ------ | ---------------------------------- | ---- | ------------------------------------------------------------ | 893| 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.<br>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.<br>Since API version 11, **CaptureFilterOptions** does not support **StreamUsage.STREAM_USAGE_VOICE_COMMUNICATION**. Therefore, no permission is required for calling this API.| 894 895## AudioScene<sup>8+</sup> 896 897Enumerates the audio scenes. 898 899**System capability**: SystemCapability.Multimedia.Audio.Communication 900 901| Name | Value | Description | 902| :--------------------- | :----- | :-------------------------------------------- | 903| AUDIO_SCENE_DEFAULT | 0 | Default audio scene. | 904| AUDIO_SCENE_RINGING<sup>12+</sup> | 1 | Normal mode.| 905| AUDIO_SCENE_PHONE_CALL<sup>12+</sup> | 2 | Phone call scene.| 906| AUDIO_SCENE_VOICE_CHAT | 3 | Voice chat scene. | 907 908## AudioConcurrencyMode<sup>12+</sup> 909 910Enumerates the audio concurrency modes. 911 912**System capability**: SystemCapability.Multimedia.Audio.Core 913 914| Name | Value| Description | 915| :--------------------- |:--|:--------| 916| CONCURRENCY_DEFAULT | 0 | Uses the system strategy by default. | 917| CONCURRENCY_MIX_WITH_OTHERS | 1 | Mixes with other audio streams. | 918| CONCURRENCY_DUCK_OTHERS | 2 | Ducks other audio streams.| 919| CONCURRENCY_PAUSE_OTHERS | 3 | Pauses other audio streams.| 920 921## AudioSessionDeactivatedReason<sup>12+</sup> 922 923Enumerates the reasons for deactivating an audio session. 924 925**System capability**: SystemCapability.Multimedia.Audio.Core 926 927| Name | Value| Description | 928| :--------------------- |:--|:-------| 929| DEACTIVATED_LOWER_PRIORITY | 0 | The application focus is preempted.| 930| DEACTIVATED_TIMEOUT | 1 | The audio session times out. | 931 932## AudioSessionStrategy<sup>12+</sup> 933 934Describes an audio session strategy. 935 936**System capability**: SystemCapability.Multimedia.Audio.Core 937 938| Name | Type | Mandatory| Description | 939| :------------ |:------------------------------------------------| :--- | :--------------- | 940| concurrencyMode | [AudioConcurrencyMode](#audioconcurrencymode12) | Yes | Audio concurrency mode. | 941 942## AudioSessionDeactivatedEvent<sup>12+</sup> 943 944Describes the event indicating that an audio session is deactivated. 945 946**System capability**: SystemCapability.Multimedia.Audio.Core 947 948| Name | Type | Mandatory| Description | 949| :------------ |:------------------------------------------------------------------| :--- | :--------------- | 950| reason | [AudioSessionDeactivatedReason](#audiosessiondeactivatedreason12) | Yes | Reason for deactivating an audio session. | 951 952## AudioManager 953 954Implements audio volume and audio device management. Before calling any API in **AudioManager**, you must use [getAudioManager](#audiogetaudiomanager) to create an **AudioManager** instance. 955 956### setAudioParameter<sup>(deprecated)</sup> 957 958setAudioParameter(key: string, value: string, callback: AsyncCallback<void>): void 959 960Sets an audio parameter. This API uses an asynchronous callback to return the result. 961 962This 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. 963 964> **NOTE** 965> 966> This API is supported since API version 7 and deprecated since API version 11. The substitute API is available only for system applications. 967 968**Required permissions**: ohos.permission.MODIFY_AUDIO_SETTINGS 969 970**System capability**: SystemCapability.Multimedia.Audio.Core 971 972**Parameters** 973 974| Name | Type | Mandatory| Description | 975| -------- | ------------------------- | ---- | ------------------------ | 976| key | string | Yes | Key of the audio parameter to set. | 977| value | string | Yes | Value of the audio parameter to set. | 978| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 979 980**Example** 981 982```ts 983import { BusinessError } from '@kit.BasicServicesKit'; 984 985audioManager.setAudioParameter('key_example', 'value_example', (err: BusinessError) => { 986 if (err) { 987 console.error(`Failed to set the audio parameter. ${err}`); 988 return; 989 } 990 console.info('Callback invoked to indicate a successful setting of the audio parameter.'); 991}); 992``` 993 994### setAudioParameter<sup>(deprecated)</sup> 995 996setAudioParameter(key: string, value: string): Promise<void> 997 998Sets an audio parameter. This API uses a promise to return the result. 999 1000This 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. 1001 1002> **NOTE** 1003> 1004> This API is supported since API version 7 and deprecated since API version 11. The substitute API is available only for system applications. 1005 1006**Required permissions**: ohos.permission.MODIFY_AUDIO_SETTINGS 1007 1008**System capability**: SystemCapability.Multimedia.Audio.Core 1009 1010**Parameters** 1011 1012| Name| Type | Mandatory| Description | 1013| ------ | ------ | ---- | ---------------------- | 1014| key | string | Yes | Key of the audio parameter to set.| 1015| value | string | Yes | Value of the audio parameter to set.| 1016 1017**Return value** 1018 1019| Type | Description | 1020| ------------------- | ------------------------------- | 1021| Promise<void> | Promise that returns no value.| 1022 1023**Example** 1024 1025```ts 1026audioManager.setAudioParameter('key_example', 'value_example').then(() => { 1027 console.info('Promise returned to indicate a successful setting of the audio parameter.'); 1028}); 1029``` 1030 1031### getAudioParameter<sup>(deprecated)</sup> 1032 1033getAudioParameter(key: string, callback: AsyncCallback<string>): void 1034 1035Obtains the value of an audio parameter. This API uses an asynchronous callback to return the result. 1036 1037This 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. 1038 1039> **NOTE** 1040> 1041> This API is supported since API version 7 and deprecated since API version 11. The substitute API is available only for system applications. 1042 1043**System capability**: SystemCapability.Multimedia.Audio.Core 1044 1045**Parameters** 1046 1047| Name | Type | Mandatory| Description | 1048| -------- | --------------------------- | ---- | ---------------------------- | 1049| key | string | Yes | Key of the audio parameter whose value is to be obtained. | 1050| 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.| 1051 1052**Example** 1053 1054```ts 1055import { BusinessError } from '@kit.BasicServicesKit'; 1056 1057audioManager.getAudioParameter('key_example', (err: BusinessError, value: string) => { 1058 if (err) { 1059 console.error(`Failed to obtain the value of the audio parameter. ${err}`); 1060 return; 1061 } 1062 console.info(`Callback invoked to indicate that the value of the audio parameter is obtained ${value}.`); 1063}); 1064``` 1065 1066### getAudioParameter<sup>(deprecated)</sup> 1067 1068getAudioParameter(key: string): Promise<string> 1069 1070Obtains the value of an audio parameter. This API uses a promise to return the result. 1071 1072This 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. 1073 1074> **NOTE** 1075> 1076> This API is supported since API version 7 and deprecated since API version 11. The substitute API is available only for system applications. 1077 1078**System capability**: SystemCapability.Multimedia.Audio.Core 1079 1080**Parameters** 1081 1082| Name| Type | Mandatory| Description | 1083| ------ | ------ | ---- | ---------------------- | 1084| key | string | Yes | Key of the audio parameter whose value is to be obtained.| 1085 1086**Return value** 1087 1088| Type | Description | 1089| --------------------- | ----------------------------------- | 1090| Promise<string> | Promise used to return the value of the audio parameter.| 1091 1092**Example** 1093 1094```ts 1095audioManager.getAudioParameter('key_example').then((value: string) => { 1096 console.info(`Promise returned to indicate that the value of the audio parameter is obtained ${value}.`); 1097}); 1098``` 1099 1100### getAudioScene<sup>8+</sup> 1101 1102getAudioScene\(callback: AsyncCallback<AudioScene\>\): void 1103 1104Obtains the audio scene. This API uses an asynchronous callback to return the result. 1105 1106**System capability**: SystemCapability.Multimedia.Audio.Communication 1107 1108**Parameters** 1109 1110| Name | Type | Mandatory| Description | 1111| :------- | :-------------------------------------------------- | :--- | :--------------------------- | 1112| callback | AsyncCallback<[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.| 1113 1114**Example** 1115 1116```ts 1117import { BusinessError } from '@kit.BasicServicesKit'; 1118 1119audioManager.getAudioScene((err: BusinessError, value: audio.AudioScene) => { 1120 if (err) { 1121 console.error(`Failed to obtain the audio scene mode. ${err}`); 1122 return; 1123 } 1124 console.info(`Callback invoked to indicate that the audio scene mode is obtained ${value}.`); 1125}); 1126``` 1127 1128### getAudioScene<sup>8+</sup> 1129 1130getAudioScene\(\): Promise<AudioScene\> 1131 1132Obtains the audio scene. This API uses a promise to return the result. 1133 1134**System capability**: SystemCapability.Multimedia.Audio.Communication 1135 1136**Return value** 1137 1138| Type | Description | 1139| :-------------------------------------------- | :--------------------------- | 1140| Promise<[AudioScene](#audioscene8)> | Promise used to return the audio scene.| 1141 1142**Example** 1143 1144```ts 1145import { BusinessError } from '@kit.BasicServicesKit'; 1146 1147audioManager.getAudioScene().then((value: audio.AudioScene) => { 1148 console.info(`Promise returned to indicate that the audio scene mode is obtained ${value}.`); 1149}).catch ((err: BusinessError) => { 1150 console.error(`Failed to obtain the audio scene mode ${err}`); 1151}); 1152``` 1153 1154### getAudioSceneSync<sup>10+</sup> 1155 1156getAudioSceneSync\(\): AudioScene 1157 1158Obtains the audio scene. This API returns the result synchronously. 1159 1160**System capability**: SystemCapability.Multimedia.Audio.Communication 1161 1162**Return value** 1163 1164| Type | Description | 1165| :-------------------------------------------- | :--------------------------- | 1166| [AudioScene](#audioscene8) | Audio scene.| 1167 1168**Example** 1169 1170```ts 1171import { BusinessError } from '@kit.BasicServicesKit'; 1172 1173try { 1174 let value: audio.AudioScene = audioManager.getAudioSceneSync(); 1175 console.info(`indicate that the audio scene mode is obtained ${value}.`); 1176} catch (err) { 1177 let error = err as BusinessError; 1178 console.error(`Failed to obtain the audio scene mode ${error}`); 1179} 1180``` 1181 1182### getVolumeManager<sup>9+</sup> 1183 1184getVolumeManager(): AudioVolumeManager 1185 1186Obtains an **AudioVolumeManager** instance. 1187 1188**System capability**: SystemCapability.Multimedia.Audio.Volume 1189 1190**Return value** 1191 1192| Type | Description | 1193|-----------------------------------------| ----------------------------- | 1194| [AudioVolumeManager](#audiovolumemanager9) | **AudioVolumeManager** instance.| 1195 1196**Example** 1197 1198```ts 1199import { audio } from '@kit.AudioKit'; 1200 1201let audioVolumeManager: audio.AudioVolumeManager = audioManager.getVolumeManager(); 1202``` 1203 1204### getStreamManager<sup>9+</sup> 1205 1206getStreamManager(): AudioStreamManager 1207 1208Obtains an **AudioStreamManager** instance. 1209 1210**System capability**: SystemCapability.Multimedia.Audio.Core 1211 1212**Return value** 1213 1214| Type | Description | 1215|--------------------------------------------| ----------------------------- | 1216| [AudioStreamManager](#audiostreammanager9) | **AudioStreamManager** instance.| 1217 1218**Example** 1219 1220```ts 1221import { audio } from '@kit.AudioKit'; 1222 1223let audioStreamManager: audio.AudioStreamManager = audioManager.getStreamManager(); 1224``` 1225 1226### getRoutingManager<sup>9+</sup> 1227 1228getRoutingManager(): AudioRoutingManager 1229 1230Obtains an **AudioRoutingManager** instance. 1231 1232**System capability**: SystemCapability.Multimedia.Audio.Device 1233 1234**Return value** 1235 1236| Type | Description | 1237|------------------------------------------| ----------------------------- | 1238| [AudioRoutingManager](#audioroutingmanager9) | **AudioRoutingManager** instance.| 1239 1240**Example** 1241 1242```ts 1243import { audio } from '@kit.AudioKit'; 1244 1245let audioRoutingManager: audio.AudioRoutingManager = audioManager.getRoutingManager(); 1246``` 1247 1248### getSessionManager<sup>12+</sup> 1249 1250getSessionManager(): AudioSessionManager 1251 1252Obtains an **AudioSessionManager** instance. 1253 1254**System capability**: SystemCapability.Multimedia.Audio.Core 1255 1256**Return value** 1257 1258| Type | Description | 1259|----------------------------------------------| ----------------------------- | 1260| [AudioSessionManager](#audiosessionmanager12) | **AudioSessionManager** instance.| 1261 1262**Example** 1263 1264```ts 1265import { audio } from '@kit.AudioKit'; 1266 1267let audioSessionManager: audio.AudioSessionManager = audioManager.getSessionManager(); 1268``` 1269 1270### setVolume<sup>(deprecated)</sup> 1271 1272setVolume(volumeType: AudioVolumeType, volume: number, callback: AsyncCallback<void>): void 1273 1274Sets the volume for a stream. This API uses an asynchronous callback to return the result. 1275 1276> **NOTE** 1277> 1278> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 1279> 1280> Applications cannot directly adjust the system volume. It is recommended that they invoke the system volume panel for users to adjust the volume. When the user adjusts the volume, a volume prompt UI is displayed to explicitly notify the user that the system volume changes. For details about the samples and introduction, see [AVVolumePanel Reference](ohos-multimedia-avvolumepanel.md). 1281 1282**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 1283 1284This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**. 1285 1286**System capability**: SystemCapability.Multimedia.Audio.Volume 1287 1288**Parameters** 1289 1290| Name | Type | Mandatory| Description | 1291| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 1292| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1293| volume | number | Yes | Volume to set. The value range can be obtained by calling [getMinVolume](#getminvolumedeprecated) and [getMaxVolume](#getmaxvolumedeprecated).| 1294| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1295 1296**Example** 1297 1298```ts 1299import { BusinessError } from '@kit.BasicServicesKit'; 1300 1301audioManager.setVolume(audio.AudioVolumeType.MEDIA, 10, (err: BusinessError) => { 1302 if (err) { 1303 console.error(`Failed to set the volume. ${err}`); 1304 return; 1305 } 1306 console.info('Callback invoked to indicate a successful volume setting.'); 1307}); 1308``` 1309 1310### setVolume<sup>(deprecated)</sup> 1311 1312setVolume(volumeType: AudioVolumeType, volume: number): Promise<void> 1313 1314Sets the volume for a stream. This API uses a promise to return the result. 1315 1316> **NOTE** 1317> 1318> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 1319> 1320> Applications cannot directly adjust the system volume. It is recommended that they invoke the system volume panel for users to adjust the volume. When the user adjusts the volume, a volume prompt UI is displayed to explicitly notify the user that the system volume changes. For details about the samples and introduction, see [AVVolumePanel Reference](ohos-multimedia-avvolumepanel.md). 1321 1322**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 1323 1324This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**. 1325 1326**System capability**: SystemCapability.Multimedia.Audio.Volume 1327 1328**Parameters** 1329 1330| Name | Type | Mandatory| Description | 1331| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 1332| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1333| volume | number | Yes | Volume to set. The value range can be obtained by calling [getMinVolume](#getminvolumedeprecated) and [getMaxVolume](#getmaxvolumedeprecated).| 1334 1335**Return value** 1336 1337| Type | Description | 1338| ------------------- | ----------------------------- | 1339| Promise<void> | Promise that returns no value.| 1340 1341**Example** 1342 1343```ts 1344audioManager.setVolume(audio.AudioVolumeType.MEDIA, 10).then(() => { 1345 console.info('Promise returned to indicate a successful volume setting.'); 1346}); 1347``` 1348 1349### getVolume<sup>(deprecated)</sup> 1350 1351getVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 1352 1353Obtains the volume of a stream. This API uses an asynchronous callback to return the result. 1354 1355> **NOTE** 1356> 1357> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getVolume](#getvolume9) in **AudioVolumeGroupManager**. 1358 1359**System capability**: SystemCapability.Multimedia.Audio.Volume 1360 1361**Parameters** 1362 1363| Name | Type | Mandatory| Description | 1364| ---------- | ----------------------------------- | ---- | ------------------ | 1365| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1366| 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).| 1367 1368**Example** 1369 1370```ts 1371import { BusinessError } from '@kit.BasicServicesKit'; 1372 1373audioManager.getVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { 1374 if (err) { 1375 console.error(`Failed to obtain the volume. ${err}`); 1376 return; 1377 } 1378 console.info('Callback invoked to indicate that the volume is obtained.'); 1379}); 1380``` 1381 1382### getVolume<sup>(deprecated)</sup> 1383 1384getVolume(volumeType: AudioVolumeType): Promise<number> 1385 1386Obtains the volume of a stream. This API uses a promise to return the result. 1387 1388> **NOTE** 1389> 1390> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getVolume](#getvolume9) in **AudioVolumeGroupManager**. 1391 1392**System capability**: SystemCapability.Multimedia.Audio.Volume 1393 1394**Parameters** 1395 1396| Name | Type | Mandatory| Description | 1397| ---------- | ----------------------------------- | ---- | ------------ | 1398| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 1399 1400**Return value** 1401 1402| Type | Description | 1403| --------------------- | ------------------------- | 1404| 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).| 1405 1406**Example** 1407 1408```ts 1409audioManager.getVolume(audio.AudioVolumeType.MEDIA).then((value: number) => { 1410 console.info(`Promise returned to indicate that the volume is obtained ${value} .`); 1411}); 1412``` 1413 1414### getMinVolume<sup>(deprecated)</sup> 1415 1416getMinVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 1417 1418Obtains the minimum volume allowed for a stream. This API uses an asynchronous callback to return the result. 1419 1420> **NOTE** 1421> 1422> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getMinVolume](#getminvolume9) in **AudioVolumeGroupManager**. 1423 1424**System capability**: SystemCapability.Multimedia.Audio.Volume 1425 1426**Parameters** 1427 1428| Name | Type | Mandatory| Description | 1429| ---------- | ----------------------------------- | ---- | ------------------ | 1430| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1431| 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.| 1432 1433**Example** 1434 1435```ts 1436import { BusinessError } from '@kit.BasicServicesKit'; 1437 1438audioManager.getMinVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { 1439 if (err) { 1440 console.error(`Failed to obtain the minimum volume. ${err}`); 1441 return; 1442 } 1443 console.info(`Callback invoked to indicate that the minimum volume is obtained. ${value}`); 1444}); 1445``` 1446 1447### getMinVolume<sup>(deprecated)</sup> 1448 1449getMinVolume(volumeType: AudioVolumeType): Promise<number> 1450 1451Obtains the minimum volume allowed for a stream. This API uses a promise to return the result. 1452 1453> **NOTE** 1454> 1455> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getMinVolume](#getminvolume9) in **AudioVolumeGroupManager**. 1456 1457**System capability**: SystemCapability.Multimedia.Audio.Volume 1458 1459**Parameters** 1460 1461| Name | Type | Mandatory| Description | 1462| ---------- | ----------------------------------- | ---- | ------------ | 1463| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 1464 1465**Return value** 1466 1467| Type | Description | 1468| --------------------- | ------------------------- | 1469| Promise<number> | Promise used to return the minimum volume.| 1470 1471**Example** 1472 1473```ts 1474audioManager.getMinVolume(audio.AudioVolumeType.MEDIA).then((value: number) => { 1475 console.info(`Promised returned to indicate that the minimum volume is obtained. ${value}`); 1476}); 1477``` 1478 1479### getMaxVolume<sup>(deprecated)</sup> 1480 1481getMaxVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 1482 1483Obtains the maximum volume allowed for a stream. This API uses an asynchronous callback to return the result. 1484 1485> **NOTE** 1486> 1487> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getMaxVolume](#getmaxvolume9) in **AudioVolumeGroupManager**. 1488 1489**System capability**: SystemCapability.Multimedia.Audio.Volume 1490 1491**Parameters** 1492 1493| Name | Type | Mandatory| Description | 1494| ---------- | ----------------------------------- | ---- | ---------------------- | 1495| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1496| 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.| 1497 1498**Example** 1499 1500```ts 1501import { BusinessError } from '@kit.BasicServicesKit'; 1502 1503audioManager.getMaxVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { 1504 if (err) { 1505 console.error(`Failed to obtain the maximum volume. ${err}`); 1506 return; 1507 } 1508 console.info(`Callback invoked to indicate that the maximum volume is obtained. ${value}`); 1509}); 1510``` 1511 1512### getMaxVolume<sup>(deprecated)</sup> 1513 1514getMaxVolume(volumeType: AudioVolumeType): Promise<number> 1515 1516Obtains the maximum volume allowed for a stream. This API uses a promise to return the result. 1517 1518> **NOTE** 1519> 1520> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getMaxVolume](#getmaxvolume9) in **AudioVolumeGroupManager**. 1521 1522**System capability**: SystemCapability.Multimedia.Audio.Volume 1523 1524**Parameters** 1525 1526| Name | Type | Mandatory| Description | 1527| ---------- | ----------------------------------- | ---- | ------------ | 1528| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 1529 1530**Return value** 1531 1532| Type | Description | 1533| --------------------- | ----------------------------- | 1534| Promise<number> | Promise used to return the maximum volume.| 1535 1536**Example** 1537 1538```ts 1539audioManager.getMaxVolume(audio.AudioVolumeType.MEDIA).then((data: number) => { 1540 console.info('Promised returned to indicate that the maximum volume is obtained.'); 1541}); 1542``` 1543 1544### mute<sup>(deprecated)</sup> 1545 1546mute(volumeType: AudioVolumeType, mute: boolean, callback: AsyncCallback<void>): void 1547 1548Mutes or unmutes a stream. This API uses an asynchronous callback to return the result. 1549 1550When 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. 1551 1552> **NOTE** 1553> 1554> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 1555 1556**System capability**: SystemCapability.Multimedia.Audio.Volume 1557 1558**Parameters** 1559 1560| Name | Type | Mandatory| Description | 1561| ---------- | ----------------------------------- | ---- | ------------------------------------- | 1562| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1563| mute | boolean | Yes | Mute status to set. The value **true** means to mute the stream, and **false** means the opposite.| 1564| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1565 1566**Example** 1567 1568```ts 1569import { BusinessError } from '@kit.BasicServicesKit'; 1570 1571audioManager.mute(audio.AudioVolumeType.MEDIA, true, (err: BusinessError) => { 1572 if (err) { 1573 console.error(`Failed to mute the stream. ${err}`); 1574 return; 1575 } 1576 console.info('Callback invoked to indicate that the stream is muted.'); 1577}); 1578``` 1579 1580### mute<sup>(deprecated)</sup> 1581 1582mute(volumeType: AudioVolumeType, mute: boolean): Promise<void> 1583 1584Mutes or unmutes a stream. This API uses a promise to return the result. 1585 1586When 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. 1587 1588> **NOTE** 1589> 1590> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 1591 1592**System capability**: SystemCapability.Multimedia.Audio.Volume 1593 1594**Parameters** 1595 1596| Name | Type | Mandatory| Description | 1597| ---------- | ----------------------------------- | ---- | ------------------------------------- | 1598| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1599| mute | boolean | Yes | Mute status to set. The value **true** means to mute the stream, and **false** means the opposite.| 1600 1601**Return value** 1602 1603| Type | Description | 1604| ------------------- | ----------------------------- | 1605| Promise<void> | Promise that returns no value.| 1606 1607**Example** 1608 1609 1610```ts 1611audioManager.mute(audio.AudioVolumeType.MEDIA, true).then(() => { 1612 console.info('Promise returned to indicate that the stream is muted.'); 1613}); 1614``` 1615 1616### isMute<sup>(deprecated)</sup> 1617 1618isMute(volumeType: AudioVolumeType, callback: AsyncCallback<boolean>): void 1619 1620Checks whether a stream is muted. This API uses an asynchronous callback to return the result. 1621 1622> **NOTE** 1623> 1624> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isMute](#ismute9) in **AudioVolumeGroupManager**. 1625 1626**System capability**: SystemCapability.Multimedia.Audio.Volume 1627 1628**Parameters** 1629 1630| Name | Type | Mandatory| Description | 1631| ---------- | ----------------------------------- | ---- | ----------------------------------------------- | 1632| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1633| 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.| 1634 1635**Example** 1636 1637```ts 1638import { BusinessError } from '@kit.BasicServicesKit'; 1639 1640audioManager.isMute(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: boolean) => { 1641 if (err) { 1642 console.error(`Failed to obtain the mute status. ${err}`); 1643 return; 1644 } 1645 console.info(`Callback invoked to indicate that the mute status of the stream is obtained. ${value}`); 1646}); 1647``` 1648 1649### isMute<sup>(deprecated)</sup> 1650 1651isMute(volumeType: AudioVolumeType): Promise<boolean> 1652 1653Checks whether a stream is muted. This API uses a promise to return the result. 1654 1655> **NOTE** 1656> 1657> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isMute](#ismute9) in **AudioVolumeGroupManager**. 1658 1659**System capability**: SystemCapability.Multimedia.Audio.Volume 1660 1661**Parameters** 1662 1663| Name | Type | Mandatory| Description | 1664| ---------- | ----------------------------------- | ---- | ------------ | 1665| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 1666 1667**Return value** 1668 1669| Type | Description | 1670| ---------------------- | ------------------------------------------------------ | 1671| 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.| 1672 1673**Example** 1674 1675```ts 1676audioManager.isMute(audio.AudioVolumeType.MEDIA).then((value: boolean) => { 1677 console.info(`Promise returned to indicate that the mute status of the stream is obtained ${value}.`); 1678}); 1679``` 1680 1681### isActive<sup>(deprecated)</sup> 1682 1683isActive(volumeType: AudioVolumeType, callback: AsyncCallback<boolean>): void 1684 1685Checks whether a stream is active. This API uses an asynchronous callback to return the result. 1686 1687> **NOTE** 1688> 1689> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isActive](#isactive9) in **AudioStreamManager**. 1690 1691**System capability**: SystemCapability.Multimedia.Audio.Volume 1692 1693**Parameters** 1694 1695| Name | Type | Mandatory| Description | 1696| ---------- | ----------------------------------- | ---- | ------------------------------------------------- | 1697| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1698| 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.| 1699 1700**Example** 1701 1702```ts 1703import { BusinessError } from '@kit.BasicServicesKit'; 1704 1705audioManager.isActive(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: boolean) => { 1706 if (err) { 1707 console.error(`Failed to obtain the active status of the stream. ${err}`); 1708 return; 1709 } 1710 console.info(`Callback invoked to indicate that the active status of the stream is obtained ${value}.`); 1711}); 1712``` 1713 1714### isActive<sup>(deprecated)</sup> 1715 1716isActive(volumeType: AudioVolumeType): Promise<boolean> 1717 1718Checks whether a stream is active. This API uses a promise to return the result. 1719 1720> **NOTE** 1721> 1722> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isActive](#isactive9) in **AudioStreamManager**. 1723 1724**System capability**: SystemCapability.Multimedia.Audio.Volume 1725 1726**Parameters** 1727 1728| Name | Type | Mandatory| Description | 1729| ---------- | ----------------------------------- | ---- | ------------ | 1730| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 1731 1732**Return value** 1733 1734| Type | Description | 1735| ---------------------- | -------------------------------------------------------- | 1736| 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.| 1737 1738**Example** 1739 1740```ts 1741audioManager.isActive(audio.AudioVolumeType.MEDIA).then((value: boolean) => { 1742 console.info(`Promise returned to indicate that the active status of the stream is obtained ${value}.`); 1743}); 1744``` 1745 1746### setRingerMode<sup>(deprecated)</sup> 1747 1748setRingerMode(mode: AudioRingMode, callback: AsyncCallback<void>): void 1749 1750Sets the ringer mode. This API uses an asynchronous callback to return the result. 1751 1752> **NOTE** 1753> 1754> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 1755 1756**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 1757 1758This permission is required only for muting or unmuting the ringer. 1759 1760**System capability**: SystemCapability.Multimedia.Audio.Communication 1761 1762**Parameters** 1763 1764| Name | Type | Mandatory| Description | 1765| -------- | ------------------------------- | ---- | ------------------------ | 1766| mode | [AudioRingMode](#audioringmode) | Yes | Ringer mode. | 1767| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1768 1769**Example** 1770 1771```ts 1772import { BusinessError } from '@kit.BasicServicesKit'; 1773 1774audioManager.setRingerMode(audio.AudioRingMode.RINGER_MODE_NORMAL, (err: BusinessError) => { 1775 if (err) { 1776 console.error(`Failed to set the ringer mode. ${err}`); 1777 return; 1778 } 1779 console.info('Callback invoked to indicate a successful setting of the ringer mode.'); 1780}); 1781``` 1782 1783### setRingerMode<sup>(deprecated)</sup> 1784 1785setRingerMode(mode: AudioRingMode): Promise<void> 1786 1787Sets the ringer mode. This API uses a promise to return the result. 1788 1789> **NOTE** 1790> 1791> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 1792 1793 1794**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 1795 1796This permission is required only for muting or unmuting the ringer. 1797 1798**System capability**: SystemCapability.Multimedia.Audio.Communication 1799 1800**Parameters** 1801 1802| Name| Type | Mandatory| Description | 1803| ------ | ------------------------------- | ---- | -------------- | 1804| mode | [AudioRingMode](#audioringmode) | Yes | Ringer mode.| 1805 1806**Return value** 1807 1808| Type | Description | 1809| ------------------- | ------------------------------- | 1810| Promise<void> | Promise that returns no value.| 1811 1812**Example** 1813 1814```ts 1815audioManager.setRingerMode(audio.AudioRingMode.RINGER_MODE_NORMAL).then(() => { 1816 console.info('Promise returned to indicate a successful setting of the ringer mode.'); 1817}); 1818``` 1819 1820### getRingerMode<sup>(deprecated)</sup> 1821 1822getRingerMode(callback: AsyncCallback<AudioRingMode>): void 1823 1824Obtains the ringer mode. This API uses an asynchronous callback to return the result. 1825 1826> **NOTE** 1827> 1828> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getRingerMode](#getringermode9) in **AudioVolumeGroupManager**. 1829 1830**System capability**: SystemCapability.Multimedia.Audio.Communication 1831 1832**Parameters** 1833 1834| Name | Type | Mandatory| Description | 1835| -------- | ---------------------------------------------------- | ---- | ------------------------ | 1836| 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.| 1837 1838**Example** 1839 1840```ts 1841import { BusinessError } from '@kit.BasicServicesKit'; 1842 1843audioManager.getRingerMode((err: BusinessError, value: audio.AudioRingMode) => { 1844 if (err) { 1845 console.error(`Failed to obtain the ringer mode. ${err}`); 1846 return; 1847 } 1848 console.info(`Callback invoked to indicate that the ringer mode is obtained ${value}.`); 1849}); 1850``` 1851 1852### getRingerMode<sup>(deprecated)</sup> 1853 1854getRingerMode(): Promise<AudioRingMode> 1855 1856Obtains the ringer mode. This API uses a promise to return the result. 1857 1858> **NOTE** 1859> 1860> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getRingerMode](#getringermode9) in **AudioVolumeGroupManager**. 1861 1862**System capability**: SystemCapability.Multimedia.Audio.Communication 1863 1864**Return value** 1865 1866| Type | Description | 1867| ---------------------------------------------- | ------------------------------- | 1868| Promise<[AudioRingMode](#audioringmode)> | Promise used to return the ringer mode.| 1869 1870**Example** 1871 1872```ts 1873audioManager.getRingerMode().then((value: audio.AudioRingMode) => { 1874 console.info(`Promise returned to indicate that the ringer mode is obtained ${value}.`); 1875}); 1876``` 1877 1878### getDevices<sup>(deprecated)</sup> 1879 1880getDevices(deviceFlag: DeviceFlag, callback: AsyncCallback<AudioDeviceDescriptors>): void 1881 1882Obtains the audio devices with a specific flag. This API uses an asynchronous callback to return the result. 1883 1884> **NOTE** 1885> 1886> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getDevices](#getdevices9) in **AudioRoutingManager**. 1887 1888**System capability**: SystemCapability.Multimedia.Audio.Device 1889 1890**Parameters** 1891 1892| Name | Type | Mandatory| Description | 1893| ---------- | ------------------------------------------------------------ | ---- | -------------------- | 1894| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag. | 1895| 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.| 1896 1897**Example** 1898```ts 1899import { BusinessError } from '@kit.BasicServicesKit'; 1900 1901audioManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG, (err: BusinessError, value: audio.AudioDeviceDescriptors) => { 1902 if (err) { 1903 console.error(`Failed to obtain the device list. ${err}`); 1904 return; 1905 } 1906 console.info('Callback invoked to indicate that the device list is obtained.'); 1907}); 1908``` 1909 1910### getDevices<sup>(deprecated)</sup> 1911 1912getDevices(deviceFlag: DeviceFlag): Promise<AudioDeviceDescriptors> 1913 1914Obtains the audio devices with a specific flag. This API uses a promise to return the result. 1915 1916> **NOTE** 1917> 1918> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getDevices](#getdevices9) in **AudioRoutingManager**. 1919 1920**System capability**: SystemCapability.Multimedia.Audio.Device 1921 1922**Parameters** 1923 1924| Name | Type | Mandatory| Description | 1925| ---------- | ------------------------- | ---- | ---------------- | 1926| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag.| 1927 1928**Return value** 1929 1930| Type | Description | 1931| ------------------------------------------------------------ | ------------------------- | 1932| Promise<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Promise used to return the device list.| 1933 1934**Example** 1935 1936```ts 1937audioManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG).then((data: audio.AudioDeviceDescriptors) => { 1938 console.info('Promise returned to indicate that the device list is obtained.'); 1939}); 1940``` 1941 1942### setDeviceActive<sup>(deprecated)</sup> 1943 1944setDeviceActive(deviceType: ActiveDeviceType, active: boolean, callback: AsyncCallback<void>): void 1945 1946Sets a device to the active state. This API uses an asynchronous callback to return the result. 1947 1948> **NOTE** 1949> 1950> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setCommunicationDevice](#setcommunicationdevice9) in **AudioRoutingManager**. 1951 1952**System capability**: SystemCapability.Multimedia.Audio.Device 1953 1954**Parameters** 1955 1956| Name | Type | Mandatory| Description | 1957| ---------- | ------------------------------------- | ---- |-------------| 1958| deviceType | [ActiveDeviceType](#activedevicetypedeprecated) | Yes | Active audio device type. | 1959| active | boolean | Yes | Active state to set. The value **true** means to set the device to the active state, and **false** means the opposite. | 1960| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1961 1962**Example** 1963 1964```ts 1965import { BusinessError } from '@kit.BasicServicesKit'; 1966 1967audioManager.setDeviceActive(audio.ActiveDeviceType.SPEAKER, true, (err: BusinessError) => { 1968 if (err) { 1969 console.error(`Failed to set the active status of the device. ${err}`); 1970 return; 1971 } 1972 console.info('Callback invoked to indicate that the device is set to the active status.'); 1973}); 1974``` 1975 1976### setDeviceActive<sup>(deprecated)</sup> 1977 1978setDeviceActive(deviceType: ActiveDeviceType, active: boolean): Promise<void> 1979 1980Sets a device to the active state. This API uses a promise to return the result. 1981 1982> **NOTE** 1983> 1984> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setCommunicationDevice](#setcommunicationdevice9) in **AudioRoutingManager**. 1985 1986**System capability**: SystemCapability.Multimedia.Audio.Device 1987 1988**Parameters** 1989 1990| Name | Type | Mandatory| Description | 1991| ---------- | ------------------------------------- | ---- | ------------------ | 1992| deviceType | [ActiveDeviceType](#activedevicetypedeprecated) | Yes | Active audio device type.| 1993| active | boolean | Yes | Active state to set. The value **true** means to set the device to the active state, and **false** means the opposite. | 1994 1995**Return value** 1996 1997| Type | Description | 1998| ------------------- | ------------------------------- | 1999| Promise<void> | Promise that returns no value.| 2000 2001**Example** 2002 2003 2004```ts 2005audioManager.setDeviceActive(audio.ActiveDeviceType.SPEAKER, true).then(() => { 2006 console.info('Promise returned to indicate that the device is set to the active status.'); 2007}); 2008``` 2009 2010### isDeviceActive<sup>(deprecated)</sup> 2011 2012isDeviceActive(deviceType: ActiveDeviceType, callback: AsyncCallback<boolean>): void 2013 2014Checks whether a device is active. This API uses an asynchronous callback to return the result. 2015 2016> **NOTE** 2017> 2018> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isCommunicationDeviceActive](#iscommunicationdeviceactive9) in **AudioRoutingManager**. 2019 2020**System capability**: SystemCapability.Multimedia.Audio.Device 2021 2022**Parameters** 2023 2024| Name | Type | Mandatory| Description | 2025| ---------- | ------------------------------------- | ---- | ------------------------ | 2026| deviceType | [ActiveDeviceType](#activedevicetypedeprecated) | Yes | Active audio device type. | 2027| 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.| 2028 2029**Example** 2030 2031```ts 2032import { BusinessError } from '@kit.BasicServicesKit'; 2033 2034audioManager.isDeviceActive(audio.ActiveDeviceType.SPEAKER, (err: BusinessError, value: boolean) => { 2035 if (err) { 2036 console.error(`Failed to obtain the active status of the device. ${err}`); 2037 return; 2038 } 2039 console.info('Callback invoked to indicate that the active status of the device is obtained.'); 2040}); 2041``` 2042 2043### isDeviceActive<sup>(deprecated)</sup> 2044 2045isDeviceActive(deviceType: ActiveDeviceType): Promise<boolean> 2046 2047Checks whether a device is active. This API uses a promise to return the result. 2048 2049> **NOTE** 2050> 2051> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isCommunicationDeviceActive](#iscommunicationdeviceactive9) in **AudioRoutingManager**. 2052 2053**System capability**: SystemCapability.Multimedia.Audio.Device 2054 2055**Parameters** 2056 2057| Name | Type | Mandatory| Description | 2058| ---------- | ------------------------------------- | ---- | ------------------ | 2059| deviceType | [ActiveDeviceType](#activedevicetypedeprecated) | Yes | Active audio device type.| 2060 2061**Return value** 2062 2063| Type | Description | 2064| ---------------------- |---------------------------------------| 2065| 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. | 2066 2067**Example** 2068 2069```ts 2070audioManager.isDeviceActive(audio.ActiveDeviceType.SPEAKER).then((value: boolean) => { 2071 console.info(`Promise returned to indicate that the active status of the device is obtained ${value}.`); 2072}); 2073``` 2074 2075### setMicrophoneMute<sup>(deprecated)</sup> 2076 2077setMicrophoneMute(mute: boolean, callback: AsyncCallback<void>): void 2078 2079Mutes or unmutes the microphone. This API uses an asynchronous callback to return the result. 2080 2081> **NOTE** 2082> 2083> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 2084 2085**Required permissions**: ohos.permission.MICROPHONE 2086 2087**System capability**: SystemCapability.Multimedia.Audio.Device 2088 2089**Parameters** 2090 2091| Name | Type | Mandatory| Description | 2092| -------- | ------------------------- | ---- | --------------------------------------------- | 2093| mute | boolean | Yes | Mute status to set. The value **true** means to mute the microphone, and **false** means the opposite.| 2094| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 2095 2096**Example** 2097 2098```ts 2099import { BusinessError } from '@kit.BasicServicesKit'; 2100 2101audioManager.setMicrophoneMute(true, (err: BusinessError) => { 2102 if (err) { 2103 console.error(`Failed to mute the microphone. ${err}`); 2104 return; 2105 } 2106 console.info('Callback invoked to indicate that the microphone is muted.'); 2107}); 2108``` 2109 2110### setMicrophoneMute<sup>(deprecated)</sup> 2111 2112setMicrophoneMute(mute: boolean): Promise<void> 2113 2114Mutes or unmutes the microphone. This API uses a promise to return the result. 2115 2116> **NOTE** 2117> 2118> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 2119 2120**Required permissions**: ohos.permission.MICROPHONE 2121 2122**System capability**: SystemCapability.Multimedia.Audio.Device 2123 2124**Parameters** 2125 2126| Name| Type | Mandatory| Description | 2127| ------ | ------- | ---- | --------------------------------------------- | 2128| mute | boolean | Yes | Mute status to set. The value **true** means to mute the microphone, and **false** means the opposite.| 2129 2130**Return value** 2131 2132| Type | Description | 2133| ------------------- | ------------------------------- | 2134| Promise<void> | Promise that returns no value.| 2135 2136**Example** 2137 2138```ts 2139audioManager.setMicrophoneMute(true).then(() => { 2140 console.info('Promise returned to indicate that the microphone is muted.'); 2141}); 2142``` 2143 2144### isMicrophoneMute<sup>(deprecated)</sup> 2145 2146isMicrophoneMute(callback: AsyncCallback<boolean>): void 2147 2148Checks whether the microphone is muted. This API uses an asynchronous callback to return the result. 2149 2150> **NOTE** 2151> 2152> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isMicrophoneMute](#ismicrophonemute9) in **AudioVolumeGroupManager**. 2153 2154**Required permissions**: ohos.permission.MICROPHONE 2155 2156**System capability**: SystemCapability.Multimedia.Audio.Device 2157 2158**Parameters** 2159 2160| Name | Type | Mandatory| Description | 2161| -------- | ---------------------------- | ---- | ------------------------------------------------------- | 2162| 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.| 2163 2164**Example** 2165 2166```ts 2167import { BusinessError } from '@kit.BasicServicesKit'; 2168 2169audioManager.isMicrophoneMute((err: BusinessError, value: boolean) => { 2170 if (err) { 2171 console.error(`Failed to obtain the mute status of the microphone. ${err}`); 2172 return; 2173 } 2174 console.info(`Callback invoked to indicate that the mute status of the microphone is obtained ${value}.`); 2175}); 2176``` 2177 2178### isMicrophoneMute<sup>(deprecated)</sup> 2179 2180isMicrophoneMute(): Promise<boolean> 2181 2182Checks whether the microphone is muted. This API uses a promise to return the result. 2183 2184> **NOTE** 2185> 2186> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isMicrophoneMute](#ismicrophonemute9) in **AudioVolumeGroupManager**. 2187 2188**Required permissions**: ohos.permission.MICROPHONE 2189 2190**System capability**: SystemCapability.Multimedia.Audio.Device 2191 2192**Return value** 2193 2194| Type | Description | 2195| ---------------------- | ------------------------------------------------------------ | 2196| 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.| 2197 2198**Example** 2199 2200```ts 2201audioManager.isMicrophoneMute().then((value: boolean) => { 2202 console.info(`Promise returned to indicate that the mute status of the microphone is obtained ${value}.`); 2203}); 2204``` 2205 2206### on('deviceChange')<sup>(deprecated)</sup> 2207 2208on(type: 'deviceChange', callback: Callback<DeviceChangeAction\>): void 2209 2210Subscribes 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. 2211 2212> **NOTE** 2213> 2214> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [on('deviceChange')](#ondevicechange9) in **AudioRoutingManager**. 2215 2216**System capability**: SystemCapability.Multimedia.Audio.Device 2217 2218**Parameters** 2219 2220| Name | Type | Mandatory| Description | 2221| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- | 2222| type | string | Yes | Event type. The value is fixed at **'deviceChange'**.| 2223| callback | Callback<[DeviceChangeAction](#devicechangeaction)\> | Yes | Callback used to return the device change details.| 2224 2225**Example** 2226 2227```ts 2228audioManager.on('deviceChange', (deviceChanged: audio.DeviceChangeAction) => { 2229 console.info(`device change type : ${deviceChanged.type} `); 2230 console.info(`device descriptor size : ${deviceChanged.deviceDescriptors.length} `); 2231 console.info(`device change descriptor : ${deviceChanged.deviceDescriptors[0].deviceRole} `); 2232 console.info(`device change descriptor : ${deviceChanged.deviceDescriptors[0].deviceType} `); 2233}); 2234``` 2235 2236### off('deviceChange')<sup>(deprecated)</sup> 2237 2238off(type: 'deviceChange', callback?: Callback<DeviceChangeAction\>): void 2239 2240Unsubscribes from the audio device change event. This API uses an asynchronous callback to return the result. 2241 2242> **NOTE** 2243> 2244> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [off('deviceChange')](#offdevicechange9) in **AudioRoutingManager**. 2245 2246**System capability**: SystemCapability.Multimedia.Audio.Device 2247 2248**Parameters** 2249 2250| Name | Type | Mandatory| Description | 2251| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 2252| type | string | Yes | Event type. The value is fixed at **'deviceChange'**.| 2253| callback | Callback<[DeviceChangeAction](#devicechangeaction)> | No | Callback used to return the device change details.| 2254 2255**Example** 2256 2257```ts 2258// Cancel all subscriptions to the event. 2259audioManager.off('deviceChange'); 2260 2261// 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. 2262let deviceChangeCallback = (deviceChanged: audio.DeviceChangeAction) => { 2263 console.info(`device change type : ${deviceChanged.type} `); 2264 console.info(`device descriptor size : ${deviceChanged.deviceDescriptors.length} `); 2265 console.info(`device change descriptor : ${deviceChanged.deviceDescriptors[0].deviceRole} `); 2266 console.info(`device change descriptor : ${deviceChanged.deviceDescriptors[0].deviceType} `); 2267}; 2268 2269audioManager.on('deviceChange', deviceChangeCallback); 2270 2271audioManager.off('deviceChange', deviceChangeCallback); 2272``` 2273 2274### on('interrupt')<sup>(deprecated)</sup> 2275 2276on(type: 'interrupt', interrupt: AudioInterrupt, callback: Callback\<InterruptAction>): void 2277 2278Subscribes 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. 2279 2280Same 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. 2281 2282> **NOTE** 2283> 2284> This API is supported since API version 7 and deprecated since API version 11. You are advised to use [on('audioInterrupt')](#onaudiointerrupt10) in **AudioCapturer**. 2285 2286**System capability**: SystemCapability.Multimedia.Audio.Renderer 2287 2288**Parameters** 2289 2290| Name | Type | Mandatory| Description | 2291| --------- |---------------------------------------------------------| ---- | ------------------------------------------------------------ | 2292| type | string | Yes | Event type. The value is fixed at **'interrupt'**.| 2293| interrupt | [AudioInterrupt](#audiointerruptdeprecated) | Yes | Audio interruption event type. | 2294| callback | Callback<[InterruptAction](#interruptactiondeprecated)> | Yes | Callback used to return the audio interruption event.| 2295 2296**Example** 2297 2298```ts 2299import { audio } from '@kit.AudioKit'; 2300 2301let interAudioInterrupt: audio.AudioInterrupt = { 2302 streamUsage:2, 2303 contentType:0, 2304 pauseWhenDucked:true 2305}; 2306 2307audioManager.on('interrupt', interAudioInterrupt, (interruptAction: audio.InterruptAction) => { 2308 if (interruptAction.actionType === 0) { 2309 console.info('An event to gain the audio focus starts.'); 2310 console.info(`Focus gain event: ${interruptAction} `); 2311 } 2312 if (interruptAction.actionType === 1) { 2313 console.info('An audio interruption event starts.'); 2314 console.info(`Audio interruption event: ${interruptAction} `); 2315 } 2316}); 2317``` 2318 2319### off('interrupt')<sup>(deprecated)</sup> 2320 2321off(type: 'interrupt', interrupt: AudioInterrupt, callback?: Callback\<InterruptAction>): void 2322 2323Unsubscribes from the audio interruption event. This API uses an asynchronous callback to return the result. 2324 2325> **NOTE** 2326> 2327> This API is supported since API version 7 and deprecated since API version 11. You are advised to use [off('audioInterrupt')](#offaudiointerrupt10) in **AudioCapturer**. 2328 2329**System capability**: SystemCapability.Multimedia.Audio.Renderer 2330 2331**Parameters** 2332 2333| Name | Type | Mandatory| Description | 2334| --------- |---------------------------------------------------------| ---- | ------------------------------------------------------------ | 2335| type | string | Yes | Event type. The value is fixed at **'interrupt'**.| 2336| interrupt | [AudioInterrupt](#audiointerruptdeprecated) | Yes | Audio interruption event type. | 2337| callback | Callback<[InterruptAction](#interruptactiondeprecated)> | No | Callback used to return the audio interruption event.| 2338 2339**Example** 2340 2341```ts 2342import { audio } from '@kit.AudioKit'; 2343 2344let interAudioInterrupt: audio.AudioInterrupt = { 2345 streamUsage:2, 2346 contentType:0, 2347 pauseWhenDucked:true 2348}; 2349 2350// Cancel all subscriptions to the event. 2351audioManager.off('interrupt', interAudioInterrupt); 2352 2353// 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. 2354let interruptCallback = (interruptAction: audio.InterruptAction) => { 2355 if (interruptAction.actionType === 0) { 2356 console.info('An event to gain the audio focus starts.'); 2357 console.info(`Focus gain event: ${interruptAction} `); 2358 } 2359 if (interruptAction.actionType === 1) { 2360 console.info('An audio interruption event starts.'); 2361 console.info(`Audio interruption event: ${interruptAction} `); 2362 } 2363}; 2364 2365audioManager.on('interrupt', interAudioInterrupt, interruptCallback); 2366 2367audioManager.off('interrupt', interAudioInterrupt, interruptCallback); 2368``` 2369 2370## AudioVolumeManager<sup>9+</sup> 2371 2372Implements audio volume management. Before calling an API in **AudioVolumeManager**, you must use [getVolumeManager](#getvolumemanager9) to obtain an **AudioVolumeManager** instance. 2373 2374### getVolumeGroupManager<sup>9+</sup> 2375 2376getVolumeGroupManager(groupId: number, callback: AsyncCallback<AudioVolumeGroupManager\>\): void 2377 2378Obtains the volume group manager. This API uses an asynchronous callback to return the result. 2379 2380**System capability**: SystemCapability.Multimedia.Audio.Volume 2381 2382**Parameters** 2383 2384| Name | Type | Mandatory| Description | 2385| ---------- | ------------------------------------------------------------ | ---- |-----------------------------------------------------------| 2386| groupId | number | Yes | Volume group ID. The default value is **LOCAL_VOLUME_GROUP_ID**. | 2387| 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.| 2388 2389**Example** 2390 2391```ts 2392import { BusinessError } from '@kit.BasicServicesKit'; 2393 2394let groupId: number = audio.DEFAULT_VOLUME_GROUP_ID; 2395 2396audioVolumeManager.getVolumeGroupManager(groupId, (err: BusinessError, value: audio.AudioVolumeGroupManager) => { 2397 if (err) { 2398 console.error(`Failed to obtain the volume group infos list. ${err}`); 2399 return; 2400 } 2401 console.info('Callback invoked to indicate that the volume group infos list is obtained.'); 2402}); 2403 2404``` 2405 2406### getVolumeGroupManager<sup>9+</sup> 2407 2408getVolumeGroupManager(groupId: number\): Promise<AudioVolumeGroupManager\> 2409 2410Obtains the volume group manager. This API uses a promise to return the result. 2411 2412**System capability**: SystemCapability.Multimedia.Audio.Volume 2413 2414**Parameters** 2415 2416| Name | Type | Mandatory| Description | 2417| ---------- | ---------------------------------------- | ---- |----------------------------------| 2418| groupId | number | Yes | Volume group ID. The default value is **LOCAL_VOLUME_GROUP_ID**.| 2419 2420**Return value** 2421 2422| Type | Description | 2423| ------------------- | ----------------------------- | 2424| Promise< [AudioVolumeGroupManager](#audiovolumegroupmanager9) > | Promise used to return the volume group manager.| 2425 2426**Example** 2427 2428```ts 2429import { audio } from '@kit.AudioKit'; 2430 2431let groupId: number = audio.DEFAULT_VOLUME_GROUP_ID; 2432let audioVolumeGroupManager: audio.AudioVolumeGroupManager | undefined = undefined; 2433 2434async function getVolumeGroupManager(){ 2435 audioVolumeGroupManager = await audioVolumeManager.getVolumeGroupManager(groupId); 2436 console.info('Promise returned to indicate that the volume group infos list is obtained.'); 2437} 2438``` 2439 2440### getVolumeGroupManagerSync<sup>10+</sup> 2441 2442getVolumeGroupManagerSync(groupId: number\): AudioVolumeGroupManager 2443 2444Obtains the volume group manager. This API returns the result synchronously. 2445 2446**System capability**: SystemCapability.Multimedia.Audio.Volume 2447 2448**Parameters** 2449 2450| Name | Type | Mandatory| Description | 2451| ---------- | ---------------------------------------- | ---- |----------------------------------| 2452| groupId | number | Yes | Volume group ID. The default value is **LOCAL_VOLUME_GROUP_ID**.| 2453 2454**Return value** 2455 2456| Type | Description | 2457| ------------------- | ----------------------------- | 2458| [AudioVolumeGroupManager](#audiovolumegroupmanager9) | Volume group manager.| 2459 2460**Error codes** 2461 2462For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2463 2464| ID| Error Message| 2465| ------- | --------------------------------------------| 2466| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2467| 6800101 | Parameter verification failed. | 2468 2469**Example** 2470 2471```ts 2472import { BusinessError } from '@kit.BasicServicesKit'; 2473 2474try { 2475 let audioVolumeGroupManager: audio.AudioVolumeGroupManager = audioVolumeManager.getVolumeGroupManagerSync(audio.DEFAULT_VOLUME_GROUP_ID); 2476 console.info(`Get audioVolumeGroupManager success.`); 2477} catch (err) { 2478 let error = err as BusinessError; 2479 console.error(`Failed to get audioVolumeGroupManager, error: ${error}`); 2480} 2481``` 2482 2483### on('volumeChange')<sup>9+</sup> 2484 2485on(type: 'volumeChange', callback: Callback\<VolumeEvent>): void 2486 2487Subscribes 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. 2488 2489**System capability**: SystemCapability.Multimedia.Audio.Volume 2490 2491**Parameters** 2492 2493| Name | Type | Mandatory| Description | 2494| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 2495| type | string | Yes | Event type. The value is fixed at **'volumeChange'**.| 2496| callback | Callback<[VolumeEvent](#volumeevent9)> | Yes | Callback used to return the changed volume.| 2497 2498**Error codes** 2499 2500For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2501 2502| ID| Error Message| 2503| ------- | --------------------------------------------| 2504| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2505| 6800101 | Parameter verification failed. | 2506 2507**Example** 2508 2509```ts 2510audioVolumeManager.on('volumeChange', (volumeEvent: audio.VolumeEvent) => { 2511 console.info(`VolumeType of stream: ${volumeEvent.volumeType} `); 2512 console.info(`Volume level: ${volumeEvent.volume} `); 2513 console.info(`Whether to updateUI: ${volumeEvent.updateUi} `); 2514}); 2515``` 2516 2517### off('volumeChange')<sup>12+</sup> 2518 2519off(type: 'volumeChange', callback?: Callback\<VolumeEvent>): void 2520 2521Unsubscribes from the system volume change event. This API uses an asynchronous callback to return the result. 2522 2523**System capability**: SystemCapability.Multimedia.Audio.Volume 2524 2525**Parameters** 2526 2527| Name | Type | Mandatory| Description | 2528| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 2529| type | string | Yes | Event type. The value is fixed at **'volumeChange'**.| 2530| callback | Callback<[VolumeEvent](#volumeevent9)> | No | Callback used to return the changed volume.| 2531 2532**Error codes** 2533 2534For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2535 2536| ID| Error Message| 2537| ------- | --------------------------------------------| 2538| 401 | Parameter error. Possible causes: 1.Mandatory parameters missing; 2.Incorrect parameter types. | 2539| 6800101 | Parameter verification failed. | 2540 2541**Example** 2542 2543```ts 2544// Cancel all subscriptions to the event. 2545audioVolumeManager.off('volumeChange'); 2546 2547// 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. 2548let volumeChangeCallback = (volumeEvent: audio.VolumeEvent) => { 2549 console.info(`VolumeType of stream: ${volumeEvent.volumeType} `); 2550 console.info(`Volume level: ${volumeEvent.volume} `); 2551 console.info(`Whether to updateUI: ${volumeEvent.updateUi} `); 2552}; 2553 2554audioVolumeManager.on('volumeChange', volumeChangeCallback); 2555 2556audioVolumeManager.off('volumeChange', volumeChangeCallback); 2557``` 2558 2559## AudioVolumeGroupManager<sup>9+</sup> 2560 2561Manages the volume of an audio group. Before calling any API in **AudioVolumeGroupManager**, you must use [getVolumeGroupManager](#getvolumegroupmanager9) to obtain an **AudioVolumeGroupManager** instance. 2562 2563### getVolume<sup>9+</sup> 2564 2565getVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 2566 2567Obtains the volume of a stream. This API uses an asynchronous callback to return the result. 2568 2569**System capability**: SystemCapability.Multimedia.Audio.Volume 2570 2571**Parameters** 2572 2573| Name | Type | Mandatory| Description | 2574| ---------- | ----------------------------------- | ---- | ------------------ | 2575| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 2576| 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).| 2577 2578**Example** 2579 2580```ts 2581import { BusinessError } from '@kit.BasicServicesKit'; 2582 2583audioVolumeGroupManager.getVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { 2584 if (err) { 2585 console.error(`Failed to obtain the volume. ${err}`); 2586 return; 2587 } 2588 console.info('Callback invoked to indicate that the volume is obtained.'); 2589}); 2590``` 2591 2592### getVolume<sup>9+</sup> 2593 2594getVolume(volumeType: AudioVolumeType): Promise<number> 2595 2596Obtains the volume of a stream. This API uses a promise to return the result. 2597 2598**System capability**: SystemCapability.Multimedia.Audio.Volume 2599 2600**Parameters** 2601 2602| Name | Type | Mandatory| Description | 2603| ---------- | ----------------------------------- | ---- | ------------ | 2604| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2605 2606**Return value** 2607 2608| Type | Description | 2609| --------------------- | ------------------------- | 2610| 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).| 2611 2612**Example** 2613 2614```ts 2615audioVolumeGroupManager.getVolume(audio.AudioVolumeType.MEDIA).then((value: number) => { 2616 console.info(`Promise returned to indicate that the volume is obtained ${value}.`); 2617}); 2618``` 2619 2620### getVolumeSync<sup>10+</sup> 2621 2622getVolumeSync(volumeType: AudioVolumeType): number; 2623 2624Obtains the volume of a stream. This API returns the result synchronously. 2625 2626**System capability**: SystemCapability.Multimedia.Audio.Volume 2627 2628**Parameters** 2629 2630| Name | Type | Mandatory| Description | 2631| ---------- | ----------------------------------- | ---- | ------------ | 2632| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2633 2634**Return value** 2635 2636| Type | Description | 2637| --------------------- | ------------------------- | 2638| number | Volume of the stream. The volume range of a specified stream can be obtained by calling [getMinVolume](#getminvolume9) and [getMaxVolume](#getmaxvolume9).| 2639 2640**Error codes** 2641 2642For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2643 2644| ID| Error Message| 2645| ------- | --------------------------------------------| 2646| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2647| 6800101 | Parameter verification failed. | 2648 2649**Example** 2650 2651```ts 2652import { BusinessError } from '@kit.BasicServicesKit'; 2653 2654try { 2655 let value: number = audioVolumeGroupManager.getVolumeSync(audio.AudioVolumeType.MEDIA); 2656 console.info(`Indicate that the volume is obtained ${value}.`); 2657} catch (err) { 2658 let error = err as BusinessError; 2659 console.error(`Failed to obtain the volume, error ${error}.`); 2660} 2661``` 2662 2663### getMinVolume<sup>9+</sup> 2664 2665getMinVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 2666 2667Obtains the minimum volume allowed for a stream. This API uses an asynchronous callback to return the result. 2668 2669**System capability**: SystemCapability.Multimedia.Audio.Volume 2670 2671**Parameters** 2672 2673| Name | Type | Mandatory| Description | 2674| ---------- | ----------------------------------- | ---- | ------------------ | 2675| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 2676| 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.| 2677 2678**Example** 2679 2680```ts 2681import { BusinessError } from '@kit.BasicServicesKit'; 2682 2683audioVolumeGroupManager.getMinVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { 2684 if (err) { 2685 console.error(`Failed to obtain the minimum volume. ${err}`); 2686 return; 2687 } 2688 console.info(`Callback invoked to indicate that the minimum volume is obtained. ${value}`); 2689}); 2690``` 2691 2692### getMinVolume<sup>9+</sup> 2693 2694getMinVolume(volumeType: AudioVolumeType): Promise<number> 2695 2696Obtains the minimum volume allowed for a stream. This API uses a promise to return the result. 2697 2698**System capability**: SystemCapability.Multimedia.Audio.Volume 2699 2700**Parameters** 2701 2702| Name | Type | Mandatory| Description | 2703| ---------- | ----------------------------------- | ---- | ------------ | 2704| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2705 2706**Return value** 2707 2708| Type | Description | 2709| --------------------- | ------------------------- | 2710| Promise<number> | Promise used to return the minimum volume.| 2711 2712**Example** 2713 2714```ts 2715audioVolumeGroupManager.getMinVolume(audio.AudioVolumeType.MEDIA).then((value: number) => { 2716 console.info(`Promised returned to indicate that the minimum volume is obtained ${value}.`); 2717}); 2718``` 2719 2720### getMinVolumeSync<sup>10+</sup> 2721 2722getMinVolumeSync(volumeType: AudioVolumeType): number; 2723 2724Obtains the minimum volume allowed for a stream. This API returns the result synchronously. 2725 2726**System capability**: SystemCapability.Multimedia.Audio.Volume 2727 2728**Parameters** 2729 2730| Name | Type | Mandatory| Description | 2731| ---------- | ----------------------------------- | ---- | ------------ | 2732| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2733 2734**Return value** 2735 2736| Type | Description | 2737| --------------------- | ------------------------- | 2738| number | Minimum volume.| 2739 2740**Error codes** 2741 2742For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2743 2744| ID| Error Message| 2745| ------- | --------------------------------------------| 2746| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2747| 6800101 | Parameter verification failed. | 2748 2749**Example** 2750 2751```ts 2752import { BusinessError } from '@kit.BasicServicesKit'; 2753 2754try { 2755 let value: number = audioVolumeGroupManager.getMinVolumeSync(audio.AudioVolumeType.MEDIA); 2756 console.info(`Indicate that the minimum volume is obtained ${value}.`); 2757} catch (err) { 2758 let error = err as BusinessError; 2759 console.error(`Failed to obtain the minimum volume, error ${error}.`); 2760} 2761``` 2762 2763### getMaxVolume<sup>9+</sup> 2764 2765getMaxVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 2766 2767Obtains the maximum volume allowed for a stream. This API uses an asynchronous callback to return the result. 2768 2769**System capability**: SystemCapability.Multimedia.Audio.Volume 2770 2771**Parameters** 2772 2773| Name | Type | Mandatory| Description | 2774| ---------- | ----------------------------------- | ---- | ---------------------- | 2775| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 2776| 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.| 2777 2778**Example** 2779 2780```ts 2781import { BusinessError } from '@kit.BasicServicesKit'; 2782 2783audioVolumeGroupManager.getMaxVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { 2784 if (err) { 2785 console.error(`Failed to obtain the maximum volume. ${err}`); 2786 return; 2787 } 2788 console.info(`Callback invoked to indicate that the maximum volume is obtained. ${value}`); 2789}); 2790``` 2791 2792### getMaxVolume<sup>9+</sup> 2793 2794getMaxVolume(volumeType: AudioVolumeType): Promise<number> 2795 2796Obtains the maximum volume allowed for a stream. This API uses a promise to return the result. 2797 2798**System capability**: SystemCapability.Multimedia.Audio.Volume 2799 2800**Parameters** 2801 2802| Name | Type | Mandatory| Description | 2803| ---------- | ----------------------------------- | ---- | ------------ | 2804| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2805 2806**Return value** 2807 2808| Type | Description | 2809| --------------------- | ----------------------------- | 2810| Promise<number> | Promise used to return the maximum volume.| 2811 2812**Example** 2813 2814```ts 2815audioVolumeGroupManager.getMaxVolume(audio.AudioVolumeType.MEDIA).then((data: number) => { 2816 console.info('Promised returned to indicate that the maximum volume is obtained.'); 2817}); 2818``` 2819 2820### getMaxVolumeSync<sup>10+</sup> 2821 2822getMaxVolumeSync(volumeType: AudioVolumeType): number; 2823 2824Obtains the maximum volume allowed for a stream. This API returns the result synchronously. 2825 2826**System capability**: SystemCapability.Multimedia.Audio.Volume 2827 2828**Parameters** 2829 2830| Name | Type | Mandatory| Description | 2831| ---------- | ----------------------------------- | ---- | ------------ | 2832| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2833 2834**Return value** 2835 2836| Type | Description | 2837| --------------------- | ----------------------------- | 2838| number | Maximum volume.| 2839 2840**Error codes** 2841 2842For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2843 2844| ID| Error Message| 2845| ------- | --------------------------------------------| 2846| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2847| 6800101 | Parameter verification failed. | 2848 2849**Example** 2850 2851```ts 2852import { BusinessError } from '@kit.BasicServicesKit'; 2853 2854try { 2855 let value: number = audioVolumeGroupManager.getMaxVolumeSync(audio.AudioVolumeType.MEDIA); 2856 console.info(`Indicate that the maximum volume is obtained. ${value}`); 2857} catch (err) { 2858 let error = err as BusinessError; 2859 console.error(`Failed to obtain the maximum volume, error ${error}.`); 2860} 2861``` 2862 2863### isMute<sup>9+</sup> 2864 2865isMute(volumeType: AudioVolumeType, callback: AsyncCallback<boolean>): void 2866 2867Checks whether a stream is muted. This API uses an asynchronous callback to return the result. 2868 2869**System capability**: SystemCapability.Multimedia.Audio.Volume 2870 2871**Parameters** 2872 2873| Name | Type | Mandatory| Description | 2874| ---------- | ----------------------------------- | ---- | ----------------------------------------------- | 2875| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 2876| 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.| 2877 2878**Example** 2879 2880```ts 2881import { BusinessError } from '@kit.BasicServicesKit'; 2882 2883audioVolumeGroupManager.isMute(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: boolean) => { 2884 if (err) { 2885 console.error(`Failed to obtain the mute status. ${err}`); 2886 return; 2887 } 2888 console.info(`Callback invoked to indicate that the mute status of the stream is obtained ${value}.`); 2889}); 2890``` 2891 2892### isMute<sup>9+</sup> 2893 2894isMute(volumeType: AudioVolumeType): Promise<boolean> 2895 2896Checks whether a stream is muted. This API uses a promise to return the result. 2897 2898**System capability**: SystemCapability.Multimedia.Audio.Volume 2899 2900**Parameters** 2901 2902| Name | Type | Mandatory| Description | 2903| ---------- | ----------------------------------- | ---- | ------------ | 2904| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2905 2906**Return value** 2907 2908| Type | Description | 2909| ---------------------- | ------------------------------------------------------ | 2910| 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.| 2911 2912**Example** 2913 2914```ts 2915audioVolumeGroupManager.isMute(audio.AudioVolumeType.MEDIA).then((value: boolean) => { 2916 console.info(`Promise returned to indicate that the mute status of the stream is obtained ${value}.`); 2917}); 2918``` 2919 2920### isMuteSync<sup>10+</sup> 2921 2922isMuteSync(volumeType: AudioVolumeType): boolean 2923 2924Checks whether a stream is muted. This API returns the result synchronously. 2925 2926**System capability**: SystemCapability.Multimedia.Audio.Volume 2927 2928**Parameters** 2929 2930| Name | Type | Mandatory| Description | 2931| ---------- | ----------------------------------- | ---- | ------------ | 2932| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2933 2934**Return value** 2935 2936| Type | Description | 2937| ---------------------- | ------------------------------------------------------ | 2938| boolean | **true**: The stream is muted.<br>**false**: The stream is not muted.| 2939 2940**Error codes** 2941 2942For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2943 2944| ID| Error Message| 2945| ------- | --------------------------------------------| 2946| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2947| 6800101 | Parameter verification failed. | 2948 2949**Example** 2950 2951```ts 2952import { BusinessError } from '@kit.BasicServicesKit'; 2953 2954try { 2955 let value: boolean = audioVolumeGroupManager.isMuteSync(audio.AudioVolumeType.MEDIA); 2956 console.info(`Indicate that the mute status of the stream is obtained ${value}.`); 2957} catch (err) { 2958 let error = err as BusinessError; 2959 console.error(`Failed to obtain the mute status of the stream, error ${error}.`); 2960} 2961``` 2962 2963### getRingerMode<sup>9+</sup> 2964 2965getRingerMode(callback: AsyncCallback<AudioRingMode>): void 2966 2967Obtains the ringer mode. This API uses an asynchronous callback to return the result. 2968 2969**System capability**: SystemCapability.Multimedia.Audio.Volume 2970 2971**Parameters** 2972 2973| Name | Type | Mandatory| Description | 2974| -------- | ---------------------------------------------------- | ---- | ------------------------ | 2975| 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.| 2976 2977**Example** 2978 2979```ts 2980import { BusinessError } from '@kit.BasicServicesKit'; 2981 2982audioVolumeGroupManager.getRingerMode((err: BusinessError, value: audio.AudioRingMode) => { 2983 if (err) { 2984 console.error(`Failed to obtain the ringer mode. ${err}`); 2985 return; 2986 } 2987 console.info(`Callback invoked to indicate that the ringer mode is obtained ${value}.`); 2988}); 2989``` 2990 2991### getRingerMode<sup>9+</sup> 2992 2993getRingerMode(): Promise<AudioRingMode> 2994 2995Obtains the ringer mode. This API uses a promise to return the result. 2996 2997**System capability**: SystemCapability.Multimedia.Audio.Volume 2998 2999**Return value** 3000 3001| Type | Description | 3002| ---------------------------------------------- | ------------------------------- | 3003| Promise<[AudioRingMode](#audioringmode)> | Promise used to return the ringer mode.| 3004 3005**Example** 3006 3007```ts 3008audioVolumeGroupManager.getRingerMode().then((value: audio.AudioRingMode) => { 3009 console.info(`Promise returned to indicate that the ringer mode is obtained ${value}.`); 3010}); 3011``` 3012 3013### getRingerModeSync<sup>10+</sup> 3014 3015getRingerModeSync(): AudioRingMode 3016 3017Obtains the ringer mode. This API returns the result synchronously. 3018 3019**System capability**: SystemCapability.Multimedia.Audio.Volume 3020 3021**Return value** 3022 3023| Type | Description | 3024| ---------------------------------------------- | ------------------------------- | 3025| [AudioRingMode](#audioringmode) | Ringer mode.| 3026 3027**Example** 3028 3029```ts 3030import { BusinessError } from '@kit.BasicServicesKit'; 3031 3032try { 3033 let value: audio.AudioRingMode = audioVolumeGroupManager.getRingerModeSync(); 3034 console.info(`Indicate that the ringer mode is obtained ${value}.`); 3035} catch (err) { 3036 let error = err as BusinessError; 3037 console.error(`Failed to obtain the ringer mode, error ${error}.`); 3038} 3039``` 3040 3041### on('ringerModeChange')<sup>9+</sup> 3042 3043on(type: 'ringerModeChange', callback: Callback\<AudioRingMode>): void 3044 3045Subscribes to the ringer mode change event, which is triggered when [audioringmode](#audioringmode) is changed. This API uses an asynchronous callback to return the result. 3046 3047**System capability**: SystemCapability.Multimedia.Audio.Volume 3048 3049**Parameters** 3050 3051| Name | Type | Mandatory| Description | 3052| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 3053| type | string | Yes | Event type. The value is fixed at **'ringerModeChange'**.| 3054| callback | Callback<[AudioRingMode](#audioringmode)> | Yes | Callback used to return the changed ringer mode.| 3055 3056**Error codes** 3057 3058For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3059 3060| ID| Error Message| 3061| ------- | --------------------------------------------| 3062| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3063| 6800101 | Parameter verification failed. | 3064 3065**Example** 3066 3067```ts 3068audioVolumeGroupManager.on('ringerModeChange', (ringerMode: audio.AudioRingMode) => { 3069 console.info(`Updated ringermode: ${ringerMode}`); 3070}); 3071``` 3072 3073### setMicrophoneMute<sup>(deprecated)</sup> 3074 3075setMicrophoneMute(mute: boolean, callback: AsyncCallback<void>): void 3076 3077Mutes or unmutes the microphone. This API uses an asynchronous callback to return the result. 3078 3079> **NOTE** 3080> 3081> This API is supported since API version 9 and deprecated since API version 11. The substitute API is available only for system applications. 3082 3083**Required permissions**: ohos.permission.MANAGE_AUDIO_CONFIG (available only for system applications) 3084 3085**System capability**: SystemCapability.Multimedia.Audio.Volume 3086 3087**Parameters** 3088 3089| Name | Type | Mandatory| Description | 3090| -------- | ------------------------- | ---- | --------------------------------------------- | 3091| mute | boolean | Yes | Mute status to set. The value **true** means to mute the microphone, and **false** means the opposite.| 3092| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 3093 3094**Example** 3095 3096```ts 3097import { BusinessError } from '@kit.BasicServicesKit'; 3098 3099audioVolumeGroupManager.setMicrophoneMute(true, (err: BusinessError) => { 3100 if (err) { 3101 console.error(`Failed to mute the microphone. ${err}`); 3102 return; 3103 } 3104 console.info('Callback invoked to indicate that the microphone is muted.'); 3105}); 3106``` 3107 3108### setMicrophoneMute<sup>(deprecated)</sup> 3109 3110setMicrophoneMute(mute: boolean): Promise<void> 3111 3112Mutes or unmutes the microphone. This API uses a promise to return the result. 3113 3114> **NOTE** 3115> 3116> This API is supported since API version 9 and deprecated since API version 11. The substitute API is available only for system applications. 3117 3118**Required permissions**: ohos.permission.MANAGE_AUDIO_CONFIG (available only for system applications) 3119 3120**System capability**: SystemCapability.Multimedia.Audio.Volume 3121 3122**Parameters** 3123 3124| Name| Type | Mandatory| Description | 3125| ------ | ------- | ---- | --------------------------------------------- | 3126| mute | boolean | Yes | Mute status to set. The value **true** means to mute the microphone, and **false** means the opposite.| 3127 3128**Return value** 3129 3130| Type | Description | 3131| ------------------- | ------------------------------- | 3132| Promise<void> | Promise that returns no value.| 3133 3134**Example** 3135 3136```ts 3137audioVolumeGroupManager.setMicrophoneMute(true).then(() => { 3138 console.info('Promise returned to indicate that the microphone is muted.'); 3139}); 3140``` 3141 3142### isMicrophoneMute<sup>9+</sup> 3143 3144isMicrophoneMute(callback: AsyncCallback<boolean>): void 3145 3146Checks whether the microphone is muted. This API uses an asynchronous callback to return the result. 3147 3148**System capability**: SystemCapability.Multimedia.Audio.Volume 3149 3150**Parameters** 3151 3152| Name | Type | Mandatory| Description | 3153| -------- | ---------------------------- | ---- | ------------------------------------------------------- | 3154| 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.| 3155 3156**Example** 3157 3158```ts 3159import { BusinessError } from '@kit.BasicServicesKit'; 3160 3161audioVolumeGroupManager.isMicrophoneMute((err: BusinessError, value: boolean) => { 3162 if (err) { 3163 console.error(`Failed to obtain the mute status of the microphone. ${err}`); 3164 return; 3165 } 3166 console.info(`Callback invoked to indicate that the mute status of the microphone is obtained ${value}.`); 3167}); 3168``` 3169 3170### isMicrophoneMute<sup>9+</sup> 3171 3172isMicrophoneMute(): Promise<boolean> 3173 3174Checks whether the microphone is muted. This API uses a promise to return the result. 3175 3176**System capability**: SystemCapability.Multimedia.Audio.Volume 3177 3178**Return value** 3179 3180| Type | Description | 3181| ---------------------- | ------------------------------------------------------------ | 3182| 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.| 3183 3184**Example** 3185 3186```ts 3187audioVolumeGroupManager.isMicrophoneMute().then((value: boolean) => { 3188 console.info(`Promise returned to indicate that the mute status of the microphone is obtained ${value}.`); 3189}); 3190``` 3191 3192### isMicrophoneMuteSync<sup>10+</sup> 3193 3194isMicrophoneMuteSync(): boolean 3195 3196Checks whether the microphone is muted. This API returns the result synchronously. 3197 3198**System capability**: SystemCapability.Multimedia.Audio.Volume 3199 3200**Return value** 3201 3202| Type | Description | 3203| ---------------------- | ------------------------------------------------------------ | 3204| boolean | **true**: The microphone is muted.<br>**false**: The microphone is not muted.| 3205 3206**Example** 3207 3208```ts 3209import { BusinessError } from '@kit.BasicServicesKit'; 3210 3211try { 3212 let value: boolean = audioVolumeGroupManager.isMicrophoneMuteSync(); 3213 console.info(`Indicate that the mute status of the microphone is obtained ${value}.`); 3214} catch (err) { 3215 let error = err as BusinessError; 3216 console.error(`Failed to obtain the mute status of the microphone, error ${error}.`); 3217} 3218``` 3219 3220### on('micStateChange')<sup>9+</sup> 3221 3222on(type: 'micStateChange', callback: Callback<MicStateChangeEvent>): void 3223 3224Subscribes 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. 3225 3226Currently, 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. 3227 3228**System capability**: SystemCapability.Multimedia.Audio.Volume 3229 3230**Parameters** 3231 3232| Name | Type | Mandatory| Description | 3233| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 3234| type | string | Yes | Event type. The value is fixed at **'micStateChange'**.| 3235| callback | Callback<[MicStateChangeEvent](#micstatechangeevent9)> | Yes | Callback used to return the changed microphone state.| 3236 3237**Error codes** 3238 3239For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3240 3241| ID| Error Message| 3242| ------- | --------------------------------------------| 3243| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3244| 6800101 | Parameter verification failed. | 3245 3246**Example** 3247 3248```ts 3249audioVolumeGroupManager.on('micStateChange', (micStateChange: audio.MicStateChangeEvent) => { 3250 console.info(`Current microphone status is: ${micStateChange.mute} `); 3251}); 3252``` 3253 3254### off('micStateChange')<sup>12+</sup> 3255 3256off(type: 'micStateChange', callback?: Callback<MicStateChangeEvent>): void 3257 3258Unsubscribes from system microphone state change event. This API uses an asynchronous callback to return the result. 3259 3260**System capability**: SystemCapability.Multimedia.Audio.Volume 3261 3262**Parameters** 3263 3264| Name | Type | Mandatory| Description | 3265| -------- | -------------------------------------- |----| ------------------------------------------------------------ | 3266| type | string | Yes | Event type. The value is fixed at **'micStateChange'**.| 3267| callback | Callback<[MicStateChangeEvent](#micstatechangeevent9)> | No | Callback used to return the changed microphone state.| 3268 3269**Error codes** 3270 3271For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3272 3273| ID| Error Message| 3274| ------- | --------------------------------------------| 3275| 401 | Parameter error. Possible causes: 1.Mandatory parameters missing; 2.Incorrect parameter types. | 3276| 6800101 | Parameter verification failed. | 3277 3278**Example** 3279 3280```ts 3281// Cancel all subscriptions to the event. 3282audioVolumeGroupManager.off('micStateChange'); 3283 3284// 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. 3285let micStateChangeCallback = (micStateChange: audio.MicStateChangeEvent) => { 3286 console.info(`Current microphone status is: ${micStateChange.mute} `); 3287}; 3288 3289audioVolumeGroupManager.on('micStateChange', micStateChangeCallback); 3290 3291audioVolumeGroupManager.off('micStateChange', micStateChangeCallback); 3292``` 3293 3294### isVolumeUnadjustable<sup>10+</sup> 3295 3296isVolumeUnadjustable(): boolean 3297 3298Checks 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. 3299 3300**System capability**: SystemCapability.Multimedia.Audio.Volume 3301 3302**Return value** 3303 3304| Type | Description | 3305| ---------------------- | ------------------------------------------------------ | 3306| boolean | **true**: The fixed volume mode is enabled.<br>**false**: The fixed volume mode is disabled.| 3307 3308**Example** 3309 3310```ts 3311let volumeAdjustSwitch: boolean = audioVolumeGroupManager.isVolumeUnadjustable(); 3312console.info(`Whether it is volume unadjustable: ${volumeAdjustSwitch}.`); 3313``` 3314 3315### getSystemVolumeInDb<sup>10+</sup> 3316 3317getSystemVolumeInDb(volumeType: AudioVolumeType, volumeLevel: number, device: DeviceType, callback: AsyncCallback<number>): void 3318 3319Obtains the volume gain. This API uses an asynchronous callback to return the result. 3320 3321**System capability**: SystemCapability.Multimedia.Audio.Volume 3322 3323**Parameters** 3324 3325| Name | Type | Mandatory| Description | 3326| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 3327| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 3328| volumeLevel | number | Yes | Volume level. | 3329| device | [DeviceType](#devicetype) | Yes | Device type. | 3330| 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.| 3331 3332**Error codes** 3333 3334For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3335 3336| ID| Error Message| 3337| ------- | --------------------------------------------| 3338| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3339| 6800101 | Parameter verification failed. Return by callback. | 3340| 6800301 | System error. Return by callback. | 3341 3342**Example** 3343 3344```ts 3345import { BusinessError } from '@kit.BasicServicesKit'; 3346 3347audioVolumeGroupManager.getSystemVolumeInDb(audio.AudioVolumeType.MEDIA, 3, audio.DeviceType.SPEAKER, (err: BusinessError, dB: number) => { 3348 if (err) { 3349 console.error(`Failed to get the volume DB. ${err}`); 3350 } else { 3351 console.info(`Success to get the volume DB. ${dB}`); 3352 } 3353}); 3354``` 3355### getSystemVolumeInDb<sup>10+</sup> 3356 3357getSystemVolumeInDb(volumeType: AudioVolumeType, volumeLevel: number, device: DeviceType): Promise<number> 3358 3359Obtains the volume gain. This API uses a promise to return the result. 3360 3361**System capability**: SystemCapability.Multimedia.Audio.Volume 3362 3363**Parameters** 3364 3365| Name | Type | Mandatory| Description | 3366| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 3367| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 3368| volumeLevel | number | Yes | Volume level. | 3369| device | [DeviceType](#devicetype) | Yes | Device type. | 3370 3371**Return value** 3372 3373| Type | Description | 3374| --------------------- | ---------------------------------- | 3375| Promise<number> | Promise used to return the volume gain (in dB).| 3376 3377**Error codes** 3378 3379For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3380 3381| ID| Error Message| 3382| ------- | --------------------------------------------| 3383| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3384| 6800101 | Parameter verification failed. Return by promise. | 3385| 6800301 | System error. Return by promise. | 3386 3387**Example** 3388 3389```ts 3390import { BusinessError } from '@kit.BasicServicesKit'; 3391 3392audioVolumeGroupManager.getSystemVolumeInDb(audio.AudioVolumeType.MEDIA, 3, audio.DeviceType.SPEAKER).then((value: number) => { 3393 console.info(`Success to get the volume DB. ${value}`); 3394}).catch((error: BusinessError) => { 3395 console.error(`Fail to adjust the system volume by step. ${error}`); 3396}); 3397``` 3398 3399### getSystemVolumeInDbSync<sup>10+</sup> 3400 3401getSystemVolumeInDbSync(volumeType: AudioVolumeType, volumeLevel: number, device: DeviceType): number 3402 3403Obtains the volume gain. This API returns the result synchronously. 3404 3405**System capability**: SystemCapability.Multimedia.Audio.Volume 3406 3407**Parameters** 3408 3409| Name | Type | Mandatory| Description | 3410| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 3411| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 3412| volumeLevel | number | Yes | Volume level. | 3413| device | [DeviceType](#devicetype) | Yes | Device type. | 3414 3415**Return value** 3416 3417| Type | Description | 3418| --------------------- | ---------------------------------- | 3419| number | Volume gain (in dB).| 3420 3421**Error codes** 3422 3423For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3424 3425| ID| Error Message| 3426| ------- | --------------------------------------------| 3427| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3428| 6800101 | Parameter verification failed. | 3429 3430**Example** 3431 3432```ts 3433import { BusinessError } from '@kit.BasicServicesKit'; 3434 3435try { 3436 let value: number = audioVolumeGroupManager.getSystemVolumeInDbSync(audio.AudioVolumeType.MEDIA, 3, audio.DeviceType.SPEAKER); 3437 console.info(`Success to get the volume DB. ${value}`); 3438} catch (err) { 3439 let error = err as BusinessError; 3440 console.error(`Fail to adjust the system volume by step. ${error}`); 3441} 3442``` 3443 3444### getMaxAmplitudeForInputDevice<sup>12+</sup> 3445 3446getMaxAmplitudeForInputDevice(inputDevice: AudioDeviceDescriptor): Promise<number> 3447 3448Obtains the maximum amplitude of the audio stream for an input device. This API uses a promise to return the result. 3449 3450**System capability**: SystemCapability.Multimedia.Audio.Volume 3451 3452**Parameters** 3453 3454| Name | Type | Mandatory| Description | 3455| ----------- | ------------------------------------- | ---- | --------------------------------------------------- | 3456| inputDevice | [AudioDeviceDescriptor](#audiodevicedescriptor) | Yes | Descriptor of the target device. | 3457 3458**Return value** 3459 3460| Type | Description | 3461| --------------------- | ---------------------------------- | 3462| Promise<number> | Promise used to return the maximum amplitude, which ranges from 0 to 1.| 3463 3464**Error codes** 3465 3466For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3467 3468| ID| Error Message| 3469| ------- | --------------------------------------------| 3470| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3471| 6800101 | Parameter verification failed. Return by promise. | 3472| 6800301 | System error. Return by promise. | 3473 3474**Example** 3475 3476```ts 3477import { BusinessError } from '@kit.BasicServicesKit'; 3478 3479let capturerInfo: audio.AudioCapturerInfo = { 3480 source: audio.SourceType.SOURCE_TYPE_MIC, // Audio source type: microphone. Set this parameter based on the service scenario. 3481 capturerFlags: 0 // AudioCapturer flag. 3482}; 3483 3484audio.getAudioManager().getRoutingManager().getPreferredInputDeviceForCapturerInfo(capturerInfo).then((data) => { 3485 audioVolumeGroupManager.getMaxAmplitudeForInputDevice(data[0]).then((value) => { 3486 console.info(`mic volatileume amplitude is: ${value}`); 3487 }).catch((err: BusinessError) => { 3488 console.error("getMaxAmplitudeForInputDevice error" + JSON.stringify(err)); 3489 }) 3490}).catch((err: BusinessError) => { 3491 console.error("get outputDeviceId error" + JSON.stringify(err)); 3492}) 3493``` 3494 3495### getMaxAmplitudeForOutputDevice<sup>12+</sup> 3496 3497getMaxAmplitudeForOutputDevice(outputDevice: AudioDeviceDescriptor): Promise<number> 3498 3499Obtains the maximum amplitude of the audio stream for an output device. This API uses a promise to return the result. 3500 3501**System capability**: SystemCapability.Multimedia.Audio.Volume 3502 3503**Parameters** 3504 3505| Name | Type | Mandatory| Description | 3506| ------------ | --------------------------------------- | ---- | -------------------------------------------------------- | 3507| outputDevice | [AudioDeviceDescriptor](#audiodevicedescriptor) | Yes | Descriptor of the target device. | 3508 3509**Return value** 3510 3511| Type | Description | 3512| --------------------- | ---------------------------------- | 3513| Promise<number> | Promise used to return the maximum amplitude, which ranges from 0 to 1.| 3514 3515**Error codes** 3516 3517For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3518 3519| ID| Error Message| 3520| ------- | --------------------------------------------| 3521| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3522| 6800101 | Parameter verification failed. Return by promise. | 3523| 6800301 | System error. Return by promise. | 3524 3525**Example** 3526 3527```ts 3528import { BusinessError } from '@kit.BasicServicesKit'; 3529 3530let rendererInfo: audio.AudioRendererInfo = { 3531 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, // Audio stream usage type: music. Set this parameter based on the service scenario. 3532 rendererFlags: 0 // AudioRenderer flag. 3533}; 3534 3535audio.getAudioManager().getRoutingManager().getPreferOutputDeviceForRendererInfo(rendererInfo).then((data) => { 3536 audioVolumeGroupManager.getMaxAmplitudeForOutputDevice(data[0]).then((value) => { 3537 console.info(`mic volatileume amplitude is: ${value}`); 3538 }).catch((err: BusinessError) => { 3539 console.error("getMaxAmplitudeForOutputDevice error" + JSON.stringify(err)); 3540 }) 3541}).catch((err: BusinessError) => { 3542 console.error("getPreferOutputDeviceForRendererInfo error" + JSON.stringify(err)); 3543}) 3544``` 3545 3546## AudioStreamManager<sup>9+</sup> 3547 3548Implements audio stream management. Before calling any API in **AudioStreamManager**, you must use [getStreamManager](#getstreammanager9) to obtain an **AudioStreamManager** instance. 3549 3550### getCurrentAudioRendererInfoArray<sup>9+</sup> 3551 3552getCurrentAudioRendererInfoArray(callback: AsyncCallback<AudioRendererChangeInfoArray>): void 3553 3554Obtains the information about the current audio renderer. This API uses an asynchronous callback to return the result. 3555 3556**System capability**: SystemCapability.Multimedia.Audio.Renderer 3557 3558**Parameters** 3559 3560| Name | Type | Mandatory | Description | 3561| -------- | ----------------------------------- | -------- | --------------------------- | 3562| 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.| 3563 3564**Example** 3565 3566```ts 3567import { BusinessError } from '@kit.BasicServicesKit'; 3568 3569audioStreamManager.getCurrentAudioRendererInfoArray(async (err: BusinessError, AudioRendererChangeInfoArray: audio.AudioRendererChangeInfoArray) => { 3570 console.info('getCurrentAudioRendererInfoArray **** Get Callback Called ****'); 3571 if (err) { 3572 console.error(`getCurrentAudioRendererInfoArray :ERROR: ${err}`); 3573 } else { 3574 if (AudioRendererChangeInfoArray != null) { 3575 for (let i = 0; i < AudioRendererChangeInfoArray.length; i++) { 3576 let AudioRendererChangeInfo: audio.AudioRendererChangeInfo = AudioRendererChangeInfoArray[i]; 3577 console.info(`StreamId for ${i} is: ${AudioRendererChangeInfo.streamId}`); 3578 console.info(`Content ${i} is: ${AudioRendererChangeInfo.rendererInfo.content}`); 3579 console.info(`Stream ${i} is: ${AudioRendererChangeInfo.rendererInfo.usage}`); 3580 console.info(`Flag ${i} is: ${AudioRendererChangeInfo.rendererInfo.rendererFlags}`); 3581 for (let j = 0;j < AudioRendererChangeInfo.deviceDescriptors.length; j++) { 3582 console.info(`Id: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].id}`); 3583 console.info(`Type: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceType}`); 3584 console.info(`Role: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceRole}`); 3585 console.info(`Name: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].name}`); 3586 console.info(`Address: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].address}`); 3587 console.info(`SampleRate: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].sampleRates[0]}`); 3588 console.info(`ChannelCount: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelCounts[0]}`); 3589 console.info(`ChannelMask: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelMasks[0]}`); 3590 } 3591 } 3592 } 3593 } 3594}); 3595``` 3596 3597### getCurrentAudioRendererInfoArray<sup>9+</sup> 3598 3599getCurrentAudioRendererInfoArray(): Promise<AudioRendererChangeInfoArray> 3600 3601Obtains the information about the current audio renderer. This API uses a promise to return the result. 3602 3603**System capability**: SystemCapability.Multimedia.Audio.Renderer 3604 3605**Return value** 3606 3607| Type | Description | 3608| ---------------------------------------------------------------------------------| --------------------------------------- | 3609| Promise<[AudioRendererChangeInfoArray](#audiorendererchangeinfoarray9)> | Promise used to return the renderer information. | 3610 3611**Example** 3612 3613```ts 3614import { BusinessError } from '@kit.BasicServicesKit'; 3615 3616async function getCurrentAudioRendererInfoArray(){ 3617 await audioStreamManager.getCurrentAudioRendererInfoArray().then((AudioRendererChangeInfoArray: audio.AudioRendererChangeInfoArray) => { 3618 console.info(`getCurrentAudioRendererInfoArray ######### Get Promise is called ##########`); 3619 if (AudioRendererChangeInfoArray != null) { 3620 for (let i = 0; i < AudioRendererChangeInfoArray.length; i++) { 3621 let AudioRendererChangeInfo: audio.AudioRendererChangeInfo = AudioRendererChangeInfoArray[i]; 3622 console.info(`StreamId for ${i} is: ${AudioRendererChangeInfo.streamId}`); 3623 console.info(`Content ${i} is: ${AudioRendererChangeInfo.rendererInfo.content}`); 3624 console.info(`Stream ${i} is: ${AudioRendererChangeInfo.rendererInfo.usage}`); 3625 console.info(`Flag ${i} is: ${AudioRendererChangeInfo.rendererInfo.rendererFlags}`); 3626 for (let j = 0;j < AudioRendererChangeInfo.deviceDescriptors.length; j++) { 3627 console.info(`Id: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].id}`); 3628 console.info(`Type: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceType}`); 3629 console.info(`Role: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceRole}`); 3630 console.info(`Name: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].name}`); 3631 console.info(`Address: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].address}`); 3632 console.info(`SampleRate: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].sampleRates[0]}`); 3633 console.info(`ChannelCount: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelCounts[0]}`); 3634 console.info(`ChannelMask: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelMasks[0]}`); 3635 } 3636 } 3637 } 3638 }).catch((err: BusinessError) => { 3639 console.error(`getCurrentAudioRendererInfoArray :ERROR: ${err}`); 3640 }); 3641} 3642``` 3643### getCurrentAudioRendererInfoArraySync<sup>10+</sup> 3644 3645getCurrentAudioRendererInfoArraySync(): AudioRendererChangeInfoArray 3646 3647Obtains the information about the current audio renderer. This API returns the result synchronously. 3648 3649**System capability**: SystemCapability.Multimedia.Audio.Renderer 3650 3651**Return value** 3652 3653| Type | Description | 3654| ---------------------------------------------------------------------------------| --------------------------------------- | 3655| [AudioRendererChangeInfoArray](#audiorendererchangeinfoarray9) | Audio renderer information. | 3656 3657**Example** 3658 3659```ts 3660import { BusinessError } from '@kit.BasicServicesKit'; 3661 3662try { 3663 let audioRendererChangeInfoArray: audio.AudioRendererChangeInfoArray = audioStreamManager.getCurrentAudioRendererInfoArraySync(); 3664 console.info(`getCurrentAudioRendererInfoArraySync success.`); 3665 if (audioRendererChangeInfoArray != null) { 3666 for (let i = 0; i < audioRendererChangeInfoArray.length; i++) { 3667 let AudioRendererChangeInfo: audio.AudioRendererChangeInfo = audioRendererChangeInfoArray[i]; 3668 console.info(`StreamId for ${i} is: ${AudioRendererChangeInfo.streamId}`); 3669 console.info(`Content ${i} is: ${AudioRendererChangeInfo.rendererInfo.content}`); 3670 console.info(`Stream ${i} is: ${AudioRendererChangeInfo.rendererInfo.usage}`); 3671 console.info(`Flag ${i} is: ${AudioRendererChangeInfo.rendererInfo.rendererFlags}`); 3672 for (let j = 0;j < AudioRendererChangeInfo.deviceDescriptors.length; j++) { 3673 console.info(`Id: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].id}`); 3674 console.info(`Type: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceType}`); 3675 console.info(`Role: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceRole}`); 3676 console.info(`Name: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].name}`); 3677 console.info(`Address: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].address}`); 3678 console.info(`SampleRate: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].sampleRates[0]}`); 3679 console.info(`ChannelCount: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelCounts[0]}`); 3680 console.info(`ChannelMask: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelMasks[0]}`); 3681 } 3682 } 3683 } 3684} catch (err) { 3685 let error = err as BusinessError; 3686 console.error(`getCurrentAudioRendererInfoArraySync :ERROR: ${error}`); 3687} 3688``` 3689 3690### getCurrentAudioCapturerInfoArray<sup>9+</sup> 3691 3692getCurrentAudioCapturerInfoArray(callback: AsyncCallback<AudioCapturerChangeInfoArray>): void 3693 3694Obtains the information about the current audio capturer. This API uses an asynchronous callback to return the result. 3695 3696**System capability**: SystemCapability.Multimedia.Audio.Renderer 3697 3698**Parameters** 3699 3700| Name | Type | Mandatory | Description | 3701| ---------- | ----------------------------------- | --------- | -------------------------------------------------------- | 3702| 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.| 3703 3704**Example** 3705 3706```ts 3707import { BusinessError } from '@kit.BasicServicesKit'; 3708 3709audioStreamManager.getCurrentAudioCapturerInfoArray(async (err: BusinessError, AudioCapturerChangeInfoArray: audio.AudioCapturerChangeInfoArray) => { 3710 console.info('getCurrentAudioCapturerInfoArray **** Get Callback Called ****'); 3711 if (err) { 3712 console.error(`getCurrentAudioCapturerInfoArray :ERROR: ${err}`); 3713 } else { 3714 if (AudioCapturerChangeInfoArray != null) { 3715 for (let i = 0; i < AudioCapturerChangeInfoArray.length; i++) { 3716 console.info(`StreamId for ${i} is: ${AudioCapturerChangeInfoArray[i].streamId}`); 3717 console.info(`Source for ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.source}`); 3718 console.info(`Flag ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.capturerFlags}`); 3719 for (let j = 0; j < AudioCapturerChangeInfoArray[i].deviceDescriptors.length; j++) { 3720 console.info(`Id: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].id}`); 3721 console.info(`Type: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceType}`); 3722 console.info(`Role: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceRole}`); 3723 console.info(`Name: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].name}`); 3724 console.info(`Address: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].address}`); 3725 console.info(`SampleRate: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].sampleRates[0]}`); 3726 console.info(`ChannelCount: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelCounts[0]}`); 3727 console.info(`ChannelMask: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelMasks[0]}`); 3728 } 3729 } 3730 } 3731 } 3732}); 3733``` 3734 3735### getCurrentAudioCapturerInfoArray<sup>9+</sup> 3736 3737getCurrentAudioCapturerInfoArray(): Promise<AudioCapturerChangeInfoArray> 3738 3739Obtains the information about the current audio capturer. This API uses a promise to return the result. 3740 3741**System capability**: SystemCapability.Multimedia.Audio.Renderer 3742 3743**Return value** 3744 3745| Type | Description | 3746| -----------------------------------------------------------------------------| ----------------------------------- | 3747| Promise<[AudioCapturerChangeInfoArray](#audiocapturerchangeinfoarray9)> | Promise used to return the audio capturer information. | 3748 3749**Example** 3750 3751```ts 3752import { BusinessError } from '@kit.BasicServicesKit'; 3753 3754async function getCurrentAudioCapturerInfoArray(){ 3755 await audioStreamManager.getCurrentAudioCapturerInfoArray().then((AudioCapturerChangeInfoArray: audio.AudioCapturerChangeInfoArray) => { 3756 console.info('getCurrentAudioCapturerInfoArray **** Get Promise Called ****'); 3757 if (AudioCapturerChangeInfoArray != null) { 3758 for (let i = 0; i < AudioCapturerChangeInfoArray.length; i++) { 3759 console.info(`StreamId for ${i} is: ${AudioCapturerChangeInfoArray[i].streamId}`); 3760 console.info(`Source for ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.source}`); 3761 console.info(`Flag ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.capturerFlags}`); 3762 for (let j = 0; j < AudioCapturerChangeInfoArray[i].deviceDescriptors.length; j++) { 3763 console.info(`Id: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].id}`); 3764 console.info(`Type: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceType}`); 3765 console.info(`Role: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceRole}`); 3766 console.info(`Name: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].name}`); 3767 console.info(`Address: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].address}`); 3768 console.info(`SampleRate: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].sampleRates[0]}`); 3769 console.info(`ChannelCount: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelCounts[0]}`); 3770 console.info(`ChannelMask: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelMasks[0]}`); 3771 } 3772 } 3773 } 3774 }).catch((err: BusinessError) => { 3775 console.error(`getCurrentAudioCapturerInfoArray :ERROR: ${err}`); 3776 }); 3777} 3778``` 3779### getCurrentAudioCapturerInfoArraySync<sup>10+</sup> 3780 3781getCurrentAudioCapturerInfoArraySync(): AudioCapturerChangeInfoArray 3782 3783Obtains the information about the current audio capturer. This API returns the result synchronously. 3784 3785**System capability**: SystemCapability.Multimedia.Audio.Capturer 3786 3787**Return value** 3788 3789| Type | Description | 3790| -----------------------------------------------------------------------------| ----------------------------------- | 3791| [AudioCapturerChangeInfoArray](#audiocapturerchangeinfoarray9) | Audio capturer information. | 3792 3793**Example** 3794 3795```ts 3796import { BusinessError } from '@kit.BasicServicesKit'; 3797 3798try { 3799 let audioCapturerChangeInfoArray: audio.AudioCapturerChangeInfoArray = audioStreamManager.getCurrentAudioCapturerInfoArraySync(); 3800 console.info('getCurrentAudioCapturerInfoArraySync success.'); 3801 if (audioCapturerChangeInfoArray != null) { 3802 for (let i = 0; i < audioCapturerChangeInfoArray.length; i++) { 3803 console.info(`StreamId for ${i} is: ${audioCapturerChangeInfoArray[i].streamId}`); 3804 console.info(`Source for ${i} is: ${audioCapturerChangeInfoArray[i].capturerInfo.source}`); 3805 console.info(`Flag ${i} is: ${audioCapturerChangeInfoArray[i].capturerInfo.capturerFlags}`); 3806 for (let j = 0; j < audioCapturerChangeInfoArray[i].deviceDescriptors.length; j++) { 3807 console.info(`Id: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].id}`); 3808 console.info(`Type: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceType}`); 3809 console.info(`Role: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceRole}`); 3810 console.info(`Name: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].name}`); 3811 console.info(`Address: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].address}`); 3812 console.info(`SampleRate: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].sampleRates[0]}`); 3813 console.info(`ChannelCount: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].channelCounts[0]}`); 3814 console.info(`ChannelMask: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].channelMasks[0]}`); 3815 } 3816 } 3817 } 3818} catch (err) { 3819 let error = err as BusinessError; 3820 console.error(`getCurrentAudioCapturerInfoArraySync ERROR: ${error}`); 3821} 3822``` 3823 3824### on('audioRendererChange')<sup>9+</sup> 3825 3826on(type: 'audioRendererChange', callback: Callback<AudioRendererChangeInfoArray>): void 3827 3828Subscribes 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. 3829 3830**System capability**: SystemCapability.Multimedia.Audio.Renderer 3831 3832**Parameters** 3833 3834| Name | Type | Mandatory | Description | 3835| -------- | ---------- | --------- | ------------------------------------------------------------------------ | 3836| type | string | Yes | Event type. The value is fixed at **'audioRendererChange'**. | 3837| callback | Callback<[AudioRendererChangeInfoArray](#audiorendererchangeinfoarray9)> | Yes | Callback used to return the audio renderer information.| 3838 3839**Error codes** 3840 3841For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3842 3843| ID| Error Message| 3844| ------- | --------------------------------------------| 3845| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3846| 6800101 | Parameter verification failed. | 3847 3848**Example** 3849 3850```ts 3851audioStreamManager.on('audioRendererChange', (audioRendererChangeInfoArray: audio.AudioRendererChangeInfoArray) => { 3852 for (let i = 0; i < audioRendererChangeInfoArray.length; i++) { 3853 let audioRendererChangeInfo: audio.AudioRendererChangeInfo = audioRendererChangeInfoArray[i]; 3854 console.info(`## RendererChange on is called for ${i} ##`); 3855 console.info(`StreamId for ${i} is: ${audioRendererChangeInfo.streamId}`); 3856 console.info(`Content ${i} is: ${audioRendererChangeInfo.rendererInfo.content}`); 3857 console.info(`Stream ${i} is: ${audioRendererChangeInfo.rendererInfo.usage}`); 3858 console.info(`Flag ${i} is: ${audioRendererChangeInfo.rendererInfo.rendererFlags}`); 3859 for (let j = 0;j < audioRendererChangeInfo.deviceDescriptors.length; j++) { 3860 console.info(`Id: ${i} : ${audioRendererChangeInfo.deviceDescriptors[j].id}`); 3861 console.info(`Type: ${i} : ${audioRendererChangeInfo.deviceDescriptors[j].deviceType}`); 3862 console.info(`Role: ${i} : ${audioRendererChangeInfo.deviceDescriptors[j].deviceRole}`); 3863 console.info(`Name: ${i} : ${audioRendererChangeInfo.deviceDescriptors[j].name}`); 3864 console.info(`Address: ${i} : ${audioRendererChangeInfo.deviceDescriptors[j].address}`); 3865 console.info(`SampleRate: ${i} : ${audioRendererChangeInfo.deviceDescriptors[j].sampleRates[0]}`); 3866 console.info(`ChannelCount: ${i} : ${audioRendererChangeInfo.deviceDescriptors[j].channelCounts[0]}`); 3867 console.info(`ChannelMask: ${i} : ${audioRendererChangeInfo.deviceDescriptors[j].channelMasks[0]}`); 3868 } 3869 } 3870}); 3871``` 3872 3873### off('audioRendererChange')<sup>9+</sup> 3874 3875off(type: 'audioRendererChange'): void 3876 3877Unsubscribes from the audio renderer change event. 3878 3879**System capability**: SystemCapability.Multimedia.Audio.Renderer 3880 3881**Parameters** 3882 3883| Name | Type | Mandatory| Description | 3884| -------- | ------- | ---- | ---------------- | 3885| type | string | Yes | Event type. The value is fixed at **'audioRendererChange'**.| 3886 3887**Error codes** 3888 3889For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3890 3891| ID| Error Message | 3892| ------- |--------------------------| 3893| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3894| 6800101 | Parameter verification failed. | 3895 3896**Example** 3897 3898```ts 3899audioStreamManager.off('audioRendererChange'); 3900``` 3901 3902### on('audioCapturerChange')<sup>9+</sup> 3903 3904on(type: 'audioCapturerChange', callback: Callback<AudioCapturerChangeInfoArray>): void 3905 3906Subscribes 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. 3907 3908**System capability**: SystemCapability.Multimedia.Audio.Capturer 3909 3910**Parameters** 3911 3912| Name | Type | Mandatory | Description | 3913| -------- | ------- | --------- | ---------------------------------------------------------------------- | 3914| type | string | Yes | Event type. The value is fixed at **'audioCapturerChange'**. | 3915| callback | Callback<[AudioCapturerChangeInfoArray](#audiocapturerchangeinfoarray9)> | Yes | Callback used to return the audio capturer information.| 3916 3917**Error codes** 3918 3919For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3920 3921| ID| Error Message| 3922| ------- | --------------------------------------------| 3923| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3924| 6800101 | Parameter verification failed. | 3925 3926**Example** 3927 3928```ts 3929audioStreamManager.on('audioCapturerChange', (AudioCapturerChangeInfoArray: audio.AudioCapturerChangeInfoArray) => { 3930 for (let i = 0; i < AudioCapturerChangeInfoArray.length; i++) { 3931 console.info(`## CapChange on is called for element ${i} ##`); 3932 console.info(`StreamId for ${i} is: ${AudioCapturerChangeInfoArray[i].streamId}`); 3933 console.info(`Source for ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.source}`); 3934 console.info(`Flag ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.capturerFlags}`); 3935 for (let j = 0; j < AudioCapturerChangeInfoArray[i].deviceDescriptors.length; j++) { 3936 console.info(`Id: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].id}`); 3937 console.info(`Type: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceType}`); 3938 console.info(`Role: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceRole}`); 3939 console.info(`Name: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].name}`); 3940 console.info(`Address: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].address}`); 3941 console.info(`SampleRate: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].sampleRates[0]}`); 3942 console.info(`ChannelCount: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelCounts[0]}`); 3943 console.info(`ChannelMask: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelMasks[0]}`); 3944 } 3945 } 3946}); 3947``` 3948 3949### off('audioCapturerChange')<sup>9+</sup> 3950 3951off(type: 'audioCapturerChange'): void 3952 3953Unsubscribes from the audio capturer change event. 3954 3955**System capability**: SystemCapability.Multimedia.Audio.Capturer 3956 3957**Parameters** 3958 3959| Name | Type | Mandatory| Description | 3960| -------- | -------- | --- | ------------------------------------------------------------- | 3961| type | string |Yes | Event type. The value is fixed at **'audioCapturerChange'**.| 3962 3963**Error codes** 3964 3965For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3966 3967| ID| Error Message| 3968| ------- | --------------------------------------------| 3969| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3970| 6800101 | Parameter verification failed. | 3971 3972**Example** 3973 3974```ts 3975audioStreamManager.off('audioCapturerChange'); 3976``` 3977 3978### isActive<sup>9+</sup> 3979 3980isActive(volumeType: AudioVolumeType, callback: AsyncCallback<boolean>): void 3981 3982Checks whether a stream is active. This API uses an asynchronous callback to return the result. 3983 3984**System capability**: SystemCapability.Multimedia.Audio.Renderer 3985 3986**Parameters** 3987 3988| Name | Type | Mandatory| Description | 3989| ---------- | ----------------------------------- | ---- | ------------------------------------------------- | 3990| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream types. | 3991| 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.| 3992 3993**Example** 3994 3995```ts 3996import { BusinessError } from '@kit.BasicServicesKit'; 3997 3998audioStreamManager.isActive(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: boolean) => { 3999if (err) { 4000 console.error(`Failed to obtain the active status of the stream. ${err}`); 4001 return; 4002} 4003 console.info(`Callback invoked to indicate that the active status of the stream is obtained ${value}.`); 4004}); 4005``` 4006 4007### isActive<sup>9+</sup> 4008 4009isActive(volumeType: AudioVolumeType): Promise<boolean> 4010 4011Checks whether a stream is active. This API uses a promise to return the result. 4012 4013**System capability**: SystemCapability.Multimedia.Audio.Renderer 4014 4015**Parameters** 4016 4017| Name | Type | Mandatory| Description | 4018| ---------- | ----------------------------------- | ---- | ------------ | 4019| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream types.| 4020 4021**Return value** 4022 4023| Type | Description | 4024| ---------------------- | -------------------------------------------------------- | 4025| 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.| 4026 4027**Example** 4028 4029```ts 4030audioStreamManager.isActive(audio.AudioVolumeType.MEDIA).then((value: boolean) => { 4031 console.info(`Promise returned to indicate that the active status of the stream is obtained ${value}.`); 4032}); 4033``` 4034 4035### isActiveSync<sup>10+</sup> 4036 4037isActiveSync(volumeType: AudioVolumeType): boolean 4038 4039Checks whether a stream is active. This API returns the result synchronously. 4040 4041**System capability**: SystemCapability.Multimedia.Audio.Renderer 4042 4043**Parameters** 4044 4045| Name | Type | Mandatory| Description | 4046| ---------- | ----------------------------------- | ---- | ------------ | 4047| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream types.| 4048 4049**Return value** 4050 4051| Type | Description | 4052| ---------------------- | -------------------------------------------------------- | 4053| boolean | **true**: The stream is active.<br> **false**: The stream is inactive.| 4054 4055**Error codes** 4056 4057For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4058 4059| ID| Error Message| 4060| ------- | --------------------------------------------| 4061| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4062| 6800101 | Parameter verification failed. | 4063 4064**Example** 4065 4066```ts 4067import { BusinessError } from '@kit.BasicServicesKit'; 4068 4069try { 4070 let value: boolean = audioStreamManager.isActiveSync(audio.AudioVolumeType.MEDIA); 4071 console.info(`Indicate that the active status of the stream is obtained ${value}.`); 4072} catch (err) { 4073 let error = err as BusinessError; 4074 console.error(`Failed to obtain the active status of the stream ${error}.`); 4075} 4076``` 4077 4078### getAudioEffectInfoArray<sup>10+</sup> 4079 4080getAudioEffectInfoArray(usage: StreamUsage, callback: AsyncCallback<AudioEffectInfoArray>): void 4081 4082Obtains information about the audio effect mode in use. This API uses an asynchronous callback to return the result. 4083 4084**System capability**: SystemCapability.Multimedia.Audio.Renderer 4085 4086**Parameters** 4087 4088| Name | Type | Mandatory | Description | 4089| -------- | ----------------------------------- | -------- | --------------------------- | 4090| usage | [StreamUsage](#streamusage) | Yes | Audio stream usage. | 4091| 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.| 4092 4093**Error codes** 4094 4095For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4096 4097| ID| Error Message| 4098| ------- | --------------------------------------------| 4099| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4100| 6800101 | Parameter verification failed. Return by callback.| 4101 4102**Example** 4103 4104```ts 4105import { BusinessError } from '@kit.BasicServicesKit'; 4106 4107audioStreamManager.getAudioEffectInfoArray(audio.StreamUsage.STREAM_USAGE_MUSIC, async (err: BusinessError, audioEffectInfoArray: audio.AudioEffectInfoArray) => { 4108 console.info('getAudioEffectInfoArray **** Get Callback Called ****'); 4109 if (err) { 4110 console.error(`getAudioEffectInfoArray :ERROR: ${err}`); 4111 return; 4112 } else { 4113 console.info(`The effect modes are: ${audioEffectInfoArray}`); 4114 } 4115}); 4116``` 4117 4118### getAudioEffectInfoArray<sup>10+</sup> 4119 4120getAudioEffectInfoArray(usage: StreamUsage): Promise<AudioEffectInfoArray> 4121 4122Obtains information about the audio effect mode in use. This API uses a promise to return the result. 4123 4124**System capability**: SystemCapability.Multimedia.Audio.Renderer 4125 4126**Parameters** 4127 4128| Name | Type | Mandatory | Description | 4129| -------- | ----------------------------------- | -------- | --------------------------- | 4130| usage | [StreamUsage](#streamusage) | Yes | Audio stream usage. | 4131 4132**Return value** 4133 4134| Type | Description | 4135| --------------------------------------------------------------------------| --------------------------------------- | 4136| Promise<[AudioEffectInfoArray](#audioeffectinfoarray10)> | Promise used to return the information about the audio effect mode obtained. | 4137 4138**Error codes** 4139 4140For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4141 4142| ID| Error Message| 4143| ------- | --------------------------------------------| 4144| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4145| 6800101 | Parameter verification failed. Return by promise. | 4146 4147**Example** 4148 4149```ts 4150import { BusinessError } from '@kit.BasicServicesKit'; 4151 4152audioStreamManager.getAudioEffectInfoArray(audio.StreamUsage.STREAM_USAGE_MUSIC).then((audioEffectInfoArray: audio.AudioEffectInfoArray) => { 4153 console.info('getAudioEffectInfoArray ######### Get Promise is called ##########'); 4154 console.info(`The effect modes are: ${audioEffectInfoArray}`); 4155}).catch((err: BusinessError) => { 4156 console.error(`getAudioEffectInfoArray :ERROR: ${err}`); 4157}); 4158``` 4159 4160### getAudioEffectInfoArraySync<sup>10+</sup> 4161 4162getAudioEffectInfoArraySync(usage: StreamUsage): AudioEffectInfoArray 4163 4164Obtains information about the audio effect mode in use. This API returns the result synchronously. 4165 4166**System capability**: SystemCapability.Multimedia.Audio.Renderer 4167 4168**Parameters** 4169 4170| Name | Type | Mandatory | Description | 4171| -------- | ----------------------------------- | -------- | --------------------------- | 4172| usage | [StreamUsage](#streamusage) | Yes | Audio stream usage. | 4173 4174**Return value** 4175 4176| Type | Description | 4177| --------------------------------------------------------------------------| --------------------------------------- | 4178| [AudioEffectInfoArray](#audioeffectinfoarray10) | Information about the audio effect mode. | 4179 4180**Error codes** 4181 4182For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4183 4184| ID| Error Message| 4185| ------- | --------------------------------------------| 4186| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4187| 6800101 | Parameter verification failed. | 4188 4189**Example** 4190 4191```ts 4192import { BusinessError } from '@kit.BasicServicesKit'; 4193 4194try { 4195 let audioEffectInfoArray: audio.AudioEffectInfoArray = audioStreamManager.getAudioEffectInfoArraySync(audio.StreamUsage.STREAM_USAGE_MUSIC); 4196 console.info(`The effect modes are: ${audioEffectInfoArray}`); 4197} catch (err) { 4198 let error = err as BusinessError; 4199 console.error(`getAudioEffectInfoArraySync ERROR: ${error}`); 4200} 4201``` 4202 4203## AudioRoutingManager<sup>9+</sup> 4204 4205Implements audio routing management. Before calling any API in **AudioRoutingManager**, you must use [getRoutingManager](#getroutingmanager9) to obtain an **AudioRoutingManager** instance. 4206 4207### getDevices<sup>9+</sup> 4208 4209getDevices(deviceFlag: DeviceFlag, callback: AsyncCallback<AudioDeviceDescriptors>): void 4210 4211Obtains the audio devices with a specific flag. This API uses an asynchronous callback to return the result. 4212 4213**System capability**: SystemCapability.Multimedia.Audio.Device 4214 4215**Parameters** 4216 4217| Name | Type | Mandatory| Description | 4218| ---------- | ------------------------------------------------------------ | ---- | -------------------- | 4219| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag. | 4220| 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.| 4221 4222**Example** 4223 4224```ts 4225import { BusinessError } from '@kit.BasicServicesKit'; 4226 4227audioRoutingManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG, (err: BusinessError, value: audio.AudioDeviceDescriptors) => { 4228 if (err) { 4229 console.error(`Failed to obtain the device list. ${err}`); 4230 return; 4231 } 4232 console.info('Callback invoked to indicate that the device list is obtained.'); 4233}); 4234``` 4235 4236### getDevices<sup>9+</sup> 4237 4238getDevices(deviceFlag: DeviceFlag): Promise<AudioDeviceDescriptors> 4239 4240Obtains the audio devices with a specific flag. This API uses a promise to return the result. 4241 4242**System capability**: SystemCapability.Multimedia.Audio.Device 4243 4244**Parameters** 4245 4246| Name | Type | Mandatory| Description | 4247| ---------- | ------------------------- | ---- | ---------------- | 4248| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag.| 4249 4250**Return value** 4251 4252| Type | Description | 4253| ------------------------------------------------------------ | ------------------------- | 4254| Promise<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Promise used to return the device list.| 4255 4256**Example** 4257 4258```ts 4259audioRoutingManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG).then((data: audio.AudioDeviceDescriptors) => { 4260 console.info('Promise returned to indicate that the device list is obtained.'); 4261}); 4262``` 4263 4264### getDevicesSync<sup>10+</sup> 4265 4266getDevicesSync(deviceFlag: DeviceFlag): AudioDeviceDescriptors 4267 4268Obtains the audio devices with a specific flag. This API returns the result synchronously. 4269 4270**System capability**: SystemCapability.Multimedia.Audio.Device 4271 4272**Parameters** 4273 4274| Name | Type | Mandatory| Description | 4275| ---------- | ------------------------- | ---- | ---------------- | 4276| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag.| 4277 4278**Return value** 4279 4280| Type | Description | 4281| ------------------------------------------------------------ | ------------------------- | 4282| [AudioDeviceDescriptors](#audiodevicedescriptors) | Device list.| 4283 4284**Error codes** 4285 4286For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4287 4288| ID| Error Message| 4289| ------- | --------------------------------------------| 4290| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4291| 6800101 | Parameter verification failed. | 4292 4293**Example** 4294 4295```ts 4296import { BusinessError } from '@kit.BasicServicesKit'; 4297 4298try { 4299 let data: audio.AudioDeviceDescriptors = audioRoutingManager.getDevicesSync(audio.DeviceFlag.OUTPUT_DEVICES_FLAG); 4300 console.info(`Indicate that the device list is obtained ${data}`); 4301} catch (err) { 4302 let error = err as BusinessError; 4303 console.error(`Failed to obtain the device list. ${error}`); 4304} 4305``` 4306 4307### isMicBlockDetectionSupported<sup>13+</sup> 4308 4309isMicBlockDetectionSupported(): Promise<boolean> 4310 4311Checks whether the current device supports microphone blocking detection. This API uses a promise to return the result. 4312 4313**System capability**: SystemCapability.Multimedia.Audio.Device 4314 4315**Return value** 4316 4317| Type | Description | 4318| ---------------------- | ------------------------------------------------------------ | 4319| 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.| 4320 4321**Example** 4322 4323```ts 4324audioRoutingManager.isMicBlockDetectionSupported().then((value: boolean) => { 4325 console.info(`Query whether microphone block detection is supported on current device result is ${value}.`); 4326}); 4327``` 4328 4329### on('micBlockStatusChanged')<sup>13+</sup> 4330 4331on(type: 'micBlockStatusChanged', callback: Callback<DeviceBlockStatusInfo\>): void 4332 4333Subscribes to the microphone blocked status change event. This API uses an asynchronous callback to return the result. 4334 4335Before 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. 4336 4337Currently, this API takes effect only for the microphone on the local device. 4338 4339**System capability**: SystemCapability.Multimedia.Audio.Device 4340 4341**Parameters** 4342 4343| Name | Type | Mandatory| Description | 4344| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- | 4345| type | string | Yes | Event type. The value is fixed at **'micBlockStatusChanged'**.| 4346| callback | Callback<[DeviceBlockStatusInfo](#deviceblockstatusinfo13)\> | Yes | Callback used to return details about whether the microphone is blocked.| 4347 4348**Error codes** 4349 4350For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4351 4352| ID| Error Message| 4353| ------- | --------------------------------------------| 4354| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4355| 6800101 | Parameter verification failed. | 4356 4357**Example** 4358 4359```ts 4360// Before the subscription, check whether the current device supports detection. 4361audioRoutingManager.isMicBlockDetectionSupported().then((value: boolean) => { 4362 console.info(`Query whether microphone block detection is supported on current device result is ${value}.`); 4363 if (value) { 4364 audioRoutingManager.on('micBlockStatusChanged', (micBlockStatusChanged: audio.DeviceBlockStatusInfo) => { 4365 console.info(`block status : ${micBlockStatusChanged.blockStatus} `); 4366 }); 4367 } 4368}); 4369``` 4370 4371### off('micBlockStatusChanged')<sup>13+</sup> 4372 4373off(type: 'micBlockStatusChanged', callback?: Callback<DeviceBlockStatusInfo\>): void 4374 4375Unsubscribes from the microphone blocked status change event. This API uses an asynchronous callback to return the result. 4376 4377**System capability**: SystemCapability.Multimedia.Audio.Device 4378 4379**Parameters** 4380 4381| Name | Type | Mandatory| Description | 4382| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 4383| type | string | Yes | Event type. The value is fixed at **'micBlockStatusChanged'**.| 4384| callback | Callback<[DeviceBlockStatusInfo](#deviceblockstatusinfo13)\> | No | Callback used to return details about whether the microphone is blocked.| 4385 4386**Error codes** 4387 4388For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4389 4390| ID| Error Message| 4391| ------- | --------------------------------------------| 4392| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4393| 6800101 | Parameter verification failed. | 4394 4395**Example** 4396 4397```ts 4398// Cancel all subscriptions to the event. 4399audioRoutingManager.off('micBlockStatusChanged'); 4400 4401// 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. 4402let micBlockStatusCallback = (micBlockStatusChanged: audio.DeviceBlockStatusInfo) => { 4403 console.info(`block status : ${micBlockStatusChanged.blockStatus} `); 4404}; 4405 4406audioRoutingManager.on('micBlockStatusChanged', micBlockStatusCallback); 4407 4408audioRoutingManager.off('micBlockStatusChanged', micBlockStatusCallback); 4409``` 4410 4411### on('deviceChange')<sup>9+</sup> 4412 4413on(type: 'deviceChange', deviceFlag: DeviceFlag, callback: Callback<DeviceChangeAction\>): void 4414 4415Subscribes 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. 4416 4417**System capability**: SystemCapability.Multimedia.Audio.Device 4418 4419**Parameters** 4420 4421| Name | Type | Mandatory| Description | 4422| :------- | :--------------------------------------------------- | :--- |:------------------------| 4423| type | string | Yes | Event type. The value is fixed at **'deviceChange'**.| 4424| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag. | 4425| callback | Callback<[DeviceChangeAction](#devicechangeaction)\> | Yes | Callback used to return the device change details. | 4426 4427**Error codes** 4428 4429For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4430 4431| ID| Error Message| 4432| ------- | --------------------------------------------| 4433| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4434| 6800101 | Parameter verification failed. | 4435 4436**Example** 4437 4438```ts 4439audioRoutingManager.on('deviceChange', audio.DeviceFlag.OUTPUT_DEVICES_FLAG, (deviceChanged: audio.DeviceChangeAction) => { 4440 console.info('device change type : ' + deviceChanged.type); 4441 console.info('device descriptor size : ' + deviceChanged.deviceDescriptors.length); 4442 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceRole); 4443 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceType); 4444}); 4445``` 4446 4447### off('deviceChange')<sup>9+</sup> 4448 4449off(type: 'deviceChange', callback?: Callback<DeviceChangeAction\>): void 4450 4451Unsubscribes from the audio device change event. This API uses an asynchronous callback to return the result. 4452 4453**System capability**: SystemCapability.Multimedia.Audio.Device 4454 4455**Parameters** 4456 4457| Name | Type | Mandatory| Description | 4458| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 4459| type | string | Yes | Event type. The value is fixed at **'deviceChange'**.| 4460| callback | Callback<[DeviceChangeAction](#devicechangeaction)> | No | Callback used to return the device change details.| 4461 4462**Error codes** 4463 4464For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4465 4466| ID| Error Message| 4467| ------- | --------------------------------------------| 4468| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4469| 6800101 | Parameter verification failed. | 4470 4471**Example** 4472 4473```ts 4474// Cancel all subscriptions to the event. 4475audioRoutingManager.off('deviceChange'); 4476 4477// 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. 4478let deviceChangeCallback = (deviceChanged: audio.DeviceChangeAction) => { 4479 console.info('device change type : ' + deviceChanged.type); 4480 console.info('device descriptor size : ' + deviceChanged.deviceDescriptors.length); 4481 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceRole); 4482 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceType); 4483}; 4484 4485audioRoutingManager.on('deviceChange', audio.DeviceFlag.OUTPUT_DEVICES_FLAG, deviceChangeCallback); 4486 4487audioRoutingManager.off('deviceChange', deviceChangeCallback); 4488``` 4489 4490### setCommunicationDevice<sup>9+</sup> 4491 4492setCommunicationDevice(deviceType: CommunicationDeviceType, active: boolean, callback: AsyncCallback<void>): void 4493 4494Sets a communication device to the active state. This API uses an asynchronous callback to return the result. 4495 4496This API will be deprecated in a later version due to function design is changed. You are not advised to use it. 4497 4498You are advised to use the [AVCastPicker component](../../media/avsession/using-switch-call-devices.md) provided by AVSession to switch between call devices. 4499 4500**System capability**: SystemCapability.Multimedia.Audio.Communication 4501 4502**Parameters** 4503 4504| Name | Type | Mandatory| Description | 4505| ---------- | ------------------------------------- | ---- |-------------------------| 4506| deviceType | [CommunicationDeviceType](#communicationdevicetype9) | Yes | Communication device type. | 4507| 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.| 4508| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 4509 4510**Example** 4511 4512```ts 4513import { BusinessError } from '@kit.BasicServicesKit'; 4514 4515audioRoutingManager.setCommunicationDevice(audio.CommunicationDeviceType.SPEAKER, true, (err: BusinessError) => { 4516 if (err) { 4517 console.error(`Failed to set the active status of the device. ${err}`); 4518 return; 4519 } 4520 console.info('Callback invoked to indicate that the device is set to the active status.'); 4521}); 4522``` 4523 4524### getAvailableDevices<sup>12+</sup> 4525 4526getAvailableDevices(deviceUsage: DeviceUsage): AudioDeviceDescriptors 4527 4528Obtains the available audio devices. This API returns the result synchronously. 4529 4530**System capability**: SystemCapability.Multimedia.Audio.Device 4531 4532**Parameters** 4533 4534| Name | Type | Mandatory| Description | 4535| ---------- | ------------------------- | ---- | ---------------- | 4536| deviceUsage| [DeviceUsage](#deviceusage12) | Yes | Usage scenario of the device.| 4537 4538**Return value** 4539 4540| Type | Description | 4541| ------------------------------------------------------------ | ------------------------- | 4542| [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | Device list.| 4543 4544**Error codes** 4545 4546For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4547 4548| ID| Error Message| 4549| ------- | --------------------------------------------| 4550| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4551| 6800101 | Parameter verification failed. | 4552 4553**Example** 4554 4555```ts 4556import { BusinessError } from '@kit.BasicServicesKit'; 4557 4558try { 4559 let data: audio.AudioDeviceDescriptors = audioRoutingManager.getAvailableDevices(audio.DeviceUsage.MEDIA_OUTPUT_DEVICES); 4560 console.info(`Indicate that the device list is obtained ${data}`); 4561} catch (err) { 4562 let error = err as BusinessError; 4563 console.error(`Failed to obtain the device list. ${error}`); 4564} 4565``` 4566 4567### on('availableDeviceChange')<sup>12+</sup> 4568 4569on(type: 'availableDeviceChange', deviceUsage: DeviceUsage, callback: Callback<DeviceChangeAction\>): void 4570 4571Subscribes 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. 4572 4573**System capability**: SystemCapability.Multimedia.Audio.Device 4574 4575**Parameters** 4576 4577| Name | Type | Mandatory| Description | 4578| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- | 4579| type | string | Yes | Event type. The value is fixed at **'availableDeviceChange'**.| 4580| deviceUsage | [DeviceUsage](#deviceusage12) | Yes | Usage scenario of the device. | 4581| callback | Callback<[DeviceChangeAction](js-apis-audio.md#devicechangeaction)\> | Yes | Callback used to return the device change details.| 4582 4583**Error codes** 4584 4585For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4586 4587| ID| Error Message| 4588| ------- | --------------------------------------------| 4589| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4590| 6800101 | Parameter verification failed. | 4591 4592**Example** 4593 4594```ts 4595audioRoutingManager.on('availableDeviceChange', audio.DeviceUsage.MEDIA_OUTPUT_DEVICES, (deviceChanged: audio.DeviceChangeAction) => { 4596 console.info('device change type : ' + deviceChanged.type); 4597 console.info('device descriptor size : ' + deviceChanged.deviceDescriptors.length); 4598 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceRole); 4599 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceType); 4600}); 4601``` 4602 4603### off('availableDeviceChange')<sup>12+</sup> 4604 4605off(type: 'availableDeviceChange', callback?: Callback<DeviceChangeAction\>): void 4606 4607Unsubscribes from the available audio device change event. This API uses an asynchronous callback to return the result. 4608 4609**System capability**: SystemCapability.Multimedia.Audio.Device 4610 4611**Parameters** 4612 4613| Name | Type | Mandatory| Description | 4614| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 4615| type | string | Yes | Event type. The value is fixed at **'availableDeviceChange'**.| 4616| callback | Callback<[DeviceChangeAction](js-apis-audio.md#devicechangeaction)> | No | Callback used to return the available device change details.| 4617 4618**Error codes** 4619 4620For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4621 4622| ID| Error Message| 4623| ------- | --------------------------------------------| 4624| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4625| 6800101 | Parameter verification failed. | 4626 4627**Example** 4628 4629```ts 4630// Cancel all subscriptions to the event. 4631audioRoutingManager.off('availableDeviceChange'); 4632 4633// 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. 4634let availableDeviceChangeCallback = (deviceChanged: audio.DeviceChangeAction) => { 4635 console.info('device change type : ' + deviceChanged.type); 4636 console.info('device descriptor size : ' + deviceChanged.deviceDescriptors.length); 4637 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceRole); 4638 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceType); 4639}; 4640 4641audioRoutingManager.on('availableDeviceChange', audio.DeviceUsage.MEDIA_OUTPUT_DEVICES, availableDeviceChangeCallback); 4642 4643audioRoutingManager.off('availableDeviceChange', availableDeviceChangeCallback); 4644``` 4645 4646### setCommunicationDevice<sup>9+</sup> 4647 4648setCommunicationDevice(deviceType: CommunicationDeviceType, active: boolean): Promise<void> 4649 4650Sets a communication device to the active state. This API uses a promise to return the result. 4651 4652This API will be deprecated in a later version due to function design is changed. You are not advised to use it. 4653 4654You are advised to use the [AVCastPicker component](../../media/avsession/using-switch-call-devices.md) provided by AVSession to switch between call devices. 4655 4656**System capability**: SystemCapability.Multimedia.Audio.Communication 4657 4658**Parameters** 4659 4660| Name | Type | Mandatory| Description | 4661| ---------- | ----------------------------------------------------- | ---- | ------------------ | 4662| deviceType | [CommunicationDeviceType](#communicationdevicetype9) | Yes | Communication device type.| 4663| 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. | 4664 4665**Return value** 4666 4667| Type | Description | 4668| ------------------- | ------------------------------- | 4669| Promise<void> | Promise that returns no value.| 4670 4671**Example** 4672 4673```ts 4674audioRoutingManager.setCommunicationDevice(audio.CommunicationDeviceType.SPEAKER, true).then(() => { 4675 console.info('Promise returned to indicate that the device is set to the active status.'); 4676}); 4677``` 4678 4679### isCommunicationDeviceActive<sup>9+</sup> 4680 4681isCommunicationDeviceActive(deviceType: CommunicationDeviceType, callback: AsyncCallback<boolean>): void 4682 4683Checks whether a communication device is active. This API uses an asynchronous callback to return the result. 4684 4685**System capability**: SystemCapability.Multimedia.Audio.Communication 4686 4687**Parameters** 4688 4689| Name | Type | Mandatory| Description | 4690| ---------- | ---------------------------------------------------- | ---- | ------------------------ | 4691| deviceType | [CommunicationDeviceType](#communicationdevicetype9) | Yes | Communication device type. | 4692| 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.| 4693 4694**Example** 4695 4696```ts 4697import { BusinessError } from '@kit.BasicServicesKit'; 4698 4699audioRoutingManager.isCommunicationDeviceActive(audio.CommunicationDeviceType.SPEAKER, (err: BusinessError, value: boolean) => { 4700 if (err) { 4701 console.error(`Failed to obtain the active status of the device. ${err}`); 4702 return; 4703 } 4704 console.info('Callback invoked to indicate that the active status of the device is obtained.'); 4705}); 4706``` 4707 4708### isCommunicationDeviceActive<sup>9+</sup> 4709 4710isCommunicationDeviceActive(deviceType: CommunicationDeviceType): Promise<boolean> 4711 4712Checks whether a communication device is active. This API uses a promise to return the result. 4713 4714**System capability**: SystemCapability.Multimedia.Audio.Communication 4715 4716**Parameters** 4717 4718| Name | Type | Mandatory| Description | 4719| ---------- | ---------------------------------------------------- | ---- | ------------------ | 4720| deviceType | [CommunicationDeviceType](#communicationdevicetype9) | Yes | Communication device type.| 4721 4722**Return value** 4723 4724| Type | Description | 4725| ---------------------- | ------------------------------- | 4726| 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.| 4727 4728**Example** 4729 4730```ts 4731audioRoutingManager.isCommunicationDeviceActive(audio.CommunicationDeviceType.SPEAKER).then((value: boolean) => { 4732 console.info(`Promise returned to indicate that the active status of the device is obtained ${value}.`); 4733}); 4734``` 4735 4736### isCommunicationDeviceActiveSync<sup>10+</sup> 4737 4738isCommunicationDeviceActiveSync(deviceType: CommunicationDeviceType): boolean 4739 4740Checks whether a communication device is active. This API returns the result synchronously. 4741 4742**System capability**: SystemCapability.Multimedia.Audio.Communication 4743 4744**Parameters** 4745 4746| Name | Type | Mandatory| Description | 4747| ---------- | ---------------------------------------------------- | ---- | ------------------ | 4748| deviceType | [CommunicationDeviceType](#communicationdevicetype9) | Yes | Communication device type.| 4749 4750**Return value** 4751 4752| Type | Description | 4753| ---------------------- | ------------------------------- | 4754| boolean | **true**: The device is active.<br>**false**: The device is inactive.| 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. | 4764 4765**Example** 4766 4767```ts 4768import { BusinessError } from '@kit.BasicServicesKit'; 4769 4770try { 4771 let value: boolean = audioRoutingManager.isCommunicationDeviceActiveSync(audio.CommunicationDeviceType.SPEAKER); 4772 console.info(`Indicate that the active status of the device is obtained ${value}.`); 4773} catch (err) { 4774 let error = err as BusinessError; 4775 console.error(`Failed to obtain the active status of the device ${error}.`); 4776} 4777``` 4778 4779### getPreferOutputDeviceForRendererInfo<sup>10+</sup> 4780 4781getPreferOutputDeviceForRendererInfo(rendererInfo: AudioRendererInfo, callback: AsyncCallback<AudioDeviceDescriptors>): void 4782 4783Obtains the output device with the highest priority based on the audio renderer information. This API uses an asynchronous callback to return the result. 4784 4785**System capability**: SystemCapability.Multimedia.Audio.Device 4786 4787**Parameters** 4788 4789| Name | Type | Mandatory| Description | 4790| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 4791| rendererInfo | [AudioRendererInfo](#audiorendererinfo8) | Yes | Audio renderer information. | 4792| 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.| 4793 4794**Error codes** 4795 4796For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4797 4798| ID| Error Message | 4799| ------- |--------------------------------------------------| 4800| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4801| 6800101 | Parameter verification failed. Return by callback. | 4802| 6800301 | System error. Return by callback. | 4803 4804**Example** 4805```ts 4806import { audio } from '@kit.AudioKit'; 4807import { BusinessError } from '@kit.BasicServicesKit'; 4808 4809let rendererInfo: audio.AudioRendererInfo = { 4810 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, // Audio stream usage type: music. Set this parameter based on the service scenario. 4811 rendererFlags: 0 // AudioRenderer flag. 4812}; 4813 4814async function getPreferOutputDevice() { 4815 audioRoutingManager.getPreferOutputDeviceForRendererInfo(rendererInfo, (err: BusinessError, desc: audio.AudioDeviceDescriptors) => { 4816 if (err) { 4817 console.error(`Result ERROR: ${err}`); 4818 } else { 4819 console.info(`device descriptor: ${desc}`); 4820 } 4821 }); 4822} 4823``` 4824 4825### getPreferOutputDeviceForRendererInfo<sup>10+</sup> 4826getPreferOutputDeviceForRendererInfo(rendererInfo: AudioRendererInfo): Promise<AudioDeviceDescriptors> 4827 4828Obtains the output device with the highest priority based on the audio renderer information. This API uses a promise to return the result. 4829 4830**System capability**: SystemCapability.Multimedia.Audio.Device 4831 4832**Parameters** 4833 4834| Name | Type | Mandatory| Description | 4835| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 4836| rendererInfo | [AudioRendererInfo](#audiorendererinfo8) | Yes | Audio renderer information. | 4837 4838**Return value** 4839 4840| Type | Description | 4841| --------------------- | --------------------------- | 4842| Promise<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Promise used to return the information about the output device with the highest priority.| 4843 4844**Error codes** 4845 4846For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4847 4848| ID| Error Message | 4849| ------- |-------------------------------------------------| 4850| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4851| 6800101 | Parameter verification failed. Return by promise. | 4852| 6800301 | System error. Return by promise. | 4853 4854**Example** 4855 4856```ts 4857import { audio } from '@kit.AudioKit'; 4858import { BusinessError } from '@kit.BasicServicesKit'; 4859 4860let rendererInfo: audio.AudioRendererInfo = { 4861 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, // Audio stream usage type: music. Set this parameter based on the service scenario. 4862 rendererFlags: 0 // AudioRenderer flag. 4863}; 4864 4865async function getPreferOutputDevice() { 4866 audioRoutingManager.getPreferOutputDeviceForRendererInfo(rendererInfo).then((desc: audio.AudioDeviceDescriptors) => { 4867 console.info(`device descriptor: ${desc}`); 4868 }).catch((err: BusinessError) => { 4869 console.error(`Result ERROR: ${err}`); 4870 }) 4871} 4872``` 4873 4874### getPreferredOutputDeviceForRendererInfoSync<sup>10+</sup> 4875getPreferredOutputDeviceForRendererInfoSync(rendererInfo: AudioRendererInfo): AudioDeviceDescriptors 4876 4877Obtains the output device with the highest priority based on the audio renderer information. This API returns the result synchronously. 4878 4879**System capability**: SystemCapability.Multimedia.Audio.Device 4880 4881**Parameters** 4882 4883| Name | Type | Mandatory| Description | 4884| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 4885| rendererInfo | [AudioRendererInfo](#audiorendererinfo8) | Yes | Audio renderer information. | 4886 4887**Return value** 4888 4889| Type | Description | 4890| --------------------- | --------------------------- | 4891| [AudioDeviceDescriptors](#audiodevicedescriptors) | Information about the output device with the highest priority.| 4892 4893**Error codes** 4894 4895For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4896 4897| ID| Error Message | 4898| ------- |--------------------------| 4899| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4900| 6800101 | Parameter verification failed. | 4901 4902**Example** 4903 4904```ts 4905import { audio } from '@kit.AudioKit'; 4906import { BusinessError } from '@kit.BasicServicesKit'; 4907 4908let rendererInfo: audio.AudioRendererInfo = { 4909 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, // Audio stream usage type: music. Set this parameter based on the service scenario. 4910 rendererFlags: 0 // AudioRenderer flag. 4911}; 4912 4913try { 4914 let desc: audio.AudioDeviceDescriptors = audioRoutingManager.getPreferredOutputDeviceForRendererInfoSync(rendererInfo); 4915 console.info(`device descriptor: ${desc}`); 4916} catch (err) { 4917 let error = err as BusinessError; 4918 console.error(`Result ERROR: ${error}`); 4919} 4920``` 4921 4922### on('preferOutputDeviceChangeForRendererInfo')<sup>10+</sup> 4923 4924on(type: 'preferOutputDeviceChangeForRendererInfo', rendererInfo: AudioRendererInfo, callback: Callback<AudioDeviceDescriptors\>): void 4925 4926Subscribes 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. 4927 4928**System capability**: SystemCapability.Multimedia.Audio.Device 4929 4930**Parameters** 4931 4932| Name | Type | Mandatory| Description | 4933| :------- | :--------------------------------------------------- | :--- |:--------------------------------------------------------| 4934| type | string | Yes | Event type. The value is fixed at **'preferOutputDeviceChangeForRendererInfo'**.| 4935| rendererInfo | [AudioRendererInfo](#audiorendererinfo8) | Yes | Audio renderer information. | 4936| callback | Callback<[AudioDeviceDescriptors](#audiodevicedescriptors)\> | Yes | Callback used to return the information about the output device with the highest priority.| 4937 4938**Error codes** 4939 4940For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4941 4942| ID| Error Message| 4943| ------- | --------------------------------------------| 4944| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4945| 6800101 | Parameter verification failed. | 4946 4947**Example** 4948 4949```ts 4950import { audio } from '@kit.AudioKit'; 4951 4952let rendererInfo: audio.AudioRendererInfo = { 4953 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, // Audio stream usage type: music. Set this parameter based on the service scenario. 4954 rendererFlags: 0 // AudioRenderer flag. 4955}; 4956 4957audioRoutingManager.on('preferOutputDeviceChangeForRendererInfo', rendererInfo, (desc: audio.AudioDeviceDescriptors) => { 4958 console.info(`device descriptor: ${desc}`); 4959}); 4960``` 4961 4962### off('preferOutputDeviceChangeForRendererInfo')<sup>10+</sup> 4963 4964off(type: 'preferOutputDeviceChangeForRendererInfo', callback?: Callback<AudioDeviceDescriptors\>): void 4965 4966Unsubscribes from the change of the output device with the highest priority. This API uses an asynchronous callback to return the result. 4967 4968**System capability**: SystemCapability.Multimedia.Audio.Device 4969 4970**Parameters** 4971 4972| Name | Type | Mandatory| Description | 4973| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 4974| type | string | Yes | Event type. The value is fixed at **'preferOutputDeviceChangeForRendererInfo'**.| 4975| callback | Callback<[AudioDeviceDescriptors](#audiodevicedescriptors)> | No | Callback used to return the information about the output device with the highest priority.| 4976 4977**Error codes** 4978 4979For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4980 4981| ID| Error Message| 4982| ------- | --------------------------------------------| 4983| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4984| 6800101 | Parameter verification failed. | 4985 4986**Example** 4987 4988```ts 4989// Cancel all subscriptions to the event. 4990audioRoutingManager.off('preferOutputDeviceChangeForRendererInfo'); 4991 4992// 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. 4993let preferOutputDeviceChangeForRendererInfoCallback = (desc: audio.AudioDeviceDescriptors) => { 4994 console.info(`device descriptor: ${desc}`); 4995}; 4996let rendererInfo: audio.AudioRendererInfo = { 4997 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, // Audio stream usage type: music. Set this parameter based on the service scenario. 4998 rendererFlags: 0 // AudioRenderer flag. 4999}; 5000 5001audioRoutingManager.on('preferOutputDeviceChangeForRendererInfo', rendererInfo, preferOutputDeviceChangeForRendererInfoCallback); 5002 5003audioRoutingManager.off('preferOutputDeviceChangeForRendererInfo', preferOutputDeviceChangeForRendererInfoCallback); 5004``` 5005 5006### getPreferredInputDeviceForCapturerInfo<sup>10+</sup> 5007 5008getPreferredInputDeviceForCapturerInfo(capturerInfo: AudioCapturerInfo, callback: AsyncCallback<AudioDeviceDescriptors>): void 5009 5010Obtains the input device with the highest priority based on the audio capturer information. This API uses an asynchronous callback to return the result. 5011 5012**System capability**: SystemCapability.Multimedia.Audio.Device 5013 5014**Parameters** 5015 5016| Name | Type | Mandatory| Description | 5017| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 5018| capturerInfo | [AudioCapturerInfo](#audiocapturerinfo8) | Yes | Audio capturer information. | 5019| 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.| 5020 5021**Error codes** 5022 5023For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5024 5025| ID| Error Message| 5026| ------- | --------------------------------------------| 5027| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5028| 6800101 | Parameter verification failed. Return by callback.| 5029| 6800301 | System error. Return by callback. | 5030 5031**Example** 5032```ts 5033import { audio } from '@kit.AudioKit'; 5034import { BusinessError } from '@kit.BasicServicesKit'; 5035 5036let capturerInfo: audio.AudioCapturerInfo = { 5037 source: audio.SourceType.SOURCE_TYPE_MIC, // Audio source type: microphone. Set this parameter based on the service scenario. 5038 capturerFlags: 0 // AudioCapturer flag. 5039}; 5040 5041audioRoutingManager.getPreferredInputDeviceForCapturerInfo(capturerInfo, (err: BusinessError, desc: audio.AudioDeviceDescriptors) => { 5042 if (err) { 5043 console.error(`Result ERROR: ${err}`); 5044 } else { 5045 console.info(`device descriptor: ${desc}`); 5046 } 5047}); 5048``` 5049 5050### getPreferredInputDeviceForCapturerInfo<sup>10+</sup> 5051 5052getPreferredInputDeviceForCapturerInfo(capturerInfo: AudioCapturerInfo): Promise<AudioDeviceDescriptors> 5053 5054Obtains the input device with the highest priority based on the audio capturer information. This API uses a promise to return the result. 5055 5056**System capability**: SystemCapability.Multimedia.Audio.Device 5057 5058**Parameters** 5059 5060| Name | Type | Mandatory| Description | 5061| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 5062| capturerInfo | [AudioCapturerInfo](#audiocapturerinfo8) | Yes | Audio capturer information. | 5063 5064**Return value** 5065 5066| Type | Description | 5067| --------------------- | --------------------------- | 5068| Promise<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Promise used to return the information about the input device with the highest priority.| 5069 5070**Error codes** 5071 5072For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5073 5074| ID| Error Message| 5075| ------- | --------------------------------------------| 5076| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5077| 6800101 | Parameter verification failed. Return by promise. | 5078| 6800301 | System error. Return by promise. | 5079 5080**Example** 5081 5082```ts 5083import { audio } from '@kit.AudioKit'; 5084import { BusinessError } from '@kit.BasicServicesKit'; 5085 5086let capturerInfo: audio.AudioCapturerInfo = { 5087 source: audio.SourceType.SOURCE_TYPE_MIC, // Audio source type: microphone. Set this parameter based on the service scenario. 5088 capturerFlags: 0 // AudioCapturer flag. 5089}; 5090 5091audioRoutingManager.getPreferredInputDeviceForCapturerInfo(capturerInfo).then((desc: audio.AudioDeviceDescriptors) => { 5092 console.info(`device descriptor: ${desc}`); 5093}).catch((err: BusinessError) => { 5094 console.error(`Result ERROR: ${err}`); 5095}); 5096``` 5097 5098### getPreferredInputDeviceForCapturerInfoSync<sup>10+</sup> 5099 5100getPreferredInputDeviceForCapturerInfoSync(capturerInfo: AudioCapturerInfo): AudioDeviceDescriptors 5101 5102Obtains the input device with the highest priority based on the audio capturer information. This API returns the result synchronously. 5103 5104**System capability**: SystemCapability.Multimedia.Audio.Device 5105 5106**Parameters** 5107 5108| Name | Type | Mandatory| Description | 5109| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 5110| capturerInfo | [AudioCapturerInfo](#audiocapturerinfo8) | Yes | Audio capturer information. | 5111 5112**Return value** 5113 5114| Type | Description | 5115| --------------------- | --------------------------- | 5116| [AudioDeviceDescriptors](#audiodevicedescriptors) | Information about the input device with the highest priority.| 5117 5118**Error codes** 5119 5120For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5121 5122| ID| Error Message| 5123| ------- | --------------------------------------------| 5124| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5125| 6800101 | Parameter verification failed. | 5126 5127**Example** 5128 5129```ts 5130import { audio } from '@kit.AudioKit'; 5131import { BusinessError } from '@kit.BasicServicesKit'; 5132 5133let capturerInfo: audio.AudioCapturerInfo = { 5134 source: audio.SourceType.SOURCE_TYPE_MIC, // Audio source type: microphone. Set this parameter based on the service scenario. 5135 capturerFlags: 0 // AudioCapturer flag. 5136}; 5137 5138try { 5139 let desc: audio.AudioDeviceDescriptors = audioRoutingManager.getPreferredInputDeviceForCapturerInfoSync(capturerInfo); 5140 console.info(`device descriptor: ${desc}`); 5141} catch (err) { 5142 let error = err as BusinessError; 5143 console.error(`Result ERROR: ${error}`); 5144} 5145``` 5146 5147### on('preferredInputDeviceChangeForCapturerInfo')<sup>10+</sup> 5148 5149on(type: 'preferredInputDeviceChangeForCapturerInfo', capturerInfo: AudioCapturerInfo, callback: Callback<AudioDeviceDescriptors\>): void 5150 5151Subscribes 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. 5152 5153**System capability**: SystemCapability.Multimedia.Audio.Device 5154 5155**Parameters** 5156 5157| Name | Type | Mandatory| Description | 5158| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- | 5159| type | string | Yes | Event type. The value is fixed at **'preferredInputDeviceChangeForCapturerInfo'**.| 5160| capturerInfo | [AudioCapturerInfo](#audiocapturerinfo8) | Yes | Audio capturer information. | 5161| callback | Callback<[AudioDeviceDescriptors](#audiodevicedescriptors)\> | Yes | Callback used to return the information about the input device with the highest priority.| 5162 5163**Error codes** 5164 5165For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5166 5167| ID| Error Message| 5168| ------- | --------------------------------------------| 5169| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5170| 6800101 | Parameter verification failed. | 5171 5172**Example** 5173 5174```ts 5175import { audio } from '@kit.AudioKit'; 5176 5177let capturerInfo: audio.AudioCapturerInfo = { 5178 source: audio.SourceType.SOURCE_TYPE_MIC, // Audio source type: microphone. Set this parameter based on the service scenario. 5179 capturerFlags: 0 // AudioCapturer flag. 5180}; 5181 5182audioRoutingManager.on('preferredInputDeviceChangeForCapturerInfo', capturerInfo, (desc: audio.AudioDeviceDescriptors) => { 5183 console.info(`device descriptor: ${desc}`); 5184}); 5185``` 5186 5187### off('preferredInputDeviceChangeForCapturerInfo')<sup>10+</sup> 5188 5189off(type: 'preferredInputDeviceChangeForCapturerInfo', callback?: Callback<AudioDeviceDescriptors\>): void 5190 5191Unsubscribes from the change of the input device with the highest priority. This API uses an asynchronous callback to return the result. 5192 5193**System capability**: SystemCapability.Multimedia.Audio.Device 5194 5195**Parameters** 5196 5197| Name | Type | Mandatory| Description | 5198| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 5199| type | string | Yes | Event type. The value is fixed at **'preferredInputDeviceChangeForCapturerInfo'**.| 5200| callback | Callback<[AudioDeviceDescriptors](#audiodevicedescriptors)> | No | Callback used to return the information about the input device with the highest priority.| 5201 5202**Error codes** 5203 5204For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5205 5206| ID| Error Message| 5207| ------- | --------------------------------------------| 5208| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5209| 6800101 | Parameter verification failed. | 5210 5211**Example** 5212 5213```ts 5214// Cancel all subscriptions to the event. 5215audioRoutingManager.off('preferredInputDeviceChangeForCapturerInfo'); 5216 5217// 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. 5218let preferredInputDeviceChangeForCapturerInfoCallback = (desc: audio.AudioDeviceDescriptors) => { 5219 console.info(`device descriptor: ${desc}`); 5220}; 5221let capturerInfo: audio.AudioCapturerInfo = { 5222 source: audio.SourceType.SOURCE_TYPE_MIC, // Audio source type: microphone. Set this parameter based on the service scenario. 5223 capturerFlags: 0 // AudioCapturer flag. 5224}; 5225 5226audioRoutingManager.on('preferredInputDeviceChangeForCapturerInfo', capturerInfo, preferredInputDeviceChangeForCapturerInfoCallback); 5227 5228audioRoutingManager.off('preferredInputDeviceChangeForCapturerInfo', preferredInputDeviceChangeForCapturerInfoCallback); 5229``` 5230 5231## AudioSessionManager<sup>12+</sup> 5232 5233Manages audio sessions. Before calling an API in **AudioSessionManager**, you must use [getSessionManager](#getsessionmanager12) to obtain an **AudioSessionManager** instance. 5234 5235### activateAudioSession<sup>12+</sup> 5236 5237activateAudioSession(strategy: AudioSessionStrategy): Promise\<void> 5238 5239Activates an audio session. This API uses a promise to return the result. 5240 5241**System capability**: SystemCapability.Multimedia.Audio.Core 5242 5243**Parameters** 5244 5245| Name| Type | Mandatory| Description | 5246| ------ |-------------------------------------------------| ---- | ------------ | 5247| strategy | [AudioSessionStrategy](#audiosessionstrategy12) | Yes | Audio session strategy.| 5248 5249**Return value** 5250 5251| Type | Description | 5252| -------------- | ------------------------- | 5253| Promise\<void> | Promise that returns no value.| 5254 5255**Error codes** 5256 5257For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5258 5259| ID| Error Message| 5260| ------- | ---------------------------------------------| 5261| 401 | Parameter error. Possible causes: 1.Mandatory parameters unspecified. 2.Incorrect parameter types. | 5262| 6800101 | Parameter verification failed.| 5263| 6800301 | System error. Returned by promise. | 5264 5265**Example** 5266 5267```ts 5268import { BusinessError } from '@kit.BasicServicesKit'; 5269 5270let strategy: audio.AudioSessionStrategy = { 5271 concurrencyMode: audio.AudioConcurrencyMode.CONCURRENCY_MIX_WITH_OTHERS 5272}; 5273 5274audioSessionManager.activateAudioSession(strategy).then(() => { 5275 console.info('activateAudioSession SUCCESS'); 5276}).catch((err: BusinessError) => { 5277 console.error(`ERROR: ${err}`); 5278}); 5279``` 5280 5281### deactivateAudioSession<sup>12+</sup> 5282 5283deactivateAudioSession(): Promise\<void> 5284 5285Deactivates this audio session. This API uses a promise to return the result. 5286 5287**System capability**: SystemCapability.Multimedia.Audio.Core 5288 5289**Return value** 5290 5291| Type | Description | 5292| -------------- | ------------------------- | 5293| Promise\<void> | Promise that returns no value.| 5294 5295**Error codes** 5296 5297For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5298 5299| ID| Error Message| 5300| ------- | ---------------------------------------------| 5301| 6800301 | System error. Returned by promise. | 5302 5303**Example** 5304 5305```ts 5306import { BusinessError } from '@kit.BasicServicesKit'; 5307 5308audioSessionManager.deactivateAudioSession().then(() => { 5309 console.info('deactivateAudioSession SUCCESS'); 5310}).catch((err: BusinessError) => { 5311 console.error(`ERROR: ${err}`); 5312}); 5313``` 5314 5315### isAudioSessionActivated<sup>12+</sup> 5316 5317isAudioSessionActivated(): boolean 5318 5319Checks whether this audio session is activated. 5320 5321**System capability**: SystemCapability.Multimedia.Audio.Core 5322 5323**Return value** 5324 5325| Type | Description | 5326| ------------------------------------------------- |---------------------------------------| 5327| boolean | Returns **true** if the audio session is activated; returns **false** otherwise.| 5328 5329**Example** 5330 5331```ts 5332let isActivated = audioSessionManager.isAudioSessionActivated(); 5333``` 5334 5335### on('audioSessionDeactivated')<sup>12+</sup> 5336 5337on(type: 'audioSessionDeactivated', callback: Callback\<AudioSessionDeactivatedEvent>): void 5338 5339Subscribes 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. 5340 5341**System capability**: SystemCapability.Multimedia.Audio.Core 5342 5343**Parameters** 5344 5345| Name | Type | Mandatory| Description | 5346| -------- |---------------------------------------------------------------------------| ---- | ------------------------------------------------------------ | 5347| type | string | Yes | Event type. The value is fixed at **'audioSessionDeactivated'**.| 5348| callback | Callback<[AudioSessionDeactivatedEvent](#audiosessiondeactivatedevent12)> | Yes | Callback used to return the reason why the audio session is deactivated.| 5349 5350**Error codes** 5351 5352For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5353 5354| ID| Error Message| 5355| ------- | --------------------------------------------| 5356| 401 | Parameter error. Possible causes: 1.Mandatory parameters unspecified. 2.Incorrect parameter types. | 5357| 6800101 | Parameter verification failed. | 5358 5359**Example** 5360 5361```ts 5362audioSessionManager.on('audioSessionDeactivated', (audioSessionDeactivatedEvent: audio.AudioSessionDeactivatedEvent) => { 5363 console.info(`reason of audioSessionDeactivated: ${audioSessionDeactivatedEvent.reason} `); 5364}); 5365``` 5366 5367### off('audioSessionDeactivated')<sup>12+</sup> 5368 5369off(type: 'audioSessionDeactivated', callback?: Callback\<AudioSessionDeactivatedEvent>): void 5370 5371Unsubscribes from the audio session deactivation event. This API uses an asynchronous callback to return the result. 5372 5373**System capability**: SystemCapability.Multimedia.Audio.Core 5374 5375**Parameters** 5376 5377| Name | Type | Mandatory| Description | 5378| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 5379| type | string | Yes | Event type. The value is fixed at **'audioSessionDeactivated'**.| 5380| callback |Callback<[AudioSessionDeactivatedEvent](#audiosessiondeactivatedevent12)> | No | Callback used to return the reason why the audio session is deactivated.| 5381 5382**Error codes** 5383 5384For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5385 5386| ID| Error Message| 5387| ------- | --------------------------------------------| 5388| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5389| 6800101 | Parameter verification failed. | 5390 5391**Example** 5392 5393```ts 5394// Cancel all subscriptions to the event. 5395audioSessionManager.off('audioSessionDeactivated'); 5396 5397// 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. 5398let audioSessionDeactivatedCallback = (audioSessionDeactivatedEvent: audio.AudioSessionDeactivatedEvent) => { 5399 console.info(`reason of audioSessionDeactivated: ${audioSessionDeactivatedEvent.reason} `); 5400}; 5401 5402audioSessionManager.on('audioSessionDeactivated', audioSessionDeactivatedCallback); 5403 5404audioSessionManager.off('audioSessionDeactivated', audioSessionDeactivatedCallback); 5405``` 5406 5407## AudioRendererChangeInfoArray<sup>9+</sup> 5408 5409type AudioRendererChangeInfoArray = Array<Readonly<AudioRendererChangeInfo>> 5410 5411Defines an **AudioRenderChangeInfo** array, which is read-only. 5412 5413**System capability**: SystemCapability.Multimedia.Audio.Renderer 5414 5415| Type | Description | 5416|---------|---------------------------------------------------------------| 5417| Array<Readonly<AudioRendererChangeInfo>> | Defines an [AudioRenderChangeInfo](#audiorendererchangeinfo9) array, which is read-only.| 5418 5419## AudioRendererChangeInfo<sup>9+</sup> 5420 5421Describes the audio renderer change event. 5422 5423**System capability**: SystemCapability.Multimedia.Audio.Renderer 5424 5425| Name | Type | Readable| Writable| Description | 5426| -------------------| ----------------------------------------- | ---- | ---- | ---------------------------- | 5427| streamId | number | Yes | No | Unique ID of an audio stream. | 5428| rendererInfo | [AudioRendererInfo](#audiorendererinfo8) | Yes | No | Audio renderer information. | 5429| deviceDescriptors | [AudioDeviceDescriptors](#audiodevicedescriptors) | Yes | No | Audio device description.| 5430 5431**Example** 5432 5433```ts 5434import { audio } from '@kit.AudioKit'; 5435 5436const audioManager = audio.getAudioManager(); 5437let audioStreamManager = audioManager.getStreamManager(); 5438 5439audioStreamManager.on('audioRendererChange', (AudioRendererChangeInfoArray) => { 5440 for (let i = 0; i < AudioRendererChangeInfoArray.length; i++) { 5441 console.info(`## RendererChange on is called for ${i} ##`); 5442 console.info(`StreamId for ${i} is: ${AudioRendererChangeInfoArray[i].streamId}`); 5443 console.info(`Content for ${i} is: ${AudioRendererChangeInfoArray[i].rendererInfo.content}`); 5444 console.info(`Stream for ${i} is: ${AudioRendererChangeInfoArray[i].rendererInfo.usage}`); 5445 console.info(`Flag ${i} is: ${AudioRendererChangeInfoArray[i].rendererInfo.rendererFlags}`); 5446 let devDescriptor = AudioRendererChangeInfoArray[i].deviceDescriptors; 5447 for (let j = 0; j < AudioRendererChangeInfoArray[i].deviceDescriptors.length; j++) { 5448 console.info(`Id: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].id}`); 5449 console.info(`Type: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].deviceType}`); 5450 console.info(`Role: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].deviceRole}`); 5451 console.info(`Name: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].name}`); 5452 console.info(`Addr: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].address}`); 5453 console.info(`SR: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].sampleRates[0]}`); 5454 console.info(`C ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].channelCounts[0]}`); 5455 console.info(`CM: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].channelMasks[0]}`); 5456 } 5457 } 5458}); 5459``` 5460 5461 5462## AudioCapturerChangeInfoArray<sup>9+</sup> 5463 5464type AudioCapturerChangeInfoArray = Array<Readonly<AudioCapturerChangeInfo>> 5465 5466Defines an **AudioCapturerChangeInfo** array, which is read-only. 5467 5468**System capability**: SystemCapability.Multimedia.Audio.Capturer 5469 5470| Type | Description | 5471|---------|-----------------------------------------------------------------| 5472| Array<Readonly<AudioCapturerChangeInfo>> | An [AudioCapturerChangeInfo](#audiocapturerchangeinfo9) array, which is read-only.| 5473 5474## AudioCapturerChangeInfo<sup>9+</sup> 5475 5476Describes the audio capturer change event. 5477 5478**System capability**: SystemCapability.Multimedia.Audio.Capturer 5479 5480| Name | Type | Readable| Writable| Description | 5481| -------------------| ----------------------------------------- | ---- | ---- | ---------------------------- | 5482| streamId | number | Yes | No | Unique ID of an audio stream. | 5483| capturerInfo | [AudioCapturerInfo](#audiocapturerinfo8) | Yes | No | Audio capturer information. | 5484| deviceDescriptors | [AudioDeviceDescriptors](#audiodevicedescriptors) | Yes | No | Audio device description.| 5485| 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.| 5486 5487**Example** 5488 5489```ts 5490import { audio } from '@kit.AudioKit'; 5491 5492const audioManager = audio.getAudioManager(); 5493let audioStreamManager = audioManager.getStreamManager(); 5494 5495audioStreamManager.on('audioCapturerChange', (AudioCapturerChangeInfoArray) => { 5496 for (let i = 0; i < AudioCapturerChangeInfoArray.length; i++) { 5497 console.info(`## CapChange on is called for element ${i} ##`); 5498 console.info(`StrId for ${i} is: ${AudioCapturerChangeInfoArray[i].streamId}`); 5499 console.info(`Src for ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.source}`); 5500 console.info(`Flag ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.capturerFlags}`); 5501 let devDescriptor = AudioCapturerChangeInfoArray[i].deviceDescriptors; 5502 for (let j = 0; j < AudioCapturerChangeInfoArray[i].deviceDescriptors.length; j++) { 5503 console.info(`Id: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].id}`); 5504 console.info(`Type: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceType}`); 5505 console.info(`Role: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceRole}`); 5506 console.info(`Name: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].name}`); 5507 console.info(`Addr: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].address}`); 5508 console.info(`SR: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].sampleRates[0]}`); 5509 console.info(`C ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelCounts[0]}`); 5510 console.info(`CM ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelMasks[0]}`); 5511 } 5512 } 5513}); 5514``` 5515 5516## AudioEffectInfoArray<sup>10+</sup> 5517 5518type AudioEffectInfoArray = Array<Readonly<AudioEffectMode>> 5519 5520Defines 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. 5521 5522**System capability**: SystemCapability.Multimedia.Audio.Renderer 5523 5524| Type | Description | 5525|---------|---------------------------------------------------------------| 5526| 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.| 5527 5528## AudioDeviceDescriptors 5529 5530type AudioDeviceDescriptors = Array<Readonly<AudioDeviceDescriptor>> 5531 5532Defines an [AudioDeviceDescriptor](#audiodevicedescriptor) array, which is read-only. 5533 5534**Atomic service API**: This API can be used in atomic services since API version 12. 5535 5536**System capability**: SystemCapability.Multimedia.Audio.Device 5537 5538| Type | Description | 5539|---------|---------------------------------------------------------------| 5540| Array<Readonly<AudioDeviceDescriptor>> | Defines an [AudioDeviceDescriptor](#audiodevicedescriptor) array, which is read-only.| 5541 5542## AudioDeviceDescriptor 5543 5544Describes an audio device. 5545 5546**Atomic service API**: This API can be used in atomic services since API version 12. 5547 5548| Name | Type | Readable| Writable| Description | 5549| ----------------------------- | -------------------------- | ---- | ---- | ---------- | 5550| deviceRole | [DeviceRole](#devicerole) | Yes | No | Device role.<br> **System capability**: SystemCapability.Multimedia.Audio.Device| 5551| deviceType | [DeviceType](#devicetype) | Yes | No | Device type.<br> **System capability**: SystemCapability.Multimedia.Audio.Device| 5552| id<sup>9+</sup> | number | Yes | No | Device ID, which is unique.<br> **System capability**: SystemCapability.Multimedia.Audio.Device| 5553| 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| 5554| 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| 5555| sampleRates<sup>9+</sup> | Array<number> | Yes | No | Supported sampling rates.<br> **System capability**: SystemCapability.Multimedia.Audio.Device| 5556| channelCounts<sup>9+</sup> | Array<number> | Yes | No | Number of channels supported.<br> **System capability**: SystemCapability.Multimedia.Audio.Device| 5557| channelMasks<sup>9+</sup> | Array<number> | Yes | No | Supported channel masks.<br> **System capability**: SystemCapability.Multimedia.Audio.Device| 5558| displayName<sup>10+</sup> | string | Yes | No | Display name of the device.<br> **System capability**: SystemCapability.Multimedia.Audio.Device| 5559| encodingTypes<sup>11+</sup> | Array<[AudioEncodingType](#audioencodingtype8)> | Yes | No | Supported encoding types.<br> **System capability**: SystemCapability.Multimedia.Audio.Core| 5560 5561**Example** 5562 5563```ts 5564import { audio } from '@kit.AudioKit'; 5565 5566function displayDeviceProp(value: audio.AudioDeviceDescriptor) { 5567 deviceRoleValue = value.deviceRole; 5568 deviceTypeValue = value.deviceType; 5569} 5570 5571let deviceRoleValue: audio.DeviceRole | undefined = undefined; 5572let deviceTypeValue: audio.DeviceType | undefined = undefined; 5573audio.getAudioManager().getRoutingManager().getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG).then((value: audio.AudioDeviceDescriptors) => { 5574 console.info('AudioFrameworkTest: Promise: getDevices OUTPUT_DEVICES_FLAG'); 5575 value.forEach(displayDeviceProp); 5576 if (deviceTypeValue != undefined && deviceRoleValue != undefined){ 5577 console.info('AudioFrameworkTest: Promise: getDevices : OUTPUT_DEVICES_FLAG : PASS'); 5578 } else { 5579 console.error('AudioFrameworkTest: Promise: getDevices : OUTPUT_DEVICES_FLAG : FAIL'); 5580 } 5581}); 5582``` 5583## AudioDataCallbackResult<sup>12+</sup> 5584 5585Enumerates the audio data callback results. 5586 5587**System capability**: SystemCapability.Multimedia.Audio.Core 5588 5589| Name | Value | Description | 5590| ---------------------| --------| ----------------- | 5591| INVALID | -1 | The callback data is invalid. | 5592| VALID | 0 | The callback data is valid. | 5593 5594## AudioRendererWriteDataCallback<sup>12+</sup> 5595 5596type AudioRendererWriteDataCallback = (data: ArrayBuffer) => AudioDataCallbackResult | void 5597 5598Defines 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. 5599 5600**System capability**: SystemCapability.Multimedia.Audio.Renderer 5601 5602**Parameters** 5603 5604| Name | Type |Mandatory | Description | 5605| :--------------| :--------| :----- | :------------ | 5606| data | ArrayBuffer | Yes| Data to be written to the buffer.| 5607 5608**Return value** 5609 5610| Type | Description | 5611|--------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------| 5612| [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.| 5613 5614## AudioRenderer<sup>8+</sup> 5615 5616Provides APIs for audio rendering. Before calling any API in **AudioRenderer**, you must use [createAudioRenderer](#audiocreateaudiorenderer8) to create an **AudioRenderer** instance. 5617 5618### Attributes 5619 5620**System capability**: SystemCapability.Multimedia.Audio.Renderer 5621 5622| Name | Type | Readable| Writable| Description | 5623| ----- | -------------------------- | ---- | ---- | ------------------ | 5624| state<sup>8+</sup> | [AudioState](#audiostate8) | Yes | No | Audio renderer state.| 5625 5626**Example** 5627 5628```ts 5629import { audio } from '@kit.AudioKit'; 5630 5631let state: audio.AudioState = audioRenderer.state; 5632``` 5633 5634### getRendererInfo<sup>8+</sup> 5635 5636getRendererInfo(callback: AsyncCallback<AudioRendererInfo\>): void 5637 5638Obtains the renderer information of this **AudioRenderer** instance. This API uses an asynchronous callback to return the result. 5639 5640**System capability**: SystemCapability.Multimedia.Audio.Renderer 5641 5642**Parameters** 5643 5644| Name | Type | Mandatory| Description | 5645| :------- | :------------------------------------------------------- | :--- | :--------------------- | 5646| 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.| 5647 5648**Example** 5649 5650```ts 5651import { BusinessError } from '@kit.BasicServicesKit'; 5652 5653audioRenderer.getRendererInfo((err: BusinessError, rendererInfo: audio.AudioRendererInfo) => { 5654 console.info('Renderer GetRendererInfo:'); 5655 console.info(`Renderer content: ${rendererInfo.content}`); 5656 console.info(`Renderer usage: ${rendererInfo.usage}`); 5657 console.info(`Renderer flags: ${rendererInfo.rendererFlags}`); 5658}); 5659``` 5660 5661### getRendererInfo<sup>8+</sup> 5662 5663getRendererInfo(): Promise<AudioRendererInfo\> 5664 5665Obtains the renderer information of this **AudioRenderer** instance. This API uses a promise to return the result. 5666 5667**System capability**: SystemCapability.Multimedia.Audio.Renderer 5668 5669**Return value** 5670 5671| Type | Description | 5672| -------------------------------------------------- | ------------------------------- | 5673| Promise<[AudioRendererInfo](#audiorendererinfo8)\> | Promise used to return the renderer information.| 5674 5675**Example** 5676 5677```ts 5678import { BusinessError } from '@kit.BasicServicesKit'; 5679 5680audioRenderer.getRendererInfo().then((rendererInfo: audio.AudioRendererInfo) => { 5681 console.info('Renderer GetRendererInfo:'); 5682 console.info(`Renderer content: ${rendererInfo.content}`); 5683 console.info(`Renderer usage: ${rendererInfo.usage}`); 5684 console.info(`Renderer flags: ${rendererInfo.rendererFlags}`) 5685}).catch((err: BusinessError) => { 5686 console.error(`AudioFrameworkRenderLog: RendererInfo :ERROR: ${err}`); 5687}); 5688``` 5689 5690### getRendererInfoSync<sup>10+</sup> 5691 5692getRendererInfoSync(): AudioRendererInfo 5693 5694Obtains the renderer information of this **AudioRenderer** instance. This API returns the result synchronously. 5695 5696**System capability**: SystemCapability.Multimedia.Audio.Renderer 5697 5698**Return value** 5699 5700| Type | Description | 5701| -------------------------------------------------- | ------------------------------- | 5702| [AudioRendererInfo](#audiorendererinfo8) | Audio renderer information.| 5703 5704**Example** 5705 5706```ts 5707import { BusinessError } from '@kit.BasicServicesKit'; 5708 5709try { 5710 let rendererInfo: audio.AudioRendererInfo = audioRenderer.getRendererInfoSync(); 5711 console.info(`Renderer content: ${rendererInfo.content}`); 5712 console.info(`Renderer usage: ${rendererInfo.usage}`); 5713 console.info(`Renderer flags: ${rendererInfo.rendererFlags}`) 5714} catch (err) { 5715 let error = err as BusinessError; 5716 console.error(`AudioFrameworkRenderLog: RendererInfo :ERROR: ${error}`); 5717} 5718``` 5719 5720### getStreamInfo<sup>8+</sup> 5721 5722getStreamInfo(callback: AsyncCallback<AudioStreamInfo\>): void 5723 5724Obtains the stream information of this **AudioRenderer** instance. This API uses an asynchronous callback to return the result. 5725 5726**System capability**: SystemCapability.Multimedia.Audio.Renderer 5727 5728**Parameters** 5729 5730| Name | Type | Mandatory| Description | 5731| :------- | :--------------------------------------------------- | :--- | :------------------- | 5732| 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.| 5733 5734**Example** 5735 5736```ts 5737import { BusinessError } from '@kit.BasicServicesKit'; 5738 5739audioRenderer.getStreamInfo((err: BusinessError, streamInfo: audio.AudioStreamInfo) => { 5740 console.info('Renderer GetStreamInfo:'); 5741 console.info(`Renderer sampling rate: ${streamInfo.samplingRate}`); 5742 console.info(`Renderer channel: ${streamInfo.channels}`); 5743 console.info(`Renderer format: ${streamInfo.sampleFormat}`); 5744 console.info(`Renderer encoding type: ${streamInfo.encodingType}`); 5745}); 5746``` 5747 5748### getStreamInfo<sup>8+</sup> 5749 5750getStreamInfo(): Promise<AudioStreamInfo\> 5751 5752Obtains the stream information of this **AudioRenderer** instance. This API uses a promise to return the result. 5753 5754**System capability**: SystemCapability.Multimedia.Audio.Renderer 5755 5756**Return value** 5757 5758| Type | Description | 5759| :--------------------------------------------- | :--------------------- | 5760| Promise<[AudioStreamInfo](#audiostreaminfo8)\> | Promise used to return the stream information.| 5761 5762**Example** 5763 5764```ts 5765import { BusinessError } from '@kit.BasicServicesKit'; 5766 5767audioRenderer.getStreamInfo().then((streamInfo: audio.AudioStreamInfo) => { 5768 console.info('Renderer GetStreamInfo:'); 5769 console.info(`Renderer sampling rate: ${streamInfo.samplingRate}`); 5770 console.info(`Renderer channel: ${streamInfo.channels}`); 5771 console.info(`Renderer format: ${streamInfo.sampleFormat}`); 5772 console.info(`Renderer encoding type: ${streamInfo.encodingType}`); 5773}).catch((err: BusinessError) => { 5774 console.error(`ERROR: ${err}`); 5775}); 5776``` 5777 5778### getStreamInfoSync<sup>10+</sup> 5779 5780getStreamInfoSync(): AudioStreamInfo 5781 5782Obtains the stream information of this **AudioRenderer** instance. This API returns the result synchronously. 5783 5784**System capability**: SystemCapability.Multimedia.Audio.Renderer 5785 5786**Return value** 5787 5788| Type | Description | 5789| :--------------------------------------------- | :--------------------- | 5790| [AudioStreamInfo](#audiostreaminfo8) | Stream information.| 5791 5792**Example** 5793 5794```ts 5795import { BusinessError } from '@kit.BasicServicesKit'; 5796 5797try { 5798 let streamInfo: audio.AudioStreamInfo = audioRenderer.getStreamInfoSync(); 5799 console.info(`Renderer sampling rate: ${streamInfo.samplingRate}`); 5800 console.info(`Renderer channel: ${streamInfo.channels}`); 5801 console.info(`Renderer format: ${streamInfo.sampleFormat}`); 5802 console.info(`Renderer encoding type: ${streamInfo.encodingType}`); 5803} catch (err) { 5804 let error = err as BusinessError; 5805 console.error(`ERROR: ${error}`); 5806} 5807``` 5808 5809### getAudioStreamId<sup>9+</sup> 5810 5811getAudioStreamId(callback: AsyncCallback<number\>): void 5812 5813Obtains the stream ID of this **AudioRenderer** instance. This API uses an asynchronous callback to return the result. 5814 5815**System capability**: SystemCapability.Multimedia.Audio.Renderer 5816 5817**Parameters** 5818 5819| Name | Type | Mandatory| Description | 5820| :------- | :--------------------------------------------------- | :--- | :------------------- | 5821| 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.| 5822 5823**Example** 5824 5825```ts 5826import { BusinessError } from '@kit.BasicServicesKit'; 5827 5828audioRenderer.getAudioStreamId((err: BusinessError, streamId: number) => { 5829 console.info(`Renderer GetStreamId: ${streamId}`); 5830}); 5831``` 5832 5833### getAudioStreamId<sup>9+</sup> 5834 5835getAudioStreamId(): Promise<number\> 5836 5837Obtains the stream ID of this **AudioRenderer** instance. This API uses a promise to return the result. 5838 5839**System capability**: SystemCapability.Multimedia.Audio.Renderer 5840 5841**Return value** 5842 5843| Type | Description | 5844| :--------------------------------------------- | :--------------------- | 5845| Promise<number\> | Promise used to return the stream ID.| 5846 5847**Example** 5848 5849```ts 5850import { BusinessError } from '@kit.BasicServicesKit'; 5851 5852audioRenderer.getAudioStreamId().then((streamId: number) => { 5853 console.info(`Renderer getAudioStreamId: ${streamId}`); 5854}).catch((err: BusinessError) => { 5855 console.error(`ERROR: ${err}`); 5856}); 5857``` 5858 5859### getAudioStreamIdSync<sup>10+</sup> 5860 5861getAudioStreamIdSync(): number 5862 5863Obtains the stream ID of this **AudioRenderer** instance. This API returns the result synchronously. 5864 5865**System capability**: SystemCapability.Multimedia.Audio.Renderer 5866 5867**Return value** 5868 5869| Type | Description | 5870| :--------------------------------------------- | :--------------------- | 5871| number | Stream ID.| 5872 5873**Example** 5874 5875```ts 5876import { BusinessError } from '@kit.BasicServicesKit'; 5877 5878try { 5879 let streamId: number = audioRenderer.getAudioStreamIdSync(); 5880 console.info(`Renderer getAudioStreamIdSync: ${streamId}`); 5881} catch (err) { 5882 let error = err as BusinessError; 5883 console.error(`ERROR: ${error}`); 5884} 5885``` 5886 5887### setAudioEffectMode<sup>10+</sup> 5888 5889setAudioEffectMode(mode: AudioEffectMode, callback: AsyncCallback\<void>): void 5890 5891Sets an audio effect mode. This API uses an asynchronous callback 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| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 5901 5902**Error codes** 5903 5904For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5905 5906| ID| Error Message| 5907| ------- | ----------------------------------------------| 5908| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5909| 6800101 | Parameter verification failed. Return by callback. | 5910 5911**Example** 5912 5913```ts 5914import { BusinessError } from '@kit.BasicServicesKit'; 5915 5916audioRenderer.setAudioEffectMode(audio.AudioEffectMode.EFFECT_DEFAULT, (err: BusinessError) => { 5917 if (err) { 5918 console.error('Failed to set params'); 5919 } else { 5920 console.info('Callback invoked to indicate a successful audio effect mode setting.'); 5921 } 5922}); 5923``` 5924 5925### setAudioEffectMode<sup>10+</sup> 5926 5927setAudioEffectMode(mode: AudioEffectMode): Promise\<void> 5928 5929Sets an audio effect mode. This API uses a promise to return the result. 5930 5931**System capability**: SystemCapability.Multimedia.Audio.Renderer 5932 5933**Parameters** 5934 5935| Name| Type | Mandatory| Description | 5936| ------ | ---------------------------------------- | ---- | ------------ | 5937| mode | [AudioEffectMode](#audioeffectmode10) | Yes | Audio effect mode to set.| 5938 5939**Return value** 5940 5941| Type | Description | 5942| -------------- | ------------------------- | 5943| Promise\<void> | Promise that returns no value.| 5944 5945**Error codes** 5946 5947For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5948 5949| ID| Error Message| 5950| ------- | ---------------------------------------------| 5951| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5952| 6800101 | Parameter verification failed. Return by promise. | 5953 5954**Example** 5955 5956```ts 5957import { BusinessError } from '@kit.BasicServicesKit'; 5958 5959audioRenderer.setAudioEffectMode(audio.AudioEffectMode.EFFECT_DEFAULT).then(() => { 5960 console.info('setAudioEffectMode SUCCESS'); 5961}).catch((err: BusinessError) => { 5962 console.error(`ERROR: ${err}`); 5963}); 5964``` 5965 5966### getAudioEffectMode<sup>10+</sup> 5967 5968getAudioEffectMode(callback: AsyncCallback\<AudioEffectMode>): void 5969 5970Obtains the audio effect mode in use. This API uses an asynchronous callback to return the result. 5971 5972**System capability**: SystemCapability.Multimedia.Audio.Renderer 5973 5974**Parameters** 5975 5976| Name | Type | Mandatory| Description | 5977| -------- | ------------------------------------------------------- | ---- | ------------------ | 5978| 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.| 5979 5980**Example** 5981 5982```ts 5983import { BusinessError } from '@kit.BasicServicesKit'; 5984 5985audioRenderer.getAudioEffectMode((err: BusinessError, effectMode: audio.AudioEffectMode) => { 5986 if (err) { 5987 console.error('Failed to get params'); 5988 } else { 5989 console.info(`getAudioEffectMode: ${effectMode}`); 5990 } 5991}); 5992``` 5993 5994### getAudioEffectMode<sup>10+</sup> 5995 5996getAudioEffectMode(): Promise\<AudioEffectMode> 5997 5998Obtains the audio effect mode in use. This API uses a promise to return the result. 5999 6000**System capability**: SystemCapability.Multimedia.Audio.Renderer 6001 6002**Return value** 6003 6004| Type | Description | 6005| ------------------------------------------------- | ------------------------- | 6006| Promise<[AudioEffectMode](#audioeffectmode10)> | Promise used to return the audio effect mode.| 6007 6008**Example** 6009 6010```ts 6011import { BusinessError } from '@kit.BasicServicesKit'; 6012 6013audioRenderer.getAudioEffectMode().then((effectMode: audio.AudioEffectMode) => { 6014 console.info(`getAudioEffectMode: ${effectMode}`); 6015}).catch((err: BusinessError) => { 6016 console.error(`ERROR: ${err}`); 6017}); 6018``` 6019 6020### start<sup>8+</sup> 6021 6022start(callback: AsyncCallback<void\>): void 6023 6024Starts the renderer. This API uses an asynchronous callback to return the result. 6025 6026**System capability**: SystemCapability.Multimedia.Audio.Renderer 6027 6028**Parameters** 6029 6030| Name | Type | Mandatory| Description | 6031| -------- | -------------------- | ---- | ---------- | 6032| 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.| 6033 6034**Example** 6035 6036```ts 6037import { BusinessError } from '@kit.BasicServicesKit'; 6038 6039audioRenderer.start((err: BusinessError) => { 6040 if (err) { 6041 console.error('Renderer start failed.'); 6042 } else { 6043 console.info('Renderer start success.'); 6044 } 6045}); 6046``` 6047 6048### start<sup>8+</sup> 6049 6050start(): Promise<void\> 6051 6052Starts the renderer. This API uses a promise to return the result. 6053 6054**System capability**: SystemCapability.Multimedia.Audio.Renderer 6055 6056**Return value** 6057 6058| Type | Description | 6059| -------------- | ------------------------- | 6060| 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.| 6061 6062**Example** 6063 6064```ts 6065import { BusinessError } from '@kit.BasicServicesKit'; 6066 6067audioRenderer.start().then(() => { 6068 console.info('Renderer started'); 6069}).catch((err: BusinessError) => { 6070 console.error(`ERROR: ${err}`); 6071}); 6072``` 6073 6074### pause<sup>8+</sup> 6075 6076pause(callback: AsyncCallback\<void>): void 6077 6078Pauses rendering. This API uses an asynchronous callback to return the result. 6079 6080**System capability**: SystemCapability.Multimedia.Audio.Renderer 6081 6082**Parameters** 6083 6084| Name | Type | Mandatory| Description | 6085| -------- | -------------------- | ---- | ---------------- | 6086| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 6087 6088**Example** 6089 6090```ts 6091import { BusinessError } from '@kit.BasicServicesKit'; 6092 6093audioRenderer.pause((err: BusinessError) => { 6094 if (err) { 6095 console.error('Renderer pause failed'); 6096 } else { 6097 console.info('Renderer paused.'); 6098 } 6099}); 6100``` 6101 6102### pause<sup>8+</sup> 6103 6104pause(): Promise\<void> 6105 6106Pauses rendering. This API uses a promise to return the result. 6107 6108**System capability**: SystemCapability.Multimedia.Audio.Renderer 6109 6110**Return value** 6111 6112| Type | Description | 6113| -------------- | ------------------------- | 6114| Promise\<void> | Promise that returns no value.| 6115 6116**Example** 6117 6118```ts 6119import { BusinessError } from '@kit.BasicServicesKit'; 6120 6121audioRenderer.pause().then(() => { 6122 console.info('Renderer paused'); 6123}).catch((err: BusinessError) => { 6124 console.error(`ERROR: ${err}`); 6125}); 6126``` 6127 6128### drain<sup>8+</sup> 6129 6130drain(callback: AsyncCallback\<void>): void 6131 6132Drains the playback buffer. This API uses an asynchronous callback to return the result. 6133 6134**System capability**: SystemCapability.Multimedia.Audio.Renderer 6135 6136**Parameters** 6137 6138| Name | Type | Mandatory| Description | 6139| -------- | -------------------- | ---- | ---------------- | 6140| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 6141 6142**Example** 6143 6144```ts 6145import { BusinessError } from '@kit.BasicServicesKit'; 6146 6147audioRenderer.drain((err: BusinessError) => { 6148 if (err) { 6149 console.error('Renderer drain failed'); 6150 } else { 6151 console.info('Renderer drained.'); 6152 } 6153}); 6154``` 6155 6156### drain<sup>8+</sup> 6157 6158drain(): Promise\<void> 6159 6160Drains the playback buffer. This API uses a promise to return the result. 6161 6162**System capability**: SystemCapability.Multimedia.Audio.Renderer 6163 6164**Return value** 6165 6166| Type | Description | 6167| -------------- | ------------------------- | 6168| Promise\<void> | Promise that returns no value.| 6169 6170**Example** 6171 6172```ts 6173import { BusinessError } from '@kit.BasicServicesKit'; 6174 6175audioRenderer.drain().then(() => { 6176 console.info('Renderer drained successfully'); 6177}).catch((err: BusinessError) => { 6178 console.error(`ERROR: ${err}`); 6179}); 6180``` 6181 6182### flush<sup>11+</sup> 6183 6184flush(): Promise\<void> 6185 6186Flushes 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. 6187 6188**System capability**: SystemCapability.Multimedia.Audio.Renderer 6189 6190**Return value** 6191 6192| Type | Description | 6193| -------------- | ------------------------- | 6194| Promise\<void> | Promise that returns no value.| 6195 6196**Error codes** 6197 6198For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 6199 6200| ID| Error Message| 6201| ------- | --------------------------------------------| 6202| 6800103 | Operation not permit at current state. Return by promise. | 6203 6204**Example** 6205 6206```ts 6207import { BusinessError } from '@kit.BasicServicesKit'; 6208 6209audioRenderer.flush().then(() => { 6210 console.info('Renderer flushed successfully'); 6211}).catch((err: BusinessError) => { 6212 console.error(`ERROR: ${err}`); 6213}); 6214``` 6215 6216### stop<sup>8+</sup> 6217 6218stop(callback: AsyncCallback\<void>): void 6219 6220Stops rendering. This API uses an asynchronous callback to return the result. 6221 6222**System capability**: SystemCapability.Multimedia.Audio.Renderer 6223 6224**Parameters** 6225 6226| Name | Type | Mandatory| Description | 6227| -------- | -------------------- | ---- | ---------------- | 6228| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 6229 6230**Example** 6231 6232```ts 6233import { BusinessError } from '@kit.BasicServicesKit'; 6234 6235audioRenderer.stop((err: BusinessError) => { 6236 if (err) { 6237 console.error('Renderer stop failed'); 6238 } else { 6239 console.info('Renderer stopped.'); 6240 } 6241}); 6242``` 6243 6244### stop<sup>8+</sup> 6245 6246stop(): Promise\<void> 6247 6248Stops rendering. This API uses a promise to return the result. 6249 6250**System capability**: SystemCapability.Multimedia.Audio.Renderer 6251 6252**Return value** 6253 6254| Type | Description | 6255| -------------- | ------------------------- | 6256| Promise\<void> | Promise that returns no value.| 6257 6258**Example** 6259 6260```ts 6261import { BusinessError } from '@kit.BasicServicesKit'; 6262 6263audioRenderer.stop().then(() => { 6264 console.info('Renderer stopped successfully'); 6265}).catch((err: BusinessError) => { 6266 console.error(`ERROR: ${err}`); 6267}); 6268``` 6269 6270### release<sup>8+</sup> 6271 6272release(callback: AsyncCallback\<void>): void 6273 6274Releases the renderer. This API uses an asynchronous callback to return the result. 6275 6276**System capability**: SystemCapability.Multimedia.Audio.Renderer 6277 6278**Parameters** 6279 6280| Name | Type | Mandatory| Description | 6281| -------- | -------------------- | ---- | ---------------- | 6282| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 6283 6284**Example** 6285 6286```ts 6287import { BusinessError } from '@kit.BasicServicesKit'; 6288 6289audioRenderer.release((err: BusinessError) => { 6290 if (err) { 6291 console.error('Renderer release failed'); 6292 } else { 6293 console.info('Renderer released.'); 6294 } 6295}); 6296``` 6297 6298### release<sup>8+</sup> 6299 6300release(): Promise\<void> 6301 6302Releases the renderer. This API uses a promise to return the result. 6303 6304**System capability**: SystemCapability.Multimedia.Audio.Renderer 6305 6306**Return value** 6307 6308| Type | Description | 6309| -------------- | ------------------------- | 6310| Promise\<void> | Promise that returns no value.| 6311 6312**Example** 6313 6314```ts 6315import { BusinessError } from '@kit.BasicServicesKit'; 6316 6317audioRenderer.release().then(() => { 6318 console.info('Renderer released successfully'); 6319}).catch((err: BusinessError) => { 6320 console.error(`ERROR: ${err}`); 6321}); 6322``` 6323 6324### write<sup>8+(deprecated)</sup> 6325 6326write(buffer: ArrayBuffer, callback: AsyncCallback\<number>): void 6327 6328Writes the buffer. This API uses an asynchronous callback to return the result. 6329 6330> **NOTE** 6331> 6332> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [on('writeData')](#onwritedata11) in **AudioRenderer**. 6333 6334**System capability**: SystemCapability.Multimedia.Audio.Renderer 6335 6336**Parameters** 6337 6338| Name | Type | Mandatory| Description | 6339| -------- | ---------------------- | ---- | --------------------------------------------------- | 6340| buffer | ArrayBuffer | Yes | Data to be written to the buffer. | 6341| 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.| 6342 6343**Example** 6344 6345```ts 6346import { BusinessError } from '@kit.BasicServicesKit'; 6347import { fileIo as fs } from '@kit.CoreFileKit'; 6348 6349let bufferSize: number; 6350class Options { 6351 offset?: number; 6352 length?: number; 6353} 6354audioRenderer.getBufferSize().then((data: number)=> { 6355 console.info(`AudioFrameworkRenderLog: getBufferSize: SUCCESS ${data}`); 6356 bufferSize = data; 6357 console.info(`Buffer size: ${bufferSize}`); 6358 let path = getContext().cacheDir; 6359 let filePath = path + '/StarWars10s-2C-48000-4SW.wav'; 6360 let file: fs.File = fs.openSync(filePath, fs.OpenMode.READ_ONLY); 6361 fs.stat(filePath).then(async (stat: fs.Stat) => { 6362 let buf = new ArrayBuffer(bufferSize); 6363 let len = stat.size % bufferSize == 0 ? Math.floor(stat.size / bufferSize) : Math.floor(stat.size / bufferSize + 1); 6364 for (let i = 0;i < len; i++) { 6365 let options: Options = { 6366 offset: i * bufferSize, 6367 length: bufferSize 6368 }; 6369 let readSize: number = await fs.read(file.fd, buf, options); 6370 let writeSize: number = await new Promise((resolve,reject)=>{ 6371 audioRenderer.write(buf,(err: BusinessError, writeSize: number)=>{ 6372 if(err){ 6373 reject(err) 6374 }else{ 6375 resolve(writeSize) 6376 } 6377 }) 6378 }) 6379 } 6380 }); 6381 }).catch((err: BusinessError) => { 6382 console.error(`AudioFrameworkRenderLog: getBufferSize: ERROR: ${err}`); 6383}); 6384``` 6385 6386### write<sup>8+(deprecated)</sup> 6387 6388write(buffer: ArrayBuffer): Promise\<number> 6389 6390Writes the buffer. This API uses a promise to return the result. 6391 6392> **NOTE** 6393> 6394> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [on('writeData')](#onwritedata11) in **AudioRenderer**. 6395 6396**System capability**: SystemCapability.Multimedia.Audio.Renderer 6397 6398**Parameters** 6399 6400| Name | Type | Mandatory| Description | 6401| -------- | ---------------------- | ---- | --------------------------------------------------- | 6402| buffer | ArrayBuffer | Yes | Data to be written to the buffer. | 6403 6404**Return value** 6405 6406| Type | Description | 6407| ---------------- | ------------------------------------------------------------ | 6408| Promise\<number> | Promise used to return the number of written bytes.| 6409 6410**Example** 6411 6412```ts 6413import { BusinessError } from '@kit.BasicServicesKit'; 6414import { fileIo as fs } from '@kit.CoreFileKit'; 6415 6416let bufferSize: number; 6417class Options { 6418 offset?: number; 6419 length?: number; 6420} 6421audioRenderer.getBufferSize().then((data: number) => { 6422 console.info(`AudioFrameworkRenderLog: getBufferSize: SUCCESS ${data}`); 6423 bufferSize = data; 6424 console.info(`BufferSize: ${bufferSize}`); 6425 let path = getContext().cacheDir; 6426 let filePath = path + '/StarWars10s-2C-48000-4SW.wav'; 6427 let file: fs.File = fs.openSync(filePath, fs.OpenMode.READ_ONLY); 6428 fs.stat(filePath).then(async (stat: fs.Stat) => { 6429 let buf = new ArrayBuffer(bufferSize); 6430 let len = stat.size % bufferSize == 0 ? Math.floor(stat.size / bufferSize) : Math.floor(stat.size / bufferSize + 1); 6431 for (let i = 0;i < len; i++) { 6432 let options: Options = { 6433 offset: i * bufferSize, 6434 length: bufferSize 6435 }; 6436 let readSize: number = await fs.read(file.fd, buf, options); 6437 try{ 6438 let writeSize: number = await audioRenderer.write(buf); 6439 } catch(err) { 6440 let error = err as BusinessError; 6441 console.error(`audioRenderer.write err: ${error}`); 6442 } 6443 } 6444 }); 6445}).catch((err: BusinessError) => { 6446 console.error(`AudioFrameworkRenderLog: getBufferSize: ERROR: ${err}`); 6447}); 6448``` 6449 6450### getAudioTime<sup>8+</sup> 6451 6452getAudioTime(callback: AsyncCallback\<number>): void 6453 6454Obtains 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. 6455 6456**System capability**: SystemCapability.Multimedia.Audio.Renderer 6457 6458**Parameters** 6459 6460| Name | Type | Mandatory| Description | 6461| -------- | ---------------------- | ---- | ---------------- | 6462| 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.| 6463 6464**Example** 6465 6466```ts 6467import { BusinessError } from '@kit.BasicServicesKit'; 6468 6469audioRenderer.getAudioTime((err: BusinessError, timestamp: number) => { 6470 console.info(`Current timestamp: ${timestamp}`); 6471}); 6472``` 6473 6474### getAudioTime<sup>8+</sup> 6475 6476getAudioTime(): Promise\<number> 6477 6478Obtains 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. 6479 6480**System capability**: SystemCapability.Multimedia.Audio.Renderer 6481 6482**Return value** 6483 6484| Type | Description | 6485| ---------------- | ----------------------- | 6486| Promise\<number> | Promise used to return the timestamp.| 6487 6488**Example** 6489 6490```ts 6491import { BusinessError } from '@kit.BasicServicesKit'; 6492 6493audioRenderer.getAudioTime().then((timestamp: number) => { 6494 console.info(`Current timestamp: ${timestamp}`); 6495}).catch((err: BusinessError) => { 6496 console.error(`ERROR: ${err}`); 6497}); 6498``` 6499 6500### getAudioTimeSync<sup>10+</sup> 6501 6502getAudioTimeSync(): number 6503 6504Obtains the timestamp of the current playback position, measured in nanoseconds from the Unix epoch (January 1, 1970). This API returns the result synchronously: 6505 6506**System capability**: SystemCapability.Multimedia.Audio.Renderer 6507 6508**Return value** 6509 6510| Type | Description | 6511| ---------------- | ----------------------- | 6512| number | Timestamp.| 6513 6514**Example** 6515 6516```ts 6517import { BusinessError } from '@kit.BasicServicesKit'; 6518 6519try { 6520 let timestamp: number = audioRenderer.getAudioTimeSync(); 6521 console.info(`Current timestamp: ${timestamp}`); 6522} catch (err) { 6523 let error = err as BusinessError; 6524 console.error(`ERROR: ${error}`); 6525} 6526``` 6527 6528### getBufferSize<sup>8+</sup> 6529 6530getBufferSize(callback: AsyncCallback\<number>): void 6531 6532Obtains a reasonable minimum buffer size in bytes for rendering. This API uses an asynchronous callback to return the result. 6533 6534**System capability**: SystemCapability.Multimedia.Audio.Renderer 6535 6536**Parameters** 6537 6538| Name | Type | Mandatory| Description | 6539| -------- | ---------------------- | ---- | -------------------- | 6540| 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.| 6541 6542**Example** 6543 6544```ts 6545import { BusinessError } from '@kit.BasicServicesKit'; 6546 6547let bufferSize: number; 6548 6549audioRenderer.getBufferSize((err: BusinessError, data: number) => { 6550 if (err) { 6551 console.error('getBufferSize error'); 6552 } else { 6553 console.info(`AudioFrameworkRenderLog: getBufferSize: SUCCESS ${data}`); 6554 bufferSize = data; 6555 } 6556}); 6557``` 6558 6559### getBufferSize<sup>8+</sup> 6560 6561getBufferSize(): Promise\<number> 6562 6563Obtains a reasonable minimum buffer size in bytes for rendering. This API uses a promise to return the result. 6564 6565**System capability**: SystemCapability.Multimedia.Audio.Renderer 6566 6567**Return value** 6568 6569| Type | Description | 6570| ---------------- | --------------------------- | 6571| Promise\<number> | Promise used to return the buffer size.| 6572 6573**Example** 6574 6575```ts 6576import { BusinessError } from '@kit.BasicServicesKit'; 6577 6578let bufferSize: number; 6579 6580audioRenderer.getBufferSize().then((data: number) => { 6581 console.info(`AudioFrameworkRenderLog: getBufferSize: SUCCESS ${data}`); 6582 bufferSize = data; 6583}).catch((err: BusinessError) => { 6584 console.error(`AudioFrameworkRenderLog: getBufferSize: ERROR: ${err}`); 6585}); 6586``` 6587 6588### getBufferSizeSync<sup>10+</sup> 6589 6590getBufferSizeSync(): number 6591 6592Obtains a reasonable minimum buffer size in bytes for rendering. This API returns the result synchronously. 6593 6594**System capability**: SystemCapability.Multimedia.Audio.Renderer 6595 6596**Return value** 6597 6598| Type | Description | 6599| ---------------- | --------------------------- | 6600| number | Buffer size.| 6601 6602**Example** 6603 6604```ts 6605import { BusinessError } from '@kit.BasicServicesKit'; 6606 6607let bufferSize: number = 0; 6608 6609try { 6610 bufferSize = audioRenderer.getBufferSizeSync(); 6611 console.info(`AudioFrameworkRenderLog: getBufferSize: SUCCESS ${bufferSize}`); 6612} catch (err) { 6613 let error = err as BusinessError; 6614 console.error(`AudioFrameworkRenderLog: getBufferSize: ERROR: ${error}`); 6615} 6616``` 6617 6618### setRenderRate<sup>8+(deprecated)</sup> 6619 6620setRenderRate(rate: AudioRendererRate, callback: AsyncCallback\<void>): void 6621 6622Sets the render rate. This API uses an asynchronous callback to return the result. 6623 6624> **NOTE** 6625> 6626> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [setSpeed](#setspeed11) in **AudioRenderer**. 6627 6628**System capability**: SystemCapability.Multimedia.Audio.Renderer 6629 6630**Parameters** 6631 6632| Name | Type | Mandatory| Description | 6633| -------- | ---------------------------------------- | ---- | ------------------------ | 6634| rate | [AudioRendererRate](#audiorendererrate8) | Yes | Audio render rate. | 6635| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 6636 6637**Example** 6638 6639```ts 6640import { BusinessError } from '@kit.BasicServicesKit'; 6641 6642audioRenderer.setRenderRate(audio.AudioRendererRate.RENDER_RATE_NORMAL, (err: BusinessError) => { 6643 if (err) { 6644 console.error('Failed to set params'); 6645 } else { 6646 console.info('Callback invoked to indicate a successful render rate setting.'); 6647 } 6648}); 6649``` 6650 6651### setRenderRate<sup>8+(deprecated)</sup> 6652 6653setRenderRate(rate: AudioRendererRate): Promise\<void> 6654 6655Sets the render rate. This API uses a promise to return the result. 6656 6657> **NOTE** 6658> 6659> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [setSpeed](#setspeed11) in **AudioRenderer**. 6660 6661**System capability**: SystemCapability.Multimedia.Audio.Renderer 6662 6663**Parameters** 6664 6665| Name| Type | Mandatory| Description | 6666| ------ | ---------------------------------------- | ---- | ------------ | 6667| rate | [AudioRendererRate](#audiorendererrate8) | Yes | Audio render rate.| 6668 6669**Return value** 6670 6671| Type | Description | 6672| -------------- | ------------------------- | 6673| Promise\<void> | Promise that returns no value.| 6674 6675**Example** 6676 6677```ts 6678import { BusinessError } from '@kit.BasicServicesKit'; 6679 6680audioRenderer.setRenderRate(audio.AudioRendererRate.RENDER_RATE_NORMAL).then(() => { 6681 console.info('setRenderRate SUCCESS'); 6682}).catch((err: BusinessError) => { 6683 console.error(`ERROR: ${err}`); 6684}); 6685``` 6686 6687### setSpeed<sup>11+</sup> 6688 6689setSpeed(speed: number): void 6690 6691Sets the playback speed. 6692 6693**System capability**: SystemCapability.Multimedia.Audio.Renderer 6694 6695**Parameters** 6696 6697| Name| Type | Mandatory| Description | 6698| ------ | ---------------------------------------- | ---- |----------------------| 6699| speed | number | Yes | Playback speed, which ranges from 0.125 to 4.0.| 6700 6701**Error codes** 6702 6703For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 6704 6705| ID| Error Message| 6706| ------- | --------------------------------------------| 6707| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 6708| 6800101 | Parameter verification failed. | 6709 6710**Example** 6711 6712```ts 6713audioRenderer.setSpeed(1.5); 6714``` 6715 6716### getRenderRate<sup>8+(deprecated)</sup> 6717 6718getRenderRate(callback: AsyncCallback\<AudioRendererRate>): void 6719 6720Obtains the current render rate. This API uses an asynchronous callback to return the result. 6721 6722> **NOTE** 6723> 6724> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [getSpeed](#getspeed11) in **AudioRenderer**. 6725 6726**System capability**: SystemCapability.Multimedia.Audio.Renderer 6727 6728**Parameters** 6729 6730| Name | Type | Mandatory| Description | 6731| -------- | ------------------------------------------------------- | ---- | ------------------ | 6732| 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.| 6733 6734**Example** 6735 6736```ts 6737import { BusinessError } from '@kit.BasicServicesKit'; 6738 6739audioRenderer.getRenderRate((err: BusinessError, renderRate: audio.AudioRendererRate) => { 6740 console.info(`getRenderRate: ${renderRate}`); 6741}); 6742``` 6743 6744### getRenderRate<sup>8+(deprecated)</sup> 6745 6746getRenderRate(): Promise\<AudioRendererRate> 6747 6748Obtains the current render rate. This API uses a promise to return the result. 6749 6750> **NOTE** 6751> 6752> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [getSpeed](#getspeed11) in **AudioRenderer**. 6753 6754**System capability**: SystemCapability.Multimedia.Audio.Renderer 6755 6756**Return value** 6757 6758| Type | Description | 6759| ------------------------------------------------- | ------------------------- | 6760| Promise<[AudioRendererRate](#audiorendererrate8)> | Promise used to return the render rate.| 6761 6762**Example** 6763 6764```ts 6765import { BusinessError } from '@kit.BasicServicesKit'; 6766 6767audioRenderer.getRenderRate().then((renderRate: audio.AudioRendererRate) => { 6768 console.info(`getRenderRate: ${renderRate}`); 6769}).catch((err: BusinessError) => { 6770 console.error(`ERROR: ${err}`); 6771}); 6772``` 6773 6774### getRenderRateSync<sup>10+(deprecated)</sup> 6775 6776getRenderRateSync(): AudioRendererRate 6777 6778Obtains the current render rate. This API returns the result synchronously. 6779 6780> **NOTE** 6781> 6782> This API is supported since API version 10 and deprecated since API version 11. You are advised to use [getSpeed](#getspeed11) in **AudioRenderer**. 6783 6784**System capability**: SystemCapability.Multimedia.Audio.Renderer 6785 6786**Return value** 6787 6788| Type | Description | 6789| ------------------------------------------------- | ------------------------- | 6790| [AudioRendererRate](#audiorendererrate8) | Audio render rate.| 6791 6792**Example** 6793 6794```ts 6795import { BusinessError } from '@kit.BasicServicesKit'; 6796 6797try { 6798 let renderRate: audio.AudioRendererRate = audioRenderer.getRenderRateSync(); 6799 console.info(`getRenderRate: ${renderRate}`); 6800} catch (err) { 6801 let error = err as BusinessError; 6802 console.error(`ERROR: ${error}`); 6803} 6804``` 6805 6806### getSpeed<sup>11+</sup> 6807 6808getSpeed(): number 6809 6810Obtains the playback speed. 6811 6812**System capability**: SystemCapability.Multimedia.Audio.Renderer 6813 6814**Return value** 6815 6816| Type | Description | 6817| ------------------------------------------------- |-----------| 6818| number | Playback speed.| 6819 6820**Example** 6821 6822```ts 6823let speed = audioRenderer.getSpeed(); 6824``` 6825 6826### setInterruptMode<sup>9+</sup> 6827 6828setInterruptMode(mode: InterruptMode): Promise<void> 6829 6830Sets the audio interruption mode for the application. This API uses a promise to return the result. 6831 6832**System capability**: SystemCapability.Multimedia.Audio.Interrupt 6833 6834**Parameters** 6835 6836| Name | Type | Mandatory | Description | 6837| ---------- | ---------------------------------- | ------ | ---------- | 6838| mode | [InterruptMode](#interruptmode9) | Yes | Audio interruption mode. | 6839 6840**Return value** 6841 6842| Type | Description | 6843| ------------------- | ----------------------------- | 6844| Promise<void> | Promise that returns no value.| 6845 6846**Example** 6847 6848```ts 6849import { BusinessError } from '@kit.BasicServicesKit'; 6850 6851let mode = 0; 6852 6853audioRenderer.setInterruptMode(mode).then(() => { 6854 console.info('setInterruptMode Success!'); 6855}).catch((err: BusinessError) => { 6856 console.error(`setInterruptMode Fail: ${err}`); 6857}); 6858``` 6859### setInterruptMode<sup>9+</sup> 6860 6861setInterruptMode(mode: InterruptMode, callback: AsyncCallback\<void>): void 6862 6863Sets the audio interruption mode for the application. This API uses an asynchronous callback to return the result. 6864 6865**System capability**: SystemCapability.Multimedia.Audio.Interrupt 6866 6867**Parameters** 6868 6869| Name | Type | Mandatory | Description | 6870| ------- | ----------------------------------- | ------ | -------------- | 6871|mode | [InterruptMode](#interruptmode9) | Yes | Audio interruption mode.| 6872|callback | AsyncCallback\<void> | Yes |Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 6873 6874**Example** 6875 6876```ts 6877import { BusinessError } from '@kit.BasicServicesKit'; 6878 6879let mode = 1; 6880 6881audioRenderer.setInterruptMode(mode, (err: BusinessError) => { 6882 if(err){ 6883 console.error(`setInterruptMode Fail: ${err}`); 6884 } 6885 console.info('setInterruptMode Success!'); 6886}); 6887``` 6888 6889### setInterruptModeSync<sup>10+</sup> 6890 6891setInterruptModeSync(mode: InterruptMode): void 6892 6893Sets the audio interruption mode for the application. This API returns the result synchronously. 6894 6895**System capability**: SystemCapability.Multimedia.Audio.Interrupt 6896 6897**Parameters** 6898 6899| Name | Type | Mandatory | Description | 6900| ---------- | ---------------------------------- | ------ | ---------- | 6901| mode | [InterruptMode](#interruptmode9) | Yes | Audio interruption mode. | 6902 6903**Error codes** 6904 6905For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 6906 6907| ID| Error Message| 6908| ------- | --------------------------------------------| 6909| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 6910| 6800101 | Parameter verification failed. | 6911 6912**Example** 6913 6914```ts 6915import { BusinessError } from '@kit.BasicServicesKit'; 6916 6917try { 6918 audioRenderer.setInterruptModeSync(0); 6919 console.info('setInterruptMode Success!'); 6920} catch (err) { 6921 let error = err as BusinessError; 6922 console.error(`setInterruptMode Fail: ${error}`); 6923} 6924``` 6925 6926### setVolume<sup>9+</sup> 6927 6928setVolume(volume: number): Promise<void> 6929 6930Sets the volume for the application. This API uses a promise to return the result. 6931 6932**System capability**: SystemCapability.Multimedia.Audio.Renderer 6933 6934**Parameters** 6935 6936| Name | Type | Mandatory | Description | 6937| ---------- | ------- | ------ | ------------------- | 6938| volume | number | Yes | Volume to set, which can be within the range from 0.0 to 1.0.| 6939 6940**Return value** 6941 6942| Type | Description | 6943| ------------------- | ----------------------------- | 6944| Promise<void> | Promise that returns no value.| 6945 6946**Example** 6947 6948```ts 6949import { BusinessError } from '@kit.BasicServicesKit'; 6950 6951audioRenderer.setVolume(0.5).then(() => { 6952 console.info('setVolume Success!'); 6953}).catch((err: BusinessError) => { 6954 console.error(`setVolume Fail: ${err}`); 6955}); 6956``` 6957### setVolume<sup>9+</sup> 6958 6959setVolume(volume: number, callback: AsyncCallback\<void>): void 6960 6961Sets the volume for the application. This API uses an asynchronous callback to return the result. 6962 6963**System capability**: SystemCapability.Multimedia.Audio.Renderer 6964 6965**Parameters** 6966 6967| Name | Type | Mandatory | Description | 6968| ------- | -----------| ------ | ------------------- | 6969|volume | number | Yes | Volume to set, which can be within the range from 0.0 to 1.0.| 6970|callback | AsyncCallback\<void> | Yes |Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 6971 6972**Example** 6973 6974```ts 6975import { BusinessError } from '@kit.BasicServicesKit'; 6976 6977audioRenderer.setVolume(0.5, (err: BusinessError) => { 6978 if(err){ 6979 console.error(`setVolume Fail: ${err}`); 6980 return; 6981 } 6982 console.info('setVolume Success!'); 6983}); 6984``` 6985### getVolume<sup>12+</sup> 6986 6987getVolume(): number 6988 6989Obtains the volume of the audio render. This API returns the result synchronously. 6990 6991**System capability**: SystemCapability.Multimedia.Audio.Renderer 6992 6993**Return value** 6994 6995| Type | Description | 6996| ---------------- | --------------------------- | 6997| number | Volume, in the range [0.0-1.0].| 6998 6999**Example** 7000 7001```ts 7002import { BusinessError } from '@kit.BasicServicesKit'; 7003 7004try { 7005 let value: number = audioRenderer.getVolume(); 7006 console.info(`Indicate that the volume is obtained ${value}.`); 7007} catch (err) { 7008 let error = err as BusinessError; 7009 console.error(`Failed to obtain the volume, error ${error}.`); 7010} 7011``` 7012 7013### getMinStreamVolume<sup>10+</sup> 7014 7015getMinStreamVolume(callback: AsyncCallback<number>): void 7016 7017Obtains the minimum volume of the application from the perspective of an audio stream. This API uses an asynchronous callback to return the result. 7018 7019**System capability**: SystemCapability.Multimedia.Audio.Renderer 7020 7021**Parameters** 7022 7023| Name | Type | Mandatory | Description | 7024| ------- | -----------| ------ | ------------------- | 7025|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.| 7026 7027**Example** 7028 7029```ts 7030import { BusinessError } from '@kit.BasicServicesKit'; 7031 7032audioRenderer.getMinStreamVolume((err: BusinessError, minVolume: number) => { 7033 if (err) { 7034 console.error(`getMinStreamVolume error: ${err}`); 7035 } else { 7036 console.info(`getMinStreamVolume Success! ${minVolume}`); 7037 } 7038}); 7039``` 7040### getMinStreamVolume<sup>10+</sup> 7041 7042getMinStreamVolume(): Promise<number> 7043 7044Obtains the minimum volume of the application from the perspective of an audio stream. This API uses a promise to return the result. 7045 7046**System capability**: SystemCapability.Multimedia.Audio.Renderer 7047 7048**Return value** 7049 7050| Type | Description | 7051| ------------------- | ----------------------------- | 7052| Promise<number>| Promise used to return the minimum volume, ranging from 0 to 1.| 7053 7054**Example** 7055 7056```ts 7057import { BusinessError } from '@kit.BasicServicesKit'; 7058 7059audioRenderer.getMinStreamVolume().then((value: number) => { 7060 console.info(`Get min stream volume Success! ${value}`); 7061}).catch((err: BusinessError) => { 7062 console.error(`Get min stream volume Fail: ${err}`); 7063}); 7064``` 7065 7066### getMinStreamVolumeSync<sup>10+</sup> 7067 7068getMinStreamVolumeSync(): number 7069 7070Obtains the minimum volume of the application from the perspective of an audio stream. This API returns the result synchronously. 7071 7072**System capability**: SystemCapability.Multimedia.Audio.Renderer 7073 7074**Return value** 7075 7076| Type | Description | 7077| ------------------- | ----------------------------- | 7078| number| Minimum volume, ranging from 0 to 1.| 7079 7080**Example** 7081 7082```ts 7083import { BusinessError } from '@kit.BasicServicesKit'; 7084 7085try { 7086 let value: number = audioRenderer.getMinStreamVolumeSync(); 7087 console.info(`Get min stream volume Success! ${value}`); 7088} catch (err) { 7089 let error = err as BusinessError; 7090 console.error(`Get min stream volume Fail: ${error}`); 7091} 7092``` 7093 7094### getMaxStreamVolume<sup>10+</sup> 7095 7096getMaxStreamVolume(callback: AsyncCallback<number>): void 7097 7098Obtains the maximum volume of the application from the perspective of an audio stream. This API uses an asynchronous callback to return the result. 7099 7100**System capability**: SystemCapability.Multimedia.Audio.Renderer 7101 7102**Parameters** 7103 7104| Name | Type | Mandatory | Description | 7105| ------- | -----------| ------ | ------------------- | 7106|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.| 7107 7108**Example** 7109 7110```ts 7111import { BusinessError } from '@kit.BasicServicesKit'; 7112 7113audioRenderer.getMaxStreamVolume((err: BusinessError, maxVolume: number) => { 7114 if (err) { 7115 console.error(`getMaxStreamVolume Fail: ${err}`); 7116 } else { 7117 console.info(`getMaxStreamVolume Success! ${maxVolume}`); 7118 } 7119}); 7120``` 7121### getMaxStreamVolume<sup>10+</sup> 7122 7123getMaxStreamVolume(): Promise<number> 7124 7125Obtains the maximum volume of the application from the perspective of an audio stream. This API uses a promise to return the result. 7126 7127**System capability**: SystemCapability.Multimedia.Audio.Renderer 7128 7129**Return value** 7130 7131| Type | Description | 7132| ------------------- | ----------------------------- | 7133| Promise<number>| Promise used to return the maximum volume, ranging from 0 to 1.| 7134 7135**Example** 7136 7137```ts 7138import { BusinessError } from '@kit.BasicServicesKit'; 7139 7140audioRenderer.getMaxStreamVolume().then((value: number) => { 7141 console.info(`Get max stream volume Success! ${value}`); 7142}).catch((err: BusinessError) => { 7143 console.error(`Get max stream volume Fail: ${err}`); 7144}); 7145``` 7146 7147### getMaxStreamVolumeSync<sup>10+</sup> 7148 7149getMaxStreamVolumeSync(): number 7150 7151Obtains the maximum volume of the application from the perspective of an audio stream. This API returns the result synchronously. 7152 7153**System capability**: SystemCapability.Multimedia.Audio.Renderer 7154 7155**Return value** 7156 7157| Type | Description | 7158| ------------------- | ----------------------------- | 7159| number| Maximum volume, ranging from 0 to 1.| 7160 7161**Example** 7162 7163```ts 7164import { BusinessError } from '@kit.BasicServicesKit'; 7165 7166try { 7167 let value: number = audioRenderer.getMaxStreamVolumeSync(); 7168 console.info(`Get max stream volume Success! ${value}`); 7169} catch (err) { 7170 let error = err as BusinessError; 7171 console.error(`Get max stream volume Fail: ${error}`); 7172} 7173``` 7174 7175### getUnderflowCount<sup>10+</sup> 7176 7177getUnderflowCount(callback: AsyncCallback<number>): void 7178 7179Obtains the number of underflow audio frames in the audio stream that is being played. This API uses an asynchronous callback to return the result. 7180 7181**System capability**: SystemCapability.Multimedia.Audio.Renderer 7182 7183**Parameters** 7184 7185| Name | Type | Mandatory | Description | 7186| ------- | -----------| ------ | ------------------- | 7187|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.| 7188 7189**Example** 7190 7191```ts 7192import { BusinessError } from '@kit.BasicServicesKit'; 7193 7194audioRenderer.getUnderflowCount((err: BusinessError, underflowCount: number) => { 7195 if (err) { 7196 console.error(`getUnderflowCount Fail: ${err}`); 7197 } else { 7198 console.info(`getUnderflowCount Success! ${underflowCount}`); 7199 } 7200}); 7201``` 7202### getUnderflowCount<sup>10+</sup> 7203 7204getUnderflowCount(): Promise<number> 7205 7206Obtains the number of underflow audio frames in the audio stream that is being played. This API uses a promise to return the result. 7207 7208**System capability**: SystemCapability.Multimedia.Audio.Renderer 7209 7210**Return value** 7211 7212| Type | Description | 7213| ------------------- | ----------------------------- | 7214| Promise<number>| Promise used to return the number of underflow audio frames.| 7215 7216**Example** 7217 7218```ts 7219import { BusinessError } from '@kit.BasicServicesKit'; 7220 7221audioRenderer.getUnderflowCount().then((value: number) => { 7222 console.info(`Get underflow count Success! ${value}`); 7223}).catch((err: BusinessError) => { 7224 console.error(`Get underflow count Fail: ${err}`); 7225}); 7226``` 7227 7228### getUnderflowCountSync<sup>10+</sup> 7229 7230getUnderflowCountSync(): number 7231 7232Obtains the number of underflow audio frames in the audio stream that is being played. This API returns the result synchronously. 7233 7234**System capability**: SystemCapability.Multimedia.Audio.Renderer 7235 7236**Return value** 7237 7238| Type | Description | 7239| ------------------- | ----------------------------- | 7240| number| Number of underflow audio frames.| 7241 7242**Example** 7243 7244```ts 7245import { BusinessError } from '@kit.BasicServicesKit'; 7246 7247try { 7248 let value: number = audioRenderer.getUnderflowCountSync(); 7249 console.info(`Get underflow count Success! ${value}`); 7250} catch (err) { 7251 let error = err as BusinessError; 7252 console.error(`Get underflow count Fail: ${error}`); 7253} 7254``` 7255 7256### getCurrentOutputDevices<sup>10+</sup> 7257 7258getCurrentOutputDevices(callback: AsyncCallback<AudioDeviceDescriptors>): void 7259 7260Obtains the output device descriptors of the audio streams. This API uses an asynchronous callback to return the result. 7261 7262**System capability**: SystemCapability.Multimedia.Audio.Device 7263 7264**Parameters** 7265 7266| Name | Type | Mandatory | Description | 7267| ------- | -----------| ------ | ------------------- | 7268|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.| 7269 7270**Example** 7271 7272```ts 7273import { BusinessError } from '@kit.BasicServicesKit'; 7274 7275audioRenderer.getCurrentOutputDevices((err: BusinessError, deviceInfo: audio.AudioDeviceDescriptors) => { 7276 if (err) { 7277 console.error(`getCurrentOutputDevices Fail: ${err}`); 7278 } else { 7279 for (let i = 0; i < deviceInfo.length; i++) { 7280 console.info(`DeviceInfo id: ${deviceInfo[i].id}`); 7281 console.info(`DeviceInfo type: ${deviceInfo[i].deviceType}`); 7282 console.info(`DeviceInfo role: ${deviceInfo[i].deviceRole}`); 7283 console.info(`DeviceInfo name: ${deviceInfo[i].name}`); 7284 console.info(`DeviceInfo address: ${deviceInfo[i].address}`); 7285 console.info(`DeviceInfo samplerate: ${deviceInfo[i].sampleRates[0]}`); 7286 console.info(`DeviceInfo channelcount: ${deviceInfo[i].channelCounts[0]}`); 7287 console.info(`DeviceInfo channelmask: ${deviceInfo[i].channelMasks[0]}`); 7288 } 7289 } 7290}); 7291``` 7292### getCurrentOutputDevices<sup>10+</sup> 7293 7294getCurrentOutputDevices(): Promise<AudioDeviceDescriptors> 7295 7296Obtains the output device descriptors of the audio streams. This API uses a promise to return the result. 7297 7298**System capability**: SystemCapability.Multimedia.Audio.Device 7299 7300**Return value** 7301 7302| Type | Description | 7303| ------------------- | ----------------------------- | 7304| Promise<[AudioDeviceDescriptors](#audiodevicedescriptors)>| Promise used to return the output device descriptors.| 7305 7306**Example** 7307 7308```ts 7309import { BusinessError } from '@kit.BasicServicesKit'; 7310 7311audioRenderer.getCurrentOutputDevices().then((deviceInfo: audio.AudioDeviceDescriptors) => { 7312 for (let i = 0; i < deviceInfo.length; i++) { 7313 console.info(`DeviceInfo id: ${deviceInfo[i].id}`); 7314 console.info(`DeviceInfo type: ${deviceInfo[i].deviceType}`); 7315 console.info(`DeviceInfo role: ${deviceInfo[i].deviceRole}`); 7316 console.info(`DeviceInfo name: ${deviceInfo[i].name}`); 7317 console.info(`DeviceInfo address: ${deviceInfo[i].address}`); 7318 console.info(`DeviceInfo samplerate: ${deviceInfo[i].sampleRates[0]}`); 7319 console.info(`DeviceInfo channelcount: ${deviceInfo[i].channelCounts[0]}`); 7320 console.info(`DeviceInfo channelmask: ${deviceInfo[i].channelMasks[0]}`); 7321 } 7322}).catch((err: BusinessError) => { 7323 console.error(`Get current output devices Fail: ${err}`); 7324}); 7325``` 7326 7327### getCurrentOutputDevicesSync<sup>10+</sup> 7328 7329getCurrentOutputDevicesSync(): AudioDeviceDescriptors 7330 7331Obtains the output device descriptors of the audio streams. This API returns the result synchronously. 7332 7333**System capability**: SystemCapability.Multimedia.Audio.Device 7334 7335**Return value** 7336 7337| Type | Description | 7338| ------------------- | ----------------------------- | 7339| [AudioDeviceDescriptors](#audiodevicedescriptors) | Output device descriptors.| 7340 7341**Example** 7342 7343```ts 7344import { BusinessError } from '@kit.BasicServicesKit'; 7345 7346try { 7347 let deviceInfo: audio.AudioDeviceDescriptors = audioRenderer.getCurrentOutputDevicesSync(); 7348 for (let i = 0; i < deviceInfo.length; i++) { 7349 console.info(`DeviceInfo id: ${deviceInfo[i].id}`); 7350 console.info(`DeviceInfo type: ${deviceInfo[i].deviceType}`); 7351 console.info(`DeviceInfo role: ${deviceInfo[i].deviceRole}`); 7352 console.info(`DeviceInfo name: ${deviceInfo[i].name}`); 7353 console.info(`DeviceInfo address: ${deviceInfo[i].address}`); 7354 console.info(`DeviceInfo samplerate: ${deviceInfo[i].sampleRates[0]}`); 7355 console.info(`DeviceInfo channelcount: ${deviceInfo[i].channelCounts[0]}`); 7356 console.info(`DeviceInfo channelmask: ${deviceInfo[i].channelMasks[0]}`); 7357 } 7358} catch (err) { 7359 let error = err as BusinessError; 7360 console.error(`Get current output devices Fail: ${error}`); 7361} 7362``` 7363### setChannelBlendMode<sup>11+</sup> 7364 7365setChannelBlendMode(mode: ChannelBlendMode): void 7366 7367Sets the audio channel blending mode. This API returns the result synchronously. 7368 7369**System capability**: SystemCapability.Multimedia.Audio.Renderer 7370 7371**Parameters** 7372 7373| Name | Type | Mandatory| Description | 7374| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 7375| mode | [ChannelBlendMode](#channelblendmode11) | Yes | Audio channel blending mode. | 7376 7377**Error codes** 7378 7379For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7380 7381| ID| Error Message| 7382| ------- | --------------------------------------------| 7383| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7384| 6800101 | Parameter verification failed. | 7385| 6800103 | Operation not permit at current state. | 7386 7387**Example** 7388 7389```ts 7390let mode = audio.ChannelBlendMode.MODE_DEFAULT; 7391 7392audioRenderer.setChannelBlendMode(mode); 7393console.info(`BlendMode: ${mode}`); 7394``` 7395### setVolumeWithRamp<sup>11+</sup> 7396 7397setVolumeWithRamp(volume: number, duration: number): void 7398 7399Sets a volume ramp. This API returns the result synchronously. 7400 7401**System capability**: SystemCapability.Multimedia.Audio.Renderer 7402 7403**Parameters** 7404 7405| Name | Type | Mandatory| Description | 7406| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 7407| volume | number | Yes | Target volume, within the range [0.0, 1.0]. | 7408| duration | number | Yes | Time range during which the ramp applies, in ms. | 7409 7410**Error codes** 7411 7412For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7413 7414| ID| Error Message| 7415| ------- | --------------------------------------------| 7416| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7417| 6800101 | Parameter verification failed. | 7418 7419**Example** 7420 7421```ts 7422let volume = 0.5; 7423let duration = 1000; 7424 7425audioRenderer.setVolumeWithRamp(volume, duration); 7426console.info(`setVolumeWithRamp: ${volume}`); 7427``` 7428 7429### setSilentModeAndMixWithOthers<sup>12+</sup> 7430 7431setSilentModeAndMixWithOthers(on: boolean): void 7432 7433Sets the silent mode in concurrent playback for the audio stream. 7434 7435If 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. 7436 7437**System capability**: SystemCapability.Multimedia.Audio.Renderer 7438 7439**Parameters** 7440 7441| Name| Type | Mandatory| Description | 7442| ------ | ---------------------------------------- | ---- |----------------------| 7443| 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.| 7444 7445**Example** 7446 7447```ts 7448audioRenderer.setSilentModeAndMixWithOthers(true); 7449``` 7450 7451### getSilentModeAndMixWithOthers<sup>12+</sup> 7452 7453getSilentModeAndMixWithOthers(): boolean 7454 7455Obtains the silent mode in concurrent playback for the audio stream. 7456 7457**System capability**: SystemCapability.Multimedia.Audio.Renderer 7458 7459**Return value** 7460 7461| Type | Description | 7462| ------------------------------------------------- |-----------| 7463| boolean | **true**: The silent mode in concurrent playback is enabled.<br>**false**: The silent mode in concurrent playback is disabled.| 7464 7465**Example** 7466 7467```ts 7468let on = audioRenderer.getSilentModeAndMixWithOthers(); 7469``` 7470 7471### setDefaultOutputDevice<sup>12+</sup> 7472 7473setDefaultOutputDevice(deviceType: DeviceType): Promise<void> 7474 7475Sets the default built-in audio output device. This API uses a promise to return the result. 7476 7477> **NOTE** 7478> 7479> - This 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. 7480> 7481> - This 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. 7482> 7483> - This API has a lower priority than [AVCastPicker](../apis-avsession-kit/ohos-multimedia-avcastpicker.md#avcastpicker). If you have already switched the audio device using **AVCastPicker**, using this API to switch devices again does not take effect. 7484 7485**System capability**: SystemCapability.Multimedia.Audio.Renderer 7486 7487**Parameters** 7488 7489| Name | Type | Mandatory | Description | 7490| ---------- |----------------| ------ |---------------------------------------------------------| 7491| deviceType | [DeviceType](#devicetype) | Yes | Device type.<br>The options are **EARPIECE**, **SPEAKER**, and **DEFAULT**.| 7492 7493**Return value** 7494 7495| Type | Description | 7496| ------------------- | ----------------------------- | 7497| Promise<void> | Promise that returns no value.| 7498 7499**Error codes** 7500 7501For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7502 7503| ID| Error Message| 7504| ------- | --------------------------------------------| 7505| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7506| 6800101 | Parameter verification failed. | 7507| 6800103 | Operation not permit at current state. | 7508 7509**Example** 7510 7511```ts 7512import { BusinessError } from '@kit.BasicServicesKit'; 7513 7514// This API can be called at any time after an **AudioRenderer** instance is created. 7515// 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. 7516// 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. 7517audioRenderer.setDefaultOutputDevice(audio.DeviceType.SPEAKER).then(() => { 7518 console.info('setDefaultOutputDevice Success!'); 7519}).catch((err: BusinessError) => { 7520 console.error(`setDefaultOutputDevice Fail: ${err}`); 7521}); 7522``` 7523 7524### on('audioInterrupt')<sup>9+</sup> 7525 7526on(type: 'audioInterrupt', callback: Callback\<InterruptEvent>): void 7527 7528Subscribes to the audio interruption event, which is triggered when the audio focus is changed. This API uses an asynchronous callback to return the result. 7529 7530The **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. 7531 7532After 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). 7533 7534**System capability**: SystemCapability.Multimedia.Audio.Interrupt 7535 7536**Parameters** 7537 7538| Name | Type | Mandatory| Description | 7539| -------- | -------------------------------------------- | ---- | ----------------------------------------------------------- | 7540| type | string | Yes | Event type. The value is fixed at **'audioInterrupt'**.| 7541| callback | Callback\<[InterruptEvent](#interruptevent9)\> | Yes | Callback used to return the audio interruption event received by the application when playback is interrupted.| 7542 7543**Error codes** 7544 7545For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7546 7547| ID| Error Message| 7548| ------- | --------------------------------------------| 7549| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7550| 6800101 | Parameter verification failed. | 7551 7552**Example** 7553 7554```ts 7555import { audio } from '@kit.AudioKit'; 7556 7557let isPlaying: boolean; // An identifier specifying whether rendering is in progress. 7558let isDucked: boolean; // An identifier specifying whether the audio volume is reduced. 7559onAudioInterrupt(); 7560 7561async function onAudioInterrupt(){ 7562 audioRenderer.on('audioInterrupt', (interruptEvent: audio.InterruptEvent) => { 7563 // When an audio interruption event occurs, the AudioRenderer receives the interruptEvent callback and performs processing based on the content in the callback. 7564 // 1. (Optional) The AudioRenderer reads the value of interruptEvent.forceType to see whether the system has forcibly performed the operation. 7565 // 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. 7566 // 2. (Mandatory) The AudioRenderer then reads the value of interruptEvent.hintType and performs corresponding processing. 7567 if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_FORCE) { 7568 // The audio focus event has been forcibly executed by the system. The application needs to update its status and displayed content. 7569 switch (interruptEvent.hintType) { 7570 case audio.InterruptHint.INTERRUPT_HINT_PAUSE: 7571 // 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. 7572 console.info('Force paused. Update playing status and stop writing'); 7573 isPlaying = false; // A simplified processing indicating several operations for switching the application to the paused state. 7574 break; 7575 case audio.InterruptHint.INTERRUPT_HINT_STOP: 7576 // The audio stream has been stopped and permanently loses the focus. The user must manually trigger the operation to resume rendering. 7577 console.info('Force stopped. Update playing status and stop writing'); 7578 isPlaying = false; // A simplified processing indicating several operations for switching the application to the paused state. 7579 break; 7580 case audio.InterruptHint.INTERRUPT_HINT_DUCK: 7581 // The audio stream is rendered at a reduced volume. 7582 console.info('Force ducked. Update volume status'); 7583 isDucked = true; // A simplified processing indicating several operations for updating the volume status. 7584 break; 7585 case audio.InterruptHint.INTERRUPT_HINT_UNDUCK: 7586 // The audio stream is rendered at the normal volume. 7587 console.info('Force ducked. Update volume status'); 7588 isDucked = false; // A simplified processing indicating several operations for updating the volume status. 7589 break; 7590 default: 7591 console.info('Invalid interruptEvent'); 7592 break; 7593 } 7594 } else if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_SHARE) { 7595 // 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. 7596 switch (interruptEvent.hintType) { 7597 case audio.InterruptHint.INTERRUPT_HINT_RESUME: 7598 // 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.) 7599 // 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. 7600 console.info('Resume force paused renderer or ignore'); 7601 // To continue rendering, the application must perform the required operations. 7602 break; 7603 default: 7604 console.info('Invalid interruptEvent'); 7605 break; 7606 } 7607 } 7608 }); 7609} 7610``` 7611 7612### on('markReach')<sup>8+</sup> 7613 7614on(type: 'markReach', frame: number, callback: Callback<number>): void 7615 7616Subscribes 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. 7617 7618For example, if **frame** is set to **100**, the callback is invoked when the number of rendered frames reaches the 100th frame. 7619 7620**System capability**: SystemCapability.Multimedia.Audio.Renderer 7621 7622**Parameters** 7623 7624| Name | Type | Mandatory| Description | 7625| :------- | :----------------------- | :--- | :---------------------------------------- | 7626| type | string | Yes | Event type. The value is fixed at **'markReach'**.| 7627| frame | number | Yes | Number of frames to trigger the event. The value must be greater than **0**. | 7628| callback | Callback\<number> | Yes | Callback used to return the value of the **frame** parameter.| 7629 7630**Example** 7631 7632```ts 7633audioRenderer.on('markReach', 1000, (position: number) => { 7634 if (position == 1000) { 7635 console.info('ON Triggered successfully'); 7636 } 7637}); 7638``` 7639 7640 7641### off('markReach')<sup>8+</sup> 7642 7643off(type: 'markReach'): void 7644 7645Unsubscribes from the mark reached event. 7646 7647**System capability**: SystemCapability.Multimedia.Audio.Renderer 7648 7649**Parameters** 7650 7651| Name| Type | Mandatory| Description | 7652| :----- | :----- | :--- | :------------------------------------------------ | 7653| type | string | Yes | Event type. The value is fixed at **'markReach'**.| 7654 7655**Example** 7656 7657```ts 7658audioRenderer.off('markReach'); 7659``` 7660 7661### on('periodReach')<sup>8+</sup> 7662 7663on(type: 'periodReach', frame: number, callback: Callback<number>): void 7664 7665Subscribes 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. 7666 7667For 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. 7668 7669**System capability**: SystemCapability.Multimedia.Audio.Renderer 7670 7671**Parameters** 7672 7673| Name | Type | Mandatory| Description | 7674| :------- | :----------------------- | :--- | :------------------------------------------ | 7675| type | string | Yes | Event type. The value is fixed at **'periodReach'**.| 7676| frame | number | Yes | Number of frames to trigger the event. The value must be greater than **0**. | 7677| callback | Callback\<number> | Yes | Callback used to return the value of the **frame** parameter.| 7678 7679**Example** 7680 7681```ts 7682audioRenderer.on('periodReach', 1000, (position: number) => { 7683 if (position == 1000) { 7684 console.info('ON Triggered successfully'); 7685 } 7686}); 7687``` 7688 7689### off('periodReach')<sup>8+</sup> 7690 7691off(type: 'periodReach'): void 7692 7693Unsubscribes from the period reached event. 7694 7695**System capability**: SystemCapability.Multimedia.Audio.Renderer 7696 7697**Parameters** 7698 7699| Name| Type | Mandatory| Description | 7700| :----- | :----- | :--- | :-------------------------------------------------- | 7701| type | string | Yes | Event type. The value is fixed at **'periodReach'**.| 7702 7703**Example** 7704 7705```ts 7706audioRenderer.off('periodReach'); 7707``` 7708 7709### on('stateChange')<sup>8+</sup> 7710 7711on(type: 'stateChange', callback: Callback<AudioState\>): void 7712 7713Subscribes 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. 7714 7715**System capability**: SystemCapability.Multimedia.Audio.Renderer 7716 7717**Parameters** 7718 7719| Name | Type | Mandatory| Description | 7720| :------- | :------------------------- | :--- | :------------------------------------------ | 7721| type | string | Yes | Event type. The value is fixed at **'stateChange'**.| 7722| callback | Callback\<[AudioState](#audiostate8)> | Yes | Callback used to return the audio status.| 7723 7724**Example** 7725 7726```ts 7727audioRenderer.on('stateChange', (state: audio.AudioState) => { 7728 if (state == 1) { 7729 console.info('audio renderer state is: STATE_PREPARED'); 7730 } 7731 if (state == 2) { 7732 console.info('audio renderer state is: STATE_RUNNING'); 7733 } 7734}); 7735``` 7736 7737### on('outputDeviceChange')<sup>10+</sup> 7738 7739on(type: 'outputDeviceChange', callback: Callback\<AudioDeviceDescriptors>): void 7740 7741Subscribes 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. 7742 7743**System capability**: SystemCapability.Multimedia.Audio.Device 7744 7745**Parameters** 7746 7747| Name | Type | Mandatory| Description | 7748| :------- | :------------------------- | :--- | :------------------------------------------ | 7749| type | string | Yes | Event type. The value is fixed at **'outputDeviceChange'**.| 7750| callback | Callback\<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Yes | Callback used to return the output device descriptor of the current audio stream.| 7751 7752**Error codes** 7753 7754For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7755 7756| ID| Error Message| 7757| ------- | --------------------------------------------| 7758| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7759| 6800101 | Parameter verification failed. | 7760 7761**Example** 7762 7763```ts 7764audioRenderer.on('outputDeviceChange', (deviceInfo: audio.AudioDeviceDescriptors) => { 7765 console.info(`DeviceInfo id: ${deviceInfo[0].id}`); 7766 console.info(`DeviceInfo name: ${deviceInfo[0].name}`); 7767 console.info(`DeviceInfo address: ${deviceInfo[0].address}`); 7768}); 7769``` 7770 7771### off('outputDeviceChange')<sup>10+</sup> 7772 7773off(type: 'outputDeviceChange', callback?: Callback\<AudioDeviceDescriptors>): void 7774 7775Unsubscribes from the audio output device change event. 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 **'outputDeviceChange'**.| 7784| callback | Callback\<[AudioDeviceDescriptors](#audiodevicedescriptors)> | No | Callback used to return the output device descriptor of the current audio stream.| 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 7798// Cancel all subscriptions to the event. 7799audioRenderer.off('outputDeviceChange'); 7800 7801// 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. 7802let outputDeviceChangeCallback = (deviceInfo: audio.AudioDeviceDescriptors) => { 7803 console.info(`DeviceInfo id: ${deviceInfo[0].id}`); 7804 console.info(`DeviceInfo name: ${deviceInfo[0].name}`); 7805 console.info(`DeviceInfo address: ${deviceInfo[0].address}`); 7806}; 7807 7808audioRenderer.on('outputDeviceChange', outputDeviceChangeCallback); 7809 7810audioRenderer.off('outputDeviceChange', outputDeviceChangeCallback); 7811``` 7812 7813### on('outputDeviceChangeWithInfo')<sup>11+</sup> 7814 7815on(type: 'outputDeviceChangeWithInfo', callback: Callback\<AudioStreamDeviceChangeInfo>): void 7816 7817Subscribes 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. 7818 7819**System capability**: SystemCapability.Multimedia.Audio.Device 7820 7821**Parameters** 7822 7823| Name | Type | Mandatory| Description | 7824| :------- |:-------------------------------------------------------------------------| :--- |:--------------------------------------------| 7825| type | string | Yes | Event type. The value is fixed at **'outputDeviceChangeWithInfo'**.| 7826| callback | Callback\<[AudioStreamDeviceChangeInfo](#audiostreamdevicechangeinfo11)> | Yes | Callback used to return the output device descriptor of the current audio stream and the change reason.| 7827 7828**Error codes** 7829 7830For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7831 7832| ID| Error Message| 7833| ------- | --------------------------------------------| 7834| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7835| 6800101 | Parameter verification failed. | 7836 7837**Example** 7838 7839```ts 7840audioRenderer.on('outputDeviceChangeWithInfo', (deviceChangeInfo: audio.AudioStreamDeviceChangeInfo) => { 7841 console.info(`DeviceInfo id: ${deviceChangeInfo.devices[0].id}`); 7842 console.info(`DeviceInfo name: ${deviceChangeInfo.devices[0].name}`); 7843 console.info(`DeviceInfo address: ${deviceChangeInfo.devices[0].address}`); 7844 console.info(`Device change reason: ${deviceChangeInfo.changeReason}`); 7845}); 7846``` 7847 7848### off('outputDeviceChangeWithInfo')<sup>11+</sup> 7849 7850off(type: 'outputDeviceChangeWithInfo', callback?: Callback\<AudioStreamDeviceChangeInfo>): void 7851 7852Unsubscribes from audio output device changes and reasons. This API uses an asynchronous callback to return the result. 7853 7854**System capability**: SystemCapability.Multimedia.Audio.Device 7855 7856**Parameters** 7857 7858| Name | Type | Mandatory| Description | 7859| :------- |:-------------------------------------------------------------------------| :--- |:--------------------------------------------| 7860| type | string | Yes | Event type. The value is fixed at **'outputDeviceChangeWithInfo'**.| 7861| callback | Callback\<[AudioStreamDeviceChangeInfo](#audiostreamdevicechangeinfo11)> | No | Callback used to return the output device descriptor of the current audio stream and the change reason.| 7862 7863**Error codes** 7864 7865For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7866 7867| ID| Error Message| 7868| ------- | --------------------------------------------| 7869| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7870| 6800101 | Parameter verification failed. | 7871 7872**Example** 7873 7874```ts 7875// Cancel all subscriptions to the event. 7876audioRenderer.off('outputDeviceChangeWithInfo'); 7877 7878// 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. 7879let outputDeviceChangeWithInfoCallback = (deviceChangeInfo: audio.AudioStreamDeviceChangeInfo) => { 7880 console.info(`DeviceInfo id: ${deviceChangeInfo.devices[0].id}`); 7881 console.info(`DeviceInfo name: ${deviceChangeInfo.devices[0].name}`); 7882 console.info(`DeviceInfo address: ${deviceChangeInfo.devices[0].address}`); 7883 console.info(`Device change reason: ${deviceChangeInfo.changeReason}`); 7884}; 7885 7886audioRenderer.on('outputDeviceChangeWithInfo', outputDeviceChangeWithInfoCallback); 7887 7888audioRenderer.off('outputDeviceChangeWithInfo', outputDeviceChangeWithInfoCallback); 7889``` 7890 7891### on('writeData')<sup>11+</sup> 7892 7893on(type: 'writeData', callback: AudioRendererWriteDataCallback): void 7894 7895Subscribes 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. 7896 7897The callback function is used only to write audio data. Do not call AudioRenderer APIs in it. 7898 7899**System capability**: SystemCapability.Multimedia.Audio.Renderer 7900 7901**Parameters** 7902 7903| Name | Type | Mandatory| Description | 7904| :------- |:--------------------------------| :--- |:--------------------------------------| 7905| type | string | Yes | Event type. The value is fixed at **'writeData'**.| 7906| 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). | 7907 7908**Error codes** 7909 7910For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7911 7912| ID| Error Message| 7913| ------- | --------------------------------------------| 7914| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7915| 6800101 | Parameter verification failed. | 7916 7917**Example** 7918 7919```ts 7920import { BusinessError } from '@kit.BasicServicesKit'; 7921import {fileIo as fs} from '@kit.CoreFileKit'; 7922 7923class Options { 7924 offset?: number; 7925 length?: number; 7926} 7927 7928let bufferSize: number = 0; 7929let path = getContext().cacheDir; 7930// Ensure that the resource exists in the path. 7931let filePath = path + '/StarWars10s-2C-48000-4SW.wav'; 7932let file: fs.File = fs.openSync(filePath, fs.OpenMode.READ_ONLY); 7933let writeDataCallback = (buffer: ArrayBuffer) => { 7934 let options: Options = { 7935 offset: bufferSize, 7936 length: buffer.byteLength 7937 }; 7938 7939 try { 7940 fs.readSync(file.fd, buffer, options); 7941 bufferSize += buffer.byteLength; 7942 // This API does not return a callback result in API version 11, but does so in API version 12 and later versions. 7943 return audio.AudioDataCallbackResult.VALID; 7944 } catch (error) { 7945 console.error('Error reading file:', error); 7946 // This API does not return a callback result in API version 11, but does so in API version 12 and later versions. 7947 return audio.AudioDataCallbackResult.INVALID; 7948 } 7949}; 7950 7951audioRenderer.on('writeData', writeDataCallback); 7952audioRenderer.start().then(() => { 7953 console.info('Renderer started'); 7954}).catch((err: BusinessError) => { 7955 console.error(`ERROR: ${err}`); 7956}); 7957``` 7958 7959### off('writeData')<sup>11+</sup> 7960 7961off(type: 'writeData', callback?: AudioRendererWriteDataCallback): void 7962 7963Unsubscribes from the audio data write event. This API uses an asynchronous callback to return the result. 7964 7965**System capability**: SystemCapability.Multimedia.Audio.Renderer 7966 7967**Parameters** 7968 7969| Name | Type | Mandatory| Description | 7970| :------- |:--------------------------------| :--- |:--------------------------------------| 7971| type | string | Yes | Event type. The value is fixed at **'writeData'**.| 7972| 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).| 7973 7974**Error codes** 7975 7976For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7977 7978| ID| Error Message| 7979| ------- | --------------------------------------------| 7980| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7981| 6800101 | Parameter verification failed. | 7982 7983**Example** 7984 7985```ts 7986// Cancel all subscriptions to the event. 7987audioRenderer.off('writeData'); 7988 7989// 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. 7990let writeDataCallback = (data: ArrayBuffer) => { 7991 console.info(`write data: ${data}`); 7992}; 7993 7994audioRenderer.on('writeData', writeDataCallback); 7995 7996audioRenderer.off('writeData', writeDataCallback); 7997``` 7998 7999## AudioCapturer<sup>8+</sup> 8000 8001Provides APIs for audio capture. Before calling any API in **AudioCapturer**, you must use [createAudioCapturer](#audiocreateaudiocapturer8) to create an **AudioCapturer** instance. 8002 8003### Attributes 8004 8005**System capability**: SystemCapability.Multimedia.Audio.Capturer 8006 8007| Name | Type | Readable| Writable| Description | 8008| :---- | :------------------------- | :--- | :--- | :--------------- | 8009| state<sup>8+</sup> | [AudioState](#audiostate8) | Yes| No | Audio capturer state.| 8010 8011**Example** 8012 8013```ts 8014import { audio } from '@kit.AudioKit'; 8015 8016let state: audio.AudioState = audioCapturer.state; 8017``` 8018 8019### getCapturerInfo<sup>8+</sup> 8020 8021getCapturerInfo(callback: AsyncCallback<AudioCapturerInfo\>): void 8022 8023Obtains the capturer information of this **AudioCapturer** instance. This API uses an asynchronous callback to return the result. 8024 8025**System capability**: SystemCapability.Multimedia.Audio.Capturer 8026 8027**Parameters** 8028 8029| Name | Type | Mandatory| Description | 8030| :------- | :-------------------------------- | :--- | :----------------------------------- | 8031| 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.| 8032 8033**Example** 8034 8035```ts 8036import { BusinessError } from '@kit.BasicServicesKit'; 8037 8038audioCapturer.getCapturerInfo((err: BusinessError, capturerInfo: audio.AudioCapturerInfo) => { 8039 if (err) { 8040 console.error('Failed to get capture info'); 8041 } else { 8042 console.info('Capturer getCapturerInfo:'); 8043 console.info(`Capturer source: ${capturerInfo.source}`); 8044 console.info(`Capturer flags: ${capturerInfo.capturerFlags}`); 8045 } 8046}); 8047``` 8048 8049 8050### getCapturerInfo<sup>8+</sup> 8051 8052getCapturerInfo(): Promise<AudioCapturerInfo\> 8053 8054Obtains the capturer information of this **AudioCapturer** instance. This API uses a promise to return the result. 8055 8056**System capability**: SystemCapability.Multimedia.Audio.Capturer 8057 8058**Return value** 8059 8060| Type | Description | 8061| :------------------------------------------------ | :---------------------------------- | 8062| Promise<[AudioCapturerInfo](#audiocapturerinfo8)\> | Promise used to return capturer information.| 8063 8064**Example** 8065 8066```ts 8067import { BusinessError } from '@kit.BasicServicesKit'; 8068 8069audioCapturer.getCapturerInfo().then((audioParamsGet: audio.AudioCapturerInfo) => { 8070 if (audioParamsGet != undefined) { 8071 console.info('AudioFrameworkRecLog: Capturer CapturerInfo:'); 8072 console.info(`AudioFrameworkRecLog: Capturer SourceType: ${audioParamsGet.source}`); 8073 console.info(`AudioFrameworkRecLog: Capturer capturerFlags: ${audioParamsGet.capturerFlags}`); 8074 } else { 8075 console.info(`AudioFrameworkRecLog: audioParamsGet is : ${audioParamsGet}`); 8076 console.info('AudioFrameworkRecLog: audioParams getCapturerInfo are incorrect'); 8077 } 8078}).catch((err: BusinessError) => { 8079 console.error(`AudioFrameworkRecLog: CapturerInfo :ERROR: ${err}`); 8080}) 8081``` 8082 8083### getCapturerInfoSync<sup>10+</sup> 8084 8085getCapturerInfoSync(): AudioCapturerInfo 8086 8087Obtains the capturer information of this **AudioCapturer** instance. This API returns the result synchronously. 8088 8089**System capability**: SystemCapability.Multimedia.Audio.Capturer 8090 8091**Return value** 8092 8093| Type | Description | 8094| :------------------------------------------------ | :---------------------------------- | 8095| [AudioCapturerInfo](#audiocapturerinfo8) | Capturer information.| 8096 8097**Example** 8098 8099```ts 8100import { BusinessError } from '@kit.BasicServicesKit'; 8101 8102try { 8103 let audioParamsGet: audio.AudioCapturerInfo = audioCapturer.getCapturerInfoSync(); 8104 console.info(`AudioFrameworkRecLog: Capturer SourceType: ${audioParamsGet.source}`); 8105 console.info(`AudioFrameworkRecLog: Capturer capturerFlags: ${audioParamsGet.capturerFlags}`); 8106} catch (err) { 8107 let error = err as BusinessError; 8108 console.error(`AudioFrameworkRecLog: CapturerInfo :ERROR: ${error}`); 8109} 8110``` 8111 8112### getStreamInfo<sup>8+</sup> 8113 8114getStreamInfo(callback: AsyncCallback<AudioStreamInfo\>): void 8115 8116Obtains the stream information of this **AudioCapturer** instance. This API uses an asynchronous callback to return the result. 8117 8118**System capability**: SystemCapability.Multimedia.Audio.Capturer 8119 8120**Parameters** 8121 8122| Name | Type | Mandatory| Description | 8123| :------- | :--------------------------------------------------- | :--- | :------------------------------- | 8124| 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.| 8125 8126**Example** 8127 8128```ts 8129import { BusinessError } from '@kit.BasicServicesKit'; 8130 8131audioCapturer.getStreamInfo((err: BusinessError, streamInfo: audio.AudioStreamInfo) => { 8132 if (err) { 8133 console.error('Failed to get stream info'); 8134 } else { 8135 console.info('Capturer GetStreamInfo:'); 8136 console.info(`Capturer sampling rate: ${streamInfo.samplingRate}`); 8137 console.info(`Capturer channel: ${streamInfo.channels}`); 8138 console.info(`Capturer format: ${streamInfo.sampleFormat}`); 8139 console.info(`Capturer encoding type: ${streamInfo.encodingType}`); 8140 } 8141}); 8142``` 8143 8144### getStreamInfo<sup>8+</sup> 8145 8146getStreamInfo(): Promise<AudioStreamInfo\> 8147 8148Obtains the stream information of this **AudioCapturer** instance. This API uses a promise to return the result. 8149 8150**System capability**: SystemCapability.Multimedia.Audio.Capturer 8151 8152**Return value** 8153 8154| Type | Description | 8155| :--------------------------------------------- | :------------------------------ | 8156| Promise<[AudioStreamInfo](#audiostreaminfo8)\> | Promise used to return the stream information.| 8157 8158**Example** 8159 8160```ts 8161import { BusinessError } from '@kit.BasicServicesKit'; 8162 8163audioCapturer.getStreamInfo().then((audioParamsGet: audio.AudioStreamInfo) => { 8164 console.info('getStreamInfo:'); 8165 console.info(`sampleFormat: ${audioParamsGet.sampleFormat}`); 8166 console.info(`samplingRate: ${audioParamsGet.samplingRate}`); 8167 console.info(`channels: ${audioParamsGet.channels}`); 8168 console.info(`encodingType: ${audioParamsGet.encodingType}`); 8169}).catch((err: BusinessError) => { 8170 console.error(`getStreamInfo :ERROR: ${err}`); 8171}); 8172``` 8173 8174### getStreamInfoSync<sup>10+</sup> 8175 8176getStreamInfoSync(): AudioStreamInfo 8177 8178Obtains the stream information of this **AudioCapturer** instance. This API returns the result synchronously. 8179 8180**System capability**: SystemCapability.Multimedia.Audio.Capturer 8181 8182**Return value** 8183 8184| Type | Description | 8185| :--------------------------------------------- | :------------------------------ | 8186| [AudioStreamInfo](#audiostreaminfo8) | Stream information.| 8187 8188**Example** 8189 8190```ts 8191import { BusinessError } from '@kit.BasicServicesKit'; 8192 8193try { 8194 let audioParamsGet: audio.AudioStreamInfo = audioCapturer.getStreamInfoSync(); 8195 console.info(`sampleFormat: ${audioParamsGet.sampleFormat}`); 8196 console.info(`samplingRate: ${audioParamsGet.samplingRate}`); 8197 console.info(`channels: ${audioParamsGet.channels}`); 8198 console.info(`encodingType: ${audioParamsGet.encodingType}`); 8199} catch (err) { 8200 let error = err as BusinessError; 8201 console.error(`getStreamInfo :ERROR: ${error}`); 8202} 8203``` 8204 8205### getAudioStreamId<sup>9+</sup> 8206 8207getAudioStreamId(callback: AsyncCallback<number\>): void 8208 8209Obtains the stream ID of this **AudioCapturer** instance. This API uses an asynchronous callback to return the result. 8210 8211**System capability**: SystemCapability.Multimedia.Audio.Capturer 8212 8213**Parameters** 8214 8215| Name | Type | Mandatory| Description | 8216| :------- | :--------------------------------------------------- | :--- | :------------------- | 8217| 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.| 8218 8219**Example** 8220 8221```ts 8222import { BusinessError } from '@kit.BasicServicesKit'; 8223 8224audioCapturer.getAudioStreamId((err: BusinessError, streamId: number) => { 8225 console.info(`audioCapturer GetStreamId: ${streamId}`); 8226}); 8227``` 8228 8229### getAudioStreamId<sup>9+</sup> 8230 8231getAudioStreamId(): Promise<number\> 8232 8233Obtains the stream ID of this **AudioCapturer** instance. This API uses a promise to return the result. 8234 8235**System capability**: SystemCapability.Multimedia.Audio.Capturer 8236 8237**Return value** 8238 8239| Type | Description | 8240| :----------------| :--------------------- | 8241| Promise<number\> | Promise used to return the stream ID.| 8242 8243**Example** 8244 8245```ts 8246import { BusinessError } from '@kit.BasicServicesKit'; 8247 8248audioCapturer.getAudioStreamId().then((streamId: number) => { 8249 console.info(`audioCapturer getAudioStreamId: ${streamId}`); 8250}).catch((err: BusinessError) => { 8251 console.error(`ERROR: ${err}`); 8252}); 8253``` 8254 8255### getAudioStreamIdSync<sup>10+</sup> 8256 8257getAudioStreamIdSync(): number 8258 8259Obtains the stream ID of this **AudioCapturer** instance. This API returns the result synchronously. 8260 8261**System capability**: SystemCapability.Multimedia.Audio.Capturer 8262 8263**Return value** 8264 8265| Type | Description | 8266| :----------------| :--------------------- | 8267| number | Stream ID.| 8268 8269**Example** 8270 8271```ts 8272import { BusinessError } from '@kit.BasicServicesKit'; 8273 8274try { 8275 let streamId: number = audioCapturer.getAudioStreamIdSync(); 8276 console.info(`audioCapturer getAudioStreamIdSync: ${streamId}`); 8277} catch (err) { 8278 let error = err as BusinessError; 8279 console.error(`ERROR: ${error}`); 8280} 8281``` 8282 8283### start<sup>8+</sup> 8284 8285start(callback: AsyncCallback<void\>): void 8286 8287Starts capturing. This API uses an asynchronous callback to return the result. 8288 8289**System capability**: SystemCapability.Multimedia.Audio.Capturer 8290 8291**Parameters** 8292 8293| Name | Type | Mandatory| Description | 8294| :------- | :------------------- | :--- | :----------------------------- | 8295| 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.| 8296 8297**Example** 8298 8299```ts 8300import { BusinessError } from '@kit.BasicServicesKit'; 8301 8302audioCapturer.start((err: BusinessError) => { 8303 if (err) { 8304 console.error('Capturer start failed.'); 8305 } else { 8306 console.info('Capturer start success.'); 8307 } 8308}); 8309``` 8310 8311 8312### start<sup>8+</sup> 8313 8314start(): Promise<void\> 8315 8316Starts capturing. This API uses a promise to return the result. 8317 8318**System capability**: SystemCapability.Multimedia.Audio.Capturer 8319 8320**Return value** 8321 8322| Type | Description | 8323| :------------- | :---------------------------- | 8324| 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.| 8325 8326**Example** 8327 8328```ts 8329import { BusinessError } from '@kit.BasicServicesKit'; 8330 8331audioCapturer.start().then(() => { 8332 console.info('AudioFrameworkRecLog: ---------START---------'); 8333 console.info('AudioFrameworkRecLog: Capturer started: SUCCESS'); 8334 console.info(`AudioFrameworkRecLog: AudioCapturer: STATE: ${audioCapturer.state}`); 8335 console.info('AudioFrameworkRecLog: Capturer started: SUCCESS'); 8336 if ((audioCapturer.state == audio.AudioState.STATE_RUNNING)) { 8337 console.info('AudioFrameworkRecLog: AudioCapturer is in Running State'); 8338 } 8339}).catch((err: BusinessError) => { 8340 console.error(`AudioFrameworkRecLog: Capturer start :ERROR : ${err}`); 8341}); 8342``` 8343 8344### stop<sup>8+</sup> 8345 8346stop(callback: AsyncCallback<void\>): void 8347 8348Stops capturing. This API uses an asynchronous callback to return the result. 8349 8350**System capability**: SystemCapability.Multimedia.Audio.Capturer 8351 8352**Parameters** 8353 8354| Name | Type | Mandatory| Description | 8355| :------- | :------------------- | :--- | :----------------------------- | 8356| callback | AsyncCallback<void\> | Yes | Callback used to return the result. If the vibration stops, **err** is **undefined**; otherwise, **err** is an error object.| 8357 8358**Example** 8359 8360```ts 8361import { BusinessError } from '@kit.BasicServicesKit'; 8362 8363audioCapturer.stop((err: BusinessError) => { 8364 if (err) { 8365 console.error('Capturer stop failed'); 8366 } else { 8367 console.info('Capturer stopped.'); 8368 } 8369}); 8370``` 8371 8372 8373### stop<sup>8+</sup> 8374 8375stop(): Promise<void\> 8376 8377Stops capturing. This API uses a promise to return the result. 8378 8379**System capability**: SystemCapability.Multimedia.Audio.Capturer 8380 8381**Return value** 8382 8383| Type | Description | 8384| :------------- | :---------------------------- | 8385| Promise<void\> | Promise that returns no value.| 8386 8387**Example** 8388 8389```ts 8390import { BusinessError } from '@kit.BasicServicesKit'; 8391 8392audioCapturer.stop().then(() => { 8393 console.info('AudioFrameworkRecLog: ---------STOP RECORD---------'); 8394 console.info('AudioFrameworkRecLog: Capturer stopped: SUCCESS'); 8395 if ((audioCapturer.state == audio.AudioState.STATE_STOPPED)){ 8396 console.info('AudioFrameworkRecLog: State is Stopped:'); 8397 } 8398}).catch((err: BusinessError) => { 8399 console.error(`AudioFrameworkRecLog: Capturer stop: ERROR: ${err}`); 8400}); 8401``` 8402 8403### release<sup>8+</sup> 8404 8405release(callback: AsyncCallback<void\>): void 8406 8407Releases this **AudioCapturer** instance. This API uses an asynchronous callback to return the result. 8408 8409**System capability**: SystemCapability.Multimedia.Audio.Capturer 8410 8411**Parameters** 8412 8413| Name | Type | Mandatory| Description | 8414| :------- | :------------------- | :--- | :---------------------------------- | 8415| callback | AsyncCallback<void\> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 8416 8417**Example** 8418 8419```ts 8420import { BusinessError } from '@kit.BasicServicesKit'; 8421 8422audioCapturer.release((err: BusinessError) => { 8423 if (err) { 8424 console.error('capturer release failed'); 8425 } else { 8426 console.info('capturer released.'); 8427 } 8428}); 8429``` 8430 8431 8432### release<sup>8+</sup> 8433 8434release(): Promise<void\> 8435 8436Releases this **AudioCapturer** instance. This API uses a promise to return the result. 8437 8438**System capability**: SystemCapability.Multimedia.Audio.Capturer 8439 8440**Return value** 8441 8442| Type | Description | 8443| :------------- | :---------------------------- | 8444| Promise<void\> | Promise that returns no value.| 8445 8446**Example** 8447 8448```ts 8449import { BusinessError } from '@kit.BasicServicesKit'; 8450 8451audioCapturer.release().then(() => { 8452 console.info('AudioFrameworkRecLog: ---------RELEASE RECORD---------'); 8453 console.info('AudioFrameworkRecLog: Capturer release : SUCCESS'); 8454 console.info(`AudioFrameworkRecLog: AudioCapturer : STATE : ${audioCapturer.state}`); 8455}).catch((err: BusinessError) => { 8456 console.error(`AudioFrameworkRecLog: Capturer stop: ERROR: ${err}`); 8457}); 8458``` 8459 8460### read<sup>8+(deprecated)</sup> 8461 8462read(size: number, isBlockingRead: boolean, callback: AsyncCallback<ArrayBuffer\>): void 8463 8464Reads the buffer. This API uses an asynchronous callback to return the result. 8465 8466> **NOTE** 8467> 8468> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [on('readData')](#onreaddata11) in **AudioCapturer**. 8469 8470**System capability**: SystemCapability.Multimedia.Audio.Capturer 8471 8472**Parameters** 8473 8474| Name | Type | Mandatory| Description | 8475| :------------- | :-------------------------- | :--- | :------------------------------- | 8476| size | number | Yes | Number of bytes to read. | 8477| isBlockingRead | boolean | Yes | Whether to block the read operation. The value **true** means to block the read operation, and **false** means the opposite. | 8478| 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.| 8479 8480**Example** 8481 8482```ts 8483import { BusinessError } from '@kit.BasicServicesKit'; 8484 8485let bufferSize: number = 0; 8486 8487audioCapturer.getBufferSize().then((data: number) => { 8488 console.info(`AudioFrameworkRecLog: getBufferSize: SUCCESS ${data}`); 8489 bufferSize = data; 8490}).catch((err: BusinessError) => { 8491 console.error(`AudioFrameworkRecLog: getBufferSize: ERROR: ${err}`); 8492}); 8493 8494audioCapturer.read(bufferSize, true, (err: BusinessError, buffer: ArrayBuffer) => { 8495 if (!err) { 8496 console.info('Success in reading the buffer data'); 8497 } 8498}); 8499``` 8500 8501### read<sup>8+(deprecated)</sup> 8502 8503read(size: number, isBlockingRead: boolean): Promise<ArrayBuffer\> 8504 8505Reads the buffer. This API uses a promise to return the result. 8506 8507> **NOTE** 8508> 8509> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [on('readData')](#onreaddata11) in **AudioCapturer**. 8510 8511**System capability**: SystemCapability.Multimedia.Audio.Capturer 8512 8513**Parameters** 8514 8515| Name | Type | Mandatory| Description | 8516| :------------- | :------ | :--- | :--------------- | 8517| size | number | Yes | Number of bytes to read. | 8518| isBlockingRead | boolean | Yes | Whether to block the read operation. The value **true** means to block the read operation, and **false** means the opposite.| 8519 8520**Return value** 8521 8522| Type | Description | 8523| :-------------------- | :----------------------------------------------------- | 8524| Promise<ArrayBuffer\> | Promise used to return the data read from the buffer.| 8525 8526**Example** 8527 8528```ts 8529import { BusinessError } from '@kit.BasicServicesKit'; 8530 8531let bufferSize: number = 0; 8532 8533audioCapturer.getBufferSize().then((data: number) => { 8534 console.info(`AudioFrameworkRecLog: getBufferSize: SUCCESS ${data}`); 8535 bufferSize = data; 8536}).catch((err: BusinessError) => { 8537 console.error(`AudioFrameworkRecLog: getBufferSize: ERROR ${err}`); 8538}); 8539console.info(`Buffer size: ${bufferSize}`); 8540 8541audioCapturer.read(bufferSize, true).then((buffer: ArrayBuffer) => { 8542 console.info('buffer read successfully'); 8543}).catch((err: BusinessError) => { 8544 console.error(`ERROR : ${err}`); 8545}); 8546``` 8547 8548### getAudioTime<sup>8+</sup> 8549 8550getAudioTime(callback: AsyncCallback<number\>): void 8551 8552Obtains 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. 8553 8554**System capability**: SystemCapability.Multimedia.Audio.Capturer 8555 8556**Parameters** 8557 8558| Name | Type | Mandatory| Description | 8559| :------- | :--------------------- | :--- | :----------------------------- | 8560| 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.| 8561 8562**Example** 8563 8564```ts 8565import { BusinessError } from '@kit.BasicServicesKit'; 8566 8567audioCapturer.getAudioTime((err: BusinessError, timestamp: number) => { 8568 console.info(`Current timestamp: ${timestamp}`); 8569}); 8570``` 8571 8572### getAudioTime<sup>8+</sup> 8573 8574getAudioTime(): Promise<number\> 8575 8576Obtains 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. 8577 8578**System capability**: SystemCapability.Multimedia.Audio.Capturer 8579 8580**Return value** 8581 8582| Type | Description | 8583| :--------------- | :---------------------------- | 8584| Promise<number\> | Promise used to return the number of nanoseconds elapsed from the Unix epoch.| 8585 8586**Example** 8587 8588```ts 8589import { BusinessError } from '@kit.BasicServicesKit'; 8590 8591audioCapturer.getAudioTime().then((audioTime: number) => { 8592 console.info(`AudioFrameworkRecLog: AudioCapturer getAudioTime : Success ${audioTime}`); 8593}).catch((err: BusinessError) => { 8594 console.error(`AudioFrameworkRecLog: AudioCapturer Created : ERROR : ${err}`); 8595}); 8596``` 8597 8598### getAudioTimeSync<sup>10+</sup> 8599 8600getAudioTimeSync(): number 8601 8602Obtains the timestamp of the current recording position, measured in nanoseconds from the Unix epoch (January 1, 1970). This API returns the result synchronously: 8603 8604**System capability**: SystemCapability.Multimedia.Audio.Capturer 8605 8606**Return value** 8607 8608| Type | Description | 8609| :--------------- | :---------------------------- | 8610| number | Timestamp.| 8611 8612**Example** 8613 8614```ts 8615import { BusinessError } from '@kit.BasicServicesKit'; 8616 8617try { 8618 let audioTime: number = audioCapturer.getAudioTimeSync(); 8619 console.info(`AudioFrameworkRecLog: AudioCapturer getAudioTimeSync : Success ${audioTime}`); 8620} catch (err) { 8621 let error = err as BusinessError; 8622 console.error(`AudioFrameworkRecLog: AudioCapturer getAudioTimeSync : ERROR : ${error}`); 8623} 8624``` 8625 8626### getBufferSize<sup>8+</sup> 8627 8628getBufferSize(callback: AsyncCallback<number\>): void 8629 8630Obtains a reasonable minimum buffer size in bytes for capturing. This API uses an asynchronous callback to return the result. 8631 8632**System capability**: SystemCapability.Multimedia.Audio.Capturer 8633 8634**Parameters** 8635 8636| Name | Type | Mandatory| Description | 8637| :------- | :--------------------- | :--- | :----------------------------------- | 8638| 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.| 8639 8640**Example** 8641 8642```ts 8643import { BusinessError } from '@kit.BasicServicesKit'; 8644 8645audioCapturer.getBufferSize((err: BusinessError, bufferSize: number) => { 8646 if (!err) { 8647 console.info(`BufferSize : ${bufferSize}`); 8648 audioCapturer.read(bufferSize, true).then((buffer: ArrayBuffer) => { 8649 console.info(`Buffer read is ${buffer.byteLength}`); 8650 }).catch((err: BusinessError) => { 8651 console.error(`AudioFrameworkRecLog: AudioCapturer Created : ERROR : ${err}`); 8652 }); 8653 } 8654}); 8655``` 8656 8657### getBufferSize<sup>8+</sup> 8658 8659getBufferSize(): Promise<number\> 8660 8661Obtains a reasonable minimum buffer size in bytes for capturing. This API uses a promise to return the result. 8662 8663**System capability**: SystemCapability.Multimedia.Audio.Capturer 8664 8665**Return value** 8666 8667| Type | Description | 8668| :--------------- | :---------------------------------- | 8669| Promise<number\> | Promise used to return the buffer size.| 8670 8671**Example** 8672 8673```ts 8674import { BusinessError } from '@kit.BasicServicesKit'; 8675 8676let bufferSize: number = 0; 8677 8678audioCapturer.getBufferSize().then((data: number) => { 8679 console.info(`AudioFrameworkRecLog: getBufferSize :SUCCESS ${data}`); 8680 bufferSize = data; 8681}).catch((err: BusinessError) => { 8682 console.error(`AudioFrameworkRecLog: getBufferSize :ERROR : ${err}`); 8683}); 8684``` 8685 8686### getBufferSizeSync<sup>10+</sup> 8687 8688getBufferSizeSync(): number 8689 8690Obtains a reasonable minimum buffer size in bytes for capturing. This API returns the result synchronously. 8691 8692**System capability**: SystemCapability.Multimedia.Audio.Capturer 8693 8694**Return value** 8695 8696| Type | Description | 8697| :--------------- | :---------------------------------- | 8698| number | Buffer size.| 8699 8700**Example** 8701 8702```ts 8703import { BusinessError } from '@kit.BasicServicesKit'; 8704 8705let bufferSize: number = 0; 8706 8707try { 8708 bufferSize = audioCapturer.getBufferSizeSync(); 8709 console.info(`AudioFrameworkRecLog: getBufferSizeSync :SUCCESS ${bufferSize}`); 8710} catch (err) { 8711 let error = err as BusinessError; 8712 console.error(`AudioFrameworkRecLog: getBufferSizeSync :ERROR : ${error}`); 8713} 8714``` 8715 8716### getCurrentInputDevices<sup>11+</sup> 8717 8718getCurrentInputDevices(): AudioDeviceDescriptors 8719 8720Obtains the descriptors of the current input devices. This API returns the result synchronously. 8721 8722**System capability**: SystemCapability.Multimedia.Audio.Device 8723 8724**Return value** 8725 8726| Type | Description | 8727| ---------------------- | ------------------------------------------------------ | 8728| [AudioDeviceDescriptors](#audiodevicedescriptors) | An array of the audio device descriptors.| 8729 8730**Example** 8731 8732```ts 8733let deviceDescriptors: audio.AudioDeviceDescriptors = audioCapturer.getCurrentInputDevices(); 8734console.info(`Device id: ${deviceDescriptors[0].id}`); 8735console.info(`Device type: ${deviceDescriptors[0].deviceType}`); 8736console.info(`Device role: ${deviceDescriptors[0].deviceRole}`); 8737console.info(`Device name: ${deviceDescriptors[0].name}`); 8738console.info(`Device address: ${deviceDescriptors[0].address}`); 8739console.info(`Device samplerates: ${deviceDescriptors[0].sampleRates[0]}`); 8740console.info(`Device channelcounts: ${deviceDescriptors[0].channelCounts[0]}`); 8741console.info(`Device channelmask: ${deviceDescriptors[0].channelMasks[0]}`); 8742if (deviceDescriptors[0].encodingTypes) { 8743 console.info(`Device encodingTypes: ${deviceDescriptors[0].encodingTypes[0]}`); 8744} 8745``` 8746 8747### getCurrentAudioCapturerChangeInfo<sup>11+</sup> 8748 8749getCurrentAudioCapturerChangeInfo(): AudioCapturerChangeInfo 8750 8751Obtains the configuration changes of the current audio capturer. This API returns the result synchronously. 8752 8753**System capability**: SystemCapability.Multimedia.Audio.Device 8754 8755**Return value** 8756 8757| Type | Description | 8758| :--------------- | :---------------------------------- | 8759| [AudioCapturerChangeInfo](#audiocapturerchangeinfo9) | Configuration changes of the audio capturer.| 8760 8761**Example** 8762 8763```ts 8764let info: audio.AudioCapturerChangeInfo = audioCapturer.getCurrentAudioCapturerChangeInfo(); 8765console.info(`Info streamId: ${info.streamId}`); 8766console.info(`Info source: ${info.capturerInfo.source}`); 8767console.info(`Info capturerFlags: ${info.capturerInfo.capturerFlags}`); 8768console.info(`Info muted: ${info.muted}`); 8769console.info(`Info type: ${info.deviceDescriptors[0].deviceType}`); 8770console.info(`Info role: ${info.deviceDescriptors[0].deviceRole}`); 8771console.info(`Info name: ${info.deviceDescriptors[0].name}`); 8772console.info(`Info address: ${info.deviceDescriptors[0].address}`); 8773console.info(`Info samplerates: ${info.deviceDescriptors[0].sampleRates[0]}`); 8774console.info(`Info channelcounts: ${info.deviceDescriptors[0].channelCounts[0]}`); 8775console.info(`Info channelmask: ${info.deviceDescriptors[0].channelMasks[0]}`); 8776if (info.deviceDescriptors[0].encodingTypes) { 8777 console.info(`Device encodingTypes: ${info.deviceDescriptors[0].encodingTypes[0]}`); 8778} 8779``` 8780 8781### on('audioInterrupt')<sup>10+</sup> 8782 8783on(type: 'audioInterrupt', callback: Callback\<InterruptEvent>): void 8784 8785Subscribes to the audio interruption event, which is triggered when the audio focus is changed. This API uses an asynchronous callback to return the result. 8786 8787The **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. 8788 8789After 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). 8790 8791**System capability**: SystemCapability.Multimedia.Audio.Interrupt 8792 8793**Parameters** 8794 8795| Name | Type | Mandatory| Description | 8796| -------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | 8797| type | string | Yes | Event type. The value is fixed at **'audioInterrupt'**.| 8798| callback | Callback\<[InterruptEvent](#interruptevent9)\> | Yes | Callback used to return the audio interruption event received by the application when recording is interrupted.| 8799 8800**Error codes** 8801 8802For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 8803 8804| ID| Error Message| 8805| ------- | --------------------------------------------| 8806| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 8807| 6800101 | Parameter verification failed. | 8808 8809**Example** 8810 8811```ts 8812import { audio } from '@kit.AudioKit'; 8813 8814let isCapturing: boolean; // An identifier specifying whether capturing is in progress. 8815onAudioInterrupt(); 8816 8817async function onAudioInterrupt(){ 8818 audioCapturer.on('audioInterrupt', (interruptEvent: audio.InterruptEvent) => { 8819 // When an audio interruption event occurs, the AudioCapturer receives the interruptEvent callback and performs processing based on the content in the callback. 8820 // 1. (Optional) The AudioCapturer reads the value of interruptEvent.forceType to see whether the system has forcibly performed the operation. 8821 // 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. 8822 // 2. (Mandatory) The AudioCapturer then reads the value of interruptEvent.hintType and performs corresponding processing. 8823 if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_FORCE) { 8824 // The audio focus event has been forcibly executed by the system. The application needs to update its status and displayed content. 8825 switch (interruptEvent.hintType) { 8826 case audio.InterruptHint.INTERRUPT_HINT_PAUSE: 8827 // 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. 8828 console.info('Force paused. Update capturing status and stop reading'); 8829 isCapturing = false; // A simplified processing indicating several operations for switching the application to the paused state. 8830 break; 8831 case audio.InterruptHint.INTERRUPT_HINT_STOP: 8832 // The audio stream has been stopped and permanently loses the focus. The user must manually trigger the operation to resume capturing. 8833 console.info('Force stopped. Update capturing status and stop reading'); 8834 isCapturing = false; // A simplified processing indicating several operations for switching the application to the paused state. 8835 break; 8836 default: 8837 console.info('Invalid interruptEvent'); 8838 break; 8839 } 8840 } else if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_SHARE) { 8841 // 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. 8842 switch (interruptEvent.hintType) { 8843 case audio.InterruptHint.INTERRUPT_HINT_RESUME: 8844 // 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.) 8845 // 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. 8846 console.info('Resume force paused renderer or ignore'); 8847 // To continue capturing, the application must perform the required operations. 8848 break; 8849 default: 8850 console.info('Invalid interruptEvent'); 8851 break; 8852 } 8853 } 8854 }); 8855} 8856``` 8857 8858### off('audioInterrupt')<sup>10+</sup> 8859 8860off(type: 'audioInterrupt'): void 8861 8862Unsubscribes from the audio interruption event. 8863 8864**System capability**: SystemCapability.Multimedia.Audio.Interrupt 8865 8866**Parameters** 8867 8868| Name | Type | Mandatory| Description | 8869| -------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | 8870| type | string | Yes | Event type. The value is fixed at **'audioInterrupt'**.| 8871 8872**Error codes** 8873 8874For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 8875 8876| ID| Error Message| 8877| ------- | --------------------------------------------| 8878| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 8879| 6800101 | Parameter verification failed. | 8880 8881**Example** 8882 8883```ts 8884audioCapturer.off('audioInterrupt'); 8885``` 8886 8887### on('inputDeviceChange')<sup>11+</sup> 8888 8889on(type: 'inputDeviceChange', callback: Callback\<AudioDeviceDescriptors>): void 8890 8891Subscribes 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. 8892 8893**System capability**: SystemCapability.Multimedia.Audio.Device 8894 8895**Parameters** 8896 8897| Name | Type | Mandatory| Description | 8898| :------- | :------------------------- | :--- | :------------------------------------------ | 8899| type | string | Yes | Event type. The value is fixed at **'inputDeviceChange**.| 8900| callback | Callback\<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Yes | Callback used to return the information about the new audio input device.| 8901 8902**Error codes** 8903 8904For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 8905 8906| ID| Error Message| 8907| ------- | --------------------------------------------| 8908| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 8909| 6800101 | Parameter verification failed. | 8910 8911**Example** 8912 8913```ts 8914audioCapturer.on('inputDeviceChange', (deviceChangeInfo: audio.AudioDeviceDescriptors) => { 8915 console.info(`inputDevice id: ${deviceChangeInfo[0].id}`); 8916 console.info(`inputDevice deviceRole: ${deviceChangeInfo[0].deviceRole}`); 8917 console.info(`inputDevice deviceType: ${deviceChangeInfo[0].deviceType}`); 8918}); 8919``` 8920### off('inputDeviceChange')<sup>11+</sup> 8921 8922off(type: 'inputDeviceChange', callback?: Callback\<AudioDeviceDescriptors>): void 8923 8924Unsubscribes from the audio input device change event. This API uses an asynchronous callback to return the result. 8925 8926**System capability**: SystemCapability.Multimedia.Audio.Device 8927 8928**Parameters** 8929 8930| Name | Type | Mandatory| Description | 8931| :------- | :------------------------- | :--- |:-----------------------------------------| 8932| type | string | Yes | Event type. The value is fixed at **'inputDeviceChange**. | 8933| callback | Callback\<[AudioDeviceDescriptors](#audiodevicedescriptors)> | No | Callback used to return the information about the audio input device.| 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 8947// Cancel all subscriptions to the event. 8948audioCapturer.off('inputDeviceChange'); 8949 8950// 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. 8951let inputDeviceChangeCallback = (deviceChangeInfo: audio.AudioDeviceDescriptors) => { 8952 console.info(`inputDevice id: ${deviceChangeInfo[0].id}`); 8953 console.info(`inputDevice deviceRole: ${deviceChangeInfo[0].deviceRole}`); 8954 console.info(`inputDevice deviceType: ${deviceChangeInfo[0].deviceType}`); 8955}; 8956 8957audioCapturer.on('inputDeviceChange', inputDeviceChangeCallback); 8958 8959audioCapturer.off('inputDeviceChange', inputDeviceChangeCallback); 8960``` 8961 8962### on('audioCapturerChange')<sup>11+</sup> 8963 8964on(type: 'audioCapturerChange', callback: Callback\<AudioCapturerChangeInfo>): void 8965 8966Subscribes 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. 8967 8968**System capability**: SystemCapability.Multimedia.Audio.Capturer 8969 8970**Parameters** 8971 8972| Name | Type | Mandatory| Description | 8973| :------- | :------------------------- | :--- | :------------------------------------------ | 8974| type | string | Yes | Event type. The value is fixed at **'audioCapturerChange'**.| 8975| callback | Callback\<[AudioCapturerChangeInfo](#audiocapturerchangeinfo9)> | Yes | Callback used to return the current configuration and status information of the audio capturer.| 8976 8977**Error codes** 8978 8979For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 8980 8981| ID| Error Message| 8982| ------- | --------------------------------------------| 8983| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 8984| 6800101 | Parameter verification failed. | 8985 8986**Example** 8987 8988```ts 8989audioCapturer.on('audioCapturerChange', (capturerChangeInfo: audio.AudioCapturerChangeInfo) => { 8990 console.info(`audioCapturerChange id: ${capturerChangeInfo[0].id}`); 8991 console.info(`audioCapturerChange deviceRole: ${capturerChangeInfo[0].deviceRole}`); 8992 console.info(`audioCapturerChange deviceType: ${capturerChangeInfo[0].deviceType}`); 8993}); 8994``` 8995 8996### off('audioCapturerChange')<sup>11+</sup> 8997 8998off(type: 'audioCapturerChange', callback?: Callback\<AudioCapturerChangeInfo>): void 8999 9000Unsubscribes from the audio capturer configuration change event. This API uses an asynchronous callback to return the result. 9001 9002**System capability**: SystemCapability.Multimedia.Audio.Capturer 9003 9004**Parameters** 9005 9006| Name | Type | Mandatory| Description | 9007| :------- | :------------------------- | :--- | :------------------------------------------ | 9008| type | string | Yes | Event type. The value is fixed at **'audioCapturerChange'**.| 9009| callback | Callback\<[AudioCapturerChangeInfo](#audiocapturerchangeinfo9)> | No | Callback used for unsubscription.| 9010 9011**Error codes** 9012 9013For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 9014 9015| ID| Error Message| 9016| ------- | --------------------------------------------| 9017| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 9018| 6800101 | Parameter verification failed. | 9019 9020**Example** 9021 9022```ts 9023// Cancel all subscriptions to the event. 9024audioCapturer.off('audioCapturerChange'); 9025 9026// 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. 9027let audioCapturerChangeCallback = (capturerChangeInfo: audio.AudioCapturerChangeInfo) => { 9028 console.info(`audioCapturerChange id: ${capturerChangeInfo[0].id}`); 9029 console.info(`audioCapturerChange deviceRole: ${capturerChangeInfo[0].deviceRole}`); 9030 console.info(`audioCapturerChange deviceType: ${capturerChangeInfo[0].deviceType}`); 9031}; 9032 9033audioCapturer.on('audioCapturerChange', audioCapturerChangeCallback); 9034 9035audioCapturer.off('audioCapturerChange', audioCapturerChangeCallback); 9036``` 9037 9038### on('markReach')<sup>8+</sup> 9039 9040on(type: 'markReach', frame: number, callback: Callback<number>): void 9041 9042Subscribes 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. 9043 9044For example, if **frame** is set to **100**, the callback is invoked when the number of captured frames reaches the 100th frame. 9045 9046**System capability**: SystemCapability.Multimedia.Audio.Capturer 9047 9048**Parameters** 9049 9050| Name | Type | Mandatory| Description | 9051| :------- | :---------------------- | :--- | :----------------------------------------- | 9052| type | string | Yes | Event type. The value is fixed at **'markReach'**. | 9053| frame | number | Yes | Number of frames to trigger the event. The value must be greater than **0**. | 9054| callback | Callback\<number> | Yes | Callback used to return the value of the **frame** parameter.| 9055 9056**Example** 9057 9058```ts 9059audioCapturer.on('markReach', 1000, (position: number) => { 9060 if (position == 1000) { 9061 console.info('ON Triggered successfully'); 9062 } 9063}); 9064``` 9065 9066### off('markReach')<sup>8+</sup> 9067 9068off(type: 'markReach'): void 9069 9070Unsubscribes from the mark reached event. 9071 9072**System capability**: SystemCapability.Multimedia.Audio.Capturer 9073 9074**Parameters** 9075 9076| Name| Type | Mandatory| Description | 9077| :----- | :----- | :--- | :-------------------------------------------- | 9078| type | string | Yes | Event type. The value is fixed at **'markReach'**.| 9079 9080**Example** 9081 9082```ts 9083audioCapturer.off('markReach'); 9084``` 9085 9086### on('periodReach')<sup>8+</sup> 9087 9088on(type: 'periodReach', frame: number, callback: Callback<number>): void 9089 9090Subscribes 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. 9091 9092For 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. 9093 9094**System capability**: SystemCapability.Multimedia.Audio.Capturer 9095 9096**Parameters** 9097 9098| Name | Type | Mandatory| Description | 9099| :------- | :----------------------- | :--- | :------------------------------------------ | 9100| type | string | Yes | Event type. The value is fixed at **'periodReach'**.| 9101| frame | number | Yes | Number of frames to trigger the event. The value must be greater than **0**. | 9102| callback | Callback\<number> | Yes |Callback used to return the value of the **frame** parameter. | 9103 9104**Example** 9105 9106```ts 9107audioCapturer.on('periodReach', 1000, (position: number) => { 9108 if (position == 1000) { 9109 console.info('ON Triggered successfully'); 9110 } 9111}); 9112``` 9113 9114### off('periodReach')<sup>8+</sup> 9115 9116off(type: 'periodReach'): void 9117 9118Unsubscribes from the period reached event. 9119 9120**System capability**: SystemCapability.Multimedia.Audio.Capturer 9121 9122**Parameters** 9123 9124| Name| Type | Mandatory| Description | 9125| :----- | :----- | :--- | :---------------------------------------------- | 9126| type | string | Yes | Event type. The value is fixed at **'periodReach'**.| 9127 9128**Example** 9129 9130```ts 9131audioCapturer.off('periodReach'); 9132``` 9133 9134### on('stateChange')<sup>8+</sup> 9135 9136on(type: 'stateChange', callback: Callback<AudioState\>): void 9137 9138Subscribes 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. 9139 9140**System capability**: SystemCapability.Multimedia.Audio.Capturer 9141 9142**Parameters** 9143 9144| Name | Type | Mandatory| Description | 9145| :------- | :------------------------- | :--- | :------------------------------------------ | 9146| type | string | Yes | Event type. The value is fixed at **'stateChange'**.| 9147| callback | Callback\<[AudioState](#audiostate8)> | Yes | Callback used to return the audio status.| 9148 9149**Example** 9150 9151```ts 9152audioCapturer.on('stateChange', (state: audio.AudioState) => { 9153 if (state == 1) { 9154 console.info('audio capturer state is: STATE_PREPARED'); 9155 } 9156 if (state == 2) { 9157 console.info('audio capturer state is: STATE_RUNNING'); 9158 } 9159}); 9160``` 9161 9162### on('readData')<sup>11+</sup> 9163 9164on(type: 'readData', callback: Callback\<ArrayBuffer>): void 9165 9166Subscribes 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. 9167 9168The callback function is used only to read audio data. Do not call AudioCapturer APIs in it. 9169 9170**System capability**: SystemCapability.Multimedia.Audio.Capturer 9171 9172**Parameters** 9173 9174| Name | Type | Mandatory| Description | 9175| :------- |:-----------------------| :--- |:--------------------------| 9176| type | string | Yes | Event type. The value is fixed at **'readData'**.| 9177| callback | Callback\<ArrayBuffer> | Yes | Callback used to return the buffer from which the data is read. | 9178 9179**Error codes** 9180 9181For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 9182 9183| ID| Error Message| 9184| ------- | --------------------------------------------| 9185| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 9186| 6800101 | Parameter verification failed. | 9187 9188**Example** 9189 9190```ts 9191import { BusinessError } from '@kit.BasicServicesKit'; 9192import { fileIo as fs } from '@kit.CoreFileKit'; 9193 9194class Options { 9195 offset?: number; 9196 length?: number; 9197} 9198 9199let bufferSize: number = 0; 9200let path = getContext().cacheDir; 9201// Ensure that the resource exists in the path. 9202let filePath = path + '/StarWars10s-2C-48000-4SW.pcm'; 9203let file: fs.File = fs.openSync(filePath, fs.OpenMode.READ_WRITE); 9204let readDataCallback = (buffer: ArrayBuffer) => { 9205 let options: Options = { 9206 offset: bufferSize, 9207 length: buffer.byteLength 9208 }; 9209 fs.writeSync(file.fd, buffer, options); 9210 bufferSize += buffer.byteLength; 9211} 9212 9213audioCapturer.on('readData', readDataCallback); 9214 9215audioCapturer.start((err: BusinessError) => { 9216 if (err) { 9217 console.error('Capturer start failed.'); 9218 } else { 9219 console.info('Capturer start success.'); 9220 } 9221}); 9222``` 9223 9224### off('readData')<sup>11+</sup> 9225 9226off(type: 'readData', callback?: Callback\<ArrayBuffer>): void 9227 9228Unsubscribes from the audio data read event. This API uses an asynchronous callback to return the result. 9229 9230**System capability**: SystemCapability.Multimedia.Audio.Capturer 9231 9232**Parameters** 9233 9234| Name | Type | Mandatory| Description | 9235| :------- |:-----------------------| :--- |:-------------------------------------------| 9236| type | string | Yes | Event type. The value is fixed at **'readData'**. | 9237| callback | Callback\<ArrayBuffer> | No | Callback used to return the buffer from which the data is read. | 9238 9239**Error codes** 9240 9241For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 9242 9243| ID| Error Message| 9244| ------- | --------------------------------------------| 9245| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 9246| 6800101 | Parameter verification failed. | 9247 9248**Example** 9249 9250```ts 9251// Cancel all subscriptions to the event. 9252audioCapturer.off('readData'); 9253 9254// 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. 9255let readDataCallback = (data: ArrayBuffer) => { 9256 console.info(`read data: ${data}`); 9257}; 9258 9259audioCapturer.on('readData', readDataCallback); 9260 9261audioCapturer.off('readData', readDataCallback); 9262``` 9263 9264### getOverflowCount<sup>12+</sup> 9265 9266getOverflowCount(): Promise<number> 9267 9268Obtains the number of overflow audio frames in the audio stream that is being captured. This API uses a promise to return the result. 9269 9270**System capability**: SystemCapability.Multimedia.Audio.Capturer 9271 9272**Return value** 9273 9274| Type | Description | 9275| ------------------- | ----------------------------- | 9276| Promise<number>| Promise used to return the number of overflow audio frames.| 9277 9278**Example** 9279 9280```ts 9281import { BusinessError } from '@kit.BasicServicesKit'; 9282 9283audioCapturer.getOverflowCount().then((value: number) => { 9284 console.info(`Get overflow count Success! ${value}`); 9285}).catch((err: BusinessError) => { 9286 console.error(`Get overflow count Fail: ${err}`); 9287}); 9288``` 9289 9290### getOverflowCountSync<sup>12+</sup> 9291 9292getOverflowCountSync(): number 9293 9294Obtains the number of overflow audio frames in the audio stream that is being captured. This API returns the result synchronously. 9295 9296**System capability**: SystemCapability.Multimedia.Audio.Capturer 9297 9298**Return value** 9299 9300| Type | Description | 9301| ------------------- | ----------------------------- | 9302| number| Number of overflow audio frames.| 9303 9304**Example** 9305 9306```ts 9307import { BusinessError } from '@kit.BasicServicesKit'; 9308 9309try { 9310 let value: number = audioCapturer.getOverflowCountSync(); 9311 console.info(`Get overflow count Success! ${value}`); 9312} catch (err) { 9313 let error = err as BusinessError; 9314 console.error(`Get overflow count Fail: ${error}`); 9315} 9316``` 9317 9318## ActiveDeviceType<sup>(deprecated)</sup> 9319 9320Enumerates the active device types. 9321 9322> **NOTE** 9323> 9324> This API is deprecated since API version 9. You are advised to use [CommunicationDeviceType](#communicationdevicetype9) instead. 9325 9326**System capability**: SystemCapability.Multimedia.Audio.Device 9327 9328| Name | Value | Description | 9329| ------------- | ------ | ---------------------------------------------------- | 9330| SPEAKER | 2 | Speaker. | 9331| BLUETOOTH_SCO | 7 | Bluetooth device using Synchronous Connection Oriented (SCO) links.| 9332 9333## InterruptActionType<sup>(deprecated)</sup> 9334 9335Enumerates the returned event types for audio interruption events. 9336 9337> **NOTE** 9338> 9339> 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. 9340 9341**System capability**: SystemCapability.Multimedia.Audio.Renderer 9342 9343| Name | Value | Description | 9344| -------------- | ------ | ------------------ | 9345| TYPE_ACTIVATED | 0 | Focus gain event.| 9346| TYPE_INTERRUPT | 1 | Audio interruption event.| 9347 9348## AudioInterrupt<sup>(deprecated)</sup> 9349 9350Describes input parameters of audio interruption events. 9351 9352> **NOTE** 9353> 9354> 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. 9355 9356**System capability**: SystemCapability.Multimedia.Audio.Renderer 9357 9358| Name | Type | Mandatory| Description | 9359| --------------- | --------------------------- | ----| ------------------------------------------------------------ | 9360| streamUsage | [StreamUsage](#streamusage) | Yes | Audio stream usage. | 9361| contentType | [ContentType](#contenttypedeprecated) | Yes | Audio content type. | 9362| 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.| 9363 9364## InterruptAction<sup>(deprecated)</sup> 9365 9366Describes the callback invoked for audio interruption or focus gain events. 9367 9368> **NOTE** 9369> 9370> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [InterruptEvent](#interruptevent9). 9371 9372**System capability**: SystemCapability.Multimedia.Audio.Renderer 9373 9374| Name | Type | Mandatory| Description | 9375| ---------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | 9376| actionType | [InterruptActionType](#interruptactiontypedeprecated) | Yes | Returned event type. The value **TYPE_ACTIVATED** means the focus gain event, and **TYPE_INTERRUPT** means the audio interruption event.| 9377| type | [InterruptType](#interrupttype) | No | Type of the audio interruption event. | 9378| hint | [InterruptHint](#interrupthint) | No | Hint provided along with the audio interruption event. | 9379| 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.| 9380 9381 <!--no_check-->