文档中心

getVolumeFactor ​

获取音量缩放因子 ​

getVolumeFactor 是 SUDRTGameAudioSession 协议中的一个同步查询方法。它用于获取当前游戏音频在原始音量基础上的增益倍数。该数值是一个浮点数，代表了游戏内部音频输出的缩放比例，而不直接等同于系统的媒体音量滑块。

方法声明 ​

objc
/**
 * 获取当前的音量缩放因子。
 * @return 返回值范围通常为 0.0（完全静音）到 1.0（原始音量）。
 */
- (float)getVolumeFactor;

运行行为 ​

  1. 相对增益：返回的因子是一个百分比系数。例如，如果返回 0.5f，意味着游戏声音将以系统当前媒体音量的 50% 进行播放。
  2. 实时同步：该方法实时反映通过 setVolumeFactor: 设置的最新状态，确保 App 侧的 UI（如音量进度条）与 SDK 内部状态保持一致。
  3. 独立性：此因子仅作用于当前游戏实例的音频轨道，不会修改 iOS 系统（AVAudioSession）的全局主音量。

代码示例 ​

用于同步 App 自定义音量调节 UI 的初始状态：

objc
- (void)syncVolumeUI {
    // 1. 从音频会话中获取当前因子
    float currentFactor = [self.audioSession getVolumeFactor];
    
    // 2. 更新 UI 组件（如 UISlider）
    self.volumeSlider.value = currentFactor;
    
    NSLog(@"当前游戏音量因子为: %.2f", currentFactor);
}

注意事项 ​

  • 默认值：在未手动调用 setVolumeFactor: 之前，SDK 默认返回的因子通常为 1.0f。
  • 与 Mute 的区别：即便 getVolumeFactor 返回 1.0f，如果此时调用了 mute:YES，游戏依然没有声音。因此在判断是否有声时，建议结合 isMute 方法共同逻辑判定。
  • 范围限制：虽然技术上可以设置大于 1.0f 的值（实现音频增益），但为了防止破音或损坏扬声器，建议 App 侧将其限制在 0.0 - 1.0 之间。