tencent cloud

Range Voice
Download PDF
Last updated: 2023-04-27 17:06:32
Range Voice
Last updated: 2023-04-27 17:06:32
Download PDF

Overview

In a voice chat room, a user can talk with other users within a certain distance. This feature calls the GME client API at the business layer to update the sound source position to inform the server of the local player's position. The server forwards the audio streams within the players' ranges after checking the local coordinates and audio reception range against remote coordinates and audio reception range. By default, 20 audio streams nearest a player are forwarded, and up to 10,000 players can mic on simultaneously in a room.


Use Cases

Battle royale games
GME provides the "Team only" and "Everyone" voice modes unique to battle royale games and mobile survival shooter games. The voice effect varies by selected mode as follows: 1. If the "Team only" mode is selected, the player can hear only the voice of teammates. 2. If the "Everyone" mode is selected, the player can hear the voice of teammates as well as the voice of enemies within a certain range.
Immersive virtual scenarios
In a virtual scenario like in-game concert, when the singer sings in the virtual room, the range voice feature can be used to enable the audience to talk with other players within a certain range while hearing the singer. Up to 10,000 players can turn on their mics simultaneously in a room.


Demo Effects

You can download the free demo to try out the 3D sound effect and range voice features.


Concepts

The range voice feature involves three concepts: voice mode, range for hearing the voice, and TeamID.

Voice mode

When the user enters a range voice room, the user can choose from two voice modes:
Voice Mode
Parameter
Feature
Everyone
RANGE_AUDIO_MODE_WORLD
In this mode, the player can be heard by other players within a certain range and can talk with them if they are also in this mode.
Teammates can hear each other.
Team only
RANGE_AUDIO_MODE_TEAM
Only teammates can hear each other.
Note
Teammates can talk with each other regardless of the distance and voice mode.

Range for hearing the voice


If the voice mode is set to Everyone (RANGE_AUDIO_MODE_WORLD), the range for hearing the voice will be subject to the UpdateAudioRecvRange API.
Suppose players A and B in different teams both set their voice modes to Everyone (RANGE_AUDIO_MODE_WORLD):
Player Coordinates
Range for Hearing the Voice
Voice Reachability of the Other Player
Voice Reachability of Teammates
A (0,0,0)
10 meters
The player can hear player B, as player B is within 10 meters of the player.
Teammates can talk with each other.
B (0,8,0)
5 meters
The player cannot hear player A, as player A is more than 5 meters away.
Teammates can talk with each other.
Note
For more information on the specific voice reachability of players, see Range Voice.

TeamID

To use the range voice feature, you need to call the SetRangeAudioTeamID API to set the team ID (TeamID) and then call the EnterRoom API to enter the room.
If TeamID specified during room entry is not 0, a user will enter the range voice chat room mode. If a user sets TeamID to 1 and the voice mode to RANGE_AUDIO_MODE_TEAM when entering a voice chat room, only members whose TeamID is 1 can hear the user. If the user sets the voice mode to RANGE_AUDIO_MODE_WORLD, players within a certain range as well as members whose TeamID is 1 can hear the user.
TeamID Value
Voice Mode
Range
Voice Reachability
TeamID is not 0. Suppose TeamID is 1.
RANGE_AUDIO_MODE_TEAM
10 meters
The user can talk with only members whose TeamID is 1.
RANGE_AUDIO_MODE_WORLD
10 meters
The user can talk with members whose TeamID is 1 and members in RANGE_AUDIO_MODE_WORLD voice mode within 10 meters in the same room.
If a user enters a voice chat room with TeamID set to 0, the user will enter the range voice host mode, where all members in the room (regardless of their voice mode) can hear the user.
TeamID Value
TeamID Modification Time
Range
Voice Reachability
TeamID = 0
TeamID is not 0 before room entry and is changed to 0 after room entry.
10 meters
All members in the room (regardless of their voice mode) can hear the user.
The user can talk with members whose TeamID is 0.
The user can hear members in RANGE_AUDIO_MODE_WORLD voice mode within 10 meters in the same room.
TeamID is 0 before and during room entry.
10 meters
All members in the room (regardless of their voice mode) can hear the user.
The user can talk with members whose TeamID is 0.
The user cannot hear other members in the room.

