setVolumeFactor
Set Volume Scaling Factor
setVolumeFactor: is the volume control method of the SUDRTGameAudioSession protocol. It is used to adjust the relative gain of the game's internal audio output without changing the iOS system master volume (Media Volume). Through this method, the App can achieve a mixing balance between the game sound and background music, or provide users with an independent volume adjustment slider.
Method Declaration
objc
/**
* Sets the volume scaling factor.
* @param factor The scaling ratio. 0.0 indicates software mute, 1.0 indicates original volume.
*/
- (void)setVolumeFactor:(float)factor;Runtime Behavior
- Multiplicative gain: This factor is multiplied by the game's original volume and the system volume. Final output volume = game original volume ×
factor× system master volume. - Non-linear adjustment: It is generally recommended to convert the linear slider value to a logarithmic scale at the UI layer, to obtain a more ergonomic change in perceived loudness.
- Immediate effect: After the call, the SDK engine immediately adjusts the mixer's output gain without restarting the audio session.
- State isolation: This setting is effective only for the audio managed by the current SDK instance and does not affect other Apps running on the device.
Code Example
Implement a simple volume adjustment logic that syncs the UI slider value to the game:
objc
- (void)onVolumeSliderChanged:(UISlider *)slider {
// 1. Get the slider value (assuming the range is 0.0 ~ 1.0)
float volumeFactor = slider.value;
// 2. Set the factor on the SDK audio session
if (self.audioSession) {
[self.audioSession setVolumeFactor:volumeFactor];
NSLog(@"Adjusted the game volume factor to: %.2f", volumeFactor);
}
}Notes
- Range recommendation: Although the parameter type is
float, it is generally recommended to limit it to between0.0(silent) and1.0(full volume). Setting a value greater than1.0may cause audio clipping and produce noise. - Stacking with mute: Even if
factoris set to1.0, ifmute:YESwas called previously, the game still produces no sound. - Persistence: After the SDK instance is destroyed, this factor is typically not saved automatically. If you want to retain the volume the next time the user enters the game, the App side needs to persist this value itself (for example, using
NSUserDefaults).
