• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.multimedia.systemSoundManager (System Sound Management)
2
3The **systemSoundManager** module provides basic capabilities for managing system sounds, including setting and obtaining system ringtones and obtaining a player to play the system ringtone.
4
5> **NOTE**
6>
7> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8>
9> The APIs provided by this module are system APIs.
10
11## Modules to Import
12
13```ts
14import systemSoundManager from '@ohos.multimedia.systemSoundManager';
15```
16
17## RingtoneType
18
19Enumerates the ringtone types.
20
21**System API**: This is a system API.
22
23**System capability**: SystemCapability.Multimedia.SystemSound.Core
24
25| Name                           |  Value    | Description                                        |
26| ------------------------------- | ------ | -------------------------------------------- |
27| RINGTONE_TYPE_DEFAULT           | 0      | Default ringtone type.                                |
28| RINGTONE_TYPE_MULTISIM          | 1      | Multi-SIM ringtone type.                             |
29
30## systemSoundManager.getSystemSoundManager
31
32getSystemSoundManager(): SystemSoundManager
33
34Obtains a system sound manager.
35
36**System API**: This is a system API.
37
38**System capability**: SystemCapability.Multimedia.SystemSound.Core
39
40**Return value**
41
42| Type                         | Description        |
43| ----------------------------- | ------------ |
44| [SystemSoundManager](#systemsoundmanager) | System sound manager obtained.|
45
46**Example**
47```ts
48let systemSoundManagerInstance: systemSoundManager.SystemSoundManager = systemSoundManager.getSystemSoundManager();
49```
50
51## SystemSoundManager
52
53Provides APIs to manage system sounds. Before calling any API in **SystemSoundManager**, you must use [getSystemSoundManager](#systemsoundmanagergetsystemsoundmanager) to create a **SystemSoundManager** instance.
54
55### setSystemRingtoneUri
56
57setSystemRingtoneUri(context: Context, uri: string, type: RingtoneType, callback: AsyncCallback<void>): void
58
59Sets a URI for the system ringtone. This API uses an asynchronous callback to return the result.
60
61**System API**: This is a system API.
62
63**System capability**: SystemCapability.Multimedia.SystemSound.Core
64
65**Parameters**
66
67| Name  | Type                                     | Mandatory| Description                    |
68| -------- | ---------------------------------------- | ---- | ------------------------ |
69| context  | Context                                  | Yes  | Application context.          |
70| uri      | string                                   | Yes  | URI of the system ringtone. For details, see [media.AVPlayer](js-apis-media.md#avplayer9).|
71| type     | [RingtoneType](#ringtonetype)            | Yes  | Type of the system ringtone.    |
72| callback | AsyncCallback<void>                | Yes  | Callback used to return the result.    |
73
74**Example**
75
76```ts
77import { BusinessError } from '@ohos.base';
78
79let context: Context = getContext(this);
80let uri = 'file://data/test.wav'; // Set the URI of the target ringtone file.
81let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT;
82
83systemSoundManagerInstance.setSystemRingtoneUri(context, uri, type, (err: BusinessError) => {
84  if (err) {
85    console.error(`Failed to set system ringtone uri. ${err}`);
86    return;
87  }
88  console.info(`Callback invoked to indicate a successful setting of the system ringtone uri.`);
89});
90```
91
92### setSystemRingtoneUri
93
94setSystemRingtoneUri(context: Context, uri: string, type: RingtoneType): Promise<void>
95
96Sets a URI for the system ringtone. This API uses a promise to return the result.
97
98**System API**: This is a system API.
99
100**System capability**: SystemCapability.Multimedia.SystemSound.Core
101
102**Parameters**
103
104| Name  | Type                                     | Mandatory| Description                    |
105| -------- | ---------------------------------------- | ---- | ------------------------ |
106| context  | Context                                  | Yes  | Application context.        |
107| uri      | string                                   | Yes  | URI of the system ringtone. For details, see [media.AVPlayer](js-apis-media.md#avplayer9).|
108| type     | [RingtoneType](#ringtonetype)            | Yes  | Type of the system ringtone.  |
109
110**Return value**
111
112| Type               | Description                           |
113| ------------------- | ------------------------------- |
114| Promise<void> | Promise used to return the result.  |
115
116**Example**
117
118```ts
119import { BusinessError } from '@ohos.base';
120
121let context: Context = getContext(this);
122let uri = 'file://data/test.wav'; // Set the URI of the target ringtone file.
123let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT;
124
125systemSoundManagerInstance.setSystemRingtoneUri(context, uri, type).then(() => {
126  console.info(`Promise returned to indicate a successful setting of the system ringtone uri.`);
127}).catch ((err: BusinessError) => {
128  console.error(`Failed to set the system ringtone uri ${err}`);
129});
130```
131
132### getSystemRingtoneUri
133
134getSystemRingtoneUri(context: Context, type: RingtoneType, callback: AsyncCallback<string>): void
135
136Obtains the URI of a system ringtone. This API uses an asynchronous callback to return the result.
137
138**System API**: This is a system API.
139
140**System capability**: SystemCapability.Multimedia.SystemSound.Core
141
142**Parameters**
143
144| Name  | Type                                     | Mandatory| Description                    |
145| -------- | ---------------------------------------- | ---- | ------------------------ |
146| context  | Context                                  | Yes  | Application context.        |
147| type     | [RingtoneType](#ringtonetype)            | Yes  | Type of the system ringtone.   |
148| callback | AsyncCallback<string>              | Yes  | Callback used to return the ringtone URI obtained.|
149
150**Example**
151
152```ts
153import { BusinessError } from '@ohos.base';
154
155let context: Context = getContext(this);
156let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT;
157
158systemSoundManagerInstance.getSystemRingtoneUri(context, type, (err: BusinessError, value: string) => {
159  if (err) {
160    console.error(`Failed to get system ringtone uri. ${err}`);
161    return;
162  }
163  console.info(`Callback invoked to indicate the value of the system ringtone uri is obtained ${value}.`);
164});
165```
166
167### getSystemRingtoneUri
168
169getSystemRingtoneUri(context: Context, type: RingtoneType): Promise<string>
170
171Obtains the URI of a system ringtone. This API uses a promise to return the result.
172
173**System API**: This is a system API.
174
175**System capability**: SystemCapability.Multimedia.SystemSound.Core
176
177**Parameters**
178
179| Name  | Type                                     | Mandatory| Description                    |
180| -------- | ---------------------------------------- | ---- | ------------------------ |
181| context  | Context                                  | Yes  | Application context.        |
182| type     | [RingtoneType](#ringtonetype)            | Yes  | Type of the system ringtone.  |
183
184**Return value**
185
186| Type               | Description                               |
187| ------------------- | ---------------------------------- |
188| Promise<string> | Promise used to return the ringtone URI obtained.|
189
190**Example**
191
192```ts
193import { BusinessError } from '@ohos.base';
194
195let context: Context = getContext(this);
196let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT;
197
198systemSoundManagerInstance.getSystemRingtoneUri(context, type).then((value: string) => {
199  console.info(`Promise returned to indicate that the value of the system ringtone uri is obtained ${value}.`);
200}).catch ((err: BusinessError) => {
201  console.error(`Failed to get the system ringtone uri ${err}`);
202});
203```
204
205### getSystemRingtonePlayer
206
207getSystemRingtonePlayer(context: Context, type: RingtoneType, callback: AsyncCallback<RingtonePlayer>): void
208
209Obtains a player to play the system ringtone. This API uses an asynchronous callback to return the result.
210
211**System API**: This is a system API.
212
213**System capability**: SystemCapability.Multimedia.SystemSound.Core
214
215**Parameters**
216
217| Name  | Type                                     | Mandatory| Description                        |
218| -------- | -----------------------------------------| ---- | --------------------------- |
219| context  | Context                                  | Yes  | Application context.           |
220| type     | [RingtoneType](#ringtonetype)            | Yes  | Type of the system ringtone.|
221| callback | AsyncCallback<[RingtonePlayer](js-apis-inner-multimedia-ringtonePlayer.md#ringtoneplayer)> | Yes| Callback used to return the ringtone player obtained.|
222
223**Example**
224
225```ts
226import { BusinessError } from '@ohos.base';
227
228let context: Context = getContext(this);
229let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT;
230let systemRingtonePlayer: systemSoundManager.RingtonePlayer | undefined = undefined;
231
232systemSoundManagerInstance.getSystemRingtonePlayer(context, type, (err: BusinessError, value: systemSoundManager.RingtonePlayer) => {
233  if (err) {
234    console.error(`Failed to get system ringtone player. ${err}`);
235    return;
236  }
237  console.info(`Callback invoked to indicate the value of the system ringtone player is obtained.`);
238  systemRingtonePlayer = value;
239});
240```
241
242### getSystemRingtonePlayer
243
244getSystemRingtonePlayer(context: Context, type: RingtoneType): Promise<RingtonePlayer>
245
246Obtains a player to play the system ringtone. This API uses a promise to return the result.
247
248**System API**: This is a system API.
249
250**System capability**: SystemCapability.Multimedia.SystemSound.Core
251
252**Parameters**
253
254| Name  | Type                                     | Mandatory| Description                        |
255| -------- | -----------------------------------------| ---- | --------------------------- |
256| context  | Context                                  | Yes  | Application context.           |
257| type     | [RingtoneType](#ringtonetype)            | Yes  | Type of the system ringtone.|
258
259**Return value**
260
261| Type               | Description                           |
262| ------------------- | ------------------------------- |
263| Promise<[RingtonePlayer](js-apis-inner-multimedia-ringtonePlayer.md#ringtoneplayer)> | Promise used to return the ringtone player obtained.|
264
265**Example**
266
267```ts
268import { BusinessError } from '@ohos.base';
269
270let context: Context = getContext(this);
271let type: systemSoundManager.RingtoneType = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT;
272let systemRingtonePlayer: systemSoundManager.RingtonePlayer | undefined = undefined;
273
274systemSoundManagerInstance.getSystemRingtonePlayer(context, type).then((value: systemSoundManager.RingtonePlayer) => {
275  console.info(`Promise returned to indicate that the value of the system ringtone player is obtained.`);
276  systemRingtonePlayer = value;
277}).catch ((err: BusinessError) => {
278  console.error(`Failed to get the system ringtone player ${err}`);
279});
280```
281