- Documentation
- Video Call
- Upgrade using advanced features
- Distincitve features
- Set the voice hearing range
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 effect, 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.
The following figure only uses the Everyone voice mode as an example.
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 .
Browser compatibility
- To check the browser's range voice support, see ZEGO Express Web SDK browser compatibility.
- To check the browser's 3D sound effect support, see the table below:
Browser Compatibility Chrome14 or laterEdge79 or laterFirefox53 or laterOpera15 or laterIENot supportedSafari14.1 or laterWebView Android55 or laterFirefox for Android53 or laterOpera Android42 or laterSafari on iOS14.5 or laterSamsung Internet6.0 or later
Notes
When using the range voice feature, pay attention to the following precautions.
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
andstartPlayingStream
methods for stream publishing/playing when using the range voice service.
Stream publishing/playing related callbacks (
publisherStateUpdate
andplayerStateUpdate
methods are no longer take effects in this range voice service.After you listen for the
roomStreamUpdate
andstreamExtraInfoUpdate
callbacks by calling theon
method, you would better not to cancel the callback by calling theoff
method.
Listen for and handle the event callbacks related to range voice
After you created a ZegoExpressEngine
instance, you can call the on
method to listen for and handle various event callbacks as needed.
rangeAudio.on("microphoneStateUpdate", (state, errorCode, extendedData) => {
if (state === 0) {
// Turn off the microphone.
} else if(state === 1) {
// Turning on the microphone.
} else if(state === 2) {
// Turn on the microphone to send audio.
}
})
Check your browser's automatic sound playback support
To check whether the browser supports playing the audio automatically, call the isAudioContextRunning
method. If it doesn't support (the isSupport
is false
), you can guide the user to
set up a click event by clicking the DOM element, and call the resumeAudioContext
method to enable the automatic sound playback feature.
<button onclick="enableAutoPlay()">Click me</button>
const isSupport = rangeAudio.isAudioContextRunning();
async function enableAutoPlay() {
// [result] indicates whether it is enabled successfully.
const result = await rangeAudio.resumeAudioContext();
}
Log in to a range voice room
1. Obtain the login token
When logging in to a room, you need to pass in a login token for user authentication. To obtain the login token, see User privilege control.
2. Log in
To log in to a room, call the loginRoom
with the following parameters:
- A unique room ID as the
roomID
parameter - The login token you obtained in the previous step
as the
token
parameter - The user ID and user name as the
roomID
anduserName
parameter - Optional: Pass the corresponding object to the
config
parameter based on the actual situation.
- To receive event callbacks after logging in to a room, you need to subscribe to event callbacks before the room login.
- You need to implement your own business logic to set the values of
roomID
,userID
, anduserName
. - Each
roomID
anduserID
must be globally unique within the scope of the AppID. We recommend you set theuserID
to a meaningful value. You can associateuserID
with the account system of your application.
// Log in to a room. It returns `true` if the login is successful.
// The roomUserUpdate callback is disabled by default. To receive this callback, you must set the `userUpdate` property to `true` when logging in to a room.
const result = await zg.loginRoom(roomID, token, {userID, userName});
Initialization
1. Set/update the local position
To set or update the local position, call the updateSelfPosition
method.
If you do not set the local position before enabling the loudspeaker (
enableSpeaker
), you can't hear anyone other than your team.The three coordinates of the local coordinates can be obtained using the angle rotation matrix of the third-party engine.
Parameter |
Description |
position |
Local position (forward, right and up) 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. |
axisForward |
Forward vector in the local coordinate system, which is an array of 3-bit floating-point numbers. The three values represent the forward, right, and up coordinates in sequence. |
axisRight |
Right vector in the local coordinate system, which is an array of 3-bit floating-point numbers. The three values represent the forward, right, and up coordinates in sequence. |
axisUp |
Up vector in the local coordinate system, which is an array of 3-bit floating-point numbers. The three values represent the forward, right, and up coordinates in sequence. |
const position = [0,0,0];
const axisForward = [1,0,0];
const axisRight = [0,1,0];
const axisUp = [0,0,1];
rangeAudio.updateSelfPosition(position, axisForward, axisRight, 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.
If the voice reception range is not set, the distance is not limited when receiving sound sources, that is, the user can hear everyone in the range voice room.
rangeAudio.setAudioReceiveRange(100);
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)
This feature only works for people outside the team.
// It is enabled when the [enable] is [true]. It is disabled when the [enable] is [false] (by default).
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.
const userID = "other";
const position = [1,0,0];
rangeAudio.updateAudioSource(userID, 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 microphoneStateUpdate
callback to receive notifications when the microphone status changes.
rangeAudio.on("microphoneStateUpdate", (state, errorCode, extendedData) => {
if (state === 0) {
// Turn off the mircophone.
} else if(state === 1) {
// Turning on the microphone.
} else if(state === 2) {
// Turned on the microphone to send audio.
}
})
// It is enabled when [enable] is [true]. It is disabled when [enable] is [false].
rangeAudio.enableMicrophone(enable);
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)
When the number of played streams exceeds the upper limit (20 streams), the system first plays the audio streams from members in the team (when team only voice mode is set), and then plays the audio streams that are closest to the local player.
// It is enabled when [enable] is [true]. It is disabled when [enable] is [false].
rangeAudio.enableSpeaker(enable);
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.
// Pass a string into the [teamID] parameter indicates you are join to the team.
rangeAudio.setRangeAudioTeamID("teamID");
// It indicates exits the team when you don't pass value to the [teamID] or pass [undefined] into it.
rangeAudio.setRangeAudioTeamID();
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 to0
. - Team only mode: set the
mode
parameter to1
.
You can modify the voice mode at any time.
Voice mode | Parameter | Feature |
---|---|---|
Everyone |
0 |
Everyone within a certain range can hear the speaker as he or she chats with his or her teammates. |
Team only |
1 |
Only teammates can hear the speaker. |
// Set the parameter to 0 or 1.
// 0 is the everyone mode. In this mode, everyone within a certain range can hear the speaker as he or she chats with his or her teammates.
// 1 is the team only mode. In this mode, only teammates can hear the speaker.
rangeAudio.setRangeAudioMode(1);
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:
In the same team | Within the range | Voice mode | Whether A and B can hear each other |
---|---|---|---|
Yes |
Yes |
Everyone (World) |
Yes |
Team only (Team) |
Yes |
||
No |
Everyone (World) |
Yes |
|
Team only (Team) |
Yes |
||
No |
Yes |
Everyone (World) |
Yes |
Team only (Team) |
No |
||
No |
Everyone (World) |
No |
|
Team only (Team) |
No |
- 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:
In the same team | Within the range | Voice mode | Whether A and B can hear each other |
---|---|---|---|
Yes |
Yes |
Everyone (World) |
Yes |
Team only (Team) |
Yes |
||
No |
Everyone (World) |
Yes |
|
Team only (Team) |
Yes |
||
No |
Yes |
Everyone (World) |
No |
Team only (Team) |
No |
||
No |
Everyone (World) |
No |
|
Team only (Team) |
No |
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.
zg.logoutRoom(roomID)
FAQ
- 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.
- What does the "range" refer to in the range voice service?
It refers to the voice reception range.
- Is 3D sound effect work in the team only voice mode?
The 3D sound effect doesn't work in team only voice mode.
- 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.