Range Audio

Feature Overview

Concept Explanation

• Range: The range within which a listener receives audio.
• Orientation: Refers to the position and direction of the listener in the game world coordinates. For details, please refer to Set 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 Audio, 3D Spatial Audio, and Team Voice.

Feature	Description
Range Audio	Listeners in the room have a range limit on the distance for receiving audio. If the distance between the speaker and themselves exceeds this range, 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 them can be heard. Suppose 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 exceeds the maximum range, and the listener cannot hear the sound. The above image takes the range audio mode as "World" as an example. For more information about sound reachability under different mode combinations, please refer to Set General Voice Mode.
3D Spatial Audio	Sound has 3D spatial sense and attenuates with distance.
General Voice Mode	Players can choose to join a team and support freely switching between "World", "Team Only", and "Secret Team" voice modes in the room. World: Players can communicate with other players in the world range, and can also communicate with teammates. Team Only: Players can only communicate with teammates. Secret Team: Players can communicate with teammates, and can only receive voice from other players in the world range (one-way). Note Communication between teammates is not affected by "range" and "3D spatial audio". For details, please refer to Set General Voice Mode. If you want to customize audio send/receive capabilities, please refer to Set Custom Voice Mode.

Use Cases

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 do not need to pay attention to stream grouping and the implementation of publishing and playing, directly implementing team voice functionality.

In battle royale games and metaverse scenarios, 3D spatial audio capability is provided. When listening to speaker sound 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 files in the "lib/topics/AudioAdvanced/range_audio" directory.

Prerequisites

Before implementing range audio, ensure:

• You have integrated ZEGO Express SDK in your project and implemented basic real-time audio and video features. For details, please refer to Quick Start - Integrating SDK and Quick Start - Implementing Video Call.
• 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.

Notes

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

• Since the range audio feature module is implemented based on the ZegoExpressEngine's publishing and playing interfaces, you do not need to pay attention to the concept of publishing and playing when using it. In the range audio scenario, the concept of publishing audio stream changes to "enable microphone", and the concept of playing audio stream changes to "enable speaker". It is recommended that you do not use the startPublishingStream and startPlayingStream interfaces for publishing and playing operations while integrating the range audio feature, to avoid effect conflicts.
• The related callbacks for publishing and playing in the range audio feature 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 the game voice feature. Developers can refer to the detailed introduction in the following documentation to implement other related interfaces as needed.

1 Create Engine

Call the createEngineWithProfile interface, pass the applied AppID to the appID parameter, and create an engine singleton object.

/** Obtain through official website registration, format is 123456789 */
int appID = appID;
/** Obtain through official website registration, format is '0123456789012345678901234567890123456789012345678901234567890123' (64 characters in total) */
String appSign = appSign;
/** General scenario access */
ZegoScenario scenario = ZegoScenario.General;

var profile = ZegoEngineProfile(appID, scenario, appSign: appSign);

/** Create engine */
ZegoExpressEngine.createEngineWithProfile(profile);

// When using real-time audio and video SDK for audio-only scenarios, you can disable the camera, which will not require camera permissions and publish video streams
// ZegoExpressEngine.instance.enableCamera(false);

/** Obtain through official website registration, format is 123456789 */
int appID = appID;
/** Obtain through official website registration, format is '0123456789012345678901234567890123456789012345678901234567890123' (64 characters in total) */
String appSign = appSign;
/** General scenario access */
ZegoScenario scenario = ZegoScenario.General;

var profile = ZegoEngineProfile(appID, scenario, appSign: appSign);

/** Create engine */
ZegoExpressEngine.createEngineWithProfile(profile);

// When using real-time audio and video SDK for audio-only scenarios, you can disable the camera, which will not require camera permissions and publish video streams
// ZegoExpressEngine.instance.enableCamera(false);

2 Create Range Audio Module

Call the createRangeAudio method to create a range audio instance.

var rangAudio = await ZegoExpressEngine.instance.createRangeAudio();
if (rangAudio == null) {
    print("Failed to create range audio instance module");
}

var rangAudio = await ZegoExpressEngine.instance.createRangeAudio();
if (rangAudio == null) {
    print("Failed to create range audio instance module");
}

3 Listen for Range Audio Event Callbacks

You can implement the ZegoExpressEngine.onRangeAudioMicrophoneStateUpdate microphone event callback as needed to listen for notifications of microphone enable status.

// set range audio event handler
ZegoExpressEngine.onRangeAudioMicrophoneStateUpdate = (ZegoRangeAudio rangeAudio, ZegoRangeAudioMicrophoneState state, int errorCode) {
};

// set range audio event handler
ZegoExpressEngine.onRangeAudioMicrophoneStateUpdate = (ZegoRangeAudio rangeAudio, ZegoRangeAudioMicrophoneState state, int errorCode) {
};

4 Login Room

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

/** Create user */
var user = ZegoUser.id("user1");

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

/** Create user */
var user = ZegoUser.id("user1");

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

5 Set Listener's Current Position

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

// One's own coordinates in the world coordinate system, in the order of forward, right, and up.
var position = Float32List.fromList(<double>[100.0, 100.0, 100.0]);
// Unit vector of one's own coordinate system's forward direction.
var axisForward = Float32List.fromList(<double>[1.0,0.0,0.0]);
// Unit vector of one's own coordinate system's right direction.
var axisRight = Float32List.fromList(<double>[0.0,1.0,0.0]);
// Unit vector of one's own coordinate system's up direction.
var axisUp = Float32List.fromList(<double>[0.0,0.0,1.0]);

rangAudio?.updateSelfPosition(position, axisForward, axisRight, axisUp);

