Game Voice

Feature Overview

Concept Explanation

• Range: The distance range within which a listener receives audio.
• Orientation: Refers to the position and facing direction of the listener in the game world coordinates. For details, refer to 5 Set the current position of the listener.
• Listener: A user in the Room who receives audio.
• Speaker: A user in the Room who sends audio.

Feature Description

Starting from version 2.11.0, ZEGO Express SDK has added a game voice module, which mainly includes: range voice, 3D audio effects, and team voice.

Feature	Description
Range Voice	The listener in the Room has a range limit for receiving audio. If the distance between the speaker and the listener exceeds this range, the speaker's voice cannot be heard. To ensure voice clarity, when more than 20 people nearby are speaking, only the voices of the 20 speakers closest to the listener can be heard. Assuming the maximum range of audio reception is set to R, and the distance between the speaker and the listener is r, then: When r < R, it means the speaker is within the normal range, and the listener can hear the voice. When r ≥ R, it means the speaker is beyond the maximum range, and the listener cannot hear the voice. The above diagram only shows an example where the range voice mode is "World". For more information about voice reachability under different mode combinations, please refer to Set Common Voice Mode.
3D Audio Effects	The voice has a 3D spatial sense and attenuates with distance.
Common Voice Mode	Players can choose to join a team and switch between "World", "Team Only", and "Secret Team" voice modes within the Room. World: Players can talk with other players in the world, and can also talk with teammates. Team Only: Players can only talk with teammates. Secret Team: Players can talk with teammates and can only hear the voices of other players in the world. Note Communication between teammates is not affected by "Range" and "3D Audio Effects". For details, please refer to Set Common Voice Mode. If you want to customize voice sending and receiving capabilities, please refer to Set Custom Voice Mode.

Applicable Scenarios

The game voice feature is suitable for battle royale games and metaverse scenarios.

In battle royale games, the team voice feature provides team formation functionality. Teams can be changed before and after the game starts. Developers do not need to focus on stream grouping and the implementation of publishing and playing streams, and can directly implement the team voice feature.

In battle royale games and metaverse scenarios, 3D audio effects capability is provided. When listening to speakers' audio effects, there is a sense of direction and distance, making the scene feel more realistic.

Example Source Code Download

Please refer to Download Example Source Code to get the source code.

For relevant source code, please view files in the "/ZegoExpressExample/Examples/AdvancedAudioProcessing/RangeAudio" directory.

Prerequisites

Before implementing range voice, please ensure:

• You have created a project in the ZEGOCLOUD Console, and applied for a valid AppID and AppSign. For details, please refer to Console - Project Information.
• You have integrated ZEGO Express SDK in your project and implemented basic audio/video publishing and playing stream functionality. For details, please refer to Quick Start - Integration and Quick Start - Implementation Flow.

Important Notes

If you are already using the real-time audio/video features of ZEGO Express SDK, please note the following:

• Since the range voice feature module is implemented based on the publishing and playing stream interfaces of ZegoExpressEngine, you do not need to focus on the concept of publishing and playing streams when using it. In range voice scenarios, the concept of publishing audio stream is changed to "turning on the microphone", and the concept of playing audio stream is changed to "turning on the speaker". It is recommended that you do not use the startPublishingStream and startPlayingStream interfaces to perform publishing and playing stream operations while integrating the range voice feature, to avoid effect conflicts.
• The related callbacks for publishing and playing streams in the range voice feature module (onPublisherStateUpdate, onPlayerStateUpdate, onPublisherQualityUpdate, and onPlayerQualityUpdate) will no longer take effect.

Usage Steps

The above diagram only shows the core steps and interfaces for implementing the game voice feature. Developers can implement other related interfaces according to business needs, referring to the detailed introduction in the documentation below.

1 Create Engine

Call the createEngineWithProfile interface, pass the applied AppID and AppSign to the parameters "appID" and "appSign", and create an engine singleton object. The engine currently only supports creating one instance at the same time. After exceeding this limit, null will be returned.

