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