diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-multimedia-ringtonePlayer.md b/zh-cn/application-dev/reference/apis/js-apis-inner-multimedia-ringtonePlayer.md new file mode 100644 index 0000000000000000000000000000000000000000..bae009565a896fb3add165e9a5f1721ac5c54d75 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-multimedia-ringtonePlayer.md @@ -0,0 +1,471 @@ +# ringtonePlayer (铃声播放器) + +铃声播放器提供了系统铃声的播放、配置、获取信息等功能。 + +ringtonePlayer需要和[@ohos.multimedia.systemSoundManager](js-apis-systemSoundManager.md)配合使用,才能完成管理系统铃声的功能。 + +> **说明:** +> +> 本模块首批接口从API version 10开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 +> +> 本模块接口为系统接口。 + +## 导入模块 + +```js +import systemSoundManager from '@ohos.multimedia.systemSoundManager'; +``` + +## RingtoneOptions + +铃声参数选项。 + +**系统接口:** 该接口为系统接口 + +**系统能力:** SystemCapability.Multimedia.SystemSound.Core + +| 名称 | 类型 |必填 | 说明 | +| --------- | -------------- | ---- | --------------------------------- | +| volume | number | 是 | 指定的相对音量大小,取值范围为[0.00, 1.00],1表示最大音量,即100%。 | +| loop | boolean | 是 | 是否开启循环播放,true表示开启循环播放,false表示不开启循环播放。 | + +## RingtonePlayer + +系统铃声播放器,提供系统铃声的参数设置、参数获取、播放、停止等功能。在调用RingtonePlayer的接口前,需要先通过[getSystemRingtonePlayer](js-apis-systemSoundManager.md#getsystemringtoneplayer)创建实例。 + +### 属性 + +**系统接口:** 该接口为系统接口 + +**系统能力:** SystemCapability.Multimedia.SystemSound.Core + +| 名称 | 类型 | 可读 | 可写 | 说明 | +| ----- | -------------------------- | ---- | ---- | ------------------ | +| state | [media.AVPlayerState](js-apis-media.md#avplayerstate9) | 是 | 否 | 音频渲染器的状态。 | + +**示例:** + +```js +let state = systemRingtonePlayer.state; +``` + +### getTitle + +getTitle(callback: AsyncCallback<string>): void + +获取铃声标题,使用callback方式异步返回结果。 + +**系统接口:** 该接口为系统接口 + +**系统能力:** SystemCapability.Multimedia.SystemSound.Core + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -----------------------------------------| ---- | ------------------------- | +| callback | AsyncCallback<string> | 是 | 回调返回获取的铃声标题。 | + +**示例:** + +```js +systemRingtonePlayer.getTitle((err, value) => { + if (err) { + console.error(`Failed to get system ringtone title. ${err}`); + return; + } + console.info(`Callback invoked to indicate the value of the system ringtone title is obtained ${value}.`); +}); +``` + +### getTitle + +getTitle(): Promise<string> + +获取铃声标题,使用Promise方式异步返回结果。 + +**系统接口:** 该接口为系统接口 + +**系统能力:** SystemCapability.Multimedia.SystemSound.Core + +**返回值:** + +| 类型 | 说明 | +| --------------------- | -------------------------------- | +| Promise<string> | Promise回调返回获取的系统铃声标题。 | + +**示例:** + +```js +systemRingtonePlayer.getTitle().then((value) => { + console.info(`Promise returned to indicate that the value of the system ringtone title is obtained ${value}.`); +}).catch ((err) => { + console.error(`Failed to get the system ringtone title ${err}`); +}); +``` + +### getAudioRendererInfo + +getAudioRendererInfo(callback: AsyncCallback<audio.AudioRendererInfo>): void + +获取铃声使用的AudioRendererInfo,使用callback方式异步返回结果。 + +**系统接口:** 该接口为系统接口 + +**系统能力:** SystemCapability.Multimedia.SystemSound.Core + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -----------------------------------------| ---- | ------------------------- | +| callback | AsyncCallback<[audio.AudioRendererInfo](js-apis-audio.md#audiorendererinfo8)> | 是 | 回调返回获取的AudioRendererInfo。 | + +**示例:** + +```js +import audio from '@ohos.multimedia.audio'; + +let audioRendererInfo: audio.AudioRendererInfo = null; + +systemRingtonePlayer.getAudioRendererInfo((err, value) => { + if (err) { + console.error(`Failed to get ringtone AudioRendererInfo. ${err}`); + return; + } + console.info(`Callback invoked to indicate the value of the ringtone AudioRendererInfo is obtained.`); + audioRendererInfo = value; +}); +``` + +### getAudioRendererInfo + +getAudioRendererInfo(): Promise<audio.AudioRendererInfo> + +获取铃声使用的AudioRendererInfo,使用Promise方式异步返回结果。 + +**系统接口:** 该接口为系统接口 + +**系统能力:** SystemCapability.Multimedia.SystemSound.Core + +**返回值:** + +| 类型 | 说明 | +| ------------------- | ------------------------------- | +| Promise<[audio.AudioRendererInfo](js-apis-audio.md#audiorendererinfo8)> | Promise回调返回获取的AudioRendererInfo。 | + +**示例:** + +```js +import audio from '@ohos.multimedia.audio'; + +let audioRendererInfo: audio.AudioRendererInfo = null; + +systemRingtonePlayer.getAudioRendererInfo().then((value) => { + console.info(`Promise returned to indicate that the value of the ringtone AudioRendererInfo is obtained ${value}.`); + audioRendererInfo = value; +}).catch ((err) => { + console.error(`Failed to get the ringtone AudioRendererInfo ${err}`); +}); +``` + +### configure + +configure(options: RingtoneOptions, callback: AsyncCallback<void>): void + +配置铃声播放参数,使用callback方式异步返回结果。 + +**系统接口:** 该接口为系统接口 + +**系统能力:** SystemCapability.Multimedia.SystemSound.Core + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -----------------------------------------| ---- | ------------------------- | +| options | [RingtoneOptions](#ringtoneoptions) | 是 | 指定铃声参数。 | +| callback | AsyncCallback<void> | 是 | 回调返回配置参数成功或失败。 | + +**示例:** + +```js +let ringtoneOptions = {volume: 0.5, loop: true}; + +systemRingtonePlayer.configure(ringtoneOptions, (err) => { + if (err) { + console.error(`Failed to configure ringtone options. ${err}`); + return; + } + console.info(`Callback invoked to indicate a successful setting of ringtone options.`); +}); +``` + +### configure + +configure(options: RingtoneOptions): Promise<void> + +配置铃声播放参数,使用Promise方式异步返回结果。 + +**系统接口:** 该接口为系统接口 + +**系统能力:** SystemCapability.Multimedia.SystemSound.Core + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -----------------------------------------| ---- | ------------------------- | +| options | [RingtoneOptions](#ringtoneoptions) | 是 | 指定铃声参数。 | + +**返回值:** + +| 类型 | 说明 | +| ------------------- | ------------------------------- | +| Promise<void> | Promise回调返回配置参数成功或失败。 | + +**示例:** + +```js +let ringtoneOptions = {volume: 0.5, loop: true}; + +systemRingtonePlayer.configure(ringtoneOptions).then(() => { + console.info(`Promise returned to indicate a successful setting of ringtone options.`); +}).catch ((err) => { + console.error(`Failed to configure ringtone options. ${err}`); +}); +``` + +### start + +start(callback: AsyncCallback<void>): void + +开始播放铃声,使用callback方式异步返回结果。 + +**系统接口:** 该接口为系统接口 + +**系统能力:** SystemCapability.Multimedia.SystemSound.Core + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -----------------------------------------| ---- | ------------------------- | +| callback | AsyncCallback<void> | 是 | 回调返回开始播放成功或失败。 | + +**示例:** + +```js +systemRingtonePlayer.start((err) => { + if (err) { + console.error(`Failed to start playing ringtone. ${err}`); + return; + } + console.info(`Callback invoked to indicate a successful starting of ringtone.`); +}); +``` + +### start + +start(): Promise<void> + +开始播放铃声,使用Promise方式异步返回结果。 + +**系统接口:** 该接口为系统接口 + +**系统能力:** SystemCapability.Multimedia.SystemSound.Core + +**返回值:** + +| 类型 | 说明 | +| ------------------- | -------------------------------- | +| Promise<void> | Promise回调返回开始播放成功或失败。 | + +**示例:** + +```js +systemRingtonePlayer.start().then(() => { + console.info(`Promise returned to indicate a successful starting of ringtone.`); +}).catch ((err) => { + console.error(`Failed to start playing ringtone. ${err}`); +}); +``` + +### stop + +stop(callback: AsyncCallback<void>): void + +停止播放铃声,使用callback方式异步返回结果。 + +**系统接口:** 该接口为系统接口 + +**系统能力:** SystemCapability.Multimedia.SystemSound.Core + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -----------------------------------------| ---- | ------------------------- | +| callback | AsyncCallback<void> | 是 | 回调返回停止播放成功或失败。 | + +**示例:** + +```js +systemRingtonePlayer.stop((err) => { + if (err) { + console.error(`Failed to stop playing ringtone. ${err}`); + return; + } + console.info(`Callback invoked to indicate a successful stopping of ringtone.`); +}); +``` + +### stop + +stop(): Promise<void> + +停止播放铃声,使用Promise方式异步返回结果。 + +**系统接口:** 该接口为系统接口 + +**系统能力:** SystemCapability.Multimedia.SystemSound.Core + +**返回值:** + +| 类型 | 说明 | +| ------------------- | -------------------------------- | +| Promise<void> | Promise回调返回停止播放成功或失败。 | + +**示例:** + +```js +systemRingtonePlayer.stop().then(() => { + console.info(`Promise returned to indicate a successful stopping of ringtone.`); +}).catch ((err) => { + console.error(`Failed to stop playing ringtone. ${err}`); +}); +``` + +### release + +release(callback: AsyncCallback<void>): void + +释放铃声播放器,使用callback方式异步返回结果。 + +**系统接口:** 该接口为系统接口 + +**系统能力:** SystemCapability.Multimedia.SystemSound.Core + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -----------------------------------------| ---- | ------------------------- | +| callback | AsyncCallback<void> | 是 | 回调返回释放成功或失败。 | + +**示例:** + +```js +systemRingtonePlayer.release((err) => { + if (err) { + console.error(`Failed to release ringtone player. ${err}`); + return; + } + console.info(`Callback invoked to indicate a successful releasing of ringtone player.`); +}); +``` + +### release + +release(): Promise<void> + +释放铃声播放器,使用Promise方式异步返回结果。 + +**系统接口:** 该接口为系统接口 + +**系统能力:** SystemCapability.Multimedia.SystemSound.Core + +**返回值:** + +| 类型 | 说明 | +| ------------------- | ------------------------------- | +| Promise<void> | Promise回调返回释放成功或失败。 | + +**示例:** + +```js +systemRingtonePlayer.release().then(() => { + console.info(`Promise returned to indicate a successful releasing of ringtone player.`); +}).catch ((err) => { + console.error(`Failed to release ringtone player. ${err}`); +}); +``` + +### on('audioInterrupt') + +on(type: 'audioInterrupt', callback: Callback<audio.InterruptEvent>): void + +监听音频中断事件。使用callback获取中断事件。 + +**系统接口:** 该接口为系统接口 + +**系统能力:** SystemCapability.Multimedia.SystemSound.Core + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ----------------------- | ---- | -------------------------------------------------------------------------- | +| type | string | 是 | 事件回调类型,支持的事件为:'audioInterrupt'(中断事件被触发,音频渲染被中断)。 | +| callback | Callback<[audio.InterruptEvent](js-apis-audio.md#interruptevent9)> | 是 | 被监听的中断事件的回调。 | + +**错误码:** + +以下错误码的详细介绍请参见[音频错误码](../errorcodes/errorcode-audio.md)。 + +| 错误码ID | 错误信息 | +| ------- | --------------------------------------------| +| 401 | if input parameter type or number mismatch | +| 6800101 | if input parameter value error | + +**示例:** + +```js +import audio from '@ohos.multimedia.audio'; + +let isPlaying; // 标识符,表示是否正在渲染 +let isDucked; // 标识符,表示是否被降低音量 + +systemRingtonePlayer.on('audioInterrupt', async(interruptEvent) => { +if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_FORCE) { + // 由系统进行操作,强制打断音频渲染,应用需更新自身状态及显示内容等 + switch (interruptEvent.hintType) { + case audio.InterruptHint.INTERRUPT_HINT_PAUSE: + // 音频流已被暂停,临时失去焦点,待可重获焦点时会收到resume对应的interruptEvent + console.info('Force paused. Update playing status and stop writing'); + isPlaying = false; // 简化处理,代表应用切换至暂停状态的若干操作 + break; + case audio.InterruptHint.INTERRUPT_HINT_STOP: + // 音频流已被停止,永久失去焦点,若想恢复渲染,需用户主动触发 + console.info('Force stopped. Update playing status and stop writing'); + isPlaying = false; // 简化处理,代表应用切换至暂停状态的若干操作 + break; + case audio.InterruptHint.INTERRUPT_HINT_DUCK: + // 音频流已被降低音量渲染 + console.info('Force ducked. Update volume status'); + isDucked = true; // 简化处理,代表应用更新音量状态的若干操作 + break; + case audio.InterruptHint.INTERRUPT_HINT_UNDUCK: + // 音频流已被恢复正常音量渲染 + console.info('Force ducked. Update volume status'); + isDucked = false; // 简化处理,代表应用更新音量状态的若干操作 + break; + default: + break; + } +} else if (interruptEvent.forceType == audio.InterruptForceType.INTERRUPT_SHARE) { + // 由应用进行操作,应用可以自主选择响应操作或忽略该事件 + switch (interruptEvent.hintType) { + case audio.InterruptHint.INTERRUPT_HINT_RESUME: + // 建议应用继续渲染(说明音频流此前被强制暂停,临时失去焦点,现在可以恢复渲染) + console.info('Resume force paused renderer or ignore'); + // 若选择继续渲染,需在此处主动执行开始渲染的若干操作 + break; + default: + break; + } +} +}); +``` \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-systemSoundManager.md b/zh-cn/application-dev/reference/apis/js-apis-systemSoundManager.md new file mode 100644 index 0000000000000000000000000000000000000000..9f99cc005596cfea2ab9dfd3f7acedf2348f42c2 --- /dev/null +++ b/zh-cn/application-dev/reference/apis/js-apis-systemSoundManager.md @@ -0,0 +1,268 @@ +# @ohos.multimedia.systemSoundManager (系统声音管理) + +系统声音管理提供管理系统声音的一些基础能力,包括对系统铃声的资源设置与读取、获取系统铃声播放器等。 + +> **说明:** +> +> 本模块首批接口从API version 10开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。 +> +> 本模块接口为系统接口。 + +## 导入模块 + +```js +import systemSoundManager from '@ohos.multimedia.systemSoundManager'; +``` + +## RingtoneType + +枚举,铃声类型。 + +**系统接口:** 该接口为系统接口。 + +**系统能力:** SystemCapability.Multimedia.SystemSound.Core + +| 名称 | 值 | 说明 | +| ------------------------------- | ------ | -------------------------------------------- | +| RINGTONE_TYPE_DEFAULT | 0 | 默认铃声类型。 | +| RINGTONE_TYPE_MULTISIM | 1 | 多SIM卡铃声类型。 | + +## systemSoundManager.getSystemSoundManager + +getSystemSoundManager(): SystemSoundManager + +获取系统声音管理器。 + +**系统接口:** 该接口为系统接口 + +**系统能力:** SystemCapability.Multimedia.SystemSound.Core + +**返回值:** + +| 类型 | 说明 | +| ----------------------------- | ------------ | +| [SystemSoundManager](#systemsoundmanager) | 系统声音管理类。 | + +**示例:** +```js +let systemSoundManagerInstance = systemSoundManager.getSystemSoundManager(); +``` + +## SystemSoundManager + +管理系统声音。在调用SystemSoundManager的接口前,需要先通过[getSystemSoundManager](#systemsoundmanagergetsystemsoundmanager)创建实例。 + +### setSystemRingtoneUri + +setSystemRingtoneUri(context: Context, uri: string, type: RingtoneType, callback: AsyncCallback<void>): void + +设置系统铃声uri,使用callback方式异步返回结果。 + +**系统接口:** 该接口为系统接口 + +**系统能力:** SystemCapability.Multimedia.SystemSound.Core + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ------------------------ | +| context | Context | 是 | 当前应用的上下文。 | +| uri | string | 是 | 被设置的系统铃声的uri,资源支持可参考[media.AVPlayer](js-apis-media.md#avplayer9)。 | +| type | [RingtoneType](#ringtonetype) | 是 | 被设置的系统铃声的类型。 | +| callback | AsyncCallback<void> | 是 | 回调返回设置成功或失败。 | + +**示例:** + +```js +let context = this.context; +let uri = 'file://data/test.wav'; // 需更改为目标铃声文件的uri +let type = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT; + +systemSoundManagerInstance.setSystemRingtoneUri(context, uri, type, (err) => { + if (err) { + console.error(`Failed to set system ringtone uri. ${err}`); + return; + } + console.info(`Callback invoked to indicate a successful setting of the system ringtone uri.`); +}); +``` + +### setSystemRingtoneUri + +setSystemRingtoneUri(context: Context, uri: string, type: RingtoneType): Promise<void> + +设置系统铃声uri,使用Promise方式异步返回结果。 + +**系统接口:** 该接口为系统接口 + +**系统能力:** SystemCapability.Multimedia.SystemSound.Core + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ------------------------ | +| context | Context | 是 | 当前应用的上下文。 | +| uri | string | 是 | 被设置的系统铃声的uri,资源支持可参考[media.AVPlayer](js-apis-media.md#avplayer9)。 | +| type | [RingtoneType](#ringtonetype) | 是 | 被设置的系统铃声的类型。 | + +**返回值:** + +| 类型 | 说明 | +| ------------------- | ------------------------------- | +| Promise<void> | Promise回调返回设置成功或失败。 | + +**示例:** + +```js +let context = this.context; +let uri = 'file://data/test.wav'; // 需更改为目标铃声文件的uri +let type = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT; + +systemSoundManagerInstance.setSystemRingtoneUri(context, uri, type).then(() => { + console.info(`Promise returned to indicate a successful setting of the system ringtone uri.`); +}).catch ((err) => { + console.error(`Failed to set the system ringtone uri ${err}`); +}); +``` + +### getSystemRingtoneUri + +getSystemRingtoneUri(context: Context, type: RingtoneType, callback: AsyncCallback<string>): void + +获取系统铃声uri,使用callback方式异步返回结果。 + +**系统接口:** 该接口为系统接口 + +**系统能力:** SystemCapability.Multimedia.SystemSound.Core + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ------------------------ | +| context | Context | 是 | 当前应用的上下文。 | +| type | [RingtoneType](#ringtonetype) | 是 | 待获取的系统铃声的类型。 | +| callback | AsyncCallback<string> | 是 | 回调返回获取的系统铃声uri。 | + +**示例:** + +```js +let context = this.context; +let type = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT; + +systemSoundManagerInstance.getSystemRingtoneUri(context, type, (err, value) => { + if (err) { + console.error(`Failed to get system ringtone uri. ${err}`); + return; + } + console.info(`Callback invoked to indicate the value of the system ringtone uri is obtained ${value}.`); +}); +``` + +### getSystemRingtoneUri + +getSystemRingtoneUri(context: Context, type: RingtoneType): Promise<string> + +获取系统铃声uri,使用Promise方式异步返回结果。 + +**系统接口:** 该接口为系统接口 + +**系统能力:** SystemCapability.Multimedia.SystemSound.Core + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | ---------------------------------------- | ---- | ------------------------ | +| context | Context | 是 | 当前应用的上下文。 | +| type | [RingtoneType](#ringtonetype) | 是 | 被设置的系统铃声的类型。 | + +**返回值:** + +| 类型 | 说明 | +| ------------------- | ---------------------------------- | +| Promise<string> | Promise回调返回获取的系统铃声uri。 | + +**示例:** + +```js +let context = this.context; +let type = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT; + +systemSoundManagerInstance.getSystemRingtoneUri(context, type).then((value) => { + console.info(`Promise returned to indicate that the value of the system ringtone uri is obtained ${value}.`); +}).catch ((err) => { + console.error(`Failed to get the system ringtone uri ${err}`); +}); +``` + +### getSystemRingtonePlayer + +getSystemRingtonePlayer(context: Context, type: RingtoneType, callback: AsyncCallback<RingtonePlayer>): void + +获取系统铃声播放器,使用callback方式异步返回结果。 + +**系统接口:** 该接口为系统接口 + +**系统能力:** SystemCapability.Multimedia.SystemSound.Core + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -----------------------------------------| ---- | --------------------------- | +| context | Context | 是 | 当前应用的上下文。 | +| type | [RingtoneType](#ringtonetype) | 是 | 待获取播放器的系统铃声的类型。 | +| callback | AsyncCallback<[RingtonePlayer](js-apis-inner-multimedia-ringtonePlayer.md#ringtoneplayer)> | 是 | 回调返回获取的系统铃声播放器。 | + +**示例:** + +```js +let context = this.context; +let type = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT; +let systemRingtonePlayer = null; + +systemSoundManagerInstance.getSystemRingtonePlayer(context, type, (err, value) => { + if (err) { + console.error(`Failed to get system ringtone player. ${err}`); + return; + } + console.info(`Callback invoked to indicate the value of the system ringtone player is obtained.`); + systemRingtonePlayer = value; +}); +``` + +### getSystemRingtonePlayer + +getSystemRingtonePlayer(context: Context, type: RingtoneType): Promise<RingtonePlayer> + +获取系统铃声播放器,使用Promise方式异步返回结果。 + +**系统接口:** 该接口为系统接口 + +**系统能力:** SystemCapability.Multimedia.SystemSound.Core + +**参数:** + +| 参数名 | 类型 | 必填 | 说明 | +| -------- | -----------------------------------------| ---- | --------------------------- | +| context | Context | 是 | 当前应用的上下文。 | +| type | [RingtoneType](#ringtonetype) | 是 | 待获取播放器的系统铃声的类型。 | + +**返回值:** + +| 类型 | 说明 | +| ------------------- | ------------------------------- | +| Promise<[RingtonePlayer](js-apis-inner-multimedia-ringtonePlayer.md#ringtoneplayer)> | Promise回调返回获取的系统铃声播放器。 | + +**示例:** + +```js +let context = this.context; +let type = systemSoundManager.RingtoneType.RINGTONE_TYPE_DEFAULT; +let systemRingtonePlayer = null; + +systemSoundManagerInstance.getSystemRingtonePlayer(context, type).then((value) => { + console.info(`Promise returned to indicate that the value of the system ringtone player is obtained.`); + systemRingtonePlayer = value; +}).catch ((err) => { + console.error(`Failed to get the system ringtone player ${err}`); +}); +```