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_44100, 80 channels: audio.AudioChannel.CHANNEL_1, 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_VOICE_COMMUNICATION, 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_44100, 133 channels: audio.AudioChannel.CHANNEL_1, 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_VOICE_COMMUNICATION, 140 rendererFlags: 0 141} 142 143let audioRendererOptions: audio.AudioRendererOptions = { 144 streamInfo: audioStreamInfo, 145 rendererInfo: audioRendererInfo 146} 147 148let audioRenderer: audio.AudioRenderer; 149audio.createAudioRenderer(audioRendererOptions).then((data) => { 150 audioRenderer = data; 151 console.info('AudioFrameworkRenderLog: AudioRenderer Created : Success : Stream Type: SUCCESS'); 152}).catch((err: BusinessError) => { 153 console.error(`AudioFrameworkRenderLog: AudioRenderer Created : ERROR : ${err}`); 154}); 155``` 156 157## audio.createAudioCapturer<sup>8+</sup> 158 159createAudioCapturer(options: AudioCapturerOptions, callback: AsyncCallback<AudioCapturer\>): void 160 161Creates an **AudioCapturer** instance. This API uses an asynchronous callback to return the result. 162 163**System capability**: SystemCapability.Multimedia.Audio.Capturer 164 165**Required permissions**: ohos.permission.MICROPHONE 166 167This permission is required only when [SourceType](#sourcetype8) is set to **SOURCE_TYPE_MIC**. 168 169**Parameters** 170 171| Name | Type | Mandatory| Description | 172| :------- | :---------------------------------------------- | :--- | :--------------- | 173| options | [AudioCapturerOptions](#audiocaptureroptions8) | Yes | Capturer configurations.| 174| 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.| 175 176**Example** 177 178```ts 179import { audio } from '@kit.AudioKit'; 180 181let audioStreamInfo: audio.AudioStreamInfo = { 182 samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_44100, 183 channels: audio.AudioChannel.CHANNEL_2, 184 sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, 185 encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW 186} 187 188let audioCapturerInfo: audio.AudioCapturerInfo = { 189 source: audio.SourceType.SOURCE_TYPE_MIC, 190 capturerFlags: 0 191} 192 193let audioCapturerOptions: audio.AudioCapturerOptions = { 194 streamInfo: audioStreamInfo, 195 capturerInfo: audioCapturerInfo 196} 197 198audio.createAudioCapturer(audioCapturerOptions, (err, data) => { 199 if (err) { 200 console.error(`AudioCapturer Created : Error: ${err}`); 201 } else { 202 console.info('AudioCapturer Created : Success : SUCCESS'); 203 let audioCapturer = data; 204 } 205}); 206``` 207 208## audio.createAudioCapturer<sup>8+</sup> 209 210createAudioCapturer(options: AudioCapturerOptions): Promise<AudioCapturer\> 211 212Creates an **AudioCapturer** instance. This API uses a promise to return the result. 213 214**System capability**: SystemCapability.Multimedia.Audio.Capturer 215 216**Required permissions**: ohos.permission.MICROPHONE 217 218This permission is required only when [SourceType](#sourcetype8) is set to **SOURCE_TYPE_MIC**. 219 220**Parameters** 221 222| Name | Type | Mandatory| Description | 223| :------ | :--------------------------------------------- | :--- | :--------------- | 224| options | [AudioCapturerOptions](#audiocaptureroptions8) | Yes | Capturer configurations.| 225 226**Return value** 227 228| Type | Description | 229| ----------------------------------------- |----------------------| 230| 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.| 231 232**Example** 233 234```ts 235import { audio } from '@kit.AudioKit'; 236import { BusinessError } from '@kit.BasicServicesKit'; 237 238let audioStreamInfo: audio.AudioStreamInfo = { 239 samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_44100, 240 channels: audio.AudioChannel.CHANNEL_2, 241 sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, 242 encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW 243} 244 245let audioCapturerInfo: audio.AudioCapturerInfo = { 246 source: audio.SourceType.SOURCE_TYPE_MIC, 247 capturerFlags: 0 248} 249 250let audioCapturerOptions:audio.AudioCapturerOptions = { 251 streamInfo: audioStreamInfo, 252 capturerInfo: audioCapturerInfo 253} 254 255let audioCapturer: audio.AudioCapturer; 256audio.createAudioCapturer(audioCapturerOptions).then((data) => { 257 audioCapturer = data; 258 console.info('AudioCapturer Created : Success : Stream Type: SUCCESS'); 259}).catch((err: BusinessError) => { 260 console.error(`AudioCapturer Created : ERROR : ${err}`); 261}); 262``` 263 264## AudioVolumeType 265 266Enumerates the audio stream types. 267 268**System capability**: SystemCapability.Multimedia.Audio.Volume 269 270| Name | Value | Description | 271| ---------------------------- | ------ | ---------- | 272| VOICE_CALL<sup>8+</sup> | 0 | Audio stream for voice calls.| 273| RINGTONE | 2 | Audio stream for ringtones. | 274| MEDIA | 3 | Audio stream for media purpose. | 275| ALARM<sup>10+</sup> | 4 | Audio stream for alarming. | 276| ACCESSIBILITY<sup>10+</sup> | 5 | Audio stream for accessibility. | 277| VOICE_ASSISTANT<sup>8+</sup> | 9 | Audio stream for voice assistant.| 278 279## InterruptMode<sup>9+</sup> 280 281Enumerates the audio interruption modes. 282 283**Atomic service API**: This API can be used in atomic services since API version 12. 284 285**System capability**: SystemCapability.Multimedia.Audio.Interrupt 286 287| Name | Value | Description | 288| ---------------------------- | ------ | ---------- | 289| SHARE_MODE | 0 | Shared mode.| 290| INDEPENDENT_MODE | 1 | Independent mode.| 291 292## DeviceFlag 293 294Enumerates the audio device flags. 295 296**System capability**: SystemCapability.Multimedia.Audio.Device 297 298| Name | Value | Description | 299| ------------------------------- | ------ |---------------------------| 300| OUTPUT_DEVICES_FLAG | 1 | Output device. | 301| INPUT_DEVICES_FLAG | 2 | Input device. | 302| ALL_DEVICES_FLAG | 3 | All devices. | 303 304## DeviceUsage<sup>12+</sup> 305 306Enumerates the usage scenarios of audio devices. 307 308**System capability**: SystemCapability.Multimedia.Audio.Device 309 310| Name | Value | Description | 311| ------------------------------- | ------ |---------------------------| 312| MEDIA_OUTPUT_DEVICES | 1 | Media output device.| 313| MEDIA_INPUT_DEVICES | 2 | Media input device.| 314| ALL_MEDIA_DEVICES | 3 | All media devices.| 315| CALL_OUTPUT_DEVICES | 4 | Call output device.| 316| CALL_INPUT_DEVICES | 8 | Call input device.| 317| ALL_CALL_DEVICES | 12 | All call devices.| 318 319## DeviceRole 320 321Enumerates the audio device roles. 322 323**Atomic service API**: This API can be used in atomic services since API version 12. 324 325**System capability**: SystemCapability.Multimedia.Audio.Device 326 327| Name | Value | Description | 328| ------------- | ------ | -------------- | 329| INPUT_DEVICE | 1 | Input role.| 330| OUTPUT_DEVICE | 2 | Output role.| 331 332## DeviceType 333 334Enumerates the audio device types. 335 336**Atomic service API**: This API can be used in atomic services since API version 12. 337 338**System capability**: SystemCapability.Multimedia.Audio.Device 339 340| Name | Value | Description | 341| ---------------------| ------ | --------------------------------------------------------- | 342| INVALID | 0 | Invalid device. | 343| EARPIECE | 1 | Earpiece. | 344| SPEAKER | 2 | Speaker. | 345| WIRED_HEADSET | 3 | Wired headset with a microphone. | 346| WIRED_HEADPHONES | 4 | Wired headset without microphone. | 347| BLUETOOTH_SCO | 7 | Bluetooth device using Synchronous Connection Oriented (SCO) links. | 348| BLUETOOTH_A2DP | 8 | Bluetooth device using Advanced Audio Distribution Profile (A2DP) links.| 349| MIC | 15 | Microphone. | 350| USB_HEADSET | 22 | USB Type-C headset. | 351| DISPLAY_PORT<sup>12+</sup> | 23 | Display port (DP), which is used to connect to external devices. | 352| REMOTE_CAST<sup>12+</sup> | 24 | Remote cast device. | 353| DEFAULT<sup>9+</sup> | 1000 | Default device type. | 354 355## CommunicationDeviceType<sup>9+</sup> 356 357Enumerates the device types used for communication. 358 359**System capability**: SystemCapability.Multimedia.Audio.Communication 360 361| Name | Value | Description | 362| ------------- | ------ | -------------| 363| SPEAKER | 2 | Speaker. | 364 365## AudioRingMode 366 367Enumerates the ringer modes. 368 369**System capability**: SystemCapability.Multimedia.Audio.Communication 370 371| Name | Value | Description | 372| ------------------- | ------ | ---------- | 373| RINGER_MODE_SILENT | 0 | Silent mode.| 374| RINGER_MODE_VIBRATE | 1 | Vibration mode.| 375| RINGER_MODE_NORMAL | 2 | Normal mode.| 376 377## AudioSampleFormat<sup>8+</sup> 378 379Enumerates the audio sample formats. 380 381**System capability**: SystemCapability.Multimedia.Audio.Core 382 383| Name | Value | Description | 384| ---------------------------------- | ------ | -------------------------- | 385| SAMPLE_FORMAT_INVALID | -1 | Invalid format. | 386| SAMPLE_FORMAT_U8 | 0 | Unsigned 8-bit integer. | 387| SAMPLE_FORMAT_S16LE | 1 | Signed 16-bit integer, little endian.| 388| SAMPLE_FORMAT_S24LE | 2 | Signed 24-bit integer, little endian.<br>Due to system restrictions, only some devices support this sampling format.| 389| SAMPLE_FORMAT_S32LE | 3 | Signed 32-bit integer, little endian.<br>Due to system restrictions, only some devices support this sampling format.| 390| 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.| 391 392## AudioErrors<sup>9+</sup> 393 394Enumerates the audio error codes. 395 396**System capability**: SystemCapability.Multimedia.Audio.Core 397 398| Name | Value | Description | 399| ---------------------| --------| ----------------- | 400| ERROR_INVALID_PARAM | 6800101 | Invalid parameter. | 401| ERROR_NO_MEMORY | 6800102 | Memory allocation failure. | 402| ERROR_ILLEGAL_STATE | 6800103 | Unsupported state. | 403| ERROR_UNSUPPORTED | 6800104 | Unsupported parameter value. | 404| ERROR_TIMEOUT | 6800105 | Processing timeout. | 405| ERROR_STREAM_LIMIT | 6800201 | Too many audio streams.| 406| ERROR_SYSTEM | 6800301 | System error. | 407 408## AudioChannel<sup>8+</sup> 409 410Enumerates the audio channels. 411 412**System capability**: SystemCapability.Multimedia.Audio.Core 413 414| Name | Value | Description | 415| --------- | -------- |------| 416| CHANNEL_1 | 0x1 << 0 | One audio channel (mono).| 417| CHANNEL_2 | 0x1 << 1 | Two audio channels (stereo).| 418| CHANNEL_3<sup>11+</sup> | 3 | Three audio channels.| 419| CHANNEL_4<sup>11+</sup> | 4 | Four audio channels.| 420| CHANNEL_5<sup>11+</sup> | 5 | Five audio channels.| 421| CHANNEL_6<sup>11+</sup> | 6 | Six audio channels.| 422| CHANNEL_7<sup>11+</sup> | 7 | Seven audio channels.| 423| CHANNEL_8<sup>11+</sup> | 8 | Eight audio channels.| 424| CHANNEL_9<sup>11+</sup> | 9 | Nine audio channels.| 425| CHANNEL_10<sup>11+</sup> | 10 | Ten audio channels.| 426| CHANNEL_12<sup>11+</sup> | 12 | Twelve audio channels.| 427| CHANNEL_14<sup>11+</sup> | 14 | Fourteen audio channels.| 428| CHANNEL_16<sup>11+</sup> | 16 | Sixteen audio channels.| 429 430## AudioSamplingRate<sup>8+</sup> 431 432Enumerates the audio sampling rates. The sampling rates supported vary according to the device in use. 433 434**System capability**: SystemCapability.Multimedia.Audio.Core 435 436| Name | Value | Description | 437| ----------------- | ------ | --------------- | 438| SAMPLE_RATE_8000 | 8000 | The sampling rate is 8000. | 439| SAMPLE_RATE_11025 | 11025 | The sampling rate is 11025.| 440| SAMPLE_RATE_12000 | 12000 | The sampling rate is 12000.| 441| SAMPLE_RATE_16000 | 16000 | The sampling rate is 16000.| 442| SAMPLE_RATE_22050 | 22050 | The sampling rate is 22050.| 443| SAMPLE_RATE_24000 | 24000 | The sampling rate is 24000.| 444| SAMPLE_RATE_32000 | 32000 | The sampling rate is 32000.| 445| SAMPLE_RATE_44100 | 44100 | The sampling rate is 44100.| 446| SAMPLE_RATE_48000 | 48000 | The sampling rate is 48000.| 447| SAMPLE_RATE_64000 | 64000 | The sampling rate is 64000.| 448| SAMPLE_RATE_88200<sup>12+</sup> | 88200 | The sampling rate is 88200.| 449| SAMPLE_RATE_96000 | 96000 | The sampling rate is 96000.| 450| SAMPLE_RATE_176400<sup>12+</sup> | 176400 | The sampling rate is 176400.| 451| SAMPLE_RATE_192000<sup>12+</sup> | 192000 | The sampling rate is 192000.| 452 453## AudioEncodingType<sup>8+</sup> 454 455Enumerates the audio encoding types. 456 457**Atomic service API**: This API can be used in atomic services since API version 12. 458 459**System capability**: SystemCapability.Multimedia.Audio.Core 460 461| Name | Value | Description | 462| --------------------- | ------ | --------- | 463| ENCODING_TYPE_INVALID | -1 | Invalid. | 464| ENCODING_TYPE_RAW | 0 | PCM encoding.| 465 466## AudioChannelLayout<sup>11+</sup> 467 468Enumerates the audio channel layouts. 469 470**System capability**: SystemCapability.Multimedia.Audio.Core 471 472| Name | Value | Description | 473| ------------------------------ | ---------------- | --------------------------------------------- | 474| CH_LAYOUT_UNKNOWN | 0x0 | Unknown. | 475| CH_LAYOUT_MONO | 0x4 | Mono. | 476| CH_LAYOUT_STEREO | 0x3 | Stereo. | 477| CH_LAYOUT_STEREO_DOWNMIX | 0x60000000 | Stereo downmix. | 478| CH_LAYOUT_2POINT1 | 0xB | 2.1. | 479| CH_LAYOUT_3POINT0 | 0x103 | 3.0. | 480| CH_LAYOUT_SURROUND | 0x7 | Surround. | 481| CH_LAYOUT_3POINT1 | 0xF | 3.1. | 482| CH_LAYOUT_4POINT0 | 0x107 | 4.0. | 483| CH_LAYOUT_QUAD | 0x33 | Quad. | 484| CH_LAYOUT_QUAD_SIDE | 0x603 | Quad side. | 485| CH_LAYOUT_2POINT0POINT2 | 0x3000000003 | 2.0.2. | 486| CH_LAYOUT_AMB_ORDER1_ACN_N3D | 0x100000000001 | First-order FOA file in ACN_N3D (ITU standards). | 487| CH_LAYOUT_AMB_ORDER1_ACN_SN3D | 0x100000001001 | First-order FOA file in ACN_SN3D (ITU standards).| 488| CH_LAYOUT_AMB_ORDER1_FUMA | 0x100000000101 | First-order FOA file in FUMA (ITU standards). | 489| CH_LAYOUT_4POINT1 | 0x10F | 4.1. | 490| CH_LAYOUT_5POINT0 | 0x607 | 5.0. | 491| CH_LAYOUT_5POINT0_BACK | 0x37 | 5.0 back. | 492| CH_LAYOUT_2POINT1POINT2 | 0x300000000B | 2.1.2. | 493| CH_LAYOUT_3POINT0POINT2 | 0x3000000007 | 3.0.2. | 494| CH_LAYOUT_5POINT1 | 0x60F | 5.1. | 495| CH_LAYOUT_5POINT1_BACK | 0x3F | 5.1 back. | 496| CH_LAYOUT_6POINT0 | 0x707 | 6.0. | 497| CH_LAYOUT_HEXAGONAL | 0x137 | Hexagonal. | 498| CH_LAYOUT_3POINT1POINT2 | 0x500F | 3.1.2. | 499| CH_LAYOUT_6POINT0_FRONT | 0x6C3 | 6.0 front. | 500| CH_LAYOUT_6POINT1 | 0x70F | 6.1. | 501| CH_LAYOUT_6POINT1_BACK | 0x13F | 6.1 back. | 502| CH_LAYOUT_6POINT1_FRONT | 0x6CB | 6.1 front. | 503| CH_LAYOUT_7POINT0 | 0x637 | 7.0. | 504| CH_LAYOUT_7POINT0_FRONT | 0x6C7 | 7.0 front. | 505| CH_LAYOUT_7POINT1 | 0x63F | 7.1. | 506| CH_LAYOUT_OCTAGONAL | 0x737 | Octagonal. | 507| CH_LAYOUT_5POINT1POINT2 | 0x300000060F | 5.1.2. | 508| CH_LAYOUT_7POINT1_WIDE | 0x6CF | 7.1 wide. | 509| CH_LAYOUT_7POINT1_WIDE_BACK | 0xFF | 7.1 wide back. | 510| CH_LAYOUT_AMB_ORDER2_ACN_N3D | 0x100000000002 | Second-order HOA file in ACN_N3D (ITU standards). | 511| CH_LAYOUT_AMB_ORDER2_ACN_SN3D | 0x100000001002 | Second-order HOA file in ACN_SN3D (ITU standards).| 512| CH_LAYOUT_AMB_ORDER2_FUMA | 0x100000000102 | Second-order HOA file in FUMA (ITU standards). | 513| CH_LAYOUT_5POINT1POINT4 | 0x2D60F | 5.1.4. | 514| CH_LAYOUT_7POINT1POINT2 | 0x300000063F | 7.1.2. | 515| CH_LAYOUT_7POINT1POINT4 | 0x2D63F | 7.1.4. | 516| CH_LAYOUT_10POINT2 | 0x180005737 | 10.2. | 517| CH_LAYOUT_9POINT1POINT4 | 0x18002D63F | 9.1.4. | 518| CH_LAYOUT_9POINT1POINT6 | 0x318002D63F | 9.1.6. | 519| CH_LAYOUT_HEXADECAGONAL | 0x18003F737 | Hexadecagonal. | 520| CH_LAYOUT_AMB_ORDER3_ACN_N3D | 0x100000000003 | Third-order HOA file in ACN_N3D (ITU standards). | 521| CH_LAYOUT_AMB_ORDER3_ACN_SN3D | 0x100000001003 | Third-order HOA file in ACN_SN3D (ITU standards).| 522| CH_LAYOUT_AMB_ORDER3_FUMA | 0x100000000103 | Third-order HOA file in FUMA (ITU standards). | 523 524## ContentType<sup>(deprecated)</sup> 525 526Enumerates the audio content types. 527 528> **NOTE** 529> 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. 530 531**System capability**: SystemCapability.Multimedia.Audio.Core 532 533| Name | Value | Description | 534| ---------------------------------- | ------ | ---------- | 535| CONTENT_TYPE_UNKNOWN | 0 | Unknown content.| 536| CONTENT_TYPE_SPEECH | 1 | Speech. | 537| CONTENT_TYPE_MUSIC | 2 | Music. | 538| CONTENT_TYPE_MOVIE | 3 | Movie. | 539| CONTENT_TYPE_SONIFICATION | 4 | Notification tone. | 540| CONTENT_TYPE_RINGTONE<sup>8+</sup> | 5 | Ringtone. | 541 542## StreamUsage 543 544Enumerates the audio stream usage. 545 546**System capability**: SystemCapability.Multimedia.Audio.Core 547 548| Name | Value | Description | 549| ------------------------------------------| ------ |---------------------------------------------------------------------------------------------------------------------------------------------| 550| STREAM_USAGE_UNKNOWN | 0 | Unknown content.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 551| 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.| 552| STREAM_USAGE_MUSIC<sup>10+</sup> | 1 | Music.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 553| STREAM_USAGE_VOICE_COMMUNICATION | 2 | VoIP voice call.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 554| 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. | 555| 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. | 556| 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. | 557| 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. | 558| STREAM_USAGE_RINGTONE<sup>10+</sup> | 6 | Ringtone.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 559| STREAM_USAGE_NOTIFICATION<sup>10+</sup> | 7 | Notification.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 560| STREAM_USAGE_ACCESSIBILITY<sup>10+</sup> | 8 | Accessibility.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 561| 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. | 562| STREAM_USAGE_GAME<sup>10+</sup> | 11 | Gaming.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 563| 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. | 564| STREAM_USAGE_NAVIGATION<sup>10+</sup> | 13 | Navigation.<br>**Atomic service API**: This API can be used in atomic services since API version 12. | 565| 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. | 566 567## AudioState<sup>8+</sup> 568 569Enumerates the audio states. 570 571**System capability**: SystemCapability.Multimedia.Audio.Core 572 573| Name | Value | Description | 574| -------------- | ------ | ---------------- | 575| STATE_INVALID | -1 | Invalid state. | 576| STATE_NEW | 0 | Creating instance state.| 577| STATE_PREPARED | 1 | Prepared. | 578| STATE_RUNNING | 2 | Running.| 579| STATE_STOPPED | 3 | Stopped. | 580| STATE_RELEASED | 4 | Released. | 581| STATE_PAUSED | 5 | Paused. | 582 583## AudioEffectMode<sup>10+</sup> 584 585Enumerates the audio effect modes. 586 587**Atomic service API**: This API can be used in atomic services since API version 12. 588 589**System capability**: SystemCapability.Multimedia.Audio.Renderer 590 591| Name | Value | Description | 592| ------------------ | ------ | ---------- | 593| EFFECT_NONE | 0 | The audio effect is disabled.| 594| EFFECT_DEFAULT | 1 | The default audio effect is used.| 595 596## AudioRendererRate<sup>8+</sup> 597 598Enumerates the audio renderer rates. 599 600**System capability**: SystemCapability.Multimedia.Audio.Renderer 601 602| Name | Value | Description | 603| ------------------ | ------ | ---------- | 604| RENDER_RATE_NORMAL | 0 | Normal rate.| 605| RENDER_RATE_DOUBLE | 1 | Double rate. | 606| RENDER_RATE_HALF | 2 | Half rate. | 607 608## InterruptType 609 610Enumerates the audio interruption types. 611 612**Atomic service API**: This API can be used in atomic services since API version 12. 613 614**System capability**: SystemCapability.Multimedia.Audio.Renderer 615 616| Name | Value | Description | 617| -------------------- | ------ | ---------------------- | 618| INTERRUPT_TYPE_BEGIN | 1 | Audio interruption started.| 619| INTERRUPT_TYPE_END | 2 | Audio interruption ended.| 620 621## InterruptForceType<sup>9+</sup> 622 623Enumerates the types of force that causes audio interruption. 624 625The force type is obtained when an [InterruptEvent](#interruptevent9) is received. 626 627This 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 [Processing Audio Interruption Events](../../media/audio/audio-playback-concurrency.md). 628 629**Atomic service API**: This API can be used in atomic services since API version 12. 630 631**System capability**: SystemCapability.Multimedia.Audio.Renderer 632 633| Name | Value | Description | 634| --------------- | ------ | ------------------------------------ | 635| INTERRUPT_FORCE | 0 | The operation is forcibly performed by the system. | 636| 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.| 637 638## InterruptHint 639 640Enumerates the hints provided along with audio interruption. 641 642The hint is obtained when an [InterruptEvent](#interruptevent9) is received. 643 644The hint specifies the operation (such as audio pause or volume adjustment) to be performed on audio streams based on the focus policy. 645 646You 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 [Processing Audio Interruption Events](../../media/audio/audio-playback-concurrency.md). 647 648**Atomic service API**: This API can be used in atomic services since API version 12. 649 650**System capability**: SystemCapability.Multimedia.Audio.Renderer 651 652| Name | Value | Description | 653| ---------------------------------- | ------ | -------------------------------------------- | 654| INTERRUPT_HINT_NONE<sup>8+</sup> | 0 | None. | 655| 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**.| 656| 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. | 657| INTERRUPT_HINT_STOP | 3 | A hint is displayed, indicating that the audio stream stops and the audio focus is lost. | 658| INTERRUPT_HINT_DUCK | 4 | A hint is displayed, indicating that audio ducking starts and the audio is played at a lower volume.| 659| 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. | 660 661## AudioStreamInfo<sup>8+</sup> 662 663Describes audio stream information. 664 665**System capability**: SystemCapability.Multimedia.Audio.Core 666 667| Name | Type | Mandatory| Description | 668| ------------ | ------------------------------------------------- | ---- | ------------------ | 669| samplingRate | [AudioSamplingRate](#audiosamplingrate8) | Yes | Audio sampling rate.| 670| channels | [AudioChannel](#audiochannel8) | Yes | Number of audio channels.| 671| sampleFormat | [AudioSampleFormat](#audiosampleformat8) | Yes | Audio sample format. | 672| encodingType | [AudioEncodingType](#audioencodingtype8) | Yes | Audio encoding type. | 673| channelLayout<sup>11+</sup> | [AudioChannelLayout](#audiochannellayout11) | No | Audio channel layout. The default value is **0x0**.| 674 675## AudioRendererInfo<sup>8+</sup> 676 677Describes audio renderer information. 678 679**System capability**: SystemCapability.Multimedia.Audio.Core 680 681| Name | Type | Mandatory | Description | 682| ------------- | --------------------------- | ---- | ---------------- | 683| 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.| 684| usage | [StreamUsage](#streamusage) | Yes | Audio stream usage.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 685| 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.| 686 687## AudioRendererOptions<sup>8+</sup> 688 689Describes audio renderer configurations. 690 691| Name | Type | Mandatory | Description | 692| ------------ | ---------------------------------------- | ---- | ---------------- | 693| streamInfo | [AudioStreamInfo](#audiostreaminfo8) | Yes | Audio stream information.<br>**System capability**: SystemCapability.Multimedia.Audio.Renderer| 694| rendererInfo | [AudioRendererInfo](#audiorendererinfo8) | Yes | Audio renderer information.<br>**System capability**: SystemCapability.Multimedia.Audio.Renderer| 695| 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| 696 697## AudioPrivacyType<sup>10+</sup> 698 699Enumerates whether an audio stream can be recorded by other applications. 700 701**System capability**: SystemCapability.Multimedia.Audio.PlaybackCapture 702 703| Name | Value | Description | 704| -------------------- | ---- | -------------------------------- | 705| PRIVACY_TYPE_PUBLIC | 0 | The audio stream can be recorded by other applications. | 706| PRIVACY_TYPE_PRIVATE | 1 | The audio stream cannot be recorded by other applications.| 707 708## InterruptEvent<sup>9+</sup> 709 710Describes the interruption event received by the application when playback is interrupted. 711 712**Atomic service API**: This API can be used in atomic services since API version 12. 713 714**System capability**: SystemCapability.Multimedia.Audio.Renderer 715 716| Name | Type |Mandatory | Description | 717| --------- | ------------------------------------------ | ---- | ------------------------------------ | 718| eventType | [InterruptType](#interrupttype) | Yes | Whether the interruption has started or ended. | 719| forceType | [InterruptForceType](#interruptforcetype9) | Yes | Whether the interruption is taken by the system or to be taken by the application.| 720| hintType | [InterruptHint](#interrupthint) | Yes | Hint provided along the interruption. | 721 722## VolumeEvent<sup>9+</sup> 723 724Describes the event received by the application when the volume is changed. 725 726**System capability**: SystemCapability.Multimedia.Audio.Volume 727 728| Name | Type | Mandatory | Description | 729| ---------- | ----------------------------------- | ---- |-------------------------------------------| 730| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 731| volume | number | Yes | Volume to set. The value range can be obtained by calling **getMinVolume** and **getMaxVolume**. | 732| 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. | 733 734## MicStateChangeEvent<sup>9+</sup> 735 736Describes the event received by the application when the microphone mute status is changed. 737 738**System capability**: SystemCapability.Multimedia.Audio.Device 739 740| Name | Type | Mandatory| Description | 741| ---------- | ----------------------------------- | ---- |-------------------------------------------------------- | 742| mute | boolean | Yes | Mute status of the microphone. The value **true** means that the microphone is muted, and **false** means the opposite. | 743 744## DeviceChangeAction 745 746Describes the device connection status and device information. 747 748**System capability**: SystemCapability.Multimedia.Audio.Device 749 750| Name | Type | Mandatory| Description | 751| :---------------- | :------------------------------------------------ | :--- | :----------------- | 752| type | [DeviceChangeType](#devicechangetype) | Yes | Device connection status.| 753| deviceDescriptors | [AudioDeviceDescriptors](#audiodevicedescriptors) | Yes | Device information. | 754 755## ChannelBlendMode<sup>11+</sup> 756 757Enumerates the audio channel blending modes. 758 759**System capability**: SystemCapability.Multimedia.Audio.Core 760 761| Name | Value | Description | 762| :------------------------------------------- | :----- | :--------------------- | 763| MODE_DEFAULT | 0 | The audio channels are not blended. | 764| MODE_BLEND_LR | 1 | The left and right audio channels are blended.| 765| MODE_ALL_LEFT | 2 | The left channel is replicated into the right channel. | 766| MODE_ALL_RIGHT | 3 | The right channel is replicated into the left channel.| 767 768## AudioStreamDeviceChangeReason<sup>11+</sup> 769 770Enumerates the reasons for audio stream device is changed. 771 772**Atomic service API**: This API can be used in atomic services since API version 12. 773 774**System capability**: SystemCapability.Multimedia.Audio.Device 775 776| Name | Value | Description | 777|:------------------------------------------| :----- |:----------------| 778| REASON_UNKNOWN | 0 | Unknown reason. | 779| REASON_NEW_DEVICE_AVAILABLE | 1 | A new device is available. | 780| REASON_OLD_DEVICE_UNAVAILABLE | 2 | The old device is unavailable. When this reason is reported, the application should consider pausing audio playback.| 781| REASON_OVERRODE | 3 | Forcibly selected.| 782 783## AudioStreamDeviceChangeInfo<sup>11+</sup> 784 785Describes the event received by the application when the audio stream device is changed. 786 787**Atomic service API**: This API can be used in atomic services since API version 12. 788 789**System capability**: SystemCapability.Multimedia.Audio.Device 790 791| Name | Type | Mandatory| Description | 792| :---------------- |:------------------------------------------------------------------| :--- | :----------------- | 793| devices | [AudioDeviceDescriptors](#audiodevicedescriptors) | Yes | Device information.| 794| changeReason | [AudioStreamDeviceChangeReason](#audiostreamdevicechangereason11) | Yes | Reason for the change.| 795 796## DeviceChangeType 797 798Enumerates the device connection statuses. 799 800**System capability**: SystemCapability.Multimedia.Audio.Device 801 802| Name | Value | Description | 803| :--------- | :--- | :------------- | 804| CONNECT | 0 | Connected. | 805| DISCONNECT | 1 | Disconnected.| 806 807## AudioCapturerOptions<sup>8+</sup> 808 809Describes audio capturer configurations. 810 811| Name | Type | Mandatory| Description | 812| ----------------------------------- | --------------------------------------------------------- | ---- | ------------------------------------------------------------ | 813| streamInfo | [AudioStreamInfo](#audiostreaminfo8) | Yes | Audio stream information.<br>**System capability**: SystemCapability.Multimedia.Audio.Capturer | 814| capturerInfo | [AudioCapturerInfo](#audiocapturerinfo8) | Yes | Audio capturer information.<br>**System capability**: SystemCapability.Multimedia.Audio.Capturer | 815| 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.| 816 817## AudioCapturerInfo<sup>8+</sup> 818 819Describes audio capturer information. 820 821**System capability**: SystemCapability.Multimedia.Audio.Core 822 823| Name | Type | Mandatory| Description | 824| :------------ | :------------------------ | :--- | :--------------- | 825| source | [SourceType](#sourcetype8) | Yes | Audio source type. | 826| capturerFlags | number | Yes | Audio capturer flags.<br>The value **0** means an audio capturer.| 827 828## SourceType<sup>8+</sup> 829 830Enumerates the audio source types. 831 832| Name | Value | Description | 833| :------------------------------------------- | :----- | :--------------------- | 834| SOURCE_TYPE_INVALID | -1 | Invalid audio source.<br>**System capability**: SystemCapability.Multimedia.Audio.Core | 835| SOURCE_TYPE_MIC | 0 | Mic source.<br>**System capability**: SystemCapability.Multimedia.Audio.Core| 836| SOURCE_TYPE_VOICE_RECOGNITION<sup>9+</sup> | 1 | Voice recognition source.<br>**System capability**: SystemCapability.Multimedia.Audio.Core | 837| 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.| 838| SOURCE_TYPE_VOICE_COMMUNICATION | 7 | Voice communication source.<br>**System capability**: SystemCapability.Multimedia.Audio.Core| 839| SOURCE_TYPE_VOICE_MESSAGE<sup>12+</sup> | 10 | Voice message source.<br>**System capability**: SystemCapability.Multimedia.Audio.Core| 840 841## AudioPlaybackCaptureConfig<sup>(deprecated)</sup> 842 843Defines the configuration of internal audio recording. 844 845> **NOTE** 846> 847> 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. 848 849**System capability**: SystemCapability.Multimedia.Audio.PlaybackCapture 850 851| Name | Type | Mandatory| Description | 852| ------------- | --------------------------------------------- | ---- | -------------------------------- | 853| filterOptions | [CaptureFilterOptions](#capturefilteroptionsdeprecated) | Yes | Options for filtering the played audio streams to be recorded.| 854 855## CaptureFilterOptions<sup>(deprecated)</sup> 856 857Defines the options for filtering the played audio streams to be recorded. 858 859> **NOTE** 860> 861> 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 863**Required permissions**: ohos.permission.CAPTURE_VOICE_DOWNLINK_AUDIO 864 865- 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. 866 867- Since API version 11, **CaptureFilterOptions** does not support **StreamUsage.STREAM_USAGE_VOICE_COMMUNICATION**. Therefore, no permission is required for calling this API. 868 869**System capability**: SystemCapability.Multimedia.Audio.PlaybackCapture 870 871| Name | Type | Mandatory| Description | 872| ------ | ---------------------------------- | ---- | ------------------------------------------------------------ | 873| 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.| 874 875## AudioScene<sup>8+</sup> 876 877Enumerates the audio scenes. 878 879**System capability**: SystemCapability.Multimedia.Audio.Communication 880 881| Name | Value | Description | 882| :--------------------- | :----- | :-------------------------------------------- | 883| AUDIO_SCENE_DEFAULT | 0 | Default audio scene. | 884| AUDIO_SCENE_RINGING<sup>12+</sup> | 1 | Normal mode.| 885| AUDIO_SCENE_PHONE_CALL<sup>12+</sup> | 2 | Phone call scene.| 886| AUDIO_SCENE_VOICE_CHAT | 3 | Voice chat scene. | 887 888## AudioConcurrencyMode<sup>12+</sup> 889 890Enumerates the audio concurrency modes. 891 892**System capability**: SystemCapability.Multimedia.Audio.Core 893 894| Name | Value| Description | 895| :--------------------- |:--|:--------| 896| CONCURRENCY_DEFAULT | 0 | Uses the system strategy by default. | 897| CONCURRENCY_MIX_WITH_OTHERS | 1 | Mixes audio with other applications that are playing audio. | 898| CONCURRENCY_DUCK_OTHERS | 2 | Lowers the volume of the application that is currently playing the audio.| 899| CONCURRENCY_PAUSE_OTHERS | 3 | Pauses the application that is currently playing the audio.| 900 901## AudioSessionDeactivatedReason<sup>12+</sup> 902 903Enumerates the reasons for deactivating an audio session. 904 905**System capability**: SystemCapability.Multimedia.Audio.Core 906 907| Name | Value| Description | 908| :--------------------- |:--|:-------| 909| DEACTIVATED_LOWER_PRIORITY | 0 | The application focus is preempted.| 910| DEACTIVATED_TIME_OUT | 1 | The application times out after the stream is stopped. | 911 912## AudioSessionStrategy<sup>12+</sup> 913 914Describes an audio session strategy. 915 916**System capability**: SystemCapability.Multimedia.Audio.Core 917 918| Name | Type | Mandatory| Description | 919| :------------ |:------------------------------------------------| :--- | :--------------- | 920| concurrencyMode | [AudioConcurrencyMode](#audioconcurrencymode12) | Yes | Audio concurrency mode. | 921 922## AudioSessionDeactivatedEvent<sup>12+</sup> 923 924Describes the event indicating that an audio session is deactivated. 925 926**System capability**: SystemCapability.Multimedia.Audio.Core 927 928| Name | Type | Mandatory| Description | 929| :------------ |:------------------------------------------------------------------| :--- | :--------------- | 930| reason | [AudioSessionDeactivatedReason](#audiosessiondeactivatedreason12) | Yes | Reason for deactivating an audio session. | 931 932## AudioManager 933 934Implements audio volume and audio device management. Before calling any API in **AudioManager**, you must use [getAudioManager](#audiogetaudiomanager) to create an **AudioManager** instance. 935 936### setAudioParameter<sup>(deprecated)</sup> 937 938setAudioParameter(key: string, value: string, callback: AsyncCallback<void>): void 939 940Sets an audio parameter. This API uses an asynchronous callback to return the result. 941 942This 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. 943 944> **NOTE** 945> 946> This API is supported since API version 7 and deprecated since API version 11. The substitute API is available only for system applications. 947 948**Required permissions**: ohos.permission.MODIFY_AUDIO_SETTINGS 949 950**System capability**: SystemCapability.Multimedia.Audio.Core 951 952**Parameters** 953 954| Name | Type | Mandatory| Description | 955| -------- | ------------------------- | ---- | ------------------------ | 956| key | string | Yes | Key of the audio parameter to set. | 957| value | string | Yes | Value of the audio parameter to set. | 958| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 959 960**Example** 961 962```ts 963import { BusinessError } from '@kit.BasicServicesKit'; 964 965audioManager.setAudioParameter('key_example', 'value_example', (err: BusinessError) => { 966 if (err) { 967 console.error(`Failed to set the audio parameter. ${err}`); 968 return; 969 } 970 console.info('Callback invoked to indicate a successful setting of the audio parameter.'); 971}); 972``` 973 974### setAudioParameter<sup>(deprecated)</sup> 975 976setAudioParameter(key: string, value: string): Promise<void> 977 978Sets an audio parameter. This API uses a promise to return the result. 979 980This 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. 981 982> **NOTE** 983> 984> This API is supported since API version 7 and deprecated since API version 11. The substitute API is available only for system applications. 985 986**Required permissions**: ohos.permission.MODIFY_AUDIO_SETTINGS 987 988**System capability**: SystemCapability.Multimedia.Audio.Core 989 990**Parameters** 991 992| Name| Type | Mandatory| Description | 993| ------ | ------ | ---- | ---------------------- | 994| key | string | Yes | Key of the audio parameter to set.| 995| value | string | Yes | Value of the audio parameter to set.| 996 997**Return value** 998 999| Type | Description | 1000| ------------------- | ------------------------------- | 1001| Promise<void> | Promise that returns no value.| 1002 1003**Example** 1004 1005```ts 1006audioManager.setAudioParameter('key_example', 'value_example').then(() => { 1007 console.info('Promise returned to indicate a successful setting of the audio parameter.'); 1008}); 1009``` 1010 1011### getAudioParameter<sup>(deprecated)</sup> 1012 1013getAudioParameter(key: string, callback: AsyncCallback<string>): void 1014 1015Obtains the value of an audio parameter. This API uses an asynchronous callback to return the result. 1016 1017This 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. 1018 1019> **NOTE** 1020> 1021> This API is supported since API version 7 and deprecated since API version 11. The substitute API is available only for system applications. 1022 1023**System capability**: SystemCapability.Multimedia.Audio.Core 1024 1025**Parameters** 1026 1027| Name | Type | Mandatory| Description | 1028| -------- | --------------------------- | ---- | ---------------------------- | 1029| key | string | Yes | Key of the audio parameter whose value is to be obtained. | 1030| 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.| 1031 1032**Example** 1033 1034```ts 1035import { BusinessError } from '@kit.BasicServicesKit'; 1036 1037audioManager.getAudioParameter('key_example', (err: BusinessError, value: string) => { 1038 if (err) { 1039 console.error(`Failed to obtain the value of the audio parameter. ${err}`); 1040 return; 1041 } 1042 console.info(`Callback invoked to indicate that the value of the audio parameter is obtained ${value}.`); 1043}); 1044``` 1045 1046### getAudioParameter<sup>(deprecated)</sup> 1047 1048getAudioParameter(key: string): Promise<string> 1049 1050Obtains the value of an audio parameter. This API uses a promise to return the result. 1051 1052This 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. 1053 1054> **NOTE** 1055> 1056> This API is supported since API version 7 and deprecated since API version 11. The substitute API is available only for system applications. 1057 1058**System capability**: SystemCapability.Multimedia.Audio.Core 1059 1060**Parameters** 1061 1062| Name| Type | Mandatory| Description | 1063| ------ | ------ | ---- | ---------------------- | 1064| key | string | Yes | Key of the audio parameter whose value is to be obtained.| 1065 1066**Return value** 1067 1068| Type | Description | 1069| --------------------- | ----------------------------------- | 1070| Promise<string> | Promise used to return the value of the audio parameter.| 1071 1072**Example** 1073 1074```ts 1075audioManager.getAudioParameter('key_example').then((value: string) => { 1076 console.info(`Promise returned to indicate that the value of the audio parameter is obtained ${value}.`); 1077}); 1078``` 1079 1080### getAudioScene<sup>8+</sup> 1081 1082getAudioScene\(callback: AsyncCallback<AudioScene\>\): void 1083 1084Obtains the audio scene. This API uses an asynchronous callback to return the result. 1085 1086**System capability**: SystemCapability.Multimedia.Audio.Communication 1087 1088**Parameters** 1089 1090| Name | Type | Mandatory| Description | 1091| :------- | :-------------------------------------------------- | :--- | :--------------------------- | 1092| 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.| 1093 1094**Example** 1095 1096```ts 1097import { BusinessError } from '@kit.BasicServicesKit'; 1098 1099audioManager.getAudioScene((err: BusinessError, value: audio.AudioScene) => { 1100 if (err) { 1101 console.error(`Failed to obtain the audio scene mode. ${err}`); 1102 return; 1103 } 1104 console.info(`Callback invoked to indicate that the audio scene mode is obtained ${value}.`); 1105}); 1106``` 1107 1108### getAudioScene<sup>8+</sup> 1109 1110getAudioScene\(\): Promise<AudioScene\> 1111 1112Obtains the audio scene. This API uses a promise to return the result. 1113 1114**System capability**: SystemCapability.Multimedia.Audio.Communication 1115 1116**Return value** 1117 1118| Type | Description | 1119| :-------------------------------------------- | :--------------------------- | 1120| Promise<[AudioScene](#audioscene8)> | Promise used to return the audio scene.| 1121 1122**Example** 1123 1124```ts 1125import { BusinessError } from '@kit.BasicServicesKit'; 1126 1127audioManager.getAudioScene().then((value: audio.AudioScene) => { 1128 console.info(`Promise returned to indicate that the audio scene mode is obtained ${value}.`); 1129}).catch ((err: BusinessError) => { 1130 console.error(`Failed to obtain the audio scene mode ${err}`); 1131}); 1132``` 1133 1134### getAudioSceneSync<sup>10+</sup> 1135 1136getAudioSceneSync\(\): AudioScene 1137 1138Obtains the audio scene. This API returns the result synchronously. 1139 1140**System capability**: SystemCapability.Multimedia.Audio.Communication 1141 1142**Return value** 1143 1144| Type | Description | 1145| :-------------------------------------------- | :--------------------------- | 1146| [AudioScene](#audioscene8) | Audio scene.| 1147 1148**Example** 1149 1150```ts 1151import { BusinessError } from '@kit.BasicServicesKit'; 1152 1153try { 1154 let value: audio.AudioScene = audioManager.getAudioSceneSync(); 1155 console.info(`indicate that the audio scene mode is obtained ${value}.`); 1156} catch (err) { 1157 let error = err as BusinessError; 1158 console.error(`Failed to obtain the audio scene mode ${error}`); 1159} 1160``` 1161 1162### getVolumeManager<sup>9+</sup> 1163 1164getVolumeManager(): AudioVolumeManager 1165 1166Obtains an **AudioVolumeManager** instance. 1167 1168**System capability**: SystemCapability.Multimedia.Audio.Volume 1169 1170**Return value** 1171 1172| Type | Description | 1173|-----------------------------------------| ----------------------------- | 1174| [AudioVolumeManager](#audiovolumemanager9) | **AudioVolumeManager** instance.| 1175 1176**Example** 1177 1178```ts 1179import { audio } from '@kit.AudioKit'; 1180 1181let audioVolumeManager: audio.AudioVolumeManager = audioManager.getVolumeManager(); 1182``` 1183 1184### getStreamManager<sup>9+</sup> 1185 1186getStreamManager(): AudioStreamManager 1187 1188Obtains an **AudioStreamManager** instance. 1189 1190**System capability**: SystemCapability.Multimedia.Audio.Core 1191 1192**Return value** 1193 1194| Type | Description | 1195|--------------------------------------------| ----------------------------- | 1196| [AudioStreamManager](#audiostreammanager9) | **AudioStreamManager** instance.| 1197 1198**Example** 1199 1200```ts 1201import { audio } from '@kit.AudioKit'; 1202 1203let audioStreamManager: audio.AudioStreamManager = audioManager.getStreamManager(); 1204``` 1205 1206### getRoutingManager<sup>9+</sup> 1207 1208getRoutingManager(): AudioRoutingManager 1209 1210Obtains an **AudioRoutingManager** instance. 1211 1212**System capability**: SystemCapability.Multimedia.Audio.Device 1213 1214**Return value** 1215 1216| Type | Description | 1217|------------------------------------------| ----------------------------- | 1218| [AudioRoutingManager](#audioroutingmanager9) | **AudioRoutingManager** instance.| 1219 1220**Example** 1221 1222```ts 1223import { audio } from '@kit.AudioKit'; 1224 1225let audioRoutingManager: audio.AudioRoutingManager = audioManager.getRoutingManager(); 1226``` 1227 1228### getSessionManager<sup>12+</sup> 1229 1230getSessionManager(): AudioSessionManager 1231 1232Obtains an **AudioSessionManager** instance. 1233 1234**System capability**: SystemCapability.Multimedia.Audio.Core 1235 1236**Return value** 1237 1238| Type | Description | 1239|----------------------------------------------| ----------------------------- | 1240| [AudioSessionManager](#audiosessionmanager12) | **AudioSessionManager** instance.| 1241 1242**Example** 1243 1244```ts 1245import { audio } from '@kit.AudioKit'; 1246 1247let audioSessionManager: audio.AudioSessionManager = audioManager.getSessionManager(); 1248``` 1249 1250### setVolume<sup>(deprecated)</sup> 1251 1252setVolume(volumeType: AudioVolumeType, volume: number, callback: AsyncCallback<void>): void 1253 1254Sets the volume for a stream. This API uses an asynchronous callback to return the result. 1255 1256> **NOTE** 1257> 1258> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setVolume](#setvolume9) in **AudioVolumeGroupManager**. The substitute API is available only for system applications. 1259 1260**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 1261 1262This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**. 1263 1264**System capability**: SystemCapability.Multimedia.Audio.Volume 1265 1266**Parameters** 1267 1268| Name | Type | Mandatory| Description | 1269| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 1270| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1271| volume | number | Yes | Volume to set. The value range can be obtained by calling [getMinVolume](#getminvolumedeprecated) and [getMaxVolume](#getmaxvolumedeprecated).| 1272| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1273 1274**Example** 1275 1276```ts 1277import { BusinessError } from '@kit.BasicServicesKit'; 1278 1279audioManager.setVolume(audio.AudioVolumeType.MEDIA, 10, (err: BusinessError) => { 1280 if (err) { 1281 console.error(`Failed to set the volume. ${err}`); 1282 return; 1283 } 1284 console.info('Callback invoked to indicate a successful volume setting.'); 1285}); 1286``` 1287 1288### setVolume<sup>(deprecated)</sup> 1289 1290setVolume(volumeType: AudioVolumeType, volume: number): Promise<void> 1291 1292Sets the volume for a stream. This API uses a promise to return the result. 1293 1294> **NOTE** 1295> 1296> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setVolume](#setvolume9) in **AudioVolumeGroupManager**. The substitute API is available only for system applications. 1297 1298**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 1299 1300This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**. 1301 1302**System capability**: SystemCapability.Multimedia.Audio.Volume 1303 1304**Parameters** 1305 1306| Name | Type | Mandatory| Description | 1307| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 1308| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1309| volume | number | Yes | Volume to set. The value range can be obtained by calling [getMinVolume](#getminvolumedeprecated) and [getMaxVolume](#getmaxvolumedeprecated).| 1310 1311**Return value** 1312 1313| Type | Description | 1314| ------------------- | ----------------------------- | 1315| Promise<void> | Promise that returns no value.| 1316 1317**Example** 1318 1319```ts 1320audioManager.setVolume(audio.AudioVolumeType.MEDIA, 10).then(() => { 1321 console.info('Promise returned to indicate a successful volume setting.'); 1322}); 1323``` 1324 1325### getVolume<sup>(deprecated)</sup> 1326 1327getVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 1328 1329Obtains the volume of a stream. This API uses an asynchronous callback to return the result. 1330 1331> **NOTE** 1332> 1333> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getVolume](#getvolume9) in **AudioVolumeGroupManager**. 1334 1335**System capability**: SystemCapability.Multimedia.Audio.Volume 1336 1337**Parameters** 1338 1339| Name | Type | Mandatory| Description | 1340| ---------- | ----------------------------------- | ---- | ------------------ | 1341| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1342| 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).| 1343 1344**Example** 1345 1346```ts 1347import { BusinessError } from '@kit.BasicServicesKit'; 1348 1349audioManager.getVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { 1350 if (err) { 1351 console.error(`Failed to obtain the volume. ${err}`); 1352 return; 1353 } 1354 console.info('Callback invoked to indicate that the volume is obtained.'); 1355}); 1356``` 1357 1358### getVolume<sup>(deprecated)</sup> 1359 1360getVolume(volumeType: AudioVolumeType): Promise<number> 1361 1362Obtains the volume of a stream. This API uses a promise to return the result. 1363 1364> **NOTE** 1365> 1366> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getVolume](#getvolume9) in **AudioVolumeGroupManager**. 1367 1368**System capability**: SystemCapability.Multimedia.Audio.Volume 1369 1370**Parameters** 1371 1372| Name | Type | Mandatory| Description | 1373| ---------- | ----------------------------------- | ---- | ------------ | 1374| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 1375 1376**Return value** 1377 1378| Type | Description | 1379| --------------------- | ------------------------- | 1380| 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).| 1381 1382**Example** 1383 1384```ts 1385audioManager.getVolume(audio.AudioVolumeType.MEDIA).then((value: number) => { 1386 console.info(`Promise returned to indicate that the volume is obtained ${value} .`); 1387}); 1388``` 1389 1390### getMinVolume<sup>(deprecated)</sup> 1391 1392getMinVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 1393 1394Obtains the minimum volume allowed for a stream. This API uses an asynchronous callback to return the result. 1395 1396> **NOTE** 1397> 1398> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getMinVolume](#getminvolume9) in **AudioVolumeGroupManager**. 1399 1400**System capability**: SystemCapability.Multimedia.Audio.Volume 1401 1402**Parameters** 1403 1404| Name | Type | Mandatory| Description | 1405| ---------- | ----------------------------------- | ---- | ------------------ | 1406| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1407| 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.| 1408 1409**Example** 1410 1411```ts 1412import { BusinessError } from '@kit.BasicServicesKit'; 1413 1414audioManager.getMinVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { 1415 if (err) { 1416 console.error(`Failed to obtain the minimum volume. ${err}`); 1417 return; 1418 } 1419 console.info(`Callback invoked to indicate that the minimum volume is obtained. ${value}`); 1420}); 1421``` 1422 1423### getMinVolume<sup>(deprecated)</sup> 1424 1425getMinVolume(volumeType: AudioVolumeType): Promise<number> 1426 1427Obtains the minimum volume allowed for a stream. This API uses a promise to return the result. 1428 1429> **NOTE** 1430> 1431> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getMinVolume](#getminvolume9) in **AudioVolumeGroupManager**. 1432 1433**System capability**: SystemCapability.Multimedia.Audio.Volume 1434 1435**Parameters** 1436 1437| Name | Type | Mandatory| Description | 1438| ---------- | ----------------------------------- | ---- | ------------ | 1439| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 1440 1441**Return value** 1442 1443| Type | Description | 1444| --------------------- | ------------------------- | 1445| Promise<number> | Promise used to return the minimum volume.| 1446 1447**Example** 1448 1449```ts 1450audioManager.getMinVolume(audio.AudioVolumeType.MEDIA).then((value: number) => { 1451 console.info(`Promised returned to indicate that the minimum volume is obtained. ${value}`); 1452}); 1453``` 1454 1455### getMaxVolume<sup>(deprecated)</sup> 1456 1457getMaxVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 1458 1459Obtains the maximum volume allowed for a stream. This API uses an asynchronous callback to return the result. 1460 1461> **NOTE** 1462> 1463> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getMaxVolume](#getmaxvolume9) in **AudioVolumeGroupManager**. 1464 1465**System capability**: SystemCapability.Multimedia.Audio.Volume 1466 1467**Parameters** 1468 1469| Name | Type | Mandatory| Description | 1470| ---------- | ----------------------------------- | ---- | ---------------------- | 1471| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1472| 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.| 1473 1474**Example** 1475 1476```ts 1477import { BusinessError } from '@kit.BasicServicesKit'; 1478 1479audioManager.getMaxVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { 1480 if (err) { 1481 console.error(`Failed to obtain the maximum volume. ${err}`); 1482 return; 1483 } 1484 console.info(`Callback invoked to indicate that the maximum volume is obtained. ${value}`); 1485}); 1486``` 1487 1488### getMaxVolume<sup>(deprecated)</sup> 1489 1490getMaxVolume(volumeType: AudioVolumeType): Promise<number> 1491 1492Obtains the maximum volume allowed for a stream. This API uses a promise to return the result. 1493 1494> **NOTE** 1495> 1496> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getMaxVolume](#getmaxvolume9) in **AudioVolumeGroupManager**. 1497 1498**System capability**: SystemCapability.Multimedia.Audio.Volume 1499 1500**Parameters** 1501 1502| Name | Type | Mandatory| Description | 1503| ---------- | ----------------------------------- | ---- | ------------ | 1504| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 1505 1506**Return value** 1507 1508| Type | Description | 1509| --------------------- | ----------------------------- | 1510| Promise<number> | Promise used to return the maximum volume.| 1511 1512**Example** 1513 1514```ts 1515audioManager.getMaxVolume(audio.AudioVolumeType.MEDIA).then((data: number) => { 1516 console.info('Promised returned to indicate that the maximum volume is obtained.'); 1517}); 1518``` 1519 1520### mute<sup>(deprecated)</sup> 1521 1522mute(volumeType: AudioVolumeType, mute: boolean, callback: AsyncCallback<void>): void 1523 1524Mutes or unmutes a stream. This API uses an asynchronous callback to return the result. 1525 1526> **NOTE** 1527> 1528> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 1529 1530**System capability**: SystemCapability.Multimedia.Audio.Volume 1531 1532**Parameters** 1533 1534| Name | Type | Mandatory| Description | 1535| ---------- | ----------------------------------- | ---- | ------------------------------------- | 1536| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1537| mute | boolean | Yes | Mute status to set. The value **true** means to mute the stream, and **false** means the opposite.| 1538| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1539 1540**Example** 1541 1542```ts 1543import { BusinessError } from '@kit.BasicServicesKit'; 1544 1545audioManager.mute(audio.AudioVolumeType.MEDIA, true, (err: BusinessError) => { 1546 if (err) { 1547 console.error(`Failed to mute the stream. ${err}`); 1548 return; 1549 } 1550 console.info('Callback invoked to indicate that the stream is muted.'); 1551}); 1552``` 1553 1554### mute<sup>(deprecated)</sup> 1555 1556mute(volumeType: AudioVolumeType, mute: boolean): Promise<void> 1557 1558Mutes or unmutes a stream. This API uses a promise to return the result. 1559 1560> **NOTE** 1561> 1562> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 1563 1564**System capability**: SystemCapability.Multimedia.Audio.Volume 1565 1566**Parameters** 1567 1568| Name | Type | Mandatory| Description | 1569| ---------- | ----------------------------------- | ---- | ------------------------------------- | 1570| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1571| mute | boolean | Yes | Mute status to set. The value **true** means to mute the stream, and **false** means the opposite.| 1572 1573**Return value** 1574 1575| Type | Description | 1576| ------------------- | ----------------------------- | 1577| Promise<void> | Promise that returns no value.| 1578 1579**Example** 1580 1581 1582```ts 1583audioManager.mute(audio.AudioVolumeType.MEDIA, true).then(() => { 1584 console.info('Promise returned to indicate that the stream is muted.'); 1585}); 1586``` 1587 1588### isMute<sup>(deprecated)</sup> 1589 1590isMute(volumeType: AudioVolumeType, callback: AsyncCallback<boolean>): void 1591 1592Checks whether a stream is muted. This API uses an asynchronous callback to return the result. 1593 1594> **NOTE** 1595> 1596> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isMute](#ismute9) in **AudioVolumeGroupManager**. 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| 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.| 1606 1607**Example** 1608 1609```ts 1610import { BusinessError } from '@kit.BasicServicesKit'; 1611 1612audioManager.isMute(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: boolean) => { 1613 if (err) { 1614 console.error(`Failed to obtain the mute status. ${err}`); 1615 return; 1616 } 1617 console.info(`Callback invoked to indicate that the mute status of the stream is obtained. ${value}`); 1618}); 1619``` 1620 1621### isMute<sup>(deprecated)</sup> 1622 1623isMute(volumeType: AudioVolumeType): Promise<boolean> 1624 1625Checks whether a stream is muted. This API uses a promise to return the result. 1626 1627> **NOTE** 1628> 1629> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isMute](#ismute9) in **AudioVolumeGroupManager**. 1630 1631**System capability**: SystemCapability.Multimedia.Audio.Volume 1632 1633**Parameters** 1634 1635| Name | Type | Mandatory| Description | 1636| ---------- | ----------------------------------- | ---- | ------------ | 1637| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 1638 1639**Return value** 1640 1641| Type | Description | 1642| ---------------------- | ------------------------------------------------------ | 1643| 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.| 1644 1645**Example** 1646 1647```ts 1648audioManager.isMute(audio.AudioVolumeType.MEDIA).then((value: boolean) => { 1649 console.info(`Promise returned to indicate that the mute status of the stream is obtained ${value}.`); 1650}); 1651``` 1652 1653### isActive<sup>(deprecated)</sup> 1654 1655isActive(volumeType: AudioVolumeType, callback: AsyncCallback<boolean>): void 1656 1657Checks whether a stream is active. This API uses an asynchronous callback to return the result. 1658 1659> **NOTE** 1660> 1661> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isActive](#isactive9) in **AudioStreamManager**. 1662 1663**System capability**: SystemCapability.Multimedia.Audio.Volume 1664 1665**Parameters** 1666 1667| Name | Type | Mandatory| Description | 1668| ---------- | ----------------------------------- | ---- | ------------------------------------------------- | 1669| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1670| 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.| 1671 1672**Example** 1673 1674```ts 1675import { BusinessError } from '@kit.BasicServicesKit'; 1676 1677audioManager.isActive(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: boolean) => { 1678 if (err) { 1679 console.error(`Failed to obtain the active status of the stream. ${err}`); 1680 return; 1681 } 1682 console.info(`Callback invoked to indicate that the active status of the stream is obtained ${value}.`); 1683}); 1684``` 1685 1686### isActive<sup>(deprecated)</sup> 1687 1688isActive(volumeType: AudioVolumeType): Promise<boolean> 1689 1690Checks whether a stream is active. This API uses a promise to return the result. 1691 1692> **NOTE** 1693> 1694> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isActive](#isactive9) in **AudioStreamManager**. 1695 1696**System capability**: SystemCapability.Multimedia.Audio.Volume 1697 1698**Parameters** 1699 1700| Name | Type | Mandatory| Description | 1701| ---------- | ----------------------------------- | ---- | ------------ | 1702| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 1703 1704**Return value** 1705 1706| Type | Description | 1707| ---------------------- | -------------------------------------------------------- | 1708| 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.| 1709 1710**Example** 1711 1712```ts 1713audioManager.isActive(audio.AudioVolumeType.MEDIA).then((value: boolean) => { 1714 console.info(`Promise returned to indicate that the active status of the stream is obtained ${value}.`); 1715}); 1716``` 1717 1718### setRingerMode<sup>(deprecated)</sup> 1719 1720setRingerMode(mode: AudioRingMode, callback: AsyncCallback<void>): void 1721 1722Sets the ringer mode. This API uses an asynchronous callback to return the result. 1723 1724> **NOTE** 1725> 1726> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 1727 1728**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 1729 1730This permission is required only for muting or unmuting the ringer. 1731 1732**System capability**: SystemCapability.Multimedia.Audio.Communication 1733 1734**Parameters** 1735 1736| Name | Type | Mandatory| Description | 1737| -------- | ------------------------------- | ---- | ------------------------ | 1738| mode | [AudioRingMode](#audioringmode) | Yes | Ringer mode. | 1739| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1740 1741**Example** 1742 1743```ts 1744import { BusinessError } from '@kit.BasicServicesKit'; 1745 1746audioManager.setRingerMode(audio.AudioRingMode.RINGER_MODE_NORMAL, (err: BusinessError) => { 1747 if (err) { 1748 console.error(`Failed to set the ringer mode. ${err}`); 1749 return; 1750 } 1751 console.info('Callback invoked to indicate a successful setting of the ringer mode.'); 1752}); 1753``` 1754 1755### setRingerMode<sup>(deprecated)</sup> 1756 1757setRingerMode(mode: AudioRingMode): Promise<void> 1758 1759Sets the ringer mode. This API uses a promise to return the result. 1760 1761> **NOTE** 1762> 1763> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 1764 1765 1766**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 1767 1768This permission is required only for muting or unmuting the ringer. 1769 1770**System capability**: SystemCapability.Multimedia.Audio.Communication 1771 1772**Parameters** 1773 1774| Name| Type | Mandatory| Description | 1775| ------ | ------------------------------- | ---- | -------------- | 1776| mode | [AudioRingMode](#audioringmode) | Yes | Ringer mode.| 1777 1778**Return value** 1779 1780| Type | Description | 1781| ------------------- | ------------------------------- | 1782| Promise<void> | Promise that returns no value.| 1783 1784**Example** 1785 1786```ts 1787audioManager.setRingerMode(audio.AudioRingMode.RINGER_MODE_NORMAL).then(() => { 1788 console.info('Promise returned to indicate a successful setting of the ringer mode.'); 1789}); 1790``` 1791 1792### getRingerMode<sup>(deprecated)</sup> 1793 1794getRingerMode(callback: AsyncCallback<AudioRingMode>): void 1795 1796Obtains the ringer mode. This API uses an asynchronous callback to return the result. 1797 1798> **NOTE** 1799> 1800> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getRingerMode](#getringermode9) in **AudioVolumeGroupManager**. 1801 1802**System capability**: SystemCapability.Multimedia.Audio.Communication 1803 1804**Parameters** 1805 1806| Name | Type | Mandatory| Description | 1807| -------- | ---------------------------------------------------- | ---- | ------------------------ | 1808| 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.| 1809 1810**Example** 1811 1812```ts 1813import { BusinessError } from '@kit.BasicServicesKit'; 1814 1815audioManager.getRingerMode((err: BusinessError, value: audio.AudioRingMode) => { 1816 if (err) { 1817 console.error(`Failed to obtain the ringer mode. ${err}`); 1818 return; 1819 } 1820 console.info(`Callback invoked to indicate that the ringer mode is obtained ${value}.`); 1821}); 1822``` 1823 1824### getRingerMode<sup>(deprecated)</sup> 1825 1826getRingerMode(): Promise<AudioRingMode> 1827 1828Obtains the ringer mode. This API uses a promise to return the result. 1829 1830> **NOTE** 1831> 1832> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getRingerMode](#getringermode9) in **AudioVolumeGroupManager**. 1833 1834**System capability**: SystemCapability.Multimedia.Audio.Communication 1835 1836**Return value** 1837 1838| Type | Description | 1839| ---------------------------------------------- | ------------------------------- | 1840| Promise<[AudioRingMode](#audioringmode)> | Promise used to return the ringer mode.| 1841 1842**Example** 1843 1844```ts 1845audioManager.getRingerMode().then((value: audio.AudioRingMode) => { 1846 console.info(`Promise returned to indicate that the ringer mode is obtained ${value}.`); 1847}); 1848``` 1849 1850### getDevices<sup>(deprecated)</sup> 1851 1852getDevices(deviceFlag: DeviceFlag, callback: AsyncCallback<AudioDeviceDescriptors>): void 1853 1854Obtains the audio devices with a specific flag. This API uses an asynchronous callback to return the result. 1855 1856> **NOTE** 1857> 1858> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getDevices](#getdevices9) in **AudioRoutingManager**. 1859 1860**System capability**: SystemCapability.Multimedia.Audio.Device 1861 1862**Parameters** 1863 1864| Name | Type | Mandatory| Description | 1865| ---------- | ------------------------------------------------------------ | ---- | -------------------- | 1866| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag. | 1867| 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.| 1868 1869**Example** 1870```ts 1871import { BusinessError } from '@kit.BasicServicesKit'; 1872 1873audioManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG, (err: BusinessError, value: audio.AudioDeviceDescriptors) => { 1874 if (err) { 1875 console.error(`Failed to obtain the device list. ${err}`); 1876 return; 1877 } 1878 console.info('Callback invoked to indicate that the device list is obtained.'); 1879}); 1880``` 1881 1882### getDevices<sup>(deprecated)</sup> 1883 1884getDevices(deviceFlag: DeviceFlag): Promise<AudioDeviceDescriptors> 1885 1886Obtains the audio devices with a specific flag. This API uses a promise to return the result. 1887 1888> **NOTE** 1889> 1890> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [getDevices](#getdevices9) in **AudioRoutingManager**. 1891 1892**System capability**: SystemCapability.Multimedia.Audio.Device 1893 1894**Parameters** 1895 1896| Name | Type | Mandatory| Description | 1897| ---------- | ------------------------- | ---- | ---------------- | 1898| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag.| 1899 1900**Return value** 1901 1902| Type | Description | 1903| ------------------------------------------------------------ | ------------------------- | 1904| Promise<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Promise used to return the device list.| 1905 1906**Example** 1907 1908```ts 1909audioManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG).then((data: audio.AudioDeviceDescriptors) => { 1910 console.info('Promise returned to indicate that the device list is obtained.'); 1911}); 1912``` 1913 1914### setDeviceActive<sup>(deprecated)</sup> 1915 1916setDeviceActive(deviceType: ActiveDeviceType, active: boolean, callback: AsyncCallback<void>): void 1917 1918Sets a device to the active state. This API uses an asynchronous callback to return the result. 1919 1920> **NOTE** 1921> 1922> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [setCommunicationDevice](#setcommunicationdevice9) in **AudioRoutingManager**. 1923 1924**System capability**: SystemCapability.Multimedia.Audio.Device 1925 1926**Parameters** 1927 1928| Name | Type | Mandatory| Description | 1929| ---------- | ------------------------------------- | ---- |-------------| 1930| deviceType | [ActiveDeviceType](#activedevicetypedeprecated) | Yes | Active audio device type. | 1931| active | boolean | Yes | Active state to set. The value **true** means to set the device to the active state, and **false** means the opposite. | 1932| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1933 1934**Example** 1935 1936```ts 1937import { BusinessError } from '@kit.BasicServicesKit'; 1938 1939audioManager.setDeviceActive(audio.ActiveDeviceType.SPEAKER, true, (err: BusinessError) => { 1940 if (err) { 1941 console.error(`Failed to set the active status of the device. ${err}`); 1942 return; 1943 } 1944 console.info('Callback invoked to indicate that the device is set to the active status.'); 1945}); 1946``` 1947 1948### setDeviceActive<sup>(deprecated)</sup> 1949 1950setDeviceActive(deviceType: ActiveDeviceType, active: boolean): Promise<void> 1951 1952Sets a device to the active state. This API uses a promise 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 1967**Return value** 1968 1969| Type | Description | 1970| ------------------- | ------------------------------- | 1971| Promise<void> | Promise that returns no value.| 1972 1973**Example** 1974 1975 1976```ts 1977audioManager.setDeviceActive(audio.ActiveDeviceType.SPEAKER, true).then(() => { 1978 console.info('Promise returned to indicate that the device is set to the active status.'); 1979}); 1980``` 1981 1982### isDeviceActive<sup>(deprecated)</sup> 1983 1984isDeviceActive(deviceType: ActiveDeviceType, callback: AsyncCallback<boolean>): void 1985 1986Checks whether a device is active. This API uses an asynchronous callback 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 [isCommunicationDeviceActive](#iscommunicationdeviceactive9) 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| 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.| 2000 2001**Example** 2002 2003```ts 2004import { BusinessError } from '@kit.BasicServicesKit'; 2005 2006audioManager.isDeviceActive(audio.ActiveDeviceType.SPEAKER, (err: BusinessError, value: boolean) => { 2007 if (err) { 2008 console.error(`Failed to obtain the active status of the device. ${err}`); 2009 return; 2010 } 2011 console.info('Callback invoked to indicate that the active status of the device is obtained.'); 2012}); 2013``` 2014 2015### isDeviceActive<sup>(deprecated)</sup> 2016 2017isDeviceActive(deviceType: ActiveDeviceType): Promise<boolean> 2018 2019Checks whether a device is active. This API uses a promise to return the result. 2020 2021> **NOTE** 2022> 2023> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isCommunicationDeviceActive](#iscommunicationdeviceactive9) in **AudioRoutingManager**. 2024 2025**System capability**: SystemCapability.Multimedia.Audio.Device 2026 2027**Parameters** 2028 2029| Name | Type | Mandatory| Description | 2030| ---------- | ------------------------------------- | ---- | ------------------ | 2031| deviceType | [ActiveDeviceType](#activedevicetypedeprecated) | Yes | Active audio device type.| 2032 2033**Return value** 2034 2035| Type | Description | 2036| ---------------------- |---------------------------------------| 2037| 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. | 2038 2039**Example** 2040 2041```ts 2042audioManager.isDeviceActive(audio.ActiveDeviceType.SPEAKER).then((value: boolean) => { 2043 console.info(`Promise returned to indicate that the active status of the device is obtained ${value}.`); 2044}); 2045``` 2046 2047### setMicrophoneMute<sup>(deprecated)</sup> 2048 2049setMicrophoneMute(mute: boolean, callback: AsyncCallback<void>): void 2050 2051Mutes or unmutes the microphone. This API uses an asynchronous callback to return the result. 2052 2053> **NOTE** 2054> 2055> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 2056 2057**Required permissions**: ohos.permission.MICROPHONE 2058 2059**System capability**: SystemCapability.Multimedia.Audio.Device 2060 2061**Parameters** 2062 2063| Name | Type | Mandatory| Description | 2064| -------- | ------------------------- | ---- | --------------------------------------------- | 2065| mute | boolean | Yes | Mute status to set. The value **true** means to mute the microphone, and **false** means the opposite.| 2066| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 2067 2068**Example** 2069 2070```ts 2071import { BusinessError } from '@kit.BasicServicesKit'; 2072 2073audioManager.setMicrophoneMute(true, (err: BusinessError) => { 2074 if (err) { 2075 console.error(`Failed to mute the microphone. ${err}`); 2076 return; 2077 } 2078 console.info('Callback invoked to indicate that the microphone is muted.'); 2079}); 2080``` 2081 2082### setMicrophoneMute<sup>(deprecated)</sup> 2083 2084setMicrophoneMute(mute: boolean): Promise<void> 2085 2086Mutes or unmutes the microphone. This API uses a promise to return the result. 2087 2088> **NOTE** 2089> 2090> This API is supported since API version 7 and deprecated since API version 9. The substitute API is available only for system applications. 2091 2092**Required permissions**: ohos.permission.MICROPHONE 2093 2094**System capability**: SystemCapability.Multimedia.Audio.Device 2095 2096**Parameters** 2097 2098| Name| Type | Mandatory| Description | 2099| ------ | ------- | ---- | --------------------------------------------- | 2100| mute | boolean | Yes | Mute status to set. The value **true** means to mute the microphone, and **false** means the opposite.| 2101 2102**Return value** 2103 2104| Type | Description | 2105| ------------------- | ------------------------------- | 2106| Promise<void> | Promise that returns no value.| 2107 2108**Example** 2109 2110```ts 2111audioManager.setMicrophoneMute(true).then(() => { 2112 console.info('Promise returned to indicate that the microphone is muted.'); 2113}); 2114``` 2115 2116### isMicrophoneMute<sup>(deprecated)</sup> 2117 2118isMicrophoneMute(callback: AsyncCallback<boolean>): void 2119 2120Checks whether the microphone is muted. This API uses an asynchronous callback to return the result. 2121 2122> **NOTE** 2123> 2124> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [isMicrophoneMute](#ismicrophonemute9) in **AudioVolumeGroupManager**. 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| 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.| 2135 2136**Example** 2137 2138```ts 2139import { BusinessError } from '@kit.BasicServicesKit'; 2140 2141audioManager.isMicrophoneMute((err: BusinessError, value: boolean) => { 2142 if (err) { 2143 console.error(`Failed to obtain the mute status of the microphone. ${err}`); 2144 return; 2145 } 2146 console.info(`Callback invoked to indicate that the mute status of the microphone is obtained ${value}.`); 2147}); 2148``` 2149 2150### isMicrophoneMute<sup>(deprecated)</sup> 2151 2152isMicrophoneMute(): Promise<boolean> 2153 2154Checks whether the microphone is muted. This API uses a promise 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**Return value** 2165 2166| Type | Description | 2167| ---------------------- | ------------------------------------------------------------ | 2168| 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.| 2169 2170**Example** 2171 2172```ts 2173audioManager.isMicrophoneMute().then((value: boolean) => { 2174 console.info(`Promise returned to indicate that the mute status of the microphone is obtained ${value}.`); 2175}); 2176``` 2177 2178### on('deviceChange')<sup>(deprecated)</sup> 2179 2180on(type: 'deviceChange', callback: Callback<DeviceChangeAction\>): void 2181 2182Subscribes to audio device change events. This API uses an asynchronous callback to return the result. Such an event is triggered when the connection status of an audio device is changed. 2183 2184> **NOTE** 2185> 2186> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [on('deviceChange')](#ondevicechange9) in **AudioRoutingManager**. 2187 2188**System capability**: SystemCapability.Multimedia.Audio.Device 2189 2190**Parameters** 2191 2192| Name | Type | Mandatory| Description | 2193| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- | 2194| type | string | Yes | Event type. The value is fixed at **'deviceChange'**.| 2195| callback | Callback<[DeviceChangeAction](#devicechangeaction)\> | Yes | Callback used to return the device change details.| 2196 2197**Example** 2198 2199```ts 2200audioManager.on('deviceChange', (deviceChanged: audio.DeviceChangeAction) => { 2201 console.info(`device change type : ${deviceChanged.type} `); 2202 console.info(`device descriptor size : ${deviceChanged.deviceDescriptors.length} `); 2203 console.info(`device change descriptor : ${deviceChanged.deviceDescriptors[0].deviceRole} `); 2204 console.info(`device change descriptor : ${deviceChanged.deviceDescriptors[0].deviceType} `); 2205}); 2206``` 2207 2208### off('deviceChange')<sup>(deprecated)</sup> 2209 2210off(type: 'deviceChange', callback?: Callback<DeviceChangeAction\>): void 2211 2212Unsubscribes from audio device change events. This API uses an asynchronous callback to return the result. 2213 2214> **NOTE** 2215> 2216> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [off('deviceChange')](#offdevicechange9) in **AudioRoutingManager**. 2217 2218**System capability**: SystemCapability.Multimedia.Audio.Device 2219 2220**Parameters** 2221 2222| Name | Type | Mandatory| Description | 2223| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 2224| type | string | Yes | Event type. The value is fixed at **'deviceChange'**.| 2225| callback | Callback<[DeviceChangeAction](#devicechangeaction)> | No | Callback used to return the device change details.| 2226 2227**Example** 2228 2229```ts 2230audioManager.off('deviceChange'); 2231``` 2232 2233### on('interrupt')<sup>(deprecated)</sup> 2234 2235on(type: 'interrupt', interrupt: AudioInterrupt, callback: Callback\<InterruptAction>): void 2236 2237Subscribes to audio interruption events. This API uses an asynchronous callback to return the result. Such an event is triggered when the application's audio is interrupted by another playback event. 2238 2239Same 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. 2240 2241> **NOTE** 2242> 2243> This API is supported since API version 7 and deprecated since API version 11. You are advised to use [on('audioInterrupt')](#onaudiointerrupt10) in **AudioCapturer**. 2244 2245**System capability**: SystemCapability.Multimedia.Audio.Renderer 2246 2247**Parameters** 2248 2249| Name | Type | Mandatory| Description | 2250| --------- |---------------------------------------------------------| ---- | ------------------------------------------------------------ | 2251| type | string | Yes | Event type. The value is fixed at **'interrupt'**.| 2252| interrupt | [AudioInterrupt](#audiointerruptdeprecated) | Yes | Audio interruption event type. | 2253| callback | Callback<[InterruptAction](#interruptactiondeprecated)> | Yes | Callback used to return the audio interruption event.| 2254 2255**Example** 2256 2257```ts 2258import { audio } from '@kit.AudioKit'; 2259 2260let interAudioInterrupt: audio.AudioInterrupt = { 2261 streamUsage:2, 2262 contentType:0, 2263 pauseWhenDucked:true 2264}; 2265audioManager.on('interrupt', interAudioInterrupt, (InterruptAction: audio.InterruptAction) => { 2266 if (InterruptAction.actionType === 0) { 2267 console.info('An event to gain the audio focus starts.'); 2268 console.info(`Focus gain event: ${InterruptAction} `); 2269 } 2270 if (InterruptAction.actionType === 1) { 2271 console.info('An audio interruption event starts.'); 2272 console.info(`Audio interruption event: ${InterruptAction} `); 2273 } 2274}); 2275``` 2276 2277### off('interrupt')<sup>(deprecated)</sup> 2278 2279off(type: 'interrupt', interrupt: AudioInterrupt, callback?: Callback\<InterruptAction>): void 2280 2281Unsubscribes from audio interruption events. This API uses an asynchronous callback to return the result. 2282 2283> **NOTE** 2284> 2285> This API is supported since API version 7 and deprecated since API version 11. You are advised to use [off('audioInterrupt')](#offaudiointerrupt10) in **AudioCapturer**. 2286 2287**System capability**: SystemCapability.Multimedia.Audio.Renderer 2288 2289**Parameters** 2290 2291| Name | Type | Mandatory| Description | 2292| --------- |---------------------------------------------------------| ---- | ------------------------------------------------------------ | 2293| type | string | Yes | Event type. The value is fixed at **'interrupt'**.| 2294| interrupt | [AudioInterrupt](#audiointerruptdeprecated) | Yes | Audio interruption event type. | 2295| callback | Callback<[InterruptAction](#interruptactiondeprecated)> | No | Callback used to return the audio interruption event.| 2296 2297**Example** 2298 2299```ts 2300import { audio } from '@kit.AudioKit'; 2301 2302let interAudioInterrupt: audio.AudioInterrupt = { 2303 streamUsage:2, 2304 contentType:0, 2305 pauseWhenDucked:true 2306}; 2307audioManager.off('interrupt', interAudioInterrupt, (InterruptAction: audio.InterruptAction) => { 2308 if (InterruptAction.actionType === 0) { 2309 console.info('An event to release the audio focus starts.'); 2310 console.info(`Focus release event: ${InterruptAction} `); 2311 } 2312}); 2313``` 2314 2315## AudioVolumeManager<sup>9+</sup> 2316 2317Implements audio volume management. Before calling an API in **AudioVolumeManager**, you must use [getVolumeManager](#getvolumemanager9) to obtain an **AudioVolumeManager** instance. 2318 2319### getVolumeGroupManager<sup>9+</sup> 2320 2321getVolumeGroupManager(groupId: number, callback: AsyncCallback<AudioVolumeGroupManager\>\): void 2322 2323Obtains the volume group manager. This API uses an asynchronous callback to return the result. 2324 2325**System capability**: SystemCapability.Multimedia.Audio.Volume 2326 2327**Parameters** 2328 2329| Name | Type | Mandatory| Description | 2330| ---------- | ------------------------------------------------------------ | ---- |-----------------------------------------------------------| 2331| groupId | number | Yes | Volume group ID. The default value is **LOCAL_VOLUME_GROUP_ID**. | 2332| 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.| 2333 2334**Example** 2335 2336```ts 2337import { BusinessError } from '@kit.BasicServicesKit'; 2338 2339let groupId: number = audio.DEFAULT_VOLUME_GROUP_ID; 2340audioVolumeManager.getVolumeGroupManager(groupId, (err: BusinessError, value: audio.AudioVolumeGroupManager) => { 2341 if (err) { 2342 console.error(`Failed to obtain the volume group infos list. ${err}`); 2343 return; 2344 } 2345 console.info('Callback invoked to indicate that the volume group infos list is obtained.'); 2346}); 2347 2348``` 2349 2350### getVolumeGroupManager<sup>9+</sup> 2351 2352getVolumeGroupManager(groupId: number\): Promise<AudioVolumeGroupManager\> 2353 2354Obtains the volume group manager. This API uses a promise to return the result. 2355 2356**System capability**: SystemCapability.Multimedia.Audio.Volume 2357 2358**Parameters** 2359 2360| Name | Type | Mandatory| Description | 2361| ---------- | ---------------------------------------- | ---- |----------------------------------| 2362| groupId | number | Yes | Volume group ID. The default value is **LOCAL_VOLUME_GROUP_ID**.| 2363 2364**Return value** 2365 2366| Type | Description | 2367| ------------------- | ----------------------------- | 2368| Promise< [AudioVolumeGroupManager](#audiovolumegroupmanager9) > | Promise used to return the volume group manager.| 2369 2370**Example** 2371 2372```ts 2373import { audio } from '@kit.AudioKit'; 2374 2375let groupId: number = audio.DEFAULT_VOLUME_GROUP_ID; 2376let audioVolumeGroupManager: audio.AudioVolumeGroupManager | undefined = undefined; 2377async function getVolumeGroupManager(){ 2378 audioVolumeGroupManager = await audioVolumeManager.getVolumeGroupManager(groupId); 2379 console.info('Promise returned to indicate that the volume group infos list is obtained.'); 2380} 2381``` 2382 2383### getVolumeGroupManagerSync<sup>10+</sup> 2384 2385getVolumeGroupManagerSync(groupId: number\): AudioVolumeGroupManager 2386 2387Obtains the volume group manager. This API returns the result synchronously. 2388 2389**System capability**: SystemCapability.Multimedia.Audio.Volume 2390 2391**Parameters** 2392 2393| Name | Type | Mandatory| Description | 2394| ---------- | ---------------------------------------- | ---- |----------------------------------| 2395| groupId | number | Yes | Volume group ID. The default value is **LOCAL_VOLUME_GROUP_ID**.| 2396 2397**Return value** 2398 2399| Type | Description | 2400| ------------------- | ----------------------------- | 2401| [AudioVolumeGroupManager](#audiovolumegroupmanager9) | Volume group manager.| 2402 2403**Error codes** 2404 2405For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2406 2407| ID| Error Message| 2408| ------- | --------------------------------------------| 2409| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2410| 6800101 | Parameter verification failed. | 2411 2412**Example** 2413 2414```ts 2415import { BusinessError } from '@kit.BasicServicesKit'; 2416 2417try { 2418 let audioVolumeGroupManager: audio.AudioVolumeGroupManager = audioVolumeManager.getVolumeGroupManagerSync(audio.DEFAULT_VOLUME_GROUP_ID); 2419 console.info(`Get audioVolumeGroupManager success.`); 2420} catch (err) { 2421 let error = err as BusinessError; 2422 console.error(`Failed to get audioVolumeGroupManager, error: ${error}`); 2423} 2424``` 2425 2426### on('volumeChange')<sup>9+</sup> 2427 2428on(type: 'volumeChange', callback: Callback\<VolumeEvent>): void 2429 2430Subscribes to system volume change events. This API uses an asynchronous callback to return the result. Such an event is triggered when the system volume is changed. 2431 2432**System capability**: SystemCapability.Multimedia.Audio.Volume 2433 2434**Parameters** 2435 2436| Name | Type | Mandatory| Description | 2437| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 2438| type | string | Yes | Event type. The value is fixed at **'volumeChange'**.| 2439| callback | Callback<[VolumeEvent](#volumeevent9)> | Yes | Callback used to return the changed volume.| 2440 2441**Error codes** 2442 2443For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2444 2445| ID| Error Message| 2446| ------- | --------------------------------------------| 2447| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2448| 6800101 | Parameter verification failed. | 2449 2450**Example** 2451 2452```ts 2453audioVolumeManager.on('volumeChange', (volumeEvent: audio.VolumeEvent) => { 2454 console.info(`VolumeType of stream: ${volumeEvent.volumeType} `); 2455 console.info(`Volume level: ${volumeEvent.volume} `); 2456 console.info(`Whether to updateUI: ${volumeEvent.updateUi} `); 2457}); 2458``` 2459 2460### off('volumeChange')<sup>12+</sup> 2461 2462off(type: 'volumeChange', callback?: Callback\<VolumeEvent>): void 2463 2464Unsubscribes from system volume change events. This API uses an asynchronous callback to return the result. 2465 2466**System capability**: SystemCapability.Multimedia.Audio.Volume 2467 2468**Parameters** 2469 2470| Name | Type | Mandatory| Description | 2471| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 2472| type | string | Yes | Event type. The value is fixed at **'volumeChange'**.| 2473| callback | Callback<[VolumeEvent](#volumeevent9)> | No | Callback used to return the changed volume.| 2474 2475**Error codes** 2476 2477For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2478 2479| ID| Error Message| 2480| ------- | --------------------------------------------| 2481| 401 | Parameter error. Possible causes: 1.Mandatory parameters missing; 2.Incorrect parameter types. | 2482| 6800101 | Parameter verification failed. | 2483 2484**Example** 2485 2486```ts 2487audioVolumeManager.off('volumeChange'); 2488``` 2489 2490## AudioVolumeGroupManager<sup>9+</sup> 2491 2492Manages the volume of an audio group. Before calling any API in **AudioVolumeGroupManager**, you must use [getVolumeGroupManager](#getvolumegroupmanager9) to obtain an **AudioVolumeGroupManager** instance. 2493 2494### getVolume<sup>9+</sup> 2495 2496getVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 2497 2498Obtains the volume of a stream. This API uses an asynchronous callback to return the result. 2499 2500**System capability**: SystemCapability.Multimedia.Audio.Volume 2501 2502**Parameters** 2503 2504| Name | Type | Mandatory| Description | 2505| ---------- | ----------------------------------- | ---- | ------------------ | 2506| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 2507| 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).| 2508 2509**Example** 2510 2511```ts 2512import { BusinessError } from '@kit.BasicServicesKit'; 2513 2514audioVolumeGroupManager.getVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { 2515 if (err) { 2516 console.error(`Failed to obtain the volume. ${err}`); 2517 return; 2518 } 2519 console.info('Callback invoked to indicate that the volume is obtained.'); 2520}); 2521``` 2522 2523### getVolume<sup>9+</sup> 2524 2525getVolume(volumeType: AudioVolumeType): Promise<number> 2526 2527Obtains the volume of a stream. This API uses a promise to return the result. 2528 2529**System capability**: SystemCapability.Multimedia.Audio.Volume 2530 2531**Parameters** 2532 2533| Name | Type | Mandatory| Description | 2534| ---------- | ----------------------------------- | ---- | ------------ | 2535| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2536 2537**Return value** 2538 2539| Type | Description | 2540| --------------------- | ------------------------- | 2541| 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).| 2542 2543**Example** 2544 2545```ts 2546audioVolumeGroupManager.getVolume(audio.AudioVolumeType.MEDIA).then((value: number) => { 2547 console.info(`Promise returned to indicate that the volume is obtained ${value}.`); 2548}); 2549``` 2550 2551### getVolumeSync<sup>10+</sup> 2552 2553getVolumeSync(volumeType: AudioVolumeType): number; 2554 2555Obtains the volume of a stream. This API returns the result synchronously. 2556 2557**System capability**: SystemCapability.Multimedia.Audio.Volume 2558 2559**Parameters** 2560 2561| Name | Type | Mandatory| Description | 2562| ---------- | ----------------------------------- | ---- | ------------ | 2563| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2564 2565**Return value** 2566 2567| Type | Description | 2568| --------------------- | ------------------------- | 2569| number | Volume of the stream. The volume range of a specified stream can be obtained by calling [getMinVolume](#getminvolume9) and [getMaxVolume](#getmaxvolume9).| 2570 2571**Error codes** 2572 2573For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2574 2575| ID| Error Message| 2576| ------- | --------------------------------------------| 2577| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2578| 6800101 | Parameter verification failed. | 2579 2580**Example** 2581 2582```ts 2583import { BusinessError } from '@kit.BasicServicesKit'; 2584 2585try { 2586 let value: number = audioVolumeGroupManager.getVolumeSync(audio.AudioVolumeType.MEDIA); 2587 console.info(`Indicate that the volume is obtained ${value}.`); 2588} catch (err) { 2589 let error = err as BusinessError; 2590 console.error(`Failed to obtain the volume, error ${error}.`); 2591} 2592``` 2593 2594### getMinVolume<sup>9+</sup> 2595 2596getMinVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 2597 2598Obtains the minimum volume allowed for a stream. This API uses an asynchronous callback to return the result. 2599 2600**System capability**: SystemCapability.Multimedia.Audio.Volume 2601 2602**Parameters** 2603 2604| Name | Type | Mandatory| Description | 2605| ---------- | ----------------------------------- | ---- | ------------------ | 2606| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 2607| 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.| 2608 2609**Example** 2610 2611```ts 2612import { BusinessError } from '@kit.BasicServicesKit'; 2613 2614audioVolumeGroupManager.getMinVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { 2615 if (err) { 2616 console.error(`Failed to obtain the minimum volume. ${err}`); 2617 return; 2618 } 2619 console.info(`Callback invoked to indicate that the minimum volume is obtained. ${value}`); 2620}); 2621``` 2622 2623### getMinVolume<sup>9+</sup> 2624 2625getMinVolume(volumeType: AudioVolumeType): Promise<number> 2626 2627Obtains the minimum volume allowed for a stream. This API uses a promise to return the result. 2628 2629**System capability**: SystemCapability.Multimedia.Audio.Volume 2630 2631**Parameters** 2632 2633| Name | Type | Mandatory| Description | 2634| ---------- | ----------------------------------- | ---- | ------------ | 2635| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2636 2637**Return value** 2638 2639| Type | Description | 2640| --------------------- | ------------------------- | 2641| Promise<number> | Promise used to return the minimum volume.| 2642 2643**Example** 2644 2645```ts 2646audioVolumeGroupManager.getMinVolume(audio.AudioVolumeType.MEDIA).then((value: number) => { 2647 console.info(`Promised returned to indicate that the minimum volume is obtained ${value}.`); 2648}); 2649``` 2650 2651### getMinVolumeSync<sup>10+</sup> 2652 2653getMinVolumeSync(volumeType: AudioVolumeType): number; 2654 2655Obtains the minimum volume allowed for a stream. This API returns the result synchronously. 2656 2657**System capability**: SystemCapability.Multimedia.Audio.Volume 2658 2659**Parameters** 2660 2661| Name | Type | Mandatory| Description | 2662| ---------- | ----------------------------------- | ---- | ------------ | 2663| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2664 2665**Return value** 2666 2667| Type | Description | 2668| --------------------- | ------------------------- | 2669| number | Minimum volume.| 2670 2671**Error codes** 2672 2673For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2674 2675| ID| Error Message| 2676| ------- | --------------------------------------------| 2677| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2678| 6800101 | Parameter verification failed. | 2679 2680**Example** 2681 2682```ts 2683import { BusinessError } from '@kit.BasicServicesKit'; 2684 2685try { 2686 let value: number = audioVolumeGroupManager.getMinVolumeSync(audio.AudioVolumeType.MEDIA); 2687 console.info(`Indicate that the minimum volume is obtained ${value}.`); 2688} catch (err) { 2689 let error = err as BusinessError; 2690 console.error(`Failed to obtain the minimum volume, error ${error}.`); 2691} 2692``` 2693 2694### getMaxVolume<sup>9+</sup> 2695 2696getMaxVolume(volumeType: AudioVolumeType, callback: AsyncCallback<number>): void 2697 2698Obtains the maximum volume allowed for a stream. This API uses an asynchronous callback to return the result. 2699 2700**System capability**: SystemCapability.Multimedia.Audio.Volume 2701 2702**Parameters** 2703 2704| Name | Type | Mandatory| Description | 2705| ---------- | ----------------------------------- | ---- | ---------------------- | 2706| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 2707| 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.| 2708 2709**Example** 2710 2711```ts 2712import { BusinessError } from '@kit.BasicServicesKit'; 2713 2714audioVolumeGroupManager.getMaxVolume(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: number) => { 2715 if (err) { 2716 console.error(`Failed to obtain the maximum volume. ${err}`); 2717 return; 2718 } 2719 console.info(`Callback invoked to indicate that the maximum volume is obtained. ${value}`); 2720}); 2721``` 2722 2723### getMaxVolume<sup>9+</sup> 2724 2725getMaxVolume(volumeType: AudioVolumeType): Promise<number> 2726 2727Obtains the maximum volume allowed for a stream. This API uses a promise to return the result. 2728 2729**System capability**: SystemCapability.Multimedia.Audio.Volume 2730 2731**Parameters** 2732 2733| Name | Type | Mandatory| Description | 2734| ---------- | ----------------------------------- | ---- | ------------ | 2735| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2736 2737**Return value** 2738 2739| Type | Description | 2740| --------------------- | ----------------------------- | 2741| Promise<number> | Promise used to return the maximum volume.| 2742 2743**Example** 2744 2745```ts 2746audioVolumeGroupManager.getMaxVolume(audio.AudioVolumeType.MEDIA).then((data: number) => { 2747 console.info('Promised returned to indicate that the maximum volume is obtained.'); 2748}); 2749``` 2750 2751### getMaxVolumeSync<sup>10+</sup> 2752 2753getMaxVolumeSync(volumeType: AudioVolumeType): number; 2754 2755Obtains the maximum volume allowed for a stream. This API returns the result synchronously. 2756 2757**System capability**: SystemCapability.Multimedia.Audio.Volume 2758 2759**Parameters** 2760 2761| Name | Type | Mandatory| Description | 2762| ---------- | ----------------------------------- | ---- | ------------ | 2763| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2764 2765**Return value** 2766 2767| Type | Description | 2768| --------------------- | ----------------------------- | 2769| number | Maximum volume.| 2770 2771**Error codes** 2772 2773For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2774 2775| ID| Error Message| 2776| ------- | --------------------------------------------| 2777| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2778| 6800101 | Parameter verification failed. | 2779 2780**Example** 2781 2782```ts 2783import { BusinessError } from '@kit.BasicServicesKit'; 2784 2785try { 2786 let value: number = audioVolumeGroupManager.getMaxVolumeSync(audio.AudioVolumeType.MEDIA); 2787 console.info(`Indicate that the maximum volume is obtained. ${value}`); 2788} catch (err) { 2789 let error = err as BusinessError; 2790 console.error(`Failed to obtain the maximum volume, error ${error}.`); 2791} 2792``` 2793 2794### isMute<sup>9+</sup> 2795 2796isMute(volumeType: AudioVolumeType, callback: AsyncCallback<boolean>): void 2797 2798Checks whether a stream is muted. This API uses an asynchronous callback to return the result. 2799 2800**System capability**: SystemCapability.Multimedia.Audio.Volume 2801 2802**Parameters** 2803 2804| Name | Type | Mandatory| Description | 2805| ---------- | ----------------------------------- | ---- | ----------------------------------------------- | 2806| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 2807| 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.| 2808 2809**Example** 2810 2811```ts 2812import { BusinessError } from '@kit.BasicServicesKit'; 2813 2814audioVolumeGroupManager.isMute(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: boolean) => { 2815 if (err) { 2816 console.error(`Failed to obtain the mute status. ${err}`); 2817 return; 2818 } 2819 console.info(`Callback invoked to indicate that the mute status of the stream is obtained ${value}.`); 2820}); 2821``` 2822 2823### isMute<sup>9+</sup> 2824 2825isMute(volumeType: AudioVolumeType): Promise<boolean> 2826 2827Checks whether a stream is muted. This API uses a promise to return the result. 2828 2829**System capability**: SystemCapability.Multimedia.Audio.Volume 2830 2831**Parameters** 2832 2833| Name | Type | Mandatory| Description | 2834| ---------- | ----------------------------------- | ---- | ------------ | 2835| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2836 2837**Return value** 2838 2839| Type | Description | 2840| ---------------------- | ------------------------------------------------------ | 2841| 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.| 2842 2843**Example** 2844 2845```ts 2846audioVolumeGroupManager.isMute(audio.AudioVolumeType.MEDIA).then((value: boolean) => { 2847 console.info(`Promise returned to indicate that the mute status of the stream is obtained ${value}.`); 2848}); 2849``` 2850 2851### isMuteSync<sup>10+</sup> 2852 2853isMuteSync(volumeType: AudioVolumeType): boolean 2854 2855Checks whether a stream is muted. This API returns the result synchronously. 2856 2857**System capability**: SystemCapability.Multimedia.Audio.Volume 2858 2859**Parameters** 2860 2861| Name | Type | Mandatory| Description | 2862| ---------- | ----------------------------------- | ---- | ------------ | 2863| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type.| 2864 2865**Return value** 2866 2867| Type | Description | 2868| ---------------------- | ------------------------------------------------------ | 2869| boolean | **true**: The stream is muted.<br>**false**: The stream is not muted.| 2870 2871**Error codes** 2872 2873For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2874 2875| ID| Error Message| 2876| ------- | --------------------------------------------| 2877| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2878| 6800101 | Parameter verification failed. | 2879 2880**Example** 2881 2882```ts 2883import { BusinessError } from '@kit.BasicServicesKit'; 2884 2885try { 2886 let value: boolean = audioVolumeGroupManager.isMuteSync(audio.AudioVolumeType.MEDIA); 2887 console.info(`Indicate that the mute status of the stream is obtained ${value}.`); 2888} catch (err) { 2889 let error = err as BusinessError; 2890 console.error(`Failed to obtain the mute status of the stream, error ${error}.`); 2891} 2892``` 2893 2894### getRingerMode<sup>9+</sup> 2895 2896getRingerMode(callback: AsyncCallback<AudioRingMode>): void 2897 2898Obtains the ringer mode. This API uses an asynchronous callback to return the result. 2899 2900**System capability**: SystemCapability.Multimedia.Audio.Volume 2901 2902**Parameters** 2903 2904| Name | Type | Mandatory| Description | 2905| -------- | ---------------------------------------------------- | ---- | ------------------------ | 2906| 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.| 2907 2908**Example** 2909 2910```ts 2911import { BusinessError } from '@kit.BasicServicesKit'; 2912 2913audioVolumeGroupManager.getRingerMode((err: BusinessError, value: audio.AudioRingMode) => { 2914 if (err) { 2915 console.error(`Failed to obtain the ringer mode. ${err}`); 2916 return; 2917 } 2918 console.info(`Callback invoked to indicate that the ringer mode is obtained ${value}.`); 2919}); 2920``` 2921 2922### getRingerMode<sup>9+</sup> 2923 2924getRingerMode(): Promise<AudioRingMode> 2925 2926Obtains the ringer mode. This API uses a promise to return the result. 2927 2928**System capability**: SystemCapability.Multimedia.Audio.Volume 2929 2930**Return value** 2931 2932| Type | Description | 2933| ---------------------------------------------- | ------------------------------- | 2934| Promise<[AudioRingMode](#audioringmode)> | Promise used to return the ringer mode.| 2935 2936**Example** 2937 2938```ts 2939audioVolumeGroupManager.getRingerMode().then((value: audio.AudioRingMode) => { 2940 console.info(`Promise returned to indicate that the ringer mode is obtained ${value}.`); 2941}); 2942``` 2943 2944### getRingerModeSync<sup>10+</sup> 2945 2946getRingerModeSync(): AudioRingMode 2947 2948Obtains the ringer mode. This API returns the result synchronously. 2949 2950**System capability**: SystemCapability.Multimedia.Audio.Volume 2951 2952**Return value** 2953 2954| Type | Description | 2955| ---------------------------------------------- | ------------------------------- | 2956| [AudioRingMode](#audioringmode) | Ringer mode.| 2957 2958**Example** 2959 2960```ts 2961import { BusinessError } from '@kit.BasicServicesKit'; 2962 2963try { 2964 let value: audio.AudioRingMode = audioVolumeGroupManager.getRingerModeSync(); 2965 console.info(`Indicate that the ringer mode is obtained ${value}.`); 2966} catch (err) { 2967 let error = err as BusinessError; 2968 console.error(`Failed to obtain the ringer mode, error ${error}.`); 2969} 2970``` 2971 2972### on('ringerModeChange')<sup>9+</sup> 2973 2974on(type: 'ringerModeChange', callback: Callback\<AudioRingMode>): void 2975 2976Subscribes to ringer mode change events. This API uses an asynchronous callback to return the result. Such an event is triggered when [audioringmode](#audioringmode) is changed. 2977 2978**System capability**: SystemCapability.Multimedia.Audio.Volume 2979 2980**Parameters** 2981 2982| Name | Type | Mandatory| Description | 2983| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 2984| type | string | Yes | Event type. The value is fixed at **'ringerModeChange'**.| 2985| callback | Callback<[AudioRingMode](#audioringmode)> | Yes | Callback used to return the changed ringer mode.| 2986 2987**Error codes** 2988 2989For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2990 2991| ID| Error Message| 2992| ------- | --------------------------------------------| 2993| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2994| 6800101 | Parameter verification failed. | 2995 2996**Example** 2997 2998```ts 2999audioVolumeGroupManager.on('ringerModeChange', (ringerMode: audio.AudioRingMode) => { 3000 console.info(`Updated ringermode: ${ringerMode}`); 3001}); 3002``` 3003 3004### setMicrophoneMute<sup>(deprecated)</sup> 3005 3006setMicrophoneMute(mute: boolean, callback: AsyncCallback<void>): void 3007 3008Mutes or unmutes the microphone. This API uses an asynchronous callback to return the result. 3009 3010> **NOTE** 3011> 3012> This API is supported since API version 9 and deprecated since API version 11. The substitute API is available only for system applications. 3013 3014**Required permissions**: ohos.permission.MANAGE_AUDIO_CONFIG (available only for system applications) 3015 3016**System capability**: SystemCapability.Multimedia.Audio.Volume 3017 3018**Parameters** 3019 3020| Name | Type | Mandatory| Description | 3021| -------- | ------------------------- | ---- | --------------------------------------------- | 3022| mute | boolean | Yes | Mute status to set. The value **true** means to mute the microphone, and **false** means the opposite.| 3023| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 3024 3025**Example** 3026 3027```ts 3028import { BusinessError } from '@kit.BasicServicesKit'; 3029 3030audioVolumeGroupManager.setMicrophoneMute(true, (err: BusinessError) => { 3031 if (err) { 3032 console.error(`Failed to mute the microphone. ${err}`); 3033 return; 3034 } 3035 console.info('Callback invoked to indicate that the microphone is muted.'); 3036}); 3037``` 3038 3039### setMicrophoneMute<sup>(deprecated)</sup> 3040 3041setMicrophoneMute(mute: boolean): Promise<void> 3042 3043Mutes or unmutes the microphone. This API uses a promise to return the result. 3044 3045> **NOTE** 3046> 3047> This API is supported since API version 9 and deprecated since API version 11. The substitute API is available only for system applications. 3048 3049**Required permissions**: ohos.permission.MANAGE_AUDIO_CONFIG (available only for system applications) 3050 3051**System capability**: SystemCapability.Multimedia.Audio.Volume 3052 3053**Parameters** 3054 3055| Name| Type | Mandatory| Description | 3056| ------ | ------- | ---- | --------------------------------------------- | 3057| mute | boolean | Yes | Mute status to set. The value **true** means to mute the microphone, and **false** means the opposite.| 3058 3059**Return value** 3060 3061| Type | Description | 3062| ------------------- | ------------------------------- | 3063| Promise<void> | Promise that returns no value.| 3064 3065**Example** 3066 3067```ts 3068audioVolumeGroupManager.setMicrophoneMute(true).then(() => { 3069 console.info('Promise returned to indicate that the microphone is muted.'); 3070}); 3071``` 3072 3073### isMicrophoneMute<sup>9+</sup> 3074 3075isMicrophoneMute(callback: AsyncCallback<boolean>): void 3076 3077Checks whether the microphone is muted. This API uses an asynchronous callback to return the result. 3078 3079**System capability**: SystemCapability.Multimedia.Audio.Volume 3080 3081**Parameters** 3082 3083| Name | Type | Mandatory| Description | 3084| -------- | ---------------------------- | ---- | ------------------------------------------------------- | 3085| 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.| 3086 3087**Example** 3088 3089```ts 3090import { BusinessError } from '@kit.BasicServicesKit'; 3091 3092audioVolumeGroupManager.isMicrophoneMute((err: BusinessError, value: boolean) => { 3093 if (err) { 3094 console.error(`Failed to obtain the mute status of the microphone. ${err}`); 3095 return; 3096 } 3097 console.info(`Callback invoked to indicate that the mute status of the microphone is obtained ${value}.`); 3098}); 3099``` 3100 3101### isMicrophoneMute<sup>9+</sup> 3102 3103isMicrophoneMute(): Promise<boolean> 3104 3105Checks whether the microphone is muted. This API uses a promise to return the result. 3106 3107**System capability**: SystemCapability.Multimedia.Audio.Volume 3108 3109**Return value** 3110 3111| Type | Description | 3112| ---------------------- | ------------------------------------------------------------ | 3113| 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.| 3114 3115**Example** 3116 3117```ts 3118audioVolumeGroupManager.isMicrophoneMute().then((value: boolean) => { 3119 console.info(`Promise returned to indicate that the mute status of the microphone is obtained ${value}.`); 3120}); 3121``` 3122 3123### isMicrophoneMuteSync<sup>10+</sup> 3124 3125isMicrophoneMuteSync(): boolean 3126 3127Checks whether the microphone is muted. This API returns the result synchronously. 3128 3129**System capability**: SystemCapability.Multimedia.Audio.Volume 3130 3131**Return value** 3132 3133| Type | Description | 3134| ---------------------- | ------------------------------------------------------------ | 3135| boolean | **true**: The microphone is muted.<br>**false**: The microphone is not muted.| 3136 3137**Example** 3138 3139```ts 3140import { BusinessError } from '@kit.BasicServicesKit'; 3141 3142try { 3143 let value: boolean = audioVolumeGroupManager.isMicrophoneMuteSync(); 3144 console.info(`Indicate that the mute status of the microphone is obtained ${value}.`); 3145} catch (err) { 3146 let error = err as BusinessError; 3147 console.error(`Failed to obtain the mute status of the microphone, error ${error}.`); 3148} 3149``` 3150 3151### on('micStateChange')<sup>9+</sup> 3152 3153on(type: 'micStateChange', callback: Callback<MicStateChangeEvent>): void 3154 3155Subscribes to microphone state change events. This API uses an asynchronous callback to return the result. Such an event is triggered when the microphone state is changed. 3156 3157Currently, 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. 3158 3159**System capability**: SystemCapability.Multimedia.Audio.Volume 3160 3161**Parameters** 3162 3163| Name | Type | Mandatory| Description | 3164| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 3165| type | string | Yes | Event type. The value is fixed at **'micStateChange'**.| 3166| callback | Callback<[MicStateChangeEvent](#micstatechangeevent9)> | Yes | Callback used to return the changed microphone state.| 3167 3168**Error codes** 3169 3170For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3171 3172| ID| Error Message| 3173| ------- | --------------------------------------------| 3174| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3175| 6800101 | Parameter verification failed. | 3176 3177**Example** 3178 3179```ts 3180audioVolumeGroupManager.on('micStateChange', (micStateChange: audio.MicStateChangeEvent) => { 3181 console.info(`Current microphone status is: ${micStateChange.mute} `); 3182}); 3183``` 3184 3185### isVolumeUnadjustable<sup>10+</sup> 3186 3187isVolumeUnadjustable(): boolean 3188 3189Checks 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. 3190 3191**System capability**: SystemCapability.Multimedia.Audio.Volume 3192 3193**Return value** 3194 3195| Type | Description | 3196| ---------------------- | ------------------------------------------------------ | 3197| boolean | **true**: The fixed volume mode is enabled.<br>**false**: The fixed volume mode is disabled.| 3198 3199**Example** 3200 3201```ts 3202let volumeAdjustSwitch: boolean = audioVolumeGroupManager.isVolumeUnadjustable(); 3203console.info(`Whether it is volume unadjustable: ${volumeAdjustSwitch}.`); 3204``` 3205 3206### getSystemVolumeInDb<sup>10+</sup> 3207 3208getSystemVolumeInDb(volumeType: AudioVolumeType, volumeLevel: number, device: DeviceType, callback: AsyncCallback<number>): void 3209 3210Obtains the volume gain. This API uses an asynchronous callback to return the result. 3211 3212**System capability**: SystemCapability.Multimedia.Audio.Volume 3213 3214**Parameters** 3215 3216| Name | Type | Mandatory| Description | 3217| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 3218| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 3219| volumeLevel | number | Yes | Volume level. | 3220| device | [DeviceType](#devicetype) | Yes | Device type. | 3221| 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.| 3222 3223**Error codes** 3224 3225For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3226 3227| ID| Error Message| 3228| ------- | --------------------------------------------| 3229| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3230| 6800101 | Parameter verification failed. Return by callback. | 3231| 6800301 | System error. Return by callback. | 3232 3233**Example** 3234 3235```ts 3236import { BusinessError } from '@kit.BasicServicesKit'; 3237 3238audioVolumeGroupManager.getSystemVolumeInDb(audio.AudioVolumeType.MEDIA, 3, audio.DeviceType.SPEAKER, (err: BusinessError, dB: number) => { 3239 if (err) { 3240 console.error(`Failed to get the volume DB. ${err}`); 3241 } else { 3242 console.info(`Success to get the volume DB. ${dB}`); 3243 } 3244}); 3245``` 3246### getSystemVolumeInDb<sup>10+</sup> 3247 3248getSystemVolumeInDb(volumeType: AudioVolumeType, volumeLevel: number, device: DeviceType): Promise<number> 3249 3250Obtains the volume gain. This API uses a promise to return the result. 3251 3252**System capability**: SystemCapability.Multimedia.Audio.Volume 3253 3254**Parameters** 3255 3256| Name | Type | Mandatory| Description | 3257| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 3258| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 3259| volumeLevel | number | Yes | Volume level. | 3260| device | [DeviceType](#devicetype) | Yes | Device type. | 3261 3262**Return value** 3263 3264| Type | Description | 3265| --------------------- | ---------------------------------- | 3266| Promise<number> | Promise used to return the volume gain (in dB).| 3267 3268**Error codes** 3269 3270For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3271 3272| ID| Error Message| 3273| ------- | --------------------------------------------| 3274| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3275| 6800101 | Parameter verification failed. Return by promise. | 3276| 6800301 | System error. Return by promise. | 3277 3278**Example** 3279 3280```ts 3281import { BusinessError } from '@kit.BasicServicesKit'; 3282 3283audioVolumeGroupManager.getSystemVolumeInDb(audio.AudioVolumeType.MEDIA, 3, audio.DeviceType.SPEAKER).then((value: number) => { 3284 console.info(`Success to get the volume DB. ${value}`); 3285}).catch((error: BusinessError) => { 3286 console.error(`Fail to adjust the system volume by step. ${error}`); 3287}); 3288``` 3289 3290### getSystemVolumeInDbSync<sup>10+</sup> 3291 3292getSystemVolumeInDbSync(volumeType: AudioVolumeType, volumeLevel: number, device: DeviceType): number 3293 3294Obtains the volume gain. This API returns the result synchronously. 3295 3296**System capability**: SystemCapability.Multimedia.Audio.Volume 3297 3298**Parameters** 3299 3300| Name | Type | Mandatory| Description | 3301| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 3302| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 3303| volumeLevel | number | Yes | Volume level. | 3304| device | [DeviceType](#devicetype) | Yes | Device type. | 3305 3306**Return value** 3307 3308| Type | Description | 3309| --------------------- | ---------------------------------- | 3310| number | Volume gain (in dB).| 3311 3312**Error codes** 3313 3314For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3315 3316| ID| Error Message| 3317| ------- | --------------------------------------------| 3318| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3319| 6800101 | Parameter verification failed. | 3320 3321**Example** 3322 3323```ts 3324import { BusinessError } from '@kit.BasicServicesKit'; 3325 3326try { 3327 let value: number = audioVolumeGroupManager.getSystemVolumeInDbSync(audio.AudioVolumeType.MEDIA, 3, audio.DeviceType.SPEAKER); 3328 console.info(`Success to get the volume DB. ${value}`); 3329} catch (err) { 3330 let error = err as BusinessError; 3331 console.error(`Fail to adjust the system volume by step. ${error}`); 3332} 3333``` 3334 3335### getMaxAmplitudeForInputDevice<sup>12+</sup> 3336 3337getMaxAmplitudeForInputDevice(inputDevice: AudioDeviceDescriptor): Promise<number> 3338 3339Obtains the maximum amplitude of the audio stream for an input device. This API uses a promise to return the result. 3340 3341**System capability**: SystemCapability.Multimedia.Audio.Volume 3342 3343**Parameters** 3344 3345| Name | Type | Mandatory| Description | 3346| ----------- | ------------------------------------- | ---- | --------------------------------------------------- | 3347| inputDevice | [AudioDeviceDescriptor](#audiodevicedescriptor) | Yes | Descriptor of the target device. | 3348 3349**Return value** 3350 3351| Type | Description | 3352| --------------------- | ---------------------------------- | 3353| Promise<number> | Promise used to return the maximum amplitude, which ranges from 0 to 1.| 3354 3355**Error codes** 3356 3357For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3358 3359| ID| Error Message| 3360| ------- | --------------------------------------------| 3361| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3362| 6800101 | Parameter verification failed. Return by promise. | 3363| 6800301 | System error. Return by promise. | 3364 3365**Example** 3366 3367```ts 3368import { BusinessError } from '@kit.BasicServicesKit'; 3369 3370let capturerInfo: audio.AudioCapturerInfo = { 3371 source: audio.SourceType.SOURCE_TYPE_MIC, 3372 capturerFlags: 0 3373} 3374 3375audioRoutingManager.getPreferredInputDeviceForCapturerInfo(capturerInfo).then((data) => { 3376 audioVolumeGroupManager.getMaxAmplitudeForInputDevice(data[0]).then((value) => { 3377 console.info(`mic volatileume amplitude is: ${value}`); 3378 }).catch((err: BusinessError) => { 3379 console.error("getMaxAmplitudeForInputDevice error" + JSON.stringify(err)); 3380 }) 3381}).catch((err: BusinessError) => { 3382 console.error("get outputDeviceId error" + JSON.stringify(err)); 3383}) 3384``` 3385 3386### getMaxAmplitudeForOutputDevice<sup>12+</sup> 3387 3388getMaxAmplitudeForOutputDevice(outputDevice: AudioDeviceDescriptor): Promise<number> 3389 3390Obtains the maximum amplitude of the audio stream for an output device. This API uses a promise to return the result. 3391 3392**System capability**: SystemCapability.Multimedia.Audio.Volume 3393 3394**Parameters** 3395 3396| Name | Type | Mandatory| Description | 3397| ------------ | --------------------------------------- | ---- | -------------------------------------------------------- | 3398| outputDevice | [AudioDeviceDescriptor](#audiodevicedescriptor) | Yes | Descriptor of the target device. | 3399 3400**Return value** 3401 3402| Type | Description | 3403| --------------------- | ---------------------------------- | 3404| Promise<number> | Promise used to return the maximum amplitude, which ranges from 0 to 1.| 3405 3406**Error codes** 3407 3408For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3409 3410| ID| Error Message| 3411| ------- | --------------------------------------------| 3412| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3413| 6800101 | Parameter verification failed. Return by promise. | 3414| 6800301 | System error. Return by promise. | 3415 3416**Example** 3417 3418```ts 3419import { BusinessError } from '@kit.BasicServicesKit'; 3420 3421let rendererInfo: audio.AudioRendererInfo = { 3422 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 3423 rendererFlags : 0 3424} 3425 3426audioRoutingManager.getPreferOutputDeviceForRendererInfo(rendererInfo).then((data) => { 3427 audioVolumeGroupManager.getMaxAmplitudeForOutputDevice(data[0]).then((value) => { 3428 console.info(`mic volatileume amplitude is: ${value}`); 3429 }).catch((err: BusinessError) => { 3430 console.error("getMaxAmplitudeForOutputDevice error" + JSON.stringify(err)); 3431 }) 3432}).catch((err: BusinessError) => { 3433 console.error("getPreferOutputDeviceForRendererInfo error" + JSON.stringify(err)); 3434}) 3435``` 3436 3437## AudioStreamManager<sup>9+</sup> 3438 3439Implements audio stream management. Before calling any API in **AudioStreamManager**, you must use [getStreamManager](#getstreammanager9) to obtain an **AudioStreamManager** instance. 3440 3441### getCurrentAudioRendererInfoArray<sup>9+</sup> 3442 3443getCurrentAudioRendererInfoArray(callback: AsyncCallback<AudioRendererChangeInfoArray>): void 3444 3445Obtains the information about the current audio renderer. This API uses an asynchronous callback to return the result. 3446 3447**System capability**: SystemCapability.Multimedia.Audio.Renderer 3448 3449**Parameters** 3450 3451| Name | Type | Mandatory | Description | 3452| -------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | 3453| 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. | 3454 3455**Example** 3456 3457```ts 3458import { BusinessError } from '@kit.BasicServicesKit'; 3459 3460audioStreamManager.getCurrentAudioRendererInfoArray(async (err: BusinessError, AudioRendererChangeInfoArray: audio.AudioRendererChangeInfoArray) => { 3461 console.info('getCurrentAudioRendererInfoArray **** Get Callback Called ****'); 3462 if (err) { 3463 console.error(`getCurrentAudioRendererInfoArray :ERROR: ${err}`); 3464 } else { 3465 if (AudioRendererChangeInfoArray != null) { 3466 for (let i = 0; i < AudioRendererChangeInfoArray.length; i++) { 3467 let AudioRendererChangeInfo: audio.AudioRendererChangeInfo = AudioRendererChangeInfoArray[i]; 3468 console.info(`StreamId for ${i} is: ${AudioRendererChangeInfo.streamId}`); 3469 console.info(`Content ${i} is: ${AudioRendererChangeInfo.rendererInfo.content}`); 3470 console.info(`Stream ${i} is: ${AudioRendererChangeInfo.rendererInfo.usage}`); 3471 console.info(`Flag ${i} is: ${AudioRendererChangeInfo.rendererInfo.rendererFlags}`); 3472 for (let j = 0;j < AudioRendererChangeInfo.deviceDescriptors.length; j++) { 3473 console.info(`Id: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].id}`); 3474 console.info(`Type: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceType}`); 3475 console.info(`Role: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceRole}`); 3476 console.info(`Name: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].name}`); 3477 console.info(`Address: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].address}`); 3478 console.info(`SampleRate: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].sampleRates[0]}`); 3479 console.info(`ChannelCount: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelCounts[0]}`); 3480 console.info(`ChannelMask: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelMasks[0]}`); 3481 } 3482 } 3483 } 3484 } 3485}); 3486``` 3487 3488### getCurrentAudioRendererInfoArray<sup>9+</sup> 3489 3490getCurrentAudioRendererInfoArray(): Promise<AudioRendererChangeInfoArray> 3491 3492Obtains the information about the current audio renderer. This API uses a promise to return the result. 3493 3494**System capability**: SystemCapability.Multimedia.Audio.Renderer 3495 3496**Return value** 3497 3498| Type | Description | 3499| ------------------------------------------------------------ | ------------------------------------------------ | 3500| Promise<[AudioRendererChangeInfoArray](#audiorendererchangeinfoarray9)> | Promise used to return the renderer information. | 3501 3502**Example** 3503 3504```ts 3505import { BusinessError } from '@kit.BasicServicesKit'; 3506 3507async function getCurrentAudioRendererInfoArray(){ 3508 await audioStreamManager.getCurrentAudioRendererInfoArray().then((AudioRendererChangeInfoArray: audio.AudioRendererChangeInfoArray) => { 3509 console.info(`getCurrentAudioRendererInfoArray ######### Get Promise is called ##########`); 3510 if (AudioRendererChangeInfoArray != null) { 3511 for (let i = 0; i < AudioRendererChangeInfoArray.length; i++) { 3512 let AudioRendererChangeInfo: audio.AudioRendererChangeInfo = AudioRendererChangeInfoArray[i]; 3513 console.info(`StreamId for ${i} is: ${AudioRendererChangeInfo.streamId}`); 3514 console.info(`Content ${i} is: ${AudioRendererChangeInfo.rendererInfo.content}`); 3515 console.info(`Stream ${i} is: ${AudioRendererChangeInfo.rendererInfo.usage}`); 3516 console.info(`Flag ${i} is: ${AudioRendererChangeInfo.rendererInfo.rendererFlags}`); 3517 for (let j = 0;j < AudioRendererChangeInfo.deviceDescriptors.length; j++) { 3518 console.info(`Id: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].id}`); 3519 console.info(`Type: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceType}`); 3520 console.info(`Role: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceRole}`); 3521 console.info(`Name: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].name}`); 3522 console.info(`Address: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].address}`); 3523 console.info(`SampleRate: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].sampleRates[0]}`); 3524 console.info(`ChannelCount: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelCounts[0]}`); 3525 console.info(`ChannelMask: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelMasks[0]}`); 3526 } 3527 } 3528 } 3529 }).catch((err: BusinessError) => { 3530 console.error(`getCurrentAudioRendererInfoArray :ERROR: ${err}`); 3531 }); 3532} 3533``` 3534 3535### getCurrentAudioRendererInfoArraySync<sup>10+</sup> 3536 3537getCurrentAudioRendererInfoArraySync(): AudioRendererChangeInfoArray 3538 3539Obtains the information about the current audio renderer. This API returns the result synchronously. 3540 3541**System capability**: SystemCapability.Multimedia.Audio.Renderer 3542 3543**Return value** 3544 3545| Type | Description | 3546| ------------------------------------------------------------ | --------------------------- | 3547| [AudioRendererChangeInfoArray](#audiorendererchangeinfoarray9) | Audio renderer information. | 3548 3549**Example** 3550 3551```ts 3552import { BusinessError } from '@kit.BasicServicesKit'; 3553 3554try { 3555 let audioRendererChangeInfoArray: audio.AudioRendererChangeInfoArray = audioStreamManager.getCurrentAudioRendererInfoArraySync(); 3556 console.info(`getCurrentAudioRendererInfoArraySync success.`); 3557 if (audioRendererChangeInfoArray != null) { 3558 for (let i = 0; i < audioRendererChangeInfoArray.length; i++) { 3559 let AudioRendererChangeInfo: audio.AudioRendererChangeInfo = audioRendererChangeInfoArray[i]; 3560 console.info(`StreamId for ${i} is: ${AudioRendererChangeInfo.streamId}`); 3561 console.info(`Content ${i} is: ${AudioRendererChangeInfo.rendererInfo.content}`); 3562 console.info(`Stream ${i} is: ${AudioRendererChangeInfo.rendererInfo.usage}`); 3563 console.info(`Flag ${i} is: ${AudioRendererChangeInfo.rendererInfo.rendererFlags}`); 3564 for (let j = 0;j < AudioRendererChangeInfo.deviceDescriptors.length; j++) { 3565 console.info(`Id: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].id}`); 3566 console.info(`Type: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceType}`); 3567 console.info(`Role: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceRole}`); 3568 console.info(`Name: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].name}`); 3569 console.info(`Address: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].address}`); 3570 console.info(`SampleRate: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].sampleRates[0]}`); 3571 console.info(`ChannelCount: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelCounts[0]}`); 3572 console.info(`ChannelMask: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelMasks[0]}`); 3573 } 3574 } 3575 } 3576} catch (err) { 3577 let error = err as BusinessError; 3578 console.error(`getCurrentAudioRendererInfoArraySync :ERROR: ${error}`); 3579} 3580``` 3581 3582### getCurrentAudioCapturerInfoArray<sup>9+</sup> 3583 3584getCurrentAudioCapturerInfoArray(callback: AsyncCallback<AudioCapturerChangeInfoArray>): void 3585 3586Obtains the information about the current audio capturer. This API uses an asynchronous callback to return the result. 3587 3588**System capability**: SystemCapability.Multimedia.Audio.Renderer 3589 3590**Parameters** 3591 3592| Name | Type | Mandatory | Description | 3593| -------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | 3594| 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. | 3595 3596**Example** 3597 3598```ts 3599import { BusinessError } from '@kit.BasicServicesKit'; 3600 3601audioStreamManager.getCurrentAudioCapturerInfoArray(async (err: BusinessError, AudioCapturerChangeInfoArray: audio.AudioCapturerChangeInfoArray) => { 3602 console.info('getCurrentAudioCapturerInfoArray **** Get Callback Called ****'); 3603 if (err) { 3604 console.error(`getCurrentAudioCapturerInfoArray :ERROR: ${err}`); 3605 } else { 3606 if (AudioCapturerChangeInfoArray != null) { 3607 for (let i = 0; i < AudioCapturerChangeInfoArray.length; i++) { 3608 console.info(`StreamId for ${i} is: ${AudioCapturerChangeInfoArray[i].streamId}`); 3609 console.info(`Source for ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.source}`); 3610 console.info(`Flag ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.capturerFlags}`); 3611 for (let j = 0; j < AudioCapturerChangeInfoArray[i].deviceDescriptors.length; j++) { 3612 console.info(`Id: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].id}`); 3613 console.info(`Type: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceType}`); 3614 console.info(`Role: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceRole}`); 3615 console.info(`Name: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].name}`); 3616 console.info(`Address: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].address}`); 3617 console.info(`SampleRate: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].sampleRates[0]}`); 3618 console.info(`ChannelCount: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelCounts[0]}`); 3619 console.info(`ChannelMask: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelMasks[0]}`); 3620 } 3621 } 3622 } 3623 } 3624}); 3625``` 3626 3627### getCurrentAudioCapturerInfoArray<sup>9+</sup> 3628 3629getCurrentAudioCapturerInfoArray(): Promise<AudioCapturerChangeInfoArray> 3630 3631Obtains the information about the current audio capturer. This API uses a promise to return the result. 3632 3633**System capability**: SystemCapability.Multimedia.Audio.Renderer 3634 3635**Return value** 3636 3637| Type | Description | 3638| ------------------------------------------------------------ | ------------------------------------------------------ | 3639| Promise<[AudioCapturerChangeInfoArray](#audiocapturerchangeinfoarray9)> | Promise used to return the audio capturer information. | 3640 3641**Example** 3642 3643```ts 3644import { BusinessError } from '@kit.BasicServicesKit'; 3645 3646async function getCurrentAudioCapturerInfoArray(){ 3647 await audioStreamManager.getCurrentAudioCapturerInfoArray().then((AudioCapturerChangeInfoArray: audio.AudioCapturerChangeInfoArray) => { 3648 console.info('getCurrentAudioCapturerInfoArray **** Get Promise Called ****'); 3649 if (AudioCapturerChangeInfoArray != null) { 3650 for (let i = 0; i < AudioCapturerChangeInfoArray.length; i++) { 3651 console.info(`StreamId for ${i} is: ${AudioCapturerChangeInfoArray[i].streamId}`); 3652 console.info(`Source for ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.source}`); 3653 console.info(`Flag ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.capturerFlags}`); 3654 for (let j = 0; j < AudioCapturerChangeInfoArray[i].deviceDescriptors.length; j++) { 3655 console.info(`Id: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].id}`); 3656 console.info(`Type: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceType}`); 3657 console.info(`Role: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceRole}`); 3658 console.info(`Name: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].name}`); 3659 console.info(`Address: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].address}`); 3660 console.info(`SampleRate: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].sampleRates[0]}`); 3661 console.info(`ChannelCount: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelCounts[0]}`); 3662 console.info(`ChannelMask: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelMasks[0]}`); 3663 } 3664 } 3665 } 3666 }).catch((err: BusinessError) => { 3667 console.error(`getCurrentAudioCapturerInfoArray :ERROR: ${err}`); 3668 }); 3669} 3670``` 3671 3672### getCurrentAudioCapturerInfoArraySync<sup>10+</sup> 3673 3674getCurrentAudioCapturerInfoArraySync(): AudioCapturerChangeInfoArray 3675 3676Obtains the information about the current audio capturer. This API returns the result synchronously. 3677 3678**System capability**: SystemCapability.Multimedia.Audio.Capturer 3679 3680**Return value** 3681 3682| Type | Description | 3683| ------------------------------------------------------------ | --------------------------- | 3684| [AudioCapturerChangeInfoArray](#audiocapturerchangeinfoarray9) | Audio capturer information. | 3685 3686**Example** 3687 3688```ts 3689import { BusinessError } from '@kit.BasicServicesKit'; 3690 3691try { 3692 let audioCapturerChangeInfoArray: audio.AudioCapturerChangeInfoArray = audioStreamManager.getCurrentAudioCapturerInfoArraySync(); 3693 console.info('getCurrentAudioCapturerInfoArraySync success.'); 3694 if (audioCapturerChangeInfoArray != null) { 3695 for (let i = 0; i < audioCapturerChangeInfoArray.length; i++) { 3696 console.info(`StreamId for ${i} is: ${audioCapturerChangeInfoArray[i].streamId}`); 3697 console.info(`Source for ${i} is: ${audioCapturerChangeInfoArray[i].capturerInfo.source}`); 3698 console.info(`Flag ${i} is: ${audioCapturerChangeInfoArray[i].capturerInfo.capturerFlags}`); 3699 for (let j = 0; j < audioCapturerChangeInfoArray[i].deviceDescriptors.length; j++) { 3700 console.info(`Id: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].id}`); 3701 console.info(`Type: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceType}`); 3702 console.info(`Role: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceRole}`); 3703 console.info(`Name: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].name}`); 3704 console.info(`Address: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].address}`); 3705 console.info(`SampleRate: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].sampleRates[0]}`); 3706 console.info(`ChannelCount: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].channelCounts[0]}`); 3707 console.info(`ChannelMask: ${i} : ${audioCapturerChangeInfoArray[i].deviceDescriptors[j].channelMasks[0]}`); 3708 } 3709 } 3710 } 3711} catch (err) { 3712 let error = err as BusinessError; 3713 console.error(`getCurrentAudioCapturerInfoArraySync ERROR: ${error}`); 3714} 3715``` 3716 3717### on('audioRendererChange')<sup>9+</sup> 3718 3719on(type: 'audioRendererChange', callback: Callback<AudioRendererChangeInfoArray>): void 3720 3721Subscribes to audio renderer change events. This API uses an asynchronous callback to return the result. Such an event is triggered when the audio playback stream status or device is changed. 3722 3723**System capability**: SystemCapability.Multimedia.Audio.Renderer 3724 3725**Parameters** 3726 3727| Name | Type | Mandatory | Description | 3728| -------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | 3729| type | string | Yes | Event type. The value is fixed at **'audioRendererChange'**. | 3730| callback | Callback<[AudioRendererChangeInfoArray](#audiorendererchangeinfoarray9)> | Yes | Callback used to return the audio renderer information. | 3731 3732**Error codes** 3733 3734For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3735 3736| ID | Error Message | 3737| ------- | ------------------------------------------------------------ | 3738| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3739| 6800101 | Parameter verification failed. | 3740 3741**Example** 3742 3743```ts 3744audioStreamManager.on('audioRendererChange', (AudioRendererChangeInfoArray: audio.AudioRendererChangeInfoArray) => { 3745 for (let i = 0; i < AudioRendererChangeInfoArray.length; i++) { 3746 let AudioRendererChangeInfo: audio.AudioRendererChangeInfo = AudioRendererChangeInfoArray[i]; 3747 console.info(`## RendererChange on is called for ${i} ##`); 3748 console.info(`StreamId for ${i} is: ${AudioRendererChangeInfo.streamId}`); 3749 console.info(`Content ${i} is: ${AudioRendererChangeInfo.rendererInfo.content}`); 3750 console.info(`Stream ${i} is: ${AudioRendererChangeInfo.rendererInfo.usage}`); 3751 console.info(`Flag ${i} is: ${AudioRendererChangeInfo.rendererInfo.rendererFlags}`); 3752 for (let j = 0;j < AudioRendererChangeInfo.deviceDescriptors.length; j++) { 3753 console.info(`Id: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].id}`); 3754 console.info(`Type: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceType}`); 3755 console.info(`Role: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].deviceRole}`); 3756 console.info(`Name: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].name}`); 3757 console.info(`Address: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].address}`); 3758 console.info(`SampleRate: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].sampleRates[0]}`); 3759 console.info(`ChannelCount: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelCounts[0]}`); 3760 console.info(`ChannelMask: ${i} : ${AudioRendererChangeInfo.deviceDescriptors[j].channelMasks[0]}`); 3761 } 3762 } 3763}); 3764``` 3765 3766### off('audioRendererChange')<sup>9+</sup> 3767 3768off(type: 'audioRendererChange'): void 3769 3770Unsubscribes from audio renderer change events. 3771 3772**System capability**: SystemCapability.Multimedia.Audio.Renderer 3773 3774**Parameters** 3775 3776| Name | Type | Mandatory | Description | 3777| ---- | ------ | --------- | ------------------------------------------------------------ | 3778| type | string | Yes | Event type. The value is fixed at **'audioRendererChange'**. | 3779 3780**Error codes** 3781 3782For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3783 3784| ID | Error Message | 3785| ------- | ------------------------------------------------------------ | 3786| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3787| 6800101 | Parameter verification failed. | 3788 3789**Example** 3790 3791```ts 3792audioStreamManager.off('audioRendererChange'); 3793console.info('######### RendererChange Off is called #########'); 3794``` 3795 3796### on('audioCapturerChange')<sup>9+</sup> 3797 3798on(type: 'audioCapturerChange', callback: Callback<AudioCapturerChangeInfoArray>): void 3799 3800Subscribes to audio capturer change events. This API uses an asynchronous callback to return the result. Such an event is triggered when the audio recording stream status or device is changed. 3801 3802**System capability**: SystemCapability.Multimedia.Audio.Capturer 3803 3804**Parameters** 3805 3806| Name | Type | Mandatory | Description | 3807| -------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | 3808| type | string | Yes | Event type. The value is fixed at **'audioCapturerChange'**. | 3809| callback | Callback<[AudioCapturerChangeInfoArray](#audiocapturerchangeinfoarray9)> | Yes | Callback used to return the audio capturer information. | 3810 3811**Error codes** 3812 3813For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3814 3815| ID | Error Message | 3816| ------- | ------------------------------------------------------------ | 3817| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3818| 6800101 | Parameter verification failed. | 3819 3820**Example** 3821 3822```ts 3823audioStreamManager.on('audioCapturerChange', (AudioCapturerChangeInfoArray: audio.AudioCapturerChangeInfoArray) => { 3824 for (let i = 0; i < AudioCapturerChangeInfoArray.length; i++) { 3825 console.info(`## CapChange on is called for element ${i} ##`); 3826 console.info(`StreamId for ${i} is: ${AudioCapturerChangeInfoArray[i].streamId}`); 3827 console.info(`Source for ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.source}`); 3828 console.info(`Flag ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.capturerFlags}`); 3829 for (let j = 0; j < AudioCapturerChangeInfoArray[i].deviceDescriptors.length; j++) { 3830 console.info(`Id: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].id}`); 3831 console.info(`Type: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceType}`); 3832 console.info(`Role: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceRole}`); 3833 console.info(`Name: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].name}`); 3834 console.info(`Address: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].address}`); 3835 console.info(`SampleRate: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].sampleRates[0]}`); 3836 console.info(`ChannelCount: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelCounts[0]}`); 3837 console.info(`ChannelMask: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelMasks[0]}`); 3838 } 3839 } 3840}); 3841 3842``` 3843 3844### off('audioCapturerChange')<sup>9+</sup> 3845 3846off(type: 'audioCapturerChange'): void 3847 3848Unsubscribes from audio capturer change events. 3849 3850**System capability**: SystemCapability.Multimedia.Audio.Capturer 3851 3852**Parameters** 3853 3854| Name | Type | Mandatory | Description | 3855| ---- | ------ | --------- | ------------------------------------------------------------ | 3856| type | string | Yes | Event type. The value is fixed at **'audioCapturerChange'**. | 3857 3858**Error codes** 3859 3860For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3861 3862| ID | Error Message | 3863| ------- | ------------------------------------------------------------ | 3864| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3865| 6800101 | Parameter verification failed. | 3866 3867**Example** 3868 3869```ts 3870audioStreamManager.off('audioCapturerChange'); 3871console.info('######### CapturerChange Off is called #########'); 3872 3873 3874``` 3875 3876### isActive<sup>9+</sup> 3877 3878isActive(volumeType: AudioVolumeType, callback: AsyncCallback<boolean>): void 3879 3880Checks whether a stream is active. This API uses an asynchronous callback to return the result. 3881 3882**System capability**: SystemCapability.Multimedia.Audio.Renderer 3883 3884**Parameters** 3885 3886| Name | Type | Mandatory | Description | 3887| ---------- | ----------------------------------- | --------- | ------------------------------------------------------------ | 3888| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream types. | 3889| 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. | 3890 3891**Example** 3892 3893```ts 3894import { BusinessError } from '@kit.BasicServicesKit'; 3895 3896audioStreamManager.isActive(audio.AudioVolumeType.MEDIA, (err: BusinessError, value: boolean) => { 3897if (err) { 3898 console.error(`Failed to obtain the active status of the stream. ${err}`); 3899 return; 3900} 3901 console.info(`Callback invoked to indicate that the active status of the stream is obtained ${value}.`); 3902}); 3903 3904``` 3905 3906### isActive<sup>9+</sup> 3907 3908isActive(volumeType: AudioVolumeType): Promise<boolean> 3909 3910Checks whether a stream is active. This API uses a promise to return the result. 3911 3912**System capability**: SystemCapability.Multimedia.Audio.Renderer 3913 3914**Parameters** 3915 3916| Name | Type | Mandatory | Description | 3917| ---------- | ----------------------------------- | --------- | ------------------- | 3918| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream types. | 3919 3920**Return value** 3921 3922| Type | Description | 3923| ---------------------- | ------------------------------------------------------------ | 3924| 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. | 3925 3926**Example** 3927 3928```ts 3929audioStreamManager.isActive(audio.AudioVolumeType.MEDIA).then((value: boolean) => { 3930 console.info(`Promise returned to indicate that the active status of the stream is obtained ${value}.`); 3931}); 3932 3933``` 3934 3935### isActiveSync<sup>10+</sup> 3936 3937isActiveSync(volumeType: AudioVolumeType): boolean 3938 3939Checks whether a stream is active. This API returns the result synchronously. 3940 3941**System capability**: SystemCapability.Multimedia.Audio.Renderer 3942 3943**Parameters** 3944 3945| Name | Type | Mandatory | Description | 3946| ---------- | ----------------------------------- | --------- | ------------------- | 3947| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream types. | 3948 3949**Return value** 3950 3951| Type | Description | 3952| ------- | ------------------------------------------------------------ | 3953| boolean | **true**: The stream is active.<br> **false**: The stream is inactive. | 3954 3955**Error codes** 3956 3957For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3958 3959| ID | Error Message | 3960| ------- | ------------------------------------------------------------ | 3961| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3962| 6800101 | Parameter verification failed. | 3963 3964**Example** 3965 3966```ts 3967import { BusinessError } from '@kit.BasicServicesKit'; 3968 3969try { 3970 let value: boolean = audioStreamManager.isActiveSync(audio.AudioVolumeType.MEDIA); 3971 console.info(`Indicate that the active status of the stream is obtained ${value}.`); 3972} catch (err) { 3973 let error = err as BusinessError; 3974 console.error(`Failed to obtain the active status of the stream ${error}.`); 3975} 3976 3977``` 3978 3979### getAudioEffectInfoArray<sup>10+</sup> 3980 3981getAudioEffectInfoArray(usage: StreamUsage, callback: AsyncCallback<AudioEffectInfoArray>): void 3982 3983Obtains information about the audio effect mode in use. This API uses an asynchronous callback to return the result. 3984 3985**System capability**: SystemCapability.Multimedia.Audio.Renderer 3986 3987**Parameters** 3988 3989| Name | Type | Mandatory | Description | 3990| -------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | 3991| usage | [StreamUsage](#streamusage) | Yes | Audio stream usage. | 3992| 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. | 3993 3994**Error codes** 3995 3996For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3997 3998| ID | Error Message | 3999| ------- | ------------------------------------------------------------ | 4000| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4001| 6800101 | Parameter verification failed. Return by callback. | 4002 4003**Example** 4004 4005```ts 4006import { BusinessError } from '@kit.BasicServicesKit'; 4007 4008audioStreamManager.getAudioEffectInfoArray(audio.StreamUsage.STREAM_USAGE_MUSIC, async (err: BusinessError, audioEffectInfoArray: audio.AudioEffectInfoArray) => { 4009 console.info('getAudioEffectInfoArray **** Get Callback Called ****'); 4010 if (err) { 4011 console.error(`getAudioEffectInfoArray :ERROR: ${err}`); 4012 return; 4013 } else { 4014 console.info(`The effect modes are: ${audioEffectInfoArray}`); 4015 } 4016}); 4017 4018``` 4019 4020### getAudioEffectInfoArray<sup>10+</sup> 4021 4022getAudioEffectInfoArray(usage: StreamUsage): Promise<AudioEffectInfoArray> 4023 4024Obtains information about the audio effect mode in use. This API uses a promise to return the result. 4025 4026**System capability**: SystemCapability.Multimedia.Audio.Renderer 4027 4028**Parameters** 4029 4030| Name | Type | Mandatory | Description | 4031| ----- | --------------------------- | --------- | ------------------- | 4032| usage | [StreamUsage](#streamusage) | Yes | Audio stream usage. | 4033 4034**Return value** 4035 4036| Type | Description | 4037| -------------------------------------------------------- | ------------------------------------------------------------ | 4038| Promise<[AudioEffectInfoArray](#audioeffectinfoarray10)> | Promise used to return the information about the audio effect mode obtained. | 4039 4040**Error codes** 4041 4042For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4043 4044| ID | Error Message | 4045| ------- | ------------------------------------------------------------ | 4046| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4047| 6800101 | Parameter verification failed. Return by promise. | 4048 4049**Example** 4050 4051```ts 4052import { BusinessError } from '@kit.BasicServicesKit'; 4053 4054audioStreamManager.getAudioEffectInfoArray(audio.StreamUsage.STREAM_USAGE_MUSIC).then((audioEffectInfoArray: audio.AudioEffectInfoArray) => { 4055 console.info('getAudioEffectInfoArray ######### Get Promise is called ##########'); 4056 console.info(`The effect modes are: ${audioEffectInfoArray}`); 4057}).catch((err: BusinessError) => { 4058 console.error(`getAudioEffectInfoArray :ERROR: ${err}`); 4059}); 4060 4061``` 4062 4063### getAudioEffectInfoArraySync<sup>10+</sup> 4064 4065getAudioEffectInfoArraySync(usage: StreamUsage): AudioEffectInfoArray 4066 4067Obtains information about the audio effect mode in use. This API returns the result synchronously. 4068 4069**System capability**: SystemCapability.Multimedia.Audio.Renderer 4070 4071**Parameters** 4072 4073| Name | Type | Mandatory | Description | 4074| ----- | --------------------------- | --------- | ------------------- | 4075| usage | [StreamUsage](#streamusage) | Yes | Audio stream usage. | 4076 4077**Return value** 4078 4079| Type | Description | 4080| ----------------------------------------------- | ---------------------------------------- | 4081| [AudioEffectInfoArray](#audioeffectinfoarray10) | Information about the audio effect mode. | 4082 4083**Error codes** 4084 4085For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4086 4087| ID | Error Message | 4088| ------- | ------------------------------------------------------------ | 4089| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4090| 6800101 | Parameter verification failed. | 4091 4092**Example** 4093 4094```ts 4095import { BusinessError } from '@kit.BasicServicesKit'; 4096 4097try { 4098 let audioEffectInfoArray: audio.AudioEffectInfoArray = audioStreamManager.getAudioEffectInfoArraySync(audio.StreamUsage.STREAM_USAGE_MUSIC); 4099 console.info(`The effect modes are: ${audioEffectInfoArray}`); 4100} catch (err) { 4101 let error = err as BusinessError; 4102 console.error(`getAudioEffectInfoArraySync ERROR: ${error}`); 4103} 4104 4105``` 4106 4107## AudioRoutingManager<sup>9+</sup> 4108 4109Implements audio routing management. Before calling any API in **AudioRoutingManager**, you must use [getRoutingManager](#getroutingmanager9) to obtain an **AudioRoutingManager** instance. 4110 4111### getDevices<sup>9+</sup> 4112 4113getDevices(deviceFlag: DeviceFlag, callback: AsyncCallback<AudioDeviceDescriptors>): void 4114 4115Obtains the audio devices with a specific flag. This API uses an asynchronous callback to return the result. 4116 4117**System capability**: SystemCapability.Multimedia.Audio.Device 4118 4119**Parameters** 4120 4121| Name | Type | Mandatory | Description | 4122| ---------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | 4123| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag. | 4124| 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. | 4125 4126**Example** 4127 4128```ts 4129import { BusinessError } from '@kit.BasicServicesKit'; 4130 4131audioRoutingManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG, (err: BusinessError, value: audio.AudioDeviceDescriptors) => { 4132 if (err) { 4133 console.error(`Failed to obtain the device list. ${err}`); 4134 return; 4135 } 4136 console.info('Callback invoked to indicate that the device list is obtained.'); 4137}); 4138 4139``` 4140 4141### getDevices<sup>9+</sup> 4142 4143getDevices(deviceFlag: DeviceFlag): Promise<AudioDeviceDescriptors> 4144 4145Obtains the audio devices with a specific flag. This API uses a promise to return the result. 4146 4147**System capability**: SystemCapability.Multimedia.Audio.Device 4148 4149**Parameters** 4150 4151| Name | Type | Mandatory | Description | 4152| ---------- | ------------------------- | --------- | ------------------ | 4153| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag. | 4154 4155**Return value** 4156 4157| Type | Description | 4158| ------------------------------------------------------------ | --------------------------------------- | 4159| Promise<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Promise used to return the device list. | 4160 4161**Example** 4162 4163```ts 4164audioRoutingManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES_FLAG).then((data: audio.AudioDeviceDescriptors) => { 4165 console.info('Promise returned to indicate that the device list is obtained.'); 4166}); 4167 4168``` 4169 4170### getDevicesSync<sup>10+</sup> 4171 4172getDevicesSync(deviceFlag: DeviceFlag): AudioDeviceDescriptors 4173 4174Obtains the audio devices with a specific flag. This API returns the result synchronously. 4175 4176**System capability**: SystemCapability.Multimedia.Audio.Device 4177 4178**Parameters** 4179 4180| Name | Type | Mandatory | Description | 4181| ---------- | ------------------------- | --------- | ------------------ | 4182| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag. | 4183 4184**Return value** 4185 4186| Type | Description | 4187| ------------------------------------------------- | ------------ | 4188| [AudioDeviceDescriptors](#audiodevicedescriptors) | Device list. | 4189 4190**Error codes** 4191 4192For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4193 4194| ID | Error Message | 4195| ------- | ------------------------------------------------------------ | 4196| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4197| 6800101 | Parameter verification failed. | 4198 4199**Example** 4200 4201```ts 4202import { BusinessError } from '@kit.BasicServicesKit'; 4203 4204try { 4205 let data: audio.AudioDeviceDescriptors = audioRoutingManager.getDevicesSync(audio.DeviceFlag.OUTPUT_DEVICES_FLAG); 4206 console.info(`Indicate that the device list is obtained ${data}`); 4207} catch (err) { 4208 let error = err as BusinessError; 4209 console.error(`Failed to obtain the device list. ${error}`); 4210} 4211 4212``` 4213 4214### on('deviceChange')<sup>9+</sup> 4215 4216on(type: 'deviceChange', deviceFlag: DeviceFlag, callback: Callback<DeviceChangeAction\>): void 4217 4218Subscribes to audio device change events. This API uses an asynchronous callback to return the result. Such an event is triggered when the connection status of an audio device is changed. 4219 4220**System capability**: SystemCapability.Multimedia.Audio.Device 4221 4222**Parameters** 4223 4224| Name | Type | Mandatory | Description | 4225| :--------- | :--------------------------------------------------- | :-------- | :---------------------------------------------------- | 4226| type | string | Yes | Event type. The value is fixed at **'deviceChange'**. | 4227| deviceFlag | [DeviceFlag](#deviceflag) | Yes | Audio device flag. | 4228| callback | Callback<[DeviceChangeAction](#devicechangeaction)\> | Yes | Callback used to return the device change details. | 4229 4230**Error codes** 4231 4232For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4233 4234| ID | Error Message | 4235| ------- | ------------------------------------------------------------ | 4236| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4237| 6800101 | Parameter verification failed. | 4238 4239**Example** 4240 4241```ts 4242audioRoutingManager.on('deviceChange', audio.DeviceFlag.OUTPUT_DEVICES_FLAG, (deviceChanged: audio.DeviceChangeAction) => { 4243 console.info('device change type : ' + deviceChanged.type); 4244 console.info('device descriptor size : ' + deviceChanged.deviceDescriptors.length); 4245 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceRole); 4246 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceType); 4247}); 4248 4249``` 4250 4251### off('deviceChange')<sup>9+</sup> 4252 4253off(type: 'deviceChange', callback?: Callback<DeviceChangeAction\>): void 4254 4255Unsubscribes from audio device change events. This API uses an asynchronous callback to return the result. 4256 4257**System capability**: SystemCapability.Multimedia.Audio.Device 4258 4259**Parameters** 4260 4261| Name | Type | Mandatory | Description | 4262| -------- | --------------------------------------------------- | --------- | ----------------------------------------------------- | 4263| type | string | Yes | Event type. The value is fixed at **'deviceChange'**. | 4264| callback | Callback<[DeviceChangeAction](#devicechangeaction)> | No | Callback used to return the device change details. | 4265 4266**Error codes** 4267 4268For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4269 4270| ID | Error Message | 4271| ------- | ------------------------------------------------------------ | 4272| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4273| 6800101 | Parameter verification failed. | 4274 4275**Example** 4276 4277```ts 4278audioRoutingManager.off('deviceChange'); 4279 4280``` 4281 4282### setCommunicationDevice<sup>9+</sup> 4283 4284setCommunicationDevice(deviceType: CommunicationDeviceType, active: boolean, callback: AsyncCallback<void>): void 4285 4286Sets a communication device to the active state. This API uses an asynchronous callback to return the result. 4287 4288This API will be deprecated in a later version due to function design is changed. You are not advised to use it. 4289 4290You are advised to use the [AVCastPicker component](../../media/avsession/using-switch-call-devices.md) provided by AVSession to switch between call devices. 4291 4292**System capability**: SystemCapability.Multimedia.Audio.Communication 4293 4294**Parameters** 4295 4296| Name | Type | Mandatory | Description | 4297| ---------- | ---------------------------------------------------- | --------- | ------------------------------------------------------------ | 4298| deviceType | [CommunicationDeviceType](#communicationdevicetype9) | Yes | Communication device type. | 4299| 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. | 4300| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object. | 4301 4302**Example** 4303 4304```ts 4305import { BusinessError } from '@kit.BasicServicesKit'; 4306 4307audioRoutingManager.setCommunicationDevice(audio.CommunicationDeviceType.SPEAKER, true, (err: BusinessError) => { 4308 if (err) { 4309 console.error(`Failed to set the active status of the device. ${err}`); 4310 return; 4311 } 4312 console.info('Callback invoked to indicate that the device is set to the active status.'); 4313}); 4314 4315``` 4316 4317### getAvailableDevices<sup>12+</sup> 4318 4319getAvailableDevices(deviceUsage: DeviceUsage): AudioDeviceDescriptors 4320 4321Obtains the available audio devices. This API returns the result synchronously. 4322 4323**System capability**: SystemCapability.Multimedia.Audio.Device 4324 4325**Parameters** 4326 4327| Name | Type | Mandatory | Description | 4328| ----------- | ----------------------------- | --------- | ----------------------------- | 4329| deviceUsage | [DeviceUsage](#deviceusage12) | Yes | Usage scenario of the device. | 4330 4331**Return value** 4332 4333| Type | Description | 4334| ------------------------------------------------------------ | ------------ | 4335| [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | Device list. | 4336 4337**Error codes** 4338 4339For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4340 4341| ID | Error Message | 4342| ------- | ------------------------------------------------------------ | 4343| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4344| 6800101 | Parameter verification failed. | 4345 4346**Example** 4347 4348```ts 4349import { BusinessError } from '@kit.BasicServicesKit'; 4350 4351try { 4352 let data: audio.AudioDeviceDescriptors = audioRoutingManager.getAvailableDevices(audio.DeviceUsage.MEDIA_OUTPUT_DEVICES); 4353 console.info(`Indicate that the device list is obtained ${data}`); 4354} catch (err) { 4355 let error = err as BusinessError; 4356 console.error(`Failed to obtain the device list. ${error}`); 4357} 4358 4359``` 4360 4361### on('availableDeviceChange')<sup>12+</sup> 4362 4363on(type: 'availableDeviceChange', deviceUsage: DeviceUsage, callback: Callback<DeviceChangeAction\>): void 4364 4365Subscribes to available audio device change events. This API uses an asynchronous callback to return the result. Such an event is triggered when the connection status of available audio devices is changed. 4366 4367**System capability**: SystemCapability.Multimedia.Audio.Device 4368 4369**Parameters** 4370 4371| Name | Type | Mandatory | Description | 4372| :---------- | :----------------------------------------------------------- | :-------- | :----------------------------------------------------------- | 4373| type | string | Yes | Event type. The value is fixed at **'availableDeviceChange'**. | 4374| deviceUsage | [DeviceUsage](#deviceusage12) | Yes | Usage scenario of the device. | 4375| callback | Callback<[DeviceChangeAction](js-apis-audio.md#devicechangeaction)\> | Yes | Callback used to return the available device change details. | 4376 4377**Error codes** 4378 4379For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4380 4381| ID | Error Message | 4382| ------- | ------------------------------------------------------------ | 4383| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4384| 6800101 | Parameter verification failed. | 4385 4386**Example** 4387 4388```ts 4389audioRoutingManager.on('availableDeviceChange', audio.DeviceUsage.MEDIA_OUTPUT_DEVICES, (deviceChanged: audio.DeviceChangeAction) => { 4390 console.info('device change type : ' + deviceChanged.type); 4391 console.info('device descriptor size : ' + deviceChanged.deviceDescriptors.length); 4392 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceRole); 4393 console.info('device change descriptor : ' + deviceChanged.deviceDescriptors[0].deviceType); 4394}); 4395 4396``` 4397 4398### off('availableDeviceChange')<sup>12+</sup> 4399 4400off(type: 'availableDeviceChange', callback?: Callback<DeviceChangeAction\>): void 4401 4402Unsubscribes from available audio device change events. This API uses an asynchronous callback to return the result. 4403 4404**System capability**: SystemCapability.Multimedia.Audio.Device 4405 4406**Parameters** 4407 4408| Name | Type | Mandatory | Description | 4409| -------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | 4410| type | string | Yes | Event type. The value is fixed at **'availableDeviceChange'**. | 4411| callback | Callback<[DeviceChangeAction](js-apis-audio.md#devicechangeaction)> | No | Callback used to return the available device change details. | 4412 4413**Error codes** 4414 4415For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4416 4417| ID | Error Message | 4418| ------- | ------------------------------------------------------------ | 4419| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4420| 6800101 | Parameter verification failed. | 4421 4422**Example** 4423 4424```ts 4425audioRoutingManager.off('availableDeviceChange'); 4426 4427``` 4428 4429### setCommunicationDevice<sup>9+</sup> 4430 4431setCommunicationDevice(deviceType: CommunicationDeviceType, active: boolean): Promise<void> 4432 4433Sets a communication device to the active state. This API uses a promise to return the result. 4434 4435This API will be deprecated in a later version due to function design is changed. You are not advised to use it. 4436 4437You are advised to use the [AVCastPicker component](../../media/avsession/using-switch-call-devices.md) provided by AVSession to switch between call devices. 4438 4439**System capability**: SystemCapability.Multimedia.Audio.Communication 4440 4441**Parameters** 4442 4443| Name | Type | Mandatory | Description | 4444| ---------- | ---------------------------------------------------- | --------- | ------------------------------------------------------------ | 4445| deviceType | [CommunicationDeviceType](#communicationdevicetype9) | Yes | Communication device type. | 4446| 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. | 4447 4448**Return value** 4449 4450| Type | Description | 4451| ------------------- | ------------------------------ | 4452| Promise<void> | Promise that returns no value. | 4453 4454**Example** 4455 4456```ts 4457audioRoutingManager.setCommunicationDevice(audio.CommunicationDeviceType.SPEAKER, true).then(() => { 4458 console.info('Promise returned to indicate that the device is set to the active status.'); 4459}); 4460 4461``` 4462 4463### isCommunicationDeviceActive<sup>9+</sup> 4464 4465isCommunicationDeviceActive(deviceType: CommunicationDeviceType, callback: AsyncCallback<boolean>): void 4466 4467Checks whether a communication device is active. This API uses an asynchronous callback to return the result. 4468 4469**System capability**: SystemCapability.Multimedia.Audio.Communication 4470 4471**Parameters** 4472 4473| Name | Type | Mandatory | Description | 4474| ---------- | ---------------------------------------------------- | --------- | ------------------------------------------------------------ | 4475| deviceType | [CommunicationDeviceType](#communicationdevicetype9) | Yes | Communication device type. | 4476| 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. | 4477 4478**Example** 4479 4480```ts 4481import { BusinessError } from '@kit.BasicServicesKit'; 4482 4483audioRoutingManager.isCommunicationDeviceActive(audio.CommunicationDeviceType.SPEAKER, (err: BusinessError, value: boolean) => { 4484 if (err) { 4485 console.error(`Failed to obtain the active status of the device. ${err}`); 4486 return; 4487 } 4488 console.info('Callback invoked to indicate that the active status of the device is obtained.'); 4489}); 4490 4491``` 4492 4493### isCommunicationDeviceActive<sup>9+</sup> 4494 4495isCommunicationDeviceActive(deviceType: CommunicationDeviceType): Promise<boolean> 4496 4497Checks whether a communication device is active. This API uses a promise to return the result. 4498 4499**System capability**: SystemCapability.Multimedia.Audio.Communication 4500 4501**Parameters** 4502 4503| Name | Type | Mandatory | Description | 4504| ---------- | ---------------------------------------------------- | --------- | -------------------------- | 4505| deviceType | [CommunicationDeviceType](#communicationdevicetype9) | Yes | Communication device type. | 4506 4507**Return value** 4508 4509| Type | Description | 4510| ---------------------- | ------------------------------------------------------------ | 4511| 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. | 4512 4513**Example** 4514 4515```ts 4516audioRoutingManager.isCommunicationDeviceActive(audio.CommunicationDeviceType.SPEAKER).then((value: boolean) => { 4517 console.info(`Promise returned to indicate that the active status of the device is obtained ${value}.`); 4518}); 4519 4520``` 4521 4522### isCommunicationDeviceActiveSync<sup>10+</sup> 4523 4524isCommunicationDeviceActiveSync(deviceType: CommunicationDeviceType): boolean 4525 4526Checks whether a communication device is active. This API returns the result synchronously. 4527 4528**System capability**: SystemCapability.Multimedia.Audio.Communication 4529 4530**Parameters** 4531 4532| Name | Type | Mandatory | Description | 4533| ---------- | ---------------------------------------------------- | --------- | -------------------------- | 4534| deviceType | [CommunicationDeviceType](#communicationdevicetype9) | Yes | Communication device type. | 4535 4536**Return value** 4537 4538| Type | Description | 4539| ------- | ------------------------------------------------------------ | 4540| boolean | **true**: The device is active.<br>**false**: The device is inactive. | 4541 4542**Error codes** 4543 4544For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4545 4546| ID | Error Message | 4547| ------- | ------------------------------------------------------------ | 4548| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4549| 6800101 | Parameter verification failed. | 4550 4551**Example** 4552 4553```ts 4554import { BusinessError } from '@kit.BasicServicesKit'; 4555 4556try { 4557 let value: boolean = audioRoutingManager.isCommunicationDeviceActiveSync(audio.CommunicationDeviceType.SPEAKER); 4558 console.info(`Indicate that the active status of the device is obtained ${value}.`); 4559} catch (err) { 4560 let error = err as BusinessError; 4561 console.error(`Failed to obtain the active status of the device ${error}.`); 4562} 4563 4564``` 4565 4566### getPreferOutputDeviceForRendererInfo<sup>10+</sup> 4567 4568getPreferOutputDeviceForRendererInfo(rendererInfo: AudioRendererInfo, callback: AsyncCallback<AudioDeviceDescriptors>): void 4569 4570Obtains the output device with the highest priority based on the audio renderer information. This API uses an asynchronous callback to return the result. 4571 4572**System capability**: SystemCapability.Multimedia.Audio.Device 4573 4574**Parameters** 4575 4576| Name | Type | Mandatory | Description | 4577| ------------ | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | 4578| rendererInfo | [AudioRendererInfo](#audiorendererinfo8) | Yes | Audio renderer information. | 4579| 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. | 4580 4581**Error codes** 4582 4583For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4584 4585| ID | Error Message | 4586| ------- | ------------------------------------------------------------ | 4587| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4588| 6800101 | Parameter verification failed. Return by callback. | 4589| 6800301 | System error. Return by callback. | 4590 4591**Example** 4592 4593```ts 4594import { audio } from '@kit.AudioKit'; 4595import { BusinessError } from '@kit.BasicServicesKit'; 4596 4597let rendererInfo: audio.AudioRendererInfo = { 4598 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 4599 rendererFlags : 0 4600} 4601 4602async function getPreferOutputDevice() { 4603 audioRoutingManager.getPreferOutputDeviceForRendererInfo(rendererInfo, (err: BusinessError, desc: audio.AudioDeviceDescriptors) => { 4604 if (err) { 4605 console.error(`Result ERROR: ${err}`); 4606 } else { 4607 console.info(`device descriptor: ${desc}`); 4608 } 4609 }); 4610} 4611 4612``` 4613 4614### getPreferOutputDeviceForRendererInfo<sup>10+</sup> 4615 4616getPreferOutputDeviceForRendererInfo(rendererInfo: AudioRendererInfo): Promise<AudioDeviceDescriptors> 4617 4618Obtains the output device with the highest priority based on the audio renderer information. This API uses a promise to return the result. 4619 4620**System capability**: SystemCapability.Multimedia.Audio.Device 4621 4622**Parameters** 4623 4624| Name | Type | Mandatory | Description | 4625| ------------ | ---------------------------------------- | --------- | --------------------------- | 4626| rendererInfo | [AudioRendererInfo](#audiorendererinfo8) | Yes | Audio renderer information. | 4627 4628**Return value** 4629 4630| Type | Description | 4631| ------------------------------------------------------------ | ------------------------------------------------------------ | 4632| Promise<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Promise used to return the information about the output device with the highest priority. | 4633 4634**Error codes** 4635 4636For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4637 4638| ID | Error Message | 4639| ------- | ------------------------------------------------------------ | 4640| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4641| 6800101 | Parameter verification failed. Return by promise. | 4642| 6800301 | System error. Return by promise. | 4643 4644**Example** 4645 4646```ts 4647import { audio } from '@kit.AudioKit'; 4648import { BusinessError } from '@kit.BasicServicesKit'; 4649 4650let rendererInfo: audio.AudioRendererInfo = { 4651 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 4652 rendererFlags : 0 4653} 4654 4655async function getPreferOutputDevice() { 4656 audioRoutingManager.getPreferOutputDeviceForRendererInfo(rendererInfo).then((desc: audio.AudioDeviceDescriptors) => { 4657 console.info(`device descriptor: ${desc}`); 4658 }).catch((err: BusinessError) => { 4659 console.error(`Result ERROR: ${err}`); 4660 }) 4661} 4662 4663``` 4664 4665### getPreferredOutputDeviceForRendererInfoSync<sup>10+</sup> 4666 4667getPreferredOutputDeviceForRendererInfoSync(rendererInfo: AudioRendererInfo): AudioDeviceDescriptors 4668 4669Obtains the output device with the highest priority based on the audio renderer information. This API returns the result synchronously. 4670 4671**System capability**: SystemCapability.Multimedia.Audio.Device 4672 4673**Parameters** 4674 4675| Name | Type | Mandatory | Description | 4676| ------------ | ---------------------------------------- | --------- | --------------------------- | 4677| rendererInfo | [AudioRendererInfo](#audiorendererinfo8) | Yes | Audio renderer information. | 4678 4679**Return value** 4680 4681| Type | Description | 4682| ------------------------------------------------- | ------------------------------------------------------------ | 4683| [AudioDeviceDescriptors](#audiodevicedescriptors) | Information about the output device with the highest priority. | 4684 4685**Error codes** 4686 4687For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4688 4689| ID | Error Message | 4690| ------- | ------------------------------------------------------------ | 4691| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4692| 6800101 | Parameter verification failed. | 4693 4694**Example** 4695 4696```ts 4697import { audio } from '@kit.AudioKit'; 4698import { BusinessError } from '@kit.BasicServicesKit'; 4699 4700let rendererInfo: audio.AudioRendererInfo = { 4701 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 4702 rendererFlags : 0 4703} 4704 4705try { 4706 let desc: audio.AudioDeviceDescriptors = audioRoutingManager.getPreferredOutputDeviceForRendererInfoSync(rendererInfo); 4707 console.info(`device descriptor: ${desc}`); 4708} catch (err) { 4709 let error = err as BusinessError; 4710 console.error(`Result ERROR: ${error}`); 4711} 4712 4713``` 4714 4715### on('preferOutputDeviceChangeForRendererInfo')<sup>10+</sup> 4716 4717on(type: 'preferOutputDeviceChangeForRendererInfo', rendererInfo: AudioRendererInfo, callback: Callback<AudioDeviceDescriptors\>): void 4718 4719Subscribes to change events of the output device with the highest priority. This API uses an asynchronous callback to return the result. Such an event is triggered when the output device with the highest priority is changed. 4720 4721**System capability**: SystemCapability.Multimedia.Audio.Device 4722 4723**Parameters** 4724 4725| Name | Type | Mandatory | Description | 4726| :----------- | :----------------------------------------------------------- | :-------- | :----------------------------------------------------------- | 4727| type | string | Yes | Event type. The value is fixed at **'preferOutputDeviceChangeForRendererInfo'**. | 4728| rendererInfo | [AudioRendererInfo](#audiorendererinfo8) | Yes | Audio renderer information. | 4729| callback | Callback<[AudioDeviceDescriptors](#audiodevicedescriptors)\> | Yes | Callback used to return the information about the output device with the highest priority. | 4730 4731**Error codes** 4732 4733For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4734 4735| ID | Error Message | 4736| ------- | ------------------------------------------------------------ | 4737| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4738| 6800101 | Parameter verification failed. | 4739 4740**Example** 4741 4742```ts 4743import { audio } from '@kit.AudioKit'; 4744 4745let rendererInfo: audio.AudioRendererInfo = { 4746 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 4747 rendererFlags : 0 4748} 4749 4750audioRoutingManager.on('preferOutputDeviceChangeForRendererInfo', rendererInfo, (desc: audio.AudioDeviceDescriptors) => { 4751 console.info(`device descriptor: ${desc}`); 4752}); 4753 4754``` 4755 4756### off('preferOutputDeviceChangeForRendererInfo')<sup>10+</sup> 4757 4758off(type: 'preferOutputDeviceChangeForRendererInfo', callback?: Callback<AudioDeviceDescriptors\>): void 4759 4760Unsubscribes from the change of the output device with the highest priority. This API uses an asynchronous callback to return the result. 4761 4762**System capability**: SystemCapability.Multimedia.Audio.Device 4763 4764**Parameters** 4765 4766| Name | Type | Mandatory | Description | 4767| -------- | ----------------------------------------------------------- | --------- | ------------------------------------------------------------ | 4768| type | string | Yes | Event type. The value is fixed at **'preferOutputDeviceChangeForRendererInfo'**. | 4769| callback | Callback<[AudioDeviceDescriptors](#audiodevicedescriptors)> | No | Callback used to return the information about the output device with the highest priority. | 4770 4771**Error codes** 4772 4773For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4774 4775| ID | Error Message | 4776| ------- | ------------------------------------------------------------ | 4777| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4778| 6800101 | Parameter verification failed. | 4779 4780**Example** 4781 4782```ts 4783audioRoutingManager.off('preferOutputDeviceChangeForRendererInfo'); 4784 4785``` 4786 4787### getPreferredInputDeviceForCapturerInfo<sup>10+</sup> 4788 4789getPreferredInputDeviceForCapturerInfo(capturerInfo: AudioCapturerInfo, callback: AsyncCallback<AudioDeviceDescriptors>): void 4790 4791Obtains the input device with the highest priority based on the audio capturer information. This API uses an asynchronous callback to return the result. 4792 4793**System capability**: SystemCapability.Multimedia.Audio.Device 4794 4795**Parameters** 4796 4797| Name | Type | Mandatory | Description | 4798| ------------ | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | 4799| capturerInfo | [AudioCapturerInfo](#audiocapturerinfo8) | Yes | Audio capturer information. | 4800| 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. | 4801 4802**Error codes** 4803 4804For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4805 4806| ID | Error Message | 4807| ------- | ------------------------------------------------------------ | 4808| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4809| 6800101 | Parameter verification failed. Return by callback. | 4810| 6800301 | System error. Return by callback. | 4811 4812**Example** 4813 4814```ts 4815import { audio } from '@kit.AudioKit'; 4816import { BusinessError } from '@kit.BasicServicesKit'; 4817 4818let capturerInfo: audio.AudioCapturerInfo = { 4819 source: audio.SourceType.SOURCE_TYPE_MIC, 4820 capturerFlags: 0 4821} 4822 4823audioRoutingManager.getPreferredInputDeviceForCapturerInfo(capturerInfo, (err: BusinessError, desc: audio.AudioDeviceDescriptors) => { 4824 if (err) { 4825 console.error(`Result ERROR: ${err}`); 4826 } else { 4827 console.info(`device descriptor: ${desc}`); 4828 } 4829}); 4830 4831``` 4832 4833### getPreferredInputDeviceForCapturerInfo<sup>10+</sup> 4834 4835getPreferredInputDeviceForCapturerInfo(capturerInfo: AudioCapturerInfo): Promise<AudioDeviceDescriptors> 4836 4837Obtains the input device with the highest priority based on the audio capturer information. This API uses a promise to return the result. 4838 4839**System capability**: SystemCapability.Multimedia.Audio.Device 4840 4841**Parameters** 4842 4843| Name | Type | Mandatory | Description | 4844| ------------ | ---------------------------------------- | --------- | --------------------------- | 4845| capturerInfo | [AudioCapturerInfo](#audiocapturerinfo8) | Yes | Audio capturer information. | 4846 4847**Return value** 4848 4849| Type | Description | 4850| ------------------------------------------------------------ | ------------------------------------------------------------ | 4851| Promise<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Promise used to return the information about the input device with the highest priority. | 4852 4853**Error codes** 4854 4855For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4856 4857| ID | Error Message | 4858| ------- | ------------------------------------------------------------ | 4859| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4860| 6800101 | Parameter verification failed. Return by promise. | 4861| 6800301 | System error. Return by promise. | 4862 4863**Example** 4864 4865```ts 4866import { audio } from '@kit.AudioKit'; 4867import { BusinessError } from '@kit.BasicServicesKit'; 4868 4869let capturerInfo: audio.AudioCapturerInfo = { 4870 source: audio.SourceType.SOURCE_TYPE_MIC, 4871 capturerFlags: 0 4872} 4873 4874audioRoutingManager.getPreferredInputDeviceForCapturerInfo(capturerInfo).then((desc: audio.AudioDeviceDescriptors) => { 4875 console.info(`device descriptor: ${desc}`); 4876}).catch((err: BusinessError) => { 4877 console.error(`Result ERROR: ${err}`); 4878}); 4879 4880``` 4881 4882### getPreferredInputDeviceForCapturerInfoSync<sup>10+</sup> 4883 4884getPreferredInputDeviceForCapturerInfoSync(capturerInfo: AudioCapturerInfo): AudioDeviceDescriptors 4885 4886Obtains the input device with the highest priority based on the audio capturer information. This API returns the result synchronously. 4887 4888**System capability**: SystemCapability.Multimedia.Audio.Device 4889 4890**Parameters** 4891 4892| Name | Type | Mandatory | Description | 4893| ------------ | ---------------------------------------- | --------- | --------------------------- | 4894| capturerInfo | [AudioCapturerInfo](#audiocapturerinfo8) | Yes | Audio capturer information. | 4895 4896**Return value** 4897 4898| Type | Description | 4899| ------------------------------------------------- | ------------------------------------------------------------ | 4900| [AudioDeviceDescriptors](#audiodevicedescriptors) | Information about the input device with the highest priority. | 4901 4902**Error codes** 4903 4904For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4905 4906| ID | Error Message | 4907| ------- | ------------------------------------------------------------ | 4908| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4909| 6800101 | Parameter verification failed. | 4910 4911**Example** 4912 4913```ts 4914import { audio } from '@kit.AudioKit'; 4915import { BusinessError } from '@kit.BasicServicesKit'; 4916 4917let capturerInfo: audio.AudioCapturerInfo = { 4918 source: audio.SourceType.SOURCE_TYPE_MIC, 4919 capturerFlags: 0 4920} 4921 4922try { 4923 let desc: audio.AudioDeviceDescriptors = audioRoutingManager.getPreferredInputDeviceForCapturerInfoSync(capturerInfo); 4924 console.info(`device descriptor: ${desc}`); 4925} catch (err) { 4926 let error = err as BusinessError; 4927 console.error(`Result ERROR: ${error}`); 4928} 4929 4930``` 4931 4932### on('preferredInputDeviceChangeForCapturerInfo')<sup>10+</sup> 4933 4934on(type: 'preferredInputDeviceChangeForCapturerInfo', capturerInfo: AudioCapturerInfo, callback: Callback<AudioDeviceDescriptors\>): void 4935 4936Subscribes to change events of the input device with the highest priority. This API uses an asynchronous callback to return the result. Such an event is triggered when an input device with the highest priority is changed. 4937 4938**System capability**: SystemCapability.Multimedia.Audio.Device 4939 4940**Parameters** 4941 4942| Name | Type | Mandatory | Description | 4943| :----------- | :----------------------------------------------------------- | :-------- | :----------------------------------------------------------- | 4944| type | string | Yes | Event type. The value is fixed at **'preferredInputDeviceChangeForCapturerInfo'**. | 4945| capturerInfo | [AudioCapturerInfo](#audiocapturerinfo8) | Yes | Audio capturer information. | 4946| callback | Callback<[AudioDeviceDescriptors](#audiodevicedescriptors)\> | Yes | Callback used to return the information about the input device with the highest priority. | 4947 4948**Error codes** 4949 4950For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4951 4952| ID | Error Message | 4953| ------- | ------------------------------------------------------------ | 4954| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4955| 6800101 | Parameter verification failed. | 4956 4957**Example** 4958 4959```ts 4960import { audio } from '@kit.AudioKit'; 4961 4962let capturerInfo: audio.AudioCapturerInfo = { 4963 source: audio.SourceType.SOURCE_TYPE_MIC, 4964 capturerFlags: 0 4965} 4966 4967audioRoutingManager.on('preferredInputDeviceChangeForCapturerInfo', capturerInfo, (desc: audio.AudioDeviceDescriptors) => { 4968 console.info(`device descriptor: ${desc}`); 4969}); 4970 4971``` 4972 4973### off('preferredInputDeviceChangeForCapturerInfo')<sup>10+</sup> 4974 4975off(type: 'preferredInputDeviceChangeForCapturerInfo', callback?: Callback<AudioDeviceDescriptors\>): void 4976 4977Unsubscribes from the change of the input device with the highest priority. This API uses an asynchronous callback to return the result. 4978 4979**System capability**: SystemCapability.Multimedia.Audio.Device 4980 4981**Parameters** 4982 4983| Name | Type | Mandatory | Description | 4984| -------- | ----------------------------------------------------------- | --------- | ------------------------------------------------------------ | 4985| type | string | Yes | Event type. The value is fixed at **'preferredInputDeviceChangeForCapturerInfo'**. | 4986| callback | Callback<[AudioDeviceDescriptors](#audiodevicedescriptors)> | No | Callback used to return the information about the input device with the highest priority. | 4987 4988**Error codes** 4989 4990For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 4991 4992| ID | Error Message | 4993| ------- | ------------------------------------------------------------ | 4994| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 4995| 6800101 | Parameter verification failed. | 4996 4997**Example** 4998 4999```ts 5000audioRoutingManager.off('preferredInputDeviceChangeForCapturerInfo'); 5001 5002``` 5003 5004## AudioSessionManager<sup>12+</sup> 5005 5006Manages audio sessions. Before calling an API in **AudioSessionManager**, you must use [getSessionManager](#getsessionmanager12) to obtain an **AudioSessionManager** instance. 5007 5008### activateAudioSession<sup>12+</sup> 5009 5010activateAudioSession(strategy: AudioSessionStrategy): Promise\<void> 5011 5012Activates an audio session. This API uses a promise to return the result. 5013 5014**System capability**: SystemCapability.Multimedia.Audio.Core 5015 5016**Parameters** 5017 5018| Name | Type | Mandatory | Description | 5019| -------- | ----------------------------------------------- | --------- | ----------------------- | 5020| strategy | [AudioSessionStrategy](#audiosessionstrategy12) | Yes | Audio session strategy. | 5021 5022**Return value** 5023 5024| Type | Description | 5025| -------------- | ------------------------------ | 5026| Promise\<void> | Promise that returns no value. | 5027 5028**Error codes** 5029 5030For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5031 5032| ID | Error Message | 5033| ------- | ------------------------------------------------------------ | 5034| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5035| 6800101 | Parameter verification failed. | 5036| 6800301 | System error. Returned by promise. | 5037 5038**Example** 5039 5040```ts 5041import { BusinessError } from '@kit.BasicServicesKit'; 5042 5043let strategy: audio.AudioSessionStrategy = { 5044 concurrencyMode: audio.AudioConcurrencyMode.CONCURRENCY_MIX_WITH_OTHERS 5045} 5046 5047audioSessionManager.activateAudioSession(strategy).then(() => { 5048 console.info('activateAudioSession SUCCESS'); 5049}).catch((err: BusinessError) => { 5050 console.error(`ERROR: ${err}`); 5051}); 5052 5053``` 5054 5055### deactivateAudioSession<sup>12+</sup> 5056 5057deactivateAudioSession(): Promise\<void> 5058 5059Deactivates this audio session. This API uses a promise to return the result. 5060 5061**System capability**: SystemCapability.Multimedia.Audio.Core 5062 5063**Return value** 5064 5065| Type | Description | 5066| -------------- | ------------------------------ | 5067| Promise\<void> | Promise that returns no value. | 5068 5069**Error codes** 5070 5071For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5072 5073| ID | Error Message | 5074| ------- | ---------------------------------- | 5075| 6800301 | System error. Returned by promise. | 5076 5077**Example** 5078 5079```ts 5080import { BusinessError } from '@kit.BasicServicesKit'; 5081 5082audioSessionManager.deactivateAudioSession().then(() => { 5083 console.info('deactivateAudioSession SUCCESS'); 5084}).catch((err: BusinessError) => { 5085 console.error(`ERROR: ${err}`); 5086}); 5087 5088``` 5089 5090### isAudioSessionActivated<sup>12+</sup> 5091 5092isAudioSessionActivated(): boolean 5093 5094Checks whether this audio session is activated. 5095 5096**System capability**: SystemCapability.Multimedia.Audio.Core 5097 5098**Return value** 5099 5100| Type | Description | 5101| ------- | ------------------------------------------------------------ | 5102| boolean | Returns **true** if the audio session is activated; returns **false** otherwise. | 5103 5104**Example** 5105 5106```ts 5107let isActivated = audioSessionManager.isAudioSessionActivated(); 5108 5109``` 5110 5111### on('audioSessionDeactivated')<sup>12+</sup> 5112 5113on(type: 'audioSessionDeactivated', callback: Callback\<AudioSessionDeactivatedEvent>): void 5114 5115Subscribes to audio session deactivation events. This API uses an asynchronous callback to return the result. Such an event is triggered when an audio session is deactivated. 5116 5117**System capability**: SystemCapability.Multimedia.Audio.Core 5118 5119**Parameters** 5120 5121| Name | Type | Mandatory | Description | 5122| -------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | 5123| type | string | Yes | Event type. The value is fixed at **'audioSessionDeactivated'**. | 5124| callback | Callback<[AudioSessionDeactivatedEvent](#audiosessiondeactivatedevent12)> | Yes | Callback used to return the reason why the audio session is deactivated. | 5125 5126**Error codes** 5127 5128For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5129 5130| ID | Error Message | 5131| ------- | ------------------------------------------------------------ | 5132| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5133| 6800101 | Parameter verification failed. | 5134 5135**Example** 5136 5137```ts 5138audioSessionManager.on('audioSessionDeactivated', (audioSessionDeactivatedEvent: audio.AudioSessionDeactivatedEvent) => { 5139 console.info(`reason of audioSessionDeactivated: ${audioSessionDeactivatedEvent.reason} `); 5140}); 5141 5142``` 5143 5144### off('audioSessionDeactivated')<sup>12+</sup> 5145 5146off(type: 'audioSessionDeactivated', callback?: Callback\<AudioSessionDeactivatedEvent>): void 5147 5148Unsubscribes from audio session deactivation events. This API uses an asynchronous callback to return the result. 5149 5150**System capability**: SystemCapability.Multimedia.Audio.Core 5151 5152**Parameters** 5153 5154| Name | Type | Mandatory | Description | 5155| -------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | 5156| type | string | Yes | Event type. The value is fixed at **'audioSessionDeactivated'**. | 5157| callback | Callback<[AudioSessionDeactivatedEvent](#audiosessiondeactivatedevent12)> | No | Callback used to return the reason why the audio session is deactivated. | 5158 5159**Error codes** 5160 5161For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5162 5163| ID | Error Message | 5164| ------- | ------------------------------------------------------------ | 5165| 401 | Parameter error. Possible causes: 1.Mandatory parameters missing; 2.Incorrect parameter types. | 5166| 6800101 | Parameter verification failed. | 5167 5168**Example** 5169 5170```ts 5171audioSessionManager.off('audioSessionDeactivated'); 5172 5173``` 5174 5175## AudioRendererChangeInfoArray<sup>9+</sup> 5176 5177Defines an **AudioRenderChangeInfo** array, which is read-only. 5178 5179**System capability**: SystemCapability.Multimedia.Audio.Renderer 5180 5181## AudioRendererChangeInfo<sup>9+</sup> 5182 5183Describes the audio renderer change event. 5184 5185**System capability**: SystemCapability.Multimedia.Audio.Renderer 5186 5187| Name | Type | Readable | Writable | Description | 5188| ----------------- | ------------------------------------------------- | -------- | -------- | ----------------------------- | 5189| streamId | number | Yes | No | Unique ID of an audio stream. | 5190| rendererInfo | [AudioRendererInfo](#audiorendererinfo8) | Yes | No | Audio renderer information. | 5191| deviceDescriptors | [AudioDeviceDescriptors](#audiodevicedescriptors) | Yes | No | Audio device description. | 5192 5193**Example** 5194 5195```ts 5196import { audio } from '@kit.AudioKit'; 5197 5198const audioManager = audio.getAudioManager(); 5199let audioStreamManager = audioManager.getStreamManager(); 5200 5201audioStreamManager.on('audioRendererChange', (AudioRendererChangeInfoArray) => { 5202 for (let i = 0; i < AudioRendererChangeInfoArray.length; i++) { 5203 console.info(`## RendererChange on is called for ${i} ##`); 5204 console.info(`StreamId for ${i} is: ${AudioRendererChangeInfoArray[i].streamId}`); 5205 console.info(`Content for ${i} is: ${AudioRendererChangeInfoArray[i].rendererInfo.content}`); 5206 console.info(`Stream for ${i} is: ${AudioRendererChangeInfoArray[i].rendererInfo.usage}`); 5207 console.info(`Flag ${i} is: ${AudioRendererChangeInfoArray[i].rendererInfo.rendererFlags}`); 5208 let devDescriptor = AudioRendererChangeInfoArray[i].deviceDescriptors; 5209 for (let j = 0; j < AudioRendererChangeInfoArray[i].deviceDescriptors.length; j++) { 5210 console.info(`Id: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].id}`); 5211 console.info(`Type: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].deviceType}`); 5212 console.info(`Role: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].deviceRole}`); 5213 console.info(`Name: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].name}`); 5214 console.info(`Addr: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].address}`); 5215 console.info(`SR: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].sampleRates[0]}`); 5216 console.info(`C ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].channelCounts[0]}`); 5217 console.info(`CM: ${i} : ${AudioRendererChangeInfoArray[i].deviceDescriptors[j].channelMasks[0]}`); 5218 } 5219 } 5220}); 5221 5222``` 5223 5224 5225## AudioCapturerChangeInfoArray<sup>9+</sup> 5226 5227Defines an **AudioCapturerChangeInfo** array, which is read-only. 5228 5229**System capability**: SystemCapability.Multimedia.Audio.Capturer 5230 5231## AudioCapturerChangeInfo<sup>9+</sup> 5232 5233Describes the audio capturer change event. 5234 5235**System capability**: SystemCapability.Multimedia.Audio.Capturer 5236 5237| Name | Type | Readable | Writable | Description | 5238| ------------------- | ------------------------------------------------- | -------- | -------- | ------------------------------------------------------------ | 5239| streamId | number | Yes | No | Unique ID of an audio stream. | 5240| capturerInfo | [AudioCapturerInfo](#audiocapturerinfo8) | Yes | No | Audio capturer information. | 5241| deviceDescriptors | [AudioDeviceDescriptors](#audiodevicedescriptors) | Yes | No | Audio device description. | 5242| 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. | 5243 5244**Example** 5245 5246```ts 5247import { audio } from '@kit.AudioKit'; 5248 5249const audioManager = audio.getAudioManager(); 5250let audioStreamManager = audioManager.getStreamManager(); 5251 5252audioStreamManager.on('audioCapturerChange', (AudioCapturerChangeInfoArray) => { 5253 for (let i = 0; i < AudioCapturerChangeInfoArray.length; i++) { 5254 console.info(`## CapChange on is called for element ${i} ##`); 5255 console.info(`StrId for ${i} is: ${AudioCapturerChangeInfoArray[i].streamId}`); 5256 console.info(`Src for ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.source}`); 5257 console.info(`Flag ${i} is: ${AudioCapturerChangeInfoArray[i].capturerInfo.capturerFlags}`); 5258 let devDescriptor = AudioCapturerChangeInfoArray[i].deviceDescriptors; 5259 for (let j = 0; j < AudioCapturerChangeInfoArray[i].deviceDescriptors.length; j++) { 5260 console.info(`Id: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].id}`); 5261 console.info(`Type: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceType}`); 5262 console.info(`Role: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].deviceRole}`); 5263 console.info(`Name: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].name}`); 5264 console.info(`Addr: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].address}`); 5265 console.info(`SR: ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].sampleRates[0]}`); 5266 console.info(`C ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelCounts[0]}`); 5267 console.info(`CM ${i} : ${AudioCapturerChangeInfoArray[i].deviceDescriptors[j].channelMasks[0]}`); 5268 } 5269 } 5270}); 5271 5272``` 5273 5274## AudioEffectInfoArray<sup>10+</sup> 5275 5276Defines 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. 5277 5278## AudioDeviceDescriptors 5279 5280Defines an [AudioDeviceDescriptor](#audiodevicedescriptor) array, which is read-only. 5281 5282**Atomic service API**: This API can be used in atomic services since API version 12. 5283 5284## AudioDeviceDescriptor 5285 5286Describes an audio device. 5287 5288**Atomic service API**: This API can be used in atomic services since API version 12. 5289 5290| Name | Type | Readable | Writable | Description | 5291| --------------------------- | ----------------------------------------------------- | -------- | -------- | ------------------------------------------------------------ | 5292| deviceRole | [DeviceRole](#devicerole) | Yes | No | Device role.<br> **System capability**: SystemCapability.Multimedia.Audio.Device | 5293| deviceType | [DeviceType](#devicetype) | Yes | No | Device type.<br> **System capability**: SystemCapability.Multimedia.Audio.Device | 5294| id<sup>9+</sup> | number | Yes | No | Device ID, which is unique.<br> **System capability**: SystemCapability.Multimedia.Audio.Device | 5295| 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 | 5296| 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 | 5297| sampleRates<sup>9+</sup> | Array<number> | Yes | No | Supported sampling rates.<br> **System capability**: SystemCapability.Multimedia.Audio.Device | 5298| channelCounts<sup>9+</sup> | Array<number> | Yes | No | Number of channels supported.<br> **System capability**: SystemCapability.Multimedia.Audio.Device | 5299| channelMasks<sup>9+</sup> | Array<number> | Yes | No | Supported channel masks.<br> **System capability**: SystemCapability.Multimedia.Audio.Device | 5300| displayName<sup>10+</sup> | string | Yes | No | Display name of the device.<br> **System capability**: SystemCapability.Multimedia.Audio.Device | 5301| encodingTypes<sup>11+</sup> | Array<[AudioEncodingType](#audioencodingtype8)> | Yes | No | Supported encoding types.<br> **System capability**: SystemCapability.Multimedia.Audio.Core | 5302 5303**Example** 5304 5305```ts 5306import { audio } from '@kit.AudioKit'; 5307 5308function displayDeviceProp(value: audio.AudioDeviceDescriptor) { 5309 deviceRoleValue = value.deviceRole; 5310 deviceTypeValue = value.deviceType; 5311} 5312 5313let deviceRoleValue: audio.DeviceRole | undefined = undefined;; 5314let deviceTypeValue: audio.DeviceType | undefined = undefined;; 5315audio.getAudioManager().getDevices(1).then((value: audio.AudioDeviceDescriptors) => { 5316 console.info('AudioFrameworkTest: Promise: getDevices OUTPUT_DEVICES_FLAG'); 5317 value.forEach(displayDeviceProp); 5318 if (deviceTypeValue != undefined && deviceRoleValue != undefined){ 5319 console.info('AudioFrameworkTest: Promise: getDevices : OUTPUT_DEVICES_FLAG : PASS'); 5320 } else { 5321 console.error('AudioFrameworkTest: Promise: getDevices : OUTPUT_DEVICES_FLAG : FAIL'); 5322 } 5323}); 5324 5325``` 5326 5327## AudioDataCallbackResult<sup>12+</sup> 5328 5329Enumerates the audio data callback results. 5330 5331**System capability**: SystemCapability.Multimedia.Audio.Core 5332 5333| Name | Value | Description | 5334| ------- | ----- | ----------------------------- | 5335| INVALID | -1 | The callback data is invalid. | 5336| VALID | 0 | The callback data is valid. | 5337 5338## AudioRendererWriteDataCallback<sup>12+</sup> 5339 5340type AudioRendererWriteDataCallback = (data: ArrayBuffer) => AudioDataCallbackResult | void 5341 5342Defines the callback function used to write data to the audio renderer. 5343 5344**System capability**: SystemCapability.Multimedia.Audio.Renderer 5345 5346**Parameters** 5347 5348| Name | Type | Mandatory | Description | 5349| :--- | :---------- | :-------- | :-------------------------------- | 5350| data | ArrayBuffer | Yes | Data to be written to the buffer. | 5351 5352**Return value** 5353 5354| Type | Description | 5355| ------------------------------------------------------------ | ------------------------------------------------------------ | 5356| [AudioDataCallbackResult](#audiodatacallbackresult12) \| void | If **void** or **AudioDataCallbackResult.VALID** is returned, the data is valid and will be played. If **AudioDataCallbackResult.INVALID** is returned, the data is invalid and will not be played. | 5357 5358## AudioRenderer<sup>8+</sup> 5359 5360Provides APIs for audio rendering. Before calling any API in **AudioRenderer**, you must use [createAudioRenderer](#audiocreateaudiorenderer8) to create an **AudioRenderer** instance. 5361 5362### Attributes 5363 5364**System capability**: SystemCapability.Multimedia.Audio.Renderer 5365 5366| Name | Type | Readable | Writable | Description | 5367| ------------------ | -------------------------- | -------- | -------- | --------------------- | 5368| state<sup>8+</sup> | [AudioState](#audiostate8) | Yes | No | Audio renderer state. | 5369 5370**Example** 5371 5372```ts 5373import { audio } from '@kit.AudioKit'; 5374 5375let state: audio.AudioState = audioRenderer.state; 5376 5377``` 5378 5379### getRendererInfo<sup>8+</sup> 5380 5381getRendererInfo(callback: AsyncCallback<AudioRendererInfo\>): void 5382 5383Obtains the renderer information of this **AudioRenderer** instance. This API uses an asynchronous callback to return the result. 5384 5385**System capability**: SystemCapability.Multimedia.Audio.Renderer 5386 5387**Parameters** 5388 5389| Name | Type | Mandatory | Description | 5390| :------- | :------------------------------------------------------- | :-------- | :----------------------------------------------------------- | 5391| 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. | 5392 5393**Example** 5394 5395```ts 5396import { BusinessError } from '@kit.BasicServicesKit'; 5397 5398audioRenderer.getRendererInfo((err: BusinessError, rendererInfo: audio.AudioRendererInfo) => { 5399 console.info('Renderer GetRendererInfo:'); 5400 console.info(`Renderer content: ${rendererInfo.content}`); 5401 console.info(`Renderer usage: ${rendererInfo.usage}`); 5402 console.info(`Renderer flags: ${rendererInfo.rendererFlags}`); 5403}); 5404 5405``` 5406 5407### getRendererInfo<sup>8+</sup> 5408 5409getRendererInfo(): Promise<AudioRendererInfo\> 5410 5411Obtains the renderer information of this **AudioRenderer** instance. This API uses a promise to return the result. 5412 5413**System capability**: SystemCapability.Multimedia.Audio.Renderer 5414 5415**Return value** 5416 5417| Type | Description | 5418| -------------------------------------------------- | ------------------------------------------------ | 5419| Promise<[AudioRendererInfo](#audiorendererinfo8)\> | Promise used to return the renderer information. | 5420 5421**Example** 5422 5423```ts 5424import { BusinessError } from '@kit.BasicServicesKit'; 5425 5426audioRenderer.getRendererInfo().then((rendererInfo: audio.AudioRendererInfo) => { 5427 console.info('Renderer GetRendererInfo:'); 5428 console.info(`Renderer content: ${rendererInfo.content}`); 5429 console.info(`Renderer usage: ${rendererInfo.usage}`); 5430 console.info(`Renderer flags: ${rendererInfo.rendererFlags}`) 5431}).catch((err: BusinessError) => { 5432 console.error(`AudioFrameworkRenderLog: RendererInfo :ERROR: ${err}`); 5433}); 5434 5435``` 5436 5437### getRendererInfoSync<sup>10+</sup> 5438 5439getRendererInfoSync(): AudioRendererInfo 5440 5441Obtains the renderer information of this **AudioRenderer** instance. This API returns the result synchronously. 5442 5443**System capability**: SystemCapability.Multimedia.Audio.Renderer 5444 5445**Return value** 5446 5447| Type | Description | 5448| ---------------------------------------- | --------------------------- | 5449| [AudioRendererInfo](#audiorendererinfo8) | Audio renderer information. | 5450 5451**Example** 5452 5453```ts 5454import { BusinessError } from '@kit.BasicServicesKit'; 5455 5456try { 5457 let rendererInfo: audio.AudioRendererInfo = audioRenderer.getRendererInfoSync(); 5458 console.info(`Renderer content: ${rendererInfo.content}`); 5459 console.info(`Renderer usage: ${rendererInfo.usage}`); 5460 console.info(`Renderer flags: ${rendererInfo.rendererFlags}`) 5461} catch (err) { 5462 let error = err as BusinessError; 5463 console.error(`AudioFrameworkRenderLog: RendererInfo :ERROR: ${error}`); 5464} 5465 5466``` 5467 5468### getStreamInfo<sup>8+</sup> 5469 5470getStreamInfo(callback: AsyncCallback<AudioStreamInfo\>): void 5471 5472Obtains the stream information of this **AudioRenderer** instance. This API uses an asynchronous callback to return the result. 5473 5474**System capability**: SystemCapability.Multimedia.Audio.Renderer 5475 5476**Parameters** 5477 5478| Name | Type | Mandatory | Description | 5479| :------- | :--------------------------------------------------- | :-------- | :----------------------------------------------------------- | 5480| 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. | 5481 5482**Example** 5483 5484```ts 5485import { BusinessError } from '@kit.BasicServicesKit'; 5486 5487audioRenderer.getStreamInfo((err: BusinessError, streamInfo: audio.AudioStreamInfo) => { 5488 console.info('Renderer GetStreamInfo:'); 5489 console.info(`Renderer sampling rate: ${streamInfo.samplingRate}`); 5490 console.info(`Renderer channel: ${streamInfo.channels}`); 5491 console.info(`Renderer format: ${streamInfo.sampleFormat}`); 5492 console.info(`Renderer encoding type: ${streamInfo.encodingType}`); 5493}); 5494 5495``` 5496 5497### getStreamInfo<sup>8+</sup> 5498 5499getStreamInfo(): Promise<AudioStreamInfo\> 5500 5501Obtains the stream information of this **AudioRenderer** instance. This API uses a promise to return the result. 5502 5503**System capability**: SystemCapability.Multimedia.Audio.Renderer 5504 5505**Return value** 5506 5507| Type | Description | 5508| :--------------------------------------------- | :--------------------------------------------- | 5509| Promise<[AudioStreamInfo](#audiostreaminfo8)\> | Promise used to return the stream information. | 5510 5511**Example** 5512 5513```ts 5514import { BusinessError } from '@kit.BasicServicesKit'; 5515 5516audioRenderer.getStreamInfo().then((streamInfo: audio.AudioStreamInfo) => { 5517 console.info('Renderer GetStreamInfo:'); 5518 console.info(`Renderer sampling rate: ${streamInfo.samplingRate}`); 5519 console.info(`Renderer channel: ${streamInfo.channels}`); 5520 console.info(`Renderer format: ${streamInfo.sampleFormat}`); 5521 console.info(`Renderer encoding type: ${streamInfo.encodingType}`); 5522}).catch((err: BusinessError) => { 5523 console.error(`ERROR: ${err}`); 5524}); 5525 5526``` 5527 5528### getStreamInfoSync<sup>10+</sup> 5529 5530getStreamInfoSync(): AudioStreamInfo 5531 5532Obtains the stream information of this **AudioRenderer** instance. This API returns the result synchronously. 5533 5534**System capability**: SystemCapability.Multimedia.Audio.Renderer 5535 5536**Return value** 5537 5538| Type | Description | 5539| :----------------------------------- | :------------------ | 5540| [AudioStreamInfo](#audiostreaminfo8) | Stream information. | 5541 5542**Example** 5543 5544```ts 5545import { BusinessError } from '@kit.BasicServicesKit'; 5546 5547try { 5548 let streamInfo: audio.AudioStreamInfo = audioRenderer.getStreamInfoSync(); 5549 console.info(`Renderer sampling rate: ${streamInfo.samplingRate}`); 5550 console.info(`Renderer channel: ${streamInfo.channels}`); 5551 console.info(`Renderer format: ${streamInfo.sampleFormat}`); 5552 console.info(`Renderer encoding type: ${streamInfo.encodingType}`); 5553} catch (err) { 5554 let error = err as BusinessError; 5555 console.error(`ERROR: ${error}`); 5556} 5557 5558``` 5559 5560### getAudioStreamId<sup>9+</sup> 5561 5562getAudioStreamId(callback: AsyncCallback<number\>): void 5563 5564Obtains the stream ID of this **AudioRenderer** instance. This API uses an asynchronous callback to return the result. 5565 5566**System capability**: SystemCapability.Multimedia.Audio.Renderer 5567 5568**Parameters** 5569 5570| Name | Type | Mandatory | Description | 5571| :------- | :--------------------- | :-------- | :----------------------------------------------------------- | 5572| 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. | 5573 5574**Example** 5575 5576```ts 5577import { BusinessError } from '@kit.BasicServicesKit'; 5578 5579audioRenderer.getAudioStreamId((err: BusinessError, streamId: number) => { 5580 console.info(`Renderer GetStreamId: ${streamId}`); 5581}); 5582 5583``` 5584 5585### getAudioStreamId<sup>9+</sup> 5586 5587getAudioStreamId(): Promise<number\> 5588 5589Obtains the stream ID of this **AudioRenderer** instance. This API uses a promise to return the result. 5590 5591**System capability**: SystemCapability.Multimedia.Audio.Renderer 5592 5593**Return value** 5594 5595| Type | Description | 5596| :--------------- | :------------------------------------ | 5597| Promise<number\> | Promise used to return the stream ID. | 5598 5599**Example** 5600 5601```ts 5602import { BusinessError } from '@kit.BasicServicesKit'; 5603 5604audioRenderer.getAudioStreamId().then((streamId: number) => { 5605 console.info(`Renderer getAudioStreamId: ${streamId}`); 5606}).catch((err: BusinessError) => { 5607 console.error(`ERROR: ${err}`); 5608}); 5609 5610``` 5611 5612### getAudioStreamIdSync<sup>10+</sup> 5613 5614getAudioStreamIdSync(): number 5615 5616Obtains the stream ID of this **AudioRenderer** instance. This API returns the result synchronously. 5617 5618**System capability**: SystemCapability.Multimedia.Audio.Renderer 5619 5620**Return value** 5621 5622| Type | Description | 5623| :----- | :---------- | 5624| number | Stream ID. | 5625 5626**Example** 5627 5628```ts 5629import { BusinessError } from '@kit.BasicServicesKit'; 5630 5631try { 5632 let streamId: number = audioRenderer.getAudioStreamIdSync(); 5633 console.info(`Renderer getAudioStreamIdSync: ${streamId}`); 5634} catch (err) { 5635 let error = err as BusinessError; 5636 console.error(`ERROR: ${error}`); 5637} 5638 5639``` 5640 5641### setAudioEffectMode<sup>10+</sup> 5642 5643setAudioEffectMode(mode: AudioEffectMode, callback: AsyncCallback\<void>): void 5644 5645Sets an audio effect mode. This API uses an asynchronous callback to return the result. 5646 5647**System capability**: SystemCapability.Multimedia.Audio.Renderer 5648 5649**Parameters** 5650 5651| Name | Type | Mandatory | Description | 5652| -------- | ------------------------------------- | --------- | ------------------------------------------------------------ | 5653| mode | [AudioEffectMode](#audioeffectmode10) | Yes | Audio effect mode to set. | 5654| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object. | 5655 5656**Error codes** 5657 5658For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5659 5660| ID | Error Message | 5661| ------- | ------------------------------------------------------------ | 5662| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5663| 6800101 | Parameter verification failed. Return by callback. | 5664 5665**Example** 5666 5667```ts 5668import { BusinessError } from '@kit.BasicServicesKit'; 5669 5670audioRenderer.setAudioEffectMode(audio.AudioEffectMode.EFFECT_DEFAULT, (err: BusinessError) => { 5671 if (err) { 5672 console.error('Failed to set params'); 5673 } else { 5674 console.info('Callback invoked to indicate a successful audio effect mode setting.'); 5675 } 5676}); 5677 5678``` 5679 5680### setAudioEffectMode<sup>10+</sup> 5681 5682setAudioEffectMode(mode: AudioEffectMode): Promise\<void> 5683 5684Sets an audio effect mode. This API uses a promise to return the result. 5685 5686**System capability**: SystemCapability.Multimedia.Audio.Renderer 5687 5688**Parameters** 5689 5690| Name | Type | Mandatory | Description | 5691| ---- | ------------------------------------- | --------- | ------------------------- | 5692| mode | [AudioEffectMode](#audioeffectmode10) | Yes | Audio effect mode to set. | 5693 5694**Return value** 5695 5696| Type | Description | 5697| -------------- | ------------------------------ | 5698| Promise\<void> | Promise that returns no value. | 5699 5700**Error codes** 5701 5702For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5703 5704| ID | Error Message | 5705| ------- | ------------------------------------------------------------ | 5706| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 5707| 6800101 | Parameter verification failed. Return by promise. | 5708 5709**Example** 5710 5711```ts 5712import { BusinessError } from '@kit.BasicServicesKit'; 5713 5714audioRenderer.setAudioEffectMode(audio.AudioEffectMode.EFFECT_DEFAULT).then(() => { 5715 console.info('setAudioEffectMode SUCCESS'); 5716}).catch((err: BusinessError) => { 5717 console.error(`ERROR: ${err}`); 5718}); 5719 5720``` 5721 5722### getAudioEffectMode<sup>10+</sup> 5723 5724getAudioEffectMode(callback: AsyncCallback\<AudioEffectMode>): void 5725 5726Obtains the audio effect mode in use. This API uses an asynchronous callback to return the result. 5727 5728**System capability**: SystemCapability.Multimedia.Audio.Renderer 5729 5730**Parameters** 5731 5732| Name | Type | Mandatory | Description | 5733| -------- | ---------------------------------------------------- | --------- | ------------------------------------------------------------ | 5734| 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. | 5735 5736**Example** 5737 5738```ts 5739import { BusinessError } from '@kit.BasicServicesKit'; 5740 5741audioRenderer.getAudioEffectMode((err: BusinessError, effectMode: audio.AudioEffectMode) => { 5742 if (err) { 5743 console.error('Failed to get params'); 5744 } else { 5745 console.info(`getAudioEffectMode: ${effectMode}`); 5746 } 5747}); 5748 5749``` 5750 5751### getAudioEffectMode<sup>10+</sup> 5752 5753getAudioEffectMode(): Promise\<AudioEffectMode> 5754 5755Obtains the audio effect mode in use. This API uses a promise to return the result. 5756 5757**System capability**: SystemCapability.Multimedia.Audio.Renderer 5758 5759**Return value** 5760 5761| Type | Description | 5762| ---------------------------------------------- | --------------------------------------------- | 5763| Promise<[AudioEffectMode](#audioeffectmode10)> | Promise used to return the audio effect mode. | 5764 5765**Example** 5766 5767```ts 5768import { BusinessError } from '@kit.BasicServicesKit'; 5769 5770audioRenderer.getAudioEffectMode().then((effectMode: audio.AudioEffectMode) => { 5771 console.info(`getAudioEffectMode: ${effectMode}`); 5772}).catch((err: BusinessError) => { 5773 console.error(`ERROR: ${err}`); 5774}); 5775 5776``` 5777 5778### start<sup>8+</sup> 5779 5780start(callback: AsyncCallback<void\>): void 5781 5782Starts the renderer. This API uses an asynchronous callback to return the result. 5783 5784**System capability**: SystemCapability.Multimedia.Audio.Renderer 5785 5786**Parameters** 5787 5788| Name | Type | Mandatory | Description | 5789| -------- | -------------------- | --------- | ------------------------------------------------------------ | 5790| 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. | 5791 5792**Example** 5793 5794```ts 5795import { BusinessError } from '@kit.BasicServicesKit'; 5796 5797audioRenderer.start((err: BusinessError) => { 5798 if (err) { 5799 console.error('Renderer start failed.'); 5800 } else { 5801 console.info('Renderer start success.'); 5802 } 5803}); 5804 5805``` 5806 5807### start<sup>8+</sup> 5808 5809start(): Promise<void\> 5810 5811Starts the renderer. This API uses a promise to return the result. 5812 5813**System capability**: SystemCapability.Multimedia.Audio.Renderer 5814 5815**Return value** 5816 5817| Type | Description | 5818| -------------- | ------------------------------------------------------------ | 5819| 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. | 5820 5821**Example** 5822 5823```ts 5824import { BusinessError } from '@kit.BasicServicesKit'; 5825 5826audioRenderer.start().then(() => { 5827 console.info('Renderer started'); 5828}).catch((err: BusinessError) => { 5829 console.error(`ERROR: ${err}`); 5830}); 5831 5832``` 5833 5834### pause<sup>8+</sup> 5835 5836pause(callback: AsyncCallback\<void>): void 5837 5838Pauses rendering. This API uses an asynchronous callback to return the result. 5839 5840**System capability**: SystemCapability.Multimedia.Audio.Renderer 5841 5842**Parameters** 5843 5844| Name | Type | Mandatory | Description | 5845| -------- | -------------------- | --------- | ------------------------------------------------------------ | 5846| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object. | 5847 5848**Example** 5849 5850```ts 5851import { BusinessError } from '@kit.BasicServicesKit'; 5852 5853audioRenderer.pause((err: BusinessError) => { 5854 if (err) { 5855 console.error('Renderer pause failed'); 5856 } else { 5857 console.info('Renderer paused.'); 5858 } 5859}); 5860 5861``` 5862 5863### pause<sup>8+</sup> 5864 5865pause(): Promise\<void> 5866 5867Pauses rendering. This API uses a promise to return the result. 5868 5869**System capability**: SystemCapability.Multimedia.Audio.Renderer 5870 5871**Return value** 5872 5873| Type | Description | 5874| -------------- | ------------------------------ | 5875| Promise\<void> | Promise that returns no value. | 5876 5877**Example** 5878 5879```ts 5880import { BusinessError } from '@kit.BasicServicesKit'; 5881 5882audioRenderer.pause().then(() => { 5883 console.info('Renderer paused'); 5884}).catch((err: BusinessError) => { 5885 console.error(`ERROR: ${err}`); 5886}); 5887 5888``` 5889 5890### drain<sup>8+</sup> 5891 5892drain(callback: AsyncCallback\<void>): void 5893 5894Drains the playback buffer. This API uses an asynchronous callback to return the result. 5895 5896**System capability**: SystemCapability.Multimedia.Audio.Renderer 5897 5898**Parameters** 5899 5900| Name | Type | Mandatory | Description | 5901| -------- | -------------------- | --------- | ------------------------------------------------------------ | 5902| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object. | 5903 5904**Example** 5905 5906```ts 5907import { BusinessError } from '@kit.BasicServicesKit'; 5908 5909audioRenderer.drain((err: BusinessError) => { 5910 if (err) { 5911 console.error('Renderer drain failed'); 5912 } else { 5913 console.info('Renderer drained.'); 5914 } 5915}); 5916 5917``` 5918 5919### drain<sup>8+</sup> 5920 5921drain(): Promise\<void> 5922 5923Drains the playback buffer. This API uses a promise to return the result. 5924 5925**System capability**: SystemCapability.Multimedia.Audio.Renderer 5926 5927**Return value** 5928 5929| Type | Description | 5930| -------------- | ------------------------------ | 5931| Promise\<void> | Promise that returns no value. | 5932 5933**Example** 5934 5935```ts 5936import { BusinessError } from '@kit.BasicServicesKit'; 5937 5938audioRenderer.drain().then(() => { 5939 console.info('Renderer drained successfully'); 5940}).catch((err: BusinessError) => { 5941 console.error(`ERROR: ${err}`); 5942}); 5943 5944``` 5945 5946### flush<sup>11+</sup> 5947 5948flush(): Promise\<void> 5949 5950Flushes 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. 5951 5952**System capability**: SystemCapability.Multimedia.Audio.Renderer 5953 5954**Return value** 5955 5956| Type | Description | 5957| -------------- | ------------------------------ | 5958| Promise\<void> | Promise that returns no value. | 5959 5960**Error codes** 5961 5962For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 5963 5964| ID | Error Message | 5965| ------- | --------------------------------------------------------- | 5966| 6800103 | Operation not permit at current state. Return by promise. | 5967 5968**Example** 5969 5970```ts 5971import { BusinessError } from '@kit.BasicServicesKit'; 5972 5973audioRenderer.flush().then(() => { 5974 console.info('Renderer flushed successfully'); 5975}).catch((err: BusinessError) => { 5976 console.error(`ERROR: ${err}`); 5977}); 5978 5979``` 5980 5981### stop<sup>8+</sup> 5982 5983stop(callback: AsyncCallback\<void>): void 5984 5985Stops rendering. This API uses an asynchronous callback to return the result. 5986 5987**System capability**: SystemCapability.Multimedia.Audio.Renderer 5988 5989**Parameters** 5990 5991| Name | Type | Mandatory | Description | 5992| -------- | -------------------- | --------- | ------------------------------------------------------------ | 5993| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object. | 5994 5995**Example** 5996 5997```ts 5998import { BusinessError } from '@kit.BasicServicesKit'; 5999 6000audioRenderer.stop((err: BusinessError) => { 6001 if (err) { 6002 console.error('Renderer stop failed'); 6003 } else { 6004 console.info('Renderer stopped.'); 6005 } 6006}); 6007 6008``` 6009 6010### stop<sup>8+</sup> 6011 6012stop(): Promise\<void> 6013 6014Stops rendering. This API uses a promise to return the result. 6015 6016**System capability**: SystemCapability.Multimedia.Audio.Renderer 6017 6018**Return value** 6019 6020| Type | Description | 6021| -------------- | ------------------------------ | 6022| Promise\<void> | Promise that returns no value. | 6023 6024**Example** 6025 6026```ts 6027import { BusinessError } from '@kit.BasicServicesKit'; 6028 6029audioRenderer.stop().then(() => { 6030 console.info('Renderer stopped successfully'); 6031}).catch((err: BusinessError) => { 6032 console.error(`ERROR: ${err}`); 6033}); 6034 6035``` 6036 6037### release<sup>8+</sup> 6038 6039release(callback: AsyncCallback\<void>): void 6040 6041Releases the renderer. This API uses an asynchronous callback to return the result. 6042 6043**System capability**: SystemCapability.Multimedia.Audio.Renderer 6044 6045**Parameters** 6046 6047| Name | Type | Mandatory | Description | 6048| -------- | -------------------- | --------- | ------------------------------------------------------------ | 6049| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object. | 6050 6051**Example** 6052 6053```ts 6054import { BusinessError } from '@kit.BasicServicesKit'; 6055 6056audioRenderer.release((err: BusinessError) => { 6057 if (err) { 6058 console.error('Renderer release failed'); 6059 } else { 6060 console.info('Renderer released.'); 6061 } 6062}); 6063 6064``` 6065 6066### release<sup>8+</sup> 6067 6068release(): Promise\<void> 6069 6070Releases the renderer. This API uses a promise to return the result. 6071 6072**System capability**: SystemCapability.Multimedia.Audio.Renderer 6073 6074**Return value** 6075 6076| Type | Description | 6077| -------------- | ------------------------------ | 6078| Promise\<void> | Promise that returns no value. | 6079 6080**Example** 6081 6082```ts 6083import { BusinessError } from '@kit.BasicServicesKit'; 6084 6085audioRenderer.release().then(() => { 6086 console.info('Renderer released successfully'); 6087}).catch((err: BusinessError) => { 6088 console.error(`ERROR: ${err}`); 6089}); 6090 6091``` 6092 6093### write<sup>8+(deprecated)</sup> 6094 6095write(buffer: ArrayBuffer, callback: AsyncCallback\<number>): void 6096 6097Writes the buffer. This API uses an asynchronous callback to return the result. 6098 6099> **NOTE** 6100> 6101> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [on('writeData')](#onwritedata11) in **AudioRenderer**. 6102 6103**System capability**: SystemCapability.Multimedia.Audio.Renderer 6104 6105**Parameters** 6106 6107| Name | Type | Mandatory | Description | 6108| -------- | ---------------------- | --------- | ------------------------------------------------------------ | 6109| buffer | ArrayBuffer | Yes | Data to be written to the buffer. | 6110| 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. | 6111 6112**Example** 6113 6114```ts 6115import { BusinessError } from '@kit.BasicServicesKit'; 6116import { fileIo } from '@kit.CoreFileKit'; 6117 6118let bufferSize: number; 6119class Options { 6120 offset?: number; 6121 length?: number; 6122} 6123audioRenderer.getBufferSize().then((data: number)=> { 6124 console.info(`AudioFrameworkRenderLog: getBufferSize: SUCCESS ${data}`); 6125 bufferSize = data; 6126 console.info(`Buffer size: ${bufferSize}`); 6127 let path = getContext().cacheDir; 6128 let filePath = path + '/StarWars10s-2C-48000-4SW.wav'; 6129 let file: fileIo.File = fileIo.openSync(filePath, fileIo.OpenMode.READ_ONLY); 6130 fileIo.stat(filePath).then(async (stat: fileIo.Stat) => { 6131 let buf = new ArrayBuffer(bufferSize); 6132 let len = stat.size % bufferSize == 0 ? Math.floor(stat.size / bufferSize) : Math.floor(stat.size / bufferSize + 1); 6133 for (let i = 0;i < len; i++) { 6134 let options: Options = { 6135 offset: i * bufferSize, 6136 length: bufferSize 6137 } 6138 let readsize: number = await fileIo.read(file.fd, buf, options) 6139 let writeSize: number = await new Promise((resolve,reject)=>{ 6140 audioRenderer.write(buf,(err: BusinessError, writeSize: number)=>{ 6141 if(err){ 6142 reject(err) 6143 }else{ 6144 resolve(writeSize) 6145 } 6146 }) 6147 }) 6148 } 6149 }); 6150 }).catch((err: BusinessError) => { 6151 console.error(`AudioFrameworkRenderLog: getBufferSize: ERROR: ${err}`); 6152}); 6153 6154 6155 6156``` 6157 6158### write<sup>8+(deprecated)</sup> 6159 6160write(buffer: ArrayBuffer): Promise\<number> 6161 6162Writes the buffer. This API uses a promise to return the result. 6163 6164> **NOTE** 6165> 6166> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [on('writeData')](#onwritedata11) in **AudioRenderer**. 6167 6168**System capability**: SystemCapability.Multimedia.Audio.Renderer 6169 6170**Parameters** 6171 6172| Name | Type | Mandatory | Description | 6173| ------ | ----------- | --------- | --------------------------------- | 6174| buffer | ArrayBuffer | Yes | Data to be written to the buffer. | 6175 6176**Return value** 6177 6178| Type | Description | 6179| ---------------- | --------------------------------------------------- | 6180| Promise\<number> | Promise used to return the number of written bytes. | 6181 6182**Example** 6183 6184```ts 6185import { BusinessError } from '@kit.BasicServicesKit'; 6186import { fileIo } from '@kit.CoreFileKit'; 6187 6188let bufferSize: number; 6189class Options { 6190 offset?: number; 6191 length?: number; 6192} 6193audioRenderer.getBufferSize().then((data: number) => { 6194 console.info(`AudioFrameworkRenderLog: getBufferSize: SUCCESS ${data}`); 6195 bufferSize = data; 6196 console.info(`BufferSize: ${bufferSize}`); 6197 let path = getContext().cacheDir; 6198 let filePath = path + '/StarWars10s-2C-48000-4SW.wav'; 6199 let file: fileIo.File = fileIo.openSync(filePath, fileIo.OpenMode.READ_ONLY); 6200 fileIo.stat(filePath).then(async (stat: fileIo.Stat) => { 6201 let buf = new ArrayBuffer(bufferSize); 6202 let len = stat.size % bufferSize == 0 ? Math.floor(stat.size / bufferSize) : Math.floor(stat.size / bufferSize + 1); 6203 for (let i = 0;i < len; i++) { 6204 let options: Options = { 6205 offset: i * bufferSize, 6206 length: bufferSize 6207 } 6208 let readsize: number = await fileIo.read(file.fd, buf, options) 6209 try{ 6210 let writeSize: number = await audioRenderer.write(buf); 6211 } catch(err) { 6212 let error = err as BusinessError; 6213 console.error(`audioRenderer.write err: ${error}`); 6214 } 6215 } 6216 }); 6217}).catch((err: BusinessError) => { 6218 console.error(`AudioFrameworkRenderLog: getBufferSize: ERROR: ${err}`); 6219}); 6220 6221``` 6222 6223### getAudioTime<sup>8+</sup> 6224 6225getAudioTime(callback: AsyncCallback\<number>): void 6226 6227Obtains the number of nanoseconds elapsed from the Unix epoch (January 1, 1970). This API uses an asynchronous callback to return the result. 6228 6229**System capability**: SystemCapability.Multimedia.Audio.Renderer 6230 6231**Parameters** 6232 6233| Name | Type | Mandatory | Description | 6234| -------- | ---------------------- | --------- | ------------------------------------------------------------ | 6235| 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. | 6236 6237**Example** 6238 6239```ts 6240import { BusinessError } from '@kit.BasicServicesKit'; 6241 6242audioRenderer.getAudioTime((err: BusinessError, timestamp: number) => { 6243 console.info(`Current timestamp: ${timestamp}`); 6244}); 6245 6246``` 6247 6248### getAudioTime<sup>8+</sup> 6249 6250getAudioTime(): Promise\<number> 6251 6252Obtains the number of nanoseconds elapsed from the Unix epoch (January 1, 1970). This API uses a promise to return the result. 6253 6254**System capability**: SystemCapability.Multimedia.Audio.Renderer 6255 6256**Return value** 6257 6258| Type | Description | 6259| ---------------- | ------------------------------------- | 6260| Promise\<number> | Promise used to return the timestamp. | 6261 6262**Example** 6263 6264```ts 6265import { BusinessError } from '@kit.BasicServicesKit'; 6266 6267audioRenderer.getAudioTime().then((timestamp: number) => { 6268 console.info(`Current timestamp: ${timestamp}`); 6269}).catch((err: BusinessError) => { 6270 console.error(`ERROR: ${err}`); 6271}); 6272 6273``` 6274 6275### getAudioTimeSync<sup>10+</sup> 6276 6277getAudioTimeSync(): number 6278 6279Obtains the number of nanoseconds elapsed from the Unix epoch (January 1, 1970). This API returns the result synchronously. 6280 6281**System capability**: SystemCapability.Multimedia.Audio.Renderer 6282 6283**Return value** 6284 6285| Type | Description | 6286| ------ | ----------- | 6287| number | Timestamp. | 6288 6289**Example** 6290 6291```ts 6292import { BusinessError } from '@kit.BasicServicesKit'; 6293 6294try { 6295 let timestamp: number = audioRenderer.getAudioTimeSync(); 6296 console.info(`Current timestamp: ${timestamp}`); 6297} catch (err) { 6298 let error = err as BusinessError; 6299 console.error(`ERROR: ${error}`); 6300} 6301 6302``` 6303 6304### getBufferSize<sup>8+</sup> 6305 6306getBufferSize(callback: AsyncCallback\<number>): void 6307 6308Obtains a reasonable minimum buffer size in bytes for rendering. This API uses an asynchronous callback to return the result. 6309 6310**System capability**: SystemCapability.Multimedia.Audio.Renderer 6311 6312**Parameters** 6313 6314| Name | Type | Mandatory | Description | 6315| -------- | ---------------------- | --------- | ------------------------------------------------------------ | 6316| 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. | 6317 6318**Example** 6319 6320```ts 6321import { BusinessError } from '@kit.BasicServicesKit'; 6322 6323let bufferSize: number; 6324audioRenderer.getBufferSize((err: BusinessError, data: number) => { 6325 if (err) { 6326 console.error('getBufferSize error'); 6327 } else { 6328 console.info(`AudioFrameworkRenderLog: getBufferSize: SUCCESS ${data}`); 6329 bufferSize = data; 6330 } 6331}); 6332 6333``` 6334 6335### getBufferSize<sup>8+</sup> 6336 6337getBufferSize(): Promise\<number> 6338 6339Obtains a reasonable minimum buffer size in bytes for rendering. This API uses a promise to return the result. 6340 6341**System capability**: SystemCapability.Multimedia.Audio.Renderer 6342 6343**Return value** 6344 6345| Type | Description | 6346| ---------------- | --------------------------------------- | 6347| Promise\<number> | Promise used to return the buffer size. | 6348 6349**Example** 6350 6351```ts 6352import { BusinessError } from '@kit.BasicServicesKit'; 6353 6354let bufferSize: number; 6355audioRenderer.getBufferSize().then((data: number) => { 6356 console.info(`AudioFrameworkRenderLog: getBufferSize: SUCCESS ${data}`); 6357 bufferSize = data; 6358}).catch((err: BusinessError) => { 6359 console.error(`AudioFrameworkRenderLog: getBufferSize: ERROR: ${err}`); 6360}); 6361 6362``` 6363 6364### getBufferSizeSync<sup>10+</sup> 6365 6366getBufferSizeSync(): number 6367 6368Obtains a reasonable minimum buffer size in bytes for rendering. This API returns the result synchronously. 6369 6370**System capability**: SystemCapability.Multimedia.Audio.Renderer 6371 6372**Return value** 6373 6374| Type | Description | 6375| ------ | ------------ | 6376| number | Buffer size. | 6377 6378**Example** 6379 6380```ts 6381import { BusinessError } from '@kit.BasicServicesKit'; 6382 6383let bufferSize: number = 0; 6384try { 6385 bufferSize = audioRenderer.getBufferSizeSync(); 6386 console.info(`AudioFrameworkRenderLog: getBufferSize: SUCCESS ${bufferSize}`); 6387} catch (err) { 6388 let error = err as BusinessError; 6389 console.error(`AudioFrameworkRenderLog: getBufferSize: ERROR: ${error}`); 6390} 6391 6392``` 6393 6394### setRenderRate<sup>8+(deprecated)</sup> 6395 6396setRenderRate(rate: AudioRendererRate, callback: AsyncCallback\<void>): void 6397 6398Sets the render rate. This API uses an asynchronous callback to return the result. 6399 6400> **NOTE** 6401> 6402> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [setSpeed](#setspeed11) in **AudioRenderer**. 6403 6404**System capability**: SystemCapability.Multimedia.Audio.Renderer 6405 6406**Parameters** 6407 6408| Name | Type | Mandatory | Description | 6409| -------- | ---------------------------------------- | --------- | ------------------------------------------------------------ | 6410| rate | [AudioRendererRate](#audiorendererrate8) | Yes | Audio render rate. | 6411| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object. | 6412 6413**Example** 6414 6415```ts 6416import { BusinessError } from '@kit.BasicServicesKit'; 6417 6418audioRenderer.setRenderRate(audio.AudioRendererRate.RENDER_RATE_NORMAL, (err: BusinessError) => { 6419 if (err) { 6420 console.error('Failed to set params'); 6421 } else { 6422 console.info('Callback invoked to indicate a successful render rate setting.'); 6423 } 6424}); 6425 6426``` 6427 6428### setRenderRate<sup>8+(deprecated)</sup> 6429 6430setRenderRate(rate: AudioRendererRate): Promise\<void> 6431 6432Sets the render rate. This API uses a promise to return the result. 6433 6434> **NOTE** 6435> 6436> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [setSpeed](#setspeed11) in **AudioRenderer**. 6437 6438**System capability**: SystemCapability.Multimedia.Audio.Renderer 6439 6440**Parameters** 6441 6442| Name | Type | Mandatory | Description | 6443| ---- | ---------------------------------------- | --------- | ------------------ | 6444| rate | [AudioRendererRate](#audiorendererrate8) | Yes | Audio render rate. | 6445 6446**Return value** 6447 6448| Type | Description | 6449| -------------- | ------------------------------ | 6450| Promise\<void> | Promise that returns no value. | 6451 6452**Example** 6453 6454```ts 6455import { BusinessError } from '@kit.BasicServicesKit'; 6456 6457audioRenderer.setRenderRate(audio.AudioRendererRate.RENDER_RATE_NORMAL).then(() => { 6458 console.info('setRenderRate SUCCESS'); 6459}).catch((err: BusinessError) => { 6460 console.error(`ERROR: ${err}`); 6461}); 6462 6463``` 6464 6465### setSpeed<sup>11+</sup> 6466 6467setSpeed(speed: number): void 6468 6469Sets the playback speed. 6470 6471**System capability**: SystemCapability.Multimedia.Audio.Renderer 6472 6473**Parameters** 6474 6475| Name | Type | Mandatory | Description | 6476| ----- | ------ | --------- | ----------------------------------------------- | 6477| speed | number | Yes | Playback speed, which ranges from 0.125 to 4.0. | 6478 6479**Error codes** 6480 6481For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 6482 6483| ID | Error Message | 6484| ------- | ------------------------------------------------------------ | 6485| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 6486| 6800101 | Parameter verification failed. | 6487 6488**Example** 6489 6490```ts 6491audioRenderer.setSpeed(1.5); 6492 6493``` 6494 6495### getRenderRate<sup>8+(deprecated)</sup> 6496 6497getRenderRate(callback: AsyncCallback\<AudioRendererRate>): void 6498 6499Obtains the current render rate. This API uses an asynchronous callback to return the result. 6500 6501> **NOTE** 6502> 6503> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [getSpeed](#getspeed11) in **AudioRenderer**. 6504 6505**System capability**: SystemCapability.Multimedia.Audio.Renderer 6506 6507**Parameters** 6508 6509| Name | Type | Mandatory | Description | 6510| -------- | ------------------------------------------------------- | --------- | ------------------------------------------------------------ | 6511| 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. | 6512 6513**Example** 6514 6515```ts 6516import { BusinessError } from '@kit.BasicServicesKit'; 6517 6518audioRenderer.getRenderRate((err: BusinessError, renderRate: audio.AudioRendererRate) => { 6519 console.info(`getRenderRate: ${renderRate}`); 6520}); 6521 6522``` 6523 6524### getRenderRate<sup>8+(deprecated)</sup> 6525 6526getRenderRate(): Promise\<AudioRendererRate> 6527 6528Obtains the current render rate. This API uses a promise to return the result. 6529 6530> **NOTE** 6531> 6532> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [getSpeed](#getspeed11) in **AudioRenderer**. 6533 6534**System capability**: SystemCapability.Multimedia.Audio.Renderer 6535 6536**Return value** 6537 6538| Type | Description | 6539| ------------------------------------------------- | --------------------------------------- | 6540| Promise<[AudioRendererRate](#audiorendererrate8)> | Promise used to return the render rate. | 6541 6542**Example** 6543 6544```ts 6545import { BusinessError } from '@kit.BasicServicesKit'; 6546 6547audioRenderer.getRenderRate().then((renderRate: audio.AudioRendererRate) => { 6548 console.info(`getRenderRate: ${renderRate}`); 6549}).catch((err: BusinessError) => { 6550 console.error(`ERROR: ${err}`); 6551}); 6552 6553``` 6554 6555### getRenderRateSync<sup>10+(deprecated)</sup> 6556 6557getRenderRateSync(): AudioRendererRate 6558 6559Obtains the current render rate. This API returns the result synchronously. 6560 6561> **NOTE** 6562> 6563> This API is supported since API version 10 and deprecated since API version 11. You are advised to use [getSpeed](#getspeed11) in **AudioRenderer**. 6564 6565**System capability**: SystemCapability.Multimedia.Audio.Renderer 6566 6567**Return value** 6568 6569| Type | Description | 6570| ---------------------------------------- | ------------------ | 6571| [AudioRendererRate](#audiorendererrate8) | Audio render rate. | 6572 6573**Example** 6574 6575```ts 6576import { BusinessError } from '@kit.BasicServicesKit'; 6577 6578try { 6579 let renderRate: audio.AudioRendererRate = audioRenderer.getRenderRateSync(); 6580 console.info(`getRenderRate: ${renderRate}`); 6581} catch (err) { 6582 let error = err as BusinessError; 6583 console.error(`ERROR: ${error}`); 6584} 6585 6586``` 6587 6588### getSpeed<sup>11+</sup> 6589 6590getSpeed(): number 6591 6592Obtains the playback speed. 6593 6594**System capability**: SystemCapability.Multimedia.Audio.Renderer 6595 6596**Return value** 6597 6598| Type | Description | 6599| ------ | --------------- | 6600| number | Playback speed. | 6601 6602**Example** 6603 6604```ts 6605let speed = audioRenderer.getSpeed(); 6606 6607``` 6608 6609### setInterruptMode<sup>9+</sup> 6610 6611setInterruptMode(mode: InterruptMode): Promise<void> 6612 6613Sets the audio interruption mode for the application. This API uses a promise to return the result. 6614 6615**System capability**: SystemCapability.Multimedia.Audio.Interrupt 6616 6617**Parameters** 6618 6619| Name | Type | Mandatory | Description | 6620| ---- | -------------------------------- | --------- | ------------------------ | 6621| mode | [InterruptMode](#interruptmode9) | Yes | Audio interruption mode. | 6622 6623**Return value** 6624 6625| Type | Description | 6626| ------------------- | ------------------------------ | 6627| Promise<void> | Promise that returns no value. | 6628 6629**Example** 6630 6631```ts 6632import { BusinessError } from '@kit.BasicServicesKit'; 6633 6634let mode = 0; 6635audioRenderer.setInterruptMode(mode).then(() => { 6636 console.info('setInterruptMode Success!'); 6637}).catch((err: BusinessError) => { 6638 console.error(`setInterruptMode Fail: ${err}`); 6639}); 6640 6641``` 6642 6643### setInterruptMode<sup>9+</sup> 6644 6645setInterruptMode(mode: InterruptMode, callback: AsyncCallback\<void>): void 6646 6647Sets the audio interruption mode for the application. This API uses an asynchronous callback to return the result. 6648 6649**System capability**: SystemCapability.Multimedia.Audio.Interrupt 6650 6651**Parameters** 6652 6653| Name | Type | Mandatory | Description | 6654| -------- | -------------------------------- | --------- | ------------------------------------------------------------ | 6655| mode | [InterruptMode](#interruptmode9) | Yes | Audio interruption mode. | 6656| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object. | 6657 6658**Example** 6659 6660```ts 6661import { BusinessError } from '@kit.BasicServicesKit'; 6662 6663let mode = 1; 6664audioRenderer.setInterruptMode(mode, (err: BusinessError) => { 6665 if(err){ 6666 console.error(`setInterruptMode Fail: ${err}`); 6667 } 6668 console.info('setInterruptMode Success!'); 6669}); 6670 6671``` 6672 6673### setInterruptModeSync<sup>10+</sup> 6674 6675setInterruptModeSync(mode: InterruptMode): void 6676 6677Sets the audio interruption mode for the application. This API returns the result synchronously. 6678 6679**System capability**: SystemCapability.Multimedia.Audio.Interrupt 6680 6681**Parameters** 6682 6683| Name | Type | Mandatory | Description | 6684| ---- | -------------------------------- | --------- | ------------------------ | 6685| mode | [InterruptMode](#interruptmode9) | Yes | Audio interruption mode. | 6686 6687**Error codes** 6688 6689For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 6690 6691| ID | Error Message | 6692| ------- | ------------------------------------------------------------ | 6693| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 6694| 6800101 | Parameter verification failed. | 6695 6696**Example** 6697 6698```ts 6699import { BusinessError } from '@kit.BasicServicesKit'; 6700 6701try { 6702 audioRenderer.setInterruptModeSync(0); 6703 console.info('setInterruptMode Success!'); 6704} catch (err) { 6705 let error = err as BusinessError; 6706 console.error(`setInterruptMode Fail: ${error}`); 6707} 6708 6709``` 6710 6711### setVolume<sup>9+</sup> 6712 6713setVolume(volume: number): Promise<void> 6714 6715Sets the volume for the application. This API uses a promise to return the result. 6716 6717**System capability**: SystemCapability.Multimedia.Audio.Renderer 6718 6719**Parameters** 6720 6721| Name | Type | Mandatory | Description | 6722| ------ | ------ | --------- | ------------------------------------------------------------ | 6723| volume | number | Yes | Volume to set, which can be within the range from 0.0 to 1.0. | 6724 6725**Return value** 6726 6727| Type | Description | 6728| ------------------- | ------------------------------ | 6729| Promise<void> | Promise that returns no value. | 6730 6731**Example** 6732 6733```ts 6734import { BusinessError } from '@kit.BasicServicesKit'; 6735 6736audioRenderer.setVolume(0.5).then(() => { 6737 console.info('setVolume Success!'); 6738}).catch((err: BusinessError) => { 6739 console.error(`setVolume Fail: ${err}`); 6740}); 6741 6742``` 6743 6744### setVolume<sup>9+</sup> 6745 6746setVolume(volume: number, callback: AsyncCallback\<void>): void 6747 6748Sets the volume for the application. This API uses an asynchronous callback to return the result. 6749 6750**System capability**: SystemCapability.Multimedia.Audio.Renderer 6751 6752**Parameters** 6753 6754| Name | Type | Mandatory | Description | 6755| -------- | -------------------- | --------- | ------------------------------------------------------------ | 6756| volume | number | Yes | Volume to set, which can be within the range from 0.0 to 1.0. | 6757| callback | AsyncCallback\<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object. | 6758 6759**Example** 6760 6761```ts 6762import { BusinessError } from '@kit.BasicServicesKit'; 6763 6764audioRenderer.setVolume(0.5, (err: BusinessError) => { 6765 if(err){ 6766 console.error(`setVolume Fail: ${err}`); 6767 return; 6768 } 6769 console.info('setVolume Success!'); 6770}); 6771 6772``` 6773 6774### getVolume<sup>12+</sup> 6775 6776getVolume(): number 6777 6778Obtains the volume of the audio render. This API returns the result synchronously. 6779 6780**System capability**: SystemCapability.Multimedia.Audio.Renderer 6781 6782**Return value** 6783 6784| Type | Description | 6785| ------ | ------------------------------- | 6786| number | Volume, in the range [0.0-1.0]. | 6787 6788**Example** 6789 6790```ts 6791import { BusinessError } from '@kit.BasicServicesKit'; 6792 6793try { 6794 let value: number = audioRenderer.getVolume(); 6795 console.info(`Indicate that the volume is obtained ${value}.`); 6796} catch (err) { 6797 let error = err as BusinessError; 6798 console.error(`Failed to obtain the volume, error ${error}.`); 6799} 6800 6801``` 6802 6803### getMinStreamVolume<sup>10+</sup> 6804 6805getMinStreamVolume(callback: AsyncCallback<number>): void 6806 6807Obtains the minimum volume of the application from the perspective of an audio stream. This API uses an asynchronous callback to return the result. 6808 6809**System capability**: SystemCapability.Multimedia.Audio.Renderer 6810 6811**Parameters** 6812 6813| Name | Type | Mandatory | Description | 6814| -------- | --------------------------- | --------- | ------------------------------------------------------------ | 6815| 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. | 6816 6817**Example** 6818 6819```ts 6820import { BusinessError } from '@kit.BasicServicesKit'; 6821 6822audioRenderer.getMinStreamVolume((err: BusinessError, minVolume: number) => { 6823 if (err) { 6824 console.error(`getMinStreamVolume error: ${err}`); 6825 } else { 6826 console.info(`getMinStreamVolume Success! ${minVolume}`); 6827 } 6828}); 6829 6830``` 6831 6832### getMinStreamVolume<sup>10+</sup> 6833 6834getMinStreamVolume(): Promise<number> 6835 6836Obtains the minimum volume of the application from the perspective of an audio stream. This API uses a promise to return the result. 6837 6838**System capability**: SystemCapability.Multimedia.Audio.Renderer 6839 6840**Return value** 6841 6842| Type | Description | 6843| --------------------- | ------------------------------------------------------------ | 6844| Promise<number> | Promise used to return the minimum volume, ranging from 0 to 1. | 6845 6846**Example** 6847 6848```ts 6849import { BusinessError } from '@kit.BasicServicesKit'; 6850 6851audioRenderer.getMinStreamVolume().then((value: number) => { 6852 console.info(`Get min stream volume Success! ${value}`); 6853}).catch((err: BusinessError) => { 6854 console.error(`Get min stream volume Fail: ${err}`); 6855}); 6856 6857``` 6858 6859### getMinStreamVolumeSync<sup>10+</sup> 6860 6861getMinStreamVolumeSync(): number 6862 6863Obtains the minimum volume of the application from the perspective of an audio stream. This API returns the result synchronously. 6864 6865**System capability**: SystemCapability.Multimedia.Audio.Renderer 6866 6867**Return value** 6868 6869| Type | Description | 6870| ------ | ------------------------------------ | 6871| number | Minimum volume, ranging from 0 to 1. | 6872 6873**Example** 6874 6875```ts 6876import { BusinessError } from '@kit.BasicServicesKit'; 6877 6878try { 6879 let value: number = audioRenderer.getMinStreamVolumeSync(); 6880 console.info(`Get min stream volume Success! ${value}`); 6881} catch (err) { 6882 let error = err as BusinessError; 6883 console.error(`Get min stream volume Fail: ${error}`); 6884} 6885 6886``` 6887 6888### getMaxStreamVolume<sup>10+</sup> 6889 6890getMaxStreamVolume(callback: AsyncCallback<number>): void 6891 6892Obtains the maximum volume of the application from the perspective of an audio stream. This API uses an asynchronous callback to return the result. 6893 6894**System capability**: SystemCapability.Multimedia.Audio.Renderer 6895 6896**Parameters** 6897 6898| Name | Type | Mandatory | Description | 6899| -------- | --------------------------- | --------- | ------------------------------------------------------------ | 6900| 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. | 6901 6902**Example** 6903 6904```ts 6905import { BusinessError } from '@kit.BasicServicesKit'; 6906 6907audioRenderer.getMaxStreamVolume((err: BusinessError, maxVolume: number) => { 6908 if (err) { 6909 console.error(`getMaxStreamVolume Fail: ${err}`); 6910 } else { 6911 console.info(`getMaxStreamVolume Success! ${maxVolume}`); 6912 } 6913}); 6914 6915``` 6916 6917### getMaxStreamVolume<sup>10+</sup> 6918 6919getMaxStreamVolume(): Promise<number> 6920 6921Obtains the maximum volume of the application from the perspective of an audio stream. This API uses a promise to return the result. 6922 6923**System capability**: SystemCapability.Multimedia.Audio.Renderer 6924 6925**Return value** 6926 6927| Type | Description | 6928| --------------------- | ------------------------------------------------------------ | 6929| Promise<number> | Promise used to return the maximum volume, ranging from 0 to 1. | 6930 6931**Example** 6932 6933```ts 6934import { BusinessError } from '@kit.BasicServicesKit'; 6935 6936audioRenderer.getMaxStreamVolume().then((value: number) => { 6937 console.info(`Get max stream volume Success! ${value}`); 6938}).catch((err: BusinessError) => { 6939 console.error(`Get max stream volume Fail: ${err}`); 6940}); 6941 6942``` 6943 6944### getMaxStreamVolumeSync<sup>10+</sup> 6945 6946getMaxStreamVolumeSync(): number 6947 6948Obtains the maximum volume of the application from the perspective of an audio stream. This API returns the result synchronously. 6949 6950**System capability**: SystemCapability.Multimedia.Audio.Renderer 6951 6952**Return value** 6953 6954| Type | Description | 6955| ------ | ------------------------------------ | 6956| number | Maximum volume, ranging from 0 to 1. | 6957 6958**Example** 6959 6960```ts 6961import { BusinessError } from '@kit.BasicServicesKit'; 6962 6963try { 6964 let value: number = audioRenderer.getMaxStreamVolumeSync(); 6965 console.info(`Get max stream volume Success! ${value}`); 6966} catch (err) { 6967 let error = err as BusinessError; 6968 console.error(`Get max stream volume Fail: ${error}`); 6969} 6970 6971``` 6972 6973### getUnderflowCount<sup>10+</sup> 6974 6975getUnderflowCount(callback: AsyncCallback<number>): void 6976 6977Obtains the number of underflow audio frames in the audio stream that is being played. This API uses an asynchronous callback to return the result. 6978 6979**System capability**: SystemCapability.Multimedia.Audio.Renderer 6980 6981**Parameters** 6982 6983| Name | Type | Mandatory | Description | 6984| -------- | --------------------------- | --------- | ------------------------------------------------------------ | 6985| 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. | 6986 6987**Example** 6988 6989```ts 6990import { BusinessError } from '@kit.BasicServicesKit'; 6991 6992audioRenderer.getUnderflowCount((err: BusinessError, underflowCount: number) => { 6993 if (err) { 6994 console.error(`getUnderflowCount Fail: ${err}`); 6995 } else { 6996 console.info(`getUnderflowCount Success! ${underflowCount}`); 6997 } 6998}); 6999 7000``` 7001 7002### getUnderflowCount<sup>10+</sup> 7003 7004getUnderflowCount(): Promise<number> 7005 7006Obtains the number of underflow audio frames in the audio stream that is being played. This API uses a promise to return the result. 7007 7008**System capability**: SystemCapability.Multimedia.Audio.Renderer 7009 7010**Return value** 7011 7012| Type | Description | 7013| --------------------- | ------------------------------------------------------------ | 7014| Promise<number> | Promise used to return the number of underflow audio frames. | 7015 7016**Example** 7017 7018```ts 7019import { BusinessError } from '@kit.BasicServicesKit'; 7020 7021audioRenderer.getUnderflowCount().then((value: number) => { 7022 console.info(`Get underflow count Success! ${value}`); 7023}).catch((err: BusinessError) => { 7024 console.error(`Get underflow count Fail: ${err}`); 7025}); 7026 7027``` 7028 7029### getUnderflowCountSync<sup>10+</sup> 7030 7031getUnderflowCountSync(): number 7032 7033Obtains the number of underflow audio frames in the audio stream that is being played. This API returns the result synchronously. 7034 7035**System capability**: SystemCapability.Multimedia.Audio.Renderer 7036 7037**Return value** 7038 7039| Type | Description | 7040| ------ | --------------------------------- | 7041| number | Number of underflow audio frames. | 7042 7043**Example** 7044 7045```ts 7046import { BusinessError } from '@kit.BasicServicesKit'; 7047 7048try { 7049 let value: number = audioRenderer.getUnderflowCountSync(); 7050 console.info(`Get underflow count Success! ${value}`); 7051} catch (err) { 7052 let error = err as BusinessError; 7053 console.error(`Get underflow count Fail: ${error}`); 7054} 7055 7056``` 7057 7058### getCurrentOutputDevices<sup>10+</sup> 7059 7060getCurrentOutputDevices(callback: AsyncCallback<AudioDeviceDescriptors>): void 7061 7062Obtains the output device descriptors of the audio streams. This API uses an asynchronous callback to return the result. 7063 7064**System capability**: SystemCapability.Multimedia.Audio.Device 7065 7066**Parameters** 7067 7068| Name | Type | Mandatory | Description | 7069| -------- | ------------------------------------------------------------ | --------- | ------------------------------------------------------------ | 7070| 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. | 7071 7072**Example** 7073 7074```ts 7075import { BusinessError } from '@kit.BasicServicesKit'; 7076 7077audioRenderer.getCurrentOutputDevices((err: BusinessError, deviceInfo: audio.AudioDeviceDescriptors) => { 7078 if (err) { 7079 console.error(`getCurrentOutputDevices Fail: ${err}`); 7080 } else { 7081 for (let i = 0; i < deviceInfo.length; i++) { 7082 console.info(`DeviceInfo id: ${deviceInfo[i].id}`); 7083 console.info(`DeviceInfo type: ${deviceInfo[i].deviceType}`); 7084 console.info(`DeviceInfo role: ${deviceInfo[i].deviceRole}`); 7085 console.info(`DeviceInfo name: ${deviceInfo[i].name}`); 7086 console.info(`DeviceInfo address: ${deviceInfo[i].address}`); 7087 console.info(`DeviceInfo samplerate: ${deviceInfo[i].sampleRates[0]}`); 7088 console.info(`DeviceInfo channelcount: ${deviceInfo[i].channelCounts[0]}`); 7089 console.info(`DeviceInfo channelmask: ${deviceInfo[i].channelMasks[0]}`); 7090 } 7091 } 7092}); 7093 7094``` 7095 7096### getCurrentOutputDevices<sup>10+</sup> 7097 7098getCurrentOutputDevices(): Promise<AudioDeviceDescriptors> 7099 7100Obtains the output device descriptors of the audio streams. This API uses a promise to return the result. 7101 7102**System capability**: SystemCapability.Multimedia.Audio.Device 7103 7104**Return value** 7105 7106| Type | Description | 7107| ------------------------------------------------------------ | ----------------------------------------------------- | 7108| Promise<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Promise used to return the output device descriptors. | 7109 7110**Example** 7111 7112```ts 7113import { BusinessError } from '@kit.BasicServicesKit'; 7114 7115audioRenderer.getCurrentOutputDevices().then((deviceInfo: audio.AudioDeviceDescriptors) => { 7116 for (let i = 0; i < deviceInfo.length; i++) { 7117 console.info(`DeviceInfo id: ${deviceInfo[i].id}`); 7118 console.info(`DeviceInfo type: ${deviceInfo[i].deviceType}`); 7119 console.info(`DeviceInfo role: ${deviceInfo[i].deviceRole}`); 7120 console.info(`DeviceInfo name: ${deviceInfo[i].name}`); 7121 console.info(`DeviceInfo address: ${deviceInfo[i].address}`); 7122 console.info(`DeviceInfo samplerate: ${deviceInfo[i].sampleRates[0]}`); 7123 console.info(`DeviceInfo channelcount: ${deviceInfo[i].channelCounts[0]}`); 7124 console.info(`DeviceInfo channelmask: ${deviceInfo[i].channelMasks[0]}`); 7125 } 7126}).catch((err: BusinessError) => { 7127 console.error(`Get current output devices Fail: ${err}`); 7128}); 7129 7130``` 7131 7132### getCurrentOutputDevicesSync<sup>10+</sup> 7133 7134getCurrentOutputDevicesSync(): AudioDeviceDescriptors 7135 7136Obtains the output device descriptors of the audio streams. This API returns the result synchronously. 7137 7138**System capability**: SystemCapability.Multimedia.Audio.Device 7139 7140**Return value** 7141 7142| Type | Description | 7143| ------------------------------------------------- | -------------------------- | 7144| [AudioDeviceDescriptors](#audiodevicedescriptors) | Output device descriptors. | 7145 7146**Example** 7147 7148```ts 7149import { BusinessError } from '@kit.BasicServicesKit'; 7150 7151try { 7152 let deviceInfo: audio.AudioDeviceDescriptors = audioRenderer.getCurrentOutputDevicesSync(); 7153 for (let i = 0; i < deviceInfo.length; i++) { 7154 console.info(`DeviceInfo id: ${deviceInfo[i].id}`); 7155 console.info(`DeviceInfo type: ${deviceInfo[i].deviceType}`); 7156 console.info(`DeviceInfo role: ${deviceInfo[i].deviceRole}`); 7157 console.info(`DeviceInfo name: ${deviceInfo[i].name}`); 7158 console.info(`DeviceInfo address: ${deviceInfo[i].address}`); 7159 console.info(`DeviceInfo samplerate: ${deviceInfo[i].sampleRates[0]}`); 7160 console.info(`DeviceInfo channelcount: ${deviceInfo[i].channelCounts[0]}`); 7161 console.info(`DeviceInfo channelmask: ${deviceInfo[i].channelMasks[0]}`); 7162 } 7163} catch (err) { 7164 let error = err as BusinessError; 7165 console.error(`Get current output devices Fail: ${error}`); 7166} 7167 7168``` 7169 7170### setChannelBlendMode<sup>11+</sup> 7171 7172setChannelBlendMode(mode: ChannelBlendMode): void 7173 7174Sets the audio channel blending mode. This API returns the result synchronously. 7175 7176**System capability**: SystemCapability.Multimedia.Audio.Renderer 7177 7178**Parameters** 7179 7180| Name | Type | Mandatory | Description | 7181| ---- | --------------------------------------- | --------- | ---------------------------- | 7182| mode | [ChannelBlendMode](#channelblendmode11) | Yes | Audio channel blending mode. | 7183 7184**Error codes** 7185 7186For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7187 7188| ID | Error Message | 7189| ------- | ------------------------------------------------------------ | 7190| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7191| 6800101 | Parameter verification failed. | 7192| 6800103 | Operation not permit at current state. | 7193 7194**Example** 7195 7196```ts 7197let mode = audio.ChannelBlendMode.MODE_DEFAULT; 7198 7199audioRenderer.setChannelBlendMode(mode); 7200console.info(`BlendMode: ${mode}`); 7201 7202``` 7203 7204### setVolumeWithRamp<sup>11+</sup> 7205 7206setVolumeWithRamp(volume: number, duration: number): void 7207 7208Sets a volume ramp. This API returns the result synchronously. 7209 7210**System capability**: SystemCapability.Multimedia.Audio.Renderer 7211 7212**Parameters** 7213 7214| Name | Type | Mandatory | Description | 7215| -------- | ------ | --------- | ------------------------------------------------ | 7216| volume | number | Yes | Target volume, within the range [0.0, 1.0]. | 7217| duration | number | Yes | Time range during which the ramp applies, in ms. | 7218 7219**Error codes** 7220 7221For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7222 7223| ID | Error Message | 7224| ------- | ------------------------------------------------------------ | 7225| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7226| 6800101 | Parameter verification failed. | 7227 7228**Example** 7229 7230```ts 7231let volume = 0.5; 7232let duration = 1000; 7233 7234audioRenderer.setVolumeWithRamp(volume, duration); 7235console.info(`setVolumeWithRamp: ${volume}`); 7236 7237``` 7238 7239### setSilentModeAndMixWithOthers<sup>12+</sup> 7240 7241setSilentModeAndMixWithOthers(on: boolean): void 7242 7243Sets the silent mode in concurrent playback for the audio stream. 7244 7245If 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. 7246 7247**System capability**: SystemCapability.Multimedia.Audio.Renderer 7248 7249**Parameters** 7250 7251| Name | Type | Mandatory | Description | 7252| ---- | ------- | --------- | ------------------------------------------------------------ | 7253| 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. | 7254 7255**Example** 7256 7257```ts 7258audioRenderer.setSilentModeAndMixWithOthers(true); 7259 7260``` 7261 7262### getSilentModeAndMixWithOthers<sup>12+</sup> 7263 7264getSilentModeAndMixWithOthers(): boolean 7265 7266Obtains the silent mode in concurrent playback for the audio stream. 7267 7268**System capability**: SystemCapability.Multimedia.Audio.Renderer 7269 7270**Return value** 7271 7272| Type | Description | 7273| ------- | ------------------------------------------------------------ | 7274| boolean | **true**: The silent mode in concurrent playback is enabled.<br>**false**: The silent mode in concurrent playback is disabled. | 7275 7276**Example** 7277 7278```ts 7279let on = audioRenderer.getSilentModeAndMixWithOthers(); 7280 7281``` 7282 7283### setDefaultOutputDevice<sup>12+</sup> 7284 7285setDefaultOutputDevice(deviceType: DeviceType): Promise<void> 7286 7287Sets the default built-in audio output device. This API uses a promise to return the result. 7288 7289This 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. 7290 7291This 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. 7292 7293**System capability**: SystemCapability.Multimedia.Audio.Renderer 7294 7295**Parameters** 7296 7297| Name | Type | Mandatory | Description | 7298| ---------- | ------------------------- | --------- | ------------------------------------------------------------ | 7299| deviceType | [DeviceType](#devicetype) | Yes | Device type.<br>The options are **EARPIECE**, **SPEAKER**, and **DEFAULT**. | 7300 7301**Return value** 7302 7303| Type | Description | 7304| ------------------- | ------------------------------ | 7305| Promise<void> | Promise that returns no value. | 7306 7307**Error codes** 7308 7309For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7310 7311| ID | Error Message | 7312| ------- | ------------------------------------------------------------ | 7313| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7314| 6800101 | Parameter verification failed. | 7315| 6800103 | Operation not permit at current state. | 7316 7317**Example** 7318 7319```ts 7320import { BusinessError } from '@kit.BasicServicesKit'; 7321 7322// This API can be called at any time after an **AudioRenderer** instance is created. 7323// 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. 7324// 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. 7325audioRenderer.setDefaultOutputDevice(audio.DeviceType.SPEAKER).then(() => { 7326 console.info('setDefaultOutputDevice Success!'); 7327}).catch((err: BusinessError) => { 7328 console.error(`setDefaultOutputDevice Fail: ${err}`); 7329}); 7330 7331``` 7332 7333### on('audioInterrupt')<sup>9+</sup> 7334 7335on(type: 'audioInterrupt', callback: Callback\<InterruptEvent>): void 7336 7337Subscribes to audio interruption events. This API uses an asynchronous callback to return the result. Such an event is triggered when the audio focus is changed. 7338 7339The **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. 7340 7341After 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 [Processing Audio Interruption Events](../../media/audio/audio-playback-concurrency.md). 7342 7343**System capability**: SystemCapability.Multimedia.Audio.Interrupt 7344 7345**Parameters** 7346 7347| Name | Type | Mandatory | Description | 7348| -------- | ---------------------------------------------- | --------- | ------------------------------------------------------------ | 7349| type | string | Yes | Event type. The value is fixed at **'audioInterrupt'**. | 7350| callback | Callback\<[InterruptEvent](#interruptevent9)\> | Yes | Callback used to return the audio interruption event received by the application when playback is interrupted. | 7351 7352**Error codes** 7353 7354For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7355 7356| ID | Error Message | 7357| ------- | ------------------------------------------------------------ | 7358| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7359| 6800101 | Parameter verification failed. | 7360 7361**Example** 7362 7363```ts 7364import { audio } from '@kit.AudioKit'; 7365 7366let isPlaying: boolean; // An identifier specifying whether rendering is in progress. 7367let isDucked: boolean; // An identifier specifying whether the audio volume is reduced. 7368onAudioInterrupt(); 7369 7370async function onAudioInterrupt(){ 7371 audioRenderer.on('audioInterrupt', (interruptEvent: audio.InterruptEvent) => { 7372 // When an audio interruption event occurs, the AudioRenderer receives the interruptEvent callback and performs processing based on the content in the callback. 7373 // 1. (Optional) The AudioRenderer reads the value of interruptEvent.forceType to see whether the system has forcibly performed the operation. 7374 // 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. 7375 // 2. (Mandatory) The AudioRenderer then reads the value of interruptEvent.hintType and performs corresponding processing. 7376 if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_FORCE) { 7377 // The audio focus event has been forcibly executed by the system. The application needs to update its status and displayed content. 7378 switch (interruptEvent.hintType) { 7379 case audio.InterruptHint.INTERRUPT_HINT_PAUSE: 7380 // 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. 7381 console.info('Force paused. Update playing status and stop writing'); 7382 isPlaying = false; // A simplified processing indicating several operations for switching the application to the paused state. 7383 break; 7384 case audio.InterruptHint.INTERRUPT_HINT_STOP: 7385 // The audio stream has been stopped and permanently loses the focus. The user must manually trigger the operation to resume rendering. 7386 console.info('Force stopped. Update playing status and stop writing'); 7387 isPlaying = false; // A simplified processing indicating several operations for switching the application to the paused state. 7388 break; 7389 case audio.InterruptHint.INTERRUPT_HINT_DUCK: 7390 // The audio stream is rendered at a reduced volume. 7391 console.info('Force ducked. Update volume status'); 7392 isDucked = true; // A simplified processing indicating several operations for updating the volume status. 7393 break; 7394 case audio.InterruptHint.INTERRUPT_HINT_UNDUCK: 7395 // The audio stream is rendered at the normal volume. 7396 console.info('Force ducked. Update volume status'); 7397 isDucked = false; // A simplified processing indicating several operations for updating the volume status. 7398 break; 7399 default: 7400 console.info('Invalid interruptEvent'); 7401 break; 7402 } 7403 } else if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_SHARE) { 7404 // 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. 7405 switch (interruptEvent.hintType) { 7406 case audio.InterruptHint.INTERRUPT_HINT_RESUME: 7407 // 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.) 7408 // 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. 7409 console.info('Resume force paused renderer or ignore'); 7410 // To continue rendering, the application must perform the required operations. 7411 break; 7412 default: 7413 console.info('Invalid interruptEvent'); 7414 break; 7415 } 7416 } 7417 }); 7418} 7419 7420``` 7421 7422### on('markReach')<sup>8+</sup> 7423 7424on(type: 'markReach', frame: number, callback: Callback<number>): void 7425 7426Subscribes to mark reached events. This API uses an asynchronous callback to return the result. Such an event is triggered (only once) when the number of frames rendered reaches the value of the **frame** parameter. 7427 7428For example, if **frame** is set to **100**, the callback is invoked when the number of rendered frames reaches the 100th frame. 7429 7430**System capability**: SystemCapability.Multimedia.Audio.Renderer 7431 7432**Parameters** 7433 7434| Name | Type | Mandatory | Description | 7435| :------- | :---------------- | :-------- | :----------------------------------------------------------- | 7436| type | string | Yes | Event type. The value is fixed at **'markReach'**. | 7437| frame | number | Yes | Number of frames to trigger the event. The value must be greater than **0**. | 7438| callback | Callback\<number> | Yes | Callback used to return the value of the **frame** parameter. | 7439 7440**Example** 7441 7442```ts 7443audioRenderer.on('markReach', 1000, (position: number) => { 7444 if (position == 1000) { 7445 console.info('ON Triggered successfully'); 7446 } 7447}); 7448 7449``` 7450 7451 7452### off('markReach')<sup>8+</sup> 7453 7454off(type: 'markReach'): void 7455 7456Unsubscribes from mark reached events. 7457 7458**System capability**: SystemCapability.Multimedia.Audio.Renderer 7459 7460**Parameters** 7461 7462| Name | Type | Mandatory | Description | 7463| :--- | :----- | :-------- | :------------------------------------------------- | 7464| type | string | Yes | Event type. The value is fixed at **'markReach'**. | 7465 7466**Example** 7467 7468```ts 7469audioRenderer.off('markReach'); 7470 7471``` 7472 7473### on('periodReach')<sup>8+</sup> 7474 7475on(type: 'periodReach', frame: number, callback: Callback<number>): void 7476 7477Subscribes to period reached events. This API uses an asynchronous callback to return the result. Such an event is triggered each time the number of frames rendered reaches the value of the **frame** parameter. In other words, the information is reported periodically. 7478 7479For 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. 7480 7481**System capability**: SystemCapability.Multimedia.Audio.Renderer 7482 7483**Parameters** 7484 7485| Name | Type | Mandatory | Description | 7486| :------- | :---------------- | :-------- | :----------------------------------------------------------- | 7487| type | string | Yes | Event type. The value is fixed at **'periodReach'**. | 7488| frame | number | Yes | Number of frames to trigger the event. The value must be greater than **0**. | 7489| callback | Callback\<number> | Yes | Callback used to return the value of the **frame** parameter. | 7490 7491**Example** 7492 7493```ts 7494audioRenderer.on('periodReach', 1000, (position: number) => { 7495 if (position == 1000) { 7496 console.info('ON Triggered successfully'); 7497 } 7498}); 7499 7500``` 7501 7502### off('periodReach')<sup>8+</sup> 7503 7504off(type: 'periodReach'): void 7505 7506Unsubscribes from period reached events. 7507 7508**System capability**: SystemCapability.Multimedia.Audio.Renderer 7509 7510**Parameters** 7511 7512| Name | Type | Mandatory | Description | 7513| :--- | :----- | :-------- | :--------------------------------------------------- | 7514| type | string | Yes | Event type. The value is fixed at **'periodReach'**. | 7515 7516**Example** 7517 7518```ts 7519audioRenderer.off('periodReach'); 7520 7521``` 7522 7523### on('stateChange')<sup>8+</sup> 7524 7525on(type: 'stateChange', callback: Callback<AudioState\>): void 7526 7527Subscribes to audio renderer state change events. This API uses an asynchronous callback to return the result. Such an event is triggered when the state of the audio renderer is changed. 7528 7529**System capability**: SystemCapability.Multimedia.Audio.Renderer 7530 7531**Parameters** 7532 7533| Name | Type | Mandatory | Description | 7534| :------- | :------------------------------------ | :-------- | :--------------------------------------------------- | 7535| type | string | Yes | Event type. The value is fixed at **'stateChange'**. | 7536| callback | Callback\<[AudioState](#audiostate8)> | Yes | Callback used to return the audio status. | 7537 7538**Example** 7539 7540```ts 7541audioRenderer.on('stateChange', (state: audio.AudioState) => { 7542 if (state == 1) { 7543 console.info('audio renderer state is: STATE_PREPARED'); 7544 } 7545 if (state == 2) { 7546 console.info('audio renderer state is: STATE_RUNNING'); 7547 } 7548}); 7549 7550``` 7551 7552### on('outputDeviceChange')<sup>10+</sup> 7553 7554on(type: 'outputDeviceChange', callback: Callback\<AudioDeviceDescriptors>): void 7555 7556Subscribes to audio output device change events. This API uses an asynchronous callback to return the result. Such an event is triggered when an audio output device is changed. 7557 7558**System capability**: SystemCapability.Multimedia.Audio.Device 7559 7560**Parameters** 7561 7562| Name | Type | Mandatory | Description | 7563| :------- | :----------------------------------------------------------- | :-------- | :----------------------------------------------------------- | 7564| type | string | Yes | Event type. The value is fixed at **'outputDeviceChange'**. | 7565| callback | Callback\<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Yes | Callback used to return the output device descriptor of the current audio stream. | 7566 7567**Error codes** 7568 7569For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7570 7571| ID | Error Message | 7572| ------- | ------------------------------------------------------------ | 7573| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7574| 6800101 | Parameter verification failed. | 7575 7576**Example** 7577 7578```ts 7579audioRenderer.on('outputDeviceChange', (deviceInfo: audio.AudioDeviceDescriptors) => { 7580 console.info(`DeviceInfo id: ${deviceInfo[0].id}`); 7581 console.info(`DeviceInfo name: ${deviceInfo[0].name}`); 7582 console.info(`DeviceInfo address: ${deviceInfo[0].address}`); 7583}); 7584 7585``` 7586 7587### off('outputDeviceChange')<sup>10+</sup> 7588 7589off(type: 'outputDeviceChange', callback?: Callback\<AudioDeviceDescriptors>): void 7590 7591Unsubscribes from audio output device change events. This API uses an asynchronous callback to return the result. 7592 7593**System capability**: SystemCapability.Multimedia.Audio.Device 7594 7595**Parameters** 7596 7597| Name | Type | Mandatory | Description | 7598| :------- | :----------------------------------------------------------- | :-------- | :----------------------------------------------------------- | 7599| type | string | Yes | Event type. The value is fixed at **'outputDeviceChange'**. | 7600| callback | Callback\<[AudioDeviceDescriptors](#audiodevicedescriptors)> | No | Callback used to return the output device descriptor of the current audio stream. | 7601 7602**Error codes** 7603 7604For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7605 7606| ID | Error Message | 7607| ------- | ------------------------------------------------------------ | 7608| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7609| 6800101 | Parameter verification failed. | 7610 7611**Example** 7612 7613```ts 7614audioRenderer.off('outputDeviceChange', (deviceInfo: audio.AudioDeviceDescriptors) => { 7615 console.info(`DeviceInfo id: ${deviceInfo[0].id}`); 7616 console.info(`DeviceInfo name: ${deviceInfo[0].name}`); 7617 console.info(`DeviceInfo address: ${deviceInfo[0].address}`); 7618}); 7619 7620``` 7621 7622### on('outputDeviceChangeWithInfo')<sup>11+</sup> 7623 7624on(type: 'outputDeviceChangeWithInfo', callback: Callback\<AudioStreamDeviceChangeInfo>): void 7625 7626Subscribes to change events of audio output devices and reasons. This API uses an asynchronous callback to return the result. Such an event is triggered when an audio output device changes, and the change reason is reported. 7627 7628**System capability**: SystemCapability.Multimedia.Audio.Device 7629 7630**Parameters** 7631 7632| Name | Type | Mandatory | Description | 7633| :------- | :----------------------------------------------------------- | :-------- | :----------------------------------------------------------- | 7634| type | string | Yes | Event type. The value is fixed at **'outputDeviceChangeWithInfo'**. | 7635| callback | Callback\<[AudioStreamDeviceChangeInfo](#audiostreamdevicechangeinfo11)> | Yes | Callback used to return the output device descriptor of the current audio stream and the change reason. | 7636 7637**Error codes** 7638 7639For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7640 7641| ID | Error Message | 7642| ------- | ------------------------------------------------------------ | 7643| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7644| 6800101 | Parameter verification failed. | 7645 7646**Example** 7647 7648```ts 7649audioRenderer.on('outputDeviceChangeWithInfo', (deviceChangeInfo: audio.AudioStreamDeviceChangeInfo) => { 7650 console.info(`DeviceInfo id: ${deviceChangeInfo.devices[0].id}`); 7651 console.info(`DeviceInfo name: ${deviceChangeInfo.devices[0].name}`); 7652 console.info(`DeviceInfo address: ${deviceChangeInfo.devices[0].address}`); 7653 console.info(`Device change reason: ${deviceChangeInfo.changeReason}`); 7654}); 7655 7656``` 7657 7658### off('outputDeviceChangeWithInfo')<sup>11+</sup> 7659 7660off(type: 'outputDeviceChangeWithInfo', callback?: Callback\<AudioStreamDeviceChangeInfo>): void 7661 7662Unsubscribes from audio output device changes and reasons. This API uses an asynchronous callback to return the result. 7663 7664**System capability**: SystemCapability.Multimedia.Audio.Device 7665 7666**Parameters** 7667 7668| Name | Type | Mandatory | Description | 7669| :------- | :----------------------------------------------------------- | :-------- | :----------------------------------------------------------- | 7670| type | string | Yes | Event type. The value is fixed at **'outputDeviceChangeWithInfo'**. | 7671| callback | Callback\<[AudioStreamDeviceChangeInfo](#audiostreamdevicechangeinfo11)> | No | Callback used to return the output device descriptor of the current audio stream and the change reason. | 7672 7673**Error codes** 7674 7675For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7676 7677| ID | Error Message | 7678| ------- | ------------------------------------------------------------ | 7679| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7680| 6800101 | Parameter verification failed. | 7681 7682**Example** 7683 7684```ts 7685audioRenderer.off('outputDeviceChangeWithInfo', (deviceChangeInfo: audio.AudioStreamDeviceChangeInfo) => { 7686 console.info(`DeviceInfo id: ${deviceChangeInfo.devices[0].id}`); 7687 console.info(`DeviceInfo name: ${deviceChangeInfo.devices[0].name}`); 7688 console.info(`DeviceInfo address: ${deviceChangeInfo.devices[0].address}`); 7689 console.info(`Device change reason: ${deviceChangeInfo.changeReason}`); 7690}); 7691 7692``` 7693 7694### on('writeData')<sup>11+</sup> 7695 7696on(type: 'writeData', callback: AudioRendererWriteDataCallback): void 7697 7698Subscribes to audio data write events. This API uses an asynchronous callback to return the result. Such an event is triggered when audio data needs to be written. 7699 7700**System capability**: SystemCapability.Multimedia.Audio.Renderer 7701 7702**Parameters** 7703 7704| Name | Type | Mandatory | Description | 7705| :------- | :----------------------------------------------------------- | :-------- | :----------------------------------------------------------- | 7706| type | string | Yes | Event type. The value is fixed at **'writeData'**. | 7707| 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). | 7708 7709**Error codes** 7710 7711For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7712 7713| ID | Error Message | 7714| ------- | ------------------------------------------------------------ | 7715| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 7716| 6800101 | Parameter verification failed. | 7717 7718**Example** 7719 7720```ts 7721import { BusinessError } from '@kit.BasicServicesKit'; 7722import {fileIo} from '@kit.CoreFileKit'; 7723 7724class Options { 7725 offset?: number; 7726 length?: number; 7727} 7728 7729let bufferSize: number = 0; 7730let path = getContext().cacheDir; 7731// Ensure that the resource exists in the path. 7732let filePath = path + '/StarWars10s-2C-48000-4SW.wav'; 7733let file: fileIo.File = fileIo.openSync(filePath, fileIo.OpenMode.READ_ONLY); 7734let writeDataCallback = (buffer: ArrayBuffer) => { 7735 let options: Options = { 7736 offset: bufferSize, 7737 length: buffer.byteLength 7738 }; 7739 7740 try { 7741 fileIo.readSync(file.fd, buffer, options); 7742 bufferSize += buffer.byteLength; 7743 // API version 11 does not support the return of the callback result. API version 12 and later support the return of the callback result. 7744 return audio.AudioDataCallbackResult.VALID; 7745 } catch (error) { 7746 console.error('Error reading file:', error); 7747 // API version 11 does not support the return of the callback result. API version 12 and later support the return of the callback result. 7748 return audio.AudioDataCallbackResult.INVALID; 7749 } 7750}; 7751 7752audioRenderer.on('writeData', writeDataCallback); 7753audioRenderer.start().then(() => { 7754 console.info('Renderer started'); 7755}).catch((err: BusinessError) => { 7756 console.error(`ERROR: ${err}`); 7757}); 7758 7759``` 7760 7761### off('writeData')<sup>11+</sup> 7762 7763off(type: 'writeData', callback?: AudioRendererWriteDataCallback): void 7764 7765Unsubscribes from audio data write events. This API uses an asynchronous callback to return the result. 7766 7767**System capability**: SystemCapability.Multimedia.Audio.Renderer 7768 7769**Parameters** 7770 7771| Name | Type | Mandatory | Description | 7772| :------- | :----------------------------------------------------------- | :-------- | :----------------------------------------------------------- | 7773| type | string | Yes | Event type. The value is fixed at **'writeData'**. | 7774| 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). | 7775 7776**Error codes** 7777 7778For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 7779 7780| ID | Error Message | 7781| ------- | ------------------------------------------------------------ | 7782| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 7783| 6800101 | Parameter verification failed. | 7784 7785**Example** 7786 7787```ts 7788audioRenderer.off('writeData', (data: ArrayBuffer) => { 7789 console.info(`write data: ${data}`); 7790}); 7791 7792``` 7793 7794## AudioCapturer<sup>8+</sup> 7795 7796Provides APIs for audio capture. Before calling any API in **AudioCapturer**, you must use [createAudioCapturer](#audiocreateaudiocapturer8) to create an **AudioCapturer** instance. 7797 7798### Attributes 7799 7800**System capability**: SystemCapability.Multimedia.Audio.Capturer 7801 7802| Name | Type | Readable | Writable | Description | 7803| :----------------- | :------------------------- | :------- | :------- | :-------------------- | 7804| state<sup>8+</sup> | [AudioState](#audiostate8) | Yes | No | Audio capturer state. | 7805 7806**Example** 7807 7808```ts 7809import { audio } from '@kit.AudioKit'; 7810 7811let state: audio.AudioState = audioCapturer.state; 7812 7813``` 7814 7815### getCapturerInfo<sup>8+</sup> 7816 7817getCapturerInfo(callback: AsyncCallback<AudioCapturerInfo\>): void 7818 7819Obtains the capturer information of this **AudioCapturer** instance. This API uses an asynchronous callback to return the result. 7820 7821**System capability**: SystemCapability.Multimedia.Audio.Capturer 7822 7823**Parameters** 7824 7825| Name | Type | Mandatory | Description | 7826| :------- | :------------------------------------------------------- | :-------- | :----------------------------------------------------------- | 7827| 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. | 7828 7829**Example** 7830 7831```ts 7832import { BusinessError } from '@kit.BasicServicesKit'; 7833 7834audioCapturer.getCapturerInfo((err: BusinessError, capturerInfo: audio.AudioCapturerInfo) => { 7835 if (err) { 7836 console.error('Failed to get capture info'); 7837 } else { 7838 console.info('Capturer getCapturerInfo:'); 7839 console.info(`Capturer source: ${capturerInfo.source}`); 7840 console.info(`Capturer flags: ${capturerInfo.capturerFlags}`); 7841 } 7842}); 7843 7844``` 7845 7846 7847### getCapturerInfo<sup>8+</sup> 7848 7849getCapturerInfo(): Promise<AudioCapturerInfo\> 7850 7851Obtains the capturer information of this **AudioCapturer** instance. This API uses a promise to return the result. 7852 7853**System capability**: SystemCapability.Multimedia.Audio.Capturer 7854 7855**Return value** 7856 7857| Type | Description | 7858| :------------------------------------------------- | :------------------------------------------- | 7859| Promise<[AudioCapturerInfo](#audiocapturerinfo8)\> | Promise used to return capturer information. | 7860 7861**Example** 7862 7863```ts 7864import { BusinessError } from '@kit.BasicServicesKit'; 7865 7866audioCapturer.getCapturerInfo().then((audioParamsGet: audio.AudioCapturerInfo) => { 7867 if (audioParamsGet != undefined) { 7868 console.info('AudioFrameworkRecLog: Capturer CapturerInfo:'); 7869 console.info(`AudioFrameworkRecLog: Capturer SourceType: ${audioParamsGet.source}`); 7870 console.info(`AudioFrameworkRecLog: Capturer capturerFlags: ${audioParamsGet.capturerFlags}`); 7871 } else { 7872 console.info(`AudioFrameworkRecLog: audioParamsGet is : ${audioParamsGet}`); 7873 console.info('AudioFrameworkRecLog: audioParams getCapturerInfo are incorrect'); 7874 } 7875}).catch((err: BusinessError) => { 7876 console.error(`AudioFrameworkRecLog: CapturerInfo :ERROR: ${err}`); 7877}) 7878 7879``` 7880 7881### getCapturerInfoSync<sup>10+</sup> 7882 7883getCapturerInfoSync(): AudioCapturerInfo 7884 7885Obtains the capturer information of this **AudioCapturer** instance. This API returns the result synchronously. 7886 7887**System capability**: SystemCapability.Multimedia.Audio.Capturer 7888 7889**Return value** 7890 7891| Type | Description | 7892| :--------------------------------------- | :-------------------- | 7893| [AudioCapturerInfo](#audiocapturerinfo8) | Capturer information. | 7894 7895**Example** 7896 7897```ts 7898import { BusinessError } from '@kit.BasicServicesKit'; 7899 7900try { 7901 let audioParamsGet: audio.AudioCapturerInfo = audioCapturer.getCapturerInfoSync(); 7902 console.info(`AudioFrameworkRecLog: Capturer SourceType: ${audioParamsGet.source}`); 7903 console.info(`AudioFrameworkRecLog: Capturer capturerFlags: ${audioParamsGet.capturerFlags}`); 7904} catch (err) { 7905 let error = err as BusinessError; 7906 console.error(`AudioFrameworkRecLog: CapturerInfo :ERROR: ${error}`); 7907} 7908 7909``` 7910 7911### getStreamInfo<sup>8+</sup> 7912 7913getStreamInfo(callback: AsyncCallback<AudioStreamInfo\>): void 7914 7915Obtains the stream information of this **AudioCapturer** instance. This API uses an asynchronous callback to return the result. 7916 7917**System capability**: SystemCapability.Multimedia.Audio.Capturer 7918 7919**Parameters** 7920 7921| Name | Type | Mandatory | Description | 7922| :------- | :--------------------------------------------------- | :-------- | :----------------------------------------------------------- | 7923| 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. | 7924 7925**Example** 7926 7927```ts 7928import { BusinessError } from '@kit.BasicServicesKit'; 7929 7930audioCapturer.getStreamInfo((err: BusinessError, streamInfo: audio.AudioStreamInfo) => { 7931 if (err) { 7932 console.error('Failed to get stream info'); 7933 } else { 7934 console.info('Capturer GetStreamInfo:'); 7935 console.info(`Capturer sampling rate: ${streamInfo.samplingRate}`); 7936 console.info(`Capturer channel: ${streamInfo.channels}`); 7937 console.info(`Capturer format: ${streamInfo.sampleFormat}`); 7938 console.info(`Capturer encoding type: ${streamInfo.encodingType}`); 7939 } 7940}); 7941 7942``` 7943 7944### getStreamInfo<sup>8+</sup> 7945 7946getStreamInfo(): Promise<AudioStreamInfo\> 7947 7948Obtains the stream information of this **AudioCapturer** instance. This API uses a promise to return the result. 7949 7950**System capability**: SystemCapability.Multimedia.Audio.Capturer 7951 7952**Return value** 7953 7954| Type | Description | 7955| :--------------------------------------------- | :--------------------------------------------- | 7956| Promise<[AudioStreamInfo](#audiostreaminfo8)\> | Promise used to return the stream information. | 7957 7958**Example** 7959 7960```ts 7961import { BusinessError } from '@kit.BasicServicesKit'; 7962 7963audioCapturer.getStreamInfo().then((audioParamsGet: audio.AudioStreamInfo) => { 7964 console.info('getStreamInfo:'); 7965 console.info(`sampleFormat: ${audioParamsGet.sampleFormat}`); 7966 console.info(`samplingRate: ${audioParamsGet.samplingRate}`); 7967 console.info(`channels: ${audioParamsGet.channels}`); 7968 console.info(`encodingType: ${audioParamsGet.encodingType}`); 7969}).catch((err: BusinessError) => { 7970 console.error(`getStreamInfo :ERROR: ${err}`); 7971}); 7972 7973``` 7974 7975### getStreamInfoSync<sup>10+</sup> 7976 7977getStreamInfoSync(): AudioStreamInfo 7978 7979Obtains the stream information of this **AudioCapturer** instance. This API returns the result synchronously. 7980 7981**System capability**: SystemCapability.Multimedia.Audio.Capturer 7982 7983**Return value** 7984 7985| Type | Description | 7986| :----------------------------------- | :------------------ | 7987| [AudioStreamInfo](#audiostreaminfo8) | Stream information. | 7988 7989**Example** 7990 7991```ts 7992import { BusinessError } from '@kit.BasicServicesKit'; 7993 7994try { 7995 let audioParamsGet: audio.AudioStreamInfo = audioCapturer.getStreamInfoSync(); 7996 console.info(`sampleFormat: ${audioParamsGet.sampleFormat}`); 7997 console.info(`samplingRate: ${audioParamsGet.samplingRate}`); 7998 console.info(`channels: ${audioParamsGet.channels}`); 7999 console.info(`encodingType: ${audioParamsGet.encodingType}`); 8000} catch (err) { 8001 let error = err as BusinessError; 8002 console.error(`getStreamInfo :ERROR: ${error}`); 8003} 8004 8005``` 8006 8007### getAudioStreamId<sup>9+</sup> 8008 8009getAudioStreamId(callback: AsyncCallback<number\>): void 8010 8011Obtains the stream ID of this **AudioCapturer** instance. This API uses an asynchronous callback to return the result. 8012 8013**System capability**: SystemCapability.Multimedia.Audio.Capturer 8014 8015**Parameters** 8016 8017| Name | Type | Mandatory | Description | 8018| :------- | :--------------------- | :-------- | :----------------------------------------------------------- | 8019| 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. | 8020 8021**Example** 8022 8023```ts 8024import { BusinessError } from '@kit.BasicServicesKit'; 8025 8026audioCapturer.getAudioStreamId((err: BusinessError, streamId: number) => { 8027 console.info(`audioCapturer GetStreamId: ${streamId}`); 8028}); 8029 8030``` 8031 8032### getAudioStreamId<sup>9+</sup> 8033 8034getAudioStreamId(): Promise<number\> 8035 8036Obtains the stream ID of this **AudioCapturer** instance. This API uses a promise to return the result. 8037 8038**System capability**: SystemCapability.Multimedia.Audio.Capturer 8039 8040**Return value** 8041 8042| Type | Description | 8043| :--------------- | :------------------------------------ | 8044| Promise<number\> | Promise used to return the stream ID. | 8045 8046**Example** 8047 8048```ts 8049import { BusinessError } from '@kit.BasicServicesKit'; 8050 8051audioCapturer.getAudioStreamId().then((streamId: number) => { 8052 console.info(`audioCapturer getAudioStreamId: ${streamId}`); 8053}).catch((err: BusinessError) => { 8054 console.error(`ERROR: ${err}`); 8055}); 8056 8057``` 8058 8059### getAudioStreamIdSync<sup>10+</sup> 8060 8061getAudioStreamIdSync(): number 8062 8063Obtains the stream ID of this **AudioCapturer** instance. This API returns the result synchronously. 8064 8065**System capability**: SystemCapability.Multimedia.Audio.Capturer 8066 8067**Return value** 8068 8069| Type | Description | 8070| :----- | :---------- | 8071| number | Stream ID. | 8072 8073**Example** 8074 8075```ts 8076import { BusinessError } from '@kit.BasicServicesKit'; 8077 8078try { 8079 let streamId: number = audioCapturer.getAudioStreamIdSync(); 8080 console.info(`audioCapturer getAudioStreamIdSync: ${streamId}`); 8081} catch (err) { 8082 let error = err as BusinessError; 8083 console.error(`ERROR: ${error}`); 8084} 8085 8086``` 8087 8088### start<sup>8+</sup> 8089 8090start(callback: AsyncCallback<void\>): void 8091 8092Starts capturing. This API uses an asynchronous callback to return the result. 8093 8094**System capability**: SystemCapability.Multimedia.Audio.Capturer 8095 8096**Parameters** 8097 8098| Name | Type | Mandatory | Description | 8099| :------- | :------------------- | :-------- | :----------------------------------------------------------- | 8100| 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. | 8101 8102**Example** 8103 8104```ts 8105import { BusinessError } from '@kit.BasicServicesKit'; 8106 8107audioCapturer.start((err: BusinessError) => { 8108 if (err) { 8109 console.error('Capturer start failed.'); 8110 } else { 8111 console.info('Capturer start success.'); 8112 } 8113}); 8114 8115``` 8116 8117 8118### start<sup>8+</sup> 8119 8120start(): Promise<void\> 8121 8122Starts capturing. This API uses a promise to return the result. 8123 8124**System capability**: SystemCapability.Multimedia.Audio.Capturer 8125 8126**Return value** 8127 8128| Type | Description | 8129| :------------- | :----------------------------------------------------------- | 8130| 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. | 8131 8132**Example** 8133 8134```ts 8135import { BusinessError } from '@kit.BasicServicesKit'; 8136 8137audioCapturer.start().then(() => { 8138 console.info('AudioFrameworkRecLog: ---------START---------'); 8139 console.info('AudioFrameworkRecLog: Capturer started: SUCCESS'); 8140 console.info(`AudioFrameworkRecLog: AudioCapturer: STATE: ${audioCapturer.state}`); 8141 console.info('AudioFrameworkRecLog: Capturer started: SUCCESS'); 8142 if ((audioCapturer.state == audio.AudioState.STATE_RUNNING)) { 8143 console.info('AudioFrameworkRecLog: AudioCapturer is in Running State'); 8144 } 8145}).catch((err: BusinessError) => { 8146 console.error(`AudioFrameworkRecLog: Capturer start :ERROR : ${err}`); 8147}); 8148 8149``` 8150 8151### stop<sup>8+</sup> 8152 8153stop(callback: AsyncCallback<void\>): void 8154 8155Stops capturing. This API uses an asynchronous callback to return the result. 8156 8157**System capability**: SystemCapability.Multimedia.Audio.Capturer 8158 8159**Parameters** 8160 8161| Name | Type | Mandatory | Description | 8162| :------- | :------------------- | :-------- | :----------------------------------------------------------- | 8163| callback | AsyncCallback<void\> | Yes | Callback used to return the result. If the vibration stops, **err** is **undefined**; otherwise, **err** is an error object. | 8164 8165**Example** 8166 8167```ts 8168import { BusinessError } from '@kit.BasicServicesKit'; 8169 8170audioCapturer.stop((err: BusinessError) => { 8171 if (err) { 8172 console.error('Capturer stop failed'); 8173 } else { 8174 console.info('Capturer stopped.'); 8175 } 8176}); 8177 8178``` 8179 8180 8181### stop<sup>8+</sup> 8182 8183stop(): Promise<void\> 8184 8185Stops capturing. This API uses a promise to return the result. 8186 8187**System capability**: SystemCapability.Multimedia.Audio.Capturer 8188 8189**Return value** 8190 8191| Type | Description | 8192| :------------- | :----------------------------- | 8193| Promise<void\> | Promise that returns no value. | 8194 8195**Example** 8196 8197```ts 8198import { BusinessError } from '@kit.BasicServicesKit'; 8199 8200audioCapturer.stop().then(() => { 8201 console.info('AudioFrameworkRecLog: ---------STOP RECORD---------'); 8202 console.info('AudioFrameworkRecLog: Capturer stopped: SUCCESS'); 8203 if ((audioCapturer.state == audio.AudioState.STATE_STOPPED)){ 8204 console.info('AudioFrameworkRecLog: State is Stopped:'); 8205 } 8206}).catch((err: BusinessError) => { 8207 console.error(`AudioFrameworkRecLog: Capturer stop: ERROR: ${err}`); 8208}); 8209 8210``` 8211 8212### release<sup>8+</sup> 8213 8214release(callback: AsyncCallback<void\>): void 8215 8216Releases this **AudioCapturer** instance. This API uses an asynchronous callback to return the result. 8217 8218**System capability**: SystemCapability.Multimedia.Audio.Capturer 8219 8220**Parameters** 8221 8222| Name | Type | Mandatory | Description | 8223| :------- | :------------------- | :-------- | :----------------------------------------------------------- | 8224| callback | AsyncCallback<void\> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object. | 8225 8226**Example** 8227 8228```ts 8229import { BusinessError } from '@kit.BasicServicesKit'; 8230 8231audioCapturer.release((err: BusinessError) => { 8232 if (err) { 8233 console.error('capturer release failed'); 8234 } else { 8235 console.info('capturer released.'); 8236 } 8237}); 8238 8239``` 8240 8241 8242### release<sup>8+</sup> 8243 8244release(): Promise<void\> 8245 8246Releases this **AudioCapturer** instance. This API uses a promise to return the result. 8247 8248**System capability**: SystemCapability.Multimedia.Audio.Capturer 8249 8250**Return value** 8251 8252| Type | Description | 8253| :------------- | :----------------------------- | 8254| Promise<void\> | Promise that returns no value. | 8255 8256**Example** 8257 8258```ts 8259import { BusinessError } from '@kit.BasicServicesKit'; 8260 8261audioCapturer.release().then(() => { 8262 console.info('AudioFrameworkRecLog: ---------RELEASE RECORD---------'); 8263 console.info('AudioFrameworkRecLog: Capturer release : SUCCESS'); 8264 console.info(`AudioFrameworkRecLog: AudioCapturer : STATE : ${audioCapturer.state}`); 8265}).catch((err: BusinessError) => { 8266 console.error(`AudioFrameworkRecLog: Capturer stop: ERROR: ${err}`); 8267}); 8268 8269``` 8270 8271### read<sup>8+(deprecated)</sup> 8272 8273read(size: number, isBlockingRead: boolean, callback: AsyncCallback<ArrayBuffer\>): void 8274 8275Reads the buffer. This API uses an asynchronous callback to return the result. 8276 8277> **NOTE** 8278> 8279> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [on('readData')](#onreaddata11) in **AudioCapturer**. 8280 8281**System capability**: SystemCapability.Multimedia.Audio.Capturer 8282 8283**Parameters** 8284 8285| Name | Type | Mandatory | Description | 8286| :------------- | :-------------------------- | :-------- | :----------------------------------------------------------- | 8287| size | number | Yes | Number of bytes to read. | 8288| isBlockingRead | boolean | Yes | Whether to block the read operation. The value **true** means to block the read operation, and **false** means the opposite. | 8289| 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. | 8290 8291**Example** 8292 8293```ts 8294import { BusinessError } from '@kit.BasicServicesKit'; 8295 8296let bufferSize: number = 0; 8297audioCapturer.getBufferSize().then((data: number) => { 8298 console.info(`AudioFrameworkRecLog: getBufferSize: SUCCESS ${data}`); 8299 bufferSize = data; 8300}).catch((err: BusinessError) => { 8301 console.error(`AudioFrameworkRecLog: getBufferSize: ERROR: ${err}`); 8302}); 8303audioCapturer.read(bufferSize, true, (err: BusinessError, buffer: ArrayBuffer) => { 8304 if (!err) { 8305 console.info('Success in reading the buffer data'); 8306 } 8307}); 8308 8309``` 8310 8311### read<sup>8+(deprecated)</sup> 8312 8313read(size: number, isBlockingRead: boolean): Promise<ArrayBuffer\> 8314 8315Reads the buffer. This API uses a promise to return the result. 8316 8317> **NOTE** 8318> 8319> This API is supported since API version 8 and deprecated since API version 11. You are advised to use [on('readData')](#onreaddata11) in **AudioCapturer**. 8320 8321**System capability**: SystemCapability.Multimedia.Audio.Capturer 8322 8323**Parameters** 8324 8325| Name | Type | Mandatory | Description | 8326| :------------- | :------ | :-------- | :----------------------------------------------------------- | 8327| size | number | Yes | Number of bytes to read. | 8328| isBlockingRead | boolean | Yes | Whether to block the read operation. The value **true** means to block the read operation, and **false** means the opposite. | 8329 8330**Return value** 8331 8332| Type | Description | 8333| :-------------------- | :---------------------------------------------------- | 8334| Promise<ArrayBuffer\> | Promise used to return the data read from the buffer. | 8335 8336**Example** 8337 8338```ts 8339import { BusinessError } from '@kit.BasicServicesKit'; 8340 8341let bufferSize: number = 0; 8342audioCapturer.getBufferSize().then((data: number) => { 8343 console.info(`AudioFrameworkRecLog: getBufferSize: SUCCESS ${data}`); 8344 bufferSize = data; 8345}).catch((err: BusinessError) => { 8346 console.error(`AudioFrameworkRecLog: getBufferSize: ERROR ${err}`); 8347}); 8348console.info(`Buffer size: ${bufferSize}`); 8349audioCapturer.read(bufferSize, true).then((buffer: ArrayBuffer) => { 8350 console.info('buffer read successfully'); 8351}).catch((err: BusinessError) => { 8352 console.error(`ERROR : ${err}`); 8353}); 8354 8355``` 8356 8357### getAudioTime<sup>8+</sup> 8358 8359getAudioTime(callback: AsyncCallback<number\>): void 8360 8361Obtains the number of nanoseconds elapsed from the Unix epoch (January 1, 1970). This API uses an asynchronous callback to return the result. 8362 8363**System capability**: SystemCapability.Multimedia.Audio.Capturer 8364 8365**Parameters** 8366 8367| Name | Type | Mandatory | Description | 8368| :------- | :--------------------- | :-------- | :----------------------------------------------------------- | 8369| 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. | 8370 8371**Example** 8372 8373```ts 8374import { BusinessError } from '@kit.BasicServicesKit'; 8375 8376audioCapturer.getAudioTime((err: BusinessError, timestamp: number) => { 8377 console.info(`Current timestamp: ${timestamp}`); 8378}); 8379 8380``` 8381 8382### getAudioTime<sup>8+</sup> 8383 8384getAudioTime(): Promise<number\> 8385 8386Obtains the number of nanoseconds elapsed from the Unix epoch (January 1, 1970). This API uses a promise to return the result. 8387 8388**System capability**: SystemCapability.Multimedia.Audio.Capturer 8389 8390**Return value** 8391 8392| Type | Description | 8393| :--------------- | :----------------------------------------------------------- | 8394| Promise<number\> | Promise used to return the number of nanoseconds elapsed from the Unix epoch. | 8395 8396**Example** 8397 8398```ts 8399import { BusinessError } from '@kit.BasicServicesKit'; 8400 8401audioCapturer.getAudioTime().then((audioTime: number) => { 8402 console.info(`AudioFrameworkRecLog: AudioCapturer getAudioTime : Success ${audioTime}`); 8403}).catch((err: BusinessError) => { 8404 console.error(`AudioFrameworkRecLog: AudioCapturer Created : ERROR : ${err}`); 8405}); 8406 8407``` 8408 8409### getAudioTimeSync<sup>10+</sup> 8410 8411getAudioTimeSync(): number 8412 8413Obtains the number of nanoseconds elapsed from the Unix epoch (January 1, 1970). This API returns the result synchronously. 8414 8415**System capability**: SystemCapability.Multimedia.Audio.Capturer 8416 8417**Return value** 8418 8419| Type | Description | 8420| :----- | :---------- | 8421| number | Timestamp. | 8422 8423**Example** 8424 8425```ts 8426import { BusinessError } from '@kit.BasicServicesKit'; 8427 8428try { 8429 let audioTime: number = audioCapturer.getAudioTimeSync(); 8430 console.info(`AudioFrameworkRecLog: AudioCapturer getAudioTimeSync : Success ${audioTime}`); 8431} catch (err) { 8432 let error = err as BusinessError; 8433 console.error(`AudioFrameworkRecLog: AudioCapturer getAudioTimeSync : ERROR : ${error}`); 8434} 8435 8436``` 8437 8438### getBufferSize<sup>8+</sup> 8439 8440getBufferSize(callback: AsyncCallback<number\>): void 8441 8442Obtains a reasonable minimum buffer size in bytes for capturing. This API uses an asynchronous callback to return the result. 8443 8444**System capability**: SystemCapability.Multimedia.Audio.Capturer 8445 8446**Parameters** 8447 8448| Name | Type | Mandatory | Description | 8449| :------- | :--------------------- | :-------- | :----------------------------------------------------------- | 8450| 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. | 8451 8452**Example** 8453 8454```ts 8455import { BusinessError } from '@kit.BasicServicesKit'; 8456 8457audioCapturer.getBufferSize((err: BusinessError, bufferSize: number) => { 8458 if (!err) { 8459 console.info(`BufferSize : ${bufferSize}`); 8460 audioCapturer.read(bufferSize, true).then((buffer: ArrayBuffer) => { 8461 console.info(`Buffer read is ${buffer.byteLength}`); 8462 }).catch((err: BusinessError) => { 8463 console.error(`AudioFrameworkRecLog: AudioCapturer Created : ERROR : ${err}`); 8464 }); 8465 } 8466}); 8467 8468``` 8469 8470### getBufferSize<sup>8+</sup> 8471 8472getBufferSize(): Promise<number\> 8473 8474Obtains a reasonable minimum buffer size in bytes for capturing. This API uses a promise to return the result. 8475 8476**System capability**: SystemCapability.Multimedia.Audio.Capturer 8477 8478**Return value** 8479 8480| Type | Description | 8481| :--------------- | :-------------------------------------- | 8482| Promise<number\> | Promise used to return the buffer size. | 8483 8484**Example** 8485 8486```ts 8487import { BusinessError } from '@kit.BasicServicesKit'; 8488 8489let bufferSize: number = 0; 8490audioCapturer.getBufferSize().then((data: number) => { 8491 console.info(`AudioFrameworkRecLog: getBufferSize :SUCCESS ${data}`); 8492 bufferSize = data; 8493}).catch((err: BusinessError) => { 8494 console.error(`AudioFrameworkRecLog: getBufferSize :ERROR : ${err}`); 8495}); 8496 8497``` 8498 8499### getBufferSizeSync<sup>10+</sup> 8500 8501getBufferSizeSync(): number 8502 8503Obtains a reasonable minimum buffer size in bytes for capturing. This API returns the result synchronously. 8504 8505**System capability**: SystemCapability.Multimedia.Audio.Capturer 8506 8507**Return value** 8508 8509| Type | Description | 8510| :----- | :----------- | 8511| number | Buffer size. | 8512 8513**Example** 8514 8515```ts 8516import { BusinessError } from '@kit.BasicServicesKit'; 8517 8518let bufferSize: number = 0; 8519try { 8520 bufferSize = audioCapturer.getBufferSizeSync(); 8521 console.info(`AudioFrameworkRecLog: getBufferSizeSync :SUCCESS ${bufferSize}`); 8522} catch (err) { 8523 let error = err as BusinessError; 8524 console.error(`AudioFrameworkRecLog: getBufferSizeSync :ERROR : ${error}`); 8525} 8526 8527``` 8528 8529### getCurrentInputDevices<sup>11+</sup> 8530 8531getCurrentInputDevices(): AudioDeviceDescriptors 8532 8533Obtains the descriptors of the current input devices. This API returns the result synchronously. 8534 8535**System capability**: SystemCapability.Multimedia.Audio.Device 8536 8537**Return value** 8538 8539| Type | Description | 8540| ------------------------------------------------- | ----------------------------------------- | 8541| [AudioDeviceDescriptors](#audiodevicedescriptors) | An array of the audio device descriptors. | 8542 8543**Example** 8544 8545```ts 8546let deviceDescriptors: audio.AudioDeviceDescriptors = audioCapturer.getCurrentInputDevices(); 8547console.info(`Device id: ${deviceDescriptors[0].id}`); 8548console.info(`Device type: ${deviceDescriptors[0].deviceType}`); 8549console.info(`Device role: ${deviceDescriptors[0].deviceRole}`); 8550console.info(`Device name: ${deviceDescriptors[0].name}`); 8551console.info(`Device address: ${deviceDescriptors[0].address}`); 8552console.info(`Device samplerates: ${deviceDescriptors[0].sampleRates[0]}`); 8553console.info(`Device channelcounts: ${deviceDescriptors[0].channelCounts[0]}`); 8554console.info(`Device channelmask: ${deviceDescriptors[0].channelMasks[0]}`); 8555if (deviceDescriptors[0].encodingTypes) { 8556 console.info(`Device encodingTypes: ${deviceDescriptors[0].encodingTypes[0]}`); 8557} 8558 8559``` 8560 8561### getCurrentAudioCapturerChangeInfo<sup>11+</sup> 8562 8563getCurrentAudioCapturerChangeInfo(): AudioCapturerChangeInfo 8564 8565Obtains the configuration changes of the current audio capturer. This API returns the result synchronously. 8566 8567**System capability**: SystemCapability.Multimedia.Audio.Device 8568 8569**Return value** 8570 8571| Type | Description | 8572| :--------------------------------------------------- | :------------------------------------------- | 8573| [AudioCapturerChangeInfo](#audiocapturerchangeinfo9) | Configuration changes of the audio capturer. | 8574 8575**Example** 8576 8577```ts 8578let info: audio.AudioCapturerChangeInfo = audioCapturer.getCurrentAudioCapturerChangeInfo(); 8579console.info(`Info streamId: ${info.streamId}`); 8580console.info(`Info source: ${info.capturerInfo.source}`); 8581console.info(`Info capturerFlags: ${info.capturerInfo.capturerFlags}`); 8582console.info(`Info muted: ${info.muted}`); 8583console.info(`Info type: ${info.deviceDescriptors[0].deviceType}`); 8584console.info(`Info role: ${info.deviceDescriptors[0].deviceRole}`); 8585console.info(`Info name: ${info.deviceDescriptors[0].name}`); 8586console.info(`Info address: ${info.deviceDescriptors[0].address}`); 8587console.info(`Info samplerates: ${info.deviceDescriptors[0].sampleRates[0]}`); 8588console.info(`Info channelcounts: ${info.deviceDescriptors[0].channelCounts[0]}`); 8589console.info(`Info channelmask: ${info.deviceDescriptors[0].channelMasks[0]}`); 8590if (info.deviceDescriptors[0].encodingTypes) { 8591 console.info(`Device encodingTypes: ${info.deviceDescriptors[0].encodingTypes[0]}`); 8592} 8593 8594``` 8595 8596### on('audioInterrupt')<sup>10+</sup> 8597 8598on(type: 'audioInterrupt', callback: Callback\<InterruptEvent>): void 8599 8600Subscribes to audio interruption events. This API uses an asynchronous callback to return the result. Such an event is triggered when the audio focus is changed. 8601 8602The **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. 8603 8604After 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 [Processing Audio Interruption Events](../../media/audio/audio-playback-concurrency.md). 8605 8606**System capability**: SystemCapability.Multimedia.Audio.Interrupt 8607 8608**Parameters** 8609 8610| Name | Type | Mandatory | Description | 8611| -------- | ---------------------------------------------- | --------- | ------------------------------------------------------------ | 8612| type | string | Yes | Event type. The value is fixed at **'audioInterrupt'**. | 8613| callback | Callback\<[InterruptEvent](#interruptevent9)\> | Yes | Callback used to return the audio interruption event received by the application when playback is interrupted. | 8614 8615**Error codes** 8616 8617For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 8618 8619| ID | Error Message | 8620| ------- | ------------------------------------------------------------ | 8621| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 8622| 6800101 | Parameter verification failed. | 8623 8624**Example** 8625 8626```ts 8627import { audio } from '@kit.AudioKit'; 8628 8629let isCapturing: boolean; // An identifier specifying whether capturing is in progress. 8630onAudioInterrupt(); 8631 8632async function onAudioInterrupt(){ 8633 audioCapturer.on('audioInterrupt', (interruptEvent: audio.InterruptEvent) => { 8634 // When an audio interruption event occurs, the AudioCapturer receives the interruptEvent callback and performs processing based on the content in the callback. 8635 // 1. (Optional) The AudioCapturer reads the value of interruptEvent.forceType to see whether the system has forcibly performed the operation. 8636 // 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. 8637 // 2. (Mandatory) The AudioCapturer then reads the value of interruptEvent.hintType and performs corresponding processing. 8638 if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_FORCE) { 8639 // The audio focus event has been forcibly executed by the system. The application needs to update its status and displayed content. 8640 switch (interruptEvent.hintType) { 8641 case audio.InterruptHint.INTERRUPT_HINT_PAUSE: 8642 // 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. 8643 console.info('Force paused. Update capturing status and stop reading'); 8644 isCapturing = false; // A simplified processing indicating several operations for switching the application to the paused state. 8645 break; 8646 case audio.InterruptHint.INTERRUPT_HINT_STOP: 8647 // The audio stream has been stopped and permanently loses the focus. The user must manually trigger the operation to resume capturing. 8648 console.info('Force stopped. Update capturing status and stop reading'); 8649 isCapturing = false; // A simplified processing indicating several operations for switching the application to the paused state. 8650 break; 8651 default: 8652 console.info('Invalid interruptEvent'); 8653 break; 8654 } 8655 } else if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_SHARE) { 8656 // 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. 8657 switch (interruptEvent.hintType) { 8658 case audio.InterruptHint.INTERRUPT_HINT_RESUME: 8659 // 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.) 8660 // 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. 8661 console.info('Resume force paused renderer or ignore'); 8662 // To continue capturing, the application must perform the required operations. 8663 break; 8664 default: 8665 console.info('Invalid interruptEvent'); 8666 break; 8667 } 8668 } 8669 }); 8670} 8671 8672``` 8673 8674### off('audioInterrupt')<sup>10+</sup> 8675 8676off(type: 'audioInterrupt'): void 8677 8678Unsubscribes from audio interruption events. 8679 8680**System capability**: SystemCapability.Multimedia.Audio.Interrupt 8681 8682**Parameters** 8683 8684| Name | Type | Mandatory | Description | 8685| ---- | ------ | --------- | ------------------------------------------------------- | 8686| type | string | Yes | Event type. The value is fixed at **'audioInterrupt'**. | 8687 8688**Error codes** 8689 8690For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 8691 8692| ID | Error Message | 8693| ------- | ------------------------------------------------------------ | 8694| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 8695| 6800101 | Parameter verification failed. | 8696 8697**Example** 8698 8699```ts 8700audioCapturer.off('audioInterrupt'); 8701 8702``` 8703 8704### on('inputDeviceChange')<sup>11+</sup> 8705 8706on(type: 'inputDeviceChange', callback: Callback\<AudioDeviceDescriptors>): void 8707 8708Subscribes to audio input device change events. This API uses an asynchronous callback to return the result. Such an event is triggered when an audio input device is changed. 8709 8710**System capability**: SystemCapability.Multimedia.Audio.Device 8711 8712**Parameters** 8713 8714| Name | Type | Mandatory | Description | 8715| :------- | :----------------------------------------------------------- | :-------- | :----------------------------------------------------------- | 8716| type | string | Yes | Event type. The value is fixed at **'inputDeviceChange**. | 8717| callback | Callback\<[AudioDeviceDescriptors](#audiodevicedescriptors)> | Yes | Callback used to return the information about the new audio input device. | 8718 8719**Error codes** 8720 8721For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 8722 8723| ID | Error Message | 8724| ------- | ------------------------------------------------------------ | 8725| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 8726| 6800101 | Parameter verification failed. | 8727 8728**Example** 8729 8730```ts 8731audioCapturer.on('inputDeviceChange', (deviceChangeInfo: audio.AudioDeviceDescriptors) => { 8732 console.info(`inputDevice id: ${deviceChangeInfo[0].id}`); 8733 console.info(`inputDevice deviceRole: ${deviceChangeInfo[0].deviceRole}`); 8734 console.info(`inputDevice deviceType: ${deviceChangeInfo[0].deviceType}`); 8735}); 8736 8737``` 8738 8739### off('inputDeviceChange')<sup>11+</sup> 8740 8741off(type: 'inputDeviceChange', callback?: Callback\<AudioDeviceDescriptors>): void 8742 8743Unsubscribes from audio input device change events. This API uses an asynchronous callback to return the result. 8744 8745**System capability**: SystemCapability.Multimedia.Audio.Device 8746 8747**Parameters** 8748 8749| Name | Type | Mandatory | Description | 8750| :------- | :----------------------------------------------------------- | :-------- | :----------------------------------------------------------- | 8751| type | string | Yes | Event type. The value is fixed at **'inputDeviceChange'**. | 8752| callback | Callback\<[AudioDeviceDescriptors](#audiodevicedescriptors)> | No | Callback used to return the information about the audio input device. | 8753 8754**Error codes** 8755 8756For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 8757 8758| ID | Error Message | 8759| ------- | ------------------------------------------------------------ | 8760| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 8761| 6800101 | Parameter verification failed. | 8762 8763**Example** 8764 8765```ts 8766audioCapturer.off('inputDeviceChange'); 8767 8768``` 8769 8770### on('audioCapturerChange')<sup>11+</sup> 8771 8772on(type: 'audioCapturerChange', callback: Callback\<AudioCapturerChangeInfo>): void 8773 8774Subscribes to audio capturer configuration change events. This API uses an asynchronous callback to return the result. Such an event is triggered when the audio recording stream status or device is changed. The subscription is implemented asynchronously and the callback, which is triggered when the audio capturer configuration changes, may fail to reflect the actual condition. 8775 8776**System capability**: SystemCapability.Multimedia.Audio.Capturer 8777 8778**Parameters** 8779 8780| Name | Type | Mandatory | Description | 8781| :------- | :----------------------------------------------------------- | :-------- | :----------------------------------------------------------- | 8782| type | string | Yes | Event type. The value is fixed at **'audioCapturerChange'**. | 8783| callback | Callback\<[AudioCapturerChangeInfo](#audiocapturerchangeinfo9)> | Yes | Callback used to return the current configuration and status information of the audio capturer. | 8784 8785**Error codes** 8786 8787For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 8788 8789| ID | Error Message | 8790| ------- | ------------------------------------------------------------ | 8791| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 8792| 6800101 | Parameter verification failed. | 8793 8794**Example** 8795 8796```ts 8797audioCapturer.on('audioCapturerChange', (capturerChangeInfo: audio.AudioCapturerChangeInfo) => { 8798 console.info(`audioCapturerChange id: ${capturerChangeInfo[0].id}`); 8799 console.info(`audioCapturerChange deviceRole: ${capturerChangeInfo[0].deviceRole}`); 8800 console.info(`audioCapturerChange deviceType: ${capturerChangeInfo[0].deviceType}`); 8801}); 8802 8803``` 8804 8805### off('audioCapturerChange')<sup>11+</sup> 8806 8807off(type: 'audioCapturerChange', callback?: Callback\<AudioCapturerChangeInfo>): void 8808 8809Unsubscribes from audio capturer configuration change events. This API uses an asynchronous callback to return the result. 8810 8811**System capability**: SystemCapability.Multimedia.Audio.Capturer 8812 8813**Parameters** 8814 8815| Name | Type | Mandatory | Description | 8816| :------- | :----------------------------------------------------------- | :-------- | :----------------------------------------------------------- | 8817| type | string | Yes | Event type. The value is fixed at **'audioCapturerChange'**. | 8818| callback | Callback\<[AudioCapturerChangeInfo](#audiocapturerchangeinfo9)> | No | Callback used for unsubscription. | 8819 8820**Error codes** 8821 8822For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 8823 8824| ID | Error Message | 8825| ------- | ------------------------------------------------------------ | 8826| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 8827| 6800101 | Parameter verification failed. | 8828 8829**Example** 8830 8831```ts 8832audioCapturer.off('audioCapturerChange'); 8833 8834``` 8835 8836### on('markReach')<sup>8+</sup> 8837 8838on(type: 'markReach', frame: number, callback: Callback<number>): void 8839 8840Subscribes to mark reached events. This API uses an asynchronous callback to return the result. Such an event is triggered (only once) when the number of frames captured reaches the value of the **frame** parameter. 8841 8842For example, if **frame** is set to **100**, the callback is invoked when the number of captured frames reaches the 100th frame. 8843 8844**System capability**: SystemCapability.Multimedia.Audio.Capturer 8845 8846**Parameters** 8847 8848| Name | Type | Mandatory | Description | 8849| :------- | :---------------- | :-------- | :----------------------------------------------------------- | 8850| type | string | Yes | Event type. The value is fixed at **'markReach'**. | 8851| frame | number | Yes | Number of frames to trigger the event. The value must be greater than **0**. | 8852| callback | Callback\<number> | Yes | Callback used to return the value of the **frame** parameter. | 8853 8854**Example** 8855 8856```ts 8857audioCapturer.on('markReach', 1000, (position: number) => { 8858 if (position == 1000) { 8859 console.info('ON Triggered successfully'); 8860 } 8861}); 8862 8863``` 8864 8865### off('markReach')<sup>8+</sup> 8866 8867off(type: 'markReach'): void 8868 8869Unsubscribes from mark reached events. 8870 8871**System capability**: SystemCapability.Multimedia.Audio.Capturer 8872 8873**Parameters** 8874 8875| Name | Type | Mandatory | Description | 8876| :--- | :----- | :-------- | :------------------------------------------------- | 8877| type | string | Yes | Event type. The value is fixed at **'markReach'**. | 8878 8879**Example** 8880 8881```ts 8882audioCapturer.off('markReach'); 8883 8884``` 8885 8886### on('periodReach')<sup>8+</sup> 8887 8888on(type: 'periodReach', frame: number, callback: Callback<number>): void 8889 8890Subscribes to period reached events. This API uses an asynchronous callback to return the result. Such an event is triggered each time the number of frames captured reaches the value of the **frame** parameter. In other words, the information is reported periodically. 8891 8892For 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. 8893 8894**System capability**: SystemCapability.Multimedia.Audio.Capturer 8895 8896**Parameters** 8897 8898| Name | Type | Mandatory | Description | 8899| :------- | :---------------- | :-------- | :----------------------------------------------------------- | 8900| type | string | Yes | Event type. The value is fixed at **'periodReach'**. | 8901| frame | number | Yes | Number of frames to trigger the event. The value must be greater than **0**. | 8902| callback | Callback\<number> | Yes | Callback used to return the value of the **frame** parameter. | 8903 8904**Example** 8905 8906```ts 8907audioCapturer.on('periodReach', 1000, (position: number) => { 8908 if (position == 1000) { 8909 console.info('ON Triggered successfully'); 8910 } 8911}); 8912 8913``` 8914 8915### off('periodReach')<sup>8+</sup> 8916 8917off(type: 'periodReach'): void 8918 8919Unsubscribes from period reached events. 8920 8921**System capability**: SystemCapability.Multimedia.Audio.Capturer 8922 8923**Parameters** 8924 8925| Name | Type | Mandatory | Description | 8926| :--- | :----- | :-------- | :--------------------------------------------------- | 8927| type | string | Yes | Event type. The value is fixed at **'periodReach'**. | 8928 8929**Example** 8930 8931```ts 8932audioCapturer.off('periodReach'); 8933 8934``` 8935 8936### on('stateChange')<sup>8+</sup> 8937 8938on(type: 'stateChange', callback: Callback<AudioState\>): void 8939 8940Subscribes to audio capturer state change events. This API uses an asynchronous callback to return the result. Such an event is triggered when the state of the audio capturer is changed. 8941 8942**System capability**: SystemCapability.Multimedia.Audio.Capturer 8943 8944**Parameters** 8945 8946| Name | Type | Mandatory | Description | 8947| :------- | :------------------------------------ | :-------- | :--------------------------------------------------- | 8948| type | string | Yes | Event type. The value is fixed at **'stateChange'**. | 8949| callback | Callback\<[AudioState](#audiostate8)> | Yes | Callback used to return the audio status. | 8950 8951**Example** 8952 8953```ts 8954audioCapturer.on('stateChange', (state: audio.AudioState) => { 8955 if (state == 1) { 8956 console.info('audio capturer state is: STATE_PREPARED'); 8957 } 8958 if (state == 2) { 8959 console.info('audio capturer state is: STATE_RUNNING'); 8960 } 8961}); 8962 8963``` 8964 8965### on('readData')<sup>11+</sup> 8966 8967on(type: 'readData', callback: Callback\<ArrayBuffer>): void 8968 8969Subscribes to audio data read events. This API uses an asynchronous callback to return the result. Such an event is triggered when audio stream data needs to be read. 8970 8971**System capability**: SystemCapability.Multimedia.Audio.Capturer 8972 8973**Parameters** 8974 8975| Name | Type | Mandatory | Description | 8976| :------- | :--------------------- | :-------- | :----------------------------------------------------------- | 8977| type | string | Yes | Event type. The value is fixed at **'readData'**. | 8978| callback | Callback\<ArrayBuffer> | Yes | Callback used to return the buffer from which the data is read. | 8979 8980**Error codes** 8981 8982For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 8983 8984| ID | Error Message | 8985| ------- | ------------------------------------------------------------ | 8986| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 8987| 6800101 | Parameter verification failed. | 8988 8989**Example** 8990 8991```ts 8992import { BusinessError } from '@kit.BasicServicesKit'; 8993import { fileIo } from '@kit.CoreFileKit'; 8994 8995class Options { 8996 offset?: number; 8997 length?: number; 8998} 8999 9000let bufferSize: number = 0; 9001let path = getContext().cacheDir; 9002// Ensure that the resource exists in the sandbox path. 9003let filePath = path + '/StarWars10s-2C-48000-4SW.wav'; 9004let file: fileIo.File = fileIo.openSync(filePath, fileIo.OpenMode.READ_WRITE); 9005let readDataCallback = (buffer: ArrayBuffer) => { 9006 let options: Options = { 9007 offset: bufferSize, 9008 length: buffer.byteLength 9009 } 9010 fileIo.writeSync(file.fd, buffer, options); 9011 bufferSize += buffer.byteLength; 9012} 9013audioCapturer.on('readData', readDataCallback); 9014audioCapturer.start((err: BusinessError) => { 9015 if (err) { 9016 console.error('Capturer start failed.'); 9017 } else { 9018 console.info('Capturer start success.'); 9019 } 9020}); 9021 9022``` 9023 9024### off('readData')<sup>11+</sup> 9025 9026off(type: 'readData', callback?: Callback\<ArrayBuffer>): void 9027 9028Unsubscribes from audio data read events. This API uses an asynchronous callback to return the result. 9029 9030**System capability**: SystemCapability.Multimedia.Audio.Capturer 9031 9032**Parameters** 9033 9034| Name | Type | Mandatory | Description | 9035| :------- | :--------------------- | :-------- | :----------------------------------------------------------- | 9036| type | string | Yes | Event type. The value is fixed at **'readData'**. | 9037| callback | Callback\<ArrayBuffer> | No | Callback used to return the buffer from which the data is read. | 9038 9039**Error codes** 9040 9041For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 9042 9043| ID | Error Message | 9044| ------- | ------------------------------------------------------------ | 9045| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 9046| 6800101 | Parameter verification failed. | 9047 9048**Example** 9049 9050```ts 9051audioCapturer.off('readData', (data: ArrayBuffer) => { 9052 console.info(`read data: ${data}`); 9053}); 9054 9055``` 9056 9057### getOverflowCount<sup>12+</sup> 9058 9059getOverflowCount(): Promise<number> 9060 9061Obtains the number of overflow audio frames in the audio stream that is being captured. This API uses a promise to return the result. 9062 9063**System capability**: SystemCapability.Multimedia.Audio.Capturer 9064 9065**Return value** 9066 9067| Type | Description | 9068| --------------------- | ----------------------------------------------------------- | 9069| Promise<number> | Promise used to return the number of overflow audio frames. | 9070 9071**Example** 9072 9073```ts 9074import { BusinessError } from '@kit.BasicServicesKit'; 9075 9076audioCapturer.getOverflowCount().then((value: number) => { 9077 console.info(`Get overflow count Success! ${value}`); 9078}).catch((err: BusinessError) => { 9079 console.error(`Get overflow count Fail: ${err}`); 9080}); 9081 9082``` 9083 9084### getOverflowCountSync<sup>12+</sup> 9085 9086getOverflowCountSync(): number 9087 9088Obtains the number of overflow audio frames in the audio stream that is being captured. This API returns the result synchronously. 9089 9090**System capability**: SystemCapability.Multimedia.Audio.Capturer 9091 9092**Return value** 9093 9094| Type | Description | 9095| ------ | -------------------------------- | 9096| number | Number of overflow audio frames. | 9097 9098**Example** 9099 9100```ts 9101import { BusinessError } from '@kit.BasicServicesKit'; 9102 9103try { 9104 let value: number = audioCapturer.getOverflowCountSync(); 9105 console.info(`Get overflow count Success! ${value}`); 9106} catch (err) { 9107 let error = err as BusinessError; 9108 console.error(`Get overflow count Fail: ${error}`); 9109} 9110 9111``` 9112 9113## ActiveDeviceType<sup>(deprecated)</sup> 9114 9115Enumerates the active device types. 9116 9117> **NOTE** 9118> 9119> This API is deprecated since API version 9. You are advised to use [CommunicationDeviceType](#communicationdevicetype9) instead. 9120 9121**System capability**: SystemCapability.Multimedia.Audio.Device 9122 9123| Name | Value | Description | 9124| ------------- | ----- | ------------------------------------------------------------ | 9125| SPEAKER | 2 | Speaker. | 9126| BLUETOOTH_SCO | 7 | Bluetooth device using Synchronous Connection Oriented (SCO) links. | 9127 9128## InterruptActionType<sup>(deprecated)</sup> 9129 9130Enumerates the returned event types for audio interruption events. 9131 9132> **NOTE** 9133> 9134> 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. 9135 9136**System capability**: SystemCapability.Multimedia.Audio.Renderer 9137 9138| Name | Value | Description | 9139| -------------- | ----- | ------------------------- | 9140| TYPE_ACTIVATED | 0 | Focus gain event. | 9141| TYPE_INTERRUPT | 1 | Audio interruption event. | 9142 9143## AudioInterrupt<sup>(deprecated)</sup> 9144 9145Describes input parameters of audio interruption events. 9146 9147> **NOTE** 9148> 9149> 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. 9150 9151**System capability**: SystemCapability.Multimedia.Audio.Renderer 9152 9153| Name | Type | Mandatory | Description | 9154| --------------- | ------------------------------------- | --------- | ------------------------------------------------------------ | 9155| streamUsage | [StreamUsage](#streamusage) | Yes | Audio stream usage. | 9156| contentType | [ContentType](#contenttypedeprecated) | Yes | Audio content type. | 9157| 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. | 9158 9159## InterruptAction<sup>(deprecated)</sup> 9160 9161Describes the callback invoked for audio interruption or focus gain events. 9162 9163> **NOTE** 9164> 9165> This API is supported since API version 7 and deprecated since API version 9. You are advised to use [InterruptEvent](#interruptevent9). 9166 9167**System capability**: SystemCapability.Multimedia.Audio.Renderer 9168 9169| Name | Type | Mandatory | Description | 9170| ---------- | ----------------------------------------------------- | --------- | ------------------------------------------------------------ | 9171| actionType | [InterruptActionType](#interruptactiontypedeprecated) | Yes | Returned event type. The value **TYPE_ACTIVATED** means the focus gain event, and **TYPE_INTERRUPT** means the audio interruption event. | 9172| type | [InterruptType](#interrupttype) | No | Type of the audio interruption event. | 9173| hint | [InterruptHint](#interrupthint) | No | Hint provided along with the audio interruption event. | 9174| 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. |