ZegoRangeAudio

Declared in ZegoRangeAudio.java

Methods

setEventHandler

public void setEventHandler(IZegoRangeAudioEventHandler handler)

set range audio event handler.

Declared in ZegoRangeAudio.java

Parameters

Name	Type	Description
handler	IZegoRangeAudioEventHandler	The object used to receive range audio callbacks.

Details

Set the callback function of the range audio module, which can receive the callback notification of the microphone on state [onRangeAudioMicrophoneStateUpdate]. Use case: Used to monitor the connection status of the current microphone.

When to call: After initializing the range audio [createRangeAudio].

Available since: 2.11.0

setAudioReceiveRange

public void setAudioReceiveRange(float range)

Set the maximum range of received audio.

Declared in ZegoRangeAudio.java

Parameters

Name	Type	Description
range	float	the audio range, the value must be greater than or equal to 0.

Details

Set the audio receiving range, the audio source sound beyond this range will not be received. Use case: Set the receiver's receiving range in the World mode.

Default value: When this function is not called, only the voices of the members in the team can be received, and all voices outside the team cannot be received.
When to call: After initializing the range audio [createRangeAudio].

Available since: 2.11.0
Restrictions: This range only takes effect for people outside the team.

setAudioReceiveRange

public int setAudioReceiveRange(ZegoReceiveRangeParam param)

Set the configuration of the audio receiving range.

Declared in ZegoRangeAudio.java

Parameters

Name	Type	Description
param	ZegoReceiveRangeParam	Configuration of audio receiving range.

Details

Set the audio receiving range, the audio source sound beyond this range will not be received. Use case: Set the receiver's receiving range in the World mode.

Default value: When this function is not called, only the voices of the members in the team can be received, and all voices outside the team cannot be received.
When to call: After initializing the range audio [createRangeAudio].

Available since: 3.7.0
Restrictions: This range only takes effect for people outside the team.

Return

Error code, please refer to the error codes document https://doc-en.zego.im/en/5548.html for details.

setPositionUpdateFrequency

public void setPositionUpdateFrequency(int frequency)

Set the frequency of real-time update locations within the SDK.

Declared in ZegoRangeAudio.java

Parameters

Name	Type	Description
frequency	int	the frequency, the value must be greater than 15 ms.

Details

Set the frequency of real-time update locations within the SDK min 15 ms. Use case: After setting the update position, the sensitivity of audio gradient is very high.

Default value: 100 ms.
When to call: After initializing the range audio [createRangeAudio].

Available since: 2.21.0

setRangeAudioVolume

public void setRangeAudioVolume(int volume)

Set range voice volume.

Declared in ZegoRangeAudio.java

Parameters

Name	Type	Description
volume	int	volume, [0,200].

Details

Set range voice volume. Use case: This interface allows you to increase or decrease the volume of a range voice stream when the user calls [startPlayingStream] and pulls another stream.

Default value: 100.
When to call: After initializing the range audio [createRangeAudio].

Available since: 2.23.0

setStreamVocalRange

public void setStreamVocalRange(String streamID, float vocalRange)

Set the sound range for the stream.

Declared in ZegoRangeAudio.java

Parameters

Name	Type	Description
streamID	String	play stream id
vocalRange	float	Flow sound range.

Details

Set range voice volume. Use case: When a user calls [startPlayingStream] and pulls another stream, the stream has a range speech effect by setting the range of sounds for that stream and calling [updateStreamPosition]. After the call will be the sound source of the sound range of the distance attenuation effect.

When to call: After initializing the range audio [createRangeAudio] and after [startPlayingStream].
Caution: When calling [enableMicrophone] to enable range speech, the resource of the stream will be switched to RTC, regardless of whether the resource specified when [startPlayingStream] was originally called to pull the stream is RTC. If you really need to specify the resource of the stream as CDN, please configure it to pull a custom CDN stream and specify the CDN address information.

Available since: 2.23.0

setStreamVocalRange

public int setStreamVocalRange(String streamID, ZegoVocalRangeParam param)

Set the sound range for the stream.

Declared in ZegoRangeAudio.java

Parameters

Name	Type	Description
streamID	String	play stream id
param	ZegoVocalRangeParam	Flow sound range.

Details

When to call: After initializing the range audio [createRangeAudio] and after [startPlayingStream].
Caution: When calling [enableMicrophone] to enable range speech, the resource of the stream will be switched to RTC, regardless of whether the resource specified when [startPlayingStream] was originally called to pull the stream is RTC. If you really need to specify the resource of the stream as CDN, please configure it to pull a custom CDN stream and specify the CDN address information.

Available since: 3.7.0

Return

Error code, please refer to the error codes document https://doc-en.zego.im/en/5548.html for details.

