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