#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();#返回值
| 名称 | 类型 | 必返 | 说明 |
|---|---|---|---|
autoplay | boolean | 是 | 设置 src 后是否自动播放,默认为 false。 |
buffered | number | 是 | 当前已缓冲到的位置,单位秒。 |
currentTime | number | 是 | 当前播放位置,单位秒。 |
destroy | () => void | 是 | 销毁当前上下文并释放播放资源;销毁后不能继续调用。 |
duration | number | 是 | 音频总时长,单位秒;资源尚未就绪时为 0。 |
loop | boolean | 是 | 是否循环播放,默认为 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 | 是 | 暂停播放。 |
paused | boolean | 是 | 当前是否暂停。 |
play | () => void | 是 | 播放音频;调用前需要先设置 src。 |
playbackRate | number | 是 | 播放速度,豆包实际使用范围为 0.5 至 2,默认为 1。 |
seek | (position: number) => void | 是 | 跳转到指定播放位置,position 的单位为秒且不能为负数。 |
src | string | 是 | 音频资源地址,支持 HTTP、HTTPS 地址和豆包应用插件本地文件路径。 |
startTime | number | 是 | 开始播放的位置,单位秒,默认为 0。 |
stop | () => void | 是 | 停止播放并将播放位置归零。 |
volume | number | 是 | 音量,范围 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 | -2002 | inner audio instance not found | Android、iOS | 实例已销毁或不存在时继续操作 | 重新创建上下文,不要继续使用已销毁实例。 |
event.errCode | -2003 | inner audio src is empty | Android、iOS | 未设置 src 就调用 play | 设置有效 src 后重试。 |
event.errCode | -2004 | inner audio src is invalid | Android、iOS | src 无法解析或不受支持 | 改用有效的 HTTP、HTTPS 地址或豆包应用插件本地文件路径。 |
event.errCode | -2005 | inner audio player unavailable | Android、iOS | 播放器无法创建或已不可用 | 销毁当前实例,重新创建后重试。 |
event.errCode | -2006 | inner audio seek failed | Android、iOS | 播放位置跳转失败 | 等待 canplay 后在音频时长范围内重试。 |
event.errCode | -2007 | inner audio play failed | Android、iOS | 音频播放失败 | 检查资源地址和网络状态后重试。 |
event.errCode | -2009 | inner audio playback is interrupted | Android、iOS | 播放被其他音频任务中断 | 根据业务需要在中断结束后重新调用 play。 |
event.errCode | -2010 | inner audio runtime is unavailable | Android、iOS | 当前页面无法创建音频实例 | 确保页面仍处于有效状态后重新创建实例。 |
event.errCode | -2012 | invalid seek position | Android、iOS | seek 位置不是有限非负数 | 传入大于或等于 0 的秒数。 |