Scenarios

Battle royale game: In a battle royale game, every four players are grouped into a team, and a team ID (TeamID) needs to be set for them. A battle room can contain 100 players, i.e., 25 teams, so all those teams enter the same voice chat room. In a battle, if a player wants to communicate with a stranger within 10 meters, the player can set the range for hearing the voice to 10 meters and the voice mode to RANGE_AUDIO_MODE_WORLD and enable both the mic and speaker. If the player wants to communicate with only teammates, the player can set the voice mode to RANGE_AUDIO_MODE_TEAM.
Game concert: If a singer wants to hold a concert in a game but doesn't need to interact with players, players can enter the range voice chat room with their TeamID set to OpenID, voice mode set to RANGE_AUDIO_MODE_WORLD, and range for hearing the voice set to an appropriate value so as to talk with players nearby. The singer can set TeamID to 0 before entering the room to be heard by all members in the room without hearing other members.
Host mode: In a game such as virtual board game, the host needs to be heard by all members in the room and hear players within a certain range. In this case, the host can enter the room with TeamID set to a non-0 value and change TeamID to 0 after room entry, so as to be heard by all members in the room while hearing players within a certain range.

Prerequisites

You have activated the voice chat service. For more information, see Activating Services.
You have integrated the GME SDK, including core APIs and voice chat APIs. For more information, see Quick Integration of Native SDK, Quick Integration of SDK for Unity, and Quick Integration of SDK for Unreal Engine.
You have applied for a voice chat room for over 10,000 users: If more than 1,000 users in a room use range voice, submit a ticket for application.

Directions


Notes
Be sure to follow the flowchart to call the API.
The blue part of the flowchart shows the process of the range voice.
A range voice chat room is different from a team voice chat room in that you must select the smooth sound quality when entering the range voice chat room.
Once you enter the room, call UpdateAudioRecvRange (once at least) and call UpdateSelfPosition once per frame.

1. Set TeamID

Calling this API to set the team ID before room entry will affect the next room entry.
This API can be called to modify the team ID after room entry. The modification will take effect immediately.
TeamID will not be automatically reset to 0 upon room exit. Therefore, once you decide to call this voice mode, do so to set the TeamID before each call of EnterRoom.
When entering a room after exiting the room, call the API for setting the team ID again after the callback for successful room exit is returned.

Function prototype

ITMGContext SetRangeAudioTeamID(int teamID)
Parameter
Type
Description
teamID
int
Team ID, which is used in range voice mode only. When it is set to 0 (default), the team voice mode is used.

2. Set the voice mode

Calling this API to change the voice mode before room entry will affect the next room entry.
Calling this API to change the voice mode after room entry will directly change the current voice mode.
This parameter will not be automatically reset to MODE_WORLD upon room exit. Therefore, once you decide to call this method, do so before each call of EnterRoom.

Function prototype

ITMGRoom int SetRangeAudioMode(RANGE_AUDIO_MODE rangeAudioMode)
Parameter
Type
Description
rangeAudioMode
int
0 (MODE_WORLD): everyone; 1 (MODE_TEAM): team only.

3. Enter a voice chat room

Before entering a voice chat room by calling EnterRoom, you need to call the following two APIs: SetRangeAudioTeamID and SetRangeAudioMode.

Function prototype

ITMGContext.GetInstance(this).EnterRoom(roomId,ITMG_ROOM_TYPE_FLUENCY, authBuffer);
Choose smooth sound quality when entering the voice chat room, and monitor and process the callback for room entry.
public void OnEvent(ITMGContext.ITMG_MAIN_EVENT_TYPE type, Intent data) {
    if (ITMGContext.ITMG_MAIN_EVENT_TYPE.ITMG_MAIN_EVENT_TYPE_ENTER_ROOM == type)
        {
               // Analyze the returned data
            int nErrCode = data.getIntExtra("result" , -1);
            String strErrMsg = data.getStringExtra("error_info");

            if (nErrCode == AVError.AV_OK)
            {
                //If you receive a success response for room entry, you can proceed with your operation
                ScrollView_ShowLog("EnterRoom success");
                Log.i(TAG,"EnterRoom success!");
            }
            else
            {
                //If you fail to enter the room, you need to analyze the returned error message
                ScrollView_ShowLog("EnterRoom fail :" + strErrMsg);
                Log.i(TAG,"EnterRoom fail!");
            }  
        }
    }
