Skip to content

getVolumeFactor ​

Get Volume Scaling Factor ​

getVolumeFactor is a synchronous query method of the SUDRTGameAudioSession protocol. It is used to obtain the gain multiplier applied to the current game audio on top of the original volume. This value is a float representing the scaling ratio of the game's internal audio output; it is not directly equivalent to the system's media volume slider.


Method Declaration ​

objc
/**
 * Gets the current volume scaling factor.
 * @return The return value typically ranges from 0.0 (fully muted) to 1.0 (original volume).
 */
- (float)getVolumeFactor;

Runtime Behavior ​

  1. Relative gain: The returned factor is a percentage coefficient. For example, if it returns 0.5f, it means the game sound will play at 50% of the system's current media volume.
  2. Real-time sync: This method reflects in real time the latest state set via setVolumeFactor:, ensuring that the App-side UI (such as a volume progress bar) stays consistent with the SDK's internal state.
  3. Independence: This factor affects only the audio track of the current game instance and does not modify the global master volume of the iOS system (AVAudioSession).

Code Example ​

Used to sync the initial state of an App's custom volume adjustment UI:

objc
- (void)syncVolumeUI {
    // 1. Get the current factor from the audio session
    float currentFactor = [self.audioSession getVolumeFactor];
    
    // 2. Update the UI component (such as a UISlider)
    self.volumeSlider.value = currentFactor;
    
    NSLog(@"Current game volume factor is: %.2f", currentFactor);
}

Notes ​

  • Default value: Before setVolumeFactor: is called manually, the factor returned by the SDK by default is typically 1.0f.
  • Difference from Mute: Even if getVolumeFactor returns 1.0f, if mute:YES has been called, the game still produces no sound. Therefore, when determining whether there is sound, it is recommended to combine the isMute method in the logic.
  • Range limit: Although technically a value greater than 1.0f can be set (to achieve audio gain), to prevent distortion or speaker damage, it is recommended that the App side limit it to between 0.0 and 1.0.