ZegoEngineProfile *profile = [ZegoEngineProfile new];
// Please obtain through official website registration, format: 1234567890
profile.appID = appID;
// 64 characters, please obtain through official website registration, format: "0123456789012345678901234567890123456789012345678901234567890123"
profile.appSign = appSign;
// For general scenario access, please select the appropriate scenario according to the actual situation
profile.scenario = ZegoScenarioDefault;
// Create the engine and register self as the eventHandler callback. If you do not need to register a callback, the eventHandler parameter can be passed as nil, and you can call the "-setEventHandler:" method later to set the callback
[ZegoExpressEngine createEngineWithProfile:profile eventHandler:self];

ZegoEngineProfile *profile = [ZegoEngineProfile new];
// Please obtain through official website registration, format: 1234567890
profile.appID = appID;
// 64 characters, please obtain through official website registration, format: "0123456789012345678901234567890123456789012345678901234567890123"
profile.appSign = appSign;
// For general scenario access, please select the appropriate scenario according to the actual situation
profile.scenario = ZegoScenarioDefault;
// Create the engine and register self as the eventHandler callback. If you do not need to register a callback, the eventHandler parameter can be passed as nil, and you can call the "-setEventHandler:" method later to set the callback
[ZegoExpressEngine createEngineWithProfile:profile eventHandler:self];

2 Create Range Voice Module

Call the createRangeAudio method to create a range audio instance.

ZegoRangeAudio *rangeAudio = [[ZegoExpressEngine sharedEngine] createRangeAudio];
if (rangeAudio == nil) {
    printf("Failed to create range audio instance module");
}

ZegoRangeAudio *rangeAudio = [[ZegoExpressEngine sharedEngine] createRangeAudio];
if (rangeAudio == nil) {
    printf("Failed to create range audio instance module");
}

3 Listen to Range Voice Event Callbacks

If necessary, call the setEventHandler interface to set event callbacks for the microphone, used to listen to the microphone on/off state microphoneStateUpdate notifications.

/// Set event callback listener
[rangeAudio setEventHandler:self];
···

/// Microphone state callback
- (void)rangeAudio:(ZegoRangeAudio *)rangeAudio microphoneStateUpdate:(ZegoRangeAudioMicrophoneState)state errorCode:(int)errorCode {
    [self appendLog:[NSString stringWithFormat:@"microphone state update. state: %td, errorCode: %d", state, errorCode]];
}

/// Set event callback listener
[rangeAudio setEventHandler:self];
···

/// Microphone state callback
- (void)rangeAudio:(ZegoRangeAudio *)rangeAudio microphoneStateUpdate:(ZegoRangeAudioMicrophoneState)state errorCode:(int)errorCode {
    [self appendLog:[NSString stringWithFormat:@"microphone state update. state: %td, errorCode: %d", state, errorCode]];
}

4 Login Room

After creating a ZegoUser user object by passing in the userID and userName parameters, call the loginRoom interface, pass in the roomID parameter and the user parameter to login to the Room.

// Create user object
ZegoUser *user = [ZegoUser userWithUserID:@"user1"];

// Start logging into the Room
[[ZegoExpressEngine sharedEngine] loginRoom:@"room1" user:user];

// Create user object
ZegoUser *user = [ZegoUser userWithUserID:@"user1"];

// Start logging into the Room
[[ZegoExpressEngine sharedEngine] loginRoom:@"room1" user:user];

5 Set the Current Position of the Listener

Developers can call the updateSelfPosition interface to set their own position and orientation, or update their position and facing direction in the world coordinate system when their own orientation changes.

// The coordinates of oneself in the world coordinate system, in the order of front, right, up
float position[3] = {100.0, 100.0, 100.0};
// The unit vector of the front orientation of your own coordinate system
float axisForward[3] = {1.0,0.0,0.0};
// The unit vector of the right orientation of your own coordinate system
float axisRight[3] = {0.0,1.0,0.0};
// The unit vector of the up orientation of your own coordinate system
float axisUp[3] = {0.0,0.0,1.0};

// Update your own position and orientation
[self.rangeAudio updateSelfPosition: position axisForward: axisForward axisRight: axisRight axisUp: axisUp];

