Game Voice

Feature 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, please refer to Set the listener's current position.
• Listener: A user in the room who receives audio.
• Speaker: A user in the room who sends audio.

Feature Description

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

Feature	Description
Range Voice	Listeners in the room have range limitations on the distance at which they can receive audio. If a speaker is beyond that range, they cannot be heard. To ensure voice clarity, when more than 20 people nearby are speaking, only the 20 closest speakers can be heard. Assuming the maximum audio receiving range 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 image only takes the range voice mode as "World" as an example. For more sound reachability under different mode combinations, please refer to Set Common Voice Mode.
3D Audio Effects	Sound has 3D spatial sense and attenuates with distance.
Common Voice Mode	Players can choose to join a team and support freely switching between "World", "Team Only", and "Secret Team" voice modes within the room. World: Players can communicate with other players in the world, and can also communicate with teammates. Team Only: Players can only communicate with teammates. Secret Team: Players can communicate with teammates, and can only hear voice from other players in the world range. Note Communication between teammates is not affected by "range" and "3D audio effects". For details, please see Set Common Voice Mode. If you want to customize voice send/receive capabilities, please refer to Set Custom Voice Mode.

Application Scenarios

Game voice features are suitable for battle royale games and metaverse scenarios.

In battle royale games, team voice provides team functionality. Teams can be changed before and after the game starts. Developers do not need to focus on stream grouping and publish/play stream implementation, directly implementing team voice functionality.

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

Example Source Code Download

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

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

Prerequisites

Before implementing range voice, please ensure:

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

Precautions

If you are already using ZEGO Express SDK's real-time audio and video functionality, please note the following:

• Since the range voice module is implemented based on ZegoExpressEngine's publish/play stream interfaces, you don't need to focus on the concept of publish/play streams when using it. In range voice scenarios, the concept of publishing audio stream becomes "enable microphone", and the concept of playing audio stream becomes "enable speaker". It is recommended not to use startPublishingStream and startPlayingStream interfaces for publish/play stream operations while integrating the range voice feature to avoid effect conflicts.
• Publish/play stream related callbacks in the range voice module (onPublisherStateUpdate, onPlayerStateUpdate, onPublisherQualityUpdate, and onPlayerQualityUpdate) will no longer take effect.

Usage Steps

The above image only shows the core steps and interfaces for implementing game voice functionality. Developers can refer to the detailed introduction in the following documentation according to business needs and implement other related interfaces.

1 Create Engine

Call the createEngine interface, pass the obtained AppID and AppSign into the parameters "appID" and "appSign", and create an engine singleton object. The engine currently only supports creating one instance at a time. Beyond that, it will return null.

/** Define SDK engine object */
ZegoExpressEngine engine;

ZegoEngineProfile profile = new ZegoEngineProfile();
/** Please obtain through official website registration, format is 123456789L */
profile.appID = appID;
/** 64 characters, please obtain through official website registration, format is "0123456789012345678901234567890123456789012345678901234567890123" */
profile.appSign = appSign;
/** General scenario access, please choose the appropriate scenario according to actual situation */
profile.scenario = ZegoScenario.DEFAULT;
/** Set app's application object */
profile.application = getApplication();
/** Create engine */
engine = ZegoExpressEngine.createEngine(profile, null);

/** Define SDK engine object */
ZegoExpressEngine engine;

ZegoEngineProfile profile = new ZegoEngineProfile();
/** Please obtain through official website registration, format is 123456789L */
profile.appID = appID;
/** 64 characters, please obtain through official website registration, format is "0123456789012345678901234567890123456789012345678901234567890123" */
profile.appSign = appSign;
/** General scenario access, please choose the appropriate scenario according to actual situation */
profile.scenario = ZegoScenario.DEFAULT;
/** Set app's application object */
profile.application = getApplication();
/** Create engine */
engine = ZegoExpressEngine.createEngine(profile, null);

2 Create Range Voice Module

Call the createRangeAudio method to create a range voice instance.

ZegoRangeAudio rangeAudio = engine.createRangeAudio();
if (rangeAudio == null) {
    printf("Failed to create range voice instance module");
}

ZegoRangeAudio rangeAudio = engine.createRangeAudio();
if (rangeAudio == null) {
    printf("Failed to create range voice instance module");
}

3 Listen to Range Voice Event Callbacks

You can call the setEventHandler interface as needed to set event callbacks for the microphone, used to listen to microphone enable state onRangeAudioMicrophoneStateUpdate notifications.

// set range audio event handler
rangeAudio.setEventHandler(new IZegoRangeAudioEventHandler() {
    @Override
    public void onRangeAudioMicrophoneStateUpdate(ZegoRangeAudio rangeAudio, ZegoRangeAudioMicrophoneState state, int errorCode) {
        super.onRangeAudioMicrophoneStateUpdate(rangeAudio, state, errorCode);
        AppLogger.getInstance().callApi("microphone state update. state: %s, errorCode: %d", state, errorCode);
    }
});

