文档中心

setGameQueryAudioOptionsListener ​

注册音频策略监听器 ​

setGameQueryAudioOptionsListener 是 SUDRTGameAudioSession 接口中用于定制音频底层行为的关键方法。它允许宿主 App 拦截并介入游戏引擎的音频初始化过程，根据 App 当前的业务场景（如是否正在进行语音通话、是否需要强制开启扬声器等）动态决策音频策略。

方法声明 ​

java
/**
 * 设置音频查询配置监听器。
 * @param var1 实现 GameQueryAudioOptionsListener 接口的对象。
 * 传入 null 可解除当前监听器的绑定。
 */
void setGameQueryAudioOptionsListener(SUDRTGameAudioSession.GameQueryAudioOptionsListener var1);

运行机制 ​

  1. 主动询问：当游戏准备开启麦克风或初始化音频轨道（AudioTrack）时，SDK 会触发此监听器。
  2. 异步响应：该机制设计了 GameQueryAudioOptionsHandle，允许 App 在处理完复杂的业务逻辑（如申请权限或检查其他音源）后再通过 complete 方法反馈结果。
  3. 参数透传：onQueryAudioOptions 会携带一个 Bundle，包含了 SDK 建议的默认配置（如 KEY_AUDIO_SPEAKER_ON），App 可以选择覆盖这些建议。

代码示例 ​

实现并注册监听器以精细化控制音频行为：

java
// 获取音频会话控制对象
SUDRTGameAudioSession audioSession = mGameHandle.getAudioSession();

// 注册监听器
audioSession.setGameQueryAudioOptionsListener(new SUDRTGameAudioSession.GameQueryAudioOptionsListener() {
    @Override
    public void onQueryAudioOptions(SUDRTGameAudioSession.GameQueryAudioOptionsHandle handle, Bundle options) {
        // 1. 解析 SDK 建议的配置
        boolean isSpeakerRequest = options.getBoolean(SUDRTGameAudioSession.KEY_AUDIO_SPEAKER_ON);
        
        // 2. 业务决策：例如在 App 语音房内，强制开启扬声器
        if (isInVoiceChatRoom()) {
            options.putBoolean(SUDRTGameAudioSession.KEY_AUDIO_SPEAKER_ON, true);
        }
        
        // 3. 必须调用 handle.complete 来通知 SDK 继续执行
        // 参数 1：是否允许此次音频初始化；参数 2：日志或说明信息
        handle.complete(true, "App applied custom audio policy");
    }
});

注意事项 ​

  • 阻塞风险：如果不调用 handle.complete()，游戏音频初始化流程可能会挂起。请确保在所有代码分支（包括异常捕获分支）中都调用了该方法。
  • 时机要求：建议在调用 gameHandle.start() 之前完成监听器的设置，以便捕获游戏启动时的首次音频配置请求。
  • 线程处理：此回调通常不在 UI 线程执行。如果在回调内涉及 UI 操作，请使用 Handler 或 runOnUiThread 进行切换。
  • 重复设置：同一个 audioSession 实例只能持有一个监听器，后设置的实例会覆盖前者。