1# @ohos.multimedia.audio (Audio Management) (System API) 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- [TonePlayer](#toneplayer9): tone player, used to manage and play Dual Tone Multi Frequency (DTMF) tones, such as dial tones and ringback tones. 9 10> **NOTE** 11> 12> - 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. 13> - This topic describes only system APIs provided by the module. For details about its public APIs, see [@ohos.multimedia.audio (Audio Management)](js-apis-audio.md). 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| LOCAL_NETWORK_ID<sup>9+</sup> | string | Yes | No | Network ID of the local device.<br>This is a system API.<br> **System capability**: SystemCapability.Multimedia.Audio.Device | 26 27## audio.createTonePlayer<sup>9+</sup> 28 29createTonePlayer(options: AudioRendererInfo, callback: AsyncCallback<TonePlayer>): void 30 31Creates a **TonePlayer** instance. This API uses an asynchronous callback to return the result. 32 33**System capability**: SystemCapability.Multimedia.Audio.Tone 34 35**System API**: This is a system API. 36 37**Parameters** 38 39| Name | Type | Mandatory| Description | 40| -------- | ----------------------------------------------- | ---- | -------------- | 41| options | [AudioRendererInfo](js-apis-audio.md#audiorendererinfo8) | Yes | Audio renderer information.| 42| callback | AsyncCallback<[TonePlayer](#toneplayer9)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the **TonePlayer** instance obtained; otherwise, **err** is an error object.| 43 44**Example** 45 46```ts 47import { audio } from '@kit.AudioKit'; 48 49let audioRendererInfo: audio.AudioRendererInfo = { 50 usage : audio.StreamUsage.STREAM_USAGE_DTMF, 51 rendererFlags : 0 52}; 53let tonePlayer: audio.TonePlayer; 54 55audio.createTonePlayer(audioRendererInfo, (err, data) => { 56 console.info(`callback call createTonePlayer: audioRendererInfo: ${audioRendererInfo}`); 57 if (err) { 58 console.error(`callback call createTonePlayer return error: ${err.message}`); 59 } else { 60 console.info(`callback call createTonePlayer return data: ${data}`); 61 tonePlayer = data; 62 } 63}); 64``` 65 66## audio.createTonePlayer<sup>9+</sup> 67 68createTonePlayer(options: AudioRendererInfo): Promise<TonePlayer> 69 70Creates a **TonePlayer** instance. This API uses a promise to return the result. 71 72**System capability**: SystemCapability.Multimedia.Audio.Tone 73 74**System API**: This is a system API. 75 76**Parameters** 77 78| Name | Type | Mandatory| Description | 79| :------ | :---------------------------------------------| :--- | :----------- | 80| options | [AudioRendererInfo](js-apis-audio.md#audiorendererinfo8) | Yes | Audio renderer information.| 81 82**Return value** 83 84| Type | Description | 85| ----------------------------------------- | -------------------------------- | 86| Promise<[TonePlayer](#toneplayer9)> | Promise used to return the **TonePlayer** instance.| 87 88**Example** 89 90```ts 91import { audio } from '@kit.AudioKit'; 92 93let tonePlayer: audio.TonePlayer; 94async function createTonePlayerBefore(){ 95 let audioRendererInfo: audio.AudioRendererInfo = { 96 usage : audio.StreamUsage.STREAM_USAGE_DTMF, 97 rendererFlags : 0 98 }; 99 tonePlayer = await audio.createTonePlayer(audioRendererInfo); 100} 101``` 102 103## audio.createAsrProcessingController<sup>12+</sup> 104 105createAsrProcessingController(audioCapturer: AudioCapturer): AsrProcessingController; 106 107Creates an Automatic Speech Recognition (ASR) processing controller. 108 109**System API**: This is a system API. 110 111**System capability**: SystemCapability.Multimedia.Audio.Capturer 112 113**Return value** 114 115| Type | Description | 116|-------------------------------------------------------| ------------ | 117| [AsrProcessingController](#asrprocessingcontroller12) | ASR processing controller.| 118 119**Error codes** 120 121For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 122 123| ID | Error Message | 124|---------|------------------------------------------| 125| 202 | Caller is not a system application. | 126| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 127| 6800101 | Parameter verification failed. | 128| 6800104 | Operation not allowed. | 129 130**Example** 131 132```ts 133import { audio } from '@kit.AudioKit'; 134 135let audioStreamInfo: audio.AudioStreamInfo = { 136 samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_48000, 137 channels: audio.AudioChannel.CHANNEL_2, 138 sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, 139 encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW 140}; 141 142let audioCapturerInfo: audio.AudioCapturerInfo = { 143 source: audio.SourceType.SOURCE_TYPE_MIC, 144 capturerFlags: 0 145}; 146 147let audioCapturerOptions: audio.AudioCapturerOptions = { 148 streamInfo: audioStreamInfo, 149 capturerInfo: audioCapturerInfo 150}; 151 152audio.createAudioCapturer(audioCapturerOptions, (err, data) => { 153 if (err) { 154 console.error(`AudioCapturer Created : Error: ${err}`); 155 } else { 156 console.info('AudioCapturer Created : Success : SUCCESS'); 157 let audioCapturer = data; 158 let asrProcessingController = audio.createAsrProcessingController(audioCapturer); 159 console.info('AsrProcessingController Created : Success : SUCCESS'); 160 } 161}); 162``` 163 164## AudioVolumeType 165 166Enumerates the audio stream types. 167 168**System capability**: SystemCapability.Multimedia.Audio.Volume 169 170| Name | Value | Description | 171| ---------------------------- | ------ | ---------- | 172| ULTRASONIC<sup>10+</sup> | 10 | Audio stream for ultrasonic.<br>This is a system API.| 173| ALL<sup>9+</sup> | 100 | All public audio streams.<br>This is a system API.| 174 175## InterruptRequestResultType<sup>9+</sup> 176 177Enumerates the result types of audio interruption requests. 178 179**System capability**: SystemCapability.Multimedia.Audio.Interrupt 180 181**System API**: This is a system API. 182 183| Name | Value | Description | 184| ---------------------------- | ------ | ---------- | 185| INTERRUPT_REQUEST_GRANT | 0 | The audio interruption request is accepted.| 186| INTERRUPT_REQUEST_REJECT | 1 | The audio interruption request is denied. There may be a stream with a higher priority.| 187 188## DeviceFlag 189 190Enumerates the audio device flags. 191 192**System capability**: SystemCapability.Multimedia.Audio.Device 193 194| Name | Value | Description | 195| ------------------------------- | ------ |---------------------------| 196| NONE_DEVICES_FLAG<sup>9+</sup> | 0 | No device is available.<br>This is a system API. | 197| DISTRIBUTED_OUTPUT_DEVICES_FLAG<sup>9+</sup> | 4 | Distributed output device.<br>This is a system API. | 198| DISTRIBUTED_INPUT_DEVICES_FLAG<sup>9+</sup> | 8 | Distributed input device.<br>This is a system API. | 199| ALL_DISTRIBUTED_DEVICES_FLAG<sup>9+</sup> | 12 | Distributed input and output device.<br>This is a system API.| 200 201 202## StreamUsage 203 204Enumerates the audio stream usage. 205 206**System capability**: SystemCapability.Multimedia.Audio.Core 207 208| Name | Value | Description | 209| ------------------------------------------| ------ |---------------------------------------------------------------------------------------------------------------------------------------------| 210| STREAM_USAGE_SYSTEM<sup>10+</sup> | 9 | System tone (such as screen lock sound effect or key tone).<br>This is a system API. | 211| STREAM_USAGE_DTMF<sup>10+</sup> | 14 | Dial tone.<br>This is a system API. | 212| STREAM_USAGE_ENFORCED_TONE<sup>10+</sup> | 15 | Forcible tone (such as camera shutter sound effect).<br>This is a system API. | 213| STREAM_USAGE_ULTRASONIC<sup>10+</sup> | 16 | Ultrasonic (currently provided only for MSDP).<br>This is a system API.| 214| STREAM_USAGE_VOICE_CALL_ASSISTANT<sup>12+</sup> | 21 | Voice assistant for calls.<br>This is a system API.| 215 216## InterruptRequestType<sup>9+</sup> 217 218Enumerates the audio interruption request types. 219 220**System API**: This is a system API. 221 222**System capability**: SystemCapability.Multimedia.Audio.Interrupt 223 224| Name | Value | Description | 225| ---------------------------------- | ------ | ------------------------- | 226| INTERRUPT_REQUEST_TYPE_DEFAULT | 0 | Default type, which can be used to interrupt audio requests. | 227 228## VolumeFlag<sup>12+</sup> 229 230Enumerates the volume-related operations. 231 232**System API**: This is a system API. 233 234**System capability**: SystemCapability.Multimedia.Audio.Volume 235 236| Name | Value| Description | 237| ---------------------------------- |---|----------| 238| FLAG_SHOW_SYSTEM_UI | 1 | Displays the system volume bar.| 239 240## AsrNoiseSuppressionMode<sup>12+</sup> 241 242Enumerates the noise suppression modes in ASR. 243 244**System API**: This is a system API. 245 246**System capability**: SystemCapability.Multimedia.Audio.Capturer 247 248| Name| Value| Description| 249|-------|-------|-------| 250| BYPASS | 0 |Bypass noise suppression.| 251| STANDARD | 1 |Standard noise suppression.| 252| NEAR_FIELD | 2 |Near-field noise suppression.| 253| FAR_FIELD | 3 |Far-field noise suppression.| 254 255## AsrAecMode<sup>12+</sup> 256 257Enumerates the Acoustic Echo Cancellation (AEC) modes in ASR. 258 259**System API**: This is a system API. 260 261**System capability**: SystemCapability.Multimedia.Audio.Capturer 262 263| Name| Value| Description| 264|-------|-------|-------| 265| BYPASS | 0 |Bypass AEC.| 266| STANDARD | 1 |Standard AEC.| 267 268## AsrWhisperDetectionMode<sup>12+</sup> 269 270Enumerates the ASR whisper detection modes. 271 272**System API**: This is a system API. 273 274**System capability**: SystemCapability.Multimedia.Audio.Capturer 275 276| Name | Value| Description | 277|-----|---|----------| 278| BYPASS | 0 | ASR whisper detection disabled.| 279| STANDARD | 1 | Standard ASR whisper detection model. | 280 281## AsrVoiceControlMode<sup>12+</sup> 282 283Enumerates the ASR voice control modes. 284 285**System API**: This is a system API. 286 287**System capability**: SystemCapability.Multimedia.Audio.Capturer 288 289| Name | Value| Description | 290|-------------------------|---|---------------------------------------| 291| AUDIO_2_VOICE_TX | 0 | ASR voice control takes effect only for media audio streams. | 292| AUDIO_MIX_2_VOICE_TX | 1 | ASR voice control takes effect for both media audio streams and microphone audio streams. | 293| AUDIO_2_VOICE_TX_EX | 2 | ASR voice control takes effect only for media audio streams. Media streams are reported to the call recording module. | 294| AUDIO_MIX_2_VOICE_TX_EX | 3 | ASR voice control takes effect for both media audio streams and microphone audio streams. Media streams are reported to the call recording module.| 295 296## AsrVoiceMuteMode<sup>12+</sup> 297 298Enumerates the ASR voice mute modes. 299 300**System API**: This is a system API. 301 302**System capability**: SystemCapability.Multimedia.Audio.Capturer 303 304| Name | Value| Description | 305|----------------|---|---------------------| 306| OUTPUT_MUTE | 0 | The local output is muted. | 307| INPUT_MUTE | 1 | The local microphone input is muted. | 308| TTS_MUTE | 2 | The media audio delivered by the application is muted locally. | 309| CALL_MUTE | 3 | The audio streams of calls are muted. | 310| OUTPUT_MUTE_EX | 4 | The local output is muted, and media audio streams are sent to the call recording module.| 311 312## InterruptResult<sup>9+</sup> 313 314Describes the audio interruption result. 315 316**System capability**: SystemCapability.Multimedia.Audio.Interrupt 317 318**System API**: This is a system API. 319 320| Name | Type | Mandatory| Description | 321| --------------| -------------------------------------------------------------- | ---- | ---------------- | 322| requestResult | [InterruptRequestResultType](#interruptrequestresulttype9) | Yes | Audio interruption request type.| 323| interruptNode | number | Yes | Node to interrupt.| 324 325## VolumeEvent<sup>9+</sup> 326 327Describes the event received by the application when the volume is changed. 328 329**System capability**: SystemCapability.Multimedia.Audio.Volume 330 331| Name | Type | Mandatory | Description | 332| ---------- | ----------------------------------- | ---- |-------------------------------------------| 333| volumeGroupId | number | Yes | Volume group ID. It can be used as an input parameter of **getGroupManager**.<br>This is a system API.| 334| networkId | string | Yes | Network ID.<br>This is a system API. | 335 336## ConnectType<sup>9+</sup> 337 338Enumerates the types of connected devices. 339 340**System API**: This is a system API. 341 342**System capability**: SystemCapability.Multimedia.Audio.Volume 343 344| Name | Value | Description | 345| :------------------------------ | :----- | :--------------------- | 346| CONNECT_TYPE_LOCAL | 1 | Local device. | 347| CONNECT_TYPE_DISTRIBUTED | 2 | Distributed device. | 348 349## VolumeGroupInfos<sup>9+</sup> 350 351Describes the volume group information. The value is an array of [VolumeGroupInfo](#volumegroupinfo9) and is read-only. 352 353**System API**: This is a system API. 354 355**System capability**: SystemCapability.Multimedia.Audio.Volume 356 357## VolumeGroupInfo<sup>9+</sup> 358 359Describes the volume group information. 360 361**System API**: This is a system API. 362 363**System capability**: SystemCapability.Multimedia.Audio.Volume 364 365| Name | Type | Readable| Writable| Description | 366| -------------------------- | -------------------------- | ---- | ---- | ---------- | 367| networkId<sup>9+</sup> | string | Yes | No | Network ID of the device. | 368| groupId<sup>9+</sup> | number | Yes | No | Group ID of the device.| 369| mappingId<sup>9+</sup> | number | Yes | No | Group mapping ID.| 370| groupName<sup>9+</sup> | string | Yes | No | Group name.| 371| type<sup>9+</sup> | [ConnectType](#connecttype9)| Yes | No | Type of the connected device.| 372 373## SourceType<sup>8+</sup> 374 375Enumerates the audio source types. 376 377| Name | Value | Description | 378| :------------------------------------------- | :----- | :--------------------- | 379| SOURCE_TYPE_WAKEUP <sup>10+</sup> | 3 | Audio recording source in voice wake-up scenarios.<br>**System capability**: SystemCapability.Multimedia.Audio.Core<br>**Required permissions**: ohos.permission.MANAGE_INTELLIGENT_VOICE <br> This is a system API.| 380| SOURCE_TYPE_VOICE_CALL<sup>11+</sup> | 4 | Audio source in voice calls.<br>**System capability**: SystemCapability.Multimedia.Audio.Core<br>**Required permissions**: ohos.permission.RECORD_VOICE_CALL <br> This is a system API.| 381 382## VolumeAdjustType<sup>10+</sup> 383 384Enumerates the volume adjustment types. 385 386**System API**: This is a system API. 387 388**System capability**: SystemCapability.Multimedia.Audio.Volume 389 390| Name | Value | Description | 391| :--------------------- | :----- | :-------------------------------------------- | 392| VOLUME_UP | 0 | Adjusts the volume upwards.<br>This is a system API. | 393| VOLUME_DOWN | 1 | Adjusts the volume downwards.<br>This is a system API. | 394 395## AudioManager 396 397Implements audio volume and audio device management. Before calling any API in **AudioManager**, you must use [getAudioManager](js-apis-audio.md#audiogetaudiomanager) to create an **AudioManager** instance. 398 399### setExtraParameters<sup>11+</sup> 400 401setExtraParameters(mainKey: string, kvpairs: Record<string, string\>): Promise<void> 402 403Sets extended audio parameters. This API uses a promise to return the result. 404 405**Required permissions**: ohos.permission.MODIFY_AUDIO_SETTINGS 406 407**System API**: This is a system API. 408 409**System capability**: SystemCapability.Multimedia.Audio.Core 410 411**Parameters** 412 413| Name| Type | Mandatory| Description | 414| ------ | ------ | ---- | ---------------------- | 415| mainKey | string | Yes | Main key of the audio parameter to set.| 416| kvpairs | Record<string, string\> | Yes | Sub-KV pair of the audio parameter to set.| 417 418**Return value** 419 420| Type | Description | 421| ------------------- | ------------------------------- | 422| Promise<void> | Promise that returns no value.| 423 424**Error codes** 425 426For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 427 428| ID| Error Message | 429|-----|------------------------------------------------------------------------------------------------------------| 430| 201 | Permission denied. | 431| 202 | Not system App. | 432| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 433| 6800101 | Parameter verification failed. | 434 435**Example** 436 437```ts 438import { BusinessError } from '@kit.BasicServicesKit'; 439 440let kvpairs = {} as Record<string, string>; 441kvpairs = { 442 'key_example': 'value_example' 443}; 444 445audioManager.setExtraParameters('key_example', kvpairs).then(() => { 446 console.info('Promise returned to indicate a successful setting of the extra parameters.'); 447}).catch ((err: BusinessError) => { 448 console.error(`Failed to set the audio extra parameters ${err}`); 449}); 450``` 451 452### getExtraParameters<sup>11+</sup> 453 454getExtraParameters(mainKey: string, subKeys?: Array\<string>): Promise\<Record\<string, string>> 455 456Obtains the value of an audio parameter. This API uses a promise to return the result. 457 458**System API**: This is a system API. 459 460**System capability**: SystemCapability.Multimedia.Audio.Core 461 462**Parameters** 463 464| Name| Type | Mandatory| Description | 465| ------ | ------ |--| ---------------------- | 466| mainKey | string | Yes| Main key of the audio parameter whose value is to be obtained.| 467| subKeys | Array\<string> | No| Subkey of the audio parameter whose value is to be obtained.| 468 469**Return value** 470 471| Type | Description | 472| --------------------- | ----------------------------------- | 473| Promise\<Record\<string, string>> | Promise used to return the value of the audio parameter.| 474 475**Error codes** 476 477For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 478 479| ID| Error Message| 480| ------ | -------------------------| 481| 202 | Not system App. | 482| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 483| 6800101 | Parameter verification failed. | 484 485**Example** 486 487```ts 488import { BusinessError } from '@kit.BasicServicesKit'; 489 490let subKeys: Array<String> = ['key_example']; 491audioManager.getExtraParameters('key_example', subKeys).then((value: Record<string, string>) => { 492 console.info(`Promise returned to indicate that the value of the audio extra parameters is obtained ${value}.`); 493}).catch ((err: BusinessError) => { 494 console.error(`Failed to get the audio extra parameters ${err}`); 495}); 496``` 497 498### setAudioScene<sup>8+</sup> 499 500setAudioScene\(scene: AudioScene, callback: AsyncCallback<void\>\): void 501 502Sets an audio scene. This API uses an asynchronous callback to return the result. 503 504**System API**: This is a system API. 505 506**System capability**: SystemCapability.Multimedia.Audio.Communication 507 508**Parameters** 509 510| Name | Type | Mandatory| Description | 511| :------- | :----------------------------------- | :--- | :------------------- | 512| scene | [AudioScene](js-apis-audio.md#audioscene8) | Yes | Audio scene to set. | 513| callback | AsyncCallback<void\> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 514 515**Example** 516 517```ts 518import { BusinessError } from '@kit.BasicServicesKit'; 519 520audioManager.setAudioScene(audio.AudioScene.AUDIO_SCENE_PHONE_CALL, (err: BusinessError) => { 521 if (err) { 522 console.error(`Failed to set the audio scene mode. ${err}`); 523 return; 524 } 525 console.info('Callback invoked to indicate a successful setting of the audio scene mode.'); 526}); 527``` 528 529### setAudioScene<sup>8+</sup> 530 531setAudioScene\(scene: AudioScene\): Promise<void\> 532 533Sets an audio scene. This API uses a promise to return the result. 534 535**System API**: This is a system API. 536 537**System capability**: SystemCapability.Multimedia.Audio.Communication 538 539**Parameters** 540 541| Name| Type | Mandatory| Description | 542| :----- | :----------------------------------- | :--- | :------------- | 543| scene | [AudioScene](js-apis-audio.md#audioscene8) | Yes | Audio scene to set.| 544 545**Return value** 546 547| Type | Description | 548| :------------- | :------------------- | 549| Promise<void\> | Promise that returns no value.| 550 551**Example** 552 553```ts 554import { BusinessError } from '@kit.BasicServicesKit'; 555 556audioManager.setAudioScene(audio.AudioScene.AUDIO_SCENE_PHONE_CALL).then(() => { 557 console.info('Promise returned to indicate a successful setting of the audio scene mode.'); 558}).catch ((err: BusinessError) => { 559 console.error(`Failed to set the audio scene mode ${err}`); 560}); 561``` 562 563### getSpatializationManager<sup>11+</sup> 564 565getSpatializationManager(): AudioSpatializationManager 566 567Obtains an **AudioSpatializationManager** instance. 568 569**System API**: This is a system API. 570 571**System capability**: SystemCapability.Multimedia.Audio.Spatialization 572 573**Return value** 574 575| Type | Description | 576|------------------------------------------| ----------------------------- | 577| [AudioSpatializationManager](#audiospatializationmanager11) | **AudioSpatializationManager** instance.| 578 579**Error codes** 580 581For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 582 583| ID| Error Message| 584| ------- | --------------------------------------------| 585| 202 | Not system App. | 586 587**Example** 588 589```ts 590import { audio } from '@kit.AudioKit'; 591 592let audioSpatializationManager: audio.AudioSpatializationManager = audioManager.getSpatializationManager(); 593``` 594 595### disableSafeMediaVolume<sup>12+</sup> 596 597disableSafeMediaVolume(): Promise<void> 598 599Disables the safe volume mode. This API uses a promise to return the result. 600 601When the device plays at a high volume for a long time while the safe volume mode is disabled, the system does not automatically remind the user to decrease the volume to a safe volume. 602 603**Required permissions**: ohos.permission.MODIFY_AUDIO_SETTINGS 604 605**System API**: This is a system API. 606 607**System capability**: SystemCapability.Multimedia.Audio.Core 608 609**Return value** 610 611| Type | Description | 612|------------------------------------------| ----------------------------- | 613| Promise<void> | Promise that returns no value.| 614 615**Error codes** 616 617For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 618 619| ID| Error Message| 620| ------- | --------------------------------------------| 621| 201 | Permission denied. | 622| 202 | Not system App. | 623 624**Example** 625 626```ts 627import { BusinessError } from '@kit.BasicServicesKit'; 628 629audioManager.disableSafeMediaVolume().then(() => { 630 console.info('disableSafeMediaVolume success.'); 631}).catch ((err: BusinessError) => { 632 console.error(`disableSafeMediaVolume fail: ${err.code},${err.message}`); 633}); 634``` 635 636### on('volumeChange')<sup>(deprecated)</sup> 637 638on(type: 'volumeChange', callback: Callback\<VolumeEvent>): void 639 640> **NOTE** 641> 642> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [on('volumeChange')](js-apis-audio.md#onvolumechange9) in **AudioVolumeManager**. 643 644Subscribes to the system volume change event, which is triggered when the system volume is changed. This API uses an asynchronous callback to return the result. 645 646**System API**: This is a system API. 647 648Currently, 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. 649 650**System capability**: SystemCapability.Multimedia.Audio.Volume 651 652**Parameters** 653 654| Name | Type | Mandatory| Description | 655| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 656| type | string | Yes | Event type. The value is fixed at **'volumeChange'**.| 657| callback | Callback<[VolumeEvent](#volumeevent9)> | Yes | Callback used to return the changed volume.| 658 659**Example** 660 661```ts 662audioManager.on('volumeChange', (volumeEvent: audio.VolumeEvent) => { 663 console.info(`VolumeType of stream: ${volumeEvent.volumeType} `); 664 console.info(`Volume level: ${volumeEvent.volume} `); 665 console.info(`Whether to updateUI: ${volumeEvent.updateUi} `); 666}); 667``` 668 669### on('ringerModeChange')<sup>(deprecated)</sup> 670 671on(type: 'ringerModeChange', callback: Callback\<AudioRingMode>): void 672 673Subscribes to the ringer mode change event, which is triggered when [audioringmode](js-apis-audio.md#audioringmode) is changed. This API uses an asynchronous callback to return the result. 674 675> **NOTE** 676> 677> This API is supported since API version 8 and deprecated since API version 9. You are advised to use [on('ringerModeChange')](js-apis-audio.md#onringermodechange9) in **AudioVolumeGroupManager**. 678 679**System API**: This is a system API. 680 681**System capability**: SystemCapability.Multimedia.Audio.Communication 682 683**Parameters** 684 685| Name | Type | Mandatory| Description | 686| -------- | ----------------------------------------- | ---- | ------------------------------------------------------------ | 687| type | string | Yes | Event type. The value is fixed at **'ringerModeChange'**.| 688| callback | Callback<[AudioRingMode](js-apis-audio.md#audioringmode)> | Yes | Callback used to return the changed ringer mode. | 689 690**Example** 691 692```ts 693audioManager.on('ringerModeChange', (ringerMode: audio.AudioRingMode) => { 694 console.info(`Updated ringermode: ${ringerMode}`); 695}); 696``` 697 698## AudioVolumeManager<sup>9+</sup> 699 700Implements audio volume management. Before calling an API in **AudioVolumeManager**, you must use [getVolumeManager](js-apis-audio.md#getvolumemanager9) to obtain an **AudioVolumeManager** instance. 701 702### getVolumeGroupInfos<sup>9+</sup> 703 704getVolumeGroupInfos(networkId: string, callback: AsyncCallback<VolumeGroupInfos\>\): void 705 706Obtains the volume groups. This API uses an asynchronous callback to return the result. 707 708**System API**: This is a system API. 709 710**System capability**: SystemCapability.Multimedia.Audio.Volume 711 712**Parameters** 713 714| Name | Type | Mandatory| Description | 715| ---------- | ------------------------------------------------------------ | ---- | -------------------- | 716| networkId | string | Yes | Network ID of the device. The network ID of the local device is **audio.LOCAL_NETWORK_ID**. | 717| callback | AsyncCallback<[VolumeGroupInfos](#volumegroupinfos9)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the volume groups obtained; otherwise, **err** is an error object.| 718 719**Example** 720```ts 721import { BusinessError } from '@kit.BasicServicesKit'; 722 723audioVolumeManager.getVolumeGroupInfos(audio.LOCAL_NETWORK_ID, (err: BusinessError, value: audio.VolumeGroupInfos) => { 724 if (err) { 725 console.error(`Failed to obtain the volume group infos list. ${err}`); 726 return; 727 } 728 console.info('Callback invoked to indicate that the volume group infos list is obtained.'); 729}); 730``` 731 732### getVolumeGroupInfos<sup>9+</sup> 733 734getVolumeGroupInfos(networkId: string\): Promise<VolumeGroupInfos\> 735 736Obtains the volume groups. This API uses a promise to return the result. 737 738**System API**: This is a system API. 739 740**System capability**: SystemCapability.Multimedia.Audio.Volume 741 742**Parameters** 743 744| Name | Type | Mandatory| Description | 745| ---------- | ------------------| ---- | -------------------- | 746| networkId | string | Yes | Network ID of the device. The network ID of the local device is **audio.LOCAL_NETWORK_ID**. | 747 748**Return value** 749 750| Type | Description | 751| ------------------- | ----------------------------- | 752| Promise<[VolumeGroupInfos](#volumegroupinfos9)> | Promise used to return the volume group information list.| 753 754**Example** 755 756```ts 757async function getVolumeGroupInfos(){ 758 let volumegroupinfos: audio.VolumeGroupInfos = await audio.getAudioManager().getVolumeManager().getVolumeGroupInfos(audio.LOCAL_NETWORK_ID); 759 console.info('Promise returned to indicate that the volumeGroup list is obtained.'+JSON.stringify(volumegroupinfos)) 760} 761``` 762 763### getVolumeGroupInfosSync<sup>10+</sup> 764 765getVolumeGroupInfosSync(networkId: string\): VolumeGroupInfos 766 767Obtains the volume groups. This API returns the result synchronously. 768 769**System API**: This is a system API. 770 771**System capability**: SystemCapability.Multimedia.Audio.Volume 772 773**Parameters** 774 775| Name | Type | Mandatory| Description | 776| ---------- | ------------------| ---- | -------------------- | 777| networkId | string | Yes | Network ID of the device. The network ID of the local device is **audio.LOCAL_NETWORK_ID**. | 778 779**Return value** 780 781| Type | Description | 782| ------------------- | ----------------------------- | 783| [VolumeGroupInfos](#volumegroupinfos9) | Volume group information list.| 784 785**Error codes** 786 787For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 788 789| ID| Error Message| 790| ------- | --------------------------------------------| 791| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 792| 6800101 | Parameter verification failed. | 793 794**Example** 795 796```ts 797import { BusinessError } from '@kit.BasicServicesKit'; 798 799try { 800 let volumegroupinfos: audio.VolumeGroupInfos = audioVolumeManager.getVolumeGroupInfosSync(audio.LOCAL_NETWORK_ID); 801 console.info(`Indicate that the volumeGroup list is obtained. ${JSON.stringify(volumegroupinfos)}`); 802} catch (err) { 803 let error = err as BusinessError; 804 console.error(`Failed to obtain the volumeGroup list ${error}`); 805} 806``` 807 808## AudioVolumeGroupManager<sup>9+</sup> 809 810Manages the volume of an audio group. Before calling any API in **AudioVolumeGroupManager**, you must use [getVolumeGroupManager](js-apis-audio.md#getvolumegroupmanager9) to obtain an **AudioVolumeGroupManager** instance. 811 812### setVolume<sup>9+</sup> 813 814setVolume(volumeType: AudioVolumeType, volume: number, callback: AsyncCallback<void>): void 815 816Sets the volume for a stream. This API uses an asynchronous callback to return the result. 817 818**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 819 820This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**. 821 822**System API**: This is a system API. 823 824**System capability**: SystemCapability.Multimedia.Audio.Volume 825 826**Parameters** 827 828| Name | Type | Mandatory| Description | 829| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 830| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 831| volume | number | Yes | Volume. The volume range can be obtained by calling [getMinVolume](js-apis-audio.md#getminvolume9) and [getMaxVolume](js-apis-audio.md#getmaxvolume9).| 832| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 833 834**Example** 835 836```ts 837import { BusinessError } from '@kit.BasicServicesKit'; 838 839audioVolumeGroupManager.setVolume(audio.AudioVolumeType.MEDIA, 10, (err: BusinessError) => { 840 if (err) { 841 console.error(`Failed to set the volume. ${err}`); 842 return; 843 } 844 console.info('Callback invoked to indicate a successful volume setting.'); 845}); 846``` 847 848### setVolume<sup>9+</sup> 849 850setVolume(volumeType: AudioVolumeType, volume: number): Promise<void> 851 852Sets the volume for a stream. This API uses a promise to return the result. 853 854**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 855 856This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**. 857 858**System API**: This is a system API. 859 860**System capability**: SystemCapability.Multimedia.Audio.Volume 861 862**Parameters** 863 864| Name | Type | Mandatory| Description | 865| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 866| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 867| volume | number | Yes | Volume. The volume range can be obtained by calling [getMinVolume](js-apis-audio.md#getminvolume9) and [getMaxVolume](js-apis-audio.md#getmaxvolume9).| 868 869**Return value** 870 871| Type | Description | 872| ------------------- | ----------------------------- | 873| Promise<void> | Promise that returns no value.| 874 875**Example** 876 877```ts 878audioVolumeGroupManager.setVolume(audio.AudioVolumeType.MEDIA, 10).then(() => { 879 console.info('Promise returned to indicate a successful volume setting.'); 880}); 881``` 882 883### setVolumeWithFlag<sup>12+</sup> 884 885setVolumeWithFlag(volumeType: AudioVolumeType, volume: number, flags: number): Promise<void> 886 887Sets the volume for a stream, with a flag to specify whether to display the system volume bar during the volume change. This API uses a promise to return the result. 888 889**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 890 891This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**. 892 893**System API**: This is a system API. 894 895**System capability**: SystemCapability.Multimedia.Audio.Volume 896 897**Parameters** 898 899| Name | Type | Mandatory| Description | 900| ---------- | ----------------------------------- | ---- |--------------------------------------| 901| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 902| volume | number | Yes | Volume. The volume range can be obtained by calling [getMinVolume](js-apis-audio.md#getminvolume9) and [getMaxVolume](js-apis-audio.md#getmaxvolume9).| 903| flags | number | Yes | Whether to display the system volume bar. The value **0** means not to display the system volume bar, and **1** means the opposite.| 904 905**Return value** 906 907| Type | Description | 908| ------------------- | ----------------------------- | 909| Promise<void> | Promise that returns no value.| 910 911**Error codes** 912 913For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 914 915| ID| Error Message| 916| ------- | --------------------------------------------| 917| 201 | Permission denied. | 918| 202 | Not system App. | 919 920**Example** 921 922```ts 923audioVolumeGroupManager.setVolumeWithFlag(audio.AudioVolumeType.MEDIA, 10, 1).then(() => { 924 console.info('Promise returned to indicate a successful volume setting.'); 925}); 926``` 927 928### mute<sup>9+</sup> 929 930mute(volumeType: AudioVolumeType, mute: boolean, callback: AsyncCallback<void>): void 931 932Mutes or unmutes a stream. This API uses an asynchronous callback to return the result. 933 934**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 935 936This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**. 937 938**System API**: This is a system API. 939 940**System capability**: SystemCapability.Multimedia.Audio.Volume 941 942**Parameters** 943 944| Name | Type | Mandatory| Description | 945| ---------- | ----------------------------------- | ---- | ------------------------------------- | 946| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 947| mute | boolean | Yes | Mute status to set. The value **true** means to mute the stream, and **false** means the opposite.| 948| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 949 950**Example** 951 952```ts 953import { BusinessError } from '@kit.BasicServicesKit'; 954 955audioVolumeGroupManager.mute(audio.AudioVolumeType.MEDIA, true, (err: BusinessError) => { 956 if (err) { 957 console.error(`Failed to mute the stream. ${err}`); 958 return; 959 } 960 console.info('Callback invoked to indicate that the stream is muted.'); 961}); 962``` 963 964### mute<sup>9+</sup> 965 966mute(volumeType: AudioVolumeType, mute: boolean): Promise<void> 967 968Mutes or unmutes a stream. This API uses a promise to return the result. 969 970**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 971 972This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**. 973 974**System API**: This is a system API. 975 976**System capability**: SystemCapability.Multimedia.Audio.Volume 977 978**Parameters** 979 980| Name | Type | Mandatory| Description | 981| ---------- | ----------------------------------- | ---- | ------------------------------------- | 982| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 983| mute | boolean | Yes | Mute status to set. The value **true** means to mute the stream, and **false** means the opposite.| 984 985**Return value** 986 987| Type | Description | 988| ------------------- | ----------------------------- | 989| Promise<void> | Promise that returns no value.| 990 991**Example** 992 993```ts 994audioVolumeGroupManager.mute(audio.AudioVolumeType.MEDIA, true).then(() => { 995 console.info('Promise returned to indicate that the stream is muted.'); 996}); 997``` 998 999### setRingerMode<sup>9+</sup> 1000 1001setRingerMode(mode: AudioRingMode, callback: AsyncCallback<void>): void 1002 1003Sets the ringer mode. This API uses an asynchronous callback to return the result. 1004 1005**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 1006 1007This permission is required only for muting or unmuting the ringer. 1008 1009**System API**: This is a system API. 1010 1011**System capability**: SystemCapability.Multimedia.Audio.Volume 1012 1013**Parameters** 1014 1015| Name | Type | Mandatory| Description | 1016| -------- | ------------------------------- | ---- | ------------------------ | 1017| mode | [AudioRingMode](js-apis-audio.md#audioringmode) | Yes | Ringer mode. | 1018| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1019 1020**Example** 1021 1022```ts 1023import { BusinessError } from '@kit.BasicServicesKit'; 1024 1025audioVolumeGroupManager.setRingerMode(audio.AudioRingMode.RINGER_MODE_NORMAL, (err: BusinessError) => { 1026 if (err) { 1027 console.error(`Failed to set the ringer mode. ${err}`); 1028 return; 1029 } 1030 console.info('Callback invoked to indicate a successful setting of the ringer mode.'); 1031}); 1032``` 1033 1034### setRingerMode<sup>9+</sup> 1035 1036setRingerMode(mode: AudioRingMode): Promise<void> 1037 1038Sets the ringer mode. This API uses a promise to return the result. 1039 1040**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 1041 1042This permission is required only for muting or unmuting the ringer. 1043 1044**System API**: This is a system API. 1045 1046**System capability**: SystemCapability.Multimedia.Audio.Volume 1047 1048**Parameters** 1049 1050| Name| Type | Mandatory| Description | 1051| ------ | ------------------------------- | ---- | -------------- | 1052| mode | [AudioRingMode](js-apis-audio.md#audioringmode) | Yes | Ringer mode.| 1053 1054**Return value** 1055 1056| Type | Description | 1057| ------------------- | ------------------------------- | 1058| Promise<void> | Promise that returns no value.| 1059 1060**Example** 1061 1062```ts 1063audioVolumeGroupManager.setRingerMode(audio.AudioRingMode.RINGER_MODE_NORMAL).then(() => { 1064 console.info('Promise returned to indicate a successful setting of the ringer mode.'); 1065}); 1066``` 1067 1068### setMicMute<sup>11+</sup> 1069 1070setMicMute(mute: boolean): Promise<void> 1071 1072Mutes or unmutes the microphone. This API uses a promise to return the result. 1073 1074**Required permissions**: ohos.permission.MANAGE_AUDIO_CONFIG 1075 1076**System API**: This is a system API. 1077 1078**System capability**: SystemCapability.Multimedia.Audio.Volume 1079 1080**Parameters** 1081 1082| Name| Type | Mandatory| Description | 1083| ------ | ------- | ---- | --------------------------------------------- | 1084| mute | boolean | Yes | Mute status to set. The value **true** means to mute the microphone, and **false** means the opposite.| 1085 1086**Return value** 1087 1088| Type | Description | 1089| ------------------- | ------------------------------- | 1090| Promise<void> | Promise that returns no value.| 1091 1092**Error codes** 1093 1094For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 1095 1096| ID| Error Message| 1097| ------- | --------------------------------------------| 1098| 201 | Permission denied. | 1099| 202 | Not system App. | 1100| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1101| 6800101 | Parameter verification failed. | 1102 1103**Example** 1104 1105```ts 1106audioVolumeGroupManager.setMicMute(true).then(() => { 1107 console.info('Promise returned to indicate that the mic is muted.'); 1108}); 1109``` 1110 1111### adjustVolumeByStep<sup>10+</sup> 1112 1113adjustVolumeByStep(adjustType: VolumeAdjustType, callback: AsyncCallback<void>): void 1114 1115Adjusts the volume of the stream with the highest priority by step. This API uses an asynchronous callback to return the result. 1116 1117**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 1118 1119This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**. 1120 1121**System API**: This is a system API. 1122 1123**System capability**: SystemCapability.Multimedia.Audio.Volume 1124 1125**Parameters** 1126 1127| Name | Type | Mandatory| Description | 1128| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 1129| adjustType | [VolumeAdjustType](#volumeadjusttype10) | Yes | Volume adjustment type. | 1130| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1131 1132**Error codes** 1133 1134For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 1135 1136| ID| Error Message| 1137| ------- | --------------------------------------------| 1138| 201 | Permission denied. | 1139| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1140| 6800101 | Parameter verification failed. Return by callback. | 1141| 6800301 | System error. Return by callback. | 1142 1143**Example** 1144 1145```ts 1146import { BusinessError } from '@kit.BasicServicesKit'; 1147 1148audioVolumeGroupManager.adjustVolumeByStep(audio.VolumeAdjustType.VOLUME_UP, (err: BusinessError) => { 1149 if (err) { 1150 console.error(`Failed to adjust the volume by step. ${err}`); 1151 return; 1152 } else { 1153 console.info('Success to adjust the volume by step.'); 1154 } 1155}); 1156``` 1157### adjustVolumeByStep<sup>10+</sup> 1158 1159adjustVolumeByStep(adjustType: VolumeAdjustType): Promise<void> 1160 1161Adjusts the volume of the stream with the highest priority by step. This API uses a promise to return the result. 1162 1163**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 1164 1165This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**. 1166 1167**System API**: This is a system API. 1168 1169**System capability**: SystemCapability.Multimedia.Audio.Volume 1170 1171**Parameters** 1172 1173| Name | Type | Mandatory| Description | 1174| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 1175| adjustType | [VolumeAdjustType](#volumeadjusttype10) | Yes | Volume adjustment type. | 1176 1177**Return value** 1178 1179| Type | Description | 1180| ------------------- | ----------------------------- | 1181| Promise<void> | Promise that returns no value.| 1182 1183**Error codes** 1184 1185For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 1186 1187| ID| Error Message| 1188| ------- | --------------------------------------------| 1189| 201 | Permission denied. | 1190| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1191| 6800101 | Parameter verification failed. Return by promise. | 1192| 6800301 | System error. Return by promise. | 1193 1194**Example** 1195 1196```ts 1197import { BusinessError } from '@kit.BasicServicesKit'; 1198 1199audioVolumeGroupManager.adjustVolumeByStep(audio.VolumeAdjustType.VOLUME_UP).then(() => { 1200 console.info('Success to adjust the volume by step.'); 1201}).catch((error: BusinessError) => { 1202 console.error('Fail to adjust the volume by step.'); 1203}); 1204``` 1205 1206### adjustSystemVolumeByStep<sup>10+</sup> 1207 1208adjustSystemVolumeByStep(volumeType: AudioVolumeType, adjustType: VolumeAdjustType, callback: AsyncCallback<void>): void 1209 1210Adjusts the volume of a stream by step. This API uses an asynchronous callback to return the result. 1211 1212**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 1213 1214This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**. 1215 1216**System API**: This is a system API. 1217 1218**System capability**: SystemCapability.Multimedia.Audio.Volume 1219 1220**Parameters** 1221 1222| Name | Type | Mandatory| Description | 1223| ---------- | ----------------------------------- | ---- | -------------------------------------------------------- | 1224| volumeType | [AudioVolumeType](#audiovolumetype) | Yes | Audio stream type. | 1225| adjustType | [VolumeAdjustType](#volumeadjusttype10) | Yes | Volume adjustment type. | 1226| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1227 1228**Error codes** 1229 1230For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 1231 1232| ID| Error Message| 1233| ------- | --------------------------------------------| 1234| 201 | Permission denied. | 1235| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1236| 6800101 | Parameter verification failed. Return by callback. | 1237| 6800301 | System error. Return by callback. | 1238 1239**Example** 1240 1241```ts 1242import { BusinessError } from '@kit.BasicServicesKit'; 1243 1244audioVolumeGroupManager.adjustSystemVolumeByStep(audio.AudioVolumeType.MEDIA, audio.VolumeAdjustType.VOLUME_UP, (err: BusinessError) => { 1245 if (err) { 1246 console.error(`Failed to adjust the system volume by step ${err}`); 1247 } else { 1248 console.info('Success to adjust the system volume by step.'); 1249 } 1250}); 1251``` 1252### adjustSystemVolumeByStep<sup>10+</sup> 1253 1254adjustSystemVolumeByStep(volumeType: AudioVolumeType, adjustType: VolumeAdjustType): Promise<void> 1255 1256Adjusts the volume of a stream by step. This API uses a promise to return the result. 1257 1258**Required permissions**: ohos.permission.ACCESS_NOTIFICATION_POLICY 1259 1260This permission is required only for muting or unmuting the ringer when **volumeType** is set to **AudioVolumeType.RINGTONE**. 1261 1262**System API**: This is a system API. 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| adjustType | [VolumeAdjustType](#volumeadjusttype10) | Yes | Volume adjustment type. | 1272 1273**Return value** 1274 1275| Type | Description | 1276| ------------------- | ----------------------------- | 1277| Promise<void> | Promise that returns no value.| 1278 1279**Error codes** 1280 1281For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 1282 1283| ID| Error Message| 1284| ------- | --------------------------------------------| 1285| 201 | Permission denied. | 1286| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 1287| 6800101 | Parameter verification failed. Return by promise. | 1288| 6800301 | System error. Return by promise. | 1289 1290**Example** 1291 1292```ts 1293import { BusinessError } from '@kit.BasicServicesKit'; 1294 1295audioVolumeGroupManager.adjustSystemVolumeByStep(audio.AudioVolumeType.MEDIA, audio.VolumeAdjustType.VOLUME_UP).then(() => { 1296 console.info('Success to adjust the system volume by step.'); 1297}).catch((error: BusinessError) => { 1298 console.error('Fail to adjust the system volume by step.'); 1299}); 1300``` 1301 1302## AudioRoutingManager<sup>9+</sup> 1303 1304Implements audio routing management. Before calling any API in **AudioRoutingManager**, you must use [getRoutingManager](js-apis-audio.md#getroutingmanager9) to obtain an **AudioRoutingManager** instance. 1305 1306### selectInputDevice<sup>9+</sup> 1307 1308selectInputDevice(inputAudioDevices: AudioDeviceDescriptors, callback: AsyncCallback<void>): void 1309 1310Selects an audio input device. Currently, only one input device can be selected. This API uses an asynchronous callback to return the result. 1311 1312**System API**: This is a system API. 1313 1314**System capability**: SystemCapability.Multimedia.Audio.Device 1315 1316**Parameters** 1317 1318| Name | Type | Mandatory| Description | 1319| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 1320| inputAudioDevices | [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | Yes | Input device. | 1321| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1322 1323**Example** 1324```ts 1325import { audio } from '@kit.AudioKit'; 1326import { BusinessError } from '@kit.BasicServicesKit'; 1327 1328let inputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{ 1329 deviceRole : audio.DeviceRole.INPUT_DEVICE, 1330 deviceType : audio.DeviceType.MIC, 1331 id : 1, 1332 name : "", 1333 address : "", 1334 sampleRates : [44100], 1335 channelCounts : [2], 1336 channelMasks : [0], 1337 networkId : audio.LOCAL_NETWORK_ID, 1338 interruptGroupId : 1, 1339 volumeGroupId : 1, 1340 displayName : "", 1341}]; 1342 1343async function selectInputDevice(){ 1344 audioRoutingManager.selectInputDevice(inputAudioDeviceDescriptor, (err: BusinessError) => { 1345 if (err) { 1346 console.error(`Result ERROR: ${err}`); 1347 } else { 1348 console.info('Select input devices result callback: SUCCESS'); 1349 } 1350 }); 1351} 1352``` 1353 1354### selectInputDevice<sup>9+</sup> 1355 1356selectInputDevice(inputAudioDevices: AudioDeviceDescriptors): Promise<void> 1357 1358**System API**: This is a system API. 1359 1360Selects an audio input device. Currently, only one input device can be selected. This API uses a promise to return the result. 1361 1362**System capability**: SystemCapability.Multimedia.Audio.Device 1363 1364**Parameters** 1365 1366| Name | Type | Mandatory| Description | 1367| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 1368| inputAudioDevices | [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | Yes | Input device. | 1369 1370**Return value** 1371 1372| Type | Description | 1373| --------------------- | --------------------------- | 1374| Promise<void> | Promise that returns no value.| 1375 1376**Example** 1377 1378```ts 1379import { audio } from '@kit.AudioKit'; 1380import { BusinessError } from '@kit.BasicServicesKit'; 1381 1382let inputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{ 1383 deviceRole : audio.DeviceRole.INPUT_DEVICE, 1384 deviceType : audio.DeviceType.MIC, 1385 id : 1, 1386 name : "", 1387 address : "", 1388 sampleRates : [44100], 1389 channelCounts : [2], 1390 channelMasks : [0], 1391 networkId : audio.LOCAL_NETWORK_ID, 1392 interruptGroupId : 1, 1393 volumeGroupId : 1, 1394 displayName : "", 1395}]; 1396 1397async function getRoutingManager(){ 1398 audioRoutingManager.selectInputDevice(inputAudioDeviceDescriptor).then(() => { 1399 console.info('Select input devices result promise: SUCCESS'); 1400 }).catch((err: BusinessError) => { 1401 console.error(`Result ERROR: ${err}`); 1402 }); 1403} 1404``` 1405 1406### selectOutputDevice<sup>9+</sup> 1407 1408selectOutputDevice(outputAudioDevices: AudioDeviceDescriptors, callback: AsyncCallback<void>): void 1409 1410Selects an audio output device. Currently, only one output device can be selected. This API uses an asynchronous callback to return the result. 1411 1412**System API**: This is a system API. 1413 1414**System capability**: SystemCapability.Multimedia.Audio.Device 1415 1416**Parameters** 1417 1418| Name | Type | Mandatory| Description | 1419| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 1420| outputAudioDevices | [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | Yes | Output device. | 1421| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1422 1423**Example** 1424```ts 1425import { audio } from '@kit.AudioKit'; 1426import { BusinessError } from '@kit.BasicServicesKit'; 1427 1428let outputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{ 1429 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 1430 deviceType : audio.DeviceType.SPEAKER, 1431 id : 1, 1432 name : "", 1433 address : "", 1434 sampleRates : [44100], 1435 channelCounts : [2], 1436 channelMasks : [0], 1437 networkId : audio.LOCAL_NETWORK_ID, 1438 interruptGroupId : 1, 1439 volumeGroupId : 1, 1440 displayName : "", 1441}]; 1442 1443async function selectOutputDevice(){ 1444 audioRoutingManager.selectOutputDevice(outputAudioDeviceDescriptor, (err: BusinessError) => { 1445 if (err) { 1446 console.error(`Result ERROR: ${err}`); 1447 } else { 1448 console.info('Select output devices result callback: SUCCESS'); } 1449 }); 1450} 1451``` 1452 1453### selectOutputDevice<sup>9+</sup> 1454 1455selectOutputDevice(outputAudioDevices: AudioDeviceDescriptors): Promise<void> 1456 1457**System API**: This is a system API. 1458 1459Selects an audio output device. Currently, only one output device can be selected. This API uses a promise to return the result. 1460 1461**System capability**: SystemCapability.Multimedia.Audio.Device 1462 1463**Parameters** 1464 1465| Name | Type | Mandatory| Description | 1466| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 1467| outputAudioDevices | [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | Yes | Output device. | 1468 1469**Return value** 1470 1471| Type | Description | 1472| --------------------- | --------------------------- | 1473| Promise<void> | Promise that returns no value.| 1474 1475**Example** 1476 1477```ts 1478import { audio } from '@kit.AudioKit'; 1479import { BusinessError } from '@kit.BasicServicesKit'; 1480 1481let outputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{ 1482 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 1483 deviceType : audio.DeviceType.SPEAKER, 1484 id : 1, 1485 name : "", 1486 address : "", 1487 sampleRates : [44100], 1488 channelCounts : [2], 1489 channelMasks : [0], 1490 networkId : audio.LOCAL_NETWORK_ID, 1491 interruptGroupId : 1, 1492 volumeGroupId : 1, 1493 displayName : "", 1494}]; 1495 1496async function selectOutputDevice(){ 1497 audioRoutingManager.selectOutputDevice(outputAudioDeviceDescriptor).then(() => { 1498 console.info('Select output devices result promise: SUCCESS'); 1499 }).catch((err: BusinessError) => { 1500 console.error(`Result ERROR: ${err}`); 1501 }); 1502} 1503``` 1504 1505### selectOutputDeviceByFilter<sup>9+</sup> 1506 1507selectOutputDeviceByFilter(filter: AudioRendererFilter, outputAudioDevices: AudioDeviceDescriptors, callback: AsyncCallback<void>): void 1508 1509**System API**: This is a system API. 1510 1511Selects an audio output device based on the filter criteria. Currently, only one output device can be selected. This API uses an asynchronous callback to return the result. 1512 1513**System capability**: SystemCapability.Multimedia.Audio.Device 1514 1515**Parameters** 1516 1517| Name | Type | Mandatory| Description | 1518| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 1519| filter | [AudioRendererFilter](#audiorendererfilter9) | Yes | Filter criteria. | 1520| outputAudioDevices | [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | Yes | Output device. | 1521| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1522 1523**Example** 1524```ts 1525import { audio } from '@kit.AudioKit'; 1526import { BusinessError } from '@kit.BasicServicesKit'; 1527 1528let outputAudioRendererFilter: audio.AudioRendererFilter = { 1529 uid : 20010041, 1530 rendererInfo : { 1531 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 1532 rendererFlags : 0 1533 }, 1534 rendererId : 0 1535}; 1536 1537let outputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{ 1538 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 1539 deviceType : audio.DeviceType.SPEAKER, 1540 id : 1, 1541 name : "", 1542 address : "", 1543 sampleRates : [44100], 1544 channelCounts : [2], 1545 channelMasks : [0], 1546 networkId : audio.LOCAL_NETWORK_ID, 1547 interruptGroupId : 1, 1548 volumeGroupId : 1, 1549 displayName : "", 1550}]; 1551 1552async function selectOutputDeviceByFilter(){ 1553 audioRoutingManager.selectOutputDeviceByFilter(outputAudioRendererFilter, outputAudioDeviceDescriptor, (err: BusinessError) => { 1554 if (err) { 1555 console.error(`Result ERROR: ${err}`); 1556 } else { 1557 console.info('Select output devices by filter result callback: SUCCESS'); } 1558 }); 1559} 1560``` 1561 1562### selectOutputDeviceByFilter<sup>9+</sup> 1563 1564selectOutputDeviceByFilter(filter: AudioRendererFilter, outputAudioDevices: AudioDeviceDescriptors): Promise<void> 1565 1566**System API**: This is a system API. 1567 1568Selects an audio output device based on the filter criteria. Currently, only one output device can be selected. This API uses a promise to return the result. 1569 1570**System capability**: SystemCapability.Multimedia.Audio.Device 1571 1572**Parameters** 1573 1574| Name | Type | Mandatory| Description | 1575| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 1576| filter | [AudioRendererFilter](#audiorendererfilter9) | Yes | Filter criteria. | 1577| outputAudioDevices | [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | Yes | Output device. | 1578 1579**Return value** 1580 1581| Type | Description | 1582| --------------------- | --------------------------- | 1583| Promise<void> | Promise that returns no value.| 1584 1585**Example** 1586 1587```ts 1588import { audio } from '@kit.AudioKit'; 1589import { BusinessError } from '@kit.BasicServicesKit'; 1590 1591let outputAudioRendererFilter: audio.AudioRendererFilter = { 1592 uid : 20010041, 1593 rendererInfo : { 1594 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 1595 rendererFlags : 0 1596 }, 1597 rendererId : 0 1598}; 1599 1600let outputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{ 1601 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 1602 deviceType : audio.DeviceType.SPEAKER, 1603 id : 1, 1604 name : "", 1605 address : "", 1606 sampleRates : [44100], 1607 channelCounts : [2], 1608 channelMasks : [0], 1609 networkId : audio.LOCAL_NETWORK_ID, 1610 interruptGroupId : 1, 1611 volumeGroupId : 1, 1612 displayName : "", 1613}]; 1614 1615async function selectOutputDeviceByFilter(){ 1616 audioRoutingManager.selectOutputDeviceByFilter(outputAudioRendererFilter, outputAudioDeviceDescriptor).then(() => { 1617 console.info('Select output devices by filter result promise: SUCCESS'); 1618 }).catch((err: BusinessError) => { 1619 console.error(`Result ERROR: ${err}`); 1620 }) 1621} 1622``` 1623 1624### selectInputDeviceByFilter<sup>14+</sup> 1625 1626selectInputDeviceByFilter(filter: AudioCapturerFilter, inputAudioDeviceDescriptor: AudioDeviceDescriptors, callback: AsyncCallback<void>): void 1627 1628Selects an audio input device based on the filter criteria. Currently, only one input device can be selected. This API uses an asynchronous callback to return the result. 1629 1630**System API**: This is a system API. 1631 1632**System capability**: SystemCapability.Multimedia.Audio.Device 1633 1634**Parameters** 1635 1636| Name | Type | Mandatory| Description | 1637|-----------------------------|-------------------------------------------------------------------| ---- |-----------------------------------------| 1638| filter | [AudioCapturerFilter](#audiocapturerfilter14) | Yes | Filter criteria. | 1639| outputAudioDeviceDescriptor | [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | Yes | Input device. | 1640| callback | AsyncCallback<void> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 1641 1642**Example** 1643```ts 1644import { audio } from '@kit.AudioKit'; 1645import { BusinessError } from '@kit.BasicServicesKit'; 1646 1647let inputAudioCapturerFilter: audio.AudioCapturerFilter = { 1648 uid : 20010041, 1649 capturerInfo : { 1650 source: audio.SourceType.SOURCE_TYPE_MIC, 1651 capturerFlags: 0 1652 } 1653}; 1654 1655let inputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{ 1656 deviceRole : audio.DeviceRole.INPUT_DEVICE, 1657 deviceType : audio.DeviceType.MIC, 1658 id : 1, 1659 name : "", 1660 address : "", 1661 sampleRates : [44100], 1662 channelCounts : [2], 1663 channelMasks : [0], 1664 networkId : audio.LOCAL_NETWORK_ID, 1665 interruptGroupId : 1, 1666 volumeGroupId : 1, 1667 displayName : "", 1668}]; 1669 1670async function selectInputDeviceByFilter() { 1671 let audioManager = audio.getAudioManager(); // Create an AudioManager instance. 1672 let audioRoutingManager = audioManager.getRoutingManager(); // Call an API of AudioManager to create an AudioRoutingManager instance. 1673 audioRoutingManager.selectInputDeviceByFilter(inputAudioCapturerFilter, inputAudioDeviceDescriptor, (err: BusinessError) => { 1674 if (err) { 1675 console.error(`Result ERROR: ${err}`); 1676 } else { 1677 console.info('Select input devices by filter result callback: SUCCESS'); } 1678 }); 1679} 1680``` 1681 1682### selectInputDeviceByFilter<sup>14+</sup> 1683 1684selectInputDeviceByFilter(filter: AudioCapturerFilter, outputAudioDevices: AudioDeviceDescriptors): Promise<void> 1685 1686Selects an audio input device based on the filter criteria. Currently, only one input device can be selected. This API uses a promise to return the result. 1687 1688**System API**: This is a system API. 1689 1690**System capability**: SystemCapability.Multimedia.Audio.Device 1691 1692**Parameters** 1693 1694| Name | Type | Mandatory| Description | 1695| ----------------------| ------------------------------------------------------------ | ---- |--------| 1696| filter | [AudioCapturerFilter](#audiocapturerfilter14) | Yes | Filter criteria.| 1697| outputAudioDeviceDescriptor | [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | Yes | Input device.| 1698 1699**Return value** 1700 1701| Type | Description | 1702| --------------------- | --------------------------- | 1703| Promise<void> | Promise that returns no value.| 1704 1705**Example** 1706 1707```ts 1708import { audio } from '@kit.AudioKit'; 1709import { BusinessError } from '@kit.BasicServicesKit'; 1710 1711let inputAudioCapturerFilter: audio.AudioCapturerFilter = { 1712 uid : 20010041, 1713 capturerInfo : { 1714 source: audio.SourceType.SOURCE_TYPE_MIC, 1715 capturerFlags: 0 1716 } 1717}; 1718 1719let inputAudioDeviceDescriptor: audio.AudioDeviceDescriptors = [{ 1720 deviceRole : audio.DeviceRole.INPUT_DEVICE, 1721 deviceType : audio.DeviceType.MIC, 1722 id : 1, 1723 name : "", 1724 address : "", 1725 sampleRates : [44100], 1726 channelCounts : [2], 1727 channelMasks : [0], 1728 networkId : audio.LOCAL_NETWORK_ID, 1729 interruptGroupId : 1, 1730 volumeGroupId : 1, 1731 displayName : "", 1732}]; 1733 1734async function selectInputDeviceByFilter(){ 1735 let audioManager = audio.getAudioManager(); // Create an AudioManager instance. 1736 let audioRoutingManager = audioManager.getRoutingManager(); // Call an API of AudioManager to create an AudioRoutingManager instance. 1737 audioRoutingManager.selectInputDeviceByFilter(inputAudioCapturerFilter, inputAudioDeviceDescriptor).then(() => { 1738 console.info('Select input devices by filter result promise: SUCCESS'); 1739 }).catch((err: BusinessError) => { 1740 console.error(`Result ERROR: ${err}`); 1741 }) 1742} 1743``` 1744 1745### getPreferredOutputDeviceByFilter<sup>14+</sup> 1746 1747getPreferredOutputDeviceByFilter(filter: AudioRendererFilter): AudioDeviceDescriptors 1748 1749Obtains an audio output device based on the filter criteria. 1750 1751**System API**: This is a system API. 1752 1753**System capability**: SystemCapability.Multimedia.Audio.Device 1754 1755**Parameters** 1756 1757| Name | Type | Mandatory| Description | 1758| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 1759| filter | [AudioRendererFilter](#audiorendererfilter9) | Yes | Filter criteria. | 1760 1761**Return value** 1762 1763| Type | Description | 1764| --------------------- | --------------------------- | 1765| [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors)| return the device list. | 1766 1767**Example** 1768```ts 1769import { audio } from '@kit.AudioKit'; 1770import { BusinessError } from '@kit.BasicServicesKit'; 1771 1772let outputAudioRendererFilter: audio.AudioRendererFilter = { 1773 uid : 20010041, 1774 rendererInfo : { 1775 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 1776 rendererFlags : 0 1777 }, 1778 rendererId : 0 1779}; 1780 1781async function selectOutputDeviceByFilter(){ 1782 let audioManager = audio.getAudioManager(); // Create an AudioManager instance. 1783 let audioRoutingManager = audioManager.getRoutingManager(); // Call an API of AudioManager to create an AudioRoutingManager instance. 1784 let desc : audio.AudioDeviceDescriptors = audioRoutingManager.getPreferredOutputDeviceByFilter(outputAudioRendererFilter); 1785 console.info(`device descriptor: ${desc}`); 1786} 1787``` 1788 1789### getPreferredInputDeviceByFilter<sup>14+</sup> 1790 1791getPreferredInputDeviceByFilter(filter: AudioRendererFilter): AudioDeviceDescriptors 1792 1793Obtains an audio input device based on the filter criteria. Currently, only one input device can be acquired. 1794 1795**System API**: This is a system API. 1796 1797**System capability**: SystemCapability.Multimedia.Audio.Device 1798 1799**Parameters** 1800 1801| Name | Type | Mandatory| Description | 1802|---------------------| ------------------------------------------------------------ | ---- | ------------------------- | 1803| filter | [AudioCapturerFilter](#audiocapturerfilter14) | Yes | Filter criteria.| 1804 1805**Return value** 1806 1807| Type | Description | 1808| --------------------- | --------------------------- | 1809| [AudioDeviceDescriptors](js-apis-audio.md#audiodevicedescriptors) | return the device list. | 1810 1811**Example** 1812 1813```ts 1814import { audio } from '@kit.AudioKit'; 1815import { BusinessError } from '@kit.BasicServicesKit'; 1816 1817let inputAudioCapturerFilter: audio.AudioCapturerFilter = { 1818 uid : 20010041, 1819 capturerInfo : { 1820 source: audio.SourceType.SOURCE_TYPE_MIC, 1821 capturerFlags: 0 1822 } 1823}; 1824 1825async function getPreferredInputDeviceByFilter(){ 1826 let audioManager = audio.getAudioManager(); // Create an AudioManager instance. 1827 let audioRoutingManager = audioManager.getRoutingManager(); // Call an API of AudioManager to create an AudioRoutingManager instance. 1828 let desc: audio.AudioDeviceDescriptors = audioRoutingManager.getPreferredInputDeviceByFilter(inputAudioCapturerFilter); 1829 console.info(`device descriptor: ${desc}`); 1830} 1831``` 1832 1833## AudioRendererChangeInfo<sup>9+</sup> 1834 1835Describes the audio renderer change event. 1836 1837**System capability**: SystemCapability.Multimedia.Audio.Renderer 1838 1839| Name | Type | Readable| Writable| Description | 1840| -------------------| ----------------------------------------- | ---- | ---- | ---------------------------- | 1841| clientUid | number | Yes | No | UID of the audio renderer client.<br>This is a system API.| 1842| rendererState | [AudioState](js-apis-audio.md#audiostate8) | Yes | No | Audio state.<br>This is a system API.| 1843 1844## AudioCapturerChangeInfo<sup>9+</sup> 1845 1846Describes the audio capturer change event. 1847 1848**System capability**: SystemCapability.Multimedia.Audio.Capturer 1849 1850| Name | Type | Readable| Writable| Description | 1851| -------------------| ----------------------------------------- | ---- | ---- | ---------------------------- | 1852| clientUid | number | Yes | No | UID of the audio capturer client.<br>This is a system API.| 1853| capturerState | [AudioState](js-apis-audio.md#audiostate8) | Yes | No | Audio state.<br>This is a system API.| 1854 1855## AudioDeviceDescriptor 1856 1857Describes an audio device. 1858 1859| Name | Type | Readable| Writable| Description | 1860| ----------------------------- | -------------------------- | ---- | ---- | ---------- | 1861| networkId<sup>9+</sup> | string | Yes | No | ID of the device network.<br>This is a system API.<br> **System capability**: SystemCapability.Multimedia.Audio.Device| 1862| interruptGroupId<sup>9+</sup> | number | Yes | No | ID of the interruption group to which the device belongs.<br>This is a system API.<br> **System capability**: SystemCapability.Multimedia.Audio.Device| 1863| volumeGroupId<sup>9+</sup> | number | Yes | No | ID of the volume group to which the device belongs.<br>This is a system API.<br> **System capability**: SystemCapability.Multimedia.Audio.Device| 1864 1865## AudioRendererFilter<sup>9+</sup> 1866 1867Implements filter criteria. Before calling **selectOutputDeviceByFilter**, you must obtain an **AudioRendererFilter** instance. 1868 1869**System API**: This is a system API. 1870 1871| Name | Type | Mandatory| Description | 1872| -------------| ---------------------------------------- | ---- | -------------- | 1873| uid | number | No | Application ID.<br> **System capability**: SystemCapability.Multimedia.Audio.Core| 1874| rendererInfo | [AudioRendererInfo](js-apis-audio.md#audiorendererinfo8) | No | Audio renderer information.<br> **System capability**: SystemCapability.Multimedia.Audio.Renderer| 1875| rendererId | number | No | Unique ID of an audio stream.<br> **System capability**: SystemCapability.Multimedia.Audio.Renderer| 1876 1877**Example** 1878 1879```ts 1880import { audio } from '@kit.AudioKit'; 1881 1882let outputAudioRendererFilter: audio.AudioRendererFilter = { 1883 uid : 20010041, 1884 rendererInfo : { 1885 usage : audio.StreamUsage.STREAM_USAGE_MUSIC, 1886 rendererFlags : 0 1887 }, 1888 rendererId : 0 1889}; 1890``` 1891## AudioCapturerFilter<sup>14+</sup> 1892 1893Filter criteria. Before calling **selectOutputDeviceByFilter**, you must obtain an **AudioCapturerFilter** instance. 1894 1895**System API**: This is a system API. 1896 1897| Name | Type | Mandatory| Description | 1898| -------------| ---------------------------------------- | ---- | -------------- | 1899| uid | number | No | Application ID.<br> **System capability**: SystemCapability.Multimedia.Audio.Core| 1900| capturerInfo | [AudioCapturerInfo](js-apis-audio.md#audiocapturerinfo8) | No | Audio capturer information.<br> **System capability**: SystemCapability.Multimedia.Audio.Capturer| 1901 1902**Example** 1903 1904```ts 1905import { audio } from '@kit.AudioKit'; 1906 1907let inputAudioCapturerFilter: audio.AudioCapturerFilter = { 1908 uid : 20010041, 1909 capturerInfo : { 1910 source: audio.SourceType.SOURCE_TYPE_MIC, 1911 capturerFlags: 0 1912 } 1913}; 1914``` 1915 1916## AudioSpatialEnabledStateForDevice<sup>12+</sup> 1917 1918Describes the enabled status of spatial audio rendering of the device. 1919 1920**System API**: This is a system API. 1921 1922**System capability**: SystemCapability.Multimedia.Audio 1923 1924| Name | Type | Mandatory| Description | 1925| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 1926| deviceDescriptor | [AudioDeviceDescriptor](js-apis-audio.md#audiodevicedescriptor) | Yes | Descriptor of the device. | 1927| enabled | boolean | Yes | Whether spatial audio rendering or head tracking is enabled. The value **true** means that it is enabled, and **false** means the opposite. | 1928 1929## AudioSpatializationManager<sup>11+</sup> 1930 1931Implements spatial audio management. Before calling an API in **AudioSpatializationManager**, you must use [getSpatializationManager](#getspatializationmanager11) to obtain an **AudioSpatializationManager** instance. 1932 1933### isSpatializationSupported<sup>11+</sup> 1934 1935isSpatializationSupported(): boolean 1936 1937Checks whether the system supports spatial audio rendering. This API returns the result synchronously. 1938 1939**System API**: This is a system API. 1940 1941**System capability**: SystemCapability.Multimedia.Audio.Spatialization 1942 1943**Return value** 1944 1945| Type | Description | 1946| ---------------------- | ------------------------------------------------------------ | 1947| boolean | Returns **true** if the system supports spatial audio rendering, and returns **false** otherwise.| 1948 1949**Error codes** 1950 1951For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 1952 1953| ID| Error Message| 1954| ------- | --------------------------------------------| 1955| 202 | Not system App. | 1956 1957**Example** 1958 1959```ts 1960import { audio } from '@kit.AudioKit'; 1961import { BusinessError } from '@kit.BasicServicesKit'; 1962try { 1963 let isSpatializationSupported: boolean = audioSpatializationManager.isSpatializationSupported(); 1964 console.info(`AudioSpatializationManager isSpatializationSupported: ${isSpatializationSupported}`); 1965} catch (err) { 1966 let error = err as BusinessError; 1967 console.error(`ERROR: ${error}`); 1968} 1969``` 1970 1971### isSpatializationSupportedForDevice<sup>11+</sup> 1972 1973isSpatializationSupportedForDevice(deviceDescriptor: AudioDeviceDescriptor): boolean 1974 1975Checks whether a device supports spatial audio rendering. This API returns the result synchronously. 1976 1977**System API**: This is a system API. 1978 1979**System capability**: SystemCapability.Multimedia.Audio.Spatialization 1980 1981**Parameters** 1982 1983| Name | Type | Mandatory| Description | 1984| ---------- | ------------------------------------------------------------ | ---- | -------------------- | 1985| deviceDescriptor | [AudioDeviceDescriptor](js-apis-audio.md#audiodevicedescriptor) | Yes | Descriptor of the device. | 1986 1987**Return value** 1988 1989| Type | Description | 1990| ---------------------- | ------------------------------------------------------------ | 1991| boolean | Returns **true** if the device supports spatial audio rendering, and returns **false** otherwise.| 1992 1993**Error codes** 1994 1995For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 1996 1997| ID| Error Message| 1998| ------- | --------------------------------------------| 1999| 202 | Not system App. | 2000| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2001| 6800101 | Parameter verification failed. | 2002 2003**Example** 2004 2005```ts 2006import { audio } from '@kit.AudioKit'; 2007import { BusinessError } from '@kit.BasicServicesKit'; 2008 2009let deviceDescriptor: audio.AudioDeviceDescriptor = { 2010 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 2011 deviceType : audio.DeviceType.BLUETOOTH_A2DP, 2012 id : 1, 2013 name : "", 2014 address : "123", 2015 sampleRates : [44100], 2016 channelCounts : [2], 2017 channelMasks : [0], 2018 networkId : audio.LOCAL_NETWORK_ID, 2019 interruptGroupId : 1, 2020 volumeGroupId : 1, 2021 displayName : "" 2022}; 2023 2024try { 2025 let isSpatializationSupportedForDevice: boolean = audioSpatializationManager.isSpatializationSupportedForDevice(deviceDescriptor); 2026 console.info(`AudioSpatializationManager isSpatializationSupportedForDevice: ${isSpatializationSupportedForDevice}`); 2027} catch (err) { 2028 let error = err as BusinessError; 2029 console.error(`ERROR: ${error}`); 2030} 2031``` 2032 2033### isHeadTrackingSupported<sup>11+</sup> 2034 2035isHeadTrackingSupported(): boolean 2036 2037Checks whether the system supports head tracking. This API returns the result synchronously. 2038 2039**System API**: This is a system API. 2040 2041**System capability**: SystemCapability.Multimedia.Audio.Spatialization 2042 2043**Return value** 2044 2045| Type | Description | 2046| ---------------------- | ------------------------------------------------------------ | 2047| boolean | Returns **true** if the system supports head tracking, and returns **false** otherwise.| 2048 2049**Error codes** 2050 2051For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2052 2053| ID| Error Message| 2054| ------- | --------------------------------------------| 2055| 202 | Not system App. | 2056 2057**Example** 2058 2059```ts 2060import { audio } from '@kit.AudioKit'; 2061import { BusinessError } from '@kit.BasicServicesKit'; 2062 2063try { 2064 let isHeadTrackingSupported: boolean = audioSpatializationManager.isHeadTrackingSupported(); 2065 console.info(`AudioSpatializationManager isHeadTrackingSupported: ${isHeadTrackingSupported}`); 2066} catch (err) { 2067 let error = err as BusinessError; 2068 console.error(`ERROR: ${error}`); 2069} 2070``` 2071 2072### isHeadTrackingSupportedForDevice<sup>11+</sup> 2073 2074isHeadTrackingSupportedForDevice(deviceDescriptor: AudioDeviceDescriptor): boolean 2075 2076Checks whether a device supports head tracking. This API returns the result synchronously. 2077 2078**System API**: This is a system API. 2079 2080**System capability**: SystemCapability.Multimedia.Audio.Spatialization 2081 2082**Parameters** 2083 2084| Name | Type | Mandatory| Description | 2085| ---------- | ------------------------------------------------------------ | ---- | -------------------- | 2086| deviceDescriptor | [AudioDeviceDescriptor](js-apis-audio.md#audiodevicedescriptor) | Yes | Descriptor of the device. | 2087 2088**Return value** 2089 2090| Type | Description | 2091| ---------------------- | ------------------------------------------------------------ | 2092| boolean | Returns **true** if the device supports head tracking, and returns **false** otherwise.| 2093 2094**Error codes** 2095 2096For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2097 2098| ID| Error Message| 2099| ------- | --------------------------------------------| 2100| 202 | Not system App. | 2101| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2102| 6800101 | Parameter verification failed. | 2103 2104**Example** 2105 2106```ts 2107import { audio } from '@kit.AudioKit'; 2108import { BusinessError } from '@kit.BasicServicesKit'; 2109 2110let deviceDescriptor: audio.AudioDeviceDescriptor = { 2111 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 2112 deviceType : audio.DeviceType.BLUETOOTH_A2DP, 2113 id : 1, 2114 name : "", 2115 address : "123", 2116 sampleRates : [44100], 2117 channelCounts : [2], 2118 channelMasks : [0], 2119 networkId : audio.LOCAL_NETWORK_ID, 2120 interruptGroupId : 1, 2121 volumeGroupId : 1, 2122 displayName : "" 2123}; 2124 2125try { 2126 let isHeadTrackingSupportedForDevice: boolean = audioSpatializationManager.isHeadTrackingSupportedForDevice(deviceDescriptor); 2127 console.info(`AudioSpatializationManager isHeadTrackingSupportedForDevice: ${isHeadTrackingSupportedForDevice}`); 2128} catch (err) { 2129 let error = err as BusinessError; 2130 console.error(`ERROR: ${error}`); 2131} 2132``` 2133 2134### setSpatializationEnabled<sup>(deprecated)</sup> 2135 2136setSpatializationEnabled(enable: boolean, callback: AsyncCallback<void>): void 2137 2138Enables or disables spatial audio rendering. This API uses an asynchronous callback to return the result. 2139 2140> **NOTE** 2141> 2142> This API is supported since API version 11 and deprecated since API version 12. You are advised to use [setSpatializationEnabled(deviceDescriptor: AudioDeviceDescriptor, enabled: boolean): Promise\<void>](#setspatializationenabled12) instead. 2143 2144**Required permissions**: ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 2145 2146**System API**: This is a system API. 2147 2148**System capability**: SystemCapability.Multimedia.Audio.Spatialization 2149 2150**Parameters** 2151 2152| Name | Type | Mandatory| Description | 2153| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 2154| enable | boolean | Yes | Whether to enable or disable spatial audio rendering. The value **true** means to enable spatial audio rendering, and **false** means the opposite. | 2155| callback | AsyncCallback<void> | Yes | Callback that returns no value.| 2156 2157**Error codes** 2158 2159For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2160 2161| ID| Error Message| 2162| ------- | --------------------------------------------| 2163| 201 | Permission denied. Return by callback. | 2164| 202 | Not system App. | 2165| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2166| 6800101 | Parameter verification failed. | 2167 2168**Example** 2169```ts 2170import { audio } from '@kit.AudioKit'; 2171import { BusinessError } from '@kit.BasicServicesKit'; 2172 2173let enable: boolean = true; 2174 2175audioSpatializationManager.setSpatializationEnabled(enable, (err: BusinessError) => { 2176 if (err) { 2177 console.error(`Result ERROR: ${err}`); 2178 } else { 2179 console.info(`setSpatializationEnabled success`); 2180 } 2181}); 2182``` 2183 2184### setSpatializationEnabled<sup>(deprecated)</sup> 2185 2186setSpatializationEnabled(enable: boolean): Promise<void> 2187 2188Enables or disables spatial audio rendering. This API uses a promise to return the result. 2189 2190> **NOTE** 2191> 2192> This API is supported since API version 11 and deprecated since API version 12. You are advised to use [setSpatializationEnabled(deviceDescriptor: AudioDeviceDescriptor, enabled: boolean): Promise\<void>](#setspatializationenabled12) instead. 2193 2194**Required permissions**: ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 2195 2196**System API**: This is a system API. 2197 2198**System capability**: SystemCapability.Multimedia.Audio.Spatialization 2199 2200**Parameters** 2201 2202| Name | Type | Mandatory| Description | 2203| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 2204| enable | boolean | Yes | Whether to enable or disable spatial audio rendering. The value **true** means to enable spatial audio rendering, and **false** means the opposite. | 2205 2206**Return value** 2207 2208| Type | Description | 2209| --------------------- | --------------------------- | 2210| Promise<void> | Promise that returns no value.| 2211 2212**Error codes** 2213 2214For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2215 2216| ID| Error Message| 2217| ------- | --------------------------------------------| 2218| 201 | Permission denied. Return by promise. | 2219| 202 | Not system App. | 2220| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2221 2222**Example** 2223 2224```ts 2225import { audio } from '@kit.AudioKit'; 2226import { BusinessError } from '@kit.BasicServicesKit'; 2227 2228let enable: boolean = true; 2229 2230audioSpatializationManager.setSpatializationEnabled(enable).then(() => { 2231 console.info(`setSpatializationEnabled success`); 2232}).catch((err: BusinessError) => { 2233 console.error(`Result ERROR: ${err}`); 2234}); 2235``` 2236### setSpatializationEnabled<sup>12+</sup> 2237 2238setSpatializationEnabled(deviceDescriptor: AudioDeviceDescriptor, enabled: boolean): Promise<void> 2239 2240Enables or disables spatial audio rendering for a device. This API uses a promise to return the result. 2241 2242**Required permissions**: ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 2243 2244**System API**: This is a system API. 2245 2246**System capability**: SystemCapability.Multimedia.Audio.Spatialization 2247 2248**Parameters** 2249 2250| Name | Type | Mandatory| Description | 2251| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 2252| deviceDescriptor | [AudioDeviceDescriptor](js-apis-audio.md#audiodevicedescriptor) | Yes | Descriptor of the device. | 2253| enabled | boolean | Yes | Whether to enable or disable spatial audio rendering. The value **true** means to enable spatial audio rendering, and **false** means the opposite. | 2254 2255**Return value** 2256 2257| Type | Description | 2258| --------------------- | --------------------------- | 2259| Promise<void> | Promise that returns no value.| 2260 2261**Error codes** 2262 2263For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2264 2265| ID| Error Message| 2266| ------- | --------------------------------------------| 2267| 201 | Permission denied. Return by promise. | 2268| 202 | Not system App. | 2269| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2270| 6800101 | Parameter verification failed. | 2271 2272 2273**Example** 2274 2275```ts 2276import { audio } from '@kit.AudioKit'; 2277import { BusinessError } from '@kit.BasicServicesKit'; 2278 2279let deviceDescriptor: audio.AudioDeviceDescriptor = { 2280 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 2281 deviceType : audio.DeviceType.BLUETOOTH_A2DP, 2282 id : 1, 2283 name : "", 2284 address : "123", 2285 sampleRates : [44100], 2286 channelCounts : [2], 2287 channelMasks : [0], 2288 networkId : audio.LOCAL_NETWORK_ID, 2289 interruptGroupId : 1, 2290 volumeGroupId : 1, 2291 displayName : "" 2292}; 2293let enabled: boolean = true; 2294 2295audioSpatializationManager.setSpatializationEnabled(deviceDescriptor, enabled).then(() => { 2296 console.info(`setSpatializationEnabled success`); 2297}).catch((err: BusinessError) => { 2298 console.error(`Result ERROR: ${err}`); 2299}); 2300``` 2301 2302### isSpatializationEnabled<sup>(deprecated)</sup> 2303 2304isSpatializationEnabled(): boolean 2305 2306Checks whether spatial audio rendering is enabled. This API returns the result synchronously. 2307 2308> **NOTE** 2309> 2310> This API is supported since API version 11 and deprecated since API version 12. You are advised to use [isSpatializationEnabled(deviceDescriptor: AudioDeviceDescriptor): boolean](#isspatializationenabled12) instead. 2311 2312**System API**: This is a system API. 2313 2314**System capability**: SystemCapability.Multimedia.Audio.Spatialization 2315 2316**Return value** 2317 2318| Type | Description | 2319| ---------------------- | ------------------------------------------------------------ | 2320| boolean | Returns **true** if spatial audio rendering is enabled, and returns **false** otherwise.| 2321 2322**Error codes** 2323 2324For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2325 2326| ID| Error Message| 2327| ------- | --------------------------------------------| 2328| 202 | Not system App. | 2329 2330**Example** 2331 2332```ts 2333import { audio } from '@kit.AudioKit'; 2334import { BusinessError } from '@kit.BasicServicesKit'; 2335 2336try { 2337 let isSpatializationEnabled: boolean = audioSpatializationManager.isSpatializationEnabled(); 2338 console.info(`AudioSpatializationManager isSpatializationEnabled: ${isSpatializationEnabled}`); 2339} catch (err) { 2340 let error = err as BusinessError; 2341 console.error(`ERROR: ${error}`); 2342} 2343``` 2344 2345### isSpatializationEnabled<sup>12+</sup> 2346 2347isSpatializationEnabled(deviceDescriptor: AudioDeviceDescriptor): boolean 2348 2349Checks whether spatial audio rendering is enabled. This API returns the result synchronously. 2350 2351**System API**: This is a system API. 2352 2353**System capability**: SystemCapability.Multimedia.Audio.Spatialization 2354 2355**Parameters** 2356 2357| Name | Type | Mandatory| Description | 2358| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 2359| deviceDescriptor | [AudioDeviceDescriptor](js-apis-audio.md#audiodevicedescriptor) | Yes | Descriptor of the device. | 2360 2361**Return value** 2362 2363| Type | Description | 2364| ---------------------- | ------------------------------------------------------------ | 2365| boolean | Returns **true** if spatial audio rendering is enabled for the device, and returns **false** otherwise.| 2366 2367**Error codes** 2368 2369For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2370 2371| ID| Error Message| 2372| ------- | --------------------------------------------| 2373| 202 | Not system App. | 2374| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2375| 6800101 | Parameter verification failed. | 2376 2377**Example** 2378 2379```ts 2380import { audio } from '@kit.AudioKit'; 2381import { BusinessError } from '@kit.BasicServicesKit'; 2382 2383let deviceDescriptor: audio.AudioDeviceDescriptor = { 2384 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 2385 deviceType : audio.DeviceType.BLUETOOTH_A2DP, 2386 id : 1, 2387 name : "", 2388 address : "123", 2389 sampleRates : [44100], 2390 channelCounts : [2], 2391 channelMasks : [0], 2392 networkId : audio.LOCAL_NETWORK_ID, 2393 interruptGroupId : 1, 2394 volumeGroupId : 1, 2395 displayName : "" 2396}; 2397 2398try { 2399 let isSpatializationEnabled: boolean = audioSpatializationManager.isSpatializationEnabled(deviceDescriptor); 2400 console.info(`AudioSpatializationManager isSpatializationEnabled: ${isSpatializationEnabled}`); 2401} catch (err) { 2402 let error = err as BusinessError; 2403 console.error(`ERROR: ${error}`); 2404} 2405``` 2406 2407### on('spatializationEnabledChange')<sup>(deprecated)</sup> 2408 2409on(type: 'spatializationEnabledChange', callback: Callback<boolean\>): void 2410 2411Subscribes to the spatial audio rendering status change event, which is triggered when the spatial audio rendering status is changed. This API uses an asynchronous callback to return the result. 2412 2413> **NOTE** 2414> 2415> This API is supported since API version 11 and deprecated since API version 12. You are advised to use [on(type: 'spatializationEnabledChangeForAnyDevice', callback: Callback<AudioSpatialEnabledStateForDevice\>): void](#onspatializationenabledchangeforanydevice12) instead. 2416 2417**System API**: This is a system API. 2418 2419**System capability**: SystemCapability.Multimedia.Audio.Spatialization 2420 2421**Parameters** 2422 2423| Name | Type | Mandatory| Description | 2424| :------- | :--------------------------------------------------- | :--- |:---------------------------------------------| 2425| type | string | Yes | Event type. The value is fixed at **'spatializationEnabledChange'**.| 2426| callback | Callback<boolean\> | Yes | Callback used to return the status of spatial audio rendering. The value **true** means that spatial audio rendering is enabled, and **false** means the opposite. | 2427 2428**Error codes** 2429 2430For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2431 2432| ID| Error Message| 2433| ------- | --------------------------------------------| 2434| 202 | Not system App. | 2435| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2436| 6800101 | Parameter verification failed. | 2437 2438**Example** 2439 2440```ts 2441import { audio } from '@kit.AudioKit'; 2442 2443audioSpatializationManager.on('spatializationEnabledChange', (isSpatializationEnabled: boolean) => { 2444 console.info(`isSpatializationEnabled: ${isSpatializationEnabled}`); 2445}); 2446``` 2447 2448### on('spatializationEnabledChangeForAnyDevice')<sup>12+</sup> 2449 2450on(type: 'spatializationEnabledChangeForAnyDevice', callback: Callback<AudioSpatialEnabledStateForDevice\>): void 2451 2452Subscribes to the spatial audio rendering status change event, which is triggered when the spatial audio rendering status is changed. This API uses an asynchronous callback to return the result. 2453 2454**System API**: This is a system API. 2455 2456**System capability**: SystemCapability.Multimedia.Audio.Spatialization 2457 2458**Parameters** 2459 2460| Name | Type | Mandatory| Description | 2461| :------- | :--------------------------------------------------- | :--- |:---------------------------------------------| 2462| type | string | Yes | Event type. The value is fixed at **'spatializationEnabledChangeForAnyDevice'**.| 2463| callback | Callback\<[AudioSpatialEnabledStateForDevice](#audiospatialenabledstatefordevice12)> | Yes | Callback used to return the device information and the enabled status of spatial audio rendering. | 2464 2465**Error codes** 2466 2467For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2468 2469| ID| Error Message| 2470| ------- | --------------------------------------------| 2471| 202 | Not system App. | 2472| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2473| 6800101 | Parameter verification failed. | 2474 2475**Example** 2476 2477```ts 2478import { audio } from '@kit.AudioKit'; 2479 2480audioSpatializationManager.on('spatializationEnabledChangeForAnyDevice', (audioSpatialEnabledStateForDevice: audio.AudioSpatialEnabledStateForDevice) => { 2481 console.info(`deviceDescriptor: ${audioSpatialEnabledStateForDevice.deviceDescriptor}`); 2482 console.info(`isSpatializationEnabled: ${audioSpatialEnabledStateForDevice.enabled}`); 2483}); 2484``` 2485 2486### off('spatializationEnabledChange')<sup>(deprecated)</sup> 2487 2488off(type: 'spatializationEnabledChange', callback?: Callback<boolean\>): void 2489 2490Unsubscribes from the spatial audio rendering status change event. This API uses an asynchronous callback to return the result. 2491 2492> **NOTE** 2493> 2494> This API is supported since API version 11 and deprecated since API version 12. You are advised to use [off(type: 'spatializationEnabledChangeForAnyDevice', callback: Callback<AudioSpatialEnabledStateForDevice\>): void](#offspatializationenabledchangeforanydevice12) instead. 2495 2496**System API**: This is a system API. 2497 2498**System capability**: SystemCapability.Multimedia.Audio.Spatialization 2499 2500**Parameters** 2501 2502| Name | Type | Mandatory| Description | 2503| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 2504| type | string | Yes | Event type. The value is fixed at **'spatializationEnabledChange'**.| 2505| callback | Callback<boolean\> | No | Callback used to return the status of spatial audio rendering. The value **true** means that spatial audio rendering is enabled, and **false** means the opposite.| 2506 2507**Error codes** 2508 2509For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2510 2511| ID| Error Message| 2512| ------- | --------------------------------------------| 2513| 202 | Not system App. | 2514| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2515| 6800101 | Parameter verification failed. | 2516 2517**Example** 2518 2519```ts 2520// Cancel all subscriptions to the event. 2521audioSpatializationManager.off('spatializationEnabledChange'); 2522 2523// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 2524let spatializationEnabledChangeCallback = (isSpatializationEnabled: boolean) => { 2525 console.info(`isSpatializationEnabled: ${isSpatializationEnabled}`); 2526}; 2527 2528audioSpatializationManager.on('spatializationEnabledChange', spatializationEnabledChangeCallback); 2529 2530audioSpatializationManager.off('spatializationEnabledChange', spatializationEnabledChangeCallback); 2531``` 2532 2533### off('spatializationEnabledChangeForAnyDevice')<sup>12+</sup> 2534 2535off(type: 'spatializationEnabledChangeForAnyDevice', callback?: Callback<AudioSpatialEnabledStateForDevice\>): void 2536 2537Unsubscribes from the spatial audio rendering status change event. This API uses an asynchronous callback to return the result. 2538 2539**System API**: This is a system API. 2540 2541**System capability**: SystemCapability.Multimedia.Audio.Spatialization 2542 2543**Parameters** 2544 2545| Name | Type | Mandatory| Description | 2546| :------- | :--------------------------------------------------- | :--- |:---------------------------------------------| 2547| type | string | Yes | Event type. The value is fixed at **'spatializationEnabledChangeForAnyDevice'**.| 2548| callback | Callback\<[AudioSpatialEnabledStateForDevice](#audiospatialenabledstatefordevice12)> | Yes | Callback used to return the device information and the enabled status of spatial audio rendering.| 2549 2550**Error codes** 2551 2552For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2553 2554| ID| Error Message| 2555| ------- | --------------------------------------------| 2556| 202 | Not system App. | 2557| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2558| 6800101 | Parameter verification failed. | 2559 2560**Example** 2561 2562```ts 2563import { audio } from '@kit.AudioKit'; 2564 2565// Cancel all subscriptions to the event. 2566audioSpatializationManager.off('spatializationEnabledChangeForAnyDevice'); 2567 2568// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 2569let spatializationEnabledChangeForAnyDeviceCallback = (audioSpatialEnabledStateForDevice: audio.AudioSpatialEnabledStateForDevice) => { 2570 console.info(`deviceDescriptor: ${audioSpatialEnabledStateForDevice.deviceDescriptor}`); 2571 console.info(`isSpatializationEnabled: ${audioSpatialEnabledStateForDevice.enabled}`); 2572}; 2573 2574audioSpatializationManager.on('spatializationEnabledChangeForAnyDevice', spatializationEnabledChangeForAnyDeviceCallback); 2575 2576audioSpatializationManager.off('spatializationEnabledChangeForAnyDevice', spatializationEnabledChangeForAnyDeviceCallback); 2577``` 2578 2579### setHeadTrackingEnabled<sup>(deprecated)</sup> 2580 2581setHeadTrackingEnabled(enable: boolean, callback: AsyncCallback<void>): void 2582 2583Enables or disables head tracking. This API uses an asynchronous callback to return the result. 2584 2585> **NOTE** 2586> 2587> This API is supported since API version 11 and deprecated since API version 12. You are advised to use [setHeadTrackingEnabled(deviceDescriptor: AudioDeviceDescriptor, enabled: boolean): Promise\<void>](#setheadtrackingenabled12) instead. 2588 2589**Required permissions**: ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 2590 2591**System API**: This is a system API. 2592 2593**System capability**: SystemCapability.Multimedia.Audio.Spatialization 2594 2595**Parameters** 2596 2597| Name | Type | Mandatory| Description | 2598| --------------------------- | ------------------------------------------------------------ | ---- | ------------------------- | 2599| enable | boolean | Yes | Whether to enable or disable head tracking. The value **true** means to enable head tracking, and **false** means the opposite. | 2600| callback | AsyncCallback<void> | Yes | Callback that returns no value.| 2601 2602**Error codes** 2603 2604For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2605 2606| ID| Error Message| 2607| ------- | --------------------------------------------| 2608| 201 | Permission denied. Return by callback. | 2609| 202 | Not system App. | 2610| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2611| 6800101 | Parameter verification failed. | 2612 2613**Example** 2614```ts 2615import { audio } from '@kit.AudioKit'; 2616import { BusinessError } from '@kit.BasicServicesKit'; 2617 2618let enable: boolean = true; 2619 2620audioSpatializationManager.setHeadTrackingEnabled(enable, (err: BusinessError) => { 2621 if (err) { 2622 console.error(`Result ERROR: ${err}`); 2623 } else { 2624 console.info(`setHeadTrackingEnabled success`); 2625 } 2626}); 2627``` 2628 2629### setHeadTrackingEnabled<sup>(deprecated)</sup> 2630 2631setHeadTrackingEnabled(enable: boolean): Promise<void> 2632 2633Enables or disables head tracking. This API uses a promise to return the result. 2634 2635> **NOTE** 2636> 2637> This API is supported since API version 11 and deprecated since API version 12. You are advised to use [setHeadTrackingEnabled(deviceDescriptor: AudioDeviceDescriptor, enabled: boolean): Promise\<void>](#setheadtrackingenabled12) instead. 2638 2639**Required permissions**: ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 2640 2641**System API**: This is a system API. 2642 2643**System capability**: SystemCapability.Multimedia.Audio.Spatialization 2644 2645**Parameters** 2646 2647| Name | Type | Mandatory| Description | 2648| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 2649| enable | boolean | Yes | Whether to enable or disable head tracking. The value **true** means to enable head tracking, and **false** means the opposite. | 2650 2651**Return value** 2652 2653| Type | Description | 2654| --------------------- | --------------------------- | 2655| Promise<void> | Promise that returns no value.| 2656 2657**Error codes** 2658 2659For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2660 2661| ID| Error Message| 2662| ------- | --------------------------------------------| 2663| 201 | Permission denied. Return by promise. | 2664| 202 | Not system App. | 2665| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2666 2667**Example** 2668 2669```ts 2670import { audio } from '@kit.AudioKit'; 2671import { BusinessError } from '@kit.BasicServicesKit'; 2672 2673let enable: boolean = true; 2674 2675audioSpatializationManager.setHeadTrackingEnabled(enable).then(() => { 2676 console.info(`setHeadTrackingEnabled success`); 2677}).catch((err: BusinessError) => { 2678 console.error(`Result ERROR: ${err}`); 2679}); 2680``` 2681 2682### setHeadTrackingEnabled<sup>12+</sup> 2683 2684setHeadTrackingEnabled(enable: boolean): Promise<void> 2685 2686Enables or disables head tracking for a device. This API uses a promise to return the result. 2687 2688**Required permissions**: ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 2689 2690**System API**: This is a system API. 2691 2692**System capability**: SystemCapability.Multimedia.Audio.Spatialization 2693 2694**Parameters** 2695 2696| Name | Type | Mandatory| Description | 2697| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 2698| deviceDescriptor | [AudioDeviceDescriptor](js-apis-audio.md#audiodevicedescriptor) | Yes | Descriptor of the device. | 2699| enable | boolean | Yes | Whether to enable or disable head tracking. The value **true** means to enable head tracking, and **false** means the opposite. | 2700 2701**Return value** 2702 2703| Type | Description | 2704| --------------------- | --------------------------- | 2705| Promise<void> | Promise that returns no value.| 2706 2707**Error codes** 2708 2709For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2710 2711| ID| Error Message| 2712| ------- | --------------------------------------------| 2713| 201 | Permission denied. Return by promise. | 2714| 202 | Not system App. | 2715| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2716| 6800101 | Parameter verification failed. | 2717 2718**Example** 2719 2720```ts 2721import { audio } from '@kit.AudioKit'; 2722import { BusinessError } from '@kit.BasicServicesKit'; 2723 2724let deviceDescriptor: audio.AudioDeviceDescriptor = { 2725 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 2726 deviceType : audio.DeviceType.BLUETOOTH_A2DP, 2727 id : 1, 2728 name : "", 2729 address : "123", 2730 sampleRates : [44100], 2731 channelCounts : [2], 2732 channelMasks : [0], 2733 networkId : audio.LOCAL_NETWORK_ID, 2734 interruptGroupId : 1, 2735 volumeGroupId : 1, 2736 displayName : "" 2737}; 2738let enable: boolean = true; 2739 2740audioSpatializationManager.setHeadTrackingEnabled(deviceDescriptor, enable).then(() => { 2741 console.info(`setHeadTrackingEnabled success`); 2742}).catch((err: BusinessError) => { 2743 console.error(`Result ERROR: ${err}`); 2744}); 2745``` 2746 2747### isHeadTrackingEnabled<sup>(deprecated)</sup> 2748 2749isHeadTrackingEnabled(): boolean 2750 2751Checks whether head tracking is enabled. This API returns the result synchronously. 2752 2753> **NOTE** 2754> 2755> This API is supported since API version 11 and deprecated since API version 12. You are advised to use [isHeadTrackingEnabled(deviceDescriptor: AudioDeviceDescriptor): boolean](#isheadtrackingenabled12) instead. 2756 2757**System API**: This is a system API. 2758 2759**System capability**: SystemCapability.Multimedia.Audio.Spatialization 2760 2761**Return value** 2762 2763| Type | Description | 2764| ---------------------- | ------------------------------------------------------------ | 2765| boolean | Returns **true** if head tracking is enabled, and returns **false** otherwise.| 2766 2767**Error codes** 2768 2769For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2770 2771| ID| Error Message| 2772| ------- | --------------------------------------------| 2773| 202 | Not system App. | 2774 2775**Example** 2776 2777```ts 2778import { audio } from '@kit.AudioKit'; 2779import { BusinessError } from '@kit.BasicServicesKit'; 2780 2781try { 2782 let isHeadTrackingEnabled: boolean = audioSpatializationManager.isHeadTrackingEnabled(); 2783 console.info(`AudioSpatializationManager isHeadTrackingEnabled: ${isHeadTrackingEnabled}`); 2784} catch (err) { 2785 let error = err as BusinessError; 2786 console.error(`ERROR: ${error}`); 2787} 2788``` 2789 2790### isHeadTrackingEnabled<sup>12+</sup> 2791 2792isHeadTrackingEnabled(): boolean 2793 2794Checks whether head tracking is enabled for a device. This API returns the result synchronously. 2795 2796**System API**: This is a system API. 2797 2798**System capability**: SystemCapability.Multimedia.Audio.Spatialization 2799 2800**Parameters** 2801 2802| Name | Type | Mandatory| Description | 2803| ----------------------| ------------------------------------------------------------ | ---- | ------------------------- | 2804| deviceDescriptor | [AudioDeviceDescriptor](js-apis-audio.md#audiodevicedescriptor) | Yes | Descriptor of the device. | 2805 2806**Return value** 2807 2808| Type | Description | 2809| ---------------------- | ------------------------------------------------------------ | 2810| boolean | Returns **true** if head tracking is enabled for the device, and returns **false** otherwise.| 2811 2812**Error codes** 2813 2814For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2815 2816| ID| Error Message| 2817| ------- | --------------------------------------------| 2818| 202 | Not system App. | 2819| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2820| 6800101 | Parameter verification failed. | 2821 2822**Example** 2823 2824```ts 2825import { audio } from '@kit.AudioKit'; 2826import { BusinessError } from '@kit.BasicServicesKit'; 2827 2828let deviceDescriptor: audio.AudioDeviceDescriptor = { 2829 deviceRole : audio.DeviceRole.OUTPUT_DEVICE, 2830 deviceType : audio.DeviceType.BLUETOOTH_A2DP, 2831 id : 1, 2832 name : "", 2833 address : "123", 2834 sampleRates : [44100], 2835 channelCounts : [2], 2836 channelMasks : [0], 2837 networkId : audio.LOCAL_NETWORK_ID, 2838 interruptGroupId : 1, 2839 volumeGroupId : 1, 2840 displayName : "" 2841}; 2842 2843try { 2844 let isHeadTrackingEnabled: boolean = audioSpatializationManager.isHeadTrackingEnabled(deviceDescriptor); 2845 console.info(`AudioSpatializationManager isHeadTrackingEnabled: ${isHeadTrackingEnabled}`); 2846} catch (err) { 2847 let error = err as BusinessError; 2848 console.error(`ERROR: ${error}`); 2849} 2850``` 2851 2852### on('headTrackingEnabledChange')<sup>(deprecated)</sup> 2853 2854on(type: 'headTrackingEnabledChange', callback: Callback<boolean\>): void 2855 2856Subscribes to the head tracking status change event, which is triggered when the head tracking status is changed. This API uses an asynchronous callback to return the result. 2857 2858> **NOTE** 2859> 2860> This API is supported since API version 11 and deprecated since API version 12. You are advised to use [on(type: 'headTrackingEnabledChangeForAnyDevice', callback: Callback<AudioSpatialEnabledStateForDevice\>): void](#onheadtrackingenabledchangeforanydevice12) instead. 2861 2862**System API**: This is a system API. 2863 2864**System capability**: SystemCapability.Multimedia.Audio.Spatialization 2865 2866**Parameters** 2867 2868| Name | Type | Mandatory| Description | 2869| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- | 2870| type | string | Yes | Event type. The value is fixed at **'headTrackingEnabledChange'**.| 2871| callback | Callback<boolean\> | Yes | Callback used to return the status of head tracking. The value **true** means that head tracking is enabled, and **false** means the opposite.| 2872 2873**Error codes** 2874 2875For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2876 2877| ID| Error Message| 2878| ------- | --------------------------------------------| 2879| 202 | Not system App. | 2880| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2881| 6800101 | Parameter verification failed. | 2882 2883**Example** 2884 2885```ts 2886import { audio } from '@kit.AudioKit'; 2887 2888audioSpatializationManager.on('headTrackingEnabledChange', (isHeadTrackingEnabled: boolean) => { 2889 console.info(`isHeadTrackingEnabled: ${isHeadTrackingEnabled}`); 2890}); 2891``` 2892 2893### on('headTrackingEnabledChangeForAnyDevice')<sup>12+</sup> 2894 2895on(type: 'headTrackingEnabledChangeForAnyDevice', callback: Callback<AudioSpatialEnabledStateForDevice\>): void 2896 2897Subscribes to the head tracking status change event, which is triggered when the head tracking status is changed. This API uses an asynchronous callback to return the result. 2898 2899**System API**: This is a system API. 2900 2901**System capability**: SystemCapability.Multimedia.Audio.Spatialization 2902 2903**Parameters** 2904 2905| Name | Type | Mandatory| Description | 2906| :------- | :--------------------------------------------------- | :--- | :----------------------------------------- | 2907| type | string | Yes | Event type. The value is fixed at **'headTrackingEnabledChangeForAnyDevice'**.| 2908| callback | Callback\<[AudioSpatialEnabledStateForDevice](#audiospatialenabledstatefordevice12)> | Yes | Callback used to return the device information and the enabled status of head tracking. | 2909 2910**Error codes** 2911 2912For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2913 2914| ID| Error Message| 2915| ------- | --------------------------------------------| 2916| 202 | Not system App. | 2917| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2918| 6800101 | Parameter verification failed. | 2919 2920**Example** 2921 2922```ts 2923import { audio } from '@kit.AudioKit'; 2924 2925audioSpatializationManager.on('headTrackingEnabledChangeForAnyDevice', (audioSpatialEnabledStateForDevice: audio.AudioSpatialEnabledStateForDevice) => { 2926 console.info(`deviceDescriptor: ${audioSpatialEnabledStateForDevice.deviceDescriptor}`); 2927 console.info(`isSpatializationEnabled: ${audioSpatialEnabledStateForDevice.enabled}`); 2928}); 2929``` 2930 2931### off('headTrackingEnabledChange')<sup>(deprecated)</sup> 2932 2933off(type: 'headTrackingEnabledChange', callback?: Callback<boolean\>): void 2934 2935Unsubscribes from the head tracking status change event. This API uses an asynchronous callback to return the result. 2936 2937> **NOTE** 2938> 2939> This API is supported since API version 11 and deprecated since API version 12. You are advised to use [off(type: 'headTrackingEnabledChangeForAnyDevice', callback: Callback<AudioSpatialEnabledStateForDevice\>): void](#offheadtrackingenabledchangeforanydevice12) instead. 2940 2941**System API**: This is a system API. 2942 2943**System capability**: SystemCapability.Multimedia.Audio.Spatialization 2944 2945**Parameters** 2946 2947| Name | Type | Mandatory| Description | 2948| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 2949| type | string | Yes | Event type. The value is fixed at **'headTrackingEnabledChange'**.| 2950| callback | Callback<boolean\> | No | Callback used to return the status of head tracking. The value **true** means that head tracking is enabled, and **false** means the opposite.| 2951 2952**Error codes** 2953 2954For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 2955 2956| ID| Error Message| 2957| ------- | --------------------------------------------| 2958| 202 | Not system App. | 2959| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 2960| 6800101 | Parameter verification failed. | 2961 2962**Example** 2963 2964```ts 2965import { audio } from '@kit.AudioKit'; 2966 2967// Cancel all subscriptions to the event. 2968audioSpatializationManager.off('headTrackingEnabledChange'); 2969 2970// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 2971let headTrackingEnabledChangeCallback = (isHeadTrackingEnabled: boolean) => { 2972 console.info(`isHeadTrackingEnabled: ${isHeadTrackingEnabled}`); 2973}; 2974 2975audioSpatializationManager.on('headTrackingEnabledChange', headTrackingEnabledChangeCallback); 2976 2977audioSpatializationManager.off('headTrackingEnabledChange', headTrackingEnabledChangeCallback); 2978``` 2979 2980### off('headTrackingEnabledChangeForAnyDevice')<sup>12+</sup> 2981 2982off(type: 'headTrackingEnabledChangeForAnyDevice', callback?: Callback<AudioSpatialEnabledStateForDevice\>): void 2983 2984Unsubscribes from the head tracking status change event. This API uses an asynchronous callback to return the result. 2985 2986**System API**: This is a system API. 2987 2988**System capability**: SystemCapability.Multimedia.Audio.Spatialization 2989 2990**Parameters** 2991 2992| Name | Type | Mandatory| Description | 2993| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 2994| type | string | Yes | Event type. The value is fixed at **'headTrackingEnabledChangeForAnyDevice'**.| 2995| callback | Callback\<[AudioSpatialEnabledStateForDevice](#audiospatialenabledstatefordevice12)> | Yes | Callback used to return the device information and the enabled status of head tracking.| 2996 2997**Error codes** 2998 2999For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3000 3001| ID| Error Message| 3002| ------- | --------------------------------------------| 3003| 202 | Not system App. | 3004| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3005| 6800101 | Parameter verification failed. | 3006 3007**Example** 3008 3009```ts 3010import { audio } from '@kit.AudioKit'; 3011 3012// Cancel all subscriptions to the event. 3013audioSpatializationManager.off('headTrackingEnabledChangeForAnyDevice'); 3014 3015// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 3016let headTrackingEnabledChangeForAnyDeviceCallback = (audioSpatialEnabledStateForDevice: audio.AudioSpatialEnabledStateForDevice) => { 3017 console.info(`deviceDescriptor: ${audioSpatialEnabledStateForDevice.deviceDescriptor}`); 3018 console.info(`isSpatializationEnabled: ${audioSpatialEnabledStateForDevice.enabled}`); 3019}; 3020 3021audioSpatializationManager.on('headTrackingEnabledChangeForAnyDevice', headTrackingEnabledChangeForAnyDeviceCallback); 3022 3023audioSpatializationManager.off('headTrackingEnabledChangeForAnyDevice', headTrackingEnabledChangeForAnyDeviceCallback); 3024``` 3025 3026### updateSpatialDeviceState<sup>11+</sup> 3027 3028updateSpatialDeviceState(spatialDeviceState: AudioSpatialDeviceState): void 3029 3030Updates the state information of a spatial device. This API returns the result synchronously. 3031 3032**Required permissions**: ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 3033 3034**System API**: This is a system API. 3035 3036**System capability**: SystemCapability.Multimedia.Audio.Spatialization 3037 3038**Parameters** 3039 3040| Name | Type | Mandatory| Description | 3041| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 3042| spatialDeviceState | [AudioSpatialDeviceState](#audiospatialdevicestate11) | Yes | New state information of the spatial device.| 3043 3044**Error codes** 3045 3046For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3047 3048| ID| Error Message| 3049| ------- | --------------------------------------------| 3050| 201 | Permission denied. | 3051| 202 | Not system App. | 3052| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3053| 6800101 | Parameter verification failed. | 3054 3055**Example** 3056 3057```ts 3058import { audio } from '@kit.AudioKit'; 3059import { BusinessError } from '@kit.BasicServicesKit'; 3060 3061let spatialDeviceState: audio.AudioSpatialDeviceState = { 3062 address: "123", 3063 isSpatializationSupported: true, 3064 isHeadTrackingSupported: true, 3065 spatialDeviceType: audio.AudioSpatialDeviceType.SPATIAL_DEVICE_TYPE_IN_EAR_HEADPHONE 3066}; 3067 3068try { 3069 audioSpatializationManager.updateSpatialDeviceState(spatialDeviceState); 3070 console.info(`AudioSpatializationManager updateSpatialDeviceState success`); 3071} catch (err) { 3072 let error = err as BusinessError; 3073 console.error(`ERROR: ${error}`); 3074} 3075``` 3076 3077### setSpatializationSceneType<sup>12+</sup> 3078 3079setSpatializationSceneType(spatializationSceneType: AudioSpatializationSceneType): void 3080 3081Sets the scene type for spatial audio rendering. This API returns the result synchronously. 3082 3083**Required permissions**: ohos.permission.MANAGE_SYSTEM_AUDIO_EFFECTS 3084 3085**System API**: This is a system API. 3086 3087**System capability**: SystemCapability.Multimedia.Audio.Spatialization 3088 3089**Parameters** 3090 3091| Name | Type | Mandatory| Description | 3092| -------- | --------------------------------------------------- | ---- | ------------------------------------------ | 3093| spatializationSceneType | [AudioSpatializationSceneType](#audiospatializationscenetype12) | Yes | Scene type.| 3094 3095**Error codes** 3096 3097For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3098 3099| ID| Error Message| 3100| ------- | --------------------------------------------| 3101| 201 | Permission denied. | 3102| 202 | Not system App. | 3103| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3104| 6800101 | Parameter verification failed. | 3105 3106**Example** 3107 3108```ts 3109import { audio } from '@kit.AudioKit'; 3110import { BusinessError } from '@kit.BasicServicesKit'; 3111 3112try { 3113 audioSpatializationManager.setSpatializationSceneType(audio.AudioSpatializationSceneType.DEFAULT); 3114 console.info(`AudioSpatializationManager setSpatializationSceneType success`); 3115} catch (err) { 3116 let error = err as BusinessError; 3117 console.error(`ERROR: ${error}`); 3118} 3119``` 3120 3121### getSpatializationSceneType<sup>12+</sup> 3122 3123getSpatializationSceneType(): AudioSpatializationSceneType 3124 3125Obtains the scene type of spatial audio rendering in use. This API returns the result synchronously. 3126 3127**System API**: This is a system API. 3128 3129**System capability**: SystemCapability.Multimedia.Audio.Spatialization 3130 3131**Return value** 3132 3133| Type | Description | 3134| ---------------------- | ------------------------------------------------------------ | 3135| [AudioSpatializationSceneType](#audiospatializationscenetype12) | Scene type.| 3136 3137**Error codes** 3138 3139For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3140 3141| ID| Error Message| 3142| ------- | --------------------------------------------| 3143| 202 | Not system App. | 3144 3145**Example** 3146 3147```ts 3148import { audio } from '@kit.AudioKit'; 3149import { BusinessError } from '@kit.BasicServicesKit'; 3150 3151try { 3152 let spatializationSceneType: audio.AudioSpatializationSceneType = audioSpatializationManager.getSpatializationSceneType(); 3153 console.info(`AudioSpatializationManager spatializationSceneType: ${spatializationSceneType}`); 3154} catch (err) { 3155 let error = err as BusinessError; 3156 console.error(`ERROR: ${error}`); 3157} 3158``` 3159 3160## AudioSpatialDeviceState<sup>11+</sup> 3161 3162Defines the state information of a spatial device. 3163 3164**System API**: This is a system API. 3165 3166**System capability**: SystemCapability.Multimedia.Audio.Spatialization 3167 3168| Name | Type | Readable| Writable| Description | 3169| ----------------------------- | -------------------------- | ---- | ---- | ---------- | 3170| address<sup>11+</sup> | string | Yes | Yes | Address of the spatial device.| 3171| isSpatializationSupported<sup>11+</sup> | boolean | Yes | Yes | Whether the spatial device supports spatial audio rendering.| 3172| isHeadTrackingSupported<sup>11+</sup> | boolean | Yes | Yes | Whether the spatial device supports head tracking.| 3173| spatialDeviceType<sup>11+</sup> | [AudioSpatialDeviceType](#audiospatialdevicetype11) | Yes | Yes | Type of the spatial device.| 3174 3175**Example** 3176 3177```ts 3178import { audio } from '@kit.AudioKit'; 3179 3180let spatialDeviceState: audio.AudioSpatialDeviceState = { 3181 address: "123", 3182 isSpatializationSupported: true, 3183 isHeadTrackingSupported: true, 3184 spatialDeviceType: audio.AudioSpatialDeviceType.SPATIAL_DEVICE_TYPE_IN_EAR_HEADPHONE 3185}; 3186``` 3187 3188## AudioSpatialDeviceType<sup>11+</sup> 3189 3190Enumerates the types of spatial devices. 3191 3192**System API**: This is a system API. 3193 3194**System capability**: SystemCapability.Multimedia.Audio.Spatialization 3195 3196| Name | Value | Description | 3197| ---------------------------------- | ------ | ------------------------- | 3198| SPATIAL_DEVICE_TYPE_NONE | 0 | No spatial device. | 3199| SPATIAL_DEVICE_TYPE_IN_EAR_HEADPHONE | 1 | In-ear headphones. | 3200| SPATIAL_DEVICE_TYPE_HALF_IN_EAR_HEADPHONE | 2 | Half-in-ear headphones. | 3201| SPATIAL_DEVICE_TYPE_OVER_EAR_HEADPHONE | 3 | Over-ear headphones. | 3202| SPATIAL_DEVICE_TYPE_GLASSES | 4 | Glasses. | 3203| SPATIAL_DEVICE_TYPE_OTHERS | 5 | Other type of the spatial device.| 3204 3205## AudioSpatializationSceneType<sup>12+</sup> 3206 3207Enumerates the scene types available for spatial audio rendering. 3208 3209**System API**: This is a system API. 3210 3211**System capability**: SystemCapability.Multimedia.Audio.Spatialization 3212 3213| Name | Value | Description | 3214| ---------------------------------- | ------ | ------------------------- | 3215| DEFAULT | 0 | Default scene. | 3216| MUSIC | 1 | Music scene for spatial audio rendering. | 3217| MOVIE | 2 | Movie scene for spatial audio rendering. | 3218| AUDIOBOOK | 3 | Audiobook scene for spatial audio rendering. | 3219 3220## ToneType<sup>9+</sup> 3221 3222Enumerates the tone types of the player. 3223 3224**System API**: This is a system API. 3225 3226**System capability**: SystemCapability.Multimedia.Audio.Tone 3227 3228| Name | Value | Description | 3229| :------------------------------------------------ | :----- | :----------------------------| 3230| TONE_TYPE_DIAL_0 | 0 | DTMF tone of key 0. | 3231| TONE_TYPE_DIAL_1 | 1 | DTMF tone of key 1. | 3232| TONE_TYPE_DIAL_2 | 2 | DTMF tone of key 2. | 3233| TONE_TYPE_DIAL_3 | 3 | DTMF tone of key 3. | 3234| TONE_TYPE_DIAL_4 | 4 | DTMF tone of key 4. | 3235| TONE_TYPE_DIAL_5 | 5 | DTMF tone of key 5. | 3236| TONE_TYPE_DIAL_6 | 6 | DTMF tone of key 6. | 3237| TONE_TYPE_DIAL_7 | 7 | DTMF tone of key 7. | 3238| TONE_TYPE_DIAL_8 | 8 | DTMF tone of key 8. | 3239| TONE_TYPE_DIAL_9 | 9 | DTMF tone of key 9. | 3240| TONE_TYPE_DIAL_S | 10 | DTMF tone of the star key (*). | 3241| TONE_TYPE_DIAL_P | 11 | DTMF tone of the pound key (#). | 3242| TONE_TYPE_DIAL_A | 12 | DTMF tone of key A. | 3243| TONE_TYPE_DIAL_B | 13 | DTMF tone of key B. | 3244| TONE_TYPE_DIAL_C | 14 | DTMF tone of key C. | 3245| TONE_TYPE_DIAL_D | 15 | DTMF tone of key D. | 3246| TONE_TYPE_COMMON_SUPERVISORY_DIAL | 100 | Supervisory tone - dial tone. | 3247| TONE_TYPE_COMMON_SUPERVISORY_BUSY | 101 | Supervisory tone - busy. | 3248| TONE_TYPE_COMMON_SUPERVISORY_CONGESTION | 102 | Supervisory tone - congestion. | 3249| TONE_TYPE_COMMON_SUPERVISORY_RADIO_ACK | 103 | Supervisory tone - radio path acknowledgment. | 3250| TONE_TYPE_COMMON_SUPERVISORY_RADIO_NOT_AVAILABLE | 104 | Supervisory tone - radio path not available. | 3251| TONE_TYPE_COMMON_SUPERVISORY_CALL_WAITING | 106 | Supervisory tone - call waiting tone. | 3252| TONE_TYPE_COMMON_SUPERVISORY_RINGTONE | 107 | Supervisory tone - ringing tone. | 3253| TONE_TYPE_COMMON_PROPRIETARY_BEEP | 200 | Proprietary tone - beep tone. | 3254| TONE_TYPE_COMMON_PROPRIETARY_ACK | 201 | Proprietary tone - ACK. | 3255| TONE_TYPE_COMMON_PROPRIETARY_PROMPT | 203 | Proprietary tone - PROMPT. | 3256| TONE_TYPE_COMMON_PROPRIETARY_DOUBLE_BEEP | 204 | Proprietary tone - double beep tone. | 3257 3258## TonePlayer<sup>9+</sup> 3259 3260Provides APIs for playing and managing DTMF tones, such as dial tones, ringback tones, supervisory tones, and proprietary tones. 3261Before calling any API in **TonePlayer**, you must use [createTonePlayer](#audiocreatetoneplayer9) to create a **TonePlayer** instance. 3262 3263**System API**: This is a system API. 3264 3265### load<sup>9+</sup> 3266 3267load(type: ToneType, callback: AsyncCallback<void>): void 3268 3269Loads the DTMF tone configuration. This API uses an asynchronous callback to return the result. 3270 3271**System API**: This is a system API. 3272 3273**System capability**: SystemCapability.Multimedia.Audio.Tone 3274 3275**Parameters** 3276 3277| Name | Type | Mandatory | Description | 3278| :--------------| :-------------------------- | :-----| :------------------------------ | 3279| type | [ToneType](#tonetype9) | Yes | Tone type. | 3280| callback | AsyncCallback<void\> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 3281 3282**Example** 3283 3284```ts 3285import { BusinessError } from '@kit.BasicServicesKit'; 3286 3287tonePlayer.load(audio.ToneType.TONE_TYPE_DIAL_5, (err: BusinessError) => { 3288 if (err) { 3289 console.error(`callback call load failed error: ${err.message}`); 3290 return; 3291 } else { 3292 console.info('callback call load success'); 3293 } 3294}); 3295``` 3296 3297### load<sup>9+</sup> 3298 3299load(type: ToneType): Promise<void> 3300 3301Loads the DTMF tone configuration. This API uses a promise to return the result. 3302 3303**System API**: This is a system API. 3304 3305**System capability**: SystemCapability.Multimedia.Audio.Tone 3306 3307**Parameters** 3308 3309| Name | Type | Mandatory | Description | 3310| :------------- | :--------------------- | :--- | ---------------- | 3311| type | [ToneType](#tonetype9) | Yes | Tone type. | 3312 3313**Return value** 3314 3315| Type | Description | 3316| :--------------| :-------------------------- | 3317| Promise<void\> | Promise that returns no value.| 3318 3319**Example** 3320 3321```ts 3322tonePlayer.load(audio.ToneType.TONE_TYPE_DIAL_1).then(() => { 3323 console.info('promise call load '); 3324}).catch(() => { 3325 console.error('promise call load fail'); 3326}); 3327``` 3328 3329### start<sup>9+</sup> 3330 3331start(callback: AsyncCallback<void>): void 3332 3333Starts DTMF tone playing. This API uses an asynchronous callback to return the result. 3334 3335**System API**: This is a system API. 3336 3337**System capability**: SystemCapability.Multimedia.Audio.Tone 3338 3339**Parameters** 3340 3341| Name | Type | Mandatory| Description | 3342| :------- | :------------------- | :--- | :----------------------------- | 3343| callback | AsyncCallback<void\> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 3344 3345**Example** 3346 3347```ts 3348import { BusinessError } from '@kit.BasicServicesKit'; 3349 3350tonePlayer.start((err: BusinessError) => { 3351 if (err) { 3352 console.error(`callback call start failed error: ${err.message}`); 3353 return; 3354 } else { 3355 console.info('callback call start success'); 3356 } 3357}); 3358``` 3359 3360### start<sup>9+</sup> 3361 3362start(): Promise<void> 3363 3364Starts DTMF tone playing. This API uses a promise to return the result. 3365 3366**System API**: This is a system API. 3367 3368**System capability**: SystemCapability.Multimedia.Audio.Tone 3369 3370**Return value** 3371 3372| Type | Description | 3373| :------------- | :---------------------------- | 3374| Promise<void\> | Promise that returns no value.| 3375 3376**Example** 3377 3378```ts 3379tonePlayer.start().then(() => { 3380 console.info('promise call start'); 3381}).catch(() => { 3382 console.error('promise call start fail'); 3383}); 3384``` 3385 3386### stop<sup>9+</sup> 3387 3388stop(callback: AsyncCallback<void>): void 3389 3390Stops the tone that is being played. This API uses an asynchronous callback to return the result. 3391 3392**System API**: This is a system API. 3393 3394**System capability**: SystemCapability.Multimedia.Audio.Tone 3395 3396**Parameters** 3397 3398| Name | Type | Mandatory| Description | 3399| :------- | :------------------- | :--- | :----------------------------- | 3400| callback | AsyncCallback<void\> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 3401 3402**Example** 3403 3404```ts 3405import { BusinessError } from '@kit.BasicServicesKit'; 3406 3407tonePlayer.stop((err: BusinessError) => { 3408 if (err) { 3409 console.error(`callback call stop error: ${err.message}`); 3410 return; 3411 } else { 3412 console.error('callback call stop success '); 3413 } 3414}); 3415``` 3416 3417### stop<sup>9+</sup> 3418 3419stop(): Promise<void> 3420 3421Stops the tone that is being played. This API uses a promise to return the result. 3422 3423**System API**: This is a system API. 3424 3425**System capability**: SystemCapability.Multimedia.Audio.Tone 3426 3427**Return value** 3428 3429| Type | Description | 3430| :------------- | :---------------------------- | 3431| Promise<void\> | Promise that returns no value.| 3432 3433**Example** 3434 3435```ts 3436tonePlayer.stop().then(() => { 3437 console.info('promise call stop finish'); 3438}).catch(() => { 3439 console.error('promise call stop fail'); 3440}); 3441``` 3442 3443### release<sup>9+</sup> 3444 3445release(callback: AsyncCallback<void>): void 3446 3447Releases the resources associated with the **TonePlayer** instance. This API uses an asynchronous callback to return the result. 3448 3449**System API**: This is a system API. 3450 3451**System capability**: SystemCapability.Multimedia.Audio.Tone 3452 3453**Parameters** 3454 3455| Name | Type | Mandatory| Description | 3456| :------- | :------------------- | :--- | :---------------------------- | 3457| callback | AsyncCallback<void\> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined**; otherwise, **err** is an error object.| 3458 3459**Example** 3460 3461```ts 3462import { BusinessError } from '@kit.BasicServicesKit'; 3463 3464tonePlayer.release((err: BusinessError) => { 3465 if (err) { 3466 console.error(`callback call release failed error: ${err.message}`); 3467 return; 3468 } else { 3469 console.info('callback call release success '); 3470 } 3471}); 3472``` 3473 3474### release<sup>9+</sup> 3475 3476release(): Promise<void> 3477 3478Releases the resources associated with the **TonePlayer** instance. This API uses a promise to return the result. 3479 3480**System API**: This is a system API. 3481 3482**System capability**: SystemCapability.Multimedia.Audio.Tone 3483 3484**Return value** 3485 3486| Type | Description | 3487| :------------- | :---------------------------- | 3488| Promise<void\> | Promise that returns no value.| 3489 3490**Example** 3491 3492```ts 3493tonePlayer.release().then(() => { 3494 console.info('promise call release'); 3495}).catch(() => { 3496 console.error('promise call release fail'); 3497}); 3498``` 3499 3500## AsrProcessingController<sup>12+</sup> 3501 3502Implements an ASR processing controller. 3503 3504**System API**: This is a system API. 3505 3506**System capability**: SystemCapability.Multimedia.Audio.Capturer 3507 3508### setAsrAecMode<sup>12+</sup> 3509 3510setAsrAecMode(mode: AsrAecMode): boolean; 3511 3512Sets an ASR AEC mode. This API returns the result synchronously. 3513 3514**System API**: This is a system API. 3515 3516**System capability**: SystemCapability.Multimedia.Audio.Capturer 3517 3518**Parameters** 3519 3520| Name| Type | Mandatory| Description| 3521|-------|----------------------------|-------|-------| 3522| mode | [AsrAecMode](#asraecmode12) | Yes|ASR AEC mode.| 3523 3524**Return value** 3525 3526| Type| Description | 3527|-------|---------------------------------------| 3528| boolean | **true**: The setting is successful.<br>**false**: The setting fails.| 3529 3530**Error codes** 3531 3532For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3533 3534| ID | Error Message | 3535|---------|------------------------------------------| 3536| 202 | Caller is not a system application. | 3537| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3538| 6800101 | Parameter verification failed. | 3539| 6800104 | Operation not allowed. | 3540 3541**Example** 3542 3543```ts 3544let flag = asrProcessingController.setAsrAecMode(audio.AsrAecMode.BYPASS); 3545``` 3546 3547### getAsrAecMode<sup>12+</sup> 3548 3549getAsrAecMode(): AsrAecMode; 3550 3551Obtains the ASR AEC mode in use. This API returns the result synchronously. 3552 3553**System API**: This is a system API. 3554 3555**System capability**: SystemCapability.Multimedia.Audio.Capturer 3556 3557**Return value** 3558 3559| Type| Description| 3560|-------|-------| 3561| [AsrAecMode](#asraecmode12) |ASR AEC mode.| 3562 3563**Error codes** 3564 3565For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3566 3567| ID | Error Message | 3568|---------|------------------------------------------| 3569| 202 | Caller is not a system application. | 3570| 6800104 | Operation not allowed. | 3571 3572 3573**Example** 3574 3575```ts 3576let mode = asrProcessingController.getAsrAecMode(); 3577``` 3578 3579### setAsrNoiseSuppressionMode<sup>12+</sup> 3580 3581setAsrNoiseSuppressionMode(mode: AsrNoiseSuppressionMode): boolean; 3582 3583Sets an ASR noise suppression mode. This API returns the result synchronously. 3584 3585**System API**: This is a system API. 3586 3587**System capability**: SystemCapability.Multimedia.Audio.Capturer 3588 3589**Parameters** 3590 3591| Name| Type | Mandatory| Description| 3592|-------|-------------------------------------------------------|-------|-------| 3593| mode | [AsrNoiseSuppressionMode](#asrnoisesuppressionmode12) | Yes|ASR noise suppression mode.| 3594 3595**Return value** 3596 3597| Type| Description | 3598|-------|----------------------------------------| 3599| boolean | **true**: The setting is successful.<br>**false**: The setting fails.| 3600 3601**Error codes** 3602 3603For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3604 3605| ID | Error Message | 3606|---------|------------------------------------------| 3607| 202 | Caller is not a system application. | 3608| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 3609| 6800101 | Parameter verification failed. | 3610| 6800104 | Operation not allowed. | 3611 3612**Example** 3613 3614```ts 3615let flag = asrProcessingController.setAsrNoiseSuppressionMode(audio.AsrNoiseSuppressionMode.BYPASS); 3616``` 3617 3618### getAsrNoiseSuppressionMode<sup>12+</sup> 3619 3620getAsrNoiseSuppressionMode(): AsrNoiseSuppressionMode; 3621 3622Obtains the ASR noise suppression mode in use. This API returns the result synchronously. 3623 3624**System API**: This is a system API. 3625 3626**System capability**: SystemCapability.Multimedia.Audio.Capturer 3627 3628**Return value** 3629 3630| Type |Description| 3631|-------------------------|-------| 3632| [AsrNoiseSuppressionMode](#asrnoisesuppressionmode12) |ASR noise suppression mode.| 3633 3634**Error codes** 3635 3636For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3637 3638| ID | Error Message | 3639|---------|------------------------------------------| 3640| 202 | Caller is not a system application. | 3641| 6800104 | Operation not allowed. | 3642 3643**Example** 3644 3645```ts 3646let mode = asrProcessingController.getAsrNoiseSuppressionMode(); 3647``` 3648 3649### isWhispering<sup>12+</sup> 3650 3651isWhispering(): boolean; 3652 3653Checks whether it is in the whisper state. 3654 3655**System API**: This is a system API. 3656 3657**System capability**: SystemCapability.Multimedia.Audio.Capturer 3658 3659**Return value** 3660 3661| Type| Description | 3662|-------|--------------------------| 3663| boolean | **true**: It is in the whisper state.<br>**false**: It is not in the whisper state.| 3664 3665**Error codes** 3666 3667For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3668 3669| ID | Error Message | 3670|---------|------------------------------------------| 3671| 202 | Caller is not a system application. | 3672| 6800104 | Operation not allowed. | 3673 3674**Example** 3675 3676```ts 3677let flag = asrProcessingController.isWhispering(); 3678``` 3679 3680### setAsrWhisperDetectionMode<sup>12+</sup> 3681 3682setAsrWhisperDetectionMode(mode: AsrWhisperDetectionMode): boolean 3683 3684Sets an ASR whisper detection mode. 3685 3686**System API**: This is a system API. 3687 3688**System capability**: SystemCapability.Multimedia.Audio.Capturer 3689 3690**Parameters** 3691 3692| Name | Type | Mandatory| Description | 3693|------|---------------------|-------|--------| 3694| mode | [AsrWhisperDetectionMode](#asrwhisperdetectionmode12) | Yes| ASR whisper detection mode.| 3695 3696**Return value** 3697 3698| Type| Description | 3699|-------|----------------------------------------| 3700| boolean | **true**: The setting is successful.<br>**false**: The setting fails.| 3701 3702**Error codes** 3703 3704For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3705 3706| ID | Error Message | 3707|---------|------------------------------------------| 3708| 202 | Caller is not a system application. | 3709| 401 | Parameter error. Possible causes: 1.Mandatory parameters unspecified; 2.Incorrect parameter types. | 3710| 6800101 | Parameter verification failed. | 3711| 6800104 | Operation not allowed. | 3712 3713**Example** 3714 3715```ts 3716let flag = asrProcessingController.setAsrWhisperDetectionMode(audio.AsrWhisperDetectionMode.BYPASS); 3717``` 3718 3719 3720### getAsrWhisperDetectionMode<sup>12+</sup> 3721 3722getAsrWhisperDetectionMode(): AsrWhisperDetectionMode 3723 3724Obtains the ASR whisper detection mode. This API returns the result synchronously. 3725 3726**System API**: This is a system API. 3727 3728**System capability**: SystemCapability.Multimedia.Audio.Capturer 3729 3730**Return value** 3731 3732| Type| Description | 3733|-------|--------| 3734| [AsrWhisperDetectionMode](#asrwhisperdetectionmode12) | ASR whisper detection mode.| 3735 3736**Error codes** 3737 3738For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3739 3740| ID | Error Message | 3741|---------|------------------------------------------| 3742| 202 | Caller is not a system application. | 3743| 6800104 | Operation not allowed. | 3744 3745**Example** 3746 3747```ts 3748let mode = asrProcessingController.getAsrWhisperDetectionMode(); 3749``` 3750 3751 3752### setAsrVoiceControlMode<sup>12+</sup> 3753 3754setAsrVoiceControlMode(mode: AsrVoiceControlMode, enable: boolean): boolean 3755 3756Sets an ASR voice control mode of the uplink channel for reporting modem and call recording during a call. 3757 3758**System API**: This is a system API. 3759 3760**System capability**: SystemCapability.Multimedia.Audio.Capturer 3761 3762**Parameters** 3763 3764| Name | Type | Mandatory| Description | 3765|------|---------------------|-------|--------| 3766| mode | [AsrVoiceControlMode](#asrvoicecontrolmode12) | Yes| ASR voice control mode.| 3767| enable | boolean | Yes| Switch status. | 3768 3769**Return value** 3770 3771| Type| Description | 3772|-------|----------------------------------------------------------------| 3773| boolean | **true**: The setting is successful.<br>**false**: The setting fails.| 3774 3775**Error codes** 3776 3777For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3778 3779| ID | Error Message | 3780|---------|------------------------------------------| 3781| 202 | Caller is not a system application. | 3782| 401 | Parameter error. Possible causes: 1.Mandatory parameters unspecified; 2.Incorrect parameter types. | 3783| 6800101 | Parameter verification failed. | 3784| 6800104 | Operation not allowed. | 3785 3786**Example** 3787 3788```ts 3789let flag = asrProcessingController.setAsrVoiceControlMode(audio.AsrVoiceControlMode.AUDIO_2_VOICE_TX, true); 3790``` 3791 3792### setAsrVoiceMuteMode<sup>12+</sup> 3793 3794setAsrVoiceMuteMode(mode: AsrVoiceMuteMode, enable: boolean): boolean 3795 3796Sets an ASR voice mute mode. 3797 3798**System API**: This is a system API. 3799 3800**System capability**: SystemCapability.Multimedia.Audio.Capturer 3801 3802**Parameters** 3803 3804| Name | Type | Mandatory| Description | 3805|------|---------------------------------------|-------|----------| 3806| mode | [AsrVoiceMuteMode](#asrvoicemutemode12) | Yes| ASR voice mute mode.| 3807| enable | boolean | Yes| Switch status. | 3808 3809**Return value** 3810 3811| Type| Description | 3812|-------|--------------------------------------------------| 3813| boolean | **true**: The setting is successful.<br>**false**: The setting fails.| 3814 3815**Error codes** 3816 3817For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 3818 3819| ID | Error Message | 3820|---------|------------------------------------------| 3821| 202 | Caller is not a system application. | 3822| 401 | Parameter error. Possible causes: 1.Mandatory parameters unspecified; 2.Incorrect parameter types. | 3823| 6800101 | Parameter verification failed. | 3824| 6800104 | Operation not allowed. | 3825 3826**Example** 3827 3828```ts 3829let flag = asrProcessingController.setAsrVoiceMuteMode(audio.AsrVoiceMuteMode.OUTPUT_MUTE, true); 3830``` 3831