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.

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:

• A project has been created in ZEGOCLOUD Console and applied for a valid AppID and AppSign. For details, please refer to Console - How to view project information .
• ZEGO Express SDK has been integrated into the project to implement basic real-time audio and video functions. For details, please refer to Integrate the SDK and Implement a basic video call.

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
  Chrome	14 or later
  Edge	79 or later
  Firefox	53 or later
  Opera	15 or later
  IE	Not supported
  Safari	14.1 or later
  WebView Android	55 or later
  Firefox for Android	53 or later
  Opera Android	42 or later
  Safari on iOS	14.5 or later
  Samsung Internet	6.0 or later

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 (publisherStateUpdate and playerStateUpdate methods are no longer take effects in this range voice service.

• After you listen for the roomStreamUpdate and streamExtraInfoUpdate callbacks by calling the on method, you would better not to cancel the callback by calling the off 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 and userName parameter
• Optional: Pass the corresponding object to the config parameter based on the actual situation.

// 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.

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.

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)

// 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)

// 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 to 0.
• Team only mode: set the mode parameter to 1.

You can modify the voice mode at any time.

// 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:

• 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:

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

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.