音频状态

有些宿主会在游戏周围绘制自己的声音和音乐按钮。frvr.com 的游戏页面是第一个:它的开关在游戏 iframe 之外。FRVR.audio 告诉游戏这些开关的当前状态,游戏就可以跟随它们,而不是再显示一套自己的。

它和生命周期音频回调是两回事。onAudioSuspend / onAudioResume 在每个渠道上仍然必须实现。FRVR.audio 只是在支持的宿主上,额外提供音乐和音效的区分。

检查宿主是否控制音频

在没有宿主音频控件的渠道上,FRVR.audio 是 undefined。存在时,isAvailable() 在与宿主握手之后 settle 一次:

const audio = FRVR.audio;
if (audio && await audio.isAvailable()) {
  hideOwnAudioControls();
  applyAudioState(audio.getState());
  audio.addListener(applyAudioState);
} else {
  showOwnAudioControls();
}

false 表示本次会话宿主不控制音频,游戏保留自己的控件。

读取状态

const { music, sound } = FRVR.audio.getState();
// true = 可以发声

在宿主上报之前,getState() 返回 { music: true, sound: true };从 isAvailable() resolve true 起它是准确的。只有一个静音按钮的宿主,两个字段会上报相同的值。

响应变化

function applyAudioState({ music, sound }) {
  mixer.music.setMuted(!music);
  mixer.sfx.setMuted(!sound);
}

FRVR.audio.addListener(applyAudioState);
// 之后
FRVR.audio.removeListener(applyAudioState);

宿主的状态优先于已保存的设置

宿主控制音频期间,它的状态在两个方向上都优先。如果玩家在之前的会话里把游戏静音了,而宿主说未静音,游戏就要出声,反之亦然。

把宿主的状态当作临时覆盖来应用。不要把它写进玩家保存的声音设置:到了没有宿主控件的渠道,游戏自己的设置要重新生效。

不读 FRVR.audio 的游戏

它们仍然会被静音。宿主把音乐和音效都关掉时,SDK 调用 FRVR.lifecycle.onAudioSuspend();任意一个重新打开时调用 onAudioResume()。只关其中一个不会触发生命周期回调,所以游戏要读 FRVR.audio 才能区分两者。

同一个标志也发布在 FRVR.channelCharacteristics.hasNativeAudioControls 上,适合只需要决定是否绘制按钮的代码。

API 摘要

方法	作用
isAvailable()	宿主控制音频状态时 resolve true。只 settle 一次。
getState()	当前的 { music, sound }。true 表示可以发声。
addListener(fn)	宿主每次改变状态时调用 fn(state)。
removeListener(fn)	移除用 addListener 添加的监听。