// set range audio event handler
rangeAudio.setEventHandler(new IZegoRangeAudioEventHandler() {
    @Override
    public void onRangeAudioMicrophoneStateUpdate(ZegoRangeAudio rangeAudio, ZegoRangeAudioMicrophoneState state, int errorCode) {
        super.onRangeAudioMicrophoneStateUpdate(rangeAudio, state, errorCode);
        AppLogger.getInstance().callApi("microphone state update. state: %s, errorCode: %d", state, errorCode);
    }
});

4 Login to Room

After creating a ZegoUser user object by passing in the user ID parameter userID and userName, call the loginRoom interface, passing in the room ID parameter roomID and user parameter user, to log in to the room.

/** Create user */
ZegoUser user = new ZegoUser("user1");

/** Start logging in to room */
engine.loginRoom("room1", user);

/** Create user */
ZegoUser user = new ZegoUser("user1");

/** Start logging in to room */
engine.loginRoom("room1", user);

5 Set the Listener's Current Position

Developers can call the updateSelfPosition interface to set the listener's own position and orientation, or update their position and facing direction in the world coordinate system when their own orientation changes.

// Your coordinates in the world coordinate system, in the order of front, right, up.
float[] position = new float[]{100.0, 100.0, 100.0};
// Unit vector of your forward facing direction in your coordinate system.
float[] axisForward = new float[]{1.0,0.0,0.0};
// Unit vector of your right facing direction in your coordinate system.
float[] axisRight = new float[]{0.0,1.0,0.0};
// Unit vector of your up facing direction in your coordinate system.
float[] axisUp = new float[]{0.0,0.0,1.0};

rangeAudio.updateSelfPosition(position, axisForward, axisRight, axisUp);

// Your coordinates in the world coordinate system, in the order of front, right, up.
float[] position = new float[]{100.0, 100.0, 100.0};
// Unit vector of your forward facing direction in your coordinate system.
float[] axisForward = new float[]{1.0,0.0,0.0};
// Unit vector of your right facing direction in your coordinate system.
float[] axisRight = new float[]{0.0,1.0,0.0};
// Unit vector of your up facing direction in your coordinate system.
float[] axisUp = new float[]{0.0,0.0,1.0};

rangeAudio.updateSelfPosition(position, axisForward, axisRight, axisUp);

6 Add or Update Speaker Position Information

After successfully logging in to the room, you need to call the updateAudioSource interface to add or update speaker position information.

• userID: The ID of other speaking users in the room.
• position: The speaker's coordinates in the world coordinate system. The parameter is a float array of length 3. The three values represent the coordinate values of front, right, and up in order.

// User coordinates in the world coordinate system, in the order of front, right, up.
float[] position = new float[]{100.0, 100.0, 100.0};
// Add/update user position
rangeAudio.updateAudioSource("abc",position);

// User coordinates in the world coordinate system, in the order of front, right, up.
float[] position = new float[]{100.0, 100.0, 100.0};
// Add/update user position
rangeAudio.updateAudioSource("abc",position);

7 (Optional) Set Audio Receiving Range

// Set the maximum range for audio receiving distance. Sounds beyond this range will not be heard
rangeAudio.setAudioReceiveRange(1000);

// Set the maximum range for audio receiving distance. Sounds beyond this range will not be heard
rangeAudio.setAudioReceiveRange(1000);

// Set the attenuation range interval for 3D audio effects [min, max]
ZegoReceiveRangeParam param = new ZegoReceiveRangeParam();
param.min = reciveRangeMin;
param.max = reciveRangeMax;
rangeAudio.setAudioReceiveRange(param);

// Set the attenuation range interval for 3D audio effects [min, max]
ZegoReceiveRangeParam param = new ZegoReceiveRangeParam();
param.min = reciveRangeMin;
param.max = reciveRangeMax;
rangeAudio.setAudioReceiveRange(param);

8 (Optional) Implement 3D Audio Effects

rangeAudio.enableSpatializer(true);

rangeAudio.enableSpatializer(true);

// Enable 3D audio effects, this step is a prerequisite
rangeAudio.enableSpatializer(true);

// Set the position of local players
// Media Player
// 1. Create media player
ZegoMediaPlayer mediaPlayer = engine.createMediaPlayer();
// 2. Set the media player's position in the world coordinate system
float [] mediaPlayerPosition = new float[3];
mediaPlayer.updatePosition(mediaPlayerPosition);
// 3. Use media player to load media resources
ZegoMediaPlayerResource resource = new ZegoMediaPlayerResource();
resource.loadType = ZegoMultimediaLoadType.FILE_PATH;
resource.filePath = "path";
mediaPlayer.loadResourceWithConfig(resource, new IZegoMediaPlayerLoadResourceCallback() {
    @Override
    public void onLoadResourceCallback(int errorCode) {
        if (errorCode == 0)
            mediaPlayer.start();
    }
});