// The coordinates of oneself in the world coordinate system, in the order of front, right, up
float position[3] = {100.0, 100.0, 100.0};
// The unit vector of the front orientation of your own coordinate system
float axisForward[3] = {1.0,0.0,0.0};
// The unit vector of the right orientation of your own coordinate system
float axisRight[3] = {0.0,1.0,0.0};
// The unit vector of the up orientation of your own coordinate system
float axisUp[3] = {0.0,0.0,1.0};

// Update your own position and orientation
[self.rangeAudio updateSelfPosition: position axisForward: axisForward axisRight: axisRight axisUp: axisUp];

6 Add or Update Speaker Position Information

After successfully logging into the Room, you can add or update speaker position information by calling the updateAudioSource interface.

• userID: The ID of other speaking users in the Room.
• position: The coordinates of the speaker in the world coordinate system. The parameter is a float array of length 3. The three values represent the coordinate values of front, right, and up.

// The coordinates of the user in the world coordinate system, in the order of front, right, up
float position[3] = {100.0, 100.0, 100.0};
// Add/update user position
[self.rangeAudio updateAudioSource:@"abc" position:position];

// The coordinates of the user in the world coordinate system, in the order of front, right, up
float position[3] = {100.0, 100.0, 100.0};
// Add/update user position
[self.rangeAudio updateAudioSource:@"abc" position:position];

7 (Optional) Set Audio Reception Range

// Set the maximum range for audio reception. Sounds beyond this range will not be heard
[self.rangeAudio setAudioReceiveRange:1000];

// Set the maximum range for audio reception. Sounds beyond this range will not be heard
[self.rangeAudio setAudioReceiveRange:1000];

// Set the attenuation range interval [min, max] for 3D audio effects
ZegoReceiveRangeParam *param = [[ZegoReceiveRangeParam alloc] init];
param.min = reciveRangeMin;
param.max = reciveRangeMax;
[self.rangeAudio setAudioReceiveRangeWithParam:param];

// Set the attenuation range interval [min, max] for 3D audio effects
ZegoReceiveRangeParam *param = [[ZegoReceiveRangeParam alloc] init];
param.min = reciveRangeMin;
param.max = reciveRangeMax;
[self.rangeAudio setAudioReceiveRangeWithParam:param];

8 (Optional) Implement 3D Audio Effects

[self.rangeAudio enableSpatializer:true];

[self.rangeAudio enableSpatializer:true];

// Enable 3D audio effects, this step is a prerequisite
[self.rangeAudio enableSpatializer:YES];

// Set the position of the local player
// Media Player
// 1. Create a media player
ZegoMediaPlayer *mediaPlayer = [[ZegoExpressEngine sharedEngine] createMediaPlayer];
// 2. Set the position of the media player in the world coordinate system, in the order of front, right, up
float mediaPlayerPosition[3] = {0, 0, 0};
[mediaPlayer updatePosition:mediaPlayerPosition];
// 3. Use the media player to load media resources
ZegoMediaPlayerResource *resource = [[ZegoMediaPlayerResource alloc] init];
resource.loadType = ZegoMultimediaLoadTypeFilePath;
resource.filePath = @"path";
[mediaPlayer loadResourceWithConfig:resource callback:^(int errorCode) {
    if (errorCode == 0)
        [mediaPlayer start];
}];

// Audio Effect Player
// 1. Create an audio effect player
self.audioEffectPlayer = [[ZegoExpressEngine sharedEngine] createAudioEffectPlayer];
// 2. Start playing audio effect resources
unsigned int effectSoundID = 1;
NSString *path = @"path";
[self.audioEffectPlayer start:effectSoundID path:path config:nil];
// 3. After receiving the [audioEffectPlayer] callback status as ZegoAudioEffectPlayState.Playing
//    Set the position of the audio effect player in the world coordinate system, in the order of front, right, up
float audioEffectPlayerposition[3] = {0, 0, 0};
[self.audioEffectPlayer updatePosition:effectSoundID position:audioEffectPlayerposition];

// Enable 3D audio effects, this step is a prerequisite
[self.rangeAudio enableSpatializer:YES];

