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