// Audio Effect Player
// 1. Create audio effect player
ZegoAudioEffectPlayer audioEffectPlayer = engine.createAudioEffectPlayer();
// 2. Start playing audio effect resources
int effectSoundID = 1;
String path = "path";
audioEffectPlayer.start(effectSoundID, path, null);
// 3. After receiving [onAudioEffectPlayStateUpdate] callback with state ZegoAudioEffectPlayState.Playing
//    Set the audio effect player's position in the world coordinate system
float [] audioEffectPlayerPosition = new float[3];
audioEffectPlayer.updatePosition(effectSoundID, audioEffectPlayerPosition);

// Enable 3D audio effects, this step is a prerequisite
rangeAudio.enableSpatializer(true);

// Set the position of local players
// Media Player
// 1. Create media player
ZegoMediaPlayer mediaPlayer = engine.createMediaPlayer();
// 2. Set the media player's position in the world coordinate system
float [] mediaPlayerPosition = new float[3];
mediaPlayer.updatePosition(mediaPlayerPosition);
// 3. Use media player to load media resources
ZegoMediaPlayerResource resource = new ZegoMediaPlayerResource();
resource.loadType = ZegoMultimediaLoadType.FILE_PATH;
resource.filePath = "path";
mediaPlayer.loadResourceWithConfig(resource, new IZegoMediaPlayerLoadResourceCallback() {
    @Override
    public void onLoadResourceCallback(int errorCode) {
        if (errorCode == 0)
            mediaPlayer.start();
    }
});

// Audio Effect Player
// 1. Create audio effect player
ZegoAudioEffectPlayer audioEffectPlayer = engine.createAudioEffectPlayer();
// 2. Start playing audio effect resources
int effectSoundID = 1;
String path = "path";
audioEffectPlayer.start(effectSoundID, path, null);
// 3. After receiving [onAudioEffectPlayStateUpdate] callback with state ZegoAudioEffectPlayState.Playing
//    Set the audio effect player's position in the world coordinate system
float [] audioEffectPlayerPosition = new float[3];
audioEffectPlayer.updatePosition(effectSoundID, audioEffectPlayerPosition);

9 Enable Microphone and Speaker

After successfully logging in to the room:

• Call the enableMicrophone interface to set whether to enable the microphone. When enable is true, it means enabled, and the SDK will automatically use the main channel to publish audio stream. When it is false, it means disabled. (Can be enabled or disabled at any time)

  Developers can listen to the onRangeAudioMicrophoneStateUpdate event callback to get the updated microphone state.

• Call the enableSpeaker interface to set whether to enable the speaker. When enable is true, it means enabled, and the SDK will automatically pull audio streams within the room. When it is false, it means disabled. (Can be enabled or disabled at any time)

// Enable microphone
rangeAudio.enableMicrophone(true);
// Enable speaker
rangeAudio.enableSpeaker(true);

// Enable microphone
rangeAudio.enableMicrophone(true);
// Enable speaker
rangeAudio.enableSpeaker(true);

10 (Optional) Join Team and Set Voice Mode

rangeAudio.setTeamID("123");

rangeAudio.setTeamID("123");

rangeAudio.setRangeAudioMode(ZegoRangeAudioMode.WORLD);

rangeAudio.setRangeAudioMode(ZegoRangeAudioMode.WORLD);

rangeAudio.setRangeAudioCustomMode(ZegoRangeAudioSpeakMode.ALL, ZegoRangeAudioListenMode.ALL);

rangeAudio.setRangeAudioCustomMode(ZegoRangeAudioSpeakMode.ALL, ZegoRangeAudioListenMode.ALL);

11 Destroy Range Voice Module

When the range voice module is no longer needed, you can call the destroyRangeAudio interface to destroy it and release the resources occupied by the range voice module.

engine.destroyRangeAudio(rangeAudio);

engine.destroyRangeAudio(rangeAudio);

12 Exit Room

Call the logoutRoom interface to exit the room. After exiting, the microphone and speaker will be automatically turned off (i.e., you cannot send your own audio or hear other people's audio), and the speaker information list will be cleared.

// Exit room
engine.logoutRoom("roomID");

// Exit room
engine.logoutRoom("roomID");

FAQ

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

To ensure voice clarity, when more than 20 people nearby are speaking, you can only hear the voices of the 20 closest speakers. If there are more than 20 people and the distance is the same, the order is determined by the order in which each userID was first passed when calling the updateAudioSource interface.

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

The "range" in range voice refers to the listening range.

3. Do team members in team voice have 3D audio effects when communicating?

Voice within the team has the effect of normal communication; there are currently no 3D audio effects.

4. If I am already calling the publish stream interface, will there be conflicts when using range voice?

Range voice currently uses the main channel to send audio. If the client has already used the main channel, there will be conflicts.