1# Interface (AudioVolumeManager) 2 3> **NOTE** 4> 5> - 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. 6> - The initial APIs of this interface are supported since API version 9. 7 8This interface implements audio volume management. 9 10Before calling any API in AudioVolumeManager, you must use [getVolumeManager](arkts-apis-audio-AudioManager.md#getvolumemanager9) to obtain an AudioVolumeManager instance. 11 12## Modules to Import 13 14```ts 15import { audio } from '@kit.AudioKit'; 16``` 17 18## getVolumeGroupManager<sup>9+</sup> 19 20getVolumeGroupManager(groupId: number, callback: AsyncCallback<AudioVolumeGroupManager\>\): void 21 22Obtains the volume group manager. This API uses an asynchronous callback to return the result. 23 24**System capability**: SystemCapability.Multimedia.Audio.Volume 25 26**Parameters** 27 28| Name | Type | Mandatory| Description | 29| ---------- | ------------------------------------------------------------ | ---- |-----------------------------------------------------------| 30| groupId | number | Yes | Volume group ID. The default value is **DEFAULT_VOLUME_GROUP_ID**. | 31| callback | AsyncCallback<[AudioVolumeGroupManager](arkts-apis-audio-AudioVolumeGroupManager.md)> | Yes | Callback used to return the result. If the operation is successful, **err** is **undefined** and **data** is the volume group manager obtained; otherwise, **err** is an error object.| 32 33**Example** 34 35```ts 36import { BusinessError } from '@kit.BasicServicesKit'; 37 38let groupId: number = audio.DEFAULT_VOLUME_GROUP_ID; 39 40audioVolumeManager.getVolumeGroupManager(groupId, (err: BusinessError, value: audio.AudioVolumeGroupManager) => { 41 if (err) { 42 console.error(`Failed to obtain the volume group infos list. ${err}`); 43 return; 44 } 45 console.info('Callback invoked to indicate that the volume group infos list is obtained.'); 46}); 47 48``` 49 50## getVolumeGroupManager<sup>9+</sup> 51 52getVolumeGroupManager(groupId: number\): Promise<AudioVolumeGroupManager\> 53 54Obtains the volume group manager. This API uses a promise to return the result. 55 56**System capability**: SystemCapability.Multimedia.Audio.Volume 57 58**Parameters** 59 60| Name | Type | Mandatory| Description | 61| ---------- | ---------------------------------------- | ---- |----------------------------------| 62| groupId | number | Yes | Volume group ID. The default value is **DEFAULT_VOLUME_GROUP_ID**.| 63 64**Return value** 65 66| Type | Description | 67| ------------------- | ----------------------------- | 68| Promise< [AudioVolumeGroupManager](arkts-apis-audio-AudioVolumeGroupManager.md) > | Promise used to return the volume group manager.| 69 70**Example** 71 72```ts 73import { audio } from '@kit.AudioKit'; 74 75let groupId: number = audio.DEFAULT_VOLUME_GROUP_ID; 76let audioVolumeGroupManager: audio.AudioVolumeGroupManager | undefined = undefined; 77 78async function getVolumeGroupManager(){ 79 audioVolumeGroupManager = await audioVolumeManager.getVolumeGroupManager(groupId); 80 console.info('Promise returned to indicate that the volume group infos list is obtained.'); 81} 82``` 83 84## getVolumeGroupManagerSync<sup>10+</sup> 85 86getVolumeGroupManagerSync(groupId: number\): AudioVolumeGroupManager 87 88Obtains the volume group manager. This API returns the result synchronously. 89 90**System capability**: SystemCapability.Multimedia.Audio.Volume 91 92**Parameters** 93 94| Name | Type | Mandatory| Description | 95| ---------- | ---------------------------------------- | ---- |----------------------------------| 96| groupId | number | Yes | Volume group ID. The default value is **DEFAULT_VOLUME_GROUP_ID**.| 97 98**Return value** 99 100| Type | Description | 101| ------------------- | ----------------------------- | 102| [AudioVolumeGroupManager](arkts-apis-audio-AudioVolumeGroupManager.md) | Volume group manager.| 103 104**Error codes** 105 106For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Audio Error Codes](errorcode-audio.md). 107 108| ID| Error Message| 109| ------- | --------------------------------------------| 110| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 111| 6800101 | Parameter verification failed. | 112 113**Example** 114 115```ts 116import { BusinessError } from '@kit.BasicServicesKit'; 117 118try { 119 let audioVolumeGroupManager: audio.AudioVolumeGroupManager = audioVolumeManager.getVolumeGroupManagerSync(audio.DEFAULT_VOLUME_GROUP_ID); 120 console.info(`Get audioVolumeGroupManager success.`); 121} catch (err) { 122 let error = err as BusinessError; 123 console.error(`Failed to get audioVolumeGroupManager, error: ${error}`); 124} 125``` 126 127## getAppVolumePercentage<sup>19+</sup> 128 129getAppVolumePercentage(): Promise<number\> 130 131Obtains the volume of the application. This API uses a promise to return the result. 132 133**System capability**: SystemCapability.Multimedia.Audio.Volume 134 135**Return value** 136 137| Type | Description | 138| ------------------- |--------------------| 139| Promise<number> | Promise used to return the application volume (ranging from 0 to 100).| 140 141**Example** 142 143```ts 144import { audio } from '@kit.AudioKit'; 145 146audioVolumeManager.getAppVolumePercentage().then((value: number) => { 147 console.info(`app volume is ${value}.`); 148}); 149``` 150 151## setAppVolumePercentage<sup>19+</sup> 152 153setAppVolumePercentage(volume: number\): Promise<void\> 154 155Sets the volume for the application. This API uses a promise to return the result. 156 157**System capability**: SystemCapability.Multimedia.Audio.Volume 158 159**Parameters** 160 161| Name | Type | Mandatory| Description | 162| ---------- | ---------------------------------------- | ---- |----------| 163| volume | number | Yes | Volume to set.| 164 165**Return value** 166 167| Type | Description | 168| ------------------- | ------------------------------- | 169| Promise<void> | Promise that returns no value.| 170 171**Error codes** 172 173For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 174 175| ID| Error Message| 176| ------- | --------------------------------------------| 177| 6800101 | Parameter verification failed.| 178| 6800301 | Crash or blocking occurs in system process. | 179 180**Example** 181 182```ts 183import { audio } from '@kit.AudioKit'; 184 185audioVolumeManager.setAppVolumePercentage(20).then(() => { 186 console.info(`set app volume success.`); 187}); 188``` 189 190## on('volumeChange')<sup>(deprecated)</sup> 191 192on(type: 'volumeChange', callback: Callback\<VolumeEvent>): void 193 194Subscribes to the system volume change event, which is triggered when the system volume is changed. This API uses an asynchronous callback to return the result. 195 196> **NOTE** 197> 198> This API is supported since API version 12 and deprecated since API version 20. You are advised to use [on('streamVolumeChange')](arkts-apis-audio-AudioVolumeManager.md#onstreamvolumechange20) instead. 199 200**System capability**: SystemCapability.Multimedia.Audio.Volume 201 202**Parameters** 203 204| Name | Type | Mandatory| Description | 205| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 206| type | string | Yes | Event type. The event **'volumeChange'** is triggered when the system volume is changed.| 207| callback | Callback<[VolumeEvent](arkts-apis-audio-i.md#volumeevent9)> | Yes | Callback used to return the changed volume.| 208 209**Error codes** 210 211For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Audio Error Codes](errorcode-audio.md). 212 213| ID| Error Message| 214| ------- | --------------------------------------------| 215| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 216| 6800101 | Parameter verification failed. | 217 218**Example** 219 220```ts 221audioVolumeManager.on('volumeChange', (volumeEvent: audio.VolumeEvent) => { 222 console.info(`VolumeType of stream: ${volumeEvent.volumeType} `); 223 console.info(`Volume level: ${volumeEvent.volume} `); 224 console.info(`Whether to updateUI: ${volumeEvent.updateUi} `); 225}); 226``` 227 228## off('volumeChange')<sup>(deprecated)</sup> 229 230off(type: 'volumeChange', callback?: Callback\<VolumeEvent>): void 231 232Unsubscribes from the system volume change event. This API uses an asynchronous callback to return the result. 233 234> **NOTE** 235> 236> This API is supported since API version 12 and deprecated since API version 20. You are advised to use [off('streamVolumeChange')](arkts-apis-audio-AudioVolumeManager.md#offstreamvolumechange20) instead. 237 238**System capability**: SystemCapability.Multimedia.Audio.Volume 239 240**Parameters** 241 242| Name | Type | Mandatory| Description | 243| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 244| type | string | Yes | Event type. The event **'volumeChange'** is triggered when the system volume is changed.| 245| callback | Callback<[VolumeEvent](arkts-apis-audio-i.md#volumeevent9)> | No | Callback used to return the changed volume.| 246 247**Error codes** 248 249For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Audio Error Codes](errorcode-audio.md). 250 251| ID| Error Message| 252| ------- | --------------------------------------------| 253| 401 | Parameter error. Possible causes: 1.Mandatory parameters missing; 2.Incorrect parameter types. | 254| 6800101 | Parameter verification failed. | 255 256**Example** 257 258```ts 259// Cancel all subscriptions to the event. 260audioVolumeManager.off('volumeChange'); 261 262// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 263let volumeChangeCallback = (volumeEvent: audio.VolumeEvent) => { 264 console.info(`VolumeType of stream: ${volumeEvent.volumeType} `); 265 console.info(`Volume level: ${volumeEvent.volume} `); 266 console.info(`Whether to updateUI: ${volumeEvent.updateUi} `); 267}; 268 269audioVolumeManager.on('volumeChange', volumeChangeCallback); 270 271audioVolumeManager.off('volumeChange', volumeChangeCallback); 272``` 273 274## on('appVolumeChange')<sup>19+</sup> 275 276on(type: 'appVolumeChange', callback: Callback\<VolumeEvent>): void 277 278Subscribes to the application-level volume change event of the application. This API uses an asynchronous callback to return the result. 279 280**System capability**: SystemCapability.Multimedia.Audio.Volume 281 282**Parameters** 283 284| Name | Type | Mandatory| Description | 285| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 286| type | string | Yes | Event type. The event **'appVolumeChange'** is triggered when the application-level volume is changed.| 287| callback | Callback<[VolumeEvent](arkts-apis-audio-i.md#volumeevent9)> | Yes | Callback used to return the changed volume.| 288 289**Error codes** 290 291For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 292 293| ID| Error Message| 294| ------- | --------------------------------------------| 295| 6800101 | Parameter verification failed. | 296 297**Example** 298 299```ts 300audioVolumeManager.on('appVolumeChange', (volumeEvent: audio.VolumeEvent) => { 301 console.info(`VolumeType of stream: ${volumeEvent.volumeType} `); 302 console.info(`Volume level: ${volumeEvent.volume} `); 303 console.info(`Whether to updateUI: ${volumeEvent.updateUi} `); 304}); 305``` 306 307## off('appVolumeChange')<sup>19+</sup> 308 309off(type: 'appVolumeChange', callback?: Callback\<VolumeEvent>): void 310 311Unsubscribes from the application-level volume change event of the application. This API uses an asynchronous callback to return the result. 312 313**System capability**: SystemCapability.Multimedia.Audio.Volume 314 315**Parameters** 316 317| Name | Type | Mandatory| Description | 318| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 319| type | string | Yes | Event type. The event **'appVolumeChange'** is triggered when the application-level volume is changed.| 320| callback | Callback<[VolumeEvent](arkts-apis-audio-i.md#volumeevent9)> | No | Callback used to return the changed volume.| 321 322**Error codes** 323 324For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 325 326| ID| Error Message| 327| ------- | --------------------------------------------| 328| 6800101 | Parameter verification failed. | 329 330**Example** 331 332```ts 333// Cancel all subscriptions to the event. 334audioVolumeManager.off('appVolumeChange'); 335 336// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 337let appVolumeChangeCallback = (volumeEvent: audio.VolumeEvent) => { 338 console.info(`VolumeType of stream: ${volumeEvent.volumeType} `); 339 console.info(`Volume level: ${volumeEvent.volume} `); 340 console.info(`Whether to updateUI: ${volumeEvent.updateUi} `); 341}; 342 343audioVolumeManager.on('appVolumeChange', appVolumeChangeCallback); 344 345audioVolumeManager.off('appVolumeChange', appVolumeChangeCallback); 346``` 347 348## getVolumeByStream<sup>20+</sup> 349 350getVolumeByStream(streamUsage: StreamUsage): number 351 352Obtains the volume of a specified audio stream. 353 354**System capability**: SystemCapability.Multimedia.Audio.Volume 355 356**Parameters** 357 358| Name | Type | Mandatory| Description | 359| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 360| streamUsage | [StreamUsage](arkts-apis-audio-e.md#streamusage) | Yes | Audio stream for which the volume is to be obtained.| 361 362**Return value** 363 364| Type | Description | 365| ------------------- | ----------------------------- | 366| number | Volume.| 367 368**Error codes** 369 370For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 371 372| ID| Error Message| 373| ------- | --------------------------------------------| 374| 6800101 | Parameter verification failed. | 375 376**Example** 377 378```ts 379// Obtain the volume of a specified audio stream. 380import { BusinessError } from '@kit.BasicServicesKit'; 381import { audio } from '@kit.AudioKit' 382 383try { 384 let volume : number = audio.getAudioManager().getVolumeManager().getVolumeByStream(audio.StreamUsage.STREAM_USAGE_MUSIC); 385 console.info(`Obtains the volume of a stream success.`); 386} catch (err) { 387 let error = err as BusinessError; 388 console.error(`Failed to obtains the volume of a stream, error: ${error}`); 389} 390``` 391 392## getMinVolumeByStream<sup>20+</sup> 393 394getMinVolumeByStream(streamUsage: StreamUsage): number 395 396Obtains the minimum volume of a specified audio stream. 397 398**System capability**: SystemCapability.Multimedia.Audio.Volume 399 400**Parameters** 401 402| Name | Type | Mandatory| Description | 403| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 404| streamUsage | [StreamUsage](arkts-apis-audio-e.md#streamusage) | Yes | Audio stream for which the minimum volume is to be obtained.| 405 406**Return value** 407 408| Type | Description | 409| ------------------- | ----------------------------- | 410| number | Volume.| 411 412**Error codes** 413 414For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 415 416| ID| Error Message| 417| ------- | --------------------------------------------| 418| 6800101 | Parameter verification failed. | 419 420**Example** 421 422```ts 423// Obtain the minimum volume of a specified audio stream. 424import { BusinessError } from '@kit.BasicServicesKit'; 425import { audio } from '@kit.AudioKit' 426 427try { 428 let volume : number = audio.getAudioManager().getVolumeManager().getMinVolumeByStream(audio.StreamUsage.STREAM_USAGE_MUSIC); 429 console.info(`Obtains the minimum volume allowed for a stream success.`); 430} catch (err) { 431 let error = err as BusinessError; 432 console.error(`Failed to obtains the minimum volume allowed for a stream, error: ${error}`); 433} 434``` 435 436## getMaxVolumeByStream<sup>20+</sup> 437 438getMaxVolumeByStream(streamUsage: StreamUsage): number 439 440Obtains the maximum volume of a specified audio stream. 441 442**System capability**: SystemCapability.Multimedia.Audio.Volume 443 444**Parameters** 445 446| Name | Type | Mandatory| Description | 447| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 448| streamUsage | [StreamUsage](arkts-apis-audio-e.md#streamusage) | Yes | Audio stream for which the maximum volume is to be obtained.| 449 450**Return value** 451 452| Type | Description | 453| ------------------- | ----------------------------- | 454| number | Volume.| 455 456**Error codes** 457 458For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 459 460| ID| Error Message| 461| ------- | --------------------------------------------| 462| 6800101 | Parameter verification failed. | 463 464**Example** 465 466```ts 467// Obtain the maximum volume of a specified audio stream. 468import { BusinessError } from '@kit.BasicServicesKit'; 469import { audio } from '@kit.AudioKit' 470 471try { 472 let volume : number = audio.getAudioManager().getVolumeManager().getMaxVolumeByStream(audio.StreamUsage.STREAM_USAGE_MUSIC); 473 console.info(`Obtains the maximum volume allowed for a stream success.`); 474} catch (err) { 475 let error = err as BusinessError; 476 console.error(`Failed to obtains the maximum volume allowed for a stream, error: ${error}`); 477} 478``` 479 480## isSystemMutedForStream<sup>20+</sup> 481 482isSystemMutedForStream(streamUsage: StreamUsage): boolean 483 484Checks whether a specified audio stream is muted. 485 486**System capability**: SystemCapability.Multimedia.Audio.Volume 487 488**Parameters** 489 490| Name | Type | Mandatory| Description | 491| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 492| streamUsage | [StreamUsage](arkts-apis-audio-e.md#streamusage) | Yes | Audio stream to check.| 493 494**Return value** 495 496| Type | Description | 497| ------------------- | ----------------------------- | 498| boolean | Check result. The value **true** means the audio stream is muted, and **false** means the opposite.| 499 500**Error codes** 501 502For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 503 504| ID| Error Message| 505| ------- | --------------------------------------------| 506| 6800101 | Parameter verification failed. | 507 508**Example** 509 510```ts 511// Check whether a specified audio stream is muted. 512import { BusinessError } from '@kit.BasicServicesKit'; 513import { audio } from '@kit.AudioKit' 514 515try { 516 let isMuted : boolean = audio.getAudioManager().getVolumeManager().isSystemMutedForStream(audio.StreamUsage.STREAM_USAGE_MUSIC); 517 console.info(`Checks whether the system is muted based on the stream success.`); 518} catch (err) { 519 let error = err as BusinessError; 520 console.error(`Failed to checks whether the system is muted based on the stream, error: ${error}`); 521} 522 523``` 524## getVolumeInUnitOfDbByStream<sup>20+</sup> 525 526getVolumeInUnitOfDbByStream(streamUsage: StreamUsage, volumeLevel: number, device: DeviceType): number 527 528Obtains the volume (in dB) calculated by the system based on the audio stream, volume level, and device type. 529 530**System capability**: SystemCapability.Multimedia.Audio.Volume 531 532**Parameters** 533 534| Name | Type | Mandatory| Description | 535| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 536| streamUsage | [StreamUsage](arkts-apis-audio-e.md#streamusage) | Yes | Audio stream.| 537| volumeLevel | number | Yes | Volume level.| 538| device | [DeviceType](arkts-apis-audio-e.md#devicetype) | Yes | Device type.| 539 540**Return value** 541 542| Type | Description | 543| ------------------- | ----------------------------- | 544| number | Volume of the audio stream, in dB.| 545 546**Error codes** 547 548For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 549 550| ID| Error Message| 551| ------- | --------------------------------------------| 552| 6800101 | Parameter verification failed. | 553 554**Example** 555 556```ts 557// Obtain the volume (in dB) calculated by the system based on the audio stream, volume level, and device type. 558import { BusinessError } from '@kit.BasicServicesKit'; 559import { audio } from '@kit.AudioKit' 560 561try { 562 let volumeInDb : number = audio.getAudioManager().getVolumeManager().getVolumeInUnitOfDbByStream(audio.StreamUsage.STREAM_USAGE_MUSIC, 5, audio.DeviceType.SPEAKER); 563 console.info(`Gets the volume db value that system calculate by volume stream, volume level and device type. 564 success.`); 565} catch (err) { 566 let error = err as BusinessError; 567 console.error(`Failed to gets the volume db value that system calculate by volume stream, volume level and device type., error: ${error}`); 568} 569``` 570 571## on('streamVolumeChange')<sup>20+</sup> 572 573 on(type: 'streamVolumeChange', streamUsage: StreamUsage, callback: Callback\<StreamVolumeEvent>): void 574 575Subscribes to the system audio volume change event, which is triggered when the system audio volume is changed. This API uses an asynchronous callback to return the result. 576 577**System capability**: SystemCapability.Multimedia.Audio.Volume 578 579**Parameters** 580 581| Name | Type | Mandatory| Description | 582| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 583| type | string | Yes | Event type. The event **'streamVolumeChange'** is triggered when the system audio volume is changed.| 584| streamUsage | [StreamUsage](arkts-apis-audio-e.md#streamusage) | Yes | Audio stream usage.| 585| callback | Callback<[StreamVolumeEvent](arkts-apis-audio-i.md#streamvolumeevent20)> | Yes | Callback used to return the changed volume.| 586 587**Error codes** 588 589For details about the error codes, see [Audio Error Codes](errorcode-audio.md). 590 591| ID| Error Message| 592| ------- | --------------------------------------------| 593| 6800101 | Parameter verification failed. | 594 595**Example** 596 597```ts 598audioVolumeManager.on('streamVolumeChange', audio.StreamUsage.STREAM_USAGE_MUSIC, (streamVolumeEvent: audio.StreamVolumeEvent) => { 599 console.info(`StreamUsage of stream: ${streamVolumeEvent.streamUsage} `); 600 console.info(`Volume level: ${streamVolumeEvent.volume} `); 601 console.info(`Whether to updateUI: ${streamVolumeEvent.updateUi} `); 602}); 603``` 604 605## off('streamVolumeChange')<sup>20+</sup> 606 607off(type: 'streamVolumeChange', callback?: Callback\<StreamVolumeEvent>): void 608 609Unsubscribes from the system audio volume change event, which is triggered when the system audio volume is changed. This API uses an asynchronous callback to return the result. 610 611**System capability**: SystemCapability.Multimedia.Audio.Volume 612 613**Parameters** 614 615| Name | Type | Mandatory| Description | 616| -------- | -------------------------------------- | ---- | ------------------------------------------------------------ | 617| type | string | Yes | Event type. The event **'volumeChange'** is triggered when the system volume is changed.| 618| callback | Callback<[StreamVolumeEvent](arkts-apis-audio-i.md#streamvolumeevent20)> | No | Callback used to return the changed volume.| 619 620**Example** 621 622```ts 623// Cancel all subscriptions to the event. 624audioVolumeManager.off('streamVolumeChange'); 625 626// For the same event, if the callback parameter passed to the off API is the same as that passed to the on API, the off API cancels the subscription registered with the specified callback parameter. 627let streamVolumeChangeCallback = (streamVolumeEvent: audio.StreamVolumeEvent) => { 628 console.info(`StreamUsage of stream: ${streamVolumeEvent.streamUsage} `); 629 console.info(`Volume level: ${streamVolumeEvent.volume} `); 630 console.info(`Whether to updateUI: ${streamVolumeEvent.updateUi} `); 631}; 632 633audioVolumeManager.on('streamVolumeChange', audio.StreamUsage.STREAM_USAGE_MUSIC, streamVolumeChangeCallback); 634 635audioVolumeManager.off('streamVolumeChange', streamVolumeChangeCallback); 636``` 637