Range Audio

Function Overview

Concept Explanation

• Range: The range within which a listener receives audio.
• Orientation: Refers to the listener's position and facing direction in the game world coordinates. For details, refer to 5 Set the listener's current position.
• Listener: A user in the room who receives audio.
• Speaker: A user in the room who sends audio.

Function Description

Since version 2.11.0, ZEGO Express SDK has added a game voice module, mainly including: range audio, 3D audio effects, and team voice.

Function	Description
Range Audio	Listeners in the room have a range limit for receiving audio. If a speaker is beyond this range from the listener, they cannot hear the sound. To ensure voice clarity, when more than 20 people nearby are speaking, only the sounds of the 20 speakers closest to the listener can be heard. If the maximum range for audio reception is set to R, and the distance between the speaker and the listener is r, then: When r < R, it means the speaker is within the normal range, and the listener can hear the sound. When r ≥ R, it means the speaker is beyond the maximum range, and the listener cannot hear the sound. The above diagram only shows the example when the range audio mode is "World". For more sound reachability under different mode combinations, please refer to Set Common Voice Mode.
3D Audio Effects	Sound has 3D spatial perception and attenuates with distance.
Common Voice Mode	Players can choose to join a team and freely switch between "World", "Team Only", and "Secret Team" voice modes in the room. World: Players can talk with other players in the world range, and can also talk with teammates. Team Only: Players can only talk with teammates. Secret Team: Players can talk with teammates and can only hear voices from other players in the world range. Note Communication between teammates is not affected by "range" and "3D audio effects". For details, please refer to Set Common Voice Mode. If you want to customize voice send/receive capabilities, please refer to Set Custom Voice Mode.

Applicable Scenarios

The game voice feature is suitable for battle royale games and metaverse scenarios.

In battle royale games, team voice provides team formation functionality. Teams can be changed before and after the game starts. Developers don't need to worry about stream grouping and stream publishing/playing implementation, and can directly implement team voice functionality.

In battle royale games and metaverse scenarios, 3D audio effects capability is provided. When listening to speaker audio effects, there is a sense of direction and distance, making the scene feel more realistic.

Download Sample Source Code

Please refer to Download Sample Source Code to get the source code.

For related source code, please check the files in the "src/Examples/Others/RangeAudio" directory.

Prerequisites

Before implementing range audio, ensure that:

• You have created a project in the ZEGOCLOUD Console and applied for a valid AppID and Server address. For details, refer to Console - Project Information.
• You have integrated ZEGO Express SDK into your project and implemented basic audio/video stream publishing and playing functionality. For details, refer to Quick Start - Integration and Quick Start - Implementation.

And ensure the development environment meets the following requirements:

• Prepare a Windows or macOS computer connected to the internet.
• Chrome browser version 56 or above is recommended. For browser compatibility information, please refer to 7 Browser Compatibility.

Important Notes

If you are already using the real-time audio/video features of ZEGO Express SDK, please note the following:

• Since the range audio module is implemented based on the stream publishing and playing interfaces of ZegoExpressEngine, you don't need to focus on the concept of stream publishing and playing when using it. In range audio scenarios, the concept of publishing audio stream changes to "enable microphone", and the concept of playing audio stream changes to "enable speaker". It's recommended not to use the startPublishingStream and startPlayingStream interfaces for stream publishing and playing operations while integrating the range audio feature, to avoid effect conflicts.
• Related callbacks for stream publishing and playing in the range audio module (publisherStateUpdate and playerStateUpdate) will no longer take effect.
• After calling ZegoExpressEngine's on interface in the range audio module to register roomStreamUpdate and streamExtraInfoUpdate event callbacks, please do not call ZegoExpressEngine's off interface to unregister all event callbacks when integrating the range audio feature.

Usage Steps

The above diagram only shows the core steps and interfaces for implementing game voice functionality. Developers can refer to the detailed introduction in the following documentation to implement other related interfaces as needed.

1 Import SDK

1. Run the npm i zego-express-engine-webrtc command to install dependencies.

2. Import the SDK in the "index.js" file.

import { ZegoExpressEngine } from 'zego-express-engine-webrtc'

import { ZegoExpressEngine } from 'zego-express-engine-webrtc'

2 Create Engine

1. Create engine

Create a ZegoExpressEngine engine instance, pass the applied AppID to the appID parameter, and pass the access server address to the server parameter.

Initialize the ZegoExpressEngine instance zg and the range audio feature instance rangeAudio.

const zg = new ZegoExpressEngine(appID, server);
const rangeAudio = zg.createRangeAudioInstance();

const zg = new ZegoExpressEngine(appID, server);
const rangeAudio = zg.createRangeAudioInstance();

2. Listen to range audio event callbacks

If you need to register callbacks, developers can implement certain methods in ZegoRangeAudioEvent as needed, and call the on interface through the range audio instance rangeAudio to set callbacks.

rangeAudio.on("microphoneStateUpdate", (state, errorCode, extendedData) => {
  if (state === 0) {
    // Microphone sound off
  } else if(state === 1) {
    // Enabling microphone
  } else if(state === 2) {
    // Microphone on and sending sound
  }
})

rangeAudio.on("microphoneStateUpdate", (state, errorCode, extendedData) => {
  if (state === 0) {
    // Microphone sound off
  } else if(state === 1) {
    // Enabling microphone
  } else if(state === 2) {
    // Microphone on and sending sound
  }
})

3 Support browsers that don't allow autoplay sound

Use the isAudioContextRunning interface to check if the browser supports autoplay sound. If isSupport is false, you can guide the user to click a DOM element on the interface to trigger a click event, and call the resumeAudioContext interface in the click event to start autoplay.

<button onclick="enableAutoPlay()">Click me</button>

