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