updateStreamPosition

public void updateStreamPosition(String streamID, float[] position)

Update the location of the flow.

Declared in ZegoRangeAudio.java

Parameters

Name	Type	Description
streamID	String	play stream id.
position	float[]	The unit vector of the front axis of its own coordinate system. The parameter is a float array with a length of 3. The three values represent the front, right, and top coordinate values in turn.

Details

Set range voice volume. Use case: When the user calls [startPlayingStream] to pull another stream, call [setStreamVocalRange] to set the stream's voice position, then call this interface to set the stream's position, so that the stream also has the range voice effect.

When to call: After initializing the range audio [createRangeAudio] and after [startPlayingStream].

Available since: 2.23.0

updateSelfPosition

public void updateSelfPosition(float[] position, float[] axisForward, float[] axisRight, float[] axisUp)

Update self position and orentation.

Declared in ZegoRangeAudio.java

Parameters

Name	Type	Description
position	float[]	The coordinates of the oneself in the world coordinate system. The parameter is a float array of length 3. The three values represent the front, right, and top coordinate values in turn.
axisForward	float[]	The unit vector of the front axis of its own coordinate system. The parameter is a float array with a length of 3. The three values represent the front, right, and top coordinate values in turn.
axisRight	float[]	The unit vector of the right axis of its own coordinate system. The parameter is a float array with a length of 3. The three values represent the front, right, and top coordinate values in turn.
axisUp	float[]	The unit vector of the up axis of its own coordinate system. The parameter is a float array with a length of 3. The three values represent the front, right, and top coordinate values in turn.

Details

Update the user's position and orientation so that the SDK can calculate the distance between the user and the audio source and the stereo effect of the left and right ears. Use case: When the role operated by the user in the game moves on the world map, the position information and head orientation of the role are updated.

When to call: Called after logging in to the room [loginRoom].
Caution: Before calling [enableSpeaker] to turn on the speaker, if you do not call this interface to set the location information, you will not be able to receive voices from other people except the team.

Available since: 2.11.0

updateAudioSource

public void updateAudioSource(String userID, float[] position)

Add or update audio source position information.

Declared in ZegoRangeAudio.java

Parameters

Name	Type	Description
userID	String	The userID of the sound source.
position	float[]	The coordinates of the speaker in the world coordinate system. The parameter is a float array of length 3. The three values represent the front, right, and top coordinate values in turn.

Details

Set the position of the audio source corresponding to the userID on the game map in the room, so that the SDK can calculate the distance and orientation of the listener to the audio source. Use case: Update the position of the voice user in the game map coordinates.

When to call: Call [loginRoom] to call after logging in to the room, and the recorded audio source information will be cleared after logging out of the room.

Available since: 2.11.0

enableSpatializer

public void enableSpatializer(boolean enable)

Turn the 3D spatial sound on or off.

Declared in ZegoRangeAudio.java

Parameters

Name	Type	Description
enable	boolean	Whether to enable 3D sound effects.

Details

After the 3D sound effect is turned on, the sound effect in the actual space will be simulated according to the position of the speaker equivalent to the listener. The intuitive feeling is that the sound size and the left and right sound difference will also change when the distance and orientation of the sound source change. Use case: It is a feature of audio recognition in FPS games or social scene games.

Default value: When this function is not called, 3D sound effects are turned off by default.
When to call: After initializing the range audio [createRangeAudio].
Caution: The 3D audio effect will only take effect when [setRangeAudioMode] is called and set to World mode.
Related APIs: After enabling the 3D sound effect, you can use [updateAudioSource] or [updateSelfPosition] to change the position and orientation to experience the 3D effect.

Available since: 2.11.0

enableMicrophone

public void enableMicrophone(boolean enable)

Turn the microphone on or off.

Declared in ZegoRangeAudio.java

Parameters

Name	Type	Description
enable	boolean	Whether to turn on the microphone.

Details

When enable is true, turn on the microphone and push audio stream; when it is false, turn off the microphone and stop pushing audio stream. Use case: The user turns on or off the microphone to communicate in the room.

Default value: When this function is not called, the microphone is turned off by default.
When to call: After initializing the range audio [createRangeAudio] and login room [loginRoom].
Caution: Turning on the microphone will automatically use the main channel to push the audio stream.
Related callbacks: Get the microphone switch state change through the callback [onRangeAudioMicrophoneStateUpdate].

Available since: 2.11.0

enableSpeaker

public void enableSpeaker(boolean enable)

Turn the speaker on or off.

Declared in ZegoRangeAudio.java

Parameters

Name	Type	Description
enable	boolean	Whether to turn on the speaker.

Details

