1# ringtonePlayer (铃声播放器)(系统接口)
2
3铃声播放器提供了系统铃声的播放、配置、获取信息等功能。
4
5ringtonePlayer需要和[@ohos.multimedia.systemSoundManager](js-apis-systemSoundManager-sys.md)配合使用，才能完成管理系统铃声的功能。
6
7> **说明：**
8>
9> - 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
10> - 本模块接口为系统接口。
11
12## 导入模块
13
14```ts
15import { systemSoundManager } from '@kit.AudioKit';
16```
17
18## RingtoneOptions
19
20铃声参数选项。
21
22**系统接口：** 该接口为系统接口
23
24**系统能力：** SystemCapability.Multimedia.SystemSound.Core
25
26| 名称      | 类型            |必填   | 说明                              |
27| --------- | -------------- | ---- | --------------------------------- |
28| volume    | number         | 是   | 指定的相对音量大小，取值范围为[0.00, 1.00]，1表示最大音量，即100%。 |
29| loop      | boolean        | 是   | 是否开启循环播放，true表示开启循环播放，false表示不开启循环播放。 |
30
31## RingtonePlayer
32
33系统铃声播放器，提供系统铃声的参数设置、参数获取、播放、停止等功能。在调用RingtonePlayer的接口前，需要先通过[getSystemRingtonePlayer](js-apis-systemSoundManager-sys.md#getsystemringtoneplayer)创建实例。
34
35### 属性
36
37**系统接口：** 该接口为系统接口
38
39**系统能力：** SystemCapability.Multimedia.SystemSound.Core
40
41| 名称  | 类型                        | 可读 | 可写 | 说明               |
42| ----- | -------------------------- | ---- | ---- | ------------------ |
43| state | [media.AVPlayerState](../apis-media-kit/js-apis-media.md#avplayerstate9) | 是   | 否   | 音频渲染器的状态。 |
44
45**示例：**
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
56获取铃声标题，使用callback方式异步返回结果。
57
58**系统接口：** 该接口为系统接口
59
60**系统能力：** SystemCapability.Multimedia.SystemSound.Core
61
62**参数：**
63
64| 参数名   | 类型                                      | 必填 | 说明                       |
65| -------- | -----------------------------------------| ---- | ------------------------- |
66| callback | AsyncCallback<string>              | 是   | 回调返回获取的铃声标题。     |
67
68**示例：**
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
86获取铃声标题，使用Promise方式异步返回结果。
87
88**系统接口：** 该接口为系统接口
89
90**系统能力：** SystemCapability.Multimedia.SystemSound.Core
91
92**返回值：**
93
94| 类型                  | 说明                              |
95| --------------------- | -------------------------------- |
96| Promise<string> | Promise回调返回获取的系统铃声标题。 |
97
98**示例：**
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
114获取铃声使用的AudioRendererInfo，使用callback方式异步返回结果。
115
116**系统接口：** 该接口为系统接口
117
118**系统能力：** SystemCapability.Multimedia.SystemSound.Core
119
120**参数：**
121
122| 参数名   | 类型                                      | 必填 | 说明                       |
123| -------- | -----------------------------------------| ---- | ------------------------- |
124| callback | AsyncCallback<[audio.AudioRendererInfo](../apis-audio-kit/js-apis-audio.md#audiorendererinfo8)> | 是 | 回调返回获取的AudioRendererInfo。 |
125
126**示例：**
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
148获取铃声使用的AudioRendererInfo，使用Promise方式异步返回结果。
149
150**系统接口：** 该接口为系统接口
151
152**系统能力：** SystemCapability.Multimedia.SystemSound.Core
153
154**返回值：**
155
156| 类型                | 说明                            |
157| ------------------- | ------------------------------- |
158| Promise<[audio.AudioRendererInfo](../apis-audio-kit/js-apis-audio.md#audiorendererinfo8)> | Promise回调返回获取的AudioRendererInfo。 |
159
160**示例：**
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
180配置铃声播放参数，使用callback方式异步返回结果。
181
182**系统接口：** 该接口为系统接口
183
184**系统能力：** SystemCapability.Multimedia.SystemSound.Core
185
186**参数：**
187
188| 参数名   | 类型                                      | 必填 | 说明                       |
189| -------- | -----------------------------------------| ---- | ------------------------- |
190| options  | [RingtoneOptions](#ringtoneoptions)      | 是   | 指定铃声参数。             |
191| callback | AsyncCallback<void>                | 是   | 回调返回配置参数成功或失败。 |
192
193**示例：**
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
217配置铃声播放参数，使用Promise方式异步返回结果。
218
219**系统接口：** 该接口为系统接口
220
221**系统能力：** SystemCapability.Multimedia.SystemSound.Core
222
223**参数：**
224
225| 参数名   | 类型                                      | 必填 | 说明                       |
226| -------- | -----------------------------------------| ---- | ------------------------- |
227| options  | [RingtoneOptions](#ringtoneoptions)      | 是   | 指定铃声参数。              |
228
229**返回值：**
230
231| 类型                | 说明                            |
232| ------------------- | ------------------------------- |
233| Promise<void> | Promise回调返回配置参数成功或失败。 |
234
235**示例：**
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
257开始播放铃声，使用callback方式异步返回结果。
258
259**系统接口：** 该接口为系统接口
260
261**系统能力：** SystemCapability.Multimedia.SystemSound.Core
262
263**参数：**
264
265| 参数名   | 类型                                      | 必填 | 说明                       |
266| -------- | -----------------------------------------| ---- | ------------------------- |
267| callback | AsyncCallback<void>                | 是   | 回调返回开始播放成功或失败。 |
268
269**示例：**
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
287开始播放铃声，使用Promise方式异步返回结果。
288
289**系统接口：** 该接口为系统接口
290
291**系统能力：** SystemCapability.Multimedia.SystemSound.Core
292
293**返回值：**
294
295| 类型                | 说明                              |
296| ------------------- | -------------------------------- |
297| Promise<void> | Promise回调返回开始播放成功或失败。 |
298
299**示例：**
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
315停止播放铃声，使用callback方式异步返回结果。
316
317**系统接口：** 该接口为系统接口
318
319**系统能力：** SystemCapability.Multimedia.SystemSound.Core
320
321**参数：**
322
323| 参数名   | 类型                                      | 必填 | 说明                       |
324| -------- | -----------------------------------------| ---- | ------------------------- |
325| callback | AsyncCallback<void>                | 是   | 回调返回停止播放成功或失败。 |
326
327**示例：**
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
345停止播放铃声，使用Promise方式异步返回结果。
346
347**系统接口：** 该接口为系统接口
348
349**系统能力：** SystemCapability.Multimedia.SystemSound.Core
350
351**返回值：**
352
353| 类型                | 说明                              |
354| ------------------- | -------------------------------- |
355| Promise<void> | Promise回调返回停止播放成功或失败。 |
356
357**示例：**
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
373释放铃声播放器，使用callback方式异步返回结果。
374
375**系统接口：** 该接口为系统接口
376
377**系统能力：** SystemCapability.Multimedia.SystemSound.Core
378
379**参数：**
380
381| 参数名   | 类型                                      | 必填 | 说明                       |
382| -------- | -----------------------------------------| ---- | ------------------------- |
383| callback | AsyncCallback<void>                | 是   | 回调返回释放成功或失败。     |
384
385**示例：**
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
403释放铃声播放器，使用Promise方式异步返回结果。
404
405**系统接口：** 该接口为系统接口
406
407**系统能力：** SystemCapability.Multimedia.SystemSound.Core
408
409**返回值：**
410
411| 类型                | 说明                            |
412| ------------------- | ------------------------------- |
413| Promise<void> | Promise回调返回释放成功或失败。   |
414
415**示例：**
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
431监听音频中断事件（当音频焦点发生变化时触发），使用callback方式返回结果。
432
433**系统接口：** 该接口为系统接口
434
435**系统能力：** SystemCapability.Multimedia.SystemSound.Core
436
437**参数：**
438
439| 参数名   | 类型                     | 必填 | 说明                                                                       |
440| -------- | ----------------------- | ---- | -------------------------------------------------------------------------- |
441| type     | string                  | 是   | 监听事件，固定为：'audioInterrupt'。 |
442| callback | Callback<[audio.InterruptEvent](../apis-audio-kit/js-apis-audio.md#interruptevent9)> | 是   | 回调函数，返回播放中断时，应用接收的中断事件信息。 |
443
444**错误码：**
445
446以下错误码的详细介绍请参见[音频错误码](errorcode-audio.md)。
447
448| 错误码ID | 错误信息 |
449| ------- | --------------------------------------------|
450| 401     | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
451| 6800101 | Parameter verification failed. |
452
453**示例：**
454
455```ts
456import { audio } from '@kit.AudioKit';
457
458let isPlaying: boolean; // 标识符，表示是否正在渲染
459let isDucked: boolean; // 标识符，表示是否被降低音量
460
461systemRingtonePlayer.on('audioInterrupt', async(interruptEvent: audio.InterruptEvent) => {
462  if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_FORCE) {
463    // 由系统进行操作，强制打断音频渲染，应用需更新自身状态及显示内容等
464    switch (interruptEvent.hintType) {
465      case audio.InterruptHint.INTERRUPT_HINT_PAUSE:
466        // 音频流已被暂停，临时失去焦点，待可重获焦点时会收到resume对应的interruptEvent
467        console.info('Force paused. Update playing status and stop writing');
468        isPlaying = false; // 简化处理，代表应用切换至暂停状态的若干操作
469        break;
470      case audio.InterruptHint.INTERRUPT_HINT_STOP:
471        // 音频流已被停止，永久失去焦点，若想恢复渲染，需用户主动触发
472        console.info('Force stopped. Update playing status and stop writing');
473        isPlaying = false; // 简化处理，代表应用切换至暂停状态的若干操作
474        break;
475      case audio.InterruptHint.INTERRUPT_HINT_DUCK:
476        // 音频流已被降低音量渲染
477        console.info('Force ducked. Update volume status');
478        isDucked = true; // 简化处理，代表应用更新音量状态的若干操作
479        break;
480      case audio.InterruptHint.INTERRUPT_HINT_UNDUCK:
481        // 音频流已被恢复正常音量渲染
482        console.info('Force ducked. Update volume status');
483        isDucked = false; // 简化处理，代表应用更新音量状态的若干操作
484        break;
485      default:
486        break;
487    }
488  } else if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_SHARE) {
489    // 由应用进行操作，应用可以自主选择响应操作或忽略该事件
490    switch (interruptEvent.hintType) {
491      case audio.InterruptHint.INTERRUPT_HINT_RESUME:
492        // 建议应用继续渲染（说明音频流此前被强制暂停，临时失去焦点，现在可以恢复渲染）
493        console.info('Resume force paused renderer or ignore');
494        // 若选择继续渲染，需在此处主动执行开始渲染的若干操作
495        break;
496      default:
497        break;
498    }
499  }
500});
501```
502
503### off('audioInterrupt') <sup>10+</sup>
504
505off(type: 'audioInterrupt'): void
506
507取消监听音频中断事件。
508
509**系统接口：** 该接口为系统接口
510
511**系统能力：** SystemCapability.Multimedia.SystemSound.Core
512
513**参数：**
514
515| 参数名 | 类型   | 必填 | 说明                                              |
516| :----- | :----- | :--- | :------------------------------------------------ |
517| type   | string | 是   | 监听事件，固定为：'audioInterrupt'。 |
518
519**错误码：**
520
521以下错误码的详细介绍请参见[音频错误码](errorcode-audio.md)。
522
523| 错误码ID | 错误信息 |
524| ------- | --------------------------------------------|
525| 401     | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. |
526| 6800101 | Parameter verification failed. |
527
528**示例：**
529
530```ts
531systemRingtonePlayer.off('audioInterrupt');
532```
533