1# @ohos.multimedia.audio (Audio Management) 2 3The Audio module provides basic audio management capabilities, including audio volume and audio device management, and audio data collection and rendering. 4 5This module provides the following common audio-related functions: 6 7- [AudioManager](#audiomanager): audio management. 8- [AudioRenderer](#audiorenderer8): audio rendering, used to play Pulse Code Modulation (PCM) audio data. 9- [AudioCapturer](#audiocapturer8): audio capture, used to record PCM audio data. 10 11> **NOTE** 12> 13> The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version. 14 15## Modules to Import 16 17```ts 18import { audio } from '@kit.AudioKit'; 19``` 20 21## Constants 22 23| Name | Type | Readable | Writable| Description | 24| --------------------------------------- | ----------| ---- | ---- | ------------------ | 25| DEFAULT_VOLUME_GROUP_ID<sup>9+</sup> | number | Yes | No | Default volume group ID.<br> **System capability**: SystemCapability.Multimedia.Audio.Volume | 26| DEFAULT_INTERRUPT_GROUP_ID<sup>9+</sup> | number | Yes | No | Default audio interruption group ID.<br> **System capability**: SystemCapability.Multimedia.Audio.Interrupt | 27 28**Example** 29 30```ts 31import { audio } from '@kit.AudioKit'; 32 33const defaultVolumeGroupId = audio.DEFAULT_VOLUME_GROUP_ID; 34const defaultInterruptGroupId = audio.DEFAULT_INTERRUPT_GROUP_ID; 35``` 36 37## audio.getAudioManager 38 39getAudioManager(): AudioManager 40 41Obtains an **AudioManager** instance. 42 43**System capability**: SystemCapability.Multimedia.Audio.Core 44 45**Return value** 46 47| Type | Description | 48| ----------------------------- | ------------ | 49| [AudioManager](#audiomanager) | **AudioManager** instance.| 50 51**Example** 52```ts 53import { audio } from '@kit.AudioKit'; 54 55let audioManager = audio.getAudioManager(); 56``` 57 58## audio.createAudioRenderer<sup>8+</sup> 59 60createAudioRenderer(options: AudioRendererOptions, callback: AsyncCallback\<AudioRenderer>): void 61 62Creates an **AudioRenderer** instance. This API uses an asynchronous callback to return the result. 63 64**System capability**: SystemCapability.Multimedia.Audio.Renderer 65 66**Parameters** 67 68| Name | Type | Mandatory| Description | 69| -------- | ----------------------------------------------- | ---- | ---------------- | 70| options | [AudioRendererOptions](#audiorendereroptions8) | Yes | Renderer configurations. | 71| callback | AsyncCallback<[AudioRenderer](#audiorenderer8)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the **AudioRenderer** instance obtained; otherwise, **err** is an error object.| 72 73**Example** 74 75```ts 76import { audio } from '@kit.AudioKit'; 77 78let audioStreamInfo: audio.AudioStreamInfo = { 79 samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_48000, 80 channels: audio.AudioChannel.CHANNEL_2, 81 sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, 82 encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW 83}; 84 85let audioRendererInfo: audio.AudioRendererInfo = { 86 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 87 rendererFlags: 0 88}; 89 90let audioRendererOptions: audio.AudioRendererOptions = { 91 streamInfo: audioStreamInfo, 92 rendererInfo: audioRendererInfo 93}; 94 95audio.createAudioRenderer(audioRendererOptions,(err, data) => { 96 if (err) { 97 console.error(`AudioRenderer Created: Error: ${err}`); 98 } else { 99 console.info('AudioRenderer Created: Success: SUCCESS'); 100 let audioRenderer = data; 101 } 102}); 103``` 104 105## audio.createAudioRenderer<sup>8+</sup> 106 107createAudioRenderer(options: AudioRendererOptions): Promise<AudioRenderer\> 108 109Creates an **AudioRenderer** instance. This API uses a promise to return the result. 110 111**System capability**: SystemCapability.Multimedia.Audio.Renderer 112 113**Parameters** 114 115| Name | Type | Mandatory| Description | 116| :------ | :--------------------------------------------- | :--- | :----------- | 117| options | [AudioRendererOptions](#audiorendereroptions8) | Yes | Renderer configurations.| 118 119**Return value** 120 121| Type | Description | 122| ----------------------------------------- | ---------------- | 123| Promise<[AudioRenderer](#audiorenderer8)> | Promise used to return the **AudioRenderer** instance.| 124 125**Example** 126 127```ts 128import { audio } from '@kit.AudioKit'; 129import { BusinessError } from '@kit.BasicServicesKit'; 130 131let audioStreamInfo: audio.AudioStreamInfo = { 132 samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_48000, 133 channels: audio.AudioChannel.CHANNEL_2, 134 sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, 135 encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW 136}; 137 138let audioRendererInfo: audio.AudioRendererInfo = { 139 usage: audio.StreamUsage.STREAM_USAGE_MUSIC, 140 rendererFlags: 0 141}; 142 143let audioRendererOptions: audio.AudioRendererOptions = { 144 streamInfo: audioStreamInfo, 145 rendererInfo: audioRendererInfo 146}; 147 148let audioRenderer: audio.AudioRenderer; 149 150audio.createAudioRenderer(audioRendererOptions).then((data) => { 151 audioRenderer = data; 152 console.info('AudioFrameworkRenderLog: AudioRenderer Created : Success : Stream Type: SUCCESS'); 153}).catch((err: BusinessError) => { 154 console.error(`AudioFrameworkRenderLog: AudioRenderer Created : ERROR : ${err}`); 155}); 156``` 157 158## audio.createAudioCapturer<sup>8+</sup> 159 160createAudioCapturer(options: AudioCapturerOptions, callback: AsyncCallback<AudioCapturer\>): void 161 162Creates an **AudioCapturer** instance. This API uses an asynchronous callback to return the result. 163 164**System capability**: SystemCapability.Multimedia.Audio.Capturer 165 166**Required permissions**: ohos.permission.MICROPHONE 167 168This permission is required when [SourceType](#sourcetype8) is set to **SOURCE_TYPE_MIC**, **SOURCE_TYPE_VOICE_RECOGNITION**, **SOURCE_TYPE_VOICE_COMMUNICATION**, **SOURCE_TYPE_VOICE_MESSAGE**, or **SOURCE_TYPE_CAMCORDER**. 169 170**Parameters** 171 172| Name | Type | Mandatory| Description | 173| :------- | :---------------------------------------------- | :--- | :--------------- | 174| options | [AudioCapturerOptions](#audiocaptureroptions8) | Yes | Capturer configurations.| 175| callback | AsyncCallback<[AudioCapturer](#audiocapturer8)> | Yes | Callback used to return the result. If the operation is successful, an **AudioCapturer** instance is returned; otherwise, an error object with either of the following error codes is returned:<br>Error code 6800301: indicates a parameter verification exception, permission verification exception, or system processing exception. For details, see system logs.<br>Error code 6800101: indicates that a mandatory parameter is null or the parameter type is incorrect.| 176 177**Example** 178 179```ts 180import { audio } from '@kit.AudioKit'; 181 182let audioStreamInfo: audio.AudioStreamInfo = { 183 samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_48000, 184 channels: audio.AudioChannel.CHANNEL_2, 185 sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, 186 encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW 187}; 188 189let audioCapturerInfo: audio.AudioCapturerInfo = { 190 source: audio.SourceType.SOURCE_TYPE_MIC, 191 capturerFlags: 0 192}; 193 194let audioCapturerOptions: audio.AudioCapturerOptions = { 195 streamInfo: audioStreamInfo, 196 capturerInfo: audioCapturerInfo 197}; 198 199audio.createAudioCapturer(audioCapturerOptions, (err, data) => { 200 if (err) { 201 console.error(`AudioCapturer Created : Error: ${err}`); 202 } else { 203 console.info('AudioCapturer Created : Success : SUCCESS'); 204 let audioCapturer = data; 205 } 206}); 207``` 208 209## audio.createAudioCapturer<sup>8+</sup> 210 211createAudioCapturer(options: AudioCapturerOptions): Promise<AudioCapturer\> 212 213Creates an **AudioCapturer** instance. This API uses a promise to return the result. 214 215**System capability**: SystemCapability.Multimedia.Audio.Capturer 216 217**Required permissions**: ohos.permission.MICROPHONE 218 219This permission is required when [SourceType](#sourcetype8) is set to **SOURCE_TYPE_MIC**, **SOURCE_TYPE_VOICE_RECOGNITION**, **SOURCE_TYPE_VOICE_COMMUNICATION**, **SOURCE_TYPE_VOICE_MESSAGE**, or **SOURCE_TYPE_CAMCORDER**. 220 221**Parameters** 222 223| Name | Type | Mandatory| Description | 224| :------ | :--------------------------------------------- | :--- | :--------------- | 225| options | [AudioCapturerOptions](#audiocaptureroptions8) | Yes | Capturer configurations.| 226 227**Return value** 228 229| Type | Description | 230| ----------------------------------------- |----------------------| 231| Promise<[AudioCapturer](#audiocapturer8)> | Promise used to return the result. If the operation is successful, an **AudioCapturer** instance is returned; otherwise, an error object with either of the following error codes is returned:<br>Error code 6800301: indicates a parameter verification exception, permission verification exception, or system processing exception. For details, see system logs.<br>Error code 6800101: indicates that a mandatory parameter is null or the parameter type is incorrect.| 232 233**Example** 234 235```ts 236import { audio } from '@kit.AudioKit'; 237import { BusinessError } from '@kit.BasicServicesKit'; 238 239let audioStreamInfo: audio.AudioStreamInfo = { 240 samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_48000, 241 channels: audio.AudioChannel.CHANNEL_2, 242 sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, 243 encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW 244}; 245 246let audioCapturerInfo: audio.AudioCapturerInfo = { 247 source: audio.SourceType.SOURCE_TYPE_MIC, 248 capturerFlags: 0 249}; 250 251let audioCapturerOptions:audio.AudioCapturerOptions = { 252 streamInfo: audioStreamInfo, 253 capturerInfo: audioCapturerInfo 254}; 255 256let audioCapturer: audio.AudioCapturer; 257 258audio.createAudioCapturer(audioCapturerOptions).then((data) => { 259 audioCapturer = data; 260 console.info('AudioCapturer Created : Success : Stream Type: SUCCESS'); 261}).catch((err: BusinessError) => { 262 console.error(`AudioCapturer Created : ERROR : ${err}`); 263}); 264``` 265 266## AudioVolumeType 267 268Enumerates the audio stream types. 269 270**System capability**: SystemCapability.Multimedia.Audio.Volume 271 272| Name | Value | Description | 273| ---------------------------- | ------ | ---------- | 274| VOICE_CALL<sup>8+</sup> | 0 | Audio stream for voice calls.| 275| RINGTONE | 2 | Audio stream for ringtones. | 276| MEDIA | 3 | Audio stream for media purpose. | 277| ALARM<sup>10+</sup> | 4 | Audio stream for alarming. | 278| ACCESSIBILITY<sup>10+</sup> | 5 | Audio stream for accessibility. | 279| VOICE_ASSISTANT<sup>8+</sup> | 9 | Audio stream for voice assistant.| 280 281## InterruptMode<sup>9+</sup> 282 283Enumerates the audio interruption modes. 284 285**Atomic service API**: This API can be used in atomic services since API version 12. 286 287**System capability**: SystemCapability.Multimedia.Audio.Interrupt 288 289| Name | Value | Description | 290| ---------------------------- | ------ | ---------- | 291| SHARE_MODE | 0 | Shared mode.| 292| INDEPENDENT_MODE | 1 | Independent mode.| 293 294## DeviceFlag 295 296Enumerates the audio device flags. 297 298**System capability**: SystemCapability.Multimedia.Audio.Device 299 300| Name | Value | Description | 301| ------------------------------- | ------ |---------------------------| 302| OUTPUT_DEVICES_FLAG | 1 | Output device. | 303| INPUT_DEVICES_FLAG | 2 | Input device. | 304| ALL_DEVICES_FLAG | 3 | All devices. | 305 306## DeviceUsage<sup>12+</sup> 307 308Enumerates the usage scenarios of audio devices. 309 310**System capability**: SystemCapability.Multimedia.Audio.Device 311 312| Name | Value | Description | 313| ------------------------------- | ------ |---------------------------| 314| MEDIA_OUTPUT_DEVICES | 1 | Media output device.| 315| MEDIA_INPUT_DEVICES | 2 | Media input device.| 316| ALL_MEDIA_DEVICES | 3 | All media devices.| 317| CALL_OUTPUT_DEVICES | 4 | Call output device.| 318| CALL_INPUT_DEVICES | 8 | Call input device.| 319| ALL_CALL_DEVICES | 12 | All call devices.| 320 321## DeviceRole 322 323Enumerates the audio device roles. 324 325**Atomic service API**: This API can be used in atomic services since API version 12. 326 327**System capability**: SystemCapability.Multimedia.Audio.Device 328 329| Name | Value | Description | 330| ------------- | ------ | -------------- | 331| INPUT_DEVICE | 1 | Input role.| 332| OUTPUT_DEVICE | 2 | Output role.| 333 334## DeviceType 335 336Enumerates the audio device types. 337 338**Atomic service API**: This API can be used in atomic services since API version 12. 339 340**System capability**: SystemCapability.Multimedia.Audio.Device 341 342| Name | Value | Description | 343| ---------------------| ------ | --------------------------------------------------------- | 344| INVALID | 0 | Invalid device. | 345| EARPIECE | 1 | Earpiece. | 346| SPEAKER | 2 | Speaker. | 347| WIRED_HEADSET | 3 | Wired headset with a microphone. | 348| WIRED_HEADPHONES | 4 | Wired headset without microphone. | 349| BLUETOOTH_SCO | 7 | Bluetooth device using Synchronous Connection Oriented (SCO) links. | 350| BLUETOOTH_A2DP | 8 | Bluetooth device using Advanced Audio Distribution Profile (A2DP) links.| 351| MIC | 15 | Microphone. | 352| USB_HEADSET | 22 | USB Type-C headset. | 353| DISPLAY_PORT<sup>12+</sup> | 23 | Display port (DP), which is used to connect to external devices. | 354| REMOTE_CAST<sup>12+</sup> | 24 | Remote cast device. | 355| DEFAULT<sup>9+</sup> | 1000 | Default device type. | 356 357## CommunicationDeviceType<sup>9+</sup> 358 359Enumerates the device types used for communication. 360 361**System capability**: SystemCapability.Multimedia.Audio.Communication 362 363| Name | Value | Description | 364| ------------- | ------ | -------------| 365| SPEAKER | 2 | Speaker. | 366 367## AudioRingMode 368 369Enumerates the ringer modes. 370 371**System capability**: SystemCapability.Multimedia.Audio.Communication 372 373| Name | Value | Description | 374| ------------------- | ------ | ---------- | 375| RINGER_MODE_SILENT | 0 | Silent mode.| 376| RINGER_MODE_VIBRATE | 1 | Vibration mode.| 377| RINGER_MODE_NORMAL | 2 | Normal mode.| 378 379## AudioSampleFormat<sup>8+</sup> 380 381Enumerates the audio sample formats. 382 383**System capability**: SystemCapability.Multimedia.Audio.Core 384 385| Name | Value | Description | 386| ---------------------------------- | ------ | -------------------------- | 387| SAMPLE_FORMAT_INVALID | -1 | Invalid format. | 388| SAMPLE_FORMAT_U8 | 0 | Unsigned 8-bit integer. | 389| SAMPLE_FORMAT_S16LE | 1 | Signed 16-bit integer, little endian.| 390| SAMPLE_FORMAT_S24LE | 2 | Signed 24-bit integer, little endian.<br>Due to system restrictions, only some devices support this sampling format.| 391| SAMPLE_FORMAT_S32LE | 3 | Signed 32-bit integer, little endian.<br>Due to system restrictions, only some devices support this sampling format.| 392| SAMPLE_FORMAT_F32LE<sup>9+</sup> | 4 | Signed 32-bit floating point number, little endian.<br>Due to system restrictions, only some devices support this sampling format.| 393 394## AudioErrors<sup>9+</sup> 395 396Enumerates the audio error codes. 397 398**System capability**: SystemCapability.Multimedia.Audio.Core 399 400| Name | Value | Description | 401| ---------------------| --------| ----------------- | 402| ERROR_INVALID_PARAM | 6800101 | Invalid parameter. | 403| ERROR_NO_MEMORY | 6800102 | Memory allocation failure. | 404| ERROR_ILLEGAL_STATE | 6800103 | Unsupported state. | 405| ERROR_UNSUPPORTED | 6800104 | Unsupported parameter value. | 406| ERROR_TIMEOUT | 6800105 | Processing timeout. | 407| ERROR_STREAM_LIMIT | 6800201 | Too many audio streams.| 408| ERROR_SYSTEM | 6800301 | System error. | 409 410## AudioChannel<sup>8+</sup> 411 412Enumerates the audio channels. 413 414**System capability**: SystemCapability.Multimedia.Audio.Core 415 416| Name | Value | Description | 417| --------- | -------- |------| 418| CHANNEL_1 | 1 | One audio channel (mono).| 419| CHANNEL_2 | 2 | Two audio channels (stereo).| 420| CHANNEL_3<sup>11+</sup> | 3 | Three audio channels.| 421| CHANNEL_4<sup>11+</sup> | 4 | Four audio channels.| 422| CHANNEL_5<sup>11+</sup> | 5 | Five audio channels.| 423| CHANNEL_6<sup>11+</sup> | 6 | Six audio channels.| 424| CHANNEL_7<sup>11+</sup> | 7 | Seven audio channels.| 425| CHANNEL_8<sup>11+</sup> | 8 | Eight audio channels.| 426| CHANNEL_9<sup>11+</sup> | 9 | Nine audio channels.| 427| CHANNEL_10<sup>11+</sup> | 10 | Ten audio channels.| 428| CHANNEL_12<sup>11+</sup> | 12 | Twelve audio channels.| 429| CHANNEL_14<sup>11+</sup> | 14 | Fourteen audio channels.| 430| CHANNEL_16<sup>11+</sup> | 16 | Sixteen audio channels.| 431 432## AudioSamplingRate<sup>8+</sup> 433 434Enumerates the audio sampling rates. The sampling rates supported vary according to the device in use. 435 436**System capability**: SystemCapability.Multimedia.Audio.Core 437 438| Name | Value | Description | 439| ----------------- | ------ | --------------- | 440| SAMPLE_RATE_8000 | 8000 | The sampling rate is 8000. | 441| SAMPLE_RATE_11025 | 11025 | The sampling rate is 11025.| 442| SAMPLE_RATE_12000 | 12000 | The sampling rate is 12000.| 443| SAMPLE_RATE_16000 | 16000 | The sampling rate is 16000.| 444| SAMPLE_RATE_22050 | 22050 | The sampling rate is 22050.| 445| SAMPLE_RATE_24000 | 24000 | The sampling rate is 24000.| 446| SAMPLE_RATE_32000 | 32000 | The sampling rate is 32000.| 447| SAMPLE_RATE_44100 | 44100 | The sampling rate is 44100.| 448| SAMPLE_RATE_48000 | 48000 | The sampling rate is 48000.| 449| SAMPLE_RATE_64000 | 64000 | The sampling rate is 64000.| 450| SAMPLE_RATE_88200<sup>12+</sup> | 88200 | The sampling rate is 88200.| 451| SAMPLE_RATE_96000 | 96000 | The sampling rate is 96000.| 452| SAMPLE_RATE_176400<sup>12+</sup> | 176400 | The sampling rate is 176400.| 453| SAMPLE_RATE_192000<sup>12+</sup> | 192000 | The sampling rate is 192000.| 454 455## AudioEncodingType<sup>8+</sup> 456 457Enumerates the audio encoding types. 458 459**Atomic service API**: This API can be used in atomic services since API version 12. 460 461**System capability**: SystemCapability.Multimedia.Audio.Core 462 463| Name | Value | Description | 464| --------------------- | ------ | --------- | 465| ENCODING_TYPE_INVALID | -1 | Invalid. | 466| ENCODING_TYPE_RAW | 0 | PCM encoding.| 467 468## AudioChannelLayout<sup>11+</sup> 469 470Enumerates the audio channel layouts. 471 472**System capability**: SystemCapability.Multimedia.Audio.Core 473 474| Name | Value | Description | 475| ------------------------------ | ---------------- | --------------------------------------------- | 476| CH_LAYOUT_UNKNOWN | 0x0 | Unknown. | 477| CH_LAYOUT_MONO | 0x4 | Mono. | 478| CH_LAYOUT_STEREO | 0x3 | Stereo. | 479| CH_LAYOUT_STEREO_DOWNMIX | 0x60000000 | Stereo downmix. | 480| CH_LAYOUT_2POINT1 | 0xB | 2.1. | 481| CH_LAYOUT_3POINT0 | 0x103 | 3.0. | 482| CH_LAYOUT_SURROUND | 0x7 | Surround. | 483| CH_LAYOUT_3POINT1 | 0xF | 3.1. | 484| CH_LAYOUT_4POINT0 | 0x107 | 4.0. | 485| CH_LAYOUT_QUAD | 0x33 | Quad. | 486| CH_LAYOUT_QUAD_SIDE | 0x603 | Quad side. | 487| CH_LAYOUT_2POINT0POINT2 | 0x3000000003 | 2.0.2. | 488| CH_LAYOUT_AMB_ORDER1_ACN_N3D | 0x100000000001 | First-order FOA file in ACN_N3D (ITU standards). | 489| CH_LAYOUT_AMB_ORDER1_ACN_SN3D | 0x100000001001 | First-order FOA file in ACN_SN3D (ITU standards).| 490| CH_LAYOUT_AMB_ORDER1_FUMA | 0x100000000101 | First-order FOA file in FUMA (ITU standards). | 491| CH_LAYOUT_4POINT1 | 0x10F | 4.1. | 492| CH_LAYOUT_5POINT0 | 0x607 | 5.0. | 493| CH_LAYOUT_5POINT0_BACK | 0x37 | 5.0 back. | 494| CH_LAYOUT_2POINT1POINT2 | 0x300000000B | 2.1.2. | 495| CH_LAYOUT_3POINT0POINT2 | 0x3000000007 | 3.0.2. | 496| CH_LAYOUT_5POINT1 | 0x60F | 5.1. | 497| CH_LAYOUT_5POINT1_BACK | 0x3F | 5.1 back. | 498| CH_LAYOUT_6POINT0 | 0x707 | 6.0. | 499| CH_LAYOUT_HEXAGONAL | 0x137 | Hexagonal. | 500| CH_LAYOUT_3POINT1POINT2 | 0x500F | 3.1.2. | 501| CH_LAYOUT_6POINT0_FRONT | 0x6C3 | 6.0 front. | 502| CH_LAYOUT_6POINT1 | 0x70F | 6.1. | 503| CH_LAYOUT_6POINT1_BACK | 0x13F | 6.1 back. | 504| CH_LAYOUT_6POINT1_FRONT | 0x6CB | 6.1 front. | 505| CH_LAYOUT_7POINT0 | 0x637 | 7.0. | 506| CH_LAYOUT_7POINT0_FRONT | 0x6C7 | 7.0 front. | 507| CH_LAYOUT_7POINT1 | 0x63F | 7.1. | 508| CH_LAYOUT_OCTAGONAL | 0x737 | Octagonal. | 509| CH_LAYOUT_5POINT1POINT2 | 0x300000060F | 5.1.2. | 510| CH_LAYOUT_7POINT1_WIDE | 0x6CF | 7.1 wide. | 511| CH_LAYOUT_7POINT1_WIDE_BACK | 0xFF | 7.1 wide back. | 512| CH_LAYOUT_AMB_ORDER2_ACN_N3D | 0x100000000002 | Second-order HOA file in ACN_N3D (ITU standards). | 513| CH_LAYOUT_AMB_ORDER2_ACN_SN3D | 0x100000001002 | Second-order HOA file in ACN_SN3D (ITU standards).| 514| CH_LAYOUT_AMB_ORDER2_FUMA | 0x100000000102 | Second-order HOA file in FUMA (ITU standards). | 515| CH_LAYOUT_5POINT1POINT4 | 0x2D60F | 5.1.4. | 516| CH_LAYOUT_7POINT1POINT2 | 0x300000063F | 7.1.2. | 517| CH_LAYOUT_7POINT1POINT4 | 0x2D63F | 7.1.4. | 518| CH_LAYOUT_10POINT2 | 0x180005737 | 10.2. | 519| CH_LAYOUT_9POINT1POINT4 | 0x18002D63F | 9.1.4. | 520| CH_LAYOUT_9POINT1POINT6 | 0x318002D63F | 9.1.6. | 521| CH_LAYOUT_HEXADECAGONAL | 0x18003F737 | Hexadecagonal. | 522| CH_LAYOUT_AMB_ORDER3_ACN_N3D | 0x100000000003 | Third-order HOA file in ACN_N3D (ITU standards). | 523| CH_LAYOUT_AMB_ORDER3_ACN_SN3D | 0x100000001003 | Third-order HOA file in ACN_SN3D (ITU standards).| 524| CH_LAYOUT_AMB_ORDER3_FUMA | 0x100000000103 | Third-order HOA file in FUMA (ITU standards). | 525 526## ContentType<sup>(deprecated)</sup> 527 528Enumerates the audio content types. 529 530> **NOTE** 531> This API is supported since API version 7 and deprecated since API version 10. You are advised to use [StreamUsage](#streamusage) to declare the audio stream type. 532 533**System capability**: SystemCapability.Multimedia.Audio.Core 534 535| Name | Value | Description | 536| ---------------------------------- | ------ | ---------- | 537| CONTENT_TYPE_UNKNOWN | 0 | Unknown content.| 538| CONTENT_TYPE_SPEECH | 1 | Speech. | 539| CONTENT_TYPE_MUSIC | 2 | Music. | 540| CONTENT_TYPE_MOVIE | 3 | Movie. | 541| CONTENT_TYPE_SONIFICATION | 4 | Notification tone. | 542| CONTENT_TYPE_RINGTONE<sup>8+</sup> | 5 | Ringtone. | 543 544## StreamUsage 545 546Enumerates the audio stream usage. 547 548**System capability**: SystemCapability.Multimedia.Audio.Core 549 550| Name | Value | Description | 551| ------------------------------------------| ------ |---------------------------------------------------------------------------------------------------------------------------------------------| 552| STREAM_USAGE_UNKNOWN | 0 | Unknown content.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 553| STREAM_USAGE_MEDIA<sup>(deprecated)</sup> | 1 | Media.<br> This enumerated value is supported since API version 7 and deprecated since API version 10. You are advised to use **STREAM_USAGE_MUSIC**, **STREAM_USAGE_MOVIE**, **STREAM_USAGE_GAME**, or **STREAM_USAGE_AUDIOBOOK** instead.| 554| STREAM_USAGE_MUSIC<sup>10+</sup> | 1 | Music.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 555| STREAM_USAGE_VOICE_COMMUNICATION | 2 | VoIP voice call.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 556| STREAM_USAGE_VOICE_ASSISTANT<sup>9+</sup> | 3 | Voice assistant.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 557| STREAM_USAGE_ALARM<sup>10+</sup> | 4 | Audio stream for alarming.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 558| STREAM_USAGE_VOICE_MESSAGE<sup>10+</sup> | 5 | Voice message.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 559| STREAM_USAGE_NOTIFICATION_RINGTONE<sup>(deprecated)</sup> | 6 | Notification tone.<br> This enumerated value is deprecated since API version 10. You are advised to use **STREAM_USAGE_RINGTONE** instead. | 560| STREAM_USAGE_RINGTONE<sup>10+</sup> | 6 | Ringtone.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 561| STREAM_USAGE_NOTIFICATION<sup>10+</sup> | 7 | Notification.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 562| STREAM_USAGE_ACCESSIBILITY<sup>10+</sup> | 8 | Accessibility.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 563| STREAM_USAGE_MOVIE<sup>10+</sup> | 10 | Movie or video.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 564| STREAM_USAGE_GAME<sup>10+</sup> | 11 | Gaming.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 565| STREAM_USAGE_AUDIOBOOK<sup>10+</sup> | 12 | Audiobooks (including crosstalks and storytelling), news radio, and podcasts.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 566| STREAM_USAGE_NAVIGATION<sup>10+</sup> | 13 | Navigation.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 567| STREAM_USAGE_VIDEO_COMMUNICATION<sup>12+</sup> | 17 | VoIP video call.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 568 569## AudioState<sup>8+</sup> 570 571Enumerates the audio states. 572 573**System capability**: SystemCapability.Multimedia.Audio.Core 574 575| Name | Value | Description | 576| -------------- | ------ | ---------------- | 577| STATE_INVALID | -1 | Invalid state. | 578| STATE_NEW | 0 | Creating instance state.| 579| STATE_PREPARED | 1 | Prepared. | 580| STATE_RUNNING | 2 | Running.| 581| STATE_STOPPED | 3 | Stopped. | 582| STATE_RELEASED | 4 | Released. | 583| STATE_PAUSED | 5 | Paused. | 584 585## AudioEffectMode<sup>10+</sup> 586 587Enumerates the audio effect modes. 588 589**Atomic service API**: This API can be used in atomic services since API version 12. 590 591**System capability**: SystemCapability.Multimedia.Audio.Renderer 592 593| Name | Value | Description | 594| ------------------ | ------ | ---------- | 595| EFFECT_NONE | 0 | The audio effect is disabled.| 596| EFFECT_DEFAULT | 1 | The default audio effect is used.| 597 598## AudioRendererRate<sup>8+</sup> 599 600Enumerates the audio renderer rates. 601 602**System capability**: SystemCapability.Multimedia.Audio.Renderer 603 604| Name | Value | Description | 605| ------------------ | ------ | ---------- | 606| RENDER_RATE_NORMAL | 0 | Normal rate.| 607| RENDER_RATE_DOUBLE | 1 | Double rate. | 608| RENDER_RATE_HALF | 2 | Half rate. | 609 610## InterruptType 611 612Enumerates the audio interruption types. 613 614**Atomic service API**: This API can be used in atomic services since API version 12. 615 616**System capability**: SystemCapability.Multimedia.Audio.Renderer 617 618| Name | Value | Description | 619| -------------------- | ------ | ---------------------- | 620| INTERRUPT_TYPE_BEGIN | 1 | Audio interruption started.| 621| INTERRUPT_TYPE_END | 2 | Audio interruption ended.| 622 623## InterruptForceType<sup>9+</sup> 624 625Enumerates the types of force that causes audio interruption. 626 627The force type is obtained when an [InterruptEvent](#interruptevent9) is received. 628 629This type specifies whether the audio interruption operation is forcibly performed by the system. The operation information (such as audio pause or stop) can be obtained through [InterruptHint](#interrupthint). For details about the audio interruption strategy, see [Handling Audio Focus Changes](../../media/audio/audio-playback-concurrency.md). 630 631**Atomic service API**: This API can be used in atomic services since API version 12. 632 633**System capability**: SystemCapability.Multimedia.Audio.Renderer 634 635| Name | Value | Description | 636| --------------- | ------ | ------------------------------------ | 637| INTERRUPT_FORCE | 0 | The operation is forcibly performed by the system. | 638| INTERRUPT_SHARE | 1 | The operation will not be performed by the system. [InterruptHint](#interrupthint) is used to provide recommended operations for the application, and the application can determine the next processing mode.| 639 640## InterruptHint 641 642Enumerates the hints provided along with audio interruption. 643 644The hint is obtained when an [InterruptEvent](#interruptevent9) is received. 645 646The hint specifies the operation (such as audio pause or volume adjustment) to be performed on audio streams based on the focus policy. 647 648You can determine whether the operation is forcibly performed by the system based on [InterruptForceType](#interruptforcetype9) in **InterruptEvent**. For details about the audio interruption strategy, see [Handling Audio Focus Changes](../../media/audio/audio-playback-concurrency.md). 649 650**Atomic service API**: This API can be used in atomic services since API version 12. 651 652**System capability**: SystemCapability.Multimedia.Audio.Renderer 653 654| Name | Value | Description | 655| ---------------------------------- | ------ | -------------------------------------------- | 656| INTERRUPT_HINT_NONE<sup>8+</sup> | 0 | None. | 657| INTERRUPT_HINT_RESUME | 1 | A hint is displayed, indicating that the audio stream is restored. The application can proactively trigger operations related to rendering or recording.<br>This operation cannot be forcibly performed by the system, and the corresponding [InterruptForceType](#interruptforcetype9) must be **INTERRUPT_SHARE**.| 658| INTERRUPT_HINT_PAUSE | 2 | A hint is displayed, indicating that the audio stream is paused and the audio focus is lost temporarily.<br>The **INTERRUPT_HINT_RESUME** event will be triggered when the focus is gained. | 659| INTERRUPT_HINT_STOP | 3 | A hint is displayed, indicating that the audio stream stops and the audio focus is lost. | 660| INTERRUPT_HINT_DUCK | 4 | A hint is displayed, indicating that audio ducking starts and the audio is played at a lower volume.| 661| INTERRUPT_HINT_UNDUCK<sup>8+</sup> | 5 | A hint is displayed, indicating that audio ducking ends and the audio is played at the normal volume. | 662 663## AudioStreamInfo<sup>8+</sup> 664 665Describes audio stream information. 666 667**System capability**: SystemCapability.Multimedia.Audio.Core 668 669| Name | Type | Mandatory| Description | 670| ------------ | ------------------------------------------------- | ---- | ------------------ | 671| samplingRate | [AudioSamplingRate](#audiosamplingrate8) | Yes | Audio sampling rate.| 672| channels | [AudioChannel](#audiochannel8) | Yes | Number of audio channels.| 673| sampleFormat | [AudioSampleFormat](#audiosampleformat8) | Yes | Audio sample format. | 674| encodingType | [AudioEncodingType](#audioencodingtype8) | Yes | Audio encoding type. | 675| channelLayout<sup>11+</sup> | [AudioChannelLayout](#audiochannellayout11) | No | Audio channel layout. The default value is **0x0**.| 676 677## AudioRendererInfo<sup>8+</sup> 678 679Describes audio renderer information. 680 681**System capability**: SystemCapability.Multimedia.Audio.Core 682 683| Name | Type | Mandatory | Description | 684| ------------- | --------------------------- | ---- | --------------- | 685| content | [ContentType](#contenttypedeprecated) | No | Audio content type.<br>This parameter is mandatory in API versions 8 and 9 and optional since API version 10. The default value is **CONTENT_TYPE_UNKNOWN**. [ContentType](#contenttypedeprecated) is deprecated. You are advised to use [StreamUsage](#streamusage) to declare the audio stream type.| 686| usage | [StreamUsage](#streamusage) | Yes | Audio stream usage.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 687| rendererFlags | number | Yes | Audio renderer flags.<br>The value **0** means an audio renderer.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 688 689## AudioRendererOptions<sup>8+</sup> 690 691Describes audio renderer configurations. 692 693| Name | Type | Mandatory | Description | 694| ------------ | ---------------------------------------- | ---- | ---------------- | 695| streamInfo | [AudioStreamInfo](#audiostreaminfo8) | Yes | Audio stream information.<br>**System capability**: SystemCapability.Multimedia.Audio.Renderer| 696| rendererInfo | [AudioRendererInfo](#audiorendererinfo8) | Yes | Audio renderer information.<br>**System capability**: SystemCapability.Multimedia.Audio.Renderer| 697| privacyType<sup>10+</sup> | [AudioPrivacyType](#audioprivacytype10) | No| Whether the audio stream can be recorded by other applications. The default value is **0**.<br>**System capability**: SystemCapability.Multimedia.Audio.PlaybackCapture| 698 699## AudioPrivacyType<sup>10+</sup> 700 701Enumerates whether an audio stream can be recorded by other applications. 702 703**System capability**: SystemCapability.Multimedia.Audio.PlaybackCapture 704 705| Name | Value | Description | 706| -------------------- | ---- | -------------------------------- | 707| PRIVACY_TYPE_PUBLIC | 0 | The audio stream can be recorded by other applications. | 708| PRIVACY_TYPE_PRIVATE | 1 | The audio stream cannot be recorded by other applications.| 709 710## InterruptEvent<sup>9+</sup> 711 712Describes the interruption event received by the application when playback is interrupted. 713 714**Atomic service API**: This API can be used in atomic services since API version 12. 715 716**System capability**: SystemCapability.Multimedia.Audio.Renderer 717 718| Name | Type |Mandatory | Description | 719| --------- | ------------------------------------------ | ---- | ------------------------------------ | 720| eventType | [InterruptType](#interrupttype) | Yes | Whether the interruption has started or ended. | 721| forceType | [InterruptForceType](#interruptforcetype9) | Yes | Whether the interruption is taken by the system or to be taken by the application.| 722| hintType | [InterruptHint](#interrupthint) | Yes | Hint provided along the interruption. | 723 724## VolumeEvent<sup>9+</sup> 725 726Describes the event received by the application when the volume is changed. 727 728**System capability**: SystemCapability.Multimedia.Audio.Volume 729 730| Name | Type | Mandatory | Description | 731| ---------- | ----------------------------------- | ---- |-------------------------------------------| 732| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 733| volume | number | Yes | Volume to set. The value range can be obtained by calling **getMinVolume** and **getMaxVolume**. | 734| updateUi | boolean | Yes | Whether the volume change is shown on the UI. The value **true** means that the volume change is shown, and **false** means the opposite. | 735 736## MicStateChangeEvent<sup>9+</sup> 737 738Describes the event received by the application when the microphone mute status is changed. 739 740**System capability**: SystemCapability.Multimedia.Audio.Device 741 742| Name | Type | Mandatory| Description | 743| ---------- | ----------------------------------- | ---- |-------------------------------------------------------- | 744| mute | boolean | Yes | Mute status of the microphone. The value **true** means that the microphone is muted, and **false** means the opposite. | 745 746## DeviceChangeAction 747 748Describes the device connection status and device information. 749 750**System capability**: SystemCapability.Multimedia.Audio.Device 751 752| Name | Type | Mandatory| Description | 753| :---------------- | :------------------------------------------------ | :--- | :----------------- | 754| type | [DeviceChangeType](#devicechangetype) | Yes | Device connection status.| 755| deviceDescriptors | [AudioDeviceDescriptors](#audiodevicedescriptors) | Yes | Device information. | 756 757## DeviceBlockStatusInfo<sup>13+</sup> 758 759Describes the audio device blocked status and device information. 760 761**System capability**: SystemCapability.Multimedia.Audio.Device 762 763| Name | Type | Mandatory| Description | 764| :---------------- | :------------------------------------------------ | :--- | :----------------- | 765| blockStatus | [DeviceBlockStatus](#deviceblockstatus13) | Yes | Blocked status of the audio device.| 766| devices | [AudioDeviceDescriptors](#audiodevicedescriptors) | Yes | Device information. | 767 768## ChannelBlendMode<sup>11+</sup> 769 770Enumerates the audio channel blending modes. 771 772**System capability**: SystemCapability.Multimedia.Audio.Core 773 774| Name | Value | Description | 775| :------------------------------------------- | :----- | :--------------------- | 776| MODE_DEFAULT | 0 | The audio channels are not blended. | 777| MODE_BLEND_LR | 1 | The left and right audio channels are blended.| 778| MODE_ALL_LEFT | 2 | The left channel is replicated into the right channel. | 779| MODE_ALL_RIGHT | 3 | The right channel is replicated into the left channel.| 780 781## AudioStreamDeviceChangeReason<sup>11+</sup> 782 783Enumerates the reasons for audio stream device is changed. 784 785**Atomic service API**: This API can be used in atomic services since API version 12. 786 787**System capability**: SystemCapability.Multimedia.Audio.Device 788 789| Name | Value | Description | 790|:------------------------------------------| :----- |:----------------| 791| REASON_UNKNOWN | 0 | Unknown reason. | 792| REASON_NEW_DEVICE_AVAILABLE | 1 | A new device is available. | 793| REASON_OLD_DEVICE_UNAVAILABLE | 2 | The old device is unavailable. When this reason is reported, the application should consider pausing audio playback.| 794| REASON_OVERRODE | 3 | Forcibly selected.| 795 796## AudioStreamDeviceChangeInfo<sup>11+</sup> 797 798Describes the event received by the application when the audio stream device is changed. 799 800**Atomic service API**: This API can be used in atomic services since API version 12. 801 802**System capability**: SystemCapability.Multimedia.Audio.Device 803 804| Name | Type | Mandatory| Description | 805| :---------------- |:------------------------------------------------------------------| :--- | :----------------- | 806| devices | [AudioDeviceDescriptors](#audiodevicedescriptors) | Yes | Device information.| 807| changeReason | [AudioStreamDeviceChangeReason](#audiostreamdevicechangereason11) | Yes | Reason for the change.| 808 809## DeviceChangeType 810 811Enumerates the device connection statuses. 812 813**System capability**: SystemCapability.Multimedia.Audio.Device 814 815| Name | Value | Description | 816| :--------- | :--- | :------------- | 817| CONNECT | 0 | Connected. | 818| DISCONNECT | 1 | Disconnected.| 819 820## DeviceBlockStatus<sup>13+</sup> 821 822Enumerates the blocked statuses of audio devices. 823 824**System capability**: SystemCapability.Multimedia.Audio.Device 825 826| Name | Value | Description | 827| :--------- | :--- | :------------- | 828| UNBLOCKED | 0 | The audio device is not blocked. | 829| BLOCKED | 1 | The audio device is blocked.| 830 831## AudioCapturerOptions<sup>8+</sup> 832 833Describes audio capturer configurations. 834 835| Name | Type | Mandatory| Description | 836| ----------------------------------- | --------------------------------------------------------- | ---- | ------------------------------------------------------------ | 837| streamInfo | [AudioStreamInfo](#audiostreaminfo8) | Yes | Audio stream information.<br>**System capability**: SystemCapability.Multimedia.Audio.Capturer | 838| capturerInfo | [AudioCapturerInfo](#audiocapturerinfo8) | Yes | Audio capturer information.<br>**System capability**: SystemCapability.Multimedia.Audio.Capturer | 839| playbackCaptureConfig<sup>(deprecated)</sup> | [AudioPlaybackCaptureConfig](#audioplaybackcaptureconfigdeprecated) | No | Configuration of internal audio recording.<br>**System capability**: SystemCapability.Multimedia.Audio.PlaybackCapture<br> This API is supported since API version 10 and deprecated since API version 12. The Audio module does not provide APIs for internal recording. You can use [AVScreenCapture](../apis-media-kit/_a_v_screen_capture.md) to perform internal recording.| 840 841## AudioCapturerInfo<sup>8+</sup> 842 843Describes audio capturer information. 844 845**System capability**: SystemCapability.Multimedia.Audio.Core 846 847| Name | Type | Mandatory| Description | 848| :------------ | :------------------------ | :--- | :--------------- | 849| source | [SourceType](#sourcetype8) | Yes | Audio source type. | 850| capturerFlags | number | Yes | Audio capturer flags.<br>The value **0** means an audio capturer.| 851 852## SourceType<sup>8+</sup> 853 854Enumerates the audio source types. 855 856| Name | Value | Description | 857| :------------------------------------------- | :----- | :--------------------- | 858| SOURCE_TYPE_INVALID | -1 | Invalid audio source.<br>**System capability**: SystemCapability.Multimedia.Audio.Core | 859| SOURCE_TYPE_MIC | 0 | Mic source.<br>**System capability**: SystemCapability.Multimedia.Audio.Core| 860| SOURCE_TYPE_VOICE_RECOGNITION<sup>9+</sup> | 1 | Voice recognition source.<br>**System capability**: SystemCapability.Multimedia.Audio.Core | 861| SOURCE_TYPE_PLAYBACK_CAPTURE<sup>(deprecated)</sup> | 2 | Internal audio recording source.<br>**System capability**: SystemCapability.Multimedia.Audio.PlaybackCapture<br> This API is supported since API version 10 and deprecated since API version 12. The Audio module does not provide APIs for internal recording. You can use [AVScreenCapture](../apis-media-kit/_a_v_screen_capture.md) to perform internal recording.| 862| SOURCE_TYPE_VOICE_COMMUNICATION | 7 | Voice communication source.<br>**System capability**: SystemCapability.Multimedia.Audio.Core| 863| SOURCE_TYPE_VOICE_MESSAGE<sup>12+</sup> | 10 | Voice message source.<br>**System capability**: SystemCapability.Multimedia.Audio.Core| 864| SOURCE_TYPE_CAMCORDER<sup>13+</sup> | 13 | Video recording source.<br>**System capability**: SystemCapability.Multimedia.Audio.Core| 865| 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**Required permissions**: ohos.permission.CAPTURE_VOICE_DOWNLINK_AUDIO 890 891- 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. 892 893- Since API version 11, **CaptureFilterOptions** does not support **StreamUsage.STREAM_USAGE_VOICE_COMMUNICATION**. Therefore, no permission is required for calling this API. 894 895**System capability**: SystemCapability.Multimedia.Audio.PlaybackCapture 896 897| Name | Type | Mandatory| Description | 898| ------ | ---------------------------------- | ---- | ------------------------------------------------------------ | 899| 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.| 900 901## AudioScene<sup>8+</sup> 902 903Enumerates the audio scenes. 904 905**System capability**: SystemCapability.Multimedia.Audio.Communication 906 907| Name | Value | Description | 908| :--------------------- | :----- | :-------------------------------------------- | 909| AUDIO_SCENE_DEFAULT | 0 | Default audio scene. | 910| AUDIO_SCENE_RINGING<sup>12+</sup> | 1 | Normal mode.| 911| AUDIO_SCENE_PHONE_CALL<sup>12+</sup> | 2 | Phone call scene.| 912| AUDIO_SCENE_VOICE_CHAT | 3 | Voice chat scene. | 913 914## AudioConcurrencyMode<sup>12+</sup> 915 916Enumerates the audio concurrency modes. 917 918**System capability**: SystemCapability.Multimedia.Audio.Core 919 920| Name | Value| Description | 921| :--------------------- |:--|:--------| 922| CONCURRENCY_DEFAULT | 0 | Uses the system strategy by default. | 923| CONCURRENCY_MIX_WITH_OTHERS | 1 | Mixes with other audio streams. | 924| CONCURRENCY_DUCK_OTHERS | 2 | Ducks other audio streams.| 925| CONCURRENCY_PAUSE_OTHERS | 3 | Pauses other audio streams.| 926 927## AudioSessionDeactivatedReason<sup>12+</sup> 928 929Enumerates the reasons for deactivating an audio session. 930 931**System capability**: SystemCapability.Multimedia.Audio.Core 932 933| Name | Value| Description | 934| :--------------------- |:--|:-------| 935| DEACTIVATED_LOWER_PRIORITY | 0 | The application focus is preempted.| 936| DEACTIVATED_TIMEOUT | 1 | The audio session times out. | 937 938## AudioSessionStrategy<sup>12+</sup> 939 940Describes an audio session strategy. 941 942**System capability**: SystemCapability.Multimedia.Audio.Core 943 944| Name | Type | Mandatory| Description | 945| :------------ |:------------------------------------------------| :--- | :--------------- | 946| concurrencyMode | [AudioConcurrencyMode](#audioconcurrencymode12) | Yes | Audio concurrency mode. | 947 948## AudioSessionDeactivatedEvent<sup>12+</sup> 949 950Describes the event indicating that an audio session is deactivated. 951 952**System capability**: SystemCapability.Multimedia.Audio.Core 953 954| Name | Type | Mandatory| Description | 955| :------------ |:------------------------------------------------------------------| :--- | :--------------- | 956| reason | [AudioSessionDeactivatedReason](#audiosessiondeactivatedreason12) | Yes | Reason for deactivating an audio session. | 957 958## AudioManager 959 960Implements audio volume and audio device management. Before calling any API in **AudioManager**, you must use [getAudioManager](#audiogetaudiomanager) to create an **AudioManager** instance. 961 962### setAudioParameter<sup>(deprecated)</sup> 963 964setAudioParameter(key: string, value: string, callback: AsyncCallback<void>): void 965 966Sets an audio parameter. This API uses an asynchronous callback to return the result. 967 968This 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. 969 970> **NOTE** 971> 972> This API is supported since API version 7 and deprecated since API version 11. The substitute API is available only for system applications. 973 974**Required permissions**: ohos.permission.MODIFY_AUDIO_SETTINGS 975 976**System capability**: SystemCapability.Multimedia.Audio.Core 977 978**Parameters** 979 980| Name | Type | Mandatory| Description | 981| -------- | ------------------------- | ---- | ------------------------ | 982| key | string | Yes | Key of the audio parameter to set. | 983| value | string | Yes | Value of the audio parameter to set. | 984| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 985 986**Example** 987 988```ts 989import { BusinessError } from '@kit.BasicServicesKit'; 990 991audioManager.setAudioParameter('key_example', 'value_example', (err: BusinessError) => { 992 if (err) { 993 console.error(`Failed to set the audio parameter. ${err}`); 994 return; 995 } 996 console.info('Callback invoked to indicate a successful setting of the audio parameter.'); 997}); 998``` 999 1000### setAudioParameter<sup>(deprecated)</sup> 1001 1002setAudioParameter(key: string, value: string): Promise<void> 1003 1004Sets an audio parameter. This API uses a promise to return the result. 1005 1006This 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. 1007 1008> **NOTE** 1009> 1010> This API is supported since API version 7 and deprecated since API version 11. The substitute API is available only for system applications. 1011 1012**Required permissions**: ohos.permission.MODIFY_AUDIO_SETTINGS 1013 1014**System capability**: SystemCapability.Multimedia.Audio.Core 1015 1016**Parameters** 1017 1018| Name| Type | Mandatory| Description | 1019| ------ | ------ | ---- | ---------------------- | 1020| key | string | Yes | Key of the audio parameter to set.| 1021| value | string | Yes | Value of the audio parameter to set.| 1022 1023**Return value** 1024 1025| Type | Description | 1026| ------------------- | ------------------------------- | 1027| Promise<void> | Promise that returns no value.| 1028 1029**Example** 1030 1031```ts 1032audioManager.setAudioParameter('key_example', 'value_example').then(() => { 1033 console.info('Promise returned to indicate a successful setting of the audio parameter.'); 1034}); 1035``` 1036 1037### getAudioParameter<sup>(deprecated)</sup> 1038 1039getAudioParameter(key: string, callback: AsyncCallback<string>): void 1040 1041Obtains the value of an audio parameter. This API uses an asynchronous callback to return the result. 1042 1043This 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. 1044 1045> **NOTE** 1046> 1047> This API is supported since API version 7 and deprecated since API version 11. The substitute API is available only for system applications. 1048 1049**System capability**: SystemCapability.Multimedia.Audio.Core 1050 1051**Parameters** 1052 1053| Name | Type | Mandatory| Description | 1054| -------- | --------------------------- | ---- | ---------------------------- | 1055| key | string | Yes | Key of the audio parameter whose value is to be obtained. | 1056| 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.| 1057 1058**Example** 1059 1060```ts 1061import { BusinessError } from '@kit.BasicServicesKit'; 1062 1063audioManager.getAudioParameter('key_example', (err: BusinessError, value: string) => { 1064 if (err) { 1065 console.error(`Failed to obtain the value of the audio parameter. ${err}`); 1066 return; 1067 } 1068 console.info(`Callback invoked to indicate that the value of the audio parameter is obtained ${value}.`); 1069}); 1070``` 1071 1072### getAudioParameter<sup>(deprecated)</sup> 1073 1074getAudioParameter(key: string): Promise<string> 1075 1076Obtains the value of an audio parameter. This API uses a promise to return the result. 1077 1078This 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. 1079 1080> **NOTE** 1081> 1082> This API is supported since API version 7 and deprecated since API version 11. The substitute API is available only for system applications. 1083 1084**System capability**: SystemCapability.Multimedia.Audio.Core 1085 1086**Parameters** 1087 1088| Name| Type | Mandatory| Description | 1089| ------ | ------ | ---- | ---------------------- | 1090| key | string | Yes | Key of the audio parameter whose value is to be obtained.| 1091 1092**Return value** 1093 1094| Type | Description | 1095| --------------------- | ----------------------------------- | 1096| Promise<string> | Promise used to return the value of the audio parameter.| 1097 1098**Example** 1099 1100```ts 1101audioManager.getAudioParameter('key_example').then((value: string) => { 1102 console.info(`Promise returned to indicate that the value of the audio parameter is obtained ${value}.`); 1103}); 1104``` 1105 1106### getAudioScene<sup>8+</sup> 1107 1108getAudioScene\(callback: AsyncCallback<AudioScene\>\): void 1109 1110Obtains the audio scene. This API uses an asynchronous callback to return the result. 1111 1112**System capability**: SystemCapability.Multimedia.Audio.Communication 1113 1114**Parameters** 1115 1116| Name | Type | Mandatory| Description | 1117| :------- | :-------------------------------------------------- | :--- | :--------------------------- | 1118| 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.| 1119 1120**Example** 1121 1122```ts 1123import { BusinessError } from '@kit.BasicServicesKit'; 1124 1125audioManager.getAudioScene((err: BusinessError, value: audio.AudioScene) => { 1126 if (err) { 1127 console.error(`Failed to obtain the audio scene mode. ${err}`); 1128 return; 1129 } 1130 console.info(`Callback invoked to indicate that the audio scene mode is obtained ${value}.`); 1131}); 1132``` 1133 1134### getAudioScene<sup>8+</sup> 1135 1136getAudioScene\(\): Promise<AudioScene\> 1137 1138Obtains the audio scene. This API uses a promise to return the result. 1139 1140**System capability**: SystemCapability.Multimedia.Audio.Communication 1141 1142**Return value** 1143 1144| Type | Description | 1145| :-------------------------------------------- | :--------------------------- | 1146| Promise<[AudioScene](#audioscene8)> | Promise used to return the audio scene.| 1147 1148**Example** 1149 1150```ts 1151import { BusinessError } from '@kit.BasicServicesKit'; 1152 1153audioManager.getAudioScene().then((value: audio.AudioScene) => { 1154 console.info(`Promise returned to indicate that the audio scene mode is obtained ${value}.`); 1155}).catch ((err: BusinessError) => { 1156 console.error(`Failed to obtain the audio scene mode ${err}`); 1157}); 1158``` 1159 1160### getAudioSceneSync<sup>10+</sup> 1161 1162getAudioSceneSync\(\): AudioScene 1163 1164Obtains the audio scene. This API returns the result synchronously. 1165 1166**System capability**: SystemCapability.Multimedia.Audio.Communication 1167 1168**Return value** 1169 1170| Type | Description | 1171| :-------------------------------------------- | :--------------------------- | 1172| [AudioScene](#audioscene8) | Audio scene.| 1173 1174**Example** 1175 1176```ts 1177import { BusinessError } from '@kit.BasicServicesKit'; 1178 1179try { 1180 let value: audio.AudioScene = audioManager.getAudioSceneSync(); 1181 console.info(`indicate that the audio scene mode is obtained ${value}.`); 1182} catch (err) { 1183 let error = err as BusinessError; 1184 console.error(`Failed to obtain the audio scene mode ${error}`); 1185} 1186``` 1187 1188### getVolumeManager<sup>9+</sup> 1189 1190getVolumeManager(): AudioVolumeManager 1191 1192Obtains an **AudioVolumeManager** instance. 1193 1194**System capability**: SystemCapability.Multimedia.Audio.Volume 1195 1196**Return value** 1197 1198| Type | Description | 1199|-----------------------------------------| ----------------------------- | 1200| [AudioVolumeManager](#audiovolumemanager9) | **AudioVolumeManager** instance.| 1201 1202**Example** 1203 1204```ts 1205import { audio } from '@kit.AudioKit'; 1206 1207let audioVolumeManager: audio.AudioVolumeManager = audioManager.getVolumeManager(); 1208``` 1209 1210### getStreamManager<sup>9+</sup> 1211 1212getStreamManager(): AudioStreamManager 1213 1214Obtains an **AudioStreamManager** instance. 1215 1216**System capability**: SystemCapability.Multimedia.Audio.Core 1217 1218**Return value** 1219 1220| Type | Description | 1221|--------------------------------------------| ----------------------------- | 1222| [AudioStreamManager](#audiostreammanager9) | **AudioStreamManager** instance.| 1223 1224**Example** 1225 1226```ts 1227import { audio } from '@kit.AudioKit'; 1228 1229let audioStreamManager: audio.AudioStreamManager = audioManager.getStreamManager(); 1230``` 1231 1232### getRoutingManager<sup>9+</sup> 1233 1234getRoutingManager(): AudioRoutingManager 1235 1236Obtains an **AudioRoutingManager** instance. 1237 1238**System capability**: SystemCapability.Multimedia.Audio.Device 1239 1240**Return value** 1241 1242| Type | Description | 1243|------------------------------------------| ----------------------------- | 1244| [AudioRoutingManager](#audioroutingmanager9) | **AudioRoutingManager** instance.| 1245 1246**Example** 1247 1248```ts 1249import { audio } from '@kit.AudioKit'; 1250 1251let audioRoutingManager: audio.AudioRoutingManager = audioManager.getRoutingManager(); 1252``` 1253 1254### getSessionManager<sup>12+</sup> 1255 1256getSessionManager(): AudioSessionManager 1257 1258Obtains an **AudioSessionManager** instance. 1259 1260**System capability**: SystemCapability.Multimedia.Audio.Core 1261 1262**Return value** 1263 1264| Type | Description | 1265|----------------------------------------------| ----------------------------- | 1266| [AudioSessionManager](#audiosessionmanager12) | **AudioSessionManager** instance.| 1267 1268**Example** 1269 1270```ts 1271import { audio } from '@kit.AudioKit'; 1272 1273let audioSessionManager: audio.AudioSessionManager = audioManager.getSessionManager(); 1274``` 1275 1276### setVolume<sup>(deprecated)</sup> 1277 1278setVolume(volumeType: AudioVolumeType, volume: number, callback: AsyncCallback<void>): void 1279 1280Sets the volume for a stream. This API uses an asynchronous callback to return the result. 1281 1282> **NOTE** 1283> 1284> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 1285> 1286> 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). 1287 1288**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 1289 1290This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**. 1291 1292**System capability**: SystemCapability.Multimedia.Audio.Volume 1293 1294**Parameters** 1295 1296| Name | Type | Mandatory| Description | 1297| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 1298| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1299| volume | number | Yes | Volume to set. The value range can be obtained by calling [getMinVolume](#getminvolumedeprecated) and [getMaxVolume](#getmaxvolumedeprecated).| 1300| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1301 1302**Example** 1303 1304```ts 1305import { BusinessError } from '@kit.BasicServicesKit'; 1306 1307audioManager.setVolume(audio.AudioVolumeType.MEDIA, 10, (err: BusinessError) => { 1308 if (err) { 1309 console.error(`Failed to set the volume. ${err}`); 1310 return; 1311 } 1312 console.info('Callback invoked to indicate a successful volume setting.'); 1313}); 1314``` 1315 1316### setVolume<sup>(deprecated)</sup> 1317 1318setVolume(volumeType: AudioVolumeType, volume: number): Promise<void> 1319 1320Sets the volume for a stream. This API uses a promise to return the result. 1321 1322> **NOTE** 1323> 1324> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 1325> 1326> 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). 1327 1328**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 1329 1330This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**. 1331 1332**System capability**: SystemCapability.Multimedia.Audio.Volume 1333 1334**Parameters** 1335 1336| Name | Type | Mandatory| Description | 1337| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 1338| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1339| volume | number | Yes | Volume to set. The value range can be obtained by calling [getMinVolume](#getminvolumedeprecated) and [getMaxVolume](#getmaxvolumedeprecated).| 1340 1341**Return value** 1342 1343| Type | Description | 1344| ------------------- | ----------------------------- | 1345| Promise<void> | Promise that returns no value.| 1346 1347**Example** 1348 1349```ts 1350audioManager.setVolume(audio.AudioVolumeType.MEDIA, 10).then(() => { 1351 console.info('Promise returned to indicate a successful volume setting.'); 1352}); 1353``` 1354 1355### getVolume<sup>(deprecated)</sup> 1356 1357getVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 1358 1359Obtains the volume of a stream. This API uses an asynchronous callback to return the result. 1360 1361> **NOTE** 1362> 1363> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getVolume](#getvolume9) in **AudioVolumeGroupManager**. 1364 1365**System capability**: SystemCapability.Multimedia.Audio.Volume 1366 1367**Parameters** 1368 1369| Name | Type | Mandatory| Description | 1370| ---------- | ----------------------------------- | ---- | ------------------ | 1371| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1372| 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).| 1373 1374**Example** 1375 1376```ts 1377import { BusinessError } from '@kit.BasicServicesKit'; 1378 1379audioManager.getVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { 1380 if (err) { 1381 console.error(`Failed to obtain the volume. ${err}`); 1382 return; 1383 } 1384 console.info('Callback invoked to indicate that the volume is obtained.'); 1385}); 1386``` 1387 1388### getVolume<sup>(deprecated)</sup> 1389 1390getVolume(volumeType: AudioVolumeType): Promise<number> 1391 1392Obtains the volume of a stream. This API uses a promise to return the result. 1393 1394> **NOTE** 1395> 1396> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getVolume](#getvolume9) in **AudioVolumeGroupManager**. 1397 1398**System capability**: SystemCapability.Multimedia.Audio.Volume 1399 1400**Parameters** 1401 1402| Name | Type | Mandatory| Description | 1403| ---------- | ----------------------------------- | ---- | ------------ | 1404| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 1405 1406**Return value** 1407 1408| Type | Description | 1409| --------------------- | ------------------------- | 1410| 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).| 1411 1412**Example** 1413 1414```ts 1415audioManager.getVolume(audio.AudioVolumeType.MEDIA).then((value: number) => { 1416 console.info(`Promise returned to indicate that the volume is obtained ${value} .`); 1417}); 1418``` 1419 1420### getMinVolume<sup>(deprecated)</sup> 1421 1422getMinVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 1423 1424Obtains the minimum volume allowed for a stream. This API uses an asynchronous callback to return the result. 1425 1426> **NOTE** 1427> 1428> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getMinVolume](#getminvolume9) in **AudioVolumeGroupManager**. 1429 1430**System capability**: SystemCapability.Multimedia.Audio.Volume 1431 1432**Parameters** 1433 1434| Name | Type | Mandatory| Description | 1435| ---------- | ----------------------------------- | ---- | ------------------ | 1436| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1437| 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.| 1438 1439**Example** 1440 1441```ts 1442import { BusinessError } from '@kit.BasicServicesKit'; 1443 1444audioManager.getMinVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { 1445 if (err) { 1446 console.error(`Failed to obtain the minimum volume. ${err}`); 1447 return; 1448 } 1449 console.info(`Callback invoked to indicate that the minimum volume is obtained. ${value}`); 1450}); 1451``` 1452 1453### getMinVolume<sup>(deprecated)</sup> 1454 1455getMinVolume(volumeType: AudioVolumeType): Promise<number> 1456 1457Obtains the minimum volume allowed for a stream. This API uses a promise to return the result. 1458 1459> **NOTE** 1460> 1461> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getMinVolume](#getminvolume9) in **AudioVolumeGroupManager**. 1462 1463**System capability**: SystemCapability.Multimedia.Audio.Volume 1464 1465**Parameters** 1466 1467| Name | Type | Mandatory| Description | 1468| ---------- | ----------------------------------- | ---- | ------------ | 1469| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 1470 1471**Return value** 1472 1473| Type | Description | 1474| --------------------- | ------------------------- | 1475| Promise<number> | Promise used to return the minimum volume.| 1476 1477**Example** 1478 1479```ts 1480audioManager.getMinVolume(audio.AudioVolumeType.MEDIA).then((value: number) => { 1481 console.info(`Promised returned to indicate that the minimum volume is obtained. ${value}`); 1482}); 1483``` 1484 1485### getMaxVolume<sup>(deprecated)</sup> 1486 1487getMaxVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 1488 1489Obtains the maximum volume allowed for a stream. This API uses an asynchronous callback to return the result. 1490 1491> **NOTE** 1492> 1493> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getMaxVolume](#getmaxvolume9) in **AudioVolumeGroupManager**. 1494 1495**System capability**: SystemCapability.Multimedia.Audio.Volume 1496 1497**Parameters** 1498 1499| Name | Type | Mandatory| Description | 1500| ---------- | ----------------------------------- | ---- | ---------------------- | 1501| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1502| 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.| 1503 1504**Example** 1505 1506```ts 1507import { BusinessError } from '@kit.BasicServicesKit'; 1508 1509audioManager.getMaxVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { 1510 if (err) { 1511 console.error(`Failed to obtain the maximum volume. ${err}`); 1512 return; 1513 } 1514 console.info(`Callback invoked to indicate that the maximum volume is obtained. ${value}`); 1515}); 1516``` 1517 1518### getMaxVolume<sup>(deprecated)</sup> 1519 1520getMaxVolume(volumeType: AudioVolumeType): Promise<number> 1521 1522Obtains the maximum volume allowed for a stream. This API uses a promise to return the result. 1523 1524> **NOTE** 1525> 1526> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getMaxVolume](#getmaxvolume9) in **AudioVolumeGroupManager**. 1527 1528**System capability**: SystemCapability.Multimedia.Audio.Volume 1529 1530**Parameters** 1531 1532| Name | Type | Mandatory| Description | 1533| ---------- | ----------------------------------- | ---- | ------------ | 1534| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 1535 1536**Return value** 1537 1538| Type | Description | 1539| --------------------- | ----------------------------- | 1540| Promise<number> | Promise used to return the maximum volume.| 1541 1542**Example** 1543 1544```ts 1545audioManager.getMaxVolume(audio.AudioVolumeType.MEDIA).then((data: number) => { 1546 console.info('Promised returned to indicate that the maximum volume is obtained.'); 1547}); 1548``` 1549 1550### mute<sup>(deprecated)</sup> 1551 1552mute(volumeType: AudioVolumeType, mute: boolean, callback: AsyncCallback<void>): void 1553 1554Mutes or unmutes a stream. This API uses an asynchronous callback to return the result. 1555 1556When 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. 1557 1558> **NOTE** 1559> 1560> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 1561 1562**System capability**: SystemCapability.Multimedia.Audio.Volume 1563 1564**Parameters** 1565 1566| Name | Type | Mandatory| Description | 1567| ---------- | ----------------------------------- | ---- | ------------------------------------- | 1568| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1569| mute | boolean | Yes | Mute status to set. The value **true** means to mute the stream, and **false** means the opposite.| 1570| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1571 1572**Example** 1573 1574```ts 1575import { BusinessError } from '@kit.BasicServicesKit'; 1576 1577audioManager.mute(audio.AudioVolumeType.MEDIA, true, (err: BusinessError) => { 1578 if (err) { 1579 console.error(`Failed to mute the stream. ${err}`); 1580 return; 1581 } 1582 console.info('Callback invoked to indicate that the stream is muted.'); 1583}); 1584``` 1585 1586### mute<sup>(deprecated)</sup> 1587 1588mute(volumeType: AudioVolumeType, mute: boolean): Promise<void> 1589 1590Mutes or unmutes a stream. This API uses a promise to return the result. 1591 1592When 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. 1593 1594> **NOTE** 1595> 1596> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 1597 1598**System capability**: SystemCapability.Multimedia.Audio.Volume 1599 1600**Parameters** 1601 1602| Name | Type | Mandatory| Description | 1603| ---------- | ----------------------------------- | ---- | ------------------------------------- | 1604| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1605| mute | boolean | Yes | Mute status to set. The value **true** means to mute the stream, and **false** means the opposite.| 1606 1607**Return value** 1608 1609| Type | Description | 1610| ------------------- | ----------------------------- | 1611| Promise<void> | Promise that returns no value.| 1612 1613**Example** 1614 1615 1616```ts 1617audioManager.mute(audio.AudioVolumeType.MEDIA, true).then(() => { 1618 console.info('Promise returned to indicate that the stream is muted.'); 1619}); 1620``` 1621 1622### isMute<sup>(deprecated)</sup> 1623 1624isMute(volumeType: AudioVolumeType, callback: AsyncCallback<boolean>): void 1625 1626Checks whether a stream is muted. This API uses an asynchronous callback to return the result. 1627 1628> **NOTE** 1629> 1630> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isMute](#ismute9) in **AudioVolumeGroupManager**. 1631 1632**System capability**: SystemCapability.Multimedia.Audio.Volume 1633 1634**Parameters** 1635 1636| Name | Type | Mandatory| Description | 1637| ---------- | ----------------------------------- | ---- | ----------------------------------------------- | 1638| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1639| 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.| 1640 1641**Example** 1642 1643```ts 1644import { BusinessError } from '@kit.BasicServicesKit'; 1645 1646audioManager.isMute(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: boolean) => { 1647 if (err) { 1648 console.error(`Failed to obtain the mute status. ${err}`); 1649 return; 1650 } 1651 console.info(`Callback invoked to indicate that the mute status of the stream is obtained. ${value}`); 1652}); 1653``` 1654 1655### isMute<sup>(deprecated)</sup> 1656 1657isMute(volumeType: AudioVolumeType): Promise<boolean> 1658 1659Checks whether a stream is muted. This API uses a promise to return the result. 1660 1661> **NOTE** 1662> 1663> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isMute](#ismute9) in **AudioVolumeGroupManager**. 1664 1665**System capability**: SystemCapability.Multimedia.Audio.Volume 1666 1667**Parameters** 1668 1669| Name | Type | Mandatory| Description | 1670| ---------- | ----------------------------------- | ---- | ------------ | 1671| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 1672 1673**Return value** 1674 1675| Type | Description | 1676| ---------------------- | ------------------------------------------------------ | 1677| 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.| 1678 1679**Example** 1680 1681```ts 1682audioManager.isMute(audio.AudioVolumeType.MEDIA).then((value: boolean) => { 1683 console.info(`Promise returned to indicate that the mute status of the stream is obtained ${value}.`); 1684}); 1685``` 1686 1687### isActive<sup>(deprecated)</sup> 1688 1689isActive(volumeType: AudioVolumeType, callback: AsyncCallback<boolean>): void 1690 1691Checks whether a stream is active. This API uses an asynchronous callback to return the result. 1692 1693> **NOTE** 1694> 1695> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isActive](#isactive9) in **AudioStreamManager**. 1696 1697**System capability**: SystemCapability.Multimedia.Audio.Volume 1698 1699**Parameters** 1700 1701| Name | Type | Mandatory| Description | 1702| ---------- | ----------------------------------- | ---- | ------------------------------------------------- | 1703| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1704| 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.| 1705 1706**Example** 1707 1708```ts 1709import { BusinessError } from '@kit.BasicServicesKit'; 1710 1711audioManager.isActive(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: boolean) => { 1712 if (err) { 1713 console.error(`Failed to obtain the active status of the stream. ${err}`); 1714 return; 1715 } 1716 console.info(`Callback invoked to indicate that the active status of the stream is obtained ${value}.`); 1717}); 1718``` 1719 1720### isActive<sup>(deprecated)</sup> 1721 1722isActive(volumeType: AudioVolumeType): Promise<boolean> 1723 1724Checks whether a stream is active. This API uses a promise to return the result. 1725 1726> **NOTE** 1727> 1728> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isActive](#isactive9) in **AudioStreamManager**. 1729 1730**System capability**: SystemCapability.Multimedia.Audio.Volume 1731 1732**Parameters** 1733 1734| Name | Type | Mandatory| Description | 1735| ---------- | ----------------------------------- | ---- | ------------ | 1736| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 1737 1738**Return value** 1739 1740| Type | Description | 1741| ---------------------- | -------------------------------------------------------- | 1742| 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.| 1743 1744**Example** 1745 1746```ts 1747audioManager.isActive(audio.AudioVolumeType.MEDIA).then((value: boolean) => { 1748 console.info(`Promise returned to indicate that the active status of the stream is obtained ${value}.`); 1749}); 1750``` 1751 1752### setRingerMode<sup>(deprecated)</sup> 1753 1754setRingerMode(mode: AudioRingMode, callback: AsyncCallback<void>): void 1755 1756Sets the ringer mode. This API uses an asynchronous callback to return the result. 1757 1758> **NOTE** 1759> 1760> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 1761 1762**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 1763 1764This permission is required only for muting or unmuting the ringer. 1765 1766**System capability**: SystemCapability.Multimedia.Audio.Communication 1767 1768**Parameters** 1769 1770| Name | Type | Mandatory| Description | 1771| -------- | ------------------------------- | ---- | ------------------------ | 1772| mode | [AudioRingMode](#audioringmode) | Yes | Ringer mode. | 1773| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1774 1775**Example** 1776 1777```ts 1778import { BusinessError } from '@kit.BasicServicesKit'; 1779 1780audioManager.setRingerMode(audio.AudioRingMode.RINGER_MODE_NORMAL, (err: BusinessError) => { 1781 if (err) { 1782 console.error(`Failed to set the ringer mode. ${err}`); 1783 return; 1784 } 1785 console.info('Callback invoked to indicate a successful setting of the ringer mode.'); 1786}); 1787``` 1788 1789### setRingerMode<sup>(deprecated)</sup> 1790 1791setRingerMode(mode: AudioRingMode): Promise<void> 1792 1793Sets the ringer mode. This API uses a promise to return the result. 1794 1795> **NOTE** 1796> 1797> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 1798 1799 1800**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 1801 1802This permission is required only for muting or unmuting the ringer. 1803 1804**System capability**: SystemCapability.Multimedia.Audio.Communication 1805 1806**Parameters** 1807 1808| Name| Type | Mandatory| Description | 1809| ------ | ------------------------------- | ---- | -------------- | 1810| mode | [AudioRingMode](#audioringmode) | Yes | Ringer mode.| 1811 1812**Return value** 1813 1814| Type | Description | 1815| ------------------- | ------------------------------- | 1816| Promise<void> | Promise that returns no value.| 1817 1818**Example** 1819 1820```ts 1821audioManager.setRingerMode(audio.AudioRingMode.RINGER_MODE_NORMAL).then(() => { 1822 console.info('Promise returned to indicate a successful setting of the ringer mode.'); 1823}); 1824``` 1825 1826### getRingerMode<sup>(deprecated)</sup> 1827 1828getRingerMode(callback: AsyncCallback<AudioRingMode>): void 1829 1830Obtains the ringer mode. This API uses an asynchronous callback to return the result. 1831 1832> **NOTE** 1833> 1834> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getRingerMode](#getringermode9) in **AudioVolumeGroupManager**. 1835 1836**System capability**: SystemCapability.Multimedia.Audio.Communication 1837 1838**Parameters** 1839 1840| Name | Type | Mandatory| Description | 1841| -------- | ---------------------------------------------------- | ---- | ------------------------ | 1842| 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.| 1843 1844**Example** 1845 1846```ts 1847import { BusinessError } from '@kit.BasicServicesKit'; 1848 1849audioManager.getRingerMode((err: BusinessError, value: audio.AudioRingMode) => { 1850 if (err) { 1851 console.error(`Failed to obtain the ringer mode. ${err}`); 1852 return; 1853 } 1854 console.info(`Callback invoked to indicate that the ringer mode is obtained ${value}.`); 1855}); 1856``` 1857 1858### getRingerMode<sup>(deprecated)</sup> 1859 1860getRingerMode(): Promise<AudioRingMode> 1861 1862Obtains the ringer mode. This API uses a promise to return the result. 1863 1864> **NOTE** 1865> 1866> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getRingerMode](#getringermode9) in **AudioVolumeGroupManager**. 1867 1868**System capability**: SystemCapability.Multimedia.Audio.Communication 1869 1870**Return value** 1871 1872| Type | Description | 1873| ---------------------------------------------- | ------------------------------- | 1874| Promise<[AudioRingMode](#audioringmode)> | Promise used to return the ringer mode.| 1875 1876**Example** 1877 1878```ts 1879audioManager.getRingerMode().then((value: audio.AudioRingMode) => { 1880 console.info(`Promise returned to indicate that the ringer mode is obtained ${value}.`); 1881}); 1882``` 1883 1884### getDevices<sup>(deprecated)</sup> 1885 1886getDevices(deviceFlag: DeviceFlag, callback: AsyncCallback<AudioDeviceDescriptors>): void 1887 1888Obtains the audio devices with a specific flag. This API uses an asynchronous callback to return the result. 1889 1890> **NOTE** 1891> 1892> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getDevices](#getdevices9) in **AudioRoutingManager**. 1893 1894**System capability**: SystemCapability.Multimedia.Audio.Device 1895 1896**Parameters** 1897 1898| Name | Type | Mandatory| Description | 1899| ---------- | ------------------------------------------------------------ | ---- | -------------------- | 1900| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag. | 1901| 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.| 1902 1903**Example** 1904```ts 1905import { BusinessError } from '@kit.BasicServicesKit'; 1906 1907audioManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG, (err: BusinessError, value: audio.AudioDeviceDescriptors) => { 1908 if (err) { 1909 console.error(`Failed to obtain the device list. ${err}`); 1910 return; 1911 } 1912 console.info('Callback invoked to indicate that the device list is obtained.'); 1913}); 1914``` 1915 1916### getDevices<sup>(deprecated)</sup> 1917 1918getDevices(deviceFlag: DeviceFlag): Promise<AudioDeviceDescriptors> 1919 1920Obtains the audio devices with a specific flag. This API uses a promise to return the result. 1921 1922> **NOTE** 1923> 1924> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getDevices](#getdevices9) in **AudioRoutingManager**. 1925 1926**System capability**: SystemCapability.Multimedia.Audio.Device 1927 1928**Parameters** 1929 1930| Name | Type | Mandatory| Description | 1931| ---------- | ------------------------- | ---- | ---------------- | 1932| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag.| 1933 1934**Return value** 1935 1936| Type | Description | 1937| ------------------------------------------------------------ | ------------------------- | 1938| Promise<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Promise used to return the device list.| 1939 1940**Example** 1941 1942```ts 1943audioManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG).then((data: audio.AudioDeviceDescriptors) => { 1944 console.info('Promise returned to indicate that the device list is obtained.'); 1945}); 1946``` 1947 1948### setDeviceActive<sup>(deprecated)</sup> 1949 1950setDeviceActive(deviceType: ActiveDeviceType, active: boolean, callback: AsyncCallback<void>): void 1951 1952Sets a device to the active state. This API uses an asynchronous callback to return the result. 1953 1954> **NOTE** 1955> 1956> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setCommunicationDevice](#setcommunicationdevice9) in **AudioRoutingManager**. 1957 1958**System capability**: SystemCapability.Multimedia.Audio.Device 1959 1960**Parameters** 1961 1962| Name | Type | Mandatory| Description | 1963| ---------- | ------------------------------------- | ---- |-------------| 1964| deviceType | [ActiveDeviceType](#activedevicetypedeprecated) | Yes | Active audio device type. | 1965| active | boolean | Yes | Active state to set. The value **true** means to set the device to the active state, and **false** means the opposite. | 1966| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1967 1968**Example** 1969 1970```ts 1971import { BusinessError } from '@kit.BasicServicesKit'; 1972 1973audioManager.setDeviceActive(audio.ActiveDeviceType.SPEAKER, true, (err: BusinessError) => { 1974 if (err) { 1975 console.error(`Failed to set the active status of the device. ${err}`); 1976 return; 1977 } 1978 console.info('Callback invoked to indicate that the device is set to the active status.'); 1979}); 1980``` 1981 1982### setDeviceActive<sup>(deprecated)</sup> 1983 1984setDeviceActive(deviceType: ActiveDeviceType, active: boolean): Promise<void> 1985 1986Sets a device to the active state. This API uses a promise to return the result. 1987 1988> **NOTE** 1989> 1990> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setCommunicationDevice](#setcommunicationdevice9) in **AudioRoutingManager**. 1991 1992**System capability**: SystemCapability.Multimedia.Audio.Device 1993 1994**Parameters** 1995 1996| Name | Type | Mandatory| Description | 1997| ---------- | ------------------------------------- | ---- | ------------------ | 1998| deviceType | [ActiveDeviceType](#activedevicetypedeprecated) | Yes | Active audio device type.| 1999| active | boolean | Yes | Active state to set. The value **true** means to set the device to the active state, and **false** means the opposite. | 2000 2001**Return value** 2002 2003| Type | Description | 2004| ------------------- | ------------------------------- | 2005| Promise<void> | Promise that returns no value.| 2006 2007**Example** 2008 2009 2010```ts 2011audioManager.setDeviceActive(audio.ActiveDeviceType.SPEAKER, true).then(() => { 2012 console.info('Promise returned to indicate that the device is set to the active status.'); 2013}); 2014``` 2015 2016### isDeviceActive<sup>(deprecated)</sup> 2017 2018isDeviceActive(deviceType: ActiveDeviceType, callback: AsyncCallback<boolean>): void 2019 2020Checks whether a device is active. This API uses an asynchronous callback to return the result. 2021 2022> **NOTE** 2023> 2024> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isCommunicationDeviceActive](#iscommunicationdeviceactive9) in **AudioRoutingManager**. 2025 2026**System capability**: SystemCapability.Multimedia.Audio.Device 2027 2028**Parameters** 2029 2030| Name | Type | Mandatory| Description | 2031| ---------- | ------------------------------------- | ---- | ------------------------ | 2032| deviceType | [ActiveDeviceType](#activedevicetypedeprecated) | Yes | Active audio device type. | 2033| 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.| 2034 2035**Example** 2036 2037```ts 2038import { BusinessError } from '@kit.BasicServicesKit'; 2039 2040audioManager.isDeviceActive(audio.ActiveDeviceType.SPEAKER, (err: BusinessError, value: boolean) => { 2041 if (err) { 2042 console.error(`Failed to obtain the active status of the device. ${err}`); 2043 return; 2044 } 2045 console.info('Callback invoked to indicate that the active status of the device is obtained.'); 2046}); 2047``` 2048 2049### isDeviceActive<sup>(deprecated)</sup> 2050 2051isDeviceActive(deviceType: ActiveDeviceType): Promise<boolean> 2052 2053Checks whether a device is active. This API uses a promise to return the result. 2054 2055> **NOTE** 2056> 2057> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isCommunicationDeviceActive](#iscommunicationdeviceactive9) in **AudioRoutingManager**. 2058 2059**System capability**: SystemCapability.Multimedia.Audio.Device 2060 2061**Parameters** 2062 2063| Name | Type | Mandatory| Description | 2064| ---------- | ------------------------------------- | ---- | ------------------ | 2065| deviceType | [ActiveDeviceType](#activedevicetypedeprecated) | Yes | Active audio device type.| 2066 2067**Return value** 2068 2069| Type | Description | 2070| ---------------------- |---------------------------------------| 2071| 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. | 2072 2073**Example** 2074 2075```ts 2076audioManager.isDeviceActive(audio.ActiveDeviceType.SPEAKER).then((value: boolean) => { 2077 console.info(`Promise returned to indicate that the active status of the device is obtained ${value}.`); 2078}); 2079``` 2080 2081### setMicrophoneMute<sup>(deprecated)</sup> 2082 2083setMicrophoneMute(mute: boolean, callback: AsyncCallback<void>): void 2084 2085Mutes or unmutes the microphone. This API uses an asynchronous callback to return the result. 2086 2087> **NOTE** 2088> 2089> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 2090 2091**Required permissions**: ohos.permission.MICROPHONE 2092 2093**System capability**: SystemCapability.Multimedia.Audio.Device 2094 2095**Parameters** 2096 2097| Name | Type | Mandatory| Description | 2098| -------- | ------------------------- | ---- | --------------------------------------------- | 2099| mute | boolean | Yes | Mute status to set. The value **true** means to mute the microphone, and **false** means the opposite.| 2100| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 2101 2102**Example** 2103 2104```ts 2105import { BusinessError } from '@kit.BasicServicesKit'; 2106 2107audioManager.setMicrophoneMute(true, (err: BusinessError) => { 2108 if (err) { 2109 console.error(`Failed to mute the microphone. ${err}`); 2110 return; 2111 } 2112 console.info('Callback invoked to indicate that the microphone is muted.'); 2113}); 2114``` 2115 2116### setMicrophoneMute<sup>(deprecated)</sup> 2117 2118setMicrophoneMute(mute: boolean): Promise<void> 2119 2120Mutes or unmutes the microphone. This API uses a promise to return the result. 2121 2122> **NOTE** 2123> 2124> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 2125 2126**Required permissions**: ohos.permission.MICROPHONE 2127 2128**System capability**: SystemCapability.Multimedia.Audio.Device 2129 2130**Parameters** 2131 2132| Name| Type | Mandatory| Description | 2133| ------ | ------- | ---- | --------------------------------------------- | 2134| mute | boolean | Yes | Mute status to set. The value **true** means to mute the microphone, and **false** means the opposite.| 2135 2136**Return value** 2137 2138| Type | Description | 2139| ------------------- | ------------------------------- | 2140| Promise<void> | Promise that returns no value.| 2141 2142**Example** 2143 2144```ts 2145audioManager.setMicrophoneMute(true).then(() => { 2146 console.info('Promise returned to indicate that the microphone is muted.'); 2147}); 2148``` 2149 2150### isMicrophoneMute<sup>(deprecated)</sup> 2151 2152isMicrophoneMute(callback: AsyncCallback<boolean>): void 2153 2154Checks whether the microphone is muted. This API uses an asynchronous callback to return the result. 2155 2156> **NOTE** 2157> 2158> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isMicrophoneMute](#ismicrophonemute9) in **AudioVolumeGroupManager**. 2159 2160**Required permissions**: ohos.permission.MICROPHONE 2161 2162**System capability**: SystemCapability.Multimedia.Audio.Device 2163 2164**Parameters** 2165 2166| Name | Type | Mandatory| Description | 2167| -------- | ---------------------------- | ---- | ------------------------------------------------------- | 2168| 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.| 2169 2170**Example** 2171 2172```ts 2173import { BusinessError } from '@kit.BasicServicesKit'; 2174 2175audioManager.isMicrophoneMute((err: BusinessError, value: boolean) => { 2176 if (err) { 2177 console.error(`Failed to obtain the mute status of the microphone. ${err}`); 2178 return; 2179 } 2180 console.info(`Callback invoked to indicate that the mute status of the microphone is obtained ${value}.`); 2181}); 2182``` 2183 2184### isMicrophoneMute<sup>(deprecated)</sup> 2185 2186isMicrophoneMute(): Promise<boolean> 2187 2188Checks whether the microphone is muted. This API uses a promise to return the result. 2189 2190> **NOTE** 2191> 2192> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isMicrophoneMute](#ismicrophonemute9) in **AudioVolumeGroupManager**. 2193 2194**Required permissions**: ohos.permission.MICROPHONE 2195 2196**System capability**: SystemCapability.Multimedia.Audio.Device 2197 2198**Return value** 2199 2200| Type | Description | 2201| ---------------------- | ------------------------------------------------------------ | 2202| 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.| 2203 2204**Example** 2205 2206```ts 2207audioManager.isMicrophoneMute().then((value: boolean) => { 2208 console.info(`Promise returned to indicate that the mute status of the microphone is obtained ${value}.`); 2209}); 2210``` 2211 2212### on('deviceChange')<sup>(deprecated)</sup> 2213 2214on(type: 'deviceChange', callback: Callback<DeviceChangeAction\>): void 2215 2216Subscribes 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. 2217 2218> **NOTE** 2219> 2220> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [on('deviceChange')](#ondevicechange9) in **AudioRoutingManager**. 2221 2222**System capability**: SystemCapability.Multimedia.Audio.Device 2223 2224**Parameters** 2225 2226| Name | Type | Mandatory| Description | 2227| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- | 2228| type | string | Yes | Event type. The value is fixed at **'deviceChange'**.| 2229| callback | Callback<[DeviceChangeAction](#devicechangeaction)\> | Yes | Callback used to return the device change details.| 2230 2231**Example** 2232 2233```ts 2234audioManager.on('deviceChange', (deviceChanged: audio.DeviceChangeAction) => { 2235 console.info(`device change type : ${deviceChanged.type} `); 2236 console.info(`device descriptor size : ${deviceChanged.deviceDescriptors.length} `); 2237 console.info(`device change descriptor : ${deviceChanged.deviceDescriptors[0].deviceRole} `); 2238 console.info(`device change descriptor : ${deviceChanged.deviceDescriptors[0].deviceType} `); 2239}); 2240``` 2241 2242### off('deviceChange')<sup>(deprecated)</sup> 2243 2244off(type: 'deviceChange', callback?: Callback<DeviceChangeAction\>): void 2245 2246Unsubscribes from the audio device change event. This API uses an asynchronous callback to return the result. 2247 2248> **NOTE** 2249> 2250> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [off('deviceChange')](#offdevicechange9) in **AudioRoutingManager**. 2251 2252**System capability**: SystemCapability.Multimedia.Audio.Device 2253 2254**Parameters** 2255 2256| Name | Type | Mandatory| Description | 2257| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 2258| type | string | Yes | Event type. The value is fixed at **'deviceChange'**.| 2259| callback | Callback<[DeviceChangeAction](#devicechangeaction)> | No | Callback used to return the device change details.| 2260 2261**Example** 2262 2263```ts 2264// Cancel all subscriptions to the event. 2265audioManager.off('deviceChange'); 2266 2267// 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. 2268let deviceChangeCallback = (deviceChanged: audio.DeviceChangeAction) => { 2269 console.info(`device change type : ${deviceChanged.type} `); 2270 console.info(`device descriptor size : ${deviceChanged.deviceDescriptors.length} `); 2271 console.info(`device change descriptor : ${deviceChanged.deviceDescriptors[0].deviceRole} `); 2272 console.info(`device change descriptor : ${deviceChanged.deviceDescriptors[0].deviceType} `); 2273}; 2274 2275audioManager.on('deviceChange', deviceChangeCallback); 2276 2277audioManager.off('deviceChange', deviceChangeCallback); 2278``` 2279 2280### on('interrupt')<sup>(deprecated)</sup> 2281 2282on(type: 'interrupt', interrupt: AudioInterrupt, callback: Callback\<InterruptAction>): void 2283 2284Subscribes 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. 2285 2286Same 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. 2287 2288> **NOTE** 2289> 2290> This API is supported since API version 7 and deprecated since API version 11. You are advised to use [on('audioInterrupt')](#onaudiointerrupt10) in **AudioCapturer**. 2291 2292**System capability**: SystemCapability.Multimedia.Audio.Renderer 2293 2294**Parameters** 2295 2296| Name | Type | Mandatory| Description | 2297| --------- |---------------------------------------------------------| ---- | ------------------------------------------------------------ | 2298| type | string | Yes | Event type. The value is fixed at **'interrupt'**.| 2299| interrupt | [AudioInterrupt](#audiointerruptdeprecated) | Yes | Audio interruption event type. | 2300| callback | Callback<[InterruptAction](#interruptactiondeprecated)> | Yes | Callback used to return the audio interruption event.| 2301 2302**Example** 2303 2304```ts 2305import { audio } from '@kit.AudioKit'; 2306 2307let interAudioInterrupt: audio.AudioInterrupt = { 2308 streamUsage:2, 2309 contentType:0, 2310 pauseWhenDucked:true 2311}; 2312 2313audioManager.on('interrupt', interAudioInterrupt, (interruptAction: audio.InterruptAction) => { 2314 if (interruptAction.actionType === 0) { 2315 console.info('An event to gain the audio focus starts.'); 2316 console.info(`Focus gain event: ${interruptAction} `); 2317 } 2318 if (interruptAction.actionType === 1) { 2319 console.info('An audio interruption event starts.'); 2320 console.info(`Audio interruption event: ${interruptAction} `); 2321 } 2322}); 2323``` 2324 2325### off('interrupt')<sup>(deprecated)</sup> 2326 2327off(type: 'interrupt', interrupt: AudioInterrupt, callback?: Callback\<InterruptAction>): void 2328 2329Unsubscribes from the audio interruption event. This API uses an asynchronous callback to return the result. 2330 2331> **NOTE** 2332> 2333> This API is supported since API version 7 and deprecated since API version 11. You are advised to use [off('audioInterrupt')](#offaudiointerrupt10) in **AudioCapturer**. 2334 2335**System capability**: SystemCapability.Multimedia.Audio.Renderer 2336 2337**Parameters** 2338 2339| Name | Type | Mandatory| Description | 2340| --------- |---------------------------------------------------------| ---- | ------------------------------------------------------------ | 2341| type | string | Yes | Event type. The value is fixed at **'interrupt'**.| 2342| interrupt | [AudioInterrupt](#audiointerruptdeprecated) | Yes | Audio interruption event type. | 2343| callback | Callback<[InterruptAction](#interruptactiondeprecated)> | No | Callback used to return the audio interruption event.| 2344 2345**Example** 2346 2347```ts 2348import { audio } from '@kit.AudioKit'; 2349 2350let interAudioInterrupt: audio.AudioInterrupt = { 2351 streamUsage:2, 2352 contentType:0, 2353 pauseWhenDucked:true 2354}; 2355 2356// Cancel all subscriptions to the event. 2357audioManager.off('interrupt', interAudioInterrupt); 2358 2359// 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. 2360let interruptCallback = (interruptAction: audio.InterruptAction) => { 2361 if (interruptAction.actionType === 0) { 2362 console.info('An event to gain the audio focus starts.'); 2363 console.info(`Focus gain event: ${interruptAction} `); 2364 } 2365 if (interruptAction.actionType === 1) { 2366 console.info('An audio interruption event starts.'); 2367 console.info(`Audio interruption event: ${interruptAction} `); 2368 } 2369}; 2370 2371audioManager.on('interrupt', interAudioInterrupt, interruptCallback); 2372 2373audioManager.off('interrupt', interAudioInterrupt, interruptCallback); 2374``` 2375 2376## AudioVolumeManager<sup>9+</sup> 2377 2378Implements audio volume management. Before calling an API in **AudioVolumeManager**, you must use [getVolumeManager](#getvolumemanager9) to obtain an **AudioVolumeManager** instance. 2379 2380### getVolumeGroupManager<sup>9+</sup> 2381 2382getVolumeGroupManager(groupId: number, callback: AsyncCallback<AudioVolumeGroupManager\>\): void 2383 2384Obtains the volume group manager. This API uses an asynchronous callback to return the result. 2385 2386**System capability**: SystemCapability.Multimedia.Audio.Volume 2387 2388**Parameters** 2389 2390| Name | Type | Mandatory| Description | 2391| ---------- | ------------------------------------------------------------ | ---- |-----------------------------------------------------------| 2392| groupId | number | Yes | Volume group ID. The default value is **LOCAL_VOLUME_GROUP_ID**. | 2393| 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.| 2394 2395**Example** 2396 2397```ts 2398import { BusinessError } from '@kit.BasicServicesKit'; 2399 2400let groupId: number = audio.DEFAULT_VOLUME_GROUP_ID; 2401 2402audioVolumeManager.getVolumeGroupManager(groupId, (err: BusinessError, value: audio.AudioVolumeGroupManager) => { 2403 if (err) { 2404 console.error(`Failed to obtain the volume group infos list. ${err}`); 2405 return; 2406 } 2407 console.info('Callback invoked to indicate that the volume group infos list is obtained.'); 2408}); 2409 2410``` 2411 2412### getVolumeGroupManager<sup>9+</sup> 2413 2414getVolumeGroupManager(groupId: number\): Promise<AudioVolumeGroupManager\> 2415 2416Obtains the volume group manager. This API uses a promise to return the result. 2417 2418**System capability**: SystemCapability.Multimedia.Audio.Volume 2419 2420**Parameters** 2421 2422| Name | Type | Mandatory| Description | 2423| ---------- | ---------------------------------------- | ---- |----------------------------------| 2424| groupId | number | Yes | Volume group ID. The default value is **LOCAL_VOLUME_GROUP_ID**.| 2425 2426**Return value** 2427 2428| Type | Description | 2429| ------------------- | ----------------------------- | 2430| Promise< [AudioVolumeGroupManager](#audiovolumegroupmanager9) > | Promise used to return the volume group manager.| 2431 2432**Example** 2433 2434```ts 2435import { audio } from '@kit.AudioKit'; 2436 2437let groupId: number = audio.DEFAULT_VOLUME_GROUP_ID; 2438let audioVolumeGroupManager: audio.AudioVolumeGroupManager | undefined = undefined; 2439 2440async function getVolumeGroupManager(){ 2441 audioVolumeGroupManager = await audioVolumeManager.getVolumeGroupManager(groupId); 2442 console.info('Promise returned to indicate that the volume group infos list is obtained.'); 2443} 2444``` 2445 2446### getVolumeGroupManagerSync<sup>10+</sup> 2447 2448getVolumeGroupManagerSync(groupId: number\): AudioVolumeGroupManager 2449 2450Obtains the volume group manager. This API returns the result synchronously. 2451 2452**System capability**: SystemCapability.Multimedia.Audio.Volume 2453 2454**Parameters** 2455 2456| Name | Type | Mandatory| Description | 2457| ---------- | ---------------------------------------- | ---- |----------------------------------| 2458| groupId | number | Yes | Volume group ID. The default value is **LOCAL_VOLUME_GROUP_ID**.| 2459 2460**Return value** 2461 2462| Type | Description | 2463| ------------------- | ----------------------------- | 2464| [AudioVolumeGroupManager](#audiovolumegroupmanager9) | Volume group manager.| 2465 2466**Error codes** 2467 2468For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2469 2470| ID| Error Message| 2471| ------- | --------------------------------------------| 2472| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2473| 6800101 | Parameter verification failed. | 2474 2475**Example** 2476 2477```ts 2478import { BusinessError } from '@kit.BasicServicesKit'; 2479 2480try { 2481 let audioVolumeGroupManager: audio.AudioVolumeGroupManager = audioVolumeManager.getVolumeGroupManagerSync(audio.DEFAULT_VOLUME_GROUP_ID); 2482 console.info(`Get audioVolumeGroupManager success.`); 2483} catch (err) { 2484 let error = err as BusinessError; 2485 console.error(`Failed to get audioVolumeGroupManager, error: ${error}`); 2486} 2487``` 2488 2489### on('volumeChange')<sup>9+</sup> 2490 2491on(type: 'volumeChange', callback: Callback\<VolumeEvent>): void 2492 2493Subscribes 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. 2494 2495**System capability**: SystemCapability.Multimedia.Audio.Volume 2496 2497**Parameters** 2498 2499| Name | Type | Mandatory| Description | 2500| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 2501| type | string | Yes | Event type. The value is fixed at **'volumeChange'**.| 2502| callback | Callback<[VolumeEvent](#volumeevent9)> | Yes | Callback used to return the changed volume.| 2503 2504**Error codes** 2505 2506For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2507 2508| ID| Error Message| 2509| ------- | --------------------------------------------| 2510| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2511| 6800101 | Parameter verification failed. | 2512 2513**Example** 2514 2515```ts 2516audioVolumeManager.on('volumeChange', (volumeEvent: audio.VolumeEvent) => { 2517 console.info(`VolumeType of stream: ${volumeEvent.volumeType} `); 2518 console.info(`Volume level: ${volumeEvent.volume} `); 2519 console.info(`Whether to updateUI: ${volumeEvent.updateUi} `); 2520}); 2521``` 2522 2523### off('volumeChange')<sup>12+</sup> 2524 2525off(type: 'volumeChange', callback?: Callback\<VolumeEvent>): void 2526 2527Unsubscribes from the system volume change event. This API uses an asynchronous callback to return the result. 2528 2529**System capability**: SystemCapability.Multimedia.Audio.Volume 2530 2531**Parameters** 2532 2533| Name | Type | Mandatory| Description | 2534| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 2535| type | string | Yes | Event type. The value is fixed at **'volumeChange'**.| 2536| callback | Callback<[VolumeEvent](#volumeevent9)> | No | Callback used to return the changed volume.| 2537 2538**Error codes** 2539 2540For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2541 2542| ID| Error Message| 2543| ------- | --------------------------------------------| 2544| 401 | Parameter error. Possible causes: 1.Mandatory parameters missing; 2.Incorrect parameter types. | 2545| 6800101 | Parameter verification failed. | 2546 2547**Example** 2548 2549```ts 2550// Cancel all subscriptions to the event. 2551audioVolumeManager.off('volumeChange'); 2552 2553// 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. 2554let volumeChangeCallback = (volumeEvent: audio.VolumeEvent) => { 2555 console.info(`VolumeType of stream: ${volumeEvent.volumeType} `); 2556 console.info(`Volume level: ${volumeEvent.volume} `); 2557 console.info(`Whether to updateUI: ${volumeEvent.updateUi} `); 2558}; 2559 2560audioVolumeManager.on('volumeChange', volumeChangeCallback); 2561 2562audioVolumeManager.off('volumeChange', volumeChangeCallback); 2563``` 2564 2565## AudioVolumeGroupManager<sup>9+</sup> 2566 2567Manages the volume of an audio group. Before calling any API in **AudioVolumeGroupManager**, you must use [getVolumeGroupManager](#getvolumegroupmanager9) to obtain an **AudioVolumeGroupManager** instance. 2568 2569### getVolume<sup>9+</sup> 2570 2571getVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 2572 2573Obtains the volume of a stream. This API uses an asynchronous callback to return the result. 2574 2575**System capability**: SystemCapability.Multimedia.Audio.Volume 2576 2577**Parameters** 2578 2579| Name | Type | Mandatory| Description | 2580| ---------- | ----------------------------------- | ---- | ------------------ | 2581| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 2582| 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).| 2583 2584**Example** 2585 2586```ts 2587import { BusinessError } from '@kit.BasicServicesKit'; 2588 2589audioVolumeGroupManager.getVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { 2590 if (err) { 2591 console.error(`Failed to obtain the volume. ${err}`); 2592 return; 2593 } 2594 console.info('Callback invoked to indicate that the volume is obtained.'); 2595}); 2596``` 2597 2598### getVolume<sup>9+</sup> 2599 2600getVolume(volumeType: AudioVolumeType): Promise<number> 2601 2602Obtains the volume of a stream. This API uses a promise to return the result. 2603 2604**System capability**: SystemCapability.Multimedia.Audio.Volume 2605 2606**Parameters** 2607 2608| Name | Type | Mandatory| Description | 2609| ---------- | ----------------------------------- | ---- | ------------ | 2610| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2611 2612**Return value** 2613 2614| Type | Description | 2615| --------------------- | ------------------------- | 2616| 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).| 2617 2618**Example** 2619 2620```ts 2621audioVolumeGroupManager.getVolume(audio.AudioVolumeType.MEDIA).then((value: number) => { 2622 console.info(`Promise returned to indicate that the volume is obtained ${value}.`); 2623}); 2624``` 2625 2626### getVolumeSync<sup>10+</sup> 2627 2628getVolumeSync(volumeType: AudioVolumeType): number; 2629 2630Obtains the volume of a stream. This API returns the result synchronously. 2631 2632**System capability**: SystemCapability.Multimedia.Audio.Volume 2633 2634**Parameters** 2635 2636| Name | Type | Mandatory| Description | 2637| ---------- | ----------------------------------- | ---- | ------------ | 2638| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2639 2640**Return value** 2641 2642| Type | Description | 2643| --------------------- | ------------------------- | 2644| number | Volume of the stream. The volume range of a specified stream can be obtained by calling [getMinVolume](#getminvolume9) and [getMaxVolume](#getmaxvolume9).| 2645 2646**Error codes** 2647 2648For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2649 2650| ID| Error Message| 2651| ------- | --------------------------------------------| 2652| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2653| 6800101 | Parameter verification failed. | 2654 2655**Example** 2656 2657```ts 2658import { BusinessError } from '@kit.BasicServicesKit'; 2659 2660try { 2661 let value: number = audioVolumeGroupManager.getVolumeSync(audio.AudioVolumeType.MEDIA); 2662 console.info(`Indicate that the volume is obtained ${value}.`); 2663} catch (err) { 2664 let error = err as BusinessError; 2665 console.error(`Failed to obtain the volume, error ${error}.`); 2666} 2667``` 2668 2669### getMinVolume<sup>9+</sup> 2670 2671getMinVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 2672 2673Obtains the minimum volume allowed for a stream. This API uses an asynchronous callback to return the result. 2674 2675**System capability**: SystemCapability.Multimedia.Audio.Volume 2676 2677**Parameters** 2678 2679| Name | Type | Mandatory| Description | 2680| ---------- | ----------------------------------- | ---- | ------------------ | 2681| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 2682| 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.| 2683 2684**Example** 2685 2686```ts 2687import { BusinessError } from '@kit.BasicServicesKit'; 2688 2689audioVolumeGroupManager.getMinVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { 2690 if (err) { 2691 console.error(`Failed to obtain the minimum volume. ${err}`); 2692 return; 2693 } 2694 console.info(`Callback invoked to indicate that the minimum volume is obtained. ${value}`); 2695}); 2696``` 2697 2698### getMinVolume<sup>9+</sup> 2699 2700getMinVolume(volumeType: AudioVolumeType): Promise<number> 2701 2702Obtains the minimum volume allowed for a stream. This API uses a promise to return the result. 2703 2704**System capability**: SystemCapability.Multimedia.Audio.Volume 2705 2706**Parameters** 2707 2708| Name | Type | Mandatory| Description | 2709| ---------- | ----------------------------------- | ---- | ------------ | 2710| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2711 2712**Return value** 2713 2714| Type | Description | 2715| --------------------- | ------------------------- | 2716| Promise<number> | Promise used to return the minimum volume.| 2717 2718**Example** 2719 2720```ts 2721audioVolumeGroupManager.getMinVolume(audio.AudioVolumeType.MEDIA).then((value: number) => { 2722 console.info(`Promised returned to indicate that the minimum volume is obtained ${value}.`); 2723}); 2724``` 2725 2726### getMinVolumeSync<sup>10+</sup> 2727 2728getMinVolumeSync(volumeType: AudioVolumeType): number; 2729 2730Obtains the minimum volume allowed for a stream. This API returns the result synchronously. 2731 2732**System capability**: SystemCapability.Multimedia.Audio.Volume 2733 2734**Parameters** 2735 2736| Name | Type | Mandatory| Description | 2737| ---------- | ----------------------------------- | ---- | ------------ | 2738| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2739 2740**Return value** 2741 2742| Type | Description | 2743| --------------------- | ------------------------- | 2744| number | Minimum volume.| 2745 2746**Error codes** 2747 2748For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2749 2750| ID| Error Message| 2751| ------- | --------------------------------------------| 2752| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2753| 6800101 | Parameter verification failed. | 2754 2755**Example** 2756 2757```ts 2758import { BusinessError } from '@kit.BasicServicesKit'; 2759 2760try { 2761 let value: number = audioVolumeGroupManager.getMinVolumeSync(audio.AudioVolumeType.MEDIA); 2762 console.info(`Indicate that the minimum volume is obtained ${value}.`); 2763} catch (err) { 2764 let error = err as BusinessError; 2765 console.error(`Failed to obtain the minimum volume, error ${error}.`); 2766} 2767``` 2768 2769### getMaxVolume<sup>9+</sup> 2770 2771getMaxVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 2772 2773Obtains the maximum volume allowed for a stream. This API uses an asynchronous callback to return the result. 2774 2775**System capability**: SystemCapability.Multimedia.Audio.Volume 2776 2777**Parameters** 2778 2779| Name | Type | Mandatory| Description | 2780| ---------- | ----------------------------------- | ---- | ---------------------- | 2781| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 2782| 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.| 2783 2784**Example** 2785 2786```ts 2787import { BusinessError } from '@kit.BasicServicesKit'; 2788 2789audioVolumeGroupManager.getMaxVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { 2790 if (err) { 2791 console.error(`Failed to obtain the maximum volume. ${err}`); 2792 return; 2793 } 2794 console.info(`Callback invoked to indicate that the maximum volume is obtained. ${value}`); 2795}); 2796``` 2797 2798### getMaxVolume<sup>9+</sup> 2799 2800getMaxVolume(volumeType: AudioVolumeType): Promise<number> 2801 2802Obtains the maximum volume allowed for a stream. This API uses a promise to return the result. 2803 2804**System capability**: SystemCapability.Multimedia.Audio.Volume 2805 2806**Parameters** 2807 2808| Name | Type | Mandatory| Description | 2809| ---------- | ----------------------------------- | ---- | ------------ | 2810| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2811 2812**Return value** 2813 2814| Type | Description | 2815| --------------------- | ----------------------------- | 2816| Promise<number> | Promise used to return the maximum volume.| 2817 2818**Example** 2819 2820```ts 2821audioVolumeGroupManager.getMaxVolume(audio.AudioVolumeType.MEDIA).then((data: number) => { 2822 console.info('Promised returned to indicate that the maximum volume is obtained.'); 2823}); 2824``` 2825 2826### getMaxVolumeSync<sup>10+</sup> 2827 2828getMaxVolumeSync(volumeType: AudioVolumeType): number; 2829 2830Obtains the maximum volume allowed for a stream. This API returns the result synchronously. 2831 2832**System capability**: SystemCapability.Multimedia.Audio.Volume 2833 2834**Parameters** 2835 2836| Name | Type | Mandatory| Description | 2837| ---------- | ----------------------------------- | ---- | ------------ | 2838| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2839 2840**Return value** 2841 2842| Type | Description | 2843| --------------------- | ----------------------------- | 2844| number | Maximum volume.| 2845 2846**Error codes** 2847 2848For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2849 2850| ID| Error Message| 2851| ------- | --------------------------------------------| 2852| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2853| 6800101 | Parameter verification failed. | 2854 2855**Example** 2856 2857```ts 2858import { BusinessError } from '@kit.BasicServicesKit'; 2859 2860try { 2861 let value: number = audioVolumeGroupManager.getMaxVolumeSync(audio.AudioVolumeType.MEDIA); 2862 console.info(`Indicate that the maximum volume is obtained. ${value}`); 2863} catch (err) { 2864 let error = err as BusinessError; 2865 console.error(`Failed to obtain the maximum volume, error ${error}.`); 2866} 2867``` 2868 2869### isMute<sup>9+</sup> 2870 2871isMute(volumeType: AudioVolumeType, callback: AsyncCallback<boolean>): void 2872 2873Checks whether a stream is muted. This API uses an asynchronous callback to return the result. 2874 2875**System capability**: SystemCapability.Multimedia.Audio.Volume 2876 2877**Parameters** 2878 2879| Name | Type | Mandatory| Description | 2880| ---------- | ----------------------------------- | ---- | ----------------------------------------------- | 2881| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 2882| 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.| 2883 2884**Example** 2885 2886```ts 2887import { BusinessError } from '@kit.BasicServicesKit'; 2888 2889audioVolumeGroupManager.isMute(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: boolean) => { 2890 if (err) { 2891 console.error(`Failed to obtain the mute status. ${err}`); 2892 return; 2893 } 2894 console.info(`Callback invoked to indicate that the mute status of the stream is obtained ${value}.`); 2895}); 2896``` 2897 2898### isMute<sup>9+</sup> 2899 2900isMute(volumeType: AudioVolumeType): Promise<boolean> 2901 2902Checks whether a stream is muted. This API uses a promise to return the result. 2903 2904**System capability**: SystemCapability.Multimedia.Audio.Volume 2905 2906**Parameters** 2907 2908| Name | Type | Mandatory| Description | 2909| ---------- | ----------------------------------- | ---- | ------------ | 2910| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2911 2912**Return value** 2913 2914| Type | Description | 2915| ---------------------- | ------------------------------------------------------ | 2916| 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.| 2917 2918**Example** 2919 2920```ts 2921audioVolumeGroupManager.isMute(audio.AudioVolumeType.MEDIA).then((value: boolean) => { 2922 console.info(`Promise returned to indicate that the mute status of the stream is obtained ${value}.`); 2923}); 2924``` 2925 2926### isMuteSync<sup>10+</sup> 2927 2928isMuteSync(volumeType: AudioVolumeType): boolean 2929 2930Checks whether a stream is muted. This API returns the result synchronously. 2931 2932**System capability**: SystemCapability.Multimedia.Audio.Volume 2933 2934**Parameters** 2935 2936| Name | Type | Mandatory| Description | 2937| ---------- | ----------------------------------- | ---- | ------------ | 2938| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2939 2940**Return value** 2941 2942| Type | Description | 2943| ---------------------- | ------------------------------------------------------ | 2944| boolean | **true**: The stream is muted.<br>**false**: The stream is not muted.| 2945 2946**Error codes** 2947 2948For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2949 2950| ID| Error Message| 2951| ------- | --------------------------------------------| 2952| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2953| 6800101 | Parameter verification failed. | 2954 2955**Example** 2956 2957```ts 2958import { BusinessError } from '@kit.BasicServicesKit'; 2959 2960try { 2961 let value: boolean = audioVolumeGroupManager.isMuteSync(audio.AudioVolumeType.MEDIA); 2962 console.info(`Indicate that the mute status of the stream is obtained ${value}.`); 2963} catch (err) { 2964 let error = err as BusinessError; 2965 console.error(`Failed to obtain the mute status of the stream, error ${error}.`); 2966} 2967``` 2968 2969### getRingerMode<sup>9+</sup> 2970 2971getRingerMode(callback: AsyncCallback<AudioRingMode>): void 2972 2973Obtains the ringer mode. This API uses an asynchronous callback to return the result. 2974 2975**System capability**: SystemCapability.Multimedia.Audio.Volume 2976 2977**Parameters** 2978 2979| Name | Type | Mandatory| Description | 2980| -------- | ---------------------------------------------------- | ---- | ------------------------ | 2981| 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.| 2982 2983**Example** 2984 2985```ts 2986import { BusinessError } from '@kit.BasicServicesKit'; 2987 2988audioVolumeGroupManager.getRingerMode((err: BusinessError, value: audio.AudioRingMode) => { 2989 if (err) { 2990 console.error(`Failed to obtain the ringer mode. ${err}`); 2991 return; 2992 } 2993 console.info(`Callback invoked to indicate that the ringer mode is obtained ${value}.`); 2994}); 2995``` 2996 2997### getRingerMode<sup>9+</sup> 2998 2999getRingerMode(): Promise<AudioRingMode> 3000 3001Obtains the ringer mode. This API uses a promise to return the result. 3002 3003**System capability**: SystemCapability.Multimedia.Audio.Volume 3004 3005**Return value** 3006 3007| Type | Description | 3008| ---------------------------------------------- | ------------------------------- | 3009| Promise<[AudioRingMode](#audioringmode)> | Promise used to return the ringer mode.| 3010 3011**Example** 3012 3013```ts 3014audioVolumeGroupManager.getRingerMode().then((value: audio.AudioRingMode) => { 3015 console.info(`Promise returned to indicate that the ringer mode is obtained ${value}.`); 3016}); 3017``` 3018 3019### getRingerModeSync<sup>10+</sup> 3020 3021getRingerModeSync(): AudioRingMode 3022 3023Obtains the ringer mode. This API returns the result synchronously. 3024 3025**System capability**: SystemCapability.Multimedia.Audio.Volume 3026 3027**Return value** 3028 3029| Type | Description | 3030| ---------------------------------------------- | ------------------------------- | 3031| [AudioRingMode](#audioringmode) | Ringer mode.| 3032 3033**Example** 3034 3035```ts 3036import { BusinessError } from '@kit.BasicServicesKit'; 3037 3038try { 3039 let value: audio.AudioRingMode = audioVolumeGroupManager.getRingerModeSync(); 3040 console.info(`Indicate that the ringer mode is obtained ${value}.`); 3041} catch (err) { 3042 let error = err as BusinessError; 3043 console.error(`Failed to obtain the ringer mode, error ${error}.`); 3044} 3045``` 3046 3047### on('ringerModeChange')<sup>9+</sup> 3048 3049on(type: 'ringerModeChange', callback: Callback\<AudioRingMode>): void 3050 3051Subscribes to the ringer mode change event, which is triggered when [audioringmode](#audioringmode) is changed. This API uses an asynchronous callback to return the result. 3052 3053**System capability**: SystemCapability.Multimedia.Audio.Volume 3054 3055**Parameters** 3056 3057| Name | Type | Mandatory| Description | 3058| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 3059| type | string | Yes | Event type. The value is fixed at **'ringerModeChange'**.| 3060| callback | Callback<[AudioRingMode](#audioringmode)> | Yes | Callback used to return the changed ringer mode.| 3061 3062**Error codes** 3063 3064For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3065 3066| ID| Error Message| 3067| ------- | --------------------------------------------| 3068| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3069| 6800101 | Parameter verification failed. | 3070 3071**Example** 3072 3073```ts 3074audioVolumeGroupManager.on('ringerModeChange', (ringerMode: audio.AudioRingMode) => { 3075 console.info(`Updated ringermode: ${ringerMode}`); 3076}); 3077``` 3078 3079### setMicrophoneMute<sup>(deprecated)</sup> 3080 3081setMicrophoneMute(mute: boolean, callback: AsyncCallback<void>): void 3082 3083Mutes or unmutes the microphone. This API uses an asynchronous callback to return the result. 3084 3085> **NOTE** 3086> 3087> This API is supported since API version 9 and deprecated since API version 11. The substitute API is available only for system applications. 3088 3089**Required permissions**: ohos.permission.MANAGE_AUDIO_CONFIG (available only for system applications) 3090 3091**System capability**: SystemCapability.Multimedia.Audio.Volume 3092 3093**Parameters** 3094 3095| Name | Type | Mandatory| Description | 3096| -------- | ------------------------- | ---- | --------------------------------------------- | 3097| mute | boolean | Yes | Mute status to set. The value **true** means to mute the microphone, and **false** means the opposite.| 3098| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 3099 3100**Example** 3101 3102```ts 3103import { BusinessError } from '@kit.BasicServicesKit'; 3104 3105audioVolumeGroupManager.setMicrophoneMute(true, (err: BusinessError) => { 3106 if (err) { 3107 console.error(`Failed to mute the microphone. ${err}`); 3108 return; 3109 } 3110 console.info('Callback invoked to indicate that the microphone is muted.'); 3111}); 3112``` 3113 3114### setMicrophoneMute<sup>(deprecated)</sup> 3115 3116setMicrophoneMute(mute: boolean): Promise<void> 3117 3118Mutes or unmutes the microphone. This API uses a promise to return the result. 3119 3120> **NOTE** 3121> 3122> This API is supported since API version 9 and deprecated since API version 11. The substitute API is available only for system applications. 3123 3124**Required permissions**: ohos.permission.MANAGE_AUDIO_CONFIG (available only for system applications) 3125 3126**System capability**: SystemCapability.Multimedia.Audio.Volume 3127 3128**Parameters** 3129 3130| Name| Type | Mandatory| Description | 3131| ------ | ------- | ---- | --------------------------------------------- | 3132| mute | boolean | Yes | Mute status to set. The value **true** means to mute the microphone, and **false** means the opposite.| 3133 3134**Return value** 3135 3136| Type | Description | 3137| ------------------- | ------------------------------- | 3138| Promise<void> | Promise that returns no value.| 3139 3140**Example** 3141 3142```ts 3143audioVolumeGroupManager.setMicrophoneMute(true).then(() => { 3144 console.info('Promise returned to indicate that the microphone is muted.'); 3145}); 3146``` 3147 3148### isMicrophoneMute<sup>9+</sup> 3149 3150isMicrophoneMute(callback: AsyncCallback<boolean>): void 3151 3152Checks whether the microphone is muted. This API uses an asynchronous callback to return the result. 3153 3154**System capability**: SystemCapability.Multimedia.Audio.Volume 3155 3156**Parameters** 3157 3158| Name | Type | Mandatory| Description | 3159| -------- | ---------------------------- | ---- | ------------------------------------------------------- | 3160| 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.| 3161 3162**Example** 3163 3164```ts 3165import { BusinessError } from '@kit.BasicServicesKit'; 3166 3167audioVolumeGroupManager.isMicrophoneMute((err: BusinessError, value: boolean) => { 3168 if (err) { 3169 console.error(`Failed to obtain the mute status of the microphone. ${err}`); 3170 return; 3171 } 3172 console.info(`Callback invoked to indicate that the mute status of the microphone is obtained ${value}.`); 3173}); 3174``` 3175 3176### isMicrophoneMute<sup>9+</sup> 3177 3178isMicrophoneMute(): Promise<boolean> 3179 3180Checks whether the microphone is muted. This API uses a promise to return the result. 3181 3182**System capability**: SystemCapability.Multimedia.Audio.Volume 3183 3184**Return value** 3185 3186| Type | Description | 3187| ---------------------- | ------------------------------------------------------------ | 3188| 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.| 3189 3190**Example** 3191 3192```ts 3193audioVolumeGroupManager.isMicrophoneMute().then((value: boolean) => { 3194 console.info(`Promise returned to indicate that the mute status of the microphone is obtained ${value}.`); 3195}); 3196``` 3197 3198### isMicrophoneMuteSync<sup>10+</sup> 3199 3200isMicrophoneMuteSync(): boolean 3201 3202Checks whether the microphone is muted. This API returns the result synchronously. 3203 3204**System capability**: SystemCapability.Multimedia.Audio.Volume 3205 3206**Return value** 3207 3208| Type | Description | 3209| ---------------------- | ------------------------------------------------------------ | 3210| boolean | **true**: The microphone is muted.<br>**false**: The microphone is not muted.| 3211 3212**Example** 3213 3214```ts 3215import { BusinessError } from '@kit.BasicServicesKit'; 3216 3217try { 3218 let value: boolean = audioVolumeGroupManager.isMicrophoneMuteSync(); 3219 console.info(`Indicate that the mute status of the microphone is obtained ${value}.`); 3220} catch (err) { 3221 let error = err as BusinessError; 3222 console.error(`Failed to obtain the mute status of the microphone, error ${error}.`); 3223} 3224``` 3225 3226### on('micStateChange')<sup>9+</sup> 3227 3228on(type: 'micStateChange', callback: Callback<MicStateChangeEvent>): void 3229 3230Subscribes 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. 3231 3232Currently, 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. 3233 3234**System capability**: SystemCapability.Multimedia.Audio.Volume 3235 3236**Parameters** 3237 3238| Name | Type | Mandatory| Description | 3239| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 3240| type | string | Yes | Event type. The value is fixed at **'micStateChange'**.| 3241| callback | Callback<[MicStateChangeEvent](#micstatechangeevent9)> | Yes | Callback used to return the changed microphone state.| 3242 3243**Error codes** 3244 3245For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3246 3247| ID| Error Message| 3248| ------- | --------------------------------------------| 3249| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3250| 6800101 | Parameter verification failed. | 3251 3252**Example** 3253 3254```ts 3255audioVolumeGroupManager.on('micStateChange', (micStateChange: audio.MicStateChangeEvent) => { 3256 console.info(`Current microphone status is: ${micStateChange.mute} `); 3257}); 3258``` 3259 3260### off('micStateChange')<sup>12+</sup> 3261 3262off(type: 'micStateChange', callback?: Callback<MicStateChangeEvent>): void 3263 3264Unsubscribes from system microphone state change event. This API uses an asynchronous callback to return the result. 3265 3266**System capability**: SystemCapability.Multimedia.Audio.Volume 3267 3268**Parameters** 3269 3270| Name | Type | Mandatory| Description | 3271| -------- | -------------------------------------- |----| ------------------------------------------------------------ | 3272| type | string | Yes | Event type. The value is fixed at **'micStateChange'**.| 3273| callback | Callback<[MicStateChangeEvent](#micstatechangeevent9)> | No | Callback used to return the changed microphone state.| 3274 3275**Error codes** 3276 3277For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3278 3279| ID| Error Message| 3280| ------- | --------------------------------------------| 3281| 401 | Parameter error. Possible causes: 1.Mandatory parameters missing; 2.Incorrect parameter types. | 3282| 6800101 | Parameter verification failed. | 3283 3284**Example** 3285 3286```ts 3287// Cancel all subscriptions to the event. 3288audioVolumeGroupManager.off('micStateChange'); 3289 3290// 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. 3291let micStateChangeCallback = (micStateChange: audio.MicStateChangeEvent) => { 3292 console.info(`Current microphone status is: ${micStateChange.mute} `); 3293}; 3294 3295audioVolumeGroupManager.on('micStateChange', micStateChangeCallback); 3296 3297audioVolumeGroupManager.off('micStateChange', micStateChangeCallback); 3298``` 3299 3300### isVolumeUnadjustable<sup>10+</sup> 3301 3302isVolumeUnadjustable(): boolean 3303 3304Checks 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. 3305 3306**System capability**: SystemCapability.Multimedia.Audio.Volume 3307 3308**Return value** 3309 3310| Type | Description | 3311| ---------------------- | ------------------------------------------------------ | 3312| boolean | **true**: The fixed volume mode is enabled.<br>**false**: The fixed volume mode is disabled.| 3313 3314**Example** 3315 3316```ts 3317let volumeAdjustSwitch: boolean = audioVolumeGroupManager.isVolumeUnadjustable(); 3318console.info(`Whether it is volume unadjustable: ${volumeAdjustSwitch}.`); 3319``` 3320 3321### getSystemVolumeInDb<sup>10+</sup> 3322 3323getSystemVolumeInDb(volumeType: AudioVolumeType, volumeLevel: number, device: DeviceType, callback: AsyncCallback<number>): void 3324 3325Obtains the volume gain. This API uses an asynchronous callback to return the result. 3326 3327**System capability**: SystemCapability.Multimedia.Audio.Volume 3328 3329**Parameters** 3330 3331| Name | Type | Mandatory| Description | 3332| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 3333| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 3334| volumeLevel | number | Yes | Volume level. | 3335| device | [DeviceType](#devicetype) | Yes | Device type. | 3336| 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.| 3337 3338**Error codes** 3339 3340For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3341 3342| ID| Error Message| 3343| ------- | --------------------------------------------| 3344| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3345| 6800101 | Parameter verification failed. Return by callback. | 3346| 6800301 | System error. Return by callback. | 3347 3348**Example** 3349 3350```ts 3351import { BusinessError } from '@kit.BasicServicesKit'; 3352 3353audioVolumeGroupManager.getSystemVolumeInDb(audio.AudioVolumeType.MEDIA, 3, audio.DeviceType.SPEAKER, (err: BusinessError, dB: number) => { 3354 if (err) { 3355 console.error(`Failed to get the volume DB. ${err}`); 3356 } else { 3357 console.info(`Success to get the volume DB. ${dB}`); 3358 } 3359}); 3360``` 3361### getSystemVolumeInDb<sup>10+</sup> 3362 3363getSystemVolumeInDb(volumeType: AudioVolumeType, volumeLevel: number, device: DeviceType): Promise<number> 3364 3365Obtains the volume gain. This API uses a promise to return the result. 3366 3367**System capability**: SystemCapability.Multimedia.Audio.Volume 3368 3369**Parameters** 3370 3371| Name | Type | Mandatory| Description | 3372| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 3373| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 3374| volumeLevel | number | Yes | Volume level. | 3375| device | [DeviceType](#devicetype) | Yes | Device type. | 3376 3377**Return value** 3378 3379| Type | Description | 3380| --------------------- | ---------------------------------- | 3381| Promise<number> | Promise used to return the volume gain (in dB).| 3382 3383**Error codes** 3384 3385For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3386 3387| ID| Error Message| 3388| ------- | --------------------------------------------| 3389| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3390| 6800101 | Parameter verification failed. Return by promise. | 3391| 6800301 | System error. Return by promise. | 3392 3393**Example** 3394 3395```ts 3396import { BusinessError } from '@kit.BasicServicesKit'; 3397 3398audioVolumeGroupManager.getSystemVolumeInDb(audio.AudioVolumeType.MEDIA, 3, audio.DeviceType.SPEAKER).then((value: number) => { 3399 console.info(`Success to get the volume DB. ${value}`); 3400}).catch((error: BusinessError) => { 3401 console.error(`Fail to adjust the system volume by step. ${error}`); 3402}); 3403``` 3404 3405### getSystemVolumeInDbSync<sup>10+</sup> 3406 3407getSystemVolumeInDbSync(volumeType: AudioVolumeType, volumeLevel: number, device: DeviceType): number 3408 3409Obtains the volume gain. This API returns the result synchronously. 3410 3411**System capability**: SystemCapability.Multimedia.Audio.Volume 3412 3413**Parameters** 3414 3415| Name | Type | Mandatory| Description | 3416| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 3417| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 3418| volumeLevel | number | Yes | Volume level. | 3419| device | [DeviceType](#devicetype) | Yes | Device type. | 3420 3421**Return value** 3422 3423| Type | Description | 3424| --------------------- | ---------------------------------- | 3425| number | Volume gain (in dB).| 3426 3427**Error codes** 3428 3429For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3430 3431| ID| Error Message| 3432| ------- | --------------------------------------------| 3433| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3434| 6800101 | Parameter verification failed. | 3435 3436**Example** 3437 3438```ts 3439import { BusinessError } from '@kit.BasicServicesKit'; 3440 3441try { 3442 let value: number = audioVolumeGroupManager.getSystemVolumeInDbSync(audio.AudioVolumeType.MEDIA, 3, audio.DeviceType.SPEAKER); 3443 console.info(`Success to get the volume DB. ${value}`); 3444} catch (err) { 3445 let error = err as BusinessError; 3446 console.error(`Fail to adjust the system volume by step. ${error}`); 3447} 3448``` 3449 3450### getMaxAmplitudeForInputDevice<sup>12+</sup> 3451 3452getMaxAmplitudeForInputDevice(inputDevice: AudioDeviceDescriptor): Promise<number> 3453 3454Obtains the maximum amplitude of the audio stream for an input device. This API uses a promise to return the result. 3455 3456**System capability**: SystemCapability.Multimedia.Audio.Volume 3457 3458**Parameters** 3459 3460| Name | Type | Mandatory| Description | 3461| ----------- | ------------------------------------- | ---- | --------------------------------------------------- | 3462| inputDevice | [AudioDeviceDescriptor](#audiodevicedescriptor) | Yes | Descriptor of the target device. | 3463 3464**Return value** 3465 3466| Type | Description | 3467| --------------------- | ---------------------------------- | 3468| Promise<number> | Promise used to return the maximum amplitude, which ranges from 0 to 1.| 3469 3470**Error codes** 3471 3472For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3473 3474| ID| Error Message| 3475| ------- | --------------------------------------------| 3476| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3477| 6800101 | Parameter verification failed. Return by promise. | 3478| 6800301 | System error. Return by promise. | 3479 3480**Example** 3481 3482```ts 3483import { BusinessError } from '@kit.BasicServicesKit'; 3484 3485let capturerInfo: audio.AudioCapturerInfo = { 3486 source: audio.SourceType.SOURCE_TYPE_MIC, 3487 capturerFlags: 0 3488}; 3489 3490audio.getAudioManager().getRoutingManager().getPreferredInputDeviceForCapturerInfo(capturerInfo).then((data) => { 3491 audioVolumeGroupManager.getMaxAmplitudeForInputDevice(data[0]).then((value) => { 3492 console.info(`mic volatileume amplitude is: ${value}`); 3493 }).catch((err: BusinessError) => { 3494 console.error("getMaxAmplitudeForInputDevice error" + JSON.stringify(err)); 3495 }) 3496}).catch((err: BusinessError) => { 3497 console.error("get outputDeviceId error" + JSON.stringify(err)); 3498}) 3499``` 3500 3501### getMaxAmplitudeForOutputDevice<sup>12+</sup> 3502 3503getMaxAmplitudeForOutputDevice(outputDevice: AudioDeviceDescriptor): Promise<number> 3504 3505Obtains the maximum amplitude of the audio stream for an output device. This API uses a promise to return the result. 3506 3507**System capability**: SystemCapability.Multimedia.Audio.Volume 3508 3509**Parameters** 3510 3511| Name | Type | Mandatory| Description | 3512| ------------ | --------------------------------------- | ---- | -------------------------------------------------------- | 3513| outputDevice | [AudioDeviceDescriptor](#audiodevicedescriptor) | Yes | Descriptor of the target device. | 3514 3515**Return value** 3516 3517| Type | Description | 3518| --------------------- | ---------------------------------- | 3519| Promise<number> | Promise used to return the maximum amplitude, which ranges from 0 to 1.| 3520 3521**Error codes** 3522 3523For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3524 3525| ID| Error Message| 3526| ------- | --------------------------------------------| 3527| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3528| 6800101 | Parameter verification failed. Return by promise. | 3529| 6800301 | System error. Return by promise. | 3530 3531**Example** 3532 3533```ts 3534import { BusinessError } from '@kit.BasicServicesKit'; 3535 3536let rendererInfo: audio.AudioRendererInfo = { 3537 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 3538 rendererFlags : 0 3539}; 3540 3541audio.getAudioManager().getRoutingManager().getPreferOutputDeviceForRendererInfo(rendererInfo).then((data) => { 3542 audioVolumeGroupManager.getMaxAmplitudeForOutputDevice(data[0]).then((value) => { 3543 console.info(`mic volatileume amplitude is: ${value}`); 3544 }).catch((err: BusinessError) => { 3545 console.error("getMaxAmplitudeForOutputDevice error" + JSON.stringify(err)); 3546 }) 3547}).catch((err: BusinessError) => { 3548 console.error("getPreferOutputDeviceForRendererInfo error" + JSON.stringify(err)); 3549}) 3550``` 3551 3552## AudioStreamManager<sup>9+</sup> 3553 3554Implements audio stream management. Before calling any API in **AudioStreamManager**, you must use [getStreamManager](#getstreammanager9) to obtain an **AudioStreamManager** instance. 3555 3556### getCurrentAudioRendererInfoArray<sup>9+</sup> 3557 3558getCurrentAudioRendererInfoArray(callback: AsyncCallback<AudioRendererChangeInfoArray>): void 3559 3560Obtains the information about the current audio renderer. This API uses an asynchronous callback to return the result. 3561 3562**System capability**: SystemCapability.Multimedia.Audio.Renderer 3563 3564**Parameters** 3565 3566| Name | Type | Mandatory | Description | 3567| -------- | ----------------------------------- | -------- | --------------------------- | 3568| 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.| 3569 3570**Example** 3571 3572```ts 3573import { BusinessError } from '@kit.BasicServicesKit'; 3574 3575audioStreamManager.getCurrentAudioRendererInfoArray(async (err: BusinessError, AudioRendererChangeInfoArray: audio.AudioRendererChangeInfoArray) => { 3576 console.info('getCurrentAudioRendererInfoArray **** Get Callback Called ****'); 3577 if (err) { 3578 console.error(`getCurrentAudioRendererInfoArray :ERROR: ${err}`); 3579 } else { 3580 if (AudioRendererChangeInfoArray != null) { 3581 for (let i = 0; i < AudioRendererChangeInfoArray.length; i++) { 3582 let AudioRendererChangeInfo: audio.AudioRendererChangeInfo = AudioRendererChangeInfoArray[i]; 3583 console.info(`StreamId for ${i} is: ${AudioRendererChangeInfo.streamId}`); 3584 console.info(`Content ${i} is: ${AudioRendererChangeInfo.rendererInfo.content}`); 3585 console.info(`Stream ${i} is: ${AudioRendererChangeInfo.rendererInfo.usage}`); 3586 console.info(`Flag ${i} is: ${AudioRendererChangeInfo.rendererInfo.rendererFlags}`); 3587 for (let j = 0;j < AudioRendererChangeInfo.deviceDescriptors.length; j++) { 3588 console.info(`Id: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].id}`); 3589 console.info(`Type: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceType}`); 3590 console.info(`Role: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceRole}`); 3591 console.info(`Name: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].name}`); 3592 console.info(`Address: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].address}`); 3593 console.info(`SampleRate: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].sampleRates[0]}`); 3594 console.info(`ChannelCount: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelCounts[0]}`); 3595 console.info(`ChannelMask: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelMasks[0]}`); 3596 } 3597 } 3598 } 3599 } 3600}); 3601``` 3602 3603### getCurrentAudioRendererInfoArray<sup>9+</sup> 3604 3605getCurrentAudioRendererInfoArray(): Promise<AudioRendererChangeInfoArray> 3606 3607Obtains the information about the current audio renderer. This API uses a promise to return the result. 3608 3609**System capability**: SystemCapability.Multimedia.Audio.Renderer 3610 3611**Return value** 3612 3613| Type | Description | 3614| ---------------------------------------------------------------------------------| --------------------------------------- | 3615| Promise<[AudioRendererChangeInfoArray](#audiorendererchangeinfoarray9)> | Promise used to return the renderer information. | 3616 3617**Example** 3618 3619```ts 3620import { BusinessError } from '@kit.BasicServicesKit'; 3621 3622async function getCurrentAudioRendererInfoArray(){ 3623 await audioStreamManager.getCurrentAudioRendererInfoArray().then((AudioRendererChangeInfoArray: audio.AudioRendererChangeInfoArray) => { 3624 console.info(`getCurrentAudioRendererInfoArray ######### Get Promise is called ##########`); 3625 if (AudioRendererChangeInfoArray != null) { 3626 for (let i = 0; i < AudioRendererChangeInfoArray.length; i++) { 3627 let AudioRendererChangeInfo: audio.AudioRendererChangeInfo = AudioRendererChangeInfoArray[i]; 3628 console.info(`StreamId for ${i} is: ${AudioRendererChangeInfo.streamId}`); 3629 console.info(`Content ${i} is: ${AudioRendererChangeInfo.rendererInfo.content}`); 3630 console.info(`Stream ${i} is: ${AudioRendererChangeInfo.rendererInfo.usage}`); 3631 console.info(`Flag ${i} is: ${AudioRendererChangeInfo.rendererInfo.rendererFlags}`); 3632 for (let j = 0;j < AudioRendererChangeInfo.deviceDescriptors.length; j++) { 3633 console.info(`Id: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].id}`); 3634 console.info(`Type: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceType}`); 3635 console.info(`Role: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceRole}`); 3636 console.info(`Name: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].name}`); 3637 console.info(`Address: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].address}`); 3638 console.info(`SampleRate: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].sampleRates[0]}`); 3639 console.info(`ChannelCount: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelCounts[0]}`); 3640 console.info(`ChannelMask: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelMasks[0]}`); 3641 } 3642 } 3643 } 3644 }).catch((err: BusinessError) => { 3645 console.error(`getCurrentAudioRendererInfoArray :ERROR: ${err}`); 3646 }); 3647} 3648``` 3649### getCurrentAudioRendererInfoArraySync<sup>10+</sup> 3650 3651getCurrentAudioRendererInfoArraySync(): AudioRendererChangeInfoArray 3652 3653Obtains the information about the current audio renderer. This API returns the result synchronously. 3654 3655**System capability**: SystemCapability.Multimedia.Audio.Renderer 3656 3657**Return value** 3658 3659| Type | Description | 3660| ---------------------------------------------------------------------------------| --------------------------------------- | 3661| [AudioRendererChangeInfoArray](#audiorendererchangeinfoarray9) | Audio renderer information. | 3662 3663**Example** 3664 3665```ts 3666import { BusinessError } from '@kit.BasicServicesKit'; 3667 3668try { 3669 let audioRendererChangeInfoArray: audio.AudioRendererChangeInfoArray = audioStreamManager.getCurrentAudioRendererInfoArraySync(); 3670 console.info(`getCurrentAudioRendererInfoArraySync success.`); 3671 if (audioRendererChangeInfoArray != null) { 3672 for (let i = 0; i < audioRendererChangeInfoArray.length; i++) { 3673 let AudioRendererChangeInfo: audio.AudioRendererChangeInfo = audioRendererChangeInfoArray[i]; 3674 console.info(`StreamId for ${i} is: ${AudioRendererChangeInfo.streamId}`); 3675 console.info(`Content ${i} is: ${AudioRendererChangeInfo.rendererInfo.content}`); 3676 console.info(`Stream ${i} is: ${AudioRendererChangeInfo.rendererInfo.usage}`); 3677 console.info(`Flag ${i} is: ${AudioRendererChangeInfo.rendererInfo.rendererFlags}`); 3678 for (let j = 0;j < AudioRendererChangeInfo.deviceDescriptors.length; j++) { 3679 console.info(`Id: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].id}`); 3680 console.info(`Type: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceType}`); 3681 console.info(`Role: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceRole}`); 3682 console.info(`Name: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].name}`); 3683 console.info(`Address: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].address}`); 3684 console.info(`SampleRate: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].sampleRates[0]}`); 3685 console.info(`ChannelCount: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelCounts[0]}`); 3686 console.info(`ChannelMask: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelMasks[0]}`); 3687 } 3688 } 3689 } 3690} catch (err) { 3691 let error = err as BusinessError; 3692 console.error(`getCurrentAudioRendererInfoArraySync :ERROR: ${error}`); 3693} 3694``` 3695 3696### getCurrentAudioCapturerInfoArray<sup>9+</sup> 3697 3698getCurrentAudioCapturerInfoArray(callback: AsyncCallback<AudioCapturerChangeInfoArray>): void 3699 3700Obtains the information about the current audio capturer. This API uses an asynchronous callback to return the result. 3701 3702**System capability**: SystemCapability.Multimedia.Audio.Renderer 3703 3704**Parameters** 3705 3706| Name | Type | Mandatory | Description | 3707| ---------- | ----------------------------------- | --------- | -------------------------------------------------------- | 3708| 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.| 3709 3710**Example** 3711 3712```ts 3713import { BusinessError } from '@kit.BasicServicesKit'; 3714 3715audioStreamManager.getCurrentAudioCapturerInfoArray(async (err: BusinessError, AudioCapturerChangeInfoArray: audio.AudioCapturerChangeInfoArray) => { 3716 console.info('getCurrentAudioCapturerInfoArray **** Get Callback Called ****'); 3717 if (err) { 3718 console.error(`getCurrentAudioCapturerInfoArray :ERROR: ${err}`); 3719 } else { 3720 if (AudioCapturerChangeInfoArray != null) { 3721 for (let i = 0; i < AudioCapturerChangeInfoArray.length; i++) { 3722 console.info(`StreamId for ${i} is: ${AudioCapturerChangeInfoArray[i].streamId}`); 3723 console.info(`Source for ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.source}`); 3724 console.info(`Flag ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.capturerFlags}`); 3725 for (let j = 0; j < AudioCapturerChangeInfoArray[i].deviceDescriptors.length; j++) { 3726 console.info(`Id: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].id}`); 3727 console.info(`Type: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceType}`); 3728 console.info(`Role: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceRole}`); 3729 console.info(`Name: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].name}`); 3730 console.info(`Address: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].address}`); 3731 console.info(`SampleRate: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].sampleRates[0]}`); 3732 console.info(`ChannelCount: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelCounts[0]}`); 3733 console.info(`ChannelMask: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelMasks[0]}`); 3734 } 3735 } 3736 } 3737 } 3738}); 3739``` 3740 3741### getCurrentAudioCapturerInfoArray<sup>9+</sup> 3742 3743getCurrentAudioCapturerInfoArray(): Promise<AudioCapturerChangeInfoArray> 3744 3745Obtains the information about the current audio capturer. This API uses a promise to return the result. 3746 3747**System capability**: SystemCapability.Multimedia.Audio.Renderer 3748 3749**Return value** 3750 3751| Type | Description | 3752| -----------------------------------------------------------------------------| ----------------------------------- | 3753| Promise<[AudioCapturerChangeInfoArray](#audiocapturerchangeinfoarray9)> | Promise used to return the audio capturer information. | 3754 3755**Example** 3756 3757```ts 3758import { BusinessError } from '@kit.BasicServicesKit'; 3759 3760async function getCurrentAudioCapturerInfoArray(){ 3761 await audioStreamManager.getCurrentAudioCapturerInfoArray().then((AudioCapturerChangeInfoArray: audio.AudioCapturerChangeInfoArray) => { 3762 console.info('getCurrentAudioCapturerInfoArray **** Get Promise Called ****'); 3763 if (AudioCapturerChangeInfoArray != null) { 3764 for (let i = 0; i < AudioCapturerChangeInfoArray.length; i++) { 3765 console.info(`StreamId for ${i} is: ${AudioCapturerChangeInfoArray[i].streamId}`); 3766 console.info(`Source for ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.source}`); 3767 console.info(`Flag ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.capturerFlags}`); 3768 for (let j = 0; j < AudioCapturerChangeInfoArray[i].deviceDescriptors.length; j++) { 3769 console.info(`Id: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].id}`); 3770 console.info(`Type: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceType}`); 3771 console.info(`Role: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceRole}`); 3772 console.info(`Name: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].name}`); 3773 console.info(`Address: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].address}`); 3774 console.info(`SampleRate: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].sampleRates[0]}`); 3775 console.info(`ChannelCount: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelCounts[0]}`); 3776 console.info(`ChannelMask: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelMasks[0]}`); 3777 } 3778 } 3779 } 3780 }).catch((err: BusinessError) => { 3781 console.error(`getCurrentAudioCapturerInfoArray :ERROR: ${err}`); 3782 }); 3783} 3784``` 3785### getCurrentAudioCapturerInfoArraySync<sup>10+</sup> 3786 3787getCurrentAudioCapturerInfoArraySync(): AudioCapturerChangeInfoArray 3788 3789Obtains the information about the current audio capturer. This API returns the result synchronously. 3790 3791**System capability**: SystemCapability.Multimedia.Audio.Capturer 3792 3793**Return value** 3794 3795| Type | Description | 3796| -----------------------------------------------------------------------------| ----------------------------------- | 3797| [AudioCapturerChangeInfoArray](#audiocapturerchangeinfoarray9) | Audio capturer information. | 3798 3799**Example** 3800 3801```ts 3802import { BusinessError } from '@kit.BasicServicesKit'; 3803 3804try { 3805 let audioCapturerChangeInfoArray: audio.AudioCapturerChangeInfoArray = audioStreamManager.getCurrentAudioCapturerInfoArraySync(); 3806 console.info('getCurrentAudioCapturerInfoArraySync success.'); 3807 if (audioCapturerChangeInfoArray != null) { 3808 for (let i = 0; i < audioCapturerChangeInfoArray.length; i++) { 3809 console.info(`StreamId for ${i} is: ${audioCapturerChangeInfoArray[i].streamId}`); 3810 console.info(`Source for ${i} is: ${audioCapturerChangeInfoArray[i].capturerInfo.source}`); 3811 console.info(`Flag ${i} is: ${audioCapturerChangeInfoArray[i].capturerInfo.capturerFlags}`); 3812 for (let j = 0; j < audioCapturerChangeInfoArray[i].deviceDescriptors.length; j++) { 3813 console.info(`Id: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].id}`); 3814 console.info(`Type: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceType}`); 3815 console.info(`Role: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceRole}`); 3816 console.info(`Name: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].name}`); 3817 console.info(`Address: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].address}`); 3818 console.info(`SampleRate: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].sampleRates[0]}`); 3819 console.info(`ChannelCount: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].channelCounts[0]}`); 3820 console.info(`ChannelMask: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].channelMasks[0]}`); 3821 } 3822 } 3823 } 3824} catch (err) { 3825 let error = err as BusinessError; 3826 console.error(`getCurrentAudioCapturerInfoArraySync ERROR: ${error}`); 3827} 3828``` 3829 3830### on('audioRendererChange')<sup>9+</sup> 3831 3832on(type: 'audioRendererChange', callback: Callback<AudioRendererChangeInfoArray>): void 3833 3834Subscribes 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. 3835 3836**System capability**: SystemCapability.Multimedia.Audio.Renderer 3837 3838**Parameters** 3839 3840| Name | Type | Mandatory | Description | 3841| -------- | ---------- | --------- | ------------------------------------------------------------------------ | 3842| type | string | Yes | Event type. The value is fixed at **'audioRendererChange'**. | 3843| callback | Callback<[AudioRendererChangeInfoArray](#audiorendererchangeinfoarray9)> | Yes | Callback used to return the audio renderer information.| 3844 3845**Error codes** 3846 3847For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3848 3849| ID| Error Message| 3850| ------- | --------------------------------------------| 3851| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3852| 6800101 | Parameter verification failed. | 3853 3854**Example** 3855 3856```ts 3857audioStreamManager.on('audioRendererChange', (audioRendererChangeInfoArray: audio.AudioRendererChangeInfoArray) => { 3858 for (let i = 0; i < audioRendererChangeInfoArray.length; i++) { 3859 let audioRendererChangeInfo: audio.AudioRendererChangeInfo = audioRendererChangeInfoArray[i]; 3860 console.info(`## RendererChange on is called for ${i} ##`); 3861 console.info(`StreamId for ${i} is: ${audioRendererChangeInfo.streamId}`); 3862 console.info(`Content ${i} is: ${audioRendererChangeInfo.rendererInfo.content}`); 3863 console.info(`Stream ${i} is: ${audioRendererChangeInfo.rendererInfo.usage}`); 3864 console.info(`Flag ${i} is: ${audioRendererChangeInfo.rendererInfo.rendererFlags}`); 3865 for (let j = 0;j < audioRendererChangeInfo.deviceDescriptors.length; j++) { 3866 console.info(`Id: ${i} : ${audioRendererChangeInfo.deviceDescriptors[j].id}`); 3867 console.info(`Type: ${i} : ${audioRendererChangeInfo.deviceDescriptors[j].deviceType}`); 3868 console.info(`Role: ${i} : ${audioRendererChangeInfo.deviceDescriptors[j].deviceRole}`); 3869 console.info(`Name: ${i} : ${audioRendererChangeInfo.deviceDescriptors[j].name}`); 3870 console.info(`Address: ${i} : ${audioRendererChangeInfo.deviceDescriptors[j].address}`); 3871 console.info(`SampleRate: ${i} : ${audioRendererChangeInfo.deviceDescriptors[j].sampleRates[0]}`); 3872 console.info(`ChannelCount: ${i} : ${audioRendererChangeInfo.deviceDescriptors[j].channelCounts[0]}`); 3873 console.info(`ChannelMask: ${i} : ${audioRendererChangeInfo.deviceDescriptors[j].channelMasks[0]}`); 3874 } 3875 } 3876}); 3877``` 3878 3879### off('audioRendererChange')<sup>9+</sup> 3880 3881off(type: 'audioRendererChange'): void 3882 3883Unsubscribes from the audio renderer change event. 3884 3885**System capability**: SystemCapability.Multimedia.Audio.Renderer 3886 3887**Parameters** 3888 3889| Name | Type | Mandatory| Description | 3890| -------- | ------- | ---- | ---------------- | 3891| type | string | Yes | Event type. The value is fixed at **'audioRendererChange'**.| 3892 3893**Error codes** 3894 3895For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3896 3897| ID| Error Message | 3898| ------- |--------------------------| 3899| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3900| 6800101 | Parameter verification failed. | 3901 3902**Example** 3903 3904```ts 3905audioStreamManager.off('audioRendererChange'); 3906``` 3907 3908### on('audioCapturerChange')<sup>9+</sup> 3909 3910on(type: 'audioCapturerChange', callback: Callback<AudioCapturerChangeInfoArray>): void 3911 3912Subscribes 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. 3913 3914**System capability**: SystemCapability.Multimedia.Audio.Capturer 3915 3916**Parameters** 3917 3918| Name | Type | Mandatory | Description | 3919| -------- | ------- | --------- | ---------------------------------------------------------------------- | 3920| type | string | Yes | Event type. The value is fixed at **'audioCapturerChange'**. | 3921| callback | Callback<[AudioCapturerChangeInfoArray](#audiocapturerchangeinfoarray9)> | Yes | Callback used to return the audio capturer information.| 3922 3923**Error codes** 3924 3925For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3926 3927| ID| Error Message| 3928| ------- | --------------------------------------------| 3929| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3930| 6800101 | Parameter verification failed. | 3931 3932**Example** 3933 3934```ts 3935audioStreamManager.on('audioCapturerChange', (AudioCapturerChangeInfoArray: audio.AudioCapturerChangeInfoArray) => { 3936 for (let i = 0; i < AudioCapturerChangeInfoArray.length; i++) { 3937 console.info(`## CapChange on is called for element ${i} ##`); 3938 console.info(`StreamId for ${i} is: ${AudioCapturerChangeInfoArray[i].streamId}`); 3939 console.info(`Source for ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.source}`); 3940 console.info(`Flag ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.capturerFlags}`); 3941 for (let j = 0; j < AudioCapturerChangeInfoArray[i].deviceDescriptors.length; j++) { 3942 console.info(`Id: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].id}`); 3943 console.info(`Type: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceType}`); 3944 console.info(`Role: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceRole}`); 3945 console.info(`Name: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].name}`); 3946 console.info(`Address: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].address}`); 3947 console.info(`SampleRate: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].sampleRates[0]}`); 3948 console.info(`ChannelCount: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelCounts[0]}`); 3949 console.info(`ChannelMask: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelMasks[0]}`); 3950 } 3951 } 3952}); 3953``` 3954 3955### off('audioCapturerChange')<sup>9+</sup> 3956 3957off(type: 'audioCapturerChange'): void 3958 3959Unsubscribes from the audio capturer change event. 3960 3961**System capability**: SystemCapability.Multimedia.Audio.Capturer 3962 3963**Parameters** 3964 3965| Name | Type | Mandatory| Description | 3966| -------- | -------- | --- | ------------------------------------------------------------- | 3967| type | string |Yes | Event type. The value is fixed at **'audioCapturerChange'**.| 3968 3969**Error codes** 3970 3971For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3972 3973| ID| Error Message| 3974| ------- | --------------------------------------------| 3975| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3976| 6800101 | Parameter verification failed. | 3977 3978**Example** 3979 3980```ts 3981audioStreamManager.off('audioCapturerChange'); 3982``` 3983 3984### isActive<sup>9+</sup> 3985 3986isActive(volumeType: AudioVolumeType, callback: AsyncCallback<boolean>): void 3987 3988Checks whether a stream is active. This API uses an asynchronous callback to return the result. 3989 3990**System capability**: SystemCapability.Multimedia.Audio.Renderer 3991 3992**Parameters** 3993 3994| Name | Type | Mandatory| Description | 3995| ---------- | ----------------------------------- | ---- | ------------------------------------------------- | 3996| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream types. | 3997| 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.| 3998 3999**Example** 4000 4001```ts 4002import { BusinessError } from '@kit.BasicServicesKit'; 4003 4004audioStreamManager.isActive(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: boolean) => { 4005if (err) { 4006 console.error(`Failed to obtain the active status of the stream. ${err}`); 4007 return; 4008} 4009 console.info(`Callback invoked to indicate that the active status of the stream is obtained ${value}.`); 4010}); 4011``` 4012 4013### isActive<sup>9+</sup> 4014 4015isActive(volumeType: AudioVolumeType): Promise<boolean> 4016 4017Checks whether a stream is active. This API uses a promise to return the result. 4018 4019**System capability**: SystemCapability.Multimedia.Audio.Renderer 4020 4021**Parameters** 4022 4023| Name | Type | Mandatory| Description | 4024| ---------- | ----------------------------------- | ---- | ------------ | 4025| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream types.| 4026 4027**Return value** 4028 4029| Type | Description | 4030| ---------------------- | -------------------------------------------------------- | 4031| 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.| 4032 4033**Example** 4034 4035```ts 4036audioStreamManager.isActive(audio.AudioVolumeType.MEDIA).then((value: boolean) => { 4037 console.info(`Promise returned to indicate that the active status of the stream is obtained ${value}.`); 4038}); 4039``` 4040 4041### isActiveSync<sup>10+</sup> 4042 4043isActiveSync(volumeType: AudioVolumeType): boolean 4044 4045Checks whether a stream is active. This API returns the result synchronously. 4046 4047**System capability**: SystemCapability.Multimedia.Audio.Renderer 4048 4049**Parameters** 4050 4051| Name | Type | Mandatory| Description | 4052| ---------- | ----------------------------------- | ---- | ------------ | 4053| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream types.| 4054 4055**Return value** 4056 4057| Type | Description | 4058| ---------------------- | -------------------------------------------------------- | 4059| boolean | **true**: The stream is active.<br> **false**: The stream is inactive.| 4060 4061**Error codes** 4062 4063For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4064 4065| ID| Error Message| 4066| ------- | --------------------------------------------| 4067| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4068| 6800101 | Parameter verification failed. | 4069 4070**Example** 4071 4072```ts 4073import { BusinessError } from '@kit.BasicServicesKit'; 4074 4075try { 4076 let value: boolean = audioStreamManager.isActiveSync(audio.AudioVolumeType.MEDIA); 4077 console.info(`Indicate that the active status of the stream is obtained ${value}.`); 4078} catch (err) { 4079 let error = err as BusinessError; 4080 console.error(`Failed to obtain the active status of the stream ${error}.`); 4081} 4082``` 4083 4084### getAudioEffectInfoArray<sup>10+</sup> 4085 4086getAudioEffectInfoArray(usage: StreamUsage, callback: AsyncCallback<AudioEffectInfoArray>): void 4087 4088Obtains information about the audio effect mode in use. This API uses an asynchronous callback to return the result. 4089 4090**System capability**: SystemCapability.Multimedia.Audio.Renderer 4091 4092**Parameters** 4093 4094| Name | Type | Mandatory | Description | 4095| -------- | ----------------------------------- | -------- | --------------------------- | 4096| usage | [StreamUsage](#streamusage) | Yes | Audio stream usage. | 4097| 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.| 4098 4099**Error codes** 4100 4101For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4102 4103| ID| Error Message| 4104| ------- | --------------------------------------------| 4105| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4106| 6800101 | Parameter verification failed. Return by callback.| 4107 4108**Example** 4109 4110```ts 4111import { BusinessError } from '@kit.BasicServicesKit'; 4112 4113audioStreamManager.getAudioEffectInfoArray(audio.StreamUsage.STREAM_USAGE_MUSIC, async (err: BusinessError, audioEffectInfoArray: audio.AudioEffectInfoArray) => { 4114 console.info('getAudioEffectInfoArray **** Get Callback Called ****'); 4115 if (err) { 4116 console.error(`getAudioEffectInfoArray :ERROR: ${err}`); 4117 return; 4118 } else { 4119 console.info(`The effect modes are: ${audioEffectInfoArray}`); 4120 } 4121}); 4122``` 4123 4124### getAudioEffectInfoArray<sup>10+</sup> 4125 4126getAudioEffectInfoArray(usage: StreamUsage): Promise<AudioEffectInfoArray> 4127 4128Obtains information about the audio effect mode in use. This API uses a promise to return the result. 4129 4130**System capability**: SystemCapability.Multimedia.Audio.Renderer 4131 4132**Parameters** 4133 4134| Name | Type | Mandatory | Description | 4135| -------- | ----------------------------------- | -------- | --------------------------- | 4136| usage | [StreamUsage](#streamusage) | Yes | Audio stream usage. | 4137 4138**Return value** 4139 4140| Type | Description | 4141| --------------------------------------------------------------------------| --------------------------------------- | 4142| Promise<[AudioEffectInfoArray](#audioeffectinfoarray10)> | Promise used to return the information about the audio effect mode obtained. | 4143 4144**Error codes** 4145 4146For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4147 4148| ID| Error Message| 4149| ------- | --------------------------------------------| 4150| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4151| 6800101 | Parameter verification failed. Return by promise. | 4152 4153**Example** 4154 4155```ts 4156import { BusinessError } from '@kit.BasicServicesKit'; 4157 4158audioStreamManager.getAudioEffectInfoArray(audio.StreamUsage.STREAM_USAGE_MUSIC).then((audioEffectInfoArray: audio.AudioEffectInfoArray) => { 4159 console.info('getAudioEffectInfoArray ######### Get Promise is called ##########'); 4160 console.info(`The effect modes are: ${audioEffectInfoArray}`); 4161}).catch((err: BusinessError) => { 4162 console.error(`getAudioEffectInfoArray :ERROR: ${err}`); 4163}); 4164``` 4165 4166### getAudioEffectInfoArraySync<sup>10+</sup> 4167 4168getAudioEffectInfoArraySync(usage: StreamUsage): AudioEffectInfoArray 4169 4170Obtains information about the audio effect mode in use. This API returns the result synchronously. 4171 4172**System capability**: SystemCapability.Multimedia.Audio.Renderer 4173 4174**Parameters** 4175 4176| Name | Type | Mandatory | Description | 4177| -------- | ----------------------------------- | -------- | --------------------------- | 4178| usage | [StreamUsage](#streamusage) | Yes | Audio stream usage. | 4179 4180**Return value** 4181 4182| Type | Description | 4183| --------------------------------------------------------------------------| --------------------------------------- | 4184| [AudioEffectInfoArray](#audioeffectinfoarray10) | Information about the audio effect mode. | 4185 4186**Error codes** 4187 4188For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4189 4190| ID| Error Message| 4191| ------- | --------------------------------------------| 4192| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4193| 6800101 | Parameter verification failed. | 4194 4195**Example** 4196 4197```ts 4198import { BusinessError } from '@kit.BasicServicesKit'; 4199 4200try { 4201 let audioEffectInfoArray: audio.AudioEffectInfoArray = audioStreamManager.getAudioEffectInfoArraySync(audio.StreamUsage.STREAM_USAGE_MUSIC); 4202 console.info(`The effect modes are: ${audioEffectInfoArray}`); 4203} catch (err) { 4204 let error = err as BusinessError; 4205 console.error(`getAudioEffectInfoArraySync ERROR: ${error}`); 4206} 4207``` 4208 4209## AudioRoutingManager<sup>9+</sup> 4210 4211Implements audio routing management. Before calling any API in **AudioRoutingManager**, you must use [getRoutingManager](#getroutingmanager9) to obtain an **AudioRoutingManager** instance. 4212 4213### getDevices<sup>9+</sup> 4214 4215getDevices(deviceFlag: DeviceFlag, callback: AsyncCallback<AudioDeviceDescriptors>): void 4216 4217Obtains the audio devices with a specific flag. This API uses an asynchronous callback to return the result. 4218 4219**System capability**: SystemCapability.Multimedia.Audio.Device 4220 4221**Parameters** 4222 4223| Name | Type | Mandatory| Description | 4224| ---------- | ------------------------------------------------------------ | ---- | -------------------- | 4225| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag. | 4226| 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.| 4227 4228**Example** 4229 4230```ts 4231import { BusinessError } from '@kit.BasicServicesKit'; 4232 4233audioRoutingManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG, (err: BusinessError, value: audio.AudioDeviceDescriptors) => { 4234 if (err) { 4235 console.error(`Failed to obtain the device list. ${err}`); 4236 return; 4237 } 4238 console.info('Callback invoked to indicate that the device list is obtained.'); 4239}); 4240``` 4241 4242### getDevices<sup>9+</sup> 4243 4244getDevices(deviceFlag: DeviceFlag): Promise<AudioDeviceDescriptors> 4245 4246Obtains the audio devices with a specific flag. This API uses a promise to return the result. 4247 4248**System capability**: SystemCapability.Multimedia.Audio.Device 4249 4250**Parameters** 4251 4252| Name | Type | Mandatory| Description | 4253| ---------- | ------------------------- | ---- | ---------------- | 4254| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag.| 4255 4256**Return value** 4257 4258| Type | Description | 4259| ------------------------------------------------------------ | ------------------------- | 4260| Promise<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Promise used to return the device list.| 4261 4262**Example** 4263 4264```ts 4265audioRoutingManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG).then((data: audio.AudioDeviceDescriptors) => { 4266 console.info('Promise returned to indicate that the device list is obtained.'); 4267}); 4268``` 4269 4270### getDevicesSync<sup>10+</sup> 4271 4272getDevicesSync(deviceFlag: DeviceFlag): AudioDeviceDescriptors 4273 4274Obtains the audio devices with a specific flag. This API returns the result synchronously. 4275 4276**System capability**: SystemCapability.Multimedia.Audio.Device 4277 4278**Parameters** 4279 4280| Name | Type | Mandatory| Description | 4281| ---------- | ------------------------- | ---- | ---------------- | 4282| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag.| 4283 4284**Return value** 4285 4286| Type | Description | 4287| ------------------------------------------------------------ | ------------------------- | 4288| [AudioDeviceDescriptors](#audiodevicedescriptors) | Device list.| 4289 4290**Error codes** 4291 4292For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4293 4294| ID| Error Message| 4295| ------- | --------------------------------------------| 4296| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4297| 6800101 | Parameter verification failed. | 4298 4299**Example** 4300 4301```ts 4302import { BusinessError } from '@kit.BasicServicesKit'; 4303 4304try { 4305 let data: audio.AudioDeviceDescriptors = audioRoutingManager.getDevicesSync(audio.DeviceFlag.OUTPUT_DEVICES_FLAG); 4306 console.info(`Indicate that the device list is obtained ${data}`); 4307} catch (err) { 4308 let error = err as BusinessError; 4309 console.error(`Failed to obtain the device list. ${error}`); 4310} 4311``` 4312 4313### isMicBlockDetectionSupported<sup>13+</sup> 4314 4315isMicBlockDetectionSupported(): Promise<boolean> 4316 4317Checks whether the current device supports microphone blocking detection. This API uses a promise to return the result. 4318 4319**System capability**: SystemCapability.Multimedia.Audio.Device 4320 4321**Return value** 4322 4323| Type | Description | 4324| ---------------------- | ------------------------------------------------------------ | 4325| 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.| 4326 4327**Example** 4328 4329```ts 4330audioRoutingManager.isMicBlockDetectionSupported().then((value: boolean) => { 4331 console.info(`Query whether microphone block detection is supported on current device result is ${value}.`); 4332}); 4333``` 4334 4335### on('micBlockStatusChanged')<sup>13+</sup> 4336 4337on(type: 'micBlockStatusChanged', callback: Callback<DeviceBlockStatusInfo\>): void 4338 4339Subscribes to the microphone blocked status change event. This API uses an asynchronous callback to return the result. 4340 4341Before 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. 4342 4343Currently, this API takes effect only for the microphone on the local device. 4344 4345**System capability**: SystemCapability.Multimedia.Audio.Device 4346 4347**Parameters** 4348 4349| Name | Type | Mandatory| Description | 4350| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- | 4351| type | string | Yes | Event type. The value is fixed at **'micBlockStatusChanged'**.| 4352| callback | Callback<[DeviceBlockStatusInfo](#deviceblockstatusinfo13)\> | Yes | Callback used to return details about whether the microphone is blocked.| 4353 4354**Error codes** 4355 4356For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4357 4358| ID| Error Message| 4359| ------- | --------------------------------------------| 4360| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4361| 6800101 | Parameter verification failed. | 4362 4363**Example** 4364 4365```ts 4366// Before the subscription, check whether the current device supports detection. 4367audioRoutingManager.isMicBlockDetectionSupported().then((value: boolean) => { 4368 console.info(`Query whether microphone block detection is supported on current device result is ${value}.`); 4369 if (value) { 4370 audioRoutingManager.on('micBlockStatusChanged', (micBlockStatusChanged: audio.DeviceBlockStatusInfo) => { 4371 console.info(`block status : ${micBlockStatusChanged.blockStatus} `); 4372 }); 4373 } 4374}); 4375``` 4376 4377### off('micBlockStatusChanged')<sup>13+</sup> 4378 4379off(type: 'micBlockStatusChanged', callback?: Callback<DeviceBlockStatusInfo\>): void 4380 4381Unsubscribes from the microphone blocked status change event. This API uses an asynchronous callback to return the result. 4382 4383**System capability**: SystemCapability.Multimedia.Audio.Device 4384 4385**Parameters** 4386 4387| Name | Type | Mandatory| Description | 4388| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 4389| type | string | Yes | Event type. The value is fixed at **'micBlockStatusChanged'**.| 4390| callback | Callback<[DeviceBlockStatusInfo](#deviceblockstatusinfo13)\> | No | Callback used to return details about whether the microphone is blocked.| 4391 4392**Error codes** 4393 4394For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4395 4396| ID| Error Message| 4397| ------- | --------------------------------------------| 4398| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4399| 6800101 | Parameter verification failed. | 4400 4401**Example** 4402 4403```ts 4404// Cancel all subscriptions to the event. 4405audioRoutingManager.off('micBlockStatusChanged'); 4406 4407// 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. 4408let micBlockStatusCallback = (micBlockStatusChanged: audio.DeviceBlockStatusInfo) => { 4409 console.info(`block status : ${micBlockStatusChanged.blockStatus} `); 4410}; 4411 4412audioRoutingManager.on('micBlockStatusChanged', micBlockStatusCallback); 4413 4414audioRoutingManager.off('micBlockStatusChanged', micBlockStatusCallback); 4415``` 4416 4417### on('deviceChange')<sup>9+</sup> 4418 4419on(type: 'deviceChange', deviceFlag: DeviceFlag, callback: Callback<DeviceChangeAction\>): void 4420 4421Subscribes 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. 4422 4423**System capability**: SystemCapability.Multimedia.Audio.Device 4424 4425**Parameters** 4426 4427| Name | Type | Mandatory| Description | 4428| :------- | :--------------------------------------------------- | :--- |:------------------------| 4429| type | string | Yes | Event type. The value is fixed at **'deviceChange'**.| 4430| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag. | 4431| callback | Callback<[DeviceChangeAction](#devicechangeaction)\> | Yes | Callback used to return the device change details. | 4432 4433**Error codes** 4434 4435For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4436 4437| ID| Error Message| 4438| ------- | --------------------------------------------| 4439| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4440| 6800101 | Parameter verification failed. | 4441 4442**Example** 4443 4444```ts 4445audioRoutingManager.on('deviceChange', audio.DeviceFlag.OUTPUT_DEVICES_FLAG, (deviceChanged: audio.DeviceChangeAction) => { 4446 console.info('device change type : ' + deviceChanged.type); 4447 console.info('device descriptor size : ' + deviceChanged.deviceDescriptors.length); 4448 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceRole); 4449 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceType); 4450}); 4451``` 4452 4453### off('deviceChange')<sup>9+</sup> 4454 4455off(type: 'deviceChange', callback?: Callback<DeviceChangeAction\>): void 4456 4457Unsubscribes from the audio device change event. This API uses an asynchronous callback to return the result. 4458 4459**System capability**: SystemCapability.Multimedia.Audio.Device 4460 4461**Parameters** 4462 4463| Name | Type | Mandatory| Description | 4464| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 4465| type | string | Yes | Event type. The value is fixed at **'deviceChange'**.| 4466| callback | Callback<[DeviceChangeAction](#devicechangeaction)> | No | Callback used to return the device change details.| 4467 4468**Error codes** 4469 4470For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4471 4472| ID| Error Message| 4473| ------- | --------------------------------------------| 4474| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4475| 6800101 | Parameter verification failed. | 4476 4477**Example** 4478 4479```ts 4480// Cancel all subscriptions to the event. 4481audioRoutingManager.off('deviceChange'); 4482 4483// 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. 4484let deviceChangeCallback = (deviceChanged: audio.DeviceChangeAction) => { 4485 console.info('device change type : ' + deviceChanged.type); 4486 console.info('device descriptor size : ' + deviceChanged.deviceDescriptors.length); 4487 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceRole); 4488 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceType); 4489}; 4490 4491audioRoutingManager.on('deviceChange', audio.DeviceFlag.OUTPUT_DEVICES_FLAG, deviceChangeCallback); 4492 4493audioRoutingManager.off('deviceChange', deviceChangeCallback); 4494``` 4495 4496### setCommunicationDevice<sup>9+</sup> 4497 4498setCommunicationDevice(deviceType: CommunicationDeviceType, active: boolean, callback: AsyncCallback<void>): void 4499 4500Sets a communication device to the active state. This API uses an asynchronous callback to return the result. 4501 4502This API will be deprecated in a later version due to function design is changed. You are not advised to use it. 4503 4504You are advised to use the [AVCastPicker component](../../media/avsession/using-switch-call-devices.md) provided by AVSession to switch between call devices. 4505 4506**System capability**: SystemCapability.Multimedia.Audio.Communication 4507 4508**Parameters** 4509 4510| Name | Type | Mandatory| Description | 4511| ---------- | ------------------------------------- | ---- |-------------------------| 4512| deviceType | [CommunicationDeviceType](#communicationdevicetype9) | Yes | Communication device type. | 4513| 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.| 4514| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 4515 4516**Example** 4517 4518```ts 4519import { BusinessError } from '@kit.BasicServicesKit'; 4520 4521audioRoutingManager.setCommunicationDevice(audio.CommunicationDeviceType.SPEAKER, true, (err: BusinessError) => { 4522 if (err) { 4523 console.error(`Failed to set the active status of the device. ${err}`); 4524 return; 4525 } 4526 console.info('Callback invoked to indicate that the device is set to the active status.'); 4527}); 4528``` 4529 4530### getAvailableDevices<sup>12+</sup> 4531 4532getAvailableDevices(deviceUsage: DeviceUsage): AudioDeviceDescriptors 4533 4534Obtains the available audio devices. This API returns the result synchronously. 4535 4536**System capability**: SystemCapability.Multimedia.Audio.Device 4537 4538**Parameters** 4539 4540| Name | Type | Mandatory| Description | 4541| ---------- | ------------------------- | ---- | ---------------- | 4542| deviceUsage| [DeviceUsage](#deviceusage12) | Yes | Usage scenario of the device.| 4543 4544**Return value** 4545 4546| Type | Description | 4547| ------------------------------------------------------------ | ------------------------- | 4548| [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | Device list.| 4549 4550**Error codes** 4551 4552For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4553 4554| ID| Error Message| 4555| ------- | --------------------------------------------| 4556| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4557| 6800101 | Parameter verification failed. | 4558 4559**Example** 4560 4561```ts 4562import { BusinessError } from '@kit.BasicServicesKit'; 4563 4564try { 4565 let data: audio.AudioDeviceDescriptors = audioRoutingManager.getAvailableDevices(audio.DeviceUsage.MEDIA_OUTPUT_DEVICES); 4566 console.info(`Indicate that the device list is obtained ${data}`); 4567} catch (err) { 4568 let error = err as BusinessError; 4569 console.error(`Failed to obtain the device list. ${error}`); 4570} 4571``` 4572 4573### on('availableDeviceChange')<sup>12+</sup> 4574 4575on(type: 'availableDeviceChange', deviceUsage: DeviceUsage, callback: Callback<DeviceChangeAction\>): void 4576 4577Subscribes 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. 4578 4579**System capability**: SystemCapability.Multimedia.Audio.Device 4580 4581**Parameters** 4582 4583| Name | Type | Mandatory| Description | 4584| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- | 4585| type | string | Yes | Event type. The value is fixed at **'availableDeviceChange'**.| 4586| deviceUsage | [DeviceUsage](#deviceusage12) | Yes | Usage scenario of the device. | 4587| callback | Callback<[DeviceChangeAction](js-apis-audio.md#devicechangeaction)\> | Yes | Callback used to return the device change details.| 4588 4589**Error codes** 4590 4591For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4592 4593| ID| Error Message| 4594| ------- | --------------------------------------------| 4595| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4596| 6800101 | Parameter verification failed. | 4597 4598**Example** 4599 4600```ts 4601audioRoutingManager.on('availableDeviceChange', audio.DeviceUsage.MEDIA_OUTPUT_DEVICES, (deviceChanged: audio.DeviceChangeAction) => { 4602 console.info('device change type : ' + deviceChanged.type); 4603 console.info('device descriptor size : ' + deviceChanged.deviceDescriptors.length); 4604 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceRole); 4605 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceType); 4606}); 4607``` 4608 4609### off('availableDeviceChange')<sup>12+</sup> 4610 4611off(type: 'availableDeviceChange', callback?: Callback<DeviceChangeAction\>): void 4612 4613Unsubscribes from the available audio device change event. This API uses an asynchronous callback to return the result. 4614 4615**System capability**: SystemCapability.Multimedia.Audio.Device 4616 4617**Parameters** 4618 4619| Name | Type | Mandatory| Description | 4620| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 4621| type | string | Yes | Event type. The value is fixed at **'availableDeviceChange'**.| 4622| callback | Callback<[DeviceChangeAction](js-apis-audio.md#devicechangeaction)> | No | Callback used to return the available device change details.| 4623 4624**Error codes** 4625 4626For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4627 4628| ID| Error Message| 4629| ------- | --------------------------------------------| 4630| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4631| 6800101 | Parameter verification failed. | 4632 4633**Example** 4634 4635```ts 4636// Cancel all subscriptions to the event. 4637audioRoutingManager.off('availableDeviceChange'); 4638 4639// 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. 4640let availableDeviceChangeCallback = (deviceChanged: audio.DeviceChangeAction) => { 4641 console.info('device change type : ' + deviceChanged.type); 4642 console.info('device descriptor size : ' + deviceChanged.deviceDescriptors.length); 4643 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceRole); 4644 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceType); 4645}; 4646 4647audioRoutingManager.on('availableDeviceChange', audio.DeviceUsage.MEDIA_OUTPUT_DEVICES, availableDeviceChangeCallback); 4648 4649audioRoutingManager.off('availableDeviceChange', availableDeviceChangeCallback); 4650``` 4651 4652### setCommunicationDevice<sup>9+</sup> 4653 4654setCommunicationDevice(deviceType: CommunicationDeviceType, active: boolean): Promise<void> 4655 4656Sets a communication device to the active state. This API uses a promise to return the result. 4657 4658This API will be deprecated in a later version due to function design is changed. You are not advised to use it. 4659 4660You are advised to use the [AVCastPicker component](../../media/avsession/using-switch-call-devices.md) provided by AVSession to switch between call devices. 4661 4662**System capability**: SystemCapability.Multimedia.Audio.Communication 4663 4664**Parameters** 4665 4666| Name | Type | Mandatory| Description | 4667| ---------- | ----------------------------------------------------- | ---- | ------------------ | 4668| deviceType | [CommunicationDeviceType](#communicationdevicetype9) | Yes | Communication device type.| 4669| 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. | 4670 4671**Return value** 4672 4673| Type | Description | 4674| ------------------- | ------------------------------- | 4675| Promise<void> | Promise that returns no value.| 4676 4677**Example** 4678 4679```ts 4680audioRoutingManager.setCommunicationDevice(audio.CommunicationDeviceType.SPEAKER, true).then(() => { 4681 console.info('Promise returned to indicate that the device is set to the active status.'); 4682}); 4683``` 4684 4685### isCommunicationDeviceActive<sup>9+</sup> 4686 4687isCommunicationDeviceActive(deviceType: CommunicationDeviceType, callback: AsyncCallback<boolean>): void 4688 4689Checks whether a communication device is active. This API uses an asynchronous callback to return the result. 4690 4691**System capability**: SystemCapability.Multimedia.Audio.Communication 4692 4693**Parameters** 4694 4695| Name | Type | Mandatory| Description | 4696| ---------- | ---------------------------------------------------- | ---- | ------------------------ | 4697| deviceType | [CommunicationDeviceType](#communicationdevicetype9) | Yes | Communication device type. | 4698| 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.| 4699 4700**Example** 4701 4702```ts 4703import { BusinessError } from '@kit.BasicServicesKit'; 4704 4705audioRoutingManager.isCommunicationDeviceActive(audio.CommunicationDeviceType.SPEAKER, (err: BusinessError, value: boolean) => { 4706 if (err) { 4707 console.error(`Failed to obtain the active status of the device. ${err}`); 4708 return; 4709 } 4710 console.info('Callback invoked to indicate that the active status of the device is obtained.'); 4711}); 4712``` 4713 4714### isCommunicationDeviceActive<sup>9+</sup> 4715 4716isCommunicationDeviceActive(deviceType: CommunicationDeviceType): Promise<boolean> 4717 4718Checks whether a communication device is active. This API uses a promise to return the result. 4719 4720**System capability**: SystemCapability.Multimedia.Audio.Communication 4721 4722**Parameters** 4723 4724| Name | Type | Mandatory| Description | 4725| ---------- | ---------------------------------------------------- | ---- | ------------------ | 4726| deviceType | [CommunicationDeviceType](#communicationdevicetype9) | Yes | Communication device type.| 4727 4728**Return value** 4729 4730| Type | Description | 4731| ---------------------- | ------------------------------- | 4732| 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.| 4733 4734**Example** 4735 4736```ts 4737audioRoutingManager.isCommunicationDeviceActive(audio.CommunicationDeviceType.SPEAKER).then((value: boolean) => { 4738 console.info(`Promise returned to indicate that the active status of the device is obtained ${value}.`); 4739}); 4740``` 4741 4742### isCommunicationDeviceActiveSync<sup>10+</sup> 4743 4744isCommunicationDeviceActiveSync(deviceType: CommunicationDeviceType): boolean 4745 4746Checks whether a communication device is active. This API returns the result synchronously. 4747 4748**System capability**: SystemCapability.Multimedia.Audio.Communication 4749 4750**Parameters** 4751 4752| Name | Type | Mandatory| Description | 4753| ---------- | ---------------------------------------------------- | ---- | ------------------ | 4754| deviceType | [CommunicationDeviceType](#communicationdevicetype9) | Yes | Communication device type.| 4755 4756**Return value** 4757 4758| Type | Description | 4759| ---------------------- | ------------------------------- | 4760| boolean | **true**: The device is active.<br>**false**: The device is inactive.| 4761 4762**Error codes** 4763 4764For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4765 4766| ID| Error Message| 4767| ------- | --------------------------------------------| 4768| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4769| 6800101 | Parameter verification failed. | 4770 4771**Example** 4772 4773```ts 4774import { BusinessError } from '@kit.BasicServicesKit'; 4775 4776try { 4777 let value: boolean = audioRoutingManager.isCommunicationDeviceActiveSync(audio.CommunicationDeviceType.SPEAKER); 4778 console.info(`Indicate that the active status of the device is obtained ${value}.`); 4779} catch (err) { 4780 let error = err as BusinessError; 4781 console.error(`Failed to obtain the active status of the device ${error}.`); 4782} 4783``` 4784 4785### getPreferOutputDeviceForRendererInfo<sup>10+</sup> 4786 4787getPreferOutputDeviceForRendererInfo(rendererInfo: AudioRendererInfo, callback: AsyncCallback<AudioDeviceDescriptors>): void 4788 4789Obtains the output device with the highest priority based on the audio renderer information. This API uses an asynchronous callback to return the result. 4790 4791**System capability**: SystemCapability.Multimedia.Audio.Device 4792 4793**Parameters** 4794 4795| Name | Type | Mandatory| Description | 4796| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 4797| rendererInfo | [AudioRendererInfo](#audiorendererinfo8) | Yes | Audio renderer information. | 4798| 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.| 4799 4800**Error codes** 4801 4802For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4803 4804| ID| Error Message | 4805| ------- |--------------------------------------------------| 4806| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4807| 6800101 | Parameter verification failed. Return by callback. | 4808| 6800301 | System error. Return by callback. | 4809 4810**Example** 4811```ts 4812import { audio } from '@kit.AudioKit'; 4813import { BusinessError } from '@kit.BasicServicesKit'; 4814 4815let rendererInfo: audio.AudioRendererInfo = { 4816 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 4817 rendererFlags : 0 4818}; 4819 4820async function getPreferOutputDevice() { 4821 audioRoutingManager.getPreferOutputDeviceForRendererInfo(rendererInfo, (err: BusinessError, desc: audio.AudioDeviceDescriptors) => { 4822 if (err) { 4823 console.error(`Result ERROR: ${err}`); 4824 } else { 4825 console.info(`device descriptor: ${desc}`); 4826 } 4827 }); 4828} 4829``` 4830 4831### getPreferOutputDeviceForRendererInfo<sup>10+</sup> 4832getPreferOutputDeviceForRendererInfo(rendererInfo: AudioRendererInfo): Promise<AudioDeviceDescriptors> 4833 4834Obtains the output device with the highest priority based on the audio renderer information. This API uses a promise to return the result. 4835 4836**System capability**: SystemCapability.Multimedia.Audio.Device 4837 4838**Parameters** 4839 4840| Name | Type | Mandatory| Description | 4841| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 4842| rendererInfo | [AudioRendererInfo](#audiorendererinfo8) | Yes | Audio renderer information. | 4843 4844**Return value** 4845 4846| Type | Description | 4847| --------------------- | --------------------------- | 4848| Promise<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Promise used to return the information about the output device with the highest priority.| 4849 4850**Error codes** 4851 4852For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4853 4854| ID| Error Message | 4855| ------- |-------------------------------------------------| 4856| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4857| 6800101 | Parameter verification failed. Return by promise. | 4858| 6800301 | System error. Return by promise. | 4859 4860**Example** 4861 4862```ts 4863import { audio } from '@kit.AudioKit'; 4864import { BusinessError } from '@kit.BasicServicesKit'; 4865 4866let rendererInfo: audio.AudioRendererInfo = { 4867 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 4868 rendererFlags : 0 4869}; 4870 4871async function getPreferOutputDevice() { 4872 audioRoutingManager.getPreferOutputDeviceForRendererInfo(rendererInfo).then((desc: audio.AudioDeviceDescriptors) => { 4873 console.info(`device descriptor: ${desc}`); 4874 }).catch((err: BusinessError) => { 4875 console.error(`Result ERROR: ${err}`); 4876 }) 4877} 4878``` 4879 4880### getPreferredOutputDeviceForRendererInfoSync<sup>10+</sup> 4881getPreferredOutputDeviceForRendererInfoSync(rendererInfo: AudioRendererInfo): AudioDeviceDescriptors 4882 4883Obtains the output device with the highest priority based on the audio renderer information. This API returns the result synchronously. 4884 4885**System capability**: SystemCapability.Multimedia.Audio.Device 4886 4887**Parameters** 4888 4889| Name | Type | Mandatory| Description | 4890| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 4891| rendererInfo | [AudioRendererInfo](#audiorendererinfo8) | Yes | Audio renderer information. | 4892 4893**Return value** 4894 4895| Type | Description | 4896| --------------------- | --------------------------- | 4897| [AudioDeviceDescriptors](#audiodevicedescriptors) | Information about the output device with the highest priority.| 4898 4899**Error codes** 4900 4901For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4902 4903| ID| Error Message | 4904| ------- |--------------------------| 4905| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4906| 6800101 | Parameter verification failed. | 4907 4908**Example** 4909 4910```ts 4911import { audio } from '@kit.AudioKit'; 4912import { BusinessError } from '@kit.BasicServicesKit'; 4913 4914let rendererInfo: audio.AudioRendererInfo = { 4915 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 4916 rendererFlags : 0 4917}; 4918 4919try { 4920 let desc: audio.AudioDeviceDescriptors = audioRoutingManager.getPreferredOutputDeviceForRendererInfoSync(rendererInfo); 4921 console.info(`device descriptor: ${desc}`); 4922} catch (err) { 4923 let error = err as BusinessError; 4924 console.error(`Result ERROR: ${error}`); 4925} 4926``` 4927 4928### on('preferOutputDeviceChangeForRendererInfo')<sup>10+</sup> 4929 4930on(type: 'preferOutputDeviceChangeForRendererInfo', rendererInfo: AudioRendererInfo, callback: Callback<AudioDeviceDescriptors\>): void 4931 4932Subscribes 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. 4933 4934**System capability**: SystemCapability.Multimedia.Audio.Device 4935 4936**Parameters** 4937 4938| Name | Type | Mandatory| Description | 4939| :------- | :--------------------------------------------------- | :--- |:--------------------------------------------------------| 4940| type | string | Yes | Event type. The value is fixed at **'preferOutputDeviceChangeForRendererInfo'**.| 4941| rendererInfo | [AudioRendererInfo](#audiorendererinfo8) | Yes | Audio renderer information. | 4942| callback | Callback<[AudioDeviceDescriptors](#audiodevicedescriptors)\> | Yes | Callback used to return the information about the output device with the highest priority.| 4943 4944**Error codes** 4945 4946For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4947 4948| ID| Error Message| 4949| ------- | --------------------------------------------| 4950| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4951| 6800101 | Parameter verification failed. | 4952 4953**Example** 4954 4955```ts 4956import { audio } from '@kit.AudioKit'; 4957 4958let rendererInfo: audio.AudioRendererInfo = { 4959 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 4960 rendererFlags : 0 4961}; 4962 4963audioRoutingManager.on('preferOutputDeviceChangeForRendererInfo', rendererInfo, (desc: audio.AudioDeviceDescriptors) => { 4964 console.info(`device descriptor: ${desc}`); 4965}); 4966``` 4967 4968### off('preferOutputDeviceChangeForRendererInfo')<sup>10+</sup> 4969 4970off(type: 'preferOutputDeviceChangeForRendererInfo', callback?: Callback<AudioDeviceDescriptors\>): void 4971 4972Unsubscribes from the change of the output device with the highest priority. This API uses an asynchronous callback to return the result. 4973 4974**System capability**: SystemCapability.Multimedia.Audio.Device 4975 4976**Parameters** 4977 4978| Name | Type | Mandatory| Description | 4979| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 4980| type | string | Yes | Event type. The value is fixed at **'preferOutputDeviceChangeForRendererInfo'**.| 4981| callback | Callback<[AudioDeviceDescriptors](#audiodevicedescriptors)> | No | Callback used to return the information about the output device with the highest priority.| 4982 4983**Error codes** 4984 4985For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4986 4987| ID| Error Message| 4988| ------- | --------------------------------------------| 4989| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4990| 6800101 | Parameter verification failed. | 4991 4992**Example** 4993 4994```ts 4995// Cancel all subscriptions to the event. 4996audioRoutingManager.off('preferOutputDeviceChangeForRendererInfo'); 4997 4998// 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. 4999let preferOutputDeviceChangeForRendererInfoCallback = (desc: audio.AudioDeviceDescriptors) => { 5000 console.info(`device descriptor: ${desc}`); 5001}; 5002let rendererInfo: audio.AudioRendererInfo = { 5003 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 5004 rendererFlags : 0 5005}; 5006 5007audioRoutingManager.on('preferOutputDeviceChangeForRendererInfo', rendererInfo, preferOutputDeviceChangeForRendererInfoCallback); 5008 5009audioRoutingManager.off('preferOutputDeviceChangeForRendererInfo', preferOutputDeviceChangeForRendererInfoCallback); 5010``` 5011 5012### getPreferredInputDeviceForCapturerInfo<sup>10+</sup> 5013 5014getPreferredInputDeviceForCapturerInfo(capturerInfo: AudioCapturerInfo, callback: AsyncCallback<AudioDeviceDescriptors>): void 5015 5016Obtains the input device with the highest priority based on the audio capturer information. This API uses an asynchronous callback to return the result. 5017 5018**System capability**: SystemCapability.Multimedia.Audio.Device 5019 5020**Parameters** 5021 5022| Name | Type | Mandatory| Description | 5023| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 5024| capturerInfo | [AudioCapturerInfo](#audiocapturerinfo8) | Yes | Audio capturer information. | 5025| 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.| 5026 5027**Error codes** 5028 5029For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5030 5031| ID| Error Message| 5032| ------- | --------------------------------------------| 5033| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5034| 6800101 | Parameter verification failed. Return by callback.| 5035| 6800301 | System error. Return by callback. | 5036 5037**Example** 5038```ts 5039import { audio } from '@kit.AudioKit'; 5040import { BusinessError } from '@kit.BasicServicesKit'; 5041 5042let capturerInfo: audio.AudioCapturerInfo = { 5043 source: audio.SourceType.SOURCE_TYPE_MIC, 5044 capturerFlags: 0 5045}; 5046 5047audioRoutingManager.getPreferredInputDeviceForCapturerInfo(capturerInfo, (err: BusinessError, desc: audio.AudioDeviceDescriptors) => { 5048 if (err) { 5049 console.error(`Result ERROR: ${err}`); 5050 } else { 5051 console.info(`device descriptor: ${desc}`); 5052 } 5053}); 5054``` 5055 5056### getPreferredInputDeviceForCapturerInfo<sup>10+</sup> 5057 5058getPreferredInputDeviceForCapturerInfo(capturerInfo: AudioCapturerInfo): Promise<AudioDeviceDescriptors> 5059 5060Obtains the input device with the highest priority based on the audio capturer information. This API uses a promise to return the result. 5061 5062**System capability**: SystemCapability.Multimedia.Audio.Device 5063 5064**Parameters** 5065 5066| Name | Type | Mandatory| Description | 5067| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 5068| capturerInfo | [AudioCapturerInfo](#audiocapturerinfo8) | Yes | Audio capturer information. | 5069 5070**Return value** 5071 5072| Type | Description | 5073| --------------------- | --------------------------- | 5074| Promise<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Promise used to return the information about the input device with the highest priority.| 5075 5076**Error codes** 5077 5078For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5079 5080| ID| Error Message| 5081| ------- | --------------------------------------------| 5082| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5083| 6800101 | Parameter verification failed. Return by promise. | 5084| 6800301 | System error. Return by promise. | 5085 5086**Example** 5087 5088```ts 5089import { audio } from '@kit.AudioKit'; 5090import { BusinessError } from '@kit.BasicServicesKit'; 5091 5092let capturerInfo: audio.AudioCapturerInfo = { 5093 source: audio.SourceType.SOURCE_TYPE_MIC, 5094 capturerFlags: 0 5095}; 5096 5097audioRoutingManager.getPreferredInputDeviceForCapturerInfo(capturerInfo).then((desc: audio.AudioDeviceDescriptors) => { 5098 console.info(`device descriptor: ${desc}`); 5099}).catch((err: BusinessError) => { 5100 console.error(`Result ERROR: ${err}`); 5101}); 5102``` 5103 5104### getPreferredInputDeviceForCapturerInfoSync<sup>10+</sup> 5105 5106getPreferredInputDeviceForCapturerInfoSync(capturerInfo: AudioCapturerInfo): AudioDeviceDescriptors 5107 5108Obtains the input device with the highest priority based on the audio capturer information. This API returns the result synchronously. 5109 5110**System capability**: SystemCapability.Multimedia.Audio.Device 5111 5112**Parameters** 5113 5114| Name | Type | Mandatory| Description | 5115| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 5116| capturerInfo | [AudioCapturerInfo](#audiocapturerinfo8) | Yes | Audio capturer information. | 5117 5118**Return value** 5119 5120| Type | Description | 5121| --------------------- | --------------------------- | 5122| [AudioDeviceDescriptors](#audiodevicedescriptors) | Information about the input device with the highest priority.| 5123 5124**Error codes** 5125 5126For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5127 5128| ID| Error Message| 5129| ------- | --------------------------------------------| 5130| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5131| 6800101 | Parameter verification failed. | 5132 5133**Example** 5134 5135```ts 5136import { audio } from '@kit.AudioKit'; 5137import { BusinessError } from '@kit.BasicServicesKit'; 5138 5139let capturerInfo: audio.AudioCapturerInfo = { 5140 source: audio.SourceType.SOURCE_TYPE_MIC, 5141 capturerFlags: 0 5142}; 5143 5144try { 5145 let desc: audio.AudioDeviceDescriptors = audioRoutingManager.getPreferredInputDeviceForCapturerInfoSync(capturerInfo); 5146 console.info(`device descriptor: ${desc}`); 5147} catch (err) { 5148 let error = err as BusinessError; 5149 console.error(`Result ERROR: ${error}`); 5150} 5151``` 5152 5153### on('preferredInputDeviceChangeForCapturerInfo')<sup>10+</sup> 5154 5155on(type: 'preferredInputDeviceChangeForCapturerInfo', capturerInfo: AudioCapturerInfo, callback: Callback<AudioDeviceDescriptors\>): void 5156 5157Subscribes 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. 5158 5159**System capability**: SystemCapability.Multimedia.Audio.Device 5160 5161**Parameters** 5162 5163| Name | Type | Mandatory| Description | 5164| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- | 5165| type | string | Yes | Event type. The value is fixed at **'preferredInputDeviceChangeForCapturerInfo'**.| 5166| capturerInfo | [AudioCapturerInfo](#audiocapturerinfo8) | Yes | Audio capturer information. | 5167| callback | Callback<[AudioDeviceDescriptors](#audiodevicedescriptors)\> | Yes | Callback used to return the information about the input device with the highest priority.| 5168 5169**Error codes** 5170 5171For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5172 5173| ID| Error Message| 5174| ------- | --------------------------------------------| 5175| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5176| 6800101 | Parameter verification failed. | 5177 5178**Example** 5179 5180```ts 5181import { audio } from '@kit.AudioKit'; 5182 5183let capturerInfo: audio.AudioCapturerInfo = { 5184 source: audio.SourceType.SOURCE_TYPE_MIC, 5185 capturerFlags: 0 5186}; 5187 5188audioRoutingManager.on('preferredInputDeviceChangeForCapturerInfo', capturerInfo, (desc: audio.AudioDeviceDescriptors) => { 5189 console.info(`device descriptor: ${desc}`); 5190}); 5191``` 5192 5193### off('preferredInputDeviceChangeForCapturerInfo')<sup>10+</sup> 5194 5195off(type: 'preferredInputDeviceChangeForCapturerInfo', callback?: Callback<AudioDeviceDescriptors\>): void 5196 5197Unsubscribes from the change of the input device with the highest priority. This API uses an asynchronous callback to return the result. 5198 5199**System capability**: SystemCapability.Multimedia.Audio.Device 5200 5201**Parameters** 5202 5203| Name | Type | Mandatory| Description | 5204| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 5205| type | string | Yes | Event type. The value is fixed at **'preferredInputDeviceChangeForCapturerInfo'**.| 5206| callback | Callback<[AudioDeviceDescriptors](#audiodevicedescriptors)> | No | Callback used to return the information about the input device with the highest priority.| 5207 5208**Error codes** 5209 5210For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5211 5212| ID| Error Message| 5213| ------- | --------------------------------------------| 5214| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5215| 6800101 | Parameter verification failed. | 5216 5217**Example** 5218 5219```ts 5220// Cancel all subscriptions to the event. 5221audioRoutingManager.off('preferredInputDeviceChangeForCapturerInfo'); 5222 5223// 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. 5224let preferredInputDeviceChangeForCapturerInfoCallback = (desc: audio.AudioDeviceDescriptors) => { 5225 console.info(`device descriptor: ${desc}`); 5226}; 5227let capturerInfo: audio.AudioCapturerInfo = { 5228 source: audio.SourceType.SOURCE_TYPE_MIC, 5229 capturerFlags: 0 5230}; 5231 5232audioRoutingManager.on('preferredInputDeviceChangeForCapturerInfo', capturerInfo, preferredInputDeviceChangeForCapturerInfoCallback); 5233 5234audioRoutingManager.off('preferredInputDeviceChangeForCapturerInfo', preferredInputDeviceChangeForCapturerInfoCallback); 5235``` 5236 5237## AudioSessionManager<sup>12+</sup> 5238 5239Manages audio sessions. Before calling an API in **AudioSessionManager**, you must use [getSessionManager](#getsessionmanager12) to obtain an **AudioSessionManager** instance. 5240 5241### activateAudioSession<sup>12+</sup> 5242 5243activateAudioSession(strategy: AudioSessionStrategy): Promise\<void> 5244 5245Activates an audio session. This API uses a promise to return the result. 5246 5247**System capability**: SystemCapability.Multimedia.Audio.Core 5248 5249**Parameters** 5250 5251| Name| Type | Mandatory| Description | 5252| ------ |-------------------------------------------------| ---- | ------------ | 5253| strategy | [AudioSessionStrategy](#audiosessionstrategy12) | Yes | Audio session strategy.| 5254 5255**Return value** 5256 5257| Type | Description | 5258| -------------- | ------------------------- | 5259| Promise\<void> | Promise that returns no value.| 5260 5261**Error codes** 5262 5263For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5264 5265| ID| Error Message| 5266| ------- | ---------------------------------------------| 5267| 401 | Parameter error. Possible causes: 1.Mandatory parameters unspecified. 2.Incorrect parameter types. | 5268| 6800101 | Parameter verification failed.| 5269| 6800301 | System error. Returned by promise. | 5270 5271**Example** 5272 5273```ts 5274import { BusinessError } from '@kit.BasicServicesKit'; 5275 5276let strategy: audio.AudioSessionStrategy = { 5277 concurrencyMode: audio.AudioConcurrencyMode.CONCURRENCY_MIX_WITH_OTHERS 5278}; 5279 5280audioSessionManager.activateAudioSession(strategy).then(() => { 5281 console.info('activateAudioSession SUCCESS'); 5282}).catch((err: BusinessError) => { 5283 console.error(`ERROR: ${err}`); 5284}); 5285``` 5286 5287### deactivateAudioSession<sup>12+</sup> 5288 5289deactivateAudioSession(): Promise\<void> 5290 5291Deactivates this audio session. This API uses a promise to return the result. 5292 5293**System capability**: SystemCapability.Multimedia.Audio.Core 5294 5295**Return value** 5296 5297| Type | Description | 5298| -------------- | ------------------------- | 5299| Promise\<void> | Promise that returns no value.| 5300 5301**Error codes** 5302 5303For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5304 5305| ID| Error Message| 5306| ------- | ---------------------------------------------| 5307| 6800301 | System error. Returned by promise. | 5308 5309**Example** 5310 5311```ts 5312import { BusinessError } from '@kit.BasicServicesKit'; 5313 5314audioSessionManager.deactivateAudioSession().then(() => { 5315 console.info('deactivateAudioSession SUCCESS'); 5316}).catch((err: BusinessError) => { 5317 console.error(`ERROR: ${err}`); 5318}); 5319``` 5320 5321### isAudioSessionActivated<sup>12+</sup> 5322 5323isAudioSessionActivated(): boolean 5324 5325Checks whether this audio session is activated. 5326 5327**System capability**: SystemCapability.Multimedia.Audio.Core 5328 5329**Return value** 5330 5331| Type | Description | 5332| ------------------------------------------------- |---------------------------------------| 5333| boolean | Returns **true** if the audio session is activated; returns **false** otherwise.| 5334 5335**Example** 5336 5337```ts 5338let isActivated = audioSessionManager.isAudioSessionActivated(); 5339``` 5340 5341### on('audioSessionDeactivated')<sup>12+</sup> 5342 5343on(type: 'audioSessionDeactivated', callback: Callback\<AudioSessionDeactivatedEvent>): void 5344 5345Subscribes 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. 5346 5347**System capability**: SystemCapability.Multimedia.Audio.Core 5348 5349**Parameters** 5350 5351| Name | Type | Mandatory| Description | 5352| -------- |---------------------------------------------------------------------------| ---- | ------------------------------------------------------------ | 5353| type | string | Yes | Event type. The value is fixed at **'audioSessionDeactivated'**.| 5354| callback | Callback<[AudioSessionDeactivatedEvent](#audiosessiondeactivatedevent12)> | Yes | Callback used to return the reason why the audio session is deactivated.| 5355 5356**Error codes** 5357 5358For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5359 5360| ID| Error Message| 5361| ------- | --------------------------------------------| 5362| 401 | Parameter error. Possible causes: 1.Mandatory parameters unspecified. 2.Incorrect parameter types. | 5363| 6800101 | Parameter verification failed. | 5364 5365**Example** 5366 5367```ts 5368audioSessionManager.on('audioSessionDeactivated', (audioSessionDeactivatedEvent: audio.AudioSessionDeactivatedEvent) => { 5369 console.info(`reason of audioSessionDeactivated: ${audioSessionDeactivatedEvent.reason} `); 5370}); 5371``` 5372 5373### off('audioSessionDeactivated')<sup>12+</sup> 5374 5375off(type: 'audioSessionDeactivated', callback?: Callback\<AudioSessionDeactivatedEvent>): void 5376 5377Unsubscribes from the audio session deactivation event. This API uses an asynchronous callback to return the result. 5378 5379**System capability**: SystemCapability.Multimedia.Audio.Core 5380 5381**Parameters** 5382 5383| Name | Type | Mandatory| Description | 5384| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 5385| type | string | Yes | Event type. The value is fixed at **'audioSessionDeactivated'**.| 5386| callback |Callback<[AudioSessionDeactivatedEvent](#audiosessiondeactivatedevent12)> | No | Callback used to return the reason why the audio session is deactivated.| 5387 5388**Error codes** 5389 5390For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5391 5392| ID| Error Message| 5393| ------- | --------------------------------------------| 5394| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5395| 6800101 | Parameter verification failed. | 5396 5397**Example** 5398 5399```ts 5400// Cancel all subscriptions to the event. 5401audioSessionManager.off('audioSessionDeactivated'); 5402 5403// 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. 5404let audioSessionDeactivatedCallback = (audioSessionDeactivatedEvent: audio.AudioSessionDeactivatedEvent) => { 5405 console.info(`reason of audioSessionDeactivated: ${audioSessionDeactivatedEvent.reason} `); 5406}; 5407 5408audioSessionManager.on('audioSessionDeactivated', audioSessionDeactivatedCallback); 5409 5410audioSessionManager.off('audioSessionDeactivated', audioSessionDeactivatedCallback); 5411``` 5412 5413## AudioRendererChangeInfoArray<sup>9+</sup> 5414 5415type AudioRendererChangeInfoArray = Array<Readonly<AudioRendererChangeInfo>> 5416 5417Defines an **AudioRenderChangeInfo** array, which is read-only. 5418 5419**System capability**: SystemCapability.Multimedia.Audio.Renderer 5420 5421| Type | Description | 5422|---------|---------------------------------------------------------------| 5423| Array<Readonly<AudioRendererChangeInfo>> | Defines an [AudioRenderChangeInfo](#audiorendererchangeinfo9) array, which is read-only.| 5424 5425## AudioRendererChangeInfo<sup>9+</sup> 5426 5427Describes the audio renderer change event. 5428 5429**System capability**: SystemCapability.Multimedia.Audio.Renderer 5430 5431| Name | Type | Readable| Writable| Description | 5432| -------------------| ----------------------------------------- | ---- | ---- | ---------------------------- | 5433| streamId | number | Yes | No | Unique ID of an audio stream. | 5434| rendererInfo | [AudioRendererInfo](#audiorendererinfo8) | Yes | No | Audio renderer information. | 5435| deviceDescriptors | [AudioDeviceDescriptors](#audiodevicedescriptors) | Yes | No | Audio device description.| 5436 5437**Example** 5438 5439```ts 5440import { audio } from '@kit.AudioKit'; 5441 5442const audioManager = audio.getAudioManager(); 5443let audioStreamManager = audioManager.getStreamManager(); 5444 5445audioStreamManager.on('audioRendererChange', (AudioRendererChangeInfoArray) => { 5446 for (let i = 0; i < AudioRendererChangeInfoArray.length; i++) { 5447 console.info(`## RendererChange on is called for ${i} ##`); 5448 console.info(`StreamId for ${i} is: ${AudioRendererChangeInfoArray[i].streamId}`); 5449 console.info(`Content for ${i} is: ${AudioRendererChangeInfoArray[i].rendererInfo.content}`); 5450 console.info(`Stream for ${i} is: ${AudioRendererChangeInfoArray[i].rendererInfo.usage}`); 5451 console.info(`Flag ${i} is: ${AudioRendererChangeInfoArray[i].rendererInfo.rendererFlags}`); 5452 let devDescriptor = AudioRendererChangeInfoArray[i].deviceDescriptors; 5453 for (let j = 0; j < AudioRendererChangeInfoArray[i].deviceDescriptors.length; j++) { 5454 console.info(`Id: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].id}`); 5455 console.info(`Type: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].deviceType}`); 5456 console.info(`Role: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].deviceRole}`); 5457 console.info(`Name: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].name}`); 5458 console.info(`Addr: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].address}`); 5459 console.info(`SR: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].sampleRates[0]}`); 5460 console.info(`C ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].channelCounts[0]}`); 5461 console.info(`CM: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].channelMasks[0]}`); 5462 } 5463 } 5464}); 5465``` 5466 5467 5468## AudioCapturerChangeInfoArray<sup>9+</sup> 5469 5470type AudioCapturerChangeInfoArray = Array<Readonly<AudioCapturerChangeInfo>> 5471 5472Defines an **AudioCapturerChangeInfo** array, which is read-only. 5473 5474**System capability**: SystemCapability.Multimedia.Audio.Capturer 5475 5476| Type | Description | 5477|---------|-----------------------------------------------------------------| 5478| Array<Readonly<AudioCapturerChangeInfo>> | An [AudioCapturerChangeInfo](#audiocapturerchangeinfo9) array, which is read-only.| 5479 5480## AudioCapturerChangeInfo<sup>9+</sup> 5481 5482Describes the audio capturer change event. 5483 5484**System capability**: SystemCapability.Multimedia.Audio.Capturer 5485 5486| Name | Type | Readable| Writable| Description | 5487| -------------------| ----------------------------------------- | ---- | ---- | ---------------------------- | 5488| streamId | number | Yes | No | Unique ID of an audio stream. | 5489| capturerInfo | [AudioCapturerInfo](#audiocapturerinfo8) | Yes | No | Audio capturer information. | 5490| deviceDescriptors | [AudioDeviceDescriptors](#audiodevicedescriptors) | Yes | No | Audio device description.| 5491| 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.| 5492 5493**Example** 5494 5495```ts 5496import { audio } from '@kit.AudioKit'; 5497 5498const audioManager = audio.getAudioManager(); 5499let audioStreamManager = audioManager.getStreamManager(); 5500 5501audioStreamManager.on('audioCapturerChange', (AudioCapturerChangeInfoArray) => { 5502 for (let i = 0; i < AudioCapturerChangeInfoArray.length; i++) { 5503 console.info(`## CapChange on is called for element ${i} ##`); 5504 console.info(`StrId for ${i} is: ${AudioCapturerChangeInfoArray[i].streamId}`); 5505 console.info(`Src for ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.source}`); 5506 console.info(`Flag ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.capturerFlags}`); 5507 let devDescriptor = AudioCapturerChangeInfoArray[i].deviceDescriptors; 5508 for (let j = 0; j < AudioCapturerChangeInfoArray[i].deviceDescriptors.length; j++) { 5509 console.info(`Id: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].id}`); 5510 console.info(`Type: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceType}`); 5511 console.info(`Role: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceRole}`); 5512 console.info(`Name: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].name}`); 5513 console.info(`Addr: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].address}`); 5514 console.info(`SR: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].sampleRates[0]}`); 5515 console.info(`C ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelCounts[0]}`); 5516 console.info(`CM ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelMasks[0]}`); 5517 } 5518 } 5519}); 5520``` 5521 5522## AudioEffectInfoArray<sup>10+</sup> 5523 5524type AudioEffectInfoArray = Array<Readonly<AudioEffectMode>> 5525 5526Defines 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**System capability**: SystemCapability.Multimedia.Audio.Renderer 5529 5530| Type | Description | 5531|---------|---------------------------------------------------------------| 5532| 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.| 5533 5534## AudioDeviceDescriptors 5535 5536type AudioDeviceDescriptors = Array<Readonly<AudioDeviceDescriptor>> 5537 5538Defines an [AudioDeviceDescriptor](#audiodevicedescriptor) array, which is read-only. 5539 5540**Atomic service API**: This API can be used in atomic services since API version 12. 5541 5542**System capability**: SystemCapability.Multimedia.Audio.Device 5543 5544| Type | Description | 5545|---------|---------------------------------------------------------------| 5546| Array<Readonly<AudioDeviceDescriptor>> | Defines an [AudioDeviceDescriptor](#audiodevicedescriptor) array, which is read-only.| 5547 5548## AudioDeviceDescriptor 5549 5550Describes an audio device. 5551 5552**Atomic service API**: This API can be used in atomic services since API version 12. 5553 5554| Name | Type | Readable| Writable| Description | 5555| ----------------------------- | -------------------------- | ---- | ---- | ---------- | 5556| deviceRole | [DeviceRole](#devicerole) | Yes | No | Device role.<br> **System capability**: SystemCapability.Multimedia.Audio.Device| 5557| deviceType | [DeviceType](#devicetype) | Yes | No | Device type.<br> **System capability**: SystemCapability.Multimedia.Audio.Device| 5558| id<sup>9+</sup> | number | Yes | No | Device ID, which is unique.<br> **System capability**: SystemCapability.Multimedia.Audio.Device| 5559| 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| 5560| 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| 5561| sampleRates<sup>9+</sup> | Array<number> | Yes | No | Supported sampling rates.<br> **System capability**: SystemCapability.Multimedia.Audio.Device| 5562| channelCounts<sup>9+</sup> | Array<number> | Yes | No | Number of channels supported.<br> **System capability**: SystemCapability.Multimedia.Audio.Device| 5563| channelMasks<sup>9+</sup> | Array<number> | Yes | No | Supported channel masks.<br> **System capability**: SystemCapability.Multimedia.Audio.Device| 5564| displayName<sup>10+</sup> | string | Yes | No | Display name of the device.<br> **System capability**: SystemCapability.Multimedia.Audio.Device| 5565| encodingTypes<sup>11+</sup> | Array<[AudioEncodingType](#audioencodingtype8)> | Yes | No | Supported encoding types.<br> **System capability**: SystemCapability.Multimedia.Audio.Core| 5566 5567**Example** 5568 5569```ts 5570import { audio } from '@kit.AudioKit'; 5571 5572function displayDeviceProp(value: audio.AudioDeviceDescriptor) { 5573 deviceRoleValue = value.deviceRole; 5574 deviceTypeValue = value.deviceType; 5575} 5576 5577let deviceRoleValue: audio.DeviceRole | undefined = undefined; 5578let deviceTypeValue: audio.DeviceType | undefined = undefined; 5579audio.getAudioManager().getRoutingManager().getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG).then((value: audio.AudioDeviceDescriptors) => { 5580 console.info('AudioFrameworkTest: Promise: getDevices OUTPUT_DEVICES_FLAG'); 5581 value.forEach(displayDeviceProp); 5582 if (deviceTypeValue != undefined && deviceRoleValue != undefined){ 5583 console.info('AudioFrameworkTest: Promise: getDevices : OUTPUT_DEVICES_FLAG : PASS'); 5584 } else { 5585 console.error('AudioFrameworkTest: Promise: getDevices : OUTPUT_DEVICES_FLAG : FAIL'); 5586 } 5587}); 5588``` 5589## AudioDataCallbackResult<sup>12+</sup> 5590 5591Enumerates the audio data callback results. 5592 5593**System capability**: SystemCapability.Multimedia.Audio.Core 5594 5595| Name | Value | Description | 5596| ---------------------| --------| ----------------- | 5597| INVALID | -1 | The callback data is invalid. | 5598| VALID | 0 | The callback data is valid. | 5599 5600## AudioRendererWriteDataCallback<sup>12+</sup> 5601 5602type AudioRendererWriteDataCallback = (data: ArrayBuffer) => AudioDataCallbackResult | void 5603 5604Defines 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. 5605 5606**System capability**: SystemCapability.Multimedia.Audio.Renderer 5607 5608**Parameters** 5609 5610| Name | Type |Mandatory | Description | 5611| :--------------| :--------| :----- | :------------ | 5612| data | ArrayBuffer | Yes| Data to be written to the buffer.| 5613 5614**Return value** 5615 5616| Type | Description | 5617|--------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------| 5618| [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.| 5619 5620## AudioRenderer<sup>8+</sup> 5621 5622Provides APIs for audio rendering. Before calling any API in **AudioRenderer**, you must use [createAudioRenderer](#audiocreateaudiorenderer8) to create an **AudioRenderer** instance. 5623 5624### Attributes 5625 5626**System capability**: SystemCapability.Multimedia.Audio.Renderer 5627 5628| Name | Type | Readable| Writable| Description | 5629| ----- | -------------------------- | ---- | ---- | ------------------ | 5630| state<sup>8+</sup> | [AudioState](#audiostate8) | Yes | No | Audio renderer state.| 5631 5632**Example** 5633 5634```ts 5635import { audio } from '@kit.AudioKit'; 5636 5637let state: audio.AudioState = audioRenderer.state; 5638``` 5639 5640### getRendererInfo<sup>8+</sup> 5641 5642getRendererInfo(callback: AsyncCallback<AudioRendererInfo\>): void 5643 5644Obtains the renderer information of this **AudioRenderer** instance. This API uses an asynchronous callback to return the result. 5645 5646**System capability**: SystemCapability.Multimedia.Audio.Renderer 5647 5648**Parameters** 5649 5650| Name | Type | Mandatory| Description | 5651| :------- | :------------------------------------------------------- | :--- | :--------------------- | 5652| 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.| 5653 5654**Example** 5655 5656```ts 5657import { BusinessError } from '@kit.BasicServicesKit'; 5658 5659audioRenderer.getRendererInfo((err: BusinessError, rendererInfo: audio.AudioRendererInfo) => { 5660 console.info('Renderer GetRendererInfo:'); 5661 console.info(`Renderer content: ${rendererInfo.content}`); 5662 console.info(`Renderer usage: ${rendererInfo.usage}`); 5663 console.info(`Renderer flags: ${rendererInfo.rendererFlags}`); 5664}); 5665``` 5666 5667### getRendererInfo<sup>8+</sup> 5668 5669getRendererInfo(): Promise<AudioRendererInfo\> 5670 5671Obtains the renderer information of this **AudioRenderer** instance. This API uses a promise to return the result. 5672 5673**System capability**: SystemCapability.Multimedia.Audio.Renderer 5674 5675**Return value** 5676 5677| Type | Description | 5678| -------------------------------------------------- | ------------------------------- | 5679| Promise<[AudioRendererInfo](#audiorendererinfo8)\> | Promise used to return the renderer information.| 5680 5681**Example** 5682 5683```ts 5684import { BusinessError } from '@kit.BasicServicesKit'; 5685 5686audioRenderer.getRendererInfo().then((rendererInfo: audio.AudioRendererInfo) => { 5687 console.info('Renderer GetRendererInfo:'); 5688 console.info(`Renderer content: ${rendererInfo.content}`); 5689 console.info(`Renderer usage: ${rendererInfo.usage}`); 5690 console.info(`Renderer flags: ${rendererInfo.rendererFlags}`) 5691}).catch((err: BusinessError) => { 5692 console.error(`AudioFrameworkRenderLog: RendererInfo :ERROR: ${err}`); 5693}); 5694``` 5695 5696### getRendererInfoSync<sup>10+</sup> 5697 5698getRendererInfoSync(): AudioRendererInfo 5699 5700Obtains the renderer information of this **AudioRenderer** instance. This API returns the result synchronously. 5701 5702**System capability**: SystemCapability.Multimedia.Audio.Renderer 5703 5704**Return value** 5705 5706| Type | Description | 5707| -------------------------------------------------- | ------------------------------- | 5708| [AudioRendererInfo](#audiorendererinfo8) | Audio renderer information.| 5709 5710**Example** 5711 5712```ts 5713import { BusinessError } from '@kit.BasicServicesKit'; 5714 5715try { 5716 let rendererInfo: audio.AudioRendererInfo = audioRenderer.getRendererInfoSync(); 5717 console.info(`Renderer content: ${rendererInfo.content}`); 5718 console.info(`Renderer usage: ${rendererInfo.usage}`); 5719 console.info(`Renderer flags: ${rendererInfo.rendererFlags}`) 5720} catch (err) { 5721 let error = err as BusinessError; 5722 console.error(`AudioFrameworkRenderLog: RendererInfo :ERROR: ${error}`); 5723} 5724``` 5725 5726### getStreamInfo<sup>8+</sup> 5727 5728getStreamInfo(callback: AsyncCallback<AudioStreamInfo\>): void 5729 5730Obtains the stream information of this **AudioRenderer** instance. This API uses an asynchronous callback to return the result. 5731 5732**System capability**: SystemCapability.Multimedia.Audio.Renderer 5733 5734**Parameters** 5735 5736| Name | Type | Mandatory| Description | 5737| :------- | :--------------------------------------------------- | :--- | :------------------- | 5738| 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.| 5739 5740**Example** 5741 5742```ts 5743import { BusinessError } from '@kit.BasicServicesKit'; 5744 5745audioRenderer.getStreamInfo((err: BusinessError, streamInfo: audio.AudioStreamInfo) => { 5746 console.info('Renderer GetStreamInfo:'); 5747 console.info(`Renderer sampling rate: ${streamInfo.samplingRate}`); 5748 console.info(`Renderer channel: ${streamInfo.channels}`); 5749 console.info(`Renderer format: ${streamInfo.sampleFormat}`); 5750 console.info(`Renderer encoding type: ${streamInfo.encodingType}`); 5751}); 5752``` 5753 5754### getStreamInfo<sup>8+</sup> 5755 5756getStreamInfo(): Promise<AudioStreamInfo\> 5757 5758Obtains the stream information of this **AudioRenderer** instance. This API uses a promise to return the result. 5759 5760**System capability**: SystemCapability.Multimedia.Audio.Renderer 5761 5762**Return value** 5763 5764| Type | Description | 5765| :--------------------------------------------- | :--------------------- | 5766| Promise<[AudioStreamInfo](#audiostreaminfo8)\> | Promise used to return the stream information.| 5767 5768**Example** 5769 5770```ts 5771import { BusinessError } from '@kit.BasicServicesKit'; 5772 5773audioRenderer.getStreamInfo().then((streamInfo: audio.AudioStreamInfo) => { 5774 console.info('Renderer GetStreamInfo:'); 5775 console.info(`Renderer sampling rate: ${streamInfo.samplingRate}`); 5776 console.info(`Renderer channel: ${streamInfo.channels}`); 5777 console.info(`Renderer format: ${streamInfo.sampleFormat}`); 5778 console.info(`Renderer encoding type: ${streamInfo.encodingType}`); 5779}).catch((err: BusinessError) => { 5780 console.error(`ERROR: ${err}`); 5781}); 5782``` 5783 5784### getStreamInfoSync<sup>10+</sup> 5785 5786getStreamInfoSync(): AudioStreamInfo 5787 5788Obtains the stream information of this **AudioRenderer** instance. This API returns the result synchronously. 5789 5790**System capability**: SystemCapability.Multimedia.Audio.Renderer 5791 5792**Return value** 5793 5794| Type | Description | 5795| :--------------------------------------------- | :--------------------- | 5796| [AudioStreamInfo](#audiostreaminfo8) | Stream information.| 5797 5798**Example** 5799 5800```ts 5801import { BusinessError } from '@kit.BasicServicesKit'; 5802 5803try { 5804 let streamInfo: audio.AudioStreamInfo = audioRenderer.getStreamInfoSync(); 5805 console.info(`Renderer sampling rate: ${streamInfo.samplingRate}`); 5806 console.info(`Renderer channel: ${streamInfo.channels}`); 5807 console.info(`Renderer format: ${streamInfo.sampleFormat}`); 5808 console.info(`Renderer encoding type: ${streamInfo.encodingType}`); 5809} catch (err) { 5810 let error = err as BusinessError; 5811 console.error(`ERROR: ${error}`); 5812} 5813``` 5814 5815### getAudioStreamId<sup>9+</sup> 5816 5817getAudioStreamId(callback: AsyncCallback<number\>): void 5818 5819Obtains the stream ID of this **AudioRenderer** instance. This API uses an asynchronous callback to return the result. 5820 5821**System capability**: SystemCapability.Multimedia.Audio.Renderer 5822 5823**Parameters** 5824 5825| Name | Type | Mandatory| Description | 5826| :------- | :--------------------------------------------------- | :--- | :------------------- | 5827| 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.| 5828 5829**Example** 5830 5831```ts 5832import { BusinessError } from '@kit.BasicServicesKit'; 5833 5834audioRenderer.getAudioStreamId((err: BusinessError, streamId: number) => { 5835 console.info(`Renderer GetStreamId: ${streamId}`); 5836}); 5837``` 5838 5839### getAudioStreamId<sup>9+</sup> 5840 5841getAudioStreamId(): Promise<number\> 5842 5843Obtains the stream ID of this **AudioRenderer** instance. This API uses a promise to return the result. 5844 5845**System capability**: SystemCapability.Multimedia.Audio.Renderer 5846 5847**Return value** 5848 5849| Type | Description | 5850| :--------------------------------------------- | :--------------------- | 5851| Promise<number\> | Promise used to return the stream ID.| 5852 5853**Example** 5854 5855```ts 5856import { BusinessError } from '@kit.BasicServicesKit'; 5857 5858audioRenderer.getAudioStreamId().then((streamId: number) => { 5859 console.info(`Renderer getAudioStreamId: ${streamId}`); 5860}).catch((err: BusinessError) => { 5861 console.error(`ERROR: ${err}`); 5862}); 5863``` 5864 5865### getAudioStreamIdSync<sup>10+</sup> 5866 5867getAudioStreamIdSync(): number 5868 5869Obtains the stream ID of this **AudioRenderer** instance. This API returns the result synchronously. 5870 5871**System capability**: SystemCapability.Multimedia.Audio.Renderer 5872 5873**Return value** 5874 5875| Type | Description | 5876| :--------------------------------------------- | :--------------------- | 5877| number | Stream ID.| 5878 5879**Example** 5880 5881```ts 5882import { BusinessError } from '@kit.BasicServicesKit'; 5883 5884try { 5885 let streamId: number = audioRenderer.getAudioStreamIdSync(); 5886 console.info(`Renderer getAudioStreamIdSync: ${streamId}`); 5887} catch (err) { 5888 let error = err as BusinessError; 5889 console.error(`ERROR: ${error}`); 5890} 5891``` 5892 5893### setAudioEffectMode<sup>10+</sup> 5894 5895setAudioEffectMode(mode: AudioEffectMode, callback: AsyncCallback\<void>): void 5896 5897Sets an audio effect mode. This API uses an asynchronous callback to return the result. 5898 5899**System capability**: SystemCapability.Multimedia.Audio.Renderer 5900 5901**Parameters** 5902 5903| Name | Type | Mandatory| Description | 5904| -------- | ---------------------------------------- | ---- | ------------------------ | 5905| mode | [AudioEffectMode](#audioeffectmode10) | Yes | Audio effect mode to set. | 5906| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 5907 5908**Error codes** 5909 5910For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5911 5912| ID| Error Message| 5913| ------- | ----------------------------------------------| 5914| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5915| 6800101 | Parameter verification failed. Return by callback. | 5916 5917**Example** 5918 5919```ts 5920import { BusinessError } from '@kit.BasicServicesKit'; 5921 5922audioRenderer.setAudioEffectMode(audio.AudioEffectMode.EFFECT_DEFAULT, (err: BusinessError) => { 5923 if (err) { 5924 console.error('Failed to set params'); 5925 } else { 5926 console.info('Callback invoked to indicate a successful audio effect mode setting.'); 5927 } 5928}); 5929``` 5930 5931### setAudioEffectMode<sup>10+</sup> 5932 5933setAudioEffectMode(mode: AudioEffectMode): Promise\<void> 5934 5935Sets an audio effect mode. This API uses a promise to return the result. 5936 5937**System capability**: SystemCapability.Multimedia.Audio.Renderer 5938 5939**Parameters** 5940 5941| Name| Type | Mandatory| Description | 5942| ------ | ---------------------------------------- | ---- | ------------ | 5943| mode | [AudioEffectMode](#audioeffectmode10) | Yes | Audio effect mode to set.| 5944 5945**Return value** 5946 5947| Type | Description | 5948| -------------- | ------------------------- | 5949| Promise\<void> | Promise that returns no value.| 5950 5951**Error codes** 5952 5953For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5954 5955| ID| Error Message| 5956| ------- | ---------------------------------------------| 5957| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5958| 6800101 | Parameter verification failed. Return by promise. | 5959 5960**Example** 5961 5962```ts 5963import { BusinessError } from '@kit.BasicServicesKit'; 5964 5965audioRenderer.setAudioEffectMode(audio.AudioEffectMode.EFFECT_DEFAULT).then(() => { 5966 console.info('setAudioEffectMode SUCCESS'); 5967}).catch((err: BusinessError) => { 5968 console.error(`ERROR: ${err}`); 5969}); 5970``` 5971 5972### getAudioEffectMode<sup>10+</sup> 5973 5974getAudioEffectMode(callback: AsyncCallback\<AudioEffectMode>): void 5975 5976Obtains the audio effect mode in use. This API uses an asynchronous callback to return the result. 5977 5978**System capability**: SystemCapability.Multimedia.Audio.Renderer 5979 5980**Parameters** 5981 5982| Name | Type | Mandatory| Description | 5983| -------- | ------------------------------------------------------- | ---- | ------------------ | 5984| 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.| 5985 5986**Example** 5987 5988```ts 5989import { BusinessError } from '@kit.BasicServicesKit'; 5990 5991audioRenderer.getAudioEffectMode((err: BusinessError, effectMode: audio.AudioEffectMode) => { 5992 if (err) { 5993 console.error('Failed to get params'); 5994 } else { 5995 console.info(`getAudioEffectMode: ${effectMode}`); 5996 } 5997}); 5998``` 5999 6000### getAudioEffectMode<sup>10+</sup> 6001 6002getAudioEffectMode(): Promise\<AudioEffectMode> 6003 6004Obtains the audio effect mode in use. This API uses a promise to return the result. 6005 6006**System capability**: SystemCapability.Multimedia.Audio.Renderer 6007 6008**Return value** 6009 6010| Type | Description | 6011| ------------------------------------------------- | ------------------------- | 6012| Promise<[AudioEffectMode](#audioeffectmode10)> | Promise used to return the audio effect mode.| 6013 6014**Example** 6015 6016```ts 6017import { BusinessError } from '@kit.BasicServicesKit'; 6018 6019audioRenderer.getAudioEffectMode().then((effectMode: audio.AudioEffectMode) => { 6020 console.info(`getAudioEffectMode: ${effectMode}`); 6021}).catch((err: BusinessError) => { 6022 console.error(`ERROR: ${err}`); 6023}); 6024``` 6025 6026### start<sup>8+</sup> 6027 6028start(callback: AsyncCallback<void\>): void 6029 6030Starts the renderer. This API uses an asynchronous callback to return the result. 6031 6032**System capability**: SystemCapability.Multimedia.Audio.Renderer 6033 6034**Parameters** 6035 6036| Name | Type | Mandatory| Description | 6037| -------- | -------------------- | ---- | ---------- | 6038| 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.| 6039 6040**Example** 6041 6042```ts 6043import { BusinessError } from '@kit.BasicServicesKit'; 6044 6045audioRenderer.start((err: BusinessError) => { 6046 if (err) { 6047 console.error('Renderer start failed.'); 6048 } else { 6049 console.info('Renderer start success.'); 6050 } 6051}); 6052``` 6053 6054### start<sup>8+</sup> 6055 6056start(): Promise<void\> 6057 6058Starts the renderer. This API uses a promise to return the result. 6059 6060**System capability**: SystemCapability.Multimedia.Audio.Renderer 6061 6062**Return value** 6063 6064| Type | Description | 6065| -------------- | ------------------------- | 6066| 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.| 6067 6068**Example** 6069 6070```ts 6071import { BusinessError } from '@kit.BasicServicesKit'; 6072 6073audioRenderer.start().then(() => { 6074 console.info('Renderer started'); 6075}).catch((err: BusinessError) => { 6076 console.error(`ERROR: ${err}`); 6077}); 6078``` 6079 6080### pause<sup>8+</sup> 6081 6082pause(callback: AsyncCallback\<void>): void 6083 6084Pauses rendering. This API uses an asynchronous callback to return the result. 6085 6086**System capability**: SystemCapability.Multimedia.Audio.Renderer 6087 6088**Parameters** 6089 6090| Name | Type | Mandatory| Description | 6091| -------- | -------------------- | ---- | ---------------- | 6092| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 6093 6094**Example** 6095 6096```ts 6097import { BusinessError } from '@kit.BasicServicesKit'; 6098 6099audioRenderer.pause((err: BusinessError) => { 6100 if (err) { 6101 console.error('Renderer pause failed'); 6102 } else { 6103 console.info('Renderer paused.'); 6104 } 6105}); 6106``` 6107 6108### pause<sup>8+</sup> 6109 6110pause(): Promise\<void> 6111 6112Pauses rendering. This API uses a promise to return the result. 6113 6114**System capability**: SystemCapability.Multimedia.Audio.Renderer 6115 6116**Return value** 6117 6118| Type | Description | 6119| -------------- | ------------------------- | 6120| Promise\<void> | Promise that returns no value.| 6121 6122**Example** 6123 6124```ts 6125import { BusinessError } from '@kit.BasicServicesKit'; 6126 6127audioRenderer.pause().then(() => { 6128 console.info('Renderer paused'); 6129}).catch((err: BusinessError) => { 6130 console.error(`ERROR: ${err}`); 6131}); 6132``` 6133 6134### drain<sup>8+</sup> 6135 6136drain(callback: AsyncCallback\<void>): void 6137 6138Drains the playback buffer. This API uses an asynchronous callback to return the result. 6139 6140**System capability**: SystemCapability.Multimedia.Audio.Renderer 6141 6142**Parameters** 6143 6144| Name | Type | Mandatory| Description | 6145| -------- | -------------------- | ---- | ---------------- | 6146| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 6147 6148**Example** 6149 6150```ts 6151import { BusinessError } from '@kit.BasicServicesKit'; 6152 6153audioRenderer.drain((err: BusinessError) => { 6154 if (err) { 6155 console.error('Renderer drain failed'); 6156 } else { 6157 console.info('Renderer drained.'); 6158 } 6159}); 6160``` 6161 6162### drain<sup>8+</sup> 6163 6164drain(): Promise\<void> 6165 6166Drains the playback buffer. This API uses a promise to return the result. 6167 6168**System capability**: SystemCapability.Multimedia.Audio.Renderer 6169 6170**Return value** 6171 6172| Type | Description | 6173| -------------- | ------------------------- | 6174| Promise\<void> | Promise that returns no value.| 6175 6176**Example** 6177 6178```ts 6179import { BusinessError } from '@kit.BasicServicesKit'; 6180 6181audioRenderer.drain().then(() => { 6182 console.info('Renderer drained successfully'); 6183}).catch((err: BusinessError) => { 6184 console.error(`ERROR: ${err}`); 6185}); 6186``` 6187 6188### flush<sup>11+</sup> 6189 6190flush(): Promise\<void> 6191 6192Flushes 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. 6193 6194**System capability**: SystemCapability.Multimedia.Audio.Renderer 6195 6196**Return value** 6197 6198| Type | Description | 6199| -------------- | ------------------------- | 6200| Promise\<void> | Promise that returns no value.| 6201 6202**Error codes** 6203 6204For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 6205 6206| ID| Error Message| 6207| ------- | --------------------------------------------| 6208| 6800103 | Operation not permit at current state. Return by promise. | 6209 6210**Example** 6211 6212```ts 6213import { BusinessError } from '@kit.BasicServicesKit'; 6214 6215audioRenderer.flush().then(() => { 6216 console.info('Renderer flushed successfully'); 6217}).catch((err: BusinessError) => { 6218 console.error(`ERROR: ${err}`); 6219}); 6220``` 6221 6222### stop<sup>8+</sup> 6223 6224stop(callback: AsyncCallback\<void>): void 6225 6226Stops rendering. This API uses an asynchronous callback to return the result. 6227 6228**System capability**: SystemCapability.Multimedia.Audio.Renderer 6229 6230**Parameters** 6231 6232| Name | Type | Mandatory| Description | 6233| -------- | -------------------- | ---- | ---------------- | 6234| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 6235 6236**Example** 6237 6238```ts 6239import { BusinessError } from '@kit.BasicServicesKit'; 6240 6241audioRenderer.stop((err: BusinessError) => { 6242 if (err) { 6243 console.error('Renderer stop failed'); 6244 } else { 6245 console.info('Renderer stopped.'); 6246 } 6247}); 6248``` 6249 6250### stop<sup>8+</sup> 6251 6252stop(): Promise\<void> 6253 6254Stops rendering. This API uses a promise to return the result. 6255 6256**System capability**: SystemCapability.Multimedia.Audio.Renderer 6257 6258**Return value** 6259 6260| Type | Description | 6261| -------------- | ------------------------- | 6262| Promise\<void> | Promise that returns no value.| 6263 6264**Example** 6265 6266```ts 6267import { BusinessError } from '@kit.BasicServicesKit'; 6268 6269audioRenderer.stop().then(() => { 6270 console.info('Renderer stopped successfully'); 6271}).catch((err: BusinessError) => { 6272 console.error(`ERROR: ${err}`); 6273}); 6274``` 6275 6276### release<sup>8+</sup> 6277 6278release(callback: AsyncCallback\<void>): void 6279 6280Releases the renderer. This API uses an asynchronous callback to return the result. 6281 6282**System capability**: SystemCapability.Multimedia.Audio.Renderer 6283 6284**Parameters** 6285 6286| Name | Type | Mandatory| Description | 6287| -------- | -------------------- | ---- | ---------------- | 6288| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 6289 6290**Example** 6291 6292```ts 6293import { BusinessError } from '@kit.BasicServicesKit'; 6294 6295audioRenderer.release((err: BusinessError) => { 6296 if (err) { 6297 console.error('Renderer release failed'); 6298 } else { 6299 console.info('Renderer released.'); 6300 } 6301}); 6302``` 6303 6304### release<sup>8+</sup> 6305 6306release(): Promise\<void> 6307 6308Releases the renderer. This API uses a promise to return the result. 6309 6310**System capability**: SystemCapability.Multimedia.Audio.Renderer 6311 6312**Return value** 6313 6314| Type | Description | 6315| -------------- | ------------------------- | 6316| Promise\<void> | Promise that returns no value.| 6317 6318**Example** 6319 6320```ts 6321import { BusinessError } from '@kit.BasicServicesKit'; 6322 6323audioRenderer.release().then(() => { 6324 console.info('Renderer released successfully'); 6325}).catch((err: BusinessError) => { 6326 console.error(`ERROR: ${err}`); 6327}); 6328``` 6329 6330### write<sup>8+(deprecated)</sup> 6331 6332write(buffer: ArrayBuffer, callback: AsyncCallback\<number>): void 6333 6334Writes the buffer. This API uses an asynchronous callback to return the result. 6335 6336> **NOTE** 6337> 6338> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [on('writeData')](#onwritedata11) in **AudioRenderer**. 6339 6340**System capability**: SystemCapability.Multimedia.Audio.Renderer 6341 6342**Parameters** 6343 6344| Name | Type | Mandatory| Description | 6345| -------- | ---------------------- | ---- | --------------------------------------------------- | 6346| buffer | ArrayBuffer | Yes | Data to be written to the buffer. | 6347| 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.| 6348 6349**Example** 6350 6351```ts 6352import { BusinessError } from '@kit.BasicServicesKit'; 6353import { fileIo as fs } from '@kit.CoreFileKit'; 6354 6355let bufferSize: number; 6356class Options { 6357 offset?: number; 6358 length?: number; 6359} 6360audioRenderer.getBufferSize().then((data: number)=> { 6361 console.info(`AudioFrameworkRenderLog: getBufferSize: SUCCESS ${data}`); 6362 bufferSize = data; 6363 console.info(`Buffer size: ${bufferSize}`); 6364 let path = getContext().cacheDir; 6365 let filePath = path + '/StarWars10s-2C-48000-4SW.wav'; 6366 let file: fs.File = fs.openSync(filePath, fs.OpenMode.READ_ONLY); 6367 fs.stat(filePath).then(async (stat: fs.Stat) => { 6368 let buf = new ArrayBuffer(bufferSize); 6369 let len = stat.size % bufferSize == 0 ? Math.floor(stat.size / bufferSize) : Math.floor(stat.size / bufferSize + 1); 6370 for (let i = 0;i < len; i++) { 6371 let options: Options = { 6372 offset: i * bufferSize, 6373 length: bufferSize 6374 }; 6375 let readSize: number = await fs.read(file.fd, buf, options); 6376 let writeSize: number = await new Promise((resolve,reject)=>{ 6377 audioRenderer.write(buf,(err: BusinessError, writeSize: number)=>{ 6378 if(err){ 6379 reject(err) 6380 }else{ 6381 resolve(writeSize) 6382 } 6383 }) 6384 }) 6385 } 6386 }); 6387 }).catch((err: BusinessError) => { 6388 console.error(`AudioFrameworkRenderLog: getBufferSize: ERROR: ${err}`); 6389}); 6390``` 6391 6392### write<sup>8+(deprecated)</sup> 6393 6394write(buffer: ArrayBuffer): Promise\<number> 6395 6396Writes the buffer. This API uses a promise to return the result. 6397 6398> **NOTE** 6399> 6400> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [on('writeData')](#onwritedata11) in **AudioRenderer**. 6401 6402**System capability**: SystemCapability.Multimedia.Audio.Renderer 6403 6404**Parameters** 6405 6406| Name | Type | Mandatory| Description | 6407| -------- | ---------------------- | ---- | --------------------------------------------------- | 6408| buffer | ArrayBuffer | Yes | Data to be written to the buffer. | 6409 6410**Return value** 6411 6412| Type | Description | 6413| ---------------- | ------------------------------------------------------------ | 6414| Promise\<number> | Promise used to return the number of written bytes.| 6415 6416**Example** 6417 6418```ts 6419import { BusinessError } from '@kit.BasicServicesKit'; 6420import { fileIo as fs } from '@kit.CoreFileKit'; 6421 6422let bufferSize: number; 6423class Options { 6424 offset?: number; 6425 length?: number; 6426} 6427audioRenderer.getBufferSize().then((data: number) => { 6428 console.info(`AudioFrameworkRenderLog: getBufferSize: SUCCESS ${data}`); 6429 bufferSize = data; 6430 console.info(`BufferSize: ${bufferSize}`); 6431 let path = getContext().cacheDir; 6432 let filePath = path + '/StarWars10s-2C-48000-4SW.wav'; 6433 let file: fs.File = fs.openSync(filePath, fs.OpenMode.READ_ONLY); 6434 fs.stat(filePath).then(async (stat: fs.Stat) => { 6435 let buf = new ArrayBuffer(bufferSize); 6436 let len = stat.size % bufferSize == 0 ? Math.floor(stat.size / bufferSize) : Math.floor(stat.size / bufferSize + 1); 6437 for (let i = 0;i < len; i++) { 6438 let options: Options = { 6439 offset: i * bufferSize, 6440 length: bufferSize 6441 }; 6442 let readSize: number = await fs.read(file.fd, buf, options); 6443 try{ 6444 let writeSize: number = await audioRenderer.write(buf); 6445 } catch(err) { 6446 let error = err as BusinessError; 6447 console.error(`audioRenderer.write err: ${error}`); 6448 } 6449 } 6450 }); 6451}).catch((err: BusinessError) => { 6452 console.error(`AudioFrameworkRenderLog: getBufferSize: ERROR: ${err}`); 6453}); 6454``` 6455 6456### getAudioTime<sup>8+</sup> 6457 6458getAudioTime(callback: AsyncCallback\<number>): void 6459 6460Obtains 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. 6461 6462**System capability**: SystemCapability.Multimedia.Audio.Renderer 6463 6464**Parameters** 6465 6466| Name | Type | Mandatory| Description | 6467| -------- | ---------------------- | ---- | ---------------- | 6468| 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.| 6469 6470**Example** 6471 6472```ts 6473import { BusinessError } from '@kit.BasicServicesKit'; 6474 6475audioRenderer.getAudioTime((err: BusinessError, timestamp: number) => { 6476 console.info(`Current timestamp: ${timestamp}`); 6477}); 6478``` 6479 6480### getAudioTime<sup>8+</sup> 6481 6482getAudioTime(): Promise\<number> 6483 6484Obtains 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. 6485 6486**System capability**: SystemCapability.Multimedia.Audio.Renderer 6487 6488**Return value** 6489 6490| Type | Description | 6491| ---------------- | ----------------------- | 6492| Promise\<number> | Promise used to return the timestamp.| 6493 6494**Example** 6495 6496```ts 6497import { BusinessError } from '@kit.BasicServicesKit'; 6498 6499audioRenderer.getAudioTime().then((timestamp: number) => { 6500 console.info(`Current timestamp: ${timestamp}`); 6501}).catch((err: BusinessError) => { 6502 console.error(`ERROR: ${err}`); 6503}); 6504``` 6505 6506### getAudioTimeSync<sup>10+</sup> 6507 6508getAudioTimeSync(): number 6509 6510Obtains the timestamp of the current playback position, measured in nanoseconds from the Unix epoch (January 1, 1970). This API returns the result synchronously: 6511 6512**System capability**: SystemCapability.Multimedia.Audio.Renderer 6513 6514**Return value** 6515 6516| Type | Description | 6517| ---------------- | ----------------------- | 6518| number | Timestamp.| 6519 6520**Example** 6521 6522```ts 6523import { BusinessError } from '@kit.BasicServicesKit'; 6524 6525try { 6526 let timestamp: number = audioRenderer.getAudioTimeSync(); 6527 console.info(`Current timestamp: ${timestamp}`); 6528} catch (err) { 6529 let error = err as BusinessError; 6530 console.error(`ERROR: ${error}`); 6531} 6532``` 6533 6534### getBufferSize<sup>8+</sup> 6535 6536getBufferSize(callback: AsyncCallback\<number>): void 6537 6538Obtains a reasonable minimum buffer size in bytes for rendering. This API uses an asynchronous callback to return the result. 6539 6540**System capability**: SystemCapability.Multimedia.Audio.Renderer 6541 6542**Parameters** 6543 6544| Name | Type | Mandatory| Description | 6545| -------- | ---------------------- | ---- | -------------------- | 6546| 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.| 6547 6548**Example** 6549 6550```ts 6551import { BusinessError } from '@kit.BasicServicesKit'; 6552 6553let bufferSize: number; 6554 6555audioRenderer.getBufferSize((err: BusinessError, data: number) => { 6556 if (err) { 6557 console.error('getBufferSize error'); 6558 } else { 6559 console.info(`AudioFrameworkRenderLog: getBufferSize: SUCCESS ${data}`); 6560 bufferSize = data; 6561 } 6562}); 6563``` 6564 6565### getBufferSize<sup>8+</sup> 6566 6567getBufferSize(): Promise\<number> 6568 6569Obtains a reasonable minimum buffer size in bytes for rendering. This API uses a promise to return the result. 6570 6571**System capability**: SystemCapability.Multimedia.Audio.Renderer 6572 6573**Return value** 6574 6575| Type | Description | 6576| ---------------- | --------------------------- | 6577| Promise\<number> | Promise used to return the buffer size.| 6578 6579**Example** 6580 6581```ts 6582import { BusinessError } from '@kit.BasicServicesKit'; 6583 6584let bufferSize: number; 6585 6586audioRenderer.getBufferSize().then((data: number) => { 6587 console.info(`AudioFrameworkRenderLog: getBufferSize: SUCCESS ${data}`); 6588 bufferSize = data; 6589}).catch((err: BusinessError) => { 6590 console.error(`AudioFrameworkRenderLog: getBufferSize: ERROR: ${err}`); 6591}); 6592``` 6593 6594### getBufferSizeSync<sup>10+</sup> 6595 6596getBufferSizeSync(): number 6597 6598Obtains a reasonable minimum buffer size in bytes for rendering. This API returns the result synchronously. 6599 6600**System capability**: SystemCapability.Multimedia.Audio.Renderer 6601 6602**Return value** 6603 6604| Type | Description | 6605| ---------------- | --------------------------- | 6606| number | Buffer size.| 6607 6608**Example** 6609 6610```ts 6611import { BusinessError } from '@kit.BasicServicesKit'; 6612 6613let bufferSize: number = 0; 6614 6615try { 6616 bufferSize = audioRenderer.getBufferSizeSync(); 6617 console.info(`AudioFrameworkRenderLog: getBufferSize: SUCCESS ${bufferSize}`); 6618} catch (err) { 6619 let error = err as BusinessError; 6620 console.error(`AudioFrameworkRenderLog: getBufferSize: ERROR: ${error}`); 6621} 6622``` 6623 6624### setRenderRate<sup>8+(deprecated)</sup> 6625 6626setRenderRate(rate: AudioRendererRate, callback: AsyncCallback\<void>): void 6627 6628Sets the render rate. This API uses an asynchronous callback to return the result. 6629 6630> **NOTE** 6631> 6632> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [setSpeed](#setspeed11) in **AudioRenderer**. 6633 6634**System capability**: SystemCapability.Multimedia.Audio.Renderer 6635 6636**Parameters** 6637 6638| Name | Type | Mandatory| Description | 6639| -------- | ---------------------------------------- | ---- | ------------------------ | 6640| rate | [AudioRendererRate](#audiorendererrate8) | Yes | Audio render rate. | 6641| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 6642 6643**Example** 6644 6645```ts 6646import { BusinessError } from '@kit.BasicServicesKit'; 6647 6648audioRenderer.setRenderRate(audio.AudioRendererRate.RENDER_RATE_NORMAL, (err: BusinessError) => { 6649 if (err) { 6650 console.error('Failed to set params'); 6651 } else { 6652 console.info('Callback invoked to indicate a successful render rate setting.'); 6653 } 6654}); 6655``` 6656 6657### setRenderRate<sup>8+(deprecated)</sup> 6658 6659setRenderRate(rate: AudioRendererRate): Promise\<void> 6660 6661Sets the render rate. This API uses a promise to return the result. 6662 6663> **NOTE** 6664> 6665> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [setSpeed](#setspeed11) in **AudioRenderer**. 6666 6667**System capability**: SystemCapability.Multimedia.Audio.Renderer 6668 6669**Parameters** 6670 6671| Name| Type | Mandatory| Description | 6672| ------ | ---------------------------------------- | ---- | ------------ | 6673| rate | [AudioRendererRate](#audiorendererrate8) | Yes | Audio render rate.| 6674 6675**Return value** 6676 6677| Type | Description | 6678| -------------- | ------------------------- | 6679| Promise\<void> | Promise that returns no value.| 6680 6681**Example** 6682 6683```ts 6684import { BusinessError } from '@kit.BasicServicesKit'; 6685 6686audioRenderer.setRenderRate(audio.AudioRendererRate.RENDER_RATE_NORMAL).then(() => { 6687 console.info('setRenderRate SUCCESS'); 6688}).catch((err: BusinessError) => { 6689 console.error(`ERROR: ${err}`); 6690}); 6691``` 6692 6693### setSpeed<sup>11+</sup> 6694 6695setSpeed(speed: number): void 6696 6697Sets the playback speed. 6698 6699**System capability**: SystemCapability.Multimedia.Audio.Renderer 6700 6701**Parameters** 6702 6703| Name| Type | Mandatory| Description | 6704| ------ | ---------------------------------------- | ---- |----------------------| 6705| speed | number | Yes | Playback speed, which ranges from 0.125 to 4.0.| 6706 6707**Error codes** 6708 6709For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 6710 6711| ID| Error Message| 6712| ------- | --------------------------------------------| 6713| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 6714| 6800101 | Parameter verification failed. | 6715 6716**Example** 6717 6718```ts 6719audioRenderer.setSpeed(1.5); 6720``` 6721 6722### getRenderRate<sup>8+(deprecated)</sup> 6723 6724getRenderRate(callback: AsyncCallback\<AudioRendererRate>): void 6725 6726Obtains the current render rate. This API uses an asynchronous callback to return the result. 6727 6728> **NOTE** 6729> 6730> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [getSpeed](#getspeed11) in **AudioRenderer**. 6731 6732**System capability**: SystemCapability.Multimedia.Audio.Renderer 6733 6734**Parameters** 6735 6736| Name | Type | Mandatory| Description | 6737| -------- | ------------------------------------------------------- | ---- | ------------------ | 6738| 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.| 6739 6740**Example** 6741 6742```ts 6743import { BusinessError } from '@kit.BasicServicesKit'; 6744 6745audioRenderer.getRenderRate((err: BusinessError, renderRate: audio.AudioRendererRate) => { 6746 console.info(`getRenderRate: ${renderRate}`); 6747}); 6748``` 6749 6750### getRenderRate<sup>8+(deprecated)</sup> 6751 6752getRenderRate(): Promise\<AudioRendererRate> 6753 6754Obtains the current render rate. This API uses a promise to return the result. 6755 6756> **NOTE** 6757> 6758> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [getSpeed](#getspeed11) in **AudioRenderer**. 6759 6760**System capability**: SystemCapability.Multimedia.Audio.Renderer 6761 6762**Return value** 6763 6764| Type | Description | 6765| ------------------------------------------------- | ------------------------- | 6766| Promise<[AudioRendererRate](#audiorendererrate8)> | Promise used to return the render rate.| 6767 6768**Example** 6769 6770```ts 6771import { BusinessError } from '@kit.BasicServicesKit'; 6772 6773audioRenderer.getRenderRate().then((renderRate: audio.AudioRendererRate) => { 6774 console.info(`getRenderRate: ${renderRate}`); 6775}).catch((err: BusinessError) => { 6776 console.error(`ERROR: ${err}`); 6777}); 6778``` 6779 6780### getRenderRateSync<sup>10+(deprecated)</sup> 6781 6782getRenderRateSync(): AudioRendererRate 6783 6784Obtains the current render rate. This API returns the result synchronously. 6785 6786> **NOTE** 6787> 6788> This API is supported since API version 10 and deprecated since API version 11. You are advised to use [getSpeed](#getspeed11) in **AudioRenderer**. 6789 6790**System capability**: SystemCapability.Multimedia.Audio.Renderer 6791 6792**Return value** 6793 6794| Type | Description | 6795| ------------------------------------------------- | ------------------------- | 6796| [AudioRendererRate](#audiorendererrate8) | Audio render rate.| 6797 6798**Example** 6799 6800```ts 6801import { BusinessError } from '@kit.BasicServicesKit'; 6802 6803try { 6804 let renderRate: audio.AudioRendererRate = audioRenderer.getRenderRateSync(); 6805 console.info(`getRenderRate: ${renderRate}`); 6806} catch (err) { 6807 let error = err as BusinessError; 6808 console.error(`ERROR: ${error}`); 6809} 6810``` 6811 6812### getSpeed<sup>11+</sup> 6813 6814getSpeed(): number 6815 6816Obtains the playback speed. 6817 6818**System capability**: SystemCapability.Multimedia.Audio.Renderer 6819 6820**Return value** 6821 6822| Type | Description | 6823| ------------------------------------------------- |-----------| 6824| number | Playback speed.| 6825 6826**Example** 6827 6828```ts 6829let speed = audioRenderer.getSpeed(); 6830``` 6831 6832### setInterruptMode<sup>9+</sup> 6833 6834setInterruptMode(mode: InterruptMode): Promise<void> 6835 6836Sets the audio interruption mode for the application. This API uses a promise to return the result. 6837 6838**System capability**: SystemCapability.Multimedia.Audio.Interrupt 6839 6840**Parameters** 6841 6842| Name | Type | Mandatory | Description | 6843| ---------- | ---------------------------------- | ------ | ---------- | 6844| mode | [InterruptMode](#interruptmode9) | Yes | Audio interruption mode. | 6845 6846**Return value** 6847 6848| Type | Description | 6849| ------------------- | ----------------------------- | 6850| Promise<void> | Promise that returns no value.| 6851 6852**Example** 6853 6854```ts 6855import { BusinessError } from '@kit.BasicServicesKit'; 6856 6857let mode = 0; 6858 6859audioRenderer.setInterruptMode(mode).then(() => { 6860 console.info('setInterruptMode Success!'); 6861}).catch((err: BusinessError) => { 6862 console.error(`setInterruptMode Fail: ${err}`); 6863}); 6864``` 6865### setInterruptMode<sup>9+</sup> 6866 6867setInterruptMode(mode: InterruptMode, callback: AsyncCallback\<void>): void 6868 6869Sets the audio interruption mode for the application. This API uses an asynchronous callback to return the result. 6870 6871**System capability**: SystemCapability.Multimedia.Audio.Interrupt 6872 6873**Parameters** 6874 6875| Name | Type | Mandatory | Description | 6876| ------- | ----------------------------------- | ------ | -------------- | 6877|mode | [InterruptMode](#interruptmode9) | Yes | Audio interruption mode.| 6878|callback | AsyncCallback\<void> | Yes |Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 6879 6880**Example** 6881 6882```ts 6883import { BusinessError } from '@kit.BasicServicesKit'; 6884 6885let mode = 1; 6886 6887audioRenderer.setInterruptMode(mode, (err: BusinessError) => { 6888 if(err){ 6889 console.error(`setInterruptMode Fail: ${err}`); 6890 } 6891 console.info('setInterruptMode Success!'); 6892}); 6893``` 6894 6895### setInterruptModeSync<sup>10+</sup> 6896 6897setInterruptModeSync(mode: InterruptMode): void 6898 6899Sets the audio interruption mode for the application. This API returns the result synchronously. 6900 6901**System capability**: SystemCapability.Multimedia.Audio.Interrupt 6902 6903**Parameters** 6904 6905| Name | Type | Mandatory | Description | 6906| ---------- | ---------------------------------- | ------ | ---------- | 6907| mode | [InterruptMode](#interruptmode9) | Yes | Audio interruption mode. | 6908 6909**Error codes** 6910 6911For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 6912 6913| ID| Error Message| 6914| ------- | --------------------------------------------| 6915| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 6916| 6800101 | Parameter verification failed. | 6917 6918**Example** 6919 6920```ts 6921import { BusinessError } from '@kit.BasicServicesKit'; 6922 6923try { 6924 audioRenderer.setInterruptModeSync(0); 6925 console.info('setInterruptMode Success!'); 6926} catch (err) { 6927 let error = err as BusinessError; 6928 console.error(`setInterruptMode Fail: ${error}`); 6929} 6930``` 6931 6932### setVolume<sup>9+</sup> 6933 6934setVolume(volume: number): Promise<void> 6935 6936Sets the volume for the application. This API uses a promise to return the result. 6937 6938**System capability**: SystemCapability.Multimedia.Audio.Renderer 6939 6940**Parameters** 6941 6942| Name | Type | Mandatory | Description | 6943| ---------- | ------- | ------ | ------------------- | 6944| volume | number | Yes | Volume to set, which can be within the range from 0.0 to 1.0.| 6945 6946**Return value** 6947 6948| Type | Description | 6949| ------------------- | ----------------------------- | 6950| Promise<void> | Promise that returns no value.| 6951 6952**Example** 6953 6954```ts 6955import { BusinessError } from '@kit.BasicServicesKit'; 6956 6957audioRenderer.setVolume(0.5).then(() => { 6958 console.info('setVolume Success!'); 6959}).catch((err: BusinessError) => { 6960 console.error(`setVolume Fail: ${err}`); 6961}); 6962``` 6963### setVolume<sup>9+</sup> 6964 6965setVolume(volume: number, callback: AsyncCallback\<void>): void 6966 6967Sets the volume for the application. This API uses an asynchronous callback to return the result. 6968 6969**System capability**: SystemCapability.Multimedia.Audio.Renderer 6970 6971**Parameters** 6972 6973| Name | Type | Mandatory | Description | 6974| ------- | -----------| ------ | ------------------- | 6975|volume | number | Yes | Volume to set, which can be within the range from 0.0 to 1.0.| 6976|callback | AsyncCallback\<void> | Yes |Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 6977 6978**Example** 6979 6980```ts 6981import { BusinessError } from '@kit.BasicServicesKit'; 6982 6983audioRenderer.setVolume(0.5, (err: BusinessError) => { 6984 if(err){ 6985 console.error(`setVolume Fail: ${err}`); 6986 return; 6987 } 6988 console.info('setVolume Success!'); 6989}); 6990``` 6991### getVolume<sup>12+</sup> 6992 6993getVolume(): number 6994 6995Obtains the volume of the audio render. This API returns the result synchronously. 6996 6997**System capability**: SystemCapability.Multimedia.Audio.Renderer 6998 6999**Return value** 7000 7001| Type | Description | 7002| ---------------- | --------------------------- | 7003| number | Volume, in the range [0.0-1.0].| 7004 7005**Example** 7006 7007```ts 7008import { BusinessError } from '@kit.BasicServicesKit'; 7009 7010try { 7011 let value: number = audioRenderer.getVolume(); 7012 console.info(`Indicate that the volume is obtained ${value}.`); 7013} catch (err) { 7014 let error = err as BusinessError; 7015 console.error(`Failed to obtain the volume, error ${error}.`); 7016} 7017``` 7018 7019### getMinStreamVolume<sup>10+</sup> 7020 7021getMinStreamVolume(callback: AsyncCallback<number>): void 7022 7023Obtains the minimum volume of the application from the perspective of an audio stream. This API uses an asynchronous callback to return the result. 7024 7025**System capability**: SystemCapability.Multimedia.Audio.Renderer 7026 7027**Parameters** 7028 7029| Name | Type | Mandatory | Description | 7030| ------- | -----------| ------ | ------------------- | 7031|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.| 7032 7033**Example** 7034 7035```ts 7036import { BusinessError } from '@kit.BasicServicesKit'; 7037 7038audioRenderer.getMinStreamVolume((err: BusinessError, minVolume: number) => { 7039 if (err) { 7040 console.error(`getMinStreamVolume error: ${err}`); 7041 } else { 7042 console.info(`getMinStreamVolume Success! ${minVolume}`); 7043 } 7044}); 7045``` 7046### getMinStreamVolume<sup>10+</sup> 7047 7048getMinStreamVolume(): Promise<number> 7049 7050Obtains the minimum volume of the application from the perspective of an audio stream. This API uses a promise to return the result. 7051 7052**System capability**: SystemCapability.Multimedia.Audio.Renderer 7053 7054**Return value** 7055 7056| Type | Description | 7057| ------------------- | ----------------------------- | 7058| Promise<number>| Promise used to return the minimum volume, ranging from 0 to 1.| 7059 7060**Example** 7061 7062```ts 7063import { BusinessError } from '@kit.BasicServicesKit'; 7064 7065audioRenderer.getMinStreamVolume().then((value: number) => { 7066 console.info(`Get min stream volume Success! ${value}`); 7067}).catch((err: BusinessError) => { 7068 console.error(`Get min stream volume Fail: ${err}`); 7069}); 7070``` 7071 7072### getMinStreamVolumeSync<sup>10+</sup> 7073 7074getMinStreamVolumeSync(): number 7075 7076Obtains the minimum volume of the application from the perspective of an audio stream. This API returns the result synchronously. 7077 7078**System capability**: SystemCapability.Multimedia.Audio.Renderer 7079 7080**Return value** 7081 7082| Type | Description | 7083| ------------------- | ----------------------------- | 7084| number| Minimum volume, ranging from 0 to 1.| 7085 7086**Example** 7087 7088```ts 7089import { BusinessError } from '@kit.BasicServicesKit'; 7090 7091try { 7092 let value: number = audioRenderer.getMinStreamVolumeSync(); 7093 console.info(`Get min stream volume Success! ${value}`); 7094} catch (err) { 7095 let error = err as BusinessError; 7096 console.error(`Get min stream volume Fail: ${error}`); 7097} 7098``` 7099 7100### getMaxStreamVolume<sup>10+</sup> 7101 7102getMaxStreamVolume(callback: AsyncCallback<number>): void 7103 7104Obtains the maximum volume of the application from the perspective of an audio stream. This API uses an asynchronous callback to return the result. 7105 7106**System capability**: SystemCapability.Multimedia.Audio.Renderer 7107 7108**Parameters** 7109 7110| Name | Type | Mandatory | Description | 7111| ------- | -----------| ------ | ------------------- | 7112|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.| 7113 7114**Example** 7115 7116```ts 7117import { BusinessError } from '@kit.BasicServicesKit'; 7118 7119audioRenderer.getMaxStreamVolume((err: BusinessError, maxVolume: number) => { 7120 if (err) { 7121 console.error(`getMaxStreamVolume Fail: ${err}`); 7122 } else { 7123 console.info(`getMaxStreamVolume Success! ${maxVolume}`); 7124 } 7125}); 7126``` 7127### getMaxStreamVolume<sup>10+</sup> 7128 7129getMaxStreamVolume(): Promise<number> 7130 7131Obtains the maximum volume of the application from the perspective of an audio stream. This API uses a promise to return the result. 7132 7133**System capability**: SystemCapability.Multimedia.Audio.Renderer 7134 7135**Return value** 7136 7137| Type | Description | 7138| ------------------- | ----------------------------- | 7139| Promise<number>| Promise used to return the maximum volume, ranging from 0 to 1.| 7140 7141**Example** 7142 7143```ts 7144import { BusinessError } from '@kit.BasicServicesKit'; 7145 7146audioRenderer.getMaxStreamVolume().then((value: number) => { 7147 console.info(`Get max stream volume Success! ${value}`); 7148}).catch((err: BusinessError) => { 7149 console.error(`Get max stream volume Fail: ${err}`); 7150}); 7151``` 7152 7153### getMaxStreamVolumeSync<sup>10+</sup> 7154 7155getMaxStreamVolumeSync(): number 7156 7157Obtains the maximum volume of the application from the perspective of an audio stream. This API returns the result synchronously. 7158 7159**System capability**: SystemCapability.Multimedia.Audio.Renderer 7160 7161**Return value** 7162 7163| Type | Description | 7164| ------------------- | ----------------------------- | 7165| number| Maximum volume, ranging from 0 to 1.| 7166 7167**Example** 7168 7169```ts 7170import { BusinessError } from '@kit.BasicServicesKit'; 7171 7172try { 7173 let value: number = audioRenderer.getMaxStreamVolumeSync(); 7174 console.info(`Get max stream volume Success! ${value}`); 7175} catch (err) { 7176 let error = err as BusinessError; 7177 console.error(`Get max stream volume Fail: ${error}`); 7178} 7179``` 7180 7181### getUnderflowCount<sup>10+</sup> 7182 7183getUnderflowCount(callback: AsyncCallback<number>): void 7184 7185Obtains the number of underflow audio frames in the audio stream that is being played. This API uses an asynchronous callback to return the result. 7186 7187**System capability**: SystemCapability.Multimedia.Audio.Renderer 7188 7189**Parameters** 7190 7191| Name | Type | Mandatory | Description | 7192| ------- | -----------| ------ | ------------------- | 7193|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.| 7194 7195**Example** 7196 7197```ts 7198import { BusinessError } from '@kit.BasicServicesKit'; 7199 7200audioRenderer.getUnderflowCount((err: BusinessError, underflowCount: number) => { 7201 if (err) { 7202 console.error(`getUnderflowCount Fail: ${err}`); 7203 } else { 7204 console.info(`getUnderflowCount Success! ${underflowCount}`); 7205 } 7206}); 7207``` 7208### getUnderflowCount<sup>10+</sup> 7209 7210getUnderflowCount(): Promise<number> 7211 7212Obtains the number of underflow audio frames in the audio stream that is being played. This API uses a promise to return the result. 7213 7214**System capability**: SystemCapability.Multimedia.Audio.Renderer 7215 7216**Return value** 7217 7218| Type | Description | 7219| ------------------- | ----------------------------- | 7220| Promise<number>| Promise used to return the number of underflow audio frames.| 7221 7222**Example** 7223 7224```ts 7225import { BusinessError } from '@kit.BasicServicesKit'; 7226 7227audioRenderer.getUnderflowCount().then((value: number) => { 7228 console.info(`Get underflow count Success! ${value}`); 7229}).catch((err: BusinessError) => { 7230 console.error(`Get underflow count Fail: ${err}`); 7231}); 7232``` 7233 7234### getUnderflowCountSync<sup>10+</sup> 7235 7236getUnderflowCountSync(): number 7237 7238Obtains the number of underflow audio frames in the audio stream that is being played. This API returns the result synchronously. 7239 7240**System capability**: SystemCapability.Multimedia.Audio.Renderer 7241 7242**Return value** 7243 7244| Type | Description | 7245| ------------------- | ----------------------------- | 7246| number| Number of underflow audio frames.| 7247 7248**Example** 7249 7250```ts 7251import { BusinessError } from '@kit.BasicServicesKit'; 7252 7253try { 7254 let value: number = audioRenderer.getUnderflowCountSync(); 7255 console.info(`Get underflow count Success! ${value}`); 7256} catch (err) { 7257 let error = err as BusinessError; 7258 console.error(`Get underflow count Fail: ${error}`); 7259} 7260``` 7261 7262### getCurrentOutputDevices<sup>10+</sup> 7263 7264getCurrentOutputDevices(callback: AsyncCallback<AudioDeviceDescriptors>): void 7265 7266Obtains the output device descriptors of the audio streams. This API uses an asynchronous callback to return the result. 7267 7268**System capability**: SystemCapability.Multimedia.Audio.Device 7269 7270**Parameters** 7271 7272| Name | Type | Mandatory | Description | 7273| ------- | -----------| ------ | ------------------- | 7274|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.| 7275 7276**Example** 7277 7278```ts 7279import { BusinessError } from '@kit.BasicServicesKit'; 7280 7281audioRenderer.getCurrentOutputDevices((err: BusinessError, deviceInfo: audio.AudioDeviceDescriptors) => { 7282 if (err) { 7283 console.error(`getCurrentOutputDevices Fail: ${err}`); 7284 } else { 7285 for (let i = 0; i < deviceInfo.length; i++) { 7286 console.info(`DeviceInfo id: ${deviceInfo[i].id}`); 7287 console.info(`DeviceInfo type: ${deviceInfo[i].deviceType}`); 7288 console.info(`DeviceInfo role: ${deviceInfo[i].deviceRole}`); 7289 console.info(`DeviceInfo name: ${deviceInfo[i].name}`); 7290 console.info(`DeviceInfo address: ${deviceInfo[i].address}`); 7291 console.info(`DeviceInfo samplerate: ${deviceInfo[i].sampleRates[0]}`); 7292 console.info(`DeviceInfo channelcount: ${deviceInfo[i].channelCounts[0]}`); 7293 console.info(`DeviceInfo channelmask: ${deviceInfo[i].channelMasks[0]}`); 7294 } 7295 } 7296}); 7297``` 7298### getCurrentOutputDevices<sup>10+</sup> 7299 7300getCurrentOutputDevices(): Promise<AudioDeviceDescriptors> 7301 7302Obtains the output device descriptors of the audio streams. This API uses a promise to return the result. 7303 7304**System capability**: SystemCapability.Multimedia.Audio.Device 7305 7306**Return value** 7307 7308| Type | Description | 7309| ------------------- | ----------------------------- | 7310| Promise<[AudioDeviceDescriptors](#audiodevicedescriptors)>| Promise used to return the output device descriptors.| 7311 7312**Example** 7313 7314```ts 7315import { BusinessError } from '@kit.BasicServicesKit'; 7316 7317audioRenderer.getCurrentOutputDevices().then((deviceInfo: audio.AudioDeviceDescriptors) => { 7318 for (let i = 0; i < deviceInfo.length; i++) { 7319 console.info(`DeviceInfo id: ${deviceInfo[i].id}`); 7320 console.info(`DeviceInfo type: ${deviceInfo[i].deviceType}`); 7321 console.info(`DeviceInfo role: ${deviceInfo[i].deviceRole}`); 7322 console.info(`DeviceInfo name: ${deviceInfo[i].name}`); 7323 console.info(`DeviceInfo address: ${deviceInfo[i].address}`); 7324 console.info(`DeviceInfo samplerate: ${deviceInfo[i].sampleRates[0]}`); 7325 console.info(`DeviceInfo channelcount: ${deviceInfo[i].channelCounts[0]}`); 7326 console.info(`DeviceInfo channelmask: ${deviceInfo[i].channelMasks[0]}`); 7327 } 7328}).catch((err: BusinessError) => { 7329 console.error(`Get current output devices Fail: ${err}`); 7330}); 7331``` 7332 7333### getCurrentOutputDevicesSync<sup>10+</sup> 7334 7335getCurrentOutputDevicesSync(): AudioDeviceDescriptors 7336 7337Obtains the output device descriptors of the audio streams. This API returns the result synchronously. 7338 7339**System capability**: SystemCapability.Multimedia.Audio.Device 7340 7341**Return value** 7342 7343| Type | Description | 7344| ------------------- | ----------------------------- | 7345| [AudioDeviceDescriptors](#audiodevicedescriptors) | Output device descriptors.| 7346 7347**Example** 7348 7349```ts 7350import { BusinessError } from '@kit.BasicServicesKit'; 7351 7352try { 7353 let deviceInfo: audio.AudioDeviceDescriptors = audioRenderer.getCurrentOutputDevicesSync(); 7354 for (let i = 0; i < deviceInfo.length; i++) { 7355 console.info(`DeviceInfo id: ${deviceInfo[i].id}`); 7356 console.info(`DeviceInfo type: ${deviceInfo[i].deviceType}`); 7357 console.info(`DeviceInfo role: ${deviceInfo[i].deviceRole}`); 7358 console.info(`DeviceInfo name: ${deviceInfo[i].name}`); 7359 console.info(`DeviceInfo address: ${deviceInfo[i].address}`); 7360 console.info(`DeviceInfo samplerate: ${deviceInfo[i].sampleRates[0]}`); 7361 console.info(`DeviceInfo channelcount: ${deviceInfo[i].channelCounts[0]}`); 7362 console.info(`DeviceInfo channelmask: ${deviceInfo[i].channelMasks[0]}`); 7363 } 7364} catch (err) { 7365 let error = err as BusinessError; 7366 console.error(`Get current output devices Fail: ${error}`); 7367} 7368``` 7369### setChannelBlendMode<sup>11+</sup> 7370 7371setChannelBlendMode(mode: ChannelBlendMode): void 7372 7373Sets the audio channel blending mode. This API returns the result synchronously. 7374 7375**System capability**: SystemCapability.Multimedia.Audio.Renderer 7376 7377**Parameters** 7378 7379| Name | Type | Mandatory| Description | 7380| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 7381| mode | [ChannelBlendMode](#channelblendmode11) | Yes | Audio channel blending mode. | 7382 7383**Error codes** 7384 7385For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7386 7387| ID| Error Message| 7388| ------- | --------------------------------------------| 7389| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7390| 6800101 | Parameter verification failed. | 7391| 6800103 | Operation not permit at current state. | 7392 7393**Example** 7394 7395```ts 7396let mode = audio.ChannelBlendMode.MODE_DEFAULT; 7397 7398audioRenderer.setChannelBlendMode(mode); 7399console.info(`BlendMode: ${mode}`); 7400``` 7401### setVolumeWithRamp<sup>11+</sup> 7402 7403setVolumeWithRamp(volume: number, duration: number): void 7404 7405Sets a volume ramp. This API returns the result synchronously. 7406 7407**System capability**: SystemCapability.Multimedia.Audio.Renderer 7408 7409**Parameters** 7410 7411| Name | Type | Mandatory| Description | 7412| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 7413| volume | number | Yes | Target volume, within the range [0.0, 1.0]. | 7414| duration | number | Yes | Time range during which the ramp applies, in ms. | 7415 7416**Error codes** 7417 7418For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7419 7420| ID| Error Message| 7421| ------- | --------------------------------------------| 7422| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7423| 6800101 | Parameter verification failed. | 7424 7425**Example** 7426 7427```ts 7428let volume = 0.5; 7429let duration = 1000; 7430 7431audioRenderer.setVolumeWithRamp(volume, duration); 7432console.info(`setVolumeWithRamp: ${volume}`); 7433``` 7434 7435### setSilentModeAndMixWithOthers<sup>12+</sup> 7436 7437setSilentModeAndMixWithOthers(on: boolean): void 7438 7439Sets the silent mode in concurrent playback for the audio stream. 7440 7441If 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. 7442 7443**System capability**: SystemCapability.Multimedia.Audio.Renderer 7444 7445**Parameters** 7446 7447| Name| Type | Mandatory| Description | 7448| ------ | ---------------------------------------- | ---- |----------------------| 7449| 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.| 7450 7451**Example** 7452 7453```ts 7454audioRenderer.setSilentModeAndMixWithOthers(true); 7455``` 7456 7457### getSilentModeAndMixWithOthers<sup>12+</sup> 7458 7459getSilentModeAndMixWithOthers(): boolean 7460 7461Obtains the silent mode in concurrent playback for the audio stream. 7462 7463**System capability**: SystemCapability.Multimedia.Audio.Renderer 7464 7465**Return value** 7466 7467| Type | Description | 7468| ------------------------------------------------- |-----------| 7469| boolean | **true**: The silent mode in concurrent playback is enabled.<br>**false**: The silent mode in concurrent playback is disabled.| 7470 7471**Example** 7472 7473```ts 7474let on = audioRenderer.getSilentModeAndMixWithOthers(); 7475``` 7476 7477### setDefaultOutputDevice<sup>12+</sup> 7478 7479setDefaultOutputDevice(deviceType: DeviceType): Promise<void> 7480 7481Sets the default built-in audio output device. This API uses a promise to return the result. 7482 7483This 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. 7484 7485This 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. 7486 7487**System capability**: SystemCapability.Multimedia.Audio.Renderer 7488 7489**Parameters** 7490 7491| Name | Type | Mandatory | Description | 7492| ---------- |----------------| ------ |---------------------------------------------------------| 7493| deviceType | [DeviceType](#devicetype) | Yes | Device type.<br>The options are **EARPIECE**, **SPEAKER**, and **DEFAULT**.| 7494 7495**Return value** 7496 7497| Type | Description | 7498| ------------------- | ----------------------------- | 7499| Promise<void> | Promise that returns no value.| 7500 7501**Error codes** 7502 7503For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7504 7505| ID| Error Message| 7506| ------- | --------------------------------------------| 7507| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7508| 6800101 | Parameter verification failed. | 7509| 6800103 | Operation not permit at current state. | 7510 7511**Example** 7512 7513```ts 7514import { BusinessError } from '@kit.BasicServicesKit'; 7515 7516// This API can be called at any time after an **AudioRenderer** instance is created. 7517// 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. 7518// 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. 7519audioRenderer.setDefaultOutputDevice(audio.DeviceType.SPEAKER).then(() => { 7520 console.info('setDefaultOutputDevice Success!'); 7521}).catch((err: BusinessError) => { 7522 console.error(`setDefaultOutputDevice Fail: ${err}`); 7523}); 7524``` 7525 7526### on('audioInterrupt')<sup>9+</sup> 7527 7528on(type: 'audioInterrupt', callback: Callback\<InterruptEvent>): void 7529 7530Subscribes to the audio interruption event, which is triggered when the audio focus is changed. This API uses an asynchronous callback to return the result. 7531 7532The **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. 7533 7534After 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). 7535 7536**System capability**: SystemCapability.Multimedia.Audio.Interrupt 7537 7538**Parameters** 7539 7540| Name | Type | Mandatory| Description | 7541| -------- | -------------------------------------------- | ---- | ----------------------------------------------------------- | 7542| type | string | Yes | Event type. The value is fixed at **'audioInterrupt'**.| 7543| callback | Callback\<[InterruptEvent](#interruptevent9)\> | Yes | Callback used to return the audio interruption event received by the application when playback is interrupted.| 7544 7545**Error codes** 7546 7547For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7548 7549| ID| Error Message| 7550| ------- | --------------------------------------------| 7551| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7552| 6800101 | Parameter verification failed. | 7553 7554**Example** 7555 7556```ts 7557import { audio } from '@kit.AudioKit'; 7558 7559let isPlaying: boolean; // An identifier specifying whether rendering is in progress. 7560let isDucked: boolean; // An identifier specifying whether the audio volume is reduced. 7561onAudioInterrupt(); 7562 7563async function onAudioInterrupt(){ 7564 audioRenderer.on('audioInterrupt', (interruptEvent: audio.InterruptEvent) => { 7565 // When an audio interruption event occurs, the AudioRenderer receives the interruptEvent callback and performs processing based on the content in the callback. 7566 // 1. (Optional) The AudioRenderer reads the value of interruptEvent.forceType to see whether the system has forcibly performed the operation. 7567 // 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. 7568 // 2. (Mandatory) The AudioRenderer then reads the value of interruptEvent.hintType and performs corresponding processing. 7569 if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_FORCE) { 7570 // The audio focus event has been forcibly executed by the system. The application needs to update its status and displayed content. 7571 switch (interruptEvent.hintType) { 7572 case audio.InterruptHint.INTERRUPT_HINT_PAUSE: 7573 // 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. 7574 console.info('Force paused. Update playing status and stop writing'); 7575 isPlaying = false; // A simplified processing indicating several operations for switching the application to the paused state. 7576 break; 7577 case audio.InterruptHint.INTERRUPT_HINT_STOP: 7578 // The audio stream has been stopped and permanently loses the focus. The user must manually trigger the operation to resume rendering. 7579 console.info('Force stopped. Update playing status and stop writing'); 7580 isPlaying = false; // A simplified processing indicating several operations for switching the application to the paused state. 7581 break; 7582 case audio.InterruptHint.INTERRUPT_HINT_DUCK: 7583 // The audio stream is rendered at a reduced volume. 7584 console.info('Force ducked. Update volume status'); 7585 isDucked = true; // A simplified processing indicating several operations for updating the volume status. 7586 break; 7587 case audio.InterruptHint.INTERRUPT_HINT_UNDUCK: 7588 // The audio stream is rendered at the normal volume. 7589 console.info('Force ducked. Update volume status'); 7590 isDucked = false; // A simplified processing indicating several operations for updating the volume status. 7591 break; 7592 default: 7593 console.info('Invalid interruptEvent'); 7594 break; 7595 } 7596 } else if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_SHARE) { 7597 // 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. 7598 switch (interruptEvent.hintType) { 7599 case audio.InterruptHint.INTERRUPT_HINT_RESUME: 7600 // 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.) 7601 // 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. 7602 console.info('Resume force paused renderer or ignore'); 7603 // To continue rendering, the application must perform the required operations. 7604 break; 7605 default: 7606 console.info('Invalid interruptEvent'); 7607 break; 7608 } 7609 } 7610 }); 7611} 7612``` 7613 7614### on('markReach')<sup>8+</sup> 7615 7616on(type: 'markReach', frame: number, callback: Callback<number>): void 7617 7618Subscribes 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. 7619 7620For example, if **frame** is set to **100**, the callback is invoked when the number of rendered frames reaches the 100th frame. 7621 7622**System capability**: SystemCapability.Multimedia.Audio.Renderer 7623 7624**Parameters** 7625 7626| Name | Type | Mandatory| Description | 7627| :------- | :----------------------- | :--- | :---------------------------------------- | 7628| type | string | Yes | Event type. The value is fixed at **'markReach'**.| 7629| frame | number | Yes | Number of frames to trigger the event. The value must be greater than **0**. | 7630| callback | Callback\<number> | Yes | Callback used to return the value of the **frame** parameter.| 7631 7632**Example** 7633 7634```ts 7635audioRenderer.on('markReach', 1000, (position: number) => { 7636 if (position == 1000) { 7637 console.info('ON Triggered successfully'); 7638 } 7639}); 7640``` 7641 7642 7643### off('markReach')<sup>8+</sup> 7644 7645off(type: 'markReach'): void 7646 7647Unsubscribes from the mark reached event. 7648 7649**System capability**: SystemCapability.Multimedia.Audio.Renderer 7650 7651**Parameters** 7652 7653| Name| Type | Mandatory| Description | 7654| :----- | :----- | :--- | :------------------------------------------------ | 7655| type | string | Yes | Event type. The value is fixed at **'markReach'**.| 7656 7657**Example** 7658 7659```ts 7660audioRenderer.off('markReach'); 7661``` 7662 7663### on('periodReach')<sup>8+</sup> 7664 7665on(type: 'periodReach', frame: number, callback: Callback<number>): void 7666 7667Subscribes 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. 7668 7669For 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. 7670 7671**System capability**: SystemCapability.Multimedia.Audio.Renderer 7672 7673**Parameters** 7674 7675| Name | Type | Mandatory| Description | 7676| :------- | :----------------------- | :--- | :------------------------------------------ | 7677| type | string | Yes | Event type. The value is fixed at **'periodReach'**.| 7678| frame | number | Yes | Number of frames to trigger the event. The value must be greater than **0**. | 7679| callback | Callback\<number> | Yes | Callback used to return the value of the **frame** parameter.| 7680 7681**Example** 7682 7683```ts 7684audioRenderer.on('periodReach', 1000, (position: number) => { 7685 if (position == 1000) { 7686 console.info('ON Triggered successfully'); 7687 } 7688}); 7689``` 7690 7691### off('periodReach')<sup>8+</sup> 7692 7693off(type: 'periodReach'): void 7694 7695Unsubscribes from the period reached event. 7696 7697**System capability**: SystemCapability.Multimedia.Audio.Renderer 7698 7699**Parameters** 7700 7701| Name| Type | Mandatory| Description | 7702| :----- | :----- | :--- | :-------------------------------------------------- | 7703| type | string | Yes | Event type. The value is fixed at **'periodReach'**.| 7704 7705**Example** 7706 7707```ts 7708audioRenderer.off('periodReach'); 7709``` 7710 7711### on('stateChange')<sup>8+</sup> 7712 7713on(type: 'stateChange', callback: Callback<AudioState\>): void 7714 7715Subscribes 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. 7716 7717**System capability**: SystemCapability.Multimedia.Audio.Renderer 7718 7719**Parameters** 7720 7721| Name | Type | Mandatory| Description | 7722| :------- | :------------------------- | :--- | :------------------------------------------ | 7723| type | string | Yes | Event type. The value is fixed at **'stateChange'**.| 7724| callback | Callback\<[AudioState](#audiostate8)> | Yes | Callback used to return the audio status.| 7725 7726**Example** 7727 7728```ts 7729audioRenderer.on('stateChange', (state: audio.AudioState) => { 7730 if (state == 1) { 7731 console.info('audio renderer state is: STATE_PREPARED'); 7732 } 7733 if (state == 2) { 7734 console.info('audio renderer state is: STATE_RUNNING'); 7735 } 7736}); 7737``` 7738 7739### on('outputDeviceChange')<sup>10+</sup> 7740 7741on(type: 'outputDeviceChange', callback: Callback\<AudioDeviceDescriptors>): void 7742 7743Subscribes 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. 7744 7745**System capability**: SystemCapability.Multimedia.Audio.Device 7746 7747**Parameters** 7748 7749| Name | Type | Mandatory| Description | 7750| :------- | :------------------------- | :--- | :------------------------------------------ | 7751| type | string | Yes | Event type. The value is fixed at **'outputDeviceChange'**.| 7752| callback | Callback\<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Yes | Callback used to return the output device descriptor of the current audio stream.| 7753 7754**Error codes** 7755 7756For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7757 7758| ID| Error Message| 7759| ------- | --------------------------------------------| 7760| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7761| 6800101 | Parameter verification failed. | 7762 7763**Example** 7764 7765```ts 7766audioRenderer.on('outputDeviceChange', (deviceInfo: audio.AudioDeviceDescriptors) => { 7767 console.info(`DeviceInfo id: ${deviceInfo[0].id}`); 7768 console.info(`DeviceInfo name: ${deviceInfo[0].name}`); 7769 console.info(`DeviceInfo address: ${deviceInfo[0].address}`); 7770}); 7771``` 7772 7773### off('outputDeviceChange')<sup>10+</sup> 7774 7775off(type: 'outputDeviceChange', callback?: Callback\<AudioDeviceDescriptors>): void 7776 7777Unsubscribes from the audio output device change event. This API uses an asynchronous callback to return the result. 7778 7779**System capability**: SystemCapability.Multimedia.Audio.Device 7780 7781**Parameters** 7782 7783| Name | Type | Mandatory| Description | 7784| :------- | :------------------------- | :--- | :------------------------------------------ | 7785| type | string | Yes | Event type. The value is fixed at **'outputDeviceChange'**.| 7786| callback | Callback\<[AudioDeviceDescriptors](#audiodevicedescriptors)> | No | Callback used to return the output device descriptor of the current audio stream.| 7787 7788**Error codes** 7789 7790For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7791 7792| ID| Error Message| 7793| ------- | --------------------------------------------| 7794| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7795| 6800101 | Parameter verification failed. | 7796 7797**Example** 7798 7799```ts 7800// Cancel all subscriptions to the event. 7801audioRenderer.off('outputDeviceChange'); 7802 7803// 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. 7804let outputDeviceChangeCallback = (deviceInfo: audio.AudioDeviceDescriptors) => { 7805 console.info(`DeviceInfo id: ${deviceInfo[0].id}`); 7806 console.info(`DeviceInfo name: ${deviceInfo[0].name}`); 7807 console.info(`DeviceInfo address: ${deviceInfo[0].address}`); 7808}; 7809 7810audioRenderer.on('outputDeviceChange', outputDeviceChangeCallback); 7811 7812audioRenderer.off('outputDeviceChange', outputDeviceChangeCallback); 7813``` 7814 7815### on('outputDeviceChangeWithInfo')<sup>11+</sup> 7816 7817on(type: 'outputDeviceChangeWithInfo', callback: Callback\<AudioStreamDeviceChangeInfo>): void 7818 7819Subscribes 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. 7820 7821**System capability**: SystemCapability.Multimedia.Audio.Device 7822 7823**Parameters** 7824 7825| Name | Type | Mandatory| Description | 7826| :------- |:-------------------------------------------------------------------------| :--- |:--------------------------------------------| 7827| type | string | Yes | Event type. The value is fixed at **'outputDeviceChangeWithInfo'**.| 7828| callback | Callback\<[AudioStreamDeviceChangeInfo](#audiostreamdevicechangeinfo11)> | Yes | Callback used to return the output device descriptor of the current audio stream and the change reason.| 7829 7830**Error codes** 7831 7832For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7833 7834| ID| Error Message| 7835| ------- | --------------------------------------------| 7836| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7837| 6800101 | Parameter verification failed. | 7838 7839**Example** 7840 7841```ts 7842audioRenderer.on('outputDeviceChangeWithInfo', (deviceChangeInfo: audio.AudioStreamDeviceChangeInfo) => { 7843 console.info(`DeviceInfo id: ${deviceChangeInfo.devices[0].id}`); 7844 console.info(`DeviceInfo name: ${deviceChangeInfo.devices[0].name}`); 7845 console.info(`DeviceInfo address: ${deviceChangeInfo.devices[0].address}`); 7846 console.info(`Device change reason: ${deviceChangeInfo.changeReason}`); 7847}); 7848``` 7849 7850### off('outputDeviceChangeWithInfo')<sup>11+</sup> 7851 7852off(type: 'outputDeviceChangeWithInfo', callback?: Callback\<AudioStreamDeviceChangeInfo>): void 7853 7854Unsubscribes from audio output device changes and reasons. This API uses an asynchronous callback to return the result. 7855 7856**System capability**: SystemCapability.Multimedia.Audio.Device 7857 7858**Parameters** 7859 7860| Name | Type | Mandatory| Description | 7861| :------- |:-------------------------------------------------------------------------| :--- |:--------------------------------------------| 7862| type | string | Yes | Event type. The value is fixed at **'outputDeviceChangeWithInfo'**.| 7863| callback | Callback\<[AudioStreamDeviceChangeInfo](#audiostreamdevicechangeinfo11)> | No | Callback used to return the output device descriptor of the current audio stream and the change reason.| 7864 7865**Error codes** 7866 7867For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7868 7869| ID| Error Message| 7870| ------- | --------------------------------------------| 7871| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7872| 6800101 | Parameter verification failed. | 7873 7874**Example** 7875 7876```ts 7877// Cancel all subscriptions to the event. 7878audioRenderer.off('outputDeviceChangeWithInfo'); 7879 7880// 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. 7881let outputDeviceChangeWithInfoCallback = (deviceChangeInfo: audio.AudioStreamDeviceChangeInfo) => { 7882 console.info(`DeviceInfo id: ${deviceChangeInfo.devices[0].id}`); 7883 console.info(`DeviceInfo name: ${deviceChangeInfo.devices[0].name}`); 7884 console.info(`DeviceInfo address: ${deviceChangeInfo.devices[0].address}`); 7885 console.info(`Device change reason: ${deviceChangeInfo.changeReason}`); 7886}; 7887 7888audioRenderer.on('outputDeviceChangeWithInfo', outputDeviceChangeWithInfoCallback); 7889 7890audioRenderer.off('outputDeviceChangeWithInfo', outputDeviceChangeWithInfoCallback); 7891``` 7892 7893### on('writeData')<sup>11+</sup> 7894 7895on(type: 'writeData', callback: AudioRendererWriteDataCallback): void 7896 7897Subscribes 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. 7898 7899The callback function is used only to write audio data. Do not call AudioRenderer APIs in it. 7900 7901**System capability**: SystemCapability.Multimedia.Audio.Renderer 7902 7903**Parameters** 7904 7905| Name | Type | Mandatory| Description | 7906| :------- |:--------------------------------| :--- |:--------------------------------------| 7907| type | string | Yes | Event type. The value is fixed at **'writeData'**.| 7908| 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). | 7909 7910**Error codes** 7911 7912For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7913 7914| ID| Error Message| 7915| ------- | --------------------------------------------| 7916| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7917| 6800101 | Parameter verification failed. | 7918 7919**Example** 7920 7921```ts 7922import { BusinessError } from '@kit.BasicServicesKit'; 7923import {fileIo as fs} from '@kit.CoreFileKit'; 7924 7925class Options { 7926 offset?: number; 7927 length?: number; 7928} 7929 7930let bufferSize: number = 0; 7931let path = getContext().cacheDir; 7932// Ensure that the resource exists in the path. 7933let filePath = path + '/StarWars10s-2C-48000-4SW.wav'; 7934let file: fs.File = fs.openSync(filePath, fs.OpenMode.READ_ONLY); 7935let writeDataCallback = (buffer: ArrayBuffer) => { 7936 let options: Options = { 7937 offset: bufferSize, 7938 length: buffer.byteLength 7939 }; 7940 7941 try { 7942 fs.readSync(file.fd, buffer, options); 7943 bufferSize += buffer.byteLength; 7944 // This API does not return a callback result in API version 11, but does so in API version 12 and later versions. 7945 return audio.AudioDataCallbackResult.VALID; 7946 } catch (error) { 7947 console.error('Error reading file:', error); 7948 // This API does not return a callback result in API version 11, but does so in API version 12 and later versions. 7949 return audio.AudioDataCallbackResult.INVALID; 7950 } 7951}; 7952 7953audioRenderer.on('writeData', writeDataCallback); 7954audioRenderer.start().then(() => { 7955 console.info('Renderer started'); 7956}).catch((err: BusinessError) => { 7957 console.error(`ERROR: ${err}`); 7958}); 7959``` 7960 7961### off('writeData')<sup>11+</sup> 7962 7963off(type: 'writeData', callback?: AudioRendererWriteDataCallback): void 7964 7965Unsubscribes from the audio data write event. This API uses an asynchronous callback to return the result. 7966 7967**System capability**: SystemCapability.Multimedia.Audio.Renderer 7968 7969**Parameters** 7970 7971| Name | Type | Mandatory| Description | 7972| :------- |:--------------------------------| :--- |:--------------------------------------| 7973| type | string | Yes | Event type. The value is fixed at **'writeData'**.| 7974| 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).| 7975 7976**Error codes** 7977 7978For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7979 7980| ID| Error Message| 7981| ------- | --------------------------------------------| 7982| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7983| 6800101 | Parameter verification failed. | 7984 7985**Example** 7986 7987```ts 7988// Cancel all subscriptions to the event. 7989audioRenderer.off('writeData'); 7990 7991// 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. 7992let writeDataCallback = (data: ArrayBuffer) => { 7993 console.info(`write data: ${data}`); 7994}; 7995 7996audioRenderer.on('writeData', writeDataCallback); 7997 7998audioRenderer.off('writeData', writeDataCallback); 7999``` 8000 8001## AudioCapturer<sup>8+</sup> 8002 8003Provides APIs for audio capture. Before calling any API in **AudioCapturer**, you must use [createAudioCapturer](#audiocreateaudiocapturer8) to create an **AudioCapturer** instance. 8004 8005### Attributes 8006 8007**System capability**: SystemCapability.Multimedia.Audio.Capturer 8008 8009| Name | Type | Readable| Writable| Description | 8010| :---- | :------------------------- | :--- | :--- | :--------------- | 8011| state<sup>8+</sup> | [AudioState](#audiostate8) | Yes| No | Audio capturer state.| 8012 8013**Example** 8014 8015```ts 8016import { audio } from '@kit.AudioKit'; 8017 8018let state: audio.AudioState = audioCapturer.state; 8019``` 8020 8021### getCapturerInfo<sup>8+</sup> 8022 8023getCapturerInfo(callback: AsyncCallback<AudioCapturerInfo\>): void 8024 8025Obtains the capturer information of this **AudioCapturer** instance. This API uses an asynchronous callback to return the result. 8026 8027**System capability**: SystemCapability.Multimedia.Audio.Capturer 8028 8029**Parameters** 8030 8031| Name | Type | Mandatory| Description | 8032| :------- | :-------------------------------- | :--- | :----------------------------------- | 8033| 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.| 8034 8035**Example** 8036 8037```ts 8038import { BusinessError } from '@kit.BasicServicesKit'; 8039 8040audioCapturer.getCapturerInfo((err: BusinessError, capturerInfo: audio.AudioCapturerInfo) => { 8041 if (err) { 8042 console.error('Failed to get capture info'); 8043 } else { 8044 console.info('Capturer getCapturerInfo:'); 8045 console.info(`Capturer source: ${capturerInfo.source}`); 8046 console.info(`Capturer flags: ${capturerInfo.capturerFlags}`); 8047 } 8048}); 8049``` 8050 8051 8052### getCapturerInfo<sup>8+</sup> 8053 8054getCapturerInfo(): Promise<AudioCapturerInfo\> 8055 8056Obtains the capturer information of this **AudioCapturer** instance. This API uses a promise to return the result. 8057 8058**System capability**: SystemCapability.Multimedia.Audio.Capturer 8059 8060**Return value** 8061 8062| Type | Description | 8063| :------------------------------------------------ | :---------------------------------- | 8064| Promise<[AudioCapturerInfo](#audiocapturerinfo8)\> | Promise used to return capturer information.| 8065 8066**Example** 8067 8068```ts 8069import { BusinessError } from '@kit.BasicServicesKit'; 8070 8071audioCapturer.getCapturerInfo().then((audioParamsGet: audio.AudioCapturerInfo) => { 8072 if (audioParamsGet != undefined) { 8073 console.info('AudioFrameworkRecLog: Capturer CapturerInfo:'); 8074 console.info(`AudioFrameworkRecLog: Capturer SourceType: ${audioParamsGet.source}`); 8075 console.info(`AudioFrameworkRecLog: Capturer capturerFlags: ${audioParamsGet.capturerFlags}`); 8076 } else { 8077 console.info(`AudioFrameworkRecLog: audioParamsGet is : ${audioParamsGet}`); 8078 console.info('AudioFrameworkRecLog: audioParams getCapturerInfo are incorrect'); 8079 } 8080}).catch((err: BusinessError) => { 8081 console.error(`AudioFrameworkRecLog: CapturerInfo :ERROR: ${err}`); 8082}) 8083``` 8084 8085### getCapturerInfoSync<sup>10+</sup> 8086 8087getCapturerInfoSync(): AudioCapturerInfo 8088 8089Obtains the capturer information of this **AudioCapturer** instance. This API returns the result synchronously. 8090 8091**System capability**: SystemCapability.Multimedia.Audio.Capturer 8092 8093**Return value** 8094 8095| Type | Description | 8096| :------------------------------------------------ | :---------------------------------- | 8097| [AudioCapturerInfo](#audiocapturerinfo8) | Capturer information.| 8098 8099**Example** 8100 8101```ts 8102import { BusinessError } from '@kit.BasicServicesKit'; 8103 8104try { 8105 let audioParamsGet: audio.AudioCapturerInfo = audioCapturer.getCapturerInfoSync(); 8106 console.info(`AudioFrameworkRecLog: Capturer SourceType: ${audioParamsGet.source}`); 8107 console.info(`AudioFrameworkRecLog: Capturer capturerFlags: ${audioParamsGet.capturerFlags}`); 8108} catch (err) { 8109 let error = err as BusinessError; 8110 console.error(`AudioFrameworkRecLog: CapturerInfo :ERROR: ${error}`); 8111} 8112``` 8113 8114### getStreamInfo<sup>8+</sup> 8115 8116getStreamInfo(callback: AsyncCallback<AudioStreamInfo\>): void 8117 8118Obtains the stream information of this **AudioCapturer** instance. This API uses an asynchronous callback to return the result. 8119 8120**System capability**: SystemCapability.Multimedia.Audio.Capturer 8121 8122**Parameters** 8123 8124| Name | Type | Mandatory| Description | 8125| :------- | :--------------------------------------------------- | :--- | :------------------------------- | 8126| 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.| 8127 8128**Example** 8129 8130```ts 8131import { BusinessError } from '@kit.BasicServicesKit'; 8132 8133audioCapturer.getStreamInfo((err: BusinessError, streamInfo: audio.AudioStreamInfo) => { 8134 if (err) { 8135 console.error('Failed to get stream info'); 8136 } else { 8137 console.info('Capturer GetStreamInfo:'); 8138 console.info(`Capturer sampling rate: ${streamInfo.samplingRate}`); 8139 console.info(`Capturer channel: ${streamInfo.channels}`); 8140 console.info(`Capturer format: ${streamInfo.sampleFormat}`); 8141 console.info(`Capturer encoding type: ${streamInfo.encodingType}`); 8142 } 8143}); 8144``` 8145 8146### getStreamInfo<sup>8+</sup> 8147 8148getStreamInfo(): Promise<AudioStreamInfo\> 8149 8150Obtains the stream information of this **AudioCapturer** instance. This API uses a promise to return the result. 8151 8152**System capability**: SystemCapability.Multimedia.Audio.Capturer 8153 8154**Return value** 8155 8156| Type | Description | 8157| :--------------------------------------------- | :------------------------------ | 8158| Promise<[AudioStreamInfo](#audiostreaminfo8)\> | Promise used to return the stream information.| 8159 8160**Example** 8161 8162```ts 8163import { BusinessError } from '@kit.BasicServicesKit'; 8164 8165audioCapturer.getStreamInfo().then((audioParamsGet: audio.AudioStreamInfo) => { 8166 console.info('getStreamInfo:'); 8167 console.info(`sampleFormat: ${audioParamsGet.sampleFormat}`); 8168 console.info(`samplingRate: ${audioParamsGet.samplingRate}`); 8169 console.info(`channels: ${audioParamsGet.channels}`); 8170 console.info(`encodingType: ${audioParamsGet.encodingType}`); 8171}).catch((err: BusinessError) => { 8172 console.error(`getStreamInfo :ERROR: ${err}`); 8173}); 8174``` 8175 8176### getStreamInfoSync<sup>10+</sup> 8177 8178getStreamInfoSync(): AudioStreamInfo 8179 8180Obtains the stream information of this **AudioCapturer** instance. This API returns the result synchronously. 8181 8182**System capability**: SystemCapability.Multimedia.Audio.Capturer 8183 8184**Return value** 8185 8186| Type | Description | 8187| :--------------------------------------------- | :------------------------------ | 8188| [AudioStreamInfo](#audiostreaminfo8) | Stream information.| 8189 8190**Example** 8191 8192```ts 8193import { BusinessError } from '@kit.BasicServicesKit'; 8194 8195try { 8196 let audioParamsGet: audio.AudioStreamInfo = audioCapturer.getStreamInfoSync(); 8197 console.info(`sampleFormat: ${audioParamsGet.sampleFormat}`); 8198 console.info(`samplingRate: ${audioParamsGet.samplingRate}`); 8199 console.info(`channels: ${audioParamsGet.channels}`); 8200 console.info(`encodingType: ${audioParamsGet.encodingType}`); 8201} catch (err) { 8202 let error = err as BusinessError; 8203 console.error(`getStreamInfo :ERROR: ${error}`); 8204} 8205``` 8206 8207### getAudioStreamId<sup>9+</sup> 8208 8209getAudioStreamId(callback: AsyncCallback<number\>): void 8210 8211Obtains the stream ID of this **AudioCapturer** instance. This API uses an asynchronous callback to return the result. 8212 8213**System capability**: SystemCapability.Multimedia.Audio.Capturer 8214 8215**Parameters** 8216 8217| Name | Type | Mandatory| Description | 8218| :------- | :--------------------------------------------------- | :--- | :------------------- | 8219| 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.| 8220 8221**Example** 8222 8223```ts 8224import { BusinessError } from '@kit.BasicServicesKit'; 8225 8226audioCapturer.getAudioStreamId((err: BusinessError, streamId: number) => { 8227 console.info(`audioCapturer GetStreamId: ${streamId}`); 8228}); 8229``` 8230 8231### getAudioStreamId<sup>9+</sup> 8232 8233getAudioStreamId(): Promise<number\> 8234 8235Obtains the stream ID of this **AudioCapturer** instance. This API uses a promise to return the result. 8236 8237**System capability**: SystemCapability.Multimedia.Audio.Capturer 8238 8239**Return value** 8240 8241| Type | Description | 8242| :----------------| :--------------------- | 8243| Promise<number\> | Promise used to return the stream ID.| 8244 8245**Example** 8246 8247```ts 8248import { BusinessError } from '@kit.BasicServicesKit'; 8249 8250audioCapturer.getAudioStreamId().then((streamId: number) => { 8251 console.info(`audioCapturer getAudioStreamId: ${streamId}`); 8252}).catch((err: BusinessError) => { 8253 console.error(`ERROR: ${err}`); 8254}); 8255``` 8256 8257### getAudioStreamIdSync<sup>10+</sup> 8258 8259getAudioStreamIdSync(): number 8260 8261Obtains the stream ID of this **AudioCapturer** instance. This API returns the result synchronously. 8262 8263**System capability**: SystemCapability.Multimedia.Audio.Capturer 8264 8265**Return value** 8266 8267| Type | Description | 8268| :----------------| :--------------------- | 8269| number | Stream ID.| 8270 8271**Example** 8272 8273```ts 8274import { BusinessError } from '@kit.BasicServicesKit'; 8275 8276try { 8277 let streamId: number = audioCapturer.getAudioStreamIdSync(); 8278 console.info(`audioCapturer getAudioStreamIdSync: ${streamId}`); 8279} catch (err) { 8280 let error = err as BusinessError; 8281 console.error(`ERROR: ${error}`); 8282} 8283``` 8284 8285### start<sup>8+</sup> 8286 8287start(callback: AsyncCallback<void\>): void 8288 8289Starts capturing. This API uses an asynchronous callback to return the result. 8290 8291**System capability**: SystemCapability.Multimedia.Audio.Capturer 8292 8293**Parameters** 8294 8295| Name | Type | Mandatory| Description | 8296| :------- | :------------------- | :--- | :----------------------------- | 8297| 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.| 8298 8299**Example** 8300 8301```ts 8302import { BusinessError } from '@kit.BasicServicesKit'; 8303 8304audioCapturer.start((err: BusinessError) => { 8305 if (err) { 8306 console.error('Capturer start failed.'); 8307 } else { 8308 console.info('Capturer start success.'); 8309 } 8310}); 8311``` 8312 8313 8314### start<sup>8+</sup> 8315 8316start(): Promise<void\> 8317 8318Starts capturing. This API uses a promise to return the result. 8319 8320**System capability**: SystemCapability.Multimedia.Audio.Capturer 8321 8322**Return value** 8323 8324| Type | Description | 8325| :------------- | :---------------------------- | 8326| 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.| 8327 8328**Example** 8329 8330```ts 8331import { BusinessError } from '@kit.BasicServicesKit'; 8332 8333audioCapturer.start().then(() => { 8334 console.info('AudioFrameworkRecLog: ---------START---------'); 8335 console.info('AudioFrameworkRecLog: Capturer started: SUCCESS'); 8336 console.info(`AudioFrameworkRecLog: AudioCapturer: STATE: ${audioCapturer.state}`); 8337 console.info('AudioFrameworkRecLog: Capturer started: SUCCESS'); 8338 if ((audioCapturer.state == audio.AudioState.STATE_RUNNING)) { 8339 console.info('AudioFrameworkRecLog: AudioCapturer is in Running State'); 8340 } 8341}).catch((err: BusinessError) => { 8342 console.error(`AudioFrameworkRecLog: Capturer start :ERROR : ${err}`); 8343}); 8344``` 8345 8346### stop<sup>8+</sup> 8347 8348stop(callback: AsyncCallback<void\>): void 8349 8350Stops capturing. This API uses an asynchronous callback to return the result. 8351 8352**System capability**: SystemCapability.Multimedia.Audio.Capturer 8353 8354**Parameters** 8355 8356| Name | Type | Mandatory| Description | 8357| :------- | :------------------- | :--- | :----------------------------- | 8358| callback | AsyncCallback<void\> | Yes | Callback used to return the result. If the vibration stops, **err** is **undefined**; otherwise, **err** is an error object.| 8359 8360**Example** 8361 8362```ts 8363import { BusinessError } from '@kit.BasicServicesKit'; 8364 8365audioCapturer.stop((err: BusinessError) => { 8366 if (err) { 8367 console.error('Capturer stop failed'); 8368 } else { 8369 console.info('Capturer stopped.'); 8370 } 8371}); 8372``` 8373 8374 8375### stop<sup>8+</sup> 8376 8377stop(): Promise<void\> 8378 8379Stops capturing. This API uses a promise to return the result. 8380 8381**System capability**: SystemCapability.Multimedia.Audio.Capturer 8382 8383**Return value** 8384 8385| Type | Description | 8386| :------------- | :---------------------------- | 8387| Promise<void\> | Promise that returns no value.| 8388 8389**Example** 8390 8391```ts 8392import { BusinessError } from '@kit.BasicServicesKit'; 8393 8394audioCapturer.stop().then(() => { 8395 console.info('AudioFrameworkRecLog: ---------STOP RECORD---------'); 8396 console.info('AudioFrameworkRecLog: Capturer stopped: SUCCESS'); 8397 if ((audioCapturer.state == audio.AudioState.STATE_STOPPED)){ 8398 console.info('AudioFrameworkRecLog: State is Stopped:'); 8399 } 8400}).catch((err: BusinessError) => { 8401 console.error(`AudioFrameworkRecLog: Capturer stop: ERROR: ${err}`); 8402}); 8403``` 8404 8405### release<sup>8+</sup> 8406 8407release(callback: AsyncCallback<void\>): void 8408 8409Releases this **AudioCapturer** instance. This API uses an asynchronous callback to return the result. 8410 8411**System capability**: SystemCapability.Multimedia.Audio.Capturer 8412 8413**Parameters** 8414 8415| Name | Type | Mandatory| Description | 8416| :------- | :------------------- | :--- | :---------------------------------- | 8417| callback | AsyncCallback<void\> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 8418 8419**Example** 8420 8421```ts 8422import { BusinessError } from '@kit.BasicServicesKit'; 8423 8424audioCapturer.release((err: BusinessError) => { 8425 if (err) { 8426 console.error('capturer release failed'); 8427 } else { 8428 console.info('capturer released.'); 8429 } 8430}); 8431``` 8432 8433 8434### release<sup>8+</sup> 8435 8436release(): Promise<void\> 8437 8438Releases this **AudioCapturer** instance. This API uses a promise to return the result. 8439 8440**System capability**: SystemCapability.Multimedia.Audio.Capturer 8441 8442**Return value** 8443 8444| Type | Description | 8445| :------------- | :---------------------------- | 8446| Promise<void\> | Promise that returns no value.| 8447 8448**Example** 8449 8450```ts 8451import { BusinessError } from '@kit.BasicServicesKit'; 8452 8453audioCapturer.release().then(() => { 8454 console.info('AudioFrameworkRecLog: ---------RELEASE RECORD---------'); 8455 console.info('AudioFrameworkRecLog: Capturer release : SUCCESS'); 8456 console.info(`AudioFrameworkRecLog: AudioCapturer : STATE : ${audioCapturer.state}`); 8457}).catch((err: BusinessError) => { 8458 console.error(`AudioFrameworkRecLog: Capturer stop: ERROR: ${err}`); 8459}); 8460``` 8461 8462### read<sup>8+(deprecated)</sup> 8463 8464read(size: number, isBlockingRead: boolean, callback: AsyncCallback<ArrayBuffer\>): void 8465 8466Reads the buffer. This API uses an asynchronous callback to return the result. 8467 8468> **NOTE** 8469> 8470> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [on('readData')](#onreaddata11) in **AudioCapturer**. 8471 8472**System capability**: SystemCapability.Multimedia.Audio.Capturer 8473 8474**Parameters** 8475 8476| Name | Type | Mandatory| Description | 8477| :------------- | :-------------------------- | :--- | :------------------------------- | 8478| size | number | Yes | Number of bytes to read. | 8479| isBlockingRead | boolean | Yes | Whether to block the read operation. The value **true** means to block the read operation, and **false** means the opposite. | 8480| 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.| 8481 8482**Example** 8483 8484```ts 8485import { BusinessError } from '@kit.BasicServicesKit'; 8486 8487let bufferSize: number = 0; 8488 8489audioCapturer.getBufferSize().then((data: number) => { 8490 console.info(`AudioFrameworkRecLog: getBufferSize: SUCCESS ${data}`); 8491 bufferSize = data; 8492}).catch((err: BusinessError) => { 8493 console.error(`AudioFrameworkRecLog: getBufferSize: ERROR: ${err}`); 8494}); 8495 8496audioCapturer.read(bufferSize, true, (err: BusinessError, buffer: ArrayBuffer) => { 8497 if (!err) { 8498 console.info('Success in reading the buffer data'); 8499 } 8500}); 8501``` 8502 8503### read<sup>8+(deprecated)</sup> 8504 8505read(size: number, isBlockingRead: boolean): Promise<ArrayBuffer\> 8506 8507Reads the buffer. This API uses a promise to return the result. 8508 8509> **NOTE** 8510> 8511> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [on('readData')](#onreaddata11) in **AudioCapturer**. 8512 8513**System capability**: SystemCapability.Multimedia.Audio.Capturer 8514 8515**Parameters** 8516 8517| Name | Type | Mandatory| Description | 8518| :------------- | :------ | :--- | :--------------- | 8519| size | number | Yes | Number of bytes to read. | 8520| isBlockingRead | boolean | Yes | Whether to block the read operation. The value **true** means to block the read operation, and **false** means the opposite.| 8521 8522**Return value** 8523 8524| Type | Description | 8525| :-------------------- | :----------------------------------------------------- | 8526| Promise<ArrayBuffer\> | Promise used to return the data read from the buffer.| 8527 8528**Example** 8529 8530```ts 8531import { BusinessError } from '@kit.BasicServicesKit'; 8532 8533let bufferSize: number = 0; 8534 8535audioCapturer.getBufferSize().then((data: number) => { 8536 console.info(`AudioFrameworkRecLog: getBufferSize: SUCCESS ${data}`); 8537 bufferSize = data; 8538}).catch((err: BusinessError) => { 8539 console.error(`AudioFrameworkRecLog: getBufferSize: ERROR ${err}`); 8540}); 8541console.info(`Buffer size: ${bufferSize}`); 8542 8543audioCapturer.read(bufferSize, true).then((buffer: ArrayBuffer) => { 8544 console.info('buffer read successfully'); 8545}).catch((err: BusinessError) => { 8546 console.error(`ERROR : ${err}`); 8547}); 8548``` 8549 8550### getAudioTime<sup>8+</sup> 8551 8552getAudioTime(callback: AsyncCallback<number\>): void 8553 8554Obtains 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. 8555 8556**System capability**: SystemCapability.Multimedia.Audio.Capturer 8557 8558**Parameters** 8559 8560| Name | Type | Mandatory| Description | 8561| :------- | :--------------------- | :--- | :----------------------------- | 8562| 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.| 8563 8564**Example** 8565 8566```ts 8567import { BusinessError } from '@kit.BasicServicesKit'; 8568 8569audioCapturer.getAudioTime((err: BusinessError, timestamp: number) => { 8570 console.info(`Current timestamp: ${timestamp}`); 8571}); 8572``` 8573 8574### getAudioTime<sup>8+</sup> 8575 8576getAudioTime(): Promise<number\> 8577 8578Obtains 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. 8579 8580**System capability**: SystemCapability.Multimedia.Audio.Capturer 8581 8582**Return value** 8583 8584| Type | Description | 8585| :--------------- | :---------------------------- | 8586| Promise<number\> | Promise used to return the number of nanoseconds elapsed from the Unix epoch.| 8587 8588**Example** 8589 8590```ts 8591import { BusinessError } from '@kit.BasicServicesKit'; 8592 8593audioCapturer.getAudioTime().then((audioTime: number) => { 8594 console.info(`AudioFrameworkRecLog: AudioCapturer getAudioTime : Success ${audioTime}`); 8595}).catch((err: BusinessError) => { 8596 console.error(`AudioFrameworkRecLog: AudioCapturer Created : ERROR : ${err}`); 8597}); 8598``` 8599 8600### getAudioTimeSync<sup>10+</sup> 8601 8602getAudioTimeSync(): number 8603 8604Obtains the timestamp of the current recording position, measured in nanoseconds from the Unix epoch (January 1, 1970). This API returns the result synchronously: 8605 8606**System capability**: SystemCapability.Multimedia.Audio.Capturer 8607 8608**Return value** 8609 8610| Type | Description | 8611| :--------------- | :---------------------------- | 8612| number | Timestamp.| 8613 8614**Example** 8615 8616```ts 8617import { BusinessError } from '@kit.BasicServicesKit'; 8618 8619try { 8620 let audioTime: number = audioCapturer.getAudioTimeSync(); 8621 console.info(`AudioFrameworkRecLog: AudioCapturer getAudioTimeSync : Success ${audioTime}`); 8622} catch (err) { 8623 let error = err as BusinessError; 8624 console.error(`AudioFrameworkRecLog: AudioCapturer getAudioTimeSync : ERROR : ${error}`); 8625} 8626``` 8627 8628### getBufferSize<sup>8+</sup> 8629 8630getBufferSize(callback: AsyncCallback<number\>): void 8631 8632Obtains a reasonable minimum buffer size in bytes for capturing. This API uses an asynchronous callback to return the result. 8633 8634**System capability**: SystemCapability.Multimedia.Audio.Capturer 8635 8636**Parameters** 8637 8638| Name | Type | Mandatory| Description | 8639| :------- | :--------------------- | :--- | :----------------------------------- | 8640| 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.| 8641 8642**Example** 8643 8644```ts 8645import { BusinessError } from '@kit.BasicServicesKit'; 8646 8647audioCapturer.getBufferSize((err: BusinessError, bufferSize: number) => { 8648 if (!err) { 8649 console.info(`BufferSize : ${bufferSize}`); 8650 audioCapturer.read(bufferSize, true).then((buffer: ArrayBuffer) => { 8651 console.info(`Buffer read is ${buffer.byteLength}`); 8652 }).catch((err: BusinessError) => { 8653 console.error(`AudioFrameworkRecLog: AudioCapturer Created : ERROR : ${err}`); 8654 }); 8655 } 8656}); 8657``` 8658 8659### getBufferSize<sup>8+</sup> 8660 8661getBufferSize(): Promise<number\> 8662 8663Obtains a reasonable minimum buffer size in bytes for capturing. This API uses a promise to return the result. 8664 8665**System capability**: SystemCapability.Multimedia.Audio.Capturer 8666 8667**Return value** 8668 8669| Type | Description | 8670| :--------------- | :---------------------------------- | 8671| Promise<number\> | Promise used to return the buffer size.| 8672 8673**Example** 8674 8675```ts 8676import { BusinessError } from '@kit.BasicServicesKit'; 8677 8678let bufferSize: number = 0; 8679 8680audioCapturer.getBufferSize().then((data: number) => { 8681 console.info(`AudioFrameworkRecLog: getBufferSize :SUCCESS ${data}`); 8682 bufferSize = data; 8683}).catch((err: BusinessError) => { 8684 console.error(`AudioFrameworkRecLog: getBufferSize :ERROR : ${err}`); 8685}); 8686``` 8687 8688### getBufferSizeSync<sup>10+</sup> 8689 8690getBufferSizeSync(): number 8691 8692Obtains a reasonable minimum buffer size in bytes for capturing. This API returns the result synchronously. 8693 8694**System capability**: SystemCapability.Multimedia.Audio.Capturer 8695 8696**Return value** 8697 8698| Type | Description | 8699| :--------------- | :---------------------------------- | 8700| number | Buffer size.| 8701 8702**Example** 8703 8704```ts 8705import { BusinessError } from '@kit.BasicServicesKit'; 8706 8707let bufferSize: number = 0; 8708 8709try { 8710 bufferSize = audioCapturer.getBufferSizeSync(); 8711 console.info(`AudioFrameworkRecLog: getBufferSizeSync :SUCCESS ${bufferSize}`); 8712} catch (err) { 8713 let error = err as BusinessError; 8714 console.error(`AudioFrameworkRecLog: getBufferSizeSync :ERROR : ${error}`); 8715} 8716``` 8717 8718### getCurrentInputDevices<sup>11+</sup> 8719 8720getCurrentInputDevices(): AudioDeviceDescriptors 8721 8722Obtains the descriptors of the current input devices. This API returns the result synchronously. 8723 8724**System capability**: SystemCapability.Multimedia.Audio.Device 8725 8726**Return value** 8727 8728| Type | Description | 8729| ---------------------- | ------------------------------------------------------ | 8730| [AudioDeviceDescriptors](#audiodevicedescriptors) | An array of the audio device descriptors.| 8731 8732**Example** 8733 8734```ts 8735let deviceDescriptors: audio.AudioDeviceDescriptors = audioCapturer.getCurrentInputDevices(); 8736console.info(`Device id: ${deviceDescriptors[0].id}`); 8737console.info(`Device type: ${deviceDescriptors[0].deviceType}`); 8738console.info(`Device role: ${deviceDescriptors[0].deviceRole}`); 8739console.info(`Device name: ${deviceDescriptors[0].name}`); 8740console.info(`Device address: ${deviceDescriptors[0].address}`); 8741console.info(`Device samplerates: ${deviceDescriptors[0].sampleRates[0]}`); 8742console.info(`Device channelcounts: ${deviceDescriptors[0].channelCounts[0]}`); 8743console.info(`Device channelmask: ${deviceDescriptors[0].channelMasks[0]}`); 8744if (deviceDescriptors[0].encodingTypes) { 8745 console.info(`Device encodingTypes: ${deviceDescriptors[0].encodingTypes[0]}`); 8746} 8747``` 8748 8749### getCurrentAudioCapturerChangeInfo<sup>11+</sup> 8750 8751getCurrentAudioCapturerChangeInfo(): AudioCapturerChangeInfo 8752 8753Obtains the configuration changes of the current audio capturer. This API returns the result synchronously. 8754 8755**System capability**: SystemCapability.Multimedia.Audio.Device 8756 8757**Return value** 8758 8759| Type | Description | 8760| :--------------- | :---------------------------------- | 8761| [AudioCapturerChangeInfo](#audiocapturerchangeinfo9) | Configuration changes of the audio capturer.| 8762 8763**Example** 8764 8765```ts 8766let info: audio.AudioCapturerChangeInfo = audioCapturer.getCurrentAudioCapturerChangeInfo(); 8767console.info(`Info streamId: ${info.streamId}`); 8768console.info(`Info source: ${info.capturerInfo.source}`); 8769console.info(`Info capturerFlags: ${info.capturerInfo.capturerFlags}`); 8770console.info(`Info muted: ${info.muted}`); 8771console.info(`Info type: ${info.deviceDescriptors[0].deviceType}`); 8772console.info(`Info role: ${info.deviceDescriptors[0].deviceRole}`); 8773console.info(`Info name: ${info.deviceDescriptors[0].name}`); 8774console.info(`Info address: ${info.deviceDescriptors[0].address}`); 8775console.info(`Info samplerates: ${info.deviceDescriptors[0].sampleRates[0]}`); 8776console.info(`Info channelcounts: ${info.deviceDescriptors[0].channelCounts[0]}`); 8777console.info(`Info channelmask: ${info.deviceDescriptors[0].channelMasks[0]}`); 8778if (info.deviceDescriptors[0].encodingTypes) { 8779 console.info(`Device encodingTypes: ${info.deviceDescriptors[0].encodingTypes[0]}`); 8780} 8781``` 8782 8783### on('audioInterrupt')<sup>10+</sup> 8784 8785on(type: 'audioInterrupt', callback: Callback\<InterruptEvent>): void 8786 8787Subscribes to the audio interruption event, which is triggered when the audio focus is changed. This API uses an asynchronous callback to return the result. 8788 8789The **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. 8790 8791After 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). 8792 8793**System capability**: SystemCapability.Multimedia.Audio.Interrupt 8794 8795**Parameters** 8796 8797| Name | Type | Mandatory| Description | 8798| -------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | 8799| type | string | Yes | Event type. The value is fixed at **'audioInterrupt'**.| 8800| callback | Callback\<[InterruptEvent](#interruptevent9)\> | Yes | Callback used to return the audio interruption event received by the application when recording is interrupted.| 8801 8802**Error codes** 8803 8804For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 8805 8806| ID| Error Message| 8807| ------- | --------------------------------------------| 8808| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 8809| 6800101 | Parameter verification failed. | 8810 8811**Example** 8812 8813```ts 8814import { audio } from '@kit.AudioKit'; 8815 8816let isCapturing: boolean; // An identifier specifying whether capturing is in progress. 8817onAudioInterrupt(); 8818 8819async function onAudioInterrupt(){ 8820 audioCapturer.on('audioInterrupt', (interruptEvent: audio.InterruptEvent) => { 8821 // When an audio interruption event occurs, the AudioCapturer receives the interruptEvent callback and performs processing based on the content in the callback. 8822 // 1. (Optional) The AudioCapturer reads the value of interruptEvent.forceType to see whether the system has forcibly performed the operation. 8823 // 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. 8824 // 2. (Mandatory) The AudioCapturer then reads the value of interruptEvent.hintType and performs corresponding processing. 8825 if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_FORCE) { 8826 // The audio focus event has been forcibly executed by the system. The application needs to update its status and displayed content. 8827 switch (interruptEvent.hintType) { 8828 case audio.InterruptHint.INTERRUPT_HINT_PAUSE: 8829 // 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. 8830 console.info('Force paused. Update capturing status and stop reading'); 8831 isCapturing = false; // A simplified processing indicating several operations for switching the application to the paused state. 8832 break; 8833 case audio.InterruptHint.INTERRUPT_HINT_STOP: 8834 // The audio stream has been stopped and permanently loses the focus. The user must manually trigger the operation to resume capturing. 8835 console.info('Force stopped. Update capturing status and stop reading'); 8836 isCapturing = false; // A simplified processing indicating several operations for switching the application to the paused state. 8837 break; 8838 default: 8839 console.info('Invalid interruptEvent'); 8840 break; 8841 } 8842 } else if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_SHARE) { 8843 // 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. 8844 switch (interruptEvent.hintType) { 8845 case audio.InterruptHint.INTERRUPT_HINT_RESUME: 8846 // 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.) 8847 // 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. 8848 console.info('Resume force paused renderer or ignore'); 8849 // To continue capturing, the application must perform the required operations. 8850 break; 8851 default: 8852 console.info('Invalid interruptEvent'); 8853 break; 8854 } 8855 } 8856 }); 8857} 8858``` 8859 8860### off('audioInterrupt')<sup>10+</sup> 8861 8862off(type: 'audioInterrupt'): void 8863 8864Unsubscribes from the audio interruption event. 8865 8866**System capability**: SystemCapability.Multimedia.Audio.Interrupt 8867 8868**Parameters** 8869 8870| Name | Type | Mandatory| Description | 8871| -------- | -------------------------------------------- | ---- | ------------------------------------------------------------ | 8872| type | string | Yes | Event type. The value is fixed at **'audioInterrupt'**.| 8873 8874**Error codes** 8875 8876For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 8877 8878| ID| Error Message| 8879| ------- | --------------------------------------------| 8880| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 8881| 6800101 | Parameter verification failed. | 8882 8883**Example** 8884 8885```ts 8886audioCapturer.off('audioInterrupt'); 8887``` 8888 8889### on('inputDeviceChange')<sup>11+</sup> 8890 8891on(type: 'inputDeviceChange', callback: Callback\<AudioDeviceDescriptors>): void 8892 8893Subscribes 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. 8894 8895**System capability**: SystemCapability.Multimedia.Audio.Device 8896 8897**Parameters** 8898 8899| Name | Type | Mandatory| Description | 8900| :------- | :------------------------- | :--- | :------------------------------------------ | 8901| type | string | Yes | Event type. The value is fixed at **'inputDeviceChange**.| 8902| callback | Callback\<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Yes | Callback used to return the information about the new audio input device.| 8903 8904**Error codes** 8905 8906For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 8907 8908| ID| Error Message| 8909| ------- | --------------------------------------------| 8910| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 8911| 6800101 | Parameter verification failed. | 8912 8913**Example** 8914 8915```ts 8916audioCapturer.on('inputDeviceChange', (deviceChangeInfo: audio.AudioDeviceDescriptors) => { 8917 console.info(`inputDevice id: ${deviceChangeInfo[0].id}`); 8918 console.info(`inputDevice deviceRole: ${deviceChangeInfo[0].deviceRole}`); 8919 console.info(`inputDevice deviceType: ${deviceChangeInfo[0].deviceType}`); 8920}); 8921``` 8922### off('inputDeviceChange')<sup>11+</sup> 8923 8924off(type: 'inputDeviceChange', callback?: Callback\<AudioDeviceDescriptors>): void 8925 8926Unsubscribes from the audio input device change event. This API uses an asynchronous callback to return the result. 8927 8928**System capability**: SystemCapability.Multimedia.Audio.Device 8929 8930**Parameters** 8931 8932| Name | Type | Mandatory| Description | 8933| :------- | :------------------------- | :--- |:-----------------------------------------| 8934| type | string | Yes | Event type. The value is fixed at **'inputDeviceChange**. | 8935| callback | Callback\<[AudioDeviceDescriptors](#audiodevicedescriptors)> | No | Callback used to return the information about the audio input device.| 8936 8937**Error codes** 8938 8939For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 8940 8941| ID| Error Message| 8942| ------- | --------------------------------------------| 8943| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 8944| 6800101 | Parameter verification failed. | 8945 8946**Example** 8947 8948```ts 8949// Cancel all subscriptions to the event. 8950audioCapturer.off('inputDeviceChange'); 8951 8952// 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. 8953let inputDeviceChangeCallback = (deviceChangeInfo: audio.AudioDeviceDescriptors) => { 8954 console.info(`inputDevice id: ${deviceChangeInfo[0].id}`); 8955 console.info(`inputDevice deviceRole: ${deviceChangeInfo[0].deviceRole}`); 8956 console.info(`inputDevice deviceType: ${deviceChangeInfo[0].deviceType}`); 8957}; 8958 8959audioCapturer.on('inputDeviceChange', inputDeviceChangeCallback); 8960 8961audioCapturer.off('inputDeviceChange', inputDeviceChangeCallback); 8962``` 8963 8964### on('audioCapturerChange')<sup>11+</sup> 8965 8966on(type: 'audioCapturerChange', callback: Callback\<AudioCapturerChangeInfo>): void 8967 8968Subscribes 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. 8969 8970**System capability**: SystemCapability.Multimedia.Audio.Capturer 8971 8972**Parameters** 8973 8974| Name | Type | Mandatory| Description | 8975| :------- | :------------------------- | :--- | :------------------------------------------ | 8976| type | string | Yes | Event type. The value is fixed at **'audioCapturerChange'**.| 8977| callback | Callback\<[AudioCapturerChangeInfo](#audiocapturerchangeinfo9)> | Yes | Callback used to return the current configuration and status information of the audio capturer.| 8978 8979**Error codes** 8980 8981For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 8982 8983| ID| Error Message| 8984| ------- | --------------------------------------------| 8985| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 8986| 6800101 | Parameter verification failed. | 8987 8988**Example** 8989 8990```ts 8991audioCapturer.on('audioCapturerChange', (capturerChangeInfo: audio.AudioCapturerChangeInfo) => { 8992 console.info(`audioCapturerChange id: ${capturerChangeInfo[0].id}`); 8993 console.info(`audioCapturerChange deviceRole: ${capturerChangeInfo[0].deviceRole}`); 8994 console.info(`audioCapturerChange deviceType: ${capturerChangeInfo[0].deviceType}`); 8995}); 8996``` 8997 8998### off('audioCapturerChange')<sup>11+</sup> 8999 9000off(type: 'audioCapturerChange', callback?: Callback\<AudioCapturerChangeInfo>): void 9001 9002Unsubscribes from the audio capturer configuration change event. This API uses an asynchronous callback to return the result. 9003 9004**System capability**: SystemCapability.Multimedia.Audio.Capturer 9005 9006**Parameters** 9007 9008| Name | Type | Mandatory| Description | 9009| :------- | :------------------------- | :--- | :------------------------------------------ | 9010| type | string | Yes | Event type. The value is fixed at **'audioCapturerChange'**.| 9011| callback | Callback\<[AudioCapturerChangeInfo](#audiocapturerchangeinfo9)> | No | Callback used for unsubscription.| 9012 9013**Error codes** 9014 9015For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 9016 9017| ID| Error Message| 9018| ------- | --------------------------------------------| 9019| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 9020| 6800101 | Parameter verification failed. | 9021 9022**Example** 9023 9024```ts 9025// Cancel all subscriptions to the event. 9026audioCapturer.off('audioCapturerChange'); 9027 9028// 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. 9029let audioCapturerChangeCallback = (capturerChangeInfo: audio.AudioCapturerChangeInfo) => { 9030 console.info(`audioCapturerChange id: ${capturerChangeInfo[0].id}`); 9031 console.info(`audioCapturerChange deviceRole: ${capturerChangeInfo[0].deviceRole}`); 9032 console.info(`audioCapturerChange deviceType: ${capturerChangeInfo[0].deviceType}`); 9033}; 9034 9035audioCapturer.on('audioCapturerChange', audioCapturerChangeCallback); 9036 9037audioCapturer.off('audioCapturerChange', audioCapturerChangeCallback); 9038``` 9039 9040### on('markReach')<sup>8+</sup> 9041 9042on(type: 'markReach', frame: number, callback: Callback<number>): void 9043 9044Subscribes 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. 9045 9046For example, if **frame** is set to **100**, the callback is invoked when the number of captured frames reaches the 100th frame. 9047 9048**System capability**: SystemCapability.Multimedia.Audio.Capturer 9049 9050**Parameters** 9051 9052| Name | Type | Mandatory| Description | 9053| :------- | :---------------------- | :--- | :----------------------------------------- | 9054| type | string | Yes | Event type. The value is fixed at **'markReach'**. | 9055| frame | number | Yes | Number of frames to trigger the event. The value must be greater than **0**. | 9056| callback | Callback\<number> | Yes | Callback used to return the value of the **frame** parameter.| 9057 9058**Example** 9059 9060```ts 9061audioCapturer.on('markReach', 1000, (position: number) => { 9062 if (position == 1000) { 9063 console.info('ON Triggered successfully'); 9064 } 9065}); 9066``` 9067 9068### off('markReach')<sup>8+</sup> 9069 9070off(type: 'markReach'): void 9071 9072Unsubscribes from the mark reached event. 9073 9074**System capability**: SystemCapability.Multimedia.Audio.Capturer 9075 9076**Parameters** 9077 9078| Name| Type | Mandatory| Description | 9079| :----- | :----- | :--- | :-------------------------------------------- | 9080| type | string | Yes | Event type. The value is fixed at **'markReach'**.| 9081 9082**Example** 9083 9084```ts 9085audioCapturer.off('markReach'); 9086``` 9087 9088### on('periodReach')<sup>8+</sup> 9089 9090on(type: 'periodReach', frame: number, callback: Callback<number>): void 9091 9092Subscribes 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. 9093 9094For 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. 9095 9096**System capability**: SystemCapability.Multimedia.Audio.Capturer 9097 9098**Parameters** 9099 9100| Name | Type | Mandatory| Description | 9101| :------- | :----------------------- | :--- | :------------------------------------------ | 9102| type | string | Yes | Event type. The value is fixed at **'periodReach'**.| 9103| frame | number | Yes | Number of frames to trigger the event. The value must be greater than **0**. | 9104| callback | Callback\<number> | Yes |Callback used to return the value of the **frame** parameter. | 9105 9106**Example** 9107 9108```ts 9109audioCapturer.on('periodReach', 1000, (position: number) => { 9110 if (position == 1000) { 9111 console.info('ON Triggered successfully'); 9112 } 9113}); 9114``` 9115 9116### off('periodReach')<sup>8+</sup> 9117 9118off(type: 'periodReach'): void 9119 9120Unsubscribes from the period reached event. 9121 9122**System capability**: SystemCapability.Multimedia.Audio.Capturer 9123 9124**Parameters** 9125 9126| Name| Type | Mandatory| Description | 9127| :----- | :----- | :--- | :---------------------------------------------- | 9128| type | string | Yes | Event type. The value is fixed at **'periodReach'**.| 9129 9130**Example** 9131 9132```ts 9133audioCapturer.off('periodReach'); 9134``` 9135 9136### on('stateChange')<sup>8+</sup> 9137 9138on(type: 'stateChange', callback: Callback<AudioState\>): void 9139 9140Subscribes 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. 9141 9142**System capability**: SystemCapability.Multimedia.Audio.Capturer 9143 9144**Parameters** 9145 9146| Name | Type | Mandatory| Description | 9147| :------- | :------------------------- | :--- | :------------------------------------------ | 9148| type | string | Yes | Event type. The value is fixed at **'stateChange'**.| 9149| callback | Callback\<[AudioState](#audiostate8)> | Yes | Callback used to return the audio status.| 9150 9151**Example** 9152 9153```ts 9154audioCapturer.on('stateChange', (state: audio.AudioState) => { 9155 if (state == 1) { 9156 console.info('audio capturer state is: STATE_PREPARED'); 9157 } 9158 if (state == 2) { 9159 console.info('audio capturer state is: STATE_RUNNING'); 9160 } 9161}); 9162``` 9163 9164### on('readData')<sup>11+</sup> 9165 9166on(type: 'readData', callback: Callback\<ArrayBuffer>): void 9167 9168Subscribes 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. 9169 9170The callback function is used only to read audio data. Do not call AudioCapturer APIs in it. 9171 9172**System capability**: SystemCapability.Multimedia.Audio.Capturer 9173 9174**Parameters** 9175 9176| Name | Type | Mandatory| Description | 9177| :------- |:-----------------------| :--- |:--------------------------| 9178| type | string | Yes | Event type. The value is fixed at **'readData'**.| 9179| callback | Callback\<ArrayBuffer> | Yes | Callback used to return the buffer from which the data is read. | 9180 9181**Error codes** 9182 9183For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 9184 9185| ID| Error Message| 9186| ------- | --------------------------------------------| 9187| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 9188| 6800101 | Parameter verification failed. | 9189 9190**Example** 9191 9192```ts 9193import { BusinessError } from '@kit.BasicServicesKit'; 9194import { fileIo as fs } from '@kit.CoreFileKit'; 9195 9196class Options { 9197 offset?: number; 9198 length?: number; 9199} 9200 9201let bufferSize: number = 0; 9202let path = getContext().cacheDir; 9203// Ensure that the resource exists in the path. 9204let filePath = path + '/StarWars10s-2C-48000-4SW.pcm'; 9205let file: fs.File = fs.openSync(filePath, fs.OpenMode.READ_WRITE); 9206let readDataCallback = (buffer: ArrayBuffer) => { 9207 let options: Options = { 9208 offset: bufferSize, 9209 length: buffer.byteLength 9210 }; 9211 fs.writeSync(file.fd, buffer, options); 9212 bufferSize += buffer.byteLength; 9213} 9214 9215audioCapturer.on('readData', readDataCallback); 9216 9217audioCapturer.start((err: BusinessError) => { 9218 if (err) { 9219 console.error('Capturer start failed.'); 9220 } else { 9221 console.info('Capturer start success.'); 9222 } 9223}); 9224``` 9225 9226### off('readData')<sup>11+</sup> 9227 9228off(type: 'readData', callback?: Callback\<ArrayBuffer>): void 9229 9230Unsubscribes from the audio data read event. This API uses an asynchronous callback to return the result. 9231 9232**System capability**: SystemCapability.Multimedia.Audio.Capturer 9233 9234**Parameters** 9235 9236| Name | Type | Mandatory| Description | 9237| :------- |:-----------------------| :--- |:-------------------------------------------| 9238| type | string | Yes | Event type. The value is fixed at **'readData'**. | 9239| callback | Callback\<ArrayBuffer> | No | Callback used to return the buffer from which the data is read. | 9240 9241**Error codes** 9242 9243For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 9244 9245| ID| Error Message| 9246| ------- | --------------------------------------------| 9247| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 9248| 6800101 | Parameter verification failed. | 9249 9250**Example** 9251 9252```ts 9253// Cancel all subscriptions to the event. 9254audioCapturer.off('readData'); 9255 9256// 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. 9257let readDataCallback = (data: ArrayBuffer) => { 9258 console.info(`read data: ${data}`); 9259}; 9260 9261audioCapturer.on('readData', readDataCallback); 9262 9263audioCapturer.off('readData', readDataCallback); 9264``` 9265 9266### getOverflowCount<sup>12+</sup> 9267 9268getOverflowCount(): Promise<number> 9269 9270Obtains the number of overflow audio frames in the audio stream that is being captured. This API uses a promise to return the result. 9271 9272**System capability**: SystemCapability.Multimedia.Audio.Capturer 9273 9274**Return value** 9275 9276| Type | Description | 9277| ------------------- | ----------------------------- | 9278| Promise<number>| Promise used to return the number of overflow audio frames.| 9279 9280**Example** 9281 9282```ts 9283import { BusinessError } from '@kit.BasicServicesKit'; 9284 9285audioCapturer.getOverflowCount().then((value: number) => { 9286 console.info(`Get overflow count Success! ${value}`); 9287}).catch((err: BusinessError) => { 9288 console.error(`Get overflow count Fail: ${err}`); 9289}); 9290``` 9291 9292### getOverflowCountSync<sup>12+</sup> 9293 9294getOverflowCountSync(): number 9295 9296Obtains the number of overflow audio frames in the audio stream that is being captured. This API returns the result synchronously. 9297 9298**System capability**: SystemCapability.Multimedia.Audio.Capturer 9299 9300**Return value** 9301 9302| Type | Description | 9303| ------------------- | ----------------------------- | 9304| number| Number of overflow audio frames.| 9305 9306**Example** 9307 9308```ts 9309import { BusinessError } from '@kit.BasicServicesKit'; 9310 9311try { 9312 let value: number = audioCapturer.getOverflowCountSync(); 9313 console.info(`Get overflow count Success! ${value}`); 9314} catch (err) { 9315 let error = err as BusinessError; 9316 console.error(`Get overflow count Fail: ${error}`); 9317} 9318``` 9319 9320## ActiveDeviceType<sup>(deprecated)</sup> 9321 9322Enumerates the active device types. 9323 9324> **NOTE** 9325> 9326> This API is deprecated since API version 9. You are advised to use [CommunicationDeviceType](#communicationdevicetype9) instead. 9327 9328**System capability**: SystemCapability.Multimedia.Audio.Device 9329 9330| Name | Value | Description | 9331| ------------- | ------ | ---------------------------------------------------- | 9332| SPEAKER | 2 | Speaker. | 9333| BLUETOOTH_SCO | 7 | Bluetooth device using Synchronous Connection Oriented (SCO) links.| 9334 9335## InterruptActionType<sup>(deprecated)</sup> 9336 9337Enumerates the returned event types for audio interruption events. 9338 9339> **NOTE** 9340> 9341> 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. 9342 9343**System capability**: SystemCapability.Multimedia.Audio.Renderer 9344 9345| Name | Value | Description | 9346| -------------- | ------ | ------------------ | 9347| TYPE_ACTIVATED | 0 | Focus gain event.| 9348| TYPE_INTERRUPT | 1 | Audio interruption event.| 9349 9350## AudioInterrupt<sup>(deprecated)</sup> 9351 9352Describes input parameters of audio interruption events. 9353 9354> **NOTE** 9355> 9356> 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. 9357 9358**System capability**: SystemCapability.Multimedia.Audio.Renderer 9359 9360| Name | Type | Mandatory| Description | 9361| --------------- | --------------------------- | ----| ------------------------------------------------------------ | 9362| streamUsage | [StreamUsage](#streamusage) | Yes | Audio stream usage. | 9363| contentType | [ContentType](#contenttypedeprecated) | Yes | Audio content type. | 9364| 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.| 9365 9366## InterruptAction<sup>(deprecated)</sup> 9367 9368Describes the callback invoked for audio interruption or focus gain events. 9369 9370> **NOTE** 9371> 9372> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [InterruptEvent](#interruptevent9). 9373 9374**System capability**: SystemCapability.Multimedia.Audio.Renderer 9375 9376| Name | Type | Mandatory| Description | 9377| ---------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | 9378| actionType | [InterruptActionType](#interruptactiontypedeprecated) | Yes | Returned event type. The value **TYPE_ACTIVATED** means the focus gain event, and **TYPE_INTERRUPT** means the audio interruption event.| 9379| type | [InterruptType](#interrupttype) | No | Type of the audio interruption event. | 9380| hint | [InterruptHint](#interrupthint) | No | Hint provided along with the audio interruption event. | 9381| 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.| 9382