1# ringtonePlayer (Ringtone Player) (System API)
2
3The **ringtonePlayer** module provides APIs for playing, configuring, and obtaining system ringtones.
4
5This module must work with [@ohos.multimedia.systemSoundManager](js-apis-systemSoundManager-sys.md) to manage system ringtones.
6
7> **NOTE**
8>
9> - 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.
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## RingtoneOptions
19
20Enumerates the ringtone parameters.
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| volume    | number         | Yes  | Relative volume. The value ranges from 0.00 to 1.00. The value **1.00** indicates the maximum volume (100%).|
29| loop      | boolean        | Yes  | Whether to enable loop playback. The value **true** means to enable loop playback, and **false** means the opposite.|
30
31## RingtonePlayer
32
33Provides APIs for setting and obtaining system ringtone parameters as well as playing and stopping system ringtones. Before calling any API in **RingtonePlayer**, you must use [getSystemRingtonePlayer](js-apis-systemSoundManager-sys.md#getsystemringtoneplayer) to create a **RingtonePlayer** instance.
34
35### Attributes
36
37**System API**: This is a system API.
38
39**System capability**: SystemCapability.Multimedia.SystemSound.Core
40
41| Name | Type                       | Readable| Writable| Description              |
42| ----- | -------------------------- | ---- | ---- | ------------------ |
43| state | [media.AVPlayerState](../apis-media-kit/js-apis-media.md#avplayerstate9) | Yes  | No  | Audio renderer state.|
44
45**Example**
46
47```ts
48import { media } from '@kit.MediaKit';
49let state: media.AVPlayerState = systemRingtonePlayer.state;
50```
51
52### getTitle
53
54getTitle(callback: AsyncCallback<string>): void
55
56Obtains the title of a system ringtone. This API uses an asynchronous callback to return the result.
57
58**System API**: This is a system API.
59
60**System capability**: SystemCapability.Multimedia.SystemSound.Core
61
62**Parameters**
63
64| Name  | Type                                     | Mandatory| Description                      |
65| -------- | -----------------------------------------| ---- | ------------------------- |
66| callback | AsyncCallback<string>              | Yes  | Callback used to return the ringtone title obtained.    |
67
68**Example**
69
70```ts
71import { BusinessError } from '@kit.BasicServicesKit';
72
73systemRingtonePlayer.getTitle((err: BusinessError, value: string) => {
74  if (err) {
75    console.error(`Failed to get system ringtone title. ${err}`);
76    return;
77  }
78  console.info(`Callback invoked to indicate the value of the system ringtone title is obtained ${value}.`);
79});
80```
81
82### getTitle
83
84getTitle(): Promise<string>
85
86Obtains the title of a system ringtone. This API uses a promise to return the result.
87
88**System API**: This is a system API.
89
90**System capability**: SystemCapability.Multimedia.SystemSound.Core
91
92**Return value**
93
94| Type                 | Description                             |
95| --------------------- | -------------------------------- |
96| Promise<string> | Promise used to return the ringtone title obtained.|
97
98**Example**
99
100```ts
101import { BusinessError } from '@kit.BasicServicesKit';
102
103systemRingtonePlayer.getTitle().then((value: string) => {
104  console.info(`Promise returned to indicate that the value of the system ringtone title is obtained ${value}.`);
105}).catch ((err: BusinessError) => {
106  console.error(`Failed to get the system ringtone title ${err}`);
107});
108```
109
110### getAudioRendererInfo
111
112getAudioRendererInfo(callback: AsyncCallback<audio.AudioRendererInfo>): void
113
114Obtains the information about the audio renderer used by the ringtone. This API uses an asynchronous callback to return the result.
115
116**System API**: This is a system API.
117
118**System capability**: SystemCapability.Multimedia.SystemSound.Core
119
120**Parameters**
121
122| Name  | Type                                     | Mandatory| Description                      |
123| -------- | -----------------------------------------| ---- | ------------------------- |
124| callback | AsyncCallback<[audio.AudioRendererInfo](../apis-audio-kit/js-apis-audio.md#audiorendererinfo8)> | Yes| Callback used to return the audio renderer information obtained.|
125
126**Example**
127
128```ts
129import { audio } from '@kit.AudioKit';
130import { BusinessError } from '@kit.BasicServicesKit';
131
132let audioRendererInfo: audio.AudioRendererInfo | undefined = undefined;
133
134systemRingtonePlayer.getAudioRendererInfo((err: BusinessError, value: audio.AudioRendererInfo) => {
135  if (err) {
136    console.error(`Failed to get ringtone AudioRendererInfo. ${err}`);
137    return;
138  }
139  console.info(`Callback invoked to indicate the value of the ringtone AudioRendererInfo is obtained.`);
140  audioRendererInfo = value;
141});
142```
143
144### getAudioRendererInfo
145
146getAudioRendererInfo(): Promise<audio.AudioRendererInfo>
147
148Obtains the information about the audio renderer used by the ringtone. This API uses a promise to return the result.
149
150**System API**: This is a system API.
151
152**System capability**: SystemCapability.Multimedia.SystemSound.Core
153
154**Return value**
155
156| Type               | Description                           |
157| ------------------- | ------------------------------- |
158| Promise<[audio.AudioRendererInfo](../apis-audio-kit/js-apis-audio.md#audiorendererinfo8)> | Promise used to return the audio renderer information obtained.|
159
160**Example**
161
162```ts
163import { audio } from '@kit.AudioKit';
164import { BusinessError } from '@kit.BasicServicesKit';
165
166let audioRendererInfo: audio.AudioRendererInfo | undefined = undefined;
167
168systemRingtonePlayer.getAudioRendererInfo().then((value: audio.AudioRendererInfo) => {
169  console.info(`Promise returned to indicate that the value of the ringtone AudioRendererInfo is obtained ${value}.`);
170  audioRendererInfo = value;
171}).catch ((err: BusinessError) => {
172  console.error(`Failed to get the ringtone AudioRendererInfo ${err}`);
173});
174```
175
176### configure
177
178configure(options: RingtoneOptions, callback: AsyncCallback<void>): void
179
180Sets ringtone parameters. This API uses an asynchronous callback to return the result.
181
182**System API**: This is a system API.
183
184**System capability**: SystemCapability.Multimedia.SystemSound.Core
185
186**Parameters**
187
188| Name  | Type                                     | Mandatory| Description                      |
189| -------- | -----------------------------------------| ---- | ------------------------- |
190| options  | [RingtoneOptions](#ringtoneoptions)      | Yes  | Ringtone parameters.            |
191| callback | AsyncCallback<void>                | Yes  | Callback used to return the result.|
192
193**Example**
194
195```ts
196import { BusinessError } from '@kit.BasicServicesKit';
197
198class RingtoneOptions {
199  volume: number = 0;
200  loop: boolean = false;
201}
202let ringtoneOptions: RingtoneOptions = {volume: 0.5, loop: true};
203
204systemRingtonePlayer.configure(ringtoneOptions, (err: BusinessError) => {
205  if (err) {
206    console.error(`Failed to configure ringtone options. ${err}`);
207    return;
208  }
209  console.info(`Callback invoked to indicate a successful setting of ringtone options.`);
210});
211```
212
213### configure
214
215configure(options: RingtoneOptions): Promise<void>
216
217Sets ringtone parameters. This API uses a promise to return the result.
218
219**System API**: This is a system API.
220
221**System capability**: SystemCapability.Multimedia.SystemSound.Core
222
223**Parameters**
224
225| Name  | Type                                     | Mandatory| Description                      |
226| -------- | -----------------------------------------| ---- | ------------------------- |
227| options  | [RingtoneOptions](#ringtoneoptions)      | Yes  | Ringtone parameters.             |
228
229**Return value**
230
231| Type               | Description                           |
232| ------------------- | ------------------------------- |
233| Promise<void> | Promise used to return the result.|
234
235**Example**
236
237```ts
238import { BusinessError } from '@kit.BasicServicesKit';
239
240class RingtoneOptions {
241  volume: number = 0;
242  loop: boolean = false;
243}
244let ringtoneOptions: RingtoneOptions = {volume: 0.5, loop: true};
245
246systemRingtonePlayer.configure(ringtoneOptions).then(() => {
247  console.info(`Promise returned to indicate a successful setting of ringtone options.`);
248}).catch ((err: BusinessError) => {
249  console.error(`Failed to configure ringtone options. ${err}`);
250});
251```
252
253### start
254
255start(callback: AsyncCallback<void>): void
256
257Starts playing the ringtone. This API uses an asynchronous callback to return the result.
258
259**System API**: This is a system API.
260
261**System capability**: SystemCapability.Multimedia.SystemSound.Core
262
263**Parameters**
264
265| Name  | Type                                     | Mandatory| Description                      |
266| -------- | -----------------------------------------| ---- | ------------------------- |
267| callback | AsyncCallback<void>                | Yes  | Callback used to return the result.|
268
269**Example**
270
271```ts
272import { BusinessError } from '@kit.BasicServicesKit';
273
274systemRingtonePlayer.start((err: BusinessError) => {
275  if (err) {
276    console.error(`Failed to start playing ringtone. ${err}`);
277    return;
278  }
279  console.info(`Callback invoked to indicate a successful starting of ringtone.`);
280});
281```
282
283### start
284
285start(): Promise<void>
286
287Starts playing the ringtone. This API uses a promise to return the result.
288
289**System API**: This is a system API.
290
291**System capability**: SystemCapability.Multimedia.SystemSound.Core
292
293**Return value**
294
295| Type               | Description                             |
296| ------------------- | -------------------------------- |
297| Promise<void> | Promise used to return the result.|
298
299**Example**
300
301```ts
302import { BusinessError } from '@kit.BasicServicesKit';
303
304systemRingtonePlayer.start().then(() => {
305  console.info(`Promise returned to indicate a successful starting of ringtone.`);
306}).catch ((err: BusinessError) => {
307  console.error(`Failed to start playing ringtone. ${err}`);
308});
309```
310
311### stop
312
313stop(callback: AsyncCallback<void>): void
314
315Stops playing the ringtone. This API uses an asynchronous callback to return the result.
316
317**System API**: This is a system API.
318
319**System capability**: SystemCapability.Multimedia.SystemSound.Core
320
321**Parameters**
322
323| Name  | Type                                     | Mandatory| Description                      |
324| -------- | -----------------------------------------| ---- | ------------------------- |
325| callback | AsyncCallback<void>                | Yes  | Callback used to return the result.|
326
327**Example**
328
329```ts
330import { BusinessError } from '@kit.BasicServicesKit';
331
332systemRingtonePlayer.stop((err: BusinessError) => {
333  if (err) {
334    console.error(`Failed to stop playing ringtone. ${err}`);
335    return;
336  }
337  console.info(`Callback invoked to indicate a successful stopping of ringtone.`);
338});
339```
340
341### stop
342
343stop(): Promise<void>
344
345Stops playing the ringtone. This API uses a promise to return the result.
346
347**System API**: This is a system API.
348
349**System capability**: SystemCapability.Multimedia.SystemSound.Core
350
351**Return value**
352
353| Type               | Description                             |
354| ------------------- | -------------------------------- |
355| Promise<void> | Promise used to return the result.|
356
357**Example**
358
359```ts
360import { BusinessError } from '@kit.BasicServicesKit';
361
362systemRingtonePlayer.stop().then(() => {
363  console.info(`Promise returned to indicate a successful stopping of ringtone.`);
364}).catch ((err: BusinessError) => {
365  console.error(`Failed to stop playing ringtone. ${err}`);
366});
367```
368
369### release
370
371release(callback: AsyncCallback<void>): void
372
373Releases the ringtone player. This API uses an asynchronous callback to return the result.
374
375**System API**: This is a system API.
376
377**System capability**: SystemCapability.Multimedia.SystemSound.Core
378
379**Parameters**
380
381| Name  | Type                                     | Mandatory| Description                      |
382| -------- | -----------------------------------------| ---- | ------------------------- |
383| callback | AsyncCallback<void>                | Yes  | Callback used to return the result.    |
384
385**Example**
386
387```ts
388import { BusinessError } from '@kit.BasicServicesKit';
389
390systemRingtonePlayer.release((err: BusinessError) => {
391  if (err) {
392    console.error(`Failed to release ringtone player. ${err}`);
393    return;
394  }
395  console.info(`Callback invoked to indicate a successful releasing of ringtone player.`);
396});
397```
398
399### release
400
401release(): Promise<void>
402
403Releases the ringtone player. This API uses a promise to return the result.
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| Promise<void> | Promise used to return the result.  |
414
415**Example**
416
417```ts
418import { BusinessError } from '@kit.BasicServicesKit';
419
420systemRingtonePlayer.release().then(() => {
421  console.info(`Promise returned to indicate a successful releasing of ringtone player.`);
422}).catch ((err: BusinessError) => {
423  console.error(`Failed to release ringtone player. ${err}`);
424});
425```
426
427### on('audioInterrupt')
428
429on(type: 'audioInterrupt', callback: Callback<audio.InterruptEvent>): void
430
431Subscribes to the audio interruption event, which is triggered when the audio focus is changed. This API uses an asynchronous callback to return the result.
432
433**System API**: This is a system API.
434
435**System capability**: SystemCapability.Multimedia.SystemSound.Core
436
437**Parameters**
438
439| Name  | Type                    | Mandatory| Description                                                                      |
440| -------- | ----------------------- | ---- | -------------------------------------------------------------------------- |
441| type     | string                  | Yes  | Event type. The value is fixed at **'audioInterrupt'**.|
442| callback | Callback<[audio.InterruptEvent](../apis-audio-kit/js-apis-audio.md#interruptevent9)> | Yes  | Callback used to return the audio interruption event received by the application when playback is interrupted.|
443
444**Error codes**
445
446For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
447
448| ID| Error Message|
449| ------- | --------------------------------------------|
450| 401     | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
451| 6800101 | Parameter verification failed. |
452
453**Example**
454
455```ts
456import { audio } from '@kit.AudioKit';
457
458let isPlaying: boolean; // An identifier specifying whether rendering is in progress.
459let isDucked: boolean; // An identifier specifying whether the audio volume is reduced.
460
461systemRingtonePlayer.on('audioInterrupt', async(interruptEvent: audio.InterruptEvent) => {
462  if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_FORCE) {
463    // The system forcibly interrupts audio rendering. The application must update the status and displayed content accordingly.
464    switch (interruptEvent.hintType) {
465      case audio.InterruptHint.INTERRUPT_HINT_PAUSE:
466        // The audio stream has been paused and temporarily loses the focus. It will receive the interruptEvent corresponding to resume when it is able to regain the focus.
467        console.info('Force paused. Update playing status and stop writing');
468        isPlaying = false; // A simplified processing indicating several operations for switching the application to the paused state.
469        break;
470      case audio.InterruptHint.INTERRUPT_HINT_STOP:
471        // The audio stream has been stopped and permanently loses the focus. The user must manually trigger the operation to resume rendering.
472        console.info('Force stopped. Update playing status and stop writing');
473        isPlaying = false; // A simplified processing indicating several operations for switching the application to the paused state.
474        break;
475      case audio.InterruptHint.INTERRUPT_HINT_DUCK:
476        // The audio stream is rendered at a reduced volume.
477        console.info('Force ducked. Update volume status');
478        isDucked = true; // A simplified processing indicating several operations for updating the volume status.
479        break;
480      case audio.InterruptHint.INTERRUPT_HINT_UNDUCK:
481        // The audio stream is rendered at the normal volume.
482        console.info('Force ducked. Update volume status');
483        isDucked = false; // A simplified processing indicating several operations for updating the volume status.
484        break;
485      default:
486        break;
487    }
488  } else if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_SHARE) {
489    // The application can choose to take action or ignore.
490    switch (interruptEvent.hintType) {
491      case audio.InterruptHint.INTERRUPT_HINT_RESUME:
492        // It is recommended that the application continue rendering. (The audio stream has been forcibly paused and temporarily lost the focus. It can resume rendering now.)
493        console.info('Resume force paused renderer or ignore');
494        // To continue rendering, the application must perform the required operations.
495        break;
496      default:
497        break;
498    }
499  }
500});
501```
502
503### off('audioInterrupt') <sup>10+</sup>
504
505off(type: 'audioInterrupt'): void
506
507Unsubscribes from the audio interruption event.
508
509**System API**: This is a system API.
510
511**System capability**: SystemCapability.Multimedia.SystemSound.Core
512
513**Parameters**
514
515| Name| Type  | Mandatory| Description                                             |
516| :----- | :----- | :--- | :------------------------------------------------ |
517| type   | string | Yes  | Event type. The value is fixed at **'audioInterrupt'**.|
518
519**Error codes**
520
521For details about the error codes, see [Audio Error Codes](errorcode-audio.md).
522
523| ID| Error Message|
524| ------- | --------------------------------------------|
525| 401     | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
526| 6800101 | Parameter verification failed. |
527
528**Example**
529
530```ts
531systemRingtonePlayer.off('audioInterrupt');
532```
533