Video Call
  • iOS
  • Android
  • Web : JavaScript
  • Flutter
  • React Native
  • Electron
  • Unity3D
  • Cocos Creator
  • Windows
  • macOS
  • Linux
  • Overview
  • Develop your app
    • Integrate the SDK
    • Implement a basic video call
    • Enhance basic feature
      • Use Tokens for authentication
      • Check the room connection status
      • Set up common video config
      • Set up common audio config
  • Best practices
    • Implement a video call for multiple users
  • Upgrade using advanced features
    • Advanced features
      • Configure the video
        • Improve your appearance in the video
        • Configure video codec
      • Improve video quality
        • Visualize the sound level
        • Monitor streaming quality
      • Message signaling
        • Broadcast real-time messages to a room
        • Quotas and limits
      • Share the screen
      • Mix the video streams
      • Publish multiple video streams
      • Replace the audio/video track
    • Distincitve features
      • Join multiple rooms
      • Customize the video and audio
      • Set the voice hearing range
      • Render the audio and video
      • Autoplay policy
      • Restrictions on playing multiple videos simultaneously in Safari
      • Play streams via URL
      • Browser compatibility
      • Audio mixing
      • Vitrual Background and Blur
    • Implement a video call using frameworks
      • Implement a video call using Vue
      • Implement a video call using Angular
      • Implement a video call using React
  • Resources & Reference
    • SDK
    • Sample codes
    • API reference
      • Client APIs
      • Server APIs
    • Debugging
      • Error codes
      • Logging/Version number
    • FAQs
    • Key concepts
  • Documentation
  • Video Call
  • Upgrade using advanced features
  • Distincitve features
  • Set the voice hearing range

Set the voice hearing range

Last updated:2023-08-31 15:50

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

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 and startPlayingStream methods for stream publishing/playing when using the range voice service.

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.
  • 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, and userName.
  • Each roomID and userID must be globally unique within the scope of the AppID. We recommend you set the userID to a meaningful value. You can associate userID 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 to 0.
  • Team only mode: set the mode parameter to 1.

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

  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.

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

It refers to the voice reception range.

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

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

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

Page Directory