Once you enter the room, call UpdateAudioRecvRange (once at least), and call UpdateSelfPosition once per frame.

4. Set the voice reception range

This method is used to set the voice reception range (subject to the game engine) and can be called only after successful room entry.
This method must be used together with UpdateSelfPosition to update the sound source position.
This method needs to be called only once to take effect, and the parameter value can be modified.

Function prototype

ITMGRoom int UpdateAudioRecvRange(int range)
Parameter
Type
Description
range
int
Maximum voice reception range in the distance unit used by the game engine.

Sample code

ITMGContext.GetInstance().GetRoom().UpdateAudioRecvRange(300);

5. Update the sound source position

The purpose of updating the sound source position is to inform the server of the local player's position. The system implements range voice by checking the local coordinates and voice reception range against the remote coordinates and voice reception range.
This API is used to update the sound source position information. It can be called only after successful room entry and needs to be called once per frame. Taking the Unity engine as an example, this API needs to be called in Update.
If range voice is enabled, the sound source position must be updated. Even if range determination is not required, this API still needs to be called once after room entry.
If you want to enable 3D sound effect at the same time, set the axisForward, axisRight, and axisUp parameters as specified in "4. Update the sound source position (for the 3D sound effect)" in Range Voice.

Function prototype

public abstract int UpdateSelfPosition(int position[3], float axisForward[3], float axisRight[3], float axisUp[3])
Parameter
Type
Description
position
int[]
Your own position (forward, right, and up) in the world coordinate system
axisForward
float[]
This parameter can be ignored in this product.
axisRight
float[]
This parameter can be ignored in this product.
axisUp
float[]
This parameter can be ignored in this product.

Range voice combined with 3D sound effects

The range voice feature controls the reachability of sound through distance. It is recommended to use with 3D sound effects if you want a more immersive experience.

Directions

If you want to use 3D sound effects while using range voice, please complete the step 1, 2, 3 and then initialize 3D engine and open 3D sound effects.


Note
The blue part of the flowchart shows the process of the 3D sound effect feature.

Prerequisites

Perform steps 1, 2, and 3 as instructed in Directions.

4. Initialize the 3D sound effect engine

This function is used to initialize the 3D sound effect engine and needs to be called after room entry. You must call this API before using the 3D sound effect, even if you want to enable only the 3D sound effect reception rather than the 3D sound effect playback.

Function prototype

public abstract int InitSpatializer(string modelPath)
Parameter
Type
Description
modelPath
string
Enter null.

5. Enable/disable the 3D sound effect

This function is used to enable or disable the 3D sound effect. You can hear the 3D sound after enabling it.

Function prototype

public abstract int EnableSpatializer(bool enable, bool applyToTeam)
Parameter
Type
Description
enable
bool
You can hear the 3D sound effect after enabling it.
applyToTeam
bool
This parameter specifies whether 3D sound effect is enabled within the team and takes effect only when enable is true.
The IsEnableSpatializer API can be used to get the 3D sound effect status.

6. Set the voice reception range (for the 3D sound effect)

This method is used to set the voice reception range (subject to the game engine) and can be called only after successful room entry.
This method must be used together with UpdateSelfPosition to update the sound source position.
This method needs to be called only once to take effect.
In the 3D sound effect, the sound will begin to attenuate to almost zero as the distance to the sound source exceeds a specified threshold (range/10).
For more information on the relationship between the distance and sound attenuation, see the appendix.

Function prototype

ITMGRoom int UpdateAudioRecvRange(int range)
Parameter
Type
Description
range
int
Maximum voice reception range in the distance unit used by the game engine.

Sample code

ITMGContext.GetInstance().GetRoom().UpdateAudioRecvRange(300);

7. Update the sound source position (for the 3D sound effect)

The purpose of updating the sound source position is to inform the server of the local player's position. The system implements range voice by checking the local coordinates and voice reception range against the remote coordinates and voice reception range.

