1# systemTonePlayer (System Tone Player) (System API) 2 3The module provides APIs for playing and configuring SMS tones and notification tones and obtaining related information. 4 5This module must work with [@ohos.multimedia.systemSoundManager](js-apis-systemSoundManager-sys.md) to manage system 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 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 tones and notification 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 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 [Universal Error Codes](../errorcode-universal.md) and [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 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 that returns no value.| 87 88**Error codes** 89 90For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [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 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 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 [Universal Error Codes](../errorcode-universal.md) and [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 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.| 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 [Universal Error Codes](../errorcode-universal.md) and [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 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 that returns no value.| 223 224**Error codes** 225 226For details about the error codes, see [Universal Error Codes](../errorcode-universal.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 [Universal Error Codes](../errorcode-universal.md), [Media Error Codes](../apis-media-kit/errorcode-media.md), and [Ringtone Error Codes](./errorcode-ringtone.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 [Universal Error Codes](../errorcode-universal.md). 302 303| ID| Error Message | 304| -------- | ----------------------------------- | 305| 202 | Caller is not a system application. | 306 307**Example** 308 309```ts 310try { 311 let scale: number = systemTonePlayer.getAudioVolumeScale(); 312 console.info(` get audio volume scale. ${scale}`); 313} catch (err) { 314 console.error(`Failed to get audio volume scale. ${err}`); 315} 316``` 317 318### getSupportedHapticsFeatures<sup>13+</sup> 319 320getSupportedHapticsFeatures(): Promise<Array<systemSoundManager.ToneHapticsFeature>> 321 322Obtains the supported haptics styles. This API uses a promise to return the result. 323 324**System API**: This is a system API. 325 326**System capability**: SystemCapability.Multimedia.SystemSound.Core 327 328**Return value** 329 330| Type | Description | 331|-----------------------------------------------------------------------------------------------------------------------------| --------------------------------------------------------------------------------------------------------------------- | 332| Promise<Array<[systemSoundManager.ToneHapticsFeature](js-apis-systemSoundManager-sys.md#tonehapticsfeature13)>> | Promise used to return an array of the supported haptics styles.| 333 334**Error codes** 335 336For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ringtone Error Codes](./errorcode-ringtone.md). 337 338| ID| Error Message | 339| -------- | ----------------------------------- | 340| 202 | Caller is not a system application. | 341| 20700003 | Unsupported operation. | 342 343**Example** 344 345```ts 346try { 347 let features: Array<systemSoundManager.ToneHapticsFeature> = await systemTonePlayer.getSupportedHapticsFeatures(); 348 console.info(` get supported haptics features. ${features}`); 349} catch (err) { 350 console.error(`Failed to get supported haptics features. ${err}`); 351} 352``` 353 354### setHapticsFeature<sup>13+</sup> 355 356setHapticsFeature(hapticsFeature: systemSoundManager.ToneHapticsFeature): void 357 358Sets a haptics style of the ringtone. 359 360Before calling this API, call [getSupportedHapticsFeatures](#getsupportedhapticsfeatures13) to obtain the supported haptics styles. The setting fails if the haptics style to set is not supported. 361 362**System API**: This is a system API. 363 364**System capability**: SystemCapability.Multimedia.SystemSound.Core 365 366**Parameters** 367 368| Name | Type | Mandatory| Description | 369| -------------- |-------------------------------------------------------------------------------------------------| ---- | ---------------- | 370| hapticsFeature | [systemSoundManager.ToneHapticsFeature](js-apis-systemSoundManager-sys.md#tonehapticsfeature13) | Yes | Haptics style.| 371 372**Error codes** 373 374For details about the error codes, see [Universal Error Codes](../errorcode-universal.md), [Media Error Codes](../apis-media-kit/errorcode-media.md), and [Ringtone Error Codes](./errorcode-ringtone.md). 375 376| ID| Error Message | 377| -------- | ----------------------------------------------------------------------------------------------------------- | 378| 202 | Caller is not a system application. | 379| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 380| 5400102 | Operation not allowed. | 381| 20700003 | Unsupported operation. | 382 383**Example** 384 385```ts 386try { 387 let features: Array<systemSoundManager.ToneHapticsFeature> = await systemTonePlayer.getSupportedHapticsFeatures(); 388 if (features.lenght == 0) { 389 return; 390 } 391 let feature: systemSoundManager.ToneHapticsFeature = features[0]; 392 systemTonePlayer.setHapticsFeature(feature); 393 console.info(` set haptics feature success`); 394} catch (err) { 395 console.error(`Failed to set haptics feature. ${err}`); 396} 397``` 398 399### getHapticsFeature<sup>13+</sup> 400 401getHapticsFeature(): systemSoundManager.ToneHapticsFeature 402 403Obtains the haptics style of the ringtone. This API returns the result synchronously. 404 405**System API**: This is a system API. 406 407**System capability**: SystemCapability.Multimedia.SystemSound.Core 408 409**Return value** 410 411| Type | Description | 412|-------------------------------------------------------------------------------------------------| -------- | 413| [systemSoundManager.ToneHapticsFeature](js-apis-systemSoundManager-sys.md#tonehapticsfeature13) | Haptics style.| 414 415**Error codes** 416 417For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ringtone Error Codes](./errorcode-ringtone.md). 418 419 420| ID| Error Message | 421| -------- | ----------------------------------- | 422| 202 | Caller is not a system application. | 423| 20700003 | Unsupported operation. | 424 425**Example** 426 427```ts 428try { 429 let feature: systemSoundManager.ToneHapticsFeature = systemTonePlayer.getHapticsFeature(); 430 console.info(` get haptics feature success. ${features}`); 431} catch (err) { 432 console.error(`Failed to get haptics feature. ${err}`); 433} 434``` 435 436### on('playFinished')<sup>18+</sup> 437 438on(type: 'playFinished', streamId: number, callback: Callback\<number>): void 439 440Subscribes to the event indicating that the ringtone playback is finished. This API uses an asynchronous callback to return the result. 441 442The object to listen for is an audio stream specified by **streamId**. If **streamId** is set to **0**, this API subscribes to the playback complete event of all audio streams of the player. 443 444**System capability**: SystemCapability.Multimedia.SystemSound.Core 445 446**Parameters** 447 448| Name | Type | Mandatory| Description | 449| -------- | ----------------------- | ---- | --------------------------------------------------------------- | 450| type | string | Yes | Event type. The event **'playFinished'** is triggered when the playback is finished.| 451| 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.| 452| callback | Callback\<number> | Yes | Callback used to return the stream ID of the audio stream that finishes playing.| 453 454**Error codes** 455 456For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ringtone Error Codes](./errorcode-ringtone.md). 457 458| ID| Error Message| 459| ------- | --------------------------------------------| 460| 202 | Not system App. | 461| 20700002 | Parameter check error. | 462 463**Example** 464 465```ts 466import { BusinessError } from '@kit.BasicServicesKit'; 467 468// Subscribe to the playback complete events of all audio streams. 469systemTonePlayer.on('playFinished', 0, (streamId: number) => { 470 console.info(`Receive the callback of playFinished, streamId: ${streamId}.`); 471}); 472 473// Subscribe to the playback complete event of a specified audio stream. 474systemTonePlayer.start().then((value: number) => { 475 systemTonePlayer.on('playFinished', value, (streamId: number) => { 476 console.info(`Receive the callback of playFinished, streamId: ${streamId}.`); 477 }); 478}).catch((err: BusinessError) => { 479 console.error(`Failed to start system tone player. ${err}`); 480}); 481``` 482 483### off('playFinished')<sup>18+</sup> 484 485off(type: 'playFinished', callback?: Callback\<number>): void 486 487Unsubscribes from the event indicating that the ringtone playback is finished. This API uses an asynchronous callback to return the result. 488 489**System capability**: SystemCapability.Multimedia.SystemSound.Core 490 491**Parameters** 492 493| Name| Type | Mandatory| Description | 494| ----- | ----- | ---- | ------------------------------------------------ | 495| type | string | Yes | Event type. The event **'playFinished'** is triggered when the playback is finished.| 496| 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.| 497 498**Error codes** 499 500For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ringtone Error Codes](./errorcode-ringtone.md). 501 502| ID| Error Message| 503| ------- | --------------------------------------------| 504| 202 | Not system App. | 505| 20700002 | Parameter check error. | 506 507**Example** 508 509```ts 510// Cancel all subscriptions to the event. 511systemTonePlayer.off('playFinished'); 512 513// 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. 514let playFinishedCallback = (streamId: number) => { 515 console.info(`Receive the callback of playFinished, streamId: ${streamId}.`); 516}; 517 518systemTonePlayer.on('playFinished', 0, playFinishedCallback); 519 520systemTonePlayer.off('playFinished', playFinishedCallback); 521``` 522 523### on('error')<sup>18+</sup> 524 525on(type: 'error', callback: ErrorCallback): void 526 527Subscribes to error events that occur during ringtone playback. This API uses an asynchronous callback to return the result. 528 529**System capability**: SystemCapability.Multimedia.SystemSound.Core 530 531**Parameters** 532 533| Name | Type | Mandatory| Description | 534| -------- | ------------- | ---- | ------------------------------------ | 535| type | string | Yes | Event type. The event **'error'** is triggered when an error occurs during ringtone playback.| 536| 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/arkts-apis-media-AVPlayer.md#onerror9) of the AVPlayer.| 537 538**Error codes** 539 540For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ringtone Error Codes](./errorcode-ringtone.md). 541 542| ID| Error Message| 543| ------- | --------------------------------------------| 544| 202 | Not system App. | 545| 20700002 | Parameter check error. | 546 547**Example** 548 549```ts 550import { BusinessError } from '@kit.BasicServicesKit'; 551 552systemTonePlayer.on('error', (err: BusinessError) => { 553 console.log("on error, err:" + JSON.stringify(err)); 554}); 555``` 556 557### off('error')<sup>18+</sup> 558 559off(type: 'error', callback?: ErrorCallback): void 560 561Unsubscribes from error events that occur during ringtone playback. This API uses an asynchronous callback to return the result. 562 563**System capability**: SystemCapability.Multimedia.SystemSound.Core 564 565**Parameters** 566 567| Name | Type | Mandatory| Description | 568| -------- | ------------- | ---- | ------------------------------------ | 569| type | string | Yes | Event type. The event **'error'** is triggered when an error occurs during ringtone playback.| 570| 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.| 571 572**Error codes** 573 574For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Ringtone Error Codes](./errorcode-ringtone.md). 575 576| ID| Error Message| 577| ------- | --------------------------------------------| 578| 202 | Not system App. | 579| 20700002 | Parameter check error. | 580 581**Example** 582 583```ts 584import { BusinessError } from '@kit.BasicServicesKit'; 585 586// Cancel all subscriptions to the event. 587systemTonePlayer.off('error'); 588 589// 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. 590let callback = (err: BusinessError) => { 591 console.log("on error, err:" + JSON.stringify(err)); 592}; 593 594systemTonePlayer.on('error', callback); 595 596systemTonePlayer.off('error', callback); 597``` 598 599<!--no_check-->