#getBackgroundAudioManager
获取全局唯一的背景音频管理器。
#扫码预览
#支持版本
前端库版本不低于 0.0.37。
#支持平台
| 平台 | 支持情况 |
|---|---|
| Android | 支持 |
| iOS | 支持 |
| PC | 不支持 |
| HarmonyOS | 不支持 |
#支持场景
| 场景 | 支持情况 |
|---|---|
| 页面 | 支持 |
| 卡片 | 不支持 |
#使用说明
- 调用 play 前先设置有效 src;播放结束且不再需要背景播放时调用 stop。
#调用方式
#同步 API
getBackgroundAudioManager(): BackgroundAudioManager#入参
无。
#调用示例
import { getBackgroundAudioManager } from '@doubao-dev/framework/api';
const audio = getBackgroundAudioManager();
audio.title = '示例音频';
audio.coverImgUrl = 'https://example.com/cover.jpg';
audio.src = 'https://example.com/audio.mp3';
audio.onError((error) => console.error(error.errCode, error.errMsg));
audio.play();#返回值
| 名称 | 类型 | 必返 | 说明 |
|---|---|---|---|
buffered | number | 是 | 当前已缓冲到的位置,单位秒。 |
coverImgUrl | string | 是 | 封面图片地址。 |
currentTime | number | 是 | 当前播放位置,单位秒。 |
duration | number | 是 | 音频总时长,单位秒;资源尚未就绪时为 0。 |
epname | string | 是 | 专辑名称。 |
offCanplay | (callback?: BackgroundAudioManagerEventCallback) => void | 是 | 取消 canplay 监听;省略 callback 时移除该事件的全部监听。 |
offEnded | (callback?: BackgroundAudioManagerEventCallback) => void | 是 | 取消 ended 监听;省略 callback 时移除该事件的全部监听。 |
offError | (callback?: BackgroundAudioManagerErrorCallback) => void | 是 | 取消 error 监听;省略 callback 时移除全部错误监听。 |
offNext | (callback?: BackgroundAudioManagerEventCallback) => void | 是 | 取消 next 监听;省略 callback 时移除该事件的全部监听。 |
offPause | (callback?: BackgroundAudioManagerEventCallback) => void | 是 | 取消 pause 监听;省略 callback 时移除该事件的全部监听。 |
offPlay | (callback?: BackgroundAudioManagerEventCallback) => void | 是 | 取消 play 监听;省略 callback 时移除该事件的全部监听。 |
offPrev | (callback?: BackgroundAudioManagerEventCallback) => void | 是 | 取消 prev 监听;省略 callback 时移除该事件的全部监听。 |
offSeeked | (callback?: BackgroundAudioManagerEventCallback) => void | 是 | 取消 seeked 监听;省略 callback 时移除该事件的全部监听。 |
offSeeking | (callback?: BackgroundAudioManagerEventCallback) => void | 是 | 取消 seeking 监听;省略 callback 时移除该事件的全部监听。 |
offStop | (callback?: BackgroundAudioManagerEventCallback) => void | 是 | 取消 stop 监听;省略 callback 时移除该事件的全部监听。 |
offTimeUpdate | (callback?: BackgroundAudioManagerEventCallback) => void | 是 | 取消 timeupdate 监听;省略 callback 时移除该事件的全部监听。 |
offWaiting | (callback?: BackgroundAudioManagerEventCallback) => void | 是 | 取消 waiting 监听;省略 callback 时移除该事件的全部监听。 |
onCanplay | (callback: BackgroundAudioManagerEventCallback) => void | 是 | 监听音频可以开始播放的事件。 |
onEnded | (callback: BackgroundAudioManagerEventCallback) => void | 是 | 监听自然播放结束事件。 |
onError | (callback: BackgroundAudioManagerErrorCallback) => void | 是 | 监听播放、资源或占用冲突错误。 |
onNext | (callback: BackgroundAudioManagerEventCallback) => void | 是 | 监听用户在豆包背景播放控件中点击下一首的事件。 |
onPause | (callback: BackgroundAudioManagerEventCallback) => void | 是 | 监听暂停事件。 |
onPlay | (callback: BackgroundAudioManagerEventCallback) => void | 是 | 监听开始播放事件。 |
onPrev | (callback: BackgroundAudioManagerEventCallback) => void | 是 | 监听用户在豆包背景播放控件中点击上一首的事件。 |
onSeeked | (callback: BackgroundAudioManagerEventCallback) => void | 是 | 监听完成跳转播放位置的事件。 |
onSeeking | (callback: BackgroundAudioManagerEventCallback) => void | 是 | 监听开始跳转播放位置的事件。 |
onStop | (callback: BackgroundAudioManagerEventCallback) => void | 是 | 监听停止事件。 |
onTimeUpdate | (callback: BackgroundAudioManagerEventCallback) => void | 是 | 监听播放进度更新事件。 |
onWaiting | (callback: BackgroundAudioManagerEventCallback) => void | 是 | 监听因缓冲不足而等待的事件。 |
pause | () => void | 是 | 暂停播放。 |
paused | boolean | 是 | 当前是否暂停。 |
play | () => void | 是 | 播放音频;调用前需要先设置 src。 |
playbackRate | number | 是 | 播放速度,默认为 1。 |
seek | (position: number) => void | 是 | 跳转到指定播放位置,position 的单位为秒且不能为负数。 |
singer | string | 是 | 歌手或作者名称。 |
src | string | 是 | 音频资源地址,支持 HTTP、HTTPS 地址。 |
startTime | number | 是 | 开始播放的位置,单位秒,默认为 0。 |
stop | () => void | 是 | 停止播放并释放当前背景音频占用。 |
title | string | 是 | 音频标题,用于豆包背景播放信息展示。 |
webUrl | string | 是 | 音频关联页面地址。 |
#返回示例
{
"src": "",
"title": "",
"epname": "",
"singer": "",
"coverImgUrl": "",
"webUrl": "",
"startTime": 0,
"currentTime": 0,
"duration": 0,
"paused": true,
"buffered": 0,
"playbackRate": 1
}#错误处理
管理器操作失败时通过错误事件回调返回。错误对象和通用错误码见 通用错误处理。
#失败示例
{
"errCode": -1001,
"errMsg": "background audio src is empty"
}#错误码
#事件错误码
| 错误字段 | 值 | 错误信息 | 平台 | 触发条件 | 处理建议 |
|---|---|---|---|---|---|
event.errCode | -1001 | background audio src is empty | Android、iOS | 未设置 src 就调用 play | 设置有效 src 后重试。 |
event.errCode | -1002 | background audio play failed | Android | 播放器启动失败 | 检查资源地址和网络状态后重试。 |
event.errCode | -1003 | background audio seek failed | Android、iOS | 播放位置跳转失败 | 等待 canplay 后在音频时长范围内重试。 |
event.errCode | -1004 | background audio player unavailable | Android、iOS | 播放器无法创建或已经不可用 | 重新设置 src 后重试。 |
event.errCode | -1005 | background audio is occupied by another applet | Android、iOS | 另一应用插件正在占用背景音频 | 提示用户结束其他背景音频后重试。 |
#平台差异
- iOS:部分系统播放器错误会在 onError 中返回系统错误码和错误信息,请为未识别的 errCode 提供兜底处理。
#已知限制与注意事项
- 背景音频管理器是全局单例;后一次调用获取到的是同一实例和同一组播放状态。