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