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