<button onclick="enableAutoPlay()">Click me</button>

const isSupport = rangeAudio.isAudioContextRunning();

async function enableAutoPlay() {
    // result indicates whether enable was successful
    const result = await rangeAudio.resumeAudioContext();
}

const isSupport = rangeAudio.isAudioContextRunning();

async function enableAutoPlay() {
    // result indicates whether enable was successful
    const result = await rangeAudio.resumeAudioContext();
}

4 Login Room

1. Get Login Token

Logging into a room requires a Token for identity verification. For how to obtain it, please refer to User Permission Control. For quick debugging, you can use the console to generate a temporary Token.

2. Login Room

Call the loginRoom interface through the ZegoExpressEngine instance zg, pass in the room ID parameter roomID, token, and user parameter user, and pass in the config parameter as needed to login to the room.

// Login room, returns true if successful
const result = await zg.loginRoom(roomID, token, {userID, userName});

// Login room, returns true if successful
const result = await zg.loginRoom(roomID, token, {userID, userName});

5 Set the listener's current position

Call the updateSelfPosition interface to add your own orientation, or update your position and facing direction in the world coordinate system when your orientation changes.

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

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

6 Add or update speaker position information

After successfully logging into the room, call the updateAudioSource interface to update the speaker position.

• userID: The ID of another speaking user in the room.
• position: The speaker's coordinates in the world coordinate system. The parameter is a number array of length 3, with the three values representing the coordinate values of forward, right, and up respectively.

const userID = "other";
const position = [1,0,0];
rangeAudio.updateAudioSource(userID, position);

const userID = "other";
const position = [1,0,0];
rangeAudio.updateAudioSource(userID, position);

7 (Optional) Set audio receive range

rangeAudio.setAudioReceiveRange(100);

rangeAudio.setAudioReceiveRange(100);

8 (Optional) Implement 3D audio effects

// enable is true to enable, false to disable. Default is disabled.
rangeAudio.enableSpatializer(true);

// enable is true to enable, false to disable. Default is disabled.
rangeAudio.enableSpatializer(true);

9 Enable microphone and speaker

After successfully logging into the room:

• Call the enableMicrophone interface to set whether to enable the microphone. When enable is true, it means enabled; when it's false, it means disabled. (Can be enabled or disabled at any time)

  Developers can listen to the microphoneStateUpdate event callback to get the updated microphone status.

• Call the enableSpeaker interface to set whether to enable the speaker. When enable is true, it means starting to play stream and play audio; when it's "false", it means stopping playing stream and playing audio. (Can be enabled or disabled at any time)

rangeAudio.on("microphoneStateUpdate", (state, errorCode, extendedData) => {
  if (state === 0) {
    // Microphone sound off
  } else if(state === 1) {
    // Enabling microphone
  } else if(state === 2) {
    // Microphone on and sending sound
  }
})
// Enable microphone, enable is true to enable, false to disable.
rangeAudio.enableMicrophone(enable);

// Enable speaker, enable is true to enable, false to disable.
rangeAudio.enableSpeaker(enable);

rangeAudio.on("microphoneStateUpdate", (state, errorCode, extendedData) => {
  if (state === 0) {
    // Microphone sound off
  } else if(state === 1) {
    // Enabling microphone
  } else if(state === 2) {
    // Microphone on and sending sound
  }
})
// Enable microphone, enable is true to enable, false to disable.
rangeAudio.enableMicrophone(enable);

// Enable speaker, enable is true to enable, false to disable.
rangeAudio.enableSpeaker(enable);

10 (Optional) Join team, set voice mode

// Parameter teamID passed as a string means joining the team of the corresponding teamID.
rangeAudio.setTeamID("teamID");
// Parameter teamID not passed or passed as undefined means leaving the team.
rangeAudio.setTeamID();

// Parameter teamID passed as a string means joining the team of the corresponding teamID.
rangeAudio.setTeamID("teamID");
// Parameter teamID not passed or passed as undefined means leaving the team.
rangeAudio.setTeamID();

// Parameter mode can be 0 or 1.
// 0 is World mode, can communicate with everyone logged into the room.
// 1 is Team Only mode, only communicate with team members.
rangeAudio.setRangeAudioMode(1);

// Parameter mode can be 0 or 1.
// 0 is World mode, can communicate with everyone logged into the room.
// 1 is Team Only mode, only communicate with team members.
rangeAudio.setRangeAudioMode(1);

zg.setRangeAudioCustomMode(0, 0);

zg.setRangeAudioCustomMode(0, 0);

11 Leave Room

Call the logoutRoom interface to leave the room. After leaving, the microphone and speaker will be automatically disabled (i.e., unable to send your own audio and unable to hear other people's audio), and the speaker information list will be cleared.

zg.logoutRoom(roomID)

zg.logoutRoom(roomID)

FAQ

1. How many streams can be played simultaneously within the listening range?

Range audio supports playing up to 20 streams simultaneously.

To ensure voice clarity, when more than 20 people nearby are speaking, only the sounds of the 20 speakers closest to you can be heard. If there are more than 20 people at the same distance, it's determined by the order in which each userID is first passed when calling the updateAudioSource interface.

2. Does "range" in range audio refer to listening range or speaking range?

The "range" in range audio refers to listening range.

3. Do team members have 3D audio effects when speaking?

Voice within a team has the effect of ordinary calling, without 3D audio effects for now.

4. If I'm already calling the publishing stream interface, will there be conflicts when using range audio?

Range audio currently uses the main channel to send audio. If you are already using the main channel, there will be conflicts.

Browser Compatibility

• For browser compatibility of range audio, please refer to Which browsers does ZEGO Express Web SDK support.
• Browser compatibility for 3D audio effects is as follows: