Set the voice hearing range

Introduction

Basic concepts

• Voice reception range: The range within which the listener can hear.
• Position: The local position in the world coordinate system.
• Listener: The user who receives sound in a room.
• Speaker: The user who speaks in the room.

Features

Starting from the ZEGOCLOUD SDK 2.11.0 (Express SDK), we support the in-game range voice service, which includes range voice room, 3D sound effects, and voice mode. This service is developed for games similar to PUBG and Metaverse game world scenarios and has the following core capabilities:

• It provides Team only and Everyone voice modes unique to games like PUBG. The Team only voice mode allows you to change teams before and after the game starts. You don't have to worry about stream grouping, stream publishing, and stream playing.

• It provides 3D sound effect, the volume level of the sound source attenuates as the distance to the sound source increases, making the scenes more realistic.

Range voice room

Listeners in the room are limited by the voice reception range. If the distance between the speaker and the listener exceeds this range, the sound cannot be heard. To ensure the clarity of speech, when more than 20 players speak nearby, only the 20 nearest voices can be heard.

If the maximum voice reception range is set as R and the distance between the speaker and the listener is r, then:

• When r < R: Indicates that the speaker is within the normal range and the listener can hear the speaker.

• When r > R: Indicates the speaker exceeds the maximum range, and the listener cannot hear the speaker.

Voice mode

When you enter a range voice room, you can choose from two voice modes:

• Everyone: In this mode, listeners in the room can hear each other only if they are all in the Everyone voice mode and within a certain distance.

• Team only: In this mode, listeners in the same team can hear each other regardless of how far apart they are or what voice modes they use.

3D sound effect

The 3D sound effect provides a sense of space and the volume level of the sound source changes as the distance of the sound source.

Prerequisites

Before you implement the range voice feature, make sure you complete the following steps:

• ZEGO Express SDK has been integrated into the project to implement basic real-time audio and video functions. For details, please refer to Quick start .
• A project has been created in ZEGOCLOUD Console and applied for a valid AppID and AppSign. For details, please refer to Console - Project Information .

Notes

If you have implemented the real-time audio and video features, pay attention to the following:

• Because the range voice service is developed based on the stream publishing and playing API of the ZegoExpressEngine, therefore, you don't need to pay attention to the concept of stream publishing and playing when using it. Instead, publishing an audio stream means turn on the microphone, playing an audio stream means enable the loudspeaker.

• To ensure the best implementation effects, we recommend you don't use the startPublishingStream and startPlayingStream methods for stream publishing/playing when using the range voice service.

• Stream publishing/playing related callbacks (onPublisherStateUpdate, onPlayerStateUpdate, onPublisherQualityUpdate, and onPlayerQualityUpdate) are no longer take effects in this range voice service.

Create a rangeAudio instance

To create a singleton instance of the rangeAudio module, call the createRangeAudio method.

ZegoRangeAudio *rangAudio = [[ZegoExpressEngine sharedEngine] createRangeAudio];
if (rangAudio == nil) {
    printf("Failed to create the instance of the range voice module.");
}

Listen for and handle the event callbacks related to range voice

To receive callbacks related to the range voice, do the following:

1. Call the setEventHandler method to set up the event handler for the microphone.
2. Listen for the rangeAudio callback to receive notifications when the microphone status changes.

/// Set the event handler for range voice.
[rangeAudio setEventHandler:self];
···

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

Log in to a range voice room

To log in to a range voice room, do the following:

1. Create a ZegoUser with a unique user ID and username.
2. Call the loginRoom method with the following parameters:

• A unique room ID as the roomID parameter
• The ZegoUser object created in the previous step as the user parameter

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

// Log in to a room.
[[ZegoExpressEngine sharedEngine] loginRoom:@"room1" user:user];

After you have successfully logged in to the room, if the app exits unexpectedly, you need to call the logoutRoom method to exit the room after restarting the app, and then call the loginRoom method to log in to the room again.

Initialization

1. Set/update the local position

To set or update the local position, call the updateSelfPosition method.

// Local position (forward, right and up) in the world coordinate system. The three values represent the forward, right, and up coordinates in sequence.
float position[3] = {100.0, 100.0, 100.0};
// Forward vector in the local coordinate system.
float axisForward[3] = {1.0,0.0,0.0};
// Right vector in the local coordinate system.
float axisRight[3] = {0.0,1.0,0.0};
// Up vector in the local coordinate system.
float axisUp[3] = {0.0,0.0,1.0};