// One's own coordinates in the world coordinate system, in the order of forward, right, and up.
var position = Float32List.fromList(<double>[100.0, 100.0, 100.0]);
// Unit vector of one's own coordinate system's forward direction.
var axisForward = Float32List.fromList(<double>[1.0,0.0,0.0]);
// Unit vector of one's own coordinate system's right direction.
var axisRight = Float32List.fromList(<double>[0.0,1.0,0.0]);
// Unit vector of one's own coordinate system's up direction.
var axisUp = Float32List.fromList(<double>[0.0,0.0,1.0]);

rangAudio?.updateSelfPosition(position, axisForward, axisRight, axisUp);

6 Add or Update Speaker Position Information

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

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

// User's coordinates in the world coordinate system, in the order of forward, right, and up.
var position = Float32List.fromList(<double>[100.0, 100.0, 100.0]);
// Add/update user position
rangAudio?.updateAudioSource("abc",position);

// User's coordinates in the world coordinate system, in the order of forward, right, and up.
var position = Float32List.fromList(<double>[100.0, 100.0, 100.0]);
// Add/update user position
rangAudio?.updateAudioSource("abc",position);

7 (Optional) Set Audio Reception Range

// Set the attenuation range interval [min, max] for 3D spatial audio
var param = ZegoReceiveRangeParam(0.5, 1.0);
rangeAudio.setAudioReceiveRange(param);

// Set the attenuation range interval [min, max] for 3D spatial audio
var param = ZegoReceiveRangeParam(0.5, 1.0);
rangeAudio.setAudioReceiveRange(param);

// Set the maximum range of audio reception distance. Sounds from audio sources beyond this range will not be heard
var param = ZegoReceiveRangeParam(0, 1000);
rangeAudio.setAudioReceiveRange(param);

// Set the maximum range of audio reception distance. Sounds from audio sources beyond this range will not be heard
var param = ZegoReceiveRangeParam(0, 1000);
rangeAudio.setAudioReceiveRange(param);

8 (Optional) Implement 3D Spatial Audio

rangAudio?.enableSpatializer(true);

rangAudio?.enableSpatializer(true);

// Enable 3D spatial audio, 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
var mediaPlayerPosition = Float32List.fromList(<double>[100.0, 100.0, 100.0]);
mediaPlayer.updatePosition(mediaPlayerPosition);
// 3. Use media player to load media resources
ZegoMediaPlayerResource resource = ZegoMediaPlayerResource.defaultResource();
resource.loadType = ZegoMultimediaLoadType.FilePath;
resource.filePath = "path";
await mediaPlayer.loadResourceWithConfig(resource);

// 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);
// 3. After receiving [onAudioEffectPlayStateUpdate] callback status as ZegoAudioEffectPlayState.Playing
// Set the audio effect player's position in the world coordinate system
var audioEffectPlayerPosition = Float32List.fromList(<double>[100.0, 100.0, 100.0]);
await audioEffectPlayer.updatePosition(effectSoundID, audioEffectPlayerPosition);

// Enable 3D spatial audio, 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
var mediaPlayerPosition = Float32List.fromList(<double>[100.0, 100.0, 100.0]);
mediaPlayer.updatePosition(mediaPlayerPosition);
// 3. Use media player to load media resources
ZegoMediaPlayerResource resource = ZegoMediaPlayerResource.defaultResource();
resource.loadType = ZegoMultimediaLoadType.FilePath;
resource.filePath = "path";
await mediaPlayer.loadResourceWithConfig(resource);

// 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);
// 3. After receiving [onAudioEffectPlayStateUpdate] callback status as ZegoAudioEffectPlayState.Playing
// Set the audio effect player's position in the world coordinate system
var audioEffectPlayerPosition = Float32List.fromList(<double>[100.0, 100.0, 100.0]);
await 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 the audio stream. When 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 status.

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

// Enable microphone
rangAudio?.enableMicrophone(true);
// Enable speaker
rangAudio?.enableSpeaker(true);

// Enable microphone
rangAudio?.enableMicrophone(true);
// Enable speaker
rangAudio?.enableSpeaker(true);

10 (Optional) Join Team, Set Voice Mode

rangAudio?.setTeamID("123");

rangAudio?.setTeamID("123");

rangAudio?.setRangeAudioMode(ZegoRangeAudioMode.World);

rangAudio?.setRangeAudioMode(ZegoRangeAudioMode.World);

rangAudio?.setRangeAudioCustomMode(ZegoRangeAudioSpeakMode.All, ZegoRangeAudioListenMode.All);

rangAudio?.setRangeAudioCustomMode(ZegoRangeAudioSpeakMode.All, ZegoRangeAudioListenMode.All);

11 Destroy Range Audio Module

When the range audio module is no longer in use, call the destroyRangeAudio interface to destroy it and release the resources occupied by the range audio module.

ZegoExpressEngine.instance.destroyRangeAudio(rangAudio!);

ZegoExpressEngine.instance.destroyRangeAudio(rangAudio!);

12 Leave Room

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

// Leave room
ZegoExpressEngine.instance.logoutRoom("roomID");

// Leave room
ZegoExpressEngine.instance.logoutRoom("roomID");

FAQ

1. How many streams in the reception range can be played simultaneously at most?

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

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

The "range" in range audio refers to the reception range.

3. Do team members in team voice have 3D spatial audio when co-hosting?

Voice within the team has the effect of normal co-hosting, and currently does not have 3D spatial audio.

4. If I am already calling the publishing interface, will there be a conflict when using range audio?

Range audio currently uses the main channel to send audio. If the customer is already using the main channel, there will be a conflict.