When enable is true, turn on the speaker and play audio stream; when it is false, turn off the speaker and stop playing audio stream. Use case: The user turns on or off the speaker to communicate in the room.

Default value: When this function is not called, the speaker is turned off by default.
When to call: After initializing the range audio [createRangeAudio] and login room [loginRoom].
Caution: Turning on the speaker will automatically pull the audio stream in the room.

Available since: 2.11.0

setRangeAudioMode

public void setRangeAudioMode(ZegoRangeAudioMode mode)

Set range audio mode.

Declared in ZegoRangeAudio.java

Parameters

Name	Type	Description
mode	ZegoRangeAudioMode	The range audio mode.

Details

The audio mode can be set to World mode or Team mode. Use case: The user can choose to chat with everyone in the World mode (with distance limitation), or to communicate within the team in the Team mode (without distance limitation).

Default value: If this function is not called, the World mode is used by default.
When to call: After initializing the range audio [createRangeAudio].
Related APIs: In the World mode, you can set the sound receiving range [setAudioReceiveRange], in the Team mode, you need to set [setTeamID] to join the corresponding team to hear the voice in the team.

Available since: 2.11.0

setRangeAudioCustomMode

public void setRangeAudioCustomMode(ZegoRangeAudioSpeakMode speakMode, ZegoRangeAudioListenMode listenMode)

Set range audio custom mode.

Declared in ZegoRangeAudio.java

Parameters

Name	Type	Description
speakMode	ZegoRangeAudioSpeakMode	The range audio speak mode.
listenMode	ZegoRangeAudioListenMode	The range audio listening mode.

Details

Can set the speak mode and listening mode respectively to control the speak and listening behavior in the world and team. Use case: The user can decide who can listen to his voice by selecting the speak mode, and can also decide whose voice to listen to by selecting the listening mode.

Default value: If this interface is not called, the ZegoRangeAudioSpeakModeAll mode and ZegoRangeAudioListenModeAll mode is used by default.
When to call: After initializing the range audio [createRangeAudio].
Related APIs: When you want to listen to sounds from the world, you need to set the sound reception range [setAudioReceiveRange]. When you want to sound and listen in the squad, you need to set [setTeamID] to join the corresponding squad.

Available since: 3.3.0
Restrictions: 1. Cannot be called with [setRangeAudioMode];

Not compatible with versions prior to 3.3.0.

setTeamID

public void setTeamID(String teamID)

Set team ID.

Declared in ZegoRangeAudio.java

Parameters

Name	Type	Description
teamID	String	Team ID, empty to exit the team, a string of up to 64 bytes in length. Support numbers, English characters and '~', '!', '@', '#', '$', '%', '^', '&', '*', '(', ')', '_', '+', '=', '-', '`', ';', '’', ',', '.', '<', '>', ''.

Details

After setting the team ID, you will be able to communicate with other users of the same team, and the sound will not change with the distance. It is also possible to exit the team by setting an empty string. Use case: Users join the team or exit the team.

Default value: When this function is not called, no team will be added by default.
When to call: After initializing the range audio [createRangeAudio].
Caution: There will be no distance limit for the sounds in the team, and there will be no 3D sound effects.

muteUser

public void muteUser(String userID, boolean mute)

Whether can receive the audio data of the specified user.

Declared in ZegoRangeAudio.java

Parameters

Name	Type	Description
userID	String	User ID.
mute	boolean	Whether it can receive the audio data of the specified remote user, "true" means prohibition, "false" means receiving, the default value is "false".

Details

In the process of real-time audio and video interaction, local users can use this function to control whether to receive audio data from designated remote users when pulling streams as needed. When the developer does not receive the audio receipt, the hardware and network overhead can be reduced.

Use cases: When developers need to quickly close and restore remote audio, they can call this function to enhance the interactive experience.
Default value: The default is false, which means to receive audio data from all users.
When to call: After initializing the range audio [createRangeAudio].
Caution: This function is valid only when the [muteAllPlayStreamAudio] function is set to false.
Related APIs: You can call the [muteAllPlayStreamAudio] function to control whether to receive all audio data. 1. When the [muteAllPlayStreamAudio(true)] function is called, it takes effect globally, that is, local users will be prohibited from receiving audio data from all remote users. At this time, the [muteUser] function will not take effect regardless of whether the [muteUser] function is called before or after [muteAllPlayStreamAudio]. 2. When the [muteAllPlayStreamAudio(false)] function is called, the local user can receive the audio data of all remote users. At this time, the [muteUser] function can be used to control whether to receive the audio data of the specified user. Calling the [muteUser(userID, true)] function allows the local user to receive audio data other than the userID; calling the [muteUser(userID, false)] function allows the local user to receive the audio data of the userID.

Available since: 2.16.0