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

# createInnerAudioContext

创建一个内部音频上下文。

## 扫码预览

![扫码预览 createInnerAudioContext](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%252Fcreate-inner-audio-context%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>

## 使用说明

返回的对象拥有独立状态和事件监听。长音频或需要锁屏控制的场景请使用
`getBackgroundAudioManager()`。

- 调用 play 前先设置有效 src；不再使用实例时调用 destroy 释放资源。

## 调用方式

### 同步 API

```typescript
createInnerAudioContext(): InnerAudioContext
```

## 入参

无。

## 调用示例

```typescript
import { createInnerAudioContext } from '@doubao-dev/framework/api';

const audio = createInnerAudioContext();
audio.onError((error) => console.error(error.errCode, error.errMsg));
audio.onEnded(() => audio.destroy());
audio.src = 'https://example.com/audio.mp3';
audio.play();
```

## 返回值

<table>
<thead>
<tr><th>名称</th><th>类型</th><th>必返</th><th>说明</th></tr>
</thead>
<tbody>
<tr><td><code>autoplay</code></td><td><code>boolean</code></td><td>是</td><td>设置 src 后是否自动播放，默认为 false。</td></tr>
<tr><td><code>buffered</code></td><td><code>number</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>destroy</code></td><td><code>() =&gt; void</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>loop</code></td><td><code>boolean</code></td><td>是</td><td>是否循环播放，默认为 false。</td></tr>
<tr><td><code>offCanplay</code></td><td><code>(callback?: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>取消 canplay 监听；省略 callback 时移除该事件的全部监听。</td></tr>
<tr><td><code>offEnded</code></td><td><code>(callback?: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>取消 ended 监听；省略 callback 时移除该事件的全部监听。</td></tr>
<tr><td><code>offError</code></td><td><code>(callback?: InnerAudioContextErrorCallback) =&gt; void</code></td><td>是</td><td>取消 error 监听；省略 callback 时移除全部错误监听。</td></tr>
<tr><td><code>offPause</code></td><td><code>(callback?: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>取消 pause 监听；省略 callback 时移除该事件的全部监听。</td></tr>
<tr><td><code>offPlay</code></td><td><code>(callback?: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>取消 play 监听；省略 callback 时移除该事件的全部监听。</td></tr>
<tr><td><code>offSeeked</code></td><td><code>(callback?: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>取消 seeked 监听；省略 callback 时移除该事件的全部监听。</td></tr>
<tr><td><code>offSeeking</code></td><td><code>(callback?: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>取消 seeking 监听；省略 callback 时移除该事件的全部监听。</td></tr>
<tr><td><code>offStop</code></td><td><code>(callback?: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>取消 stop 监听；省略 callback 时移除该事件的全部监听。</td></tr>
<tr><td><code>offTimeUpdate</code></td><td><code>(callback?: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>取消 timeupdate 监听；省略 callback 时移除该事件的全部监听。</td></tr>
<tr><td><code>offWaiting</code></td><td><code>(callback?: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>取消 waiting 监听；省略 callback 时移除该事件的全部监听。</td></tr>
<tr><td><code>onCanplay</code></td><td><code>(callback: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>监听音频可以开始播放的事件。</td></tr>
<tr><td><code>onEnded</code></td><td><code>(callback: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>监听自然播放结束事件。</td></tr>
<tr><td><code>onError</code></td><td><code>(callback: InnerAudioContextErrorCallback) =&gt; void</code></td><td>是</td><td>监听播放、参数或资源错误。</td></tr>
<tr><td><code>onPause</code></td><td><code>(callback: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>监听暂停事件。</td></tr>
<tr><td><code>onPlay</code></td><td><code>(callback: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>监听开始播放事件。</td></tr>
<tr><td><code>onSeeked</code></td><td><code>(callback: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>监听完成跳转播放位置的事件。</td></tr>
<tr><td><code>onSeeking</code></td><td><code>(callback: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>监听开始跳转播放位置的事件。</td></tr>
<tr><td><code>onStop</code></td><td><code>(callback: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>监听停止事件。</td></tr>
<tr><td><code>onTimeUpdate</code></td><td><code>(callback: InnerAudioContextEventCallback) =&gt; void</code></td><td>是</td><td>监听播放进度更新事件。</td></tr>
<tr><td><code>onWaiting</code></td><td><code>(callback: InnerAudioContextEventCallback) =&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>播放速度，豆包实际使用范围为 0.5 至 2，默认为 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>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>volume</code></td><td><code>number</code></td><td>是</td><td>音量，范围 0 至 1，默认为 1。</td></tr>
</tbody>
</table>

### 返回示例

```json
{
  "src": "",
  "startTime": 0,
  "autoplay": false,
  "loop": false,
  "volume": 1,
  "playbackRate": 1,
  "currentTime": 0,
  "duration": 0,
  "paused": true,
  "buffered": 0
}
```

## 错误处理

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

### 失败示例

```json
{
  "errCode": -2003,
  "errMsg": "inner 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>-2002</code></td><td><code>inner audio instance not found</code></td><td>Android、iOS</td><td>实例已销毁或不存在时继续操作</td><td>重新创建上下文，不要继续使用已销毁实例。</td></tr>
<tr><td><code>event.errCode</code></td><td><code>-2003</code></td><td><code>inner 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>-2004</code></td><td><code>inner audio src is invalid</code></td><td>Android、iOS</td><td>src 无法解析或不受支持</td><td>改用有效的 HTTP、HTTPS 地址或豆包应用插件本地文件路径。</td></tr>
<tr><td><code>event.errCode</code></td><td><code>-2005</code></td><td><code>inner audio player unavailable</code></td><td>Android、iOS</td><td>播放器无法创建或已不可用</td><td>销毁当前实例，重新创建后重试。</td></tr>
<tr><td><code>event.errCode</code></td><td><code>-2006</code></td><td><code>inner audio seek failed</code></td><td>Android、iOS</td><td>播放位置跳转失败</td><td>等待 canplay 后在音频时长范围内重试。</td></tr>
<tr><td><code>event.errCode</code></td><td><code>-2007</code></td><td><code>inner audio play failed</code></td><td>Android、iOS</td><td>音频播放失败</td><td>检查资源地址和网络状态后重试。</td></tr>
<tr><td><code>event.errCode</code></td><td><code>-2009</code></td><td><code>inner audio playback is interrupted</code></td><td>Android、iOS</td><td>播放被其他音频任务中断</td><td>根据业务需要在中断结束后重新调用 play。</td></tr>
<tr><td><code>event.errCode</code></td><td><code>-2010</code></td><td><code>inner audio runtime is unavailable</code></td><td>Android、iOS</td><td>当前页面无法创建音频实例</td><td>确保页面仍处于有效状态后重新创建实例。</td></tr>
<tr><td><code>event.errCode</code></td><td><code>-2012</code></td><td><code>invalid seek position</code></td><td>Android、iOS</td><td>seek 位置不是有限非负数</td><td>传入大于或等于 0 的秒数。</td></tr>
</tbody>
</table>