// Update the local position.
[self.rangeAudio updateSelfPosition: position axisForward: axisForward axisRight: axisRight axisUp: axisUp];

2. Optional: Set the voice reception range

To set the maximum voice reception range, call the setAudioReceiveRange method. After this range is set and the 3D sound effect is enabled, the volume level of the sound source attenuates as the distance to the sound source increases. If the unit distance exceeds the range, the volume level will attenuate to almost zero.

• This voice reception range and 3D sound effect don't take effects in the Team only voice mode.

[self.rangeAudio setAudioReceiveRange:1000];

3. Optional: Enable/disable the 3D sound effect

To enable the 3D sound effect, call the enableSpatializer method, and set the enable to true. After this is enabled, the 3D sound effect works outside the team. To disable it, set the enable to false. (This feature can be enabled/disabled at any time)

[self.rangeAudio enableSpatializer:true];

Set/Update the sound source position

To set or update the sound source position after successful room entry, call the updateAudioSource method.

• userID: The ID of other sound sources in the range voice room.
• position: The sound source position in the world coordinate system, which is an array of 3-bit floating-point numbers. The three values represent the forward, right, and up coordinates in sequence.

// The sound source position in the world coordinate system. The three values represent the forward, right, and up coordinates in sequence.
float position[3] = {100.0, 100.0, 100.0};
// Update the sound source position.
[self.rangeAudio updateAudioSource:@"abc" position:position];

Turn on/off the microphone

To turn on/off the microphone, call the enableMicrophone method, and set the enable to true. After this is enabled, the SDK automatically publishes audio streams via the main channel. To disable it, set the enable to false. (This feature can be turned on/off at any time)

You can listen for the rangeAudio callback to receive notifications when the microphone status changes.

[self.rangeAudio enableMicrophone:true];

Enable/Disable the loudspeaker

To enable/disable the loudspeaker, call the enableSpeaker method, and set the enable to true. After this is enabled, the SDK automatically plays audio streams in the range voice room. To disable it, set the enable to false. (This feature can be turned on/off at any time)

[self.rangeAudio enableSpeaker:true];

Optional: Set team only voice mode

1. Set teamID

To join the team you want, call the setTeamID method with the team ID. (You can change the ID at any time).

After you join a team, you can communicate with other teammates without the limitation of voice reception range and 3D sound effects.

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

2. Set the voice mode

To set the voice mode, call the setRangeAudioMode method, and set the mode parameter accordingly:

• Everyone mode: set the mode parameter to ZEGO_RANGE_AUDIO_MODE_ALL_WORLD.
• Team only mode: set the mode parameter to ZEGO_RANGE_AUDIO_MODE_ONLY_TEAM.

You can modify the voice mode at any time.

[self.rangeAudio setRangeAudioMode:ZegoRangeAudioModeWorld];

In different voice modes, the specific voice reachability varies.

• The table below lists the possible cases of sound reachability for player B in different voice modes if player A selects the Everyone mode:

• The table below lists the possible cases of sound reachability for player B in different voice modes if player A selects the Team only mode:

Destroy the ZegoRangeAudio instance

To destroy the ZegoRangeAudio instance and release the resources it occupies, call the destroyRangeAudio method.

[[ZegoExpressEngine sharedEngine] destroyRangeAudio:rangeAudio];

Log out from a range voice room

To log out from a room, call the logoutRoom method. After the logout, the microphone and loudspeaker will be disabled automatically (which means you can't send your audio streams or receive audio streams from others), and the speaker list will also be cleared.

// Log out from a room.
[[ZegoExpressEngine sharedEngine] logoutRoom:@"room1"];

FAQ

1. How many streams can I play simultaneously within the voice reception range?

To ensure clarity of voice, when more than 20 people speak, only the 20 nearest voices can be heard. When more than 20 voices with the same distance, the voice you can hear will be decided by the order when calling the updateAudioSource method.

2. What does the "range" refer to in the range voice service?

It refers to the voice reception range.

3. Is 3D sound effect work in the team only voice mode?

The 3D sound effect doesn't work in team only voice mode.

4. Is there a conflict in using range voice service when calling the method for stream publishing?

Yes. Because the range voice service uses the main channel for audio stream sending, there is a conflict if you are using the main channel for stream publishing.