This API is used to update the sound source position information. It can be called only after successful room entry and needs to be called once per frame. Taking the Unity engine as an example, this API needs to be called in Update.
Directly copy and call the sample code to use this feature.

Function prototype

public abstract int UpdateSelfPosition(int position[3], float axisForward[3], float axisRight[3], float axisUp[3])
Parameter
Type
Description
position
int[]
Local position (forward, right, and up) in the world coordinate system
axisForward
float[]
Forward vector in the local coordinate system
axisRight
float[]
Right vector in the local coordinate system
axisUp
float[]
Up vector in the local coordinate system

Sample code

Unreal
FVector cameraLocation = UGameplayStatics::GetPlayerCameraManager(GetWorld(), 0)->GetCameraLocation();
FRotator cameraRotation = UGameplayStatics::GetPlayerCameraManager(GetWorld(), 0)->GetCameraRotation();
int position[] = { 
    (int)cameraLocation.X,
    (int)cameraLocation.Y,
    (int)cameraLocation.Z };
FMatrix matrix = ((FRotationMatrix)cameraRotation);
float forward[] = { 
    matrix.GetColumn(0).X,
    matrix.GetColumn(1).X,
    matrix.GetColumn(2).X };
float right[] = { 
    matrix.GetColumn(0).Y,
    matrix.GetColumn(1).Y,
    matrix.GetColumn(2).Y };
float up[] = { 
    matrix.GetColumn(0).Z,
    matrix.GetColumn(1).Z,
    matrix.GetColumn(2).Z};
ITMGContextGetInstance()->GetRoom()->UpdateSelfPosition(position, forward, right, up);
Unity
Transform selftrans = currentPlayer.gameObject.transform;
Matrix4x4 matrix = Matrix4x4.TRS(Vector3.zero, selftrans.rotation, Vector3.one);
int[] position = new int[3] { 
    selftrans.position.z,
    selftrans.position.x,
    selftrans.position.y};
float[] axisForward = new float[3] { 
    matrix.m22,
    matrix.m02,
    matrix.m12 };
float[] axisRight = new float[3] { 
    matrix.m20,
    matrix.m00,
    matrix.m10 };
float[] axisUp = new float[3] { 
    matrix.m21,
    matrix.m01,
    matrix.m11 };
ITMGContext.GetInstance().GetRoom().UpdateSelfPosition(position, axisForward, axisRight, axisUp);

Disabling the 3D sound effect for the host

If a player in the scenario uses the range voice host mode, the player's voice needs to be heard by all players in the room. In this case, you need to add the host to the 3D sound effect blocklist of all the other players as instructed in 3D Sound Effect to prevent the host's voice from being attenuated by the 3D sound effect feature.
Below are the API call sequences of different roles:
API Call Sequence of the Host
API Call Sequence of a Listener



Appendix

Voice modes

Player voice reachability in different voice modes is as follows:
The table below lists the possible cases of voice reachability for player B in different voice modes if player A selects the "Everyone" mode:
In the Same Team
Within the Range
Voice Mode
Can A and B Hear Each Other
Same team
Yes
MODE_WORLD
Yes
MODE_TEAM
Yes
No
MODE_WORLD
Yes
MODE_TEAM
Yes
Different team
Yes
MODE_WORLD
Yes
MODE_TEAM
No
No
MODE_WORLD
No
MODE_TEAM
No
The table below lists the possible cases of voice reachability for player B in different voice modes if player A selects the "Team only" mode:
In the Same Team
Within the Range
Voice Mode
Can A and B Hear Each Other
Same team
Yes
MODE_WORLD
Yes
MODE_TEAM
Yes
No
MODE_WORLD
Yes
MODE_TEAM
Yes
Different team
Yes
MODE_WORLD
No
MODE_TEAM
No
No
MODE_WORLD
No
MODE_TEAM
No

The relationship between distance and sound attenuation

In the 3D sound effect, the sound will begin to attenuate to almost zero as the distance to the sound source exceeds a specified threshold (range/10).
Distance (Unit in the Engine)
Attenuation Coefficient
0 < N < range/10
1.0 (no attenuation)
N ≥ range/10
Range/10/N




Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback