> 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.

# getBackgroundAudioManager

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

## 扫码预览

![扫码预览 getBackgroundAudioManager](https://api.qrserver.com/v1/create-qr-code/?size=200x200\&data=doubao%3A%2F%2Fdoubao_apps%3Fapp_id%3Ddb_1McM5Ni%26path%3D%252Fpages%252Fapi%252Fmedia%252Fget-background-audio-manager%252Findex)

## 支持版本

前端库版本不低于 `0.0.37`。

## 支持平台

<table>
<thead>
<tr><th>平台</th><th>支持情况</th></tr>
</thead>
<tbody>
<tr><td>Android</td><td>支持</td></tr>
<tr><td>iOS</td><td>支持</td></tr>
<tr><td>PC</td><td>不支持</td></tr>
<tr><td>HarmonyOS</td><td>不支持</td></tr>
</tbody>
</table>

## 支持场景

<table>
<thead>
<tr><th>场景</th><th>支持情况</th></tr>
</thead>
<tbody>
<tr><td>页面</td><td>支持</td></tr>
<tr><td>卡片</td><td>不支持</td></tr>
</tbody>
</table>

## 使用说明

- 调用 play 前先设置有效 src；播放结束且不再需要背景播放时调用 stop。

## 调用方式

### 同步 API

```typescript
getBackgroundAudioManager(): BackgroundAudioManager
```

## 入参

无。

## 调用示例

```typescript
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();
```

## 返回值

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>buffered</code></td><td><code>number</code></td><td>是</td><td>当前已缓冲到的位置，单位秒。</td></tr>
<tr><td><code>coverImgUrl</code></td><td><code>string</code></td><td>是</td><td>封面图片地址。</td></tr>
<tr><td><code>currentTime</code></td><td><code>number</code></td><td>是</td><td>当前播放位置，单位秒。</td></tr>
<tr><td><code>duration</code></td><td><code>number</code></td><td>是</td><td>音频总时长，单位秒；资源尚未就绪时为 0。</td></tr>
<tr><td><code>epname</code></td><td><code>string</code></td><td>是</td><td>专辑名称。</td></tr>
<tr><td><code>offCanplay</code></td><td><code>(callback?: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>取消 canplay 监听；省略 callback 时移除该事件的全部监听。</td></tr>
<tr><td><code>offEnded</code></td><td><code>(callback?: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>取消 ended 监听；省略 callback 时移除该事件的全部监听。</td></tr>
<tr><td><code>offError</code></td><td><code>(callback?: BackgroundAudioManagerErrorCallback) =&gt; void</code></td><td>是</td><td>取消 error 监听；省略 callback 时移除全部错误监听。</td></tr>
<tr><td><code>offNext</code></td><td><code>(callback?: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>取消 next 监听；省略 callback 时移除该事件的全部监听。</td></tr>
<tr><td><code>offPause</code></td><td><code>(callback?: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>取消 pause 监听；省略 callback 时移除该事件的全部监听。</td></tr>
<tr><td><code>offPlay</code></td><td><code>(callback?: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>取消 play 监听；省略 callback 时移除该事件的全部监听。</td></tr>
<tr><td><code>offPrev</code></td><td><code>(callback?: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>取消 prev 监听；省略 callback 时移除该事件的全部监听。</td></tr>
<tr><td><code>offSeeked</code></td><td><code>(callback?: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>取消 seeked 监听；省略 callback 时移除该事件的全部监听。</td></tr>
<tr><td><code>offSeeking</code></td><td><code>(callback?: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>取消 seeking 监听；省略 callback 时移除该事件的全部监听。</td></tr>
<tr><td><code>offStop</code></td><td><code>(callback?: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>取消 stop 监听；省略 callback 时移除该事件的全部监听。</td></tr>
<tr><td><code>offTimeUpdate</code></td><td><code>(callback?: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>取消 timeupdate 监听；省略 callback 时移除该事件的全部监听。</td></tr>
<tr><td><code>offWaiting</code></td><td><code>(callback?: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>取消 waiting 监听；省略 callback 时移除该事件的全部监听。</td></tr>
<tr><td><code>onCanplay</code></td><td><code>(callback: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>监听音频可以开始播放的事件。</td></tr>
<tr><td><code>onEnded</code></td><td><code>(callback: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>监听自然播放结束事件。</td></tr>
<tr><td><code>onError</code></td><td><code>(callback: BackgroundAudioManagerErrorCallback) =&gt; void</code></td><td>是</td><td>监听播放、资源或占用冲突错误。</td></tr>
<tr><td><code>onNext</code></td><td><code>(callback: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>监听用户在豆包背景播放控件中点击下一首的事件。</td></tr>
<tr><td><code>onPause</code></td><td><code>(callback: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>监听暂停事件。</td></tr>
<tr><td><code>onPlay</code></td><td><code>(callback: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>监听开始播放事件。</td></tr>
<tr><td><code>onPrev</code></td><td><code>(callback: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>监听用户在豆包背景播放控件中点击上一首的事件。</td></tr>
<tr><td><code>onSeeked</code></td><td><code>(callback: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>监听完成跳转播放位置的事件。</td></tr>
<tr><td><code>onSeeking</code></td><td><code>(callback: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>监听开始跳转播放位置的事件。</td></tr>
<tr><td><code>onStop</code></td><td><code>(callback: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>监听停止事件。</td></tr>
<tr><td><code>onTimeUpdate</code></td><td><code>(callback: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>监听播放进度更新事件。</td></tr>
<tr><td><code>onWaiting</code></td><td><code>(callback: BackgroundAudioManagerEventCallback) =&gt; void</code></td><td>是</td><td>监听因缓冲不足而等待的事件。</td></tr>
<tr><td><code>pause</code></td><td><code>() =&gt; void</code></td><td>是</td><td>暂停播放。</td></tr>
<tr><td><code>paused</code></td><td><code>boolean</code></td><td>是</td><td>当前是否暂停。</td></tr>
<tr><td><code>play</code></td><td><code>() =&gt; void</code></td><td>是</td><td>播放音频；调用前需要先设置 src。</td></tr>
<tr><td><code>playbackRate</code></td><td><code>number</code></td><td>是</td><td>播放速度，默认为 1。</td></tr>
<tr><td><code>seek</code></td><td><code>(position: number) =&gt; void</code></td><td>是</td><td>跳转到指定播放位置，position 的单位为秒且不能为负数。</td></tr>
<tr><td><code>singer</code></td><td><code>string</code></td><td>是</td><td>歌手或作者名称。</td></tr>
<tr><td><code>src</code></td><td><code>string</code></td><td>是</td><td>音频资源地址，支持 HTTP、HTTPS 地址。</td></tr>
<tr><td><code>startTime</code></td><td><code>number</code></td><td>是</td><td>开始播放的位置，单位秒，默认为 0。</td></tr>
<tr><td><code>stop</code></td><td><code>() =&gt; void</code></td><td>是</td><td>停止播放并释放当前背景音频占用。</td></tr>
<tr><td><code>title</code></td><td><code>string</code></td><td>是</td><td>音频标题，用于豆包背景播放信息展示。</td></tr>
<tr><td><code>webUrl</code></td><td><code>string</code></td><td>是</td><td>音频关联页面地址。</td></tr>
</tbody>
</table>

### 返回示例

```json
{
  "src": "",
  "title": "",
  "epname": "",
  "singer": "",
  "coverImgUrl": "",
  "webUrl": "",
  "startTime": 0,
  "currentTime": 0,
  "duration": 0,
  "paused": true,
  "buffered": 0,
  "playbackRate": 1
}
```

## 错误处理

管理器操作失败时通过错误事件回调返回。错误对象和通用错误码见 [通用错误处理](/apps-plugin/docs/js-api/common-errors.md#错误返回)。

### 失败示例

```json
{
  "errCode": -1001,
  "errMsg": "background audio src is empty"
}
```

### 错误码

#### 事件错误码

<table>
<thead>
<tr><th>错误字段</th><th>值</th><th>错误信息</th><th>平台</th><th>触发条件</th><th>处理建议</th></tr>
</thead>
<tbody>
<tr><td><code>event.errCode</code></td><td><code>-1001</code></td><td><code>background audio src is empty</code></td><td>Android、iOS</td><td>未设置 src 就调用 play</td><td>设置有效 src 后重试。</td></tr>
<tr><td><code>event.errCode</code></td><td><code>-1002</code></td><td><code>background audio play failed</code></td><td>Android</td><td>播放器启动失败</td><td>检查资源地址和网络状态后重试。</td></tr>
<tr><td><code>event.errCode</code></td><td><code>-1003</code></td><td><code>background audio seek failed</code></td><td>Android、iOS</td><td>播放位置跳转失败</td><td>等待 canplay 后在音频时长范围内重试。</td></tr>
<tr><td><code>event.errCode</code></td><td><code>-1004</code></td><td><code>background audio player unavailable</code></td><td>Android、iOS</td><td>播放器无法创建或已经不可用</td><td>重新设置 src 后重试。</td></tr>
<tr><td><code>event.errCode</code></td><td><code>-1005</code></td><td><code>background audio is occupied by another applet</code></td><td>Android、iOS</td><td>另一应用插件正在占用背景音频</td><td>提示用户结束其他背景音频后重试。</td></tr>
</tbody>
</table>

## 平台差异

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

## 已知限制与注意事项

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