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/createInnerAudioContext.md.

createInnerAudioContext

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

扫码预览

扫码预览 createInnerAudioContext

支持版本

前端库版本不低于 0.0.37。

支持平台

平台支持情况
Android支持
iOS支持
PC不支持
HarmonyOS不支持

支持场景

场景支持情况
页面支持
卡片不支持

使用说明

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

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

调用方式

同步 API

createInnerAudioContext(): InnerAudioContext

入参

无。

调用示例

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

返回值

名称类型必返说明
autoplayboolean是设置 src 后是否自动播放,默认为 false。
bufferednumber是当前已缓冲到的位置,单位秒。
currentTimenumber是当前播放位置,单位秒。
destroy() => void是销毁当前上下文并释放播放资源;销毁后不能继续调用。
durationnumber是音频总时长,单位秒;资源尚未就绪时为 0。
loopboolean是是否循环播放,默认为 false。
offCanplay(callback?: InnerAudioContextEventCallback) => void是取消 canplay 监听;省略 callback 时移除该事件的全部监听。
offEnded(callback?: InnerAudioContextEventCallback) => void是取消 ended 监听;省略 callback 时移除该事件的全部监听。
offError(callback?: InnerAudioContextErrorCallback) => void是取消 error 监听;省略 callback 时移除全部错误监听。
offPause(callback?: InnerAudioContextEventCallback) => void是取消 pause 监听;省略 callback 时移除该事件的全部监听。
offPlay(callback?: InnerAudioContextEventCallback) => void是取消 play 监听;省略 callback 时移除该事件的全部监听。
offSeeked(callback?: InnerAudioContextEventCallback) => void是取消 seeked 监听;省略 callback 时移除该事件的全部监听。
offSeeking(callback?: InnerAudioContextEventCallback) => void是取消 seeking 监听;省略 callback 时移除该事件的全部监听。
offStop(callback?: InnerAudioContextEventCallback) => void是取消 stop 监听;省略 callback 时移除该事件的全部监听。
offTimeUpdate(callback?: InnerAudioContextEventCallback) => void是取消 timeupdate 监听;省略 callback 时移除该事件的全部监听。
offWaiting(callback?: InnerAudioContextEventCallback) => void是取消 waiting 监听;省略 callback 时移除该事件的全部监听。
onCanplay(callback: InnerAudioContextEventCallback) => void是监听音频可以开始播放的事件。
onEnded(callback: InnerAudioContextEventCallback) => void是监听自然播放结束事件。
onError(callback: InnerAudioContextErrorCallback) => void是监听播放、参数或资源错误。
onPause(callback: InnerAudioContextEventCallback) => void是监听暂停事件。
onPlay(callback: InnerAudioContextEventCallback) => void是监听开始播放事件。
onSeeked(callback: InnerAudioContextEventCallback) => void是监听完成跳转播放位置的事件。
onSeeking(callback: InnerAudioContextEventCallback) => void是监听开始跳转播放位置的事件。
onStop(callback: InnerAudioContextEventCallback) => void是监听停止事件。
onTimeUpdate(callback: InnerAudioContextEventCallback) => void是监听播放进度更新事件。
onWaiting(callback: InnerAudioContextEventCallback) => void是监听因缓冲不足而等待的事件。
pause() => void是暂停播放。
pausedboolean是当前是否暂停。
play() => void是播放音频;调用前需要先设置 src。
playbackRatenumber是播放速度,豆包实际使用范围为 0.5 至 2,默认为 1。
seek(position: number) => void是跳转到指定播放位置,position 的单位为秒且不能为负数。
srcstring是音频资源地址,支持 HTTP、HTTPS 地址和豆包应用插件本地文件路径。
startTimenumber是开始播放的位置,单位秒,默认为 0。
stop() => void是停止播放并将播放位置归零。
volumenumber是音量,范围 0 至 1,默认为 1。

返回示例

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

错误处理

管理器操作失败时通过错误事件回调返回。错误对象和通用错误码见 通用错误处理。

失败示例

{
  "errCode": -2003,
  "errMsg": "inner audio src is empty"
}

错误码

事件错误码

错误字段值错误信息平台触发条件处理建议
event.errCode-2002inner audio instance not foundAndroid、iOS实例已销毁或不存在时继续操作重新创建上下文,不要继续使用已销毁实例。
event.errCode-2003inner audio src is emptyAndroid、iOS未设置 src 就调用 play设置有效 src 后重试。
event.errCode-2004inner audio src is invalidAndroid、iOSsrc 无法解析或不受支持改用有效的 HTTP、HTTPS 地址或豆包应用插件本地文件路径。
event.errCode-2005inner audio player unavailableAndroid、iOS播放器无法创建或已不可用销毁当前实例,重新创建后重试。
event.errCode-2006inner audio seek failedAndroid、iOS播放位置跳转失败等待 canplay 后在音频时长范围内重试。
event.errCode-2007inner audio play failedAndroid、iOS音频播放失败检查资源地址和网络状态后重试。
event.errCode-2009inner audio playback is interruptedAndroid、iOS播放被其他音频任务中断根据业务需要在中断结束后重新调用 play。
event.errCode-2010inner audio runtime is unavailableAndroid、iOS当前页面无法创建音频实例确保页面仍处于有效状态后重新创建实例。
event.errCode-2012invalid seek positionAndroid、iOSseek 位置不是有限非负数传入大于或等于 0 的秒数。