文档中心

setVolumeFactor ​

设置音量缩放因子 ​

setVolumeFactor 是 SUDRTGameAudioSession 接口中用于调节游戏音量强度的核心方法。它通过改变音频输出的增益值（Gain），在不触动系统全局媒体音量的前提下，实现对游戏内声音大小的精准控制。

方法声明 ​

java
/**
 * 设置当前游戏实例的音量缩放比例。
 * @param var1 音量因子，取值范围为 0.0f（完全无声）到 1.0f（满额音量）。
 * 超出此范围的值通常会被 SDK 自动截断（Clamp）在 [0, 1] 区间。
 */
void setVolumeFactor(float var1);

运行行为 ​

  1. 相对增益：该方法调节的是相对比例。实际听觉音量 = Android系统媒体音量 × var1。
  2. 即时生效：调用后，正在播放的背景音乐（BGM）和实时音效（SFX）会立即产生音量变化，无需重启音频流。
  3. 非破坏性：调低此数值不会影响手机上其他 App（如正在后台运行的音乐播放器）的音量，实现了应用内的音频隔离。

代码示例 ​

实现一个音量滑动条（SeekBar）来控制游戏音量：

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

// SeekBar 进度改变监听（假设范围 0-100）
volumeSeekBar.setOnSeekBarChangeListener(new SeekBar.OnSeekBarChangeListener() {
    @Override
    public void onProgressChanged(SeekBar seekBar, int progress, boolean fromUser) {
        // 将 0-100 转换为 0.0-1.0 的浮点数
        float factor = progress / 100.0f;
        
        // 调用 SDK 设置音量因子
        audioSession.setVolumeFactor(factor);
        
        Log.d("SudAudio", "调节游戏音量因子为: " + factor);
    }
});

注意事项 ​

  • 平滑处理：虽然 SDK 支持直接设置，但如果 App 侧短时间内高频调用（如在动画循环中），建议做一定的节流（Throttling）处理，以确保音频切换平滑。
  • 与静音冲突：如果当前已调用 mute(true)，则无论 setVolumeFactor 设置为多少，用户都听不到声音。
  • 默认强度：大多数 SDK 在初始化时默认音量因子为 1.0f。