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