For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt, and this page is available as Markdown at /apps-plugin/docs/js-api/media/getBackgroundAudioManager.md.

getBackgroundAudioManager

获取全局唯一的背景音频管理器。

扫码预览

扫码预览 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();

返回值

名称类型必返说明
bufferednumber是当前已缓冲到的位置,单位秒。
coverImgUrlstring是封面图片地址。
currentTimenumber是当前播放位置,单位秒。
durationnumber是音频总时长,单位秒;资源尚未就绪时为 0。
epnamestring是专辑名称。
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是暂停播放。
pausedboolean是当前是否暂停。
play() => void是播放音频;调用前需要先设置 src。
playbackRatenumber是播放速度,默认为 1。
seek(position: number) => void是跳转到指定播放位置,position 的单位为秒且不能为负数。
singerstring是歌手或作者名称。
srcstring是音频资源地址,支持 HTTP、HTTPS 地址。
startTimenumber是开始播放的位置,单位秒,默认为 0。
stop() => void是停止播放并释放当前背景音频占用。
titlestring是音频标题,用于豆包背景播放信息展示。
webUrlstring是音频关联页面地址。

返回示例

{
  "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-1001background audio src is emptyAndroid、iOS未设置 src 就调用 play设置有效 src 后重试。
event.errCode-1002background audio play failedAndroid播放器启动失败检查资源地址和网络状态后重试。
event.errCode-1003background audio seek failedAndroid、iOS播放位置跳转失败等待 canplay 后在音频时长范围内重试。
event.errCode-1004background audio player unavailableAndroid、iOS播放器无法创建或已经不可用重新设置 src 后重试。
event.errCode-1005background audio is occupied by another appletAndroid、iOS另一应用插件正在占用背景音频提示用户结束其他背景音频后重试。

平台差异

  • iOS:部分系统播放器错误会在 onError 中返回系统错误码和错误信息,请为未识别的 errCode 提供兜底处理。

已知限制与注意事项

  • 背景音频管理器是全局单例;后一次调用获取到的是同一实例和同一组播放状态。