1# ringtonePlayer (铃声播放器)(系统接口) 2<!--Kit: Audio Kit--> 3<!--Subsystem: Multimedia--> 4<!--Owner: @songshenke--> 5<!--Designer: @caixuejiang; @hao-liangfei; @zhanganxiang--> 6<!--Tester: @Filger--> 7<!--Adviser: @zengyawen--> 8 9铃声播放器提供了系统铃声的播放、配置、获取信息等功能。 10 11ringtonePlayer需要和[@ohos.multimedia.systemSoundManager](js-apis-systemSoundManager-sys.md)配合使用，才能完成管理系统铃声的功能。 12 13> **说明：** 14> 15> - 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 16> - 本模块接口为系统接口。 17 18## 导入模块 19 20```ts 21import { systemSoundManager } from '@kit.AudioKit'; 22``` 23 24## RingtoneOptions 25 26铃声参数选项。 27 28**系统接口：** 该接口为系统接口 29 30**系统能力：** SystemCapability.Multimedia.SystemSound.Core 31 32| 名称 | 类型 |必填 | 说明 | 33| --------- | -------------- | ---- | --------------------------------- | 34| volume | number | 是 | 指定的相对音量大小，取值范围为[0.00, 1.00]，1表示最大音量，即100%。 | 35| loop | boolean | 是 | 是否开启循环播放，true表示开启循环播放，false表示不开启循环播放。 | 36 37## RingtonePlayer 38 39系统铃声播放器，提供系统铃声的参数设置、参数获取、播放、停止等功能。在调用RingtonePlayer的接口前，需要先通过[getRingtonePlayer](./js-apis-systemSoundManager-sys.md#getringtoneplayer11)创建实例。 40 41### 属性 42 43**系统接口：** 该接口为系统接口 44 45**系统能力：** SystemCapability.Multimedia.SystemSound.Core 46 47| 名称 | 类型 | 只读 | 可选 | 说明 | 48| ----- | -------------------------- | ---- | ---- | ------------------ | 49| state | [media.AVPlayerState](../apis-media-kit/arkts-apis-media-t.md#avplayerstate9) | 是 | 否 | 音频渲染器的状态。 | 50 51**示例：** 52 53```ts 54import { media } from '@kit.MediaKit'; 55let state: media.AVPlayerState = systemRingtonePlayer.state; 56``` 57 58### getTitle 59 60getTitle(callback: AsyncCallback<string>): void 61 62获取铃声标题。使用callback异步回调。 63 64**系统接口：** 该接口为系统接口 65 66**系统能力：** SystemCapability.Multimedia.SystemSound.Core 67 68**参数：** 69 70| 参数名 | 类型 | 必填 | 说明 | 71| -------- | -----------------------------------------| ---- | ------------------------- | 72| callback | AsyncCallback<string> | 是 | 回调函数。当获取铃声标题成功，err为undefined，data为获取到的铃声标题；否则为错误对象。 | 73 74**示例：** 75 76```ts 77import { BusinessError } from '@kit.BasicServicesKit'; 78 79systemRingtonePlayer.getTitle((err: BusinessError, value: string) => { 80 if (err) { 81 console.error(`Failed to get system ringtone title. ${err}`); 82 return; 83 } 84 console.info(`Callback invoked to indicate the value of the system ringtone title is obtained ${value}.`); 85}); 86``` 87 88### getTitle 89 90getTitle(): Promise<string> 91 92获取铃声标题。使用Promise异步回调。 93 94**系统接口：** 该接口为系统接口 95 96**系统能力：** SystemCapability.Multimedia.SystemSound.Core 97 98**返回值：** 99 100| 类型 | 说明 | 101| --------------------- | -------------------------------- | 102| Promise<string> | Promise对象，返回获取的系统铃声标题。 | 103 104**示例：** 105 106```ts 107import { BusinessError } from '@kit.BasicServicesKit'; 108 109systemRingtonePlayer.getTitle().then((value: string) => { 110 console.info(`Promise returned to indicate that the value of the system ringtone title is obtained ${value}.`); 111}).catch ((err: BusinessError) => { 112 console.error(`Failed to get the system ringtone title ${err}`); 113}); 114``` 115 116### getAudioRendererInfo 117 118getAudioRendererInfo(callback: AsyncCallback<audio.AudioRendererInfo>): void 119 120获取铃声使用的AudioRendererInfo。使用callback异步回调。 121 122**系统接口：** 该接口为系统接口 123 124**系统能力：** SystemCapability.Multimedia.SystemSound.Core 125 126**参数：** 127 128| 参数名 | 类型 | 必填 | 说明 | 129| -------- | -----------------------------------------| ---- | ------------------------- | 130| callback | AsyncCallback<[audio.AudioRendererInfo](../apis-audio-kit/arkts-apis-audio-i.md#audiorendererinfo8)> | 是 | 回调函数。当获取音频渲染器信息成功，err为undefined，data为获取到的音频渲染器信息；否则为错误对象。 | 131 132**示例：** 133 134```ts 135import { audio } from '@kit.AudioKit'; 136import { BusinessError } from '@kit.BasicServicesKit'; 137 138let audioRendererInfo: audio.AudioRendererInfo | undefined = undefined; 139 140systemRingtonePlayer.getAudioRendererInfo((err: BusinessError, value: audio.AudioRendererInfo) => { 141 if (err) { 142 console.error(`Failed to get ringtone AudioRendererInfo. ${err}`); 143 return; 144 } 145 console.info(`Callback invoked to indicate the value of the ringtone AudioRendererInfo is obtained.`); 146 audioRendererInfo = value; 147}); 148``` 149 150### getAudioRendererInfo 151 152getAudioRendererInfo(): Promise<audio.AudioRendererInfo> 153 154获取铃声使用的AudioRendererInfo。使用Promise异步回调。 155 156**系统接口：** 该接口为系统接口 157 158**系统能力：** SystemCapability.Multimedia.SystemSound.Core 159 160**返回值：** 161 162| 类型 | 说明 | 163| ------------------- | ------------------------------- | 164| Promise<[audio.AudioRendererInfo](../apis-audio-kit/arkts-apis-audio-i.md#audiorendererinfo8)> | Promise对象，返回获取的音频渲染器信息。 | 165 166**示例：** 167 168```ts 169import { audio } from '@kit.AudioKit'; 170import { BusinessError } from '@kit.BasicServicesKit'; 171 172let audioRendererInfo: audio.AudioRendererInfo | undefined = undefined; 173 174systemRingtonePlayer.getAudioRendererInfo().then((value: audio.AudioRendererInfo) => { 175 console.info(`Promise returned to indicate that the value of the ringtone AudioRendererInfo is obtained ${value}.`); 176 audioRendererInfo = value; 177}).catch ((err: BusinessError) => { 178 console.error(`Failed to get the ringtone AudioRendererInfo ${err}`); 179}); 180``` 181 182### configure 183 184configure(options: RingtoneOptions, callback: AsyncCallback<void>): void 185 186配置铃声播放参数。使用callback异步回调。 187 188**系统接口：** 该接口为系统接口 189 190**系统能力：** SystemCapability.Multimedia.SystemSound.Core 191 192**参数：** 193 194| 参数名 | 类型 | 必填 | 说明 | 195| -------- | -----------------------------------------| ---- | ------------------------- | 196| options | [RingtoneOptions](#ringtoneoptions) | 是 | 指定铃声参数。 | 197| callback | AsyncCallback<void> | 是 | 回调函数。当配置铃声播放参数成功，err为undefined，否则为错误对象。 | 198 199**示例：** 200 201```ts 202import { BusinessError } from '@kit.BasicServicesKit'; 203 204class RingtoneOptions { 205 volume: number = 0; 206 loop: boolean = false; 207} 208let ringtoneOptions: RingtoneOptions = {volume: 0.5, loop: true}; 209 210systemRingtonePlayer.configure(ringtoneOptions, (err: BusinessError) => { 211 if (err) { 212 console.error(`Failed to configure ringtone options. ${err}`); 213 return; 214 } 215 console.info(`Callback invoked to indicate a successful setting of ringtone options.`); 216}); 217``` 218 219### configure 220 221configure(options: RingtoneOptions): Promise<void> 222 223配置铃声播放参数。使用Promise异步回调。 224 225**系统接口：** 该接口为系统接口 226 227**系统能力：** SystemCapability.Multimedia.SystemSound.Core 228 229**参数：** 230 231| 参数名 | 类型 | 必填 | 说明 | 232| -------- | -----------------------------------------| ---- | ------------------------- | 233| options | [RingtoneOptions](#ringtoneoptions) | 是 | 指定铃声参数。 | 234 235**返回值：** 236 237| 类型 | 说明 | 238| ------------------- | ------------------------------- | 239| Promise<void> | Promise对象。无返回结果的Promise对象。 | 240 241**示例：** 242 243```ts 244import { BusinessError } from '@kit.BasicServicesKit'; 245 246class RingtoneOptions { 247 volume: number = 0; 248 loop: boolean = false; 249} 250let ringtoneOptions: RingtoneOptions = {volume: 0.5, loop: true}; 251 252systemRingtonePlayer.configure(ringtoneOptions).then(() => { 253 console.info(`Promise returned to indicate a successful setting of ringtone options.`); 254}).catch ((err: BusinessError) => { 255 console.error(`Failed to configure ringtone options. ${err}`); 256}); 257``` 258 259### start 260 261start(callback: AsyncCallback<void>): void 262 263开始播放铃声。使用callback异步回调。 264 265**系统接口：** 该接口为系统接口 266 267**系统能力：** SystemCapability.Multimedia.SystemSound.Core 268 269**参数：** 270 271| 参数名 | 类型 | 必填 | 说明 | 272| -------- | -----------------------------------------| ---- | ------------------------- | 273| callback | AsyncCallback<void> | 是 | 回调函数。当开始播放铃声成功，err为undefined，否则为错误对象。 | 274 275**示例：** 276 277```ts 278import { BusinessError } from '@kit.BasicServicesKit'; 279 280systemRingtonePlayer.start((err: BusinessError) => { 281 if (err) { 282 console.error(`Failed to start playing ringtone. ${err}`); 283 return; 284 } 285 console.info(`Callback invoked to indicate a successful starting of ringtone.`); 286}); 287``` 288 289### start 290 291start(): Promise<void> 292 293开始播放铃声。使用Promise异步回调。 294 295**系统接口：** 该接口为系统接口 296 297**系统能力：** SystemCapability.Multimedia.SystemSound.Core 298 299**返回值：** 300 301| 类型 | 说明 | 302| ------------------- | -------------------------------- | 303| Promise<void> | Promise对象。无返回结果的Promise对象。 | 304 305**示例：** 306 307```ts 308import { BusinessError } from '@kit.BasicServicesKit'; 309 310systemRingtonePlayer.start().then(() => { 311 console.info(`Promise returned to indicate a successful starting of ringtone.`); 312}).catch ((err: BusinessError) => { 313 console.error(`Failed to start playing ringtone. ${err}`); 314}); 315``` 316 317### stop 318 319stop(callback: AsyncCallback<void>): void 320 321停止播放铃声。使用callback异步回调。 322 323**系统接口：** 该接口为系统接口 324 325**系统能力：** SystemCapability.Multimedia.SystemSound.Core 326 327**参数：** 328 329| 参数名 | 类型 | 必填 | 说明 | 330| -------- | -----------------------------------------| ---- | ------------------------- | 331| callback | AsyncCallback<void> | 是 | 回调函数。当停止播放铃声成功，err为undefined，否则为错误对象。 | 332 333**示例：** 334 335```ts 336import { BusinessError } from '@kit.BasicServicesKit'; 337 338systemRingtonePlayer.stop((err: BusinessError) => { 339 if (err) { 340 console.error(`Failed to stop playing ringtone. ${err}`); 341 return; 342 } 343 console.info(`Callback invoked to indicate a successful stopping of ringtone.`); 344}); 345``` 346 347### stop 348 349stop(): Promise<void> 350 351停止播放铃声。使用Promise异步回调。 352 353**系统接口：** 该接口为系统接口 354 355**系统能力：** SystemCapability.Multimedia.SystemSound.Core 356 357**返回值：** 358 359| 类型 | 说明 | 360| ------------------- | -------------------------------- | 361| Promise<void> | Promise对象。无返回结果的Promise对象。 | 362 363**示例：** 364 365```ts 366import { BusinessError } from '@kit.BasicServicesKit'; 367 368systemRingtonePlayer.stop().then(() => { 369 console.info(`Promise returned to indicate a successful stopping of ringtone.`); 370}).catch ((err: BusinessError) => { 371 console.error(`Failed to stop playing ringtone. ${err}`); 372}); 373``` 374 375### release 376 377release(callback: AsyncCallback<void>): void 378 379释放铃声播放器。使用callback异步回调。 380 381**系统接口：** 该接口为系统接口 382 383**系统能力：** SystemCapability.Multimedia.SystemSound.Core 384 385**参数：** 386 387| 参数名 | 类型 | 必填 | 说明 | 388| -------- | -----------------------------------------| ---- | ------------------------- | 389| callback | AsyncCallback<void> | 是 | 回调函数。当释放铃声播放器成功，err为undefined，否则为错误对象。 | 390 391**示例：** 392 393```ts 394import { BusinessError } from '@kit.BasicServicesKit'; 395 396systemRingtonePlayer.release((err: BusinessError) => { 397 if (err) { 398 console.error(`Failed to release ringtone player. ${err}`); 399 return; 400 } 401 console.info(`Callback invoked to indicate a successful releasing of ringtone player.`); 402}); 403``` 404 405### release 406 407release(): Promise<void> 408 409释放铃声播放器。使用Promise异步回调。 410 411**系统接口：** 该接口为系统接口 412 413**系统能力：** SystemCapability.Multimedia.SystemSound.Core 414 415**返回值：** 416 417| 类型 | 说明 | 418| ------------------- | ------------------------------- | 419| Promise<void> | Promise对象。无返回结果的Promise对象。 | 420 421**示例：** 422 423```ts 424import { BusinessError } from '@kit.BasicServicesKit'; 425 426systemRingtonePlayer.release().then(() => { 427 console.info(`Promise returned to indicate a successful releasing of ringtone player.`); 428}).catch ((err: BusinessError) => { 429 console.error(`Failed to release ringtone player. ${err}`); 430}); 431``` 432 433### on('audioInterrupt') 434 435on(type: 'audioInterrupt', callback: Callback<audio.InterruptEvent>): void 436 437监听音频中断事件（当音频焦点发生变化时触发）。使用callback异步回调。 438 439**系统接口：** 该接口为系统接口 440 441**系统能力：** SystemCapability.Multimedia.SystemSound.Core 442 443**参数：** 444 445| 参数名 | 类型 | 必填 | 说明 | 446| -------- | ----------------------- | ---- | -------------------------------------------------------------------------- | 447| type | string | 是 | 事件回调类型，支持的事件为'audioInterrupt'，当音频焦点状态发生变化时，触发该事件。 | 448| callback | Callback<[audio.InterruptEvent](../apis-audio-kit/arkts-apis-audio-i.md#interruptevent9)> | 是 | 回调函数，返回中断事件信息。 | 449 450**错误码：** 451 452以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 453 454| 错误码ID | 错误信息 | 455| ------- | --------------------------------------------| 456| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 457| 6800101 | Parameter verification failed. | 458 459**示例：** 460 461```ts 462import { audio } from '@kit.AudioKit'; 463 464let isPlaying: boolean = false; // 标识符，表示是否正在渲染。 465let isDucked: boolean = false; // 标识符，表示是否被降低音量。 466 467systemRingtonePlayer.on('audioInterrupt', async(interruptEvent: audio.InterruptEvent) => { 468 if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_FORCE) { 469 // 由系统进行操作，强制打断音频渲染，应用需更新自身状态及显示内容等。 470 switch (interruptEvent.hintType) { 471 case audio.InterruptHint.INTERRUPT_HINT_PAUSE: 472 // 音频流已被暂停，临时失去焦点，待可重获焦点时会收到resume对应的interruptEvent。 473 console.info('Force paused. Update playing status and stop writing'); 474 isPlaying = false; // 简化处理，代表应用切换至暂停状态的若干操作。 475 break; 476 case audio.InterruptHint.INTERRUPT_HINT_STOP: 477 // 音频流已被停止，永久失去焦点，若想恢复渲染，需用户主动触发。 478 console.info('Force stopped. Update playing status and stop writing'); 479 isPlaying = false; // 简化处理，代表应用切换至暂停状态的若干操作。 480 break; 481 case audio.InterruptHint.INTERRUPT_HINT_DUCK: 482 // 音频流已被降低音量渲染。 483 console.info('Force ducked. Update volume status'); 484 isDucked = true; // 简化处理，代表应用更新音量状态的若干操作。 485 break; 486 case audio.InterruptHint.INTERRUPT_HINT_UNDUCK: 487 // 音频流已被恢复正常音量渲染。 488 console.info('Force unducked. Update volume status'); 489 isDucked = false; // 简化处理，代表应用更新音量状态的若干操作。 490 break; 491 default: 492 break; 493 } 494 } else if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_SHARE) { 495 // 由应用进行操作，应用可以自主选择响应操作或忽略该事件。 496 switch (interruptEvent.hintType) { 497 case audio.InterruptHint.INTERRUPT_HINT_RESUME: 498 // 建议应用继续渲染（说明音频流此前被强制暂停，临时失去焦点，现在可以恢复渲染）。 499 console.info('Resume force paused renderer or ignore'); 500 // 若选择继续渲染，需在此处主动执行开始渲染的若干操作。 501 break; 502 default: 503 break; 504 } 505 } 506}); 507``` 508 509### off('audioInterrupt') <sup>10+</sup> 510 511off(type: 'audioInterrupt'): void 512 513取消监听音频中断事件。 514 515**系统接口：** 该接口为系统接口 516 517**系统能力：** SystemCapability.Multimedia.SystemSound.Core 518 519**参数：** 520 521| 参数名 | 类型 | 必填 | 说明 | 522| :----- | :----- | :--- | :------------------------------------------------ | 523| type | string | 是 | 事件回调类型，支持的事件为'audioInterrupt'，当取消监听音频中断事件时，触发该事件。 | 524 525**错误码：** 526 527以下错误码的详细介绍请参见[通用错误码说明文档](../errorcode-universal.md)和[Audio错误码](errorcode-audio.md)。 528 529| 错误码ID | 错误信息 | 530| ------- | --------------------------------------------| 531| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types. | 532| 6800101 | Parameter verification failed. | 533 534**示例：** 535 536```ts 537systemRingtonePlayer.off('audioInterrupt'); 538``` 539