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