1# systemTonePlayer (System Alert Tone Player) (System API) 2 3The systemTonePlayer module provides APIs for playing and configuring SMS alert tones and notification alert tones and obtaining related information. 4 5This module must work with [@ohos.multimedia.systemSoundManager](js-apis-systemSoundManager-sys.md) to manage system alert tones. 6 7> **NOTE** 8> 9> - The initial APIs of this module are supported since API version 11. Newly added APIs will be marked with a superscript to indicate their earliest API version. 10> - The APIs provided by this module are system APIs. 11 12## Modules to Import 13 14```ts 15import { systemSoundManager } from '@kit.AudioKit'; 16``` 17 18## SystemToneOptions 19 20Describes the options of system alert tones. 21 22**System API**: This is a system API. 23 24**System capability**: SystemCapability.Multimedia.SystemSound.Core 25 26| Name | Type | Mandatory| Description | 27| ----------- | ------- | ---- | --------------------------------------------- | 28| muteAudio | boolean | No | Whether the sound is muted. The value **true** means that the sound is muted, and **false** means the opposite. | 29| muteHaptics | boolean | No | Whether haptics feedback is turned off. The value **true** means that haptics feedback is turned off, and **false** means the opposite.| 30 31## SystemTonePlayer 32 33Implements APIs for playing and configuring SMS alert tones and notification alert tones and obtaining related information. Before calling any API in **SystemTonePlayer**, you must use [getSystemTonePlayer](js-apis-systemSoundManager-sys.md#getsystemtoneplayer11) to create a **SystemTonePlayer** instance. 34 35### getTitle 36 37getTitle(): Promise<string> 38 39Obtains the title of a system alert tone. This API uses a promise to return the result. 40 41**System API**: This is a system API. 42 43**System capability**: SystemCapability.Multimedia.SystemSound.Core 44 45**Return value** 46 47| Type | Description | 48| ------- | ------------------------------------- | 49| Promise<string> | Promise used to return the title obtained.| 50 51**Error codes** 52 53For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 54 55| ID| Error Message | 56| -------- | ----------------------------------- | 57| 202 | Caller is not a system application. | 58| 5400103 | I/O error. | 59 60**Example** 61 62```ts 63import { BusinessError } from '@kit.BasicServicesKit'; 64 65systemTonePlayer.getTitle().then((value: string) => { 66 console.info(`Promise returned to indicate that the value of the system tone player title is obtained ${value}.`); 67}).catch ((err: BusinessError) => { 68 console.error(`Failed to get the system tone player title ${err}`); 69}); 70``` 71 72### prepare 73 74prepare(): Promise<void> 75 76Prepares to play a system alert tone. This API uses a promise to return the result. 77 78**System API**: This is a system API. 79 80**System capability**: SystemCapability.Multimedia.SystemSound.Core 81 82**Return value** 83 84| Type | Description | 85| ------- | ------------------------------- | 86| Promise<void> | Promise used to return the result.| 87 88**Error codes** 89 90For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 91 92| ID| Error Message | 93| -------- | ----------------------------------- | 94| 202 | Caller is not a system application. | 95| 5400102 | Operation not allowed. | 96| 5400103 | I/O error. | 97 98**Example** 99 100```ts 101import { BusinessError } from '@kit.BasicServicesKit'; 102 103systemTonePlayer.prepare().then(() => { 104 console.info(`Promise returned to indicate a successful prepareing of system tone player.`); 105}).catch ((err: BusinessError) => { 106 console.error(`Failed to prepareing system tone player. ${err}`); 107}); 108``` 109 110### start 111 112start(toneOptions?: SystemToneOptions): Promise<number> 113 114Starts playing a system alert tone. This API uses a promise to return the result. 115 116**System API**: This is a system API. 117 118**System capability**: SystemCapability.Multimedia.SystemSound.Core 119 120**Required permissions**: ohos.permission.VIBRATE 121 122**Parameters** 123 124| Name | Type | Mandatory| Description | 125| ----------- | --------------------------------------- | ---- | ---------------- | 126| toneOptions | [SystemToneOptions](#systemtoneoptions) | No | Options of the system alert tone.| 127 128**Return value** 129 130| Type | Description | 131| ------- | ------------------------- | 132| Promise<number> | Promise used to return the stream ID.| 133 134**Error codes** 135 136For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 137 138| ID| Error Message | 139| -------- | ----------------------------------------------------------------------------------------------------------- | 140| 201 | Permission denied. | 141| 202 | Caller is not a system application. | 142| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 143| 5400102 | Operation not allowed. | 144 145**Example** 146 147```ts 148import { BusinessError } from '@kit.BasicServicesKit'; 149 150class SystemToneOptions { 151 muteAudio: boolean = false; 152 muteHaptics: boolean = false; 153} 154let systemToneOptions: SystemToneOptions = {muteAudio: true, muteHaptics: false}; 155 156systemTonePlayer.start(systemToneOptions).then((value: number) => { 157 console.info(`Promise returned to indicate that the value of the system tone player streamID is obtained ${value}.`); 158}).catch ((err: BusinessError) => { 159 console.error(`Failed to start system tone player. ${err}`); 160}); 161``` 162 163### stop 164 165stop(id: number): Promise<void> 166 167Stops playing a system alert tone. This API uses a promise to return the result. 168 169**System API**: This is a system API. 170 171**System capability**: SystemCapability.Multimedia.SystemSound.Core 172 173**Parameters** 174 175| Name| Type | Mandatory| Description | 176| ------ | ------ | ---- | ------------------------- | 177| id | number | Yes | Stream ID returned by **start()**.| 178 179**Return value** 180 181| Type | Description | 182| ------- | ----------------------------------- | 183| Promise<void> | Promise used to return the result.| 184 185**Error codes** 186 187For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 188 189| ID| Error Message | 190| -------- | ----------------------------------------------------------------------------------------------------------- | 191| 202 | Caller is not a system application. | 192| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 193| 5400102 | Operation not allowed. | 194 195**Example** 196 197```ts 198import { BusinessError } from '@kit.BasicServicesKit'; 199 200let streamID: number = 0; // streamID is the stream ID returned by start(). Only initialization is performed here. 201systemTonePlayer.stop(streamID).then(() => { 202 console.info(`Promise returned to indicate a successful stopping of system tone player.`); 203}).catch ((err: BusinessError) => { 204 console.error(`Failed to stop system tone player. ${err}`); 205}); 206``` 207 208### release 209 210release(): Promise<void> 211 212Releases the system alert tone player. This API uses a promise to return the result. 213 214**System API**: This is a system API. 215 216**System capability**: SystemCapability.Multimedia.SystemSound.Core 217 218**Return value** 219 220| Type | Description | 221| ------- | ------------------------------- | 222| Promise<void> | Promise used to return the result.| 223 224**Error codes** 225 226For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 227 228| ID| Error Message | 229| -------- | ----------------------------------- | 230| 202 | Caller is not a system application. | 231 232**Example** 233 234```ts 235import { BusinessError } from '@kit.BasicServicesKit'; 236 237systemTonePlayer.release().then(() => { 238 console.info(`Promise returned to indicate a successful releasing of system tone player.`); 239}).catch ((err: BusinessError) => { 240 console.error(`Failed to release system tone player. ${err}`); 241}); 242``` 243 244### setAudioVolumeScale<sup>13+</sup> 245 246setAudioVolumeScale(scale: number): void 247 248Sets the scale of the audio volume. No result is returned. 249 250**System API**: This is a system API. 251 252**System capability**: SystemCapability.Multimedia.SystemSound.Core 253 254**Parameters** 255 256| Name| Type | Mandatory| Description | 257| ------ | ------ | ---- | ------------------------------------ | 258| scale | number | Yes | Scale of the audio volume. The value is in the range [0, 1].| 259 260**Error codes** 261 262For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 263 264| ID| Error Message | 265| -------- | ----------------------------------------------------------------------------------------------------------- | 266| 202 | Caller is not a system application. | 267| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 268| 5400102 | Operation not allowed. | 269| 20700002 | Parameter check error, For example, value is out side [0, 1] | 270 271**Example** 272 273```ts 274let scale: number = 0.5; 275try { 276 systemTonePlayer.setAudioVolumeScale(scale); 277} catch (err) { 278 console.error(`Failed to set audio volume scale. ${err}`); 279} 280``` 281 282### getAudioVolumeScale<sup>13+</sup> 283 284getAudioVolumeScale(): number; 285 286Obtains the scale of the audio volume. This API returns the result synchronously. 287 288**System API**: This is a system API. 289 290**System capability**: SystemCapability.Multimedia.SystemSound.Core 291 292**Return value** 293 294 295| Type | Description | 296| ------ | ------------ | 297| number | Scale of the audio volume.| 298 299**Error codes** 300 301For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 302 303 304| ID| Error Message | 305| -------- | ----------------------------------- | 306| 202 | Caller is not a system application. | 307 308**Example** 309 310```ts 311try { 312 let scale: number = systemTonePlayer.getAudioVolumeScale(); 313 console.info(` get audio volume scale. ${scale}`); 314} catch (err) { 315 console.error(`Failed to get audio volume scale. ${err}`); 316} 317``` 318 319### getSupportedHapticsFeatures<sup>13+</sup> 320 321getSupportedHapticsFeatures(): Promise<Array<systemSoundManager.ToneHapticsFeature>> 322 323Obtains the supported haptics styles. This API uses a promise to return the result. 324 325**System API**: This is a system API. 326 327**System capability**: SystemCapability.Multimedia.SystemSound.Core 328 329**Return value** 330 331 332| Type | Description | 333|-----------------------------------------------------------------------------------------------------------------------------| --------------------------------------------------------------------------------------------------------------------- | 334| Promise<Array<[systemSoundManager.ToneHapticsFeature](js-apis-systemSoundManager-sys.md#tonehapticsfeature13)>> | Promise used to return an array of the supported haptics styles.| 335 336**Error codes** 337 338For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 339 340 341| ID| Error Message | 342| -------- | ----------------------------------- | 343| 202 | Caller is not a system application. | 344| 20700003 | Unsupported operation. | 345 346**Example** 347 348```ts 349try { 350 let features: Array<systemSoundManager.ToneHapticsFeature> = await systemTonePlayer.getSupportedHapticsFeatures(); 351 console.info(` get supported haptics features. ${features}`); 352} catch (err) { 353 console.error(`Failed to get supported haptics features. ${err}`); 354} 355``` 356 357### setHapticsFeature<sup>13+</sup> 358 359setHapticsFeature(hapticsFeature: systemSoundManager.ToneHapticsFeature): void 360 361Sets a haptics style of the ringtone. 362 363Before calling this API, call [getSupportedHapticsFeatures](#getsupportedhapticsfeatures13) to obtain the supported haptics styles. The setting fails if the haptics style to set is not supported. 364 365**System API**: This is a system API. 366 367**System capability**: SystemCapability.Multimedia.SystemSound.Core 368**Parameters** 369 370 371| Name | Type | Mandatory| Description | 372| -------------- |-------------------------------------------------------------------------------------------------| ---- | ---------------- | 373| hapticsFeature | [systemSoundManager.ToneHapticsFeature](js-apis-systemSoundManager-sys.md#tonehapticsfeature13) | Yes | Haptics style.| 374 375**Error codes** 376 377For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 378 379 380| ID| Error Message | 381| -------- | ----------------------------------------------------------------------------------------------------------- | 382| 202 | Caller is not a system application. | 383| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 384| 5400102 | Operation not allowed. | 385| 20700003 | Unsupported operation. | 386 387**Example** 388 389```ts 390try { 391 let features: Array<systemSoundManager.ToneHapticsFeature> = await systemTonePlayer.getSupportedHapticsFeatures(); 392 if (features.lenght == 0) { 393 return; 394 } 395 let feature: systemSoundManager.ToneHapticsFeature = features[0]; 396 systemTonePlayer.setHapticsFeature(feature); 397 console.info(` set haptics feature success`); 398} catch (err) { 399 console.error(`Failed to set haptics feature. ${err}`); 400} 401``` 402 403### getHapticsFeature<sup>13+</sup> 404 405getHapticsFeature(): systemSoundManager.ToneHapticsFeature 406 407Obtains the haptics style of the ringtone. This API returns the result synchronously. 408 409**System API**: This is a system API. 410 411**System capability**: SystemCapability.Multimedia.SystemSound.Core 412 413**Return value** 414 415 416| Type | Description | 417|-------------------------------------------------------------------------------------------------| -------- | 418| [systemSoundManager.ToneHapticsFeature](js-apis-systemSoundManager-sys.md#tonehapticsfeature13) | Haptics style.| 419 420**Error codes** 421 422For details about the error codes, see [Media Error Codes](../apis-media-kit/errorcode-media.md). 423 424 425| ID| Error Message | 426| -------- | ----------------------------------- | 427| 202 | Caller is not a system application. | 428| 20700003 | Unsupported operation. | 429 430**Example** 431 432```ts 433try { 434 let feature: systemSoundManager.ToneHapticsFeature = systemTonePlayer.getHapticsFeature(); 435 console.info(` get haptics feature success. ${features}`); 436} catch (err) { 437 console.error(`Failed to get haptics feature. ${err}`); 438} 439``` 440 441### on('playFinished')<sup>18+</sup> 442 443on(type: 'playFinished', streamId: number, callback: Callback\<number>): void 444 445Subscribes to the event indicating that the playback of an audio stream specified by **streamId** is complete. If **streamId** is set to **0**, this API subscribes to the playback complete event of all audio streams of the player. 446 447**System capability**: SystemCapability.Multimedia.SystemSound.Core 448 449**Parameters** 450 451| Name | Type | Mandatory| Description | 452| -------- | ----------------------- | ---- | --------------------------------------------------------------- | 453| type | string | Yes | Event type. The event **'playFinished'** is triggered when the playback of the audio stream specified by **streamId** is complete.| 454| streamId | number | Yes | ID of the audio stream. **streamId** is obtained through [start](#start). If **streamId** is set to **0**, the playback complete event of all audio streams of the player is subscribed to.| 455| callback | Callback\<number> | Yes | Callback used to return the stream ID of the audio stream that finishes playing.| 456 457**Error codes** 458 459For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ring Error Codes](./errorcode-ringtone.md). 460 461| ID| Error Message| 462| ------- | --------------------------------------------| 463| 202 | Not system App. | 464| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 465| 20700002 | Parameter check error. | 466 467**Example** 468 469```ts 470import { BusinessError } from '@kit.BasicServicesKit'; 471 472// Subscribe to the playback complete events of all audio streams. 473systemTonePlayer.on('playFinished', 0, (streamId: number) => { 474 console.info(`Receive the callback of playFinished, streamId: ${streamId}.`); 475}); 476 477// Subscribe to the playback complete event of a specified audio stream. 478systemTonePlayer.start().then((value: number) => { 479 systemTonePlayer.on('playFinished', value, (streamId: number) => { 480 console.info(`Receive the callback of playFinished, streamId: ${streamId}.`); 481 }); 482}).catch((err: BusinessError) => { 483 console.error(`Failed to start system tone player. ${err}`); 484}); 485``` 486 487### off('playFinished')<sup>18+</sup> 488 489off(type: 'playFinished', callback?: Callback\<number>): void 490 491Unsubscribes from the event indicating that the audio stream playback is complete. 492 493**System capability**: SystemCapability.Multimedia.SystemSound.Core 494 495**Parameters** 496 497| Name| Type | Mandatory| Description | 498| ----- | ----- | ---- | ------------------------------------------------ | 499| type | string | Yes | Event type. The event **'playFinished'** is triggered when the playback is complete.| 500| callback | Callback\<number> | No | Callback used to return the ID of the audio stream. If this parameter is not specified, all the subscriptions to the specified event are canceled.| 501 502**Error codes** 503 504For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ring Error Codes](./errorcode-ringtone.md). 505 506| ID| Error Message| 507| ------- | --------------------------------------------| 508| 202 | Not system App. | 509| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 510| 20700002 | Parameter check error. | 511 512**Example** 513 514```ts 515// Cancel all subscriptions to the event. 516systemTonePlayer.off('playFinished'); 517 518// 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. 519let playFinishedCallback = (streamId: number) => { 520 console.info(`Receive the callback of playFinished, streamId: ${streamId}.`); 521}; 522 523systemTonePlayer.on('playFinished', 0, playFinishedCallback); 524 525systemTonePlayer.off('playFinished', playFinishedCallback); 526``` 527 528### on('error')<sup>18+</sup> 529 530on(type: 'error', callback: ErrorCallback): void 531 532Subscribes to error events that occur during ringtone playback. 533 534**System capability**: SystemCapability.Multimedia.SystemSound.Core 535 536**Parameters** 537 538| Name | Type | Mandatory| Description | 539| -------- | ------------- | ---- | ------------------------------------ | 540| type | string | Yes | Event type, which is **error** in this case.| 541| callback | ErrorCallback | Yes | Callback used to return the error code and error information. For details about the error codes, see [on('error')](../apis-media-kit/js-apis-media.md#onerror9) of the AVPlayer.| 542 543**Error codes** 544 545For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ring Error Codes](./errorcode-ringtone.md). 546 547| ID| Error Message| 548| ------- | --------------------------------------------| 549| 202 | Not system App. | 550| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 551| 20700002 | Parameter check error. | 552 553**Example** 554 555```ts 556import { BusinessError } from '@kit.BasicServicesKit'; 557 558systemTonePlayer.on('error', (err: BusinessError) => { 559 console.log("on error, err:" + JSON.stringify(err)); 560}); 561``` 562 563### off('error')<sup>18+</sup> 564 565off(type: 'error', callback?: ErrorCallback): void 566 567Unsubscribes from the error events that occur during ringtone playback. 568 569**System capability**: SystemCapability.Multimedia.SystemSound.Core 570 571**Parameters** 572 573| Name | Type | Mandatory| Description | 574| -------- | ------------- | ---- | ------------------------------------ | 575| type | string | Yes | Event type, which is **error** in this case.| 576| callback | ErrorCallback | No | Callback used to return the error code and error information. If this parameter is not specified, all the subscriptions to the specified event are canceled.| 577 578**Error codes** 579 580For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ring Error Codes](./errorcode-ringtone.md). 581 582| ID| Error Message| 583| ------- | --------------------------------------------| 584| 202 | Not system App. | 585| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 586| 20700002 | Parameter check error. | 587 588**Example** 589 590```ts 591import { BusinessError } from '@kit.BasicServicesKit'; 592 593// Cancel all subscriptions to the event. 594systemTonePlayer.off('error'); 595 596// 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. 597let callback = (err: BusinessError) => { 598 console.log("on error, err:" + JSON.stringify(err)); 599}; 600 601systemTonePlayer.on('error', callback); 602 603systemTonePlayer.off('error', callback); 604``` 605