// Set the position of the local player
// Media Player
// 1. Create a media player
ZegoMediaPlayer *mediaPlayer = [[ZegoExpressEngine sharedEngine] createMediaPlayer];
// 2. Set the position of the media player in the world coordinate system, in the order of front, right, up
float mediaPlayerPosition[3] = {0, 0, 0};
[mediaPlayer updatePosition:mediaPlayerPosition];
// 3. Use the media player to load media resources
ZegoMediaPlayerResource *resource = [[ZegoMediaPlayerResource alloc] init];
resource.loadType = ZegoMultimediaLoadTypeFilePath;
resource.filePath = @"path";
[mediaPlayer loadResourceWithConfig:resource callback:^(int errorCode) {
    if (errorCode == 0)
        [mediaPlayer start];
}];

// Audio Effect Player
// 1. Create an audio effect player
self.audioEffectPlayer = [[ZegoExpressEngine sharedEngine] createAudioEffectPlayer];
// 2. Start playing audio effect resources
unsigned int effectSoundID = 1;
NSString *path = @"path";
[self.audioEffectPlayer start:effectSoundID path:path config:nil];
// 3. After receiving the [audioEffectPlayer] callback status as ZegoAudioEffectPlayState.Playing
//    Set the position of the audio effect player in the world coordinate system, in the order of front, right, up
float audioEffectPlayerposition[3] = {0, 0, 0};
[self.audioEffectPlayer updatePosition:effectSoundID position:audioEffectPlayerposition];

9 Enable Microphone and Speaker

After successfully logging into the Room:

• Call the enableMicrophone interface to set whether to enable the microphone. When enable is true, it means enabled. At this time, the SDK will automatically use the main channel to publish audio stream. When false, it means disabled. (Can be enabled or disabled at any time)

  Developers can listen to the microphoneStateUpdate event callback to get the updated microphone state.

• Call the enableSpeaker interface to set whether to enable the speaker. When enable is true, it means enabled. At this time, the audio stream in the Room will be automatically played. When false, it means disabled. (Can be enabled or disabled at any time)

// Enable microphone
[self.rangeAudio enableMicrophone:true];
// Enable speaker
[self.rangeAudio enableSpeaker:true];

// Enable microphone
[self.rangeAudio enableMicrophone:true];
// Enable speaker
[self.rangeAudio enableSpeaker:true];

10 (Optional) Join Team, Set Voice Mode

[self.rangeAudio setTeamID:@"123"];

[self.rangeAudio setTeamID:@"123"];

[self.rangeAudio setRangeAudioMode:ZegoRangeAudioModeWorld];

[self.rangeAudio setRangeAudioMode:ZegoRangeAudioModeWorld];

[self.rangeAudio setRangeAudioCustomMode:ZegoRangeAudioSpeakModeAll listenMode:ZegoRangeAudioListenModeAll];

[self.rangeAudio setRangeAudioCustomMode:ZegoRangeAudioSpeakModeAll listenMode:ZegoRangeAudioListenModeAll];

11 Destroy Range Voice Module

When the range voice module is no longer in use, call the destroyRangeAudio interface to destroy it and release the resources occupied by the range voice module.

[[ZegoExpressEngine sharedEngine] destroyRangeAudio:rangeAudio];

[[ZegoExpressEngine sharedEngine] destroyRangeAudio:rangeAudio];

12 Leave Room

Call the logoutRoom interface to leave the Room. After leaving, the microphone and speaker will be automatically turned off (i.e., you cannot send your own audio and cannot hear other people's voices), and the speaker information list will be cleared.

// Leave the Room
[[ZegoExpressEngine sharedEngine] logoutRoom:@"room1"];

// Leave the Room
[[ZegoExpressEngine sharedEngine] logoutRoom:@"room1"];

FAQ

1. How many streams can be played simultaneously within the listening range?

To ensure voice clarity, when more than 20 people nearby are speaking, only the voices of the 20 speakers closest to you can be heard. If there are more than 20 people and the distance is the same, the order is determined by the order in which each userID is first passed when calling the updateAudioSource interface.

2. Does the "range" in range voice refer to the listening range or the speaking range?

The "range" in range voice refers to the listening range.

3. Do team members have 3D audio effects when communicating through the microphone?

The voice within the team has the effect of ordinary communication. There are no 3D audio effects for now.

4. If I am already calling the publishing stream interface, will there be a conflict when I need to use range voice?

Range voice currently uses the main channel to send audio. If the customer has already used the main channel, there will be a conflict.