1# systemTonePlayer (System Alert Tone Player) 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.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> 11> The APIs provided by this module are system APIs. 12 13## Modules to Import 14 15```ts 16import systemSoundManager from '@ohos.multimedia.systemSoundManager'; 17``` 18 19## SystemToneOptions 20 21Describes the options of system alert tones. 22 23**System API**: This is a system API. 24 25**System capability**: SystemCapability.Multimedia.SystemSound.Core 26 27| Name | Type | Mandatory| Description | 28| --------- | -------------- |---|---------------------------| 29| muteAudio | boolean | No| Whether the sound is muted. The value **true** means that the sound is muted, and **false** means the opposite.| 30| muteHaptics | boolean | No| Whether haptics feedback is turned off. The value **true** means that haptics feedback is turned off, and **false** means the opposite.| 31 32## SystemTonePlayer 33 34Implements 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.md#getsystemtoneplayer11) to create a **SystemTonePlayer** instance. 35 36### getTitle 37 38getTitle(): Promise<string> 39 40Obtains the title of a system alert tone. This API uses a promise to return the result. 41 42**System API**: This is a system API. 43 44**System capability**: SystemCapability.Multimedia.SystemSound.Core 45 46**Return value** 47 48| Type | Description | 49| --------------------- | -------------------------------- | 50| Promise<string> | Promise used to return the title obtained.| 51 52**Error codes** 53 54For details about the error codes, see [Media Error Codes](../errorcodes/errorcode-media.md). 55 56| ID| Error Message | 57| ------- | --------------------- | 58| 5400103 | I/O error. | 59 60**Example** 61 62```ts 63import { BusinessError } from '@ohos.base'; 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](../errorcodes/errorcode-media.md). 91 92| ID| Error Message | 93| ------- | --------------------- | 94| 5400102 | Operation not allowed. | 95| 5400103 | I/O error. | 96 97**Example** 98 99```ts 100import { BusinessError } from '@ohos.base'; 101 102systemTonePlayer.prepare().then(() => { 103 console.info(`Promise returned to indicate a successful prepareing of system tone player.`); 104}).catch ((err: BusinessError) => { 105 console.error(`Failed to prepareing system tone player. ${err}`); 106}); 107``` 108 109### start 110 111start(toneOptions?: SystemToneOptions): Promise<number> 112 113Starts playing a system alert tone. This API uses a promise to return the result. 114 115**System API**: This is a system API. 116 117**System capability**: SystemCapability.Multimedia.SystemSound.Core 118 119**Required permissions**: ohos.permission.VIBRATE 120 121**Parameters** 122 123| Name | Type | Mandatory| Description | 124| -------- |-----------------------------------------|--| ------------------------- | 125| toneOptions | [SystemToneOptions](#systemtoneoptions) | No| Options of the system alert tone.| 126 127**Return value** 128 129| Type | Description | 130| ------------------- | ------------------------------- | 131| Promise<number> | Promise used to return the stream ID.| 132 133**Error codes** 134 135For details about the error codes, see [Media Error Codes](../errorcodes/errorcode-media.md). 136 137| ID| Error Message | 138| ------- | --------------------- | 139| 5400102 | Operation not allowed. | 140 141**Example** 142 143```ts 144import { BusinessError } from '@ohos.base'; 145 146class SystemToneOptions { 147 muteAudio: boolean = false; 148 muteHaptics: boolean = false; 149} 150let systemToneOptions: SystemToneOptions = {muteAudio: true, muteHaptics: false}; 151 152systemTonePlayer.start(systemToneOptions).then((value: number) => { 153 console.info(`Promise returned to indicate that the value of the system tone player streamID is obtained ${value}.`); 154}).catch ((err: BusinessError) => { 155 console.error(`Failed to start system tone player. ${err}`); 156}); 157``` 158 159### stop 160 161stop(id: number): Promise<void> 162 163Stops playing a system alert tone. This API uses a promise to return the result. 164 165**System API**: This is a system API. 166 167**System capability**: SystemCapability.Multimedia.SystemSound.Core 168 169**Parameters** 170 171| Name | Type | Mandatory| Description | 172| -------- |-----------------------------------------|--| ------------------------- | 173| id | number | Yes| Stream ID returned by **start()**.| 174 175**Return value** 176 177| Type | Description | 178| ------------------- | -------------------------------- | 179| Promise<void> | Promise used to return the result.| 180 181**Error codes** 182 183For details about the error codes, see [Media Error Codes](../errorcodes/errorcode-media.md). 184 185| ID| Error Message | 186| ------- | --------------------- | 187| 5400102 | Operation not allowed. | 188 189**Example** 190 191```ts 192import { BusinessError } from '@ohos.base'; 193 194let streamID: number = 0; // streamID is the stream ID returned by start(). Only initialization is performed here. 195systemTonePlayer.stop(streamID).then(() => { 196 console.info(`Promise returned to indicate a successful stopping of system tone player.`); 197}).catch ((err: BusinessError) => { 198 console.error(`Failed to stop system tone player. ${err}`); 199}); 200``` 201 202### release 203 204release(): Promise<void> 205 206Releases the system alert tone player. This API uses a promise to return the result. 207 208**System API**: This is a system API. 209 210**System capability**: SystemCapability.Multimedia.SystemSound.Core 211 212**Return value** 213 214| Type | Description | 215| ------------------- | ------------------------------- | 216| Promise<void> | Promise used to return the result. | 217 218**Example** 219 220```ts 221import { BusinessError } from '@ohos.base'; 222 223systemTonePlayer.release().then(() => { 224 console.info(`Promise returned to indicate a successful releasing of system tone player.`); 225}).catch ((err: BusinessError) => { 226 console.error(`Failed to release system tone player. ${err}`); 227}); 228``` 229