音频

相关参考：Scene API / 音频

Web 高级 API 当前提供的是对场景中已有音频对象的控制能力。

也就是说，音频通常是在场景编辑器中预先配置好的，宿主页面再通过高级 API 去：

• 获取音频对象
• 播放、暂停、停止、重播
• 读取时长、播放位置、循环状态
• 跳转播放时间
• 监听播放相关事件

获取音频对象

当前没有 createAudio() 这类运行时新增音频的 API。宿主页面可自己实例化Audio对象进行音频播放控制。

最常见的方式是通过对象名称获取：

const audio = await api.getObject('scene-bgm');

如果返回 null，通常说明：

• 场景里没有这个名称的音频对象
• 对象还未进入可读取状态
• 名称写错了

因此更稳妥的时机通常是 loadSceneEnd 或 sceneStart 之后再获取：

iframe.addEventListener('loadSceneEnd', async () => {
  const audio = await api.getObject('scene-bgm');
  console.log(audio);
});

播放控制

播放

await api.playAudio(audio, {
  loop: false,
});

如果需要，也可以通过 options.loop 直接指定是否循环播放。

暂停、停止、重播

await api.pauseAudio(audio);
await api.stopAudio(audio);
await api.playbackAudio(audio, { loop: false });

这几个方法的区别通常是：

• pauseAudio()：暂停在当前位置
• stopAudio()：停止并回到开头
• playbackAudio()：从头重新开始播放

读取状态

const duration = await api.getAudioDuration(audio);
const paused = await api.getAudioPaused(audio);
const currentTime = await api.getAudioCurrentTime(audio);
const loop = await api.getAudioLoop(audio);

常见用途：

• 根据 paused 切换宿主层播放按钮图标
• 根据 currentTime 和 duration 做简单进度显示
• 根据 loop 判断当前是否处于循环模式

跳转时间与循环设置

await api.setAudioCurrentTime(audio, 12.5);
await api.setAudioLoop(audio, true);

适合的场景包括：

• 从宿主层自定义进度条跳转到指定位置
• 切换背景音乐是否循环
• 做“试听片段”或“重新播放指定段落”的交互

播放事件

音频对象支持和视频类似的媒体事件：

• play - 开始播放时触发
• pause - 暂停时触发
• ended - 自然播放完毕时触发

示例：

function onPlay(event) {
  // https://developer.mozilla.org/en-US/docs/Web/API/Event
}

function onPause(event) {
  // https://developer.mozilla.org/en-US/docs/Web/API/Event
}

function onEnded(event) {
  // https://developer.mozilla.org/en-US/docs/Web/API/Event
}

await api.on('play', onPlay, audio);
await api.on('pause', onPause, audio);
await api.on('ended', onEnded, audio);

推荐用法

背景音乐

常见做法是：

1. 场景编辑器中放入一个背景音乐对象
2. 宿主页面通过 getObject() 拿到它
3. 在用户点击“开始体验”或宿主按钮之后调用 playAudio()
4. 用宿主层按钮控制 pauseAudio() / playbackAudio()

场景音效

适合：

• 某个关键交互发生后播放提示音
• 配合对象点击、动画完成、识别成功等流程做反馈
• 在宿主层控制是否静音或重新播放

注意

没有运行时创建 API

当前音频能力主要面向控制已有音频对象，不是在宿主层动态创建新音频。

音频不是 3D 对象

音频不属于普通的 3D 对象，因此不能像模型、图片、视频那样去做 addChild() 这类层级挂接。

自动播放仍受浏览器限制

即便插件内部有一些兼容处理，音频播放仍然会受浏览器自动播放策略影响。尤其要注意：

• 强制隐藏“立即体验”按钮后，更容易被浏览器拦截
• iOS 和部分 App 内 WebView 的限制更严格
• 如果播放不是由用户手势触发，成功率会下降

因此如果你的项目依赖背景音乐或重要提示音，最好：

1. 保留默认开始流程，或
2. 在宿主层提供一个明确的用户点击入口，再开始播放音频

对象名最好提前规划

如果你打算在宿主页面里控制音频，建议在场景编辑器里为音频对象设置稳定、可读的名称，例如：

• scene-bgm
• button-click-sfx
• result-voiceover

这样后续通过 getObject() 获取会更稳定。